Make a cheatsheet on the rules syntax

Discussion on adblockplus.org website and translations
__Vano
Posts: 4
Joined: Tue Mar 01, 2011 4:35 pm

Make a cheatsheet on the rules syntax

Post by __Vano »

Can we have subj in documentation so I don't have to read all the verbiage at http://adblockplus.org/en/filters to extract a grain of information?
Wladimir Palant

Re: Make a cheatsheet on the rules syntax

Post by Wladimir Palant »

Sure. Who is going to write it? ;)
Michael
Posts: 1361
Joined: Sat Dec 19, 2009 12:29 pm

Re: Make a cheatsheet on the rules syntax

Post by Michael »

I'll have some time to write the documentation in about a month or so if there is no particular rush. However, you may have to remind me about it...
__Vano
Posts: 4
Joined: Tue Mar 01, 2011 4:35 pm

Re: Make a cheatsheet on the rules syntax

Post by __Vano »

Good. I have scheduled to do it within the week.
__Vano
Posts: 4
Joined: Tue Mar 01, 2011 4:35 pm

Finally

Post by __Vano »

Here it is. I don't yet have the right to edit wiki nor it has a 'view source' function. So I can't know the local markup and am using an ad-hoc one (using HTML or MediaWiki's would require too much rewriting if local one differs greatly).

Lists are intended to be tables, each item being a row. "--" is the column separator. A sublist is a subtable. Everything that's supposed be the part of a filter code and references to such parts are intended to be monospace. Bold subheaders inside lists are intended to be colspan unless there's an embedded column separator, in that case they are column headers.

The grammar used is a standard command-line syntax format grammar.

Important: "??" designate the details that aren't described in "Writing... filters" and need further clarification.

General format
  • Format -- Comments
  • string -- Match anywhere (there is an implied * at start and at end). The match is case-insensitive. Metacharacters are:
    • * -- matches anything
    • ^ -- matches an URL separator - anything except letters, digits, underscore(_), minus(-), dot(.), percent sign(%). Matches at the end of the line, too.
    (?? metacharacter escaping?)
  • /regexp/ -- match a JavaScript regular expression rather than wildcards. Can be used anywhere where a string is expected. The use is not recommended for performance reasons
  • |string -- Match at the start of URL
  • string| -- Match at the end of URL
  • ||example.com/banner.gif -- Match at the start of URL, both http and https and subdomains
  • @@rule -- an exception rule
  • @@|http://example.org -- Disable ABP for all pages in a domain (?? subdomains?). Address must start with http:// or https://, pipe is optional
  • ! This is a comment -- a comment (-C.O.)
  • rule$option[,...] -- filter options (see below)
Element hiding rules
Warning: These rules' syntax is unrelated to the general syntax! Specifically, wildcards and regexps cannot be used unless stated otherwise.
Element Hiding Helper extension is a great help in writing these filters.
  • ##[tag][attr-spec[...]][,...] -- hide the contents of elements matching the given CSS3 selector (note that not all CSS3 selectors are supported by FF yet).
    In particular:
    Hide tag(s) with attributes matching the given specification(s).
    Either tag or specifications can be omitted. To omit both, use * as tag.
    An attribute specification can be one of the following:
    • #id -- id attribute equals id
    • .class or [class~=class] -- class attribute includes class
    • [attr[*|^|$]="str"] -- attr attribute matches str (?? how to specify embedded quotes?)
      The comparison methods are:
      • = -- equals
      • *= -- contains
      • ^= -- starts with
      • $= -- ends with
  • ##tag-spec1 > tag-spec2[:firstchild][:lastchild] [+ ...] -- hide contents of a tag matching tag-spec1 that has child(ren) matching tag-spec2, etc (?? in that/any order?) optionally requiring a child to be the first and/or the last child. (?? must the number of children be equal to the number of child tags specified here if there's more than one specified? - element hide helper suggests it must) (?? can a child specification match multiple child tags?)
    This construction can be recursed. (?? how are subexpressions delimited?)
    If there are multiple children specified, "tag-spec1 >" can be omitted to block any tag with matching children.
  • [~]domain[,...]##rule -- only apply an element-blocking rule to domain(s), including subdomains. A leading tilde excludes a domain and its subdomains.
  • browser##rule -- (side-effect) apply an element-blocking rule to FF UI (?? link to info on its object tree)
  • #tag[(attr=value) -- deprecated simplified element hiding syntax. (?? details?)
Filter options
Make the filter only apply to specific objects or otherwise modify its behavior
(?? how various options are connected together, precedence)
  • Type options -- apply to objects of a specific type
  • script -- external scripts loaded via HTML script tag
  • image -- regular images, typically loaded via HTML img tag
  • background -- background images, often specified via CSS
  • stylesheet -- external CSS stylesheet files
  • object -- content handled by browser plugins, e.g. Flash or Java
  • xbl -- XBL bindings (typically loaded by -moz-binding CSS property)
  • ping -- link pings
  • xmlhttprequest -- requests started by the XMLHttpRequest object
  • object-subrequest -- requests started by plugins like Flash
  • dtd -- DTD files loaded by XML documents
  • subdocument -- embedded pages, usually included via HTML frames
  • document -- the page itself (exception rules only, disables ABP for the page)
  • elemhide -- similar to document but only disables element hiding rules rather than all filter rules (exception rules only) (ABP 1.2+)
  • other -- everything else
  • Other options
  • ~option -- negate option (applicable to all options except domain)
  • third-party -- apply to requests with the different origin that the currently viewed page (?? explain how it can be, e.g. example)
  • domain=[~]domain1[|[~]domain2[,...]] -- apply to domain and subdomains. A leading tilde excludes a domain with subdomains
  • match-case -- match case-sensitively
  • collapse -- override the "Collapse blocked elements" setting
  • donottrack -- send a Do-Not-Track header unless the URL also matches an exception rule with such option (ABP 1.3.5+)
Michael
Posts: 1361
Joined: Sat Dec 19, 2009 12:29 pm

Re: Make a cheatsheet on the rules syntax

Post by Michael »

I'd actually also started to write the documentation as you hadn't responded for nigh on a month - I have uploaded my finished version of the blockable items cheat sheet to the EasyList website for examination.
Michael
Posts: 1361
Joined: Sat Dec 19, 2009 12:29 pm

Re: Make a cheatsheet on the rules syntax

Post by Michael »

I have uploaded an updated version of the file to the EasyList website with documentation of what I believe is all relevant Adblock Plus filter syntax.
Last edited by Michael on Wed Sep 07, 2011 8:20 pm, edited 1 time in total.
Wladimir Palant

Re: Make a cheatsheet on the rules syntax

Post by Wladimir Palant »

I started combining the two versions: http://adblockplus.org/en/filter-cheatsheet

I think that separating by filter type is a good idea, mixing info on blocking filters and element hiding rules isn't going to be useful. I liked the listing of syntax elements and the examples in Michael's version but the explanation needs to be shorter, that's a cheat sheet after all.
User avatar
Gingerbread Man
Posts: 1339
Joined: Fri Aug 12, 2011 5:28 am

Re: Make a cheatsheet on the rules syntax

Post by Gingerbread Man »

object-subrequest
~object
The second line should read ~object-subrequest, right?
Wladimir Palant

Re: Make a cheatsheet on the rules syntax

Post by Wladimir Palant »

@Gingerbread Man: Sure, that was a copy&paste mistake.
Wladimir Palant

Re: Make a cheatsheet on the rules syntax

Post by Wladimir Palant »

@Michael: You should have permission to edit en/filter-cheatsheet if you like to - sorry about stalling that work.
Michael
Posts: 1361
Joined: Sat Dec 19, 2009 12:29 pm

Re: Make a cheatsheet on the rules syntax

Post by Michael »

While I would like to start work on the cheat sheet, when logged in I am no longer able to even edit a translation - the only options available are "New translation", "View" and "History".
Wladimir Palant

Re: Make a cheatsheet on the rules syntax

Post by Wladimir Palant »

Heh, Anwiki permissions are quite tricky :-(
Should be working now (this time I tested it).
Michael
Posts: 1361
Joined: Sat Dec 19, 2009 12:29 pm

Re: Make a cheatsheet on the rules syntax

Post by Michael »

The "Edit" and "Translate" options are now present thanks. I will start work later this evening and report progress in this topic.
Michael
Posts: 1361
Joined: Sat Dec 19, 2009 12:29 pm

Re: Make a cheatsheet on the rules syntax

Post by Michael »

I've added a few more filter options and should finish documenting the type options tomorrow. Should I separate out the other options, as shown in my original attempt, or add them all to the filter options table?
Post Reply