milessabin/ciris

Ciris

Lightweight, extensible, and validated configuration loading in Scala, Scala.js, and Scala Native.
The core library is dependency-free, while modules provide integrations with external libraries.

The name comes from being an abbreviation of the word configurations.
Ciris' logo was inspired by the epyllion Ciris from Appendix Vergiliana.

The Ciris is an epyllion in 541 hexameters describing the myth of Nisus, the king of Megara and his daughter Scylla.
After the city falls and Scylla is taken prisoner on the Cretan ships, Amphitrite transforms her into the ciris seabird.

Ciris is a new project under active development. Feedback and contributions are welcome.

Introduction

Ciris is a configuration as code library for compile-time safe configurations. For the configuration values which cannot reside in code, Ciris helps you to load and decode values from various sources, while dealing with effects and errors. Validation is encoded by using appropriate data types, with integrations to libraries such as enumeratum, refined, spire, and squants.

Ciris is an alternative to configuration files in situations where it's easy to change and deploy software. Ciris aims to make it easy, safe, and secure to work with configurations, by eliminating many common configuration errors, by preventing errors from occurring as early as possible, and by loading secret configuration values directly from vault services.

For a more detailed introduction, please refer to the usage guide.

Getting Started

To get started with sbt, simply add the following lines to your build.sbt file.
For an overview, usage instructions, and examples, please see the usage guide.

val cirisVersion = "0.12.1"

libraryDependencies ++= Seq(
  "is.cir" %% "ciris-cats",
  "is.cir" %% "ciris-cats-effect",
  "is.cir" %% "ciris-core",
  "is.cir" %% "ciris-enumeratum",
  "is.cir" %% "ciris-generic",
  "is.cir" %% "ciris-refined",
  "is.cir" %% "ciris-spire",
  "is.cir" %% "ciris-squants"
).map(_ % cirisVersion)

Make sure to replace %% with %%% above if you are using Scala.js or Scala Native.
Libraries are published for Scala 2.11 and 2.12, and Java 8 where possible.
For changes between versions, please see the release notes.

Refer to the table below for platform and version support across modules.

Module	Dependency	Scala	Scala.js	Scala Native
`ciris-cats`	cats 1.5.0	✓ 2.11, 2.12	✓ 0.6 (2.11, 2.12)	𐄂
`ciris-cats-effect`	cats-effect 1.1.0	✓ 2.11, 2.12	✓ 0.6 (2.11, 2.12)	𐄂
`ciris-core`	𐄂	✓ 2.11, 2.12	✓ 0.6 (2.11, 2.12)	✓ 0.3 (2.11)
`ciris-enumeratum`	enumeratum 1.5.13	✓ 2.11, 2.12	✓ 0.6 (2.11, 2.12)	𐄂
`ciris-generic`	shapeless 2.3.3	✓ 2.11, 2.12	✓ 0.6 (2.11, 2.12)	✓ 0.3 (2.11)
`ciris-refined`	refined 0.9.3	✓ 2.11, 2.12	✓ 0.6 (2.11, 2.12)	✓ 0.3 (2.11)
`ciris-spire`	spire 0.16.0	✓ 2.11, 2.12	✓ 0.6 (2.11, 2.12)	𐄂
`ciris-squants`	squants 1.4.0	✓ 2.11, 2.12	✓ 0.6 (2.11, 2.12)	✓ 0.3 (2.11)

Backwards binary compatibility for the library is guaranteed between patch versions.
For example, 0.12.x is backwards binary compatible with 0.12.y for any x > y.
More recent patch versions are drop-in replacements for earlier patch versions.

The only required module is ciris-core, the rest are optional library integrations.
For an explanation of how to use the modules, refer to the modules overview section.

The ciris-cats module provides type classes and type class instances from cats.
The ciris-cats-effect module provides effect type classes from cats-effect.
The ciris-enumeratum module allows loading enumeratum enumerations.
The ciris-generic module allows loading more types with shapeless.
The ciris-refined module allows loading refined refinement types.
The ciris-spire module allows loading spire number types.
The ciris-squants module allows loading squants data types.

If you're using ciris-cats or ciris-cats-effect, you should enable partial unification.

scalacOptions += "-Ypartial-unification"

Ammonite

To start an Ammonite REPL with Ciris loaded and imported, simply run the following.

curl -Ls try.cir.is | sh

You will need to have a JDK installed. The script will then:

download and install the latest available version of coursier,
use coursier to fetch Ammonite and the latest Ciris version,
start an Ammonite REPL with Ciris already imported.

To use Typelevel Scala with literal types enabled, instead use the following.

curl -Ls try.cir.is/typelevel | sh

If you already have the Ammonite REPL installed, you can load Ciris using the following commands.

import $ivy.`is.cir::ciris-cats:0.12.1`, ciris.cats._
import $ivy.`is.cir::ciris-cats-effect:0.12.1`, ciris.cats.effect._, ciris.cats.effect.syntax._
import $ivy.`is.cir::ciris-core:0.12.1`, ciris._
import $ivy.`is.cir::ciris-enumeratum:0.12.1`, ciris.enumeratum._
import $ivy.`is.cir::ciris-generic:0.12.1`, ciris.generic._
import $ivy.`is.cir::ciris-refined:0.12.1`, ciris.refined._, ciris.refined.syntax._
import $ivy.`is.cir::ciris-spire:0.12.1`, ciris.spire._
import $ivy.`is.cir::ciris-squants:0.12.1`, ciris.squants._

External Libraries

Below is an incomplete list of third-party libraries that integrate with Ciris.
If your library is not included in the list, then please open a pull request.

Documentation

For an overview, with examples and explanations of the most common use cases, please refer to the usage guide.
If you're looking for a more detailed code-centric overview, you can instead take a look at the API documentation.
There is also a small example application available to exemplify how to use the library in an application context.

Participation

Ciris embraces pure, typeful, idiomatic functional programming in Scala, and wants to provide a safe and friendly environment for teaching, learning, and contributing as described in the Typelevel Code of Conduct. It is expected that participants follow the code of conduct in all official channels, including on GitHub and in the Gitter chat room.

If you would like to be involved in building Ciris, check out the contributing guide.

License

Ciris is available under the MIT license, available at https://opensource.org/licenses/MIT and in the license file.

milessabin / ciris