decoding 0.3.0 → 0.5.0

data/lib/decoding/decoders/optional.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require_relative "../decoder"
+
+module Decoding
+  module Decoders
+    # A decoder for a value that may or may not be `nil`, decoding any other
+    # value with a given decoder.
+    #
+    # The given decoder gets to decode a `nil` value first, so it can give it a
+    # meaning of its own. Only when it fails to do so does this decoder treat
+    # `nil` as an absent value.
+    #
+    # @see Decoding::Decoders.optional
+    class Optional < Decoder
+      # @param decoder [Decoding::Decoder<a>]
+      def initialize(decoder)
+        @decoder = decoder.to_decoder
+        super()
+      end
+
+      # @param value [Object]
+      # @return [Decoding::Result<a, nil>]
+      def call(value)
+        result = @decoder.call(value)
+        return result if result.ok?
+        return ok(nil) if value.nil?
+
+        result
+      end
+    end
+  end
+end

data/lib/decoding/decoders/optional_field.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require_relative "../decoder"
+require_relative "field"
+
+module Decoding
+  module Decoders
+    # Decode a value from a key that may be absent from a hash.
+    #
+    # This differs from wrapping a {Field} decoder in an {Optional} decoder,
+    # which describes a key that is present but may hold `nil`. Here the key
+    # itself may be missing; when it is present, its value must still decode.
+    #
+    # @see Decoding::Decoders.optional_field
+    class OptionalField < Decoder
+      # @param key [Object]
+      # @param decoder [Decoding::Decoder<a>]
+      # @param default [Object] used when the key is absent.
+      def initialize(key, decoder, default: nil)
+        @key = String(key)
+        @field = Field.new(@key, decoder)
+        @default = default
+        super()
+      end
+
+      # @param value [Object]
+      # @return [Decoding::Result<a>]
+      def call(value)
+        return ok(@default) if value.is_a?(::Hash) && !value.key?(@key)
+
+        @field.call(value)
+      end
+    end
+  end
+end

data/lib/decoding/decoders/succeed.rb

@@ -11,9 +11,14 @@ module Decoding
     # @example Always return a fixed value
     #   decode(Succeed.new(5), "anything") # => Decoding::Ok(5)
     #
-    # @example Use with field to provide defaults
-    #   decode(any(field("x", integer), Succeed.new(0)), {})
-    #   # => Decoding::Ok(0)
+    # @example Use in conditional decoding
+    #   and_then(field("kind", string)) do |kind|
+    #     kind == "none" ? Succeed.new(nil) : field("value", integer)
+    #   end
+    #
+    # Note this is not the way to give a key a default value: combining it with
+    # {Any} would also swallow the failure of a key that is present but holds a
+    # value of the wrong type. Use {OptionalField} for that instead.
     class Succeed < Decoder
       # @param value [Object] the value to always return
       def initialize(value)

data/lib/decoding/decoders/time.rb

@@ -0,0 +1,143 @@
+# frozen_string_literal: true
+
+require "time"
+
+module Decoding
+  # Decoders are composable functions for deconstructing unknown input values
+  # into known output values.
+  module Decoders
+    # The standard formats {Decoding::Decoders.time} can parse, each named after
+    # the `Time` method that parses it.
+    TIME_FORMATS = %i[iso8601 xmlschema rfc2822 rfc822 httpdate parse].freeze
+
+    # The units {Decoding::Decoders.unix_time} can read a timestamp in, mapped
+    # to the number of them that make up a second.
+    UNIX_TIME_UNITS = { seconds: 1, milliseconds: 1000 }.freeze
+
+    module_function
+
+    # Decode a `Time` object, or a string describing a time in a given format.
+    #
+    # The format is either the name of one of {TIME_FORMATS}, or a string with a
+    # `strptime` pattern. Note that the `:parse` format is lenient: it fills in
+    # any components the input value leaves out from the current time.
+    #
+    # Times are resolved by `Time` itself, and so in the system's time zone,
+    # unless another zone is given. Anything answering the format you name will
+    # do: an `ActiveSupport::TimeZone` resolves in the application's zone, which
+    # is rarely the system's, but note it answers only `iso8601`, `rfc3339` and
+    # `parse` of the names above.
+    #
+    # @example
+    #   decode(time(:iso8601), "2020-01-01T10:00:00Z")
+    #   # => Decoding::Ok(2020-01-01 10:00:00 UTC)
+    #   decode(time("%Y|%m"), "nope")
+    #   # => Decoding::Err("expected a time matching \"%Y|%m\", got \"nope\"")
+    #   decode(time(:parse, zone: Time.zone), "2020-01-01 10:00:00")
+    #   # => Decoding::Ok(2020-01-01 10:00:00 +0100)
+    # @param format [Symbol, String]
+    # @param zone [Object] anything answering the format you name, such as
+    #   `Time` or an `ActiveSupport::TimeZone`.
+    # @raise [ArgumentError] when the format is not a known name or a pattern,
+    #   or the zone cannot parse it. This is raised when the decoder is built,
+    #   not when it is used.
+    # @return [Decoding::Decoder<Time>]
+    # @see Decoding::Decoders::MapErr
+    def time(format, zone: ::Time)
+      parse, description = time_format(format, zone)
+      Decoders.map_err(
+        Decoders.any(
+          Decoders.match(::Time),
+          parsed_by(parse)
+        )
+      ) { |_message, value| "expected #{description}, got #{value.inspect}" }
+    end
+
+    # @private
+    def time_format(format, zone)
+      case format
+      when ::String
+        description = "a time matching #{format.inspect}"
+        require_parser(zone, :strptime, description)
+        [->(str) { zone.strptime(str, format) }, description]
+      when ::Symbol
+        raise ArgumentError, "unknown time format: #{format.inspect}" unless TIME_FORMATS.include?(format)
+
+        description = format == :parse ? "a time" : "a time in #{format} format"
+        require_parser(zone, format, description)
+        [->(str) { zone.public_send(format, str) }, description]
+      else
+        raise ArgumentError, "expected a time format name or a strptime pattern, got #{format.inspect}"
+      end
+    end
+
+    # Decode a unix timestamp, given as a number or as a string describing one.
+    #
+    # Timestamps are read as a number of seconds since the epoch unless another
+    # unit is given. Note that reading a timestamp in the wrong unit is not an
+    # error but a wildly different point in time, so a source that reports
+    # milliseconds has to say so.
+    #
+    # A timestamp names a point in time rather than a local one, so the zone
+    # only decides how the value describes itself afterwards -- which matters as
+    # soon as anything derives a date from it.
+    #
+    # @example
+    #   decode(unix_time, 1_595_674_680) # => Decoding::Ok(2020-07-25 10:58:00 UTC)
+    #   decode(unix_time(:milliseconds), 1_595_674_680_123)
+    #   # => Decoding::Ok(2020-07-25 10:58:00.123 UTC)
+    # @param unit [Symbol] one of the keys of {UNIX_TIME_UNITS}.
+    # @param zone [Object] anything answering `at`, such as `Time` or an
+    #   `ActiveSupport::TimeZone`.
+    # @raise [ArgumentError] when the unit is not a known one, or the zone
+    #   cannot read a timestamp. This is raised when the decoder is built, not
+    #   when it is used.
+    # @return [Decoding::Decoder<Time>]
+    # @see Decoding::Decoders::MapErr
+    def unix_time(unit = :seconds, zone: ::Time)
+      raise ArgumentError, "unknown unit: #{unit.inspect}" unless UNIX_TIME_UNITS.key?(unit)
+
+      require_parser(zone, :at, "a unix timestamp")
+      Decoders.map_err(
+        Decoders.any(
+          Decoders.match(::Time),
+          timestamp_in(zone, UNIX_TIME_UNITS.fetch(unit))
+        )
+      ) { |_message, value| "expected a unix timestamp, got #{value.inspect}" }
+    end
+
+    # Decode a number, or a string describing one, as a point in time.
+    #
+    # @private
+    def timestamp_in(zone, per_second)
+      Decoders.map(
+        Decoders.any(Decoders.integer, Decoders.float, Decoders.parsed_integer, Decoders.parsed_float)
+      ) { zone.at(per_second == 1 ? _1 : _1 / Rational(per_second)) }
+    end
+
+    # Decode a string with the given parser, treating a nil answer as a failure.
+    #
+    # Every method of `Time` raises for a value it cannot parse, but
+    # `ActiveSupport::TimeZone#parse` answers with nil instead, which would
+    # otherwise decode as a successful nil.
+    #
+    # @private
+    def parsed_by(parse)
+      Decoders.and_then(Decoders.map(Decoders.string) { parse.call(_1) }) do |value|
+        value.nil? ? Decoders.fail("parsed to nothing") : Decoders.succeed(value)
+      end
+    end
+
+    # Refuse a zone that cannot answer the parsing this decoder will ask of it,
+    # while the decoder is being built rather than once it is decoding.
+    #
+    # @private
+    def require_parser(zone, method, description)
+      return if zone.respond_to?(method)
+
+      raise ArgumentError, "cannot decode #{description}: the given zone does not respond to #{method}"
+    end
+
+    private_class_method :time_format, :parsed_by, :timestamp_in, :require_parser
+  end
+end

data/lib/decoding/decoders/uri.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require "uri"
+
+module Decoding
+  # Decoders are composable functions for deconstructing unknown input values
+  # into known output values.
+  module Decoders
+    module_function
+
+    # Decode a URI object, or a string that can be parsed as one.
+    #
+    # @example
+    #   decode(uri, "https://example.com") # => Decoding::Ok(URI("https://example.com"))
+    #   decode(uri, 123) # => Decoding::Err("expected a URI, got 123")
+    # @return [Decoding::Decoder<URI::Generic>]
+    # @see Decoding::Decoders::MapErr
+    def uri
+      Decoders.map_err(
+        Decoders.any(
+          Decoders::Match.new(::URI::Generic),
+          Decoders.map(Decoders.string) { ::URI.parse(_1) }
+        )
+      ) { |_msg, value| "expected a URI, got #{value.inspect}" }
+    end
+  end
+end

data/lib/decoding/decoders.rb

@@ -2,8 +2,13 @@
 
 require_relative "decoders/match"
 require_relative "decoders/map"
+require_relative "decoders/map_err"
+require_relative "decoders/optional"
+require_relative "decoders/lazy"
+require_relative "decoders/enum"
 require_relative "decoders/any"
 require_relative "decoders/field"
+require_relative "decoders/optional_field"
 require_relative "decoders/array"
 require_relative "decoders/index"
 require_relative "decoders/hash"
@@ -30,6 +35,37 @@ module Decoding
     # @see Decoding::Decoders::Match
     def string = Decoders::Match.new(String)
 
+    # Decode any value matching the given pattern, using the `===` operator.
+    # This works with anything that can be used in a `case` statement, such as
+    # classes, ranges and regular expressions.
+    #
+    # @example
+    #   decode(match(Symbol), :foo) # => Decoding::Ok(:foo)
+    #   decode(match(1..5), 3) # => Decoding::Ok(3)
+    # @param pattern [#===]
+    # @return [Decoding::Decoder<Object>]
+    # @see Decoding::Decoders::Match
+    def match(pattern) = Decoders::Match.new(pattern)
+
+    # Decode a value that must be one of a fixed set of values.
+    #
+    # The values are compared for equality, and can be given either as separate
+    # arguments or as a single array.
+    #
+    # @example
+    #   decode(enum("active", "archived"), "active") # => Decoding::Ok("active")
+    #   decode(enum("active", "archived"), "nope")
+    #   # => Decoding::Err(%(expected one of "active", "archived", got "nope"))
+    # @overload enum(value, *values)
+    #   @param value [Object]
+    #   @param values [Object]
+    # @overload enum(values)
+    #   @param values [Array<Object>]
+    # @raise [ArgumentError] when no values are given, or one is repeated.
+    # @return [Decoding::Decoder<Object>]
+    # @see Decoding::Decoders::Enum
+    def enum(...) = Decoders::Enum.new(...)
+
     # Decode any string value that matches a regular expression.
     #
     # @param regex [Regexp, String]
@@ -92,7 +128,7 @@ module Decoding
     #   decode(boolean, true) # => Decoding::Ok(true)
     #   decode(boolean, false) # => Decoding::Ok(false)
     # @return [Decoding::Decoder<Boolean>]
-    def boolean = any(self.true, self.false)
+    def boolean = map_err(any(self.true, self.false)) { |_msg, value| "expected true or false, got #{value.class}" }
 
     # Decode a String value into a symbol.
     #
@@ -101,6 +137,46 @@ module Decoding
     # @return [Decoding::Decoder<Symbol>]
     def symbol = map(string, &:to_sym)
 
+    # @!group Parsing decoders
+
+    # Decode a string describing an integer into that integer.
+    #
+    # The string is always read as a decimal number, so `"08"` decodes to `8`
+    # and `"0x1f"` is not a valid integer.
+    #
+    # @example
+    #   decode(parsed_integer, "8080") # => Decoding::Ok(8080)
+    #   decode(parsed_integer, "abc") # => Decoding::Err(%(expected an integer, got "abc"))
+    # @return [Decoding::Decoder<Integer>]
+    def parsed_integer
+      map_err(map(string) { Integer(_1, 10) }) { |_message, value| "expected an integer, got #{value.inspect}" }
+    end
+
+    # Decode a string describing a number into a float.
+    #
+    # @example
+    #   decode(parsed_float, "1.5") # => Decoding::Ok(1.5)
+    #   decode(parsed_float, "abc") # => Decoding::Err(%(expected a number, got "abc"))
+    # @return [Decoding::Decoder<Float>]
+    def parsed_float
+      map_err(map(string) { Float(_1) }) { |_message, value| "expected a number, got #{value.inspect}" }
+    end
+
+    # Decode the string `"true"` or `"false"` into the matching boolean.
+    #
+    # Only those two values are accepted: anything else, such as `"1"` or
+    # `"yes"`, is an error rather than a guess at what was meant.
+    #
+    # @example
+    #   decode(parsed_boolean, "true") # => Decoding::Ok(true)
+    #   decode(parsed_boolean, "1") # => Decoding::Err(%(expected "true" or "false", got "1"))
+    # @return [Decoding::Decoder<Boolean>]
+    def parsed_boolean
+      map_err(map(enum("true", "false")) { _1 == "true" }) do |_message, value|
+        %(expected "true" or "false", got #{value.inspect})
+      end
+    end
+
     # @!group Utility decoders
 
     # A decoder that always succeeds with the given value.
@@ -151,6 +227,28 @@ module Decoding
     # @see Decoding::Decoders::Map
     def map(...) = Decoders::Map.new(...)
 
+    # Decode a value with the given decoder and, if it failed, replace its
+    # error message with the result of the given block.
+    #
+    # This is useful for giving a compound decoder a single, fitting error
+    # message rather than exposing the messages of the decoders it is built
+    # from. The location of the original error, if any, is retained.
+    #
+    # @example
+    #   decoder = map_err(any(string, integer)) { |_msg, value|
+    #     "expected a string or integer, got #{value.inspect}"
+    #   }
+    #   decode(decoder, nil)
+    #   # => Decoding::Err("expected a string or integer, got nil")
+    # @overload map_err(decoder)
+    #   @param decoder [Decoding::Decoder<a>]
+    #   @yieldparam msg [String] the original error message
+    #   @yieldparam value [Object] the value being decoded
+    #   @yieldreturn [String]
+    #   @return [Decoding::Decoder<a>]
+    # @see Decoding::Decoders::MapErr
+    def map_err(...) = Decoders::MapErr.new(...)
+
     # Decode a value by trying many different decoders in order, using the first
     # matching result -- or a failure when none of the given decoders succeed.
     #
@@ -168,9 +266,15 @@ module Decoding
     # @example
     #   decode(string, "foo") # => Decoding::Ok("foo")
     #   decode(string, nil) # => Decoding::Ok(nil)
-    # @param decoder [Decoding::Decoder<a>]
-    # @return [Decoding::Decoder<a, nil>]
-    def optional(decoder) = any(decoder, self.nil)
+    # The given decoder gets to decode a `nil` value first, so it can give it a
+    # meaning of its own. Only when it fails to do so is `nil` treated as an
+    # absent value.
+    #
+    # @overload optional(decoder)
+    #   @param decoder [Decoding::Decoder<a>]
+    #   @return [Decoding::Decoder<a, nil>]
+    # @see Decoding::Decoders::Optional
+    def optional(...) = Decoders::Optional.new(...)
 
     # Decode a value from a given key in a hash.
     #
@@ -183,6 +287,26 @@ module Decoding
     # @see Decoding::Decoders::Field
     def field(...) = Decoders::Field.new(...)
 
+    # Decode a value from a key that may be absent from a hash.
+    #
+    # When the key is absent, the given default is used. When it is present, its
+    # value must still decode: a key holding a value of the wrong type is an
+    # error rather than a reason to fall back to the default.
+    #
+    # @example
+    #   decoder = optional_field("count", integer, default: 0)
+    #   decode(decoder, {}) # => Decoding::Ok(0)
+    #   decode(decoder, { "count" => 5 }) # => Decoding::Ok(5)
+    #   decode(decoder, { "count" => "x" })
+    #   # => Decoding::Err("Error at .count: expected Integer, got String")
+    # @overload optional_field(key, decoder, default: nil)
+    #   @param key [Object]
+    #   @param decoder [Decoding::Decoder<a>]
+    #   @param default [Object]
+    #   @return [Decoding::Decoder<a>]
+    # @see Decoding::Decoders::OptionalField
+    def optional_field(...) = Decoders::OptionalField.new(...)
+
     # Decode an array of values using a given decoder.
     #
     # @example
@@ -262,6 +386,26 @@ module Decoding
     # @see Decoding::Decoders::AndThen
     def and_then(...) = Decoders::AndThen.new(...)
 
+    # Create a decoder that is only built when it is used.
+    #
+    # This makes recursive decoders possible: without it, a decoder that refers
+    # to itself would recurse endlessly while being built.
+    #
+    # @example
+    #   def tree
+    #     decode_hash(
+    #       name: field("name", string),
+    #       children: field("children", array(lazy { tree }))
+    #     )
+    #   end
+    #   decode(tree, { "name" => "a", "children" => [] })
+    #   # => Decoding::Ok({ name: "a", children: [] })
+    # @overload lazy
+    #   @yieldreturn [Decoding::Decoder<a>]
+    #   @return [Decoding::Decoder<a>]
+    # @see Decoding::Decoders::Lazy
+    def lazy(...) = Decoders::Lazy.new(...)
+
     # Decode deeply-nested fields.
     #
     # @example
@@ -269,7 +413,7 @@ module Decoding
     #   decode(decoder, { "a" => { "b" => { "c" => "d" } } })
     #   # => Decoding::Ok("d")
     #   decode(decoder, { "a" => { "b" => "d" } })
-    #   # => Decoding::Err("Error at .a.b: expected a Hash, got String")
+    #   # => Decoding::Err("Error at .a.b: expected Hash, got String")
     # @overload at(*fields, decoder)
     #   @param fields [String]
     #   @param decoder [Decoding::Decoder<a>]

data/lib/decoding/env.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+require_relative "../decoding"
+
+# Decoding is a library to help transform unknown external data into neat values
+# with known shapes.
+module Decoding
+  # The types {Decoding.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.
+  ENV_TYPES = {
+    string: :string,
+    symbol: :symbol,
+    integer: :parsed_integer,
+    float: :parsed_float,
+    boolean: :parsed_boolean
+  }.freeze
+
+  # Marks the absence of a default value, so that `nil` can be used as one.
+  NO_DEFAULT = Object.new.freeze
+  private_constant :NO_DEFAULT
+
+  module_function
+
+  # 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.
+  #
+  # @example
+  #   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 ...>
+  # @param name [String] the name of the environment variable.
+  # @param type [Symbol, Decoding::Decoder] one of the keys of {ENV_TYPES}, or
+  #   any decoder to run against the value.
+  # @param default [Object] returned, undecoded, when the variable is not set.
+  # @param from [#key?, #fetch] where to read the variable from.
+  # @raise [ArgumentError] when the type is not a known name or a decoder.
+  # @raise [Decoding::UnwrapError] when the variable is missing or its value
+  #   cannot be decoded.
+  # @return [Object]
+  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
+
+  # @private
+  def env_decoder(type)
+    return type.to_decoder if type.respond_to?(:to_decoder)
+    raise ArgumentError, "expected a type name or a decoder, got #{type.inspect}" unless type.is_a?(Symbol)
+    raise ArgumentError, "unknown type: #{type.inspect}" unless ENV_TYPES.key?(type)
+
+    Decoders.public_send(ENV_TYPES.fetch(type))
+  end
+
+  private_class_method :env_decoder
+end

data/lib/decoding/error.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module Decoding
+  # Base class for all errors raised by this library.
+  class Error < StandardError; end
+end

data/lib/decoding/failure.rb

@@ -9,6 +9,17 @@ module Decoding
   # error, the `array` decoder can push `3` to the stack to indicate that
   # happened at index 3 in its input value.
   class Failure
+    # The error message, without the location it occurred at.
+    #
+    # @return [String]
+    attr_reader :msg
+
+    # The stack of segments describing where the error occurred, innermost
+    # first.
+    #
+    # @return [Array]
+    attr_reader :path
+
     # @param msg [String]
     # @param path [Array] Internal parameter for creating copies with updated paths
     def initialize(msg, path = [])
@@ -33,6 +44,37 @@ module Decoding
       self.class.new(@msg, @path + [segment])
     end
 
+    # Create a copy of this failure with a transformed error message, retaining
+    # the current stack of errors.
+    #
+    # This is useful for decoders that want to replace the error message of a
+    # nested decoder with something more fitting, without losing the location
+    # of the error.
+    #
+    # @yieldparam msg [String]
+    # @yieldreturn [String]
+    # @return [Decoding::Failure]
+    def map = self.class.new(yield(@msg), @path)
+
+    # Combine this failure with others into a single failure, using the given
+    # block to build a single message from all of their messages.
+    #
+    # When all failures occurred at the same location, that location is kept for
+    # the combined failure and left out of the individual messages, since the
+    # combined failure already describes it. Otherwise each message describes
+    # its own location.
+    #
+    # @param others [Array<Decoding::Failure>]
+    # @yieldparam messages [Array<String>]
+    # @yieldreturn [String]
+    # @return [Decoding::Failure]
+    def combine(others)
+      failures = [self, *others]
+      return self.class.new(yield(failures.map(&:to_s))) unless failures.map(&:path).uniq.size == 1
+
+      self.class.new(yield(failures.map(&:msg)), @path)
+    end
+
     def to_s
       if @path.any?
         "Error at .#{@path.reverse.join(".")}: #{@msg}"
@@ -40,9 +82,5 @@ module Decoding
         @msg
       end
     end
-
-    protected
-
-    attr_reader :msg, :path
   end
 end

data/lib/decoding/matcher_helpers.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Decoding
+  # Shared logic for the matchers that describe decoding, loaded along with
+  # them by `require "decoding/rspec"`.
+  #
+  # Decoders report failures as {Decoding::Failure} values, but {Decoding.decode}
+  # renders those into strings, so matchers have to understand both.
+  module MatcherHelpers
+    # Split the error value of a result into its message and the path it
+    # occurred at, with the outermost path segment first.
+    #
+    # @param result [Decoding::Result]
+    # @return [Array(String, Array)]
+    def describe_failure(result)
+      error = result.unwrap_err(nil)
+      return [error.msg, error.path.reverse] if error.is_a?(Decoding::Failure)
+
+      match = error.to_s.match(/\AError at \.(?<path>.+?): (?<msg>.*)\z/m)
+      match ? [match[:msg], match[:path].split(".")] : [error.to_s, []]
+    end
+
+    # @param path [Array]
+    # @return [String]
+    def render_path(path) = path.empty? ? "" : " at .#{path.join(".")}"
+
+    # The path set by the `at` chain, if any.
+    #
+    # @return [Array]
+    def expected_path = @expected_path ||= []
+
+    # @param path [Array]
+    # @return [Boolean]
+    def path_matches?(path) = path.map(&:to_s) == expected_path.map(&:to_s)
+
+    # Compare a decoded value to what the example expects. Values are
+    # compared strictly, so that a decoder returning a value of the wrong
+    # type is not mistaken for a success, unless the example expects a
+    # matcher rather than a value.
+    #
+    # @param expected [Object]
+    # @param actual [Object]
+    # @return [Boolean]
+    def matches_value?(expected, actual)
+      return values_match?(expected, actual) if RSpec::Support.is_a_matcher?(expected)
+
+      actual.eql?(expected)
+    end
+  end
+end

data/lib/decoding/result.rb

@@ -1,8 +1,10 @@
 # frozen_string_literal: true
 
+require_relative "error"
+
 module Decoding
   # Raised when calling {Result#unwrap!} on an `Err` value.
-  class UnwrapError < StandardError; end
+  class UnwrapError < Error; end
 
   # A result represent the outcome of some computation that can succeed or fail.
   # The results are represented with two subclasses of `Result`: `Ok` and `Err`.