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