chrome/common/extensions/docs/templates/articles/match_patterns.html

   1 <h1>Match Patterns</h1>
   2
   3 <p>
   4 <a href="declare_permissions#host-permissions">Host
   5 permissions</a>
   6 {{^is_apps}}
   7 and <a href="content_scripts">content script</a>
   8 {{/is_apps}}
   9 matching {{^is_apps}}are{{:}}is{{/is_apps}} based on a set of URLs defined by
  10 <dfn>match patterns</dfn>.  A match pattern is essentially a
  11 URL that begins with a permitted scheme (<code>http</code>,
  12 <code>https</code>, <code>file</code>, or <code>ftp</code>,
  13 and that can contain '<code>*</code>' characters.
  14 The special pattern
  15 <code>&lt;all_urls&gt;</code> matches any URL
  16 that starts with a permitted scheme.
  17 Each match pattern has 3 parts:</p>
  18 </p>
  19
  20 <ul>
  21   <li> <em>scheme</em> &mdash;
  22     for example, <code>http</code> or <code>file</code>
  23     or <code>*</code>
  24     <p class="note">
  25     <b>Note:</b>
  26     Access to <code>file</code> URLs isn't automatic.
  27     The user must visit the extensions management page
  28     and opt in to <code>file</code> access for each extension that requests it.
  29     </p>
  30   </li>
  31   <li> <em>host</em> &mdash;
  32     for example, <code>www.google.com</code>
  33     or <code>*.google.com</code>
  34     or <code>*</code>;
  35     if the scheme is <code>file</code>,
  36     there is no <em>host</em> part
  37   </li>
  38   <li> <em>path</em> &mdash;
  39     for example, <code>/*</code>, <code>/foo*</code>,
  40     or <code>/foo/bar</code>. The path must be present in a
  41     host permission, but is always treated
  42     as <code>/*</code>.
  43   </li>
  44 </ul>
  45
  46 <p>Here's the basic syntax:</p>
  47
  48 <pre>
  49 <em>&lt;url-pattern&gt;</em> := <em>&lt;scheme&gt;</em>://<em>&lt;host&gt;</em><em>&lt;path&gt;</em>
  50 <em>&lt;scheme&gt;</em> := '*' | 'http' | 'https' | 'file' | 'ftp'
  51 <em>&lt;host&gt;</em> := '*' | '*.' <em>&lt;any char except '/' and '*'&gt;</em>+
  52 <em>&lt;path&gt;</em> := '/' <em>&lt;any chars&gt;</em>
  53 </pre>
  54
  55 <p>
  56 The meaning of '<code>*</code>' depends on whether
  57 it's in the <em>scheme</em>, <em>host</em>, or <em>path</em> part.
  58 If the <em>scheme</em> is <code>*</code>,
  59 then it matches either <code>http</code> or <code>https</code>,
  60 and <strong>not</strong> <code>file</code>, or <code>ftp</code>.
  61 If the <em>host</em> is just <code>*</code>,
  62 then it matches any host.
  63 If the <em>host</em> is <code>*.<em>hostname</em></code>,
  64 then it matches the specified host or any of its subdomains.
  65 In the <em>path</em> section,
  66 each '<code>*</code>' matches 0 or more characters.
  67 The following table shows some valid patterns.
  68 </p>
  69
  70 <table class="simple">
  71 <tbody>
  72 <tr>
  73   <th style="margin-left:0; padding-left:0">Pattern</th>
  74   <th style="margin-left:0; padding-left:0">What it does</th>
  75   <th style="margin-left:0; padding-left:0">Examples of matching URLs</th>
  76 </tr>
  77
  78 <tr>
  79   <td>
  80     <code>http://*/*</code>
  81   </td>
  82
  83   <td>Matches any URL that uses the <code>http</code> scheme</td>
  84
  85   <td>
  86     http://www.google.com/<br>
  87     http://example.org/foo/bar.html
  88   </td>
  89 </tr>
  90
  91 <tr>
  92   <td>
  93     <code>http://*/foo*</code>
  94   </td>
  95
  96   <td>
  97     Matches any URL that uses the <code>http</code> scheme, on any host,
  98     as long as the path starts with <code>/foo</code>
  99   </td>
 100
 101   <td>
 102     http://example.com/foo/bar.html<br>
 103     http://www.google.com/foo<b></b>
 104   </td>
 105 </tr>
 106
 107 <tr>
 108   <td>
 109     <code>https://*.google.com/foo*bar </code>
 110   </td>
 111
 112   <td>
 113     Matches any URL that uses the <code>https</code> scheme,
 114     is on a google.com host
 115     (such as www.google.com, docs.google.com, or google.com),
 116     as long as the path starts with <code>/foo</code>
 117     and ends with <code>bar</code>
 118   </td>
 119
 120   <td>
 121     http://www.google.com/foo/baz/bar<br>
 122     http://docs.google.com/foobar
 123   </td>
 124 </tr>
 125
 126 <tr>
 127   <td>
 128     <code>http://example.org/foo/bar.html </code>
 129   </td>
 130
 131   <td>Matches the specified URL</td>
 132
 133   <td>
 134     http://example.org/foo/bar.html
 135   </td>
 136 </tr>
 137
 138 <tr>
 139   <td>
 140     <code>file:///foo*</code>
 141   </td>
 142
 143   <td>Matches any local file whose path starts with <code>/foo</code>
 144   </td>
 145
 146   <td>
 147     file:///foo/bar.html<br>
 148     file:///foo
 149   </td>
 150 </tr>
 151
 152 <tr>
 153   <td>
 154     <code>http://127.0.0.1/*</code>
 155   </td>
 156
 157   <td>
 158     Matches any URL that uses the <code>http</code> scheme
 159     and is on the host 127.0.0.1
 160   </td>
 161   <td>
 162     http://127.0.0.1/<br>
 163     http://127.0.0.1/foo/bar.html
 164   </td>
 165 </tr>
 166
 167 <tr>
 168   <td>
 169     <code>*://mail.google.com/* </code>
 170   </td>
 171
 172   <td>
 173     Matches any URL that starts with
 174     <code>http://mail.google.com</code> or
 175     <code>https://mail.google.com</code>.
 176   </td>
 177
 178   <td>
 179     http://mail.google.com/foo/baz/bar<br>
 180     https://mail.google.com/foobar
 181   </td>
 182 </tr>
 183
 184 <tr>
 185   <td>
 186     <code>&lt;all_urls&gt;</code>
 187   </td>
 188
 189   <td>
 190     Matches any URL that uses a permitted scheme.
 191     (See the beginning of this section for the list of permitted
 192     schemes.)
 193   </td>
 194   <td>
 195     http://example.org/foo/bar.html<br>
 196     file:///bar/baz.html
 197   </td>
 198 </tr>
 199 </tbody>
 200 </table>
 201
 202 <p>
 203 Here are some examples of <em>invalid</em> pattern matches:
 204 </p>
 205
 206 <table class="simple">
 207 <tbody>
 208 <tr>
 209   <th style="margin-left:0; padding-left:0">Bad pattern</th>
 210   <th style="margin-left:0; padding-left:0">Why it's bad</th>
 211 </tr>
 212
 213 <tr>
 214   <td><code>http://www.google.com</code></td>
 215   <td>No <em>path</em></td>
 216 </tr>
 217
 218 <tr>
 219   <td><code>http://*foo/bar</code></td>
 220   <td>'*' in the <em>host</em> can be followed only by a '.' or '/'</td>
 221 </tr>
 222
 223 <tr>
 224   <td><code>http://foo.*.bar/baz&nbsp; </code></td>
 225   <td>If '*' is in the <em>host</em>, it must be the first character</td>
 226   </tr>
 227
 228 <tr>
 229   <td><code>http:/bar</code></td>
 230   <td>Missing <em>scheme</em> separator ("/" should be "//")</td>
 231 </tr>
 232
 233 <tr>
 234   <td><code>foo://*</code></td>
 235   <td>Invalid <em>scheme</em></td>
 236 </tr>
 237 </tbody>
 238 </table>
 239
 240 <p>
 241 Some schemes are not supported in all contexts.
 242 </p>