chance-token-replacer

A simple utility to replace tokens in a string with generations from the Chance random generator helper.

Installation

npm install chance-token-replacer

Usage

replacer.processString(tokenString)

Example

var TokenReplacer = require('chance-token-replacer');

var replacer = new TokenReplacer();

var tokenString = 'Hello, my name is <@first@> <@last@>.  You can email me at !1.![e-mail], or call me at <@phone@>. This is my catchphrase: <@sentence#{words:5}@>';

var processedString = replacer.processString(tokenString);

console.log(processedString); // Hello, my name is Landon McKinney.  You can email me at [e-mail], or call me at [phone]. This is my catchphrase: Rokbove ilevuzen ugze monvun mi.

Basic Use

The replacer uses the Chance random generator helper to replace tokens in a string with generated data. The replacer looks for the token format <@chanceMethodName@> and replaces it with the result of the corresponding Chance method call.

Custom starting and ending tokens

You can use custom starting and ending tokens instead of the default <@ and @> by passing an options object to the constructor:

var replacer = new TokenReplacer({
    endToken: '%]',
    startToken: '[%'
});

replacer.processString('My first name is [%first%].');

Custom replacer functions

The replacer will also accept a custom replacer function to process tokens in addition to the chance api methods. It does not accept anything after the # inside of a token.

Example

var dummyConfigObject = {
    customValue: 'ABC_123'
};

function customReplacerFn(s) {
    var customEvaluation = s;

    if (_.startsWith(s, 'dummyConfigObject')) {
        var key = s.split('.')[1];

        if (!!dummyConfigObject[key]) {
            customEvaluation = dummyConfigObject[key];
        }
    }

    return customEvaluation;
}

var options = {
    customReplacerFn: customReplacerFn
};

var replacer = new TokenReplacer(options);

replacer.processString('<@dummyConfigObject.customValue@>'); // 'ABC_123'

Passing JSON5 object to token methods

You can also pass a configuration object (in JSON5 format) to the method by including a # followed by a configuration object:

'<@chanceMethodName#{key:value, key2:value2}@>'

'This is my social security number: <@ssn#{dashes:false}@>';

// Evaluates to:
'This is my social security number: 344750126';

'<@pickone#["A","B","C"]@>'

'selected letter: <@pickone#["A","B","C"]@>';

// Evaluates to:
'selected letter: B';

Backreferences

The replacer caches every evaluated token to an array using a 1-based index. You can reference these values with bang (!) and a number corresponding to the order the tokens were replaced.

'My name is <@first@> <@last@>, but you can just call me !1.  Mr. !2 is my father.';

// Evaluates to:
'My name is Lawrence Armstrong, but you can just call me Lawrence.  Mr. Armstrong is my father.';

Evaluated tokens persist with the replacer instance, so you can even reference replacements from previous calls:

var TokenReplacer = require('./index.js');

var replacer = new TokenReplacer();

var tokenStringOne = 'Say hello to Mr. <@last@>.';
var tokenStringTwo = 'Hi, Mr. !1.';

var evaluatedStringOne = replacer.processString(tokenStringOne);
var evaluatedStringTwo = replacer.processString(tokenStringTwo);

console.log(evaluatedStringOne); // Say hello to Mr. Graham.
console.log(evaluatedStringTwo); // Hi, Mr. Graham.

The evaluated token cache can be reset by calling replacer.resetEvaluatedTokens().

API

replacer.processString

Returns an evaluated string.

replacer.processString(tokenString)

replacer.resetEvaluatedTokens

Removes cached evaluated token values.

replacer.resetEvaluatedTokens()