Mapping entry patterns

Mapping patterns can contain wildcard characters. In particular, the usual so-callled "glob style" wildcard characters are allowed: an asterisk, , will match zero or more characters and each percent sign,  , will match a single character. Asterisks, percent signs, spaces, and tabs can be quoted by preceding them with a dollar sign,. Quoting an asterisk or percent sign robs it of any special meaning. Spaces and tabs must be quoted to prevent them from ending prematurely a pattern or template. Literal dollar sign characters should be doubled,, the first dollar sign quoting the second one. Additional wildcards available in patterns are listed in the table shown below.

(‡) When combined with a back match or glob wildcard, only one dollar sign character is used for both; for instance,  is a non-saved back match of the first (0th) wildcard, and similarly,   is a non-saved alphabetic character glob wildcard.

Within globs, i.e., within a ...   construct, the backslash character, , is the quote character. To represent a literal hyphen, , or right bracket,  , within a glob the hyphen or right bracket must be quoted with a backslash.

All other characters in a pattern just represent and match themselves. In particular, single and double quote characters as well as parentheses have no special meaning in either mapping patterns or templates; they are just ordinary characters. This makes it easy to write entries that correspond to illegal addresses or partial addresses.

Note that to specify multiple modifiers, or to specify modifiers and a back match, or to specify modifiers and a glob, the syntax uses just one dollar character. For instance, to back match the initial wild card, without saving the back match itself, one would use, not . Similarly, to match a decimal digit without saving the matched digit, one would use,  not .

Note that the    utility may be used to test mapping patterns and specifically to test wildcard behavior in patterns.

 Back matching with $n&#x2a;
In some mapping tables, it is particularly useful to be able to compare whether two portions (fields) of the mapping table input are identical. The "back match" wildcards are provided for this purpose. Back matches of  through   are available. For instance, a  wild card looks for (matches on) the same characters already matched in the very first wildcard or glob in an entry, while a   wildcard looks for the same characters already matched in the second wildcard or glob in an entry, etc.

 The $_ modifier: minimal vs. maximal matching
Asterisk,, wildcards maximize what they match working from left  to right across the input string. For instance, when the input string " " is compared to the pattern,  the left asterisk will match " " and the right asterisk will match " ".

The  modifier causes wildcard matching to be minimized, where the least possible match is considered the match, working from left to right across the input string. For instance, when the input string " " is compared to the pattern,  the left   will match " " and the right   will match  " ".

 Controlling saving of wildcard or globs with $@ and $^
By default, the MTA keeps track of (saves) which character(s) are considered to have matched a wildcard or glob in a mapping table pattern for the duration of that mapping table entry (line). These retained character(s) can then be substituted back into the mapping table entry template via the  through   template substitutions. (That is, the character(s) matched in the left hand side (pattern) of a mapping table entry can be substituted back into the right hand side (template) of a mapping table entry, if desired.) But the MTA can only retain ten such matches. This restriction on the number of "saved" matches can always be dealt with by using multiple, iterative mapping table entries to achieve a desired effect (each entry doing only some matching/restoring, before leaving additional work to be done by a later entry). However, in many cases, where there is a desire to enforce a great deal of matching structure (more than ten wildcards or globs) but no need to reuse hence "save" the matched value(s), it is simpler to just "turn off" the saving via the  modifier.

The  modifier (the default behavior) turns on "saving". The  modifier turns off saving. Note that such modifiers, when combined with a pattern wildcard glob or backmatch that already includes a dollar sign,, in a syntax   , are then indicated simply by including the modifier letter (but not the dollar sign) "within" the wildcard or back match syntax, as   , where   is the modifier character, and   is the wildcard or back match -- only one dollar sign character is used. For example, the syntax to match without saving any number of binary digits is, not .

For instance, if it is desired to match fifteen of any sort of character: %%%%%%%%%%$@%$@%$@%$@%$@%   $Y matches and saves the first ten characters, and then matches without saving another five characters (though in fact in this example since none of the matched characters are actually substituted back into the template result, one could just as well have not bothered to save any of the matched characters -- that is, used the  modifier on all of the   character matches).

Or if it is desired to match eight alphabetic characters followed by a period followed by eight decimal digits, and retain only the first four alphabetic characters and the first four decimal digits, that could be done as: $A$A$A$A$@A$@A$@A$@A.$D$D$D$D$@D$@D$@D$@D  $Y$0$1$2$3.$4$5$6$7 where here only the first four alphabetic characters and first four decimal digits are saved (and then substituted back into the template).

 IP matching
With IPv4 "prefix bits" matching, an IP address or subnet is specified, optionally followed by a slash and the number of bits from the prefix that are significant when comparing for a match. For instance, $(123.45.67.0/24) will match anything in the 123.45.67.0 class C subnet.

With IPv4 "ignore bits" matching, an IP address or subnet is specified, optionally followed by a slash and the number of bits to ignore when checking for a match. For instance, $&#x3c;123.45.67.0/8&#x3e; will match anything in the 123.45.67.0 subnet. Or another example is that $&#x3c;123.45.67.4/2&#x3e; will match anything in the range 123.45.67.4--123.45.67.7.

IPv6 matching matches an IPv6 address or subnet. The syntax is: ${xxxx:xxxx:xxxx:xxxx:xxxx:xxxx:xxxx:xxxx/n} where each   can consist of one to four hexadecimal digits (digits in the range 0 to F) and where    is an integer in the range 0 to 128 specifying  the number of prefix bits that must match. In particular, each additional 16 bits of prefix matching requires that another 4  hexadecimal digit "chunk" of the IPv6 address must match. For instance, ${12AF:0:0:0:0:0:0:0/16} means to match any IPv6 address where the first sixteen bits correspond to the hexadecimal value  12AF, regardless of what the remaining 112  bits in the address may be.

For IPv6  matching, chunks may be omitted using the    marker. For instance, ,  , and    are all equivalent. In particular, a commonly used example is that to match the local host, one may use ${::1} meaning to match.

See the   mapping table for examples of IP address matching.

See also:
 * Mapping table format
 * Mapping operation
 * Testing mapping tables
 * INTERNAL_IP mapping table