Updated documentation.

README

@@ -10,6 +10,87 @@ Sieve implementation for Dovecot (1.2)
   
 ################################################################################
 
+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. 
+  Produced errors are aimed to be useful and generally user-comprehensible.  
+  Things like 'Generic error' are a nuisance of the past. 
+* Highly extendable with new sieve capabilities: This keeps the possibility of 
+  plugins in mind. It should eventually provide the necessary infrastructure for 
+  at least all currently known (proposed) extensions. The goal is to keep the
+  extension interface provided by sieve engine as generic as possible, i.e. 
+  without explicit support for specific extensions. New similar extensions can
+  then use the same interface methods without changes to the sieve engine code.
+  If an extension is not loaded using the require command, the compiler truly 
+  does not know of its existance. 
+* The interpreter produces a result containing a set of actions to execute.
+  Duplicate actions can be avoided and conflicts can be detected. Multiple 
+  scripts could be executed in succession on the result object although no 
+  support to do so is currently available. 
+* Supports all extensions provided by the original CMUSieve plugin (currently
+  except notify) and in addition to that it has support for the new and very
+  useful variables extension (see list below). 
+* Compiled binary code can be saved to and loaded back from disk. The binary 
+  is structured as a set of data blocks, which can contain extension-dependent
+  extra data. For example, the include extension uses this to store the 
+  compiled included scripts (no external inclusion of binaries supported yet).
+* This sieve implementation is available as an alternative plugin to  
+  dovecot's deliver. 
+
+Implementation Status
+---------------------
+
+Base tests:
+  false, true: trivial, full
+  address: full
+  header: full 
+  exists: full
+  size: full 	 
+  not, anyof, allof: full
+
+Base commands:
+  require: full
+  if,elsif,else: full
+  discard: full
+  keep: full
+  redirect: full 
+  stop: trivial, full
+	
+Extensions:
+
+  Base specification (RFC5228):
+    fileinto: full
+    reject: full
+    envelope: full
+    encoded-character: full
+
+  Other RFCs/drafts:
+    subaddress: mostly full; not configurable
+    comparator-i;ascii-numeric: full
+    relational: full 
+    copy: full
+    regex: mostly full; but suboptimal and no UTF-8
+    body: full, but text body-transform implementation is simple
+    include: mostly full; needs some more work (no external binaries)
+    vacation: mostly full; no support for required References header
+    imapflags: full
+    variables: mostly full; currently no support for future namespaces 
+
+  Next in order of descending priority:
+	environment: planned
+    notify: planned, first mailto only 
+	date,index: planned
+    editheader: planned, needs additional support from Dovecot though.
+    mimeloop: planned
+
+All implemented extensions are like the engine itself currently very much 
+experimental. A status of 'full' does not mean that the extension is bug-free 
+or even fully RFC-compliant. Other extensions will be added as soon as the 
+necessary infrastructure is available. Extensions already supported by cmusieve
+have priority.
+
 Compiling and Configuring
 -------------------------
 
@@ -90,89 +171,6 @@ 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. It should eventually provide the necessary infrastructure for 
-  at least all currently known (proposed) extensions. The goal is to keep the
-  extension interface provided by sieve engine as generic as possible, i.e. 
-  without explicit support for specific extensions. New similar extensions can
-  then use the same interface methods without changes to the sieve engine code.
-
-What works:
-* Scripts can be parsed, the grammar is fully supported. 
-* Script validation (contextual analysis) works.
-* Script code generation works for all core commands. Comparators, match-types 
-  and address-part modifiers work as required.
-* Interpreter runs core commands and tests. Comparators, match-types and 
-  address-part modifiers have the desired effect. 
-* The interpreter produces a result containing a set of actions to execute.
-  Duplicate actions can be avoided and conflicts can be detected. Multiple 
-  scripts could be executed in succession on the result object although no 
-  support to do so is currently available. Runtime errors are a bit obscure 
-  though; these should provide line numbers.
-* Execution of the result is supported for all core action commands and all
-  fully implemented extensions (see list below).  
-* Compiled binary code can be saved to and loaded back from disk. The binary 
-  is structured as a set of data blocks, which can contain extension-dependent
-  extra data. For example, the include extension uses this to store the 
-  compiled included scripts (no external inclusion of binaries supported yet).
-* This sieve implementation is available as an alternative plugin to  
-  dovecot's deliver. It is not completely useful yet, but hopefully this will 
-  soon be able to replace the current cmusieve implementation.
-
-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 (RFC5228):
-    fileinto: full
-    reject: full
-    envelope: full
-    encoded-character: full
-
-  Other RFCs/drafts:
-    subaddress: mostly full; not configurable
-    comparator-i;ascii-numeric: full
-    relational: full 
-    copy: full
-    regex: mostly full; but suboptimal and no UTF-8
-    body: full, but text body-transform implementation is simple
-    include: mostly full; needs some more work (no external binaries)
-    vacation: mostly full; no support for required References header
-    imapflags: full
-    variables: mostly full; currently no support for future namespaces 
-
-  Next in order of descending priority:
-	environment: planned
-    notify: planned, first mailto only 
-	date,index: planned
-    editheader: planned, needs additional support from Dovecot though.
-    mimeloop: planned
-
-All implemented extensions are like the engine itself currently very much 
-experimental. A status of 'full' does not mean that the extension is bug-free 
-or even fully RFC-compliant. Other extensions will be added as soon as the 
-necessary infrastructure is available. Extensions already supported by cmusieve
-have priority.
-
 Contact Info
 ------------
 

src/testsuite/ext-testsuite.c

@@ -4,12 +4,29 @@
  * Authors: Stephan Bosch
  * Specification: vendor-specific 
  *   (FIXME: provide specification for test authors)
- * Implementation: skeleton
+ * Implementation: very basic
  * Status: under development
- * Purpose: This custom extension is used to add sieve commands that act
- *   on the test suite. This provides the ability to specify and change the 
- *   input message inside the script and to fail validation, code generation and 
- *   execution based on predicates.
+ * Purpose: This custom extension is used to add sieve commands and tests that 
+ *          act the Sieve engine and on the test suite itself. This practically 
+ *          provides the means to completely control and thereby test the Sieve 
+ *          compiler and interpreter. This extension transforms the basic Sieve 
+ *          language into something much more powerful and suitable to perform 
+ *          complex self-test operations. Of course, this extension is only 
+ *          available (as vnd.dovecot.testsuite) when the sieve engine is used
+ *          from within the testsuite commandline tool. Test scripts have the
+ *          extension .svtest by convention to distinguish them from any normal
+ *          sieve scripts that may reside in the same directory. 
+ *
+ * WARNING: Although this code can serve as an example on how to write extensions 
+ *          to the Sieve interpreter, it is generally _NOT_ to be used as a source 
+ *          for ideas on new Sieve extensions. Many of the commands and tests that 
+ *          this extension introduces conflict with the goal and the implied 
+ *          restrictions of the Sieve language. These restrictions were put in 
+ *          place with good reason. Therefore, do _NOT_ export functionality 
+ *          provided by this testsuite extension to your custom extensions that are 
+ *          to be put to general use. 
+ *
+ *          Thank you.
  */
 
 #include <stdio.h>