Difference between revisions of "Test -expression utility"

From Messaging Server Technical Reference Wiki
Jump to: navigation, search
m (Bulk update)
m (Bulk update)
 
Line 194: Line 194:
 
| |  Encodes the string ''<tt>s</tt>'' into the specified encoding ''<tt>:e</tt>''. The ''<tt>:e</tt>'' nonpositional parameter must be one of :base64, :base85, :hex, :idn, :param, :quotedprintable, or :url. The default is :hex.     
 
| |  Encodes the string ''<tt>s</tt>'' into the specified encoding ''<tt>:e</tt>''. The ''<tt>:e</tt>'' nonpositional parameter must be one of :base64, :base85, :hex, :idn, :param, :quotedprintable, or :url. The default is :hex.     
 
|- style="background:blanchedalmond"
 
|- style="background:blanchedalmond"
| | '''<tt>find(</tt>'''''<tt>s1</tt>'''''<tt>,</tt>'''''<tt>s2</tt>'''''<tt>,</tt>'''''<tt>i</tt>'''''<tt>,</tt>'''''<tt>j</tt>'''''<tt>)</tt>'''
+
| | '''<tt>find(</tt>'''''<tt>s1</tt>'''''<tt>,</tt>'''''<tt>s2</tt>&#x5b;'''''<tt>,</tt>'''''<tt>i</tt>'''''<tt>,</tt>'''''<tt>j</tt>''''&#x5d;'''''<tt>)</tt>'''
| |  Returns the position in ''<tt>s2</tt>'' of the first occurence of ''<tt>s1</tt>'' in ''<tt>s2</tt>''<tt>&#x5b;</tt>''<tt>i</tt>'':''<tt>j</tt>''<tt>&#x5d;</tt>.     
+
| |  Returns the position of the first occurence of ''<tt>s1</tt>'' in ''<tt>s2</tt>''<tt>&#x5b;</tt>''<tt>i</tt>'':''<tt>j</tt>''<tt>&#x5d;</tt>. The entire string is searched if <tt>i</tt> and <tt>j</tt> are omitted.     
 
|- style="background:blanchedalmond"
 
|- style="background:blanchedalmond"
| | '''<tt>find(</tt>'''''<tt>s</tt>'''''<tt>,</tt>'''''<tt>l</tt>'''''<tt>,</tt>'''''<tt>i</tt>'''''<tt>,</tt>'''''<tt>j</tt>'''''<tt>)</tt>'''
+
| | '''<tt>find(</tt>'''''<tt>s</tt>'''''<tt>,</tt>'''''<tt>l</tt>&#x5b;'''''<tt>,</tt>'''''<tt>i</tt>'''''<tt>,</tt>'''''<tt>j</tt>''''&#x5d;'''''<tt>)</tt>'''
| | Returns the position in ''<tt>l</tt>''  of the first list element from ''<tt>l</tt>''<tt>&#x5b;</tt>''<tt>i</tt>''<tt>:</tt>''<tt>j</tt>''<tt>&#x5d;</tt>  that matches ''<tt>s</tt>''.     
+
| |       Returns the position of the first list element from ''<tt>l</tt>''<tt>&#x5b;</tt>''<tt>i</tt>''<tt>:</tt>''<tt>j</tt>''<tt>&#x5d;</tt>  that matches ''<tt>s</tt>''. The entire list is searched if <tt>i</tt> and <tt>j</tt> are omitted.     
 
|- style="background:blanchedalmond"
 
|- style="background:blanchedalmond"
 
| | '''<tt>genid</tt>'''
 
| | '''<tt>genid</tt>'''

Latest revision as of 00:40, 25 March 2020

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

Syntax

  imsimta test -expression

imsimta test -expression Command Switches
Switch Default
-statement=n -statement=1
-multiple -multiple
-block -noblock
-symbols -nosymbols
-uav=n -uav=1
-input=filename None
-output=filename None
-parseonly None
-string=n -string=65535
-iterations=n -⁠iterations=max_sieve_match_iterations
-list=n -⁠list=max_sieve_list_size
-debug[=n] -debug=1
-mm See text
-xc See text
-message=filename None
-required -required
-from=address -from="postmaster-address"
-to=recipient-address -noto
-envid=id -noenvid
-system -nosystem
-mtpriority=n -mtpriority=0
-sender=sender -nosender
-username=username -nousername
-utf8 -noutf8
-source=source-channel-name -source=l
-rsecret=recall-secret -norsecret

Restrictions

Must be superuser or the MTA user (the user option in restricted.cnf, or prior to MS 7.0.5, the imta_user MTA Tailor option value), or be in the group specified by the group option in restricted.cnf (prior to MS 7.0.5, be in the group specified by the imta_world_group MTA Tailor option value), in order to have any hold or capture actions applied by a Sieve filter be shown in the utility's output.

Prompts

imsimta test -exression Prompts
Prompt Value
Expression: expression

Description

Test an expression, such as a Sieve filter or a configuration recipe. test -expression -⁠mm tests message enqueue functions, such as Sieve filters (with the -message switch). test -⁠expression -xc 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 -parseonly 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 -⁠symbols 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'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 'fileinto "folder";'. (See Variable indices under Recipe language for further discussion of indexing into strings and lists.)

Without the -mm switch, test -expression 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 imsimta test -expression 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, "if..." 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.

Symbol table functions
Function Description
abs(i) Return the absolute value of i.
allof(i1[,i2...]) Returns a nonzero value if all of i1, i2, ... are nonzero; returns 0 otherwise.
any(s1,s2) Return 2 if any character in s1 appears as the first character of s2; return 0 otherwise.
anyof(i1[,i2...]) Returns a nonzero value if any of i1, i2, ... are nonzero, returns 0 if all are zero.
bal(c1,c2,c3,s) Scan s looking for an occurence of a character in c1 that is balanced with respect to c2 and c3. Returns the position of the first balanced c3 character in s if one is found, length(s)+1 if no c3 character is found but the string as a whole is balanced, or 0 if the string isn't balanced.
center(s1,n,s2) Return a string that has string s1's last character at position n, padding on the left with the character or characters from string s2. s2 may be omitted, in which case space characters are used to pad out the string.
check8(s) Return 1 if string s contains any eight bit data; return 0 otherwise.
check8(s,n) If n is 0, it is ignored and the function returns 0 or 1 according to whether the string s contains any eight bit data. If n is any positive integer, then return the string s with any eight bit characters replaced by the question mark character, "?".
chr(i1[,i2...]) Returns a string containing successive characters with decimal values i1,i2, ...
datetime Return the current date and time, in RFC 822/RFC 1123 date-time string format, e.g., "Fri, 10 Oct 2008 15:40:02 -0700 (PDT)"
decode [:e] s Decodes the string s from the specified encoding :e. The :e nonpositional parameter must be one of :base64, :base85, :hex, :idn, or :quotedprintable. The default is :hex.
defined(s) Returns 1 if s is defined as a variable; return 0 otherwise.
encode [:e] s Encodes the string s into the specified encoding :e. The :e nonpositional parameter must be one of :base64, :base85, :hex, :idn, :param, :quotedprintable, or :url. The default is :hex.
find(s1,s2[,i,j']) Returns the position of the first occurence of s1 in s2[i:j]. The entire string is searched if i and j are omitted.
find(s,l[,i,j']) Returns the position of the first list element from l[i:j] that matches s. The entire list is searched if i and j are omitted.
genid Return a unique id string, such as that used for generating Message-id's or message queue file names.
integer(e) Converts e to an integer. If e is already an integer it is returned unchanged; if e is a string it is read as a sequence of ASCII digits. If e is a list it must contain one element and is treated in the same way a string would be.
lcase(e) Converts any upper case characters in e to lower case. If e is a number it is converted to a string.
left(s1,i[,s2]) Returns leftmost i characters of s1. If i is greater than length(s1) the result is padded with s2. As much of s2 as is necessary will be used; if s2 is too short it will be used multiple times. s2 defaults to a space if it is omitted.
left(l1,i[,l2]) Returns leftmost i elements of l1. If i is greater than length(l1) the result is padded with l2. As much of l2 as is necessary will be used; if l2 is too short it will be used multiple times. l2 defaults to one empty list element if it is omitted.
length(s) Returns the number of 8-bit characters in the string s.
length(l) Returns the number of elements in the list l.
list(s,n) Returns a list n elements long with each element equal to s.
list(l,n) Returns a list consisting of n copies of l.
map(s1,s2,s3) Returns a string obtained by mapping characters of s1 that occur in s2 into corresponding characters in s3. Characters that don't appear in s2 are unchanged.
max(i,j[,...]) Returns the largest element in a set of integers.
match(r,s) Returns 1 (true) if the regular expression r matches a substring of string s, 0 (false) otherwise. Note that the pattern r may be prefixed with "^" (match beginning of line) and suffixed with "$" (match end of line) to require a full string match. The regular expression vocabulary is compatible with that of the TCL/TK scripting language.
max(s1,s2[,...]) Returns the largest element in a set of strings.
min(i,j[,...]) Returns the smallest element in a set of integers.
min(s1,s2[,...]) Returns the smallest element in a set of strings.
repl(s,j) Returns a string consisting of j concatenations of s.
repl(l,j) Returns a list consisting of j concatenations of l.
reverse(s) Reverses all the characters in s and returns the result.
reverse(l) Reverses all the elements in l and returns the result.
right(s1,i[,s2]) Returns rightmost i characters of s1. If i is greater than length(s1) the result is padded with s2. As much of s2 as is necessary will be used; if s2 is too short it will be used multiple times. s2 defaults to a space if it is omitted.
right(l1,i[,l2]) Returns rightmost i elements of l1. If i is greater than length(l1) the result is padded with l2. As much of l2 as is necessary will be used; if l2 is too short it will be used multiple times. l2 defaults to one empty list element if it is omitted.
sign(i) Returns -1 if i < 0, 0 if i = 0, +1 if i > 0.
sort(l1[,i[,l2]]) Sorts the elements of l1 to be in ascending order if i <> 0 and descending order if i = 0. i defaults to 1 if it is omitted. If l2 is present its elements are shifted in the same way as elements in l1 are shifted.
split(s[,c[,i]]) Produces a list of elements consisting of pieces of s delineated by characters in c. If omitted c defaults to a comma. If i is 0 or 1, zero length elements are preserved; if i is 2, they are not. If omitted i defaults to 1.
split(l[,c[,i]]) Produces a list of elements consisting of pieces of elements of l delineated by characters in c. If omitted c defaults to a comma. If i is 0, boundaries between the original elements aren't preserved and zero length elements can be output; if i is 1, boundaries are preserved and zero length elements can be output; if i is 2, boundaries aren't preserved and zero length elements are omitted. If omitted i defaults to 1.
string(e) Converts e to a string. If e is already a string it is returned unchanged. If e is an integer it is converted to a string. If e is a list, the string that results from concatenating the elements of e is returned.
string(l,s) Converts the list l to a string, inserting the string s between each pair of elements of l. So for instance string(["a","cd","e"],"01") would return the string "a01cd01e".
string(i[,j[,k]]) (New in MS 6.3 are the optional second and third arguments.) Converts the integer i to a string, optionally padding with zeros (on the left) so that the length of the string is j, and optionally outputting the result in the radix specified by k. So for instance string(15,8,2) returns 00001111.
trim(s[,c]) Returns s with any trailing characters found in c removed. c defaults to space and tab if omitted.
trim(l[,c]) Returns l with any trailing characters found in c removed from each element. c defaults to space and tab if omitted.
type(e) Returns "integer" if e evaluates to an integer, "string" if e evaluates to a string, and "list" if e evaluates to a list.
ucase(e) Converts any lower case characters in e to upper case. If e is a number it is converted to a string.
Directory function Description
gettag(x) If x evalutes to a string, returns the tag character for that string. If x evaluates to a list, returns the default and per-element tags as a string. An error will be returned if x evalutes to anything other than a string or list.
settag(x,y) Sets the tag or tags of x to y. x may be either a string or a list. If x is a string, then y must be a one character string. If x is a list, then y must be a string of length length(x)+1 and the first character of y must be a space.

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

By default, each line of expression is evaluated independently (separately). The -block 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, -block is useful when evaluating a multi-line Sieve filter.

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

Switches

-block, -noblock (default)

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

-debug[=n], -nodebug (default)

The test -expression utility is capable of outputting additional, detailed information about the internal steps of its operation. The -debug switch enables this output. Specifying -⁠debug is equivalent to specifying -debug=1; greater amounts of debug information can be requested by specifying -debug=n for values of n up to 10.

Note that a debug level of 2 or more enables output of strings specified via Sieve "debug" actions. Note that a debug level of 3 or more enables output (via "mmc_output_line(x) header line:" 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 "mmc_output_line(x) internal body line:" 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 "mmc_output_line(x) external body line:" debug output lines). -⁠debug=1 is the default.

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

-envid=id, -noenvid (default)

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

-from=return-address, -to=recipient-address, -⁠noto (default)

(-from new in MS 6.2; -to and -noto new in MS 6.3) -from and -to are only available when -mm and -message are specified. -from 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 return_address MTA option).

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

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

-input=filename

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

-iterations=n

The -iterations 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 max_sieve_match_iterations MTA option. (Note that the default value of max_sieve_match_iterations is 1,000,000,000.)

-list=n

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

-message=filename

The -message switch may only be used when the -mm 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's queue area (which contains additional, envelope information beyond the basic RFC 822 message itself).

-mm, -xc

The -mm switch means to test using the MTA's normal enqueue code. The -xc switch (new in MS 7.5) means to test recipe language syntax, operating on a Unified Configuration. -mm and -⁠xc may not be specified together.

-mtpriority=n, -nomtpriority (default)

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

-multiple (default), -nomultiple

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

-output=filename

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

-required (default), -norequired

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


require list-of-all-possible-extensions;

-rsecret=recall-secret, -norsecret (default)

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

-sender=sender-address, -nosender (default)

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

-source=source-channel-name, -nosource

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

-statement=n

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.

Statement parsing flags
Bit(s) Value(s) Usage
0 1 Allow statements
1 2 Allow loops, including the Sieve "loop" construct
2-4 4-28 Debug level (4, 8, 12, ... 28)
6 64 Allow mapped file
7 128 Allow directives
8 256 Enforce "require" must be used only at beginning of Sieve
9 512 Allow bracketed lists
10 1024 Return evaluation error details

Bit 0 is the least significant bit.


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

-string=n

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

-symbols, -nosymbols (default)

The -symbols switch allows the use of variables and symbolic values, and operations may be performed on variables. For instance, symbolic names such as IMTA_TABLE may be used to reference the imta_table directory specification, and assignments may be made to symbolic variable names, such as a := 1, and operators such as those shown in Operators in Order of Precedence of the recipe language may be used. -nosymbols is the default.

-system, -nosystem (default)

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

-uav=n

The -uav switch controls the interpretation of unassigned variables. The default is -uav=1.

Unassigned variable interpretation
Value Usage
0 Variables must be predefined; variable creation not allowed
1 Assignment defines variable; no default value
2 Define variable upon first reference; default value ""
3 Define variable upon first reference except in modify operations; default value 0
4 (New in MS 8.0/patch to MS 7.0u5) Same as value 1 (assignment defines variable; no default value), with the difference (appropriate for Sieve usage) don't create a symbol table at parse time

-username=username, -nousername (default)

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

-utf8, -noutf8 (default)

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

Examples


# ./imsimta test -expression -mm -block -message=msg.txt
Expression: require "fileinto";
Expression: if header :contains ["Subject"] ["foo"] { fileinto "foo"; }
Expression: if header :contains ["Subject"] ["test"] { 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: [ discard ]

The above command sequence tests the result of various Sieve filter command lines on a message file, msg.txt, 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".


# ./imsimta test -expression -mm -block -message=msg.txt -from=\"\"
Expression: require ["envelope","fileinto"];
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" ' '
Filter result: [ fileinto "notifications" ]
      

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 "notifications", when that Sieve filter is presented with some message and when the envelope From is set to be empty via the -from switch.


# ./imsimta test -expression -mm -statement=3 -block -message=msg.txt"
Expression: loop { discard; exitif (true); }
Expression: CTRL/D
Dump: loop  5  discard;0  0  ;  1  exitif
Result: 1
Filter result: [ discard ]

The above example shows use of the new-in-MS-7.0.5 "loop" construct in a Sieve filter. Note that -statement=3 must be specified on the command line in order to use a "loop" construct in this utility.


See also: