More spelling fixes (issue 7930)
[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 itself. 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 AEL 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 stimuli, 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 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 AEL 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 The ability to make extensions match by CID is preserved in
585 AEL; just use '/' and the CID number in the specification. See below.
586
587
588 context default {
589
590     regexten _5XXX => NoOp(it's a pattern!);
591 }
592
593
594
595 context default {
596
597     hint(Sip/1) _5XXX => NoOp(it's a pattern!);
598 }
599
600
601
602 context default {
603
604     regexten hint(Sip/1) _5XXX => NoOp(it's a pattern!);
605 }
606
607
608 The regexten must come before the hint if they are both present.
609
610 CID matching is done as with the extensions.conf file. Follow the extension
611 name/number with a slash (/) and the number to match against the Caller ID:
612
613 context zoombo 
614 {
615         819/7079953345 => { NoOp(hello, 3345); }
616 }
617
618 In the above,  the 819/7079953345 extension will only be matched if the
619 CallerID is 7079953345, and the dialed number is 819. Hopefully you have
620 another 819 extension defined for all those who wish 819, that are not so lucky
621 as to have 7079953345 as their CallerID!
622
623
624 Includes
625 ========
626
627 Contexts can be included in other contexts. All included contexts are
628 listed within a single block.
629
630
631 context default {
632     includes {
633          local;
634          longdistance;
635          international;
636     }
637 }
638
639
640 Time-limited inclusions can be specified, as in extensions.conf
641 format, with the fields described in the wiki page Asterisk cmd
642 GotoIfTime.
643
644
645 context default {
646     includes {
647          local;
648          longdistance|16:00-23:59|mon-fri|*|*;
649          international;
650     }
651 }
652
653
654 #include
655 ========
656
657 You can include other files with the #include "filepath" construct.
658
659
660    #include "/etc/asterisk/testfor.ael"
661
662
663 An interesting property of the #include, is that you can use it almost
664 anywhere in the .ael file. It is possible to include the contents of
665 a file in a macro, context, or even extension.  The #include does not
666 have to occur at the beginning of a line. Included files can include
667 other files, up to 50 levels deep. If the path provided in quotes is a
668 relative path, the parser looks in the config file directory for the
669 file (usually /etc/asterisk).
670
671
672
673 Dialplan Switches
674 =================
675
676 Switches are listed in their own block within a context. For clues as
677 to what these are used for, see Asterisk - dual servers, and Asterisk
678 config extensions.conf.
679
680
681 context default {
682     switches {
683          DUNDi/e164;
684          IAX2/box5;
685     };
686     eswitches {
687          IAX2/context@${CURSERVER};
688     }
689 }
690
691
692
693 Ignorepat
694 =========
695
696 ignorepat can be used to instruct channel drivers to not cancel
697 dialtone upon receipt of a particular pattern. The most commonly used
698 example is '9'.
699
700
701 context outgoing {
702     ignorepat => 9;
703 }
704
705
706
707
708 Variables
709 =========
710
711 Variables in Asterisk do not have a type, so to define a variable, it
712 just has to be specified with a value.
713
714 Global variables are set in their own block.
715
716
717 globals {
718     CONSOLE=Console/dsp;
719     TRUNK=Zap/g2;
720 }
721
722
723
724 Variables can be set within extensions as well.
725
726
727 context foo {
728     555 => {
729          x=5;
730          y=blah;
731          divexample=10/2
732          NoOp(x is ${x} and y is ${y} !);
733     }
734 }
735
736
737 NOTE: AEL wraps the right hand side of an assignment with $[ ] to allow 
738 expressions to be used If this is unwanted, you can protect the right hand 
739 side from being wrapped by using the Set() application. 
740 Read the README.variables about the requirements and behavior 
741 of $[ ] expressions.
742
743 NOTE: These things are wrapped up in a $[ ] expression: The while() test; 
744 the if() test; the middle expression in the for( x; y; z) statement 
745 (the y expression); Assignments - the right hand side, so a = b -> Set(a=$[b])
746
747 Writing to a dialplan function is treated the same as writing to a variable.
748
749
750 context blah {
751     s => {
752          CALLERID(name)=ChickenMan;
753          NoOp(My name is ${CALLERID(name)} !);
754     }
755
756
757
758
759 Loops
760 =====
761
762 AEL has implementations of 'for' and 'while' loops.
763
764
765 context loops {
766     1 => {
767          for (x=0; ${x} < 3; x=${x} + 1) {
768               Verbose(x is ${x} !);
769          }
770     }
771     2 => {
772          y=10;
773          while (${y} >= 0) {
774               Verbose(y is ${y} !);
775               y=${y}-1;
776          }
777     }
778 }
779
780
781 NOTE: The conditional expression (the "${y} >= 0" above) is wrapped in
782       $[ ] so it can be evaluated.  NOTE: The for loop test expression
783       (the "${x} < 3" above) is wrapped in $[ ] so it can be evaluated.
784
785
786
787 Conditionals
788 ============
789
790 AEL supports if and switch statements, like AEL, but adds ifTime, and
791 random. Unlike the original AEL, though, you do NOT need to put curly
792 braces around a single statement in the "true" branch of an if(), the
793 random(), or an ifTime() statement. The if(), ifTime(), and random()
794 statements allow optional else clause.
795
796
797 context conditional {
798     _8XXX => {
799          Dial(SIP/${EXTEN});
800          if ("${DIALSTATUS}" = "BUSY")
801          {
802               NoOp(yessir);
803               Voicemail(${EXTEN}|b);
804          }
805          else
806               Voicemail(${EXTEN}|u);
807          ifTime (14:00-25:00|sat-sun|*|*) 
808               Voicemail(${EXTEN}|b);
809          else
810          {
811               Voicemail(${EXTEN}|u);
812               NoOp(hi, there!);
813          }
814          random(51) NoOp(This should appear 51% of the time);
815
816          random( 60 )
817          {
818                        NoOp( This should appear 60% of the time );
819          }
820          else
821          {
822                        random(75)
823                        {
824                                NoOp( This should appear 30% of the time! );
825                        }
826                        else
827                        {
828                                NoOp( This should appear 10% of the time! );
829                        }
830           }
831     }
832     _777X => {
833          switch (${EXTEN}) {
834               case 7771:
835                    NoOp(You called 7771!);
836                    break;
837               case 7772:
838                    NoOp(You called 7772!);
839                    break;
840               case 7773:
841                    NoOp(You called 7773!);
842                    // fall thru-
843               pattern 777[4-9]:
844                     NoOp(You called 777 something!);
845               default:
846                    NoOp(In the default clause!);
847          }
848     }
849 }
850
851
852 NOTE: The conditional expression in if() statements (the
853       "${DIALSTATUS}" = "BUSY" above) is wrapped by the compiler in 
854       $[] for evaluation.
855
856 NOTE: Neither the switch nor case values are wrapped in $[ ]; they can
857       be constants, or ${var} type references only.
858
859 NOTE: AEL generates each case as a separate extension. case clauses
860       with no terminating 'break', or 'goto', have a goto inserted, to
861       the next clause, which creates a 'fall thru' effect.
862
863 NOTE: AEL introduces the ifTime keyword/statement, which works just
864       like the if() statement, but the expression is a time value,
865       exactly like that used by the application GotoIfTime(). See
866       Asterisk cmd GotoIfTime
867
868 NOTE: The pattern statement makes sure the new extension that is
869       created has an '_' preceding it to make sure asterisk recognizes
870       the extension name as a pattern.
871
872 NOTE: Every character enclosed by the switch expression's parenthesis
873       are included verbatim in the labels generated. So watch out for
874       spaces!
875
876 NOTE: NEW: Previous to version 0.13, the random statement used the
877       "Random()" application, which has been deprecated. It now uses
878       the RAND() function instead, in the GotoIf application.
879
880
881 Break, Continue, and Return
882 ===========================
883
884
885 Three keywords, break, continue, and return, are included in the
886 syntax to provide flow of control to loops, and switches.
887
888 The break can be used in switches and loops, to jump to the end of the
889 loop or switch.
890
891 The continue can be used in loops (while and for) to immediately jump
892 to the end of the loop. In the case of a for loop, the increment and
893 test will then be performed. In the case of the while loop, the
894 continue will jump to the test at the top of the loop.
895
896 The return keyword will cause an immediate jump to the end of the
897 context, or macro, and can be used anywhere.
898
899
900
901 goto, jump, and labels
902 ======================
903
904 This is an example of how to do a goto in AEL.
905
906
907 context gotoexample {
908     s => {
909 begin:
910          NoOp(Infinite Loop!  yay!);
911          Wait(1);
912          goto begin;    // go to label in same extension
913     }
914     3 => {
915             goto s|begin;   // go to label in different extension
916      }
917      4 => {
918             goto gotoexample|s|begin;  // overkill go to label in same context
919      }
920 }
921
922 context gotoexample2 {
923      s =>  {
924    end: 
925            goto gotoexample|s|begin;   // go to label in different context
926      }
927 }
928
929 You can use the special label of "1" in the goto and jump
930 statements. It means the "first" statement in the extension. I would
931 not advise trying to use numeric labels other than "1" in goto's or
932 jumps, nor would I advise declaring a "1" label anywhere! As a matter
933 of fact, it would be bad form to declare a numeric label, and it might
934 conflict with the priority numbers used internally by asterisk.
935
936 The syntax of the jump statement is: jump
937 extension[,priority][@context] If priority is absent, it defaults to
938 "1". If context is not present, it is assumed to be the same as that
939 which contains the "jump".
940
941
942 context gotoexample {
943     s => {
944 begin:
945          NoOp(Infinite Loop!  yay!);
946          Wait(1);
947          jump s;    // go to first extension in same extension
948     }
949     3 => {
950             jump s,begin;   // go to label in different extension
951      }
952      4 => {
953             jump s,begin@gotoexample;  // overkill go to label in same context
954      }
955 }
956
957 context gotoexample2 {
958      s =>  {
959    end: 
960            jump s@gotoexample;   // go to label in different context
961      }
962 }
963
964 NOTE: goto labels follow the same requirements as the Goto()
965       application, except the last value has to be a label. If the
966       label does not exist, you will have run-time errors. If the
967       label exists, but in a different extension, you have to specify
968       both the extension name and label in the goto, as in: goto s|z;
969       if the label is in a different context, you specify
970       context|extension|label. There is a note about using goto's in a
971       switch statement below...
972
973 NOTE  AEL introduces the special label "1", which is the beginning
974       context number for most extensions.
975
976 NOTE: A NEW addition to AEL: you can now use ',' instead of '|' to 
977       separate the items in the target address. You can't have a mix,
978       though, of '|' and ',' in the target. It's either one, or the other.
979
980
981
982
983 Macros
984 ======
985
986 A macro is defined in its own block like this. The arguments to the
987 macro are specified with the name of the macro. They are then referred
988 to by that same name. A catch block can be specified to catch special
989 extensions.
990
991
992 macro std-exten( ext , dev ) {
993        Dial(${dev}/${ext},20);
994        switch(${DIALSTATUS) {
995        case BUSY:
996                Voicemail(b${ext});
997                break;
998        default:
999                Voicemail(u${ext});
1000
1001        }
1002        catch a {
1003                VoiceMailMain(${ext});
1004                return;
1005        }
1006 }
1007
1008
1009 A macro is then called by preceding the macro name with an
1010 ampersand. Empty arguments can be passed simply with nothing between
1011 comments(0.11).
1012
1013
1014 context example {
1015     _5XXX => &std-exten(${EXTEN}, "IAX2");
1016     _6XXX => &std-exten(, "IAX2");
1017     _7XXX => &std-exten(${EXTEN},);
1018     _8XXX => &std-exten(,);
1019 }
1020
1021
1022
1023 Examples
1024 ========
1025
1026
1027 context demo {
1028     s => {
1029          Wait(1);
1030          Answer();
1031          TIMEOUT(digit)=5;
1032          TIMEOUT(response)=10;
1033 restart:
1034          Background(demo-congrats);
1035 instructions:
1036          for (x=0; ${x} < 3; x=${x} + 1) {
1037               Background(demo-instruct);
1038               WaitExten();
1039          }
1040     }
1041     2 => {
1042          Background(demo-moreinfo);
1043          goto s|instructions;
1044     }
1045     3 => {
1046          LANGUAGE()=fr;
1047          goto s|restart;
1048     }
1049
1050     500 => {
1051          Playback(demo-abouttotry);
1052          Dial(IAX2/guest@misery.digium.com);
1053          Playback(demo-nogo);
1054          goto s|instructions;
1055     }
1056     600 => {
1057          Playback(demo-echotest);
1058          Echo();
1059          Playback(demo-echodone);
1060          goto s|instructions;
1061     }
1062     # => {
1063 hangup:
1064          Playback(demo-thanks);
1065          Hangup();
1066     }
1067     t => goto #|hangup;
1068     i => Playback(invalid);
1069 }
1070
1071
1072 Semantic Checks
1073 ===============
1074
1075
1076 AEL, after parsing, but before compiling, traverses the dialplan
1077 tree, and makes several checks:
1078
1079     * Macro calls to non-existent macros.
1080     * Macro calls to contexts.
1081     * Macro calls with argument count not matching the definition.
1082     * application call to macro. (missing the '&')
1083     * application calls to "GotoIf", "GotoIfTime", "while",
1084       "endwhile", "Random", and "execIf", will generate a message to
1085       consider converting the call to AEL goto, while, etc. constructs.
1086     * goto a label in an empty extension.
1087     * goto a non-existent label, either a within-extension,
1088       within-context, or in a different context, or in any included
1089       contexts. Will even check "sister" context references.
1090     * All the checks done on the time values in the dial plan, are
1091       done on the time values in the ifTime() and includes times:
1092           o the time range has to have two times separated by a dash;
1093           o the times have to be in range of 0 to 24 hours.
1094           o The weekdays have to match the internal list, if they are provided;
1095           o the day of the month, if provided, must be in range of 1 to 31;
1096           o the month name or names have to match those in the internal list. 
1097     * (0.5) If an expression is wrapped in $[ ... ], and the compiler
1098       will wrap it again, a warning is issued.
1099     * (0.5) If an expression had operators (you know,
1100       +,-,*,/,%,!,etc), but no ${ } variables, a warning is
1101       issued. Maybe someone forgot to wrap a variable name?
1102     * (0.12) check for duplicate context names.
1103     * (0.12) check for abstract contexts that are not included by any context.
1104     * (0.13) Issue a warning if a label is a numeric value. 
1105
1106 There are a subset of checks that have been removed until the proposed
1107 AAL (Asterisk Argument Language) is developed and incorporated into Asterisk.
1108 These checks will be:
1109
1110     * (if the application argument analyzer is working: the presence
1111       of the 'j' option is reported as error.
1112     * if options are specified, that are not available in an
1113       application.
1114     * if you specify too many arguments to an application.
1115     * a required argument is not present in an application call.
1116     * Switch-case using "known" variables that applications set, that
1117       does not cover all the possible values. (a "default" case will
1118       solve this problem. Each "unhandled" value is listed.
1119     * a Switch construct is used, which is uses a known variable, and
1120       the application that would set that variable is not called in
1121       the same extension. This is a warning only...
1122     * Calls to applications not in the "applist" database (installed
1123       in /var/lib/asterisk/applist" on most systems).
1124     * In an assignment statement, if the assignment is to a function,
1125       the function name used is checked to see if it one of the
1126       currently known functions. A warning is issued if it is not.
1127
1128
1129
1130 Differences with the original version of AEL
1131 ============================================
1132
1133    1. The $[...] expressions have been enhanced to include the ==, ||,
1134       and && operators. These operators are exactly equivalent to the
1135       =, |, and & operators, respectively. Why? So the C, Java, C++
1136       hackers feel at home here.
1137    2. It is more free-form. The newline character means very little,
1138       and is pulled out of the white-space only for line numbers in
1139       error messages.
1140    3. It generates more error messages -- by this I mean that any
1141       difference between the input and the grammar are reported, by
1142       file, line number, and column.
1143    4. It checks the contents of $[ ] expressions (or what will end up
1144       being $[ ] expressions!) for syntax errors. It also does
1145       matching paren/bracket counts.
1146    5. It runs several semantic checks after the parsing is over, but
1147       before the compiling begins, see the list above.
1148    6. It handles #include "filepath" directives. -- ALMOST
1149       anywhere, in fact. You could easily include a file in a context,
1150       in an extension, or at the root level. Files can be included in
1151       files that are included in files, down to 50 levels of hierarchy...
1152    7. Local Goto's inside Switch statements automatically have the
1153       extension of the location of the switch statement appended to them.
1154    8. A pretty printer function is available within pbx_ael.so.
1155    9. In the utils directory, two standalone programs are supplied for
1156       debugging AEL files. One is called "aelparse", and it reads in
1157       the /etc/asterisk/extensions.ael file, and shows the results of
1158       syntax and semantic checking on stdout, and also shows the
1159       results of compilation to stdout. The other is "aelparse1",
1160       which uses the original ael compiler to do the same work,
1161       reading in "/etc/asterisk/extensions.ael", using the original
1162       'pbx_ael.so' instead.
1163   10. AEL supports the "jump" statement, and the "pattern" statement
1164       in switch constructs. Hopefully these will be documented in the
1165       AEL README.
1166   11. Added the "return" keyword, which will jump to the end of an
1167       extension/Macro.
1168   12. Added the ifTime (<time range>|<days of week>|<days of
1169       month>|<months> ) {} [else {}] construct, which executes much
1170       like an if () statement, but the decision is based on the
1171       current time, and the time spec provided in the ifTime. See the
1172       example above. (Note: all the other time-dependent Applications
1173       can be used via ifTime)
1174   13. Added the optional time spec to the contexts in the includes
1175       construct. See examples above.
1176   14. You don't have to wrap a single "true" statement in curly
1177       braces, as in the original AEL. An "else" is attached to the
1178       closest if. As usual, be careful about nested if statements!
1179       When in doubt, use curlies!
1180   15. Added the syntax [regexten] [hint(channel)] to precede an
1181       extension declaration. See examples above, under
1182       "Extension". The regexten keyword will cause the priorities in
1183       the extension to begin with 2 instead of 1. The hint keyword
1184       will cause its arguments to be inserted in the extension under
1185       the hint priority. They are both optional, of course, but the
1186       order is fixed at the moment-- the regexten must come before the
1187       hint, if they are both present.
1188   16. Empty case/default/pattern statements will "fall thru" as
1189       expected. (0.6)
1190   17. A trailing label in an extension, will automatically have a
1191       NoOp() added, to make sure the label exists in the extension on
1192       Asterisk. (0.6)
1193   18. (0.9) the semicolon is no longer required after a closing brace!
1194       (i.e. "];" ===> "}". You can have them there if you like, but
1195       they are not necessary. Someday they may be rejected as a syntax
1196       error, maybe.
1197   19. (0.9) the // comments are not recognized and removed in the
1198       spots where expressions are gathered, nor in application call
1199       arguments. You may have to move a comment if you get errors in
1200       existing files.
1201   20. (0.10) the random statement has been added. Syntax: random (
1202       <expr> ) <lucky-statement> [ else <unlucky-statement> ]. The
1203       probability of the lucky-statement getting executed is <expr>,
1204       which should evaluate to an integer between 0 and 100. If the
1205       <lucky-statement> isn't so lucky this time around, then the
1206       <unlucky-statement> gets executed, if it is present.
1207
1208
1209
1210 Hints and Bugs
1211 ==============
1212
1213     * The safest way to check for a null strings is to say $[ "${x}" =
1214      "" ] The old way would do as shell scripts often do, and append
1215      something on both sides, like this: $[ ${x}foo = foo ]. The
1216      trouble with the old way, is that, if x contains any spaces, then
1217      problems occur, usually syntax errors. It is better practice and
1218      safer wrap all such tests with double quotes! Also, there are now
1219      some functions that can be used in a variable reference,
1220      ISNULL(), and LEN(), that can be used to test for an empty string:
1221      ${ISNULL(${x})} or $[ ${LEN(${x}) = 0 ].
1222
1223     * Assignment vs. Set(). Keep in mind that setting a variable to
1224       value can be done two different ways. If you choose say 'x=y;',
1225       keep in mind that AEL will wrap the right-hand-side with
1226       $[]. So, when compiled into extension language format, the end
1227       result will be 'Set(x=$[y])'. If you don't want this effect,
1228       then say "Set(x=y);" instead.
1229
1230
1231 The Full Power of AEL
1232 ==============================
1233
1234 A newcomer to Asterisk will look at the above constructs and
1235 descriptions, and ask, "Where's the string manipulation functions?",
1236 "Where's all the cool operators that other languages have to offer?",
1237 etc.
1238
1239 The answer is that the rich capabilities of Asterisk are made
1240 available through AEL, via:
1241
1242     * Applications: See Asterisk - documentation of application
1243       commands
1244
1245     * Functions: Functions were implemented inside ${ .. } variable
1246       references, and supply many useful capabilities. 
1247
1248     * Expressions: An expression evaluation engine handles items
1249       wrapped inside $[...]. This includes some string manipulation
1250       facilities, arithmetic expressions, etc. 
1251
1252     * Application Gateway Interface: Asterisk can fork external
1253       processes that communicate via pipe. AGI applications can be
1254       written in any language. Very powerful applications can be added
1255       this way. 
1256
1257     * Variables: Channels of communication have variables associated
1258       with them, and asterisk provides some global variables. These can be
1259       manipulated and/or consulted by the above mechanisms. 
1260