expander

Expand template strings in declarative configurations.

npm install expander
61 downloads in the last week
67 downloads in the last month

expander Build Status

Expand template strings in declarative configurations.

API

get(data, lookup, imports)

Retrieve a value from the data object with all template strings resolved.

data a configuration object lookup a dot-notated key options sent to _.template when resolving values.

Example:

var data = {
  key: '<%= uppercase("foo") %>'
};
expander.get(data, 'key', {
  imports: {
    uppercase: function (str) {
      return str.toUpperCase();
    }
  }
}); // FOO

getRaw(data, lookup)

Retrieve a literal value from the data object.

data a configuration object lookup a dot-notated string representing a key in the configuration

set(data, lookup, value)

Set a value in the data object.

data a configuration object lookup a dot-notated string representing a key in the data value the value to set

process(data, lookup, options)

Resolve any arbitrary template string.

data a configuration object lookup any string value, typically a template string, e.g. "<%= key %>" options sent to _.template when resolving values.

interface(data, options)

Bind the above API to a provided data object so you can access it more succinctly.

data a configuration object options sent to _.template automatically when resolving values.

Note: When using the interface API, passing options to get or process will perform a shallow merge over options provided when the interface was instantiated.

Example:

var configRaw = {
  key: 'value',
  keyRef: '<%= key %>'
};
var config = expander.interface(config);
config('key'); // value
config.get('key'); // value
config('keyRef'); // value
config.get('keyRef'); // value
config('key', 'changed'); // changed
config('key'); // changed

Examples

var expander = require('expander');

var data = {
  key: 'value',
  keyRef: '<%= key %>',
  recursiveKeyRef: '<%= keyRef %>',
  arrayRef: ['test', '<%= key %>'],
  recursiveArrayRef: ['test', '<%= arrayRef %>'],
  obj: {
    keyRef: '<%= key %>',
    recursiveKeyRef: '<%= keyRef %>',
    arrayRef: ['test', '<%= key %>'],
    recursiveArrayRef: ['test', '<%= arrayRef %>']
  },
  dotRef: '<%= obj.keyRef %>',
  objRef: '<%= obj %>',
  interpolated: 'test <%= key %>',
  interpolatedRecursiveRef: 'test <%= keyRef %>',
  methodRef: expander.fn(function (config) {
    // config is the entire config
    return config.key;
  }),
  methodRefContext: expander.fn(function (config) {
    // this is a reference to expander
    return this.get(config, 'keyRef');
  })
};

expander.get(data, 'keyRef'); // value
expander.get(data, 'recursiveKeyRef'); // value
expander.get(data, 'arrayRef'); // ['test', 'value']
expander.get(data, 'recursiveArrayRef'); // ['test', ['test', 'value']]
expander.get(data, 'obj'); // {
                           //   keyRef: 'value',
                           //   recursiveKeyRef: 'value',
                           //   arrayRef: ['test', 'value'],
                           //   recursiveArrayRef: ['test', ['test', 'value']]
                           // }
expander.get(data, 'objRef'); // {
                              //   keyRef: 'value',
                              //   recursiveKeyRef: 'value',
                              //   arrayRef: ['test', 'value'],
                              //   recursiveArrayRef: ['test', ['test', 'value']]
                              // }
expander.get(data, 'interpolated'); // test value
expander.get(data, 'interpolatedRecursiveRef'); // test value
expander.get(data, 'methodRef'); // value
expander.get(data, 'methodRefContext'); // value

// getter setter api
var config = expander.interface(data);
config('keyRef'); // value
config('recursiveKeyRef'); // value
config('arrayRef'); // ['test', 'value']
config('recursiveArrayRef'); // ['test', ['test', 'value']]
config('obj'); // {
               //   keyRef: 'value',
               //   recursiveKeyRef: 'value',
               //   arrayRef: ['test', 'value'],
               //   recursiveArrayRef: ['test', ['test', 'value']]
               // }
config('objRef'); // {
                  //   keyRef: 'value',
                  //   recursiveKeyRef: 'value',
                  //   arrayRef: ['test', 'value'],
                  //   recursiveArrayRef: ['test', ['test', 'value']]
                  // }
config('interpolated'); // test value
config('interpolatedRecursiveRef'); // test value
config('methodRef'); // value
config('methodRefContext'); // value

Release History

  • 2014-02-21 - v0.3.3 - allow overriding default options for _.template in interface api
  • 2014-02-20 - v0.3.2 - allow passing options to _.template
  • 2014-02-11 - v0.3.1 - interface emits events on set
  • 2014-02-10 - v0.3.0 - support a getter/setter api
  • 2013-12-15 - v0.2.2 - support auto expansion of functions
  • 2013-11-21 - v0.2.1 - support ${value} strings
  • 2013-11-08 - v0.2.0 - correctly handle recursively interpolated values
  • 2013-11-05 - v0.1.0 - initial release
npm loves you