How to use NGinn rules engine

1. Required libraries

To use NGinn.RippleBoo engine in your application you need to add references to the following libraries:

• NGinn.RippleBoo


• Rhino.DSL.dll


• Boo.Lang.dll


• Boo.Lang.Compiler.dll


• NLog.dll

2. Invoking RippleBoo

The code below shows how to configure rule repository and how to execute some rules.

using System;
using System.Collections.Generic;
using NGinn.RippleBoo;

class TestMe
{
    private RuleRepository _repos;

    public TestMe()
    {
        _repos = new RuleRepository();
        _repos.BaseDirectory = "c:\\rules";
        _repos.ImportNamespaces.Add("System");
    }

    public void RunSomeRules()
    {
        Dictionary<string, object> variables = new Dictionary<string,object>();
        variables["Email"] = "my@email.com";
        variables["Timestamp"] = DateTime.Now;

        Dictionary<string, object> context = new Dictionary<string,object>();
        context["Output"] = Console.Output;

        _repos.EvaluateRules("some_rules.boo", variables, context);
    }
}

RuleRepository class stores common configuration properties for your rules and allows you to call rules stored as '*.boo' files in base directory. It compiles the rule scripts and caches them so subsequent evaluations are fast. If rule script changes, it will be automatically recompiled. You should create rule repository once and hold it as long as needed.

Rule evaluation is done in 'RunSomeRules' method. To execute rules you call RuleRepository.EvaluateRules, passing the rule file name and two dictionaries.
First one contains variables that can be referenced from rules through 'Variables' object. The second one contains 'context' object, they can be referenced from rules throug 'Context' object.

Example rule:

ruleset "SomeRules":
    rule "R1":
        when Variables.Email.EndsWith("mydomain.com")
        action:
            Context.Output.WriteLine("Email from my domain")
            

This rule references the 'Email' variable and the 'Output' context object. Please note that in rules you don't have to quote the variable names - it's because of Boo language's IQuackFu magic interface.
RuleRepository.EvaluateRules method is thread safe.

Rules engine improved

First attempts to use the RippleBoo rules engine in real software showed that version 0.1 wasn't very useful, so I had to prepare version 0.2.
First of all, the structure of rule definition was changed - now it's more descriptive:

rule "SPAM":
  label "Spam? - move to spam"
  when IS_SPAM()
  except_rule "Friendly_spam"
  action:
      MOVE_TO "Spam"
  else_rule "WORK"

What we have here:

• declaration of rule "SPAM"
• label - for documentation
• when - this is rule condition
  
• except_rule - this is the 'exception' rule - containing an exception for the rule condition. Our 'SPAM' rule will be fired when its condition is true and the exception does not fire
• action - executed when rule fires
• else_rule - successor when rule condition is not satisfied

You should read it like so: when IS_SPAM() returs true, move message to 'SPAM' folder, except for messages where "Friendly spam" rule applies. If IS_SPAM() returns false, do nothing but proceed to rule "WORK"
That's basically how Ripple Down Rules work. You should note that only one rule will be fired - the one with satisfied condition and no exceptions to apply. This can be a problem when you want to execute some code each time rule condition is satisfied, no matter if there are exceptions or not. In such case you can either put your code in rule condition, or use special 'side_effect' block:

rule "VERY_IMPORTANT":
   label "Important? - mark high priority"
   when __msg.From == "customer_care@mybank.com"
   side_effect:
       __msg.Priority = "High"

The 'side_effect' will be executed just after rule condition evals to true but BEFORE checking exception rules. In contrast, the 'action' block will be executed only when rule conditions eval to true AND no exceptions apply (no rule is fired when evaling exception subtree).


Here's an example rule definition file, containing simple email message processing rules. NGinn.RippleBoo engine allows you to declare your own 'local' variables and helper functions that can be used in rules:

#variable alias
__msg = Variables.Message

#helper function - check if message is spam
IS_SPAM = def() :
    return __msg.Subject.IndexOf("[--spam--]") >= 0

#helper - move message to specified folder
MOVE_TO = def(folder):
    Context.MessageDb.MoveMessage(__msg, folder)
    

ruleset "Email_default_rules":
    
    rule "SPAM":
        label "Spam? - move to spam"
        when IS_SPAM()
        except_rule "Friendly_spam"
        action:
            MOVE_TO "Spam"
        else_rule "WORK"
        
    rule "Friendly_spam":
        label "Interesting subject? - read!"
        when __msg.Subject.IndexOf("enlarge") >= 0
        action:
            MOVE_TO "Useful_spam"
        
    rule "WORK":
        label "Work? - move to WORK"
        when __msg.From.EndsWith("mycompany.com")
        action:
            MOVE_TO "Work"
        else_rule "VERY_IMPORTANT"
        
        
    rule "VERY_IMPORTANT":
        label "Important? - mark high priority"
        when __msg.From == "customer_care@mybank.com"
        side_effect:
            __msg.Priority = "High"

    

And here's a graphical representation of the ruleset defined above.



The picture is automatically generated from rule definition, using the GraphViz tool (useful, but very user-unfriendly, unix-style program).

Other features

What is important, we can define several rulesets in single file. First ruleset will be the default one, but RippleBoo allows you to call also the other rulesets.
You can also call other rulesets from your actions, by executing

goto_ruleset "another ruleset"

Think of secondary rulesets as sub-procedures that can be called from the main procedure.

There is also an option to execute rules from external file

goto_file "another_rules.boo"

This will execute rules from another file.
Remember, you call goto_ruleset or goto_file from an action block inside some rule. Only one action will be executed, so you don't need to worry about continuation after goto - because there will be no continuation. Simply - there is no return from goto_ruleset or goto_file.



OK, I'll shed some light on using RippleBoo in your programs in next posts, because now I'm getting sick of code formatting at this blog engine. Does anyone know why it sucks so much and what can I do so it stops messing with my html?