@c This is part of the GNU Mailutils manual.
@c Copyright (C) 1999-2004, 2007-2008, 2010-2012, 2014-2015 Free
@c 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 t
|