Add Asterisk Extension Language support (AEL) from Astricon talk
[asterisk/asterisk.git] / doc / README.ael
1 The Asterisk Extension Language
2 ===================================
3
4 Over time, people have been pushing to add features to extensions.conf to make
5 it more like a programming language.  AEL is intended to provide an actual
6 programming language that can be used to write an Asterisk dialplan.
7
8
9 Contexts
10 -------------------------
11 Contexts in AEL represent a set of extensions in the same way that they do
12 in extensions.conf.
13
14 context default {
15
16 };
17
18
19 Extensions
20 -------------------------
21 To specify an extension in a context, the following syntax is used.  If more
22 than one application is be called in an extension, they can be listed in order
23 inside of a block.
24
25 context default {
26         1234 => Playback(tt-monkeys);
27         8000 => {
28                 NoOp(one);
29                 NoOp(two);
30                 NoOp(three);
31         };
32         _5XXX => NoOp(it's a pattern!);
33 };
34
35
36 Includes
37 -------------------------
38 Contexts can be included in other contexts.  All included contexts are listed
39 within a single block.
40
41 context default {
42         includes {
43                 local;
44                 longdistance;
45                 international;
46         };
47 };
48
49
50 Dialplan Switches
51 -------------------------
52 Switches are listed in their own block within a context.
53
54 context default {
55         switches {
56                 DUNDi/e164;
57                 IAX2/box5;
58         };
59         eswitches {
60                 IAX2/context@${CURSERVER};
61         };
62 };
63
64
65 Ignorepat
66 -------------------------
67 ignorepat can be used to instruct channel drivers to not cancel dialtone upon
68 receipt of a particular pattern.  The most commonly used example is '9'.
69
70 context outgoing {
71         ignorepat => 9;
72 };
73
74
75 Variables
76 -------------------------
77 Variables in Asterisk do not have a type, so to define a variable, it just has
78 to be specified with a value.
79
80 Global variables are set in their own block.
81
82 globals {
83         CONSOLE=Console/dsp;
84         TRUNK=Zap/g2;
85 };
86
87 Variables can be set within extensions as well.
88
89 context foo {
90         555 => {
91                 x=5;
92                 y=blah;
93                 NoOp(x is ${x} and y is ${y} !);
94         };
95 };
96
97 Writing to a dialplan function is treated the same as writing to a variable.
98
99 context blah {
100         s => {
101                 CALLERID(name)=ChickenMan;
102                 NoOp(My name is ${CALLERID(name)} !);
103         };
104 }; 
105
106
107 Loops
108 -------------------------
109 AEL has implementations of 'for' and 'while' loops.
110
111 context loops {
112         1 => {
113                 for (x=0; ${x} < 3; x=${x} + 1) {
114                         Verbose(x is ${x} !);
115                 };
116         };
117         2 => {
118                 y=10;
119                 while (${y} >= 0) {
120                         Verbose(y is ${y} !);
121                         y=${y}-1;
122                 };
123         };
124 };
125
126
127 Conditionals
128 -------------------------
129 AEL supports if and switch statements.  Note that if you have an else 
130 clause, you MUST place braces around the non-else portion of the if 
131 statement.
132
133 context conditional {
134         _8XXX => {
135                 Dial(SIP/${EXTEN});
136                 if (${DIALSTATUS} = "BUSY") {
137                         Voicemail(${EXTEN}|b);
138                 } else
139                         Voicemail(${EXTEN}|u);
140         };
141         _777X => {
142                 switch (${EXTEN}) {
143                         case 7771:
144                                 NoOp(You called 7771!);
145                                 break;
146                         case 7772:
147                                 NoOp(You called 7772!);
148                                 break;
149                         case 7773:
150                                 NoOp(You called 7773!);
151                                 // fall through
152                         default:
153                                 NoOp(In the default clause!);
154                 };
155         };
156 };
157
158
159 goto and labels
160 -------------------------
161 This is an example of how to do a goto in AEL.
162
163 context gotoexample {
164         s => {
165 begin:
166                 NoOp(Infinite Loop!  yay!);
167                 Wait(1);
168                 goto begin;
169         };
170 };
171
172
173 Macros
174 -------------------------
175 A macro is defined in its own block like this.  The arguments to the macro are
176 specified with the name of the macro.  They are then reffered to by that same
177 name.  A catch block can be specified to catch special extensions.
178
179 macro std-exten( ext , dev ) {
180         Dial(${ext}/${dev},20);
181         switch(${DIALSTATUS) {
182         case BUSY:
183                 Voicemail(b${ext});
184                 break;
185         default:
186                 Voicemail(u${ext});
187         };
188         catch a {
189                 VoiceMailMain(${ext});
190                 return;
191         };
192 };
193
194 A macro is then called by preceeding the macro name with an ampersand.
195
196 context example {
197         _5XXX => &std-exten(${EXTEN});
198 };
199
200
201 Examples
202 ------------------------
203
204 context demo {
205         s => {
206                 Wait(1);
207                 Answer();
208                 TIMEOUT(digit)=5;
209                 TIMEOUT(response)=10;
210 restart:
211                 Background(demo-congrats);
212 instructions:
213                 for (x=0; ${x} < 3; x=${x} + 1) {
214                         Background(demo-instruct);
215                         WaitExten();
216                 };
217         };
218         2 => {
219                 Background(demo-moreinfo);
220                 goto instructions;
221         };
222         3 => {
223                 LANGUAGE()=fr;
224                 goto restart;
225         };
226         500 => {
227                 Playback(demo-abouttotry);
228                 exten => 500,n,Dial(IAX2/guest@misery.digium.com)
229                 Playback(demo-nogo);
230                 goto instructions;
231         };
232         600 => {
233                 Playback(demo-echotest);
234                 Echo();
235                 Playback(demo-echodone);
236                 goto instructions;
237         };
238         # => {
239 hangup:
240                 Playback(demo-thanks);
241                 Hangup();
242         };
243         t => goto hangup;
244         i => Playback(invalid);
245 };
246