Getting started with nools

What is nools?

Nools is a rete based rules engine written entirely in javascript, with a target platform of node.js.
Nools was written for Pollenware to allow them to status offers in their market clearing events in a more dynamic way.

Getting Started

To install nools run

npm install nools

Or

git clone git@github.com:Pollenware/nools.git

To run the tests

make test

To run the benchmarks

make benchmarks

Terms

First lets start with a few terms that are used in nools.

• rule - A collection of constraints that must be satisfied for in order for a action to occur.
• action - The code that will execute when a all of a rule's constraints have been satisfied.
• fact - An object/item inserted into a session that the rule's constraints match against.
• flow - This is container for rules that will be executed, you can think of it as a rule book.
• session - This is an "instance" of a flow used to match facts. Sessions are obtained from a flow.

Writing rules

Nools includes a parser to parse nools files into a flow.
Lets look at an example

//Define our object classes, you can
//also declare these outside of the nools
//file by passing them into the compile method
define Fibonacci {
    value:-1,
    sequence:null
}
define Result {
    value : -1
}

rule Recurse {
    priority:1,
    when {
        //you can use not or or methods in here
        not(f : Fibonacci f.sequence == 1);
        //f1 is how you can reference the fact else where
        f1 : Fibonacci f1.sequence != 1;
    }
    then {
        assert(new Fibonacci({sequence : f1.sequence - 1}));
    }
}

rule Bootstrap {
   when {
       f : Fibonacci f.value == -1 && (f.sequence == 1 || f.sequence == 2);
   }
   then{
       modify(f, function(){
           this.value = 1;
       });
   }
}

rule Calculate {
    when {
        f1 : Fibonacci f1.value != -1 {sequence : s1};
        //here we define constraints along with a hash so you can reference sequence
        //as s2 else where
        f2 : Fibonacci f2.value != -1 && f2.sequence == s1 + 1 {sequence:s2};
        f3 : Fibonacci f3.value == -1 && f3.sequence == s2 + 1;
        r : Result
    }
    then {
        modify(f3, function(){
            this.value = r.result = f1.value + f2.value;
        });
        retract(f1);
    }
}

Defining Objects

In the above flow we define two classes Fibonacci and Result Both of these classes can be referenced by name throughout the file you can also access them by through the flow by calling getDefined.
In the nools language any valid javascript hash can be put inside of the define block, however if you define a constructor property then that will override the default constructor
For example we could change Fibonacci to to accept a sequence and value directly

define Fibonacci{
   constructor : function(sequence, value){
       this.sequence = sequence || -1;
       this.value = value || -1;
   }
}

You could then use the new constructor in your rules

var fib = new Fibonacci(10, 1);

Rule Definition

The rules Recurse, Bootstrap and Calculate use the nool rule syntax

rule <name> {
   when {<constraints>}
   then {<action>}
}

Lets look at the Recurse rule a little closer.

//Define a rule recurse
rule Recurse {
    //Give it a priority. The priority is 1 which is above all
    //other rules as the default priority/salience is 0
    priority:1,
    //Our LHS when block
    when {
        //you can use not or or methods in here
        //give the fact an alias of f and we checking that there is
        //NOT a Fibonacci object with a sequence of 1
        not(f : Fibonacci f.sequence == 1);

        //look for a Fibonacci object who's sequence does not equal 1
        f1 : Fibonacci f1.sequence != 1;
    }
    then {
        //assert a new fact into the engine
        assert(new Fibonacci({sequence : f1.sequence - 1}));
    }
}

Note In the when block each constraint must end with a ;

But my action is async

The actions also support async actions through a next(err?) call.

rule Recurse {
    priority:1,
    when {
        not(f : Fibonacci f.sequence == 1);
        f1 : Fibonacci f1.sequence != 1;
    }
    then {
        process.nextTick(function(){
           assert(new Fibonacci({sequence : f1.sequence - 1}));
           next();
        });
    }
}

Note if next is called with an argument then it will be assumed to be an error and the session execution will stop and an error will be passed into the callback.

Defining Helper Functions

Nools also allows the definition of helper functions, the function can be any valid javascript.

function subtract(a, b){
   return a, b;
}

function add(a, b){
   return a + b;
}

function sum(){
   var arr = Array.prototype.slice.call(arguments);
   var sum = 0;
   arr.forEach(function(a){sum += 0});
   return sum;
}

You can reference the methods in your actions or within other defined functions.

Working With Flows

The flow object is the container for all rules engines, a flow is created once and you can get multiple sessions from the flow.
To get a flow for the above fibonacci rules

//compile the file into a flow
var flow = nools.compile(__dirname + "/fibonacci.nools");

//Get defined classes
var Fibonacci = flow.getDefined("Fibonacci"), 
    Result = flow.getDefined("Result");

Sessions

The flow object is simply a conatainer for rules. To run the engine you need to obtain a session.

var r1 = new Result(),
    //Get a new session inserting a new Fibonacci object and a result to gather the
    //final number
    session1 = flow.getSession(new Fibonacci({sequence:10}), r1),
    s1 = +(new Date());
//call match to execute the engine
session1.match(function(err){
   if(err){
       console.error(err);
   }else{
      console.log("%d [%dms]", r1.result, +(new Date()) - s1);
      //cleanup the session
      session1.dispose();
   }
});

Session Events

Then session object also emits different events

• fire - emitted when a new rule is fired. The event is emitted with the name of the rule fired and associated facts.
• assert - emitted when a new fact is asserted
• retract - emitted when a fact is retracted(removed) from the session
• modify - emitted when a fact is modified

Wrap Up

I hope this was a good introduction into nools for more information visit :

• github page
• nools webpage.