metacarattere v2.2.0

metacarattere

metacarattere is a small matcher for URLs with colon placeholders.

• Installation
• Usage
  • Loading it
  • metacarattere() - The exposed function
  • .match() - Match an URL
  • .parse() - Parse an URL
  • .build() - Replace placeholders
  • .getPattern() - Get the pattern
  • .getPlaceholders() - Get the placeholders
  • .getExpression() - Get the compiled expression
• Naming
• Try it

Installation

You can install metacarattere for your node.js (or CommonJS in general) project with npm:

npm install metacarattere

You also can install it with bower for your front-end (or AMD in general) project:

bower install metacarattere

Usage

Loading it

Depending on your project structure, metacarattere is exposed in different ways.

• If you are in a browser environment without any module loader a global metacarattere function will be exposed (as window.metacarattere).
• If you use a module loader such as require.js in your front-end application, you can load metacarattere like any other module.
• If you are in a node.js environment, metacarattere can be required as usual.

The exposed function

metacarattere is a constructor function that takes a pattern.

var metacarattere = function(pattern) { /*...*/ }

If no pattern is given, the created object will not match any URL so that matches() will always return false and parse() will always return null. However, it won't throw any exception.

Match an URL

The matches() function can be used to test if the given URL matches the object's pattern.

var metacarattere = require('metacarattere');

var pattern = new metacarattere("/api/:version/:collection/:store/:resource");

pattern.matches('/api/v1/users/max/card');          // true
pattern.matches('/api/v2/store/users/max/card');    // false
pattern.matches();                                  // false
pattern.matches('');                                // false

Parse an URL

The parse() function takes an URL and returns an object with key-value-mappings if the URL matches the pattern. Otherwise, null is returned.

var metacarattere = require('metacarattere');

var pattern = new metacarattere("/api/:version/:collection/:store/:resource");
var pretty = function(obj) { return JSON.stringify(obj, null, 4); };
var values;

values = pattern.parse('/api/v1/users/max/card');
console.log( pretty(values) );
/*
{
    "version": "v1",
    "collection": "users",
    "store": "max",
    "resource": "card"
}
*/

values = pattern.parse('/api/v1/users/max');
console.log( values );
/*
null
*/

values = pattern.parse('/api/v7.9/cloud/files/database');
console.log( pretty(values) );
/*
{
    "version": "v7.9",
    "collection": "cloud",
    "store": "files",
    "resource": "database"
}
*/

Replace placeholders

If you need to replace placeholders of the pattern with values you can use the .build() function. Given an object with key-value-mappings it will return a new pattern with replaced values. This also works with partly replacements.

var m     = new metacarattere('/:service/:name/:version');
var api   = new metacarattere( m.build({'service':'api'}) );
var apiV2 = new metacarattere( api.build({'version': 'v2'}) );

api.getPattern();   // /api/:name/:version
apiV2.getPattern(); // /api/:name/:v2

.build() will return null if the pattern is invalid or if you do not submit a valid object.

Get the pattern

The original pattern given to the constructor function can be retrieved using the getPattern() function.

new metacarattere('/api/:version/:document').getPattern();  // '/api/:version/:document'
new metacarattere().getPattern();   // undefined
new metacarattere(null).getPattern();   // null

Get the placeholders

The placeholders defined in the pattern can be accessed using getPlaceholders().

new metacarattere('/api/:version/:document').getPlaceholders();  // ['version','document']
new metacarattere().getPlaceholders();  // [ ]
new metacarattere(null).getPlaceholders();   // [ ]

Get the compiled expression

If it is required to get the compiled regular expression for the pattern the getExpression() can be used to get it.

new metacarattere('/:version/:key/:abc').getExpression();       // ^/([^\/]+)/([^\/]+)/([^\/]+)$
new metacarattere('').getExpression();  // ^$
new metacarattere().getExpression();    // ^(?!)$

Naming

metacarattere is the Italian word for Wild card.

Try it

There is a JSBin that automatically uses the latest version of metacarattere and can be used to play around with it.