qo 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA256:
-  metadata.gz: 2dcdd32a9c1743ae07fee6699551ca57393c751ce8172950edea505013e5a628
-  data.tar.gz: 4b39a86b816b039c3282a5b0d307afb796f5dabed249cf3b658462a5bd791ece
+SHA1:
+  metadata.gz: 02dea6ad061112d957032940212ab369e09b0ec1
+  data.tar.gz: '037591f1119e010e7faba94c51f1ed4678cafe45'
 SHA512:
-  metadata.gz: bb43a7e3a7e2134d477149548c1de8de6961fa62a8da1c606ffa743287d95cb05bd5d400174e343297cf9c21a205f32aa60500abbb32c094c1cac4699558f18f
-  data.tar.gz: 481c3331b0e1328b8e6eae0fd8c34ca54df0f58204cf8a0dc0cfff568343af618450a5978c1132e3a250da474c7dfd90fc4df3132ecc99f80095a1fc485b7faa
+  metadata.gz: b01330722400077045a769eaaccc565ad2132f0413624b510f370754bfda109dac6ffcf1ea6cd2ce6987182d19cceb773bd04e67f49c990eef84f7a8774d53ea
+  data.tar.gz: df76eed79e30353032930972ef916a7788500753b4e0fd684cf42be4c8f2f2dded8493c9e43ed52e71c2023291952f1b2b6c319dfca0de9b9b64b951ed6dc1d7

data/.gitignore

@@ -14,3 +14,6 @@
 # built gems
 *.gem
 repro_cases/*.rb
+
+# Junk files
+.DS_Store

data/README.md

@@ -52,43 +52,51 @@ How about some pattern matching? There are two styles:
 
 #### Pattern Match
 
-The original style
+##### Case Statements
+
+Qo case statements work much like a Ruby case statement, except in that they leverage
+the full power of Qo matchers behind the scenes.
 
 ```ruby
 # 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(
-  Qo.m(name_longer_than_three) { |person| Person.new(person.name[0..2], person.age) },
-  Qo.m(Any) # Identity function, catch-all
-))
+name_longer_than_three = -> person { person.name.size > 3 }
 
-# And standalone like a case:
-Qo.match(people.first,
-  Qo.m(age: 10..19) { |person| "#{person.name} is a teen that's #{person.age} years old" },
-  Qo.m(Any) { |person| "#{person.name} is #{person.age} years old" }
-)
+person_with_truncated_name = Qo.case(people.first) { |m|
+  m.when(name_longer_than_three) { |person|
+    Person.new(person.name[0..2], person.age)
+  }
+
+  m.else
+}
 ```
 
-#### Pattern Match Block
+It takes in a value directly, and returns the result, much like a case statement.
+
+Note that if `else` receives no block, it will default to an identity function
+(`{ |v| v }`). If no else is provided and there's no match, you'll get back a nil.
+You can write this out if you wish.
 
-The new style, likely to take over in `v1.0.0` after testing:
+##### Match Statements
+
+Match statements are like case statements, except in that they don't directly take
+a value to match against. They're waiting for a value to come in later from
+something else.
 
 ```ruby
-name_longer_than_three      = -> person { person.name.size > 3 }
+name_longer_than_three = -> person { person.name.size > 3 }
+
 people_with_truncated_names = people.map(&Qo.match { |m|
   m.when(name_longer_than_three) { |person| Person.new(person.name[0..2], person.age) }
-  m.else(&:itself)
+  m.else
 })
 
 # And standalone like a case:
-Qo.match(people.first) { |m|
+Qo.match { |m|
   m.when(age: 10..19) { |person| "#{person.name} is a teen that's #{person.age} years old" }
   m.else { |person| "#{person.name} is #{person.age} years old" }
-}
+}.call(people.first)
 ```
 
-(More details coming on the difference and planned 1.0.0 APIs)
-
 ### Qo'isms
 
 Qo supports three main types of queries: `and`, `or`, and `not`.
@@ -439,18 +447,18 @@ people_hashes.select(&Qo[age: :nil?])
 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
-Qo.match(['Robert', 22],
-  Qo.m(Any, 20..99) { |n, a| "#{n} is an adult that is #{a} years old" },
-  Qo.m(Any)
-)
+Qo.case(['Robert', 22]) { |m|
+  m.when(Any, 20..99) { |n, a| "#{n} is an adult that is #{a} years old" }
+  m.else
+}
 # => "Robert is an adult that is 22 years old"
 ```
 
 ```ruby
-Qo.match(people_objects.first,
-  Qo.m(name: Any, age: 20..99) { |person| "#{person.name} is an adult that is #{person.age} years old" },
-  Qo.m(Any)
-)
+Qo.case(people_objects.first) { |m|
+  m.when(name: Any, age: 20..99) { |person| "#{person.name} is an adult that is #{person.age} years old" }
+  m.else
+}
 ```
 
 In this case it's trying to do a few things:
@@ -460,18 +468,14 @@ 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.
 
-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(
-  Qo.m(name_longer_than_three) { |person|
-    person.name = person.name[0..2]
-    person
-  },
-  Qo.m(Any)
-))
+people_objects.map(&Qo.match { |m|
+  m.when(name_longer_than_three) { |person| Person.new(person.name[0..2], person.age) }
+
+  m.else
+})
 
 # => [Person(age: 22, name: "Rob"), Person(age: 22, name: "Rob"), Person(age: 42, name: "Foo"), Person(age: 17, name: "Bar")]
 ```
@@ -517,6 +521,8 @@ Qo.count_by([1,2,3,2,2,2,1], &:even?)
 # }
 ```
 
+This feature may be added to Ruby 2.6+: https://bugs.ruby-lang.org/issues/11076
+
 ### 5 - Hacky Fun Time
 
 These examples will grow over the next few weeks as I think of more fun things to do with Qo. PRs welcome if you find fun uses!
@@ -573,10 +579,10 @@ HTTP responses.
 
 ```ruby
 def get_url(url)
-  Net::HTTP.get_response(URI(url)).yield_self(&Qo.match(
-    Qo.m(Net::HTTPSuccess) { |response| response.body.size },
-    Qo.m(Any)              { |response| raise response.message }
-  ))
+  Net::HTTP.get_response(URI(url)).yield_self(&Qo.match { |m|
+    m.when(Net::HTTPSuccess) { |response| response.body.size },
+    m.else                   { |response| raise response.message }
+  })
 end
 
 get_url('https://github.com/baweaver/qo')
@@ -590,7 +596,7 @@ The difference between this and case? Well, the first is you can pass this to
 be used in there, including predicate and content checks on the body:
 
 ```ruby
-Qo.m(Net::HTTPSuccess, body: /Qo/)
+m.when(Net::HTTPSuccess, body: /Qo/)
 ```
 
 You could put as many checks as you want in there, or use different Qo matchers
@@ -617,11 +623,11 @@ 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(
-  Qo.m(Avail: /Gi$/) { |row|
+rows.map(&Qo.match { |m|
+  m.when(Avail: /Gi$/) { |row|
     "#{row['Filesystem']} mounted on #{row['Mounted']} [#{row['Avail']} / #{row['Size']}]"
   }
-)).compact
+}).compact
 # => ["/dev/***** mounted on / [186Gi / 466Gi]"]
 ```
 

data/Rakefile

@@ -19,13 +19,13 @@ task :default => :spec
 #       "anything can be a key" bit of Ruby.
 #
 # @return [Unit] StdOut
-def run_benchmark(title, **benchmarks)
+def run_benchmark(title, quiet = false, **benchmarks)
   puts '', title, '=' * title.size, ''
 
   # Validation
   benchmarks.each do |benchmark_name, benchmark_fn|
     puts "#{benchmark_name} result: #{benchmark_fn.call()}"
-  end
+  end unless quiet
 
   puts
 
@@ -147,6 +147,110 @@ task :perf do
   )
 end
 
+task :perf_pattern_match do
+  # Going to redefine the way that success and fail happen in here.
+  return false
+
+  require 'dry-matcher'
+
+  # Match `[:ok, some_value]` for success
+  success_case = Dry::Matcher::Case.new(
+    match:   -> value { value.first == :ok },
+    resolve: -> value { value.last }
+  )
+
+  # Match `[:err, some_error_code, some_value]` for failure
+  failure_case = Dry::Matcher::Case.new(
+    match: -> value, *pattern {
+      value[0] == :err && (pattern.any? ? pattern.include?(value[1]) : true)
+    },
+    resolve: -> value { value.last }
+  )
+
+  # Build the matcher
+  matcher = Dry::Matcher.new(success: success_case, failure: failure_case)
+
+  qo_m = Qo.match { |m|
+    m.success(Any) { |v| v }
+    m.failure(Any) { "ERR!" }
+  }
+
+  qo_m_case = proc { |target|
+    Qo.case(target) { |m|
+      m.success(Any) { |v| v }
+      m.failure(Any) { "ERR!" }
+    }
+  }
+
+  dm_m = proc { |target|
+    matcher.(target) do |m|
+      m.success { |(v)| v }
+      m.failure { 'ERR!' }
+    end
+  }
+
+  # v_m = proc { |target|
+  #   next target[1] if target[0] == :ok
+  #   'ERR!'
+  # }
+
+  ok_target  = [:ok, 12345]
+  err_target = [:err, "OH NO!"]
+
+  run_benchmark('Single Item Tuple',
+    'Qo': -> {
+      "OK: #{qo_m[ok_target]}, ERR: #{qo_m[err_target]}"
+    },
+
+    'Qo Case': -> {
+      "OK: #{qo_m_case[ok_target]}, ERR: #{qo_m_case[err_target]}"
+    },
+
+    'DryRB': -> {
+      "OK: #{dm_m[ok_target]}, ERR: #{dm_m[err_target]}"
+    },
+
+    # 'Vanilla': -> {
+    #   "OK: #{v_m[ok_target]}, ERR: #{v_m[err_target]}"
+    # },
+  )
+
+  collection = [ok_target, err_target] * 2_000
+
+  run_benchmark('Large Tuple Collection', true,
+    'Qo':           -> { collection.map(&qo_m)      },
+    'Qo Case':      -> { collection.map(&qo_m_case) },
+    'DryRB':        -> { collection.map(&dm_m)      },
+    # 'Vanilla':      -> { collection.map(&v_m) }
+  )
+
+  # Person = Struct.new(:name, :age)
+  # people = [
+  #   Person.new('Robert', 22),
+  #   Person.new('Roberta', 22),
+  #   Person.new('Foo', 42),
+  #   Person.new('Bar', 17)
+  # ] * 1_000
+
+  # v_om = proc { |target|
+  #   if /^F/.match?(target.name) && (30..50).include?(target.age)
+  #     "It's foo!"
+  #   else
+  #     "Not foo"
+  #   end
+  # }
+
+  # qo_om = Qo.match { |m|
+  #   m.when(name: /^F/, age: 30..50)  { "It's foo!" }
+  #   m.else { "Not foo" }
+  # }
+
+  # run_benchmark('Large Object Collection', true,
+  #   'Qo':           -> { people.map(&qo_om) },
+  #   'Vanilla':      -> { people.map(&v_om) }
+  # )
+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.
 #

data/lib/qo.rb

@@ -11,7 +11,6 @@ require 'qo/matchers/guard_block_matcher'
 
 # Meta Matchers
 require 'qo/matchers/pattern_match'
-require 'qo/matchers/pattern_match_block'
 
 # Helpers
 require 'qo/helpers'
@@ -21,6 +20,9 @@ require 'qo/exceptions'
 require 'qo/public_api'
 
 module Qo
+  # Identity function that returns its argument directly
+  IDENTITY = -> v { v }
+
   extend Qo::Exceptions
   extend Qo::Helpers
   extend Qo::PublicApi

data/lib/qo/exceptions.rb

@@ -27,19 +27,6 @@ module Qo
       end
     end
 
-    # In the case of a Pattern Match, we need to ensure all arguments are
-    # GuardBlockMatchers.
-    #
-    # @author baweaver
-    # @since 0.2.0
-    #
-    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
-
     # In the case of a Pattern Match, we should only have one "else" clause
     #
     # @author baweaver

data/lib/qo/helpers.rb

@@ -5,8 +5,11 @@ module Qo
     # @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
+    # @param path_map [String]
+    #   Dot-delimited path
+    #
+    # @param expected_value [Any]
+    #   Matcher
     #
     # @return [Proc]
     #     Hash -> Bool # Status of digging against the hash
@@ -22,10 +25,14 @@ module Qo
     # 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
+    # @param targets [Array[Any]]
+    #   Targets to count
+    #
+    # @param &fn [Proc]
+    #   Function to define count key
     #
-    # @return [Hash[Any, Integer]] Counts
+    # @return [Hash[Any, Integer]]
+    #   Counts
     def count_by(targets, &fn)
       fn ||= -> v { v }
 

data/lib/qo/matchers/array_matcher.rb

@@ -14,6 +14,14 @@ module Qo
     # # => true
     # ```
     #
+    # It should be noted that arrays of dissimilar size will result in an instant
+    # false return value. If you wish to do a single value match, simply use the
+    # provided `Any` type as such:
+    #
+    # ```ruby
+    # array.select(&Any)
+    # ```
+    #
     # In the case of an Array matching against an Object, it will match each provided
     # matcher against the object.
     #
@@ -33,6 +41,11 @@ module Qo
     # @since 0.2.0
     #
     class ArrayMatcher < BaseMatcher
+      def initialize(type, array_matchers)
+        @array_matchers = array_matchers
+        @type           = type
+      end
+
       # Wrapper around call to allow for invocation in an Enumerable function,
       # such as:
       #
@@ -59,6 +72,8 @@ module Qo
         return true if @array_matchers == target
 
         if target.is_a?(::Array)
+          return false unless target.size == @array_matchers.size
+
           match_with(@array_matchers.each_with_index) { |matcher, i|
             match_value?(target[i], matcher)
           }

data/lib/qo/matchers/base_matcher.rb

@@ -22,10 +22,12 @@ module Qo
     # @since 0.2.0
     #
     class BaseMatcher
-      def initialize(type, *array_matchers, **keyword_matchers)
-        @array_matchers   = array_matchers
-        @keyword_matchers = keyword_matchers
-        @type             = type
+      def initialize(type, array_matchers, keyword_matchers)
+        @type = type
+
+        @full_matcher = array_matchers.empty? ?
+          Qo::Matchers::HashMatcher.new(type, keyword_matchers) :
+          Qo::Matchers::ArrayMatcher.new(type, array_matchers)
       end
 
       # Converts a Matcher to a proc for use in querying, such as:
@@ -34,9 +36,7 @@ module Qo
       #
       # @return [Proc[Any]]
       def to_proc
-        @array_matchers.empty? ?
-          Qo::Matchers::HashMatcher.new(@type, **@keyword_matchers).to_proc :
-          Qo::Matchers::ArrayMatcher.new(@type, *@array_matchers).to_proc
+        @full_matcher.to_proc
       end
 
       # You can directly call a matcher as well, much like a Proc,
@@ -46,11 +46,12 @@ module Qo
       #
       # @return [Boolean] Result of the match
       def call(target)
-        self.to_proc.call(target)
+        @full_matcher.call(target)
       end
 
       alias_method :===, :call
       alias_method :[],  :call
+      alias_method :match?,  :call
 
       # Runs the relevant match method against the given collection with the
       # given matcher function.
@@ -60,10 +61,12 @@ module Qo
       #
       # @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'
-
-        collection.all?(&fn)
+        case @type
+        when 'and' then collection.all?(&fn)
+        when 'or'  then collection.any?(&fn)
+        when 'not' then collection.none?(&fn)
+        else false
+        end
       end
 
       # Wraps a case equality statement to make it a bit easier to read. The

data/lib/qo/matchers/guard_block_matcher.rb

@@ -10,9 +10,9 @@ module Qo
     # you're going to want to read that documentation first.
     #
     # @example
-    #     Qo::Matchers::GuardBlockMatcher == Qo.matcher == Qo.m
+    #     Qo::Matchers::GuardBlockMatcher
     #
-    #     guard_matcher = Qo.m(Integer) { |v| v * 2 }
+    #     guard_matcher = Qo::Matchers::GuardBlockMatcher.new(Integer) { |v| v * 2 }
     #     guard_matcher.call(1)  # => [true, 2]
     #     guard_matcher.call(:x) # => [false, false]
     #
@@ -23,28 +23,68 @@ module Qo
     # @since 0.1.5
     #
     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
+      def initialize(array_matchers, keyword_matchers, &fn)
+        @fn = fn || Qo::IDENTITY
+
+        super('and', array_matchers, keyword_matchers)
+      end
+
+      # Direct test of whether or not a target matches the GuardBlock's
+      # condition
+      #
+      # @param target [Any]
+      #   Target value to match against
+      #
+      # @return [Boolean]
+      #   Whether or not the target matched
+      def match?(target)
+        super(target)
+      end
 
-        super('and', *array_matchers, **keyword_matchers)
+      # Forces a resolution of a match. Note that this method should
+      # not be used outside of pattern matches, as only a pattern
+      # match will have the necessary additional context to call
+      # it correctly.
+      #
+      # @param target [Any]
+      #   Target value to match against
+      #
+      # @return [Any]
+      #   Result of the function being called on the target
+      def match(target)
+        @fn.call(target)
       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
+      # @see Qo::Matchers::GuardBlockMatcher#call
+      #
+      # @return [Proc[Any]]
+      #   Function awaiting target value
       def to_proc
-        Proc.new { |target|
-          super[target] ? [true, @fn.call(target)] : NON_MATCH
-        }
+        Proc.new { |target| self.call(target) }
+      end
+
+
+      # Overrides the call method to wrap values in a return tuple to represent
+      # a positive match to guard against valid falsy returns
+      #
+      # @param target [Any]
+      #   Target value to match against
+      #
+      # @return [Array[false, false]]
+      #   The guard block did not match
+      #
+      # @return [Array[true, Any]]
+      #   The guard block matched, and the provided function called through
+      #   providing a return value.
+      def call(target)
+        super(target) ? [true, @fn.call(target)] : NON_MATCH
       end
     end
   end

data/lib/qo/matchers/hash_matcher.rb

@@ -26,6 +26,11 @@ module Qo
     # @since 0.2.0
     #
     class HashMatcher < BaseMatcher
+      def initialize(type, keyword_matchers)
+        @keyword_matchers = keyword_matchers
+        @type             = type
+      end
+
       # Wrapper around call to allow for invocation in an Enumerable function,
       # such as:
       #
@@ -95,6 +100,7 @@ module Qo
       # @return [Boolean]
       private def hash_case_match?(target, match_key, matcher)
         return true if case_match?(target[match_key], matcher)
+        return false unless target.keys.first.is_a?(String)
 
         match_key.respond_to?(:to_s) &&
         target.key?(match_key.to_s) &&

data/lib/qo/matchers/pattern_match.rb

@@ -2,71 +2,94 @@ require 'qo/exceptions'
 
 module Qo
   module Matchers
-    # Creates a PatternMatch, which will evaluate once given a match target.
+    # Creates a PatternMatch in a succinct block format:
     #
-    # 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
+    # ```ruby
+    # Qo.match(target) { |m|
+    #   m.when(/^F/, 42) { |(name, age)| "#{name} is #{age}" }
+    #   m.else { "We need a default, right?" }
     # }
     # ```
     #
-    # Qo will instead pipe the entire matched object, and might look something like this:
+    # The Public API obscures the fact that the matcher is only called when it
+    # is explicitly given an argument to match against. If it is not, it will
+    # just return a class waiting for a target, as such:
     #
     # ```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(:*)
-    # )
+    # def get_url(url)
+    #   Net::HTTP.get_response(URI(url)).yield_self(&Qo.match { |m|
+    #     m.when(Net::HTTPSuccess) { |response| response.body.size }
+    #     m.else { |response| raise response.message }
+    #   })
+    # end
+    #
+    # get_url('https://github.com/baweaver/qo')
+    # # => 142387
+    # get_url('https://github.com/baweaver/qo/does_not_exist')
+    # # => RuntimeError: Not Found
     # ```
     #
-    # 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.
+    # This is intended for flexibility between singular calls and calls as a
+    # paramater to higher order functions like `map` and `yield_self`.
     #
-    # We'll evaluate those options in a few experiments later.
+    # This variant was inspired by ideas from Scala, Haskell, and various Ruby
+    # libraries dealing with Async and self-yielding blocks. Especially notable
+    # were websocket handlers and dry-ruby implementations.
     #
     # @author baweaver
-    # @since 0.2.0
+    # @since 0.3.0
     #
     class PatternMatch
-      def initialize(*matchers)
-        raise Qo::Exceptions::NotAllGuardMatchersProvided unless matchers.all? { |q|
-          q.is_a?(Qo::Matchers::GuardBlockMatcher)
-        }
+      def initialize
+        @matchers = []
+
+        yield(self)
+      end
 
-        @matchers = matchers
+      # Creates a match case. This is the exact same as any other `and` style
+      # match reflected in the public API, except that it's a Guard Block
+      # match being performed. That means if the left side matches, the right
+      # side function is invoked and that value is returned.
+      #
+      # @param *array_matchers [Array[Any]]
+      #   Array style matchers
+      #
+      # @param **keyword_matchers [Hash[Any, Any]]
+      #   Hash style matchers
+      #
+      # @param &fn [Proc]
+      #   If matched, this function will be called. If no function is provided
+      #   Qo will default to identity
+      #
+      # @return [Array[GuardBlockMatcher]]
+      #   The return of this method should not be directly depended on, but will
+      #   provide all matchers currently present. This will likely be left for
+      #   ease of debugging later.
+      def when(*array_matchers, **keyword_matchers, &fn)
+        @matchers << Qo::Matchers::GuardBlockMatcher.new(
+          array_matchers,
+          keyword_matchers,
+          &(fn || Qo::IDENTITY)
+        )
       end
 
-      # Function return of a PatternMatch waiting for a target to run
+      # Else is the last statement that will be evaluated if all other parts
+      # fail. It should be noted that it won't magically appear, you have to
+      # explicitly put an `else` case in for it to catch on no match unless
+      # you want a `nil` return
+      #
+      # @param &fn [Proc]
+      #   Function to call when all other matches have failed. If no value is
+      #   provided, it assumes `Qo::IDENTITY` which will return the value given.
+      #
+      # @return [Proc]
+      def else(&fn)
+        raise Qo::Exceptions::MultipleElseClauses if @else
+
+        @else = fn || Qo::IDENTITY
+      end
+
+      # Proc version of a PatternMatch
       #
       # @return [Proc]
       #     Any -> Any | nil
@@ -80,15 +103,24 @@ module Qo
       #   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
+      # @return [Any]
+      #   Result of the piped block
+      #
+      # @return [nil]
+      #   No matches were found, so nothing is returned
       def call(target)
         @matchers.each { |guard_block_matcher|
-          did_match, match_result = guard_block_matcher.call(target)
-          return match_result if did_match
+          next unless guard_block_matcher.match?(target)
+          return guard_block_matcher.match(target)
         }
 
+        return @else.call(target) if @else
+
         nil
       end
+
+      alias_method :===, :call
+      alias_method :[], :call
     end
   end
 end

data/lib/qo/public_api.rb

@@ -15,8 +15,11 @@ module Qo
     # 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
+    # @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"
@@ -31,8 +34,11 @@ module Qo
     # 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
+    # @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"
@@ -44,8 +50,11 @@ module Qo
     # 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
+    # @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"
@@ -53,90 +62,74 @@ module Qo
       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]`.
+    # A pattern match will try and run all guard block style matchers in sequence
+    # until it finds one that "matches". Once found, it will pass the target
+    # into the associated matcher's block function.
     #
-    # This wrapping is done to preserve intended false or nil responses,
-    # and is unwrapped with match below.
+    # @example
+    #   [1,2,3].map(&Qo.match { |m|
+    #     m.when(:even?) { |v| v * 3 }
+    #     m.else         { |v| v - 1 }
+    #   })
+    #   => [0, 6, 2]
     #
-    # @param *array_matchers    [Array] varargs matchers
-    # @param **keyword_matchers [Hash]  kwargs matchers
-    # @param &fn                [Proc]  Guarded function
+    # @param fn [Proc]
+    #   Body of the matcher, as shown in examples
     #
-    # @return [Proc[Any]]
-    #     Any -> Proc[Any]
-    def matcher(*array_matchers, **keyword_matchers, &fn)
-      Qo::Matchers::GuardBlockMatcher.new(*array_matchers, **keyword_matchers, &fn)
-    end
+    # @return [Qo::PatternMatch]
+    #   A function awaiting a value to match against
+    def match(&fn)
+      return proc { false } unless block_given?
 
-    # Might be a tinge fond of shorthand
-    alias_method :m, :matcher
+      Qo::Matchers::PatternMatch.new(&fn)
+    end
 
-    # "Curried" function that waits for a target, or evaluates immediately if given
-    # one.
+    # Similar to the common case statement of Ruby, except in that it behaves
+    # as if `Array#===` and `Hash#===` exist in the form of Qo matchers.
     #
-    # 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.
+    # @note
+    #   I refer to the potential 2.6+ features currently being discussed here:
     #
-    # @param fn [Proc]
-    #   If provided, the pattern match will become block-style, utilizing
-    #   PatternMatchBlock instead. If any args are provided, the first
-    #   will be treated as the target.
+    #   * `Hash#===`  - https://bugs.ruby-lang.org/issues/14869
+    #   * `Array#===` - https://bugs.ruby-lang.org/issues/14916
     #
-    # @param *args [Array[Any, *GuardBlockMatcher]]
-    #   Collection of matchers to run, potentially prefixed by a target object
+    # @see Qo#match
     #
-    # @return [Qo::PatternMatchBlock]
-    #   If a value is not provided, a block style pattern match will be returned
-    #   that responds to proc coercion. It can be used for functions like `map`.
+    # @example
+    #   Qo.case([1, 1]) { |m|
+    #     m.when(Any, Any) { |a, b| a + b }
+    #     m.else { |v| v }
+    #   }
+    #   => 2
     #
-    # @return [Qo::PatternMatch]
-    #   If a value is not provided and no function is present, a PatternMatch
-    #   will be returned, awaiting a value to match against.
+    # @param value [Any]
+    #   Value to match against
+    #
+    # @param &fn [Proc]
+    #   Body of the matcher, as shown above
     #
     # @return [Any]
-    #   If a value is provided, matchers will attempt to call through on it,
-    #   returning the result of the function.
-    def match(*args, &fn)
-      if block_given?
-        return args.empty? ?
-          Qo::Matchers::PatternMatchBlock.new(&fn) :
-          Qo::Matchers::PatternMatchBlock.new(&fn).call(args.first)
-      end
-
-      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
+    #   The result of calling a pattern match with a provided value
+    def case(value, &fn)
+      Qo::Matchers::PatternMatch.new(&fn).call(value)
     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
+    # @param type [String]
+    #   Type of matcher
+    #
+    # @param array_matchers [Array[Any]]
+    #   Array-like conditionals
     #
-    # @raises Qo::Exceptions::NoMatchersProvided
-    # @raises Qo::Exceptions::MultipleMatchersProvided
+    # @param keyword_matchers [Hash[Any, Any]]
+    #   Keyword style conditionals
     #
     # @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)
+      raise MultipleMatchersProvided if !array_matchers.empty? && !keyword_matchers.empty?
 
-      if hash_empty
-        Qo::Matchers::ArrayMatcher.new(type, *array_matchers)
-      else
-        Qo::Matchers::HashMatcher.new(type, **keyword_matchers)
-      end
+      Qo::Matchers::BaseMatcher.new(type, array_matchers, keyword_matchers)
     end
   end
 end

data/lib/qo/version.rb

@@ -1,3 +1,3 @@
 module Qo
-  VERSION = '0.4.0'
+  VERSION = '0.5.0'
 end

data/performance_report.txt

@@ -1,4 +1,4 @@
-Running on Qo v0.4.0 at rev 96607b76bba3fea60d46e118a67fa5b4c76d5c72
+Running on Qo v0.5.0 at rev 7b49c20d29630d9f56328d4663bb1b1ce1add2b0
  - Ruby ruby 2.5.1p57 (2018-03-29 revision 63029) [x86_64-darwin17]
 
 Array * Array - Literal
@@ -8,15 +8,15 @@ Vanilla result: true
 Qo.and result: true
 
 Warming up --------------------------------------
-             Vanilla   275.772k i/100ms
-              Qo.and    77.013k i/100ms
+             Vanilla   245.363k i/100ms
+              Qo.and    67.365k i/100ms
 Calculating -------------------------------------
-             Vanilla      8.911M (± 2.0%) i/s -     44.675M in   5.015740s
-              Qo.and    992.994k (± 1.7%) i/s -      5.006M in   5.042624s
+             Vanilla      7.823M (± 4.0%) i/s -     39.258M in   5.027372s
+              Qo.and    859.133k (± 2.3%) i/s -      4.311M in   5.020923s
 
 Comparison:
-             Vanilla:  8910560.1 i/s
-              Qo.and:   992994.3 i/s - 8.97x  slower
+             Vanilla:  7822633.5 i/s
+              Qo.and:   859133.0 i/s - 9.11x  slower
 
 
 Array * Array - Index pattern match
@@ -26,15 +26,15 @@ Vanilla result: true
 Qo.and result: true
 
 Warming up --------------------------------------
-             Vanilla    48.662k i/100ms
-              Qo.and    22.868k i/100ms
+             Vanilla    43.805k i/100ms
+              Qo.and    21.434k i/100ms
 Calculating -------------------------------------
-             Vanilla    569.942k (± 1.6%) i/s -      2.871M in   5.038819s
-              Qo.and    247.240k (± 2.8%) i/s -      1.258M in   5.091282s
+             Vanilla    511.690k (± 2.0%) i/s -      2.584M in   5.053034s
+              Qo.and    241.516k (± 2.7%) i/s -      1.222M in   5.062575s
 
 Comparison:
-             Vanilla:   569942.4 i/s
-              Qo.and:   247239.9 i/s - 2.31x  slower
+             Vanilla:   511689.7 i/s
+              Qo.and:   241515.5 i/s - 2.12x  slower
 
 
 Array * Object - Predicate match
@@ -44,15 +44,15 @@ Vanilla result: false
 Qo.and result: false
 
 Warming up --------------------------------------
-             Vanilla   142.790k i/100ms
-              Qo.and    28.458k i/100ms
+             Vanilla   129.649k i/100ms
+              Qo.and    25.903k i/100ms
 Calculating -------------------------------------
-             Vanilla      2.251M (± 1.8%) i/s -     11.280M in   5.012252s
-              Qo.and    315.757k (± 1.8%) i/s -      1.594M in   5.048759s
+             Vanilla      2.049M (± 2.7%) i/s -     10.242M in   5.002097s
+              Qo.and    287.416k (± 3.8%) i/s -      1.451M in   5.054898s
 
 Comparison:
-             Vanilla:  2251336.4 i/s
-              Qo.and:   315757.2 i/s - 7.13x  slower
+             Vanilla:  2049180.0 i/s
+              Qo.and:   287416.4 i/s - 7.13x  slower
 
 
 Array * Array - Select index pattern match
@@ -62,15 +62,15 @@ Vanilla result: [["Robert", 22], ["Roberta", 22]]
 Qo.and result: [["Robert", 22], ["Roberta", 22]]
 
 Warming up --------------------------------------
-             Vanilla    14.162k i/100ms
-              Qo.and     7.559k i/100ms
+             Vanilla    12.729k i/100ms
+              Qo.and     6.911k i/100ms
 Calculating -------------------------------------
-             Vanilla    150.748k (± 1.7%) i/s -    764.748k in   5.074423s
-              Qo.and     78.082k (± 1.6%) i/s -    393.068k in   5.035396s
+             Vanilla    135.430k (± 1.8%) i/s -    687.366k in   5.077139s
+              Qo.and     71.615k (± 2.8%) i/s -    359.372k in   5.022246s
 
 Comparison:
-             Vanilla:   150748.3 i/s
-              Qo.and:    78082.2 i/s - 1.93x  slower
+             Vanilla:   135430.5 i/s
+              Qo.and:    71615.2 i/s - 1.89x  slower
 
 
 Hash * Hash - Hash intersection
@@ -80,15 +80,15 @@ Vanilla result: [{:name=>"Robert", :age=>22}, {:name=>"Roberta", :age=>22}]
 Qo.and result: [{:name=>"Robert", :age=>22}, {:name=>"Roberta", :age=>22}]
 
 Warming up --------------------------------------
-             Vanilla    35.977k i/100ms
-              Qo.and     5.112k i/100ms
+             Vanilla    33.461k i/100ms
+              Qo.and     5.366k i/100ms
 Calculating -------------------------------------
-             Vanilla    410.483k (± 1.3%) i/s -      2.087M in   5.084305s
-              Qo.and     51.860k (± 1.6%) i/s -    260.712k in   5.028458s
+             Vanilla    366.234k (± 3.1%) i/s -      1.840M in   5.030236s
+              Qo.and     54.974k (± 4.4%) i/s -    279.032k in   5.087315s
 
 Comparison:
-             Vanilla:   410483.2 i/s
-              Qo.and:    51860.4 i/s - 7.92x  slower
+             Vanilla:   366233.9 i/s
+              Qo.and:    54973.5 i/s - 6.66x  slower
 
 
 Hash * Object - Property match
@@ -98,13 +98,13 @@ Vanilla result: [#<struct Person name="Robert", age=22>, #<struct Person name="R
 Qo.and result: [#<struct Person name="Robert", age=22>, #<struct Person name="Roberta", age=22>]
 
 Warming up --------------------------------------
-             Vanilla    36.219k i/100ms
-              Qo.and     5.415k i/100ms
+             Vanilla    33.166k i/100ms
+              Qo.and     5.659k i/100ms
 Calculating -------------------------------------
-             Vanilla    412.314k (± 1.3%) i/s -      2.064M in   5.007920s
-              Qo.and     55.712k (± 1.6%) i/s -    281.580k in   5.055626s
+             Vanilla    371.150k (± 3.4%) i/s -      1.857M in   5.010508s
+              Qo.and     58.451k (± 3.4%) i/s -    294.268k in   5.040637s
 
 Comparison:
-             Vanilla:   412313.9 i/s
-              Qo.and:    55711.7 i/s - 7.40x  slower
+             Vanilla:   371149.8 i/s
+              Qo.and:    58450.6 i/s - 6.35x  slower
 

data/qo.gemspec

@@ -28,6 +28,7 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency "benchmark-ips"
   spec.add_development_dependency "yard"
   spec.add_development_dependency "redcarpet"
+  spec.add_development_dependency "dry-matcher"
 
   spec.add_runtime_dependency "any", '0.1.0'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: qo
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.5.0
 platform: ruby
 authors:
 - Brandon Weaver
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2018-08-06 00:00:00.000000000 Z
+date: 2018-08-09 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -122,6 +122,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: dry-matcher
+  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: any
   requirement: !ruby/object:Gem::Requirement
@@ -199,7 +213,6 @@ files:
 - lib/qo/matchers/guard_block_matcher.rb
 - lib/qo/matchers/hash_matcher.rb
 - lib/qo/matchers/pattern_match.rb
-- lib/qo/matchers/pattern_match_block.rb
 - lib/qo/public_api.rb
 - lib/qo/version.rb
 - performance_report.txt
@@ -224,7 +237,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.7.6
+rubygems_version: 2.6.14.1
 signing_key: 
 specification_version: 4
 summary: Qo is a querying library for Ruby pattern matching

data/lib/qo/matchers/pattern_match_block.rb

@@ -1,115 +0,0 @@
-require 'qo/exceptions'
-
-module Qo
-  module Matchers
-    # Creates a PatternMatch in the style of a block.
-    #
-    # This varies from the regular PatternMatch in that all matchers are
-    # provided in a more succinct block format:
-    #
-    # ```ruby
-    # Qo.match(target) { |m|
-    #   m.when(/^F/, 42) { |(name, age)| "#{name} is #{age}" }
-    #   m.else { "We need a default, right?" }
-    # }
-    # ```
-    #
-    # The Public API obscures the fact that the matcher is only called when it
-    # is explicitly given an argument to match against. If it is not, it will
-    # just return a class waiting for a target, as such:
-    #
-    # ```ruby
-    # def get_url(url)
-    #   Net::HTTP.get_response(URI(url)).yield_self(&Qo.match { |m|
-    #     m.when(Net::HTTPSuccess) { |response| response.body.size }
-    #     m.else { |response| raise response.message }
-    #   })
-    # end
-    #
-    # get_url('https://github.com/baweaver/qo')
-    # # => 142387
-    # get_url('https://github.com/baweaver/qo/does_not_exist')
-    # # => RuntimeError: Not Found
-    # ```
-    #
-    # This is intended for flexibility between singular calls and calls as a
-    # paramater to higher order functions like `map` and `yield_self`.
-    #
-    # This variant was inspired by ideas from Scala, Haskell, and various Ruby
-    # libraries dealing with Async and self-yielding blocks. Especially notable
-    # were websocket handlers and dry-ruby implementations.
-    #
-    # @author baweaver
-    # @since 0.3.0
-    #
-    class PatternMatchBlock
-      def initialize
-        @matchers = []
-
-        yield(self)
-      end
-
-      # Creates a match case. This is the exact same as any other `and` style
-      # match reflected in the public API, except that it's a Guard Block
-      # match being performed. That means if the left side matches, the right
-      # side function is invoked and that value is returned.
-      #
-      # @param *array_matchers [Array[Any]]
-      #   Array style matchers
-      #
-      # @param **keyword_matchers [Hash[Any, Any]]
-      #   Hash style matchers
-      #
-      # @param &fn [Proc]
-      #   If matched, this function will be called
-      #
-      # @return [Array[GuardBlockMatcher]]
-      #   The return of this method should not be directly depended on, but will
-      #   provide all matchers currently present. This will likely be left for
-      #   ease of debugging later.
-      def when(*array_matchers, **keyword_matchers, &fn)
-        @matchers << Qo::Matchers::GuardBlockMatcher.new(*array_matchers, **keyword_matchers, &fn)
-      end
-
-      # Else is the last statement that will be evaluated if all other parts
-      # fail. It should be noted that it won't magically appear, you have to
-      # explicitly put an `else` case in for it to catch on no match unless
-      # you want a `nil` return
-      #
-      # @param &fn [Proc]
-      #   Function to call when all other matches have failed
-      #
-      # @return [Proc]
-      def else(&fn)
-        raise Qo::Exceptions::MultipleElseClauses if @else
-        @else = fn
-      end
-
-      # Proc version of a PatternMatchBlock
-      #
-      # @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
-        }
-
-        return @else.call(target) if @else
-
-        nil
-      end
-    end
-  end
-end