qo 0.1.3 → 0.1.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: a106b00677e65b0d1bc7f87678d234aaba4a7580
-  data.tar.gz: 56745cdd7c92b3504434209bf269851e95bf6a6a
+  metadata.gz: a097911edc42e2a5ebf4ef3ea3fde3493ab82ae4
+  data.tar.gz: 7233bc3005d008543c13a2083b0f7e6560194b0f
 SHA512:
-  metadata.gz: c74eee58565ad19a3cd268e3f3a704d8c861f8c978f314ab830d011a46b67bd8a4031730a6a178514b0cf749e03b10643d129bc6fac7c12644520c6d3edacfd9
-  data.tar.gz: 7f976433977c10a5655313e4aacf155cfb5c6c4a4517ea9abfa8f6ce1c048381656f593661047e9d30524918f616c59bcc72c84449d8c55edadd7de057cd0425
+  metadata.gz: e53d71122117634454907e9fbe0b960a38aa7bedcebecb9faa876f8da2febd54e0f7da94278bae75bc75740697d2c37f7d8e81677ab0c31d915ffdb45ce7afea
+  data.tar.gz: 329801b537a3ac7d08e2f08741152fe3ca86265a4dc10178121ccc3aaa2f0230b64a882d0e8a509b7713e3dd1638dd987df6f5ee0d2b753c0aaa00bf3bff441a

data/README.md

@@ -2,22 +2,6 @@
 
 Short for Query Object, my play at Ruby pattern matching and fluent querying
 
-## Installation
-
-Add this line to your application's Gemfile:
-
-```ruby
-gem 'qo'
-```
-
-And then execute:
-
-    $ bundle
-
-Or install it yourself as:
-
-    $ gem install qo
-
 ## How does it work?
 
 Triple equals black magic, mostly.
@@ -37,97 +21,347 @@ Most examples are written in terms of `and` and its alias `[]`. `[]` is mostly u
 ```ruby
 Qo[/Rob/, 22]
 
-# ...is functionally the same as:
+# ...is functionally the same as an and query, which uses `all?` to match
 Qo.and(/Rob/, 22)
-```
 
-### Qo'isms
+# This is shorthand for
+Qo::Matcher.new('and', /Rob/, 22)
+
+# An `or` matcher uses the same shorthand as `and` but uses `any?` behind the scenes instead:
+Qo.or(/Rob/, 22)
+
+# Same with not, except it uses `none?`
+Qo.not(/Rob/, 22)
+```
 
 Qo has a few Qo'isms, mainly based around triple equals in Ruby. See the above articles for tutorials on that count.
 
-It also has a wildcard, `:*`, which will match any value:
+We will assume the following data:
+
+```ruby
+people_arrays = [
+  ['Robert', 22],
+  ['Roberta', 22],
+  ['Foo', 42],
+  ['Bar', 18]
+]
+
+people_objects = [
+  Person.new('Robert', 22),
+  Person.new('Roberta', 22),
+  Person.new('Foo', 42),
+  Person.new('Bar', 17),
+]
+```
+
+### 1 - Wildcard Matching
+
+Qo has a concept of a Wildcard, `:*`, which will match against any value
+
+```ruby
+Qo[:*, :*] === ['Robert', 22] # true
+```
+
+### 2 - Array Matching
+
+The first way a Qo matcher can be defined is by using `*varargs`:
 
 ```ruby
-Qo[/Rob/, :*] === ['Robert', 22] # true
+# Qo::Matcher(type, *varargs, **kwargs)
 ```
 
-As it responds to triple equals, that also means it can be used with `case` statements in a play at pattern matching:
+This gives us the `and` matcher shorthand for array matchers.
+
+#### 2.1 - Array matched against an Array
+
+When an Array matcher is run against an Array, it will compare elements by index in the following priority:
+
+1. Was a wildcard provided?
+2. Does it case match (`===`)?
+3. Does it have a predicate method by that name that matches?
+
+This functionality is left biased and permissive, meaning that if the right side of the argument is longer it will ignore those items in the match. If it's shorter? Not so much.
+
+##### 2.1.1 - Wildcard provided
 
 ```ruby
-case ['Robert', 22]
-when Qo[:*, 10..19] then 'teenager'
-when Qo[:*. 20..99] then 'adult'
-else 'who knows'
+# Standalone
+
+Qo[:*, :*] === ['Robert', 22]
+# => true
+
+# Case statement
+
+case ['Roberta', 22]
+when Qo[:*, :*] then 'it matched'
+else 'will not ever be reached'
 end
+# => 'adult'
+
+# Select
+
+people_arrays.select(&Qo[:*, :*])
+# => [['Robert', 22], ['Roberta', 22], ['Foo', 42], ['Bar', 18]]
 ```
 
-It's even nice enough to work on types, as they respond to `===` too:
+##### 2.1.2 - Case Match present
+
+We've seen some case matching so far with `Range` and `Regex`:
 
 ```ruby
-case ['Robert', 22]
-when Qo[String, Integer] then 'normal person'
-when Qo[String, Float] then 'probably a kid'
-else 'who knows'
+# Standalone
+
+Qo[/Rob/, :*] === ['Robert', 22]
+# => true
+
+# Case statement
+
+case ['Roberta', 22]
+when Qo[:*, 0..9] then 'child'
+when Qo[:*, 10..19] then 'teen'
+when Qo[:*, 20..99] then 'adult'
+else 'not sure'
 end
+# => 'adult'
+
+# Select
+
+people_arrays.select(&Qo[:*, 10..19])
+# => [['Bar', 18]]
 ```
 
-Predicate methods given as symbols will also call through:
+##### 2.1.3 - Predicate Method matched
+
+If no wildcard or case match is found, it will attempt to see if a predicate method by the same name exists, call it, and check the result:
 
 ```ruby
-case [1, 2]
-when Qo[:even?, :odd?], Qo[:odd?, :even?]
-  'balanced'
-when Qo[:even?, :even?]
-  'even better'
-when Qo[:odd?, :odd?]
-  'odd pair, them'
-else
-  'what did ya do!?'
+dirty_values = [nil, '', true]
+
+# Standalone
+
+Qo[:nil?] === [nil]
+# => true
+
+# Case statement
+
+case ['Roberta', nil]
+when Qo[:*, :nil?] then 'no age'
+else 'not sure'
 end
+# => 'adult'
+
+# Select
+
+people_arrays.select(&Qo[:*, :even?])
+# => [["Robert", 22], ["Roberta", 22], ["Foo", 42], ["Bar", 18]]
 ```
 
-Though chances are you don't have tuple-like code, you have objects. How about we play with those:
+#### 2.2 - Array matched against an Object
+
+When an Array matcher is matched against anything other than an Array it will follow the priority:
+
+1. Was a wildcard provided?
+2. Does it case match (`===`)?
+3. Does it have a predicate method by that name that matches?
+
+Every argument provided will be run against the target object.
+
+##### 2.2.1 - Wildcard provided
+
+A wildcard in an Array to Object match is functionally an always true, but can be used as such:
 
 ```ruby
-# Person has a name and an age attr
+Qo[:*] === :literally_anything_here
+```
+
+##### 2.2.2 - Case Match present
+
+```ruby
+# Standalone
+
+Qo[Integer, 15..25] === 20
+# => true
+
+# Case statement - functionally indistinguishable from a regular case statement
+
+# Select
+
+[nil, '', 10, 'string'].select(&Qo.or(/str/, 10..20))
+# => [10, "string"]
+```
+
+##### 2.2.3 - Predicate Method matched
+
+Now this is where some of the fun starts in
+
+```ruby
+# Standalone
+
+Qo.or(:nil?, :empty?) === nil
+# => true
+Qo.not(:nil?, :empty?) === nil
+# => false
+
+# Case statement
 
-case robert
-when Qo[age: 10..19] then 'teenager'
-when Qo[age: 20..99] then 'adult'
-else 'objection!'
+case 42
+when Qo[Integer, :even?, 40..50] then 'oddly specific number criteria'
+else 'nope'
 end
+# => "oddly specific number criteria"
+
+# Reject
+
+[nil, '', 10, 'string'].reject(&Qo.or(/str/, 10..20))
+# => [10, "string"]
 ```
 
-### Arrays
+### 3 - Hash Matching
+
+#### 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.
+
+##### 3.1.1 - Key present
+
+Checks to see if the key is even present on the other object, false if not.
 
-As Qo returns an Object that responds to `to_proc` it can be used with several Enumerable methods:
+##### 3.1.2 - Wildcard provided
+
+As with other wildcards, if the value matched against is a wildcard it'll always get through:
 
 ```ruby
-people = [
-  ['Robert', 22],
-  ['Roberta', 22],
-  ['Foo', 42],
-  ['Bar', 18]
-]
+Qo[name: :*] === {name: 'Foo'}
+# => true
+```
+
+##### 3.1.3 - Case match present
+
+If a case match is present for the key, it'll try and compare:
+
+```ruby
+# Standalone
+
+Qo[name: /Foo/] === {name: 'Foo'}
+# => true
+
+# Case statement
+
+case {name: 'Foo', age: 42}
+when Qo[age: 40..50] then 'Gotcha!'
+else 'nope'
+end
+# => "Gotcha!"
 
-people.select(&Qo[:*, 15..25]) # => [["Robert", 22], ["Roberta", 22], ["Bar", 18]]
+# Select
+
+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}]
 ```
 
-### Hashes and Objects
+##### 3.1.4 - Predicate match present
 
-If you have a lot of JSON or Objects, good news! Qo has tricks:
+Much like our array friend above, if a predicate style method is present see if it'll work
 
 ```ruby
-people = [
-  Person.new('Robert', 22),
-  Person.new('Roberta', 22),
-  Person.new('Foo', 42),
-  Person.new('Bar', 17),
-]
+# Standalone
+
+Qo[name: :empty?] === {name: ''}
+# => true
+
+# Case statement
+
+case {name: 'Foo', age: nil}
+when Qo[age: :nil?] then 'No age provided!'
+else 'nope'
+end
+# => "No age provided!"
+
+# Select
 
-people.select(&Qo[name: /Rob/]) # => [Person('Robert', 22), Person('Roberta', 22)]
+people_hashes = people_arrays.map { |(n,a)| {name: n, age: a} } << {name: 'Ghost', age: nil}
+people_hashes.select(&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
+
+Coerces the key into a string if possible, and sees if that can provide a valid case match
+
+#### 3.2 - Hash matched against an Object
+
+1. Does the object respond to the match key?
+2. Was a wildcard value provided?
+3. Does the result of sending the match key as a method case match the provided value?
+4. Does a predicate method exist for it?
+
+##### 3.2.1 - Responds to match key
+
+If it doesn't know how to deal with it, false out.
+
+##### 3.2.2 - Wildcard provided
+
+Same as other wildcards
+
+##### 3.2.3 - Case match present
+
+This is where we can get into some interesting code, much like the hash selections above
+
+```ruby
+# Standalone
+
+Qo[name: /Rob/] === people_objects.first
+# => true
+
+# Case statement
+
+case people_objects.first
+when Qo[name: /Rob/] then "It's Rob!"
+else 'Na, not them'
+end
+# => "It's Rob!"
+
+# Select
+
+people_objects.select(&Qo[name: /Rob/])
+# => [Person(Robert, 22), Person(Roberta, 22)]
+```
+
+##### 3.2.4 - Predicate match present
+
+```ruby
+# Standalone
+
+Qo[name: :empty?] === Person.new('', 22)
+# => true
+
+# Case statement
+
+case Person.new('', nil)
+when Qo[age: :nil?] then 'No age provided!'
+else 'nope'
+end
+# => "No age provided!"
+
+# Select
+
+people_hashes.select(&Qo[age: :nil?])
+# => []
+```
+
+### 4 - 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!
+
+#### 4.1 - JSON
+
 Qo tries to be clever though, it assumes Symbol keys first and then String keys, so how about some JSON?:
 
 ```ruby
@@ -142,17 +376,36 @@ posts.select(&Qo[userId: 1])
 
 Nifty!
 
+#### 4.2 - Opsy Stuff
+
+##### 4.2.1 - NMap
+
 What about NMap for our Opsy friends? Well, simulated, but still fun.
 
 ```ruby
 hosts = (`nmap -oG - -sP 192.168.1.* 10.0.0.* | grep Host`).lines.map { |v| v.split[1..2] }
-=> [["192.168.1.1", "(Linksys03384)"], ["192.168.1.2", "(My Computer)"], ["10.0.0.1", "(Gateway)"]]
+=> [["192.168.1.1", "(Router)"], ["192.168.1.2", "(My Computer)"], ["10.0.0.1", "(Gateway)"]]
 
 hosts.select(&Qo[IPAddr.new('192.168.1.1/8')])
-=> [["192.168.1.1", "(Linksys03384)"], ["192.168.1.2", "(My Computer)"]]
-[13] pry(main)>
+=> [["192.168.1.1", "(Router)"], ["192.168.1.2", "(My Computer)"]]
+```
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'qo'
 ```
 
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install qo
+
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.

data/lib/qo/matcher.rb

@@ -116,11 +116,14 @@ 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) &&
         wildcard_match(match_value) ||
-        case_match(match_target[match_key], match_value) || (
+        case_match(match_target[match_key], match_value)  ||
+        method_matches?(match_target[match_key], match_value) || (
           # This is done for JSON responses, but as key can be `Any` we don't want to assume it knows how
           # to coerce `to_s` either. It's more of a nicety function.
           match_key.respond_to?(:to_s) &&
+          match_target.key?(match_key.to_s) &&
           case_match(match_target[match_key.to_s], match_value)
         )
       }
@@ -134,8 +137,10 @@ 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) &&
         wildcard_match(match_value) ||
-        case_match(method_send(match_target, match_key), match_value)
+        case_match(method_send(match_target, match_key), match_value) ||
+        method_matches?(method_send(match_target, match_key), match_value)
       }
     end
 

data/lib/qo/version.rb

@@ -1,3 +1,3 @@
 module Qo
-  VERSION = '0.1.3'
+  VERSION = '0.1.4'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: qo
 version: !ruby/object:Gem::Version
-  version: 0.1.3
+  version: 0.1.4
 platform: ruby
 authors:
 - Brandon Weaver