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:

{ :x => 1          } -> A
{ :x => 1, :y => 1 } -> B
{ :x => 1, :y => 2 } -> C

Then patrun can give you the following results:

{ :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

Current Version: 0.1.3

Tested on: Ruby 2.0.0p481

Quick example

Here’s how you register some patterns, and then search for matches:

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

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:

Do this:

# 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:

# 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

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:

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:

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:

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.

pm = Patrun.new()
  .add({:a => 1, :b => 1},'B1')
  .add({:a => 1, :b => 2},'B2')

# finds:
# [ { match: { :a => '1', :b => '1' }, :data => 'B1' },
#   { match: { :a => '1', :b => '2' }, :data => 'B2' } ]
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 => '*'})

# finds nothing: []
puts pm.list({:c => 1})

If you provide no pattern argument at all, list will list all patterns that have been added.

# 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.

.toJSON()

Generate JSON representation of the tree.

Development

From the Irish patrún: pattern. Pronounced pah-troon.