metacarattere
metacarattere is a small matcher for URLs with colon placeholders.
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 (aswindow.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 { /*...*/ }
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 = ; var pattern = "/api/:version/:collection/:store/:resource"; pattern; // truepattern; // falsepattern; // falsepattern; // 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 = ; var pattern = "/api/:version/:collection/:store/:resource";var { return JSON; };var values; values = pattern;console;/*{ "version": "v1", "collection": "users", "store": "max", "resource": "card"}*/ values = pattern;console;/*null*/ values = pattern;console;/*{ "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 = '/:service/:name/:version';var api = m ;var apiV2 = api ; api; // /api/:name/:versionapiV2; // /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.
'/api/:version/:document'; // '/api/:version/:document'; // undefinednull; // null
Get the placeholders
The placeholders defined in the pattern can be accessed using getPlaceholders()
.
'/api/:version/:document'; // ['version','document']; // [ ]null; // [ ]
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.
'/:version/:key/:abc'; // ^/([^\/]+)/([^\/]+)/([^\/]+)$''; // ^$; // ^(?!)$
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.