Asterisk Expressions

Asterisk dialplan expressions are special expressions that can be used in the dialplan of Asterisk.

Syntax

$[expr1 operator expr2]

Page Contents

Syntax
The high-level view of variable evaluations in Asterisk:
Operator Precedence
- Conditionals
Example

See also

The high-level view of variable evaluations in Asterisk:

Since most user input will come via config files to Asterisk, some filtering and substitutions are done
as the config files are read.

Next, as the dialplan is executed, the ${ ... } variables and functions are evaluated and substituted.

And lastly, the contents of $[ .. ] expressions are evaluated and substituted.

Parameter Quoting:

exten => s,5,BackGround,blabla

The parameter (blabla) can be quoted ("blabla"). In this case, a comma does not terminate the field. However, the double quotes will be passed down to the Background command, in this example.

Also, characters special to variable substitution, expression evaluation, etc (see below), can be quoted. For example, to literally use a $ on the string "$1231", quote it with a preceding \. Special characters that must be quoted to be used, are [ ] $ " \. (to write \ itself, use \\).

These double quotes and escapes are evaluated at the level of the asterisk config file parser.

Double quotes can also be used inside expressions, as discussed below.

Spaces Inside Variable

UPDATE: with the latest Asterisk Beta (1.2.0_2) there is the following notice:

Dialplan Expressions:

The dialplan expression parser (which handles $[ ... ] constructs) has gone through a major upgrade, but has one incompatible change: spaces are no longer required around expression operators, including string comparisons. However, you can now use quoting to keep strings together for comparison. For more details, please read the doc/README.variables file, and check over your dialplan for possible problems.

If the variable being evaluated contains spaces, there can be problems.

For these cases, double quotes around text that may contain spaces will force the surrounded text to be evaluated as a single token. The double quotes will be counted as part of that lexical token.

As an example:

exten => s,6,GotoIf($[ "${CALLERIDNAME}" : "Privacy Manager" ]?callerid-liar|s|1:s|7)

The variable CALLERIDNAME could evaluate to "DELOREAN MOTORS" (with a space) but the above will evaluate to:

"DELOREAN MOTORS" : "Privacy Manager"

and will evaluate to 0.

The above without double quotes would have evaluated to:

DELOREAN MOTORS : Privacy Manager

and will result in syntax errors, because token DELOREAN is immediately followed by token MOTORS and the expression parser will not know how to evaluate this expression.

Null Strings

Testing to see if a string is null can be done in one of three different ways:

  exten => _XX.,1,GotoIf($["${calledid}" != ""]?3)

  exten => _XX.,1,GotoIf($[foo${calledid} != foo]?3)

  exten => _XX.,1,GotoIf($[${LEN(${calledid})} > 0]?3)

The second example above is the way suggested by the WIKI. It will work as long as there are no spaces in the evaluated value.

The first way should work in all cases, and indeed, might now be the safest way to handle this situation.

The third way seems the most logical. Anyone care to comment. Besides the LEN() function, there is now also ISNULL. Keep in mind such function calls need to kept inside ${...}.

Logical operators

expr1 | expr2 (Logical OR)
- If expr1 evaluates to a non-empty string or a non-zero value, returns this value ("true"). Otherwise returns the evaluation of expr2.
expr1 & expr2 (Logical AND)
!expr (Logical Unary Complement)
- If both expressions evaluate to non-empty strings or non-zero values, then returns the value of expr1 ("true"). Otherwise returns zero ("false").
- Not available in versions of Asterisk < 1.1
- Note that if a space is inserted between the '!' and the expression, an error will occur.

Comparison operators

expr1 = expr2
expr1 != expr2
expr1 < expr2
expr1 > expr2
expr1 <= expr2
expr1 >= expr2
- If both arguments are integers, returns the result of an integer comparison. Otherwise returns the result of string comparison using the locale-specific collation sequence. In either case, the result of a comparison is 1 if the specified relation is true, or 0 if the relation is false.

Arithmetic operators

expr1 + expr2
expr1 - expr2
- expr (unary negation operator)
- Returns the results of addition or subtraction of integer-valued arguments.
- Not available in versions of Asterisk < 1.1
expr1 * expr2
expr1 / expr2
expr1 % expr2
- Return the results of multiplication, integer division, or remainder of integer-valued arguments.

Regular expressions

expr1 : regexp
- The ':' operator matches expr1 against regexp, which must be a regular expression. The regular expression is anchored to the beginning of the string with an implicit '^'.
- If the match succeeds and regexp contains at least one regular expression subexpression '$...$', the string corresponding to '\1' is returned; otherwise the result returned is the number of characters matched. If the match fails and regexp contains a regular expression subexpression, the null string is returned; otherwise 0.
expr1 =~ expr2
- Exactly the same as the ':' operator, except that the match is not anchored to the beginning of the string. Pardon any similarity to seemingly similar operators in other programming languages!
- The ":" and "=~" operators share the same precedence.
- Not available in versions of Asterisk < 1.1

THE DOCUMENTATION ABOVE FOR REGULAR EXPRESSIONS IS WOEFULLY INADEQUATE. The problem seems to be that the regular expression syntax conflicts with Asterisk expression syntax. As a result, one must backslash escape anything which looks like it might be an expression operator. Also, contrary to what is suggested above, it does not seem to be necessary to backslash escape the parentheses.

Here is one example that works:

exten => stripcidtext,n,Set(regx="([0-9]+)") ; Note the quotes -- and note that parentheses are REQUIRED if you want to return the matched string
exten => stripcidtext,n,Set(cid2=$["${cid}" : ${regx}]) ; Returns numeric beginning to string

So if ${cid} contains 123foo then ${cid2} will contain just 123.

However, if ${cid} contains foo123 then ${cid2} will be empty. Supposedly you could use =~ instead of : and the string matching would work anywhere, but I don't think that works correctly (at least, I could not get =~ to work).

Here is another example:

exten => s,n,Set(enum-protocol=$["${enum-record}" : "([a-zA-Z0-9]\+)\:"])

If enum-record contains "sip:18005558355@tf.voipmich.com", then this command will set enum-protocol to "sip".

Conditional operator

expr1 ? expr2 :: expr3
- Traditional Conditional operator. If expr1 is a number that evaluates to 0 (false), expr3 is result of the this expression evaluation. Otherwise, expr2 is the result.
- If expr1 is a string, and evaluates to an empty string, or the two characters (""), then expr3 is the result. Otherwise, expr2 is the result.
- In Asterisk, all 3 exprs will be "evaluated"; if expr1 is "true", expr2 will be the result of the "evaluation" of this expression. expr3 will be the result otherwise.
- This operator has the lowest precedence.
- Not available in versions of Asterisk < 1.1
- This operator is quite buggy. The IF function is recommended instead.

Parentheses are used for grouping in the usual manner.

Operator Precedence

Parentheses: (, )
Unary operators !, -
Regular expression comparison: :, =~
Multiplicative arithmetic operators: *, /, %
Additive arithmetic operators: +, -
Comparison operators: =, !=, <, >, <=, >=
Logical operators: |, &
Conditional operator: ? :

Conditionals

There are now several conditional applications-- an example is the conditional gotoIf :

exten => 1,2,GotoIf,condition?label1:label2

If condition is true go to label1, else go to label2. Labels are interpreted exactly as in the normal goto command.

"condition" is just a string. If the string is empty or "0", the condition is considered to be false, if it's anything else, the condition is true. This is designed to be used together with the expression syntax described above, eg :

exten => 1,2,GotoIf,$[${CALLERID} = 123456]2|1:3|1

Example

After the sequence:

exten => 1,1,SetVar(lala=$[1 + 2]);
exten => 1,2,SetVar(koko=$[2 * ${lala}]);

the value of ${koko} is "6".

voip-info.org