strings ![NPM version](https://badge.fury.io/js/strings.png)
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 install strings --save
Basics
Main Strings concepts:
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:
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 parserreplacements
(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 replacedreplacement
(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,
replacement: 'b'
});
Or using a function:
strings.parser('foo', {
pattern: /a/g,
replacement: function(match) {
return match.toUpperCase();
}
});
.template( propstring, groups, context )
- process a prop-string, using
- an object or array of replacement patterns, with
- 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 stringname
{String}: Name of replacement group to use for building the final stringcontext
{Object}: Optional Object to bind to replacment function as this
strings.process('foo', 'a', context);
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 storepropstring
{String}: the propstring to useparsers
{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 usecontext
{Object}: Optional Object to bind to replacment function as this
strings.run('group-foo', context);
Authors
Brian Woodward
Jon Schlinkert
License
Copyright (c) 2014 Brian Woodward, contributors.
Released under the MIT license
This file was generated by verb-cli on May 21, 2014.