= 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 http://rools.rubyforge.org
	The project page can be found at http://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 =~ /^How\sdid\syou\shear\sabout\sbrand\sX\?/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.