/[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.3 by gray, Sat Nov 30 13:39:43 2002 UTC revision 1.4 by gray, Tue Dec 10 15:00:04 2002 UTC
# Line 3  Line 3 
3  @c See file mailutils.texi for copying conditions.  @c See file mailutils.texi for copying conditions.
4  @comment *******************************************************************  @comment *******************************************************************
5    
6    This chapter describes GNU Sieve library.
7    
8    @menu
9    * Library Description::
10    * Input Language::
11    * Extensions::
12    @end menu
13    
14    @node Library Description
15    @section Library Description
16    
17  @menu  @menu
18  * Sieve Data Types::  * Sieve Data Types::
19  * Manipulating the Sieve Machine::  * Manipulating the Sieve Machine::
# Line 13  Line 24 
24  @end menu  @end menu
25    
26  @node Sieve Data Types  @node Sieve Data Types
27  @section Sieve Data Types  @subsection Sieve Data Types
28    
29  @deftp {Data Type} sieve_machine_t  @deftp {Data Type} sieve_machine_t
30  This is an opaque data type representing a pointer to an instance of  This is an opaque data type representing a pointer to an instance of
# Line 284  case. [FIXME: describe how to do that] Line 295  case. [FIXME: describe how to do that]
295  @end deftp  @end deftp
296    
297  @node Manipulating the Sieve Machine  @node Manipulating the Sieve Machine
298  @section Manipulating the Sieve Machine  @subsection Manipulating the Sieve Machine
299    
300  This section describes functions used to create an instance of the  This subsection describes functions used to create an instance of the
301  sieve machine, read or alter its internal fields and destroy it.  sieve machine, read or alter its internal fields and destroy it.
302    
303  @deftypefn int sieve_machine_init (sieve_machine_t *@var{mach}, void *@var{data})  @deftypefn int sieve_machine_init (sieve_machine_t *@var{mach}, void *@var{data})
# Line 468  return value is a pointer to a static co Line 479  return value is a pointer to a static co
479  @end deftypefn  @end deftypefn
480    
481  @node Logging and Diagnostic Functions  @node Logging and Diagnostic Functions
482  @section Logging and Diagnostic Functions  @subsection Logging and Diagnostic Functions
483    
484  @deftypefn void sieve_error (sieve_machine_t @var{mach}, const char *@var{fmt}, @dots{})  @deftypefn void sieve_error (sieve_machine_t @var{mach}, const char *@var{fmt}, @dots{})
485  Format and output an error message using error printer of the machine @var{mach}.  Format and output an error message using error printer of the machine @var{mach}.
# Line 487  Immediately abort the execution of the s Line 498  Immediately abort the execution of the s
498  @end deftypefn  @end deftypefn
499    
500  @node Symbol Space Functions  @node Symbol Space Functions
501  @section Symbol Space Functions  @subsection Symbol Space Functions
502    
503  @deftypefn {sieve_register_t *} sieve_test_lookup (sieve_machine_t @var{mach}, const char *@var{name})  @deftypefn {sieve_register_t *} sieve_test_lookup (sieve_machine_t @var{mach}, const char *@var{name})
504  Find a register object describing the test @var{name}. Returns  Find a register object describing the test @var{name}. Returns
# Line 515  Find a register object describing the ac Line 526  Find a register object describing the ac
526  @end deftypefn  @end deftypefn
527    
528  @node Memory Allocation  @node Memory Allocation
529  @section Memory Allocation  @subsection Memory Allocation
530    
531  The following functions act as their libc counterparts. The allocated  The following functions act as their libc counterparts. The allocated
532  memory is associated with the @var{mach} argument and is automatically  memory is associated with the @var{mach} argument and is automatically
# Line 552  If @var{ptr} is @code{NULL}, no operatio Line 563  If @var{ptr} is @code{NULL}, no operatio
563  @end deftypefn  @end deftypefn
564    
565  @node Compiling and Executing the Script  @node Compiling and Executing the Script
566  @section Compiling and Executing the Script  @subsection Compiling and Executing the Script
567    
568  @deftypefn int sieve_compile (sieve_machine_t @var{mach}, const char *@var{name})  @deftypefn int sieve_compile (sieve_machine_t @var{mach}, const char *@var{name})
569  Compile the seive script from the file @var{name}.  Compile the seive script from the file @var{name}.
# Line 572  over the @var{message}. Line 583  over the @var{message}.
583  Dump the disassembled code of the sieve machine @var{mach}.  Dump the disassembled code of the sieve machine @var{mach}.
584  @end deftypefn  @end deftypefn
585    
586    @node Input Language
587    @section Input Language
588    
589    The input language understood by the GNU Sieve Library is a superset of
590    the Sieve language as described in RFC 3028.
591    
592    @menu
593    * Syntax::
594    * Preprocessor::
595    * Require Statement::
596    * Comparators::
597    * Tests::
598    * Actions::
599    @end menu
600    
601    @node Syntax
602    @subsection
603    
604    @node Preprocessor
605    @subsection Preprocessor
606    @cindex Sieve preprocessor statements, a GNU extension
607    
608    The preprocessor statements are a GNU extension to the Sieve language.
609    The syntax for a preprocessor statement is similar to that used in
610    @code{C} programming language, i.e.: a pound character (@samp{#})
611    followed by a preprocessor directive and any arguments. Any amount of
612    whitespace can be inserted between the @samp{#} and the directive.
613    Currently implemented directives are @code{include} and @code{searchpath}.
614    
615    @menu
616    * #include::        Include the contents of a file.
617    * #searchpath::     Modify the current search path.
618    @end menu
619    
620    @node #include
621    @subsubsection Sieve #include directive
622    @cindex #include, sieve
623    
624    The @code{#include} directive reads in the contents of the given file.
625    The contents is ``inserted'' into the text being parsed starting at the
626    line where the directive appears. The directive takes two forms:
627    
628    @table @code
629    @item #include "@var{filename}"
630    The @var{filename} is taken relative to the current directory.
631    
632    @item #include <@var{filename}>"
633    The @var{filename} is searched in the list of include directories
634    as specified by the @option{-I} command line options.
635    @end table
636    
637    If @var{filename} starts with a directory separator character
638    (@samp{/}) both forms have the same effect.
639    
640    @node #searchpath
641    @subsubsection Sieve #searchpath directive
642    @cindex #searchpath, sieve
643    
644    The @code{#searchpath} directive adds its argument to the list of
645    directories searched for loadable modules. It has the same effect
646    as @option{-L} command line switch used by GNU sieve utility
647    (@pxref{sieve group}).
648    
649    @node Require Statement
650    @subsection Require Statement
651    
652    @example
653    Syntax:   require @var{string};
654              require @var{string-list};
655    @end example
656    
657    The require statement informs the parser that a script makes use of a certain
658    extension. Multiple capabilities can be declared using the second form
659    of the statement. The actual handling of a capability name depends on
660    its suffix.
661    
662    If the name starts with @samp{comparator-}, it is understood
663    as a request to use the specified comparator. The comparator name
664    consists of the characters following the suffix.
665    
666    If the name starts with @samp{test-}, it means a request to use
667    the given test. The test name consists of the characters following
668    the suffix.
669    
670    Otherwise, the capability is understood as a name of an action to be
671    used.
672    
673    The @code{require} statement, if present, must be used before any other
674    statement that is using the required capability. As an extension, the GNU
675    sieve allows the @code{require} and any other statements to be
676    interspersed.
677    
678    By default the following actions and comparators are always required:
679    @itemize
680    @item stop
681    @item keep
682    @item discard
683    @item i;octet
684    @item i;ascii-casemap
685    @end itemize
686    
687    Example:
688    
689    @example
690    require ["fileinto", "reject"];
691    
692    require "fileinto";
693    
694    require "comparator-i;ascii-numeric";
695    @end example
696    
697    When processing arguments for @code{require} statement, GNU libsieve
698    uses the following algorithm:
699    
700    @enumerate 1
701    @item Look up the name in a symbol table. If the name begins with
702    @samp{comparator-} it is looked up in the comparator table. If it
703    begins with @samp{test-}, the test table is used instead. Otherwise
704    the name is looked up in the action table.
705    
706    @item If the name is found, the search is terminated.
707    
708    @item Otherwise, transform the name. First, any @samp{comparator-} or
709    @samp{test-} prefix is stripped. Then, any character other than
710    alphanumeric characters, @samp{.} and @samp{,} is replaced with
711    dash (@samp{-}). The name thus obtained is used as a file name
712    of an external loadable module.
713    
714    @item Try to load the module. The module is searched in the
715    following search paths (in the order given):
716    
717    @enumerate 1
718    @item Mailutils module directory. By default it is
719    @file{$prefix/lib/mailutils}.
720    
721    @item Sieve library path as given with the @option{-L} options in
722    the command line
723    
724    @item Additional search directories specified with the
725    @code{#searchpath} directive.
726    
727    @item The value of the environment variable LTDL_LIBRARY_PATH.
728    
729    @item System library search path: The system dependent library
730    search path (e.g. on Linux it is set by the contents of the file
731    @file{/etc/ld.so.conf} and the value of the environment variable
732    LD_LIBRARY_PATH).
733    @end enumerate
734    
735    The value of LTDL_LIBRARY_PATH and LD_LIBRARY_PATH must be a
736    colon-separated list of absolute directories, for example,
737    @samp{"/usr/lib/mypkg:/lib/foo"}.
738    
739    In any of these directories, @command{libsieve} first attempts to find
740    and load the given filename. If this fails, it tries to append the
741    following suffixes to the file name:
742    
743    @enumerate 1
744    @item the libtool archive extension @samp{.la}
745    
746    @item the extension used for native dynamic libraries on the host
747    platform, e.g., @samp{.so}, @samp{.sl}, etc.
748    @end enumerate
749    
750    @item If the module is found, @command{libsieve} executes its
751    initialization function (see below) and again looks up the name
752    in the symbol table. If found, search terminates successfully.
753    
754    @item If either the module is not found, or the symbol wasn't
755    found after execution of the module initialization function,
756    search is terminated with an error status. @command{libsieve} then
757    issues the following diagnostic message:
758    
759    @example
760    source for the required action NAME is not available
761    @end example
762    @end enumerate
763    
764    @node Comparators
765    @subsection Comparators
766    
767    GNU libsieve supports the following built-in comparators:
768    
769    @table @code
770    @item i;octet
771    This comparator simply compares the two arguments octet by octet
772    
773    @item i;ascii-casemap
774    It treats uppercase and lowercase characters in the @sc{ascii} subset of
775    @sc{utf-8} as the same. This is the default comparator.
776    
777    @item i;ascii-numeric
778    Treats the two arguments as @sc{ascii} representation of decimal
779    numbers and compares their numeric values. This comparator must
780    be explicitly required prior to use.
781    @end table
782    
783    @node Tests
784    @subsection Tests
785    
786    This section describes the built-in tests supported by GNU libsieve.
787    In the discussion below the following macro-notations are used:
788    
789    @table @var
790    @item match-type
791    This tag specifies the matching type to be used with the test. It can
792    be one of the following:
793    
794    @table @code
795    @item :is
796    The @code{:is} match type describes an absolute match; if the contents of
797    the first string are absolutely the same as the contents of the
798    second string, they match.  Only the string ``frobnitzm'' is the string
799    ``frobnitzm''.  The null key ``:is'' and only ``:is'' the null value.
800    This is the default match-type.
801    
802    @item :contains
803    The @code{:contains} match type describes a substring match.  If the value
804    argument contains the key argument as a substring, the match is true.
805    For instance, the string ``frobnitzm'' contains ``frob'' and ``nit'', but
806    not ``fbm''.  The null key ``'' is contained in all values.
807    
808    @item :matches
809    The @code{:matches} version specifies a wildcard match using the
810    characters @samp{*} and @samp{?}. @samp{*} matches zero or more
811    characters, and @samp{?} matches a single character. @samp{?} and
812    @samp{*} may be escaped as @samp{\\?} and @samp{\\*} in strings to match
813    against themselves.  The first backslash escapes the second backslash;
814    together, they escape the @samp{*}.
815    
816    @item :regex
817    The @code{:regex} version specifies a match using POSIX Extended Regular
818    Expressions.
819    @end table
820    
821    @item comparator
822    A @var{comparator} syntax item is defined as follows:
823    
824    @example
825    :comparator "@var{comparator-name}"
826    @end example
827    @noindent
828    @sp 1
829    It instructs sieve to use the given comparator with the test.
830    If @var{comparator-name} is not one of @samp{i;octet},
831    @samp{i;ascii-casemap} it must be required prior to using it.
832    For example:
833    
834    @example
835    require "comparator-i;ascii-numeric";
836    
837    if header :comparator "i;ascii-numeric" :is "X-Num" "10"
838      @{
839        ...
840    @end example
841    
842    @item address-part
843    This syntax item is used when testing structured Internet addresses. It
844    specifies which part of an address must be used in comparisons.
845    Exactly one of the following tags may be used:
846    
847    @table @code
848    @item :all
849    Use the whole address. This is the default.
850    
851    @item :localpart
852    Use local part of the address.
853    
854    @item :domain
855    Use domain part of the address.
856    @end table
857    
858    @end table
859    
860    @emph{Notice}, that @var{match-type} modifiers interact with
861    comparators. Some comparators are not suitable for matching with
862    @code{:contains} or @code{:matches}. If this occurs, sieve issues
863    an appropriate error message. For example, the statement:
864    
865    @example
866    if header :matches :comparator "i;ascii-numeric"
867    @end example
868    @sp 1
869    @noindent
870    would result in the following error message:
871    
872    @example
873    comparator `i;ascii-numeric' is incompatible with match type `:matches'
874    in call to `header'
875    @end example
876    
877    @menu
878    * false:Sieve test false.
879    * true:Sieve test true.
880    * address:Sieve test address.
881    * size:Sieve test size.
882    * envelope:Sieve test envelope.
883    * exists:Sieve test exists.
884    * header:Sieve test header.
885    * numaddr:Sieve test numaddr.
886    @end menu
887    
888    @node Sieve test false
889    @subsubsection Sieve test false
890    
891    @example
892    Syntax: false
893    @end example
894    
895    This test always evaluates to ``false''.
896    
897    @node Sieve test true
898    @subsubsection Sieve test true
899    
900    @example
901    Syntax: true
902    @end example
903    
904    This test always evaluates to ``true''.
905    
906    @node Sieve test address
907    @subsubsection Sieve test address
908    
909    @example
910    Syntax: address [@var{address-part}][@var{comparator}][@var{match-type}]
911                    @var{header-names} @var{key-list}
912    @end example
913    @sp 1
914    @noindent
915    Tagged arguments:
916    
917    @table @var
918    @item address-part
919    Selects the address part to compare. Default is the whole email address
920    (@code{:all}).
921    
922    @item comparator
923    Specifies the comparator to be used instead of the default @code{i;ascii-casemap}.
924    
925    @item match-type
926    Specifies the match type to be used instead of the default @code{:is}.
927    @end table
928    @sp 1
929    @noindent
930    Required arguments:
931    
932    @table @var
933    @item header-names
934    A list of header names.
935    
936    @item key-list
937    A list of address values.
938    @end table
939    @sp 1
940    @noindent
941    
942    The @code{address} test matches Internet addresses in structured headers
943    that contain addresses.  It returns @code{true} if any header contains any
944    key in the specified part of the address, as modified by
945    @var{comparator} and @var{match-type} optional arguments.
946    
947    This test returns @code{true} if any combination of the
948    @var{header-names} and @var{key-list} arguments match.
949    
950    The @code{address} primitive never acts on the phrase part of an email
951    address, nor on comments within that address. Use the @code{header} test
952    instead. It also never acts on group names, although it does act on the
953    addresses within the group construct.
954    
955    Example:
956    
957    @example
958    if address :is :all "from" "tim@@example.com"
959      @{
960         discard;
961      @}
962    @end example
963    
964    @node Sieve test size
965    @subsubsection Sieve test size
966    
967    @example
968    Syntax: size [:over|:under] @var{number}
969    @end example
970    @sp 1
971    @noindent
972    The @code{size} test deals with the size of a message. The required
973    argument @var{number} represents the size of the message in bytes. It
974    may be suffixed with the following quantifiers:
975    
976    @table @samp
977    @item k
978    @itemx K
979    The number is expressed in kilobytes.
980    @item m
981    @itemx M
982    The number is expressed in megabytes.
983    @item g
984    @item G
985    The number is expressed in gigabytes.
986    @end table
987    
988    If the tagged argument is @samp{:over}, and the size of the message is greater
989    than @var{number}, the test is true; otherwise, it is false.
990    
991    If the argument is @samp{:under}, and the size of the message is less than
992    the @var{number}, the test is true; otherwise, it is false.
993    
994    Otherwise, the test is true only if the size of the message equals
995    exactly @var{number}. This is a GNU extension
996    
997    The size of a message is defined to be the number of octets from the
998    initial header until the last character in the message body.
999    
1000    
1001    @node Sieve test envelope
1002    @subsubsection Sieve test envelope
1003    
1004    @example
1005    Syntax:   envelope [@var{address-part}][@var{comparator}][@var{match-type}]
1006                       @var{envelope-part} @var{key-list}
1007    @end example
1008    @sp 1
1009    @noindent
1010    Tagged arguments:
1011    
1012    @table @var
1013    @item address-part
1014    Selects the address part to compare. Default is the whole email address
1015    (@code{:all}).
1016    
1017    @item comparator
1018    Specifies the comparator to be used instead of the default @code{i;ascii-casemap}.
1019    
1020    @item match-type
1021    Specifies the match type to be used instead of the default @code{:is}.
1022    @end table
1023    @sp 1
1024    @noindent
1025    Required arguments:
1026    
1027    @table @var
1028    @item envelope-parts
1029    A list of envelope parts to operate upon.
1030    
1031    @item key-list
1032    A list of address values.
1033    @end table
1034    @sp 1
1035    @noindent
1036    
1037    The @code{envelope} test is true if the specified part of the @sc{smtp}
1038    envelope matches the specified key.
1039    
1040    If the envelope-part strings is (case insensitive) @samp{from},
1041    then matching occurs against the FROM address used in the
1042    @command{SMTP MAIL} command.  
1043    
1044    @emph{Notice}, that due to the limitations imposed by @sc{smtp} envelope
1045    structure the use of any other values in @var{envelope-parts} header is
1046    meaningless.
1047    
1048    @node Sieve test exists
1049    @subsubsection Sieve test exists
1050    
1051    @example
1052    Syntax:   exists @var{header-names}
1053    @end example
1054    @sp 1
1055    @noindent
1056    
1057    The @code{exists} test is @code{true} if the headers listed in
1058    @var{header-names} argument exist within the message. All of the headers
1059    must exist or the test is false.
1060    
1061    The following example throws out mail that doesn't have a From header
1062    and a Date header:
1063    
1064    @example
1065    if not exists ["From","Date"]
1066      @{
1067         discard;
1068      @}
1069    @end example
1070    
1071    @node Sieve test header
1072    @subsubsection Sieve test header
1073    
1074    @example
1075    Syntax:  header [@var{comparator}] [@var{match-type}] [:mime]
1076                    @var{header-names} @var{key-list}
1077    @end example
1078    
1079    @noindent
1080    Tagged arguments:
1081    
1082    @table @asis
1083    @item @var{comparator}
1084    Specifies the comparator to be used instead of the default @code{i;ascii-casemap}.
1085    
1086    @item @var{match-type}
1087    Specifies the match type to be used instead of the default @code{:is}.
1088    
1089    @item :mime
1090    This tag instructs @code{header} to search through the mime headers in
1091    multipart messages as well.
1092    
1093    @end table
1094    @sp 1
1095    @noindent
1096    Required arguments:
1097    
1098    @table @var
1099    @item header-names
1100    A list of header names.
1101    
1102    @item key-list
1103    A list of header values.
1104    @end table
1105    @sp 1
1106    @noindent
1107    The @code{header} test evaluates to true if any header name matches any
1108    key.  The type of match is specified by the optional match argument,
1109    which defaults to ":is" if not explicitly given.
1110    
1111    The test returns @code{true} if any combination of the @var{header-names}
1112    and @var{key-list} arguments match.
1113    
1114    If a header listed in @var{header-names} exists, it contains the null
1115    key (@samp{""}).  However, if the named header is not present, it
1116    does not contain the null key.  So if a message contained the header
1117    
1118    @example
1119    X-Caffeine: C8H10N4O2
1120    @end example
1121    @sp 1
1122    @noindent
1123    these tests on that header evaluate as follows:
1124    
1125    @example
1126    header :is ["X-Caffeine"] [""] @result{} false
1127    header :contains ["X-Caffeine"] [""] @result{} true
1128    @end example
1129    
1130    @node Sieve test numaddr
1131    @subsubsection Sieve test numaddr
1132    
1133    @example
1134    Syntax: require "test-numaddr";
1135            numaddr [:over|:under] @var{header-names} @var{number}
1136    @end example
1137    @sp 1
1138    @noindent
1139    
1140    This test is provided as an example of loadable extension tests. You
1141    must use @samp{require "test-numaddr"} statement before actually using
1142    it.
1143    
1144    The @code{numaddr} test counts Internet addresses in structured headers
1145    that contain addresses.  It returns true if the total number of
1146    addresses satisfies the requested relation.
1147    
1148    If the tagged argument is @samp{:over} and the number of addresses is
1149    greater than @var{number}, the test is true; otherwise, it is false.
1150    
1151    If the tagged argument is @samp{:under} and the number of addresses is
1152    less than @var{number}, the test is true; otherwise, it is false.
1153    
1154    If the tagged argument is not given, @samp{:over} is assumed.
1155            
1156    @node Actions
1157    @subsection Actions
1158    
1159    @node Extensions
1160    @section Extensions
1161    

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

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