XetPan Documentation.
Part of the XetPan Open Mail User Agent Project.
(C) 2002, 2003, Melvin Hadasht <melvin.hadasht@free.fr>
GPL license v2, or any later.

XETPAN PROCESSING RULES SYNTAX

1. Processing Rules

A procesing rule is the combination of one condition and one action.
When the condition is satisfied, the action is performed.

Future plans are to allow a list of actions, and a list of action to
perform when condition is not satisfied.

Each condition, action and rule is uniquely identified with a name in their
private namespace: no two conditions can share the same ID, but a condition
and a rule can have the same ID.

2. Condition

2.1. Expression Syntax

An expression allows to perform tests on some objects. The test
evaluates to TRUE if it succeeds, FALSE otherwise.

An expression is of the form:

ATTRIBUTE OPERATOR OPERAND
ATTRIBUTE VALUE...
REFERENCE

future plans are to support OPERAND1, OPERAND2... with the same
semantic as Sieve server-side mail filtering language where the
condition must apply to OPERAND1 OR OPERAND2 etc...

2.1.1. Header Attributes

Headers are written in a case insensitive manner and are suffixed with
a colon:

from:
to:
subject:
date:
cc:
reply-to:
in-reply-to:
references:
message-id:
...

any text that ends with ": " and does not contain a space is
considered to be a header. The user can thus specify any header, for
example the X-headers.

Header attributes support the following STRING OPERATORS that operates
on string operands.

is     for case insensitive equality
IS     for case sensitive equality
has    for case insensitive substring matching
HAS    for case sensitive substring matching
regexp for case insensitive regular expression matching
REGEXP for case sensitive regular expression matching

A string is delimited by double-quotes (").  
Backslash is the escape character: any double-quote
in the string is escaped by a back-slash.  A back-slash is also
escaped with a back-slash. Thus, to match the string <I said: "hi">
the operand must be written "I said: \"hi\"". 

2.1.2. Message Content

Supported message content tests are:

body	  to match a string in the body of the message. 
mime	  (not decided yet)

Supported operators for message content are the same as for headers.


2.1.3. Message Attributes

Supported message attributes are:

size	  total size of a message
mime_size total size of a MIME part
uid	  message unique identifier in the mailbox (IMAP'S UID)
age	  message age
score	  message score

these attributes support the following ORDER OPERATORS, and apply to a
number or a size (a size being a number with units: b, k, M, G):
<      lower than
<=     lower or equal than
>      greater than
>=     greater or equal than
=      equal to
<>     not equal to

Number (not sizes) can be written in hexadecimals.

date	  message date. 

Support the same ORDER OPERATOR, the operand being a date.
The format of the date is
YYYY-MM-DD HH:mm

flags	  message flags

this attribute has a special syntax:

flags ([+-]([dfnu]|[^-+ ]))*

+ the following flags must be set
- the following flags must be unset
n: New flag
u: Unseen flag
d: Deleted flag
f: Flagged flag
any other string is considered a flag supported by the mailbox.

Example:
flags -f+d+Spam will match a message that is not flagged, but marked for deleted and which has a flag "Spam" set.

folder	  message original folder

this attribute supports the string operators and apply to a string. Useful when processing virtual folders.

2.1.4. External tests

XetPan supports using external commands of Python functions to perform
message matching.

shell COMMAND ARGS... launches sh -c "COMMAND ARGS..."
python MODULE FUNCTION ARGS is equivalent to:
import MODULE
FUNCTION(message, ARGS) 

where message is a C pointer to the internal XetPan message structure.

ARGS are normal strings

2.1.5. Reference To Other Known Conditions

When an attribute is not recognized, it is assumed to be a reference
to another registered condition.

2.2. String Operands

String operands can contain tokens which are expanded for each message
processed. These tokens have the following syntax:

%ATTRIBUTE%

where attribute is one of the previously mentioned attributes.

2.3. Combining Expressions

The expression can be combined with another expression using booleans
operators. Supported operators are "not", "&" (and), "|" (or) and "^"
(exclusive or).

Boolean operators are evaluated from left to right, with precedence of
operators of higher priority. Currently, the only high priority
boolean operator is "&" which is evaluated before "|" and "^". The
negation operator "not" apply to the expression immediatly on its
right.

Parenthesis can be used to explicitly change the order of evaluation.

Examples:

Example 1:

expression1 & expression2 | expression3

is evaluated as (expression1 & expression2) | expression3

Example 2:

expression1 | expression2 & expression3

is evaluated as expression1 | (expresion2 & expression3)

Example 3:

not expression1 & expression2
is evaluated as (not expression1) & expression2

Example 4:

not (expression1 & expression2)
is evalueated as such and is different than Example 3

3. Actions

Not implemented yet.