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

npm

npm install strings --save

bower

bower install strings --save

API

Strings

Strings constructor method

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

Example

var strings = new Strings({destbase: '_gh_pages/'});

• return {Object} Instance of a Strings object

.propstring

Set or get a named propstring.

strings.propstring(name, propstring)

Example

strings.propstring('url', ':base/blog/posts/:basename:ext');

• name {String}
• propstring {String}
  
• return {Strings} to allow chaining

.pattern

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

strings.pattern(name, pattern, flags);

Example

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

.source

Return the RegExp source from a stored pattern.

strings.source(name);

Example

strings.pattern('foo', {re: /:([\\w]+)/gm});
strings.source('foo');
//=> ':([\\w]+)'

• name {String}: The name of the stored pattern.
  

.replacement

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

strings.replacement(name, replacement)

Example

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

.parser

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

strings.parser (name, replacements)

Example

Pass an object:

strings.parser('prop', {
  pattern: /:([\\w]+)/,
  replacement: function(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

.parsers

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

strings.parsers(array)

Example

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

// or a string
strings.parsers('a');

Using parsers like this:

strings.parsers([
  'jumbotron',
  'labels',
  'progress',
  'glyphicons',
  'badges',
  'alerts',
  'newlines'
]);

is just sugar for:

var parsers = [
  strings.parser('jumbotron'),
  strings.parser('labels'),
  strings.parser('progress'),
  strings.parser('glyphicons'),
  strings.parser('badges'),
  strings.parser('alerts'),
  strings.parser('newlines'),
];

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}

.extendParser

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)

Example

strings.extendParser('prop', {
  pattern: /:([\\w]+)/,
  replacement: function(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

.template

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);

Example

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

Replace :propstrings with the real values.

strings.replace(str, context)

Example

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

.process

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)

Examples:

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}

.run

Process a template with the given context.

strings.run(template, context)

Example

strings.run('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}

Authors

Jon Schlinkert

• github/jonschlinkert
• twitter/jonschlinkert

Brian Woodward

• github/doowb
• twitter/doowb

License

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

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