Back: wiki:Extensions/KarmaBlocker

The operation of Karma Blocker is divided into sections like the common .ini file format. There are four valid kinds of lines:

  • A group header.
    I.E.: [Settings], [Group].
  • A configuration directive.
    Always a field name, an equals sign, then a value appropriate for the field.
    I.E.: threshold=5.
  • A comment (valid anywhere).
    A hash mark followed by anything, up to the end of the line.
    I.E.: # This group will ...
  • A blank line.

Whitespace (newline, space, tab) can exist between any valid tokens; it will be ignored. A comment can start anywhere, not only at the beginning of a line. The values usually fall into one of these groups:

number
Any positive or negative integer or floating point number.
string
Any character string, delimited by single or double quotes. Strings do not span lines.
boolean
Either of true or false, exactly.

Settings

The [Settings] section describes the overall operation of Karma Blocker.

Field Values Description
threshold number The threshold is the minimum score required to block. Each group gets a score; each matching group's score is added together. When that total is greater than or equal to the threshold, the resource will be blocked.
cutoff number The cutoff functions just like the threshold. The difference between the two is that the threshold is only compared after all groups have been checked, while the cutoff is checked after every group. If, at any point, the score is greater than or equal to the cutoff, the request is immediately denied. (Immediately accepted if it is less than or equal to the negative value of the cutoff.)

Inject

The [Inject] section controls injection of dummy content into web pages.

Field Values Description
function string This line may be repeated one or more times. For each time that it is provided, a function with the name passed will be placed into content pages. Use this to avoid "something is undefined" error messages when scripts are blocked.

Group

The [Group] section is the main meat of Karma Blocker. You may have one or more group sections.

Field Values Description
name string A name which will be displayed in the monitor window.
match One of: any, all This group matches when any of its rules match, or matches when all of its rules match. (Default: any)
score number When this group matches, this score is added onto the total karma for this resource. (Default: 1)
rule see below The rule line specifies a field, an operator, and a value to check for. Since it is complicated, it gets its own section.

Rules

Rules come in a simple format with many possibilities: a field, an operator, and a value. Each field has different values that are appropriate to match it; different values have different appropriate operators.

Operators:

Name Operator Description
Equals == Field matches value exactly.
Not equals != Boolean opposite of equals.
Matches =~ Applies a regular expression (regex) to the field. The regex should be expressed as a string. For those who know JavaScript: his string is passed directly to the new RegExp() constructor. For everyone else: this means that you do '''not''' need to backslash-escape forward slashes. Otherwise, this is a standard regex expressed as a string, with all the capabilities of Mozilla's engine.
Not matches !~ Boolean opposite of matches.
Starts-with ^= Though this could be written as a regex with the match operator, the starts-with operator uses plain string operations, so there should be '''no''' character escaping.
Ends-with $= Complement to starts-with.

(Note: all comparisons are done in a case-insensitive manner.)

Fields

Field Values Description
$thirdParty boolean When the referrer is a different domain than the resource, third party is true. Equals is the only operator that makes sense for this field.
$type other, script, image, stylesheet, object, document, subdocument, refresh These values are based on the constants defined in the Mozilla interface nsIContentPolicy. Most of these are self-explanitory, but read that page for a more thorough description. Equals and not equals are the only operators that make sense for this field.
$url string The (full) URL of the resource being evaluated. Also available: $url.host, $url.path, $url.scheme, for just those parts of the URL.
$origin string The (full) URL of the "origin" of the resource being evaluated. Also known as the "referrer". Also available: $origin.host, $origin.path, $origin.scheme for just those parts of the URL.
$origin.tag string The HTML tag name (i.e. img, style, script, object) that this resource is being loaded into.