# Yahoo! UI Library

### substitute 3.0.0

Yahoo! UI Library > substitute > substitute.js (source view)
Search:
Filters Show Private Show Protected Show Deprecated

    /**
     * String variable substitution and string formatting.
     * If included, the substitute method is added to the YUI instance.
     *
     * @module substitute
     */

        var L = Y.Lang, DUMP='dump', SPACE=' ', LBRACE='{', RBRACE='}',

        /**
         * The following methods are added to the YUI instance
         * @class YUI~substitute
         */

         // @todo template configurability is not implemented yet
         // @param ldelim {string} optional left delimiter for the replacement token (default: left brace)
         // @param rdelim {string} optional right delimiter for the replacement token (default: right brace)

        /**
         * Does variable substitution on a string. It scans through the string
         * looking for expressions enclosed in { } braces. If an expression
         * is found, it is used a key on the object.  If there is a space in
         * the key, the first word is used for the key and the rest is provided
         * to an optional function to be used to programatically determine the
         * value (the extra information might be used for this decision). If
         * the value for the key in the object, or what is returned from the
         * function has a string value, number value, or object value, it is
         * substituted for the bracket expression and it repeats.  If this
         * value is an object, it uses the Object's toString() if this has
         * been overridden, otherwise it does a shallow dump of the key/value
         * pairs if Y.dump is available (if dump isn't available, toString()
         * is used).
         *
         * This method is included in the 'substitute' module.  It is not included
         * in the YUI module.
         *
         * @method substitute
         * @param s {string} The string that will be modified.
         * @param o An object containing the replacement values
         * @param f {function} An optional function that can be used to
         *                     process each match.  It receives the key,
         *                     value, and any extra metadata included with
         *                     the key inside of the braces.
         * @return {string} the substituted string
         */

        substitute = function (s, o, f, ldelim, rdelim) {
            var i, j, k, key, v, meta, saved=[], token, dump;
            ldelim = ldelim || LBRACE;
            rdelim = rdelim || RBRACE;

            for (;;) {
                i = s.lastIndexOf(ldelim);
                if (i < 0) {
                    break;
                }
                j = s.indexOf(rdelim, i);
                if (i + 1 >= j) {
                    break;
                }

                //Extract key and meta info
                token = s.substring(i + 1, j);
                key = token;
                meta = null;
                k = key.indexOf(SPACE);
                if (k > -1) {
                    meta = key.substring(k + 1);
                    key = key.substring(0, k);
                }

                // lookup the value
                v = o[key];

                // if a substitution function was provided, execute it
                if (f) {
                    v = f(key, v, meta);
                }

                if (L.isObject(v)) {
                    if (!Y.dump) {
                        v = v.toString();
                    } else {
                        if (L.isArray(v)) {
                            v = Y.dump(v, parseInt(meta, 10));
                        } else {
                            meta = meta || "";

                            // look for the keyword 'dump', if found force obj dump
                            dump = meta.indexOf(DUMP);
                            if (dump > -1) {
                                meta = meta.substring(4);
                            }

                            // use the toString if it is not the Object toString
                            // and the 'dump' meta info was not found
                            if (v.toString===Object.prototype.toString||dump>-1) {
                                v = Y.dump(v, parseInt(meta, 10));
                            } else {
                                v = v.toString();
                            }
                        }
                    }
                } else if (!L.isString(v) && !L.isNumber(v)) {
                    // This {block} has no replace string. Save it for later.
                    v = "~-" + saved.length + "-~";
                    saved[saved.length] = token;

                    // break;
                }

                s = s.substring(0, i) + v + s.substring(j + 1);

            }

            // restore saved {block}s
            for (i=saved.length-1; i>=0; i=i-1) {
                s = s.replace(new RegExp("~-" + i + "-~"), ldelim  + saved[i] + rdelim, "g");
            }

            return s;

        };

        Y.substitute = substitute;
        L.substitute = substitute;

Copyright © 2009 Yahoo! Inc. All rights reserved.