doc/README.variables

   1 EXTENSION LOGIC :
   2
   3 There are two levels of parameter evaluation done in asterisk in
   4 extensions.conf.
   5 The first, and most frequently used, is the substitution of variable
   6 references with their values.
   7
   8 Then there are the evaluations done in $[ .. ]. This will be
   9 discussed below.
  10
  11 ___________________________
  12 PARAMETER QUOTING:
  13 ---------------------------
  14
  15 exten => s,5,BackGround,blabla
  16
  17 The parameter (blabla) can be quoted ("blabla"). In this case, a
  18 comma does not terminate the field. However, the double quotes
  19 will be passed down to the Background command, in this example.
  20
  21 Also, characters special to variable substitution, expression evaluation, etc
  22 (see below), can be quoted. For example, to literally use a $ on the
  23 string "$1231", quote it with a preceding \. Special characters that must
  24 be quoted to be used, are [ ] $ " \. (to write \ itself, use \\).
  25
  26 These Double quotes and escapes are evaluated at the level of the
  27 asterisk config file parser.
  28
  29 Double quotes can also be used inside expressions, as discussed below.
  30
  31
  32 ___________________________
  33 VARIABLES:
  34 ---------------------------
  35
  36 Parameter strings can include variables. Variable names are arbitrary strings.
  37 They are stored in the respective channel structure.
  38
  39 To set a variable to a particular value, do :
  40
  41 ;exten => 1,2,SetVar,varname=value
  42
  43 You can substitute the value of a variable everywhere using ${variablename}.
  44 For example, to stringwise append $lala to $blabla and store result in $koko,
  45 do:
  46
  47 ;exten => 1,2,SetVar,koko=${blabla}${lala}
  48
  49 There are also the following special variables:
  50
  51 ${CALLERID}     Caller ID
  52 ${CALLERIDNAME} Caller ID Name only
  53 ${CALLERIDNUM}  Caller ID Number only
  54 ${EXTEN}        Current extension
  55 ${CONTEXT}      Current context
  56 ${PRIORITY}     Current priority
  57 ${CHANNEL}      Current channel name
  58 ${ENV(VAR)}     Environmental variable VAR
  59 ${LEN(VAR)}     String length of VAR (integer)
  60 ${EPOCH}        Current unix style epoch
  61 ${DATETIME}     Current date time in the format: YYYY-MM-DD_HH:MM:SS
  62 ${TIMESTAMP}    Current date time in the format: YYYYMMDD-HHMMSS
  63 ${UNIQUEID}     Current call unique identifier
  64 ${DNID}         Dialed Number Identifier
  65 ${RDNIS}        Redirected Dial Number ID Service
  66 ${HANGUPCAUSE}  Asterisk hangup cause
  67 ${ACCOUNTCODE}  Account code (if specified)
  68 ${LANGUAGE}     Current language
  69 ${SIPDOMAIN}    SIP destination domain of an inbound call (if appropriate)
  70 ${SIPUSERAGENT} SIP user agent
  71 ${SIPCALLID}    SIP Call-ID: header verbatim (for logging or CDR matching)
  72 ${MEETMESECS}   Number of seconds a user participated in a MeetMe conference
  73
  74 There are two reference modes - reference by value and reference by name.
  75 To refer to a variable with its name (as an argument to a function that
  76 requires a variable), just write the name. To refer to the variable's value,
  77 enclose it inside ${}. For example, SetVar takes as the first argument
  78 (before the =) a variable name, so:
  79
  80 ;exten => 1,2,SetVar,koko=lala
  81 ;exten => 1,3,SetVar,${koko}=blabla
  82
  83 stores to the variable "koko" the value "lala" and to variable "lala" the
  84 value "blabla".
  85
  86 In fact, everything contained ${here} is just replaced with the value of
  87 the variable "here".
  88
  89 ___________________________
  90 EXPRESSIONS:
  91 ---------------------------
  92
  93 Everything contained inside a bracket pair prefixed by a $ (like $[this]) is
  94 considered as an expression and it is evaluated. Evaluation works similar to
  95 (but is done on a later stage than) variable substitution: the expression
  96 (including the square brackets) is replaced by the result of the expression
  97 evaluation. The arguments and operands of the expression MUST BE separated
  98 by at least one space.
  99
 100
 101 For example, after the sequence:
 102
 103 exten => 1,1,SetVar,"lala=$[1 + 2]";
 104 exten => 1,2,SetVar,"koko=$[2 * ${lala}]";
 105
 106 the value of variable koko is "6".
 107
 108 And, further:
 109
 110 exten => 1,1,SetVar,"lala=$[1+2]";
 111
 112 will not work as you might have expected. Since all the chars in the single
 113 token "1+2" are not numbers, it will be evaluated as the string "1+2". Again,
 114 please do not forget, that this is a very simple parsing engine, and it
 115 uses a space (at least one), to separate "tokens".
 116
 117 and, further:
 118
 119 exten => 1,1,SetVar,"lala=$[  1 +    2   ]";
 120
 121 will parse as intended. Extra spaces are ignored.
 122
 123 ___________________________
 124 SPACES INSIDE VARIABLE
 125 ---------------------------
 126 If the variable being evaluated contains spaces, there can be problems.
 127
 128 For these cases, double quotes around text that may contain spaces
 129 will force the surrounded text to be evaluated as a single token.
 130 The double quotes will be counted as part of that lexical token.
 131
 132 As an example:
 133
 134 exten => s,6,GotoIf($[ "${CALLERIDNAME}" : "Privacy Manager" ]?callerid-liar|s|1:s|7)
 135
 136 The variable CALLERIDNAME could evaluate to "DELOREAN MOTORS" (with a space)
 137 but the above will evaluate to:
 138
 139 "DELOREAN MOTORS" : "Privacy Manager"
 140
 141 and will evaluate to 0.
 142
 143 The above without double quotes would have evaluated to:
 144
 145 DELOREAN MOTORS : Privacy Manager
 146
 147 and will result in syntax errors, because token DELOREAN is immediately
 148 followed by token MOTORS and the expression parser will not know how to
 149 evaluate this expression.
 150
 151 _____________________
 152 OPERATORS
 153 ---------------------
 154 Operators are listed below in order of increasing precedence.  Operators
 155 with equal precedence are grouped within { } symbols.
 156
 157      expr1 | expr2
 158              Return the evaluation of expr1 if it is neither an empty string
 159              nor zero; otherwise, returns the evaluation of expr2.
 160
 161      expr1 & expr2
 162              Return the evaluation of expr1 if neither expression evaluates to
 163              an empty string or zero; otherwise, returns zero.
 164
 165      expr1 {=, >, >=, <, <=, !=} expr2
 166              Return the results of integer comparison if both arguments are
 167              integers; otherwise, returns the results of string comparison
 168              using the locale-specific collation sequence.  The result of each
 169              comparison is 1 if the specified relation is true, or 0 if the
 170              relation is false.
 171
 172      expr1 {+, -} expr2
 173              Return the results of addition or subtraction of integer-valued
 174              arguments.
 175
 176      expr1 {*, /, %} expr2
 177              Return the results of multiplication, integer division, or
 178              remainder of integer-valued arguments.
 179
 180      expr1 : expr2
 181              The `:' operator matches expr1 against expr2, which must be a
 182              regular expression.  The regular expression is anchored to the
 183              beginning of  the string with an implicit `^'.
 184
 185              If the match succeeds and the pattern contains at least one regu-
 186              lar expression subexpression `\(...\)', the string correspond-
 187              ing to `\1' is returned; otherwise the matching operator
 188              returns the number of characters matched.  If the match fails and
 189              the pattern contains a regular expression subexpression the null
 190              string is returned; otherwise 0.
 191
 192 Parentheses are used for grouping in the usual manner.
 193
 194 The parser must be parsed with bison (bison is REQUIRED - yacc cannot
 195 produce pure parsers, which are reentrant)
 196
 197 ___________________________
 198 CONDITIONALS
 199 ---------------------------
 200
 201 There is one conditional operator - the conditional goto :
 202
 203 ;exten => 1,2,gotoif,condition?label1:label2
 204
 205 If condition is true go to label1, else go to label2. Labels are interpreted
 206 exactly as in the normal goto command.
 207
 208 "condition" is just a string. If the string is empty or "0", the condition
 209 is considered to be false, if it's anything else, the condition is true.
 210 This is designed to be used together with the expression syntax described
 211 above, eg :
 212
 213 exten => 1,2,gotoif,$[${CALLERID} = 123456]?2|1:3|1
 214
 215
 216 Example of use :
 217
 218 exten => s,2,SetVar,"vara=1"
 219 exten => s,3,SetVar,"varb=$[${vara} + 2]"
 220 exten => s,4,SetVar,"varc=$[${varb} * 2]"
 221 exten => s,5,GotoIf,"$[${varc} = 6]?99|1:s|6";
 222
 223 ___________________________
 224 PARSE ERRORS
 225 ---------------------------
 226
 227 Syntax errors are now output with 3 lines.
 228
 229 If the extensions.conf file contains a line like:
 230
 231 exten => s,6,GotoIf($[ "${CALLERIDNUM}"  = "3071234567" & "${CALLERIDNAME}" : "Privacy Manager" ]?callerid-liar|s|1:s|7)
 232
 233 You may see an error in /var/log/asterisk/messages like this:
 234
 235 May  3 15:58:53 WARNING[1234455344]: ast_yyerror(): syntax error: parse error; Input:
 236  "3072312154"  : "3071234567" & & "Steves Extension" : "Privacy Manager"
 237  ^^^^^^^^^^^^^^^^^^^^^^^^^^^
 238                                   ^
 239
 240 The first line shows the string passed to the expression parser. This
 241 string is the result of the variable replacements, etc. This way, you
 242 can see the actual string that went into the parser.
 243
 244 The second line usually shows a string of '^' chars, that show what's
 245 been legally parsed so far.
 246
 247 And the third line shows where the parser was (lookahead token lexing,
 248 etc), when the parse hit the rocks. A single '^' here. The error is
 249 going to be somewhere between the last '^' on the second line, and the
 250 '^' on the third line. That's right, in the example above, there are two
 251 '&' chars, separated by a space, and this is a definite no-no!
 252
 253
 254 ___________________________
 255 NULL STRINGS
 256 ---------------------------
 257
 258 Testing to see if a string is null can be done in one of two different ways:
 259
 260 exten => _XX.,1,GotoIf($["${calledid}" != ""]?3)
 261
 262 exten => _XX.,1,GotoIf($[foo${calledid} != foo]?3)
 263
 264
 265 The second example above is the way suggested by the WIKI. It will
 266 work as long as there are no spaces in the evaluated value.
 267
 268 The first way should work in all cases, and indeed, might now
 269 be the safest way to handle this situation.
 270
 271 ___________________________
 272 WARNING
 273 ---------------------------
 274
 275 If you need to do complicated things with strings, asterisk expressions
 276 is most likely NOT the best way to go about it. AGI scripts are an
 277 excellent option to this need, and make available the full power of
 278 whatever language you desire, be it Perl, C, C++, Cobol, RPG, Java,
 279 Snobol, PL/I, Scheme, Common Lisp, Shell scripts, Tcl, Forth, Modula,
 280 Pascal, APL, assembler, etc.
 281