Exim Filter Specification - String testing conditions

Go to the first, previous, next, last section, table of contents.

## String testing conditions

There are a number of conditions that operate on text strings, using the words `begins', `ends', `is', `contains' and `matches'. If the condition names are written in lower-case, the testing of letters is done without regard to case; if they are written in upper-case (for example, `CONTAINS') then the case of letters is significant.

         <text1> begins <text2>
         <text1> does not begin <text2>
    e.g. $header_from: begins "Friend@"

A `begins' test checks for the presence of the second string at the start of the first, both strings having been expanded.

         <text1> ends <text2>
         <text1> does not end <text2>
    e.g. $header_from: ends "public.com"

An `ends' test checks for the presence of the second string at the end of the first, both strings having been expanded.

         <text1> is <text2>
         <text1> is not <text2>
    e.g. $local_part_suffix is "-foo"

An `is' test does an exact match between the strings, having first expanded both strings.

         <text1> contains <text2>
         <text1> does not contain <text2>
    e.g. $header_subject: contains "evolution"

A `contains' test does a partial string match, having expanded both strings.

         <text1> matches <text2>
         <text2> does not match <text2>
    e.g. $sender_address matches "(Bill|John)@"

For a `matches' test, after expansion of both strings, the second one is interpreted as a regular expression. Exim uses the PCRE regular expression library, which provides regular expressions that are compatible with Perl.

Care must be taken if you need a backslash in a regular expression, because backslashes are interpreted as escape characters both by the string expansion code and by Exim's normal string reading code. For example, if you want to test the sender address for a domain ending in ``.com'` the regular expression is

    \.com$

The backslash and dollar sign in that expression have to be escaped when used in a filter command, as otherwise they would be interpreted by the expansion code. Thus what you actually write is

    if $sender_address matches \\.com\$

However, if the expression is given in quotes (mandatory only if it contains white space) you have to write

    if $sender_address matches "\\\\.com\\$"

with `\\\\' for a backslash and `\\$' for a dollar sign. Hence, if you actually require the string `\$' in a regular expression that is given in double quotes, you need to write `\\\\\\$'.

If the regular expression contains bracketed sub-expressions, then numeric variable substitutions such as $1 can be used in the subsequent actions after a successful match. If the match fails, the values of the numeric variables remain unchanged. Previous values are not restored after ``endif'` -- in other words, only one set of values is ever available. If the condition contains several sub-conditions connected by ``and'` or ``or'`, it is the strings extracted from the last successful match that are available in subsequent actions. Numeric variables from any one sub-condition are also available for use in subsequent sub-conditions, since string expansion of a condition occurs just before it is tested.

Go to the first, previous, next, last section, table of contents.