UrlPattern class

A pattern, similar to a RegExp, that is designed to match against URL paths, easily return groups of a matched path, and produce paths from a list of arguments - this is they are "reversible".

UrlPatterns also allow for handling plain paths and URLs with a fragment in a uniform way so that they can be used for client side routing on browsers that support window.history.pushState as well as legacy browsers.

The differences from a plain RegExp: All non-literals must be in a group. Everything outside of a groups is considered a literal and special regex characters are escaped. There can only be one match, and it must match the entire string. ^ and $ are automatically added to the beginning and end of the pattern, respectively.

The pattern must be un-ambiguous, eg (.///)(.///) is not allowed at the top-level.

The hash character (#) matches both '#' and '/', and it is only allowed once per pattern. Hashes are not allowed inside groups.

With those differences, UrlPatterns become much more useful for routing URLs and constructing them, both on the client and server. The best practice is to define your application's set of URLs in a shared library.


library urls;

final articleUrl = new UrlPattern(r'/articles/(\d+)');

Use with older browsers

Since '#' matches both '#' and '/' it can be used in as a path separator between the "static" portion of your URL and the "dynamic" portion. The dynamic portion would be the part that change when a user navigates to new data that's loaded dynamically rather than loading a new page.

In newer browsers that support History.pushState() an entire new path can be pushed into the location bar without reloading the page. In older browsers only the fragment can be changed without reloading the page. By matching both characters, and by producing either, we can use pushState in newer browsers, but fall back to fragments when necessary.


var pattern = new UrlPattern(r'/app#profile/(\d+)');
pattern.matches('/app/profile/1234'); // true
pattern.matches('/app#profile/1234'); // true
pattern.expand([1234], useFragment: true); // /app#profile/1234
pattern.expand([1234], useFragment: false); // /app/profile/1234
Implemented types


UrlPattern(String pattern)


hashCode int
The hash code for this object. [...]
read-only, override
pattern String
regex RegExp
runtimeType Type
A representation of the runtime type of the object.
read-only, inherited


allMatches(String str, [int start = 0]) Iterable<Match>
Match this pattern against the string repeatedly. [...]
expand(Iterable args, {bool useFragment: false}) String
Replaces pattern-groups with args
matchAsPrefix(String string, [int start = 0]) Match
Match this pattern against the start of string. [...]
matches(String str) bool
Returns true if this pattern matches path.
matchesNonFragment(String str) bool
Returns true if the path portion of the pattern, the part before the fragment, matches str. If there is no fragment in the pattern, this is equivalent to calling matches. [...]
noSuchMethod(Invocation invocation) → dynamic
Invoked when a non-existent method or property is accessed. [...]
parse(String path) List<String>
Parses a URL path, or path + fragment, and returns the group matches. Throws ArgumentError if this pattern does not match path.
toString() String
Returns a string representation of this object.


operator ==(dynamic other) bool
The equality operator. [...]