Easily replace and transform :props in 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!


npm install strings --save


bower install strings --save

Strings constructor method

Create a new instance of Strings, optionally passing a default context to use.


var strings = new Strings({destbase: '_gh_pages/'});
  • return {Object} Instance of a Strings object

Set or get a named propstring.

strings.propstring(name, propstring)


strings.propstring('url', ':base/blog/posts/:basename:ext');
  • name {String}
  • propstring {String}
  • return {Strings} to allow chaining

Set or get a string or regex pattern to be used for matching.

strings.pattern(name, pattern, flags);


strings.pattern('anyProp', ':([\\w]+)');
  • name {String}: The name of the stored pattern.
  • pattern {String|RegExp|Function}: The pattern to use for matching.
  • flags {String}: Optionally pass RegExp flags to use.
  • return {Strings} to allow chaining

Return the RegExp source from a stored pattern.



strings.pattern('foo', {re: /:([\\w]+)/gm});
//=> ':([\\w]+)' 
  • name {String}: The name of the stored pattern.

Set or get a replacement pattern. Replacement patterns can be a regular expression, string or function.

strings.replacement(name, replacement)


strings.replacement('prop', function(match) {
  return match.toUpperCase();
  • name {String}
  • replacement {String|Function}: The replacement to use when patterns are matched.
  • return {Strings} to allow chaining

Set a parser that can later be used to parse any given string.

strings.parser (name, replacements)


Pass an object:

strings.parser('prop', {
  pattern: /:([\\w]+)/,
  replacementfunction(match) {
    return match.toUpperCase();

Or an array

strings.parser('prop', [
    pattern: 'a',
    replacement: 'b'
    pattern: 'c',
    replacement: 'd'
  • name {String}
  • arr {Object|Array}: Object or array of replacement patterns to associate.
  • return {Strings} to allow chaining

Get an array of stored parsers by passing a parser name or array of parser names.



// pass an array of parser names 
strings.parsers(['a', 'b', 'c']);
// or a string 

Using parsers like this:


is just sugar for:

var parsers = [

For an example, see markdown-symbols, which uses this to store replacement patterns for custom markdown symbols.

  • parsers {String|Array}: string or array of parsers to get.
  • return {Array}

Extend a parser with additional replacement patterns. Useful if you're using an external module for replacement patterns and you need to extend it.

strings.extendParser(parser, replacements)


strings.extendParser('prop', {
  pattern: /:([\\w]+)/,
  replacementfunction(str) {
    return str.toUpperCase();
  • name {String}: name of the parser to extend.
  • arr {Object|Array}: array of replacement patterns to store with the given name.
  • pattern {String|RegExp}
  • replacement {String|Function}
  • return {Strings} to allow chaining

Set or get a reusable Strings template, consisting of a propstring and an array of parsers.

Templates are useful since they can be stored and then later used with any context.

strings.template(name, propstring, parsers);


strings.template('abc', ':a/:b/:c', ['a', 'b', 'c']);
// or use a named propstring 
strings.template('abc', 'foo', ['a', 'b', 'c']);
                     here ^
  • name {String}
  • propstring {String}
  • parsers {Array}: Names of the parsers to use with the template.
  • return {Strings} to allow chaining

Replace :propstrings with the real values.

strings.replace(str, context)


strings.replace(':a/:b/:c', {
  a: 'foo',
  b: 'bar',
  c: 'baz'
//=> foo/bar/baz 
  • str {String}: The string with :propstrings to replace.
  • context {String}: The object with replacement properties.
  • return {Strings} to allow chaining

Directly process the given prop-string, using a named replacement pattern or array of named replacement patterns, with the given context.

strings.process(str, parsers, context)


Pass a propstring and the parsers to use:

// define some parsers to do simple key-value replacements 
strings.parser('a', {'{foo}': 'AAA'});
strings.parser('b', {'{bar}': 'BBB'});
strings.parser('c', {'{baz}': 'CCC'});
console.log(strings.process('{foo}/{bar}/{baz}', ['a', 'b', 'c']));
// => 'AAA/BBB/CCC' 
  • str {String}: the string to process
  • parsers {String|Object|Array}: named parsers or parser objects to use when processing.
  • context {Object}: context to use. optional if a global context is passed.
  • return {String}

Process a template with the given context., context)

Example'blogTemplate', {
  dest: '_gh_pages',
  basename: '2014-07-01-post',
  ext: '.html'
  • template {String}: The template to process.
  • context {Object}: Optional context object, to bind to replacement function as this
  • return {String}

Jon Schlinkert

Brian Woodward

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

This file was generated by verb-cli on July 03, 2014.