matchable 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 20eea165b65f710ddb8430164ad48ac52a4893382b7ce73065964b3d35fcc5e3
-  data.tar.gz: e1e50759a271a337147ef19c44c9f95d0725ef2f9556cdecbdb2e0a8d09ef9e9
+  metadata.gz: ea2b5bef957487e83b056970242e39508465ae5b3a4b466e881a71c8d235e7fd
+  data.tar.gz: 0d00fac4bda33448af11fdde57ee9bb010d1b50ff0be881084dea7a26d1b6dd2
 SHA512:
-  metadata.gz: 5d1ec0a429ed529641461774b7ea5bab46e49e41c2fe7cabe1d91d2357d935b44c5a26e778ac111d35a9e272147bb77de843a4cba960a0ff623204cf3019584e
-  data.tar.gz: fd72d05a74294d517a31dbfdfbc750c40c0bc84e4c2da3c7fd00c09f8009314d2c709789b467bf298d949a0d7ab05d0fc65e876a77a9ae5b3f26660732cde8f3
+  metadata.gz: 7f6cbb7043d57f74cb6131b536e277882aafaae7e05885ad79e7155707f236dd13263853f3ed212f0976f2fdd8e8ce1c21e2607504943a82b69f82fc56681b38
+  data.tar.gz: 78eed8f187eb98ef08c46fda76280123004b122c30a13d46ae9cab1bc412a8a66f3f266b5db808ebcd0d948e87af26090cf53f814c093e50dcaa1d26e416e545

data/.gitignore

@@ -1,3 +1,4 @@
+*.gem
 /.bundle/
 /.yardoc
 /_yardoc/

data/.ruby-version

@@ -0,0 +1 @@
+3.0.0

data/Gemfile

@@ -9,3 +9,4 @@ gem "rake", "~> 13.0"
 
 gem "rspec", "~> 3.0"
 gem "guard-rspec"
+gem "benchmark-ips"

data/Gemfile.lock

@@ -1,11 +1,12 @@
 PATH
   remote: .
   specs:
-    matchable (0.1.0)
+    matchable (0.1.1)
 
 GEM
   remote: https://rubygems.org/
   specs:
+    benchmark-ips (2.8.4)
     coderay (1.1.3)
     diff-lcs (1.4.4)
     ffi (1.14.2)
@@ -60,6 +61,7 @@ PLATFORMS
   x86_64-darwin-19
 
 DEPENDENCIES
+  benchmark-ips
   guard-rspec
   matchable!
   rake (~> 13.0)

data/benchmarks/dynamic_vs_generated_benchmark.rb

@@ -0,0 +1,136 @@
+#!/usr/bin/env ruby -W0
+
+require 'matchable'
+require 'benchmark/ips'
+
+class PersonMacro
+  include Matchable
+
+  deconstruct :new
+  deconstruct_keys :name, :age
+
+  attr_reader :name, :age
+
+  def initialize(name, age)
+    @name = name
+    @age  = age
+  end
+end
+
+class PersonDynamic
+  VALID_KEYS = %i(name age)
+
+  attr_reader :name, :age
+
+  def initialize(name, age)
+    @name = name
+    @age  = age
+  end
+
+  def deconstruct() = VALID_KEYS.map { public_send(_1) }
+
+  def deconstruct_keys(keys)
+    valid_keys = keys ? VALID_KEYS & keys : VALID_KEYS
+    valid_keys.to_h { [_1, public_send(_1)] }
+  end
+end
+
+alice_macro = PersonMacro.new('Alice', 42)
+alice_dynamic = PersonDynamic.new('Alice', 42)
+
+Benchmark.ips do |x|
+  x.report("[Person] Macro Generated - Full Hash") do
+    alice_macro in { name: /^A/, age: 30.. }
+  end
+
+  x.report("[Person] Macro Generated - Partial Hash") do
+    alice_macro in { name: /^A/ }
+  end
+
+  x.report("[Person] Macro Generated - Array") do
+    alice_macro in [/^A/, 30..]
+  end
+
+  x.report("[Person] Dynamic Generated - Full Hash") do
+    alice_dynamic in { name: /^A/, age: 30.. }
+  end
+
+  x.report("[Person] Dynamic Generated - Partial Hash") do
+    alice_dynamic in { name: /^A/ }
+  end
+
+  x.report("[Person] Dynamic Generated - Array") do
+    alice_dynamic in [/^A/, 30..]
+  end
+end
+
+puts '', '-' * 80, ''
+
+# 26 attributes, should be enough to stress things out
+LETTERS = ('a'..'z').to_a.map(&:to_sym)
+LETTER_IVARS = LETTERS.map { "@#{_1} = #{_1}" }.join("\n")
+LETTER_VALUES = LETTERS.each_with_index.to_h
+
+# Easier than typing 26 attrs
+eval <<~RUBY
+  class BigAttrMacro
+    include Matchable
+
+    deconstruct :new
+    deconstruct_keys *LETTERS
+
+    attr_reader *LETTERS
+
+    def initialize(#{LETTERS.join(', ')})
+      #{LETTER_IVARS}
+    end
+  end
+RUBY
+
+eval <<~RUBY
+  class BigAttrDynamic
+    VALID_KEYS = LETTERS
+
+    attr_reader *LETTERS
+
+    def initialize(#{LETTERS.join(', ')})
+      #{LETTER_IVARS}
+    end
+
+    def deconstruct() = VALID_KEYS.map { public_send(_1) }
+
+    def deconstruct_keys(keys)
+      valid_keys = keys ? VALID_KEYS & keys : VALID_KEYS
+      valid_keys.to_h { [_1, public_send(_1)] }
+    end
+  end
+RUBY
+
+big_attr_macro   = BigAttrMacro.new(*1..26)
+big_attr_dynamic = BigAttrDynamic.new(*1..26)
+
+Benchmark.ips do |x|
+  x.report("[BigAttr] Macro Generated - Full Hash") do
+    big_attr_macro in {}
+  end
+
+  x.report("[BigAttr] Macro Generated - Partial Hash") do
+    big_attr_macro in { a:, b:, c:, d:, e:, f: }
+  end
+
+  x.report("[BigAttr] Macro Generated - Array") do
+    big_attr_macro in [1, 2, 3, *]
+  end
+
+  x.report("[BigAttr] Dynamic Generated - Full Hash") do
+    big_attr_dynamic in {}
+  end
+
+  x.report("[BigAttr] Dynamic Generated - Partial Hash") do
+    big_attr_dynamic in { a:, b:, c:, d:, e:, f: }
+  end
+
+  x.report("[BigAttr] Dynamic Generated - Array") do
+    big_attr_dynamic in [1, 2, 3, *]
+  end
+end

data/benchmarks/dynamic_vs_generated_benchmark_results.txt

@@ -0,0 +1,55 @@
+Warming up --------------------------------------
+[Person] Macro Generated - Full Hash
+                       108.660k i/100ms
+[Person] Macro Generated - Partial Hash
+                       150.641k i/100ms
+[Person] Macro Generated - Array
+                       209.579k i/100ms
+[Person] Dynamic Generated - Full Hash
+                       102.585k i/100ms
+[Person] Dynamic Generated - Partial Hash
+                       154.093k i/100ms
+[Person] Dynamic Generated - Array
+                       136.640k i/100ms
+Calculating -------------------------------------
+[Person] Macro Generated - Full Hash
+                          1.104M (± 3.0%) i/s -      5.542M in   5.025098s
+[Person] Macro Generated - Partial Hash
+                          1.657M (± 1.8%) i/s -      8.436M in   5.093239s
+[Person] Macro Generated - Array
+                          2.101M (± 3.8%) i/s -     10.689M in   5.095977s
+[Person] Dynamic Generated - Full Hash
+                        998.994k (± 2.1%) i/s -      5.027M in   5.033974s
+[Person] Dynamic Generated - Partial Hash
+                          1.484M (± 3.6%) i/s -      7.551M in   5.093305s
+[Person] Dynamic Generated - Array
+                          1.421M (± 2.5%) i/s -      7.105M in   5.002556s
+
+--------------------------------------------------------------------------------
+
+Warming up --------------------------------------
+[BigAttr] Macro Generated - Full Hash
+                        62.462k i/100ms
+[BigAttr] Macro Generated - Partial Hash
+                        57.960k i/100ms
+[BigAttr] Macro Generated - Array
+                       159.136k i/100ms
+[BigAttr] Dynamic Generated - Full Hash
+                        19.686k i/100ms
+[BigAttr] Dynamic Generated - Partial Hash
+                        52.946k i/100ms
+[BigAttr] Dynamic Generated - Array
+                        29.178k i/100ms
+Calculating -------------------------------------
+[BigAttr] Macro Generated - Full Hash
+                        644.864k (± 5.9%) i/s -      3.248M in   5.054710s
+[BigAttr] Macro Generated - Partial Hash
+                        580.784k (± 3.4%) i/s -      2.956M in   5.096195s
+[BigAttr] Macro Generated - Array
+                          1.568M (± 4.0%) i/s -      7.957M in   5.082464s
+[BigAttr] Dynamic Generated - Full Hash
+                        194.429k (± 3.2%) i/s -    984.300k in   5.068253s
+[BigAttr] Dynamic Generated - Partial Hash
+                        518.690k (± 3.7%) i/s -      2.594M in   5.008953s
+[BigAttr] Dynamic Generated - Array
+                        295.488k (± 2.1%) i/s -      1.488M in   5.038268s

data/lib/matchable.rb

@@ -5,9 +5,30 @@ require_relative "matchable/version"
 # Interface for Pattern Matching hooks
 #
 # @author baweaver
-# @since 0.0.1
+# @since 0.1.0
 #
 module Matchable
+  # Nicety wrapper to ensure unmatched methods give a clear response on what's
+  # missing
+  #
+  # @author baweaver
+  # @since 0.1.1
+  #
+  class UnmatchedName < StandardError
+    def initialize(msg)
+      @msg = <<~ERROR
+        Some attributes are missing methods for the match. Ensure all attributes
+        have a method of the same name, or an `attr_` method.
+
+        Original Error: #{msg}
+      ERROR
+
+      super(@msg)
+    end
+  end
+
+  DeconstructedBranch = Struct.new(:method_name, :code_branch, :guard_condition)
+
   # Constant to prepend methods and extensions to
   MODULE_NAME = "MatchableDeconstructors".freeze
 
@@ -17,7 +38,7 @@ module Matchable
   # Class method hooks for adding pattern matching interfaces
   #
   # @author baweaver
-  # @since 0.0.1
+  # @since 0.1.0
   module ClassMethods
     # Hook for the `deconstruct` instance method which triggers its definition
     # based on a deconstruction method passed. If the method is not yet defined
@@ -28,12 +49,12 @@ module Matchable
     #
     # @return [Array[status, method_name]]
     def deconstruct(method_name)
-      return if deconstructable_module.const_defined?('DECONSTRUCTION_METHOD')
+      return if matchable_module.const_defined?("MATCHABLE_METHOD")
 
       # :new should mean :initialize if one wants to match against arguments
       # to :new
       method_name = :initialize if method_name == :new
-      deconstructable_module.const_set('DECONSTRUCTION_METHOD', method_name)
+      matchable_module.const_set("MATCHABLE_METHOD", method_name)
 
       # If this was called after the method was added, go ahead and attach,
       # otherwise we need some trickery to make sure the method is defined
@@ -77,26 +98,76 @@ module Matchable
     # @return [void]
     def deconstruct_keys(*keys)
       # Return early if called more than once
-      return if deconstructable_module.const_defined?('DECONSTRUCTION_KEYS')
+      return if matchable_module.const_defined?('MATCHABLE_KEYS')
 
       # Ensure keys are symbols, then generate Ruby code for each
       # key assignment branch to be used below
-      sym_keys        = keys.map(&:to_sym)
-      deconstructions = sym_keys.map { deconstructed_value(_1) }.join("\n\n")
+      sym_keys = keys.map(&:to_sym)
 
       # Retain a reference to which keys we deconstruct from
-      deconstructable_module.const_set('DECONSTRUCTION_KEYS', sym_keys)
+      matchable_module.const_set('MATCHABLE_KEYS', sym_keys)
+
+      # Lazy Hash mapping of all keys to all values wrapped in lazy
+      # procs.
+      #
+      # see: #lazy_match_value
+      matchable_module.const_set('MATCHABLE_LAZY_VALUES', lazy_match_values(sym_keys))
 
       # `public_send` can be slow, and `to_h` and `each_with_object` can also
       # be slow. This defines the direct method calls in-line to prevent
       # any performance penalties to generate optimal match code.
-      deconstructable_module.class_eval <<~RUBY, __FILE__ , __LINE__ + 1
+      #
+      # This generates and adds a method to the prepended module. We add YARDoc
+      # to this because the generated source can be seen and we want to be nice.
+      #
+      # We also intercept name errors to give more useful errors should it
+      # be implemented incorrectly.
+      matchable_module.class_eval <<~RUBY, __FILE__ , __LINE__ + 1
+        # Pattern Matching hooks for hash-like matches.
+        #
+        # This method was generated by Matchable. Make sure all properties have
+        # associated methods attached or this will raise an error.
+        #
+        # @param keys [Array[Symbol]]
+        #   Keys to limit the deconstruction to. If keys are `nil` then return
+        #   all possible keys instead.
+        #
+        # @return [Hash[Symbol, Any]]
+        #   Deconstructed keys and values
         def deconstruct_keys(keys)
+          # If `keys` is `nil` we want to return all possible keys. This
+          # generates all of them as a direct Hash representation and
+          # returns that, rather than guard all methods below on
+          # `keys.nil? || ...`.
+          if keys.nil?
+            return {
+              #{nil_guard_values(sym_keys)}
+            }
+          end
+
+          # If keys are present, we want to iterate the keys to add requested
+          # values. Before we iterate we also want to ensure only valid keys
+          # are being passed through here.
           deconstructed_values = {}
+          valid_keys           = MATCHABLE_KEYS & keys
 
-          #{deconstructions}
+          # This is where things get interesting. Each value is retrieved through
+          # a lazy hash in which `method_name or `key` points to a proc:
+          #
+          #   key: -> o { o.key }
+          #
+          # The actual method is interpolated directly and `eval`'d to make this
+          # faster than `public_send`.
+          valid_keys.each do |key|
+            deconstructed_values[key] = MATCHABLE_LAZY_VALUES[key].call(self)
+          end
 
+          # ...and once this is done, return back the deconstructed values.
           deconstructed_values
+        # We rescue `NameError` here to return a more useful message and indicate
+        # there are some missing methods for the match.
+        rescue NameError => e
+          raise Matchable::UnmatchedName, e
         end
       RUBY
 
@@ -104,26 +175,41 @@ module Matchable
       nil
     end
 
-    # Generates Ruby code for `deconstruct_keys` branches which will
-    # directly call the method rather than utilizing `public_send` or
-    # similar methods.
+    # Generates key-value pairs of `method_name` pointing to `method_name` for
+    # the case where `keys` is `nil`, requiring all keys to be directly returned.
     #
-    # Note that in the case of `keys` being `nil` it is expected to return
-    # all keys that are possible from a pattern match rather than nothing,
-    # hence adding this guard in every case.
-    #
-    # @param method_name [Symbol]
-    #   Name of the method to add a deconstructed key from
+    # @param method_names [Array[Symbol]]
+    #   Names of the methods
     #
     # @return [String]
-    #   Evaluatable Ruby code for adding a deconstructed key to requested
-    #   values.
-    private def deconstructed_value(method_name)
-      <<~RUBY
-        if keys.nil? || keys.include?(:#{method_name})
-          deconstructed_values[:#{method_name}] = #{method_name}
-        end
-      RUBY
+    #   Ruby code for all key-value pairs for method names
+    def nil_guard_values(method_names)
+      method_names
+        .map { |method_name| "#{method_name}: #{method_name}" }
+        .join(",\n")
+    end
+
+    # Generated Ruby Hash based on a mapping of valid keys to a lazy function
+    # to retrieve them directly without the need for `public_send` or similar
+    # methods. This code instead directly interpolates the method call and
+    # evaluates that, but will not run the code until called as a proc in the
+    # actual `deconstruct_keys` method.
+    #
+    # @param method_names [Array[Symbol]]
+    #   Names of the methods
+    #
+    # @return [Hash[Symbol, Proc]]
+    #   Mapping of deconstruction key to lazy retrieval function
+    def lazy_match_values(method_names)
+      method_names
+        # Name of the method points to a lazy function to retrieve it
+        .map { |method_name| "  #{method_name}: -> o { o.#{method_name} }," }
+        # Join them into one String
+        .join("\n")
+        # Wrap them in Hash brackets
+        .then { |kv_pairs| "{\n#{kv_pairs}\n}"}
+        # ...and `eval` it to turn it into a Hash
+        .then { |ruby_code| eval ruby_code }
     end
 
     # Attaches the deconstructor to the parent class. If the method is
@@ -138,27 +224,60 @@ module Matchable
     private def attach_deconstructor(method_name)
       i_method = instance_method(method_name)
 
-      deconstruction_code = if method_name == :initialize
-        param_names = i_method.parameters.map(&:last)
+      deconstruction_code =
+        # If the method is `initialize` we want to treat it differently, as
+        # it represents a unique destructuring based on the method's parameters.
+        if method_name == :initialize
+          # Example of parameters:
+          #
+          #   -> a, b = 2, *c, d:, e: 3, **f, &fn {}.parameters
+          #   # => [
+          #   #   [:req, :a], [:opt, :b], [:rest, :c], [:keyreq, :d], [:key, :e],
+          #   #   [:keyrest, :f], [:block, :fn]
+          #   # ]
+          #
+          # The `last` of each is the name of the param. This assumes a tied
+          # method to each of these names, and will fail otherwise.
+          param_names = i_method.parameters.map(&:last)
 
-        "[#{param_names.join(', ')}]"
-      else
-        method_name
-      end
+          # Take the literal names of those parameters and treat them like
+          # method calls to have the entire thing inlined
+          "[#{param_names.join(', ')}]"
+        # Otherwise we just want the method name, don't do anything special to
+        # this. If you have any other methods that might make sense here let me
+        # know by filing an issue.
+        else
+          method_name
+        end
 
-      deconstructable_module.class_eval <<~RUBY, __FILE__ , __LINE__ + 1
+      # Then we evaluate that in the context of our prepended module and away
+      # we go with our new method. Added YARDoc because this will show up in the
+      # actual code and we want to be nice.
+      matchable_module.class_eval <<~RUBY, __FILE__ , __LINE__ + 1
+        # Pattern Matching hook for array-like deconstruction methods.
+        #
+        # This method was generated by Matchable and based on the `#{method_name}`
+        # method. Make sure all properties have associated methods attached or
+        # this will raise an error.
+        #
+        # @return [Array]
         def deconstruct
           #{deconstruction_code}
+        # We rescue `NameError` here to return a more useful message and indicate
+        # there are some missing methods for the match.
+        rescue NameError => e
+          raise Matchable::UnmatchedName, e
         end
       RUBY
 
+      # Return back nil because this value really should not be relied upon
       nil
     end
 
     # Prepended module to define methods against
     #
     # @return [Module]
-    private def deconstructable_module
+    private def matchable_module
       if const_defined?(MODULE_NAME)
         const_get(MODULE_NAME)
       else

data/lib/matchable/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: matchable
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.1
 platform: ruby
 authors:
 - Brandon Weaver
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2021-01-31 00:00:00.000000000 Z
+date: 2021-02-01 00:00:00.000000000 Z
 dependencies: []
 description:
 email:
@@ -20,6 +20,7 @@ files:
 - ".github/workflows/main.yml"
 - ".gitignore"
 - ".rspec"
+- ".ruby-version"
 - CODE_OF_CONDUCT.md
 - Gemfile
 - Gemfile.lock
@@ -27,6 +28,8 @@ files:
 - LICENSE.txt
 - README.md
 - Rakefile
+- benchmarks/dynamic_vs_generated_benchmark.rb
+- benchmarks/dynamic_vs_generated_benchmark_results.txt
 - bin/console
 - bin/setup
 - lib/matchable.rb