qo 0.2.0 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: dcbbe9e009a9ccf04769b8ccb7eca4343ea972a5
-  data.tar.gz: 53dae10eca53508dacfb75ad940207f0f047d288
+SHA256:
+  metadata.gz: 11b6629bbb972894e4d1ebc01916769e14a70ec4dbc0d197f990d2c6849d3ffa
+  data.tar.gz: d609ce71af4795164999b2219f3e70892c09c0eaca4174d73d79bc3e2d988231
 SHA512:
-  metadata.gz: 62bceca4a54804a1e18c86a26802e3903693a61d213fa27b959e0e6a362b54470aeb22f45101ebd8b73cb5dfa90a7c1214c7d78574d3a366a679734744005007
-  data.tar.gz: 40a0319fa994a9e82e1f55001deab434e95187819efc1ef5eaa6bdd9be015987c481b7b7097b00820974cdc43eeed815fc4b9f7d442f5388b1881549ad00eb62
+  metadata.gz: c44fe7b89ec3da320eca4007f0b207da6d2300999c23c167c494e281bbe96c7449f88419d1eec29dcc9f5bc987df3ecea9b1bb0b88afa7968c6e2f3d94b12237
+  data.tar.gz: c4e5e607debf592180547d4f7180251e38cc09958a5a2f4961ebbe91c4a52416fb2a2ceeb26c7ba0076e24999c7333716141649aace38d4152931040d8b1dc7d

data/.yardopts

@@ -0,0 +1,3 @@
+--markup=markdown
+--asset img:img
+--output-dir docs

data/README.md

@@ -4,10 +4,12 @@
 [![Maintainability](https://api.codeclimate.com/v1/badges/186e9cbb7003842acaf0/maintainability)](https://codeclimate.com/github/baweaver/qo/maintainability)
 [![Gem Version](https://badge.fury.io/rb/qo.svg)](https://badge.fury.io/rb/qo)
 
-Short for Query Object, my play at Ruby pattern matching and fluent querying
+Short for Query Object, my play at Ruby pattern matching and fluent querying, [pronounced "Q-whoah"](img/whoa_lemur.png).
 
 ![Qo Lemur logo](img/qo_logo.png)
 
+[Read the Docs for more detailed information](https://baweaver.github.io/qo/)
+
 ## How does it work?
 
 Mostly by using Ruby language features like `to_proc` and `===`.
@@ -537,7 +539,7 @@ Qo.count_by([1,2,3,2,2,2,1], &:even?)
 
 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
+#### 5.1 - JSON and HTTP
 
 > Note that Qo does not support deep querying of hashes (yet)
 
@@ -581,6 +583,37 @@ users.select(&Qo.and(
 
 Nifty!
 
+##### Yield Self HTTP status matching
+
+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.
+
+```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(:*)               { |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
+```
+
+The 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:
+
+```ruby
+Qo.m(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.
+
 #### 5.2 - Opsy Stuff
 
 ##### 5.2.1 - NMap

data/Rakefile

@@ -22,6 +22,13 @@ task :default => :spec
 def run_benchmark(title, **benchmarks)
   puts '', title, '=' * title.size, ''
 
+  # Validation
+  benchmarks.each do |benchmark_name, benchmark_fn|
+    puts "#{benchmark_name} result: #{benchmark_fn.call()}"
+  end
+
+  puts
+
   Benchmark.ips do |bm|
     benchmarks.each do |benchmark_name, benchmark_fn|
       bm.report(benchmark_name, &benchmark_fn)
@@ -31,10 +38,14 @@ def run_benchmark(title, **benchmarks)
   end
 end
 
+def xrun_benchmark(title, **benchmarks) end
+
 # Note that the current development of Qo is NOT to be performance first, it's to
 # be readability first with performance coming later. That means that early iterations
 # may well be slower, but the net expressiveness we get is worth it in the short run.
 task :perf do
+  puts "Running on Qo v#{Qo::VERSION} at commit #{`git rev-parse HEAD`}"
+
   # Compare simple array equality. I almost think this isn't fair to Qo considering
   # no sane dev should use it for literal 1 to 1 matches like this.
 
@@ -45,7 +56,7 @@ task :perf do
     },
 
     'Qo.and':  -> {
-      Qo.and(*simple_array).call(simple_array)
+      Qo.and(1, 1).call(simple_array)
     }
   )
 
@@ -61,7 +72,7 @@ task :perf do
     },
 
     'Qo.and':  -> {
-      Qo.and(*range_match_set).call(range_match_target)
+      Qo.and(1..10, 1..10, 1..10, 1..10).call(range_match_target)
     }
   )
 
@@ -101,7 +112,37 @@ task :perf do
     },
 
     'Qo.and':  -> {
-      Qo.and(*people_array_query).call(people_array_target)
+      people_array_target.select(&Qo.and(/Rob/, 15..25))
+    }
+  )
+
+  people_hashes = people_array_target.map { |(name, age)| {name: name, age: age} }
+
+  run_benchmark('Hash * Hash - Hash intersection',
+    'Vanilla': -> {
+      people_hashes.select { |person| (15..25).include?(person[:age]) && /Rob/ =~ person[:name] }
+    },
+
+    'Qo.and':  -> {
+      people_hashes.select(&Qo.and(name: /Rob/, age: 15..25))
+    }
+  )
+
+  Person = Struct.new(:name, :age)
+  people = [
+    Person.new('Robert', 22),
+    Person.new('Roberta', 22),
+    Person.new('Foo', 42),
+    Person.new('Bar', 17)
+  ]
+
+  run_benchmark('Hash * Object - Property match',
+    'Vanilla': -> {
+      people.select { |person| (15..25).include?(person.age) && /Rob/ =~ person.name }
+    },
+
+    'Qo.and':  -> {
+      people.select(&Qo.and(name: /Rob/, age: 15..25))
     }
   )
 end
@@ -117,6 +158,17 @@ end
 # of the 2.4+ bug of lambdas not destructuring automatically, which will wreak
 # havoc on hash matchers.
 
+task :kwargs_vs_positional do
+  def add_kw(a:, b:, c:, d:) a + b + c + d end
+
+  def add_pos(a,b,c,d) a + b + c + d end
+
+  run_benchmark('Positional vs KW Args',
+    'keyword':      -> { add_kw(a: 1, b: 2, c: 3, d: 4) },
+    'positional':   -> { add_pos(1,2,3,4) }
+  )
+end
+
 task :perf_predicates do
   array = (1..1000).to_a
 
@@ -154,18 +206,18 @@ task :perf_predicates do
 end
 
 task :perf_random do
-  # run_benchmark('Empty on blank array',
-  #   'empty?':     -> { [].empty?     },
-  #   'size == 0':  -> { [].size == 0  },
-  #   'size.zero?': -> { [].size.zero? },
-  # )
+  run_benchmark('Empty on blank array',
+    'empty?':     -> { [].empty?     },
+    'size == 0':  -> { [].size == 0  },
+    'size.zero?': -> { [].size.zero? },
+  )
 
   array = (1..1000).to_a
-  # run_benchmark('Empty on several elements array',
-  #   'empty?':     -> { array.empty?     },
-  #   'size == 0':  -> { array.size == 0  },
-  #   'size.zero?': -> { array.size.zero? },
-  # )
+  run_benchmark('Empty on several elements array',
+    'empty?':     -> { array.empty?     },
+    'size == 0':  -> { array.size == 0  },
+    'size.zero?': -> { array.size.zero? },
+  )
 
   hash = array.map { |v| [v, v] }.to_h
 

data/docs/Qo.html

@@ -0,0 +1,165 @@
+<!DOCTYPE html>
+<html>
+  <head>
+    <meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1.0">
+<title>
+  Module: Qo
+  
+    &mdash; Documentation by YARD 0.9.12
+  
+</title>
+
+  <link rel="stylesheet" href="css/style.css" type="text/css" charset="utf-8" />
+
+  <link rel="stylesheet" href="css/common.css" type="text/css" charset="utf-8" />
+
+<script type="text/javascript" charset="utf-8">
+  pathId = "Qo";
+  relpath = '';
+</script>
+
+
+  <script type="text/javascript" charset="utf-8" src="js/jquery.js"></script>
+
+  <script type="text/javascript" charset="utf-8" src="js/app.js"></script>
+
+
+  </head>
+  <body>
+    <div class="nav_wrap">
+      <iframe id="nav" src="class_list.html?1"></iframe>
+      <div id="resizer"></div>
+    </div>
+
+    <div id="main" tabindex="-1">
+      <div id="header">
+        <div id="menu">
+  
+    <a href="_index.html">Index (Q)</a> &raquo;
+    
+    
+    <span class="title">Qo</span>
+  
+</div>
+
+        <div id="search">
+  
+    <a class="full_list_link" id="class_list_link"
+        href="class_list.html">
+
+        <svg width="24" height="24">
+          <rect x="0" y="4" width="24" height="4" rx="1" ry="1"></rect>
+          <rect x="0" y="12" width="24" height="4" rx="1" ry="1"></rect>
+          <rect x="0" y="20" width="24" height="4" rx="1" ry="1"></rect>
+        </svg>
+    </a>
+  
+</div>
+        <div class="clear"></div>
+      </div>
+
+      <div id="content"><h1>Module: Qo
+  
+  
+  
+</h1>
+<div class="box_info">
+  
+
+  
+  
+  <dl>
+      <dt>Extended by:</dt>
+      <dd><span class='object_link'><a href="Qo/Exceptions.html" title="Qo::Exceptions (module)">Exceptions</a></span>, <span class='object_link'><a href="Qo/Helpers.html" title="Qo::Helpers (module)">Helpers</a></span>, <span class='object_link'><a href="Qo/PublicApi.html" title="Qo::PublicApi (module)">PublicApi</a></span></dd>
+  </dl>
+  
+  
+  
+  
+
+  
+
+  
+  <dl>
+    <dt>Defined in:</dt>
+    <dd>lib/qo.rb<span class="defines">,<br />
+  lib/qo/helpers.rb,<br /> lib/qo/version.rb,<br /> lib/qo/exceptions.rb,<br /> lib/qo/public_api.rb,<br /> lib/qo/matchers/base_matcher.rb,<br /> lib/qo/matchers/hash_matcher.rb,<br /> lib/qo/matchers/array_matcher.rb,<br /> lib/qo/matchers/pattern_match.rb,<br /> lib/qo/matchers/guard_block_matcher.rb</span>
+</dd>
+  </dl>
+  
+</div>
+
+<h2>Defined Under Namespace</h2>
+<p class="children">
+  
+    
+      <strong class="modules">Modules:</strong> <span class='object_link'><a href="Qo/Exceptions.html" title="Qo::Exceptions (module)">Exceptions</a></span>, <span class='object_link'><a href="Qo/Helpers.html" title="Qo::Helpers (module)">Helpers</a></span>, <span class='object_link'><a href="Qo/Matchers.html" title="Qo::Matchers (module)">Matchers</a></span>, <span class='object_link'><a href="Qo/PublicApi.html" title="Qo::PublicApi (module)">PublicApi</a></span>
+    
+  
+    
+  
+</p>
+
+  <h2>Constant Summary</h2>
+  <dl class="constants">
+    
+      <dt id="WILDCARD_MATCH-constant" class="">WILDCARD_MATCH =
+        
+      </dt>
+      <dd><pre class="code"><span class='symbol'>:*</span></pre></dd>
+    
+      <dt id="VERSION-constant" class="">VERSION =
+        
+      </dt>
+      <dd><pre class="code"><span class='tstring'><span class='tstring_beg'>&#39;</span><span class='tstring_content'>0.2.0</span><span class='tstring_end'>&#39;</span></span></pre></dd>
+    
+  </dl>
+
+
+
+
+
+
+
+
+  
+  
+  
+  
+  
+  
+  <h2>Method Summary</h2>
+  
+  <h3 class="inherited">Methods included from <span class='object_link'><a href="Qo/PublicApi.html" title="Qo::PublicApi (module)">PublicApi</a></span></h3>
+  <p class="inherited"><span class='object_link'><a href="Qo/PublicApi.html#and-instance_method" title="Qo::PublicApi#and (method)">and</a></span>, <span class='object_link'><a href="Qo/PublicApi.html#match-instance_method" title="Qo::PublicApi#match (method)">match</a></span>, <span class='object_link'><a href="Qo/PublicApi.html#matcher-instance_method" title="Qo::PublicApi#matcher (method)">matcher</a></span>, <span class='object_link'><a href="Qo/PublicApi.html#not-instance_method" title="Qo::PublicApi#not (method)">not</a></span>, <span class='object_link'><a href="Qo/PublicApi.html#or-instance_method" title="Qo::PublicApi#or (method)">or</a></span></p>
+
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  <h3 class="inherited">Methods included from <span class='object_link'><a href="Qo/Helpers.html" title="Qo::Helpers (module)">Helpers</a></span></h3>
+  <p class="inherited"><span class='object_link'><a href="Qo/Helpers.html#count_by-instance_method" title="Qo::Helpers#count_by (method)">count_by</a></span>, <span class='object_link'><a href="Qo/Helpers.html#dig-instance_method" title="Qo::Helpers#dig (method)">dig</a></span></p>
+
+
+</div>
+
+      <div id="footer">
+  Generated on Sun Apr 15 20:29:44 2018 by
+  <a href="http://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
+  0.9.12 (ruby-2.4.4).
+</div>
+
+    </div>
+  </body>
+</html>

data/docs/Qo/Exceptions.html

@@ -0,0 +1,160 @@
+<!DOCTYPE html>
+<html>
+  <head>
+    <meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1.0">
+<title>
+  Module: Qo::Exceptions
+  
+    &mdash; Documentation by YARD 0.9.12
+  
+</title>
+
+  <link rel="stylesheet" href="../css/style.css" type="text/css" charset="utf-8" />
+
+  <link rel="stylesheet" href="../css/common.css" type="text/css" charset="utf-8" />
+
+<script type="text/javascript" charset="utf-8">
+  pathId = "Qo::Exceptions";
+  relpath = '../';
+</script>
+
+
+  <script type="text/javascript" charset="utf-8" src="../js/jquery.js"></script>
+
+  <script type="text/javascript" charset="utf-8" src="../js/app.js"></script>
+
+
+  </head>
+  <body>
+    <div class="nav_wrap">
+      <iframe id="nav" src="../class_list.html?1"></iframe>
+      <div id="resizer"></div>
+    </div>
+
+    <div id="main" tabindex="-1">
+      <div id="header">
+        <div id="menu">
+  
+    <a href="../_index.html">Index (E)</a> &raquo;
+    <span class='title'><span class='object_link'><a href="../Qo.html" title="Qo (module)">Qo</a></span></span>
+     &raquo; 
+    <span class="title">Exceptions</span>
+  
+</div>
+
+        <div id="search">
+  
+    <a class="full_list_link" id="class_list_link"
+        href="../class_list.html">
+
+        <svg width="24" height="24">
+          <rect x="0" y="4" width="24" height="4" rx="1" ry="1"></rect>
+          <rect x="0" y="12" width="24" height="4" rx="1" ry="1"></rect>
+          <rect x="0" y="20" width="24" height="4" rx="1" ry="1"></rect>
+        </svg>
+    </a>
+  
+</div>
+        <div class="clear"></div>
+      </div>
+
+      <div id="content"><h1>Module: Qo::Exceptions
+  
+  
+  
+</h1>
+<div class="box_info">
+  
+
+  
+  
+  
+  
+  
+
+  
+  <dl>
+    <dt>Included in:</dt>
+    <dd><span class='object_link'><a href="../Qo.html" title="Qo (module)">Qo</a></span>, <span class='object_link'><a href="PublicApi.html" title="Qo::PublicApi (module)">PublicApi</a></span></dd>
+  </dl>
+  
+
+  
+  <dl>
+    <dt>Defined in:</dt>
+    <dd>lib/qo/exceptions.rb</dd>
+  </dl>
+  
+</div>
+
+<h2>Overview</h2><div class="docstring">
+  <div class="discussion">
+    <p>Defines common exception classes for use throughout the library</p>
+
+
+  </div>
+</div>
+<div class="tags">
+  
+<p class="tag_title">Author:</p>
+<ul class="author">
+  
+    <li>
+      
+      
+      
+      
+        
+        <div class='inline'><p>baweaver</p>
+</div>
+      
+    </li>
+  
+</ul>
+<p class="tag_title">Since:</p>
+<ul class="since">
+  
+    <li>
+      
+      
+      
+      
+        
+        <div class='inline'><p>0.2.0</p>
+</div>
+      
+    </li>
+  
+</ul>
+
+</div><h2>Defined Under Namespace</h2>
+<p class="children">
+  
+    
+  
+    
+      <strong class="classes">Classes:</strong> <span class='object_link'><a href="Exceptions/MultipleMatchersProvided.html" title="Qo::Exceptions::MultipleMatchersProvided (class)">MultipleMatchersProvided</a></span>, <span class='object_link'><a href="Exceptions/NoMatchersProvided.html" title="Qo::Exceptions::NoMatchersProvided (class)">NoMatchersProvided</a></span>, <span class='object_link'><a href="Exceptions/NotAllGuardMatchersProvided.html" title="Qo::Exceptions::NotAllGuardMatchersProvided (class)">NotAllGuardMatchersProvided</a></span>
+    
+  
+</p>
+
+
+
+
+
+
+
+
+
+</div>
+
+      <div id="footer">
+  Generated on Sun Apr 15 20:29:44 2018 by
+  <a href="http://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
+  0.9.12 (ruby-2.4.4).
+</div>
+
+    </div>
+  </body>
+</html>