Short for Query Object, my play at Ruby pattern matching and fluent querying, pronounced "Q-whoah".
Read the Docs for more detailed information
Mostly by using Ruby language features like to_proc and ===.
There's an article explaining most of the base mechanics behind Qo:
For Want of Pattern Matching in Ruby - The Creation of Qo
Most of it, though, utilizes Triple Equals. If you're not familiar with what all you can do with it in Ruby, I would encourage you to read this article as well:
The original inspiration was from a chat I'd had with a few other Rubyists about pattern matching, which led to this experiment:
Fast forward a few months and I kind of wanted to make it real, so here it is. Introducing Qo!
Note that Qo uses the Any gem for wildcard matching. Any will respond true to any == or === query against it,
and is included in the gem.
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:
case ['Foo', 42]
when Qo[Any, 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 pattern matching? There are two styles:
Qo case statements work much like a Ruby case statement, except in that they leverage the full power of Qo matchers behind the scenes.
# How about some "right-hand assignment" pattern matching
name_longer_than_three = -> person { person.name.size > 3 }
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
}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.
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.
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
})
# And standalone like a case:
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)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:
Qo[/Rob/, 22]
# ...is functionally the same as an and query, which uses `all?` to match
Qo.and(/Rob/, 22)
# This is shorthand for
Qo::Matchers::BaseMatcher.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.
We will assume the following data:
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),
]Qo has a concept of a Wildcard, Any, which will match against any value
Qo[Any, Any] === ['Robert', 22] # trueA single wildcard will match anything, and can frequently be used as an always true:
Qo[Any] === :literally_anything_hereThe first way a Qo matcher can be defined is by using *varargs:
Qo::Matchers::BaseMatcher(type, *varargs, **kwargs)This gives us the and matcher shorthand for array matchers.
When an Array matcher is run against an Array, it will compare elements by index in the following priority:
- Does it case match (
===)? - 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.
We've seen some case matching so far with Range and Regex:
# Standalone
Qo[/Rob/, Any] === ['Robert', 22]
# => true
# Case statement
case ['Roberta', 22]
when Qo[Any, 0..9] then 'child'
when Qo[Any, 10..19] then 'teen'
when Qo[Any, 20..99] then 'adult'
else 'not sure'
end
# => 'adult'
# Select
people_arrays.select(&Qo[Any, 10..19])
# => [['Bar', 18]]If no case match is found, it will attempt to see if a predicate method by the same name exists, call it, and check the result:
dirty_values = [nil, '', true]
# Standalone
Qo[:nil?] === [nil]
# => true, though you could also just use Qo[nil]
# Case statement
case ['Roberta', nil]
when Qo[Any, :nil?] then 'no age'
else 'not sure'
end
# => 'no age'
# Select
people_arrays.select(&Qo[Any, :even?])
# => [["Robert", 22], ["Roberta", 22], ["Foo", 42], ["Bar", 18]]When an Array matcher is matched against anything other than an Array it will follow the priority:
- Does it case match (
===)? - Does it have a predicate method by that name that matches?
Every argument provided will be run against the target object.
# 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"]Now this is where some of the fun starts in
# Standalone
Qo.or(:nil?, :empty?) === nil
# => true
Qo.not(:nil?, :empty?) === nil
# => false
# Case statement
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(:nil?, :empty?))
# => [10, "string"]- Does the key exist on the other hash?
- Are the match value and match target hashes?
- Does the target object's value case match against the match value?
- Does the target object's value predicate match against the match value?
- What about the String version of the match key? Abort if it can't coerce.
Checks to see if the key is even present on the other object, false if not.
If both the match value (match_key: matcher) 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:
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
}
})If a case match is present for the key, it'll try and compare:
# 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!"
# 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}]Much like our array friend above, if a predicate style method is present see if it'll work
# 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!"
# Reject
people_hashes = people_arrays.map { |(n,a)| {name: n, age: a} } << {name: 'Ghost', 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.
Coerces the key into a string if possible, and sees if that can provide a valid case match
- Does the object respond to the match key?
- Does the result of sending the match key as a method case match the provided value?
- Does a predicate method exist for it?
If it doesn't know how to deal with it, false out.
This is where we can get into some interesting code, much like the hash selections above
# 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)]# 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?])
# => []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.
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"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:
- Iterate over every matcher until it finds a match
- Execute its block function
If no block function is provided, it assumes an identity function (-> v { v }) instead. If no match is found, nil will be returned.
name_longer_than_three = -> person { person.name.size > 3 }
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")]So we just truncated everyone's name that was longer than three characters.
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.
Dig is used to get in deep at a nested hash value. It takes a dot-path and a === respondent matcher:
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}}}
# => trueTo be fair that means anything that can respond to ===, including classes and other such things.
This ends up coming up a lot, especially around querying, so let's get a way to count by!
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
# }This feature may be added to Ruby 2.6+: https://bugs.ruby-lang.org/issues/11076
With the release of Qo 1.0.0 we introduced the idea of custom branches and pattern matchers for more advanced users of the library.
Consider a Monadic type like Some and None:
# Technically Some and None don't exist yet, so we have to "cheat" instead
# of just saying `Some` for the precondition
#
# We start by defining two branches that match against a Some type and a None
# type, extracting the value on match before yielding to their associated
# functions
SomeBranch = Qo.create_branch(
name: 'some',
precondition: -> v { v.is_a?(Some) },
extractor: :value
)
NoneBranch = Qo.create_branch(
name: 'none',
precondition: -> v { v.is_a?(None) },
extractor: :value
)
# Now we create a new pattern matching class with those branches. Note that
# there's nothing stopping you from making as many branches as you want,
# except that it may get confusing after a while.
SomePatternMatch = Qo.create_pattern_match(branches: [
SomeBranch,
NoneBranch
])
class Some
# There's also a provided mixin that gives an `match` method that
# works exactly like a pattern match without having to use it explicitly
include SomePatternMatch.mixin
attr_reader :value
def initialize(value) @value = value end
def self.[](value) new(value) end
def fmap(&fn)
new_value = fn.call(value)
new_value ? Some[new_value] : None[value]
end
end
class None
include SomePatternMatch.mixin
attr_reader :value
def initialize(value) @value = value end
def self.[](value) new(value) end
def fmap(&fn) None[value] end
end
# So now we can pattern match with `some` and `none` branches using the `match`
# method that was mixed into both types.
Some[1]
.fmap { |v| v * 2 }
.match { |m|
m.some { |v| v + 100 }
m.none { "OHNO!" }
}
=> 102
Some[1]
.fmap { |v| nil }
.match { |m|
m.some { |v| v + 100 }
m.none { "OHNO!" }
}
=> "OHNO!"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!
Note that Qo does not support deep querying of hashes (yet)
Qo tries to be clever though, it assumes Symbol keys first and then String keys, so how about some JSON?:
require 'json'
require 'net/http'
posts = JSON.parse(
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!
You can even use #yield_self to pipe values into a pattern matching block. In
this particular case it'll let you check against the type signatures of the
HTTP responses.
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 FoundThe difference between this and case? Well, the first is you can pass this to
yield_self for a more inline solution. The second is that any Qo matcher can
be used in there, including predicate and content checks on the body:
m.when(Net::HTTPSuccess, body: /Qo/)You could put as many checks as you want in there, or use different Qo matchers nested to get even further in.
Now if we wanted to add more power and create an HTTP matcher:
HTTP_Matcher = Qo.create_pattern_match(branches: [
Qo.create_branch(name: 'success', precondition: Net::HTTPSuccess),
Qo.create_branch(name: 'error', precondition: Net::HTTPError),
Qo::Braches::ElseBranch
])
def get_url(url)
Net::HTTP.get_response(URI(url)).then(&HTTP_Matcher.match { |m|
m.success { |response| response.body.size },
m.else { |response| raise response.message }
})
endWhat about NMap for our Opsy friends? Well, simulated, but still fun.
hosts = (`nmap -oG - -sP 192.168.1.* 10.0.0.* | grep Host`).lines.map { |v| v.split[1..2] }
=> [["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", "(Router)"], ["192.168.1.2", "(My Computer)"]]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 separators that may vary in length:
rows = CSV.new(`df -h`, col_sep: " ", headers: true).read.map(&:to_h)
rows.map(&Qo.match { |m|
m.when(Avail: /Gi$/) { |row|
"#{row['Filesystem']} mounted on #{row['Mounted']} [#{row['Avail']} / #{row['Size']}]"
}
}).compact
# => ["/dev/***** mounted on / [186Gi / 466Gi]"]Add this line to your application's Gemfile:
gem 'qo'And then execute:
$ bundle
Or install it yourself as:
$ gem install qo
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.
To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and tags, and push the .gem file to rubygems.org.
Bug reports and pull requests are welcome on GitHub at https://github.com/baweaver/qo. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the Contributor Covenant code of conduct.
The gem is available as open source under the terms of the MIT License.
Everyone interacting in the Qo project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.