Overview
Ciris is a functional programming library for loading configurations.
In particular, the following features are supported.
- Loading values from multiple sources and defining default values.
- Composing multiple configuration values into larger configurations.
- Preventing secret values from being shown, redacting sensitive errors.
- Decoding configuration values to various commonly used types.
- Accumulating errors when multiple values cannot be loaded.
Documentation is kept up-to-date, currently documenting v3.8.0 on Scala 2.13.
Getting Started
To get started with sbt, add the following line to your build.sbt file.
libraryDependencies += "is.cir" %% "ciris" % "3.8.0"
Published for Scala 2.12, 2.13 and 3.3, Scala.js 1.18 and Scala Native 0.4.
For changes between versions, please refer to the release notes.
If you are using Scala.js or Scala Native, make sure to replace %% with %%% above.
For Scala 2.12, enable partial unification by adding the following line to build.sbt.
scalacOptions += "-Ypartial-unification"
Modules
Following are additional provided modules.
circe
For circe support, add the following line to your build.sbt file.
libraryDependencies += "is.cir" %% "ciris-circe" % "3.8.0"
circe-yaml
For circe-yaml support, add the following line to your build.sbt file.
libraryDependencies += "is.cir" %% "ciris-circe-yaml" % "3.8.0"
enumeratum
For enumeratum support, add the following line to your build.sbt file.
libraryDependencies += "is.cir" %% "ciris-enumeratum" % "3.8.0"
http4s
For http4s support, add the following line to your build.sbt file.
libraryDependencies += "is.cir" %% "ciris-http4s" % "3.8.0"
http4s-aws
For http4s-aws support, add the following line to your build.sbt file.
libraryDependencies += "is.cir" %% "ciris-http4s-aws" % "3.8.0"
refined
For refined support, add the following line to your build.sbt file.
libraryDependencies += "is.cir" %% "ciris-refined" % "3.8.0"
squants
For squants support, add the following line to your build.sbt file.
libraryDependencies += "is.cir" %% "ciris-squants" % "3.8.0"
External Modules
Following is an incomplete list of third-party integrations.
ciris-aiven-kafkaciris-aws-secretsmanagerciris-aws-ssmciris-credstashciris-hoconciris-kubernetes
Signatures
Stable release artifacts are signed with the 3C73 EC3D A303 8ED3 key.
Compatibility
Backwards binary-compatibility for the library is guaranteed between minor and patch versions.
Version 3.a.b is backwards binary-compatible with 3.c.d for any a > c or a = c and b > d.
Please note binary-compatibility is not guaranteed between milestone releases.
Snapshot Releases
To use the latest snapshot release, add the following lines to your build.sbt file.
resolvers += Resolver.sonatypeRepo("snapshots")
libraryDependencies += "is.cir" %% "ciris" % "3.8.0+14-1f05eaf3-SNAPSHOT"
Dependencies
Refer to the table below for dependencies and version support across modules.
| Module | Dependencies | Scala |
|---|---|---|
ciris | cats-effect 3.6.1 | Scala 2.12, 2.13 and 3.3 |
ciris-circe | circe 0.14.8 | Scala 2.12, 2.13 and 3.3 |
ciris-circe-yaml | circe-yaml 0.16.0 | Scala 2.13 and 3.3 |
ciris-enumeratum | enumeratum 1.7.6 | Scala 2.12, 2.13 and 3.3 |
ciris-http4s | http4s 0.23.30 | Scala 2.12, 2.13 and 3.3 |
ciris-http4s-aws | http4s-aws 6.1.0 | Scala 2.13 and 3.3 |
ciris-refined | refined 0.11.1 | Scala 2.12, 2.13 and 3.3 |
ciris-squants | squants 1.8.3 | Scala 2.12, 2.13 and 3.3 |
For Scala.js and Scala Native version support, refer to the following table.
| Module | Scala.js | Scala Native |
|---|---|---|
ciris | Scala.js 1.18 (Scala 2.12, 2.13 and 3.3) | Scala Native 0.4 (Scala 2.13 and 3.3) |
ciris-circe | Scala.js 1.18 (Scala 2.12, 2.13 and 3.3) | Scala Native 0.4 (Scala 2.13 and 3.3) |
ciris-circe-yaml | - | - |
ciris-enumeratum | Scala.js 1.18 (Scala 2.12, 2.13 and 3.3) | - |
ciris-http4s | Scala.js 1.18 (Scala 2.12, 2.13 and 3.3) | Scala Native 0.4 (Scala 2.13 and 3.3) |
ciris-http4s-aws | - | - |
ciris-refined | Scala.js 1.18 (Scala 2.12, 2.13 and 3.3) | Scala Native 0.4 (Scala 2.13 and 3.3) |
ciris-squants | Scala.js 1.18 (Scala 2.12, 2.13 and 3.3) | Scala Native 0.4 (Scala 2.13) |
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 Scala Code of Conduct.
License
Licensed under the MIT license. Refer to the license file.