Current Supported Sources

The following sources are the currently supported configuration sources in the core module. The core module only includes configuration sources which can be supported without any external dependencies. External libraries, like ciris-kubernetes and ciris-aws-ssm, provide support for configuration sources which do not meet this requirement. You can also easily write your own configuration sources, refer to the supporting new sources section for more information.

  • Command-line arguments are supported with arg and argF (for suspending reading on mutable IndexedSeq). If you’re writing non-trivial command-line applications, you might want to take a look at dedicated full-featured command-line parsing libraries, like decline.
import cats.effect.IO
// import cats.effect.IO

import ciris.{arg, argF}
// import ciris.{arg, argF}

import ciris.cats.effect._
// import ciris.cats.effect._

// The arguments from main(Array[String]): Unit
args
// res1: Array[String] = Array(10)

arg[Int](args)(0)
// res2: ciris.ConfigEntry[ciris.api.Id,Int,String,Int] = ConfigEntry(0, Argument)

argF[IO, Int](args)(0)
// res3: ciris.ConfigEntry[cats.effect.IO,Int,String,Int] = ConfigEntry(0, Argument)
  • Environment variables are supported with the env and envF (for lifting values into context F) functions. Since environment variables are immutable, both the env and envF functions are pure and safe to use. Note that envF is just making use of transformF on ConfigEntry.
import ciris.{env, envF}
// import ciris.{env, envF}

env[String]("LANG")
// res4: ciris.ConfigEntry[ciris.api.Id,String,String,String] = ConfigEntry(LANG, Environment)

envF[IO, String]("LANG")
// res5: ciris.ConfigEntry[cats.effect.IO,String,String,String] = ConfigEntry(LANG, Environment)
import ciris.{file, fileSync, fileWithName, fileWithNameSync}
// import ciris.{file, fileSync, fileWithName, fileWithNameSync}

file[Int](tempFile, _.trim)
// res6: ciris.ConfigEntry[ciris.api.Id,(java.io.File, java.nio.charset.Charset),String,Int] = ConfigEntry((/var/folders/ff/tg7g7zh52_g9s5_djb5z81w00000gn/T/temp-6860746118496236880.tmp,UTF-8), ConfigKeyType(file))

fileSync[IO, Int](tempFile, _.trim)
// res7: ciris.ConfigEntry[cats.effect.IO,(java.io.File, java.nio.charset.Charset),String,Int] = ConfigEntry((/var/folders/ff/tg7g7zh52_g9s5_djb5z81w00000gn/T/temp-6860746118496236880.tmp,UTF-8), ConfigKeyType(file))

fileWithName[Int](tempFileName, _.trim)
// res8: ciris.ConfigEntry[ciris.api.Id,(java.io.File, java.nio.charset.Charset),String,Int] = ConfigEntry((/var/folders/ff/tg7g7zh52_g9s5_djb5z81w00000gn/T/temp-6860746118496236880.tmp,UTF-8), ConfigKeyType(file))

fileWithNameSync[IO, Int](tempFileName, _.trim)
// res9: ciris.ConfigEntry[cats.effect.IO,(java.io.File, java.nio.charset.Charset),String,Int] = ConfigEntry((/var/folders/ff/tg7g7zh52_g9s5_djb5z81w00000gn/T/temp-6860746118496236880.tmp,UTF-8), ConfigKeyType(file))
  • System properties are supported with the prop and propF (for suspending reading) functions. Note that system properties are mutable, so using prop is generally not pure if system properties are modified at runtime. If you want to be on the safe side, prefer to use propF for reading system properties.
import ciris.{prop, propF}
// import ciris.{prop, propF}

prop[String]("file.encoding")
// res10: ciris.ConfigEntry[ciris.api.Id,String,String,String] = ConfigEntry(file.encoding, Property)

propF[IO, String]("file.encoding")
// res11: ciris.ConfigEntry[cats.effect.IO,String,String,String] = ConfigEntry(file.encoding, Property)