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:: |
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 |
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}) |
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}. |
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 |
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 |
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}. |
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 |
|
|