Ciris v0.10.1

Changes

• Add Secret#valueHash and valueShortHash to retrieve the SHA1 hash of the value. (#164)
• Change Secret#toString to include the short SHA1 hash (first 7 characters) of the value. (#164)

Refer to the usage guide for more details on these changes.

Updates

• Update refined to 0.9.2. (#168)
• Update scala.js to 0.6.24. (#167)

Documentation

• Add example of showPretty derivation from kittens for logging configurations. (#165)

Miscellaneous

• Change to use tutOnly when generating readme and contributing guide. (#166)
• Update sbt plugins to latest versions. (#169)

Released on 2018-07-14.

Ciris v0.10.0

Changes

• Add ConfigErrors#message for a combined error message of the included errors. (#146, #150)
• Add orRaiseErrors and orRaiseThrowable syntax for loaded configurations. (#147, #149)
• Add support for redacting sensitive details in ConfigError messages. (#151)
  • If you're wrapping the types of your secret configuration values in Secret,
    then sensitive details will automatically be redacted from error messages.
  • If you're creating custom ConfigErrors which might contain potentially sensitive
    details, make sure you create the error using the ConfigError#sensitive function.
• Change to hide sensitive details in ConfigValue and ConfigEntry. (#151)
  • String representations, including those from Show instances, no longer
    include any values. If you want String representations including values,
    then use one of toStringWithValue or toStringWithValues.
  • You will now not accidentally log configuration values, unless you're explicitly
    logging the result from a function with value in the name (sourceValue,
    value, toStringWithValue, toStringWithValues, ...).
• Fix ConfigSource#suspendMemoizeF to capture memoization effect. (#145)
• Fix to prevent generic decoding for Option. (#153)
• Remove support for Scala 2.10. (#161)

Updates

• Update ammonite to 1.1.2. (#142)
• Update cats-effect to 0.10.1. (#135)
• Update kittens to 1.0.0. (#160)
• Update refined to 0.9.0. (#137)
• Update scala native to 0.3.7. (#132)
• Update scala to 2.12.6. (#140)
• Update scalacheck to 1.14.0. (#138)
• Update spire to 0.16.0. (#162)

Documentation

• Add dependency versions to index and readme pages. (#154)
• Add section on creating new modules to contributing guide. (#122, #144)
• Change documentation label on microsite to 'API Documentation'. (#163)

Miscellaneous

• Add platform suffix to files to workaround Codecov limitations. (#148)
• Change to correctly configure compiler options in try scripts. (#134)
• Change to not include test dependencies in .pom. (#152)
• Remove Google Analytics from microsite. (#136)
• Update sbt plugins to latest versions. (#141, #159)
• Update sbt to 1.1.6. (#158)

Released on 2018-06-21.

Ciris v0.9.2

Changes

• Change Option decoder to work on missing keys. (#128)
• Remove the ConfigValue#orElse type parameter. (#130)

Documentation

• Change to clarify Option decoding, and use of ConfigValue#orElse and orNone. (#128)
• Add note on which ConfigErrors to return for custom configuration sources. (#128)
• Add note on ciris-generic potentially overriding other behaviours. (#129)
• Add note on not having to specify the type to decode in orElse. (#130)

Miscellaneous

• Remove ciris-generic default import in try scripts. (#129)
• Update Ammonite in try scripts to 1.1.0. (#126)
• Update SBT plugins to latest versions. (#131)
• Update SBT to 1.1.2. (#127)

Released on 2018-03-28.

Ciris v0.9.1

Changes

• Change ConfigValue#orElse and orNone to work on missing keys. (#124)

Updates

• Update enumeratum to 1.5.13. (#125)

Released on 2018-03-26.

Ciris v0.9.0

Changes

• Change ConfigValue#orElse to not evaluate the alternative value unless necessary. (#121)

Updates

• Update cats to 1.1.0. (#119)
• Update cats-effect to 0.10. (#120)
• Update Scala to 2.12.5. (#118)

Miscellaneous

• There is a new demo on the index/readme page. (#117)

Released on 2018-03-21.

Ciris v0.8.1

Some modules were not published correctly during the release of v0.8.0.
This release simply adresses that issue, and no other changes are made.

Released on 2018-03-11.

Ciris v0.8.0

This release arrives with a much rewritten and expanded usage guide. (#116)
Some of the notable changes to the usage guide include the following.

• Most references to types and functions are now hyperlinked to the API documentation.
• Usage Basics includes guidance on when configuration files are appropriate, and when configuration as code is a better fit. Working with configuration values is covered in more detail, and there is a section on suspending effects.
• Encoding Validation covers refined types in greater depth, including useable configurations and external libraries.
• Multiple Environments better explains when to use withValues (and withValue) and how to deal with different values, and different configuration loading, across environments, while eliminating duplicated configuration values.
• Logging Configurations shows how to use Secret for avoiding logging secret configuration values. There is also a section on how to use Show from cats together with kittens, for improved configuration logging over toString.
• Configuration sources and source transformations are covered in more detail, including current supported sources.
• There is a new section on how to support new sources, including a detailed example of supporting property files.
• Configuration decoders are covered in more detail, including current supported types and supporting new types.
• The modules overview has been split into separate pages.

Changes

• Add orNone function on ConfigValue for optional fallback values. (#107)
  The updated usage guide provides more details on configuration values.

  env[ApiKey]("API_KEY")
    .orElse(prop[ApiKey]("api.key"))
    .orNone

• Add cats-effect suspendMemoizeF syntax for ConfigSource. (#110)
  The usage guide has more information on source transformations.
• Add ConfigDecoder[String, scala.util.matching.Regex]. (#111)
  The usage guide provides a list of all the current supported types.
• Fix BigDecimal decoding using fixed precision on Scala 2.10. (#111)
• Add support for decoding yes/no and on/off Boolean values. (#111)
  The usage guide provides a list of all the current supported types.
• Remove unnecessary Show[Id[A]] derivation causing ambiguous implicits. (#112)
  The usage guide explains how Show can be used for logging configurations.
• Improve the error message for combined configuration errors. (#106)
• Try scripts no longer shadow other libraries' namespaces. (#114)

Updates

• Update ammonite to 1.0.5. (#115)
• Update cats-effect to 0.9. (#109)
• Update spire to 0.15.0. (#108)

Released on 2018-03-11.

Ciris v0.7.2

Changes

• Fix ambiguous implicits between ciris-cats and ciris-cats-effect. (#105)

This is a hotfix released very shortly after v0.7.1. If you were quick enough to grab v0.7.1, be aware that v0.7.2 breaks binary backwards compatibility for ciris-cats-effect on Scala 2.10 and 2.11, and you should instead update to use v0.7.2.

Released on 2018-02-14.

Ciris v0.7.1

Changes

• Add simplified ApplicativeError, MonadError, and Sync from cats and cats-effect. (#104)
• Add ciris-cats-effect module with conversions from cats.effect.Sync to ciris. (#104)
• Add ConfigSource#transformF for creating a new ConfigSource with new context F[_]. (#104)
• Add ConfigSource#suspendF for creating a new ConfigSource where reading is suspended into a new context F[_]: Sync. (#104)
• Add argF, propF, fileSync, and fileWithNameSync as pure alternatives, suspending reading into context F[_]: Sync. (#104)
• Add envF for lifting values into F[_] : Applicative. (#104)

Released on 2018-02-14.

Ciris v0.7.0

Changes

• Add ciris.api with simplified typeclasses Applicative, Apply, FlatMap, FunctionK, Functor, and Monad from cats. There is also Id, ~> (FunctionK), and a ciris.api.syntax package with syntax imports. (#102)

• Add a ciris-cats module with implicit conversions from cats typeclasses to Ciris typeclasses. There is also an initial set of typeclass instances for Ciris types and cats typeclasses. See the usage guide for an example of how the module can be used. (#103)

• ConfigSource has been parameterised on F[_] and the type of values it can return V; the type signature is now ConfigSource[F[_], K, V]. ConfigSource#applyF, fromOptionF, emptyF, alwaysF, failedF (and failed), fromMapF, fromEntriesF, fromTryF, fromTryOptionF, catchNonFatalF, and byIndexF have been added for creating ConfigSources with context F. (#84, #102)

• ConfigEntry has been created to combine the functionality of ConfigSourceEntry and ConfigValue; the type signature is ConfigEntry[F[_]: Apply, K, S, V] for context F, key K, unmodified source value S, and transformed value V. ConfigEntry#applyF has been added to create ConfigEntrys with context F. Most functions previously using ConfigValue now make use of ConfigEntry instead. ConfigSourceEntry has been removed. ConfigValue still exists, but as ConfigValue[F[_]: Apply, V] to support orElse and error accumulation; ConfigEntry also directly extends ConfigValue. (#89, #91, #95, #102)

• The ciris.refined.syntax package now works on ConfigEntrys instead, and functions have been renamed refineValue (previously refine) and mapRefineValue (previously mapRefine). The error messages for these functions have been improved thanks to operating on ConfigEntrys. (#95)

  For example, previously we would get an error message like the following, which is missing details like the key, key type, and unmodified source value.

  scala> env[Int]("NUMBER").mapRefine[Negative](_ + 1).value.left.map(_.message)
  res0: Either[String, eu.timepit.refined.api.Refined[Int, Negative]] = Left("Converted value [0] to [1] but was unable to refine: Predicate failed: (1 < 0).")

  But when working with ConfigEntrys, we now get more detailed error messages.

  scala> env[Int]("NUMBER").mapRefineValue[Negative](_ + 1).value.left.map(_.message)
  res0: scala.util.Either[String,eu.timepit.refined.api.Refined[Int,eu.timepit.refined.numeric.Negative]] = Left(Environment variable [NUMBER] with value [1] (and unmodified value [0]) cannot be converted to type [eu.timepit.refined.api.Refined[Int,eu.timepit.refined.numeric.Negative]]: Predicate failed: (1 < 0).)

• ConfigEntry keeps the original unmodified source value, while also keeping a second copy of the value, with additional transformations applied to it, through functions decodeValue, mapValue, flatMapValue, withValue, withValueF, transformValue, and transformF. ConfigEntrys can be chained together to create a new ConfigValue with orElse. The String representation includes both the source value and the modified value, but only if they themselves have different String representations. (#92, #95, #102)

• ConfigReader has been renamed to ConfigDecoder and has been parameterised on F[_]: Monad, unmodified source value S, and value A; the type signature is now ConfigDecoder[A, B], decoding entries via decode (previously read) from ConfigEntry[F, K, S, A] to F[Either[ConfigError, B]]. The readers package has been renamed decoders, and traits ending with ConfigReaders have been renamed to end in ConfigDecoders. (#93, #94, #102)

• ConfigReader#mapBoth has been renamed to ConfigDecoder#fold. (#101)

• ConfigReader#map has been renamed to ConfigDecoder#flatMap. (#101)

• With both ConfigSource and ConfigDecoder being generic in the value type V and context F, there is now support for sources and decoders of arbitrary value types and contexts. However, most ConfigDecoders provided by Ciris still only support decoding Strings. (#95)

• The ciris-generic module now supports decoding products of any arity. See the usage guide for an example of how this works. (#98)

• ConfigError#wrongType now accepts the unmodified source value and includes it in the error message, but only if the value and the unmodified source value have different String representations. The cause parameter no longer has a default value, and is only included in toString if it is available. (#95, #101)

• ConfigError#combined no longer includes Vector in its String representation. (#101)

• The read[Value](key: String) function has been removed, as it can no longer work as intended. It can be replaced with a custom definition, or by using source.read(key).decodeValue[Value] directly on the ConfigSource. (#95)

• Change to prevent double trailing dots in ConfigException message. (#88)

• Add ConfigError#left and right, and ConfigErrors#left and right. (#102)

Updates

• Update Scala.js to 0.6.22. (#96)
• Updated refined to 0.8.7. (#97)

External Libraries

• ciris-aiven-kafka for Aiven Kafka support.
• ciris-kubernetes for Kubernetes secrets support.

Released on 2018-02-12.