Expansion operators

The following operations can be performed on portions of an expanded string. The substring is first expanded before the operation is applied to it.

______________________________________________________________

${domain:<string>}

The string is interpreted as an RFC 822 address and the domain is extracted from it. If the string does not parse successfully, the result is empty.

______________________________________________________________

${escape:<string>}

If the string contains any non-printing characters, they are converted to escape sequences starting with a backslash.

______________________________________________________________

${expand:<string>}

The expand operator causes a string to be expanded for a second time. For example,

${expand:${lookup{$domain}dbm{/some/file}{$value}}}

first looks up a string in a file while expanding the operand for expand, and then re-expands what it has found.

______________________________________________________________

${hash_<n>_<m>:<string>}

The two items <n> and <m> are numbers. If <n> is greater than or equal to the length of the string, the operator returns the string. Otherwise it computes a new string of length <n> by applying a hashing function to the string. The new string consists of characters taken from the first <m> characters of the string

abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQWRSTUVWXYZ0123456789

and if <m> is not present the value 26 is used, so that only lower case letters appear. These examples:

${hash_3:monty}
${hash_5:monty}
${hash_4_62:monty python}

yield

jmg
monty
fbWx

respectively. The abbreviation h can be used instead of hash.

______________________________________________________________

${nhash_<n>:<string>}

The string is processed by a hash function which returns a numeric value in the range 0--<n>-1.

______________________________________________________________

${nhash_<n>_<m>:<string>}

The string is processed by a div/mod hash function which returns two numbers, separated by a slash, in the ranges 0--<n>-1 and 0--<m>-1, respectively. For example,

${nhash_8_64:supercalifragilisticexpialidocious}

returns the string `6/33'.

______________________________________________________________

${lc:<string>}

This forces the letters in the string into lower-case, for example:

${lc:$local_part}

______________________________________________________________

${uc:<string>}

This forces the letters in the string into upper-case.

${length_<number>:<string>}

The length operator can be used to extract the initial portion of a string. It is followed by an underscore and the number of characters required. For example

${length_50:$message_body}

The result of this operator is either the first <number> characters or the whole string, whichever is the shorter. The abbreviation l can be used instead of length.

______________________________________________________________

${local_part:<string>}

The string is interpreted as an RFC 822 address and the local part is extracted from it. If the string does not parse successfully, the result is empty.

${mask:<IP address>/<bit count>}

If the form of the string to be operated on is not an IP address followed by a slash and an integer, the expansion fails. Otherwise, this operator converts the IP address to binary, masks off the least significant bits according to the bit count, and converts the result back to text, with mask appended. For example,

${mask:10.111.131.206/28}

returns the string `10.111.131.192/28'. Since this operation is expected to be mostly used for looking up masked addresses in files, the result for an IPv6 address uses fullstops (periods) to separate components instead of colons, because colon terminates a key string in lsearch files. So, for example,

${mask:5f03:1200:836f:0a00:000a:0800:200a:c031/99}

returns the string

5f03.1200.836f.0a00.000a.0800.2000.0000/99

Letters in IPv6 addresses are always output in lower case.

______________________________________________________________

${quote:<string>}

The quote operator puts its argument into double quotes if it contains anything other than letters, digits, underscores, full stops (periods), and hyphens. Any occurrences of double quotes and backslashes are escaped with a backslash. For example,

${quote:ab"*"cd}

becomes

"ab\"*\"cd"

The place where this is useful is when the argument is a substitution from a variable or a message header.

______________________________________________________________

${quote_<lookup-type>:<string>}

This operator applies lookup-specific quoting rules to the string. Each query-style lookup type has its own quoting rules which are described with the lookups in chapter . For example,

${quote_ldap:two + two}

returns `two%20%5C+%20two'. For single-key lookup types, no quoting is necessary and this operator yields an unchanged string.

______________________________________________________________

${rxquote:<string>}

The rxquote operator inserts a backslash before any non-alphanumeric characters in its argument. This is useful when substituting the values of variables or headers inside regular expressions.

______________________________________________________________

${substr_<start>_<length>:<string>}

The substr operator can be used to extract more general substrings than length. It is followed by an underscore and the starting offset, then a second underscore and the length required. For example

${substr_3_2:$local_part}

If the starting offset is greater than the string length the result is the null string; if the length plus starting offset is greater than the string length, the result is the right-hand part of the string, starting from the given offset. The first character in the string has offset zero. The abbreviation s can be used instead of substr.

The substr expansion operator can take negative offset values to count from the righthand end of its operand. The last character is offset -1, the second-last is offset -2, and so on. Thus, for example,

${substr_-5_2:1234567}

yields `34'. If the absolute value of a negative offset is greater than the length of the string, the substring starts at the beginning of the string, and the length is reduced by the amount of overshoot. Thus, for example,

${substr_-5_2:12}

yields an empty string, but

${substr_-3_2:12}

yields `1'.

If the second number is omitted from substr, the remainder of the string is taken if the offset was positive. If it was negative, all characters in the string preceding the offset point are taken. For example, an offset of -1 and no length yields all but the last character of the string.

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