dio 0.0.2 → 0.0.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2bdc81fcaa60149f840667355881ac6a53875ef032ca860a1bd8c695ecb5557e
-  data.tar.gz: 7916ffd72b1a56a65425e1e43a91c48d788d44e3866c265826425f43c84f53e1
+  metadata.gz: b059e97a8c1f5e6d1d68b445e51c553c14657ec837de6b61bbe1ce6bd8ccc106
+  data.tar.gz: 327197a40cc4cc1a3e0f814c60bb0f78bab24bff8b8012d69430a93454712ad2
 SHA512:
-  metadata.gz: abc3478a6776c6a37ce181437fe168ca54eae42f5919f48b17e8a331641fd1038fe12a465ad70a52ad4e5f69cef239c1ffa11f72ef05875fe908e0d2b0b532ba
-  data.tar.gz: a8c94fcda04a3d2e9cd88f89107cf63f860f56c0d16b80a3c2fbf0a8788455d93fff5a35425378669e5c948287d9201da375c75f536ad32a43181cfa86e9ad06
+  metadata.gz: c9fd3543e1c9fca221b21db3629467b1f481c41e0a8191057e1d72bcfe1d190e859e902453e7292b45bb11a48ba56328582ff80d2dc10926aeca3d9a8b0dac11
+  data.tar.gz: '0194555bdc1bc59719e7c09167c26a7159ceff987dbb200754623694e3d49b2e1b87cf0ded4bfb4ac4af2eee05a1df9e2cb6f160bb95e889b6be3705caf55cdf'

data/.gitignore

@@ -7,5 +7,8 @@
 /spec/reports/
 /tmp/
 
+# Gem builds
+*.gem
+
 # rspec failure tracking
 .rspec_status

data/CHANGELOG.md

@@ -0,0 +1,20 @@
+# Changelog
+
+## Unreleased
+
+* None
+
+## 0.0.3 - 01/17/2021
+
+* Forwarders introduced
+  * Base concept of Forwarder and two new Forwarders introduced
+  * Attribute Forwarder to only work on `attr_*` methods, narrowing scope
+  * String Hash Forwarder to work on String keyed Hashes
+
+## 0.0.2 - 01/17/2021
+
+* [Patch 1](https://github.com/baweaver/dio/issues/1) - Lock Ruby version to 3.x
+
+## 0.0.1 - 01/17/2021
+
+* Initial release

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    dio (0.0.1)
+    dio (0.0.3)
 
 GEM
   remote: https://rubygems.org/

data/README.md

@@ -15,8 +15,166 @@ match against it.
 
 ## Usage
 
-Further usage instructions will be documented at a later date, see
-`spec/dio_spec.rb` for ideas in the mean time.
+There are three core types of Forwarders, the center of how Dio works:
+
+1. **Dynamic** - Uses `public_send` for `Hash` matches, and `Array` method coercion for `Array` matches
+2. **Attribute** - Uses `attr_*` methods as source of match data
+3. **String Hash** - Treats `String` Hashes like `Symbol` ones for the purpose of matching.
+
+Let's take a look at each of them.
+
+### Dynamic Forwarder
+
+Used with `Dio.dynamic` or `Dio[]`, the default forwarder. This uses `public_send` to extract attributes for pattern matching.
+
+#### With Hash Matching
+
+With an `Integer` this might look like this:
+
+```ruby
+Dio[1] in { succ: { succ: { succ: 4 } } }
+# => true
+```
+
+This has the same result as calling `1.succ.succ.succ` with each nested `Hash` in the pattern match working on the next value. That means it can also be used to do this:
+
+```ruby
+Dio[1] in {
+  succ: { chr: "\x02", to_s: '2' },
+  to_s: '1'
+}
+```
+
+#### With Array Matching
+
+If the object under the wrapper provides a method that can be used to coerce the value into an `Array` it can be used for an `Array` match.
+
+Those methods are: `to_a`, `to_ary`, and `map`.
+
+Given a `Node` class with a value and a set of children:
+
+```ruby
+Node = Struct.new(:value, :children)
+```
+
+We can match against it as if it were capable of natively pattern matching:
+
+```ruby
+tree = Node[1,
+  Node[2, Node[3, Node[4]]],
+  Node[5],
+  Node[6, Node[7], Node[8]]
+]
+
+case Dio.dynamic(tree)
+in [1, [*, [5, _], *]]
+  true
+else
+  false
+end
+```
+
+### Attribute Forwarder
+
+Attribute Forwarders are more conservative than Dynamic ones as they only work on public attributes, or those that are defined with `attr_*`. In the case of this class:
+
+```ruby
+class Person
+  attr_reader :name, :age, :children
+
+  def initialize(name:, age:, children: [])
+    @name = name
+    @age = age
+    @children = children
+  end
+end
+```
+
+...the attributes available would be `name`, `age`, and `children`. This also means that you can dive into `children` as well.
+
+#### With Hash Matching
+
+Let's say we had Alice here:
+
+```ruby
+Person.new(
+  name: 'Alice',
+  age: 40,
+  children: [
+    Person.new(name: 'Jim', age: 10),
+    Person.new(name: 'Jill', age: 10)
+  ]
+)
+```
+
+With Hash style matching we can do this:
+
+```ruby
+case Dio.attribute(alice)
+in { name: /^A/, age: 30..50 }
+  true
+else
+  false
+end
+```
+
+...which, as pattern matches use `===` lets us use a lot of other fun things. We can even go deeper into searching through the `children` attribute:
+
+```ruby
+case Dio.attribute(alice)
+in { children: [*, { name: /^J/ }, *] }
+  true
+else
+  false
+end
+```
+
+#### With Array Matching
+
+This one is a bit more spurious, as it applies the attributes in the name it sees them. For something like our `Node` above with two attributes it will work the same as `dynamic`.
+
+### String Hash Forwarder
+
+Pattern Matching cannot apply to `String` keys, which can be annoying when working with data and not wanting to deep transform it into `Symbol` keys. The String Hash Forwarder tries to address this.
+
+#### With Hash Matching
+
+Let's say we had the following `Hash`:
+
+```ruby
+hash = {
+  'a' => 1,
+  'b' => 2,
+  'c' => {
+    'd' => 3,
+    'e' => {
+      'f' => 4
+    }
+  }
+}
+```
+
+We can match against it by using the `Symbol` equivalents of our `String` keys:
+
+```ruby
+case Dio.string_hash(hash)
+in { a: 1, b: 2 }
+  true
+else
+  false
+end
+```
+
+...and because of the nature of Dio you can continue to dive deeper:
+
+```ruby
+case Dio.string_hash(hash)
+in { a: 1, b: 2, c: { d: 1..10, e: { f: 3.. } } }
+  true
+else
+  false
+end
+```
 
 ## Installation
 

data/lib/dio.rb

@@ -1,7 +1,7 @@
 require 'dio/version'
 require 'dio/public_api'
 require 'dio/errors'
-require 'dio/dive_forwarder'
+require 'dio/forwarders'
 
 module Dio
   extend PublicApi

data/lib/dio/errors.rb

@@ -11,5 +11,17 @@ module Dio
 
       def initialize(msg=MSG) = super
     end
+
+    # Error raised when no deconstruction method is available on an object being
+    # treated like an Array deconstruction.
+    #
+    # @author [baweaver]
+    # @since 0.0.1
+    class UnknownAttributesProvided < ArgumentError
+      # Error message
+      MSG = 'Unknown attribute arguments provided to method'
+
+      def initialize(attributes) = super("#{MSG}: #{attributes.join(', ')}")
+    end
   end
 end

data/lib/dio/forwarders.rb

@@ -0,0 +1,8 @@
+require 'dio/forwarders/base_forwarder'
+require 'dio/forwarders/attribute_forwarder'
+require 'dio/forwarders/string_hash_forwarder'
+
+module Dio
+  module Forwarders
+  end
+end

data/lib/dio/forwarders/attribute_forwarder.rb

@@ -0,0 +1,76 @@
+require 'delegate'
+
+module Dio
+  module Forwarders
+    # A more controlled forwarder that targets only `attr_` type methods like
+    # `attr_reader` and `attr_accessor`. These attributes are found by diffing
+    # instance variables and method names to find generated accessor methods.
+    #
+    # It should be noted that this could be faster if there was an assumption
+    # of purity at the time of the match. I may make another variant for that.
+    #
+    # @author [baweaver]
+    # @since 0.0.3
+    #
+    class AttributeForwarder < BaseForwarder
+      # Wrapper for creating a new Forwarder
+      NEW_DIVE = -> v { new(v) }
+
+      def initialize(base_object)
+        ivars = Set.new base_object
+          .instance_variables
+          .map { _1.to_s.delete('@').to_sym }
+
+        all_methods = Set.new base_object.methods
+
+        @attributes = ivars.intersection(all_methods)
+
+        super
+      end
+
+      # Deconstructs from a list of attribute names, wrapping each value
+      # in a new dive in case the pattern match goes further than one level.
+      #
+      # @return [Array]
+      def deconstruct
+        return @base_object.map(&NEW_DIVE) if @base_object.is_a?(Array)
+
+        @attributes.map { NEW_DIVE[@base_object.public_send(_1)] }
+      end
+
+      # Deconstructs attributes from an object, wrapping each value in a new
+      # dive in case the pattern match goes further than one level.
+      #
+      # @param keys [Array]
+      #   Keys to be extracted, diffed against possible attributes
+      #
+      # @raises [Dio::Errors::UnknownAttributesProvided]
+      #   Guard against unknown attributes without an associated accessor
+      #   method
+      #
+      # @return [Hash]
+      def deconstruct_keys(keys)
+        key_set      = Set.new(keys)
+        unknown_keys = key_set - @attributes
+
+        if unknown_keys.any?
+          raise Dio::Errors::UnknownAttributesProvided.new(unknown_keys)
+        end
+
+        known_keys = @attributes.intersection(key_set)
+
+        known_keys.to_h { [_1, NEW_DIVE[@base_object.public_send(_1)]] }
+      end
+
+      # Unwrapped context, aliased afterwards to use Ruby's delegator interface
+      #
+      # @return [Any]
+      #   Originally wrapped object
+      def value
+        @base_object
+      end
+
+      alias_method :__getobj__, :value
+    end
+  end
+end

data/lib/dio/forwarders/base_forwarder.rb

@@ -0,0 +1,131 @@
+require 'delegate'
+
+module Dio
+  module Forwarders
+    # Allows for Pattern Matching against arbitrary objects by wrapping them
+    # in an interface that understands methods of deconstructing objects.
+    #
+    # **Approximating Deconstruction**
+    #
+    # As Ruby does not, by default, define `deconstruct` and `deconstruct_keys` on
+    # objects this class attempts to approximate them.
+    #
+    # This class does, however, do something unique in treating `deconstruct_keys`
+    # as a series of calls to sent to the class and its "nested" values.
+    #
+    # **Demonstrating Nested Values**
+    #
+    # Consider an integer:
+    #
+    # ```ruby
+    # Dio[1] in { succ: { succ: { succ: 4 } } }
+    # # => true
+    # ```
+    #
+    # It has no concept of deconstruction, except in that its `succ` method returns
+    # a "nested" value we can match against, allowing us to "dive into" the
+    # object, diving us our namesake Dio, or "Dive Into Object"
+    #
+    # **Delegation**
+    #
+    # As with most monadic-like design patterns that add additional behavior by
+    # wrapping objects we need to extract the value at the end to do anything
+    # particularly useful.
+    #
+    # By adding delegation to this class we have a cheat around this in that
+    # any method called on the nested DiveForwarder instances will call through
+    # to the associated base object instead.
+    #
+    # I am not 100% sold on this approach, and will consider it more in the
+    # future.
+    #
+    # @author [baweaver]
+    #
+    class BaseForwarder < ::Delegator
+      # Wrapper for creating a new Forwarder
+      NEW_DIVE = -> v { new(v) }
+
+      # Creates a new delegator that understands the pattern matching interface
+      #
+      # @param base_object [Any]
+      #   Any object that does not necessarily understand pattern matching
+      #
+      # @return [DiveForwarder]
+      def initialize(base_object)
+        @base_object = base_object
+      end
+
+      # Approximation of an Array deconstruction:
+      #
+      # ```ruby
+      # [1, 2, 3] in [*, 2, *]
+      # ```
+      #
+      # Attempts to find a reasonable interface by which to extract values
+      # to be matched. If an object that knows how to match already is sent
+      # through wrap its child values for deeper matching.
+      #
+      # Current interface will work with `to_a`, `to_ary`, `map`, and values
+      # that can already `deconstruct`. If others are desired please submit a PR
+      # to add them
+      #
+      # @raises [Dio::Errors::NoDeconstructionMethod]
+      #   If no method of deconstruction exists, an exception is raised to
+      #   communicate the proper interface and note the abscense of a current one.
+      #
+      # @return [Array[DiveForwarder]]
+      #   Values lifted into a Dio context for further matching
+      def deconstruct
+        return @base_object.deconstruct.map!(&NEW_DIVE) if @base_object.respond_to?(:deconstruct)
+
+        return @base_object.to_a.map!(&NEW_DIVE) if @base_object.respond_to?(:to_a)
+        return @base_object.to_ary.map!(&NEW_DIVE) if @base_object.respond_to?(:to_ary)
+        return @base_object.map(&NEW_DIVE) if @base_object.respond_to?(:map)
+
+        raise Dio::Errors::NoDeconstructionMethod
+      end
+
+      # Approximates `deconstruct_keys` for Hashes, except in adding `Qo`-like
+      # behavior that allows to treat objects as "nested values" through their
+      # method calls.
+      #
+      # **Deconstructing an Object**
+      #
+      # In `Qo` one could match against an object by calling to its methods using
+      # `public_send`. This allowed one to "dive into" an object through a series
+      # of method calls, approximating a Hash pattern match.
+      #
+      # **Native Behavior**
+      #
+      # If the object already responds to `deconstruct_keys` this method will
+      # behave similarly to `deconstruct` and wrap its values as new
+      # `DiveForwarder` contexts.
+      #
+      # @param keys [Array]
+      #   Keys to be extracted from the object
+      #
+      # @return [Hash]
+      #   Deconstructed keys pointing to associated values extracted from a Hash
+      #   or an Object. Note that these values are matched against using `===`.
+      def deconstruct_keys(keys)
+        if @base_object.respond_to?(:deconstruct_keys)
+          @base_object
+            .deconstruct_keys(keys)
+            .transform_values!(&NEW_DIVE)
+        else
+          keys.to_h { |k| @base_object.public_send(k).then { |v| [k, NEW_DIVE[v]] } }
+        end
+      end
+
+      # Unwrapped context, aliased afterwards to use Ruby's delegator interface
+      #
+      # @return [Any]
+      #   Originally wrapped object
+      def value
+        @base_object
+      end
+
+      alias_method :__getobj__, :value
+    end
+  end
+end

data/lib/dio/forwarders/string_hash_forwarder.rb

@@ -0,0 +1,63 @@
+require 'delegate'
+
+module Dio
+  module Forwarders
+    # Pattern Matching relies on Symbol keys for Hash matching, but a significant
+    # number of Ruby Hashes are keyed with Strings. This forwarder addresses
+    # that issue by transforming String keys into Symbols for the sake of matching
+    # against them:
+    #
+    # ```ruby
+    # Dio.string_hash({ 'a' => 1 }) in { a: 1 }
+    # # => true
+    # ```
+    #
+    # @author [baweaver]
+    # @since 0.0.3
+    #
+    class StringHashForwarder < BaseForwarder
+      # Wrapper for creating a new Forwarder
+      NEW_DIVE = -> v { new(v) }
+
+      # If an Array is provided from nested values we may want to match against
+      # it as well. Wrap the values in new forwarders to accomodate this.
+      #
+      # @raises [Dio::Errors::NoDeconstructionMethod]
+      #   Debating on this one. If the base is not an Array it complicates how
+      #   to Array match against a Hash. Raise an error for now, consider
+      #   revisiting later.
+      #
+      # @return [Array]
+      def deconstruct
+        return @base_object.map(&NEW_DIVE) if @base_object.is_a?(Array)
+
+        # Debating on this one
+        raise Dio::Errors::NoDeconstructionMethod
+      end
+
+      # Extracts keys from a Hash by treating the provided keys like Strings.
+      # Return the base object with keys transformed to Symbols to accomodate
+      # pattern matching features.
+      #
+      # @param keys [Array]
+      #   Keys to extract
+      #
+      # @return [Hash]
+      def deconstruct_keys(keys)
+        @base_object
+          .slice(*keys.map(&:to_s))
+          .to_h { |k, v| [k.to_sym, NEW_DIVE[v]] }
+      end
+
+      # Unwrapped context, aliased afterwards to use Ruby's delegator interface
+      #
+      # @return [Any]
+      #   Originally wrapped object
+      def value
+        @base_object
+      end
+
+      alias_method :__getobj__, :value
+    end
+  end
+end

data/lib/dio/public_api.rb

@@ -1,4 +1,8 @@
 module Dio
+  # Public API for Dio
+  #
+  # @author [baweaver]
+  # @since 0.0.1
   module PublicApi
     # Treats `[]` like an alternative constructor and forwards to `DiveForwarder`
     #
@@ -7,6 +11,31 @@ module Dio
     #
     # @return [Dio::DiveForwarder]
     #   Dio pattern matching interface
-    def [](...) = Dio::DiveForwarder.new(...)
+    def [](...) = Dio::Forwarders::BaseForwarder.new(...)
+
+    # Dynamic Forwarder, uses `public_send` for Hash forwarding
+    #
+    # @param ... [Any]
+    #   Arguments to match against
+    #
+    # @return [Dio::Forwarders::BaseForwarder]
+    def dynamic(...) = Dio::Forwarders::BaseForwarder.new(...)
+
+    # Attribute Forwarder, extracts `attr_*` methods to match against
+    #
+    # @param ... [Any]
+    #   Arguments to match against
+    #
+    # @return [Dio::Forwarders::AttributeForwarder]
+    def attribute(...) = Dio::Forwarders::AttributeForwarder.new(...)
+
+    # String Hash Forwarder, treats a String Hash like a Symbol Hash for
+    # matching against.
+    #
+    # @param ... [Any]
+    #   Arguments to match against
+    #
+    # @return [Dio::Forwarders::StringHashForwarder]
+    def string_hash(...) = Dio::Forwarders::StringHashForwarder.new(...)
   end
 end

data/lib/dio/version.rb

@@ -1,3 +1,3 @@
 module Dio
-  VERSION = '0.0.2'.freeze
+  VERSION = '0.0.3'.freeze
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: dio
 version: !ruby/object:Gem::Version
-  version: 0.0.2
+  version: 0.0.3
 platform: ruby
 authors:
 - Brandon Weaver
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2021-01-17 00:00:00.000000000 Z
+date: 2021-01-18 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -75,6 +75,7 @@ extra_rdoc_files: []
 files:
 - ".gitignore"
 - ".rspec"
+- CHANGELOG.md
 - CODE_OF_CONDUCT.md
 - Gemfile
 - Gemfile.lock
@@ -86,8 +87,11 @@ files:
 - bin/setup
 - dio.gemspec
 - lib/dio.rb
-- lib/dio/dive_forwarder.rb
 - lib/dio/errors.rb
+- lib/dio/forwarders.rb
+- lib/dio/forwarders/attribute_forwarder.rb
+- lib/dio/forwarders/base_forwarder.rb
+- lib/dio/forwarders/string_hash_forwarder.rb
 - lib/dio/public_api.rb
 - lib/dio/version.rb
 homepage: https://www.github.com/baweaver/dio

data/lib/dio/dive_forwarder.rb

@@ -1,129 +0,0 @@
-require 'delegate'
-
-module Dio
-  # Allows for Pattern Matching against arbitrary objects by wrapping them
-  # in an interface that understands methods of deconstructing objects.
-  #
-  # **Approximating Deconstruction**
-  #
-  # As Ruby does not, by default, define `deconstruct` and `deconstruct_keys` on
-  # objects this class attempts to approximate them.
-  #
-  # This class does, however, do something unique in treating `deconstruct_keys`
-  # as a series of calls to sent to the class and its "nested" values.
-  #
-  # **Demonstrating Nested Values**
-  #
-  # Consider an integer:
-  #
-  # ```ruby
-  # Dio[1] in { succ: { succ: { succ: 4 } } }
-  # # => true
-  # ```
-  #
-  # It has no concept of deconstruction, except in that its `succ` method returns
-  # a "nested" value we can match against, allowing us to "dive into" the
-  # object, diving us our namesake Dio, or "Dive Into Object"
-  #
-  # **Delegation**
-  #
-  # As with most monadic-like design patterns that add additional behavior by
-  # wrapping objects we need to extract the value at the end to do anything
-  # particularly useful.
-  #
-  # By adding delegation to this class we have a cheat around this in that
-  # any method called on the nested DiveForwarder instances will call through
-  # to the associated base object instead.
-  #
-  # I am not 100% sold on this approach, and will consider it more in the
-  # future.
-  #
-  # @author [baweaver]
-  #
-  class DiveForwarder < ::Delegator
-    # Wrapper for creating a new DiveForwarder
-    NEW_DIVE = -> v { DiveForwarder.new(v) }
-
-    # Creates a new delegator that understands the pattern matching interface
-    #
-    # @param base_object [Any]
-    #   Any object that does not necessarily understand pattern matching
-    #
-    # @return [DiveForwarder]
-    def initialize(base_object)
-      @base_object = base_object
-    end
-
-    # Approximation of an Array deconstruction:
-    #
-    # ```ruby
-    # [1, 2, 3] in [*, 2, *]
-    # ```
-    #
-    # Attempts to find a reasonable interface by which to extract values
-    # to be matched. If an object that knows how to match already is sent
-    # through wrap its child values for deeper matching.
-    #
-    # Current interface will work with `to_a`, `to_ary`, `map`, and values
-    # that can already `deconstruct`. If others are desired please submit a PR
-    # to add them
-    #
-    # @raises [Dio::Errors::NoDeconstructionMethod]
-    #   If no method of deconstruction exists, an exception is raised to
-    #   communicate the proper interface and note the abscense of a current one.
-    #
-    # @return [Array[DiveForwarder]]
-    #   Values lifted into a Dio context for further matching
-    def deconstruct
-      return @base_object.deconstruct.map!(&NEW_DIVE) if @base_object.respond_to?(:deconstruct)
-
-      return @base_object.to_a.map!(&NEW_DIVE) if @base_object.respond_to?(:to_a)
-      return @base_object.to_ary.map!(&NEW_DIVE) if @base_object.respond_to?(:to_ary)
-      return @base_object.map(&NEW_DIVE) if @base_object.respond_to?(:map)
-
-      raise Dio::Errors::NoDeconstructionMethod
-    end
-
-    # Approximates `deconstruct_keys` for Hashes, except in adding `Qo`-like
-    # behavior that allows to treat objects as "nested values" through their
-    # method calls.
-    #
-    # **Deconstructing an Object**
-    #
-    # In `Qo` one could match against an object by calling to its methods using
-    # `public_send`. This allowed one to "dive into" an object through a series
-    # of method calls, approximating a Hash pattern match.
-    #
-    # **Native Behavior**
-    #
-    # If the object already responds to `deconstruct_keys` this method will
-    # behave similarly to `deconstruct` and wrap its values as new
-    # `DiveForwarder` contexts.
-    #
-    # @param keys [Array]
-    #   Keys to be extracted from the object
-    #
-    # @return [Hash]
-    #   Deconstructed keys pointing to associated values extracted from a Hash
-    #   or an Object. Note that these values are matched against using `===`.
-    def deconstruct_keys(keys)
-      if @base_object.respond_to?(:deconstruct_keys)
-        @base_object
-          .deconstruct_keys(*keys)
-          .transform_values!(&NEW_DIVE)
-      else
-        keys.to_h { |k| @base_object.public_send(k).then { |v| [k, NEW_DIVE[v]] } }
-      end
-    end
-
-    # Unwrapped context, aliased afterwards to use Ruby's delegator interface
-    #
-    # @return [Any]
-    #   Originally wrapped object
-    def value
-      @base_object
-    end
-
-    alias_method :__getobj__, :value
-  end
-end