Module: Decoding

Defined in:
lib/decoding.rb,
lib/decoding/env.rb,
lib/decoding/data.rb,
lib/decoding/error.rb,
lib/decoding/result.rb,
lib/decoding/decoder.rb,
lib/decoding/failure.rb,
lib/decoding/version.rb,
lib/decoding/decoders.rb,
lib/decoding/decoders/at.rb,
lib/decoding/decoders/any.rb,
lib/decoding/decoders/map.rb,
lib/decoding/decoders/uri.rb,
lib/decoding/decoders/date.rb,
lib/decoding/decoders/enum.rb,
lib/decoding/decoders/fail.rb,
lib/decoding/decoders/hash.rb,
lib/decoding/decoders/lazy.rb,
lib/decoding/decoders/pass.rb,
lib/decoding/decoders/time.rb,
lib/decoding/decoders/array.rb,
lib/decoding/decoders/field.rb,
lib/decoding/decoders/index.rb,
lib/decoding/decoders/match.rb,
lib/decoding/matcher_helpers.rb,
lib/decoding/decoders/map_err.rb,
lib/decoding/decoders/succeed.rb,
lib/decoding/decoders/and_then.rb,
lib/decoding/decoders/optional.rb,
lib/decoding/decoders/big_decimal.rb,
lib/decoding/decoders/optional_field.rb

Overview

Decoding is a library to help transform unknown external data into neat values with known shapes.

Defined Under Namespace

Modules: Data, Decoders, MatcherHelpers Classes: Decoder, Err, Error, Failure, Ok, Result, UnwrapError

Constant Summary collapse

ENV_TYPES =

The types env accepts by name, mapped to the decoder that reads them.

Environment variables are always strings, so these are all decoders that parse a string. Pass a decoder directly for anything else.

{
  string: :string,
  symbol: :symbol,
  integer: :parsed_integer,
  float: :parsed_float,
  boolean: :parsed_boolean
}.freeze
VERSION = 
"0.5.0"

Class Method Summary collapse

Class Method Details

.decode(decoder, value) ⇒ Decoding::Result<a>

Run a given decoder on the given input value.

Parameters:

Returns:



121
 
# File 'lib/decoding.rb', line 121

def decode(decoder, value) = decoder.call(value).map_err(&:to_s)

.decode!(decoder, value) ⇒ Object

Run a given decoder on the given input value, returning the decoded value or raising an error when decoding failed.

Examples:

decode!(string, "foo") # => "foo"
decode!(string, 123) # raises Decoding::UnwrapError

Parameters:

Returns:

  • (Object)

Raises:

See Also:



135
 
# File 'lib/decoding.rb', line 135

def decode!(...) = decode(...).unwrap!

.env(name, type = :string, default: NO_DEFAULT, from: ENV) ⇒ Object

Read a single environment variable, decoding its value.

This is meant for configuration read at boot time, such as a Rails initializer: it returns the decoded value itself and raises when the variable is missing or its value cannot be decoded, rather than letting a misconfigured application start.

Examples:

Decoding.env("DATABASE_URL") # => "postgres://localhost/app"
Decoding.env("PORT", :integer) # => 8080
Decoding.env("PORT", :integer, default: 3000) # => 3000 when unset
Decoding.env("DATABASE_URL", Decoders.uri) # => #<URI::Generic ...>

Parameters:

  • name (String) —

    the name of the environment variable.

  • type (Symbol, Decoding::Decoder) (defaults to: :string) —

    one of the keys of ENV_TYPES, or any decoder to run against the value.

  • default (Object) (defaults to: NO_DEFAULT) —

    returned, undecoded, when the variable is not set.

  • from (#key?, #fetch) (defaults to: ENV) —

    where to read the variable from.

Returns:

  • (Object)

Raises:

  • (ArgumentError) —

    when the type is not a known name or a decoder.

  • (Decoding::UnwrapError) —

    when the variable is missing or its value cannot be decoded.



48
49
50
51
52
53
54
55
56
57
58
 
# File 'lib/decoding/env.rb', line 48

def env(name, type = :string, default: NO_DEFAULT, from: ENV)
  decoder = env_decoder(type)
  return default if !from.key?(name) && !default.equal?(NO_DEFAULT)

  decode!(
    Decoders.map_err(decoder) do |message, value|
      value.nil? ? "ENV[#{name.inspect}] is not set" : "ENV[#{name.inspect}]: #{message}"
    end,
    from.fetch(name, nil)
  )
end