# metacarattere

> A small URL pattern matcher

Latest version **2.2.0** (published 2015-03-23) · MIT license · 0 weekly downloads

## Install

```sh
npm install metacarattere
pnpm add metacarattere
yarn add metacarattere
bun add metacarattere
```

## Health

**Score 15/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 2.2.0 |
| Published | 2015-03-23 |
| First published | 2015-03-13 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 0 |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Author | dak0rn |
| Maintainers | dak0rn |
| Keywords | url, pattern, matching |

## Links

- npm: https://www.npmjs.com/package/metacarattere
- Repository: https://dak0rn@github.com/dak0rn/metacarattere
- Homepage: https://github.com/dak0rn/metacarattere
- Issues: https://github.com/dak0rn/metacarattere/issues
- npm.io page: https://npm.io/package/metacarattere

## Alternatives

- [base64url](https://npm.io/package/base64url.md) — 6.1M weekly downloads
- [get-installed-path](https://npm.io/package/get-installed-path.md) — 502.9K weekly downloads
- [@uppy/url](https://npm.io/package/@uppy/url.md) — 185.8K weekly downloads
- [@d3fc/d3fc-shape](https://npm.io/package/@d3fc/d3fc-shape.md) — 16.2K weekly downloads
- [localizer](https://npm.io/package/localizer.md) — 226 weekly downloads

## Recent versions

- 2.2.0 (latest) — 2015-03-23
- 2.1.0 — 2015-03-19
- 1.0.0 — 2015-03-13

## README

# metacarattere
metacarattere is a small matcher for URLs with colon placeholders.


- [Installation](#installation)
- [Usage](#usage)
    - [Loading it](#loading-it)
    - [`metacarattere()` - The exposed function](#the-exposed-function)
    - [`.match()` - Match an URL](#match-an-url)
    - [`.parse()` - Parse an URL](#parse-an-url)
    - [`.build()` - Replace placeholders](#replace-placeholders)
    - [`.getPattern()` - Get the pattern](#get-the-pattern)
    - [`.getPlaceholders()` - Get the placeholders](#get-the-placeholders)
    - [`.getExpression()` - Get the compiled expression](#get-the-compiled-expression)
- [Naming](#naming)
- [Try it](#try-it)

## Installation

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

```shell
npm install metacarattere
```

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

```shell
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.

```javascript
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.

```javascript
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.

```javascript
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.

```javascript
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.

```javascript
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()`.

```javascript
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.

```javascript
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](http://jsbin.com/setuzu/edit?js,console) that automatically
uses the latest version of metacarattere and can be used to play around with it.

---
_Source: https://npm.io/package/metacarattere · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._