https://wiki.greasespot.net/api.php?action=feedcontributions&user=80.3.109.93&feedformat=atomGreaseSpot Wiki - User contributions [en]2024-03-29T04:44:38ZUser contributionsMediaWiki 1.41.0https://wiki.greasespot.net/index.php?title=Include_and_exclude_rules&diff=6782Include and exclude rules2011-10-24T11:04:50Z<p>80.3.109.93: /* Magic TLD */</p>
<hr />
<div>[[User script]]s specify include and exclude rules in the [[metadata block]].<br />
<br />
'''The script will execute if it matches any include rule, as long as it does not match an exclude rule.'''<br />
<br />
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:<br />
<br />
* <code><nowiki>http://www.example.com/foo/bar</nowiki></code> and,<br />
* <code><nowiki>http://www.example.com/foo/</nowiki></code><br />
<br />
but not:<br />
<br />
* <code><nowiki>http://www.example.com/baz/</nowiki></code>.<br />
<br />
== Globs ==<br />
<br />
Include and exclude rules support the <code>*</code> or [[wikipedia:Glob (programming)|globbing operator]].<br />
The <code>*</code> serves as a wildcard that matches one or more of any character.<br />
A rule can have several wildcards or none, in which case the rule must match the entire URL exactly.<br />
Exclude rules look the same, and prevent the script from being executed.<br />
For example:<br />
<br />
<pre class="sample"><br />
// ==UserScript==<br />
// @include <nowiki>http://www.example.com/foo/*</nowiki><br />
// @include <nowiki>http://www.example.org/*.bar</nowiki><br />
// @exclude <nowiki>http://www.example.com/foo/baz</nowiki><br />
// ==/UserScript==<br />
</pre><br />
<br />
If no include rule is provided, <code>@include *</code> is assumed.<br />
That is: every URL will be matched, within the allowed [[#Greaseable_schemes |Greaseable schemes]].<br />
<br />
== Regular Expressions ==<br />
<br />
As of [[Version_history#0.9.8|Greasemonkey 0.9.8]], support for full regular expressions in include and exclude rules was added.<br />
If the rule both starts and ends with a forward-slash (<code>/</code>) character, the contents inside those slashes are interpreted as a a regular expression.<br />
For example:<br />
<br />
<pre class="sample"><br />
// ==UserScript==<br />
// @include <nowiki>/^https?://www\.example\.com/.*$/</nowiki><br />
// @include <nowiki>/^http://www\.example\.(org|net)//</nowiki><br />
// ==/UserScript==<br />
</pre><br />
<br />
Note:<br />
* The rule is parsed as a standard javascript <code>new RegExp()</code>, so you do not need to escape forward slashes inside the rule. Other special characters (like <code>.</code> '''should''' still be escaped, as in the above examples.)<br />
* The rule is always treated as case insensitive.<br />
* Anchors (<code>^</code>, <code>$</code>) are not supplied for you. If desired, they should be used as in the above example.<br />
<br />
== Greaseable schemes ==<br />
<br />
Greasemonkey will run scripts only on documents loaded from particular [http://tools.ietf.org/html/rfc3986#section-3.1 schemes].<br />
By default, those are:<br />
<br />
* http<br />
* https<br />
* ftp<br />
* data<br />
<br />
(<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>.)<br />
<br />
== Extra schemes ==<br />
<br />
Greasemonkey will also run scripts on:<br />
<br />
; file:<br />
: Only if <code>greasemonkey.fileIsGreaseable</code> is set to <code>true</code> in [http://kb.mozillazine.org/About:config about:config].<br />
; about:<br />
: <s>Prior to 0.9.8, scripts would only run if <code>greasemonkey.aboutIsGreaseable</code> is set to <code>true</code> in [http://kb.mozillazine.org/About:config about:config]. (But about:blank is always allowed.)</s>.<br />
: Since 0.9.8, Only about:blank is allowed. ({{GitTicket|1375}})<br />
<br />
In both cases this restriction is intended to prevent security/privacy vulnerabilities.<br />
<br />
== Magic TLD ==<br />
<br />
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.<br />
<br />
== Data scheme user scripts ==<br />
<br />
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].<br />
For example, the below URI will display a HTML page that indirectly includes an image from google.com as its sole content:<br />
<br />
<nowiki>data:text/html;charset=utf-8,<html><head><title>data: test</title></head><body><img src='http://www.google.com/intl/en_ALL/images/logo.gif'></body></html></pre></nowiki><br />
<br />
[http://tinyurl.com/yl8djvy This link] points to the above data URI and can be clicked to see it in action.<br />
<br />
Firefox ignores unknown semicolon 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:<br />
<br />
data:text/html;MyScript;charset=utf-8,<html><head><title>data: test</title>....<br />
<br />
one can then use [[Include and exclude rules]] such as<br />
<br />
@include data:text/html;MyScript;*<br />
<br />
to trigger user scripts to run on a subtype of <code>data</code> URIs.<br />
<br />
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.</div>80.3.109.93