Skip to content

Commit

Permalink
Update documentation with new String representations
Browse files Browse the repository at this point in the history
  • Loading branch information
Viktor Lövgren committed Jun 16, 2018
1 parent b62a940 commit 6238c4f
Show file tree
Hide file tree
Showing 6 changed files with 116 additions and 112 deletions.
8 changes: 4 additions & 4 deletions modules/core/jvm/src/main/scala/ciris/CirisPlatformSpecific.scala
View file
Original file line number Diff line number Diff line change
Expand Up @@ -28,8 +28,8 @@ private[ciris] trait CirisPlatformSpecific {
* @return a [[ConfigEntry]] with the result
* @see [[fileWithName]]
* @example {{{
* scala> file[Double](new java.io.File("/number.txt"))
* res0: ConfigEntry[api.Id, (java.io.File,java.nio.charset.Charset), String, Double] = ConfigEntry((/number.txt,UTF-8), ConfigKeyType(file), Left(ReadException((/number.txt,UTF-8), ConfigKeyType(file), java.io.FileNotFoundException: /number.txt (No such file or directory))))
* scala> file[Double](new java.io.File("/number.txt")).toStringWithValues
* res0: String = ConfigEntry((/number.txt,UTF-8), ConfigKeyType(file), Left(ReadException((/number.txt,UTF-8), ConfigKeyType(file), java.io.FileNotFoundException: /number.txt (No such file or directory))))
* }}}
*/
def file[Value](
Expand Down Expand Up @@ -104,8 +104,8 @@ private[ciris] trait CirisPlatformSpecific {
* @return a [[ConfigEntry]] with the result
* @see [[file]]
* @example {{{
* scala> fileWithName[Double]("/number.txt")
* res0: ConfigEntry[api.Id, (java.io.File,java.nio.charset.Charset), String, Double] = ConfigEntry((/number.txt,UTF-8), ConfigKeyType(file), Left(ReadException((/number.txt,UTF-8), ConfigKeyType(file), java.io.FileNotFoundException: /number.txt (No such file or directory))))
* scala> fileWithName[Double]("/number.txt").toStringWithValues
* res0: String = ConfigEntry((/number.txt,UTF-8), ConfigKeyType(file), Left(ReadException((/number.txt,UTF-8), ConfigKeyType(file), java.io.FileNotFoundException: /number.txt (No such file or directory))))
* }}}
*/
def fileWithName[Value](
Expand Down
57 changes: 29 additions & 28 deletions modules/core/shared/src/main/scala/ciris/ConfigEntry.scala
View file
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,7 @@ import ciris.api.syntax._
* To create a [[ConfigEntry]], use [[ConfigEntry#apply]].
* {{{
* scala> ConfigEntry("key", ConfigKeyType.Environment, Right("value"))
* res0: ConfigEntry[api.Id, String, String, String] = ConfigEntry(key, Environment, Right(value))
* res0: ConfigEntry[api.Id, String, String, String] = ConfigEntry(key, Environment)
* }}}
*
* @param key the key which was retrieved from the configuration source
Expand Down Expand Up @@ -64,10 +64,11 @@ final class ConfigEntry[F[_]: Apply, K, S, V] private (
* or a [[ConfigError]] if the value is not available
* @example {{{
* scala> val entry = ConfigEntry("key", ConfigKeyType.Environment, Right("value "))
* entry: ConfigEntry[api.Id, String, String, String] = ConfigEntry(key, Environment, Right(value ))
* entry: ConfigEntry[api.Id, String, String, String] = ConfigEntry(key, Environment)
*
* scala> entry.mapValue(_.trim).toStringWithValues
* res0: String = ConfigEntry(key, Environment, Right(value ), Right(value))
*
* scala> entry.mapValue(_.trim)
* res0: ConfigEntry[api.Id, String, String, String] = ConfigEntry(key, Environment, Right(value ), Right(value))
* }}}
*/
def mapValue[A](f: V => A): ConfigEntry[F, K, S, A] =
Expand All @@ -85,10 +86,10 @@ final class ConfigEntry[F[_]: Apply, K, S, V] private (
* or a [[ConfigError]] if the value is not available
* @example {{{
* scala> val entry = ConfigEntry("key", ConfigKeyType.Environment, Right("value"))
* entry: ConfigEntry[api.Id, String, String, String] = ConfigEntry(key, Environment, Right(value))
* entry: ConfigEntry[api.Id, String, String, String] = ConfigEntry(key, Environment)
*
* scala> entry.flatMapValue(v => if(v.length > 2) Right(v) else Left(ConfigError("error")))
* res0: ConfigEntry[api.Id, String, String, String] = ConfigEntry(key, Environment, Right(value))
* scala> entry.flatMapValue(v => if(v.length > 2) Right(v) else Left(ConfigError("error"))).toStringWithValues
* res0: String = ConfigEntry(key, Environment, Right(value))
* }}}
*/
def flatMapValue[A](f: V => Either[ConfigError, A]): ConfigEntry[F, K, S, A] =
Expand All @@ -104,10 +105,10 @@ final class ConfigEntry[F[_]: Apply, K, S, V] private (
* @return a new [[ConfigEntry]]
* @example {{{
* scala> val entry = ConfigEntry("key", ConfigKeyType.Environment, Right("value"))
* entry: ConfigEntry[api.Id, String, String, String] = ConfigEntry(key, Environment, Right(value))
* entry: ConfigEntry[api.Id, String, String, String] = ConfigEntry(key, Environment)
*
* scala> entry.withValue(Right(123))
* res0: ConfigEntry[api.Id, String, String, Int] = ConfigEntry(key, Environment, Right(value), Right(123))
* scala> entry.withValue(Right(123)).toStringWithValues
* res0: String = ConfigEntry(key, Environment, Right(value), Right(123))
* }}}
*/
def withValue[A](value: Either[ConfigError, A]): ConfigEntry[F, K, S, A] =
Expand All @@ -124,13 +125,13 @@ final class ConfigEntry[F[_]: Apply, K, S, V] private (
* @return a new [[ConfigEntry]]
* @example {{{
* scala> val entry = ConfigEntry("key", ConfigKeyType.Environment, Right("value"))
* entry: ConfigEntry[api.Id, String, String, String] = ConfigEntry(key, Environment, Right(value))
* entry: ConfigEntry[api.Id, String, String, String] = ConfigEntry(key, Environment)
*
* scala> entry.withValueF(Right(123))
* res0: ConfigEntry[api.Id, String, String, Int] = ConfigEntry(key, Environment, Right(value), Right(123))
* scala> entry.withValueF(Right(123)).toStringWithValues
* res0: String = ConfigEntry(key, Environment, Right(value), Right(123))
*
* scala> entry.withValue(Right(456))
* res0: ConfigEntry[api.Id, String, String, Int] = ConfigEntry(key, Environment, Right(value), Right(456))
* scala> entry.withValue(Right(456)).toStringWithValues
* res0: String = ConfigEntry(key, Environment, Right(value), Right(456))
* }}}
*/
def withValueF[A](value: F[Either[ConfigError, A]]): ConfigEntry[F, K, S, A] =
Expand All @@ -147,13 +148,13 @@ final class ConfigEntry[F[_]: Apply, K, S, V] private (
* @return a new [[ConfigEntry]]
* @example {{{
* scala> val entry = ConfigEntry("key", ConfigKeyType.Environment, Right("value "))
* entry: ConfigEntry[api.Id, String, String, String] = ConfigEntry(key, Environment, Right(value ))
* entry: ConfigEntry[api.Id, String, String, String] = ConfigEntry(key, Environment)
*
* scala> entry.transformValue(_.right.map(_.trim))
* res0: ConfigEntry[api.Id, String, String, String] = ConfigEntry(key, Environment, Right(value ), Right(value))
* scala> entry.transformValue(_.right.map(_.trim)).toStringWithValues
* res0: String = ConfigEntry(key, Environment, Right(value ), Right(value))
*
* scala> entry.mapValue(_.trim)
* res1: ConfigEntry[api.Id, String, String, String] = ConfigEntry(key, Environment, Right(value ), Right(value))
* scala> entry.mapValue(_.trim).toStringWithValues
* res1: String = ConfigEntry(key, Environment, Right(value ), Right(value))
* }}}
*/
def transformValue[A](
Expand All @@ -177,22 +178,22 @@ final class ConfigEntry[F[_]: Apply, K, S, V] private (
s"ConfigEntry($key, $keyType)"

/**
* Returns a [[String]] representation of this [[ConfigEntry]]
* Returns a `String` representation of this [[ConfigEntry]]
* including the value. If the value is potentially sensitive,
* then be careful to not include it in log output.
*
* @return a [[String]] representation with the value
* @return a `String` representation with the value
*/
override def toStringWithValue: String =
s"ConfigEntry($key, $keyType, $value)"

/**
* Returns a [[String]] representation of this [[ConfigEntry]]
* Returns a `String` representation of this [[ConfigEntry]]
* including both the source value and value. If the values
* include potentially sensitive details, be careful to
* not include them in log output.
*
* @return a [[String]] representation with values
* @return a `String` representation with values
*/
def toStringWithValues: String = {
val sourceValueString = sourceValue.toString
Expand Down Expand Up @@ -223,10 +224,10 @@ object ConfigEntry {
* @return a new [[ConfigEntry]]
* @example {{{
* scala> ConfigEntry("key", ConfigKeyType.Environment, Right("value"))
* res0: ConfigEntry[api.Id, String, String, String] = ConfigEntry(key, Environment, Right(value))
* res0: ConfigEntry[api.Id, String, String, String] = ConfigEntry(key, Environment)
*
* scala> ConfigEntry.applyF[api.Id, String, String]("key", ConfigKeyType.Environment, Right("value"))
* res1: ConfigEntry[api.Id, String, String, String] = ConfigEntry(key, Environment, Right(value))
* res1: ConfigEntry[api.Id, String, String, String] = ConfigEntry(key, Environment)
* }}}
*/
def apply[K, S](
Expand Down Expand Up @@ -258,10 +259,10 @@ object ConfigEntry {
* @return a new [[ConfigEntry]]
* @example {{{
* scala> ConfigEntry.applyF[api.Id, String, String]("key", ConfigKeyType.Environment, Right("value"))
* res0: ConfigEntry[api.Id, String, String, String] = ConfigEntry(key, Environment, Right(value))
* res0: ConfigEntry[api.Id, String, String, String] = ConfigEntry(key, Environment)
*
* scala> ConfigEntry("key", ConfigKeyType.Environment, Right("value"))
* res1: ConfigEntry[api.Id, String, String, String] = ConfigEntry(key, Environment, Right(value))
* res1: ConfigEntry[api.Id, String, String, String] = ConfigEntry(key, Environment)
* }}}
*/
def applyF[F[_]: Apply, K, S](
Expand Down
Loading

0 comments on commit 6238c4f

Please sign in to comment.