Occamsrazor finds the function (or the functions) that matches a list of arguments. It can be be used to write event systems, or to make an application extensible.
Let's say you have some objects:
var shape1 = radius: 10;var shape2 = radius: 5;var shape3 = width: 5;
Every object represents a different shape. You need to calculate the area of these objects.
varreturn circleradius * circleradius * MathPI;;varreturn squarewidth * squarewidth;;
The problem is: how can you pick the right function for each shape ?
This is where occamsrazor enter. First of all you need some validator. A validator will help to identify a "shape":
var validator = require'occamsrazor-validator';var has_radius = validatorhas'radius';var has_width = validatorhas'width';
A validator is a function that runs over an argument and returns a positive score if the argument matches, or null if it doesn't. You can find further explanations here.
These two validators match objects with a "radius" or "width" attribute respectively. Now I create a special function that wraps the two area functions defined previously. I call it "function registry":
var shapeArea = occamsrazor;
Then add the two functions to it:
shapeAreaaddhas_radius circleArea;shapeAreaaddhas_width squareArea;
The validators (has_radius and has_width) are used internally to pick the right function. If you prefer you can chain the "add" methods together:
var shapeArea = occamsrazoraddhas_radius circleAreaaddhas_width squareArea;
From now on if you need to calculate the area you will do:
var area = shapeAreashape1;
Maybe you are thinking, why doing this while you can just extend an object using its prototype or copying attributes and methods. Well, you just can't change a third party script, for example. You may also want to provide a way to extend your code without changing it.
Working in this way promotes the open/close principle (https://en.wikipedia.org/wiki/Open/closed_principle) because you can add functionalities without changing the original code.
Validators with different scores allow to choose different functions. Now I add another type of shape, a rectangle:
var shape4 = width: 5 height: 6;
A rectangle has both width and height so you will define a more specific validator:
var has_width_and_height = validator // this scores 1has'width' // this scores 2has'height'; // this scores 3
Every time you extend a validator, you get a new one so you could instead extend the previous one:
var has_width_and_height = has_widthhas'height'; // score 3
But pay attention! this is different from defining a validator like this:
var wrong_has_width_and_height = validatorhas'width' 'height'; // score 2
The last one has the same specificity of has_width so occamsrazor won't be able to decide what function to use!
The score of this validator gets bigger every time is chained with another one:
var is_parallelepiped = has_width_and_heighthas'depth';
shape4 fits the description of a rectangle and a square (they both has a width) but the has_width_and_height validator is more specific. Using this validator you can add another function:
varreturn rectanglewidth * rectangleheight;;shapeAreaaddhas_width_and_height rectangleArea;
When you call the registry it will execute the most specific function (based on the validator with the highest score):
var area = shapeAreashape4; // rectangleMath(shape4)
If the arguments (shape4 in the previous example) matches with more than one function with the same score, it will throw an exception.
In the previous example you used a validator to match an argument, in reality you can match any number of arguments. This one doesn't try to match any argument.
shapeAreaaddreturn 'I can\'t calculate the area';;
This one matches two:
shapeAreaaddhas_width has_width// combining the areas of two squaresreturn shape1width * shape1width + shape2width * shape2width;;
You might wonder how the system decide to match a function or another. Well, all the respective scores are put in an array and compared. For example:
// this has the lowest score, it doesn't match any argument1 >2 > 11 1 > 11 1 > 1 02 1 > 1 9 9 9
In the "add" method you specify the arguments you want to match but you are not forced to validate all arguments passed to the function.
shapeAreaaddhas_width_and_height// shape argument is validated (it must have a width and an height)// name is not validatedconsole.logname + ' is a rectangle';;
If you want to delete a function you can use the "remove" method:
The remove method is chainable:
You can also remove all functions with:
Occamsrazor works with constructor functions too! you just need to wrap the constructor function inside a special wrapper:
var Shape = occamsrazoraddhas_width occamsrazorwrapConstructorthiswidth = objwidth;addhas_radius occamsrazorwrapConstructorthisradius = objradius;;var shape = width: 5;
The prototype chain and "constructor" attribute will work as expected.
Validators can be expressed in a shorter way as documented here
var shapeArea = occamsrazoraddradius: undefined circleAreaaddwidth: undefined squareArea;
The shortcuts provide a way to match complex object with a very simple syntax. They have a fixed score:
var registry = occamsrazoradd'select' center: x: undefined y: undefined// does something with the point;registry'point' center: x: 3 y: 2; // this matches!
That is the equivalent of the less concise:
var validator = require'occamsrazor-validator';var is_select = validatormatch'select';var is_point = validatormatchcenter: x: undefined y: undefined ;var registry = occamsrazoraddis_select is_point// does something with the point;registry'point' center: x: 3 y: 2; // this matches!
So far you have used occamsrazor to get the most specific function (the one with the highest specificity score). You can also get all functions matching the validators, no matter what the score is:
var shapeCalculations = occamsrazoraddhas_widthreturn 'Perimeter is ' + shapewidth * 4;addhas_widthreturn 'Area is ' + shapewidth * shapewidth;addhas_radiusreturn 'Perimeter is ' + 2 * MathPI * shaperadius;addhas_radiusreturn 'Area is ' + MathPI * shaperadius * shaperadius;;var results = shapeCalculationsallwidth: 10;// ['Perimeter is 40', 'Area is 100']
This will return an array containing all the results.
Using its matching capabilities and the expressiveness of the shortcut syntax, you can use occamsrazor as an event system:
var pubsub = occamsrazor;pubsubon'selected' has_radius// do something with the shape;pubsubtrigger'selected' radius: 10;
".on" attaches an event handler and ".trigger" runs all the event handlers matching its arguments. In reality ".on" is an alias of ".add" and ".trigger" is a slightly modified version of .all (it doesn't return the result of the functions and it defers the execution using setImmediate). Of course you can remove the event handler using ".off" (an alias of remove). If you need to handle the event only once there is a special method ".one":
pubsubone"selected" has_radiusconsole.log'This is executed only once';;
Usually you'll need to have an event handler attached (with .on) BEFORE triggering it. Some events represent a state change and it is very convenient keeping them published (imagine something like the "ready" jQuery event for example). You can publish an event permanently using "stick". This method works like trigger but allows to keep the arguments published, so any new event handler fires immediately:
pubsubon"selected" has_radiusconsole.log'Circle is selected and the radius is ' circleradius;;pubsubstick"selected" radius: 10;pubsubon"selected" has_radiusconsole.log'This will be fired as well!';;
If you need to remove functions you added, without affecting others, you can create a new namespace:
var namespace = pubsubnamespace;namespaceon'selected' has_radiusconsole.log'I have added a function using a namespace';;// the following are exactly the samepubsubtrigger'selected' radius: 10;namespacetrigger'selected' radius: 10;namespaceremove; // this removes only the function abovepubsubremove; // this removes all functions
Some methods retain the current context (this). They are: all/trigger, stick, adapt (that is a version of the object invoked without any method). This allows you to call them as methods or using call/apply.
This helper function is useful to group functions in registries:
var mathregistry = occamsrazorregistry'math'getArea = mathregistry'area_functions';
If a registry doesn't exist it is created and returned by the registry function. If the function registry required doesn't exist it is created and returned too. If you don't specify a specific registry you'll get the "default" registry:
var registry = occamsrazorregistrygetArea = registry'area_functions';
Occamsrazor is a commonjs module
var occamsrazor = require'occamsrazor';
var funcs = occamsrazoradapters;
var funcs = occamsrazor;
funcsarg1 arg2 ;
It is equivalent to:
funcsadaptarg1 arg2 ;
it takes 0 or more arguments. It calls the most specific function with the given arguments and returns its result. It retains the context (this). If more than one function matches with the same score it throws an exception.
funcsallarg1 arg2 ;
it takes 0 or more arguments. It calls all functions that matches, with the given arguments. It retains the context (this). It returns the results of all functions in an array.
funcstriggerarg1 arg2 ;
it takes 0 or more arguments. It calls all functions that matches, with the given arguments. It retains the context (this). It doesn't return the results as it's execution is deferred (using setImmediate).
funcsstickarg1 arg2 ;
It works the same as trigger, the arguments (including the current context "this") are stored forever. When an new function is added (using "add", "on" or "one"), it is executed immediatly (if it matches).
funcsaddfunc;funcsaddvalidator func;funcsaddvalidator validator validator func;
Add a function and 0 or more validators to the function registry. The function is always the last argument.
It returns the function registry, or the namespaced function registry (this method can be chained). The validator will be converted automatically to a function using validator.match
The same as .add but the function will be execute only once and them removed.
funcsremove; // delete all functions
Delete one or all functions from the function registry. If it is called on a namespaced function registry, it removes only the functions added with through that namespace. It returns the function registry, or the namespaced function registry (this method can be chained).
It returns the number of functions in the function registry.
funcs1mergefuncs2 funcs3 ;
It returns a new function registry merging all functions of itself and the input function registries. Without arguments is equivalent to clone the function registry.
var proxy = funcsnamespacename;
It returns a namespaced function registry. This is mostly equivalent to the original function registry (you can't call it like a function though, you can use the "adapt" method). Every function added through the this object get marked and can get removed easily using remove:
funcsadd; // this won't be touchednamespaceadd; // this will be removednamespaceremove; // this will be removed
The name is optional, a random string is used if not defined. You just have to keep the reference.
Create a registry with a specific name (a registry of registries!!!) in the global namespace (window or global). You can use it to get a function registry.
This is created if it doesn't exist.
It transform a constructor function in a simple function that you can call without using "new"
The name of the library is taken from this philosophical principle: Occam's Razor: This principle is often summarized as "other things being equal, a simpler explanation is better than a more complex one." http://en.wikipedia.org/wiki/Occam's_razor
Ok this name can be a little pretentious but I think it can effectively describe a library capable to find the most appropriate answer (function in this case) from a series of assumptions (validators).