util/match-pattern

Unstable

Test strings containing URLs against simple patterns.

Usage

Specifying Patterns

There are three ways you can specify patterns:

  • as an exact match string
  • using a wildcard in a string
  • using a regular expression

Exact Matches

A URL matches only that URL. The URL must start with a scheme, end with a slash, and contain no wildcards.

Example pattern Example matching URLs Example non-matching URLs
"http://example.com/" http://example.com/ http://example.com
http://example.com/foo
https://example.com/
http://foo.example.com/

Wildcards

A single asterisk matches any URL with an http, https, or ftp scheme. For other schemes like file, resource, or data, use a scheme followed by an asterisk, as below.

Example pattern Example matching URLs Example non-matching URLs
"*" http://example.com/
https://example.com/
ftp://example.com/
http://bar.com/foo.js
http://foo.com/		 file://example.js
resource://me/my-addon/data/file.html
data:text/html,Hi there

A domain name prefixed with an asterisk and dot matches any URL of that domain or a subdomain, using any of http, https, ftp.

Example pattern Example matching URLs Example non-matching URLs
"*.example.com" http://example.com/
http://foo.example.com/
https://example.com/
http://example.com/foo
ftp://foo.example.com/		 ldap://example.com
http://example.foo.com/

A URL followed by an asterisk matches that URL and any URL prefixed with the pattern.

Example pattern Example matching URLs Example non-matching URLs
"https://foo.com/*" https://foo.com/
https://foo.com/bar		 http://foo.com/
https://foo.com
https://bar.foo.com/

A scheme followed by an asterisk matches all URLs with that scheme. To match local files, use file://*, and to match files loaded from your add-on's data directory, use resource://.

Example pattern Example matching URLs
"file://*" file://C:/file.html
file:///home/file.png
"resource://*" resource://my-addon-at-me-dot-org/my-addon/data/file.html
"data:*" data:text/html,Hi there

Regular Expressions

You can specify patterns using a regular expression:

var { MatchPattern } = require("sdk/util/match-pattern");
var pattern = new MatchPattern(/.*example.*/);

The regular expression is subject to restrictions based on those applied to the HTML5 pattern attribute. In particular:

  • The pattern must match the entire value, not just any subset. For example, the pattern /moz.*/ will not match the URL http://mozilla.org.

  • The expression is compiled with the global, ignoreCase, and multiline flags disabled. The MatchPattern constructor will throw an exception if you try to set any of these flags.

Example pattern Example matching URLs Example non-matching URLs
/.*moz.*/ http://foo.mozilla.org/
http://mozilla.org
https://mozilla.org
http://foo.com/mozilla
http://hemozoon.org
mozscheme://foo.org		 http://foo.org
/https:\/\/www\.moz.*/ https://www.mozilla.org
https://www.mozzarella.com		 http://www.mozilla.org
https://foo.mozilla.org/
https://foo.com/moz
/http.*moz.*/ http://foo.mozilla.org/
http://mozilla.org
http://hemozoon.org/
https://anydomain.com/foomozbar/		 ftp://http/mozilla.org
/[^:/]+:\/\/[^/]*mozilla\.org\/.*/ ftp://foo.mozilla.org/
http://www.mozilla.org/
https://developer.mozilla.org/any		 ftp://http/mozilla.org
http://anydomain.com/mozilla.org/

Examples

var { MatchPattern } = require("sdk/util/match-pattern");
var pattern = new MatchPattern("http://example.com/*");
console.log(pattern.test("http://example.com/"));       // true
console.log(pattern.test("http://example.com/foo"));    // true
console.log(pattern.test("http://foo.com/"));           // false!

Globals

Constructors

MatchPattern(pattern)

This constructor creates match pattern objects that can be used to test URLs.

Parameters

pattern : string
The pattern to use. See Patterns above.

MatchPattern

Methods

test(url)

Tests a URL against the match pattern.

Parameters

url : string
The URL to test.

Returns

boolean : True if the URL matches the pattern and false otherwise.