Make a cheatsheet on the rules syntax

Discussion on adblockplus.org website and translations

Make a cheatsheet on the rules syntax

Postby __Vano » Sat May 28, 2011 5:55 am

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?
__Vano
 
Posts: 4
Joined: Tue Mar 01, 2011 5:35 pm

Re: Make a cheatsheet on the rules syntax

Postby Wladimir Palant » Mon May 30, 2011 10:14 am

Sure. Who is going to write it? ;)
Wladimir Palant
ABP Developer
 
Posts: 8397
Joined: Fri Jun 09, 2006 6:59 pm
Location: Cologne, Germany

Re: Make a cheatsheet on the rules syntax

Postby Michael » Mon May 30, 2011 12:55 pm

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...
Michael
 
Posts: 1361
Joined: Sat Dec 19, 2009 1:29 pm

Re: Make a cheatsheet on the rules syntax

Postby __Vano » Fri Jun 03, 2011 9:31 am

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

Finally

Postby __Vano » Mon Jun 27, 2011 3:19 am

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+)
__Vano
 
Posts: 4
Joined: Tue Mar 01, 2011 5:35 pm

Re: Make a cheatsheet on the rules syntax

Postby Michael » Mon Jun 27, 2011 5:34 pm

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 1:29 pm

Re: Make a cheatsheet on the rules syntax

Postby Michael » Sat Jul 02, 2011 1:58 pm

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.
Michael
 
Posts: 1361
Joined: Sat Dec 19, 2009 1:29 pm

Re: Make a cheatsheet on the rules syntax

Postby Wladimir Palant » Mon Jul 04, 2011 5:09 pm

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.
Wladimir Palant
ABP Developer
 
Posts: 8397
Joined: Fri Jun 09, 2006 6:59 pm
Location: Cologne, Germany

Re: Make a cheatsheet on the rules syntax

Postby Gingerbread Man » Fri Aug 12, 2011 4:46 pm

object-subrequest
~object

The second line should read ~object-subrequest, right?
User avatar
Gingerbread Man
 
Posts: 1339
Joined: Fri Aug 12, 2011 5:28 am

Re: Make a cheatsheet on the rules syntax

Postby Wladimir Palant » Tue Aug 16, 2011 3:58 pm

@Gingerbread Man: Sure, that was a copy&paste mistake.
Wladimir Palant
ABP Developer
 
Posts: 8397
Joined: Fri Jun 09, 2006 6:59 pm
Location: Cologne, Germany

Re: Make a cheatsheet on the rules syntax

Postby Wladimir Palant » Thu Aug 18, 2011 8:11 am

@Michael: You should have permission to edit https://adblockplus.org/en/filter-cheatsheet if you like to - sorry about stalling that work.
Wladimir Palant
ABP Developer
 
Posts: 8397
Joined: Fri Jun 09, 2006 6:59 pm
Location: Cologne, Germany

Re: Make a cheatsheet on the rules syntax

Postby Michael » Tue Aug 23, 2011 5:34 pm

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".
Michael
 
Posts: 1361
Joined: Sat Dec 19, 2009 1:29 pm

Re: Make a cheatsheet on the rules syntax

Postby Wladimir Palant » Tue Aug 23, 2011 5:49 pm

Heh, Anwiki permissions are quite tricky :-(
Should be working now (this time I tested it).
Wladimir Palant
ABP Developer
 
Posts: 8397
Joined: Fri Jun 09, 2006 6:59 pm
Location: Cologne, Germany

Re: Make a cheatsheet on the rules syntax

Postby Michael » Tue Aug 23, 2011 6:22 pm

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 1:29 pm

Re: Make a cheatsheet on the rules syntax

Postby Michael » Tue Aug 23, 2011 10:05 pm

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?
Michael
 
Posts: 1361
Joined: Sat Dec 19, 2009 1:29 pm

Next

Return to Website and translations

Who is online

Users browsing this forum: No registered users and 2 guests