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 <sieve-file> [<mailfile>/-]

Reads mail message from the specified mailfile (- = stdin) and executes the 
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. 

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

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.
* 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. Action commands have no effect. 
 
Extensions and their implementation status:

  Base specification (RFC3028):
    fileinto: validation, generation and interpretation; no execution 
    reject: validation, generation and interpretation; no execution
    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: validation, generation and interpretation; no execution
    imapflags: flag management works, but flags are not stored.
    include: planned (* first leave out variables support)  
	variables: planned (* also amend previously implemented extensions)
    body: planned                        
    copy: 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 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
----

* Produce a fully working interpreter that actually executes actions, currently
  tests are evaluated and actions just print their occurence.
* Extract code dump functionality from interpreter and start sieve-code-dump.c
* Resolve code duplication introduced for handling address-parts and match-types
  in different command implementations.
* Implement a faster substring search algorithm to make sopport for the body 
  extension a less bad idea.  
* Further implement error handling and limit the maximum number of errors. 
* Resolve code duplication amongst comparator, address-part and match-type 
  support as much as possible. 
* Use dovecot streams for code dump (debugging), currently the code is riddled 
  with printf()s. 
* Give the binary format some more thought, it is currently quite rough and
  to the point. 
* Produce a substitute sieve plugin for deliver (currently a stub and not 
  part of the make process)
* Full standards compliance review for the engine and all fully implemented sieve
  extensions.
* Automate script tests; i.e. build a test suite.
* Use mmap for the binary script representation. 
* Allow the currently in-memory byte-code to be stored as a script binary