|
| 1 | +# Path-to-RegExp |
| 2 | + |
| 3 | +Turn an Express-style path string such as `/user/:name` into a regular expression. |
| 4 | + |
| 5 | +[![NPM version][npm-image]][npm-url] |
| 6 | +[![Build status][travis-image]][travis-url] |
| 7 | +[![Test coverage][coveralls-image]][coveralls-url] |
| 8 | + |
| 9 | +## Installation |
| 10 | + |
| 11 | +``` |
| 12 | +npm install path-to-regexp --save |
| 13 | +``` |
| 14 | + |
| 15 | +## Usage |
| 16 | + |
| 17 | +```javascript |
| 18 | +var pathToRegexp = require('path-to-regexp'); |
| 19 | + |
| 20 | +// pathToRegexp(path, keys, options); |
| 21 | +``` |
| 22 | + |
| 23 | +- **path** A string in the express format, an array of strings, or a regular expression. |
| 24 | +- **keys** An array to be populated with the keys present in the url. |
| 25 | +- **options** |
| 26 | + - **sensitive** When `true` the route will be case sensitive. (default: `false`) |
| 27 | + - **strict** When `false` the trailing slash is optional. (default: `false`) |
| 28 | + - **end** When `false` the path will match at the beginning. (default: `true`) |
| 29 | + |
| 30 | +```javascript |
| 31 | +var keys = []; |
| 32 | +var re = pathToRegexp('/foo/:bar', keys); |
| 33 | +// re = /^\/foo\/([^\/]+?)\/?$/i |
| 34 | +// keys = [{ name: 'bar', delimiter: '/', repeat: false, optional: false }] |
| 35 | +``` |
| 36 | + |
| 37 | +### Parameters |
| 38 | + |
| 39 | +The path has the ability to define parameters and automatically populate the keys array. |
| 40 | + |
| 41 | +#### Named Parameters |
| 42 | + |
| 43 | +Named parameters are defined by prefixing a colon to the parameter name (`:foo`). By default, this parameter will match up to the next path segment. |
| 44 | + |
| 45 | +```js |
| 46 | +var re = pathToRegexp('/:foo/:bar', keys); |
| 47 | +// keys = [{ name: 'foo', ... }, { name: 'bar', ... }] |
| 48 | + |
| 49 | +re.exec('/test/route'); |
| 50 | +//=> ['/test/route', 'test', 'route'] |
| 51 | +``` |
| 52 | + |
| 53 | +#### Suffixed Parameters |
| 54 | + |
| 55 | +##### Optional |
| 56 | + |
| 57 | +Parameters can be suffixed with a question mark (`?`) to make the entire parameter optional. This will also make any prefixed path delimiter optional (`/` or `.`). |
| 58 | + |
| 59 | +```js |
| 60 | +var re = pathToRegexp('/:foo/:bar?', keys); |
| 61 | +// keys = [{ name: 'foo', ... }, { name: 'bar', delimiter: '/', optional: true, repeat: false }] |
| 62 | + |
| 63 | +re.exec('/test'); |
| 64 | +//=> ['/test', 'test', undefined] |
| 65 | + |
| 66 | +re.exec('/test/route'); |
| 67 | +//=> ['/test', 'test', 'route'] |
| 68 | +``` |
| 69 | + |
| 70 | +##### Zero or more |
| 71 | + |
| 72 | +Parameters can be suffixed with an asterisk (`*`) to denote a zero or more parameter match. The prefixed path delimiter is also taken into account for the match. |
| 73 | + |
| 74 | +```js |
| 75 | +var re = pathToRegexp('/:foo*', keys); |
| 76 | +// keys = [{ name: 'foo', delimiter: '/', optional: true, repeat: true }] |
| 77 | + |
| 78 | +re.exec('/'); |
| 79 | +//=> ['/', undefined] |
| 80 | + |
| 81 | +re.exec('/bar/baz'); |
| 82 | +//=> ['/bar/baz', 'bar/baz'] |
| 83 | +``` |
| 84 | + |
| 85 | +##### One or more |
| 86 | + |
| 87 | +Parameters can be suffixed with a plus sign (`+`) to denote a one or more parameters match. The prefixed path delimiter is included in the match. |
| 88 | + |
| 89 | +```js |
| 90 | +var re = pathToRegexp('/:foo+', keys); |
| 91 | +// keys = [{ name: 'foo', delimiter: '/', optional: false, repeat: true }] |
| 92 | + |
| 93 | +re.exec('/'); |
| 94 | +//=> null |
| 95 | + |
| 96 | +re.exec('/bar/baz'); |
| 97 | +//=> ['/bar/baz', 'bar/baz'] |
| 98 | +``` |
| 99 | + |
| 100 | +#### Custom Match Parameters |
| 101 | + |
| 102 | +All parameters can be provided a custom matching regexp and override the default. Please note: Backslashes need to be escaped in strings. |
| 103 | + |
| 104 | +```js |
| 105 | +var re = pathToRegexp('/:foo(\\d+)', keys); |
| 106 | +// keys = [{ name: 'foo', ... }] |
| 107 | + |
| 108 | +re.exec('/123'); |
| 109 | +//=> ['/123', '123'] |
| 110 | + |
| 111 | +re.exec('/abc'); |
| 112 | +//=> null |
| 113 | +``` |
| 114 | + |
| 115 | +#### Unnamed Parameters |
| 116 | + |
| 117 | +It is possible to write an unnamed parameter that is only a matching group. It works the same as a named parameter, except it will be numerically indexed. |
| 118 | + |
| 119 | +```js |
| 120 | +var re = pathToRegexp('/:foo/(.*)', keys); |
| 121 | +// keys = [{ name: 'foo', ... }, { name: '0', ... }] |
| 122 | + |
| 123 | +re.exec('/test/route'); |
| 124 | +//=> ['/test/route', 'test', 'route'] |
| 125 | +``` |
| 126 | + |
| 127 | +## Compatibility with Express <= 4.x |
| 128 | + |
| 129 | +Path-To-RegExp breaks compatibility with Express <= 4.x in a few ways: |
| 130 | + |
| 131 | +* RegExp special characters can now be used in the regular path. E.g. `/user[(\\d+)]` |
| 132 | +* All RegExp special characters can now be used inside the custom match. E.g. `/:user(.*)` |
| 133 | +* No more support for asterisk matching - use an explicit parameter instead. E.g. `/(.*)` |
| 134 | +* Parameters can have suffixes that augment meaning - `*`, `+` and `?`. E.g. `/:user*` |
| 135 | +* Strings aren't interpreted as literal regexp strings - no more non-capturing groups, lookaheads, lookbehinds or nested matching groups (but you can still pass a regexp manually) |
| 136 | + |
| 137 | +## Live Demo |
| 138 | + |
| 139 | +You can see a live demo of this library in use at [express-route-tester](http://forbeslindesay.github.com/express-route-tester/). |
| 140 | + |
| 141 | +## License |
| 142 | + |
| 143 | +MIT |
| 144 | + |
| 145 | +[npm-image]: https://img.shields.io/npm/v/path-to-regexp.svg?style=flat |
| 146 | +[npm-url]: https://npmjs.org/package/path-to-regexp |
| 147 | +[travis-image]: https://img.shields.io/travis/component/path-to-regexp.svg?style=flat |
| 148 | +[travis-url]: https://travis-ci.org/component/path-to-regexp |
| 149 | +[coveralls-image]: https://img.shields.io/coveralls/component/path-to-regexp.svg?style=flat |
| 150 | +[coveralls-url]: https://coveralls.io/r/component/path-to-regexp?branch=master |
0 commit comments