File: filter_32.html

package info (click to toggle)
exim-html 3.20-1
links: PTS
area: main
in suites: etch, etch-m68k, sarge, woody
size: 2,868 kB
ctags: 4,188
sloc: makefile: 40; sh: 19
file content (400 lines) | stat: -rw-r--r-- 9,693 bytes
<HTML>
<HEAD>
<!-- This HTML file has been created by texi2html 1.52
     from filter on 25 November 2000 -->

<TITLE>Exim Filter Specification - Expansion operators</TITLE>
</HEAD>
<body bgcolor="#FFFFFF" text="#00005A" link="#FF6600" alink="#FF9933" vlink="#990000">
Go to the <A HREF="filter_1.html">first</A>, <A HREF="filter_31.html">previous</A>, <A HREF="filter_33.html">next</A>, <A HREF="filter_34.html">last</A> section, <A HREF="filter_toc.html">table of contents</A>.
<P><HR><P>


<H2><A NAME="SEC32" HREF="filter_toc.html#TOC32">Expansion operators</A></H2>

<P>
<A NAME="IDX12"></A>
The following operations can be performed on portions of an expanded string.
The substring is first expanded before the operation is applied to it.

</P>


<PRE>
<font color=blue>______________________________________________________________</font>

<b>${domain:&#60;<EM>string</EM>&#62;}</b>
</PRE>

<P>
<A NAME="IDX13"></A>
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.

</P>


<PRE>
<font color=blue>______________________________________________________________</font>

<b>${escape:&#60;<EM>string</EM>&#62;}</b>
</PRE>

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

</P>


<PRE>
<font color=blue>______________________________________________________________</font>

<b>${expand:&#60;<EM>string</EM>&#62;}</b>
</PRE>

<P>
The <EM>expand</EM> operator causes a string to be expanded for a second time. For
example,

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

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

</P>


<PRE>
<font color=blue>______________________________________________________________</font>

<b>${hash_&#60;<EM>n</EM>&#62;_&#60;<EM>m</EM>&#62;:&#60;<EM>string</EM>&#62;}</b>
</PRE>

<P>
<A NAME="IDX14"></A>
The two items &#60;<EM>n</EM>&#62; and &#60;<EM>m</EM>&#62; are numbers. If &#60;<EM>n</EM>&#62; is greater than or equal to
the length of the string, the operator returns the string. Otherwise it
computes a new string of length &#60;<EM>n</EM>&#62; by applying a hashing function to the
string. The new string consists of characters taken from the first &#60;<EM>m</EM>&#62;
characters of the string

<PRE>
abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQWRSTUVWXYZ0123456789
</PRE>

<P>
and if &#60;<EM>m</EM>&#62; is not present the value 26 is used, so that only lower case
letters appear. These examples:

<PRE>
${hash_3:monty}
${hash_5:monty}
${hash_4_62:monty python}
</PRE>

<P>
yield

<PRE>
jmg
monty
fbWx
</PRE>

<P>
respectively. The abbreviation <EM>h</EM> can be used instead of <EM>hash</EM>.

</P>


<PRE>
<font color=blue>______________________________________________________________</font>

<b>${nhash_&#60;<EM>n</EM>&#62;:&#60;<EM>string</EM>&#62;}</b>
</PRE>

<P>
<A NAME="IDX15"></A>
<A NAME="IDX16"></A>
The string is processed by a hash function which returns a numeric value in the
<font color=green>
range 0--&#60;<EM>n</EM>&#62;-1.
</font>

</P>


<PRE>
<font color=blue>______________________________________________________________</font>

<b>${nhash_&#60;<EM>n</EM>&#62;_&#60;<EM>m</EM>&#62;:&#60;<EM>string</EM>&#62;}</b>
</PRE>

<P>
The string is processed by a div/mod hash function which returns two numbers,
separated by a slash, in the ranges
<font color=green>
0--&#60;<EM>n</EM>&#62;-1 and 0--&#60;<EM>m</EM>&#62;-1,
</font>
respectively. For example,

<PRE>
${nhash_8_64:supercalifragilisticexpialidocious}
</PRE>

<P>
returns the string `6/33'.

</P>

<P>
<A NAME="IDX17"></A>
<A NAME="IDX18"></A>
<A NAME="IDX19"></A>

</P>

<PRE>
<font color=blue>______________________________________________________________</font>

<b>${lc:&#60;<EM>string</EM>&#62;}</b>
</PRE>

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

<PRE>
${lc:$local_part}
</PRE>

<P>
<A NAME="IDX20"></A>

</P>

<PRE>
<font color=blue>______________________________________________________________</font>

<b>${uc:&#60;<EM>string</EM>&#62;}</b>
</PRE>

<P>
This forces the letters in the string into upper-case.

</P>


<PRE>
<b>${length_&#60;<EM>number</EM>&#62;:&#60;<EM>string</EM>&#62;}</b>
</PRE>

<P>
The <EM>length</EM> 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

<PRE>
${length_50:$message_body}
</PRE>

<P>
The result of this operator is either the first &#60;<EM>number</EM>&#62; characters or the
whole string, whichever is the shorter. The abbreviation <EM>l</EM> can be used
instead of <EM>length</EM>.

</P>


<PRE>
<font color=blue>______________________________________________________________</font>

<b>${local_part:&#60;<EM>string</EM>&#62;}</b>
</PRE>

<P>
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.

</P>


<PRE>
<b>${mask:&#60;<EM>IP address</EM>&#62;/&#60;<EM>bit count</EM>&#62;}</b>
</PRE>

<P>
<A NAME="IDX21"></A>
<A NAME="IDX22"></A>
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,

<PRE>
${mask:10.111.131.206/28}
</PRE>

<P>
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,

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

<P>
returns the string

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

<P>
Letters in IPv6 addresses are always output in lower case.

</P>


<PRE>
<font color=blue>______________________________________________________________</font>

<b>${quote:&#60;<EM>string</EM>&#62;}</b>
</PRE>

<P>
<A NAME="IDX23"></A>
The <EM>quote</EM> 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,

<PRE>
${quote:ab"*"cd}
</PRE>

<P>
becomes

<PRE>
"ab\"*\"cd"
</PRE>

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

</P>


<PRE>
<font color=blue>______________________________________________________________</font>

<b>${quote_&#60;<EM>lookup-type</EM>&#62;:&#60;<EM>string</EM>&#62;}</b>
</PRE>

<P>
<A NAME="IDX24"></A>
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,

<PRE>
${quote_ldap:two + two}
</PRE>

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

</P>


<PRE>
<font color=blue>______________________________________________________________</font>

<b>${rxquote:&#60;<EM>string</EM>&#62;}</b>
</PRE>

<P>
<A NAME="IDX25"></A>
<A NAME="IDX26"></A>
The <EM>rxquote</EM> 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.

</P>


<PRE>
<font color=blue>______________________________________________________________</font>

<b>${substr_&#60;<EM>start</EM>&#62;_&#60;<EM>length</EM>&#62;:&#60;<EM>string</EM>&#62;}</b>
</PRE>

<P>
<A NAME="IDX27"></A>
<A NAME="IDX28"></A>
The <EM>substr</EM> operator can be used to extract more general substrings than
<EM>length</EM>. It is followed by an underscore and the starting offset, then a
second underscore and the length required. For example

<PRE>
${substr_3_2:$local_part}
</PRE>

<P>
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 <EM>s</EM>
can be used instead of <EM>substr</EM>.

</P>
<P>
The <EM>substr</EM> 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,

<PRE>
${substr_-5_2:1234567}
</PRE>

<P>
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,

<PRE>
${substr_-5_2:12}
</PRE>

<P>
yields an empty string, but

<PRE>
${substr_-3_2:12}
</PRE>

<P>
yields `1'.

</P>
<P>
If the second number is omitted from <EM>substr</EM>, 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.

</P>

<P><HR><P>
Go to the <A HREF="filter_1.html">first</A>, <A HREF="filter_31.html">previous</A>, <A HREF="filter_33.html">next</A>, <A HREF="filter_34.html">last</A> section, <A HREF="filter_toc.html">table of contents</A>.
</BODY>
</HTML>