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 |
|---|---|---|
"https://example.com/" |
https://example.com/ |
https://example.comhttps://example.com/foohttps://example.com/https://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 |
|---|---|---|
"*" |
https://example.com/https://example.com/ftp://example.com/https://bar.com/foo.jshttps://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" |
https://example.com/https://foo.example.com/https://example.com/https://example.com/fooftp://foo.example.com/ |
ldap://example.comhttps://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 |
https://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 URLhttps://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.*/ |
https://foo.mozilla.org/https://mozilla.orghttps://mozilla.orghttps://foo.com/mozillahttps://hemozoon.orgmozscheme://foo.org |
https://foo.org |
/https:\/\/www\.moz.*/ |
https://www.mozilla.orghttps://www.mozzarella.com |
https://www.mozilla.orghttps://foo.mozilla.org/https://foo.com/moz |
/http.*moz.*/ |
https://foo.mozilla.org/https://mozilla.orghttps://hemozoon.org/https://anydomain.com/foomozbar/ |
ftp://http/mozilla.org |
/[^:/]+:\/\/[^/]*mozilla\.org\/.*/ |
ftp://foo.mozilla.org/https://www.mozilla.org/https://developer.mozilla.org/any |
ftp://http/mozilla.orghttps://anydomain.com/mozilla.org/ |
Examples
var { MatchPattern } = require("sdk/util/match-pattern");
var pattern = new MatchPattern("https://example.com/*");
console.log(pattern.test("https://example.com/")); // true
console.log(pattern.test("https://example.com/foo")); // true
console.log(pattern.test("https://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.