xref: /external/chromium/chrome/common/extensions/docs/static/match_patterns.html

<div id="pageData-name" class="pageData">Match Patterns</div>

<p>
<a href="content_scripts.html">Content scripts</a> operate on
a set of URLs defined by match patterns.
You can put one or more match patterns
in the <code>"matches"</code> part of
a content script's section of the manifest.
This page describes the match pattern syntax &mdash;
the rules you need to follow when you specify
which URLs your content script affects.
</p>

<p>
A match pattern is essentially a URL
that begins with a permitted scheme (<code>http</code>,
<code>https</code>, <code>file</code>, or <code>ftp</code>),
and that can contain '<code>*</code>' characters.
The special pattern
<code>&lt;all_urls&gt;</code> matches any URL
that starts with a permitted scheme.
Each match pattern has 3 parts:</p>
</p>

<ul>
  <li> <em>scheme</em> &mdash;
    for example, <code>http</code> or <code>file</code>
    or <code>*</code>
    <p class="note">
    <b>Note:</b>
    Access to <code>file</code> URLs isn't automatic.
    The user must visit the extensions management page
    and opt in to <code>file</code> access for each extension that requests it.
    </p>
  </li>
  <li> <em>host</em> &mdash;
    for example, <code>www.google.com</code>
    or <code>*.google.com</code>
    or <code>*</code>;
    if the scheme is <code>file</code>,
    there is no <em>host</em> part
  </li>
  <li> <em>path</em> &mdash;
    for example, <code>/*</code>, <code>/foo* </code>,
    or <code>/foo/bar </code>
  </li>
</ul>

<p>Here's the basic syntax:</p>

<pre>
<em>&lt;url-pattern&gt;</em> := <em>&lt;scheme&gt;</em>://<em>&lt;host&gt;</em><em>&lt;path&gt;</em>
<em>&lt;scheme&gt;</em> := '*' | 'http' | 'https' | 'file' | 'ftp'
<em>&lt;host&gt;</em> := '*' | '*.' <em>&lt;any char except '/' and '*'&gt;</em>+
<em>&lt;path&gt;</em> := '/' <em>&lt;any chars&gt;</em>
</pre>

<p>
The meaning of '<code>*</code>' depends on whether
it's in the <em>scheme</em>, <em>host</em>, or <em>path</em> part.
If the <em>scheme</em> is <code>*</code>,
then it matches either <code>http</code> or <code>https</code>.
If the <em>host</em> is just <code>*</code>,
then it matches any host.
If the <em>host</em> is <code>*.<em>hostname</em></code>,
then it matches the specified host or any of its subdomains.
In the <em>path</em> section,
each '<code>*</code>' matches 0 or more characters.
The following table shows some valid patterns.
</p>

<table class="columns">
<tbody>
<tr>
  <th style="margin-left:0; padding-left:0">Pattern</th>
  <th style="margin-left:0; padding-left:0">What it does</th>
  <th style="margin-left:0; padding-left:0">Examples of matching URLs</th>
</tr>

<tr>
  <td>
    <code>http://*/*</code>
  </td>

  <td>Matches any URL that uses the <code>http</code> scheme</td>

  <td>
    http://www.google.com/<br>
    http://example.org/foo/bar.html
  </td>
</tr>

<tr>
  <td>
    <code>http://*/foo*</code>
  </td>

  <td>
    Matches any URL that uses the <code>http</code> scheme, on any host,
    as long as the path starts with <code>/foo</code>
  </td>

  <td>
    http://example.com/foo/bar.html<br>
    http://www.google.com/foo<b></b>
  </td>
</tr>

<tr>
  <td>
    <code>https://*.google.com/foo*bar </code>
  </td>

  <td>
    Matches any URL that uses the <code>https</code> scheme,
    is on a google.com host
    (such as www.google.com, docs.google.com, or google.com),
    as long as the path starts with <code>/foo</code>
    and ends with <code>bar</code>
  </td>

  <td>
    http://www.google.com/foo/baz/bar<br>
    http://docs.google.com/foobar
  </td>
</tr>

<tr>
  <td>
    <code>http://example.org/foo/bar.html </code>
  </td>

  <td>Matches the specified URL</td>

  <td>
    http://example.org/foo/bar.html
  </td>
</tr>

<tr>
  <td>
    <code>file:///foo*</code>
  </td>

  <td>Matches any local file whose path starts with <code>/foo</code>
  </td>

  <td>
    file:///foo/bar.html<br>
    file:///foo
  </td>
</tr>

<tr>
  <td>
    <code>http://127.0.0.1/*</code>
  </td>

  <td>
    Matches any URL that uses the <code>http</code> scheme
    and is on the host 127.0.0.1
  </td>
  <td>
    http://127.0.0.1/<br>
    http://127.0.0.1/foo/bar.html
  </td>
</tr>

<tr>
  <td>
    <code>*://mail.google.com/* </code>
  </td>

  <td>
    Matches any URL that starts with
    <code>http://mail.google.com</code> or
    <code>https://mail.google.com</code>.
  </td>

  <td>
    http://mail.google.com/foo/baz/bar<br>
    https://mail.google.com/foobar
  </td>
</tr>

<tr>
  <td>
    <code>&lt;all_urls&gt;</code>
  </td>

  <td>
    Matches any URL that uses a permitted scheme.
    (See the beginning of this section for the list of permitted
    schemes.)
  </td>
  <td>
    http://example.org/foo/bar.html<br>
    file:///bar/baz.html
  </td>
</tr>
</tbody>
</table>

<p>
Here are some examples of <em>invalid</em> pattern matches:
</p>

<table class="columns">
<tbody>
<tr>
  <th style="margin-left:0; padding-left:0">Bad pattern</th>
  <th style="margin-left:0; padding-left:0">Why it's bad</th>
</tr>

<tr>
  <td><code>http://www.google.com</code></td>
  <td>No <em>path</em></td>
</tr>

<tr>
  <td><code>http://*foo/bar</code></td>
  <td>'*' in the <em>host</em> can be followed only by a '.' or '/'</td>
</tr>

<tr>
  <td><code>http://foo.*.bar/baz ; </code></td>
  <td>If '*' is in the <em>host</em>, it must be the first character</td>
  </tr>

<tr>
  <td><code>http:/bar</code></td>
  <td>Missing <em>scheme</em> separator ("/" should be "//")</td>
</tr>

<tr>
  <td><code>foo://*</code></td>
  <td>Invalid <em>scheme</em></td>
</tr>
</tbody>
</table>