As we begin our dive into the deeper aspects of dialplans, it is time to introduce you to a few tools that will greatly add to the power you can exercise in your dialplan. These constructs add incredible intelligence to your dialplan by enabling it to make decisions based on different criteria you define. Put on your thinking cap, and let’s get started.
Expressions are combinations of variables, operators, and
values that you string together to produce 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 here:
$[expression
]
Thus, we would write our 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[91]:
exten => 321,1,Set(COUNT=3) same => n,Set(NEWCOUNT=$[${COUNT} + 1]) same => n,SayNumber(${NEWCOUNT})
In the first priority, we assign the
value of 3
to the variable named
COUNT
.
In the second priority, only one
application—Set()
—is involved, but
three things actually happen:
Asterisk substitutes ${COUNT}
with the number 3
in the expression. The expression
effectively becomes this:
exten => 321,n,Set(NEWCOUNT=$[3 + 1])
Asterisk evaluates the
expression, adding 1
to 3
, and replaces it with its computed value
of 4
:
exten => 321,n,Set(NEWCOUNT=4)
The Set()
application assigns the value 4
to the NEWCOUNT
variable
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).
When you create an Asterisk dialplan, you’re really writing code in a specialized scripting language. This means that the Asterisk dialplan—like any programming language—recognizes symbols called operators that allow you to manipulate variables. Let’s look at the types of operators that are available in Asterisk:
These operators evaluate the “truth” of a statement. In computing terms, that essentially refers to whether the statement is something or nothing (nonzero 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 local settings of your operating system.)
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.[92] The regular expression is anchored to the
beginning of the string with an implicit ^
.[93]
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.
In Asterisk version 1.0 the parser was quite simple, so it required that you put at least one space between the operator and any other values. Consequently, the following might not have worked as expected:
exten => 123,1,Set(TEST=$[2+1])
This would have assigned the variable
TEST
to the string “2+1”, instead of
the value 3
. In order to remedy that,
we would put spaces around the operator, like so:
exten => 234,1,Set(TEST=$[2 + 1])
This is no longer necessary in current versions of Asterisk, as the expression parser has been made more forgiving in these types of scenarios. However, for readability’s sake, we still recommend including the spaces around your operators.
To concatenate text onto the beginning or end of a variable, simply place them together, like this:
exten => 234,1,Set(NEWTEST=blah${TEST})
[91] 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.
[92] For more on regular expressions, grab a copy of the ultimate reference, Jeffrey E. F. Friedl’s Mastering Regular Expressions (O’Reilly), or visit http://www.regular-expressions.info.
[93] If you don’t know what a ^
has to do with regular
expressions, you simply must read Mastering
Regular Expressions. It will change
your life!