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>

Reads mail message from standard input and executes the sieve script to
produce a verdict. Currently only prints an execution dump with the 
instructions encountered during execution.

In the directory ./sieve various example scripts are bundled. 

Features
--------

* Well-structured 3-stage compiler; uses dovecot framework and avoids using
  lex/yucc. Parser 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. Match type :matches is not 
  supported yet. 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, but fails to handle leading zeros
    relational: full 
    regex: full, but suboptimal
    vacation: validation, generation and interpretation; no execution
    imapflags: planned (* first implement tests) 
    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 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.

TODO
----

* Resolve code duplication introduced for handling address-parts and match-types
  in different command implementations. 
* 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. 
* Produce a fully working interpreter that actually executes actions, currently
  tests are evaluated and actions just print their occurence.
* 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)
* 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