initial commit

1 files changed, 449 insertions, 0 deletions

diff --git a/files/ar/mozilla/add-ons/webextensions/match_patterns/index.html b/files/ar/mozilla/add-ons/webextensions/match_patterns/index.html
new file mode 100644
index 0000000000..d5775418be
--- /dev/null
+++ b/files/ar/mozilla/add-ons/webextensions/match_patterns/index.html
@@ -0,0 +1,449 @@
+---
+title: Match patterns
+slug: Mozilla/Add-ons/WebExtensions/Match_patterns
+translation_of: Mozilla/Add-ons/WebExtensions/Match_patterns
+---
+<div>{{AddonSidebar}}</div>
+
+<p>Match patterns are a way to specify groups of URLs: a match pattern matches a specific set of URLs. They are for extensions using WebExtensions APIs in a few places, most notably to specify which documents to load <a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/Content_scripts">content scripts</a> into, and to specify which URLs to add <code><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/API/webRequest">webRequest</a></code> listeners to.</p>
+
+<p>APIs that use match patterns usually accept a list of match patterns, and will perform the appropriate action if the URL matches any of the patterns. See, for example, the <code><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/content_scripts">content_scripts</a></code> key in manifest.json.</p>
+
+<h2 id="Match_pattern_structure">Match pattern structure</h2>
+
+<p>All match patterns are specified as strings. Apart from the special <a href="/en-US/Add-ons/WebExtensions/Match_patterns#%3Call_urls%3E">"&lt;all_urls&gt;"</a> pattern, match patterns consist of three parts: <em>scheme</em>, <em>host</em>, and <em>path</em>. The scheme and host are separated by "://".</p>
+
+<pre>&lt;scheme&gt;://&lt;host&gt;&lt;path&gt;</pre>
+
+<h3 id="scheme">scheme</h3>
+
+<p>The <em>scheme</em> component may take one of two forms:</p>
+
+<table class="fullwidth-table standard-table">
+ <thead>
+  <tr>
+   <th scope="col" style="width: 50%;">Form</th>
+   <th scope="col">Matches</th>
+  </tr>
+ </thead>
+ <tbody>
+  <tr>
+   <td>"*"</td>
+   <td>Only "http" and "https".</td>
+  </tr>
+  <tr>
+   <td>One of "http", "https", "file", "ftp", "app".</td>
+   <td>Only the given scheme.</td>
+  </tr>
+ </tbody>
+</table>
+
+<h3 id="host">host</h3>
+
+<p>The <em>host</em> component may take one of three forms:</p>
+
+<table class="fullwidth-table standard-table">
+ <thead>
+  <tr>
+   <th scope="col" style="width: 50%;">Form</th>
+   <th scope="col">Matches</th>
+  </tr>
+ </thead>
+ <tbody>
+  <tr>
+   <td>"*"</td>
+   <td>Any host.</td>
+  </tr>
+  <tr>
+   <td>"*." followed by part of the hostname.</td>
+   <td>The given host and any of its subdomains.</td>
+  </tr>
+  <tr>
+   <td>A complete hostname, without wildcards.</td>
+   <td>Only the given host.</td>
+  </tr>
+ </tbody>
+</table>
+
+<p><em>host</em> is optional only if the <em>scheme</em> is "file".</p>
+
+<p>Note that the wildcard may only appear at the start.</p>
+
+<h3 id="path">path</h3>
+
+<p>The path component must begin with a "/".</p>
+
+<p>After that, it may subsequently contain any combination of the "*" wildcard and any of the characters that are allowed in URL paths. Unlike <em>host</em>, the <em>path</em> component may contain the "*" wildcard in the middle or at the end, and the "*" wildcard may appear more than once.</p>
+
+<h3 id="&lt;all_urls>">&lt;all_urls&gt;</h3>
+
+<p>The special value "&lt;all_urls&gt;" matches all URLs under any of the supported schemes: that is, "http", "https", "file", "ftp", "app".</p>
+
+<h2 id="Examples">Examples</h2>
+
+<table class="fullwidth-table standard-table">
+ <thead>
+  <tr>
+   <th scope="col" style="width: 33%;">Pattern</th>
+   <th scope="col" style="width: 33%;">Example matches</th>
+   <th scope="col" style="width: 33%;">Example non-matches</th>
+  </tr>
+ </thead>
+ <tbody>
+  <tr>
+   <td>
+    <p><code>&lt;all_urls&gt;</code></p>
+
+    <p>Match all URLs.</p>
+   </td>
+   <td>
+    <p><code>http://example.org/</code></p>
+
+    <p><code>ftp://files.somewhere.org/</code></p>
+
+    <p><code>https://a.org/some/path/</code></p>
+   </td>
+   <td>
+    <p><code>resource://a/b/c/</code><br>
+     (unsupported scheme)</p>
+   </td>
+  </tr>
+  <tr>
+   <td>
+    <p><code>*://*.mozilla.org/*</code></p>
+
+    <p>Match all HTTP and HTTPS URLs that are hosted at "mozilla.org" or one of its subdomains.</p>
+   </td>
+   <td>
+    <p><code>http://mozilla.org/</code></p>
+
+    <p><code>https://mozilla.org/</code></p>
+
+    <p><code>http://a.mozilla.org/</code></p>
+
+    <p><code>http://a.b.mozilla.org/</code></p>
+
+    <p><code>https://b.mozilla.org/path/</code></p>
+   </td>
+   <td>
+    <p><code>ftp://mozilla.org/</code><br>
+     (unmatched scheme)</p>
+
+    <p><code>http://mozilla.com/</code><br>
+     (unmatched host)</p>
+
+    <p><code>http://firefox.org/</code><br>
+     (unmatched host)</p>
+   </td>
+  </tr>
+  <tr>
+   <td>
+    <p><code>*://mozilla.org/</code></p>
+
+    <p>Match all HTTP and HTTPS URLs that are hosted at exactly "mozilla.org/".</p>
+   </td>
+   <td>
+    <p><code>http://mozilla.org/</code></p>
+
+    <p><code>https://mozilla.org/</code></p>
+   </td>
+   <td>
+    <p><code>ftp://mozilla.org/</code><br>
+     (unmatched scheme)</p>
+
+    <p><code>http://a.mozilla.org/</code><br>
+     (unmatched host)</p>
+
+    <p><code>http://mozilla.org/a</code><br>
+     (unmatched path)</p>
+   </td>
+  </tr>
+  <tr>
+   <td>
+    <p><code>ftp://mozilla.org/</code></p>
+
+    <p>Match only "ftp://mozilla.org/".</p>
+   </td>
+   <td><code>ftp://mozilla.org</code></td>
+   <td>
+    <p><code>http://mozilla.org/</code><br>
+     (unmatched scheme)</p>
+
+    <p><code>ftp://sub.mozilla.org/</code><br>
+     (unmatched host)</p>
+
+    <p><code>ftp://mozilla.org/path</code><br>
+     (unmatched path)</p>
+   </td>
+  </tr>
+  <tr>
+   <td>
+    <p><code>https://*/path</code></p>
+
+    <p>Match HTTPS URLs on any host, whose path is "path".</p>
+   </td>
+   <td>
+    <p><code>https://mozilla.org/path</code></p>
+
+    <p><code>https://a.mozilla.org/path</code></p>
+
+    <p><code>https://something.com/path</code></p>
+   </td>
+   <td>
+    <p><code>http://mozilla.org/path</code><br>
+     (unmatched scheme)</p>
+
+    <p><code>https://mozilla.org/path/</code><br>
+     (unmatched path)</p>
+
+    <p><code>https://mozilla.org/a</code><br>
+     (unmatched path)</p>
+
+    <p><code>https://mozilla.org/</code><br>
+     (unmatched path)</p>
+   </td>
+  </tr>
+  <tr>
+   <td>
+    <p><code>https://*/path/</code></p>
+
+    <p>Match HTTPS URLs on any host, whose path is "path/".</p>
+   </td>
+   <td>
+    <p><code>https://mozilla.org/path/</code></p>
+
+    <p><code>https://a.mozilla.org/path/</code></p>
+
+    <p><code>https://something.com/path</code>/</p>
+   </td>
+   <td>
+    <p><code>http://mozilla.org/path/</code><br>
+     (unmatched scheme)</p>
+
+    <p><code>https://mozilla.org/path</code><br>
+     (unmatched path)</p>
+
+    <p><code>https://mozilla.org/a</code><br>
+     (unmatched path)</p>
+
+    <p><code>https://mozilla.org/</code><br>
+     (unmatched path)</p>
+   </td>
+  </tr>
+  <tr>
+   <td>
+    <p><code>https://mozilla.org/*</code></p>
+
+    <p>Match HTTPS URLs only at "mozilla.org", with any path.</p>
+   </td>
+   <td>
+    <p><code>https://mozilla.org/</code></p>
+
+    <p><code>https://mozilla.org/path</code></p>
+
+    <p><code>https://mozilla.org/another</code></p>
+
+    <p><code>https://mozilla.org/path/to/doc</code></p>
+   </td>
+   <td>
+    <p><code>http://mozilla.org/path</code><br>
+     (unmatched scheme)</p>
+
+    <p><code>https://mozilla.com/path</code><br>
+     (unmatched host)</p>
+   </td>
+  </tr>
+  <tr>
+   <td>
+    <p><code>https://mozilla.org/a/b/c/</code></p>
+
+    <p>Match only this URL.</p>
+   </td>
+   <td><code>https://mozilla.org/a/b/c/</code></td>
+   <td>Anything else.</td>
+  </tr>
+  <tr>
+   <td>
+    <p><code>https://mozilla.org/*/b/*/</code></p>
+
+    <p>Match HTTPS URLs hosted on "mozilla.org", whose path contains a component "b" somewhere in the middle.</p>
+   </td>
+   <td>
+    <p><code>https://mozilla.org/a/b/c/</code></p>
+
+    <p><code>https://mozilla.org/d/b/f/</code></p>
+
+    <p><code>https://mozilla.org/a/b/c/d/</code></p>
+   </td>
+   <td>
+    <p><code>https://mozilla.org/b/*/</code><br>
+     (unmatched path)</p>
+
+    <p><code>https://mozilla.org/a/b/</code><br>
+     (unmatched path)</p>
+   </td>
+  </tr>
+  <tr>
+   <td>
+    <p><code>file:///blah/*</code></p>
+
+    <p>Match any FILE URL whose path begins with "blah".</p>
+   </td>
+   <td>
+    <p><code>file:///blah/</code></p>
+
+    <p><code>file:///blah/bleh</code></p>
+   </td>
+   <td><code>file:///bleh/</code><br>
+    (unmatched path)</td>
+  </tr>
+ </tbody>
+</table>
+
+<h3 id="Invalid_match_patterns">Invalid match patterns</h3>
+
+<table class="fullwidth-table standard-table">
+ <thead>
+  <tr>
+   <th scope="col">Invalid pattern</th>
+   <th scope="col">Reason</th>
+  </tr>
+ </thead>
+ <tbody>
+  <tr>
+   <td><code>resource://path/</code></td>
+   <td>Unsupported scheme.</td>
+  </tr>
+  <tr>
+   <td><code>https://mozilla.org</code></td>
+   <td>No path.</td>
+  </tr>
+  <tr>
+   <td><code>https://mozilla.*.org/</code></td>
+   <td>"*" in host must be at the start.</td>
+  </tr>
+  <tr>
+   <td><code>https://*zilla.org/</code></td>
+   <td>"*" in host must be the only character or be followed by ".".</td>
+  </tr>
+  <tr>
+   <td><code>http*://mozilla.org/</code></td>
+   <td>"*" in scheme must be the only character.</td>
+  </tr>
+  <tr>
+   <td><code>file://*</code></td>
+   <td>Empty path: this should be "<code>file:///*</code>".</td>
+  </tr>
+ </tbody>
+</table>
+
+<h2 id="Testing_match_patterns">Testing match patterns</h2>
+
+<p>When writing extensions, you don't generally work with match patterns directly: usually you pass a match pattern string into an API, and the API constructs a match pattern and uses it to test URLs. However, if you're trying to work out which match pattern to use, or debugging a problem with one, it can be useful to be able to create and test match patterns directly. This section explains how to do this.</p>
+
+<p>Note that the code here <strong>will not work</strong> in an extension, and is only provided to help manually test match patterns using the console.</p>
+
+<p>First, open the developer tool settings and check the setting marked "Enable browser chrome and add-on debugging toolboxes":</p>
+
+<p>{{EmbedYouTube("JDEe2fyFpHE")}}</p>
+
+<p>Next, open the "Browser Console":</p>
+
+<p>{{EmbedYouTube("mfuBMje6dA4")}}</p>
+
+<p>This gives you a command line that you can use to execute privileged JavaScript in Firefox.</p>
+
+<div class="warning">
+<p>Because code running in the Browser Console has system privileges, any time you use it to run code, you need to understand exactly what the code is doing. That includes the code samples in this article.</p>
+</div>
+
+<p>Now paste this code into the command line and press <kbd>enter</kbd>:</p>
+
+<pre class="brush: js">Cu.import("resource://gre/modules/MatchPattern.jsm");
+Cu.import("resource://gre/modules/BrowserUtils.jsm");</pre>
+
+<p>This does two things:</p>
+
+<ul>
+ <li>imports "MatchPattern.jsm": this is the system module that implements match patterns. Specifically, the module contains a constructor for <code>MatchPattern</code> objects. <code>MatchPattern</code> objects define a function called <code>matches()</code>, that takes a URI and returns <code>true</code> or <code>false</code>.</li>
+ <li>imports "BrowserUtils.jsm": this includes a function <code>makeURI()</code>, that converts a string into an <code><a href="/en-US/docs/Mozilla/Tech/XPCOM/Reference/Interface/nsIURI">nsIURI</a></code> object. <code>nsIURI</code> is the type that <code>matches()</code> expects to receive.</li>
+</ul>
+
+<p>Now you can construct <code>MatchPattern</code> objects, construct URIs, and check whether the URIs match:</p>
+
+<pre class="brush: js">var match = new MatchPattern("*://mozilla.org/");
+
+var uri = BrowserUtils.makeURI("https://mozilla.org/");
+match.matches(uri); //        &lt; true
+
+uri = BrowserUtils.makeURI("https://mozilla.org/path");
+match.matches(uri); //        &lt; false</pre>
+
+<h2 id="Converting_Match_Patterns_to_Regular_Expressions">Converting Match Patterns to Regular Expressions</h2>
+
+<p>All match patterns can be represented by regular expressions. This code converts a match pattern to a regular expression:</p>
+
+<pre class="brush: js">/**
+ * Transforms a valid match pattern into a regular expression
+ * which matches all URLs included by that pattern.
+ *
+ * @param  {string}  pattern  The pattern to transform.
+ * @return {RegExp}           The pattern's equivalent as a RegExp.
+ * @throws {TypeError}        If the pattern is not a valid MatchPattern
+ */
+function matchPatternToRegExp(pattern) {
+    if (pattern === '') {
+        return (/^(?:http|https|file|ftp|app):\/\//);
+    }
+
+    const schemeSegment = '(\\*|http|https|file|ftp)';
+    const hostSegment = '(\\*|(?:\\*\\.)?(?:[^/*]+))?';
+    const pathSegment = '(.*)';
+    const matchPatternRegExp = new RegExp(
+        `^${schemeSegment}://${hostSegment}/${pathSegment}$`
+    );
+
+    let match = matchPatternRegExp.exec(pattern);
+    if (!match) {
+         throw new TypeError(`"${pattern}" is not a valid MatchPattern`);
+    }
+
+    let [, scheme, host, path] = match;
+    if (!host) {
+        throw new TypeError(`"${pattern}" does not have a valid host`);
+    }
+
+    let regex = '^';
+
+    if (scheme === '*') {
+        regex += '(http|https)';
+    } else {
+        regex += scheme;
+    }
+
+    regex += '://';
+
+    if (host &amp;&amp; host === '*') {
+        regex += '[^/]+?';
+    } else if (host) {
+        if (host.match(/^\*\./)) {
+            regex += '[^/]*?';
+            host = host.substring(2);
+        }
+        regex += host.replace(/\./g, '\\.');
+    }
+
+    if (path) {
+        if (path === '*') {
+            regex += '(/.*)?';
+        } else if (path.charAt(0) !== '/') {
+            regex += '/';
+            regex += path.replace(/\./g, '\\.').replace(/\*/g, '.*?');
+            regex += '/?';
+        }
+    }
+
+    regex += '$';
+    return new RegExp(regex);
+}
+</pre>