jssource/src_files/include/javascript/yui3/build/substitute/substitute.js

   1 /*
   2 Copyright (c) 2010, Yahoo! Inc. All rights reserved.
   3 Code licensed under the BSD License:
   4 http://developer.yahoo.com/yui/license.html
   5 version: 3.3.0
   6 build: 3167
   7 */
   8 YUI.add('substitute', function(Y) {
   9
  10 /**
  11  * String variable substitution and string formatting.
  12  * If included, the substitute method is added to the YUI instance.
  13  *
  14  * @module substitute
  15  */
  16
  17     var L = Y.Lang, DUMP = 'dump', SPACE = ' ', LBRACE = '{', RBRACE = '}',
  18
  19     /**
  20      * The following methods are added to the YUI instance
  21      * @class YUI~substitute
  22      */
  23
  24     /**
  25      * Does variable substitution on a string. It scans through the string
  26      * looking for expressions enclosed in { } braces. If an expression
  27      * is found, it is used a key on the object.  If there is a space in
  28      * the key, the first word is used for the key and the rest is provided
  29      * to an optional function to be used to programatically determine the
  30      * value (the extra information might be used for this decision). If
  31      * the value for the key in the object, or what is returned from the
  32      * function has a string value, number value, or object value, it is
  33      * substituted for the bracket expression and it repeats.  If this
  34      * value is an object, it uses the Object's toString() if this has
  35      * been overridden, otherwise it does a shallow dump of the key/value
  36      * pairs if Y.dump is available (if dump isn't available, toString()
  37      * is used).
  38      *
  39      * This method is included in the 'substitute' module.  It is not included
  40      * in the YUI module.
  41      *
  42      * @method substitute
  43      * @param {string} s The string that will be modified.
  44      * @param {object} o An object containing the replacement values.
  45      * @param {function} f An optional function that can be used to
  46      *                     process each match.  It receives the key,
  47      *                     value, and any extra metadata included with
  48      *                     the key inside of the braces.
  49      * @param {boolean} recurse if true, the replacement will be recursive,
  50      * letting you have replacement tokens in replacement text.  The
  51      * default is false.
  52      * @return {string} the substituted string.
  53      */
  54
  55     substitute = function(s, o, f, recurse) {
  56         var i, j, k, key, v, meta, saved = [], token, dump,
  57             lidx = s.length;
  58
  59         for (;;) {
  60             i = s.lastIndexOf(LBRACE, lidx);
  61             if (i < 0) {
  62                 break;
  63             }
  64             j = s.indexOf(RBRACE, i);
  65             if (i + 1 >= j) {
  66                 break;
  67             }
  68
  69             //Extract key and meta info
  70             token = s.substring(i + 1, j);
  71             key = token;
  72             meta = null;
  73             k = key.indexOf(SPACE);
  74             if (k > -1) {
  75                 meta = key.substring(k + 1);
  76                 key = key.substring(0, k);
  77             }
  78
  79             // lookup the value
  80             v = o[key];
  81
  82             // if a substitution function was provided, execute it
  83             if (f) {
  84                 v = f(key, v, meta);
  85             }
  86
  87             if (L.isObject(v)) {
  88                 if (!Y.dump) {
  89                     v = v.toString();
  90                 } else {
  91                     if (L.isArray(v)) {
  92                         v = Y.dump(v, parseInt(meta, 10));
  93                     } else {
  94                         meta = meta || '';
  95
  96                         // look for the keyword 'dump', if found force obj dump
  97                         dump = meta.indexOf(DUMP);
  98                         if (dump > -1) {
  99                             meta = meta.substring(4);
 100                         }
 101
 102                         // use the toString if it is not the Object toString
 103                         // and the 'dump' meta info was not found
 104                         if (v.toString === Object.prototype.toString ||
 105                             dump > -1) {
 106                             v = Y.dump(v, parseInt(meta, 10));
 107                         } else {
 108                             v = v.toString();
 109                         }
 110                     }
 111                 }
 112             } else if (!L.isString(v) && !L.isNumber(v)) {
 113                 // This {block} has no replace string. Save it for later.
 114                 v = '~-' + saved.length + '-~';
 115                 saved[saved.length] = token;
 116
 117                 // break;
 118             }
 119
 120             s = s.substring(0, i) + v + s.substring(j + 1);
 121
 122             if (!recurse) {
 123                 lidx = i - 1;
 124             }
 125
 126         }
 127
 128         // restore saved {block}s
 129         for (i = saved.length - 1; i >= 0; i = i - 1) {
 130             s = s.replace(new RegExp('~-' + i + '-~'), LBRACE +
 131                 saved[i] + RBRACE, 'g');
 132         }
 133
 134         return s;
 135
 136     };
 137
 138     Y.substitute = substitute;
 139     L.substitute = substitute;
 140
 141
 142
 143 }, '3.3.0' ,{optional:['dump']});