add extjs 6.0.1 sources

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

/**\r
 * This class holds the parsed text for a bind template. The syntax is that of a normal\r
 * `Ext.Template` except that substitution tokens can contain dots to reference property\r
 * names.\r
 *\r
 * The template is parsed and stored in a representation like this:\r
 *\r
 *      me.text = 'Hey {foo.bar}! Test {bar} and {foo.bar} with {abc} over {bar:number}'\r
 *\r
 *      me.tokens = [ 'foo.bar', 'bar', 'abc' ]\r
 *\r
 *      me.buffer = [           me.slots = [\r
 *          'Hey ',                 undefined,\r
 *          undefined,              { token: 'foo.bar', pos: 0 },\r
 *          '! Test ',              undefined,\r
 *          undefined,              { token: 'bar', pos: 1 },\r
 *          ' and ',                undefined,\r
 *          undefined,              { token: 'foo.bar', pos: 0 },\r
 *          ' with ',               undefined,\r
 *          undefined,              { token: 'abc', pos: 2 },\r
 *          ' over ',               undefined,\r
 *          undefined               { token: 'bar', fmt: 'number', pos: 1 }\r
 *      ]                       ]\r
 *\r
 * @private\r
 * @since 5.0.0\r
 */\r
Ext.define('Ext.app.bind.Template', {\r
    requires: [\r
        'Ext.util.Format'\r
    ],\r
\r
    numberRe: /^(?:\d+(?:\.\d*)?)$/,\r
\r
    stringRe: /^(?:["][^"]*["])$/,\r
\r
    /**\r
     * @property {RegExp} tokenRe\r
     * Regular expression used to extract tokens.\r
     *\r
     * Finds the following expressions within a format string\r
     *\r
     *                     {AND?}\r
     *                     /    \\r
     *                   /        \\r
     *                 /            \\r
     *               /                \\r
     *            OR                   AND?\r
     *           /  \                  / \\r
     *          /    \                /   \\r
     *         /      \              /     \\r
     *    (\d+)  ([a-z_][\w\-\.]*)  /       \\r
     *     index       name       /         \\r
     *                           /           \\r
     *                          /             \\r
     *                   :([a-z_\.]*)    (?:\(([^\)]*?)?\))?\r
     *                      formatFn           args\r
     *\r
     * Numeric index or (name followed by optional formatting function and args)\r
     * @private\r
     */\r
    tokenRe: /\{[!]?(?:(?:(\d+)|([a-z_][\w\-\.]*))(?::([a-z_\.]+)(?:\(([^\)]*?)?\))?)?)\}/gi,\r
\r
    formatRe: /^([a-z_]+)(?:\(([^\)]*?)?\))?$/i,\r
\r
    /**\r
     * @property {String[]} buffer\r
     * Initially this is just the array of string fragments with `null` between each\r
     * to hold the place of a substitution token. On first use these slots are filled\r
     * with the token's value and this array is joined to form the output.\r
     * @private\r
     */\r
    buffer: null,\r
\r
    /**\r
     * @property {Object[]} slots\r
     * The elements of this array line up with those of `buffer`. This array holds\r
     * the parsed information for the substitution token that fills a given slot in\r
     * the generated string. Indices that correspond to literal text are `null`.\r
     *\r
     * Consider the following substitution token:\r
     *\r
     *      {foo:this.fmt(2,4)}\r
     *\r
     * The object in this array has the following properties to describe this token:\r
     *\r
     *   * `fmt` The name of the formatting function ("fmt") or `null` if none.\r
     *   * `index` The numeric index if this is not a named substitution or `null`.\r
     *   * `not` True if the token has a logical not ("!") at the front.\r
     *   * `token` The name of the token ("foo") if not an `index`.\r
     *   * `pos` The position of this token in the `tokens` array.\r
     *   * `scope` A reference to the object on which the `fmt` method exists. This\r
     *    will be `Ext.util.Format` if no "this." is present or `null` if it is (or\r
     *    if there is no `fmt`). In the above example, this is `null` to indicate the\r
     *    scope is unknown.\r
     *   * `args` An array of arguments to `fmt` if the arguments are simple enough\r
     *    to parse directly. Otherwise this is `null` and `fn` is used.\r
     *   * `fn` A generated function to use to evaluate the arguments to the `fmt`. In\r
     *    rare cases these arguments can reference global variables so the expression\r
     *    must be evaluated on each call.\r
     *   * `format` The method to call to perform the format. This method accepts the\r
     *    scope (in case `scope` is unknown) and the value. This function is `null` if\r
     *    there is no `fmt`.\r
     *\r
     * @private\r
     */\r
    slots: null,\r
\r
    /**\r
     * @property {String[]} tokens\r
     * The distinct set of tokens used in the template excluding formatting. This is\r
     * used to ensure that only one bind is performed per unique token. This array is\r
     * passed to {@link Ext.app.ViewModel#bind} to perform a "multi-bind". The result\r
     * is an array of values corresponding these tokens. Each entry in `slots` then\r
     * knows its `pos` in this array from which to pick up its value, apply formats\r
     * and place in `buffer`.\r
     * @private\r
     */\r
    tokens: null,\r
\r
    /**\r
     * @param {String} text The text of the template.\r
     */\r
    constructor: function (text) {\r
        var me = this,\r
            initters = me._initters,\r
            name;\r
\r
        me.text = text;\r
\r
        for (name in initters) {\r
            me[name] = initters[name];\r
        }\r
    },\r
\r
    /**\r
     * @property {Object} _initters\r
     * Each of the methods contained on this object are placed in new instances to lazily\r
     * parse the template text.\r
     * @private\r
     * @since 5.0.0\r
     */\r
    _initters: {\r
        apply: function (values, scope) {\r
            return this.parse().apply(values, scope);\r
        },\r
        getTokens: function () {\r
            return this.parse().getTokens();\r
        }\r
    },\r
\r
    /**\r
     * Applies this template to the given `values`. The `values` must correspond to the\r
     * `tokens` returned by `getTokens`.\r
     *\r
     * @param {Array} values The values of the `tokens`.\r
     * @param {Object} scope The object instance to use for "this." formatter calls in the\r
     * template.\r
     * @return {String}\r
     * @since 5.0.0\r
     */\r
    apply: function (values, scope) {\r
        var me = this,\r
            slots = me.slots,\r
            buffer = me.buffer,\r
            length = slots.length,  // === buffer.length\r
            i, slot, value;\r
\r
        for (i = 0; i < length; ++i) {\r
            slot = slots[i];\r
            if (slot) {\r
                if ((value = values[slot.pos]) == null) {\r
                    // map (value === null || value === undefined) to '':\r
                    value = '';\r
                }\r
                if (slot.not) {\r
                    value = !value;\r
                }\r
                if (slot.format) {\r
                    value = slot.format(value, scope);\r
                }\r
                buffer[i] = value;\r
            }\r
        }\r
\r
        return buffer.join('');\r
    },\r
\r
    /**\r
     * Returns the distinct set of binding tokens for this template.\r
     * @return {String[]} The `tokens` for this template.\r
     */\r
    getTokens: function () {\r
        return this.tokens;\r
    },\r
\r
    /**\r
     * Parses the template text into `buffer`, `slots` and `tokens`. This method is called\r
     * automatically when the template is first used.\r
     * @return {Ext.app.bind.Template} this\r
     * @private\r
     */\r
    parse: function () {\r
        // NOTE: The particulars of what is stored here, while private, are likely to be\r
        // important to Sencha Architect so changes need to be coordinated.\r
        var me = this,\r
            text = me.text,\r
            buffer = [],\r
            slots = [],\r
            tokens = [],\r
            tokenMap = {},\r
            last = 0,\r
            tokenRe = me.tokenRe,\r
            pos = 0,\r
            fmt, i, length, match, s, slot, token;\r
\r
        // Remove the initters so that we don't get called here again.\r
        for (i in me._initters) {\r
            delete me[i];\r
        }\r
\r
        me.buffer = buffer;\r
\r
        me.slots = slots;\r
\r
        me.tokens = tokens;\r
\r
        // text = 'Hello {foo:this.fmt(2,4)} World {bar} - {1}'\r
        while ((match = tokenRe.exec(text))) {\r
            //   0                      1          2         3           4         index\r
            // [ '{foo:this.fmt(2,4)}', undefined, 'foo',    'this.fmt', '2,4']        6\r
            // [ '{bar}',               undefined, 'bar',     undefined,  undefined]  32\r
            // [ '{1}',                 '1',       undefined, undefined,  undefined]  40\r
            length = match.index - last;\r
            if (length) {\r
                buffer[pos++] = text.substring(last, last + length);\r
                last += length;\r
            }\r
            last += (s = match[0]).length;\r
\r
            slot = {\r
                fmt: (fmt = match[3] || null),\r
                index: match[1] ? parseInt(match[1], 10) : null,\r
                not: s.charAt(1) === '!',\r
                token: match[2] || null\r
            };\r
\r
            token = slot.token || String(slot.index);\r
            if (token in tokenMap) {\r
                slot.pos = tokenMap[token];\r
            } else {\r
                tokenMap[token] = slot.pos = tokens.length;\r
                tokens.push(token);\r
            }\r
\r
            if (fmt) {\r
                if (fmt.substring(0,5) === 'this.') {\r
                    slot.fmt = fmt.substring(5);\r
                } else {\r
                    //<debug>\r
                    if (!(fmt in Ext.util.Format)) {\r
                        Ext.raise('Invalid format specified: "' + fmt + '"');\r
                    }\r
                    //</debug>\r
                    slot.scope = Ext.util.Format;\r
                }\r
\r
                me.parseArgs(match[4], slot);\r
            }\r
\r
            slots[pos++] = slot;\r
        }\r
\r
        if (last < text.length) {\r
            buffer[pos++] = text.substring(last);\r
        }\r
\r
        return me;\r
    },\r
\r
    parseArgs: function (argsString, slot) {\r
        var me = this,\r
            numberRe = me.numberRe,\r
            stringRe = me.stringRe,\r
            arg, args, i, length;\r
\r
        if (!argsString) {\r
            args = [];\r
        } else if (argsString.indexOf(',') < 0) {\r
            args = [argsString];\r
        } else {\r
            args = argsString.split(',');\r
        }\r
\r
        slot = slot || {};\r
        length = args.length;\r
        slot.args = args;\r
\r
        for (i = 0; i < length; ++i) {\r
            arg = args[i];\r
            if (arg === 'true') {\r
                args[i] = true;\r
            } else if (arg === 'false') {\r
                args[i] = false;\r
            } else if (arg === 'null') {\r
                args[i] = null;\r
            } else if (numberRe.test(arg)) {\r
                args[i] = parseFloat(arg);\r
            } else if (stringRe.test(arg)) {\r
                args[i] = arg.substring(1, arg.length - 1);\r
            } else {\r
                slot.fn = Ext.functionFactory('return ['+  argsString +'];');\r
                slot.format = me._formatEval;\r
                break;\r
            }\r
        }\r
\r
        if (!slot.format) {\r
            // make room for the value at index 0\r
            args.unshift(0);\r
            slot.format = me._formatArgs;\r
        }\r
\r
        return slot;\r
    },\r
\r
    /**\r
     * This method parses token formats and returns an object with a `format` method that\r
     * can format values accordingly.\r
     * @param {String} fmt The format suffix of a template token. For example, in the\r
     * token "{foo:round(2)}" the format is "round(2)".\r
     * @return {Object} An object with a `format` method to format values.\r
     * @private\r
     * @since 5.0.0\r
     */\r
    parseFormat: function (fmt) {\r
        var me = this,\r
            match = me.formatRe.exec(fmt),\r
            slot = {\r
                fmt: fmt,\r
                scope: Ext.util.Format\r
            },\r
            args;\r
\r
        //<debug>\r
        if (!match) {\r
            Ext.raise('Invalid format syntax: "' + slot + '"');\r
        }\r
        //</debug>\r
\r
        args = match[2];\r
        if (args) {\r
            slot.fmt = match[1];\r
            me.parseArgs(args, slot);\r
        } else {\r
            slot.args = [0]; // for the value\r
            slot.format = me._formatArgs;\r
        }\r
\r
        return slot;\r
    },\r
\r
    /**\r
     * This method is placed on an entry in `slots` as the `format` method when that entry\r
     * has `args` that could be parsed from the template.\r
     * @param {Object} value The value of the token.\r
     * @param {Object} [scope] The object instance to use for "this." formatter calls in the\r
     * template.\r
     * @return {String} The formatted result to place in `buffer`.\r
     * @private\r
     * @since 5.0.0\r
     */\r
    _formatArgs: function (value, scope) {\r
        // NOTE: our "this" pointer is the object in the "slots" array!\r
        scope = this.scope || scope;\r
        this.args[0] = value; // index 0 is reserved for the value\r
        return scope[this.fmt].apply(scope, this.args);\r
    },\r
\r
    /**\r
     * This method is placed on an entry in `slots` as the `format` method when that entry\r
     * does not have a parsed `args` array.\r
     * @param {Object} value The value of the token.\r
     * @param {Object} [scope] The object instance to use for "this." formatter calls in the\r
     * template.\r
     * @return {String} The formatted result to place in `buffer`.\r
     * @private\r
     * @since 5.0.0\r
     */\r
    _formatEval: function (value, scope) {\r
        // NOTE: our "this" pointer is the object in the "slots" array!\r
        var args = this.fn(); // invoke to get the args array\r
        args.unshift(value); // inject the value at the front\r
        scope = this.scope || scope;\r
        return scope[this.fmt].apply(scope, args);\r
    }\r
});\r