d675190ccf7a184eec17843cce908fce14da4f29
[asterisk/asterisk.git] / doc / ael.tex
1 \section{Introduction}
2
3 AEL is a specialized language intended purely for 
4 describing Asterisk dial plans.
5
6 The current version was written by Steve Murphy, and is a rewrite of 
7 the original version.
8
9 This new version further extends AEL, and
10 provides more flexible syntax, better error messages, and some missing
11 functionality.
12
13 AEL is really the merger of 4 different 'languages', or syntaxes:
14
15 \begin{itemize}
16     \item The first and most obvious is the AEL syntax itself. A BNF is
17       provided near the end of this document.
18
19     \item The second syntax is the Expression Syntax, which is normally
20      handled by Asterisk extension engine, as expressions enclosed in
21      \$[...]. The right hand side of assignments are wrapped in \$[ ... ] 
22      by AEL, and so are the if and while expressions, among others.
23
24     \item The third syntax is the Variable Reference Syntax, the stuff
25       enclosed in \${..} curly braces. It's a bit more involved than just
26       putting a variable name in there. You can include one of dozens of
27       'functions', and their arguments, and there are even some string
28       manipulation notation in there.
29
30     \item The last syntax that underlies AEL, and is not used
31       directly in AEL, is the Extension Language Syntax. The
32       extension language is what you see in extensions.conf, and AEL
33       compiles the higher level AEL language into extensions and
34       priorities, and passes them via function calls into
35       Asterisk. Embedded in this language is the Application/AGI
36       commands, of which one application call per step, or priority
37       can be made. You can think of this as a "macro assembler"
38       language, that AEL will compile into.
39 \end{itemize}
40
41 Any programmer of AEL should be familiar with it's syntax, of course,
42 as well as the Expression syntax, and the Variable syntax.
43
44
45 \section{Asterisk in a Nutshell}
46
47 Asterisk acts as a server. Devices involved in telephony, like Zapata
48 cards, or Voip phones, all indicate some context that should be
49 activated in their behalf. See the config file formats for IAX, SIP,
50 zapata.conf, etc. They all help describe a device, and they all
51 specify a context to activate when somebody picks up a phone, or a
52 call comes in from the phone company, or a voip phone, etc.
53
54 \subsection{Contexts}
55
56 Contexts are a grouping of extensions.
57
58 Contexts can also include other contexts. Think of it as a sort of
59 merge operation at runtime, whereby the included context's extensions
60 are added to the contexts making the inclusion.
61
62 \subsection{Extensions and priorities}
63
64 A Context contains zero or more Extensions. There are several
65 predefined extensions. The "s" extension is the "start" extension, and
66 when a device activates a context the "s" extension is the one that is
67 going to be run. Other extensions are the timeout "t" extension, the
68 invalid response, or "i" extension, and there's a "fax" extension. For
69 instance, a normal call will activate the "s" extension, but an
70 incoming FAX call will come into the "fax" extension, if it
71 exists. (BTW, asterisk can tell it's a fax call by the little "beep"
72 that the calling fax machine emits every so many seconds.).
73
74 Extensions contain several priorities, which are individual
75 instructions to perform. Some are as simple as setting a variable to a
76 value. Others are as complex as initiating the Voicemail application,
77 for instance. Priorities are executed in order.
78
79 When the 's" extension completes, asterisk waits until the timeout for
80 a response. If the response matches an extension's pattern in the
81 context, then control is transferred to that extension. Usually the
82 responses are tones emitted when a user presses a button on their
83 phone. For instance, a context associated with a desk phone might not
84 have any "s" extension. It just plays a dialtone until someone starts
85 hitting numbers on the keypad, gather the number, find a matching
86 extension, and begin executing it. That extension might Dial out over
87 a connected telephone line for the user, and then connect the two
88 lines together.
89
90 The extensions can also contain "goto" or "jump" commands to skip to
91 extensions in other contexts. Conditionals provide the ability to
92 react to different stimuli, and there you have it.
93
94 \subsection{Macros}
95
96 Think of a macro as a combination of a context with one nameless
97 extension, and a subroutine. It has arguments like a subroutine
98 might. A macro call can be made within an extension, and the
99 individual statements there are executed until it ends. At this point,
100 execution returns to the next statement after the macro call. Macros
101 can call other macros. And they work just like function calls.
102
103 \subsection{Applications}
104
105 Application calls, like "Dial()", or "Hangup()", or "Answer()", are
106 available for users to use to accomplish the work of the
107 dialplan. There are over 145 of them at the moment this was written,
108 and the list grows as new needs and wants are uncovered. Some
109 applications do fairly simple things, some provide amazingly complex
110 services.
111
112 Hopefully, the above objects will allow you do anything you need to in
113 the Asterisk environment!
114
115 \section{Getting Started}
116
117 The AEL parser (pbx\_ael.so) is completely separate from the module
118 that parses extensions.conf (pbx\_config.so). To use AEL, the only
119 thing that has to be done is the module pbx\_ael.so must be loaded by
120 Asterisk. This will be done automatically if using 'autoload=yes' in
121 /etc/asterisk/modules.conf. When the module is loaded, it will look
122 for 'extensions.ael' in /etc/asterisk/. extensions.conf and
123 extensions.ael can be used in conjunction with
124 each other if that is what is desired. Some users may want to keep
125 extensions.conf for the features that are configured in the 'general'
126 section of extensions.conf.
127
128 Reloading extensions.ael
129
130 To reload extensions.ael, the following command can be issued at the
131 CLI:
132
133     *CLI> ael reload
134
135
136 \section{Debugging}
137
138 Right at this moment, the following commands are available, but do
139 nothing:
140
141 Enable AEL contexts debug
142    *CLI> ael debug contexts 
143
144 Enable AEL macros debug
145    *CLI> ael debug macros 
146
147 Enable AEL read debug
148    *CLI> ael debug read
149
150 Enable AEL tokens debug
151    *CLI> ael debug tokens 
152
153 Disable AEL debug messages
154    *CLI> ael no debug
155
156 If things are going wrong in your dialplan, you can use the following
157 facilities to debug your file:
158
159 1. The messages log in /var/log/asterisk. (from the checks done at load time).
160 2. the "show dialplan" command in asterisk
161 3. the standalone executable, "aelparse" built in the utils/ dir in the source.
162
163
164 \section{About "aelparse"}
165
166 You can use the "aelparse" program to check your extensions.ael
167 file before feeding it to asterisk. Wouldn't it be nice to eliminate
168 most errors before giving the file to asterisk?
169
170 aelparse is compiled in the utils directory of the asterisk release.
171 It isn't installed anywhere (yet). You can copy it to your favorite
172 spot in your PATH.
173
174 aelparse has two optional arguments:
175
176 \begin{itemize}
177   \item -d
178   \begin{itemize}
179     \item Override the normal location of the config file dir, (usually
180        /etc/asterisk), and use the current directory instead as the
181        config file dir. Aelparse will then expect to find the file
182        "./extensions.ael" in the current directory, and any included
183        files in the current directory as well.
184   \end{itemize}
185   \item -n
186   \begin{itemize}
187     \item don't show all the function calls to set priorities and contexts
188        within asterisk. It will just show the errors and warnings from
189        the parsing and semantic checking phases.
190   \end{itemize}
191 \end{itemize}
192
193 \section{General Notes about Syntax}
194
195 Note that the syntax and style are now a little more free-form. The
196 opening '{' (curly-braces) do not have to be on the same line as the
197 keyword that precedes them. Statements can be split across lines, as
198 long as tokens are not broken by doing so. More than one statement can
199 be included on a single line. Whatever you think is best!
200
201 You can just as easily say,
202
203 \begin{verbatim}
204 if(${x}=1) { NoOp(hello!); goto s|3; } else { NoOp(Goodbye!); goto s|12; }
205 \end{verbatim}
206
207 as you can say:
208
209 \begin{verbatim}
210 if(${x}=1)
211 {
212        NoOp(hello!);
213    goto s|3;
214 }
215 else
216 {
217        NoOp(Goodbye!);
218        goto s|12;
219 }
220 \end{verbatim}
221
222 or:
223
224 \begin{verbatim}
225 if(${x}=1) {
226        NoOp(hello!);
227    goto s|3;
228 } else {
229        NoOp(Goodbye!);
230        goto s|12;
231 }
232 \end{verbatim}
233
234 or:
235
236 \begin{verbatim}
237 if (${x}=1) {
238        NoOp(hello!); goto s|3;
239 } else {
240        NoOp(Goodbye!); goto s|12;
241 }
242 \end{verbatim}
243
244 \section{Keywords}
245
246 The AEL keywords are case-sensitive. If an application name and a
247 keyword overlap, there is probably good reason, and you should
248 consider replacing the application call with an AEL statement. If you
249 do not wish to do so, you can still use the application, by using a
250 capitalized letter somewhere in its name. In the Asterisk extension
251 language, application names are NOT case-sensitive.
252
253 The following are keywords in the AEL language:
254 \begin{itemize}
255     \item abstract
256     \item context
257     \item macro
258     \item globals
259     \item ignorepat
260     \item switch
261     \item if
262     \item ifTime
263     \item else
264     \item random
265     \item goto
266     \item jump
267     \item return
268     \item break
269     \item continue
270     \item regexten
271     \item hint
272     \item for
273     \item while
274     \item case
275     \item pattern
276     \item default   NOTE: the "default" keyword can be used as a context name, 
277                       for those who would like to do so.
278     \item catch
279     \item switches
280     \item eswitches
281     \item includes 
282 \end{itemize}
283
284
285 \section{Procedural Interface and Internals}
286
287 AEL first parses the extensions.ael file into a memory structure representing the file.
288 The entire file is represented by a tree of "pval" structures linked together.
289
290 This tree is then handed to the semantic check routine. 
291
292 Then the tree is handed to the compiler. 
293
294 After that, it is freed from memory.
295
296 A program could be written that could build a tree of pval structures, and
297 a pretty printing function is provided, that would dump the data to a file,
298 or the tree could be handed to the compiler to merge the data into the 
299 asterisk dialplan. The modularity of the design offers several opportunities
300 for developers to simplify apps to generate dialplan data.
301
302
303 \subsection{AEL version 2 BNF}
304
305 (hopefully, something close to bnf).
306
307 First, some basic objects
308
309 \begin{verbatim}
310 ------------------------
311 <word>    a lexical token consisting of characters matching this pattern: [-a-zA-Z0-9"_/.\<\>\*\+!$#\[\]][-a-zA-Z0-9"_/.!\*\+\<\>\{\}$#\[\]]*
312
313 <word3-list>  a concatenation of up to 3 <word>s.
314
315 <collected-word>  all characters encountered until the character that follows the <collected-word> in the grammar.
316 -------------------------
317
318 <file> :== <objects>
319
320 <objects> :== <object>
321            | <objects> <object>
322
323
324 <object> :==  <context>
325          | <macro>
326          | <globals>
327          | ';'
328
329
330 <context> :==  'context' <word> '{' <elements> '}'
331             | 'context' <word> '{' '}'
332             | 'context' 'default' '{' <elements> '}'
333             | 'context' 'default' '{' '}'
334             | 'abstract'  'context' <word> '{' <elements> '}'
335             | 'abstract'  'context' <word> '{' '}'
336             | 'abstract'  'context' 'default' '{' <elements> '}'
337             | 'abstract'  'context' 'default' '{' '}'
338
339
340 <macro> :== 'macro' <word> '(' <arglist> ')' '{' <macro_statements> '}'
341        | 'macro' <word> '(' <arglist> ')' '{'  '}'
342        | 'macro' <word> '(' ')' '{' <macro_statements> '}'
343        | 'macro' <word> '(' ')' '{'  '}'
344
345
346 <globals> :== 'globals' '{' <global_statements> '}'
347          | 'globals' '{' '}'
348
349
350 <global_statements> :== <global_statement>
351                    | <global_statements> <global_statement>
352
353
354 <global_statement> :== <word> '=' <collected-word> ';'
355
356
357 <arglist> :== <word>
358          | <arglist> ',' <word>
359
360
361 <elements> :==  <element>
362              | <elements> <element>
363
364
365 <element> :== <extension>
366          | <includes>
367          | <switches>
368          | <eswitches>
369          | <ignorepat>
370          | <word> '='  <collected-word> ';'
371          | ';'
372
373
374 <ignorepat> :== 'ignorepat' '=>' <word> ';'
375
376
377 <extension> :== <word> '=>' <statement>
378            | 'regexten' <word> '=>' <statement>
379            | 'hint' '(' <word3-list> ')' <word> '=>' <statement>
380            | 'regexten' 'hint' '(' <word3-list> ')' <word> '=>' <statement>
381
382
383 <statements> :== <statement>
384             | <statements> <statement>
385
386 <if_head> :== 'if' '('  <collected-word> ')'
387
388 <random_head> :== 'random' '(' <collected-word> ')'
389
390 <ifTime_head> :== 'ifTime' '(' <word3-list> ':' <word3-list> ':' <word3-list> '|' <word3-list> '|' <word3-list> '|' <word3-list> ')'
391                        | 'ifTime' '(' <word> '|' <word3-list> '|' <word3-list> '|' <word3-list> ')'
392
393
394 <word3-list> :== <word>
395        | <word> <word>
396        | <word> <word> <word>
397
398 <switch_head> :== 'switch' '(' <collected-word> ')'  '{'
399
400
401 <statement> :== '{' <statements> '}'
402        | <word> '='  <collected-word> ';'
403        | 'goto' <target> ';'
404        | 'jump' <jumptarget> ';'
405        | <word> ':'
406        | 'for' '('  <collected-word> ';'  <collected-word> ';' <collected-word> ')' <statement>
407        | 'while' '('  <collected-word> ')' <statement>
408        | <switch_head> '}'
409        | <switch_head> <case_statements> '}'
410        | '&' macro_call ';'
411        | <application_call> ';'
412        | <application_call> '='  <collected-word> ';'
413        | 'break' ';'
414        | 'return' ';'
415        | 'continue' ';'
416        | <random_head> <statement>
417        | <random_head> <statement> 'else' <statement>
418        | <if_head> <statement>
419        | <if_head> <statement> 'else' <statement>
420        | <ifTime_head> <statement>
421        | <ifTime_head> <statement> 'else' <statement>
422        | ';'
423
424 <target> :== <word>
425        | <word> '|' <word>
426        | <word> '|' <word> '|' <word>
427        | 'default' '|' <word> '|' <word>
428        | <word> ',' <word>
429        | <word> ',' <word> ',' <word>
430        | 'default' ',' <word> ',' <word>
431
432 <jumptarget> :== <word>
433                | <word> ',' <word>
434                | <word> ',' <word> '@' <word>
435                | <word> '@' <word>
436                | <word> ',' <word> '@' 'default'
437                | <word> '@' 'default'
438
439 <macro_call> :== <word> '(' <eval_arglist> ')'
440        | <word> '(' ')'
441
442 <application_call_head> :== <word>  '('
443
444 <application_call> :== <application_call_head> <eval_arglist> ')'
445        | <application_call_head> ')'
446
447 <eval_arglist> :==  <collected-word>
448        | <eval_arglist> ','  <collected-word>
449        |  /* nothing */
450        | <eval_arglist> ','  /* nothing */
451
452 <case_statements> :== <case_statement>
453        | <case_statements> <case_statement>
454
455
456 <case_statement> :== 'case' <word> ':' <statements>
457        | 'default' ':' <statements>
458        | 'pattern' <word> ':' <statements>
459        | 'case' <word> ':'
460        | 'default' ':'
461        | 'pattern' <word> ':'
462
463 <macro_statements> :== <macro_statement>
464        | <macro_statements> <macro_statement>
465
466 <macro_statement> :== <statement>
467        | 'catch' <word> '{' <statements> '}'
468
469 <switches> :== 'switches' '{' <switchlist> '}'
470        | 'switches' '{' '}'
471
472 <eswitches> :== 'eswitches' '{' <switchlist> '}'
473        | 'eswitches' '{'  '}'
474
475 <switchlist> :== <word> ';'
476        | <switchlist> <word> ';'
477
478 <includeslist> :== <includedname> ';'
479        | <includedname> '|' <word3-list> ':' <word3-list> ':' <word3-list> '|' <word3-list> '|' <word3-list> '|' <word3-list> ';'
480        | <includedname> '|' <word> '|' <word3-list> '|' <word3-list> '|' <word3-list> ';'
481        | <includeslist> <includedname> ';'
482        | <includeslist> <includedname> '|' <word3-list> ':' <word3-list> ':' <word3-list> '|' <word3-list> '|' <word3-list> '|' <word3-list> ';'
483        | <includeslist> <includedname> '|' <word> '|' <word3-list> '|' <word3-list> '|' <word3-list> ';'
484
485 <includedname> :== <word>
486         | 'default'
487
488 <includes> :== 'includes' '{' <includeslist> '}'
489        | 'includes' '{' '}'
490
491 \end{verbatim}
492
493
494 \section{AEL Example USAGE}
495
496 \subsection{Comments}
497
498 Comments begin with // and end with the end of the line.
499
500 Comments are removed by the lexical scanner, and will not be
501 recognized in places where it is busy gathering expressions to wrap in
502 \$[] , or inside application call argument lists. The safest place to put
503 comments is after terminating semicolons, or on otherwise empty lines.
504
505
506 \subsection{Context}
507
508 Contexts in AEL represent a set of extensions in the same way that
509 they do in extensions.conf.
510
511 \begin{verbatim}
512 context default {
513
514 }
515
516
517 A context can be declared to be "abstract", in which case, this
518 declaration expresses the intent of the writer, that this context will
519 only be included by another context, and not "stand on its own". The
520 current effect of this keyword is to prevent "goto " statements from
521 being checked.
522
523 \begin{verbatim}
524 abstract context longdist {
525      _1NXXNXXXXXX => NoOp(generic long distance dialing actions in the US);
526 }
527 \end{verbatim}
528
529
530 \subsection{Extensions}
531
532 To specify an extension in a context, the following syntax is used. If
533 more than one application is be called in an extension, they can be
534 listed in order inside of a block.
535
536 \begin{verbatim}
537 context default {
538     1234 => Playback(tt-monkeys);
539     8000 => {
540          NoOp(one);
541          NoOp(two);
542          NoOp(three);
543     };
544     _5XXX => NoOp(it's a pattern!);
545 }
546 \end{verbatim}
547
548 Two optional items have been added to the AEL syntax, that allow the
549 specification of hints, and a keyword, regexten, that will force the
550 numbering of priorities to start at 2.
551
552 The ability to make extensions match by CID is preserved in
553 AEL; just use '/' and the CID number in the specification. See below.
554
555 \begin{verbatim}
556 context default {
557
558     regexten _5XXX => NoOp(it's a pattern!);
559 }
560 \end{verbatim}
561
562 \begin{verbatim}
563 context default {
564
565     hint(Sip/1) _5XXX => NoOp(it's a pattern!);
566 }
567 \end{verbatim}
568
569 \begin{verbatim}
570 context default {
571
572     regexten hint(Sip/1) _5XXX => NoOp(it's a pattern!);
573 }
574 \end{verbatim}
575
576 The regexten must come before the hint if they are both present.
577
578 CID matching is done as with the extensions.conf file. Follow the extension
579 name/number with a slash (/) and the number to match against the Caller ID:
580
581 \begin{verbatim}
582 context zoombo 
583 {
584         819/7079953345 => { NoOp(hello, 3345); }
585 }
586 \end{verbatim}
587
588 In the above,  the 819/7079953345 extension will only be matched if the
589 CallerID is 7079953345, and the dialed number is 819. Hopefully you have
590 another 819 extension defined for all those who wish 819, that are not so lucky
591 as to have 7079953345 as their CallerID!
592
593
594 \subsection{Includes}
595
596 Contexts can be included in other contexts. All included contexts are
597 listed within a single block.
598
599 \begin{verbatim}
600 context default {
601     includes {
602          local;
603          longdistance;
604          international;
605     }
606 }
607 \end{verbatim}
608
609 Time-limited inclusions can be specified, as in extensions.conf
610 format, with the fields described in the wiki page Asterisk cmd
611 GotoIfTime.
612
613 \begin{verbatim}
614 context default {
615     includes {
616          local;
617          longdistance|16:00-23:59|mon-fri|*|*;
618          international;
619     }
620 }
621 \end{verbatim}
622
623 \subsection{\#include}
624
625 You can include other files with the \#include "filepath" construct.
626
627 \begin{verbatim}
628    #include "/etc/asterisk/testfor.ael"
629 \end{verbatim}
630
631 An interesting property of the \#include, is that you can use it almost
632 anywhere in the .ael file. It is possible to include the contents of
633 a file in a macro, context, or even extension.  The \#include does not
634 have to occur at the beginning of a line. Included files can include
635 other files, up to 50 levels deep. If the path provided in quotes is a
636 relative path, the parser looks in the config file directory for the
637 file (usually /etc/asterisk).
638
639
640
641 \subsection{Dialplan Switches}
642
643 Switches are listed in their own block within a context. For clues as
644 to what these are used for, see Asterisk - dual servers, and Asterisk
645 config extensions.conf.
646
647 \begin{verbatim}
648 context default {
649     switches {
650          DUNDi/e164;
651          IAX2/box5;
652     };
653     eswitches {
654          IAX2/context@${CURSERVER};
655     }
656 }
657 \end{verbatim}
658
659
660 \subsection{Ignorepat}
661
662 ignorepat can be used to instruct channel drivers to not cancel
663 dialtone upon receipt of a particular pattern. The most commonly used
664 example is '9'.
665
666 \begin{verbatim}
667 context outgoing {
668     ignorepat => 9;
669 }
670 \end{verbatim}
671
672
673 \subsection{Variables}
674
675 Variables in Asterisk do not have a type, so to define a variable, it
676 just has to be specified with a value.
677
678 Global variables are set in their own block.
679
680 \begin{verbatim}
681 globals {
682     CONSOLE=Console/dsp;
683     TRUNK=Zap/g2;
684 }
685 \end{verbatim}
686
687
688 Variables can be set within extensions as well.
689
690 \begin{verbatim}
691 context foo {
692     555 => {
693          x=5;
694          y=blah;
695          divexample=10/2
696          NoOp(x is ${x} and y is ${y} !);
697     }
698 }
699 \end{verbatim}
700
701 NOTE: AEL wraps the right hand side of an assignment with \$[ ] to allow 
702 expressions to be used If this is unwanted, you can protect the right hand 
703 side from being wrapped by using the Set() application. 
704 Read the README.variables about the requirements and behavior 
705 of \$[ ] expressions.
706
707 NOTE: These things are wrapped up in a \$[ ] expression: The while() test; 
708 the if() test; the middle expression in the for( x; y; z) statement 
709 (the y expression); Assignments - the right hand side, so a = b -> Set(a=\$[b])
710
711 Writing to a dialplan function is treated the same as writing to a variable.
712
713 \begin{verbatim}
714 context blah {
715     s => {
716          CALLERID(name)=ChickenMan;
717          NoOp(My name is ${CALLERID(name)} !);
718     }
719
720 \end{verbatim}
721
722
723 \subsection{Loops}
724
725 AEL has implementations of 'for' and 'while' loops.
726
727 \begin{verbatim}
728 context loops {
729     1 => {
730          for (x=0; ${x} < 3; x=${x} + 1) {
731               Verbose(x is ${x} !);
732          }
733     }
734     2 => {
735          y=10;
736          while (${y} >= 0) {
737               Verbose(y is ${y} !);
738               y=${y}-1;
739          }
740     }
741 }
742 \end{verbatim}
743
744 NOTE: The conditional expression (the "\${y} >= 0" above) is wrapped in
745       \$[ ] so it can be evaluated.  NOTE: The for loop test expression
746       (the "\${x} < 3" above) is wrapped in \$[ ] so it can be evaluated.
747
748
749
750 \subsection{Conditionals}
751
752 AEL supports if and switch statements, like AEL, but adds ifTime, and
753 random. Unlike the original AEL, though, you do NOT need to put curly
754 braces around a single statement in the "true" branch of an if(), the
755 random(), or an ifTime() statement. The if(), ifTime(), and random()
756 statements allow optional else clause.
757
758 \begin{verbatim}
759 context conditional {
760     _8XXX => {
761          Dial(SIP/${EXTEN});
762          if ("${DIALSTATUS}" = "BUSY")
763          {
764               NoOp(yessir);
765               Voicemail(${EXTEN}|b);
766          }
767          else
768               Voicemail(${EXTEN}|u);
769          ifTime (14:00-25:00|sat-sun|*|*) 
770               Voicemail(${EXTEN}|b);
771          else
772          {
773               Voicemail(${EXTEN}|u);
774               NoOp(hi, there!);
775          }
776          random(51) NoOp(This should appear 51% of the time);
777
778          random( 60 )
779          {
780                        NoOp( This should appear 60% of the time );
781          }
782          else
783          {
784                        random(75)
785                        {
786                                NoOp( This should appear 30% of the time! );
787                        }
788                        else
789                        {
790                                NoOp( This should appear 10% of the time! );
791                        }
792           }
793     }
794     _777X => {
795          switch (${EXTEN}) {
796               case 7771:
797                    NoOp(You called 7771!);
798                    break;
799               case 7772:
800                    NoOp(You called 7772!);
801                    break;
802               case 7773:
803                    NoOp(You called 7773!);
804                    // fall thru-
805               pattern 777[4-9]:
806                     NoOp(You called 777 something!);
807               default:
808                    NoOp(In the default clause!);
809          }
810     }
811 }
812 \end{verbatim}
813
814 NOTE: The conditional expression in if() statements (the
815       "\${DIALSTATUS}" = "BUSY" above) is wrapped by the compiler in 
816       \$[] for evaluation.
817
818 NOTE: Neither the switch nor case values are wrapped in \$[ ]; they can
819       be constants, or \${var} type references only.
820
821 NOTE: AEL generates each case as a separate extension. case clauses
822       with no terminating 'break', or 'goto', have a goto inserted, to
823       the next clause, which creates a 'fall thru' effect.
824
825 NOTE: AEL introduces the ifTime keyword/statement, which works just
826       like the if() statement, but the expression is a time value,
827       exactly like that used by the application GotoIfTime(). See
828       Asterisk cmd GotoIfTime
829
830 NOTE: The pattern statement makes sure the new extension that is
831       created has an '\_' preceding it to make sure asterisk recognizes
832       the extension name as a pattern.
833
834 NOTE: Every character enclosed by the switch expression's parenthesis
835       are included verbatim in the labels generated. So watch out for
836       spaces!
837
838 NOTE: NEW: Previous to version 0.13, the random statement used the
839       "Random()" application, which has been deprecated. It now uses
840       the RAND() function instead, in the GotoIf application.
841
842
843 \subsection{Break, Continue, and Return}
844
845 Three keywords, break, continue, and return, are included in the
846 syntax to provide flow of control to loops, and switches.
847
848 The break can be used in switches and loops, to jump to the end of the
849 loop or switch.
850
851 The continue can be used in loops (while and for) to immediately jump
852 to the end of the loop. In the case of a for loop, the increment and
853 test will then be performed. In the case of the while loop, the
854 continue will jump to the test at the top of the loop.
855
856 The return keyword will cause an immediate jump to the end of the
857 context, or macro, and can be used anywhere.
858
859
860
861 \subsection{goto, jump, and labels}
862
863 This is an example of how to do a goto in AEL.
864
865 \begin{verbatim}
866 context gotoexample {
867     s => {
868 begin:
869          NoOp(Infinite Loop!  yay!);
870          Wait(1);
871          goto begin;    // go to label in same extension
872     }
873     3 => {
874             goto s|begin;   // go to label in different extension
875      }
876      4 => {
877             goto gotoexample|s|begin;  // overkill go to label in same context
878      }
879 }
880
881 context gotoexample2 {
882      s =>  {
883    end: 
884            goto gotoexample|s|begin;   // go to label in different context
885      }
886 }
887 \end{verbatim}
888
889 You can use the special label of "1" in the goto and jump
890 statements. It means the "first" statement in the extension. I would
891 not advise trying to use numeric labels other than "1" in goto's or
892 jumps, nor would I advise declaring a "1" label anywhere! As a matter
893 of fact, it would be bad form to declare a numeric label, and it might
894 conflict with the priority numbers used internally by asterisk.
895
896 The syntax of the jump statement is: jump
897 extension[,priority][@context] If priority is absent, it defaults to
898 "1". If context is not present, it is assumed to be the same as that
899 which contains the "jump".
900
901 \begin{verbatim}
902 context gotoexample {
903     s => {
904 begin:
905          NoOp(Infinite Loop!  yay!);
906          Wait(1);
907          jump s;    // go to first extension in same extension
908     }
909     3 => {
910             jump s,begin;   // go to label in different extension
911      }
912      4 => {
913             jump s,begin@gotoexample;  // overkill go to label in same context
914      }
915 }
916
917 context gotoexample2 {
918      s =>  {
919    end: 
920            jump s@gotoexample;   // go to label in different context
921      }
922 }
923 \end{verbatim}
924
925 NOTE: goto labels follow the same requirements as the Goto()
926       application, except the last value has to be a label. If the
927       label does not exist, you will have run-time errors. If the
928       label exists, but in a different extension, you have to specify
929       both the extension name and label in the goto, as in: goto s|z;
930       if the label is in a different context, you specify
931       context|extension|label. There is a note about using goto's in a
932       switch statement below...
933
934 NOTE  AEL introduces the special label "1", which is the beginning
935       context number for most extensions.
936
937 NOTE: A NEW addition to AEL: you can now use ',' instead of '|' to 
938       separate the items in the target address. You can't have a mix,
939       though, of '|' and ',' in the target. It's either one, or the other.
940
941
942
943
944 \subsection{Macros}
945
946 A macro is defined in its own block like this. The arguments to the
947 macro are specified with the name of the macro. They are then referred
948 to by that same name. A catch block can be specified to catch special
949 extensions.
950
951 \begin{verbatim}
952 macro std-exten( ext , dev ) {
953        Dial(${dev}/${ext},20);
954        switch(${DIALSTATUS) {
955        case BUSY:
956                Voicemail(b${ext});
957                break;
958        default:
959                Voicemail(u${ext});
960
961        }
962        catch a {
963                VoiceMailMain(${ext});
964                return;
965        }
966 }
967 \end{verbatim}
968
969 A macro is then called by preceding the macro name with an
970 ampersand. Empty arguments can be passed simply with nothing between
971 comments(0.11).
972
973 \begin{verbatim}
974 context example {
975     _5XXX => &std-exten(${EXTEN}, "IAX2");
976     _6XXX => &std-exten(, "IAX2");
977     _7XXX => &std-exten(${EXTEN},);
978     _8XXX => &std-exten(,);
979 }
980 \end{verbatim}
981
982
983 \section{Examples}
984
985 \begin{verbatim}
986 context demo {
987     s => {
988          Wait(1);
989          Answer();
990          TIMEOUT(digit)=5;
991          TIMEOUT(response)=10;
992 restart:
993          Background(demo-congrats);
994 instructions:
995          for (x=0; ${x} < 3; x=${x} + 1) {
996               Background(demo-instruct);
997               WaitExten();
998          }
999     }
1000     2 => {
1001          Background(demo-moreinfo);
1002          goto s|instructions;
1003     }
1004     3 => {
1005          LANGUAGE()=fr;
1006          goto s|restart;
1007     }
1008
1009     500 => {
1010          Playback(demo-abouttotry);
1011          Dial(IAX2/guest@misery.digium.com);
1012          Playback(demo-nogo);
1013          goto s|instructions;
1014     }
1015     600 => {
1016          Playback(demo-echotest);
1017          Echo();
1018          Playback(demo-echodone);
1019          goto s|instructions;
1020     }
1021     # => {
1022 hangup:
1023          Playback(demo-thanks);
1024          Hangup();
1025     }
1026     t => goto #|hangup;
1027     i => Playback(invalid);
1028 }
1029 \end{verbatim}
1030
1031
1032 \section{Semantic Checks}
1033
1034
1035 AEL, after parsing, but before compiling, traverses the dialplan
1036 tree, and makes several checks:
1037
1038 \begin{itemize}
1039     \item Macro calls to non-existent macros.
1040     \item Macro calls to contexts.
1041     \item Macro calls with argument count not matching the definition.
1042     \item application call to macro. (missing the '\&')
1043     \item application calls to "GotoIf", "GotoIfTime", "while",
1044       "endwhile", "Random", and "execIf", will generate a message to
1045       consider converting the call to AEL goto, while, etc. constructs.
1046     \item goto a label in an empty extension.
1047     \item goto a non-existent label, either a within-extension,
1048       within-context, or in a different context, or in any included
1049       contexts. Will even check "sister" context references.
1050     \item All the checks done on the time values in the dial plan, are
1051       done on the time values in the ifTime() and includes times:
1052           o the time range has to have two times separated by a dash;
1053           o the times have to be in range of 0 to 24 hours.
1054           o The weekdays have to match the internal list, if they are provided;
1055           o the day of the month, if provided, must be in range of 1 to 31;
1056           o the month name or names have to match those in the internal list. 
1057     \item (0.5) If an expression is wrapped in \$[ ... ], and the compiler
1058       will wrap it again, a warning is issued.
1059     \item (0.5) If an expression had operators (you know,
1060       +,-,*,/,%,!,etc), but no \${ } variables, a warning is
1061       issued. Maybe someone forgot to wrap a variable name?
1062     \item (0.12) check for duplicate context names.
1063     \item (0.12) check for abstract contexts that are not included by any context.
1064     \item (0.13) Issue a warning if a label is a numeric value. 
1065 \end{itemize}
1066
1067 There are a subset of checks that have been removed until the proposed
1068 AAL (Asterisk Argument Language) is developed and incorporated into Asterisk.
1069 These checks will be:
1070
1071 \begin{itemize}
1072     \item (if the application argument analyzer is working: the presence
1073       of the 'j' option is reported as error.
1074     \item if options are specified, that are not available in an
1075       application.
1076     \item if you specify too many arguments to an application.
1077     \item a required argument is not present in an application call.
1078     \item Switch-case using "known" variables that applications set, that
1079       does not cover all the possible values. (a "default" case will
1080       solve this problem. Each "unhandled" value is listed.
1081     \item a Switch construct is used, which is uses a known variable, and
1082       the application that would set that variable is not called in
1083       the same extension. This is a warning only...
1084     \item Calls to applications not in the "applist" database (installed
1085       in /var/lib/asterisk/applist" on most systems).
1086     \item In an assignment statement, if the assignment is to a function,
1087       the function name used is checked to see if it one of the
1088       currently known functions. A warning is issued if it is not.
1089 \end{itemize}
1090
1091
1092 Differences with the original version of AEL
1093 ============================================
1094
1095 \begin{enumerate}
1096    \item The \$[...] expressions have been enhanced to include the ==, ||,
1097       and \&\& operators. These operators are exactly equivalent to the
1098       =, |, and \& operators, respectively. Why? So the C, Java, C++
1099       hackers feel at home here.
1100    \item It is more free-form. The newline character means very little,
1101       and is pulled out of the white-space only for line numbers in
1102       error messages.
1103    \item It generates more error messages -- by this I mean that any
1104       difference between the input and the grammar are reported, by
1105       file, line number, and column.
1106    \item It checks the contents of \$[ ] expressions (or what will end up
1107       being \$[ ] expressions!) for syntax errors. It also does
1108       matching paren/bracket counts.
1109    \item It runs several semantic checks after the parsing is over, but
1110       before the compiling begins, see the list above.
1111    \item It handles \#include "filepath" directives. -- ALMOST
1112       anywhere, in fact. You could easily include a file in a context,
1113       in an extension, or at the root level. Files can be included in
1114       files that are included in files, down to 50 levels of hierarchy...
1115    \item Local Goto's inside Switch statements automatically have the
1116       extension of the location of the switch statement appended to them.
1117    \item A pretty printer function is available within pbx\_ael.so.
1118    \item In the utils directory, two standalone programs are supplied for
1119       debugging AEL files. One is called "aelparse", and it reads in
1120       the /etc/asterisk/extensions.ael file, and shows the results of
1121       syntax and semantic checking on stdout, and also shows the
1122       results of compilation to stdout. The other is "aelparse1",
1123       which uses the original ael compiler to do the same work,
1124       reading in "/etc/asterisk/extensions.ael", using the original
1125       'pbx\_ael.so' instead.
1126   \item AEL supports the "jump" statement, and the "pattern" statement
1127       in switch constructs. Hopefully these will be documented in the
1128       AEL README.
1129   \item Added the "return" keyword, which will jump to the end of an
1130       extension/Macro.
1131   \item Added the ifTime (<time range>|<days of week>|<days of
1132       month>|<months> ) {} [else {}] construct, which executes much
1133       like an if () statement, but the decision is based on the
1134       current time, and the time spec provided in the ifTime. See the
1135       example above. (Note: all the other time-dependent Applications
1136       can be used via ifTime)
1137   \item Added the optional time spec to the contexts in the includes
1138       construct. See examples above.
1139   \item You don't have to wrap a single "true" statement in curly
1140       braces, as in the original AEL. An "else" is attached to the
1141       closest if. As usual, be careful about nested if statements!
1142       When in doubt, use curlies!
1143   \item Added the syntax [regexten] [hint(channel)] to precede an
1144       extension declaration. See examples above, under
1145       "Extension". The regexten keyword will cause the priorities in
1146       the extension to begin with 2 instead of 1. The hint keyword
1147       will cause its arguments to be inserted in the extension under
1148       the hint priority. They are both optional, of course, but the
1149       order is fixed at the moment-- the regexten must come before the
1150       hint, if they are both present.
1151   \item Empty case/default/pattern statements will "fall thru" as
1152       expected. (0.6)
1153   \item A trailing label in an extension, will automatically have a
1154       NoOp() added, to make sure the label exists in the extension on
1155       Asterisk. (0.6)
1156   \item (0.9) the semicolon is no longer required after a closing brace!
1157       (i.e. "];" ===> "\}". You can have them there if you like, but
1158       they are not necessary. Someday they may be rejected as a syntax
1159       error, maybe.
1160   \item (0.9) the // comments are not recognized and removed in the
1161       spots where expressions are gathered, nor in application call
1162       arguments. You may have to move a comment if you get errors in
1163       existing files.
1164   \item (0.10) the random statement has been added. Syntax: random (
1165       <expr> ) <lucky-statement> [ else <unlucky-statement> ]. The
1166       probability of the lucky-statement getting executed is <expr>,
1167       which should evaluate to an integer between 0 and 100. If the
1168       <lucky-statement> isn't so lucky this time around, then the
1169       <unlucky-statement> gets executed, if it is present.
1170 \end{enumerate}
1171
1172
1173 \section{Hints and Bugs}
1174
1175      The safest way to check for a null strings is to say \$[ "\${x}" =
1176      "" ] The old way would do as shell scripts often do, and append
1177      something on both sides, like this: \$[ \${x}foo = foo ]. The
1178      trouble with the old way, is that, if x contains any spaces, then
1179      problems occur, usually syntax errors. It is better practice and
1180      safer wrap all such tests with double quotes! Also, there are now
1181      some functions that can be used in a variable reference,
1182      ISNULL(), and LEN(), that can be used to test for an empty string:
1183      \${ISNULL(\${x})} or \$[ \${LEN(\${x}) = 0 ].
1184
1185       Assignment vs. Set(). Keep in mind that setting a variable to
1186       value can be done two different ways. If you choose say 'x=y;',
1187       keep in mind that AEL will wrap the right-hand-side with
1188       \$[]. So, when compiled into extension language format, the end
1189       result will be 'Set(x=\$[y])'. If you don't want this effect,
1190       then say "Set(x=y);" instead.
1191
1192
1193 \section{The Full Power of AEL}
1194
1195 A newcomer to Asterisk will look at the above constructs and
1196 descriptions, and ask, "Where's the string manipulation functions?",
1197 "Where's all the cool operators that other languages have to offer?",
1198 etc.
1199
1200 The answer is that the rich capabilities of Asterisk are made
1201 available through AEL, via:
1202
1203 \begin{itemize}
1204     \item Applications: See Asterisk - documentation of application
1205       commands
1206
1207     \item Functions: Functions were implemented inside \${ .. } variable
1208       references, and supply many useful capabilities. 
1209
1210     \item Expressions: An expression evaluation engine handles items
1211       wrapped inside \$[...]. This includes some string manipulation
1212       facilities, arithmetic expressions, etc. 
1213
1214     \item Application Gateway Interface: Asterisk can fork external
1215       processes that communicate via pipe. AGI applications can be
1216       written in any language. Very powerful applications can be added
1217       this way. 
1218
1219     \item Variables: Channels of communication have variables associated
1220       with them, and asterisk provides some global variables. These can be
1221       manipulated and/or consulted by the above mechanisms. 
1222 \end{itemize}