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