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