rools 0.1.3

data/CHANGELOG

@@ -0,0 +1,9 @@
+- 0.1.1
+	Added RuleConsequenceError
+	
+- 0.1.2
+	Added RAKEFILE, README, CHANGELOG
+	
+- 0.1.3
+	Finished most documentation
+	Tweaked the rakefile

data/RAKEFILE

@@ -0,0 +1,67 @@
+require 'rubygems'
+require 'rake'
+require 'rake/rdoctask'
+require 'rake/gempackagetask'
+require 'rake/contrib/rubyforgepublisher'
+require 'pscp'
+
+PACKAGE_VERSION = '0.1.3'
+
+PACKAGE_FILES = FileList[
+  'README',
+  'CHANGELOG',
+  'RAKEFILE',
+  'lib/rools.rb',
+  'lib/**/*.rb'
+].to_a
+
+PROJECT = 'rools'
+
+ENV['RUBYFORGE_USER'] = "ssmoot@rubyforge.org"
+ENV['RUBYFORGE_PROJECT'] = "/var/www/gforge-projects/#{PROJECT}"
+
+desc 'Release Files'
+task :default => [:rdoc, :gem]
+
+# Generate the RDoc documentation
+rd = Rake::RDocTask.new do |rdoc|
+  rdoc.rdoc_dir = 'doc'
+  rdoc.title = 'Rools -- A Pure Ruby Rules Engine'
+  rdoc.options << '--line-numbers --inline-source --main README'
+  rdoc.rdoc_files.include(PACKAGE_FILES)
+end
+
+gem_spec = Gem::Specification.new do |s|
+  s.platform = Gem::Platform::RUBY
+  s.name = PROJECT
+  s.summary = "A Rules Engine written in Ruby"
+  s.description = "Can be used for program-flow, ideally suited to processing applications"
+  s.version = PACKAGE_VERSION
+  
+  s.authors = 'Sam Smoot', 'Scott Bauer'
+  s.email = 'ssmoot@gmail.com; bauer.mail@gmail.com'
+  s.rubyforge_project = PROJECT
+  s.homepage = 'http://substantiality.net'
+  
+  s.files = PACKAGE_FILES
+  
+  s.require_path = 'lib'
+  s.requirements << 'none'
+  s.autorequire = 'rools'
+  
+  s.has_rdoc = true
+  s.rdoc_options << '--line-numbers' << '--inline-source' << '--main' << 'README'
+  s.extra_rdoc_files = rd.rdoc_files.reject { |fn| fn =~ /\.rb$/ }.to_a
+end
+
+Rake::GemPackageTask.new(gem_spec) do |p|
+  p.gem_spec = gem_spec
+  p.need_tar = true
+  p.need_zip = true
+end
+
+desc "Publish RDOC to RubyForge"
+task :rubyforge => [:rdoc, :gem] do
+  Rake::SshDirPublisher.new(ENV['RUBYFORGE_USER'], ENV['RUBYFORGE_PROJECT'], 'doc').upload
+  Rake::SshFilePublisher.new(ENV['RUBYFORGE_USER'], ENV['RUBYFORGE_PROJECT'], 'pkg', "#{PROJECT}-#{PACKAGE_VERSION}.gem").upload  
+end

data/README

@@ -0,0 +1,179 @@
+= 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.
+
+== Example
+
+	require 'rools'
+	
+	rules = Rools::RuleSet.new do
+		
+		rule 'Is it a String?' do
+			parameter String
+			consequence { puts "Yes, it's a String" }
+		end
+		
+		rule 'Is it a country?' do
+			condition { Country.find_all.collect { |c| c.name }.include?(string) }
+			consequence { puts "Yes, #{string} is in the country list"}
+		end
+	end
+	
+	rules.assert 'Japan'
+	
+	> Yes, it's a String
+	> Yes, Japan is in the country list
+	
+You can also store your rules in a seperate file, and pass a path to Rools::RuleSet#new instead of a block. e.g.
+	
+	require 'rools'
+	
+	rules = Rools::RuleSet.new 'countries.rules'
+	rules.assert 'Japan'
+	
+== 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 (to-do), 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.

data/lib/rools.rb

@@ -0,0 +1,5 @@
+require 'rools/rule_set'
+
+# Test Documentation
+module Rools
+end

data/lib/rools/default_parameter_proc.rb

@@ -0,0 +1,51 @@
+module Rools
+  
+  # The DefaultParameterProc binds to a Rule and
+  # is allows the block to use method_missing to
+  # refer to the asserted object.
+  class DefaultParameterProc
+    
+    # Determines whether a method is vital to the functionality
+    # of the class.
+    def self.is_vital(method)
+      return method =~ /__(.+)__|method_missing|instance_eval/
+    end
+
+    # Removes unnecessary methods from the class to minimize
+    # name collisions with method_missing.      
+    for method in instance_methods
+      undef_method(method) unless is_vital(method)
+    end
+    
+    # The "rule" parameter must respond to an :assert method.
+    # The "b" parameter is a block that will be rebound to this
+    # instance.
+    def initialize(rule, b)
+      raise ArgumentError.new('The "rule" parameter must respond to an :assert method') unless rule.respond_to?(:assert)
+      @rule = rule
+      @proc = b
+      @working_object = nil
+    end
+    
+    # Call the bound block and set the working object so that it
+    # can be referred to by method_missing
+    def call(obj)
+      @working_object = obj
+      status = instance_eval(&@proc)
+      @working_object = nil
+      return status
+    end
+    
+    # Assert a new object up the composition-chain into the current RuleSet
+    def assert(obj)
+      @rule.assert(obj)
+    end
+    
+    # Parameterless method calls by the attached block are assumed to
+    # be references to the working object
+    def method_missing(sym, *args)
+      return @working_object if @working_object && args.size == 0
+    end
+    
+  end
+end

data/lib/rools/errors.rb

@@ -0,0 +1,27 @@
+module Rools
+
+  class RuleError < StandardError
+      attr_reader :rule, :inner_error
+      
+      # Pass the Rools::Rule that caused the error, and an optional inner_error
+      def initialize(rule, inner_error = nil)    
+        @rule = rule
+        @inner_error = inner_error      
+      end
+      
+      # returns the name of the associated Rools::Rule, and the message of the inner_error
+      def to_s
+        "#{@rule.name}\n#{@inner_error.to_s}"
+      end
+      
+  end
+  
+  # See: Rools::RuleError (RuleCheckError is only a default derivation)
+  class RuleCheckError < RuleError
+  end
+
+  # See: Rools::RuleError (RuleConsequenceError is only a default derivation)
+  class RuleConsequenceError < RuleError
+  end
+  
+end

data/lib/rools/rule.rb

@@ -0,0 +1,107 @@
+require 'rools/errors'
+require 'rools/default_parameter_proc'
+
+module Rools
+  class Rule
+    attr_reader :name
+    
+    # A Rule requires a Rools::RuleSet, a name, and an associated block
+    # which will be executed at initialization
+    def initialize(rule_set, name, b)
+      @rule_set = rule_set
+      @name = name
+      
+      @conditions = []
+      @consequences = []
+      @parameters = []
+      
+      instance_eval(&b)
+    end
+    
+    # Adds a condition to the Rule.
+    # For readability, it might be preferrable to use a
+    # new condition for every evaluation when possible.
+    # ==Example
+    #   condition { person.name == 'Fred' }
+    #   condition { person.age > 18 }
+    # As opposed to:
+    #   condition { person.name == 'Fred' && person.age > 18 }
+    def condition(&b)
+      @conditions << DefaultParameterProc.new(self, b)
+    end
+    
+    # Adds a consequence to the Rule
+    # ==Example
+    #   consequence { user.failed_logins += 1; user.save! }
+    def consequence(&b)
+      @consequences << DefaultParameterProc.new(self, b)
+    end
+    
+    # Sets the parameters of the Rule
+    # ==Example
+    #   parameters Person, :name, :occupation
+    # The arguments passed are evaluated with :is_a? for each
+    # constant-name passed, and :responds_to? for each symbol.
+    # So the above example would be the same as:
+    #   obj.is_a?(Person) &&
+    #     obj.responds_to?(:name) &&
+    #     obj.responds_to?(:occupation)
+    # You can pass any combination of symbols or constants.
+    # You might want to refrain from referencing constants to
+    # aid in "duck-typing", or you might want to use parameters such as:
+    #   parameters Person, Employee, :department
+    # To verify that the asserted object is an Employee, that inherits from
+    # Person, and responds to :department
+    def parameters(*matches)
+      @parameters += matches
+    end
+    
+    # parameters is aliased to aid in readability if you decide
+    # to pass only one parameter.
+    alias :parameter :parameters
+    
+    # Checks to see if this Rule's parameters match the asserted object
+    def parameters_match?(obj)
+      @parameters.each do |p|
+        if p.is_a?(Symbol)
+          return false unless obj.respond_to?(p)
+        else
+          return false unless obj.is_a?(p)
+        end
+      end
+      
+      return true
+    end
+    
+    # Checks to see if this Rule's conditions match the asserted object
+    # Any StandardErrors are caught and wrapped in RuleCheckErrors, then raised.
+    def conditions_match?(obj)
+      begin
+        @conditions.each { |c| return false unless c.call(obj) }
+      rescue StandardError => e
+        raise RuleCheckError.new(self, e)
+      end
+      
+      return true
+    end
+    
+    # Calls Rools::RuleSet#assert in the bound working-set
+    def assert(obj)
+      @rule_set.assert(obj)
+    end
+    
+    # Execute each consequence.
+    # Any StandardErrors are caught and wrapped in Rools::RuleConsequenceError,
+    # then raised to break out of the current assertion.
+    def call(obj)
+      begin
+        @consequences.each do |c|
+          c.call(obj)
+        end
+      rescue StandardError => e
+        # discontinue the Rools::RuleSet#assert if any consequence fails
+        raise RuleConsequenceError.new(rule, e)
+      end
+    end
+  end
+end

data/lib/rools/rule_set.rb

@@ -0,0 +1,113 @@
+require 'rools/errors'
+require 'rools/rule'
+
+module Rools
+  class RuleSet
+    # You can pass a set of Rools::Rules with a block parameter,
+    # or you can pass a file-path to evaluate.
+    def initialize(file = nil, &b)
+      
+      @rules = {}
+      @dependencies = {}
+      
+      if block_given?
+        instance_eval(&b)
+      else
+        instance_eval(File::open(file).read)
+      end
+    end		
+    
+    # rule creates a Rools::Rule. Make sure to use a descriptive name or symbol.
+    # For the purposes of extending Rules, all names are converted to
+    # strings and downcased.
+    # ==Example
+    #   rule 'ruby is the best' do
+    #     condition { language.name.downcase == 'ruby' }
+    #     consequence { "#{language.name} is the best!" }
+    #   end
+    def rule(name, &b)
+      name.to_s.downcase!
+      @rules[name] = Rule.new(self, name, b)
+    end
+    
+    # Use in conjunction with Rools::RuleSet#with to create a Rools::Rule dependent on
+    # another. Dependencies are created through names (converted to
+    # strings and downcased), so lax naming can get you into trouble with
+    # creating dependencies or overwriting rules you didn't mean to.
+    def extend(name, &b)
+      name.to_s.downcase!
+      @extend_rule_name = name
+      instance_eval(&b) if block_given?
+      return self
+    end
+    
+    # Used in conjunction with Rools::RuleSet#extend to create a dependent Rools::Rule
+    # ==Example
+    #   extend('ruby is the best').with('ruby rules the world') do
+    #     condition { language.age > 15 }
+    #     consequence { "In the year 2008 Ruby conquered the known universe" }
+    #   end
+    def with(name, &b)
+      name.to_s.downcase!
+       (@dependencies[@extend_rule_name] ||= []) << Rule.new(self, name, b)
+    end
+    
+    # Used to create a working-set of rules for an object, and evaluate it
+    # against them.
+    def assert(obj)
+      
+      # create a working-set of all parameter-matching, non-dependent rules
+      available_rules = @rules.values.select { |rule| rule.parameters_match?(obj) }
+      
+      begin
+        
+        # loop through the available_rules, evaluating each one,
+        # until there are no more matching rules available
+        begin # loop
+          
+          # the loop condition is reset to break by default after every iteration
+          matches = false
+          
+          available_rules.each do |rule|
+            # RuleCheckErrors are caught and swallowed and the rule that
+            # raised the error is removed from the working-set.
+            begin
+              if rule.conditions_match?(obj)
+                matches = true
+                
+                # remove the rule from the working-set so it's not re-evaluated
+                available_rules.delete(rule)
+                
+                # find all parameter-matching dependencies of this rule and
+                # add them to the working-set.
+                if @dependencies.has_key?(rule.name)
+                  available_rules += @dependencies[rule.name].select do |dependency|
+                    dependency.parameters_match?(obj)
+                  end
+                end
+                
+                # execute this rule
+                rule.call(obj)
+                
+                # break the current iteration and start back from the first rule defined.
+                break
+              end # if rule.conditions_match?(obj)
+              
+            rescue RuleCheckError => e
+              # log da error or sumpin
+              available_rules.delete(e.rule)
+            end # begin/rescue
+            
+          end # available_rules.each
+          
+        end while(matches)
+        
+      rescue RuleConsequenceError => rce
+        # RuleConsequenceErrors are allowed to break out of the current assertion,
+        # then the inner error is bubbled-up to the asserting code.
+        raise rce.inner_error
+      end
+    end # def assert
+    
+  end # class RuleSet
+end # module Rools

metadata

@@ -0,0 +1,58 @@
+!ruby/object:Gem::Specification 
+rubygems_version: 0.8.11
+specification_version: 1
+name: rools
+version: !ruby/object:Gem::Version 
+  version: 0.1.3
+date: 2005-12-12 00:00:00 -06:00
+summary: A Rules Engine written in Ruby
+require_paths: 
+- lib
+email: ssmoot@gmail.com; bauer.mail@gmail.com
+homepage: http://substantiality.net
+rubyforge_project: rools
+description: Can be used for program-flow, ideally suited to processing applications
+autorequire: rools
+default_executable: 
+bindir: bin
+has_rdoc: true
+required_ruby_version: !ruby/object:Gem::Version::Requirement 
+  requirements: 
+  - - ">"
+    - !ruby/object:Gem::Version 
+      version: 0.0.0
+  version: 
+platform: ruby
+signing_key: 
+cert_chain: 
+authors: 
+- Sam Smoot
+- Scott Bauer
+files: 
+- README
+- CHANGELOG
+- RAKEFILE
+- lib/rools.rb
+- lib/rools/default_parameter_proc.rb
+- lib/rools/errors.rb
+- lib/rools/rule.rb
+- lib/rools/rule_set.rb
+test_files: []
+
+rdoc_options: 
+- --line-numbers
+- --inline-source
+- --main
+- README
+extra_rdoc_files: 
+- README
+- CHANGELOG
+- RAKEFILE
+executables: []
+
+extensions: []
+
+requirements: 
+- none
+dependencies: []
+