decoding 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 95c32106911949f49f3b50dc46f744912cc9abf75405cd7e20248de3dd0b1668
-  data.tar.gz: 492fbe3bf3d64cfe954da4b7016dabb5287d19d140bbf662146cff678dbe7ca6
+  metadata.gz: 3f462705ab2cc82507ed66b66274dd6f9167ade6b3bab3e8d12dc329f8f564fb
+  data.tar.gz: 2a16abba19d6b9f8cb68d7db943e55627c439925b40090f96dc3c8b6dc27e65e
 SHA512:
-  metadata.gz: 7ad3271531ef17b985ecacf39e480baa8c117170d6d3d69b0e2bb1f231663f9ad10a41a390e740ff951600dac7f2d7163ac817d3f1928979cea03898249b8a77
-  data.tar.gz: 95b14f9f7bd57df7f537d6c3402b2eafd46ef397686ac343b2239e76732189d606896e26b606838c403436d1738007deee3e51880880f6839ab77308d7d80a90
+  metadata.gz: 918dae4e293d0585afd44aa092fd95a295d3ed5153fd9a5f4acf041a551fdc97a8ca14f030f038c7507f0b7de799b6cb6076dcbb3bac8b18f024e45ed05fd068
+  data.tar.gz: 818550ca01578f9ba869bf54bb875f962ac22ee179f12c23e7565ab4923e733aaa629325561c73f5c1659c290857200b5dd1bb3b3d4eafad00e445c8ff291385

data/.tool-versions

@@ -1 +1 @@
-ruby 3.3.0
+ruby 3.4.7

data/CHANGELOG.md

@@ -1,5 +1,13 @@
 ## [Unreleased]
 
+## [0.2.0] - 2025-10-25
+
+* Added `decode_hash`, `regexp` and `original` decoders
+* Fixed incorrect `Decoding::Failure` value comparisons
+* Fixed some decoders incorrectly returning `String` values rather than
+  `Decoding::Failure` values
+* Bumped target Ruby version to 3.4.7
+
 ## [0.1.0] - 2024-05-08
 
 - Initial release

data/README.md

@@ -1,12 +1,9 @@
 # Decoding
 
-Decoding is a library to help transform unknown external data into neat values
-with known shapes.
+Decoding is a library to help transform unknown external data into neat values with known shapes.
 
 ## Installation
 
-TODO: Replace `decoding` with your gem name right after releasing it to RubyGems.org. Please do not do it earlier due to security reasons. Alternatively, replace this section with instructions to install your gem from git if you don't plan to release to RubyGems.org.
-
 Install the gem and add to the application's Gemfile by executing:
 
     $ bundle add decoding
@@ -17,111 +14,137 @@ If bundler is not being used to manage dependencies, install the gem by executin
 
 ## Usage
 
-Decoding is a library to help transform unknown external data into neat values
-with known shapes. Consider calling an HTTP API: you might pull in whatever
-value. After passing it through decoder, you will have a value with a known
-shape -- or a sensible error message.
+Decoding is a library to help transform unknown external data into neat values with known shapes. Consider calling an HTTP API: you might pull in whatever value. After passing it through decoder, you will have a value with a known shape -- or a sensible error message.
 
 For example, call an API to get some JSON value:
 
-    body = JSON.parse(Net::HTTP.get("https://api.placeholderjson.dev/shipments/7EBWXB5"))
+```ruby
+body = JSON.parse(Net::HTTP.get("https://api.placeholderjson.dev/shipments/7EBWXB5"))
+```
 
-How do you safely work with `body`? If parsing the response body as JSON has
-worked, you know you have some kind of Ruby value -- but you're not sure of
-its structure. This can lead to cryptic error messages far removing of making
-this HTTP call where values are of unexpected types, hashes turn out not to
-have certain keys or the nesting of data is different from what you expected.
+How do you safely work with `body`? If parsing the response body as JSON has worked, you know you have some kind of Ruby value -- but you're not sure of its structure. This can lead to cryptic error messages far removing of making this HTTP call where values are of unexpected types, hashes turn out not to have certain keys or the nesting of data is different from what you expected.
 
 Assume the response body, parsed as JSON, results in a value like this:
 
-    {
-      "orderID" => "7EBWXB5",
-      "orderDate" => "1595674680",
-      "estimatedDeliveryDate" => "1596365935",
-      "deliveryDate" => null,
-      "delayed" => false,
-      "status" => {
-        "orderPlaced" => true,
-        "orderShipped" => true,
-        "outForDelivery" => true,
-        "orderDelivered" => false
-      }
-    }
-
-We can use decoders to extract exactly those pieces from this payload that we need,
-making assertions along the way of what the data looks like and generating helpful errors
-when reality does not match our expectations.
+```ruby
+{
+  "orderID" => "7EBWXB5",
+  "orderDate" => "1595674680",
+  "estimatedDeliveryDate" => "1596365935",
+  "deliveryDate" => null,
+  "delayed" => false,
+  "status" => {
+    "orderPlaced" => true,
+    "orderShipped" => true,
+    "outForDelivery" => true,
+    "orderDelivered" => false
+  }
+}
+```
+
+We can use decoders to extract exactly those pieces from this payload that we need, making assertions along the way of what the data looks like and generating helpful errors when reality does not match our expectations.
 
 For example, we could parse the above payload like so:
 
-    Order = Data.define(:id, :date, :status)
-    D = Decoding::Decoders
-    order_decoder = D.map(
-      D.field("orderID", D.string),
-      D.map(D.field("orderDate", D.string)) { Time.at(_1.to_i) },
-      D.hash(D.string, D.boolean)
-    ) { Order.new(*args) }
-    Decoding.decode(order_decoder, body)
-    # => Decoding::Ok(#<data Order
-      id: '7EBWXB5',
-      date: 2020-07-25 12:58:00 +0200,
-      status: {"orderPlaced"=>true,"orderShipped"=>true,"outForDelivery"=>true,"orderDelivered"=>false}>)
-
-Decoders take an input value and generate an output value from it. There are
-decoders for basic Ruby types, compound types such as arrays and hashes,
-decoders for trying out various decoders and, finally, there is the `map`
-decoder for decoding one or more output values from a given input value and
-applying a transformation to them with a block. All these decoders can be
-composed together into new, more complex decoders.
-
-A decoder is, in essence, a function that returns a result based on an input value. Consider
-how, roughly, the `string` decoder is implemented:
-
-    string_decoder = ->(input_value) do
-      if input_value.is_a?(String)
-        Decoding::Result.ok(input_value)
-      else
-        Decoding::Result.err("expected String, got #{input_value.class}")
-      end
-    end
-
-You can use the base decoders along with `map` to write more complex decoder. For example, you could
-extract a `time_decoder` from the example above:
-
-    time_decoder = D.map(D.string) { Time.at(_1.to_i) }
-
-When the shape of the incoming data is unknown, you can try out various
-decoders in a row to find the first that succeeds using `any`:
-
-    string_or_integer = D.any(D.string, D.integer)
-    Decoding.decode(string_or_integer, 1) # => Decoding::Ok(1)
-    Decoding.decode(string_or_integer, '1') # => Decoding::Ok('1')
-
-You can also base one decoder on a previously decoded value. For example, a
-payload might contain a version number describing its format. Use `and_then`
-to decode one value and then construct a new decoder to run against the same
-input using that value:
-
-    multiple_version_decoder = D.and_then(D.field("version", D.string)) do |version|
-      if version == "1"
-        D.field("name", D.string)
-      else
-        D.field("fullName", D.string)
-      end
-    end
+```ruby
+Order = Data.define(:id, :date, :status)
+D = Decoding::Decoders
+
+time_decoder = D.map(D.string) { Time.at(_1.to_i) }
+order_decoder = D.map(
+  D.field("orderID", D.string),
+  D.field("orderDate", time_decoder),
+  D.hash(D.string, D.boolean)
+) { Order.new(*args) }
+
+Decoding.decode(order_decoder, body)
+# => Decoding::Ok(#<data Order
+  id: '7EBWXB5',
+  date: 2020-07-25 12:58:00 +0200,
+  status: {"orderPlaced"=>true,"orderShipped"=>true,"outForDelivery"=>true,"orderDelivered"=>false}>)
+```
+
+Decoders take an input value and generate an output value from it. There are decoders for basic Ruby types, compound types such as arrays and hashes, decoders for trying out various decoders and, finally, there is the `map` decoder for decoding one or more output values from a given input value and applying a transformation to them with a block. All these decoders can be composed together into new, more complex decoders.
+
+A decoder is, in essence, a function that returns a result based on an input value. Consider how, roughly, the `string` decoder is implemented:
+
+```ruby
+string_decoder = ->(input_value) do
+  if input_value.is_a?(String)
+    Decoding::Result.ok(input_value)
+  else
+    Decoding::Result.err("expected String, got #{input_value.class}")
+  end
+end
+```
+
+You can use the base decoders along with `map` to write more complex decoder. For example, you could extract a `time_decoder` from the example above:
+
+```ruby
+time_decoder = D.map(D.string) { Time.at(_1.to_i) }
+```
+
+When the shape of the incoming data is unknown, you can try out various decoders in a row to find the first that succeeds using `any`:
+
+```ruby
+string_or_integer = D.any(D.string, D.integer)
+Decoding.decode(string_or_integer, 1) # => Decoding::Ok(1)
+Decoding.decode(string_or_integer, '1') # => Decoding::Ok('1')
+```
+
+You can also base one decoder on a previously decoded value. For example, a payload might contain a version number describing its format. Use `and_then` to decode one value and then construct a new decoder to run against the same input using that value:
+
+```ruby
+multiple_version_decoder = D.and_then(D.field("version", D.string)) do |version|
+  if version == "1"
+    D.field("name", D.string)
+  else
+    D.field("fullName", D.string)
+  end
+end
+```
 
 Now, you have a decoder that can work inputs using format version 1 and 2:
 
-    Decoding.decode(multiple_version_decoder, "version" => "1", "name" => "John")
-    # => "John"
-    Decoding.decode(multiple_version_decoder, "version" => "2", "fullName" => "Paul")
-    # => "Paul"
-
-The return values of decoding are `Decoding::Result` values, which come in
-`Ok` and `Err` subclasses. These describe how the decoding either succeeded or
-failed. The `Ok` values contain the decoded result, while the `Err` values
-always contain a string error message. It is up to you, as a developer, to
-decide how to deal with unsuccessful decoding.
+```ruby
+Decoding.decode(multiple_version_decoder, "version" => "1", "name" => "John")
+# => "John"
+Decoding.decode(multiple_version_decoder, "version" => "2", "fullName" => "Paul")
+# => "Paul"
+```
+
+The return values of decoding are `Decoding::Result` values, which come in `Ok` and `Err` subclasses. These describe how the decoding either succeeded or failed. The `Ok` values contain the decoded result, while the `Err` values always contain a string error message. It is up to you, as a developer, to decide how to deal with unsuccessful decoding.
+
+## Available decoders
+
+The following decoders are included:
+
+* Basic types
+    * `string`
+    * `integer`
+    * `float`
+    * `numeric`
+    * `nil`
+    * `true`
+    * `false`
+    * `boolean`
+    * `symbol`
+    * `regexp`
+* Utility decoders
+    * `succeed`
+    * `fail`
+    * `original`
+    * `map`
+    * `decode_hash`
+    * `and_then`
+* Compound decoders
+    * `any`
+    * `optional`
+    * `field`
+    * `array`
+    * `index`
+    * `hash`
+    * `at`
 
 ## Development
 

data/lib/decoding/decoder.rb

@@ -2,6 +2,7 @@
 
 require "forwardable"
 require_relative "result"
+require_relative "failure"
 
 module Decoding
   # A decoder is a callable object that reads any input value and returns an
@@ -10,6 +11,7 @@ module Decoding
   # @abstract
   class Decoder
     extend Forwardable
+
     def_delegators "Decoding::Result", :all, :ok, :err
 
     # @param value [Object]
@@ -18,5 +20,9 @@ module Decoding
 
     # @return [Decoding::Decoder<a>]
     def to_decoder = self
+
+    # @param str [String]
+    # @return [Decoding::Failure]
+    def failure(str) = Decoding::Failure.new(str)
   end
 end

data/lib/decoding/decoders/any.rb

@@ -10,9 +10,6 @@ module Decoding
     #
     # @see Decoding::Decoders.any
     class Any < Decoder
-      # @private
-      Err = Result.err("None of the decoders matched")
-
       # @param decoder [Decoding::Decoder<Object>]
       # @param decoders [Decoding::Decoder<Object>]
       def initialize(decoder, *decoders)
@@ -23,7 +20,8 @@ module Decoding
       # @param value [Object]
       # @return [Decoding::Result<Object>]
       def call(value)
-        @decoders.lazy.map { _1.call(value) }.find(-> { Err }, &:ok?)
+        err_proc = -> { err(failure("None of the decoders matched")) }
+        @decoders.lazy.map { _1.call(value) }.find(err_proc, &:ok?)
       end
     end
   end

data/lib/decoding/decoders/array.rb

@@ -21,7 +21,7 @@ module Decoding
         if value.is_a?(::Array)
           value
             .each_with_index
-            .map { |v, i| @decoder.call(v).map_err { |e| "error decoding array item #{i}: #{e}" } }
+            .map { |v, i| @decoder.call(v).map_err { _1.push(i) } }
             .then { all _1 }
         else
           err("expected an Array, got: #{value.class}")

data/lib/decoding/decoders/at.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require_relative "../decoder"
+
+module Decoding
+  module Decoders
+    # Decode a value in deeply nested hashes.
+    #
+    # @see Decoding::Decoders.field
+    class At < Decoder
+      # @param keys [Array<Object>]
+      # @param decoder [Decoding::Decoder<a>]
+      def initialize(*keys, decoder)
+        @keys = keys.to_a
+        @decoder = decoder.to_decoder
+        super()
+      end
+
+      # @param value [Object]
+      # @return [Deceoding::Result<a>]
+      def call(value)
+        first, *rest = @keys.reverse
+        nested_decoder = rest.reduce(Decoders::Field.new(first, @decoder)) do |acc, k|
+          Decoders::Field.new(k, acc)
+        end
+        nested_decoder.call(value)
+      end
+    end
+  end
+end

data/lib/decoding/decoders/field.rb

@@ -21,7 +21,7 @@ module Decoding
       def call(value)
         if value.is_a?(::Hash)
           if value.key?(@key)
-            @decoder.call(value.fetch(@key))
+            @decoder.call(value.fetch(@key)).map_err { _1.push(@key) }
           else
             err("expected a Hash with key #{@key}")
           end

data/lib/decoding/decoders/hash.rb

@@ -25,11 +25,11 @@ module Decoding
               [
                 @key_decoder
                   .call(k)
-                  .map_err { |e| "error decoding key #{k.inspect}: #{e}" },
+                  .map_err { |e| failure("error decoding key #{k.inspect}: #{e}") },
 
                 @value_decoder
                   .call(v)
-                  .map_err { |e| "error decoding value for key #{k.inspect}: #{e}" }
+                  .map_err { |e| failure("error decoding value for key #{k.inspect}: #{e}") }
               ]
             )
           end

data/lib/decoding/decoders/match.rb

@@ -19,9 +19,9 @@ module Decoding
         if @pattern === value
           ok(value)
         elsif @pattern.is_a?(Class)
-          err("expected #{@pattern}, got #{value.class}")
+          err(failure("expected #{@pattern}, got #{value.class}"))
         else
-          err("expected value matching #{@pattern.inspect}, got: #{value.inspect}")
+          err(failure("expected value matching #{@pattern.inspect}, got: #{value.inspect}"))
         end
       end
     end

data/lib/decoding/decoders/pass.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Decoding
+  module Decoders
+    class Pass < Decoder
+      def call(value) = ok(value)
+    end
+  end
+end

data/lib/decoding/decoders.rb

@@ -8,6 +8,8 @@ require_relative "decoders/array"
 require_relative "decoders/index"
 require_relative "decoders/hash"
 require_relative "decoders/and_then"
+require_relative "decoders/at"
+require_relative "decoders/pass"
 require_relative "result"
 
 module Decoding
@@ -26,6 +28,13 @@ module Decoding
     # @see Decoding::Decoders::Match
     def string = Decoders::Match.new(String)
 
+    # Decode any string value that matches a regular expression.
+    #
+    # @param re [Regexp, String]
+    # @return [Decoding::Decoder<String>]
+    # @see Decoding::Decoders::Match
+    def regexp(re) = Decoders::Match.new(Regexp.new(re))
+
     # Decode any integer value.
     #
     # @example
@@ -104,7 +113,14 @@ module Decoding
     # @example
     #   decode(fail("oh no"), "foo") # => Decoding::Err("oh no")
     # @return [Decoding::Decoder<String>]
-    def fail(value) = ->(_) { Result.err(value) }
+    def fail(value) = ->(_) { Result.err(Decoding::Failure.new(value)) }
+
+    # A decoder that returns the input value, unaltered.
+    #
+    # @example
+    #   decode(original, [1, 2]) # => Decoding::Ok([1, 2])
+    # @return [Decoding::Decoder<Object>]
+    def original = Decoders::Pass.new
 
     # @!group Compound decoders
 
@@ -199,6 +215,27 @@ module Decoding
     # @see Decoding::Decoders::Hash
     def hash(...) = Decoders::Hash.new(...)
 
+    # Decode a value into a hash using multiple decoders.
+    #
+    # This is a shortcut for:
+    #
+    #   deocde(map(field("id", integer), field("name", string)) { |id, name|
+    #     { id:, name: }
+    #   }, { "id" => 1, "name" => "John" })
+    #   # => Decoding::Ok({ id: 1, name: "John" })
+    #
+    # @example
+    #   decode(decode_hash(
+    #     id: field("id", integer)
+    #   ), { "id" => 1 })
+    #   # => Decode::Ok({ id: 1 })
+    # @return Decoding::Decoder
+    def decode_hash(decoders)
+      map(*decoders.values) do |*values|
+        decoders.keys.zip(values).to_h
+      end
+    end
+
     # Create a decoder that depends on a previously decoded value.
     #
     # @example
@@ -220,5 +257,22 @@ module Decoding
     #   @return [Decoding::Decoder<b>]
     # @see Decoding::Decoders::AndThen
     def and_then(...) = Decoders::AndThen.new(...)
+
+    # Decode deeply-nested fields.
+    #
+    # @example
+    #   decoder = at('a', 'b', 'c', string)
+    #   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")
+    # @overload at(*fields, decoder)
+    #   @param fields [String]
+    #   @param decoder [Decoding::Decoder<a>]
+    #   @return [Decoding::Decoder<a>]
+    # @see Decoding::Decoders::At
+    def at(...)
+      Decoders::At.new(...)
+    end
   end
 end

data/lib/decoding/failure.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Decoding
+  class Failure
+    protected attr_reader :msg
+    protected attr_reader :path
+
+    # @paramn msg [String]
+    def initialize(msg)
+      @msg = msg
+      @path = []
+    end
+
+    def eql?(other)
+      other.is_a?(self.class) &&
+        msg == other.msg &&
+        path == other.path
+    end
+    alias == eql?
+
+    # Add segments to the stack of errors.
+    #
+    # This is useful to create clearer error messages when using compound
+    # decoders, such as `array(string)`. If the `string` decoder fails with an
+    # error, the `array` decoder can push `3` to the stack to indicate that
+    # happened at index 3 in its input value.
+    #
+    # @param segment [String]
+    # @return [Decoding::Failure]
+    def push(segment)
+      @path << segment
+      self
+    end
+
+    def to_s
+      if @path.any?
+        "Error at .#{@path.reverse.join(".")}: #{@msg}"
+      else
+        @msg
+      end
+    end
+  end
+end

data/lib/decoding/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Decoding
-  VERSION = "0.1.0"
+  VERSION = "0.2.0"
 end

data/lib/decoding.rb

@@ -118,5 +118,5 @@ module Decoding
   # @param decoder [Decoding::Decoder<a>]
   # @param value [Object]
   # @return [Decoding::Result<a>]
-  def decode(decoder, value) = decoder.call(value)
+  def decode(decoder, value) = decoder.call(value).map_err(&:to_s)
 end

metadata

@@ -1,16 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: decoding
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Arjan van der Gaag
-autorequire:
 bindir: exe
 cert_chain: []
-date: 2024-06-07 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies: []
-description:
 email:
 - arjan@arjanvandergaag.nl
 executables: []
@@ -32,11 +30,14 @@ files:
 - lib/decoding/decoders/and_then.rb
 - lib/decoding/decoders/any.rb
 - lib/decoding/decoders/array.rb
+- lib/decoding/decoders/at.rb
 - lib/decoding/decoders/field.rb
 - lib/decoding/decoders/hash.rb
 - lib/decoding/decoders/index.rb
 - lib/decoding/decoders/map.rb
 - lib/decoding/decoders/match.rb
+- lib/decoding/decoders/pass.rb
+- lib/decoding/failure.rb
 - lib/decoding/result.rb
 - lib/decoding/version.rb
 - sig/decoding.rbs
@@ -48,7 +49,6 @@ metadata:
   homepage_uri: https://github.com/avdgaag/decoding
   source_code_uri: https://github.com/avdgaag/decoding
   rubygems_mfa_required: 'true'
-post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -63,8 +63,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.3
-signing_key:
+rubygems_version: 3.6.9
 specification_version: 4
 summary: Decode dynamic values into known Ruby data structures
 test_files: []