@c This is part of the GNU Mailutils manual.
@c Copyright (C) 1999, 2000, 2001, 2002, 2003, 2004, 2007, 2008, 2010
@c Free Software Foundation, Inc.
@c See file mailutils.texi for copying conditions.
@comment *******************************************************************
The input language understood by the GNU Sieve Library
is a superset of the Sieve language as described in RFC 3028.
@menu
* Lexical Structure::
* Syntax::
* Preprocessor::
* Require Statement::
* Comparators::
* Tests::
* Actions::
* GNU Extensions::
@end menu
@node Lexical Structure
@section Lexical Structure
@subheading Whitespace and Comments
Comments are semantically equivalent to whitespace and can be used
anyplace that whitespace is (with one exception in multi-line strings,
as described below).
There are two kinds of comments: hash comments, that begin with a
@samp{#} character that is not contained within a string and continue
until the next newline, and C-style or bracketed comments, that are
delimited by @samp{/*} and @samp{*/} tokens. The bracketed comments
may span multiple lines. E.g.:
@smallexample
if size :over 100K
@{ # this is a comment
discard;
@}
if size :over 100K
@{ /* this is a comment
this is still a comment */ discard /* this is a comment again
*/ ;
@}
@end smallexample
Like in C, bracketed comments do not nest.
@subheading Lexical Tokens
The basic lexical entities are @dfn{identifiers} and @dfn{literals}.
An @dfn{identifier} is a sequence of letters, digits and underscores,
that begins with a letter or underscore. For example, @code{header} and
@code{check_822_again} are valid identifiers, whereas @code{1st} is not.
A special form of identifier is @dfn{tag}: it is an identifier prefixed
with a colon (@samp{:}), e.g.: @code{:comparator}.
A @dfn{literal} is a data that is not executed, merely evaluated ``as
is'', to be used as arguments to commands. There are four kinds of
literals:
@itemize
@item Number
@cindex numbers, sieve
@dfn{Numbers} are given as ordinary unsigned decimal numbers. An
optional suffix may be used to indicate a multiple of a power of two.
The suffixes are: @samp{K} specifying ``kibi-'', or 1,024 (2^10) times
the value of the number; @samp{M} specifying ``mebi-'', or 1,048,576
(2^20) times the value of the number; and @samp{G} specifying ``tebi-'',
or 1,073,741,824 (2^30) times the value of the number.
The numbers have 32 bits of magnitude.
@item String
@cindex strings, sieve
A @dfn{string} is any sequence of characters enclosed in double quotes
(@samp{"}). A string cannot contain newlines and double quote
characters. This limitation will disappear in future releases.
@item Multiline Strings
@cindex multiline strings, sieve
@kwindex text:
A @dfn{multiline string} is used to represent large blocks of text
with embedded newlines and special characters. It starts with the
keyword @code{text:} followed by a newline and ends with a dot
(@samp{.}) on a newline by itself. Any characters between these two
markers are taken verbatim. For example:
@smallexample
text:
** This is an automatic response from my message **
** filtering program. **
I can not attend your message right now. However it
will be saved, and I will read it as soon as I am back.
Regards,
Fred
.
@end smallexample
Notice that a hashed comment or whitespace may occur between
@code{text:} and the newline. However, when used inside the multiline
string a hash sign looses its special meaning (except in one case, see
below) and is taken as is, as well as bracketed comment delimiters.
In other words, no comments are allowed within a multiline string. E.g.:
@smallexample
text: # This is a comment
Sample text
# This line is taken verbatim
/* And this line too */
.
@end smallexample
The only exception to this rule is that preprocessor @code{include}
statement is expanded as usual when found within a multiline string
(@pxref{Preprocessor}), e.g.:
@smallexample
text:
#include <myresponse.txt>
.
@end smallexample
This results in the contents of file @file{myresponse.txt} being read
and interpreted as the contents of the multiline string.
GNU libmu_sieve extends the described syntax as follows. If the keyword
@code{text:} is immediately followed by a dash (@samp{-}), then all
leading tab characters are stripped from input lines and the line
containing delimiter (@samp{.}). This allows multiline strings within
scripts to be indented in a natural fashion.
Furthermore, if the @code{text:} (optionally followed by @samp{-}) is
immediately followed by a word, this word will be used as ending
delimiter of multiline string instead of the default dot. For
example:
@smallexample
@group
if header "from" "me@@example.com"
@{
reject text:-EOT
I do not accept messages from
this address.
.
.
EOT
# Notice that this the multiline string ends here.
# The single dots above will be part of it.
;
@}
@end group
@end smallexample
@noindent
@item String Lists
@cindex string list, sieve
A @dfn{string list} is a comma-delimited list of quoted strings, enclosed
in a pair of square brackets, e.g.:
@smallexample
["me@@example.com", "me00@@landru.example.edu"]
@end smallexample
For convenience, in any context where a list of strings is appropriate,
a single string is allowed without being a member of a list: it is
equivalent to a list with a single member. For example, the following
two statements are equivalent:
@smallexample
exists "To";
exists ["To"];
@end smallexample
@end itemize
@node Syntax
@section Syntax
Being designed for the sole purpose of filtering mail, Sieve has a very
simple syntax.
@menu
* Commands::
* Actions Described::
* Control Flow::
* Tests and Conditions::
@end menu
@node Commands
@subsection Commands
The basic syntax element is a @dfn{command}. It is defined as follows:
@smallexample
@var{command-name} [@var{tags}] @var{args}
@end smallexample
@noindent
where @var{command-name} is an identifier representing the name of the
command, @var{tags} is an optional list of @dfn{optional} or
@dfn{tagged arguments} and @var{args} is a list of @dfn{required} or
@dfn{positional arguments}.
Positional arguments are literals delimited with whitespace. They
provide the command with the information necessary to its proper
functioning. Each command has a fixed number of positional arguments. It
is an error to supply more arguments to the command or to give it fewer
arguments than it accepts.
Optional arguments allow to modify the behaviour of the command, like
command line options in UNIX do. They are a list of @dfn{tags}
(@pxref{Lexical Structure}) separated by whitespace. An optional
argument may have at most one parameter.
Each command understands a set of optional arguments. Supplying it tags
that it does not understand results in an error
|