Add ${LANGUAGE} channel variable (bug #1078)
[asterisk/asterisk.git] / doc / README.variables
1 GENERAL ENHANCEMENTS TO EXTENSION LOGIC : 
2
3 QUOTING: 
4
5 exten => s,5,BackGround,blabla
6
7 The parameter (blabla) can be quoted ("blabla"). In this case, a 
8 comma does not terminate the field. 
9
10 Also, characters special to variable substitution, expression evaluation, etc
11 (see below), can be quoted. For example, to literally use a $ on the 
12 string "$1231", quote it with a preceding \. Special characters that must
13 be quoted to be used, are [ ] $ " \. (to write \ itself, use \\). 
14
15 VARIABLES: 
16
17 Parameter strings can include variables. Variable names are arbitrary strings. 
18 They are stored in the respective channel structure. 
19
20 To set a variable to a particular value, do : 
21
22 ;exten => 1,2,SetVar,varname=value
23
24 You can substitute the value of a variable everywhere using ${variablename}.
25 For example, to stringwise append $lala to $blabla and store result in $koko, 
26 do: 
27
28 ;exten => 1,2,SetVar,koko=${blabla}${lala}
29
30 There are also the following special variables: 
31
32 ${CALLERID}     Caller ID
33 ${CALLERIDNAME} Caller ID Name only
34 ${CALLERIDNUM}  Caller ID Number only
35 ${EXTEN}        Current extension
36 ${CONTEXT}      Current context
37 ${PRIORITY}     Current priority
38 ${CHANNEL}      Current channel name
39 ${ENV(VAR)}     Environmental variable VAR
40 ${LEN(VAR)}     String length of VAR (integer)
41 ${EPOCH}        Current unix style epoch
42 ${DATETIME}     Current date time in the format: YYYY-MM-DD_HH:MM:SS
43 ${TIMESTAMP}    Current date time in the format: YYYYMMDD-HHMMSS
44 ${UNIQUEID}     Current call unique identifier
45 ${DNID}         Dialed Number Identifier
46 ${RDNIS}        Redirected Dial Number ID Service
47 ${HANGUPCAUSE}  Asterisk hangup cause
48 ${ACCOUNTCODE}  Account code (if specified)
49 ${LANGUAGE}     Current language
50 ${SIPDOMAIN}    SIP destination domain of an inbound call (if appropriate)
51
52 There are two reference modes - reference by value and reference by name. 
53 To refer to a variable with its name (as an argument to a function that 
54 requires a variable), just write the name. To refer to the variable's value, 
55 enclose it inside ${}. For example, SetVar takes as the first argument 
56 (before the =) a variable name, so: 
57
58 ;exten => 1,2,SetVar,koko=lala
59 ;exten => 1,3,SetVar,${koko}=blabla
60
61 stores to the variable "koko" the value "lala" and to variable "lala" the 
62 value "blabla". 
63
64 In fact, everything contained ${here} is just replaced with the value of 
65 the variable "here". 
66
67 EXPRESSIONS: 
68
69 Everything contained inside a bracket pair prefixed by a $ (like $[this]) is 
70 considered as an expression and it is evaluated. Evaluation works similar to 
71 (but is done on a later stage than) variable substitution: the expression 
72 (including the square brackets) is replaced by the result of the expression 
73 evaluation. The arguments and operands of the expression MUST BE separated 
74 with spaces (take care NOT to leave ANY spaces between opening and closing 
75 square brackets and the first and last arguments). 
76
77 For example, after the sequence: 
78
79 exten => 1,1,SetVar,"lala=$[1 + 2]";
80 exten => 1,2,SetVar,"koko=$[2 * ${lala}]";
81
82 the value of variable koko is "6".
83
84 Operators are listed below in order of increasing precedence.  Operators
85 with equal precedence are grouped within { } symbols.
86
87      expr1 | expr2
88              Return the evaluation of expr1 if it is neither an empty string
89              nor zero; otherwise, returns the evaluation of expr2.
90
91      expr1 & expr2
92              Return the evaluation of expr1 if neither expression evaluates to
93              an empty string or zero; otherwise, returns zero.
94
95      expr1 {=, >, >=, <, <=, !=} expr2
96              Return the results of integer comparison if both arguments are
97              integers; otherwise, returns the results of string comparison
98              using the locale-specific collation sequence.  The result of each
99              comparison is 1 if the specified relation is true, or 0 if the
100              relation is false.
101
102      expr1 {+, -} expr2
103              Return the results of addition or subtraction of integer-valued
104              arguments.
105
106      expr1 {*, /, %} expr2
107              Return the results of multiplication, integer division, or
108              remainder of integer-valued arguments.
109
110      expr1 : expr2
111              The `:' operator matches expr1 against expr2, which must be a
112              regular expression.  The regular expression is anchored to the
113              beginning of  the string with an implicit `^'.
114
115              If the match succeeds and the pattern contains at least one regu-
116              lar expression subexpression `\(...\)', the string correspond-
117              ing to `\1' is returned; otherwise the matching operator
118              returns the number of characters matched.  If the match fails and
119              the pattern contains a regular expression subexpression the null
120              string is returned; otherwise 0.
121
122 Parentheses are used for grouping in the usual manner.
123
124 The parser must be parsed with bison (bison is REQUIRED - yacc cannot 
125 produce pure parsers, which are reentrant) 
126
127 CONDITIONALS
128
129 There is one conditional operator - the conditional goto : 
130
131 ;exten => 1,2,gotoif,condition?label1:label2
132
133 If condition is true go to label1, else go to label2. Labels are interpreted
134 exactly as in the normal goto command.
135
136 "condition" is just a string. If the string is empty or "0", the condition
137 is considered to be false, if it's anything else, the condition is true. 
138 This is designed to be used together with the expression syntax described 
139 above, eg : 
140
141 exten => 1,2,gotoif,$[${CALLERID} = 123456]?2|1:3|1
142
143
144 Example of use : 
145
146 exten => s,2,SetVar,"vara=1"
147 exten => s,3,SetVar,"varb=$[${vara} + 2]"
148 exten => s,4,SetVar,"varc=$[${varb} * 2]"
149 exten => s,5,GotoIf,"$[${varc} = 6]?99|1:s|6";
150