Make a cheatsheet on the rules syntax
Make a cheatsheet on the rules syntax
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?
Re: Make a cheatsheet on the rules syntax
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...
Re: Make a cheatsheet on the rules syntax
Good. I have scheduled to do it within the week.
Finally
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
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.
Make the filter only apply to specific objects or otherwise modify its behavior
(?? how various options are connected together, precedence)
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.
- /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)
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?)
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+)
Re: Make a cheatsheet on the rules syntax
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.
Re: Make a cheatsheet on the rules syntax
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.
Re: Make a cheatsheet on the rules syntax
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.
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.
- Gingerbread Man
- Posts: 1339
- Joined: Fri Aug 12, 2011 5:28 am
Re: Make a cheatsheet on the rules syntax
The second line should read ~object-subrequest, right?object-subrequest
~object
Re: Make a cheatsheet on the rules syntax
@Gingerbread Man: Sure, that was a copy&paste mistake.
Re: Make a cheatsheet on the rules syntax
@Michael: You should have permission to edit en/filter-cheatsheet if you like to - sorry about stalling that work.
Re: Make a cheatsheet on the rules syntax
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".
Re: Make a cheatsheet on the rules syntax
Heh, Anwiki permissions are quite tricky
Should be working now (this time I tested it).
Should be working now (this time I tested it).
Re: Make a cheatsheet on the rules syntax
The "Edit" and "Translate" options are now present thanks. I will start work later this evening and report progress in this topic.
Re: Make a cheatsheet on the rules syntax
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?