lib/yuilib/3.13.0/substitute/substitute.js

   1 /*
   2 YUI 3.13.0 (build 508226d)
   3 Copyright 2013 Yahoo! Inc. All rights reserved.
   4 Licensed under the BSD License.
   5 http://yuilibrary.com/license/
   6 */
   7
   8 YUI.add('substitute', function (Y, NAME) {
   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  * @deprecated
  16  */
  17
  18     var L = Y.Lang, DUMP = 'dump', SPACE = ' ', LBRACE = '{', RBRACE = '}',
  19                 savedRegExp =  /(~-(\d+)-~)/g, lBraceRegExp = /\{LBRACE\}/g, rBraceRegExp = /\{RBRACE\}/g,
  20
  21     /**
  22      * The following methods are added to the YUI instance
  23      *
  24      * <strong>Use `Y.Lang.sub` or `Y.Template` instead.</strong>
  25      * @class YUI~substitute
  26      * @deprecated
  27      */
  28
  29 /**
  30 <strong>Use `Y.Lang.sub` or `Y.Template` instead.</strong>
  31
  32
  33
  34 Does `{placeholder}` substitution on a string.  The object passed as the
  35 second parameter provides values to replace the `{placeholder}`s.
  36 {placeholder} token names must match property names of the object.  For
  37 example
  38
  39 `var greeting = Y.substitute("Hello, {who}!", { who: "World" });`
  40
  41 `{placeholder}` tokens that are undefined on the object map will be left in
  42 tact (leaving unsightly "{placeholder}"s in the output string).  If your
  43 replacement strings *should* include curly braces, use `{LBRACE}` and
  44 `{RBRACE}` in your object map string value.
  45
  46 If a function is passed as a third argument, it will be called for each
  47 {placeholder} found.  The {placeholder} name is passed as the first value
  48 and the value from the object map is passed as the second.  If the
  49 {placeholder} contains a space, the first token will be used to identify
  50 the object map property and the remainder will be passed as a third
  51 argument to the function.  See below for an example.
  52
  53 If the value in the object map for a given {placeholder} is an object and
  54 the `dump` module is loaded, the replacement value will be the string
  55 result of calling `Y.dump(...)` with the object as input.  Include a
  56 numeric second token in the {placeholder} to configure the depth of the call
  57 to `Y.dump(...)`, e.g. "{someObject 2}".  See the
  58 <a href="../classes/YUI.html#method_dump">`dump`</a> method for details.
  59
  60     @method substitute
  61     @deprecated
  62     @param {string} s The string that will be modified.
  63     @param {object} o An object containing the replacement values.
  64     @param {function} f An optional function that can be used to
  65                         process each match.  It receives the key,
  66                         value, and any extra metadata included with
  67                         the key inside of the braces.
  68     @param {boolean} recurse if true, the replacement will be recursive,
  69                         letting you have replacement tokens in replacement text.
  70                         The default is false.
  71     @return {string} the substituted string.
  72
  73     @example
  74
  75         function getAttrVal(key, value, name) {
  76             // Return a string describing the named attribute and its value if
  77             // the first token is @. Otherwise, return the value from the
  78             // replacement object.
  79             if (key === "@") {
  80                 value += name + " Value: " + myObject.get(name);
  81             }
  82             return value;
  83         }
  84
  85         // Assuming myObject.set('foo', 'flowers'),
  86         // => "Attr: foo Value: flowers"
  87         var attrVal = Y.substitute("{@ foo}", { "@": "Attr: " }, getAttrVal);
  88     **/
  89
  90     substitute = function(s, o, f, recurse) {
  91         var i, j, k, key, v, meta, saved = [], token, dump,
  92             lidx = s.length;
  93
  94         for (;;) {
  95             i = s.lastIndexOf(LBRACE, lidx);
  96             if (i < 0) {
  97                 break;
  98             }
  99             j = s.indexOf(RBRACE, i);
 100             if (i + 1 >= j) {
 101                 break;
 102             }
 103
 104             //Extract key and meta info
 105             token = s.substring(i + 1, j);
 106             key = token;
 107             meta = null;
 108             k = key.indexOf(SPACE);
 109             if (k > -1) {
 110                 meta = key.substring(k + 1);
 111                 key = key.substring(0, k);
 112             }
 113
 114             // lookup the value
 115             v = o[key];
 116
 117             // if a substitution function was provided, execute it
 118             if (f) {
 119                 v = f(key, v, meta);
 120             }
 121
 122             if (L.isObject(v)) {
 123                 if (!Y.dump) {
 124                     v = v.toString();
 125                 } else {
 126                     if (L.isArray(v)) {
 127                         v = Y.dump(v, parseInt(meta, 10));
 128                     } else {
 129                         meta = meta || '';
 130
 131                         // look for the keyword 'dump', if found force obj dump
 132                         dump = meta.indexOf(DUMP);
 133                         if (dump > -1) {
 134                             meta = meta.substring(4);
 135                         }
 136
 137                         // use the toString if it is not the Object toString
 138                         // and the 'dump' meta info was not found
 139                         if (v.toString === Object.prototype.toString ||
 140                             dump > -1) {
 141                             v = Y.dump(v, parseInt(meta, 10));
 142                         } else {
 143                             v = v.toString();
 144                         }
 145                     }
 146                 }
 147                         } else if (L.isUndefined(v)) {
 148                 // This {block} has no replace string. Save it for later.
 149                 v = '~-' + saved.length + '-~';
 150                                         saved.push(token);
 151
 152                 // break;
 153             }
 154
 155             s = s.substring(0, i) + v + s.substring(j + 1);
 156
 157                         if (!recurse) {
 158                                 lidx = i - 1;
 159                         }
 160                 }
 161                 // restore saved {block}s and escaped braces
 162
 163                 return s
 164                         .replace(savedRegExp, function (str, p1, p2) {
 165                                 return LBRACE + saved[parseInt(p2,10)] + RBRACE;
 166                         })
 167                         .replace(lBraceRegExp, LBRACE)
 168                         .replace(rBraceRegExp, RBRACE)
 169                 ;
 170         };
 171
 172     Y.substitute = substitute;
 173     L.substitute = substitute;
 174
 175
 176
 177 }, '3.13.0', {"requires": ["yui-base"], "optional": ["dump"]});