Merged revisions 77424,77429 via svnmerge from
[asterisk/asterisk.git] / doc / tex / 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 local
268     \item return
269     \item break
270     \item continue
271     \item regexten
272     \item hint
273     \item for
274     \item while
275     \item case
276     \item pattern
277     \item default   NOTE: the "default" keyword can be used as a context name, 
278                       for those who would like to do so.
279     \item catch
280     \item switches
281     \item eswitches
282     \item includes 
283 \end{itemize}
284
285
286 \section{Procedural Interface and Internals}
287
288 AEL first parses the extensions.ael file into a memory structure representing the file.
289 The entire file is represented by a tree of "pval" structures linked together.
290
291 This tree is then handed to the semantic check routine. 
292
293 Then the tree is handed to the compiler. 
294
295 After that, it is freed from memory.
296
297 A program could be written that could build a tree of pval structures, and
298 a pretty printing function is provided, that would dump the data to a file,
299 or the tree could be handed to the compiler to merge the data into the 
300 asterisk dialplan. The modularity of the design offers several opportunities
301 for developers to simplify apps to generate dialplan data.
302
303
304 \subsection{AEL version 2 BNF}
305
306 (hopefully, something close to bnf).
307
308 First, some basic objects
309
310 \begin{verbatim}
311 ------------------------
312 <word>    a lexical token consisting of characters matching this pattern: [-a-zA-Z0-9"_/.\<\>\*\+!$#\[\]][-a-zA-Z0-9"_/.!\*\+\<\>\{\}$#\[\]]*
313
314 <word3-list>  a concatenation of up to 3 <word>s.
315
316 <collected-word>  all characters encountered until the character that follows the <collected-word> in the grammar.
317 -------------------------
318
319 <file> :== <objects>
320
321 <objects> :== <object>
322            | <objects> <object>
323
324
325 <object> :==  <context>
326          | <macro>
327          | <globals>
328          | ';'
329
330
331 <context> :==  'context' <word> '{' <elements> '}'
332             | 'context' <word> '{' '}'
333             | 'context' 'default' '{' <elements> '}'
334             | 'context' 'default' '{' '}'
335             | 'abstract'  'context' <word> '{' <elements> '}'
336             | 'abstract'  'context' <word> '{' '}'
337             | 'abstract'  'context' 'default' '{' <elements> '}'
338             | 'abstract'  'context' 'default' '{' '}'
339
340
341 <macro> :== 'macro' <word> '(' <arglist> ')' '{' <macro_statements> '}'
342        | 'macro' <word> '(' <arglist> ')' '{'  '}'
343        | 'macro' <word> '(' ')' '{' <macro_statements> '}'
344        | 'macro' <word> '(' ')' '{'  '}'
345
346
347 <globals> :== 'globals' '{' <global_statements> '}'
348          | 'globals' '{' '}'
349
350
351 <global_statements> :== <global_statement>
352                    | <global_statements> <global_statement>
353
354
355 <global_statement> :== <word> '=' <collected-word> ';'
356
357
358 <arglist> :== <word>
359          | <arglist> ',' <word>
360
361
362 <elements> :==  <element>
363              | <elements> <element>
364
365
366 <element> :== <extension>
367          | <includes>
368          | <switches>
369          | <eswitches>
370          | <ignorepat>
371          | <word> '='  <collected-word> ';'
372          | 'local' <word> '='  <collected-word> ';'
373          | ';'
374
375
376 <ignorepat> :== 'ignorepat' '=>' <word> ';'
377
378
379 <extension> :== <word> '=>' <statement>
380            | 'regexten' <word> '=>' <statement>
381            | 'hint' '(' <word3-list> ')' <word> '=>' <statement>
382            | 'regexten' 'hint' '(' <word3-list> ')' <word> '=>' <statement>
383
384
385 <statements> :== <statement>
386             | <statements> <statement>
387
388 <if_head> :== 'if' '('  <collected-word> ')'
389
390 <random_head> :== 'random' '(' <collected-word> ')'
391
392 <ifTime_head> :== 'ifTime' '(' <word3-list> ':' <word3-list> ':' <word3-list> '|' <word3-list> '|' <word3-list> '|' <word3-list> ')'
393                        | 'ifTime' '(' <word> '|' <word3-list> '|' <word3-list> '|' <word3-list> ')'
394
395
396 <word3-list> :== <word>
397        | <word> <word>
398        | <word> <word> <word>
399
400 <switch_head> :== 'switch' '(' <collected-word> ')'  '{'
401
402
403 <statement> :== '{' <statements> '}'
404        | <word> '='  <collected-word> ';'
405        | 'local' <word> '='  <collected-word> ';'
406        | 'goto' <target> ';'
407        | 'jump' <jumptarget> ';'
408        | <word> ':'
409        | 'for' '('  <collected-word> ';'  <collected-word> ';' <collected-word> ')' <statement>
410        | 'while' '('  <collected-word> ')' <statement>
411        | <switch_head> '}'
412        | <switch_head> <case_statements> '}'
413        | '&' macro_call ';'
414        | <application_call> ';'
415        | <application_call> '='  <collected-word> ';'
416        | 'break' ';'
417        | 'return' ';'
418        | 'continue' ';'
419        | <random_head> <statement>
420        | <random_head> <statement> 'else' <statement>
421        | <if_head> <statement>
422        | <if_head> <statement> 'else' <statement>
423        | <ifTime_head> <statement>
424        | <ifTime_head> <statement> 'else' <statement>
425        | ';'
426
427 <target> :== <word>
428        | <word> '|' <word>
429        | <word> '|' <word> '|' <word>
430        | 'default' '|' <word> '|' <word>
431        | <word> ',' <word>
432        | <word> ',' <word> ',' <word>
433        | 'default' ',' <word> ',' <word>
434
435 <jumptarget> :== <word>
436                | <word> ',' <word>
437                | <word> ',' <word> '@' <word>
438                | <word> '@' <word>
439                | <word> ',' <word> '@' 'default'
440                | <word> '@' 'default'
441
442 <macro_call> :== <word> '(' <eval_arglist> ')'
443        | <word> '(' ')'
444
445 <application_call_head> :== <word>  '('
446
447 <application_call> :== <application_call_head> <eval_arglist> ')'
448        | <application_call_head> ')'
449
450 <eval_arglist> :==  <collected-word>
451        | <eval_arglist> ','  <collected-word>
452        |  /* nothing */
453        | <eval_arglist> ','  /* nothing */
454
455 <case_statements> :== <case_statement>
456        | <case_statements> <case_statement>
457
458
459 <case_statement> :== 'case' <word> ':' <statements>
460        | 'default' ':' <statements>
461        | 'pattern' <word> ':' <statements>
462        | 'case' <word> ':'
463        | 'default' ':'
464        | 'pattern' <word> ':'
465
466 <macro_statements> :== <macro_statement>
467        | <macro_statements> <macro_statement>
468
469 <macro_statement> :== <statement>
470        | 'catch' <word> '{' <statements> '}'
471
472 <switches> :== 'switches' '{' <switchlist> '}'
473        | 'switches' '{' '}'
474
475 <eswitches> :== 'eswitches' '{' <switchlist> '}'
476        | 'eswitches' '{'  '}'
477
478 <switchlist> :== <word> ';'
479        | <switchlist> <word> ';'
480
481 <includeslist> :== <includedname> ';'
482        | <includedname> '|' <word3-list> ':' <word3-list> ':' <word3-list> '|' <word3-list> '|' <word3-list> '|' <word3-list> ';'
483        | <includedname> '|' <word> '|' <word3-list> '|' <word3-list> '|' <word3-list> ';'
484        | <includeslist> <includedname> ';'
485        | <includeslist> <includedname> '|' <word3-list> ':' <word3-list> ':' <word3-list> '|' <word3-list> '|' <word3-list> '|' <word3-list> ';'
486        | <includeslist> <includedname> '|' <word> '|' <word3-list> '|' <word3-list> '|' <word3-list> ';'
487
488 <includedname> :== <word>
489         | 'default'
490
491 <includes> :== 'includes' '{' <includeslist> '}'
492        | 'includes' '{' '}'
493
494 \end{verbatim}
495
496
497 \section{AEL Example USAGE}
498
499 \subsection{Comments}
500
501 Comments begin with // and end with the end of the line.
502
503 Comments are removed by the lexical scanner, and will not be
504 recognized in places where it is busy gathering expressions to wrap in
505 \$[] , or inside application call argument lists. The safest place to put
506 comments is after terminating semicolons, or on otherwise empty lines.
507
508
509 \subsection{Context}
510
511 Contexts in AEL represent a set of extensions in the same way that
512 they do in extensions.conf.
513
514 \begin{verbatim}
515 context default {
516
517 }
518
519
520 A context can be declared to be "abstract", in which case, this
521 declaration expresses the intent of the writer, that this context will
522 only be included by another context, and not "stand on its own". The
523 current effect of this keyword is to prevent "goto " statements from
524 being checked.
525
526 \begin{verbatim}
527 abstract context longdist {
528      _1NXXNXXXXXX => NoOp(generic long distance dialing actions in the US);
529 }
530 \end{verbatim}
531
532
533 \subsection{Extensions}
534
535 To specify an extension in a context, the following syntax is used. If
536 more than one application is be called in an extension, they can be
537 listed in order inside of a block.
538
539 \begin{verbatim}
540 context default {
541     1234 => Playback(tt-monkeys);
542     8000 => {
543          NoOp(one);
544          NoOp(two);
545          NoOp(three);
546     };
547     _5XXX => NoOp(it's a pattern!);
548 }
549 \end{verbatim}
550
551 Two optional items have been added to the AEL syntax, that allow the
552 specification of hints, and a keyword, regexten, that will force the
553 numbering of priorities to start at 2.
554
555 The ability to make extensions match by CID is preserved in
556 AEL; just use '/' and the CID number in the specification. See below.
557
558 \begin{verbatim}
559 context default {
560
561     regexten _5XXX => NoOp(it's a pattern!);
562 }
563 \end{verbatim}
564
565 \begin{verbatim}
566 context default {
567
568     hint(Sip/1) _5XXX => NoOp(it's a pattern!);
569 }
570 \end{verbatim}
571
572 \begin{verbatim}
573 context default {
574
575     regexten hint(Sip/1) _5XXX => NoOp(it's a pattern!);
576 }
577 \end{verbatim}
578
579 The regexten must come before the hint if they are both present.
580
581 CID matching is done as with the extensions.conf file. Follow the extension
582 name/number with a slash (/) and the number to match against the Caller ID:
583
584 \begin{verbatim}
585 context zoombo 
586 {
587   819/7079953345 => { NoOp(hello, 3345); }
588 }
589 \end{verbatim}
590
591 In the above,  the 819/7079953345 extension will only be matched if the
592 CallerID is 7079953345, and the dialed number is 819. Hopefully you have
593 another 819 extension defined for all those who wish 819, that are not so lucky
594 as to have 7079953345 as their CallerID!
595
596
597 \subsection{Includes}
598
599 Contexts can be included in other contexts. All included contexts are
600 listed within a single block.
601
602 \begin{verbatim}
603 context default {
604     includes {
605          local;
606          longdistance;
607          international;
608     }
609 }
610 \end{verbatim}
611
612 Time-limited inclusions can be specified, as in extensions.conf
613 format, with the fields described in the wiki page Asterisk cmd
614 GotoIfTime.
615
616 \begin{verbatim}
617 context default {
618     includes {
619          local;
620          longdistance|16:00-23:59|mon-fri|*|*;
621          international;
622     }
623 }
624 \end{verbatim}
625
626 \subsection{\#include}
627
628 You can include other files with the \#include "filepath" construct.
629
630 \begin{verbatim}
631    #include "/etc/asterisk/testfor.ael"
632 \end{verbatim}
633
634 An interesting property of the \#include, is that you can use it almost
635 anywhere in the .ael file. It is possible to include the contents of
636 a file in a macro, context, or even extension.  The \#include does not
637 have to occur at the beginning of a line. Included files can include
638 other files, up to 50 levels deep. If the path provided in quotes is a
639 relative path, the parser looks in the config file directory for the
640 file (usually /etc/asterisk).
641
642
643
644 \subsection{Dialplan Switches}
645
646 Switches are listed in their own block within a context. For clues as
647 to what these are used for, see Asterisk - dual servers, and Asterisk
648 config extensions.conf.
649
650 \begin{verbatim}
651 context default {
652     switches {
653          DUNDi/e164;
654          IAX2/box5;
655     };
656     eswitches {
657          IAX2/context@${CURSERVER};
658     }
659 }
660 \end{verbatim}
661
662
663 \subsection{Ignorepat}
664
665 ignorepat can be used to instruct channel drivers to not cancel
666 dialtone upon receipt of a particular pattern. The most commonly used
667 example is '9'.
668
669 \begin{verbatim}
670 context outgoing {
671     ignorepat => 9;
672 }
673 \end{verbatim}
674
675
676 \subsection{Variables}
677
678 Variables in Asterisk do not have a type, so to define a variable, it
679 just has to be specified with a value.
680
681 Global variables are set in their own block.
682
683 \begin{verbatim}
684 globals {
685     CONSOLE=Console/dsp;
686     TRUNK=Zap/g2;
687 }
688 \end{verbatim}
689
690
691 Variables can be set within extensions as well.
692
693 \begin{verbatim}
694 context foo {
695     555 => {
696          x=5;
697          y=blah;
698          divexample=10/2
699          NoOp(x is ${x} and y is ${y} !);
700     }
701 }
702 \end{verbatim}
703
704 NOTE: AEL wraps the right hand side of an assignment with \$[ ] to allow 
705 expressions to be used If this is unwanted, you can protect the right hand 
706 side from being wrapped by using the Set() application. 
707 Read the README.variables about the requirements and behavior 
708 of \$[ ] expressions.
709
710 NOTE: These things are wrapped up in a \$[ ] expression: The while() test; 
711 the if() test; the middle expression in the for( x; y; z) statement 
712 (the y expression); Assignments - the right hand side, so a = b -> Set(a=\$[b])
713
714 Writing to a dialplan function is treated the same as writing to a variable.
715
716 \begin{verbatim}
717 context blah {
718     s => {
719          CALLERID(name)=ChickenMan;
720          NoOp(My name is ${CALLERID(name)} !);
721     }
722
723 \end{verbatim}
724
725 You can declare variables in Macros, as so:
726
727 \begin{verbatim}
728 Macro myroutine(firstarg, secondarg)
729 {
730   Myvar=1;
731   NoOp(Myvar is set to ${myvar});
732 }
733 \end{verbatim}
734
735 \subsection{Local Variables}
736
737 In 1.2, and 1.4, ALL VARIABLES are CHANNEL variables, including the function
738 arguments and associated ARG1, ARG2, etc variables. Sorry.
739
740 In trunk (1.6 and higher), we have made all arguments local variables to
741 a macro call. They will not affect channel variables of the same name.
742 This includes the ARG1, ARG2, etc variables. 
743
744 Users can declare their own local variables by using the keyword 'local'
745 before setting them to a value;
746
747 \begin{verbatim}
748 Macro myroutine(firstarg, secondarg)
749 {
750   local Myvar=1;
751   NoOp(Myvar is set to ${Myvar}, and firstarg is ${firstarg}, and secondarg is ${secondarg});
752 }
753 \end{verbatim}
754
755 In the above example, Myvar, firstarg, and secondarg are all local variables,
756 and will not be visible to the calling code, be it an extension, or another Macro. 
757
758 If you need to make a local variable within the Set() application, you can do it this way:
759
760 \begin{verbatim}
761 Macro myroutine(firstarg, secondarg)
762 {
763   Set(LOCAL(Myvar)=1);
764   NoOp(Myvar is set to ${Myvar}, and firstarg is ${firstarg}, and secondarg is ${secondarg});
765 }
766 \end{verbatim}
767
768
769 \subsection{Loops}
770
771 AEL has implementations of 'for' and 'while' loops.
772
773 \begin{verbatim}
774 context loops {
775     1 => {
776          for (x=0; ${x} < 3; x=${x} + 1) {
777               Verbose(x is ${x} !);
778          }
779     }
780     2 => {
781          y=10;
782          while (${y} >= 0) {
783               Verbose(y is ${y} !);
784               y=${y}-1;
785          }
786     }
787 }
788 \end{verbatim}
789
790 NOTE: The conditional expression (the "\${y} $>$= 0" above) is wrapped in
791       \$[ ] so it can be evaluated.  NOTE: The for loop test expression
792       (the "\${x} $<$ 3" above) is wrapped in \$[ ] so it can be evaluated.
793
794
795
796 \subsection{Conditionals}
797
798 AEL supports if and switch statements, like AEL, but adds ifTime, and
799 random. Unlike the original AEL, though, you do NOT need to put curly
800 braces around a single statement in the "true" branch of an if(), the
801 random(), or an ifTime() statement. The if(), ifTime(), and random()
802 statements allow optional else clause.
803
804 \begin{verbatim}
805 context conditional {
806     _8XXX => {
807          Dial(SIP/${EXTEN});
808          if ("${DIALSTATUS}" = "BUSY")
809          {
810               NoOp(yessir);
811               Voicemail(${EXTEN}|b);
812          }
813          else
814               Voicemail(${EXTEN}|u);
815          ifTime (14:00-25:00|sat-sun|*|*) 
816               Voicemail(${EXTEN}|b);
817          else
818          {
819               Voicemail(${EXTEN}|u);
820               NoOp(hi, there!);
821          }
822          random(51) NoOp(This should appear 51% of the time);
823
824          random( 60 )
825          {
826                        NoOp( This should appear 60% of the time );
827          }
828          else
829          {
830                        random(75)
831                        {
832                                NoOp( This should appear 30% of the time! );
833                        }
834                        else
835                        {
836                                NoOp( This should appear 10% of the time! );
837                        }
838           }
839     }
840     _777X => {
841          switch (${EXTEN}) {
842               case 7771:
843                    NoOp(You called 7771!);
844                    break;
845               case 7772:
846                    NoOp(You called 7772!);
847                    break;
848               case 7773:
849                    NoOp(You called 7773!);
850                    // fall thru-
851               pattern 777[4-9]:
852                     NoOp(You called 777 something!);
853               default:
854                    NoOp(In the default clause!);
855          }
856     }
857 }
858 \end{verbatim}
859
860 NOTE: The conditional expression in if() statements (the
861       "\${DIALSTATUS}" = "BUSY" above) is wrapped by the compiler in 
862       \$[] for evaluation.
863
864 NOTE: Neither the switch nor case values are wrapped in \$[ ]; they can
865       be constants, or \${var} type references only.
866
867 NOTE: AEL generates each case as a separate extension. case clauses
868       with no terminating 'break', or 'goto', have a goto inserted, to
869       the next clause, which creates a 'fall thru' effect.
870
871 NOTE: AEL introduces the ifTime keyword/statement, which works just
872       like the if() statement, but the expression is a time value,
873       exactly like that used by the application GotoIfTime(). See
874       Asterisk cmd GotoIfTime
875
876 NOTE: The pattern statement makes sure the new extension that is
877       created has an '\_' preceding it to make sure asterisk recognizes
878       the extension name as a pattern.
879
880 NOTE: Every character enclosed by the switch expression's parenthesis
881       are included verbatim in the labels generated. So watch out for
882       spaces!
883
884 NOTE: NEW: Previous to version 0.13, the random statement used the
885       "Random()" application, which has been deprecated. It now uses
886       the RAND() function instead, in the GotoIf application.
887
888
889 \subsection{Break, Continue, and Return}
890
891 Three keywords, break, continue, and return, are included in the
892 syntax to provide flow of control to loops, and switches.
893
894 The break can be used in switches and loops, to jump to the end of the
895 loop or switch.
896
897 The continue can be used in loops (while and for) to immediately jump
898 to the end of the loop. In the case of a for loop, the increment and
899 test will then be performed. In the case of the while loop, the
900 continue will jump to the test at the top of the loop.
901
902 The return keyword will cause an immediate jump to the end of the
903 context, or macro, and can be used anywhere.
904
905
906
907 \subsection{goto, jump, and labels}
908
909 This is an example of how to do a goto in AEL.
910
911 \begin{verbatim}
912 context gotoexample {
913     s => {
914 begin:
915          NoOp(Infinite Loop!  yay!);
916          Wait(1);
917          goto begin;    // go to label in same extension
918     }
919     3 => {
920             goto s|begin;   // go to label in different extension
921      }
922      4 => {
923             goto gotoexample|s|begin;  // overkill go to label in same context
924      }
925 }
926
927 context gotoexample2 {
928      s =>  {
929    end: 
930            goto gotoexample|s|begin;   // go to label in different context
931      }
932 }
933 \end{verbatim}
934
935 You can use the special label of "1" in the goto and jump
936 statements. It means the "first" statement in the extension. I would
937 not advise trying to use numeric labels other than "1" in goto's or
938 jumps, nor would I advise declaring a "1" label anywhere! As a matter
939 of fact, it would be bad form to declare a numeric label, and it might
940 conflict with the priority numbers used internally by asterisk.
941
942 The syntax of the jump statement is: jump
943 extension[,priority][@context] If priority is absent, it defaults to
944 "1". If context is not present, it is assumed to be the same as that
945 which contains the "jump".
946
947 \begin{verbatim}
948 context gotoexample {
949     s => {
950 begin:
951          NoOp(Infinite Loop!  yay!);
952          Wait(1);
953          jump s;    // go to first extension in same extension
954     }
955     3 => {
956             jump s,begin;   // go to label in different extension
957      }
958      4 => {
959             jump s,begin@gotoexample;  // overkill go to label in same context
960      }
961 }
962
963 context gotoexample2 {
964      s =>  {
965    end: 
966            jump s@gotoexample;   // go to label in different context
967      }
968 }
969 \end{verbatim}
970
971 NOTE: goto labels follow the same requirements as the Goto()
972       application, except the last value has to be a label. If the
973       label does not exist, you will have run-time errors. If the
974       label exists, but in a different extension, you have to specify
975       both the extension name and label in the goto, as in: goto s|z;
976       if the label is in a different context, you specify
977       context|extension|label. There is a note about using goto's in a
978       switch statement below...
979
980 NOTE  AEL introduces the special label "1", which is the beginning
981       context number for most extensions.
982
983 NOTE: A NEW addition to AEL: you can now use ',' instead of '|' to 
984       separate the items in the target address. You can't have a mix,
985       though, of '|' and ',' in the target. It's either one, or the other.
986
987
988
989
990 \subsection{Macros}
991
992 A macro is defined in its own block like this. The arguments to the
993 macro are specified with the name of the macro. They are then referred
994 to by that same name. A catch block can be specified to catch special
995 extensions.
996
997 \begin{verbatim}
998 macro std-exten( ext , dev ) {
999        Dial(${dev}/${ext},20);
1000        switch(${DIALSTATUS) {
1001        case BUSY:
1002                Voicemail(b${ext});
1003                break;
1004        default:
1005                Voicemail(u${ext});
1006
1007        }
1008        catch a {
1009                VoiceMailMain(${ext});
1010                return;
1011        }
1012 }
1013 \end{verbatim}
1014
1015 A macro is then called by preceding the macro name with an
1016 ampersand. Empty arguments can be passed simply with nothing between
1017 comments(0.11).
1018
1019 \begin{verbatim}
1020 context example {
1021     _5XXX => &std-exten(${EXTEN}, "IAX2");
1022     _6XXX => &std-exten(, "IAX2");
1023     _7XXX => &std-exten(${EXTEN},);
1024     _8XXX => &std-exten(,);
1025 }
1026 \end{verbatim}
1027
1028
1029 \section{Examples}
1030
1031 \begin{verbatim}
1032 context demo {
1033     s => {
1034          Wait(1);
1035          Answer();
1036          TIMEOUT(digit)=5;
1037          TIMEOUT(response)=10;
1038 restart:
1039          Background(demo-congrats);
1040 instructions:
1041          for (x=0; ${x} < 3; x=${x} + 1) {
1042               Background(demo-instruct);
1043               WaitExten();
1044          }
1045     }
1046     2 => {
1047          Background(demo-moreinfo);
1048          goto s|instructions;
1049     }
1050     3 => {
1051          LANGUAGE()=fr;
1052          goto s|restart;
1053     }
1054
1055     500 => {
1056          Playback(demo-abouttotry);
1057          Dial(IAX2/guest@misery.digium.com);
1058          Playback(demo-nogo);
1059          goto s|instructions;
1060     }
1061     600 => {
1062          Playback(demo-echotest);
1063          Echo();
1064          Playback(demo-echodone);
1065          goto s|instructions;
1066     }
1067     # => {
1068 hangup:
1069          Playback(demo-thanks);
1070          Hangup();
1071     }
1072     t => goto #|hangup;
1073     i => Playback(invalid);
1074 }
1075 \end{verbatim}
1076
1077
1078 \section{Semantic Checks}
1079
1080
1081 AEL, after parsing, but before compiling, traverses the dialplan
1082 tree, and makes several checks:
1083
1084 \begin{itemize}
1085     \item Macro calls to non-existent macros.
1086     \item Macro calls to contexts.
1087     \item Macro calls with argument count not matching the definition.
1088     \item application call to macro. (missing the '\&')
1089     \item application calls to "GotoIf", "GotoIfTime", "while",
1090       "endwhile", "Random", and "execIf", will generate a message to
1091       consider converting the call to AEL goto, while, etc. constructs.
1092     \item goto a label in an empty extension.
1093     \item goto a non-existent label, either a within-extension,
1094       within-context, or in a different context, or in any included
1095       contexts. Will even check "sister" context references.
1096     \item All the checks done on the time values in the dial plan, are
1097       done on the time values in the ifTime() and includes times:
1098           o the time range has to have two times separated by a dash;
1099           o the times have to be in range of 0 to 24 hours.
1100           o The weekdays have to match the internal list, if they are provided;
1101           o the day of the month, if provided, must be in range of 1 to 31;
1102           o the month name or names have to match those in the internal list. 
1103     \item (0.5) If an expression is wrapped in \$[ ... ], and the compiler
1104       will wrap it again, a warning is issued.
1105     \item (0.5) If an expression had operators (you know,
1106       +,-,*,/,%,!,etc), but no \${ } variables, a warning is
1107       issued. Maybe someone forgot to wrap a variable name?
1108     \item (0.12) check for duplicate context names.
1109     \item (0.12) check for abstract contexts that are not included by any context.
1110     \item (0.13) Issue a warning if a label is a numeric value. 
1111 \end{itemize}
1112
1113 There are a subset of checks that have been removed until the proposed
1114 AAL (Asterisk Argument Language) is developed and incorporated into Asterisk.
1115 These checks will be:
1116
1117 \begin{itemize}
1118     \item (if the application argument analyzer is working: the presence
1119       of the 'j' option is reported as error.
1120     \item if options are specified, that are not available in an
1121       application.
1122     \item if you specify too many arguments to an application.
1123     \item a required argument is not present in an application call.
1124     \item Switch-case using "known" variables that applications set, that
1125       does not cover all the possible values. (a "default" case will
1126       solve this problem. Each "unhandled" value is listed.
1127     \item a Switch construct is used, which is uses a known variable, and
1128       the application that would set that variable is not called in
1129       the same extension. This is a warning only...
1130     \item Calls to applications not in the "applist" database (installed
1131       in /var/lib/asterisk/applist" on most systems).
1132     \item In an assignment statement, if the assignment is to a function,
1133       the function name used is checked to see if it one of the
1134       currently known functions. A warning is issued if it is not.
1135 \end{itemize}
1136
1137 \section{Differences with the original version of AEL}
1138
1139 \begin{enumerate}
1140    \item The \$[...] expressions have been enhanced to include the ==, ||,
1141       and \&\& operators. These operators are exactly equivalent to the
1142       =, |, and \& operators, respectively. Why? So the C, Java, C++
1143       hackers feel at home here.
1144    \item It is more free-form. The newline character means very little,
1145       and is pulled out of the white-space only for line numbers in
1146       error messages.
1147    \item It generates more error messages -- by this I mean that any
1148       difference between the input and the grammar are reported, by
1149       file, line number, and column.
1150    \item It checks the contents of \$[ ] expressions (or what will end up
1151       being \$[ ] expressions!) for syntax errors. It also does
1152       matching paren/bracket counts.
1153    \item It runs several semantic checks after the parsing is over, but
1154       before the compiling begins, see the list above.
1155    \item It handles \#include "filepath" directives. -- ALMOST
1156       anywhere, in fact. You could easily include a file in a context,
1157       in an extension, or at the root level. Files can be included in
1158       files that are included in files, down to 50 levels of hierarchy...
1159    \item Local Goto's inside Switch statements automatically have the
1160       extension of the location of the switch statement appended to them.
1161    \item A pretty printer function is available within pbx\_ael.so.
1162    \item In the utils directory, two standalone programs are supplied for
1163       debugging AEL files. One is called "aelparse", and it reads in
1164       the /etc/asterisk/extensions.ael file, and shows the results of
1165       syntax and semantic checking on stdout, and also shows the
1166       results of compilation to stdout. The other is "aelparse1",
1167       which uses the original ael compiler to do the same work,
1168       reading in "/etc/asterisk/extensions.ael", using the original
1169       'pbx\_ael.so' instead.
1170   \item AEL supports the "jump" statement, and the "pattern" statement
1171       in switch constructs. Hopefully these will be documented in the
1172       AEL README.
1173   \item Added the "return" keyword, which will jump to the end of an
1174       extension/Macro.
1175   \item Added the ifTime ($<$time range$>$|$<$days of week$>$|$<$days of
1176       month$>$|$<$months$>$ ) {} [else {}] construct, which executes much
1177       like an if () statement, but the decision is based on the
1178       current time, and the time spec provided in the ifTime. See the
1179       example above. (Note: all the other time-dependent Applications
1180       can be used via ifTime)
1181   \item Added the optional time spec to the contexts in the includes
1182       construct. See examples above.
1183   \item You don't have to wrap a single "true" statement in curly
1184       braces, as in the original AEL. An "else" is attached to the
1185       closest if. As usual, be careful about nested if statements!
1186       When in doubt, use curlies!
1187   \item Added the syntax [regexten] [hint(channel)] to precede an
1188       extension declaration. See examples above, under
1189       "Extension". The regexten keyword will cause the priorities in
1190       the extension to begin with 2 instead of 1. The hint keyword
1191       will cause its arguments to be inserted in the extension under
1192       the hint priority. They are both optional, of course, but the
1193       order is fixed at the moment-- the regexten must come before the
1194       hint, if they are both present.
1195   \item Empty case/default/pattern statements will "fall thru" as
1196       expected. (0.6)
1197   \item A trailing label in an extension, will automatically have a
1198       NoOp() added, to make sure the label exists in the extension on
1199       Asterisk. (0.6)
1200   \item (0.9) the semicolon is no longer required after a closing brace!
1201       (i.e. "];" ===$>$ "\}". You can have them there if you like, but
1202       they are not necessary. Someday they may be rejected as a syntax
1203       error, maybe.
1204   \item (0.9) the // comments are not recognized and removed in the
1205       spots where expressions are gathered, nor in application call
1206       arguments. You may have to move a comment if you get errors in
1207       existing files.
1208   \item (0.10) the random statement has been added. Syntax: random (
1209       $<$expr$>$ ) $<$lucky-statement$>$ [ else $<$unlucky-statement$>$ ]. The
1210       probability of the lucky-statement getting executed is $<$expr$>$,
1211       which should evaluate to an integer between 0 and 100. If the
1212       $<$lucky-statement$>$ isn't so lucky this time around, then the
1213       $<$unlucky-statement$>$ gets executed, if it is present.
1214 \end{enumerate}
1215
1216
1217 \section{Hints and Bugs}
1218
1219      The safest way to check for a null strings is to say \$[ "\${x}" =
1220      "" ] The old way would do as shell scripts often do, and append
1221      something on both sides, like this: \$[ \${x}foo = foo ]. The
1222      trouble with the old way, is that, if x contains any spaces, then
1223      problems occur, usually syntax errors. It is better practice and
1224      safer wrap all such tests with double quotes! Also, there are now
1225      some functions that can be used in a variable reference,
1226      ISNULL(), and LEN(), that can be used to test for an empty string:
1227      \${ISNULL(\${x})} or \$[ \${LEN(\${x}) = 0 ].
1228
1229       Assignment vs. Set(). Keep in mind that setting a variable to
1230       value can be done two different ways. If you choose say 'x=y;',
1231       keep in mind that AEL will wrap the right-hand-side with
1232       \$[]. So, when compiled into extension language format, the end
1233       result will be 'Set(x=\$[y])'. If you don't want this effect,
1234       then say "Set(x=y);" instead.
1235
1236
1237 \section{The Full Power of AEL}
1238
1239 A newcomer to Asterisk will look at the above constructs and
1240 descriptions, and ask, "Where's the string manipulation functions?",
1241 "Where's all the cool operators that other languages have to offer?",
1242 etc.
1243
1244 The answer is that the rich capabilities of Asterisk are made
1245 available through AEL, via:
1246
1247 \begin{itemize}
1248     \item Applications: See Asterisk - documentation of application
1249       commands
1250
1251     \item Functions: Functions were implemented inside \${ .. } variable
1252       references, and supply many useful capabilities. 
1253
1254     \item Expressions: An expression evaluation engine handles items
1255       wrapped inside \$[...]. This includes some string manipulation
1256       facilities, arithmetic expressions, etc. 
1257
1258     \item Application Gateway Interface: Asterisk can fork external
1259       processes that communicate via pipe. AGI applications can be
1260       written in any language. Very powerful applications can be added
1261       this way. 
1262
1263     \item Variables: Channels of communication have variables associated
1264       with them, and asterisk provides some global variables. These can be
1265       manipulated and/or consulted by the above mechanisms. 
1266 \end{itemize}