add extjs 6.0.1 sources

[extjs.git] / extjs / packages / core / src / app / bind / Formula.js

/**\r
 * This class manages a formula defined for an `Ext.app.ViewModel`.\r
 *\r
 * ## Formula Basics\r
 *\r
 * Formulas in a `ViewModel` can be defined as simply as just a function:\r
 *\r
 *      formulas: {\r
 *          xy: function (get) { return get('x') * get('y'); }\r
 *      }\r
 *\r
 * When you need to be more explicit, "xy" can become an object. The following means the\r
 * same thing as above:\r
 *\r
 *      formulas: {\r
 *          xy: {\r
 *              get: function (get) { return get('x') * get('y'); }\r
 *          }\r
 *      }\r
 *\r
 * ### Data Dependencies\r
 *\r
 * One of the important aspects of a `ViewModel` is notification of change. In order to\r
 * manage this, a `ViewModel` *must* know the dependencies between data. In the above case\r
 * this is accomplished by **parsing the text of the function**. While this is convenient\r
 * and reduces the maintenance/risk that would come from explicitly listing dependencies\r
 * separately, there are some rules to be aware of:\r
 *\r
 *   * All dependencies are resolved by matching the binding statements in the getter function.\r
 *   * If you need to use these values in other ways, cache them as a `var` (following\r
 *     the first rule to capture the value) and use that `var`.\r
 *\r
 * In the above formulas, the "xy" formula depends on "x" and "y" in the `ViewModel`. As\r
 * these values change, the formula is called to produce the correct value for "xy". This\r
 * in turn can be used by other formulas. For example:\r
 *\r
 *      formulas: {\r
 *          xy: function (get) {  // "get" is arbitrary but a good convention\r
 *              return get('x') * get('y');\r
 *          },\r
 *\r
 *          xyz: function (get) {\r
 *              return get('xy') * get('z');\r
 *          }\r
 *      }\r
 *\r
 * In the above, "xyz" depends on "xy" and "z" values in the `ViewModel`.\r
 *\r
 * ### The Getter Method\r
 *\r
 * The argument passed to the formula is a function that allows you to retrieve\r
 * the matched bind statements.\r
 *\r
 *      formulas: {\r
 *          foo: function (get) {\r
 *              return get('theUser.address.city');\r
 *          }\r
 *      }\r
 *\r
 * In the above, the dependency is resolved to `theUser.address.city`. The formula will not\r
 * be triggered until the value for `city` is present.\r
 *\r
 * ### Capturing Values\r
 *\r
 * If values need to be used repeatedly, you can use a `var` as long as the Rules are not\r
 * broken.\r
 *\r
 *      formulas: {\r
 *          x2y2: function (get) {\r
 *              // These are still "visible" as "get('x')" and "get('y')" so this is OK:\r
 *              var x = get('x'),\r
 *                  y = get('y');\r
 *\r
 *              return x * x * y * y;\r
 *          }\r
 *      }\r
 *\r
 * ## Explicit Binding\r
 *\r
 * While function parsing is convenient, there are times it is not the best solution. In\r
 * these cases, an explicit `bind` can be given. To revisit the previous example with an\r
 * explicit binding:\r
 *\r
 *      formulas: {\r
 *          zip: {\r
 *              bind: '{foo.bar.zip}',\r
 *\r
 *              get: function (zip) {\r
 *                  // NOTE: the only thing we get is what our bind produces.\r
 *                  return zip * 2;\r
 *              }\r
 *          }\r
 *      }\r
 *\r
 * In this case we have given the formula an explicit `bind` value so it will no longer\r
 * parse the `get` function. Instead, it will call `{@link Ext.app.ViewModel#bind}` with\r
 * the value of the `bind` property and pass the produced value to `get` whenever it\r
 * changes.\r
 *\r
 * ## Settable Formulas\r
 *\r
 * When a formula is "reversible" it can be given a `set` method to allow it to participate\r
 * in two-way binding. For example:\r
 *\r
 *      formulas: {\r
 *             fullName: {\r
 *                 get: function (get) {\r
 *                     var ret = get('firstName') || '';\r
 *\r
 *                     if (get('lastName')) {\r
 *                         ret += ' ' +  get('lastName');\r
 *                     }\r
 *\r
 *                     return ret;\r
 *                 },\r
 *\r
 *                 set: function (value) {\r
 *                     var space = value.indexOf(' '),\r
 *                         split = (space < 0) ? value.length : space;\r
 *\r
 *                     this.set({\r
 *                         firstName: value.substring(0, split),\r
 *                         lastName: value.substring(split + 1)\r
 *                     });\r
 *                 }\r
 *             }\r
 *         }\r
 *\r
 * When the `set` method is called the `this` reference is the `Ext.app.ViewModel` so it\r
 * just calls its `{@link Ext.app.ViewModel#method-set set method}`.\r
 *\r
 * ## Single Run Formulas\r
 *\r
 * If a formula only needs to produce an initial value, it can be marked as `single`.\r
 *\r
 *      formulas: {\r
 *          xy: {\r
 *              single: true,\r
 *\r
 *              get: function (get) {\r
 *                  return get('x') * get('y');\r
 *              }\r
 *          }\r
 *      }\r
 *\r
 * This formulas `get` method will be called with `x` and `y` once and then its binding\r
 * to these properties will be destroyed. This means the `get` method (and hence the value\r
 * of `xy`) will only be executed/calculated once.\r
 */\r
Ext.define('Ext.app.bind.Formula', {\r
    extend: 'Ext.util.Schedulable',\r
\r
    requires: [\r
        'Ext.util.LruCache'\r
    ],\r
\r
    statics: {\r
        getFormulaParser: function(name) {\r
            var cache = this.formulaCache,\r
                parser, s;\r
\r
            if (!cache) {\r
                cache = this.formulaCache = new Ext.util.LruCache({\r
                    maxSize: 20\r
                });\r
            }\r
\r
            parser = cache.get(name);\r
            if (!parser) {\r
                // Unescaped: [^\.a-z0-9_]NAMEHERE\(\s*(['"])(.*?)\1\s*\)\r
                s = '[^\\.a-z0-9_]' + name + '\\(\\s*([\'"])(.*?)\\1\\s*\\)';\r
                parser = new RegExp(s, 'gi');\r
                cache.add(name, parser);\r
            }\r
            return parser;\r
        }\r
    },\r
\r
    isFormula: true,\r
\r
    calculation: null,\r
\r
    explicit: false,\r
\r
    /**\r
     * @cfg {Object} [bind]\r
     * An explicit bind request to produce data to provide the `get` function. If this is\r
     * specified, the result of this bind is the first argument to `get`. If not given,\r
     * then `get` receives a getter function that can retrieve bind expressions. For details on what can\r
     * be specified for this property see `{@link Ext.app.ViewModel#bind}`.\r
     * @since 5.0.0\r
     */\r
\r
    /**\r
     * @cfg {Function} get\r
     * The function to call to calculate the formula's value. The `get` method executes\r
     * with a `this` pointer of the `ViewModel` and receives a getter function or the result of a configured `bind`.\r
     * @since 5.0.0\r
     */\r
\r
    /**\r
     * @cfg {Function} [set]\r
     * If provided this method allows a formula to be set. This method is typically called\r
     * when `{@link Ext.app.bind.Binding#setValue}` is called. The `set` method executes\r
     * with a `this` pointer of the `ViewModel`. Whatever values need to be updated can\r
     * be set by calling `{@link Ext.app.ViewModel#set}`.\r
     * @since 5.0.0\r
     */\r
    set: null,\r
\r
    /**\r
     * @cfg {Boolean} [single=false]\r
     * This option instructs the binding to call its `destroy` method immediately after\r
     * delivering the initial value.\r
     * @since 5.0.0\r
     */\r
    single: false,\r
\r
    argumentNamesRe: /^function\s*\(\s*([^,\)\s]+)/,\r
\r
    constructor: function (stub, formula) {\r
        var me = this,\r
            owner = stub.owner,\r
            bindTo, expressions, getter, options;\r
\r
        me.owner = owner;\r
        me.stub = stub;\r
\r
        me.callParent();\r
\r
        if (formula instanceof Function) {\r
            me.get = getter = formula;\r
        } else {\r
            me.get = getter = formula.get;\r
            me.set = formula.set;\r
            expressions = formula.bind;\r
\r
            if (formula.single) {\r
                me.single = formula.single;\r
            }\r
\r
            if (expressions) {\r
                bindTo = expressions.bindTo;\r
\r
                if (bindTo) {\r
                    options = Ext.apply({}, expressions);\r
                    delete options.bindTo;\r
                    expressions = bindTo;\r
                }\r
            }\r
        }\r
\r
        //<debug>\r
        if (!getter) {\r
            Ext.raise('Must specify a getter method for a formula');\r
        }\r
        //</debug>\r
\r
        if (expressions) {\r
            me.explicit = true;\r
        } else {\r
            expressions = getter.$expressions || me.parseFormula(getter);\r
        }\r
\r
        me.binding = owner.bind(expressions, me.onChange, me, options);\r
    },\r
\r
    destroy: function () {\r
        var me = this,\r
            binding = me.binding,\r
            stub = me.stub;\r
\r
        if (binding) {\r
            binding.destroy();\r
            me.binding = null;\r
        }\r
\r
        if (stub) {\r
            stub.formula = null;\r
        }\r
\r
        me.callParent();\r
\r
        // Save for last because this is used to remove us from the Scheduler\r
        me.getterFn = me.owner = null;\r
    },\r
\r
    getFullName: function () {\r
        return this.fullName ||\r
              (this.fullName = this.stub.getFullName() + '=' + this.callParent() + ')');\r
    },\r
\r
    getRawValue: function () {\r
        return this.calculation;\r
    },\r
\r
    onChange: function () {\r
        if (!this.scheduled) {\r
            this.schedule();\r
        }\r
    },\r
\r
    parseFormula: function (formula) {\r
        var str = formula.toString(),\r
            expressions = {\r
                $literal: true\r
            },\r
            match, getterProp, formulaRe, expr;\r
\r
        match = this.argumentNamesRe.exec(str);\r
        getterProp = match ? match[1] : 'get';\r
        formulaRe = Ext.app.bind.Formula.getFormulaParser(getterProp);\r
\r
        while ((match = formulaRe.exec(str))) {\r
            expr = match[2];\r
            expressions[expr] = expr;\r
        }\r
\r
        expressions.$literal = true;\r
\r
        // We store the parse results on the function object because we might reuse the\r
        // formula function (typically when a ViewModel class is created a 2nd+ time).\r
        formula.$expressions = expressions;\r
\r
        return expressions;\r
    },\r
\r
    react: function () {\r
        var me = this,\r
            owner = me.owner,\r
            data = me.binding.lastValue,\r
            getterFn = me.getterFn,\r
            arg;\r
\r
        if (me.explicit) {\r
            arg = data;\r
        } else {\r
            arg = owner.getFormulaFn(data);\r
        }\r
        me.settingValue = true;\r
        me.stub.set(me.calculation = me.get.call(owner, arg));\r
        me.settingValue = false;\r
\r
        if (me.single) {\r
            me.destroy();\r
        }\r
    },\r
\r
    setValue: function(value) {\r
        this.set.call(this.stub.owner, value);\r
    },\r
\r
    privates: {\r
        getScheduler: function () {\r
            var owner = this.owner;\r
            return owner && owner.getScheduler();\r
        },\r
        \r
        sort: function () {\r
            var me = this,\r
                binding = me.binding;\r
\r
            // Our binding may be single:true\r
            if (!binding.destroyed) {\r
                me.scheduler.sortItem(binding);\r
            }\r
\r
            // Schedulable#sort === emptyFn\r
            //me.callParent();\r
        }\r
    }\r
});\r