Gazelle Wiki | ListmomCommands / ListFiltersSet

Shown below is the e-mail command syntax to create List Filters. First, ensure that you are familiar with the List Filters terminology, otherwise much of this might not make much sense.

Syntax Rules

Everything is case independent -- this includes match strings, keywords, parameters, etc.
- The only exception is replacement text in replacement filters; case is preserved in those text strings.
Spacing is irrelevant
- Tabs are converted to spaces
- Multiple-space runs are converted to single spaces
- Leading and trailing spaces are stripped from all command lines
In most cases, equals signs "=" may be replaced by colons ":"

-> For some, colons may make the syntax easier to compose and read. Either one works.

In most cases, quotes (including quotes around the match string) are optional.

Processing Rules

Gazelle will perform multiple sequential matches, until a limiting condition is reached:
- Processing will stop when a DROP filter is matched
- Unless a DROP filter is matched, all filters will execute
-> Gazelle will not stop matching after the first match is encountered
Strings spanning continuation lines in the header will be matched.
Strings spanning different lines in the body of the message will not be matched.

Keywords

The full suite of keywords that may be used to compose a single filter are:

CREATE FILTER
MATCH
LOCATION
CONTEXT
ACTION
EXPIRATION
NOTIFY
END FILTER

Each keyword, and all parameter data that goes with it, must appear on a line by itself. Not all keywords are necessary for the creation of a filter. Some of the keywords are defaulted to pre-set values; scroll to the bottom of the page for the default settings.

Syntax

Each keyword is shown below, and the "simple" syntax for that keyword immediately follows. If there is a more complex variation of the "simple" syntax, it appears immediately after the simple syntax. Any notes or additional information for the keyword or its parameters follows the syntax. Each keyword (and its associated data) must appear on a line by itself.

CREATE FILTER: Every filter segment must begin with a "create filter" command.

create filter

MATCH: This defines the string that will be matched

match = "match string"
mat[ch] = "match string"

Notes on "match"

* The maximum length of any match string is 72 characters

* Quotes are optional

* The match string may contain any sequence of characters

- Tabs will be converted to spaces

- Multiple spaces will be compressed

- Match performance is unaffected (improved, actually) by these modifications

LOCATION: This tells Gazelle where in the message to look for the match string.

location = {header, body, anywhere} [= {any, *, header-name}]
loc[ation] = {hea[der], bod[y], any[where]} [= {any, *, header-name}]

where....

* "header" tells Gazelle to find the match string in a specific header, as follows:

- header-name specifies the header to use (e.g., "From:", "Subject:", etc.; the ending colon is optional).

- If "any" or "*" is used, then Gazelle will search all headers for the match string.

* "body" tells Gazelle to search for the match string in the body of the message.

* "anywhere" tells Gazelle that the match string may appear anywhere -- i.e., in the body or in any header.

* "body" and "anywhere" do not require a header name.

CONTEXT: Tells Gazelle what types of messages to apply against the filter.

context = {posts, commands, anywhere}
context = {pos[ts], com[mands], any[where]}

where....

* "posts" tells Gazelle to look for the match string in posts (i.e., messages to the list).

* "commands" tells Gazelle to look in command messages (i.e., messages to the server).

* "anywhere" tells Gazelle to check all messages -- posts and commands.

ACTION: Tells Gazelle what action to take upon a filter match.

action = {reject, moderate, redirect, replace} = action parameter
action = {rej[ect], mod[erate], red[irect], rep[lace]} = action parameter

where....

* "reject" tells Gazelle to reject the post when the match string is found

* "moderate" tells Gazelle to submit the post for moderation when the match string is found

* "redirect" tells Gazelle to return a message to the sender, suggesting that s/he re-send his post to a different list

* "replace" tells Gazelle to replace every occurrence of match string with the string specified in the action parameter

* The definition/interpretation of the action parameter is based on the action keyword selected above (i.e., reject, moderate, redirect, or replace), and is defined as follows:

- For "reject," the action parameter can be either a document (i.e., a file name) or the word "quiet," where:

- If a document name is specified, then that document will be sent to the sender when the post is rejected.

- If the word "quiet" is used, then no message will be returned; the post will essentially be "dropped" on the floor. (This is useful for suspected spam messages and for non-spam messages in which you don't want the user to know that the post has been rejected.)

- For "moderate," the action parameter is the reason for moderating the message (i.e., the reason for moderating the thread).

- For "redirect," the action parameter is the "short name" of the list to which the message should be redirected (where the "short name" of a list is the part to the left of the "@" sign in the list's posting address).

NOTE: The message will not actually be sent to the other list; instead, a document will be sent to the user, suggesting that the message might be more appropriate for the other list.

- For "replace," the action parameter is the text that will replace the match string.

NOTE: Case and spacing are preserved in the replacement string.

EXPIRATION: Establishes a date on which the filter will expire.

expiration = {yyyymmdd, none}
exp[iration] = {yyyymmdd, none}

where....

* yyyymmdd is a four-digit year, two-digit month, two-digit day representation of the date on which you want this filter to expire.

NOTE: The filter will continue to execute ON the expiration date, and will be removed at 1:00 a.m. ET on the day AFTER the expiration date.

* "none" specifies that the filter will never expire.

NOTIFY: Tells Gazelle whether the List Managers should be informed that this filter has executed.

notify = {yes, no}
not[ify] = {y[es], n[o]}

where....

* "yes" instructs Gazelle to send a notification message to specific List Managers, informing them that a filter has triggered.

* "no" lets the filter execute quietly.

NOTES:

1. "Specific List Managers" are those who have the "Gazelle Messages" flag set in their List Manager account profiles (this is a List Manager-settable flag).

2. It is recommended that all DROP actions (i.e., "action = reject = quiet") be sent to the List Managers for review, since the sender does not receive any notification of the drop.

END FILTER: Denotes the end of a filter.

end filter

Default Settings

Examples

CREATE FILTER
match="Steve Jobs is a jerk"
location=header=subject
context=post
action=reject=reject_message.txt
expiration=20090501
notify=yes
END FILTER

Spaces are ignored everywhere -- so the following filter is equivalent to the previous filter, and might be clearer (or at least easier to read):

CREATE FILTER
match = "Steve Jobs is a jerk"
location = header = subject
context = post
action = reject = reject_message.txt
expiration = 20090501
notify = yes
END FILTER

A replacement filter could try to fix the problem rather than kill the thread:

CREATE FILTER
match = "Steve Jobs is a jerk"
location = header = subject
context = post
action = replace = "Steve Jobs is a god"
expiration = 20090501
notify = yes
END FILTER

Or perhaps that text appeared in the body of a message in an otherwise useful thread. In that case:

CREATE FILTER
match = "Steve Jobs is a jerk"
location = body
context = post
action = moderate = "Need to stop all the pontificating about Steve Jobs"
expiration = 20090501
notify = no
END FILTER

The "digest" filter is one that would not have an expiration:

CREATE FILTER
match = "mac-l digest"
location = header = subject
context = post
action = reject = do_not_post_digest.txt
expiration = none
notify = no
END FILTER

I'll post additional examples as are necessary to help illustrate other filter cases.

Return to the Command Interface page....