qo 0.2.0 → 0.2.1

data/lib/qo/matchers/base_matcher.rb

@@ -1,4 +1,16 @@
 module Qo
+  # A Qo Matcher is a class that acts like a Proc. It takes in a set of match
+  # values or key value pairs and a target value to evaluate against, and returns
+  # the status of that match.
+  #
+  # It is possible to override this behavior via `to_proc` overloading and
+  # utilization of `super` as noted in `GuardBlockMatcher`.
+  #
+  # @see Qo::Matchers::GuardBlockMatcher
+  #
+  # @author baweaver
+  # @since 0.2.0
+  #
   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.
@@ -6,7 +18,8 @@ module Qo
     # Will delegate responsibilities to either Array or Hash style matchers if
     # invoked directly.
     #
-    # @author [baweaver]
+    # @author baweaver
+    # @since 0.2.0
     #
     class BaseMatcher
       def initialize(type, *array_matchers, **keyword_matchers)
@@ -19,7 +32,7 @@ module Qo
       #
       #     data.select(&Qo[...])
       #
-      # @return [Proc]
+      # @return [Proc[Any]]
       def to_proc
         @array_matchers.empty? ?
           Qo::Matchers::HashMatcher.new(@type, **@keyword_matchers).to_proc :
@@ -31,7 +44,7 @@ module Qo
       #
       # @param target [Any] Object to match against
       #
-      # @return [type] [description]
+      # @return [Boolean] Result of the match
       def call(target)
         self.to_proc.call(target)
       end
@@ -39,12 +52,13 @@ module Qo
       alias_method :===, :call
       alias_method :[],  :call
 
-      # Wrapper around public send to encapsulate the matching method (any, all, none)
+      # Runs the relevant match method against the given collection with the
+      # given matcher function.
       #
       # @param collection [Enumerable] Any collection that can be enumerated over
-      # @param fn         [Proc] Function to match with
+      # @param fn         [Proc]       Function to match with
       #
-      # @return [Enumerable] Resulting collection
+      # @return [Boolean] Result of the match
       private def match_with(collection, &fn)
         return collection.any?(&fn)  if @type == 'or'
         return collection.none?(&fn) if @type == 'not'
@@ -68,8 +82,9 @@ module Qo
       # 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?(:===)]
+      # @param target  [Any]
+      #   Target to match against
+      # @param matcher [#===]
       #   Anything that responds to ===, preferably in a unique and entertaining way.
       #
       # @return [Boolean]
@@ -81,7 +96,7 @@ module Qo
       # 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
+      # @param matcher [#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)
@@ -92,8 +107,8 @@ module Qo
 
       # 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
+      # @param target  [Any]     Object to send to
+      # @param matcher [#to_sym] Anything that can be coerced into a method name
       #
       # @return [Boolean] Success status of predicate
       private def method_matches?(target, matcher)

data/lib/qo/matchers/guard_block_matcher.rb

@@ -6,7 +6,21 @@ module Qo
     # It returns tuples of (status, result) in order to prevent masking of
     # legitimate falsy or nil values returned.
     #
-    # @author [baweaver]
+    # Guard Block Matchers are best used with a PatternMatch, and chances are
+    # you're going to want to read that documentation first.
+    #
+    # @example
+    #     Qo::Matchers::GuardBlockMatcher == Qo.matcher == Qo.m
+    #
+    #     guard_matcher = Qo.m(Integer) { |v| v * 2 }
+    #     guard_matcher.call(1)  # => [true, 2]
+    #     guard_matcher.call(:x) # => [false, false]
+    #
+    # @see Qo::Matchers::PatternMatch
+    #   Pattern Match using GuardBlockMatchers
+    #
+    # @author baweaver
+    # @since 0.1.5
     #
     class GuardBlockMatcher < BaseMatcher
       # Identity function that returns its argument directly
@@ -25,8 +39,8 @@ module Qo
       # and potentially call through to the associated block if a base
       # matcher would have passed
       #
-      # @return [Proc]
-      #     Any -> [Bool, Any] # (status, result) tuple
+      # @return [Proc[Any] - (Bool, Any)]
+      #   (status, result) tuple
       def to_proc
         Proc.new { |target|
           super[target] ? [true, @fn.call(target)] : NON_MATCH

data/lib/qo/matchers/hash_matcher.rb

@@ -6,37 +6,46 @@ module Qo
     # In the case of a Hash matching against a Hash, it will compare the intersection
     # of keys and match the values against eachother.
     #
+    # ```ruby
+    # Qo[name: /Foo/, age: 30..50].call({name: 'Foo', age: 42})
+    # # => true
+    # ```
+    #
     # 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.
     #
+    # # ```ruby
+    # Qo[name: /Foo/, age: 30..50].call(Person.new('Foo', 42))
+    # # => true
+    # ```
+    #
     # All variants present in the BaseMatcher are present here, including 'and',
     # 'not', and 'or'.
     #
-    # @author [baweaver]
+    # @author baweaver
+    # @since 0.2.0
     #
     class HashMatcher < BaseMatcher
-      # Used to match against a matcher made from an Array, like:
+      # Wrapper around call to allow for invocation in an Enumerable function,
+      # such as:
       #
-      #     Qo['Foo', 'Bar']
-      #
-      # @param matchers [Array[respond_to?(===)]] indexed tuple to match the target object against
+      # ```ruby
+      # people.select(&Qo[name: /Foo/, age: 20..40])
+      # ```
       #
       # @return [Proc[Any]]
-      #     Array  -> Bool # Tuple match against targets index
-      #     Object -> Bool # Boolean public send
+      #   Proc awaiting a target to match against
       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?(:===)]]
+      # @param matchers [Hash[Any, #===]]
       #     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
+      # @return [Boolean] Result of the match
       def call(target)
         return true if @keyword_matchers == target
 
@@ -49,9 +58,9 @@ module Qo
 
       # 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 ===
+      # @param target    [Any]    Target of the match
+      # @param match_key [Symbol] Key of the hash to reference
+      # @param matcher   [#===]   Any matcher responding to ===
       #
       # @return [Boolean] Match status
       private def match_hash_value?(target, match_key, matcher)
@@ -66,9 +75,9 @@ module Qo
 
       # 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 ===
+      # @param target         [Any]    Target of the match
+      # @param match_property [Symbol] Property of the object to reference
+      # @param matcher        [#===]   Any matcher responding to ===
       #
       # @return [Boolean] Match status
       private def match_object_value?(target, match_property, matcher)
@@ -81,9 +90,9 @@ module Qo
       # 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
+      # @param target    [Hash]   Target of the match
+      # @param match_key [Symbol] Key to match against
+      # @param matcher   [#===]   Matcher
       #
       # @return [Boolean]
       private def hash_case_match?(target, match_key, matcher)
@@ -108,9 +117,9 @@ module Qo
       # 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
+      # @param target         [Hash]   Target of the match
+      # @param match_property [Symbol] Method to call
+      # @param matcher        [#===]   Matcher
       #
       # @return [Boolean]
       private def hash_method_case_match?(target, match_property, matcher)

data/lib/qo/matchers/pattern_match.rb

@@ -54,7 +54,8 @@ module Qo
     #
     # We'll evaluate those options in a few experiments later.
     #
-    # @author [baweaver]
+    # @author baweaver
+    # @since 0.2.0
     #
     class PatternMatch
       def initialize(*matchers)

data/lib/qo/public_api.rb

@@ -5,7 +5,8 @@ module Qo
   # externally facing methods renamed or moved under pain of a look of profound
   # disappointment from the creator.
   #
-  # @author [baweaver]
+  # @author baweaver
+  # @since 0.2.0
   #
   module PublicApi
     include Qo::Exceptions
@@ -20,7 +21,7 @@ module Qo
     # @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)
+      create_matcher('and', array_matchers, keyword_matchers)
     end
 
     # The magic that lets you use `Qo[...]` instead of `Qo.and(...)`. Use wisely
@@ -36,7 +37,7 @@ module Qo
     # @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)
+      create_matcher('or', array_matchers, keyword_matchers)
     end
 
     # Creates a `not` type query matcher. No conditions in this type of matcher
@@ -49,7 +50,7 @@ module Qo
     # @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)
+      create_matcher('not', array_matchers, keyword_matchers)
     end
 
     # Creates a Guard Block matcher.
@@ -105,7 +106,7 @@ module Qo
     # @raises Qo::Exceptions::MultipleMatchersProvided
     #
     # @return [Qo::Matcher]
-    private def create_matcher(type, *array_matchers, **keyword_matchers)
+    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

data/lib/qo/version.rb

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

data/performance_report.txt

@@ -1,60 +1,109 @@
+Running on Qo v0.2.0 at commit ba999659acb51beec215fab4240a34298794a5bf
 
 Array * Array - Literal
 =======================
 
+Vanilla result: true
+Qo.and result: true
+
 Warming up --------------------------------------
-             Vanilla   283.062k i/100ms
-              Qo.and    48.476k i/100ms
+             Vanilla   278.882k i/100ms
+              Qo.and    83.044k i/100ms
 Calculating -------------------------------------
-             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
+             Vanilla      8.950M (± 1.7%) i/s -     44.900M in   5.018406s
+              Qo.and      1.062M (± 1.2%) i/s -      5.315M in   5.003728s
 
 Comparison:
-             Vanilla:  9319318.3 i/s
-              Qo.and:   573855.1 i/s - 16.24x  slower
+             Vanilla:  8949563.3 i/s
+              Qo.and:  1062331.4 i/s - 8.42x  slower
 
 
 Array * Array - Index pattern match
 ===================================
 
+Vanilla result: true
+Qo.and result: true
+
 Warming up --------------------------------------
-             Vanilla    44.095k i/100ms
-              Qo.and    12.753k i/100ms
+             Vanilla    49.757k i/100ms
+              Qo.and    22.362k i/100ms
 Calculating -------------------------------------
-             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
+             Vanilla    562.718k (± 4.0%) i/s -      2.836M in   5.048960s
+              Qo.and    238.217k (± 1.7%) i/s -      1.208M in   5.070540s
 
 Comparison:
-             Vanilla:   482804.7 i/s
-              Qo.and:   128969.8 i/s - 3.74x  slower
+             Vanilla:   562718.0 i/s
+              Qo.and:   238216.8 i/s - 2.36x  slower
 
 
 Array * Object - Predicate match
 ================================
 
+Vanilla result: false
+Qo.and result: false
+
 Warming up --------------------------------------
-             Vanilla   138.847k i/100ms
-              Qo.and    16.157k i/100ms
+             Vanilla   145.056k i/100ms
+              Qo.and    27.888k i/100ms
 Calculating -------------------------------------
-             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
+             Vanilla      2.204M (± 4.4%) i/s -     11.024M in   5.011429s
+              Qo.and    323.232k (± 2.4%) i/s -      1.618M in   5.007142s
 
 Comparison:
-             Vanilla:  2153240.3 i/s
-              Qo.and:   174878.6 i/s - 12.31x  slower
+             Vanilla:  2204056.6 i/s
+              Qo.and:   323232.5 i/s - 6.82x  slower
 
 
 Array * Array - Select index pattern match
 ==========================================
 
+Vanilla result: [["Robert", 22], ["Roberta", 22]]
+Qo.and result: [["Robert", 22], ["Roberta", 22]]
+
+Warming up --------------------------------------
+             Vanilla    14.343k i/100ms
+              Qo.and     7.454k i/100ms
+Calculating -------------------------------------
+             Vanilla    149.518k (± 2.9%) i/s -    760.179k in   5.088601s
+              Qo.and     77.519k (± 2.8%) i/s -    387.608k in   5.004058s
+
+Comparison:
+             Vanilla:   149517.6 i/s
+              Qo.and:    77519.5 i/s - 1.93x  slower
+
+
+Hash * Hash - Hash intersection
+===============================
+
+Vanilla result: [{:name=>"Robert", :age=>22}, {:name=>"Roberta", :age=>22}]
+Qo.and result: [{:name=>"Robert", :age=>22}, {:name=>"Roberta", :age=>22}]
+
+Warming up --------------------------------------
+             Vanilla    36.214k i/100ms
+              Qo.and     5.050k i/100ms
+Calculating -------------------------------------
+             Vanilla    411.041k (± 2.3%) i/s -      2.064M in   5.024556s
+              Qo.and     50.029k (± 5.0%) i/s -    252.500k in   5.060014s
+
+Comparison:
+             Vanilla:   411041.4 i/s
+              Qo.and:    50028.6 i/s - 8.22x  slower
+
+
+Hash * Object - Property match
+==============================
+
+Vanilla result: [#<struct Person name="Robert", age=22>, #<struct Person name="Roberta", age=22>]
+Qo.and result: [#<struct Person name="Robert", age=22>, #<struct Person name="Roberta", age=22>]
+
 Warming up --------------------------------------
-             Vanilla    13.175k i/100ms
-              Qo.and    21.534k i/100ms
+             Vanilla    36.167k i/100ms
+              Qo.and     5.263k i/100ms
 Calculating -------------------------------------
-             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
+             Vanilla    411.057k (± 3.4%) i/s -      2.062M in   5.021612s
+              Qo.and     52.776k (± 4.0%) i/s -    268.413k in   5.094233s
 
 Comparison:
-              Qo.and:   240447.2 i/s
-             Vanilla:   137128.2 i/s - 1.75x  slower
+             Vanilla:   411057.2 i/s
+              Qo.and:    52775.9 i/s - 7.79x  slower
 

data/qo.gemspec

@@ -26,4 +26,6 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency "guard"
   spec.add_development_dependency "guard-rspec"
   spec.add_development_dependency "benchmark-ips"
+  spec.add_development_dependency "yard"
+  spec.add_development_dependency "redcarpet"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: qo
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.2.1
 platform: ruby
 authors:
 - Brandon Weaver
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2018-04-16 00:00:00.000000000 Z
+date: 2018-04-18 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -94,6 +94,34 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: redcarpet
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 description: 
 email:
 - keystonelemur@gmail.com
@@ -105,6 +133,7 @@ files:
 - ".pryrc"
 - ".rspec"
 - ".travis.yml"
+- ".yardopts"
 - CODE_OF_CONDUCT.md
 - Gemfile
 - Guardfile
@@ -114,8 +143,37 @@ files:
 - bin/console
 - bin/setup
 - docs/.gitkeep
+- docs/Qo.html
+- docs/Qo/Exceptions.html
+- docs/Qo/Exceptions/MultipleMatchersProvided.html
+- docs/Qo/Exceptions/NoMatchersProvided.html
+- docs/Qo/Exceptions/NotAllGuardMatchersProvided.html
+- docs/Qo/Helpers.html
+- docs/Qo/Matchers.html
+- docs/Qo/Matchers/ArrayMatcher.html
+- docs/Qo/Matchers/BaseMatcher.html
+- docs/Qo/Matchers/GuardBlockMatcher.html
+- docs/Qo/Matchers/HashMatcher.html
+- docs/Qo/Matchers/PatternMatch.html
+- docs/Qo/PublicApi.html
 - docs/_config.yml
+- docs/_index.html
+- docs/class_list.html
+- docs/css/common.css
+- docs/css/full_list.css
+- docs/css/style.css
+- docs/file.README.html
+- docs/file_list.html
+- docs/frames.html
+- docs/img/qo_logo.png
+- docs/index.html
+- docs/js/app.js
+- docs/js/full_list.js
+- docs/js/jquery.js
+- docs/method_list.html
+- docs/top-level-namespace.html
 - img/qo_logo.png
+- img/whoa_lemur.png
 - lib/qo.rb
 - lib/qo/exceptions.rb
 - lib/qo/helpers.rb
@@ -148,7 +206,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.6.14.1
+rubygems_version: 2.7.6
 signing_key: 
 specification_version: 4
 summary: Qo is a querying library for Ruby pattern matching