# Class UrlMatcher

Matches URLs against patterns.

Matches URLs against patterns and extracts named parameters from the path or the search part of the URL.

A URL pattern consists of a path pattern, optionally followed by '?' and a list of search (query) parameters. Multiple search parameter names are separated by '&'. Search parameters do not influence whether or not a URL is matched, but their values are passed through into the matched parameters returned by [[UrlMatcher.exec]].

- Path parameters are defined using curly brace placeholders (`/somepath/{param}`) or colon placeholders (`/somePath/:param`).

- A parameter RegExp may be defined for a param after a colon (`/somePath/{param:[a-zA-Z0-9]+}`) in a curly brace placeholder. The regexp must match for the url to be matched. Should the regexp itself contain curly braces, they must be in matched pairs or escaped with a backslash.

Note: a RegExp parameter will encode its value using either [[ParamTypes.path]] or [[ParamTypes.query]].

- Custom parameter types may also be specified after a colon (`/somePath/{param:int}`) in curly brace parameters. See [[UrlMatcherFactory.type]] for more information.

- Catch-all parameters are defined using an asterisk placeholder (`/somepath/*catchallparam`). A catch-all * parameter value will contain the remainder of the URL.

Parameter names may contain only word characters (latin letters, digits, and underscore) and must be unique within the pattern (across both path and search parameters). A path parameter matches any number of characters other than '/'. For catch-all placeholders the path parameter matches any number of characters.

Examples:

- `'/hello/'` - Matches only if the path is exactly '/hello/'. There is no special treatment for trailing slashes, and patterns have to match the entire path, not just a prefix.
- `'/user/:id'` - Matches '/user/bob' or '/user/1234!!!' or even '/user/' but not '/user' or '/user/bob/details'. The second path segment will be captured as the parameter 'id'.
- `'/user/{id}'` - Same as the previous example, but using curly brace syntax.
- `'/user/{id:[^/]*}'` - Same as the previous example.
- `'/user/{id:[0-9a-fA-F]{1,8}}'` - Similar to the previous example, but only matches if the id parameter consists of 1 to 8 hex digits.
- `'/files/{path:.*}'` - Matches any URL starting with '/files/' and captures the rest of the path into the parameter 'path'.
- `'/files/*path'` - ditto.
- `'/calendar/{start:date}'` - Matches "/calendar/2014-11-12" (because the pattern defined in the built-in `date` ParamType matches `2014-11-12`) and provides a Date object in $stateParams.start

- Defined in router/url/url-matcher.js:94
- Defined in router/url/url-matcher.js:533

#####
Index

### Constructors

constructor

### Properties

_cache
_children
_compiled
_params
_segments
config
pattern
nameValidator

### Methods

_getDecodedParamValue
append
exec
format
isRoot
parameter
parameters
toString
validates
compare
encodeDashes
pathSegmentsAndParams
queryParams

##
Constructors

### constructor

- new UrlMatcher(pattern, paramTypes, paramFactory, config): UrlMatcher

- #### Parameters

  - pattern: any

    The pattern to compile into a matcher.

  - paramTypes: any

    The [[ParamTypes]] registry

  - paramFactory: any

    A [[ParamFactory]] object

  - config: any

    A [[UrlMatcherCompileConfig]] configuration object

  #### Returns UrlMatcher

  - Defined in router/url/url-matcher.js:184

##
Properties

### _cache

_cache: {
path: UrlMatcher[];
}

- Defined in router/url/url-matcher.js:185

### _children

_children: any[]

- Defined in router/url/url-matcher.js:187

### _compiled

_compiled: any[]

- Defined in router/url/url-matcher.js:193
- Defined in router/url/url-matcher.js:283

### _params

_params: any[]

- Defined in router/url/url-matcher.js:189

### _segments

_segments: any[]

- Defined in router/url/url-matcher.js:191

### config

config: any

- Defined in router/url/url-matcher.js:194

### pattern

pattern: any

- Defined in router/url/url-matcher.js:195

### `Static` nameValidator

nameValidator: RegExp

- Defined in router/url/url-matcher.js:533

##
Methods

### _getDecodedParamValue

- _getDecodedParamValue(value, param): any

- #### Parameters

  - value: any
  - param: any

  #### Returns any

  - Defined in router/url/url-matcher.js:311

### append

- append(url): any

- Creates a new concatenated UrlMatcher

  Builds a new UrlMatcher by appending another UrlMatcher to this one.

  #### Parameters

  - url: any

    A `UrlMatcher` instance to append as a child of the current `UrlMatcher`.

  #### Returns any

  - Defined in router/url/url-matcher.js:294

### exec

- exec(path, search?, hash): {
  #: any;
  }

- Tests the specified url/path against this matcher.

  Tests if the given url matches this matcher's pattern, and returns an object containing the captured parameter values. Returns null if the path does not match.

  The returned object contains the values of any search parameters that are mentioned in the pattern, but their value may be null if they are not present in `search`. This means that search parameters are always treated as optional.

  #### Example:

      new UrlMatcher('/user/{id}?q&r').exec('/user/bob', {
        x: '1', q: 'hello'
      });
      // returns { id: 'bob', q: 'hello', r: null }

  #### Parameters

  - path: any

    The URL path to match, e.g. `$location.path()`.

  - search: {} = {}

    URL search parameters, e.g. `$location.search()`.

  - hash: any

    URL hash e.g. `$location.hash()`.

  #### Returns {
  #: any;
  }

  The captured parameter values.

  - ##### #: any

  - Defined in router/url/url-matcher.js:342

### format

- format(values?): string

- Given a set of parameter values, creates a URL from this UrlMatcher.

  Creates a URL that matches this pattern by substituting the specified values for the path and search parameters.

  #### Example:

      new UrlMatcher('/user/{id}?q').format({ id:'bob', q:'yes' });
      // returns '/user/bob?q=yes'

  #### Parameters

  - values: {} = {}

    the values to substitute for the parameters in this pattern.

  #### Returns string

  the formatted URL (path and optionally search part).

  - Defined in router/url/url-matcher.js:459

### isRoot

- isRoot(): boolean

- #### Returns boolean

  - Defined in router/url/url-matcher.js:304

### parameter

- parameter(id, opts?): any
- `Internal`

  Returns a single parameter from this UrlMatcher by id

  #### Parameters

  - id: any
  - opts: {} = {}

  #### Returns any

  - Defined in router/url/url-matcher.js:411

### parameters

- parameters(opts?): Param[]
- `Internal`

  Returns all the [[Param]] objects of all path and search parameters of this pattern in order of appearance.

  #### Parameters

  - opts: {} = {}

  #### Returns Param[]

  An array of [[Param]] objects. Must be treated as read-only. If the pattern has no parameters, an empty array is returned.

  - Defined in router/url/url-matcher.js:399

### toString

- toString(): any

- Returns the input pattern string

  #### Returns any

  - Defined in router/url/url-matcher.js:308

### validates

- validates(params): any

- Validates the input parameter values against this UrlMatcher

  Checks an object hash of parameters to validate their correctness according to the parameter types of this `UrlMatcher`.

  #### Parameters

  - params: any

    The object hash of parameters to validate.

  #### Returns any

  Returns `true` if `params` validates, otherwise `false`.

  - Defined in router/url/url-matcher.js:433

### `Static` compare

- compare(a, b): number

- Compare two UrlMatchers

  This comparison function converts a UrlMatcher into static and dynamic path segments. Each static path segment is a static string between a path separator (slash character). Each dynamic segment is a path parameter.

  The comparison function sorts static segments before dynamic ones.

  #### Parameters

  - a: any
  - b: any

  #### Returns number

  - Defined in router/url/url-matcher.js:125

### `Static` encodeDashes

- encodeDashes(str): string

- #### Parameters

  - str: any

  #### Returns string

  - Defined in router/url/url-matcher.js:95

### `Static` pathSegmentsAndParams

- pathSegmentsAndParams(matcher): any
- `Internal`

  Given a matcher, return an array with the matcher's path segments and path params, in order

  #### Parameters

  - matcher: any

  #### Returns any

  - Defined in router/url/url-matcher.js:103

### `Static` queryParams

- queryParams(matcher): any
- `Internal`

  Given a matcher, return an array with the matcher's query params

  #### Parameters

  - matcher: any

  #### Returns any

  - Defined in router/url/url-matcher.js:113