Include and exclude rules: Difference between revisions

From GreaseSpot Wiki
Jump to navigationJump to search
(Update for 4.0)
(25 intermediate revisions by 12 users not shown)
Line 3: Line 3:
'''The script will execute if it matches any include rule, as long as it does not match an exclude rule.'''
'''The script will execute if it matches any include rule, as long as it does not match an exclude rule.'''


The rules are URLs, which can have a "wildcard" asterisk (*), which matches any string including the empty string. For example: <code><nowiki>http://www.example.com/foo/*</nowiki></code> will match <code><nowiki>http://www.example.com/foo/bar</nowiki></code> and <code><nowiki>http://www.example.com/foo/</nowiki></code>, but not <code><nowiki>http://www.example.com/baz/</nowiki></code>. A rule can have several wildcards or none, in which case the rule must match the entire URL exactly. Exclude rules look the same, and prevent the script from being executed. An example:
== Globs ==


// ==UserScript==
Include and exclude rules support the <code>*</code> or [[wikipedia:Glob (programming)|globbing operator]].
// @include    <nowiki>http://www.example.com/foo/*</nowiki>
The <code>*</code> serves as a wildcard that matches one or more of any character.
// @include    <nowiki>http://www.example.org/*.bar</nowiki>
A rule can have several wildcards or none, in which case the rule must match the entire URL exactly.
// @exclude    <nowiki>http://www.example.com/foo/baz</nowiki>
Exclude rules look the same, and prevent the script from being executed.
// ==/UserScript==


If no include rule is provided, <code>@include *</code> is assumed. That is, every URL will be matched within the allowed [[#Greaseable_schemes |Greaseable schemes]].
For example: <code><nowiki>http://www.example.com/foo/*</nowiki></code> will match:


[[#top |top]]
* <code><nowiki>http://www.example.com/foo/bar</nowiki></code> and,
* <code><nowiki>http://www.example.com/foo/</nowiki></code>


== Greaseable schemes ==
but not:


Greasemonkey will run scripts only on documents loaded from particular [http://tools.ietf.org/html/rfc3986#section-3.1 schemes].
* <code><nowiki>http://www.example.com/baz/</nowiki></code>.
By default, those are:


* http
Further examples:
* https
* ftp
* data


(<b>Note:</b> What is officially called a 'scheme' in a URL is also found in Javascript as the <code>.protocol</code> property of any abstract <code>link</code> element such as <code>&lt;a&gt;</code>, <code>&lt;link&gt;</code>, or a DOM object such as <code>document.location</code>.)
<pre class="sample">
// ==UserScript==
// @include    <nowiki>http://www.example.com/foo/*</nowiki>
// @include    <nowiki>http://www.example.org/*.bar</nowiki>
// @exclude    <nowiki>http://www.example.com/foo/baz</nowiki>
// ==/UserScript==
</pre>


== Extra schemes ==
If no include rule is provided, <code>@include *</code> is assumed.
That is: every URL will be matched, within the allowed [[#Greaseable_schemes|Greaseable schemes]].


Greasemonkey will also run scripts on:
== Regular Expressions ==


; file:
Support for full regular expressions in include and exclude rules is also available.
: Only if <code>greasemonkey.fileIsGreaseable</code> is set to <code>true</code> in [http://kb.mozillazine.org/About:config about:config].
If the rule both starts and ends with a forward-slash (<code>/</code>) character, the contents inside those slashes are interpreted as a regular expression.
; about:
For example:
: Only if <code>greasemonkey.aboutIsGreaseable</code> is set to <code>true</code> in [http://kb.mozillazine.org/About:config about:config].<br>(But about:blank is always allowed.)


In both cases this restriction is intended to prevent security/privacy vulnerabilities.
<pre class="sample">
// ==UserScript==
// @include    <nowiki>/^https?://www\.example\.com/.*$/</nowiki>
// @include    <nowiki>/^http://www\.example\.(org|net)//</nowiki>
// ==/UserScript==
</pre>


== Data scheme user scripts ==
Note:
* The rule is parsed as a standard javascript <code>new RegExp()</code>, so you do not need to escape forward slashes inside the rule.  Special regex characters (like <code>.</code>) '''should''' still be escaped, as in the above examples; otherwise they have their normal regex meaning (like <code>.</code> matching any non-newline character).
* The rule is always treated as case insensitive.
* Anchors (<code>^</code>, <code>$</code>) are not supplied for you.  If desired, they should be used as in the above example.


Browsers can open windows in which all of the page top content is contained in a [http://en.wikipedia.org/wiki/Data_URI_scheme data scheme URI].
== Greaseable schemes ==
For example, the below URI will display a HTML page that indirectly includes an image from google.com as its sole content:


data:text/html;charset=utf-8,<html><head><title>data: test</title></head><body><img src='<nowiki>http://www.google.com/intl/en_ALL/images/logo.gif</nowiki>'></body></html></pre>
Greasemonkey will run scripts only on documents loaded from particular [http://tools.ietf.org/html/rfc3986#section-3.1 schemes].
By default, those are:


[http://tinyurl.com/yl8djvy This link] points to the above data URI and can be clicked to see it in action.
* http
* https
* about:blank


Firefox ignores unknown ';' separated parameters in the header of a <code>data</code> URI (and the standards seem to leave this possibility open) which means if one adds say the string <code>MyScript;</code> in the header of the above URI, giving:
User scripts will not run on documents from any other scheme (ftp, file, etc.) or any other part of about.


data:text/html;MyScript;charset=utf-8,<html><head><title>data: test</title>....
<!-- Not in 4.0
== Magic TLD ==


one can then use [[Include and exclude rules]] such as
The only special syntax besides the wildcard is .tld. An include such as <code><nowiki>http://www.example.tld/*</nowiki></code> will match any top level domain, such as <code>www.example.com</code>, <code>www.example.org</code>, <code>www.example.co.uk</code>, and so on. One must be careful with this, to not accidentally leak data to a site that they did not mean to match. This list of TLDs includes myriad dual-segment TLDs (such as ca.us, aeroport.fr and kyoto.jp), beside the plain country or category codes (com, jp, se).  For a full list see the [[Magic TLD]] page.


@include data:text/html;MyScript;*
-->
 
<!-- Not in 4.0
to trigger user scripts to run on a subtype of <code>data</code> URIs.
== User Specified Rules ==
 
This ability can be useful if a user script creates one or more <code>data</code> URIs and then opens them. Augmenting the URIs with some extra marking can cause specific user scripts to run in their windows. For example, a user script can create a <code>data URI</code> that contains a HTML <code>table</code> and trigger a user script for it that allows the user sort it.
 
== Magic TLD ==


The only special syntax besides the wildcard is .tld. An include such as <code><nowiki>http://www.example.tld/*</nowiki></code> will match any top level domain, such as <code>www.example.com</code>, <code>www.example.org</code>, <code>www.example.co.uk</code>, and so on. One must be careful with this, to not accidentally leak data to a site that they did not mean to match. This list of TLDs includes a myriad of dual-segment TLDs (such as ca.us, aeroport.fr and kyoto.jp), beside the plain country or category codes (com, jp, se).  For a full list see the [[Magic TLD]] page.
Since Greasemonkey [[Version history#0.9.9|0.9.9]], users have been able to specify their own exclude and include values through the script options dialog in the Add Ons Manager.
Thus, each script has its own rules plus optionally the user's rules.


[[#top |top]]
The user's rules are checked first, then the script's rules are checked.
If any exclude matches the page, the script does not run.
If any include matches the page, the script will run.
If a script include matches, but a user exclude also matches, the user exclude will take precedence over the script, and it will not run.
If a script exclude matches, but a user include also matches, the user include will take precedence over the script, and it will run.
-->

Revision as of 19:55, 3 November 2017

User scripts specify include and exclude rules in the metadata block.

The script will execute if it matches any include rule, as long as it does not match an exclude rule.

Globs

Include and exclude rules support the * or globbing operator. The * serves as a wildcard that matches one or more of any character. A rule can have several wildcards or none, in which case the rule must match the entire URL exactly. Exclude rules look the same, and prevent the script from being executed.

For example: http://www.example.com/foo/* will match:

  • http://www.example.com/foo/bar and,
  • http://www.example.com/foo/

but not:

  • http://www.example.com/baz/.

Further examples:

// ==UserScript==
// @include     http://www.example.com/foo/*
// @include     http://www.example.org/*.bar
// @exclude     http://www.example.com/foo/baz
// ==/UserScript==

If no include rule is provided, @include * is assumed. That is: every URL will be matched, within the allowed Greaseable schemes.

Regular Expressions

Support for full regular expressions in include and exclude rules is also available. If the rule both starts and ends with a forward-slash (/) character, the contents inside those slashes are interpreted as a regular expression. For example:

// ==UserScript==
// @include     /^https?://www\.example\.com/.*$/
// @include     /^http://www\.example\.(org|net)//
// ==/UserScript==

Note:

  • The rule is parsed as a standard javascript new RegExp(), so you do not need to escape forward slashes inside the rule. Special regex characters (like .) should still be escaped, as in the above examples; otherwise they have their normal regex meaning (like . matching any non-newline character).
  • The rule is always treated as case insensitive.
  • Anchors (^, $) are not supplied for you. If desired, they should be used as in the above example.

Greaseable schemes

Greasemonkey will run scripts only on documents loaded from particular schemes. By default, those are:

  • http
  • https
  • about:blank

User scripts will not run on documents from any other scheme (ftp, file, etc.) or any other part of about.