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