qo 0.1.6 → 0.1.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: d097b1d36fb935478c96f41a34ac4e7e74ccdcc7
-  data.tar.gz: 51ea508193f5156aafc7e86a1a8de2fc0e77c36b
+  metadata.gz: c98fa2c3b82ac4167eba17b183fe1cea46a0e36f
+  data.tar.gz: ab2527c365781b54fac1290ac64e8a17acdcd07c
 SHA512:
-  metadata.gz: 8fc0fa88d3264cd2c8cafefea4be82bdd14bc7eed37d41d0e890d6c55a2352f784327db6d718c24c011b3d39b813501952c4f9859571b5ffaa812d5bf1c1259c
-  data.tar.gz: f6d73da83547b82ab3ad62822d1ce3fd7cab7feb396f5542431d015d907d66353bd126bcf3b4baf06a2951622468524420f0cd69a59ac5c56d6cede08dc40582
+  metadata.gz: f1e9b886e694b8c08f212209db40bc8ca1276b738d1d30c81040e0b651f264bcfc9c83a21d82d96f2ff418d05def3e5abae82a29394f184266fab424f5dad4a6
+  data.tar.gz: ab226ea4d673ea462b2e41084d25c8a61b2c04e37e8aac9354745b1b17c4ae54b5efa6184ae28e0201fa453b525938f4d8f260912300a0f145cc0992607424e1

data/README.md

@@ -14,6 +14,38 @@ Fast forward a few months and I kind of wanted to make it real, so here it is. I
 
 ## Usage
 
+### Quick Start
+
+Qo is used for pattern matching in Ruby. All Qo matchers respond to `===` and `to_proc` meaning they can be used with `case` and Enumerable functions alike:
+
+
+```ruby
+case ['Foo', 42]
+when Qo[:*, 42] then 'Truly the one answer'
+else nil
+end
+
+# Run a select like an AR query, getting the age attribute against a range
+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(
+  Qo.m(name_longer_than_three) { |person| Person.new(person.name[0..2], person.age) },
+  Qo.m(:*) # Identity function, catch-all
+))
+
+# 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(:*) { |person| "#{person.name} is #{person.age} years old" }
+)
+```
+
+Get a lot more expressiveness in your queries and transformations. Read on for the full details.
+
+### Qo'isms
+
 Qo supports three main types of queries: `and`, `or`, and `not`.
 
 Most examples are written in terms of `and` and its alias `[]`. `[]` is mostly used for portable syntax:
@@ -62,6 +94,12 @@ Qo has a concept of a Wildcard, `:*`, which will match against any value
 Qo[:*, :*] === ['Robert', 22] # true
 ```
 
+A single wildcard will match anything, and can frequently be used as an always true:
+
+```ruby
+Qo[:*] === :literally_anything_here
+```
+
 ### 2 - Array Matching
 
 The first way a Qo matcher can be defined is by using `*varargs`:
@@ -96,7 +134,7 @@ case ['Roberta', 22]
 when Qo[:*, :*] then 'it matched'
 else 'will not ever be reached'
 end
-# => 'adult'
+# => 'it matched'
 
 # Select
 
@@ -140,7 +178,7 @@ dirty_values = [nil, '', true]
 # Standalone
 
 Qo[:nil?] === [nil]
-# => true
+# => true, though you could also just use Qo[nil]
 
 # Case statement
 
@@ -148,7 +186,7 @@ case ['Roberta', nil]
 when Qo[:*, :nil?] then 'no age'
 else 'not sure'
 end
-# => 'adult'
+# => 'no age'
 
 # Select
 
@@ -212,7 +250,7 @@ end
 
 # Reject
 
-[nil, '', 10, 'string'].reject(&Qo.or(/str/, 10..20))
+[nil, '', 10, 'string'].reject(&Qo.or(:nil?, :empty?))
 # => [10, "string"]
 ```
 
@@ -221,16 +259,58 @@ end
 #### 3.1 - Hash matched against a Hash
 
 1. Does the key exist on the other hash?
-2. Was a wildcard value provided?
-3. Does the target object's value case match against the match value?
-4. Does the target object's value predicate match against the match value?
-5. What about the String version of the match key? Abort if it can't coerce.
+2. Are the match value and match target hashes?
+3. Was a wildcard value provided?
+4. Does the target object's value case match against the match value?
+5. Does the target object's value predicate match against the match value?
+6. What about the String version of the match key? Abort if it can't coerce.
 
 ##### 3.1.1 - Key present
 
 Checks to see if the key is even present on the other object, false if not.
 
-##### 3.1.2 - Wildcard provided
+##### 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:
+
+```ruby
+Qo[a: {b: {c: 5..15}}] === {a: {b: {c: 10}}}
+# => true
+
+# Na, no fun. Deeper!
+Qo.and(a: {
+  f: 5..15,
+  b: {
+    c: /foo/,
+    d: 10..30
+  }
+}).call(a: {
+  f: 10,
+  b: {
+    c: 'foobar',
+    d: 20
+  }
+})
+# => true
+
+# It can get chaotic with `or` though. Anything anywhere in there matches and
+# it'll pass.
+Qo.or(a: {
+  f: false,
+  b: {
+    c: /nope/,
+    d: 10..30
+  }
+}).call(a: {
+  f: 10,
+  b: {
+    c: 'foobar',
+    d: 20
+  }
+})
+```
+
+##### 3.1.3 - Wildcard provided
 
 As with other wildcards, if the value matched against is a wildcard it'll always get through:
 
@@ -239,7 +319,7 @@ Qo[name: :*] === {name: 'Foo'}
 # => true
 ```
 
-##### 3.1.3 - Case match present
+##### 3.1.4 - Case match present
 
 If a case match is present for the key, it'll try and compare:
 
@@ -259,12 +339,12 @@ end
 
 # Select
 
-people_hashes = people_arrays.map { |(n,a)| {name: n, age: a} }
+people_hashes = people_arrays.map { |n, a| {name: n, age: a} }
 people_hashes.select(&Qo[age: 15..25])
 # => [{:name=>"Robert", :age=>22}, {:name=>"Roberta", :age=>22}, {:name=>"Bar", :age=>18}]
 ```
 
-##### 3.1.4 - Predicate match present
+##### 3.1.5 - Predicate match present
 
 Much like our array friend above, if a predicate style method is present see if it'll work
 
@@ -282,16 +362,16 @@ else 'nope'
 end
 # => "No age provided!"
 
-# Select
+# Reject
 
 people_hashes = people_arrays.map { |(n,a)| {name: n, age: a} } << {name: 'Ghost', age: nil}
-people_hashes.select(&Qo[age: :nil?])
+people_hashes.reject(&Qo[age: :nil?])
 # => [{:name=>"Robert", :age=>22}, {:name=>"Roberta", :age=>22}, {:name=>"Bar", :age=>18}]
 ```
 
 Careful though, if the key doesn't exist that won't match. I'll have to consider this one later.
 
-##### 3.1.5 - String variant present
+##### 3.1.6 - String variant present
 
 Coerces the key into a string if possible, and sees if that can provide a valid case match
 
@@ -308,7 +388,7 @@ If it doesn't know how to deal with it, false out.
 
 ##### 3.2.2 - Wildcard provided
 
-Same as other wildcards
+Same as other wildcards, but if the object doesn't respond to the method you specify it'll have false'd out before it reaches here.
 
 ##### 3.2.3 - Case match present
 
@@ -402,22 +482,89 @@ people_objects.map(&Qo.match_fn(
 
 So we just truncated everyone's name that was longer than three characters.
 
+### 6 - Helper functions
+
+There are a few functions added for convenience, and it should be noted that because all Qo matchers respond to `===` that they can be used as helpers as well.
+
+#### 6.1 - Dig
+
+Dig is used to get in deep at a nested hash value. It takes a dot-path and a `===` respondant matcher:
+
+```ruby
+Qo.dig('a.b.c', Qo.or(1..5, 15..25)) === {a: {b: {c: 1}}}
+# => true
+
+Qo.dig('a.b.c', Qo.or(1..5, 15..25)) === {a: {b: {c: 20}}}
+# => true
+```
+
+To be fair that means anything that can respond to `===`, including classes and other such things.
+
+#### 6.2 - Count By
+
+This ends up coming up a lot, especially around querying, so let's get a way to count by!
+
+```ruby
+Qo.count_by([1,2,3,2,2,2,1]
+
+# => {
+#   1 => 2,
+#   2 => 4,
+#   3 => 1
+# }
+
+Qo.count_by([1,2,3,2,2,2,1], &:even?)
+
+# => {
+#   false => 3,
+#   true  => 4
+# }
+```
+
 ### 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!
 
 #### 5.1 - JSON
 
+> Note that Qo does not support deep querying of hashes (yet)
+
+##### 5.1.1 - JSON Placeholder
+
 Qo tries to be clever though, it assumes Symbol keys first and then String keys, so how about some JSON?:
 
 ```ruby
 require 'json'
 require 'net/http'
+
 posts = JSON.parse(
-  Net::HTTP.get(URI("https://jsonplaceholder.typicode.com/posts")),symbolize_names: true
+  Net::HTTP.get(URI("https://jsonplaceholder.typicode.com/posts")), symbolize_names: true
+)
+
+users = JSON.parse(
+  Net::HTTP.get(URI("https://jsonplaceholder.typicode.com/users")), symbolize_names: true
 )
 
+# Get all posts where the userId is 1.
 posts.select(&Qo[userId: 1])
+
+# Get users named Nicholas or have two names and an address somewhere with a zipcode
+# that starts with 9 or 4.
+#
+# Qo matchers return a `===` respondant object, remember, so we can totally nest them.
+users.select(&Qo.and(
+  name: Qo.or(/^Nicholas/, /^\w+ \w+$/),
+  address: {
+    zipcode: Qo.or(/^9/, /^4/)
+  }
+))
+
+# We could even use dig to get at some of the same information. This and the above will
+# return the same results even.
+users.select(&Qo.and(
+  Qo.dig('address.zipcode', Qo.or(/^9/, /^4/)),
+  name: Qo.or(/^Nicholas/, /^\w+ \w+$/)
+))
 ```
 
 Nifty!
@@ -436,6 +583,21 @@ hosts.select(&Qo[IPAddr.new('192.168.1.1/8')])
 => [["192.168.1.1", "(Router)"], ["192.168.1.2", "(My Computer)"]]
 ```
 
+##### 5.2.2 - `du`
+
+The nice thing about Unix style commands is that they use headers, which means CSV can get a hold of them for some good formatting. It's also smart enough to deal with space seperators that may vary in length:
+
+```ruby
+rows = CSV.new(`df -h`, col_sep: " ", headers: true).read.map(&:to_h)
+
+rows.map(&Qo.match_fn(
+  Qo.m(Avail: /Gi$/) { |row|
+    "#{row['Filesystem']} mounted on #{row['Mounted']} [#{row['Avail']} / #{row['Size']}]"
+  }
+)).compact
+# => ["/dev/***** mounted on / [186Gi / 466Gi]"]
+```
+
 ## Installation
 
 Add this line to your application's Gemfile:

data/docs/_config.yml

@@ -0,0 +1 @@
+theme: jekyll-theme-cayman

data/lib/qo.rb

@@ -6,31 +6,61 @@ module Qo
   WILDCARD_MATCH = :*
 
   class << self
-    def m(*array_matchers, **keyword_matchers, &fn)
+
+    # 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
 
-    def match(data, *qo_matchers)
-      all_are_guards = qo_matchers.all? { |q| q.is_a?(Qo::GuardBlockMatcher)}
+    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(data)
+        did_match, match_result = matcher.call(target)
         break match_result if did_match
       }
     end
 
+    # 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)
-      -> data { match(data, *qo_matchers) }
+      -> target { match(target, *qo_matchers) }
     end
 
     def and(*array_matchers, **keyword_matchers)
       Qo::Matcher.new('and', *array_matchers, **keyword_matchers)
     end
 
-    def [](*array_matchers, **keyword_matchers)
-      Qo::Matcher.new('and', *array_matchers, **keyword_matchers)
-    end
+    alias_method :[], :and
 
     def or(*array_matchers, **keyword_matchers)
       Qo::Matcher.new('or', *array_matchers, **keyword_matchers)
@@ -39,5 +69,24 @@ module Qo
     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 }
+
+      targets.each_with_object(Hash.new(0)) { |target, counts|
+        counts[fn[target]] += 1
+      }
+    end
   end
 end

data/lib/qo/matcher.rb

@@ -116,7 +116,13 @@ module Qo
     #     Any -> Any -> Bool # Matches against wildcard or a key and value. Coerces key to_s if no matches for JSON.
     private def hash_against_hash_matcher(match_target)
       -> match_key, match_value {
-        match_target.key?(match_key) &&
+        return false unless match_target.key?(match_key)
+
+        # If both the match value and target are hashes, descend if the key exists
+        if match_value.is_a?(Hash) && match_target.is_a?(Hash)
+          return match_against_hash(match_value)[match_target[match_key]]
+        end
+
         wildcard_match(match_value) ||
         case_match(match_target[match_key], match_value)  ||
         method_matches?(match_target[match_key], match_value) || (
@@ -137,7 +143,8 @@ module Qo
     #     Any -> Any -> Bool # Matches against wildcard or match value versus the public send return of the target
     private def hash_against_object_matcher(match_target)
       -> match_key, match_value {
-        match_target.respond_to?(match_key) &&
+        return false unless match_target.respond_to?(match_key)
+
         wildcard_match(match_value) ||
         case_match(method_send(match_target, match_key), match_value) ||
         method_matches?(method_send(match_target, match_key), match_value)
@@ -191,7 +198,7 @@ module Qo
 
     # 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.
+    # more of a clarity thing than anything. Also makes for nicer stack traces.
     #
     # @param target [Any] Target to match against
     # @param value [respond_to?(:===)]

data/lib/qo/version.rb

@@ -1,3 +1,3 @@
 module Qo
-  VERSION = '0.1.6'
+  VERSION = '0.1.7'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: qo
 version: !ruby/object:Gem::Version
-  version: 0.1.6
+  version: 0.1.7
 platform: ruby
 authors:
 - Brandon Weaver
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2018-04-12 00:00:00.000000000 Z
+date: 2018-04-13 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -99,6 +99,8 @@ files:
 - Rakefile
 - bin/console
 - bin/setup
+- docs/.gitkeep
+- docs/_config.yml
 - lib/qo.rb
 - lib/qo/guard_block_matcher.rb
 - lib/qo/matcher.rb