Matchstick

A NodeJS module that converts string patterns into regular expressions. It can also tokenize and perform string replacement. It's useful for route handling or simple template systems.

Installation

Install using NPM.

$ npm install matchstick

You may require sudo depending on your local configuration.

Usage

Require matchstick at the top of your script.

var matchstick = require('matchstick');

Arguments

• pattern is a string representing a search
• mode is a string that tells matchstick how to interpret the pattern
  • strict: Exact match
  • static: Exact match with optional trailing slash (for URLs)
  • wildcard: Asterisks match any character(s) e.g. /path/*/
  • template: Curly brace tokens match any character(s) e.g. /path/{token}/
  • symbolic: Ruby-style symbols with leading colons match any character(s) e.g. /path/:token/
  • regexp: Convert into a true RegExp Object e.g. ^\/path\/$
• modifiers is a string containing one (or none) of any of the following characters
  • i: Case insensitive
  • g: Global match
  • m: Multiline matching

Example

Matchstick is a constructor that returns a fresh instance so you don't need the new keyword.

> var ms = matchstick('/project/{pid}/task/{tid}', 'template');
> ms
 
  {
  	pattern  : '/project/{pid}/task/{tid}',
  	mode     : 'template',
  	tokens   : [
  		'pid',
  		'tid'
  	],
  	regexp  : /^\/project\/(.*)\/task\/(.*)$/,
  	matches : null,
  	match   : function() {},
  	stick : function() {}
  }

Set it to a variable and use the match method to return true or false

> var ms = matchstick('/path', 'static')
> ms.match('/path/')
 
  true

...or evaluate it directly.

> var str = '/path/';
> if( matchstick('/path', 'static' ).match(str) ) { 'match!' }
 
  'match!'

Dynamic Properties

Tokens

Template and symbolic modes populate the tokens property with an array representing the token names in the other they appear in the pattern.

> var ms = matchstick('/project/{pid}/task/{tid}', 'template')
> ms.tokens
 
  ['pid', 'tid']

Matches

The matches property will always contain the lastest results of a match() call.

Wildcard and RegExp modes populate the matches property with an array of strings representing the order in which they are captured.

> var ms = matchstick('/project/{pid}/task/{tid}', 'template')
> ms.match('/project/123/task/abc');
> ms.matches
 
  ['123', 'abc']	

Template and symbolic modes populate the matches property with an object with tokens and strings as key/value pairs.

> var ms = matchstick('/project/{pid}/task/{tid}', 'template')
> ms.match('/project/123/task/abc');
> ms.matches
    
  {pid:'123', tid:'abc'}

RegExp

All patterns populate the regexp property which you can access directly if needed.

> var ms = matchstick('^\/path\/$', 'regexp', 'g')
> ms.regexp
 
  /^/path/$/g

Methods

Match

Static mode

> matchstick('/path/', 'static').match('/PATH/')
 
  true

Wildcard mode

> matchstick('/path/*/', 'wildcard').match('/path/something/')
 
  true

Regexp mode

> matchstick('^\/path\/$', 'regexp').match('/path/')
 
  true

Stick

Template Mode

> var ms = matchstick('/project/{pid}/task/{tid}', 'pattern');
> ms.stick({pid:'123', tid:'abc'});
 
  /project/123/task/abc

Symbolic Mode

> var ms = matchstick('/project/:pid/task/:tid/action/:aid', 'pattern');
> ms.stick({pid:'123', tid:'abc'});
 
  /project/123/task/abc/action/

Note: Unused tokens are removed

Development

Clone the github repo, cd to the directory, install the dependencies with NPM, and run gulp.

$ cd matchstick
$ npm install
$ gulp

Gulp will watch the lib and test directories and re-run the tests for you. gulp will also lint the files and report test coverage.

If you submit a pull request, please follow these guidelines:

1. Use separate PR's for individual features or bugs
2. Keep test coverage at 100%
3. Update the documentation in this README