Type Members

1.  sealed abstract class ConfigDecoder[A, B] extends AnyRef

   Decodes configuration values from a first type to a second type.

2.  sealed abstract class ConfigError extends AnyRef

   Error which occurred while loading or decoding configuration values.

   Error which occurred while loading or decoding configuration values.

   Configuration errors can be created using ConfigError.apply, or with ConfigError.sensitive if the error might contain sensitive details. When writing ConfigDecoders, ConfigError.decode can be useful for creating decoding errors.

   Errors for a single configuration value, which might be retrieved from one of multiple sources, can be combined and accumulated with ConfigError#or. Errors for multiple configuration values can similarly be accumulated using ConfigError#and.

   Error messages can be retrieved using ConfigError#messages. If the error relates to a value which might contain sensitive details, ConfigError#redacted can be used to redact such details. When ConfigValue#secret is used, sensitive details are redacted and the value is wrapped in Secret to prevent it from being shown.

   A Throwable representation of a ConfigError can be retrieved using ConfigError#throwable.

   Example:

   1. scala> val error = ConfigError("error")
      error: ConfigError = ConfigError(error)
      
      scala> val sensitive = ConfigError.sensitive("error", "redacted")
      sensitive: ConfigError = Sensitive(error, redacted)
      
      scala> error.or(sensitive).messages
      res0: cats.data.Chain[String] = Chain(Error and error)
      
      scala> error.and(sensitive).redacted.messages
      res1: cats.data.Chain[String] = Chain(error, redacted)

3.  sealed abstract class ConfigException extends RuntimeException

   Exception which occurred while loading or decoding configuration values.

4.  sealed abstract class ConfigKey extends AnyRef

   Provides a description of a key used for loading configuration values.

   Provides a description of a key used for loading configuration values.

   Example:

   1. scala> val apiKey = ConfigKey.env("API_KEY")
      apiKey: ConfigKey = ConfigKey(environment variable API_KEY)
      
      scala> apiKey.description
      res0: String = environment variable API_KEY

5.  sealed abstract class ConfigValue[A] extends AnyRef

   Represents a configuration value or a composition of multiple values.

   Represents a configuration value or a composition of multiple values.

   If a configuration value is missing, we can use ConfigValue#or to try and load the value from elsewhere. ConfigValue#default can be used to set a default value if all other values are missing. If the value is optional, ConfigValue#option can be used to default to None if all values are missing.

   Values can be converted to a different type using ConfigValue#as. If the value might contain sensitive details, ConfigValue#secret can be used to redact sensitive details from error messages while also wrapping the value in Secret, preventing the value from being shown.

   Sometimes, we first need to load a configuration value to determine how to continue loading the remaining values. In such cases, it's suitable to use ConfigValue#flatMap. When loading values in sequence using flatMap, errors are not accumulated, and so only the first error will be available.

   Parallel composition lets us achieve error accumulation. Functions like parMapN and parTupled on tuples of ConfigValues loads several values while also accumulating errors. It is often helpful to see all errors when loading configurations, so prefer options which accumulate errors.

   Configuration values can be loaded using ConfigValue#load, which loads the value using a specified effect type. If there are errors and we want to deal with them explicitly, ConfigValue#attempt can be used.

   Example:

   1. scala> import cats.implicits._
      import cats.implicits._
      
      scala> case class Config(maxRetries: Int, apiKey: Option[Secret[String]])
      defined class Config
      
      scala> val maxRetries = env("MAX_RETRIES").or(prop("max.retries")).as[Int].default(5)
      maxRetries: ConfigValue[Int] = ciris.ConfigValue$$$$anon$$3@5821f472
      
      scala> val apiKey = env("API_KEY").or(prop("api.key")).secret.option
      apiKey: ConfigValue[Option[Secret[String]]] = ciris.ConfigValue$$$$anon$$3@186ab4b8
      
      scala> val config = (maxRetries, apiKey).parMapN(Config)
      config: ciris.ConfigValue[Config] = ciris.ConfigValue$$$$anon$$3@565e528c

6.  sealed abstract class Secret[+A] extends AnyRef

   Secret configuration value which might contain sensitive details.

   Secret configuration value which might contain sensitive details.

   When a secret configuration value is shown, the value is replaced by the first 7 characters of the SHA-1 hash for the value. This short SHA-1 hash is available as Secret#valueShortHash, and the full SHA-1 hash is available as Secret#valueHash. The underlying configuration value is available as Secret#value.

   ConfigValue#secret can be used to wrap a value in Secret, while also redacting sentitive details from errors.

   Example:

   1. scala> import cats.implicits._
      import cats.implicits._
      
      scala> val secret = Secret(123)
      secret: Secret[Int] = Secret(40bd001)
      
      scala> secret.valueShortHash
      res0: String = 40bd001
      
      scala> secret.valueHash
      res1: String = 40bd001563085fc35165329ea1ff5c5ecbdbbeef
      
      scala> secret.value
      res2: Int = 123