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. You may require sudo depending on your local configuration.

$ npm install matchstick

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

Tests

Install the global dependancies with sudo permissions.

$ sudo npm install -g mocha
$ sudo npm install -g should

Run mocha directly to see the test results.

$ cd matchstick
$ mocha