6.1. Expressions and Variable Manipulation

Before we dive further into dialplans, we need to introduce you to a few tricks that will greatly add to the power you can exercise with your dialplan. These constructs add incredible intelligence to your dialplan, by enabling it to make decisions based on all sorts of different criteria. Put on your thinking cap, and let's get started.

6.1.1. Basic Expressions

Expressions are combinations of variables, operators, and values that you put together to get a result. An expression can test values, alter strings, or perform mathematical calculations. Let's say we have a variable called COUNT. In plain English, two expressions using that variable might be "COUNT plus 1" and "COUNT divided by 2." Each of these expressions has a particular result or value, depending on the value of the given variable.

In Asterisk, expressions always begin with a dollar sign and an opening square bracket and end with a closing square bracket, as shown below:

    $[expression]

Thus, we would write the above two examples like this:

    $[${COUNT} + 1]
    $[${COUNT} / 2]

When Asterisk encounters an expression in a dialplan, it replaces the entire expression with the resulting value. It is important to note that this takes place after variable substitution. To demonstrate, let's look at the following code:^[*]

^[*] Remember that when you reference a variable, you can call it by its name, but when you refer to a variable's value, you have to use the dollar sign and brackets around the variable name.

    exten => 321,1,Set(COUNT=3)
    exten => 321,2,Set(NEWCOUNT=$[${COUNT} + 1])
    exten => 321,3,SayNumber(${NEWCOUNT})

In the first priority, we assign the value of 3 to the variable named COUNT.

In the second priority, only one applicationSet( )is involved, but three things actually happen:

The third priority simply invokes the SayNumber( ) application, which speaks the current value of the variable ${NEWCOUNT} (set to the value 4 in priority two).

Try it out in your own dialplan.

6.1.2. Operators

When you create an Asterisk dialplan, you're really writing code in a specialized scripting language. This means that the Asterisk dialplanlike any programming languagerecognizes symbols called operators that allow you to manipulate variables. Let's look at the types of operators that are available in Asterisk:

Boolean operators

These operators evaluate the "truth" of a statement. In computing terms, that essentially refers to whether the statement is something or nothing (non-zero or zero, true or false, on or off, and so on). The Boolean operators are:

expr1 | expr2

This operator (called the "or" operator, or "pipe") returns the evaluation of expr1 if it is true (neither an empty string nor zero). Otherwise, it returns the evaluation of expr2.

expr1 & expr2

This operator (called "and") returns the evaluation of expr1 if both expressions are true (i.e., neither expression evaluates to an empty string or zero). Otherwise, it returns zero.

expr1 {=, >, >=, <, <=, !=} expr2

These operators return the results of an integer comparison if both arguments are integers; otherwise, they return the results of a string comparison. The result of each comparison is 1 if the specified relation is true, or 0 if the relation is false. (If you are doing string comparisons, they will be done in a manner that's consistent with the current locale settings of your operating system.)

Mathematical operators

Want to perform a calculation? You'll want one of these:

expr1 {+, -} expr2

These operators return the results of the addition or subtraction of integer-valued arguments.

expr1 {*, /, %} expr2

These return, respectively, the results of the multiplication, integer division, or remainder of integer-valued arguments.

Regular expression operator

You can also use the regular expression operator in Asterisk:

expr1 : expr2

This operator matches expr1 against expr2, where expr2 must be a regular expression.^[*] The regular expression is anchored to the beginning of the string with an implicit ^.^[]

^[*] For more on regular expressions, grab a copy of the ultimate reference, Jeffrey Friedl's Mastering Regular Expressions (O'Reilly; http://www.oreilly.com/catalog/regex2/) or visit http://www.regular-expressions.info.

^[] If you don't know what a ^ has to do with regular expressions, you simply must obtain a copy of Mastering Regular Expressions. It will change your life!

If the match succeeds and the pattern contains at least one regular expression subexpression\(...\)the string corresponding to \1 is returned; otherwise, the matching operator returns the number of characters matched. If the match fails and the pattern contains a regular expression subexpression, the null string is returned; otherwise, 0 is returned.

The Asterisk parser is quite simple, so it requires that you put at least one space between the operator and any other values. Consequently, the following may not work as expected:

    exten => 123,1,Set(TEST=$[2+1])

This would assign the variable TEST the string "2+1", instead of the value 3. Instead, put spaces around the operator, like this:

    exten => 234,1,Set(TEST=$[2 + 1])

To concatenate text onto the beginning or end of a variable, simply place them together in an expression, like this:

    exten => 234,1,Set(NEWTEST=$[blah${TEST}])