strings

Easily replace and transform :props in strings.

Strings is the result of many hours on screenhero and a truly collaborative effort between Brian Woodward and Jon Schlinkert.

Please report any bugs or feature requests, thanks!

Install

Install with npm:

npm i strings --save

bower

bower install strings --save

Basics

Main Strings concepts:

• prop-strings
• parsers
• context

prop-strings

A prop-string, or propstring, is a sort of template with one or more delimiters denoting the strings that will replaced with actual values.

Example prop-string:

:a/:b/:c

context

The data that will be used to replace properties in the prop-strings.

Example context:

{
  a: 'aaa',
  b: 'bbb',
  c: 'ccc'
}

If used to replace the prop-strings in the previous section, the result would be:

aaa/bbb/ccc

parsers

By default, Strings will parse and replace the values in the previous examples with no problem. Parsers are used to tell Strings how to process patterns that it can't natively.

Example:

// replace all occurrences of `a` with `b`
strings.parser('a', {pattern: /a/g, replacement: 'b'});

API

Initialize a new Strings object.

var strings = new Strings();

Optionally pass a default context to use:

var strings = new Strings({dirname: 'foo/bar'});

An example use case is dynamically generating dest filepaths from source filepaths, in which case you might have "constants" that shouldn't change regardless of the filepath. like destBase or cwd etc.

.propstring( name, propstring )

Store a named prop-string:

strings.propstring('foo', ':alpha/:beta/:gamma');

.parser( name, replacements )

Define a named parser to be used against any given prop-string.

Params:

• name (String): the name of the parser
• replacements (object|array): the replacement patterns to use, this is the logic for the parser. Replacement patterns consist of the following properties:
  • pattern (regex|string): the pattern to be replaced
  • replacement (string|function): the actual replacement to use. This is a string value or function used to replace or tranform the prop-strings. Also, in replacement functions this is the given context.

Example:

strings.parser('foo', {
  pattern: /a/g,    // find all occurences of `a`
  replacement: 'b'  // and replace them with `b`
});

Or using a function:

strings.parser('foo', {
  pattern: /a/g, // find all occurences of `a`
  replacement: function(match) {
    // and replace them with uppercase `A`
    return match.toUpperCase();
  }
});

.template( propstring, groups, context )

1. process a prop-string, using
2. an object or array of replacement patterns, with
3. context from the given object

strings.template('{foo}/{bar}/{baz}/index.html', ['path'], context);
strings.template('{{foo}}/{{bar}}/{{baz}}/index.html', ['path'], context);
strings.template(':foo/:bar/:baz/index.html', ['path'], context);
strings.template(':foo/:bar/:baz/index.html', [{
  pattern: ':dirname',
  replacement: function () {
    return path.dirname(this.filepath);
  }
}], context);

.process( propstring, parsers, context )

Process the named propstring using a named collection of replacement patterns, and a context.

Params:

• propstring {String}: Named template used for building the final string
• name {String}: Name of replacement group to use for building the final string
• context {Object}: Optional Object to bind to replacment function as this

strings.process('foo', 'a', context);
// or
strings.process('foo', ['a', 'b']);

.group( name, propstring, parsers )

Store a named group of propstring/parser mappings.

Params:

• name {String} the name of the group to store
• propstring {String}: the propstring to use
• parsers {String|Array}: name or array of names of parsers to use.

strings.group('mapA', 'foo', ['a', 'b', 'c']);
strings.group('mapB', 'foo', ['d', 'e', 'slugify']);

.run( group, context )

Run the named group using the given context.

• group {String}: The name of the group to use
• context {Object}: Optional Object to bind to replacment function as this

strings.run('group-foo', context);

Authors

Brian Woodward

• github/doowb
• twitter/doowb

Jon Schlinkert

• github/jonschlinkert
• twitter/jonschlinkert

License

Copyright (c) 2014 Brian Woodward, contributors.
Released under the MIT license

This file was generated by verb-cli on May 21, 2014.