Here is an example for one of the central macros of WWW Shield. The long macro description string is broken into multiple lines for easy reading; it must be entered in one long line in the rules file.
nobanner = [
"ad.preferences.com",
"doubleclick.net",
"promo",
"adlink",
"adforce",
"bannerbroker"
];
macro "nobanner" "<B>Remove banner ads</B>\nAll pictures and all
hyperlinks from the list are replaced with a short notice, [deleted]. Any link,
image, or form action that contains one of the words in the list is killed.$nobanner"
true
{
if (a.href contains nobanner) {
kill;
insert "[<a href=" . a.href . ">deleted</A>]";
}
if (img.src contains nobanner) {
kill;
insert "[<a href=" . img.src . ">deleted</A>]";
}
if (form.action contains nobanner) {
kill;
insert "[<a href=" . form.action . ">deleted</A>]";
}
}
The macro statement defines a macro with the name nobanner. A descriptive text that is shown in the macro page follows. Note the formatting conventions - it begins with a brief boldfaced name, followed by a paragraph break (\n), and a detailed description that explains in simple terms what the macro is doing. The true token that follows enables the macro by default, which means it is checked in the macro page.
Before the macro definition, there is a variable that has the same name as the macro itself (a useful convention), nobanner. This variable appears after a dollar sign in the macro description, which causes WWW Shield to insert a text entry field for the variable after the word killed. This variable exist before the macro definition. It is an array variable, indicated by the square brackets that enclose a comma-separated list of values.
The macro body is enclosed in curly braces. It consists of three if statements. Each condition tests whether the value of a variable is contained in the nobanner variable. Since this variable is an array, the condition checks if the value of the left-hand-side (lhs) variable is contained in any of the right-hand-side array members. For example, if the HTML file contains the HTML command
<a href=http://www.promo.com/ad.html> click me </A>
WWW Shield will set the variable a.href to the value http://www.promo.com/ad.html. Note that capitalization does not matter for variable names - if the HTML command were lowercase, or the variable name in the macro were uppercase, it would still work. If the macro is enabled (it is by default), it will be executed when the first > is found. The if condition will now check whether the string http://www.promo.com/ad.html contains any of the strings in the nobanner array. Since the third array member, promo, is contained in http://www.promo.com/ad.html, the condition is true, so the if body, enclosed in braces, is executed.
The if body contains two commands. The first, kill, instructs WWW Shield to delete the entire <a href=http://www.promo.com/ad.html> command, and the following text (click me), up to the matching closing statement (</A>). Closing statements always begin with a slash. If drop command had been used, only the <A...> part but not the click me or </A> would have been deleted. It is important to never kill a HTML command that has no closing statement, such as <img> - WWW Shield would kill all the way to the end of the page because it never finds /img. WWW Shield can deal with nested statements too, and picks the correct closing statement.
Now we got rid of the original hyperlink. The following insert statement inserts a new HTML command in this location. Since the original statement was killed, there is no difference between insert and append here, but if it hadn't been killed (or dropped) insert would have put the new text before the <A and append would have put it after the ...html>.
The text being inserted is a string, put together by concatenating three parts. The first and third are literal quoted strings, and the middle one is the value of the variable that was already used in the condition. Effectively, the original HTML commands shown above are replaced with
[<a href=http://www.promo.com/ad.html>deleted</A>]
The difference seems small - there are square brackets now, and the click me text was replaced with deleted. The point is that the HTML page probably did not say click me but showed a large animated GIF image, which is now gone. The hyperlink is retained because the user may want to follow it after all, or check where it leads, but it has been rendered unobtrusive.
The next two if statements do basically the same thing, only for images and embedded scripts or Java programs.
|
| Language documentation |
|
| Go to WWW Shield's main menu |
|
| Back to my home page |
|
| Tell me if you found this information interesting or useful, or if you have comments. |