ciris

package ciris

Members list

Packages

Type members

Classlikes

Attributes

Companion: class
Source: ConfigDecoder.scala
Supertypes: class Object

trait Matchable

class Any
Self type: ConfigDecoder.type

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

Attributes

Companion: object
Source: ConfigDecoder.scala
Supertypes: class Object

trait Matchable

class Any

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.

Attributes

Example

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)

Companion

object

Source

ConfigError.scala

Supertypes

class Object

trait Matchable

class Any

Attributes

Companion: class
Source: ConfigError.scala
Supertypes: trait Sum

trait Mirror

class Object

trait Matchable

class Any
Self type: ConfigError.type

Attributes

Companion: class
Source: ConfigException.scala
Supertypes: trait Product

trait Mirror

class Object

trait Matchable

class Any
Self type: ConfigException.type

Attributes

Companion: object
Source: ConfigException.scala
Supertypes: trait Product

trait Equals

class RuntimeException

class Exception

class Throwable

trait Serializable

class Object

trait Matchable

class Any
Show all

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

Attributes

Example

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

Companion

object

Source

ConfigKey.scala

Supertypes

class Object

trait Matchable

class Any

Attributes

Companion: class
Source: ConfigKey.scala
Supertypes: class Object

trait Matchable

class Any
Self type: ConfigKey.type

Attributes

Companion: class
Source: ConfigValue.scala
Supertypes: class Object

trait Matchable

class Any
Self type: ConfigValue.type

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 a ConfigValue contains Resources for loading the configuration, there is also the option to return a Resource with ConfigValue#resource.

Attributes

Example

scala> import cats.effect.IO
import cats.effect.IO
scala> import cats.effect.unsafe.implicits.global
import cats.effect.unsafe.implicits.global
scala> import cats.syntax.all._
import cats.syntax.all._
scala> case class Config(maxRetries: Int, apiKey: Option[Secret[String]])
class Config
scala> val maxRetries = env("MAX_RETRIES").or(prop("max.retries")).as[Int].default(5)
val maxRetries: ConfigValue[[x]Effect[x],Int] = ConfigValue$$88354410
scala> val apiKey = env("API_KEY").or(prop("api.key")).secret.option
val apiKey: ConfigValue[[x]Effect[x],Option[Secret[String]]] = ConfigValue$$2109306667
scala> val config = (maxRetries, apiKey).parMapN(Config(_, _))
val config: ConfigValue[[x]Effect[x],Config] = ConfigValue$$1463229407
scala> config.load[IO].unsafeRunSync()
res0: Config = Config(5,None)

Companion

object

Source

ConfigValue.scala

Supertypes

class Object

trait Matchable

class Any

Attributes

Companion: class
Source: Secret.scala
Supertypes: class Object

trait Matchable

class Any
Self type: Secret.type

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.

Attributes

Example

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

Companion

object

Source

Secret.scala

Supertypes

class Object

trait Matchable

class Any

Attributes

Companion: class
Source: UseOnceSecret.scala
Supertypes: class Object

trait Matchable

class Any
Self type: UseOnceSecret.type

Secret configuration value which can only be used once before being nullified.

UseOnceSecret.apply wraps an Array[Char] ensuring the array is only accessed once and that the array is nullified once used. The array can be accessed with UseOnceSecret#useOnce or alternatively, through Resource using UseOnceSecret#resource.

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

Attributes

Companion: object
Source: UseOnceSecret.scala
Supertypes: class Object

trait Matchable

class Any

Types

Indicates a ConfigValue can be used with any effect type.

Attributes

Source: ciris.scala

Value members

Concrete methods

Returns a new ConfigValue with the specified default value.

Attributes

Source: ciris.scala

Returns a new ConfigValue for the specified system property.

Attributes

Source: ciris.scala

Inherited methods

Returns a new ConfigValue for the specified environment variable.

Attributes

Inherited from:: CirisRuntimePlatform (hidden)
Source: CirisRuntimePlatform.scala

Returns a new ConfigValue for the file at the specified path.

The file contents are read synchronously using the specified charset.

If the file does not exist, the value is missing. If the file cannot be read, for example when the path is a directory, loading fails with an error.

Attributes

Inherited from:: CirisRuntimePlatform (hidden)
Source: CirisRuntimePlatform.scala

In this article

Generated with