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.comhttp://example.com/foohttps://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.jshttp://foo.com/ |
file://example.jsresource://me/my-addon/data/file.htmldata: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/fooftp://foo.example.com/ |
ldap://example.comhttp://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.comhttps://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.htmlfile:///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 URLhttp://mozilla.org. -
The expression is compiled with the
global,ignoreCase, andmultilineflags disabled. TheMatchPatternconstructor 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.orghttps://mozilla.orghttp://foo.com/mozillahttp://hemozoon.orgmozscheme://foo.org |
http://foo.org |
/http:\/\/moz.*/ |
http://mozilla.orghttp://mozzarella.com |
https://mozilla.orghttp://foo.mozilla.org/http://foo.com/moz |
/http.*moz.*/ |
http://foo.mozilla.org/http://mozilla.orghttp://hemozoon.org/ |
ftp://http/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.
