Compilation
-----------

Refer to INSTALL file.

Installation
------------

This package is currently not built for installation. To test the sieve 
engine it is currently only useful to execute the binaries in the 
src/sieve-bin/ directory:

sievec <sieve-file>

Compiles the script and produces various dumps of intermittent compilation
results. This already works pretty good for all supported features.

sieve-test [-r <recipient address>][-s <envelope sender>]
           [-m <mailbox>][-d <dump filename>] <scriptfile> <mailfile>

Reads mail message from the specified mailfile and executes the specified 
sieve script to produce a verdict. This prints an execution dump with the 
instructions encountered during execution and finally it prints a list of 
actions that would have been performed on this message.

Options:
	-r  envelope recipient address
	-s	envelope sender
	-m	the mailbox where the keep action should store
	-d	causes a dump of the generated code to be written to the specified
		file. Using - as filename causes the dump to be written to stdout

Various example scripts are bundled in the directory 'sieve'.

Authors
-------

Refer to AUTHORS file.

Features
--------

* Well-structured 3-stage compiler; uses dovecot framework and avoids using
  lex/yucc. Compiler doesn't bail on first error, but tries to find more.
* Highly extendable with new sieve capabilities. This keeps the possibility
  of plugins in mind. Should eventually provide the necessary infrastructure for 
  at least all currently known (proposed) extensions.  

What works:
* Scripts can be parsed, the grammar is fully supported. 
* Script validation (contextual analysis) works almost completely. Outgoing 
  mail addresses are not verified yet as required. 
* Script code generation works for most core commands. Comparators, match-types 
  and address-part modifiers already work.
* Interpreter runs and dumps core commands and tests. Comparators, match-types and 
  address-part modifiers have the desired effect. Most test commands work as 
  specified (see list below).
* The interpreter produces a result containing a set of actions to execute.
  Duplicate actions can now be avoided and conflicts can be detected. 
* Execution is now also supported for all core commands.  

Base tests and their implementation status:
	false, true: trivial, full
	address: full
	header: full 
	exists: full
	size: full 	
	not, anyof, allof: full

Base commands and their implementation status:
	require: full
	if,elsif,else: full
	discard: full
	keep: full
	redirect: full
	stop: trivial, full
	
Extensions and their implementation status:

  Base specification (RFC3028):
    fileinto: full
    reject: full
    envelope: full
	encoded-character: planned (draft-ietf-sieve-3028bis)

  Other RFCs/drafts:
    subaddress: full
    comparator-i;ascii-numeric: full
    relational: full 
    regex: full, but suboptimal
    vacation: almost complete; no support for required References header
              and :addresses and :mime are currently ignored.
    imapflags: flag management works, but flags are not stored 
    copy: full
    include: planned (* first leave out variables support)  
	variables: planned (* also amend previously implemented extensions)
    body: planned                        
    notify: planned (- lowest priority)

All implemented extensions are like the engine itself currently very much 
experimental. Other extensions will be added a soon as the necessary 
infrastructure is available. Extensions supported by cmu-sieve have priority, 
although variables might be implemented somewhere in between. 

Design
------

The compiler consists of the following stages:

PARSER: sieve-parser.c, sieve-lexer.c
  Parses the scriptfile and produces an abstract syntax tree for it 
  (sieve-ast.c). 

VALIDATOR: sieve-validator.c
  Performs contextual analysis on the ast produced by the parser. This 
  checks for the validity of commands, tests and arguments. The ast is 
  decorated with any context data acquired during the process. This 
  context is used by the last compiler stage. 

GENERATOR: sieve-generator.c
  This last compiler stage uses a visitor pattern to wander through the ast
  and produces sieve byte code (sieve-binary.c).

The resulting (in-memory) binary can be fed to the interpreter for execution:

INTERPRETER: sieve-interpreter.c 
  The interpreter executes the byte code and produces a sieve_result object. 
  This result is no more than just a collection of actions to be performed. 

TODO
----

* Further implement error handling and limit the maximum number of errors. 
* Produce a substitute sieve plugin for deliver (currently a stub and not 
  part of the make process)
* Verify outgoing mail addresses
* Resolve code duplication introduced for handling address-parts and match-types
  in different command implementations.
* Resolve code duplication amongst comparator, address-part and match-type 
  support as much as possible. 
* Allow the currently in-memory byte-code to be stored as a script binary
* Make this implementation conform section 2.7.2 of RFC3028 (Comparisons Across
  Character Sets). 
* Implement a faster substring search algorithm to make sopport for the body 
  extension a less bad idea.  
* Give the binary format some more thought, it is currently quite rough and
  to the point. 
* Full standards compliance review for the engine and all fully implemented sieve
  extensions.
* Full security review. Enforce limits on number of created objects, script size,
  execution time, etc...
* Automate script tests; i.e. build a test suite.
* Use mmap for the binary script representation.