qo 0.1.10 → 0.2.0

data/lib/qo/matchers/guard_block_matcher.rb

@@ -0,0 +1,37 @@
+module Qo
+  module Matchers
+    # A GuardBlockMatcher is like a regular matcher, except in that if it
+    # "matches" it will provide its match target to its associated block.
+    #
+    # It returns tuples of (status, result) in order to prevent masking of
+    # legitimate falsy or nil values returned.
+    #
+    # @author [baweaver]
+    #
+    class GuardBlockMatcher < BaseMatcher
+      # Identity function that returns its argument directly
+      IDENTITY  = -> v { v }
+
+      # Definition of a non-match
+      NON_MATCH = [false, false]
+
+      def initialize(*array_matchers, **keyword_matchers, &fn)
+        @fn = fn || IDENTITY
+
+        super('and', *array_matchers, **keyword_matchers)
+      end
+
+      # Overrides the base matcher's #to_proc to wrap the value in a status
+      # and potentially call through to the associated block if a base
+      # matcher would have passed
+      #
+      # @return [Proc]
+      #     Any -> [Bool, Any] # (status, result) tuple
+      def to_proc
+        Proc.new { |target|
+          super[target] ? [true, @fn.call(target)] : NON_MATCH
+        }
+      end
+    end
+  end
+end

data/lib/qo/matchers/hash_matcher.rb

@@ -0,0 +1,131 @@
+module Qo
+  module Matchers
+    # A Hash Matcher is a matcher that uses only keyword args to define a sequence
+    # of matches to perform against either an Object or another Hash.
+    #
+    # In the case of a Hash matching against a Hash, it will compare the intersection
+    # of keys and match the values against eachother.
+    #
+    # In the case of a Hash matching against an Object, it will treat the keys as
+    # method property invocations to be matched against the provided values.
+    #
+    # All variants present in the BaseMatcher are present here, including 'and',
+    # 'not', and 'or'.
+    #
+    # @author [baweaver]
+    #
+    class HashMatcher < 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
+
+      # Used to match against a matcher made from Keyword Arguments (a Hash)
+      #
+      # @param matchers [Hash[Any, respond_to?(:===)]]
+      #     Any key mapping to any value that responds to `===`. Notedly more
+      #     satisfying when `===` does something fun.
+      #
+      # @return [Proc[Any]]
+      #     Hash   -> Bool # Value matching against similar keys, will attempt to coerce to_s because JSON
+      #     Object -> Bool # Uses keys as methods with public send to `===` match against the value
+      def call(target)
+        return true if @keyword_matchers == target
+
+        match_fn = target.is_a?(::Hash) ?
+          Proc.new { |match_key, matcher| match_hash_value?(target, match_key, matcher)   } :
+          Proc.new { |match_key, matcher| match_object_value?(target, match_key, matcher) }
+
+        match_with(@keyword_matchers, &match_fn)
+      end
+
+      # Checks if a hash value matches a given matcher
+      #
+      # @param target    [Any]               Target of the match
+      # @param match_key [Symbol]            Key of the hash to reference
+      # @param matcher   [respond_to?(:===)] Any matcher responding to ===
+      #
+      # @return [Boolean] Match status
+      private def match_hash_value?(target, match_key, matcher)
+        return false unless target.key?(match_key)
+        return true if wildcard_match?(matcher)
+
+        return hash_recurse(target[match_key], matcher) if target.is_a?(Hash) && matcher.is_a?(Hash)
+
+        hash_case_match?(target, match_key, matcher) ||
+        hash_method_predicate_match?(target, match_key, matcher)
+      end
+
+      # Checks if an object property matches a given matcher
+      #
+      # @param target         [Any]               Target of the match
+      # @param match_property [Symbol]            Property of the object to reference
+      # @param matcher        [respond_to?(:===)] Any matcher responding to ===
+      #
+      # @return [Boolean] Match status
+      private def match_object_value?(target, match_property, matcher)
+        return false unless target.respond_to?(match_property)
+
+        wildcard_match?(matcher) ||
+        hash_method_case_match?(target, match_property, matcher)
+      end
+
+      # Double wraps case match in order to ensure that we try against both Symbol
+      # and String variants of the keys, as this is a very common mixup in Ruby.
+      #
+      # @param target    [Hash]              Target of the match
+      # @param match_key [Symbol]            Key to match against
+      # @param matcher   [respond_to?(:===)] Matcher
+      #
+      # @return [Boolean]
+      private def hash_case_match?(target, match_key, matcher)
+        return true if case_match?(target[match_key], matcher)
+
+        match_key.respond_to?(:to_s) &&
+        target.key?(match_key.to_s) &&
+        case_match?(target[match_key.to_s], matcher)
+      end
+
+      # Attempts to run a matcher as a predicate method against the target
+      #
+      # @param target          [Hash]   Target of the match
+      # @param match_key       [Symbol] Method to call
+      # @param match_predicate [Symbol] Matcher
+      #
+      # @return [Boolean]
+      private def hash_method_predicate_match?(target, match_key, match_predicate)
+        method_matches?(target[match_key], match_predicate)
+      end
+
+      # Attempts to run a case match against a method call derived from a hash
+      # key, and checks the result.
+      #
+      # @param target         [Hash]              Target of the match
+      # @param match_property [Symbol]            Method to call
+      # @param matcher        [respond_to?(:===)] Matcher
+      #
+      # @return [Boolean]
+      private def hash_method_case_match?(target, match_property, matcher)
+        case_match?(method_send(target, match_property), matcher)
+      end
+
+      # Recurses on nested hashes.
+      #
+      # @param target  [Hash]
+      # @param matcher [Hash]
+      #
+      # @return [Boolean]
+      private def hash_recurse(target, matcher)
+        Qo::Matchers::HashMatcher.new(@type, **matcher).call(target)
+      end
+    end
+  end
+end

data/lib/qo/matchers/pattern_match.rb

@@ -0,0 +1,93 @@
+require 'qo/exceptions'
+
+module Qo
+  module Matchers
+    # Creates a PatternMatch, which will evaluate once given a match target.
+    #
+    # Each GuardBlockMatcher given will be run in sequence until a "match" is
+    # located. Once that condition is met, it will call the associated block
+    # function of that GuardBlockMatcher with the match target.
+    #
+    # This is done as an effort to emulate Right Hand Assignment seen in other
+    # functionally oriented languages pattern matching systems. Most notably this
+    # is done in Scala: (https://docs.scala-lang.org/tour/pattern-matching.html)
+    #
+    # ```scala
+    # notification match {
+    #   case Email(email, title, _) =>
+    #     s"You got an email from $email with title: $title"
+    #
+    #   case SMS(number, message) =>
+    #     s"You got an SMS from $number! Message: $message"
+    #
+    #   case VoiceRecording(name, link) =>
+    #     s"You received a Voice Recording from $name! Click the link to hear it: $link"
+    #
+    #   case other => other
+    # }
+    # ```
+    #
+    # Qo will instead pipe the entire matched object, and might look something like this:
+    #
+    # ```ruby
+    # # Assuming notification is in the form of a tuple
+    #
+    # Qo.match(notification,
+    #   Qo.m(EMAIL_REGEX, String, :*) { |email, title, _|
+    #     "You got an email from #{email} with title: #{title}"
+    #   },
+    #
+    #   Qo.m(PHONE_REGEX, String) { |number, message, _|
+    #     "You got an SMS from #{number}! Message: #{message}"
+    #   },
+    #
+    #   Qo.m(String, LINK_REGEX) { |name, link, _|
+    #     "You received a Voice Recording from #{name}! Click the link to hear it: #{link}"
+    #   },
+    #
+    #   Qo.m(:*)
+    # )
+    # ```
+    #
+    # Efforts to emulate the case class mechanic may be present in later versions,
+    # but for now the associated performance penalty may be too steep to consider.
+    #
+    # We'll evaluate those options in a few experiments later.
+    #
+    # @author [baweaver]
+    #
+    class PatternMatch
+      def initialize(*matchers)
+        raise Qo::Exceptions::NotAllGuardMatchersProvided unless matchers.all? { |q|
+          q.is_a?(Qo::Matchers::GuardBlockMatcher)
+        }
+
+        @matchers = matchers
+      end
+
+      # Function return of a PatternMatch waiting for a target to run
+      #
+      # @return [Proc]
+      #     Any -> Any | nil
+      def to_proc
+        Proc.new { |target| self.call(target) }
+      end
+
+      # Immediately invokes a PatternMatch
+      #
+      # @param target [Any]
+      #   Target to run against and pipe to the associated block if it
+      #   "matches" any of the GuardBlocks
+      #
+      # @return [Any | nil] Result of the piped block, or nil on a miss
+      def call(target)
+        @matchers.each { |guard_block_matcher|
+          did_match, match_result = guard_block_matcher.call(target)
+          return match_result if did_match
+        }
+
+        nil
+      end
+    end
+  end
+end

data/lib/qo/public_api.rb

@@ -0,0 +1,121 @@
+module Qo
+  # The Public API consists of methods that should be openly accessible to the
+  # top level Qo namespace, and should not change. It should be used as the
+  # subject of Acceptance level tests for the library and should not have its
+  # externally facing methods renamed or moved under pain of a look of profound
+  # disappointment from the creator.
+  #
+  # @author [baweaver]
+  #
+  module PublicApi
+    include Qo::Exceptions
+
+    # Creates an `and` type query matcher. All conditions in this type of matcher
+    # must pass to be considered a "match". It will short-circuit in the case of
+    # a false match.
+    #
+    # @param *array_matchers    [Array] Array-like conditionals
+    # @param **keyword_matchers [Hash]  Keyword style conditionals
+    #
+    # @return [Proc[Any]]
+    #     Any -> Bool # Given a target, will return if it "matches"
+    def and(*array_matchers, **keyword_matchers)
+      create_matcher('and', *array_matchers, **keyword_matchers)
+    end
+
+    # The magic that lets you use `Qo[...]` instead of `Qo.and(...)`. Use wisely
+    alias_method :[], :and
+
+    # Creates an `or` type query matcher. Any conditions in this type of matcher
+    # must pass to be considered a "match". It will short-circuit in the case of
+    # a true match.
+    #
+    # @param *array_matchers    [Array] Array-like conditionals
+    # @param **keyword_matchers [Hash]  Keyword style conditionals
+    #
+    # @return [Proc[Any]]
+    #     Any -> Bool # Given a target, will return if it "matches"
+    def or(*array_matchers, **keyword_matchers)
+      create_matcher('or', *array_matchers, **keyword_matchers)
+    end
+
+    # Creates a `not` type query matcher. No conditions in this type of matcher
+    # should pass to be considered a "match". It will short-circuit in the case of
+    # a true match.
+    #
+    # @param *array_matchers    [Array] Array-like conditionals
+    # @param **keyword_matchers [Hash]  Keyword style conditionals
+    #
+    # @return [Proc[Any]]
+    #     Any -> Bool # Given a target, will return if it "matches"
+    def not(*array_matchers, **keyword_matchers)
+      create_matcher('not', *array_matchers, **keyword_matchers)
+    end
+
+    # 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::Matchers::GuardBlockMatcher.new(*array_matchers, **keyword_matchers, &fn)
+    end
+
+    # Might be a tinge fond of shorthand
+    alias_method :m, :matcher
+
+    # "Curried" function that waits for a target, or evaluates immediately if given
+    # one.
+    #
+    # A PatternMatch will try and run all GuardBlock matchers in sequence until
+    # it finds one that "matches". Once found, it will pass the target into the
+    # associated matcher's block function.
+    #
+    # @param *args [Array[Any, *GuardBlockMatcher]]
+    #   Collection of matchers to run, potentially prefixed by a target object
+    #
+    # @return [Qo::PatternMatch | Any]
+    #   Returns a PatternMatch waiting for a target, or an evaluated PatternMatch response
+    def match(*args)
+      if args.first.is_a?(Qo::Matchers::GuardBlockMatcher)
+        Qo::Matchers::PatternMatch.new(*args)
+      else
+        match_target, *qo_matchers = args
+        Qo::Matchers::PatternMatch.new(*qo_matchers).call(match_target)
+      end
+    end
+
+    # Abstraction for creating a matcher, allowing for common error handling scenarios.
+    #
+    # @param type [String] Type of matcher
+    # @param *array_matchers [Array] Array-like conditionals
+    # @param **keyword_matchers [Hash] Keyword style conditionals
+    #
+    # @raises Qo::Exceptions::NoMatchersProvided
+    # @raises Qo::Exceptions::MultipleMatchersProvided
+    #
+    # @return [Qo::Matcher]
+    private def create_matcher(type, *array_matchers, **keyword_matchers)
+      array_empty, hash_empty = array_matchers.empty?, keyword_matchers.empty?
+
+      raise Qo::NoMatchersProvided       if array_empty && hash_empty
+      raise Qo::MultipleMatchersProvided if !(array_empty || hash_empty)
+
+      if hash_empty
+        Qo::Matchers::ArrayMatcher.new(type, *array_matchers)
+      else
+        Qo::Matchers::HashMatcher.new(type, **keyword_matchers)
+      end
+    end
+  end
+end

data/lib/qo/version.rb

@@ -1,3 +1,3 @@
 module Qo
-  VERSION = '0.1.10'
+  VERSION = '0.2.0'
 end

data/performance_report.txt

@@ -3,58 +3,58 @@ Array * Array - Literal
 =======================
 
 Warming up --------------------------------------
-             Vanilla   290.029k i/100ms
-              Qo.and    37.778k i/100ms
+             Vanilla   283.062k i/100ms
+              Qo.and    48.476k i/100ms
 Calculating -------------------------------------
-             Vanilla      9.559M (± 2.3%) i/s -     47.855M in   5.009272s
-              Qo.and    468.514k (± 2.5%) i/s -      2.342M in   5.002419s
+             Vanilla      9.319M (± 2.1%) i/s -     46.705M in   5.013834s
+              Qo.and    573.855k (± 1.3%) i/s -      2.909M in   5.069323s
 
 Comparison:
-             Vanilla:  9558516.6 i/s
-              Qo.and:   468514.2 i/s - 20.40x  slower
+             Vanilla:  9319318.3 i/s
+              Qo.and:   573855.1 i/s - 16.24x  slower
 
 
 Array * Array - Index pattern match
 ===================================
 
 Warming up --------------------------------------
-             Vanilla    47.088k i/100ms
-              Qo.and    14.227k i/100ms
+             Vanilla    44.095k i/100ms
+              Qo.and    12.753k i/100ms
 Calculating -------------------------------------
-             Vanilla    540.415k (± 3.3%) i/s -      2.731M in   5.059509s
-              Qo.and    149.040k (± 4.2%) i/s -    754.031k in   5.068772s
+             Vanilla    482.805k (± 5.9%) i/s -      2.425M in   5.041737s
+              Qo.and    128.970k (± 4.3%) i/s -    650.403k in   5.052438s
 
 Comparison:
-             Vanilla:   540414.9 i/s
-              Qo.and:   149040.0 i/s - 3.63x  slower
+             Vanilla:   482804.7 i/s
+              Qo.and:   128969.8 i/s - 3.74x  slower
 
 
 Array * Object - Predicate match
 ================================
 
 Warming up --------------------------------------
-             Vanilla   139.244k i/100ms
-              Qo.and    20.096k i/100ms
+             Vanilla   138.847k i/100ms
+              Qo.and    16.157k i/100ms
 Calculating -------------------------------------
-             Vanilla      2.356M (± 3.4%) i/s -     11.836M in   5.030228s
-              Qo.and    218.039k (± 2.9%) i/s -      1.105M in   5.073725s
+             Vanilla      2.153M (± 3.9%) i/s -     10.830M in   5.037676s
+              Qo.and    174.879k (± 3.8%) i/s -    888.635k in   5.089311s
 
 Comparison:
-             Vanilla:  2355717.5 i/s
-              Qo.and:   218038.9 i/s - 10.80x  slower
+             Vanilla:  2153240.3 i/s
+              Qo.and:   174878.6 i/s - 12.31x  slower
 
 
 Array * Array - Select index pattern match
 ==========================================
 
 Warming up --------------------------------------
-             Vanilla    14.015k i/100ms
-              Qo.and    20.325k i/100ms
+             Vanilla    13.175k i/100ms
+              Qo.and    21.534k i/100ms
 Calculating -------------------------------------
-             Vanilla    140.673k (± 3.6%) i/s -    714.765k in   5.087715s
-              Qo.and    219.533k (± 3.8%) i/s -      1.098M in   5.006844s
+             Vanilla    137.128k (± 3.6%) i/s -    685.100k in   5.002872s
+              Qo.and    240.447k (± 2.7%) i/s -      1.206M in   5.019112s
 
 Comparison:
-              Qo.and:   219533.2 i/s
-             Vanilla:   140672.7 i/s - 1.56x  slower
+              Qo.and:   240447.2 i/s
+             Vanilla:   137128.2 i/s - 1.75x  slower