MFL knows about the MIME structure of messages, and has the concept of a "current message part." All header tests are done in the context of this current message part. In the default state, the top-level message part (i.e., the message headers) are selected. MFL scripts may select other message parts (e.g. the children of a multipart message part). Let's say you have a message whose top level content type is "multipart/alternative" with two children, one with content type "text/plain" and the next with "text/html". Consider these three statements:

    /* A */  sieve { header :matches "content-type" "multipart/*" }
    /* B */  sieve { header :matches "content-type" "text/plain*" }
    /* C */  sieve { header :matches "content-type" "text/html*" }

MFL is like C

What's in MFL's C-like component: fundamental and compound data types, expressions, control flow statements, variables, initializers, functions, and a cpp-like preprocessor.

What's not: switch statement (and case labels), function prototypes (except for function definitions), local variables inside any compound block (including functions);

Oddities: MFL C-like variables may contain "$". Thus "$a" and "a$" are legal variable names. Functions supplied as part of mvmf will always name variables and functions starting with '$' -- other script writers should avoid doing that.

Status of C-like implementation

Thing	Status	Comments
Fundamental data types and modifiers
unsigned	Supported	May be used as a modifier to an integer type, or by itself as an abbreviation for unsigned int
short	Supported	May be used as a modifier to int, or by itself as an abbreviation for short int
long	Supported	May be used as a modifier to int, or by itself as an abbreviation for long int
char	Supported	A 1-byte value
int	Supported	A natural integer (currently 2-byte value)
$int4$	Supported	MFL extension to guarantee 4-byte int
(short int is 2 bytes; long int is 4 bytes.)
float	Supported	Floating point number
double	Supported	Double precision floating point number
string	Supported	MFL extension for character strings.
Aggregates and metatypes
typedef	Supported	Defines a new type in terms of another type definition
struct	Supported	A data structure
union	Supported	A data overlay
enum	Supported	Enumerated types. See note "E".
[]	Supported	Arrays.
*	Supported	Pointers. See note "P".
Control statements
break	Supported	Exit loop.
continue	Supported	Next loop iteration.
do	Supported	Loop control.
if	Supported	Conditional execution
else	Supported	(implemented as part of "if")
for	Supported	Loop control
return	Supported	Return from a function (with optional return value)
switch..case	Not supported	Value detection -- no plan to support this
while	Supported	Loop control
pv$	Supported	MFL extension to print to stdout. See note "PV".
[built-in functions]	Supported	Described here
[MFL functions]	Supported	User-written functions (see below)
Expressions and evaluation
C	Supported	MFL extension to introduce a C-like code block, which must be enclosed in curly braces. Useful to guarantee that a script is in C-like mode, e.g. for a code snippet that is intended to be included by another script.
sizeof	Supported	Returns number of bytes of a variable, storage element, type, or expression. See note "SO".
sieve	Supported	MFL extension to introduce a SIEVE code block, which must be enclosed in curly braces.
( )	Supported	Parenthetical grouping for explicit precedence
? :	Supported	Conditional expression: test ? truth : falsth
!	Supported	"!" Operator (boolean not)
~	Supported	"~" Operator (bitwise complement)
,	Supported	"," Operator (return second of two expressions)
=	Supported	"=" Operator or assignment
==	Supported	"==" Operator (compare equal)
==^	Supported	"==^" Operator (string compare equal, ignore case) See note "S".
!=	Supported	"!=" Operator (compare not equal)
!=^	Supported	"!=^" Operator (string compare not equal, ignore case) See note "S".
=.	Supported	"=." Operator (regex matching, pattern on RHS) See note "S".
!=.	Supported	"!=." Operator (regex non-matching, pattern on RHS) See note "S".
=?	Supported	"=?" Operator (glob-style matching, pattern on RHS) See note "S".
=?^	Supported	"=?^" Operator (glob-style matching, ignore case, pattern on RHS) See note "S".
!=?	Supported	"!=?" Operator (glob-style non-matching, pattern on RHS) See note "S".
!=?^	Supported	"!=?^" Operator (glob-style non-matching, ignore case, pattern on RHS) See note "S".
<	Supported	"<" Operator (compare less than)
<^	Supported	"<^" Operator (string compare less than, ignore case) See note "S".
<=	Supported	"<=" Operator (compare less than or equal)
<=^	Supported	"<=^" Operator (string compare less than or equal, ignore case) See note "S".
<<	Supported	"<<" Operator (shift left)
<<=	Supported	"<<=" Assignment operator (shift left)
>	Supported	">" Operator (compare greater than)
>^	Supported	">^" Operator (string compare greater than) See note "S".
>=	Supported	">=" Operator (compare greater than or equal)
>=^	Supported	">=^" Operator (string compare greater than or equal, ignore case) See note "S".
>>	Supported	">>" Operator (shift right)
>>=	Supported	">>=" Assignment operator (shift right)
+	Supported	"+" Operator (add)
+=	Supported	"+=" Assignment operator (add)
++	Supported	"++" Operator (increment)
-	Supported	"-" Operator (subtract)
-=	Supported	"-=" Assignment operator (subtract)
--	Supported	"--" Operator (decrement)
*	Supported	"*" Prefix operator (pointer dereference)
*	Supported	"*" Infix operator (multiply)
*=	Supported	"*=" Assignment operator (multiply)
/	Supported	"/" Operator (divide)
/=	Supported	"/=" Assignment operator (divide)
%	Supported	"%" Operator (modulo)
%=	Supported	"%=" Assignment operator (modulo)
[	Supported	"[" Operator(kinda) (array reference)
&	Supported	"&" infix operator (bitwise AND)
&	Supported	"&" Prefix operator (address-of)
&&	Supported	"&&" Operator (boolean AND)
&=	Supported	"&=" Assignment operator (bitwise AND)
|	Supported	"|" Operator (bitwise OR)
||	Supported	"||" Operator (boolean OR)
|=	Supported	"|=" Assignment operator (bitwise OR)
.	Supported	"." Operator (member reference)
->	Supported	"->" Operator (member reference)
Preprocessor
MFL sports a basic cpp-like preprocessor; this section lists the preprocessor elements you might expect. The preprocessor is conceptually responsible for removing comments and interpreting preprocessor directives. Directives are indicated in a script by using '@' as the first character on the line (i.e., in the first column). (The use of '#', as with C, conflicts with the Sieve-mandated comment characters. Nevertheless when you configure mvmf you can enable the use of '#' instead of or in addition to the '@' character.) There are more elaborate notes about the use of the preprocessor later in this document.
@define	Supported	Defines a preprocessor constant or macro.
@else	Supported	Starts the "else" part of a preprocessor conditional
@endif	Supported	Ends a preprocessor conditional block
@help	Supported	Prints the supported preprocessor statements (useful only in interactive mode)
@ifdef	Supported	Begins a conditional block that is executed if a preprocessor symbol is defined.
@ifndef	Supported	Begins a conditional block that is executed if a preprocessor symbol is not defined.
@include	Supported	Includes the contents of another MFL file at this point in the compilation/interpretation
/*..*/	Supported	Block comment
//	Supported	Comment to end of line
Preprocessor extensions
MFL has some other preprocessor directives.
@ifdef_func	Supported	Begins a conditional block that is executed if an mfl function is defined.
@ifdef_var	Supported	Begins a conditional block that is executed if an mfl variable is defined.
@ifndef_func	Supported	Begins a conditional block that is executed if an mfl function is not defined.
@ifndef_var	Supported	Begins a conditional block that is executed if an mfl variable is not defined.
@include_noerr	Supported	Like @include, but doesn't complain if the file is not available. Useful for loading control files that don't have to exist.

Note E: A specific assignment to an enum member definition is not supported, e.g.:

    enum {
        aa,
	bb=3,
	cc }

Note P: Pointers are supported inasmuch as you can point to some other data storage defined in an MFL program. Pointers are constrained at run-time only to reference a particular data object.

Note PV: pv$ is basically a hack to allow debugging printouts. You can print a single value e.g.

    int x;
    pv$ x;

    int x;
    x = 23;
    pv$ "x is %d\n", x;

Note S: These string comparison operators are MFL extensions.

Note SO: The MFL interpreter does late type binding and late evaluation; there is currently no way for the interpreter to figure out the type of an expression without evaluating it. sizeof can give you the size of an expression, but note well that the expression will be evaluated in the process. E.g. in:

   int x = 0;
   int sx;

   sx = sizeof( x = 3 );

Initializers

    int x = 3;
    int y = {3};

   struct {
       int key;
       string val;
} kvt[3] = {
    { 10, "key 1" },
    { 20, "key 2" },
    { 30, "key 3" } };

Statements and blocks in expressions

    int i;
    i = { 3 + 7 };		// This is wrong
    i = { 3 + 7; };		// This is correct

    int i;
    i = if ( foo() ) 3; else 4; ;	// looks odd
    i = if ( foo() ) {3;} else {4;} ;	// perhaps better.

Strings

Strings are implemented using something called a refstr, which is a view of a referenced string. Multiple views to common strings may be obtained via string pointers (i.e. (string *)) which can be dereferenced to access their reference target. When a string is modified, any views into the underlying string object are modified to reflect the change. For example, consider this MFL code sequence:

    string s = "I am a test";
    string *sp = $str_sub(s, 7, 4);       // points to "test"
    string *s1P = $str_sub(s, 2, 2);      // points to "am"
    *s1P = "used to be";

    "I used to be a test"

    "test"

Every string, including the targets of string pointers, has the following attributes:

Start offset

The offset into the base string at which this refstr begins. This offset is absolute, but it may be subject to change either explicitly or implicitly when some other refstr alters the base string (see discussion above). An absolute value of -1 means that the offset is anchored at the beginning of the string, despite any attempts to move it.

End offset

Just like the start offset, this is where in the base string that the refstr ends. A value of -1 anchors the end offset at the end of the base string.

Current byte index aka "bx"

Some string operations keep track of a current byte index. For example, built-in-functions to find or extract a token from a string will use the bx as a start point, and will update it to provide the next start point -- this allows repeated "find token" operations to step through the string. The bx may be used internally in some cases as well. Note that the bx is associated with each refstr, including the refstr that is the target of a pointer. So:

      string s = "hello there";
      string *sP;
      sP = $str_sub(s, 4, 4);	// "o th"
      $str_bx_set(*sP,3);	// Sets to 3, the 'h' position
      $str_bx(s);		// will initially be 0
      $str_bx(*sP);		// is still 3.
  

Some operations on strings:

Conversions.

Converting from a non-string to a string will attempt to do the right thing. e.g. '(string)3' yields the string "3". Converting from a string to a non-string will also attempt to do something reasonable: e.g. assigning from a string to an int will perform a C-like 'atol()' function on the string.

"+"

Adding something to a string will convert the second term to a string if possible, then return the concatenation of the two strings. So '(string)"hello" + 3' yields the string '"hello3"' .

Comparisons

'==', '!=', '<', '<=', '>=', '>' do what you might expect.

Regex matches

'=.' performs a regex match on a string, with the pattern on the right hand side. e.g. in:

       string s = "hello";
       if ( s =. "h.*o" )
           some code here;
    

the test would succeed. '!=.' is the notted version of the test.

Wild matches

'=?' and '!=?' are similar to regex matching, but using more familiar (to some) matching where '?' matches exactly one character and '*' matches zero or more characters. This is just like the sieve ":matches" match-type.

Case insensitivity

Some of the string match operators have a case-insensitive mode which is indicated by using a '^' after the operator. These are: "==^", "!=^", "=?^", "!=?^", "<^", "<=^", ">^", and ">=^" . The '^' is supposed to suggest some kind of case shifting.

Notes about string pointers:

General

Every string is a refstr which is a view into an underlying string. The only way to manipulate this view is through string pointers. Various built-in functions such as $str_sub provide ways to create a refstr to another string; the reference is always done via a pointer. When you dereference the pointer, you are operating on the string.

"+" and "-"

If you add or subtract to a string pointer, you shift its position into the underlying string. Both the start and ending positions will be adjusted, unless they run off the end of the reference string. Consider:

       string s = "abcdefgh";
       string *sp;
       sp = $str_sub( s, 3, 2 );	// Now points to "de"
       ++sp;				// Now points to "ef"
       sp - 4;				// points to "ab"
       sp - 5;				// points to "a"
    

Note that a string literal is not a string until it is coerced into one. Since those kinds of coercions happen automatically in many places you might not notice the need for it. But be aware that:

    "abcdefg" + 3

    (string)"abcdefg" + 3

built-in functions

MFL functions

An MFL function has a C-like syntax, with a declaration of a return type, a formal argument list, and a function body. One quirk of MFL functions is that a function is treated syntactically like a variable declaration, one side-effect of which is that it has to be terminated with a semicolon (or a comma and another declaration using the same type). An MFL function therefore looks something like this:

    /* Recursive function to return digits of an integer
       separated by spaces
    */
    string dp( int n ) {
        if ( n < 10 ) return (string)n;
        return dp( n/10 ) + " " + (string)(n%10);
    };

Preprocessor

Comment removal. Conceptually, the preprocessor removes comments from the script before it is interpreted. There are two styles of comments: block comments and rest-of-line comments.

A block comment begins with the pair of characters /* and ends with the pair */. Comments do not nest: once a comment block is opened with /* the next */ closes it, even if another /* is encountered first.

A rest-of-line comment begins with the pair of characters // or with the single character # and ends at the end of the line. This is useful for annotating a single statement.

The following illustrates both kinds of comments:

    /* Basic SIEVE setup */
    sieve {
	require ["fileinto", "envelope"];
    }

    int score = 0;		// Declare and initialize score
    float f;			# A temporary

    /* Now look for a special "X-Spam-Score" header and adjust
       our integer score according to the floating point value
       found there.
    */
    if ( sieve { header :matches "X-Spam-Score" "*" } ) {
	f = $str_match(0);	// pick up the score value
	if ( ( f >= 9.0 ) && ( f <= 9.9 ) )
	    ++score;		// Significant value bumps score.

Macro substitution. The preprocessor has its own symbol table. Symbols in this table are variously thought of as preprocessor symbols, macro names, or manifest constants. The combination of a symbol and its value may be thought of as a macro. Whenever the preprocessor encounters one of these symbols in the input stream (e.g., in the script), the value that has been assigned to that symbol is used instead of the actual symbol. This is known as macro substitution or macro expansion. A macro is created via the "@define" preprocessor directive, described below.

There are two kinds of macros: those with arguments and those without. Actual arguments to a macro are supplied in a parenthesized list, with arguments separated by commas. (Depending on the way MFL is built, whitespace may or may not be allowed between the macro name and the opening parenthesis. To be safe, don't use whitespace here: follow the macro name immediately by an opening parenthesis.)

A simple example of macro definition and substitution:

    @define ALTADDR "fred@example.com"

    sieve {
        redirect ALTADDR;
    }

	redirect "fred@example.com";

A macro with arguments:

    @define aab(a,b) (a+a+b)

    int i = aab(3,4);

    int i = (3 + 3 + 4);

Macro references can not be recursive. While a macro is being expanded, it is prevented from further expansion until its value is completely substituted. (It's said that the macro is "painted blue" while it is ineligible for expansion.) This prevents a macro value from refering to the macro name itself, or to the name of another macro being expanded. Note also that macro substitution occurs on a token-by-token basis. Since a quoted string is an individual token, any macro names inside a quoted string are not substituted.

Preprocessor directives. The preprocessor is otherwise commanded via preprocessor directives. A preprocessor directive is indicated by a @ character at the first character position on a line, followed by a recognized preprocessor command. For compatibility with older mvmf releases, when you build and install mvmf, you can choose to enable '#' as an alternative preprocessor introducer character, in place of or in addition to the use of '@'. Note that the indentation in various examples is for clarity only: the @ (or '#') must occur at column 1. Whitespace may occur between the @ and the command and in fact is encouraged to indicate a nesting level. However, when one talks about a preprocessor directive, it's usually with the concatenation of the @ and the command name. Preprocessor directives:

@define macroname[(arguments)] [value]

Define a macro, either with or without formal arguments. Its simplest form is:

    @define NAME  value

so that whenever NAME is encountered in the script after this, the value is used instead. Formal arguments may also be given by including them in parenthesis directly following the macro name. Each occurance of a formal argument in the macro body will be replaced by the actual argument when the macro is invoked. For example:

    @define RS(rcpt) sieve { redirect rcpt; }

    RS( "bozo@example.com" )

will cause this code to be used:

    sieve { redirect "bozo@example.com"; }

Macros can be used to stand in for commonly used strings or sequences, particulary for code that might be changed from time to time (thus you'd only have to change the macro definition rather than changing code in multiple places in your script). As with C guidelines, making your macro names uppercase gives a visual clue that macro names are being used.

@else

Negates the effect of conditional parsing.

@endif

Ends a conditionally parsed block.

@help

Prints a list of valid preprocessor commands. Useful only in interactive mode.

@ifdef macroname

Tests whether a name exists in the preprocessor symbol table; if it does, allows interpretation of the script up to the next matching @else or @endif directive. If it doesn't, the script up to the next matching @else or @endif directive is not parsed. Example:

    /* @define DROPMAIL  */

    sieve {
    @ifdef DROPMAIL
	discard;
    @else
	keep;
    @endif
    }

i.e., if DROPMAIL is defined to the preprocessor, the discard statement is executed. Otherwise, the keep statement is executed.

@ifdef_func funcname

Tests whether an MFL function exists.

@ifdef_var varname

Tests whether an MFL variable exists.

@ifndef macroname

Tests whether a name doesn't exist in the preprocessor symbol table, and performs conditional script parsing based on that. i.e., this is the inverse of @ifdef.

@ifndef_func funcname

Tests whether an MFL function doesn't exist.

@ifndef_var varname

Tests whether an MFL variable doesn't exist.

@include fileref

Inserts another script file at this point in the parsing of the script where the @include is encountered. fileref is either a quoted string, in which case it refers to a user-level file, or it's a name enclosed in anglebrackets, in which case it refers to a system-level file. Each sort of access has its own include path, i.e. a list of directories that will be searched for the file (for a user-level file, the file is always looked for relative to the current directory before trying the user-level include path). Every application that uses MFL will establish at least one directory in the system-level path, and you can add directories to both paths, e.g. by using the built-in-function $mfl_incdir_add().

    @include "data.mfl"

inserts the contents of the file data.mfl located in the current directory (e.g., your home directory) or in the user-level include path, and

    @include <common.mfl>

inserts the contents of the file common.mfl that is found along the system-level include path.

@include_noerr fileref

Like @include, but ignores any error accessing the file.

Preprocessor statements are always acted on at parse time. You might have an elaborate MFL function that you store in its own file; using something like

    @include "bigfunction.mfl"

    sieve {
	if envelope :is "from" "monthly-report@example.com" {
	    C {
		$mfl_exec_string( "@include \"bigfunction.mfl\"" );
		bigfunction();
	    }
	}
    }

Misc notes

Each application may also call specially-named MFL functions at particular points in the utility's execution. You may supply these hook functions to affect some aspect of the application's operation at the point the hook is called.

Application-specific details such as these are described along with each utility that incorporates MFL.

Future plans and ideas

Examples