Difference between revisions of "Include and exclude rules"

From GreaseSpot Wiki
Jump to navigationJump to search
(added TLD pseudo-code)
(Recommend @match over @include)
 
(43 intermediate revisions by 17 users not shown)
Line 1: Line 1:
[[User script]]s 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. The rules are URLs, which can have a "wildcard" asterisk (*), which matches any string. 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/. 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:
[[User script]]s specify include and exclude rules in the [[metadata block]].


// ==UserScript==
'''The script will execute if it matches any include rule, as long as it does not match an exclude rule.'''
// @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.
'''Please note: The <code>@match</code> rule is safer than the older <code>@include</code> rule, and now widely supported, so you are recommended to use that instead.  [https://wiki.greasespot.net/Metadata_Block#.40match Read about the <code>@match</code> rule here].


== Globs ==
Include and exclude rules support the <code>*</code> or [[wikipedia:Glob (programming)|globbing operator]].
The <code>*</code> 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: <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>.
Further examples:
<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>
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]].
== 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 (<code>/</code>) character, the contents inside those slashes are interpreted as a regular expression.
For example:
<pre class="sample">
// ==UserScript==
// @include    <nowiki>/^https?://www\.example\.com/.*$/</nowiki>
// @include    <nowiki>/^http://www\.example\.(org|net)//</nowiki>
// ==/UserScript==
</pre>
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.
== Greaseable schemes ==
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
* https
* about:blank
User scripts will not run on documents from any other scheme (ftp, file, etc.) or any other part of about.
<!-- Not in 4.0
== Magic TLD ==
== Magic TLD ==


The only special syntax besides the wildcard is .tld. An include such as http://www.example.tld/* will match any top level domain, such as www.example.com, www.example.org, www.example.net, and so on. One must be careful with this, to not accidentally leak data to a site that they did not mean to match.
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.
 
-->
<!-- Not in 4.0
== User Specified Rules ==


The following is a pseudo-code representation of the code that performs the regular expression searching in Greasemonkey that supports the TLD special function. The actual Javascript code is located in the extension convert2RegExp.js file.
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.


Key:
The user's rules are checked first, then the script's rules are checked.
<code>
If any exclude matches the page, the script does not run.
  .    = actual required period character
If any include matches the page, the script will run.
  *    = any character
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.
  !    = any character not a period
If a script exclude matches, but a user include also matches, the user include will take precedence over the script, and it will run.
  []    = optional
-->
  ()    = parenthetical grouping
  AND  = logical and
  OR    = logical OR
  ,    = logical OR
  Note that some "AND's" are implied, and Space characters are ignored
</code>
Pseudo-code:
<code>
*  AND
(
      demon.co.uk
  OR
      esc.edu.ar
  OR  ( [ co.  OR  ci. ] !.  AND
      ( vt.us, ne.us, ks.us, il.us, hi.us, sc.us, nh.us, ia.us, wy.us, or.us,
        ma.us, vi.us, tn.us, in.us, az.us, id.us, nc.us, co.us, dc.us, nd.us,
        me.us, al.us, ak.us, de.us, wv.us, nm.us, mo.us, pr.us, nj.us, sd.us,
        md.us, va.us, ri.us, ut.us, ct.us, pa.us, ok.us, ky.us, mt.us, ga.us,
        la.us, oh.us, ms.us, wi.us, wa.us, gu.us, mi.us, tx.us, fl.us, ca.us,
        ar.us, mn.us, ny.us, nv.us ) )
  OR
      !. [pvt.] ( k12., cc., tec., lib., state., gen. ) .  AND
      ( vt.us, ne.us, ks.us, il.us, hi.us, sc.us, nh.us, ia.us, wy.us, or.us,
        ma.us, vi.us, tn.us, in.us, az.us, id.us, nc.us, co.us, dc.us, nd.us,
        me.us, al.us, ak.us, de.us, wv.us, nm.us, mo.us, pr.us, nj.us, sd.us,
        md.us, va.us, ri.us, ut.us, ct.us, pa.us, ok.us, ky.us, mt.us, ga.us,
        la.us, oh.us, ms.us, wi.us, wa.us, gu.us, mi.us, tx.us, fl.us, ca.us,
        ar.us, mn.us, ny.us, nv.us )
  OR
      !. (2000.hu, ab.ca, ac, ac.ae, ac.at, ac.be, ac.cn, ac.cr, ac.cy, ac.fj,
        ac.fk, ac.gg, ac.id, ac.il, ac.im, ac.in, ac.je, ac.jp, ac.kr, ac.ma,
        ac.ng, ac.nz, ac.om, ac.pa, ac.pg, ac.th, ac.ug, ac.uk, ac.vn, ac.yu,
        ac.za, ac.zw, ad, ad.jp, ae, aero, aeroport.fr, af, ag, agrar.hu,
        agro.pl, ah.cn, ai, aichi.jp, aid.pl, ak, akita.jp, al, al, alderney.gg,
        alt.na, alt.za, am, an, ao, aomori.jp, aq, ar, ar, arpa, art.br, art.do,
        art.dz, arts.co, arts.ve, as, asn.au, asn.lv, ass.dz, assedic.fr,
        asso.fr, asso.re, at, at.tt, atm.pl, au, au.com, au.tt, auto.pl,
        avocat.fr, avoues.fr, aw, ax, az, az, ba, barreau.fr, bb, bbs.tr, bc.ca,
        bd, be, be.tt, belgie.be, bf, bg, bh, bi, bib.ve, biz, biz.et, biz.om,
        biz.pk, biz.pl, biz.tt, biz.vn, bj, bj.cn, bm, bn, bo, bolt.hu,
        bourse.za, br, br.com, bs, bt, bv, bw, by, bz, ca, ca, ca.tt, casino.hu,
        cc, cci.fr, cd, cf, cg, ch, ch.vu, chambagri.fr, chiba.jp,
        chirurgiens-dentistes.fr, ci, city.hu, city.za, ck, cl, cm, cn, cn.com,
        co, co, co.ae, co.at, co.ck, co.cr, co.dk, co.gg, co.hu, co.id, co.il,
        co.im, co.in, co.je, co.jp, co.kr, co.ma, co.nz, co.om, co.th, co.tt,
        co.tv, co.ug, co.uk, co.ve, co.vi, co.yu, co.za, co.zw, com, com.ac,
        com.ae, com.ai, com.ar, com.au, com.az, com.bb, com.bh, com.bm, com.br,
        com.bs, com.cn, com.co, com.cu, com.cy, com.do, com.dz, com.ec, com.eg,
        com.et, com.fj, com.fk, com.fr, com.ge, com.gu, com.hk, com.jo, com.kh,
        com.kw, com.la, com.lb, com.lc, com.lv, com.ly, com.mk, com.mm, com.mo,
        com.mt, com.mx, com.my, com.na, com.nc, com.ng, com.ni, com.np, com.om,
        com.pa, com.pe, com.pg, com.ph, com.pk, com.pl, com.py, com.qa, com.re,
        com.ru, com.sa, com.sb, com.sd, com.sg, com.sh, com.sv, com.sy, com.tn,
        com.tr, com.tt, com.tw, com.ua, com.uy, com.ve, com.vn, com.vu, com.ws,
        com.ye, conf.au, conf.lv, coop, cq.cn, cr, cri.nz, cs, csiro.au, ct, cu,
        cul.na, cv, cx, cy, cz, dc, de, de, de.com, de.net, de.tt, de.vu, dj,
        dk, dk.org, dk.tt, dm, dni.us, dns.be, do, dz, e164.arpa, ec, ed.cr,
        ed.jp, edu, edu.ac, edu.ai, edu.ar, edu.au, edu.bh, edu.bm, edu.ck,
        edu.cn, edu.co, edu.do, edu.dz, edu.ec, edu.eg, edu.et, edu.ge, edu.gu,
        edu.hk, edu.jo, edu.kh, edu.kw, edu.lb, edu.lc, edu.lv, edu.mm, edu.mo,
        edu.mt, edu.my, edu.na, edu.ng, edu.ni, edu.np, edu.om, edu.pa, edu.pe,
        edu.pk, edu.pl, edu.ps, edu.py, edu.qa, edu.sa, edu.sb, edu.sd, edu.sg,
        edu.sh, edu.sv, edu.tr, edu.tt, edu.tw, edu.ua, edu.uk, edu.uy, edu.ve,
        edu.vn, edu.vu, edu.ws, edu.ye, edu.yu, edu.za, edunet.tn, ee, eg, eh,
        ehime.jp, ens.tn, er, ernet.in, erotica.hu, erotika.hu, es, es.tt, et,
        etc.br, eu, eu.com, eu.org, eu.tt, eun.eg, experts-comptables.fr,
        fam.pk, fax.nr, fed.us, fgov.be, fi, fi.cr, film.hu, fin.ec, fin.tn,
        firm.co, firm.in, firm.ve, fj, fk, fl, fm, fo, forum.hu, fr, fr.tt,
        fr.vu, fukui.jp, fukuoka.jp, fukushima.jp, g12.br, ga, ga, games.hu, gb,
        gb.com, gb.net, gd, gd.cn, ge, geek.nz, gen.in, gen.nz, gen.tr,
        geometre-expert.fr, gf, gg, gh, gi, gifu.jp, gl, gm, gmina.pl, gn,
        go.cr, go.id, go.jp, go.kr, go.th, go.ug, gob.ni, gob.pa, gob.pe,
        gob.pk, gob.sv, gok.pk, gon.pk, gop.pk, gos.pk, gouv.fr, gov, gov.ac,
        gov.ae, gov.ai, gov.ar, gov.au, gov.bh, gov.bm, gov.br, gov.ck, gov.cn,
        gov.co, gov.cy, gov.do, gov.dz, gov.ec, gov.eg, gov.et, gov.fj, gov.fk,
        gov.ge, gov.gg, gov.gu, gov.hk, gov.il, gov.im, gov.in, gov.je, gov.jo,
        gov.jp, gov.kh, gov.kw, gov.lb, gov.lc, gov.lv, gov.mm, gov.mo, gov.my,
        gov.ng, gov.np, gov.om, gov.pk, gov.ps, gov.qa, gov.sa, gov.sb, gov.sd,
        gov.sg, gov.sh, gov.sy, gov.tn, gov.tr, gov.tt, gov.ua, gov.uk, gov.ve,
        gov.vn, gov.ws, gov.ye, gov.za, gov.zw, gove.tw, govt.nz, gp, gq, gr,
        gr.jp, greta.fr, gs, gs.cn, gsm.pl, gt, gu, gu, gub.uy, guernsey.gg,
        gunma.jp, gv.at, gw, gx.cn, gy, gz.cn, hb.cn, he.cn, health.vn, hi,
        hi.cn, hiroshima.jp, hk, hk.cn, hl.cn, hm, hn, hn.cn, hokkaido.jp,
        hotel.hu, hr, ht, hu, hu.com, huissier-justice.fr, hyogo.jp, ia,
        ibaraki.jp, id, id, id.au, id.fj, id.lv, idf.il, idv.hk, idv.tw, ie, il,
        il, im, in, in, ind.br, ind.gg, ind.in, ind.je, ind.tn, inf.br, info,
        info.au, info.co, info.et, info.hu, info.pl, info.tn, info.tt, info.ve,
        info.vn, ingatlan.hu, int, int.ar, int.co, int.ve, int.vn, intl.tn, io,
        iq, ir, is, ishikawa.jp, it, it.tt, iwate.jp, iwi.nz, je, jersey.je,
        jl.cn, jm, jo, jobs, jogasz.hu, jp, js.cn, k12.ec, k12.il, k12.tr,
        kagawa.jp, kagoshima.jp, kanagawa.jp, kanazawa.jp, kawasaki.jp, ke, kg,
        kh, ki, kitakyushu.jp, km, kn, kobe.jp, kochi.jp, konyvelo.hu, kp, kr,
        ks, kumamoto.jp, kw, ky, ky, kyonggi.kr, kyoto.jp, kz, la, la, lakas.hu,
        law.za, lb, lc, lg.jp, li, lk, lkd.co.im, ln.cn, lr, ls, lt, ltd.gg,
        ltd.je, ltd.uk, lu, lv, ly, ma, ma, mail.pl, maori.nz, matsuyama.jp,
        mb.ca, mc, md, md, me, me.uk, med.ec, med.om, med.sa, med.sd,
        medecin.fr, media.hu, media.pl, mg, mh, mi, miasta.pl, mie.jp, mil,
        mil.ac, mil.ar, mil.br, mil.co, mil.do, mil.ec, mil.ge, mil.gu, mil.id,
        mil.in, mil.jo, mil.kh, mil.lb, mil.lv, mil.nz, mil.pe, mil.ph, mil.pl,
        mil.sh, mil.tr, mil.uy, mil.ve, mil.ye, mil.za, miyagi.jp, miyazaki.jp,
        mk, ml, mm, mn, mn, mo, mo, mo.cn, mob.nr, mobil.nr, mobile.nr, mod.om,
        mod.uk, mp, mq, mr, ms, ms, mt, mt, mu, muni.il, museum, museum.om, mv,
        mw, mx, my, mz, na, nagano.jp, nagasaki.jp, nagoya.jp, name, name.et,
        name.tt, name.vn, nara.jp, nat.tn, nb.ca, nc, nc, nd, ne, ne, ne.jp,
        ne.kr, net, net.ac, net.ae, net.ar, net.au, net.az, net.bb, net.bh,
        net.bm, net.br, net.bs, net.ck, net.cn, net.cu, net.cy, net.do, net.dz,
        net.ec, net.eg, net.et, net.fk, net.ge, net.gg, net.gu, net.hk, net.id,
        net.il, net.im, net.in, net.je, net.jo, net.jp, net.kh, net.kw, net.la,
        net.lb, net.lc, net.lv, net.ly, net.ma, net.mm, net.mo, net.mt, net.mx,
        net.my, net.na, net.nc, net.ng, net.ni, net.np, net.nz, net.om, net.pa,
        net.pe, net.pg, net.ph, net.pk, net.pl, net.py, net.qa, net.ru, net.sa,
        net.sb, net.sd, net.sg, net.sh, net.sy, net.th, net.tn, net.tr, net.tt,
        net.tw, net.ua, net.uk, net.uy, net.ve, net.vi, net.vn, net.vu, net.ws,
        net.ye, net.za, news.hu, nf, nf.ca, ng, ngo.ph, ngo.za, nh, nhs.uk, ni,
        nic.im, nic.in, nic.tt, nic.uk, nieruchomosci.pl, niigata.jp, nj, nl,
        nl.ca, nm, nm.cn, no, no.com, nom.co, nom.fk, nom.fr, nom.ni, nom.pe,
        nom.pl, nom.re, nom.ve, nom.za, notaires.fr, np, nr, ns.ca, nt.ca, nu,
        nu.ca, nvus, nx.cn, ny, nz, oh, oita.jp, ok, okayama.jp, okinawa.jp,
        om, on.ca, or, or.at, or.cr, or.id, or.jp, or.kr, or.th, or.ug, org,
        org.ac, org.ae, org.ai, org.ar, org.au, org.az, org.bb, org.bh, org.bm,
        org.br, org.bs, org.ck, org.cn, org.co, org.cu, org.cy, org.do, org.dz,
        org.ec, org.eg, org.et, org.fj, org.fk, org.ge, org.gg, org.gu, org.hk,
        org.hu, org.il, org.im, org.in, org.je, org.jo, org.jp, org.kh, org.kw,
        org.la, org.lb, org.lc, org.lv, org.ly, org.ma, org.mm, org.mo, org.mt,
        org.mx, org.my, org.na, org.nc, org.ng, org.ni, org.np, org.nz, org.om,
        org.pa, org.pe, org.ph, org.pk, org.pl, org.py, org.qa, org.ru, org.sa,
        org.sb, org.sd, org.sg, org.sh, org.sv, org.sy, org.tn, org.tr, org.tt,
        org.tw, org.ua, org.uk, org.uy, org.ve, org.vi, org.vn, org.vu, org.ws,
        org.ye, org.yu, org.za, org.zw, osaka.jp, otc.au, oz.au, pa, pa, pc.pl,
        pe, pe.ca, pe.kr, per.kh, per.sg, pf, pg, ph, pharmacien.fr, pk, pl,
        plc.co.im, plc.uk, plo.ps, pm, pn, pol.dz, police.uk, port.fr,
        powiat.pl, pp.ru, pr, pr, prd.fr, press.ma, presse.fr, priv.at, priv.hu,
        priv.pl, pro, pro.ae, pro.om, pro.tt, pro.vn, ps, psi.br, pt, pub.sa,
        pvt.ge, pw, py, qa, qc.ca, qc.com, qh.cn, re, re.kr, realestate.pl,
        rec.br, rec.co, rec.ve, red.sv, reklam.hu, rel.pl, res.in, ri, rnrt.tn,
        rns.tn, rnu.tn, ro, ru, ru.com, rw, sa, sa.com, sa.cr, saga.jp,
        saitama.jp, sapporo.jp, sark.gg, sb, sc, sc, sc.cn, sch.ae, sch.gg,
        sch.je, sch.ng, sch.sa, sch.sd, sch.uk, school.fj, school.nz, school.za,
        sci.eg, sd, sd, se, se.com, se.tt, sec.ps, sendai.jp, seoul.kr, sex.hu,
        sex.pl, sg, sh, sh.cn, shiga.jp, shimane.jp, shizuoka.jp, shop.hu,
        shop.pl, si, sj, sk, sk.ca, sklep.pl, sl, sld.pa, sm, sn, sn.cn, so,
        sos.pl, sp.br, sport.hu, sr, st, store.co, store.ve, su, suli.hu, sv,
        sx.cn, sy, sz, szex.hu, szkola.pl, takamatsu.jp, targi.pl, tc, td,
        tec.ve, tel.no, tel.nr, telecom.na, telememo.au, tf, tg, th, tj, tj.cn,
        tk, tl, tlf.nr, tm, tm.fr, tm.hu, tm.mt, tm.pl, tm.za, tmp.br, tn, to,
        tochigi.jp, tokushima.jp, tokyo.jp, tottori.jp, tourism.pl, tourism.tn,
        toyama.jp, tozsde.hu, tp, tr, travel, travel.pl, tt, turystyka.pl, tv,
        tw, tw.cn, tx, tz, ua, uba.ar, ug, uk, uk.com, uk.net, uk.tt, um,
        unam.na, us, us.com, us.tt, ut, utazas.hu, utsunomiya.jp, uu.mt, uy,
        uy.com, uz, va, va, vc, ve, veterinaire.fr, vg, vi, vi, video.hu, vn,
        vt, vu, wa, wakayama.jp, web.co, web.do, web.pk, web.ve, web.za, wf, wi,
        ws, wv, wy, xj.cn, xxx, xz.cn, yamagata.jp, yamaguchi.jp, yamanashi.jp,
        ye, yk.ca, yn.cn, yokohama.jp, yt, yu, za, za.com, zj.cn, zm, zw )
)
</code>

Latest revision as of 06:47, 13 March 2018

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.

Please note: The @match rule is safer than the older @include rule, and now widely supported, so you are recommended to use that instead. Read about the @match rule here.

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.