Rools – A pure ruby rules-engine

Rools is a rules engine for abstracting business logic and program-flow. It’s ideally suited to processing applications where the business logic undergoes frequent modification.

RubyForge

This documentation can be found at rools.rubyforge.org The project page can be found at rubyforge.org/projects/rools

Example

require ‘rools’ rules = Rools::RuleSet.new do rule ‘Hello?’ do parameter String consequence { puts “Hello, Rools!” } end end rules.assert ‘Heya’ > Hello, Rools!

You can also store your rules in a separate file, and pass a path to Rools::RuleSet#new instead of a block. e.g. require ‘rools’ rules = Rools::RuleSet.new ‘test/data/hello.rules’ rules.assert ‘heya’

Parameter

The parameter method accepts Constants and/or Symbols. Every constant in the list is called with :is_a? on the asserted object, while every symbol in the list is passed to :respond_to? on the asserted object. In other words:

parameter Person, :name, :occupation Is effectively the same as:

condition { object.is_a?(Person) && object.responds_to?(:name) && object.responds_to?(:occupation) } The parameter method is obviously preferred for it’s conciseness, and because the working set of rules can be optimized to only include for evaluation those rules whose parameters match the asserted object.

Condition

The condition method is used to evaluate the asserted object. You can have any number of conditions. Rools::DefaultParameterProc#method_missing is used so that you can refer to the asserted object by practically any lower_case_underscore name. Generally you’ll want to use names that make sense in the context of the Rule, and be consistent through-out the Rule. Here’s an example:

rule ‘Programmer’ do condition { person.occupation == ‘coder’ } consequence { puts “#person is a coder” } end Here’s an example of something you might want to avoid:

rule ‘Manager’ do condition { obj.occupation == ‘manager’ } consequence { puts “#manager is a manager” } end

Both examples are syntactically correct, but the first is easier to read.

Consequence

A consequence is a block of code that executes if the conditions evaluate to true. You can have one or more consequences. In the above examples we’re doing something simple such as just printing something to the string in the consequences. Usually the consequence is something that will actually change the state of the asserted object in some way however.

rule ‘User’ do parameter User, :failed_login_attempts condition { user.failed_login_attempts > 3 } consequence { user.lockout! } end Nevermind that this is application logic you’d probably keep in your domain model. The intent isn’t to show you best-practices here, only to make the point that consequences usually modify state.

Assert

What happens if in a consequence, you need to create other objects though? You can use the assert method in a consequence. Consider the following:

rule ‘Message is Referral?’ do parameter :subject, :body

condition { message.subject == ‘Sales Referral’ } condition { message.body =~ /^HowsdidsyoushearsaboutsbrandsX?/m }

consequence { assert Referral.new(message) } end rule ‘Referral is Large Account’ do parameter Referral

condition { referral.annual_sales_volume > 100_000_000 } consequence { referral.prioritize :high } end

The first rule asserted a new Referral object into the RuleSet. You could also assert into a completey different RuleSet however if you need to split them up to keep them manageable:

consequence { RuleSet.new(‘referral.rules’).assert Referral.new(message) }

Extend

Problem: You have a sequence of rules that depend on each other:

rule ‘Valid User’ do condition { user.valid? } condition { user.password.size > 6 } consequence { puts “#user is valid” } end

rule ‘Active User’ do condition { user.valid? } condition { user.password.size > 6 } condition { user.last_logon < 1.month.ago } condition do user.logins_for(:january).inject(0) do |sum, duration| sum += duration end > 5.minutes end

consequence { puts “#user is active” } end

rule ‘Administrative User’ do condition { user.valid? } condition { user.password.size > 6 } condition { user.last_logon < 1.month.ago } condition do user.logins_for(:january).inject(0) do |sum, duration| sum += duration end > 5.minutes end condition { user.admin? }

consequence { puts “#user is an admin” } end This chain of rules quickly becomes rather cumbersome. To help, you can use the extend -> with syntax to enable chaining and branching rules. The same example as above could also be written this way: (extend rule_name with new_rule_name)

rule ‘Valid User’ do condition { user.valid? } condition { user.password.size > 6 } consequence { puts “#user is valid” } end extend(‘Valid User’).with(‘Active User’) do condition { user.last_logon < 1.month.ago } condition do user.logins_for(:january).inject(0) do |sum, duration| sum += duration end > 5.minutes end consequence { puts “#user is active” } end extend(‘Active User’).with(‘Administrative User’) do condition { user.admin? } consequence { puts “#user is an admin” } end In this simplistic example, it saves 11 lines (about a third), but in more complex examples you could easily end up with half the code. The first example could perform up to 11 condition checks for a valid, active, admin user. Because the extend syntax defers adding the dependent rules to the working set until the extended rule evaluates to true, the extend syntax would do the same work with only 5 comparisons (less than half the work). For expensive operations, such as file operations, regular expressions, or database calls, the extend syntax is potentially several times faster than the “brute-force” method, and the difference only becomes greater the larger your RuleSet.

It’s important to remember that you can only extend rules within the same Rools::RuleSet.

You can also extend a target rule with several additional rules at once with a block:

extend(‘Active User’) do with ‘Administrative User’ do condition { user.admin? } consequence { puts “#user is an admin” } end with ‘Customer User’ do condition { user.customer? } consequence { puts “#user is a customer” } end end

Rule names are case-insensitive. It’s important to give good descriptive names to rules as not only does it make maintaining them much easier, but it also gives you better logging, and makes extend calls easier to follow.