qo 0.1.10 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 1af9159c107b7761e1b30c7062b108e692403067
-  data.tar.gz: 483b4e35c8c9bba6a7e84c7516ea3e8a1de6e5b2
+  metadata.gz: dcbbe9e009a9ccf04769b8ccb7eca4343ea972a5
+  data.tar.gz: 53dae10eca53508dacfb75ad940207f0f047d288
 SHA512:
-  metadata.gz: 3db647525ff5685025108dacbe62b7945f135399d56c8a68eb9f39eb63dda3704614da143608a97d66251754c7d57c97d69d5e1a0d73f0c56e5d256cf813acdf
-  data.tar.gz: 72582ba2f1d0f81d149e2f0b9e3d35d10dcb929418c2cde4f88d3773a734f93c7e78594dc59689058f8de0d2cf3edfbc9dc7bb448ec7cfe9bda237fe101a07d0
+  metadata.gz: 62bceca4a54804a1e18c86a26802e3903693a61d213fa27b959e0e6a362b54470aeb22f45101ebd8b73cb5dfa90a7c1214c7d78574d3a366a679734744005007
+  data.tar.gz: 40a0319fa994a9e82e1f55001deab434e95187819efc1ef5eaa6bdd9be015987c481b7b7097b00820974cdc43eeed815fc4b9f7d442f5388b1881549ad00eb62

data/README.md

@@ -10,11 +10,19 @@ Short for Query Object, my play at Ruby pattern matching and fluent querying
 
 ## How does it work?
 
-Triple equals black magic, mostly.
+Mostly by using Ruby language features like `to_proc` and `===`.
 
-Want to understand more of how that works? Check out this post: https://medium.com/rubyinside/triple-equals-black-magic-d934936a6379
+There's an article explaining most of the base mechanics behind Qo:
 
-The original inspiration was from a chat I'd had with a few other Rubyists about pattern matching, which led to this experiment: https://gist.github.com/baweaver/611389c41c9005d025fb8e55448bf5f5
+[For Want of Pattern Matching in Ruby - The Creation of Qo](https://medium.com/@baweaver/for-want-of-pattern-matching-in-ruby-the-creation-of-qo-c3b267109b25)
+
+Most of it, though, utilizes Triple Equals. If you're not familiar with what all you can do with it in Ruby, I would encourage you to read this article as well:
+
+[Triple Equals Black Magic](https://medium.com/rubyinside/triple-equals-black-magic-d934936a6379)
+
+The original inspiration was from a chat I'd had with a few other Rubyists about pattern matching, which led to this experiment:
+
+[Having fun with M and Q](https://gist.github.com/baweaver/611389c41c9005d025fb8e55448bf5f5)
 
 Fast forward a few months and I kind of wanted to make it real, so here it is. Introducing Qo!
 
@@ -36,7 +44,7 @@ people.select(&Qo[age: 18..30])
 
 # How about some "right-hand assignment" pattern matching
 name_longer_than_three      = -> person { person.name.size > 3 }
-people_with_truncated_names = people.map(&Qo.match_fn(
+people_with_truncated_names = people.map(&Qo.match(
   Qo.m(name_longer_than_three) { |person| Person.new(person.name[0..2], person.age) },
   Qo.m(:*) # Identity function, catch-all
 ))
@@ -63,7 +71,7 @@ Qo[/Rob/, 22]
 Qo.and(/Rob/, 22)
 
 # This is shorthand for
-Qo::Matcher.new('and', /Rob/, 22)
+Qo::Matchers::BaseMatcher.new('and', /Rob/, 22)
 
 # An `or` matcher uses the same shorthand as `and` but uses `any?` behind the scenes instead:
 Qo.or(/Rob/, 22)
@@ -111,7 +119,7 @@ Qo[:*] === :literally_anything_here
 The first way a Qo matcher can be defined is by using `*varargs`:
 
 ```ruby
-# Qo::Matcher(type, *varargs, **kwargs)
+Qo::Matchers::BaseMatcher(type, *varargs, **kwargs)
 ```
 
 This gives us the `and` matcher shorthand for array matchers.
@@ -277,7 +285,7 @@ Checks to see if the key is even present on the other object, false if not.
 
 ##### 3.1.2 - Match value and target are hashes
 
-If both the match value (`match_key: match_value`) and the match target are hashes, Qo will begin a recursive descent starting at the match key until it finds a matcher to try out:
+If both the match value (`match_key: matcher`) and the match target are hashes, Qo will begin a recursive descent starting at the match key until it finds a matcher to try out:
 
 ```ruby
 Qo[a: {b: {c: 5..15}}] === {a: {b: {c: 10}}}
@@ -444,8 +452,6 @@ people_hashes.select(&Qo[age: :nil?])
 
 ### 4 - Right Hand Pattern Matching
 
-> ALPHA - This feature is alpha, currently testing. Considering whether or not to add `or` and `not` as `m_or` and `m_not`.
-
 This is where I start going a bit off into the weeds. We're going to try and get RHA style pattern matching in Ruby.
 
 ```ruby
@@ -470,12 +476,12 @@ In this case it's trying to do a few things:
 
 If no block function is provided, it assumes an identity function (`-> v { v }`) instead. If no match is found, `nil` will be returned.
 
-Now you _can_ also use a reversed version, `match_fn` (name pending better ideas), to run with map:
+If an initial target is not furnished, the matcher will become a curried proc awaiting a target. In more simple terms it just wants a target to run against, so let's give it a few with map:
 
 ```ruby
 name_longer_than_three = -> person { person.name.size > 3 }
 
-people_objects.map(&Qo.match_fn(
+people_objects.map(&Qo.match(
   Qo.m(name_longer_than_three) { |person|
     person.name = person.name[0..2]
     person
@@ -596,7 +602,7 @@ The nice thing about Unix style commands is that they use headers, which means C
 ```ruby
 rows = CSV.new(`df -h`, col_sep: " ", headers: true).read.map(&:to_h)
 
-rows.map(&Qo.match_fn(
+rows.map(&Qo.match(
   Qo.m(Avail: /Gi$/) { |row|
     "#{row['Filesystem']} mounted on #{row['Mounted']} [#{row['Avail']} / #{row['Size']}]"
   }

data/Rakefile

@@ -105,3 +105,75 @@ task :perf do
     }
   )
 end
+
+# Below this mark are mostly my experiments to see what features perform a bit better
+# than others, and are mostly left to check different versions of Ruby against eachother.
+#
+# Feel free to use them in development, but the general consensus of them is that
+# `send` type methods are barely slower. One _could_ write an IIFE to get around
+# that and maintain the flexibility but it's a net loss of clarity.
+#
+# Proc wise, they're all within margin of error. We just need to be really careful
+# of the 2.4+ bug of lambdas not destructuring automatically, which will wreak
+# havoc on hash matchers.
+
+task :perf_predicates do
+  array = (1..1000).to_a
+
+  run_benchmark('Predicates any?',
+    'block_any?':      -> { array.any? { |v| v.even? } },
+    'proc_any?':       -> { array.any?(&:even?) },
+    'send_proc_any?':  -> { array.public_send(:any?, &:even?) }
+  )
+
+  run_benchmark('Predicates all?',
+    'block_all?':      -> { array.all? { |v| v.even? } },
+    'proc_all?':       -> { array.all?(&:even?) },
+    'send_proc_all?':  -> { array.public_send(:all?, &:even?) }
+  )
+
+  run_benchmark('Predicates none?',
+    'block_none?':     -> { array.none? { |v| v.even? } },
+    'proc_none?':      -> { array.none?(&:even?) },
+    'send_proc_none?': -> { array.public_send(:none?, &:even?) },
+  )
+
+  even_stabby_lambda = -> n { n % 2 == 0 }
+  even_lambda        = lambda { |n| n % 2 == 0 }
+  even_proc_new      = Proc.new { |n|  n % 2 == 0 }
+  even_proc_short    = proc { |n|  n % 2 == 0 }
+  even_to_proc       = :even?.to_proc
+
+  run_benchmark('Types of Functions in Ruby',
+    even_stabby_lambda: -> { array.all?(&even_stabby_lambda) },
+    even_lambda:        -> { array.all?(&even_lambda) },
+    even_proc_new:      -> { array.all?(&even_proc_new) },
+    even_proc_short:    -> { array.all?(&even_proc_short) },
+    even_to_proc:       -> { array.all?(&even_to_proc) },
+  )
+end
+
+task :perf_random do
+  # run_benchmark('Empty on blank array',
+  #   'empty?':     -> { [].empty?     },
+  #   'size == 0':  -> { [].size == 0  },
+  #   'size.zero?': -> { [].size.zero? },
+  # )
+
+  array = (1..1000).to_a
+  # run_benchmark('Empty on several elements array',
+  #   'empty?':     -> { array.empty?     },
+  #   'size == 0':  -> { array.size == 0  },
+  #   'size.zero?': -> { array.size.zero? },
+  # )
+
+  hash = array.map { |v| [v, v] }.to_h
+
+  run_benchmark('Empty on blank hash vs array',
+    'hash empty?':  -> { {}.empty? },
+    'array empty?': -> { [].empty? },
+
+    'full hash empty?':  -> { hash.empty? },
+    'full array empty?': -> { array.empty? },
+  )
+end

data/lib/qo.rb

@@ -1,92 +1,25 @@
 require "qo/version"
-require 'qo/matcher'
-require 'qo/guard_block_matcher'
 
-module Qo
-  WILDCARD_MATCH = :*
-
-  class << self
-
-    # Creates a Guard Block matcher.
-    #
-    # A guard block matcher is used to guard a function from running unless
-    # the left-hand matcher passes. Once called with a value, it will either
-    # return `[false, false]` or `[true, Any]`.
-    #
-    # This wrapping is done to preserve intended false or nil responses,
-    # and is unwrapped with match below.
-    #
-    # @param *array_matchers    [Array] varargs matchers
-    # @param **keyword_matchers [Hash]  kwargs matchers
-    # @param &fn                [Proc]  Guarded function
-    #
-    # @return [Proc[Any]]
-    #     Any -> Proc[Any]
-    def matcher(*array_matchers, **keyword_matchers, &fn)
-      Qo::GuardBlockMatcher.new(*array_matchers, **keyword_matchers, &fn)
-    end
-
-    alias_method :m, :matcher
-
-
-    # Takes a set of Guard Block matchers, runs each in sequence, then
-    # unfolds the response from the first passing block.
-    #
-    # @param target       [Any]                      Target object to run against
-    # @param *qo_matchers [Array[GuardBlockMatcher]] Collection of matchers to run
-    #
-    # @return [type] [description]
-    def match(target, *qo_matchers)
-      all_are_guards = qo_matchers.all? { |q| q.is_a?(Qo::GuardBlockMatcher) }
-      raise 'Must patch Qo GuardBlockMatchers!' unless all_are_guards
-
-      qo_matchers.reduce(nil) { |_, matcher|
-        did_match, match_result = matcher.call(target)
-        break match_result if did_match
-      }
-    end
+# Matchers
+require 'qo/matchers/base_matcher'
+require 'qo/matchers/array_matcher'
+require 'qo/matchers/hash_matcher'
+require 'qo/matchers/guard_block_matcher'
 
-    # Wraps match to allow it to be used in a points-free style like regular matchers.
-    #
-    # @param *qo_matchers [Array[GuardBlockMatcher]] Collection of matchers to run
-    #
-    # @return [Proc[Any]]
-    #     Any -> Any
-    def match_fn(*qo_matchers)
-      -> target { match(target, *qo_matchers) }
-    end
+# Meta Matchers
+require 'qo/matchers/pattern_match'
 
-    def and(*array_matchers, **keyword_matchers)
-      Qo::Matcher.new('and', *array_matchers, **keyword_matchers)
-    end
+# Helpers
+require 'qo/helpers'
 
-    alias_method :[], :and
+# Public API
+require 'qo/exceptions'
+require 'qo/public_api'
 
-    def or(*array_matchers, **keyword_matchers)
-      Qo::Matcher.new('or', *array_matchers, **keyword_matchers)
-    end
-
-    def not(*array_matchers, **keyword_matchers)
-      Qo::Matcher.new('not', *array_matchers, **keyword_matchers)
-    end
-
-    # Utility functions. Consider placing these elsewhere.
-
-    def dig(path_map, expected_value)
-      -> hash {
-        segments = path_map.split('.')
-
-        expected_value === hash.dig(*segments) ||
-        expected_value === hash.dig(*segments.map(&:to_sym))
-      }
-    end
-
-    def count_by(targets, &fn)
-      fn ||= -> v { v }
+module Qo
+  WILDCARD_MATCH = :*
 
-      targets.each_with_object(Hash.new(0)) { |target, counts|
-        counts[fn[target]] += 1
-      }
-    end
-  end
+  extend Qo::Exceptions
+  extend Qo::Helpers
+  extend Qo::PublicApi
 end

data/lib/qo/exceptions.rb

@@ -0,0 +1,39 @@
+module Qo
+  # Defines common exception classes for use throughout the library
+  #
+  # @author [baweaver]
+  #
+  module Exceptions
+    # If no matchers in either Array or Hash style are provided.
+    #
+    # @author [lemur]
+    #
+    class NoMatchersProvided < ArgumentError
+      def to_s
+        "No Qo matchers were provided!"
+      end
+    end
+
+    # If both Array and Hash style matchers are provided.
+    #
+    # @author [lemur]
+    #
+    class MultipleMatchersProvided < ArgumentError
+      def to_s
+        "Cannot provide both array and keyword matchers!"
+      end
+    end
+
+    # In the case of a Pattern Match, we need to ensure all arguments are
+    # GuardBlockMatchers.
+    #
+    # @author [lemur]
+    #
+    class NotAllGuardMatchersProvided < ArgumentError
+      def to_s
+        "All provided matchers must be of type Qo::Matchers::GuardBlockMatcher " +
+        "defined with `Qo.matcher` or `Qo.m` instead of regular matchers."
+      end
+    end
+  end
+end

data/lib/qo/helpers.rb

@@ -0,0 +1,37 @@
+module Qo
+  module Helpers
+    # A curried variant of Hash#dig meant to be passed as a matcher util.
+    #
+    # @note This method will attempt to coerce path segments to Symbols
+    #       if unsuccessful in first dig.
+    #
+    # @param path_map       [String] Dot-delimited path
+    # @param expected_value [Any]    Matcher
+    #
+    # @return [Proc]
+    #     Hash -> Bool # Status of digging against the hash
+    def dig(path_map, expected_value)
+      Proc.new { |hash|
+        segments = path_map.split('.')
+
+        expected_value === hash.dig(*segments) ||
+        expected_value === hash.dig(*segments.map(&:to_sym))
+      }
+    end
+
+    # Counts by a function. This is entirely because I hackney this everywhere in
+    # pry anyways, so I want a function to do it for me already.
+    #
+    # @param targets [Array[Any]] Targets to count
+    # @param &fn     [Proc]       Function to define count key
+    #
+    # @return [Hash[Any, Integer]] Counts
+    def count_by(targets, &fn)
+      fn ||= -> v { v }
+
+      targets.each_with_object(Hash.new(0)) { |target, counts|
+        counts[fn[target]] += 1
+      }
+    end
+  end
+end

data/lib/qo/matchers/array_matcher.rb

@@ -0,0 +1,63 @@
+module Qo
+  module Matchers
+    # An Array Matcher is a matcher that uses only varargs to define a sequence
+    # of matches to perform against either an object or another Array.
+    #
+    # In the case of an Array matching against an Array it will compare via index.
+    #
+    # In the case of an Array matching against an Object, it will match each provided
+    # matcher against the object.
+    #
+    # All variants present in the BaseMatcher are present here, including 'and',
+    # 'not', and 'or'.
+    #
+    # @author [baweaver]
+    #
+    class ArrayMatcher < BaseMatcher
+      # Used to match against a matcher made from an Array, like:
+      #
+      #     Qo['Foo', 'Bar']
+      #
+      # @param matchers [Array[respond_to?(===)]] indexed tuple to match the target object against
+      #
+      # @return [Proc[Any]]
+      #     Array  -> Bool # Tuple match against targets index
+      #     Object -> Bool # Boolean public send
+      def to_proc
+        Proc.new { |target| self.call(target) }
+      end
+
+      # Invocation for the match sequence. Will determine the target and applicable
+      # matchers to run against it.
+      #
+      # @param target [Any]
+      #
+      # @return [Boolean] Match status
+      def call(target)
+        return true if @array_matchers == target
+
+        if target.is_a?(::Array)
+          match_with(@array_matchers.each_with_index) { |matcher, i|
+            match_value?(target[i], matcher)
+          }
+        else
+          match_with(@array_matchers) { |matcher|
+            match_value?(target, matcher)
+          }
+        end
+      end
+
+      # Defines what it means for a value to match a matcher
+      #
+      # @param target  [Any] Target to match against
+      # @param matcher [Any] Any matcher to run against, most frequently responds to ===
+      #
+      # @return [Boolean] Match status
+      private def match_value?(target, matcher)
+        wildcard_match?(matcher) ||
+        case_match?(target, matcher) ||
+        method_matches?(target, matcher)
+      end
+    end
+  end
+end

data/lib/qo/matchers/base_matcher.rb

@@ -0,0 +1,104 @@
+module Qo
+  module Matchers
+    # Base instance of matcher which is meant to take in either Array style or
+    # Keyword style arguments to run a match against various datatypes.
+    #
+    # Will delegate responsibilities to either Array or Hash style matchers if
+    # invoked directly.
+    #
+    # @author [baweaver]
+    #
+    class BaseMatcher
+      def initialize(type, *array_matchers, **keyword_matchers)
+        @array_matchers   = array_matchers
+        @keyword_matchers = keyword_matchers
+        @type             = type
+      end
+
+      # Converts a Matcher to a proc for use in querying, such as:
+      #
+      #     data.select(&Qo[...])
+      #
+      # @return [Proc]
+      def to_proc
+        @array_matchers.empty? ?
+          Qo::Matchers::HashMatcher.new(@type, **@keyword_matchers).to_proc :
+          Qo::Matchers::ArrayMatcher.new(@type, *@array_matchers).to_proc
+      end
+
+      # You can directly call a matcher as well, much like a Proc,
+      # using one of call, ===, or []
+      #
+      # @param target [Any] Object to match against
+      #
+      # @return [type] [description]
+      def call(target)
+        self.to_proc.call(target)
+      end
+
+      alias_method :===, :call
+      alias_method :[],  :call
+
+      # Wrapper around public send to encapsulate the matching method (any, all, none)
+      #
+      # @param collection [Enumerable] Any collection that can be enumerated over
+      # @param fn         [Proc] Function to match with
+      #
+      # @return [Enumerable] Resulting collection
+      private def match_with(collection, &fn)
+        return collection.any?(&fn)  if @type == 'or'
+        return collection.none?(&fn) if @type == 'not'
+
+        collection.all?(&fn)
+      end
+
+      # Wraps wildcard in case we want to do anything fun with it later
+      #
+      # @param value [Any] Value to test against the wild card
+      #
+      # @note The rescue is because some classes override `==` to do silly things,
+      #       like IPAddr, and I kinda want to use that.
+      #
+      # @return [Boolean]
+      private def wildcard_match?(value)
+        value == WILDCARD_MATCH rescue false
+      end
+
+      # Wraps a case equality statement to make it a bit easier to read. The
+      # typical left bias of `===` can be confusing reading down a page, so
+      # more of a clarity thing than anything. Also makes for nicer stack traces.
+      #
+      # @param target [Any] Target to match against
+      # @param matcher  [respond_to?(:===)]
+      #   Anything that responds to ===, preferably in a unique and entertaining way.
+      #
+      # @return [Boolean]
+      private def case_match?(target, matcher)
+        matcher === target
+      end
+
+      # Guarded version of `public_send` meant to stamp out more
+      # obscure errors when running against non-matching types.
+      #
+      # @param target  [Any] Object to send to
+      # @param matcher [respond_to?(:to_sym)] Anything that can be coerced into a method name
+      #
+      # @return [Any] Response of sending to the method, or false if failed
+      private def method_send(target, matcher)
+        matcher.respond_to?(:to_sym) &&
+        target.respond_to?(matcher.to_sym) &&
+        target.public_send(matcher)
+      end
+
+      # Predicate variant of `method_send` with the same guard concerns
+      #
+      # @param target  [Any] Object to send to
+      # @param matcher [respond_to?(:to_sym)] Anything that can be coerced into a method name
+      #
+      # @return [Boolean] Success status of predicate
+      private def method_matches?(target, matcher)
+        !!method_send(target, matcher)
+      end
+    end
+  end
+end