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