# Class: UrlMatcher

## UrlMatcher

#### new UrlMatcher(pattern)

  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 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 exec.

  Path parameter placeholders can be specified using simple colon/catch-all syntax or curly brace syntax, which optionally allows a regular expression for the parameter to be specified:

  - ':' name - colon placeholder
  - '*' name - catch-all placeholder
  - '{' name '}' - curly placeholder
  - '{' name ':' regexp '}' - curly placeholder with regexp. Should the regexp itself contain curly braces, they must be in matched pairs or escaped with a backslash.

  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). For colon placeholders or curly placeholders without an explicit regexp, 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.

  ##### Parameters:

  Name | Type | Description
  --- | --- | ---
  `pattern` | string | the pattern to compile into a matcher.

  ##### Properties:

  Name | Type | Description
  --- | --- | ---
  `prefix` | string | A static prefix of this pattern. The matcher guarantees that any URL matching this matcher (i.e. any string for which exec() returns non-null) will start with this prefix.

  Source:
    - urlMatcherFactory.js, line 44

### Methods

#### concat(pattern) → {UrlMatcher}

  Returns a new matcher for a pattern constructed by appending the path part and adding the search parameters of the specified pattern to this pattern. The current pattern is not modified. This can be understood as creating a pattern for URLs that are relative to (or suffixes of) the current pattern.

  ### Example

  The following two matchers are equivalent:

      new UrlMatcher('/user/{id}?q').concat('/details?date');
      new UrlMatcher('/user/{id}/details?q&date');

  ##### Parameters:

  Name | Type | Description
  --- | --- | ---
  `pattern` | string | The pattern to append.

  Source:
    - urlMatcherFactory.js, line 128

  ##### Returns:

  A matcher for the concatenated pattern.

  Type
    UrlMatcher

#### exec(path, searchParams) → {Object}

  Tests the specified path against this matcher, and returns an object containing the captured parameter values, or 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 `searchParams`. 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:

  Name | Type | Description
  --- | --- | ---
  `path` | string | The URL path to match, e.g. `$location.path()`.
  `searchParams` | Object | URL search parameters, e.g. `$location.search()`.

  Source:
    - urlMatcherFactory.js, line 156

  ##### Returns:

  The captured parameter values.

  Type
    Object

#### format(values) → {string}

  Creates a URL that matches this pattern by substituting the specified values for the path and search parameters. Null values for path parameters are treated as empty strings.

  ### Example

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

  ##### Parameters:

  Name | Type | Description
  --- | --- | ---
  `values` | Object | the values to substitute for the parameters in this pattern.

  Source:
    - urlMatcherFactory.js, line 193

  ##### Returns:

  the formatted URL (path and optionally search part).

  Type
    string

#### parameters() → {Array.<string>}

  Returns the names of all path and search parameters of this pattern in an unspecified order.

  Source:
    - urlMatcherFactory.js, line 175

  ##### Returns:

  An array of parameter names. Must be treated as read-only. If the pattern has no parameters, an empty array is returned.

  Type
    Array.<string>