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.
Ciris encourages compile-time safety by defining as much as possible of your configurations in Scala. For the data which cannot reside in code, Ciris helps you to load and decode values, while dealing with errors. Validation is encoded by using appropriate data types, with available integrations to libraries such as refined, spire, and squants.
Ciris is intended as an alternative to configuration files, and libraries like Typesafe Config, in situations where it’s easy to change and deploy software. Ciris aims to make it easy and safe to work with configurations by completely eliminating many common configuration errors, and by preventing errors from occurring as early as possible.
Refer to the presentation Refined types for validated configurations (slides) and follow-up blog post
Validated Configurations with Ciris for an introduction to Ciris and configurations with refined types.
val cirisVersion = "0.6.0" libraryDependencies ++= Seq( "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
%%% above if you are using Scala.js.
Libraries are published for Scala 2.10, 2.11, and 2.12, and Java 8.
For changes between versions, please see the release notes.
Binary compatibility for the library is guaranteed between minor versions.
0.6.x is binary compatible with
0.6.y for any
The only required module is
ciris-core, the rest are optional library integrations.
For an explanation of how to use the modules, see the Modules Overview section.
ciris-enumeratummodule allows loading enumeratum enumerations.
ciris-genericmodule allows loading more types with shapeless.
ciris-refinedmodule allows loading refined refinement types.
ciris-spiremodule allows loading spire number types.
ciris-squantsmodule allows loading squants data types.
If you’re using
ciris-generic with Scala 2.10, you’ll need to include the Macro Paradise compiler plugin.
libraryDependencies += compilerPlugin("org.scalamacros" % "paradise" % "2.1.0" cross CrossVersion.patch)
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-core:0.6.0`, ciris._, ciris.syntax._ import $ivy.`is.cir::ciris-enumeratum:0.6.0`, ciris.enumeratum._ import $ivy.`is.cir::ciris-generic:0.6.0`, ciris.generic._ import $ivy.`is.cir::ciris-refined:0.6.0`, ciris.refined._, ciris.refined.syntax._ import $ivy.`is.cir::ciris-spire:0.6.0`, ciris.spire._ import $ivy.`is.cir::ciris-squants:0.6.0`, ciris.squants._
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.
ciris-aws-ssmfor Amazon EC2 Systems Manager (SSM) parameter store as configuration source.
ciris-credstashfor using CredStash as a configuration source.
When it takes little effort to change and release software, for example when employing continuous deployment practices, writing your configurations in Scala can be a viable alternative to configuration files, in order to increase compile-time safety. Since configuration files are not validated at compile-time, any errors will occur at runtime. Tests and macros can be used to perform validation, but by simply using Scala as a configuration language, we ensure that the configuration is correct when compiling, thereby eliminating many potential runtime errors, without having to resort to macros.
For security reasons, it’s desirable that secrets, like passwords, are not stored in the source code. For a Scala configuration, this means that the code containing your secrets should be stored in a different place, and later be compiled together with the rest of your application. If you require that your secrets shouldn’t be persisted to disk, that might not be feasible. Alternatively, you can define most of your configuration in Scala and only load secrets, and other values which cannot reside in code, from the application’s environment.
While it’s possible to not use any libraries in the latter case, loading values from the environment typically means dealing with: different environments and configuration sources, type conversions, error handling, and validation. This is where Ciris comes in: a small library, dependency-free at its core, helping you to deal with all of that more easily.
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.
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.