Packages

  • package root

    This is the API documentation for Ciris: lightweight, extensible, and validated configuration loading in Scala.
    The documentation is kept up-to-date with new releases, currently documenting release v0.12.0 on Scala 2.12.
    Please note that the documentation targets the JVM, and there may be differences on Scala.js and Scala Native.

    This is the API documentation for Ciris: lightweight, extensible, and validated configuration loading in Scala.
    The documentation is kept up-to-date with new releases, currently documenting release v0.12.0 on Scala 2.12.
    Please note that the documentation targets the JVM, and there may be differences on Scala.js and Scala Native.

    Ciris is divided into the following set of modules.

    • The cats module integrates with cats for type classes and type class instances.
    • The cats-effect module integrates with cats-effect for type classes for effect types.
    • The core module provides basic functionality and support for standard library types.
    • The enumeratum module integrates with enumeratum to be able to read enumerations.
    • The generic module uses shapeless to be able to read products and coproducts.
    • The refined module integrates with refined to be able to read refinement types.
    • The spire module integrates with spire to be able to read more number types.
    • The squants module integrates with squants to read values with unit of measure.

    If you're looking for usage instructions, please refer to the usage guide.

    Definition Classes
    root
  • package ciris

    The main namespace of Ciris is ciris, and the easiest way to get started is to bring it into scope with an import.
    If you are looking for a getting started guide, with examples and explanations, please refer to the usage guide.

    The main namespace of Ciris is ciris, and the easiest way to get started is to bring it into scope with an import.
    If you are looking for a getting started guide, with examples and explanations, please refer to the usage guide.

    Definition Classes
    root
  • package api
    Definition Classes
    ciris
  • package cats

    Module providing an integration with cats.

    Module providing an integration with cats.

    Definition Classes
    ciris
  • package decoders
    Definition Classes
    ciris
  • package enumeratum

    Module providing an integration with enumeratum.

    Module providing an integration with enumeratum.

    Definition Classes
    ciris
  • package generic

    Module using shapeless for generic derivation of ConfigDecoders.

    Module using shapeless for generic derivation of ConfigDecoders.

    Definition Classes
    ciris
  • package refined

    Module providing an integration with refined.

    Module providing an integration with refined.

    Definition Classes
    ciris
  • package spire

    Module providing an integration with spire.

    Module providing an integration with spire.

    Definition Classes
    ciris
  • package squants

    Module providing an integration with squants.

    Module providing an integration with squants.

    Definition Classes
    ciris
  • ConfigDecoder
  • ConfigEntry
  • ConfigError
  • ConfigErrors
  • ConfigException
  • ConfigKeyType
  • ConfigResult
  • ConfigSource
  • ConfigValue
  • Secret

abstract class ConfigDecoder[A, B] extends AnyRef

ConfigDecoder represents the ability to convert the value of a ConfigEntry to a different type. A ConfigDecoder supports converting values of type A to values of type B, within a context F, while also supporting sensible error messages.

To create a new ConfigDecoder, simply extended the class and implement the decode method. Alternatively, refer to the companion object for helper methods.

Note that most ConfigDecoder instances provided by Ciris support converting from String to some type B, which should be enough for most use cases.

A

the type from which the decoder converts

B

the type to which the decoder converts

Self Type
ConfigDecoder[A, B]
Source
ConfigDecoder.scala
Linear Supertypes
Ordering
  1. Alphabetic
  2. By Inheritance
Inherited
  1. ConfigDecoder
  2. AnyRef
  3. Any
  1. Hide All
  2. Show All
Visibility
  1. Public
  2. All

Instance Constructors

  1. new ConfigDecoder()

Abstract Value Members

  1. abstract def decode[F[_], K, S](entry: ConfigEntry[F, K, S, A])(implicit arg0: Monad[F]): F[Either[ConfigError, B]]

    Decodes the value of the specified ConfigEntry, converting the value from type A to type B, within a context F, while also supporting sensible error messages.

    Decodes the value of the specified ConfigEntry, converting the value from type A to type B, within a context F, while also supporting sensible error messages.

    F

    the context in which to decode the configuration value

    K

    the type of the key read from the configuration source

    S

    the type of the original configuration source value

    entry

    the ConfigEntry for which to decode the value

    returns

    the decoded value or a ConfigError if decoding failed

Concrete Value Members

  1. final def !=(arg0: Any): Boolean
    Definition Classes
    AnyRef → Any
  2. final def ##(): Int
    Definition Classes
    AnyRef → Any
  3. final def ==(arg0: Any): Boolean
    Definition Classes
    AnyRef → Any
  4. final def asInstanceOf[T0]: T0
    Definition Classes
    Any
  5. def clone(): AnyRef
    Attributes
    protected[java.lang]
    Definition Classes
    AnyRef
    Annotations
    @native() @throws( ... )
  6. final def collect[C](typeName: String)(f: PartialFunction[B, C]): ConfigDecoder[A, C]

    Applies a partial function on the converted value.

    Applies a partial function on the converted value. The type conversion to C will only succeed for values which the partial function is defined.

    C

    the type for which to convert the value to

    typeName

    the name of the type C

    f

    the partial function converting from B to C

    returns

    a new ConfigDecoder[A, C]

    Example:
    1. scala> val source = ConfigSource.byIndex(ConfigKeyType.Argument)(Vector("123456", "-123"))
      source: ConfigSource[Int, String] = ConfigSource(Argument)
      
      scala> val decoder = ConfigDecoder[String].collect("PosBigInt") { case s if s.forall(_.isDigit) => BigInt(s) }
      decoder: ConfigDecoder[String, scala.math.BigInt] = [email protected]727cfc59
      
      scala> decoder.decode(source.read(0))
      res0: Either[ConfigError, scala.math.BigInt] = Right(123456)
      
      scala> decoder.decode(source.read(1))
      res1: Either[ConfigError, scala.math.BigInt] = Left(WrongType(1, Argument, Right(-123), -123, PosBigInt))
      
      scala> decoder.decode(source.read(2))
      res2: Either[ConfigError, scala.math.BigInt] = Left(MissingKey(2, Argument))
  7. final def eq(arg0: AnyRef): Boolean
    Definition Classes
    AnyRef
  8. def equals(arg0: Any): Boolean
    Definition Classes
    AnyRef → Any
  9. def finalize(): Unit
    Attributes
    protected[java.lang]
    Definition Classes
    AnyRef
    Annotations
    @throws( classOf[java.lang.Throwable] )
  10. final def getClass(): Class[_]
    Definition Classes
    AnyRef → Any
    Annotations
    @native()
  11. def hashCode(): Int
    Definition Classes
    AnyRef → Any
    Annotations
    @native()
  12. final def isInstanceOf[T0]: Boolean
    Definition Classes
    Any
  13. final def map[C](f: (B) ⇒ C): ConfigDecoder[A, C]

    Applies a function to the converted value from this ConfigDecoder.

    Applies a function to the converted value from this ConfigDecoder. The specified function is only applied if the conversion to B was successful, otherwise the behaviour remains unchanged.

    C

    the type for which to convert the value to

    f

    the function to apply to the value

    returns

    a new ConfigDecoder[A, C]

    Example:
    1. scala> val source = ConfigSource.byIndex(ConfigKeyType.Argument)(Vector("123456", "abc"))
      source: ConfigSource[Int, String] = ConfigSource(Argument)
      
      scala> val decoder = ConfigDecoder[String].map(_.take(2))
      decoder: ConfigDecoder[String, String] = [email protected]2274f2dd
      
      scala> decoder.decode(source.read(0))
      res0: Either[ConfigError, String] = Right(12)
      
      scala> decoder.decode(source.read(1))
      res1: Either[ConfigError, String] = Right(ab)
      
      scala> decoder.decode(source.read(2))
      res2: Either[ConfigError, String] = Left(MissingKey(2, Argument))
  14. final def mapCatchNonFatal[C](typeName: String)(f: (B) ⇒ C): ConfigDecoder[A, C]

    Applies a function on the converted value to C, making sure to catch any non-fatal exceptions thrown by the function.

    Applies a function on the converted value to C, making sure to catch any non-fatal exceptions thrown by the function. The conversion will be considered successful only if the function does not throw an exception.

    C

    the type for which to convert the value to

    typeName

    the name of the type C

    f

    the function converting from B to C

    returns

    a new ConfigDecoder[A, C]

    Example:
    1. scala> val source = ConfigSource.byIndex(ConfigKeyType.Argument)(Vector("123456", "abc"))
      source: ConfigSource[Int, String] = ConfigSource(Argument)
      
      scala> val decoder = ConfigDecoder[String].mapCatchNonFatal("Int")(_.toInt)
      decoder: ConfigDecoder[String, Int] = [email protected]17323c05
      
      scala> decoder.decode(source.read(0))
      res0: Either[ConfigError, Int] = Right(123456)
      
      scala> decoder.decode(source.read(1))
      res1: Either[ConfigError, Int] = Left(WrongType(1, Argument, Right(abc), abc, Int, java.lang.NumberFormatException: For input string: "abc"))
      
      scala> decoder.decode(source.read(2))
      res2: Either[ConfigError, Int] = Left(MissingKey(2, Argument))
  15. final def mapEither[L, R](typeName: String)(f: (B) ⇒ Either[L, R]): ConfigDecoder[A, R]

    Applies a function on the converted value, returning an Either[L, R].

    Applies a function on the converted value, returning an Either[L, R]. If the function returns Left[L, R], the type conversion to R will be considered to have failed. Returning a Right[L, R] means that the conversion succeeded.

    L

    the type representing an error for the type conversion;
    should have a sensible toString method for error messages

    R

    the type for which to convert the value to

    typeName

    the name of the type R

    f

    the function converting from B to Either[L, R]

    returns

    a new ConfigDecoder[A, R]

    Example:
    1. scala> val source = ConfigSource.byIndex(ConfigKeyType.Argument)(Vector("123456", "abc"))
      source: ConfigSource[Int, String] = ConfigSource(Argument)
      
      scala> val decoder = ConfigDecoder[String].mapEither("Int")(value => scala.util.Try(value.toInt).map(Right.apply).recover { case e => Left(e) }.get)
      decoder: ConfigDecoder[String, Int] = [email protected]8635c89
      
      scala> decoder.decode(source.read(0))
      res0: Either[ConfigError,Int] = Right(123456)
      
      scala> decoder.decode(source.read(1))
      res1: Either[ConfigError,Int] = Left(WrongType(1, Argument, Right(abc), abc, Int, java.lang.NumberFormatException: For input string: "abc"))
      
      scala> decoder.decode(source.read(2))
      res2: Either[ConfigError,Int] = Left(MissingKey(2, Argument))
  16. final def mapEntryValue(f: (A) ⇒ A): ConfigDecoder[A, B]

    Applies a function on the values in the ConfigEntrys decoded by this decoder, before trying to convert the value to type B.

    Applies a function on the values in the ConfigEntrys decoded by this decoder, before trying to convert the value to type B. This method returns a new ConfigDecoder with the behavior, leaving the existing ConfigDecoder unmodified.

    f

    the function to apply on the ConfigEntry value

    returns

    a new ConfigDecoder decoding modified entry values

    Example:
    1. scala> val source = ConfigSource.byIndex(ConfigKeyType.Argument)(Vector("123 "))
      source: ConfigSource[Int, String] = ConfigSource(Argument)
      
      scala> val decoder = ConfigDecoder[String, Int].mapEntryValue(_.trim)
      decoder: ConfigDecoder[Int] = [email protected]57c04ac9
      
      scala> decoder.decode(source.read(0))
      res0: Either[ConfigError,Int] = Right(123)
  17. final def mapOption[C](typeName: String)(f: (B) ⇒ Option[C]): ConfigDecoder[A, C]

    Applies a function on the converted value, returning an Option[C].

    Applies a function on the converted value, returning an Option[C]. If the function returns None, the type conversion to C will be considered to have failed. Returning a Some will be interpreted like the conversion succeeded.

    C

    the type for which to convert the value to

    typeName

    the name of the type C

    f

    the function converting from B to Option[C]

    returns

    a new ConfigDecoder[A, C]

    Example:
    1. scala> val source = ConfigSource.byIndex(ConfigKeyType.Argument)(Vector("123456", "abc"))
      source: ConfigSource[Int, String] = ConfigSource(Argument)
      
      scala> val decoder = ConfigDecoder[String].mapOption("Int")(value => scala.util.Try(value.toInt).toOption)
      decoder: ConfigDecoder[String, Int] = [email protected]669d8d59
      
      scala> decoder.decode(source.read(0))
      res0: Either[ConfigError, Int] = Right(123456)
      
      scala> decoder.decode(source.read(1))
      res1: Either[ConfigError, Int] = Left(WrongType(1, Argument, Right(abc), abc, Int))
      
      scala> decoder.decode(source.read(2))
      res2: Either[ConfigError, Int] = Left(MissingKey(2, Argument))
  18. final def mapTry[C](typeName: String)(f: (B) ⇒ Try[C]): ConfigDecoder[A, C]

    Applies a function on the converted value, returning a Try[C].

    Applies a function on the converted value, returning a Try[C]. If the function returns a Success, the type conversion will be considered successful. Returning a Failure means that the conversion failed.

    C

    the type for which to convert the value to

    typeName

    the name of the type C

    f

    the function converting from B to Try[C]

    returns

    a new ConfigDecoder[A, C]

    Example:
    1. scala> val source = ConfigSource.byIndex(ConfigKeyType.Argument)(Vector("123456", "abc"))
      source: ConfigSource[Int, String] = ConfigSource(Argument)
      
      scala> val decoder = ConfigDecoder[String].mapTry("Int")(value => scala.util.Try(value.toInt))
      decoder: ConfigDecoder[String, Int] = [email protected]380729e4
      
      scala> decoder.decode(source.read(0))
      res0: Either[ConfigError, Int] = Right(123456)
      
      scala> decoder.decode(source.read(1))
      res1: Either[ConfigError, Int] = Left(WrongType(1, Argument, Right(abc), abc, Int, java.lang.NumberFormatException: For input string: "abc"))
      
      scala> decoder.decode(source.read(2))
      res2: Either[ConfigError, Int] = Left(MissingKey(2, Argument))
  19. final def ne(arg0: AnyRef): Boolean
    Definition Classes
    AnyRef
  20. final def notify(): Unit
    Definition Classes
    AnyRef
    Annotations
    @native()
  21. final def notifyAll(): Unit
    Definition Classes
    AnyRef
    Annotations
    @native()
  22. final def redactSensitive: ConfigDecoder[A, B]

    Removes any potentially sensitive details, like configuration values, from any errors returned as a result of decoding with this ConfigDecoder.

    Removes any potentially sensitive details, like configuration values, from any errors returned as a result of decoding with this ConfigDecoder.

    returns

    a new ConfigDecoder

    Example:
    1. scala> val source = ConfigSource.byIndex(ConfigKeyType.Argument)(Vector("123 "))
      source: ConfigSource[Int, String] = ConfigSource(Argument)
      
      scala> val decoder = ConfigDecoder[String, Int]
      decoder: ConfigDecoder[Int] = [email protected]7bdb183f
      
      scala> decoder.decode(source.read(0)).left.map(_.message).toString
      res0: String = Left(Command-line argument [0] with value [123 ] cannot be converted to type [Int]: java.lang.NumberFormatException: For input string: "123 ")
      
      scala> val decoderRedacted = decoder.redactSensitive
      decoderRedacted: ConfigDecoder[Int] = [email protected]28aa7479
      
      scala> decoderRedacted.decode(source.read(0)).left.map(_.message).toString
      res1: String = Left(Command-line argument [0] with value [<redacted>] cannot be converted to type [Int])
  23. final def synchronized[T0](arg0: ⇒ T0): T0
    Definition Classes
    AnyRef
  24. def toString(): String
    Definition Classes
    ConfigDecoder → AnyRef → Any
  25. final def wait(): Unit
    Definition Classes
    AnyRef
    Annotations
    @throws( ... )
  26. final def wait(arg0: Long, arg1: Int): Unit
    Definition Classes
    AnyRef
    Annotations
    @throws( ... )
  27. final def wait(arg0: Long): Unit
    Definition Classes
    AnyRef
    Annotations
    @native() @throws( ... )

Inherited from AnyRef

Inherited from Any

Ungrouped