1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
|
<HTML>
<HEAD>
<!-- This HTML file has been created by texi2html 1.52
from filter on 25 November 2000 -->
<TITLE>Exim Filter Specification - Expansion items</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_30.html">previous</A>, <A HREF="filter_32.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="SEC31" HREF="filter_toc.html#TOC31">Expansion items</A></H2>
<P>
The following items are recognized in expanded strings. White space may be used
between sub-items that are keywords or substrings enclosed in braces inside an
outer set of braces, to improve readability.
<font color=green>
Within braces, however, white space is significant.
</font>
</P>
<PRE>
<font color=blue>______________________________________________________________</font>
<b>$<<EM>variable name</EM>> or ${<<EM>variable name</EM>>}</b>
</PRE>
<P>
<A NAME="IDX1"></A>
Substitute the contents of the named variable, for example
<PRE>
$local_part
${domain}
</PRE>
<P>
The second form can be used to separate the name from subsequent alphanumeric
characters. This form (using curly brackets) is available only for variables;
it does <EM>not</EM> apply to message headers. The names of the variables are given
in section 1.33 below. If the name of a non-existent
variable is given, the expansion fails.
</P>
<PRE>
<font color=blue>______________________________________________________________</font>
<b>$header_<<EM>header name</EM>>: or $h_<<EM>header name</EM>>:</b>
</PRE>
<P>
<A NAME="IDX2"></A>
Substitute the contents of the named message header line, for example
<PRE>
$header_reply-to:
</PRE>
<P>
The header names follow the syntax of RFC 822, which states that they may
contain any printing characters except space and colon. Consequently, curly
brackets <EM>do not</EM> terminate header names,
and should not be used to enclose them as if they were variables. Attempting to
do so causes a syntax error.
</P>
<P>
Upper-case and lower-case letters are synonymous in header names. If the
following character is white space, the terminating colon may be omitted, but
this is not recommended, because you may then forget it when it is needed. When
white space terminates the header name, it is included in the expanded string.
If the message does not contain the given header, the expansion item is
replaced by an empty string. (See the <EM>def</EM> condition in section
1.32 for a means of testing for the existence of a header.)
If there is more than one header with the same name, they are all concatenated
to form the substitution string, with a newline character between each of them.
However, if the length of this string exceeds 64K, any further headers of the
same name are ignored.
</P>
<PRE>
<font color=blue>______________________________________________________________</font>
<b>${<<EM>op</EM>>:<<EM>string</EM>>}</b>
</PRE>
<P>
<A NAME="IDX3"></A>
The string is first itself expanded, and then the operation specified by <<EM>op</EM>>
is applied to it. For example,
<PRE>
${lc:$local_part}
</PRE>
<P>
A list of operators is given in section 1.31 below. The
string starts with the first character after the colon, which may be leading
white space.
</P>
<P>
<font color=green>
</P>
<PRE>
<font color=blue>______________________________________________________________</font>
<b>${extract{<<EM>key</EM>>}{<<EM>string1</EM>>}{<<EM>string2</EM>>}{<<EM>string3</EM>>}}</b>
</PRE>
<P>
The key and <<EM>string1</EM>> are first expanded separately. The key must not
consist entirely of digits. For the string, the result must be of the form:
<PRE>
<<EM>key1</EM>> = <<EM>value1</EM>> <<EM>key2</EM>> = <<EM>value2</EM>> ...
</PRE>
<P>
where the equals signs and spaces are optional. If any of the values contain
white space, they must be enclosed in double quotes, and any values that are
enclosed in double quotes are subject to escape processing as described in
section
5. The expanded <<EM>string1</EM>> is searched for the value that
corresponds to the key. If it is found, <<EM>string2</EM>> is expanded, and replaces
the whole item; otherwise <<EM>string3</EM>> is used. During the expansion of
<<EM>string2</EM>> the variable $<EM>value</EM> contains the value that has been extracted.
Afterwards, it is restored to any previous value it might have had.
</P>
<P>
If {<<EM>string3</EM>>} is omitted, the item is replaced by nothing if the key is
not found. If {<<EM>string2</EM>>} is also omitted, the value that was looked up is
used. Thus, for example, these two expansions are identical, and yield `2001':
<PRE>
${extract{gid}{uid=1984 gid=2001}}
${extract{gid}{uid=1984 gid=2001}{$value}}
</PRE>
<P>
Instead of {<<EM>string3</EM>>} the word `fail' (not in curly brackets) can appear,
for example:
<PRE>
${extract{Z}{A=... B=...}{$value} fail }
</PRE>
<P>
{<<EM>string2</EM>>} must be present for `fail' to be recognized. When this syntax
is used, if the extraction fails,
the entire expansion fails. This causes processing of the filter file to fail,
which either delays delivery of the message, or causes the filter file to be
ignored, depending on how the administrator has configured Exim.
</P>
<PRE>
<font color=blue>______________________________________________________________</font>
<b>${extract{<<EM>number</EM>>}{<<EM>separators</EM>>}{<<EM>string1</EM>>}{<<EM>string2</EM>>}{<<EM>string3</EM>>}}</b>
</PRE>
<P>
The <<EM>number</EM>> argument must consist entirely of decimal digits. This is what
distinguishes this form of <EM>extract</EM> from the previous kind. It behaves in the
same way, except that, instead of extracting a named field, it extracts from
<<EM>string1</EM>> the field whose number is given as the first argument. The first
field is numbered one. If the number is greater than the number of fields in
the string, the result is empty; if it is zero, the entire string is returned.
The fields in the string are separated by any one of the characters in the
separator string. For example:
<PRE>
${extract{2}{:}{x:42:99:& Mailer::/bin/bash}}
</PRE>
<P>
yields `42'. Two successive separators mean that the field between them is
empty (for example, the sixth field above).
</font>
</P>
<PRE>
<font color=blue>______________________________________________________________</font>
<b>${if <<EM>condition</EM>> {<<EM>string1</EM>>}{<<EM>string2</EM>>}}</b>
</PRE>
<P>
<A NAME="IDX4"></A>
If <<EM>condition</EM>> is true, <<EM>string1</EM>> is expanded and replaces the whole item;
otherwise <<EM>string2</EM>> is used. For example,
<PRE>
${if eq {$local_part}{postmaster} {yes}{no} }
</PRE>
<P>
The second string need not be present; if it is not and the condition is not
true, the item is replaced with nothing. Alternatively, the word `fail' may be
present instead of the second string (without any curly brackets). In this
case, the expansion is forced to fail if the condition is not true. The
available conditions are described in section 1.32 below.
</P>
<PRE>
<font color=blue>______________________________________________________________</font>
<b>${lookup{<<EM>key</EM>>} <<EM>search type</EM>> {<<EM>file</EM>>} {<<EM>string1</EM>>} {<<EM>string2</EM>>}}</b>
</PRE>
<PRE>
<b>${lookup <<EM>search type</EM>> {<<EM>query</EM>>} {<<EM>string1</EM>>} {<<EM>string2</EM>>}}</b>
</PRE>
<P>
<A NAME="IDX5"></A>
<A NAME="IDX6"></A>
<A NAME="IDX7"></A>
<A NAME="IDX8"></A>
These items specify data lookups in files and databases, as discussed in
chapter . The first form is used for single-key lookups, and the
second is used for query-style lookups. The <<EM>key</EM>>, <<EM>file</EM>>, and <<EM>query</EM>>
strings are expanded before use.
</P>
<P>
If there is any white space in a lookup item which is part of a filter command,
the lookup item must be enclosed in double quotes.
The use of data lookups in users' filter files may be locked out by the system
administrator.
</P>
<P>
<A NAME="IDX9"></A>
If the lookup succeeds, <<EM>string1</EM>> is expanded and replaces the entire item.
During its expansion, the variable $<EM>value</EM> contains the data returned by the
lookup.
<font color=green>
Afterwards it reverts to the value it had previously (at the outer level it is
empty).
</font>
If the lookup fails, <<EM>string2</EM>> is expanded and replaces the entire item. If
{<<EM>string2</EM>>} is omitted, the replacement is null on failure. Alternatively,
<<EM>string2</EM>> can itself be a nested lookup, thus providing a mechanism for
looking up a default value when the original lookup fails.
</P>
<P>
<font color=green>
If a nested lookup is used as part of <<EM>string1</EM>>, $<EM>value</EM> contains the data
for the outer lookup while the parameters of the second lookup are expanded,
and also while <<EM>string2</EM>> of the second lookup is expanded, should the second
lookup fail.
</font>
</P>
<P>
Instead of {<<EM>string2</EM>>} the word `fail' can appear, and in this case, if the
lookup fails, the entire expansion is forced to fail. If both {<<EM>string1</EM>>}
and {<<EM>string2</EM>>} are omitted, the result is the looked up value in the case
of a successful lookup, and nothing in the case of failure.
</font>
</P>
<P>
For single-key lookups, the string `partial-' is permitted to precede the
search type in order to do partial matching, and * or *@ may follow a
search type to request default lookups if the key does not match (see sections
and ).
</P>
<P>
If a partial search is used, the variables $<EM>1</EM> and $<EM>2</EM> contain the wild
and non-wild parts of the key during the expansion of the replacement text.
They return to their previous values at the end of the lookup item.
</P>
<P>
This example looks up the postmaster alias in the conventional alias file.
<PRE>
${lookup {postmaster} lsearch {/etc/aliases} {$value}}
</PRE>
<P>
This example uses NIS+ to look up the full name of the user corresponding to
the local part of an address, forcing the expansion to fail if it is not found.
<PRE>
"${lookup nisplus {[name=$local_part],passwd.org_dir:gcos} \
{$value}fail}"
</PRE>
<PRE>
<font color=blue>______________________________________________________________</font>
<b>${lookup{<<EM>key:subkey</EM>>} <<EM>search type</EM>> {<<EM>file</EM>>} {<<EM>string1</EM>>} {<<EM>string2</EM>>}}</b>
</PRE>
<P>
<font color=green>
This is just a syntactic variation for a single-key lookup, surrounded by an
<EM>extract</EM> item. It searches for <<EM>key</EM>> in the file as described above for
single-key lookups; if it succeeds, it extracts from the data a subfield which
is identified by the <<EM>subkey</EM>>. For example, if a line in a linearly searched
file contains
<PRE>
alice: uid=1984 gid=2001
</PRE>
<P>
then expanding the string
<PRE>
${lookup{alice:uid}lsearch{<<EM>file name</EM>>}{$value}}
</PRE>
<P>
yields the string `1984'. If the subkey is not found in the looked up data,
then <<EM>string2</EM>>, if present, is expanded and replaces the entire item.
Otherwise the replacement is null. The example above could equally well be
written like this:
<PRE>
${extract{uid}{${lookup{alice}lsearch{<<EM>file name</EM>>}}}}
</PRE>
<P>
and this is recommended, because this approach can also be used with
query-style lookups.
</font>
</P>
<P>
<font color=green>
</P>
<PRE>
<font color=blue>______________________________________________________________</font>
<b>${sg{<<EM>subject</EM>>}{<<EM>regex</EM>>}{<<EM>replacement</EM>>}}</b>
</PRE>
<P>
<A NAME="IDX10"></A>
This item works like Perl's substitution operator (s) with the global (/g)
option; hence its name. It takes three arguments: the subject string, a regular
expression, and a substitution string. For example
<PRE>
${sg{abcdefabcdef}{abc}{xyz}}
</PRE>
<P>
yields `xyzdefxyzdef'. Because all three arguments are expanded before use, if
any $ or \ characters are required in the regular expression or in the
substitution string, they have to be escaped. For example
<PRE>
${sg {abcdef}{^(...)(...)\$}{\$2\$1}}
</PRE>
<P>
yields `defabc', and
<PRE>
${sg{1=A 4=D 3=C}{(\\d+)=}{K\$1=}}
</PRE>
<P>
yields `K1=A K4=D K3=C'.
</P>
<PRE>
<font color=blue>______________________________________________________________</font>
<b>${tr{<<EM>subject</EM>>}{<<EM>characters</EM>>}{<<EM>replacements</EM>>}}</b>
</PRE>
<P>
<A NAME="IDX11"></A>
This item does single-character translation on its subject string. The second
argument is a list of characters to be translated in the subject string. Each
matching character is replaced by the corresponding character from the
replacement list. For example
<PRE>
${tr{abcdea}{ac}{13}}
</PRE>
<P>
yields `1b3de1'. If there are duplicates in the second character string, the
last occurrence is used. If the third string is shorter than the second, its
last character is replicated. However, if it is empty, no translation takes
place.
</font>
</P>
<P><HR><P>
Go to the <A HREF="filter_1.html">first</A>, <A HREF="filter_30.html">previous</A>, <A HREF="filter_32.html">next</A>, <A HREF="filter_34.html">last</A> section, <A HREF="filter_toc.html">table of contents</A>.
</BODY>
</HTML>
|
