mericano1 / ciris Goto Github PK

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

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.

The presentation below introduces Ciris and covers configurations with refined types.
The blog post Validated Configurations with Ciris provides more details on the topic.

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.

// Libraries are published for Scala 2.10, 2.11, 2.12
libraryDependencies ++= Seq(
  "is.cir" %% "ciris-core" % "0.4.2",
  "is.cir" %% "ciris-enumeratum" % "0.4.2",
  "is.cir" %% "ciris-generic" % "0.4.2",
  "is.cir" %% "ciris-refined" % "0.4.2",
  "is.cir" %% "ciris-spire" % "0.4.2",
  "is.cir" %% "ciris-squants" % "0.4.2"
)

Make sure to replace %% with %%% if you are using Scala.js.
For changes between versions, please see the release notes.

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.

• 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-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.

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

import $ivy.`is.cir::ciris-core:0.4.2`, ciris._
import $ivy.`is.cir::ciris-enumeratum:0.4.2`, ciris.enumeratum._
import $ivy.`is.cir::ciris-generic:0.4.2`, ciris.generic._
import $ivy.`is.cir::ciris-refined:0.4.2`, ciris.refined._
import $ivy.`is.cir::ciris-spire:0.4.2`, ciris.spire._
import $ivy.`is.cir::ciris-squants:0.4.2`, 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-ssm for Amazon EC2 Systems Manager (SSM) parameter store as configuration source.
• ciris-credstash for 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.

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