/[mailutils]/mailutils/doc/texinfo/libsieve.texi
ViewVC logotype

Diff of /mailutils/doc/texinfo/libsieve.texi

Parent Directory Parent Directory | Revision Log Revision Log | View Patch Patch

revision 1.4 by gray, Tue Dec 10 15:00:04 2002 UTC revision 1.5 by gray, Tue Dec 10 21:26:53 2002 UTC
# Line 874  comparator `i;ascii-numeric' is incompat Line 874  comparator `i;ascii-numeric' is incompat
874  in call to `header'  in call to `header'
875  @end example  @end example
876    
877  @menu  @deffn Test false
 * false:Sieve test false.  
 * true:Sieve test true.  
 * address:Sieve test address.  
 * size:Sieve test size.  
 * envelope:Sieve test envelope.  
 * exists:Sieve test exists.  
 * header:Sieve test header.  
 * numaddr:Sieve test numaddr.  
 @end menu  
   
 @node Sieve test false  
 @subsubsection Sieve test false  
   
 @example  
 Syntax: false  
 @end example  
   
878  This test always evaluates to ``false''.  This test always evaluates to ``false''.
879    @end deffn
880    
881  @node Sieve test true  @deffn Test true
 @subsubsection Sieve test true  
   
 @example  
 Syntax: true  
 @end example  
   
882  This test always evaluates to ``true''.  This test always evaluates to ``true''.
883    @end deffn
884    
885  @node Sieve test address  @deffn Test address [@var{address-part}][@var{comparator}][@var{match-type}] @var{header-names} @var{key-list}
 @subsubsection Sieve test address  
886    
 @example  
 Syntax: address [@var{address-part}][@var{comparator}][@var{match-type}]  
                 @var{header-names} @var{key-list}  
 @end example  
 @sp 1  
 @noindent  
887  Tagged arguments:  Tagged arguments:
888    
889  @table @var  @table @var
# Line 960  example Line 932  example
932       discard;       discard;
933    @}    @}
934  @end example  @end example
935    @end deffn
936    
937  @node Sieve test size  @deffn Test size [:over|:under] @var{number}
 @subsubsection Sieve test size  
   
 @example  
 Syntax: size [:over|:under] @var{number}  
 @end example  
938  @sp 1  @sp 1
939  @noindent  @noindent
940  The @code{size} test deals with the size of a message. The required  The @code{size} test deals with the size of a message. The required
# Line 992  If the argument is @samp{:under}, and th Line 960  If the argument is @samp{:under}, and th
960  the @var{number}, the test is true; otherwise, it is false.  the @var{number}, the test is true; otherwise, it is false.
961    
962  Otherwise, the test is true only if the size of the message equals  Otherwise, the test is true only if the size of the message equals
963  exactly @var{number}. This is a GNU extension  exactly @var{number}. This is a GNU extension.
964    
965  The size of a message is defined to be the number of octets from the  The size of a message is defined to be the number of octets from the
966  initial header until the last character in the message body.  initial header until the last character in the message body.
967    @end deffn
968    
969    @deffn Test envelope [@var{address-part}][@var{comparator}][@var{match-type}] @var{envelope-part} @var{key-list}
 @node Sieve test envelope  
 @subsubsection Sieve test envelope  
   
 @example  
 Syntax:   envelope [@var{address-part}][@var{comparator}][@var{match-type}]  
                    @var{envelope-part} @var{key-list}  
 @end example  
970  @sp 1  @sp 1
971  @noindent  @noindent
972  Tagged arguments:  Tagged arguments:
# Line 1044  then matching occurs against the FROM ad Line 1006  then matching occurs against the FROM ad
1006  @emph{Notice}, that due to the limitations imposed by @sc{smtp} envelope  @emph{Notice}, that due to the limitations imposed by @sc{smtp} envelope
1007  structure the use of any other values in @var{envelope-parts} header is  structure the use of any other values in @var{envelope-parts} header is
1008  meaningless.  meaningless.
1009    @end deffn
1010    
1011  @node Sieve test exists  @deffn Test exists @var{header-names}
1012  @subsubsection Sieve test exists  @sp 1
1013    @noindent
1014    Required arguments:
1015    
1016  @example  @table @var
1017  Syntax:   exists @var{header-names}  @item header-names
1018  @end example  List of message header names.
1019    @end table
1020  @sp 1  @sp 1
1021  @noindent  @noindent
1022    
# Line 1067  if not exists ["From","Date"] Line 1033  if not exists ["From","Date"]
1033       discard;       discard;
1034    @}    @}
1035  @end example  @end example
1036    @end deffn
1037    
1038  @node Sieve test header  @deffn header [@var{comparator}] [@var{match-type}] [:mime] @var{header-names} @var{key-list}
1039  @subsubsection Sieve test header  @sp 1
   
 @example  
 Syntax:  header [@var{comparator}] [@var{match-type}] [:mime]  
                 @var{header-names} @var{key-list}  
 @end example  
   
1040  @noindent  @noindent
1041  Tagged arguments:  Tagged arguments:
1042    
# Line 1126  these tests on that header evaluate as f Line 1087  these tests on that header evaluate as f
1087  header :is ["X-Caffeine"] [""] @result{} false  header :is ["X-Caffeine"] [""] @result{} false
1088  header :contains ["X-Caffeine"] [""] @result{} true  header :contains ["X-Caffeine"] [""] @result{} true
1089  @end example  @end example
1090    @end deffn
1091    
1092  @node Sieve test numaddr  @deffn Test numaddr [:over|:under] @var{header-names} @var{number}
 @subsubsection Sieve test numaddr  
   
 @example  
 Syntax: require "test-numaddr";  
         numaddr [:over|:under] @var{header-names} @var{number}  
 @end example  
 @sp 1  
 @noindent  
1093    
1094  This test is provided as an example of loadable extension tests. You  This test is provided as an example of loadable extension tests. You
1095  must use @samp{require "test-numaddr"} statement before actually using  must use @samp{require "test-numaddr"} statement before actually using
# Line 1152  If the tagged argument is @samp{:under} Line 1106  If the tagged argument is @samp{:under}
1106  less than @var{number}, the test is true; otherwise, it is false.  less than @var{number}, the test is true; otherwise, it is false.
1107    
1108  If the tagged argument is not given, @samp{:over} is assumed.  If the tagged argument is not given, @samp{:over} is assumed.
1109    @end deffn
1110                    
1111  @node Actions  @node Actions
1112  @subsection Actions  @subsection Actions
1113    
1114    The GNU libsieve supports the following default actions:
1115    
1116    @itemize
1117    @item stop
1118    @item keep
1119    @item discard
1120    @item fileinto
1121    @item reject
1122    @item redirect
1123    @end itemize
1124    
1125    Among them the first three actions do not need to be explicitly required
1126    by a @code{require} statement, while the others do.
1127    
1128    These actions are described in detail below.
1129    
1130    @deffn Action stop
1131    
1132    The @code{stop} action ends all processing. If no actions have been
1133    executed, then the @code{keep} action is taken.
1134    @end deffn
1135    
1136    @deffn Action keep
1137    
1138    The effect of this action is to preserve the current message in the
1139    mailbox. This action is executed if no other action has been executed.
1140    @end deffn
1141    
1142    @deffn discard
1143    
1144    @code{Discard} silently throws away the current message. No notification
1145    is returned to the sender, the message is deleted from the mailbox.
1146    
1147    Example:
1148    @example
1149    if header :contains ["from"] ["idiot@@example.edu"]
1150      @{
1151        discard;
1152      @}
1153    @end example
1154    @end deffn
1155    
1156    @deffn Action fileinto @var{folder}
1157    @noindent
1158    @sp 1
1159    Required arguments:
1160    
1161    @table @var
1162    @item folder
1163    A string representing the folder name
1164    @end table
1165    
1166    The @code{fileinto} action delivers the message into the specified folder.
1167    @end deffn
1168    
1169    @deffn Action reject @var{reason}
1170    
1171    The optional @code{reject} action refuses delivery of a message by sending
1172    back a message delivery notification to the sender. It resends the
1173    message to the sender, wrapping it in a ``reject'' form, noting that it
1174    was rejected by the recipient. The required argument @var{reason} is
1175    a string specifying the reason for rejecting the message.
1176    
1177    Example:
1178    
1179    If the message contained
1180    @example
1181    Date: Tue, 1 Apr 1997 09:06:31 -0800 (PST)
1182    From: coyote@@desert.example.org
1183    To: roadrunner@@acme.example.com
1184    Subject: I have a present for you
1185    
1186    I've got some great birdseed over here at my place.
1187    Want to buy it?
1188    @end example
1189    @noindent
1190    @sp 1
1191    and the user's script contained:
1192    
1193    @example
1194    if header :contains "from" "coyote@@desert.example.org"
1195      @{
1196        reject "I am not taking mail from you, and I don't want
1197                your birdseed, either!";
1198      @}
1199    @end example
1200    @noindent
1201    then the original sender <coyote@@desert.example.org> would receive the
1202    following notification:
1203    
1204    @example
1205    To: <coyote@@desert.example.org>
1206    X-Authentication-Warning: roadrunner set sender using -f flag
1207    Content-Type: multipart/mixed; boundary=----- =_aaaaaaaaaa0
1208    MIME-Version: 1.0
1209    ----- =_aaaaaaaaaa0
1210    The original message was received at
1211    Tue, 1 Apr 1997 09:07:15 -0800 from
1212    coyote@@desert.example.org.
1213    Message was refused by recipient's mail filtering program.
1214    Reason given was as follows:
1215    
1216    I am not taking mail from you, and I don't want your birdseed, either!
1217    
1218    ----- =_aaaaaaaaaa0
1219    Content-Type: message/delivery-status
1220    
1221    Reporting-UA: sieve; GNU Mailutils 0.1.3
1222    Arrival-Date: Tue, 1 Apr 1997 09:07:15 -0800
1223    Final-Recipient: RFC822; roadrunner@@acme.example.com
1224    Action: deleted
1225    Disposition: automatic-action/MDN-sent-automatically;deleted
1226    Last-Attempt-Date: Tue, 1 Apr 1997 09:07:15 -0800
1227    
1228    ----- =_aaaaaaaaaa0
1229    Content-Type: message/rfc822
1230    
1231    From: coyote@@desert.example.org
1232    To: roadrunner@@acme.example.com
1233    Subject: I have a present for you
1234    
1235    I've got some great birdseed over here at my place.
1236    Want to buy it?
1237    ----- =_aaaaaaaaaa0
1238    @end example
1239    
1240    If the @var{reason} argument is rather long, the common approach is
1241    to use the combination of the @code{text:} and @code{#include} keywords,
1242    e.g.:
1243    
1244    @example
1245    if header :mime :matches "Content-Type"
1246              [ "*application/msword;*", "*audio/x-midi*" ]
1247      @{
1248        reject text:
1249    #include "nomsword.txt"
1250        .
1251        ;
1252      @}
1253    @end example      
1254    
1255    @end deffn
1256    
1257    @deffn Action redirect @var{address}
1258    The @code{redirect} action is used to send the message to another user at
1259    a supplied @var{address}, as a mail forwarding feature does.  This action
1260    makes no changes to the message body or existing headers, but it may add
1261    new headers. It also modifies the envelope recipient.
1262    
1263    The @code{redirect} command performs an MTA-style ``forward'' --- that
1264    is, what you get from a @file{.forward} file using @code{sendmail} under
1265    @sc{unix}.  The address on the SMTP envelope is replaced with the one on
1266    the @code{redirect} command and the message is sent back
1267    out. @emph{Notice}, that it differs from the MUA-style forward, which
1268    creates a new message with a different sender and message ID, wrapping
1269    the old message in a new one.
1270    @end deffn
1271    
1272  @node Extensions  @node Extensions
1273  @section Extensions  @section Extensions
1274    
1275    This section summarizes the GNU extensions to the sieve language
1276    
1277    @enumerate 1
1278    
1279    @item Handling of the @code{require} statement.
1280    
1281    @itemize
1282    @item According to the RFC an error must occur if a @code{require} appears
1283    after a command other than @code{require}. The GNU sieve library allows
1284    interspersing the @code{require} and other statements. The only
1285    requirement is that @code{require} must occur before a statement that is
1286    using the required capability (@pxref{Require Statement}).
1287    
1288    @item Prefixing the required capability with ``test'' requires the use
1289    of an extension test.
1290    @end itemize
1291    
1292    @item @code{header} test
1293    
1294    The @code{header} takes an optional argument @code{:mime}, meaning to
1295    scan the headers from each part of a multipart message.
1296    
1297    @item @code{size} test
1298    
1299    The @code{size} test allows to omit the optional argument
1300    (:over|:under). In this case exact equality is assumed.
1301    
1302    @item @code{envelope} test
1303    
1304    The only value that can be meaningfully used as the first required
1305    argument of an @code{envelope} test is @samp{from}. This limitation
1306    may disappear from the subsequent releases.
1307    
1308    @item Match type optional argument.
1309    
1310    Along with the usual @code{:is}, @code{:matches} and @code{contains}
1311    matching type, GNU sieve library understands @code{:regex} type. This
1312    matching type toggles POSIX Extended Regular Expression matching.
1313    
1314    @end enumerate
1315    
1316    
1317    
1318    

Legend:
Removed from v.1.4  
changed lines
  Added in v.1.5

savannah-hackers-public@gnu.org
ViewVC Help
Powered by ViewVC 1.1.26