patrun 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 26be7b15694fcdb3af30b2cf505e1f5446e75094
-  data.tar.gz: 8d6c257f618b6c0acdbfa7ff47a2cb02c0225014
+  metadata.gz: 0a552276944c28770e97035adabe76cb38332489
+  data.tar.gz: 651c5a0732b33481159413c8e74c91985092708b
 SHA512:
-  metadata.gz: e08f11b282afa711d2b25cff516780804d1647cb0b51960edcca2768ddefc289647f401b36839f17e9b0c4ad9c5e116219beb2eaacf3c8627e1bae572fa2b2e4
-  data.tar.gz: f4903d54e56315f32e43964d746d07a1b5c7ce45f2954286f1f285128268369dfeb0770ec22530a6256c35d8531551a1b09406a345ff257e3c6b7d5f3589dd2b
+  metadata.gz: 4afd8163e39836f303d037928e2c891dbe9528223ee2bdad1ec31bd0f9f22a708790e393aba63fe3eb1895e5176dc0e674c7e24e7dacfe704498e2b03d149290
+  data.tar.gz: 4b3dcae0a76b89bcbb2efa3db29352e0243a35547fa16489d967ceb918fcde4347e910e0a91c974f01c616c9037644c4cb3551d103c1148037d2a4ed97a1fa60

data/LICENSE

@@ -0,0 +1,22 @@
+The MIT License (MIT)
+
+Copyright (c) 2015 
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

data/README.md

@@ -0,0 +1,317 @@
+# patrun-ruby
+
+### A fast pattern matcher on Ruby object properties.
+
+Need to pick out an object based on a subset of its properties? Say you've got:
+
+```Ruby
+{ :x => 1          } -> A
+{ :x => 1, :y => 1 } -> B
+{ :x => 1, :y => 2 } -> C
+```
+
+Then patrun can give you the following results:
+
+```Ruby
+{ :x => 1 }      -> A
+{ :x => 2 }      -> no match
+{ :x => 1, :y => 1 } -> B
+{ :x => 1, :y => 2 } -> C
+{ :x => 2, :y => 2 } -> no match
+{ :y => 1 }      -> no match
+```
+
+It's basically _query-by-example_ for property sets.
+
+
+### Support
+
+If you're using this library, feel free to contact me on twitter if you have any questions! :) [@colmharte](http://twitter.com/colmharte)
+
+
+Current Version: 0.1.1
+
+Tested on: Ruby 2.0.0p481
+
+
+### Quick example
+
+Here's how you register some patterns, and then search for matches:
+
+```Ruby
+require('patrun')
+
+pm = Patrun.new()
+pm.add({:a => 1},'A').add({:b => 2},'B')
+
+# prints A
+puts pm.find({:a => 1})  
+
+# prints nil
+puts pm.find({:a => 2})
+
+# prints A, :b => 1 is ignored, it was never registered
+puts pm.find({:a => 1, :b => 1})
+
+# prints B, :c => 3 is ignored, it was never registered
+puts pm.find({:b => 2, :c => 3})
+```
+
+You're matching a subset, so your input can contain any number of other properties.
+
+
+## Install
+
+```sh
+gem install patrun
+```
+
+
+# The Why
+
+This module lets you build a simple decision tree so you can avoid
+writing _if_ statements. It tries to make the minimum number of
+comparisons necessary to pick out the most specific match.
+
+This is very useful for handling situations where you have lots of
+"cases", some of which have "sub-cases", and even "sub-sub-sub-cases".
+
+For example, here are some sales tax rules:
+
+   * default: no sales tax
+   * here's a list of countries with known rates: Ireland: 23%, UK: 20%, Germany: 19%, ...
+   * but wait, that's only standard rates, here's [the other rates](http://www.vatlive.com/vat-rates/european-vat-rates/eu-vat-rates/)
+   * Oh, and we also have the USA, where we need to worry about each state...
+
+Do this:
+
+```Ruby
+# queries return a Proc, in case there is some
+# really custom logic (and there is, see US, NY below)
+# in the normal case, just pass the rate back out with
+# an identity function
+# also record the rate for custom printing later
+I = Proc.new { | val |
+  rate = Proc.new {
+    val
+  }
+  rate
+}
+
+salestax = Patrun.new()
+salestax
+  .add({}, I.call(0.0) )
+  .add({ :country => 'IE' }, I.call(0.25) )
+  .add({ :country => 'UK' }, I.call(0.20) )
+  .add({ :country => 'DE' }, I.call(0.19) )
+  .add({ :country => 'IE', :type => 'reduced' }, I.call(0.135) )
+  .add({ :country => 'IE', :type => 'food' },    I.call(0.048) )
+  .add({ :country => 'UK', :type => 'food' },    I.call(0.0) )
+  .add({ :country => 'DE', type:'reduced' }, I.call(0.07) )
+  .add({ :country => 'US' }, I.call(0.0) ) # no federeal rate (yet!)
+  .add({ :country => 'US', :state => 'AL' }, I.call(0.04) )
+  .add({ :country => 'US', :state => 'AL', city:'Montgomery' }, I.call(0.10) )
+  .add({ :country => 'US', :state => 'NY' }, I.call(0.07) )
+
+under110 = Proc.new { | net |
+  net < 110 ? 0.0 : salestax.find( {:country => 'US', :state => 'NY'}).call(net)
+}
+
+salestax.add({ :country => 'US', :state => 'NY', :type => 'reduced' }, under110)
+
+puts "Default rate: #{salestax.find({}).call(99)}"
+
+puts "Standard rate in Ireland on E99: #{salestax.find({country:'IE'}).call(99)}"
+
+puts "Food rate in Ireland on E99:     #{salestax.find({country:'IE',type:'food'}).call(99)}"
+
+puts "Reduced rate in Germany on E99:  #{salestax.find({country:'IE',type:'reduced'}).call(99)}"
+
+puts "Standard rate in Alabama on $99: #{salestax.find({country:'US',state:'AL'}).call(99)}"
+
+puts "Standard rate in Montgomery, Alabama on $99: #{salestax.find({country:'US',state:'AL',city:'Montgomery'}).call(99)}"
+
+puts "Reduced rate in New York for clothes on $99: #{salestax.find({country:'US',state:'NY',type:'reduced'}).call(199)}"
+
+
+# prints:
+# Default rate: 0
+# Standard rate in Ireland on E99: 0.25
+# Food rate in Ireland on E99:     0.048
+# Reduced rate in Germany on E99:  0.135
+# Standard rate in Alabama on $99: 0.04
+# Standard rate in Montgomery, Alabama on $99: 0.1
+# Reduced rate in New York for clothes on $99: 0.0
+```
+
+You can take a look a the decision tree at any time:
+
+```Ruby
+
+# print out patterns, using a custom format function
+puts salestax.toString( Proc.new { | f | ":#{f.call(99)}"})
+
+
+# prints:
+-> :0.0
+city=Montgomery, country=US, state=AL -> :0.1
+country=IE -> :0.25
+country=IE, type=reduced -> :0.135
+country=IE, type=food -> :0.048
+country=UK -> :0.2
+country=UK, type=food -> :0.0
+country=DE -> :0.19
+country=DE, type=reduced -> :0.07
+country=US -> :0.0
+country=US, state=AL -> :0.04
+country=US, state=NY -> :0.07
+country=US, state=NY, type=reduced -> :0.0
+```
+
+
+# The Rules
+
+   * 1: More specific matches beat less specific matches. That is, more property values beat fewer.
+   * 2: Property names are checked in alphabetical order.
+
+And that's it.
+
+
+# Customization
+
+You can customize the way that data is stored. For example, you might want to add a constant property to each pattern.
+
+To do this, you provide a custom function when you create the _patrun_ object:
+
+```Ruby
+alwaysAddFoo = Patrun.new( Proc.new{ | pm, pat, data |
+  pat['foo'] = true
+})
+
+alwaysAddFoo.add( {:a => 1}, "bar" )
+
+alwaysAddFoo.find( {:a => 1} ) # nothing!
+alwaysAddFoo.find( {:a => 1, :foo => true} ) # == "bar"
+```
+
+Your custom function can also return a modifer function for found
+data, and optionally a modifier for removing data.
+
+Here's an example that modifies found data:
+
+```Ruby
+upperify = Patrun.new( Proc.new { | pm, pat, data |
+  Proc.new { | pm, pat, data |
+    data.to_s.upcase()
+  }
+})
+
+upperify.add( {:a => 1}, "bar" )
+
+upperify.find( {:a => 1} ) # BAR
+```
+
+Finally, here's an example that allows you to add multiple matches for a given pattern:
+
+```Ruby
+many = Patrun.new( Proc.new { | pm, pat, data |
+  items = pm.find(pat,true) || []
+  items.push(data)
+
+  {:find => Proc.new { | pm, args, data |
+      0 < items.length ? items : nil
+    },
+   :remove => Proc.new { | pm, args, data |
+      items.pop()
+      0 == items.length
+    }
+  }
+})
+
+many.add( {:a => 1}, 'A' )
+many.add( {:a => 1}, 'B' )
+many.add( {:b => 1}, 'C' )
+
+many.find( {:a => 1} )  # [ 'A', 'B' ]
+many.find( {:b => 1} ) # [ 'C' ]
+
+many.remove( {:a => 1} )
+many.find( {:a => 1} ) # [ 'A' ]
+
+many.remove( {:b => 1} )
+many.find( {:b => 1} ) # nil
+```
+
+
+# API
+
+## patrun( custom )
+
+Generates a new pattern matcher instance. Optionally provide a customisation Proc.
+
+
+## .add( {...pattern...}, object )
+
+Register a pattern, and the object that will be returned if an input
+matches.  Both keys and values are considered to be strings. Other
+types are converted to strings.
+
+## .find( {...subject...}[, exact] )
+
+Return the unique match for this subject, or nil if not found. The
+properties of the subject are matched against the patterns previously
+added, and the most specifc pattern wins. Unknown properties in the
+subject are ignored. You can optionally provide a second boolean
+parameter, _exact_. If true, then all properties of the subject must
+match.
+
+
+## .list( {...pattern-partial...}[, exact] )
+
+Return the list of registered patterns that contain this partial
+pattern. You can use wildcards for property values.  Omitted values
+are *not* equivalent to a wildcard of _"*"_, you must specify each
+property explicitly. You can optionally provide a second boolean
+parameter, _exact_. If true, then only those patterns matching the
+pattern-partial exactly are returned.
+
+```Ruby
+pm = Patrun.new()
+  .add({:a => 1, :b => 1},'B1')
+  .add({:a => 1, :b => 2},'B2')
+
+# finds nothing: []
+puts pm.list({:a => 1})
+
+# finds:
+# [ { match: { :a => '1', :b => '1' }, :data => 'B1' },
+#   { match: { :a => '1', :b => '2' }, :data => 'B2' } ]
+puts pm.list({:a => 1, :b => '*'})
+```
+
+If you provide no pattern argument at all, _list_ will list all patterns that have been added.
+```Ruby
+# finds everything
+puts pm.list()
+```
+
+## .remove( {...pattern...} )
+
+Remove this pattern, and it's object, from the matcher.
+
+
+## .toString( [proc][, tree] )
+
+Generate a string representation of the decision tree for debugging. Optionally provide a formatting Proc for objects.
+
+   * proc: format proc for data, optional
+   * tree: boolean flag, if true, print an indented tree rather than a list of patterns, default: false
+
+## .toJSON()
+
+Generate JSON representation of the tree.
+
+
+# Development
+
+From the Irish patr&uacute;n: [pattern](http://www.focloir.ie/en/dictionary/ei/pattern). Pronounced _pah-troon_.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: patrun
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.1
 platform: ruby
 authors:
 - Colm Harte
@@ -14,15 +14,24 @@ description: A fast pattern matcher on Ruby object properties.
 email: colm.harte@nearform.com
 executables: []
 extensions: []
-extra_rdoc_files: []
+extra_rdoc_files:
+- README.md
+- LICENSE
 files:
 - lib/patrun.rb
-homepage: http://rubygems.org/gems/patrun
+- README.md
+- LICENSE
+homepage: https://github.com/colmharte/patrun-ruby
 licenses:
 - MIT
 metadata: {}
 post_install_message: 
-rdoc_options: []
+rdoc_options:
+- --main
+- README.md
+- --title
+- Fast Pattern Matcher
+- --line-numbers
 require_paths:
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement