Operators

Unary operators

The following unary operations are available. It is possible to use brackets around the operand to make it look like a function call as in the "defined" example below.

not

The not operator expects a boolean value. It will evaluate to undef if the value is undefined. If it receives an unknown value that evaluates to a non-boolean, it will result in a run-time execution error.

Example 1. Using the "not" operand

If the $Success field has a value of false, an error is logged.

if not $Success log_error("Job failed");

-

The unary negation (-) operator changes the operand into a negative. Unary negation as a sign inversion operator (multiplying a value by -1) is not supported. See also the subtraction binary operator.

Correct and incorrect usage of unary negation

$a = -1       # Valid.
$b = -(-1);   # Invalid. Translates to nothing - (-1).
$b = -$a;     # Invalid. Translates to nothing - $a.
$b = -($a);   # Invalid. Translates to nothing - ($a).

Example 2. Unary negation

This statement will always print "ten".

if 5 - (-5) == 10 log_info("ten");

defined

The defined operator will evaluate to TRUE if the operand is defined, otherwise FALSE.

Example 3. Using the Unary "defined" Operation

This statement is a no-op, it does nothing.

if defined undef log_info("never printed");

If the $EventTime field has not been set (due perhaps to failed parsing), it will be set to the current time.

if not defined($EventTime) $EventTime = now();

Binary operators

The following binary operations are available.

The operations are described with the following syntax:

LEFT_OPERAND_TYPE OPERATION RIGHT_OPERAND_TYPE = EVALUATED_VALUE_TYPE

=~

This is the regular expression match operation as in Perl. This operation takes a string and a regular expression operand and evaluates to a boolean value which will be TRUE if the regular expression matches the subject string. Captured sub-strings are accessible through numeric reference (such as $1) and the full subject string is placed into $0. Regular expression-based string substitution is supported with the s/// operator. For more details, see Regular Expressions.

string =~ regexp = boolean
regexp =~ string = boolean

Example 4. Regular expression string-matching

A log message will be generated if the $Message field matches the regular expression.

if $Message =~ /^Test message/ log_info("matched");

!~

This is the opposite of =~

The expression will evaluate to TRUE if the regular expression does not match on the subject string. It can be also written as not LEFT_OPERAND =~ RIGHT_OPERAND. The s/// substitution operator is supported.

string !~ regexp = boolean
regexp !~ string = boolean

Example 5. Negative regular expression string-matching

A log message will be generated if the $Message field does not match the regular expression.

if $Message !~ /^Test message/ log_info("didn't match");

==

This operator compares two values for equality. Comparing a defined value with an undefined results in undef.

Example 6. Equality

A log message will be generated if $SeverityValue is 1.

if $SeverityValue == 1 log_info("severity is one");

!=

This operator compares two values for inequality. Comparing a defined value with an undefined results in undef.

Example 7. Inequality

A log message will be generated if $SeverityValue is not 1.

if $SeverityValue != 1 log_info("severity is not one");

<

This operation will evaluate to TRUE if the left operand is less than the right operand, and FALSE otherwise. Comparing a defined value with an undefined results in undef.

integer < integer = boolean
datetime < datetime = boolean

Example 8. Less

A log message will be generated if $SeverityValue is less than 1.

if $SeverityValue < 1 log_info("severity is less than one");

<=

This operation will evaluate to TRUE if the left operand is less than or equal to the right operand, and FALSE otherwise. Comparing a defined value with an undefined results in undef.

integer <= integer = boolean
datetime <= datetime = boolean

Example 9. Less or Equal

A log message will be generated if $SeverityValue is less than or equal to 1.

if $SeverityValue < 1 log_info("severity is less than or equal to one");

>

This operation will evaluate to TRUE if the left operand is greater than the right operand, and FALSE otherwise. Comparing a defined value with an undefined results in undef.

integer > integer = boolean
datetime > datetime = boolean

Example 10. Greater

A log message will be generated if $SeverityValue is greater than 1.

if $SeverityValue > 1 log_info("severity is greater than one");

>=

This operation will evaluate to TRUE if the left operand is greater than or equal to the right operand, and FALSE otherwise. Comparing a defined value with an undefined results in undef.

integer >= integer = boolean
datetime >= datetime = boolean

Example 11. Greater or Equal

A log message will be generated if $SeverityValue is greater than or equal to 1.

if $SeverityValue >= 1 log_info("severity is greater than or equal to one");

and

This operation evaluates to TRUE if and only if both operands are TRUE. The operation will evaluate to undef if either operand is undefined.

boolean and boolean = boolean

Example 12. And Operation

A log message will be generated only if both $SeverityValue equals 1 and $FacilityValue equals 2.

if $SeverityValue == 1 and $FacilityValue == 2 log_info("1 and 2");

or

This operation evaluates to TRUE if either operand is TRUE. The operation will evaluate to undef if both operands are undefined.

boolean or boolean = boolean

Example 13. Or Operation

A log message will be generated if $SeverityValue is equal to either 1 or 2.

if $SeverityValue == 1 or $SeverityValue == 2 log_info("1 or 2");

+

This operation will result in an integer if both operands are integers. If either operand is a string, the result will be a string where non-string typed values are converted to strings. In this case it acts as a concatenation operator, like the dot (.) operator in Perl. Adding an undefined value to a non-string will result in undef.

integer + integer = integer
string + undef = string
undef + string = string
undef + undef = undef
string + string = string (Concatenate two strings.)
datetime + integer = datetime (Add the number of seconds in the right value to the datetime stored in the left value.)
integer + datetime = datetime (Add the number of seconds in the left value to the datetime stored in the right value.)

Example 14. Concatenation

This statement will always cause a log message to be generated.

if 1 + "a" == "1a" log_info("this will be printed");

-

Subtraction. The result is undef if either operand is undefined.

integer - integer = integer (Subtract two integers.)
datetime - datetime = integer (Subtract two datetime types. The result is the difference between to two expressed in microseconds.)
datetime - integer = datetime (Subtract the number of seconds from the datetime stored in the left value.)

If an integer immediately follows the minus operator, it is treated as unary negation.

Correct and incorrect usage of the subtraction operator

$a = 2;
$b = 1- 1;    # Valid. Translates to 1 - 1.
$b = 1--1     # Valid. Translates to 1 - (-1).
$b = 1-$a;    # Valid. Trnslates to 1 - 2.
$b = 1-1;     # Invalid. Translates to 1 (-1).
$b = 1 -1;    # Invalid. Translates to 1 (-1).

Example 15. Subtraction

This statement will always output a log message.

if 4 - 1 == 3 log_info("four minus one is three");

*

Multiply an integer with another. The result will be undef if either operand is undefined.

integer * integer = integer

Example 16. Multiplication

This statement will always cause a log message to be generated.

if 4 * 2 == 8 log_info("four times two is eight");

/

Divide an integer with another. The result will be undef if either operand is undefined. Since the result is an integer, a fractional part is lost.

integer / integer = integer

Example 17. Division

This statement will always cause a log message to be generated.

if 9 / 4 == 2 log_info("9 divided by 4 is 2");

%

The modulo operation divides an integer with another and returns the remainder. The result will be undef if either operand is undefined.

integer % integer = integer

Example 18. Modulo

This statement will always cause a log message to be generated.

if 3 % 2 == 1 log_info("three mod two is one");

IN

This operation will evaluate to TRUE if the left operand is equal to any of the expressions in the list on the right, and FALSE otherwise. Comparing a undefined value results in undef.

unknown IN unknown, unknown … = boolean

Example 19. IN

A log message will be generated if $EventID is equal to any one of the values in the list.

if $EventID IN (1000, 1001, 1004, 4001) log_info("EventID found");

NOT IN

This operation is equivalent to NOT expr IN expr_list.

unknown NOT IN unknown, unknown … = boolean

Example 20. NOT IN

A log message will be generated if $EventID is not equal to any of the values in the list.

if $EventID NOT IN (1000, 1001, 1004, 4001) log_info("EventID not in list");

Ternary operators

The ternary operator expr1 ? expr2 : expr3 evaluates to expr2 if expr1 is TRUE, otherwise to expr3. The parentheses as shown here are optional.

Example 21. Using the ternary operator

The $Important field is set to TRUE if $SeverityValue is greater than 2, or FALSE otherwise.

$Important = ( $SeverityValue > 2 ? TRUE : FALSE );