Test -expression utility

Test an expression, e.g., a Sieve filter or configuration recipe.

Syntax
imsimta test -expression

Restrictions
Must be superuser or the MTA user (the  option in  ,  or prior to MS 7.0.5, the    MTA  Tailor option value), or be in the group specified by the    option in   (prior to MS  7.0.5, be in the group specified by the   MTA Tailor option value), in order to have any    or    actions applied by  a Sieve filter  be shown in the utility&#x27;s output.

Description
Test an expression, such as a Sieve filter or a  configuration recipe. tests message enqueue functions, such as Sieve filters (with  the   switch). tests recipe syntax operating on a Unified Configuration. Testing consists of parsing the expression, which converts it to an internal compiled form, and then evaluating the compiled form. The  switch can be used to disable the evaluation step.

Basic arithmetic and string operators are supported in expressions; and when variables may be used, that is, if the   switch has been used, then additional operations upon variables are supported. For a list of the supported operators (with one exception), see the recipe language&#x27;s list of Operators in Order of Precedence. The one difference between the operator support for the recipe language, vs. for Sieve filters, is that since in Sieve syntax square brackets represent lists, indexing into a string in Sieve must be performed using parentheses rather than square brackets. So for instance a Sieve script: require "fileinto"; str := "12folderXYZ"; substr := str(3,9); fileinto substr; is equivalent to &#x27; &#x27;. (See Variable indices under Recipe language for further  discussion of indexing into strings and lists.)

Without the  switch,   tests symbol  table functions (in general, comprising various string functions). The symbol table functions available include those shown in  Symbol table functions. (Note that this set of functions supported by  and by Sieve filters does not include all of the Recipe language functions discussed under Recipe language; the recipe language includes support for additional functions useful in configuration recipes.)

Conditional expressions may be used, having the form: test ? then-result : else-result However, " ..." tests of the form if test {then-result} else {else-result} are only allowed in certain contexts; in particular, they are not allowed when only basic expressions are permitted, as in  mapping table  expression substitutions.

The expression to test may be read from a file via the   switch. If  is not specified, then the utility  enters an interactive loop, prompting for expressions to test with an " " prompt; the utility will exit when CTRL/D (UNIX)   is entered.

By default, each line of expression is evaluated independently (separately). The  switch may be used to tell the  utility to evaluate the entire block of input expression(s) at once, as  a whole; thus in particular,   is useful when  evaluating a multi-line Sieve filter.

New in MS 7.0u2,  will return  a nonzero status in the event of either a parse or evaluation error.

,  (default)
By default, input is evaluated one line at time. With the  switch, evaluation is postponed  until the entire input file has been read (if the    switch is used), or until CTRL/D is entered (if    is not used and expressions are being entered interactively). Thus in particular   allows use of multi-line Sieve  constructs.

&#x5b; &#x5d;,   (default)
The  utility is capable of outputting  additional, detailed information about the internal steps of its  operation. The  switch enables this output. Specifying  is equivalent to specifying   ; greater amounts of debug information can be  requested by specifying     for values of    up to 10.

Note that a debug level of 2 or more enables output of strings specified via Sieve " " actions. Note that a debug level of 3 or more enables output (via  "   "  debug output  lines) of the header lines of the message file being processed, while a  debug level of 4 or more enables output not only of the header lines,  but also of the message body lines handled in memory (via  "   " debug  output lines) of the message file being processed, and a debug level of  5 or more enables output of the message body lines handled via an  external file for "large" message bodies (via  "   " debug  output lines). is the default.

New in MS 7.0u2,   turns off the dump of the expression.

,  (default)
(New in MS 7.0u3.)  is only available when    and   are specified. sets the envelope ENVID value for use with the Sieve envelope-dsn extension  for envelope ENVID tests. is the default.

, ,    (default)
( new in MS 6.2;   and   new in MS 6.3)    and   are only available when    and   are specified. sets the return address for use in Sieve envelope From comparisons. If this switch is not used, the default postmaster address is assumed (see the    MTA option).

To specify an empty (null) envelope From, the command wants to see  ---  however shell quoting, e.g., , may be  required in order to get such an argument through the shell.

sets the recipient address for use in Sieve envelope To comparisons. If this switch is not used, or if  is  explicitly specified, then no recipient address is set.

The  switch tells the utility to read its input  from the specified file, rather than prompting for and reading input  interactively. Note that when using  to enter a  Sieve filter file,  one usually also wants to use    (so that multi-line Sieve constructs can be handled).

The  switch may be used to specify the maximum  number of iterations permitted in the internal code implementing :matches, overriding (for this command execution) any  setting of the    MTA option. (Note that the default value of   is 1,000,000,000.)

The  switch may be used to specify the maximum  size of list permitted, overriding (for this command execution) any  setting of the    MTA option. (Note that the default value of   is 64.)

The  switch may only be used when the    switch is present. It is used to specify an input message to process; this should be an RFC 822 message, not a message  file from the MTA&#x27;s queue area (which contains additional, envelope  information beyond the basic RFC 822 message itself).

,
The  switch means to test using the MTA&#x27;s normal  enqueue code. The  switch (new in MS 7.5) means to  test recipe language syntax, operating on a Unified Configuration. and  may not  be specified together.

,  (default)
(New in MS 8.0)  takes a required integer  argument specifying the initial MT-PRIORITY value. This can affect, for instance, the value of the  Sieve environment item. This may only be specified when   has also been specified. Furthermore, it is only relevant when   has been specified (though it will  not result in an error to specify   without   ).

(default),
Specifying  disables evaluating multiple,  semicolon-separated, result-generating, statements per physical line. When  is specified, only the first result found  when evaluating the line will be returned. is the default.

The  switch tells the utility to output to the  specified file, rather than to the terminal screen.

(default),
(New in MS 6.2.) The  or    switch may only be used when    is specified. Specifying  causes  Sieve  " " clauses to not be required: any Sieve  operation that would normally need an appropriate  " " clause in order to be permitted will  be permitted even without such a " "  clause. In other words,  gives an effect as if  the Sieve script in question had initially done a  require list-of-all-possible-extensions;

,  (default)
(New in MS 8.0) Specify the recall secret. This is only relevant when   has been specified.

,  (default)
(New in MS 8.0.) The  switch may be used to specify  an "authenticated" sender address, as if SMTP AUTH had been  used. For instance, the Sieve environment item    will be set to the  sender value, if specified. This is only relevant when   has been specified.

,
(New in MS 8.0) Specify the source channel; the default is   (the "L"ocal channel). This is only relevant when   has been specified.

Set symbol table statement parsing flags. The argument is a bit-encoded integer, with default value 1. The meanings of the various bits are shown below.

Bit 0 is the least significant bit.

Note that use of the  switch sets bit 9 (allow  bracketed lists). Use of the  switch sets bits 2  through 4 (debug level).

The  switch may be used to specify the maximum  length of string permitted; the default is 65535.

,  (default)
The  switch allows the use of variables and  symbolic values, and operations may be performed on variables. For instance, symbolic names such as    may be used to  reference  the    directory specification, and assignments may be made to  symbolic variable names, such as , and operators  such as those shown in  Operators in Order of Precedence of the recipe language  may be used. is the default.

,  (default)
(New in MS 7.0.5) The  switch must be used in order  to use. If  is specified with  , then the Sieve is treated as a  system-level Sieve; if  not, then it is treated as a user-level Sieve.

The  switch controls the interpretation of unassigned  variables. The default is.

,  (default)
(New in MS 8.0) The  switch may be used to  specify a username, relevant when username-based checks are in use. For instance, the  Sieve environment item    will be set to the  username value, if specified. This is only relevant when   has been specified.

,  (default)
(New in MS 8.0) The  switch specifies allowing use of  internationalized email addresses, as with the SMTPUTF8 SMTP extension  (from RFC 6531). is the default.

Examples
Expression: require "fileinto"; Expression: if header :contains &#x5b;"Subject"&#x5d; &#x5b;"foo"&#x5d; { fileinto "foo"; } Expression: if header :contains &#x5b;"Subject"&#x5d; &#x5b;"test"&#x5d; { discard; } Expression: CTRL/D Dump: header:2000111;0 3  1  :contains  1  "Subject"  1  "foo"  if Dump: 5  ;  fileinto:2000110;0  1  1  "foo"  ;  header:2000111;0  3 Dump: 1 :contains  1  "Subject"  1  "test"  if  3  ;  discard:2000107;0 Dump: 0 Result: 1 Filter result: &#x5b; discard &#x5d; The above command sequence tests the result of various Sieve filter command lines on a message file, , that for the  purposes of this example is assumed to have a Subject: header line that  contains the word "test" but does not contain the word  "foo". Expression: require &#x5b;"envelope","fileinto"&#x5d;; Expression: if envelope :all :is "from" "" { fileinto "notifications"; } Expression: CTRL/D Dump: envelope:4000115;0 4  1  :all  1  :is  1  "from"  1  ""  if  5 Dump: ; fileinto:4000114;0 1  1  "notifications" Result: "notifications" &#x27; &#x27; Filter result: &#x5b; fileinto "notifications" &#x5d; The above command sequence tests the result of a Sieve filter script that files all notification messages (messages with empty  envelope From) to a folder named " ",  when that  Sieve filter is presented with some message and when the envelope From  is set to be empty via the   switch. Expression: loop { discard; exitif (true); } Expression: CTRL/D Dump: loop 5  discard;0  0  ;  1  exitif Result: 1 Filter result: &#x5b; discard &#x5d; The above example shows use of the new-in-MS-7.0.5  " " construct  in a Sieve filter. Note that   must be specified on the command line in  order to use a " " construct in this utility.
 * 1) ./imsimta test -expression -mm -block -message=msg.txt
 * 1) ./imsimta test -expression -mm -block -message=msg.txt -from=\"\"
 * 1) ./imsimta test -expression -mm -statement=3 -block -message=msg.txt"

See also:
 * Sieve filters
 * Recipe language
 * restricted.cnf file
 * Recipe language
 * Recipe language
 * Sieve hold extension
 * Sieve capture extension
 * Mapping entry templates
 * Sieve envelope extension
 * return_address MTA Option
 * max_sieve_list_size MTA Option
 * max_sieve_match_iterations MTA Option
 * Sieve environment extension
 * Sieve hierarchy
 * Sieve loop extension
 * MTA command line utilities