formula-es5

Browser support

Chrome, Safari, Firefox, Opera, IE9+

Installation

    npm install formula-es5

    or 

    jspm install npm:formula-es5

Usage

Some examples :

    var Formula = require('formula-es5');


    /**
    * A `resolver` is to determine how to resolve
    * a formula. It is the formula consumer.
    * 
    * It has to implement two methods :
    *   1. canResolveSymbol() - check whether a symbol in formula expression
    *                           is valid or not.
    *   2. resolveSymbol()    - resolve a symbol and return its value.
    */
    var resolver: {
        _allowedSymNames: new RegExp('^[a-zA-Z]+$'),
        
        canResolveSymbol: function (sym) {
            return this._allowedSymNames.test(sym);
        },
        
        /**
        * A self-resolvable method.
        * 
        * In the real world, resolveSymbol() usually 
        * get symbol value from somewhere else, e.g.
        * get an equity's real-time price from stock market.
        */
        resolveSymbol: function (sym) {
            var val = 0;

            for (var i = 0; i < sym.length; i++)
                val += sym.charCodeAt(i);

            return val;
        }
    };

    var newFormula = function (resolver) {
        var f = new Formula();
        f.addResolver(resolver);    // Add resolver.
        return f;
    };


    var f = newFormula(resolver);
    /**
    * Inside setExpression() it will call resolver.canResolveSymbol(symbol)
    * to check symbols `a` and `b` 's validity.
    */
    f.setExpression('a + b');   
    f.isValid();                // true
    f.error();                  // null
    /**
    * Inside evaluate() it will call resolver.resolveSymbol(symbol)
    * to get each symbol's value and evaluate the formula.
    */
    f.evaluate();               // 195 ( a(97) + b(98) )


    var f = newFormula(resolver);
    /**
    * Inside `Formula` class, `min` is the abbreviation of `Math.min`
    */
    f.setExpression('min(a,b,c)');
    f.isValid();                // true
    f.evaluate();               // 97 ( a(97) )


    var f = newFormula(resolver);
    f.setExpression('(3*4) - 2');
    f.isValid();                // true
    f.evaluate();               // 10


    var f = newFormula(resolver);
    f.setExpression('2 + (1,3)');
    f.isValid();                // false


    /**
    * For more examples, you can see file `test/test.js`.
    */

Public properties and methods :

    constructor: Formula


    /**
    * This is not public property,
    * just to list all abbreviations.
    */
    _fnAliases: {
        'power':    'Math.pow',
        'pow':      'Math.pow',
        'absolute': 'Math.abs',
        'abs':      'Math.abs',
        'log':      'Math.log',
        'min':      'Math.min',
        'minimum':  'Math.min',
        'max':      'Math.max',
        'maximum':  'Math.max'
        'pi':       'Math.PI'
    }


    /**
    * A `symResolver` is to determine how to resolve
    * a formula. It is the formula consumer.
    */
    addResolver: function (symResolver)


    getExpression: function ()


    setExpression: function (expr)


    /**
     * Resolves all symbols and aliases, 
     * evaluates the expression.
     *
     * @return A numeric value, or NaN.
     * @throws An exception if the expression is invalid.
     */
    evaluate: function ()


    /**
     * Returns whether this formula has any unresolved symbol(s).
     * @return {Boolean}
     */
    hasUnresolvedSymbols: function ()


    /**
    * Get all symbols.
    * @return {Array}
    */
    symbols: function ()


    /**
    * Get all resolved symbols.
    * @return {Array}
    */
    resolvedSymbols: function ()


    /**
    * Get all unresolved symbols.
    * @return {Array}
    */
    unresolvedSymbols: function ()


    /**
    * Set resolver for an existing symbol.
    */
    setResolver: function (symbol, resolver)


    /**
    * Whether formula expression is valid.
    * @return {Boolean}
    */
    isValid: function ()



    /**
    * Whether formula expression has error.
    * 
    *   1. If has error it will return error text.
    *   2. If no error but has unresolved symbols, it returns the 
    *      first unresolved symbol.
    *   3. If no error and all symbols are resolved, return Null.
    *
    * @return {String or Null}
    */
    error: function ()

Tests

    npm test