Ed Wildgoose writes:

Yes it does. At least the maildropfilter page I'm looking at has a section called "PATTERNS", which describes every regular expression syntax implemented by maildrop. If something does not appear in that section, then it's not implemented, as far as regular expressions go.

I'm going to reproduce that portion of the man page, then you can explain to me what exactly "DOESN'T describe exactly what works", below:

PATTERNS The pattern syntax in maildrop is similar to the grep command’s syn- tax, with some minor differences. A pattern takes the following form in the filter file:

/pattern/:options

pattern specifies the text to look for in the message. pattern, because the leading slash will then be interpreted as a division sign. If you must search for text that starts with a space, use something like "/[ ] ... /".

With the exception of the following characters, an exact match is looked for. The following special characters are used to specify com- plex patterns. If it is necessary to look for one of the following characters, verbatim, in the message, put a backslash in front of it. "x" and "abc" designates an arbitrary character, or a pattern, which may include other special characters as well.

x* Look for zero, or more, occurrences of the single character x.

(abc)* Look for zero or more occurrences of abc.

x+ Look for at least one, may be more, occurrences of the single character x.

(abc)+ Look for at least one, or more, occurrences of abc.

x? Look for zero, or one occurrence of the single character x.

. The period matches any character except the newline character. (This is also applicable within sets - see below).

(abc)? look for zero, or one occurrence, of "abc".

abc!def The exclamation mark is used to separate sections of matched pattern. See "Pattern Match Results" below.

[abc] Specifies a set of characters - this matches one character, either a, b, or c. List all characters that can be matched between the brackets. One or more characters can be listed. For example, [~=+] matches either a tilde, an equals sign, or a +. This is EXACTLY equivalent to (~|=|+), however with large list of characters this notation is much shorter. In addition, [a-b] matches any character between a and b, inclusive. For example: [0-9] matches a digit. [0-9A-Za-z_] matches either a digit, a letter, or an underscore. To include the dash, the left or the right bracket character in the set itself, prefix them with a backslash. Use two backslashes to include the back- slash character itself. (Other, historical ways of including these special characters are permitted, but discouraged).

[^abc] specifies a set of characters that is NOT the given characters indicated. If the set begins with the ^ symbol, it matches a single character that is NOT any of the characters listed.

\x where "x" is a character. Specifies that x must be matched exactly. In order to match any special character verbatim (for example - you want to match the asterisk, *) you must prefix it with a backslash character. Use two backslashes in order to match a backslash character verbatim. Also, there are several characters reserved for matching control characters, without having to enter them verbatim into the pattern. See below for more information.

\nnn specifies a character in octal. "nnn" is an octal number.

The following shorthand notation can be used to specify some common sets. Note that maildrop always uses the "C" locale:

[:alnum:] An alphanumeric character, same as [0-9A-Za-z].

[:alpha:] An uppercase or a lowercase letter, same as [A-Za-z].

[:cntrl:] A control character.

[:digit:] A digit, same as [0-9].

[:graph:] A "graphable" character (a non-control character that’s not a space).

[:lower:] A lowercase letter, same as[a-z].

[:print:] A printable character (not a control character).

[:punct:] A punctuation character.

[:space:] Any whitespace character.

[:upper:] An uppercase letter, same as [A-Z].

[:wbreak:] Any character other than a letter, digit, or an underscore, same as [^a-zA-Z0-9_].

[:xdigit:] A hexadecimal digit, same as [0-9A-Fa-f].

To match any special character, put a backslash in front of it. For example, \? matches the question mark. To match a backslash, use \\.

Normally, the pattern can be found anywhere within the message header or body (see below). However, putting the character ^ at the beginning of the pattern forces the pattern to be matched against the beginning of the line only. Putting the character $ at the end of the pattern forces the pattern to be matched against the end of the line only.

Elsewhere in the pattern, the $ sign is used for variable substitution (see above). To include the $ character in the pattern, prefix it with a backslash.

OTHER BACKSLASH SUBSTITUTIONS The following backslashed characters are interpreted as follows, when used in a pattern specification:

\n Matches a newline character. Note - this is only effective if the w option is specified, because without this option maildrop does not recognize multi-line patterns.

\r Matches a carriage return. Note - maildrop automatically ignores carriage returns at the end of each line. I don’t know why you’d want to use \r, but it’s there if you need it.

\t Matches a tab.

\f Matches a form feed.

\v Matches a vertical tab.

Long double or singly-quoted text can be broken across multiple lines by ending the line with a lone backslash character, like this:

TEXT="This is a long \ text string" The backslash, the newline, and all leading whitespace on the next line is removed, resulting in "This is a long text string".

PATTERN OPTIONS Following /pattern/, there may be an optional colon, followed by one. or more options. The following options may be specified in any order:

h Match this pattern against the message header.

b Match this pattern against the message body.

w Match this pattern against the entire message and/or body.

D This is a case sensitive match. Normally the patterns match either uppercase or lowercase text. /john/ will match "John", "john", or "JOHN". Specify the D option for a case-sensitive search: lowercase letters in the pattern must match lowercase letters in the message; ditto for uppercase.

Please note that the ’b’ and the ’w’ options consume an excessive amount of CPU time, and should be avoided, if possible. HINT: If pos- sible, use the SIZE variable to avoid using patterns with these flags on large messages.

If neither ’h’ or ’b’ is specified, the pattern is matched against the header only. Specifying the ’b’ option causes the pattern to be matched against the message body. Specifying both causes the pattern to be matched against the entire message.

Normally, each line in the message gets matched against the pattern individually. When applying patterns to a header, multi-line headers (headers split on several lines by beginning each continuation line with whitespace) are silently combined into a single line, before the pattern is applied. Specifying the ’w’ flag causes the pattern to be applied to the whole part of the message that’s being searched (which is specified via the presence, or the absence, of the h and b flags). Also, if the ’w’ flag is used, but neither ’h’ nor ’b’ flags are used, the ’b’ flag is the default, instead of the ’h’ flag.

This flag also changes the way that ^ and $ is interpreted in pat- terns. Normally, those characters anchor the pattern at the begin- ning, or the end, of each line. When the ’w’ flag is specified, ^ and $ anchors the pattern against the beginning, or the end, of either the header, body, or both.

WEIGHTED SCORING Patterns are evaluated by maildrop as any other numerical expression. If a pattern is found, maildrop’s filter interprets the results of the pattern match as number 1, or true, for filtering purposes. If a pat- tern is not found the results of the pattern search is zero. Once a pattern is found, the search stops. Second, and subsequent occurrences of the same pattern are NOT searched for.

maildrop can also do weighted scoring. In weighted scoring, multiple occurrences of the same pattern are used to calculate a numerical score.

To use a weighted search, specify the pattern as follows:

/pattern/:options,xxx,yyy where xxx and yyy are two numbers. yyy is optional -- it will default to 1, if missing.

The first occurrence of the pattern is evaluated as xxx. The second occurrence of the pattern is evaluated as xxx*yyy, the third as xxx*yyy*yyy, etc... All occurrences of the pattern are added up to calculate the final score.

Note:

When the w option is not specified, maildrop does not recognize multiple occurrences of the same pattern in the same line. This is required in order to have the ^ and $ operators working cor- rectly. For example:

/^Received:/:1 This pattern counts how many Received: headers the message has, and does not recognize any occurrences of the text "Received:" anywhere else in the headers.

You must specify the w option in order to take into account multiple occurrences of the same pattern in the message. This also activates all the usual semantics of the ’w’ option. For example:

/[:upper:]/:wbD,1 counts the number of uppercase letters in the body of the message.

PATTERN MATCH RESULTS After a pattern is successfully matched, the actual text that is matched is placed in the MATCH variable. For example:

/^From:.*/ matches a line of the form:

From: postmaster@localhost

Here the variable MATCH will be set to "From: postmaster@localhost", which can be used in subsequent statements. It is possible to use selective parts of the matched string by using the ! character in patterns. For example:

/^From: *!.*/ matched against the same line will set MATCH to "From: " and MATCH2 to "postmaster@localhost". More than one ! character may be used. Sub- sequent matched text is assigned to MATCH3, MATCH4, and so on.

Note: Please note that the abuse of this feature will eat plenty of CPU time -- the ! character introduces a lot of com- plexity for maildrop to deal with.

When there is more than one way to match a string, maildrop favors matching as much as possible initially. For example:

/^To:.*,!.*/ when matched against

To: joe@somewhere,bo...@somewhere.else,gary@whoknowswhere will set MATCH to "To: joe@somewhere,bo...@somewhere.else," and MATCH2 to "gary@whoknowswhere".

The MATCH variables are NOT set when weighted scoring is used, since the same pattern is matched multiple times.