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><all_urls></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> — 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> — 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> — 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><url-pattern></em> := <em><scheme></em>://<em><host></em><em><path></em> 50 <em><scheme></em> := '*' | 'http' | 'https' | 'file' | 'ftp' 51 <em><host></em> := '*' | '*.' <em><any char except '/' and '*'></em>+ 52 <em><path></em> := '/' <em><any chars></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><all_urls></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 ; </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> 243
