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

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