[asterisk-commits] branch murf/AEL2 r11945 -
/team/murf/AEL2/doc/ael2.txt
asterisk-commits at lists.digium.com
asterisk-commits at lists.digium.com
Sun Mar 5 17:00:20 MST 2006
Author: murf
Date: Sun Mar 5 18:00:18 2006
New Revision: 11945
URL: http://svn.digium.com/view/asterisk?rev=11945&view=rev
Log:
Updated the ael2.txt file to include all the info on the Wiki Page.
Modified:
team/murf/AEL2/doc/ael2.txt
Modified: team/murf/AEL2/doc/ael2.txt
URL: http://svn.digium.com/view/asterisk/team/murf/AEL2/doc/ael2.txt?rev=11945&r1=11944&r2=11945&view=diff
==============================================================================
--- team/murf/AEL2/doc/ael2.txt (original)
+++ team/murf/AEL2/doc/ael2.txt Sun Mar 5 18:00:18 2006
@@ -1,226 +1,302 @@
The Asterisk Extension Language - v 2
=====================================
-AEL2 is a "rewrite" of the AEL parser, to provide
-better diagnostics, error checking, and is a bit more modular
-in design. Fundamentally, it does the same thing as the current
-ael compiler: it reads in the AEL dialplan, and builds contexts,
-extensions and priorities in asterisk.
-
-The BIG differences:
-
-1. It reads in "/etc/asterisk/extensions.ael2", instead of extensions.ael
-2. It is more free-form. The newline character means very little, and is
- pulled out of the white-space only for line numbers in error messages.
-3. It generates more error messages -- by this I mean that any difference
- between the input and the grammar are reported, by file, line number, and
- column.
-4. It checks the contents of $[ ] expressions (or what will end up being $[ ]
- expressions!) for syntax errors. It also does matching paren/bracket counts.
-5. It runs several semantic checks after the parsing is over, but before
- the compiling begins, and issues these warnings and errors:
- a. (if the application argument analyzer is working: the presence of the
- 'j' option is reported as error.
- b. if options are specified, that are not available in an application.
- c. if you specify too many arguments to an application.
- d. a required argument is not present in an application call.
- e. Switch-case using "known" variables that applications set, that does
- not cover all the possible values. (a "default" case will solve this
- problem. Each "unhandled" value is listed.
- f. a Switch construct is used, which is uses a known variable, and the
- application that would set that variable is not called in the same
- extension. This is a warning only...
- g. Macro calls to non-existent macros.
- h. Macro calls to contexts.
- i. Macro calls with argument count not matching the definition.
- j. application call to macro.
- k. application calls to "GotoIf", "GotoIfTime", "while", "endwhile",
- "Random", and "execIf", will generate a message to consider converting the
- call to AEL goto, while, etc. constructs.
- l. Calls to applications not in the "applist" database (installed in
- /var/lib/asterisk/applist" on most systems).
- m. goto a label in an empty extension.
- n. goto a non-existent label, either a within-extension, within-context,
- or in a different context, or in any included contexts.
- o. All the checks done on the time values in the dial plan, are done on
- the time values in the ifTime() and includes times: the time range
- has to have two times separated by a dash; the times have to be in
- range of 0 to 24 hours. The weekdays have to match the list, if provided;
- the day of the month, if provided, must be in range of 1 to 31; the month
- name or names have to match those in the internal list.
- p. Check all expressions that will be wrapped with $[] to make sure they
- aren't already wrapped in $[], and issue warning.
- q. Check $[] expressions for a combination of an operator, with no
- variable references, and issue warning if found. It could be, that the
- user forgot to wrap a variable name with ${}.
-
-6. It handles #include "filepath" directives. -- ALMOST anywhere, in fact.
- You could easily include a file in a context, in an extension, or at the
- root level. Files can be included in files that are included in files, down
- to 50 levels of hierarchy...
-7. Local Goto's inside Switch statements automatically have the extension of the
- location of the switch statement appended to them.
-8. A pretty printer function is available within pbx_ael2.so.
-9. In the utils directory, two standalone programs are supplied for debugging
- AEL files. One is called "aelparse", and it reads in the
- /etc/asterisk/extensions.ael2 file, and shows the results of syntax and semantic
- checking on stdout, and also shows the results of compilation to stdout.
- The other is "aelparse1", which uses the original ael compiler to do the same
- work, reading in "/etc/asterisk/extensions.ael", instead.
-10. AEL2 supports the "jump" statement, and the "pattern" statement in
- switch constructs. Hopefully these will be documented in the AEL README.
-11. Added the "return" keyword, which will jump to the end of an extension/Macro.
-12. Added the ifTime (<time range>|<days of week>|<days of month>|<months> ) {} [else {}]
- construct, which executes much like an if () statement, but the decision is based
- on the current time, and the time spec provided in the ifTime. You can use
- it in this fashion:
- ifTime(14:00-25:00|sat-sun|*|*)
- {
- BackGround(Hello);
- }
- else
- BackGround(Sorry);
- (Note: all the other time-dependent Applications can be used via ifTime)
-
-13. Added the optional time spec to the contexts in the includes construct.
- You can enter the 4 time values like this:
- includes {
- other|16:00-23:59|mon-fri|*|*;
- }
-14. There is no restriction about using {}'s in the if or ifTime statements. In
- other words, you can say this:
-
- ifTime(14:00-25:00|sat-sun|*|*)
- BackGround(Hello);
- else
- BackGround(Sorry);
-
- (you don't have to wrap a single "true" statement in curly braces, as in the
- orignal ael). This creates a conflict in the grammar, but the parser "shifts"
- in this case, and the result is that an "else" is attached to the closest if.
- So, stating something like this:
-
- ifTime(14:00-23:00|sat-sun|*|*)
- ifTime(18:00-23:00|sat-sun|*|*)
- BackGround(Hello);
- else
- BackGround(Sorry);
-
- results in the else being associated with the second "ifTime". As usual, be
- careful about nested if statements! When in doubt, use curlies!
-
-15. Added the syntax [regexten] [hint(channel)] to preceed an extension declaration.
- You can now say things like this:
- regexten hint(SIP/1) 123 => {
- NoOp(hello there);
- }
-
- The regexten keyword will cause the priorities in the extension to begin
- with 2 instead of 1. The hint keyword will cause its arguments to be inserted
- in the extension under the hint priority. They are both optional, of course,
- but the order is fixed at the moment-- the regexten must come before the hint.
-16. A small enhancement-- syntax errors are published with internal token names
- used in the bison/flex files. Added code to substitute SEMI with ';', etc, so the
- users are not confused by the notation.
-17. The ';' after a closing brace '}' is now optional. All extraneous ';' at ALMOST
- every level will be silently ignored. Consider the ';' after '}' obsolesced. At
- some point in the future, we might do away with them entirely. All AEL2 docs will
- stop mentioning them, or using them. Users will not have to edit them out of
- .ael files to make them .ael2 files.
-18. Comments-- // is still used as comments, but comments are not recognized inside
- areas where $[ ] strings are gathered, nor in application call arguments. This
- way, we get rid of a situation where //'s are removed unexpectedly, as part of
- the arguments to the CURL or AGI applications. Comments will not be recognized
- and removed in assignment statements, before the terminating semicolon.
-19. There WAS one more Application that provided flow of control, the Random()
- application. I have introduced the random(x)<statement>[else statement] statement.
- it takes one numeric arg, which should evaluate to a number between 0 and 100,
- which represents the probability of the "true" statement getting flow of control.
- the else statements, if present, gets flow of control the remaining (100-x) percent
- of the time. The numeric arg will be enclosed in $[...], and therefore, can
- be an expression, a constant, or a simple variable ref.
-
-
-DEBUG
-=====
-
-If things are going wrong in your dialplan, you can use the following facilities
-to debug your file:
+AEL2 is a new version of the AEL compiler, written by Steve Murphy.
+
+AEL2 (like AEL) is considered an EXPERIMENTAL Version. (yet is being
+used in the field with success)
+
+AEL2 is intended to provide an actual programming language that can be
+used to write an Asterisk dialplan. It further extends AEL, and
+provides more flexible syntax, better error messages, and some missing
+functionality.
+
+AEL/AEL2 is really the merger of 4 different 'languages', or syntaxes:
+
+ * The first and most obvious is the AEL2 syntax itselft. A BNF is
+ provided near the end of this document.
+
+ * The second syntax is the Expression Syntax, which is normally
+ handled by Asterisk extension engine, as expressions enclosed in
+ $[...]. The right hand side of assignments are wrapped in $[ ... ]
+ by AEL, and so are the if and while expressions, among others.
+
+ * The third syntax is the Variable Reference Syntax, the stuff
+ enclosed in ${..} curly braces. It's a bit more involved than just
+ putting a variable name in there. You can include one of dozens of
+ 'functions', and their arguments, and there are even some string
+ manipulation notation in there.
+
+ * The last syntax that underlies AEL/AEL2, and is not used
+ directly in AEL/AEL2, is the Extension Language Syntax. The
+ extension language is what you see in extensions.conf, and AEL2
+ compiles the higher level AEL2 language into extensions and
+ priorities, and passes them via function calls into
+ Asterisk. Embedded in this language is the Application/AGI
+ commands, of which one application call per step, or priority
+ can be made. You can think of this as a "macro assembler"
+ language, that AEL2 will compile into.
+
+
+Any programmer of AEL2 should be familiar with it's syntax, of course,
+as well as the Expression syntax, and the Variable syntax.
+
+**************************
+* Asterisk in a Nutshell *
+**************************
+
+Asterisk acts as a server. Devices involved in telephony, like Zapata
+cards, or Voip phones, all indicate some context that should be
+activated in their behalf. See the config file formats for IAX, SIP,
+zapata.conf, etc. They all help describe a device, and they all
+specify a context to activate when somebody picks up a phone, or a
+call comes in from the phone company, or a voip phone, etc.
+
+Contexts
+--------
+
+Contexts are a grouping of extensions.
+
+Contexts can also include other contexts. Think of it as a sort of
+merge operation at runtime, whereby the included context's extensions
+are added to the contexts making the inclusion.
+
+Extensions and priorities
+-------------------------
+
+A Context contains zero or more Extensions. There are several
+predefined extensions. The "s" extension is the "start" extension, and
+when a device activates a context the "s" extension is the one that is
+going to be run. Other extensions are the timeout "t" extension, the
+invalid response, or "i" extension, and there's a "fax" extension. For
+instance, a normal call will activate the "s" extension, but an
+incoming FAX call will come into the "fax" extension, if it
+exists. (BTW, asterisk can tell it's a fax call by the little "beep"
+that the calling fax machine emits every so many seconds.).
+
+Extensions contain several priorities, which are individual
+instructions to perform. Some are as simple as setting a variable to a
+value. Others are as complex as initiating the Voicemail application,
+for instance. Priorities are executed in order.
+
+When the 's" extension completes, asterisk waits until the timeout for
+a response. If the response matches an extension's pattern in the
+context, then control is transferred to that extension. Usually the
+responses are tones emitted when a user presses a button on their
+phone. For instance, a context associated with a desk phone might not
+have any "s" extension. It just plays a dialtone until someone starts
+hitting numbers on the keypad, gather the number, find a matching
+extension, and begin executing it. That extension might Dial out over
+a connected telephone line for the user, and then connect the two
+lines together.
+
+The extensions can also contain "goto" or "jump" commands to skip to
+extensions in other contexts. Conditionals provide the ability to
+react to different stimiuli, and there you have it.
+
+Macros
+------
+
+Think of a macro as a combination of a context with one nameless
+extension, and a subroutine. It has arguments like a subroutine
+might. A macro call can be made within an extension, and the
+individual statements there are executed until it ends. At this point,
+execution returns to the next statement after the macro call. Macros
+can call other macros. And they work just like function calls.
+
+Applications
+------------
+
+Application calls, like "Dial()", or "Hangup()", or "Answer()", are
+available for users to use to accomplish the work of the
+dialplan. There are over 145 of them at the moment this was written,
+and the list grows as new needs and wants are uncovered. Some
+applications do fairly simple things, some provide amazingly complex
+services.
+
+Hopefully, the above objects will allow you do anything you need to in
+the Asterisk environment!
+
+
+*******************
+* Getting Started *
+*******************
+
+The AEL2 parser (pbx_ael2.so) is completely separate from the module
+that parses extensions.conf (pbx_config.so). To use AEL2, the only
+thing that has to be done is the module pbx_ael2.so must be loaded by
+Asterisk. This will be done automatically if using 'autoload=yes' in
+/etc/asterisk/modules.conf. When the module is loaded, it will look
+for 'extensions.ael2' in /etc/asterisk/. extensions.conf and
+extensions.ael and extensions.ael2 can be used in conjunction with
+each other if that is what is desired. Some users may want to keep
+extensions.conf for the features that are configured in the 'general'
+section of extensions.conf.
+
+------------------------------
+- Reloading extensions.ael2 -
+------------------------------
+
+To reload extensions.ael2, the following command can be issued at the
+CLI:
+
+ *CLI> ael2 reload
+
+
+
+*************
+* Debugging *
+*************
+
+Right at this moment, the following commands are available, but do
+nothing:
+
+Enable AEL2 contexts debug
+ *CLI> ael2 debug contexts
+
+Enable AEL2 macros debug
+ *CLI> ael2 debug macros
+
+Enable AEL2 read debug
+ *CLI> ael2 debug read
+
+Enable AEL2 tokens debug
+ *CLI> ael2 debug tokens
+
+Disable AEL2 debug messages
+ *CLI> ael2 no debug
+
+If things are going wrong in your dialplan, you can use the following
+facilities to debug your file:
1. The messages log in /var/log/asterisk. (from the checks done at load time).
2. the "show dialplan" command in asterisk
3. the standalone executable, "aelparse" built in the utils/ dir in the source.
-You can also use the "aelparse" program to check your extensions.ael2 file before
-feeding it to asterisk. Wouldn't it be nice to eliminate most errors before giving
-the file to asterisk?
-
-
-Syntax
-======
-
-For syntax, refer to the README.ael file. Note that the syntax and
-style are a little more free-form. The opening '{' (curly-braces) do
-not have to be on the same line as the keyword that precedes
-them. Statements can be split across lines, as long as tokens are not
-broken by doing so. More than one statement can be included on a
-single line. Whatever you think is best! You can just as easily say,
-"if(${x}=1) { NoOp(hello!); goto s|3; } else { NoOp(Goodbye!); goto s|12; }" as
-you can say:
-if(${x}=1)
-{
- NoOp(hello!);
- goto s|3;
-}
-else
-{
- NoOp(Goodbye!);
- goto s|12;
-}
-
-or:
-
-if(${x}=1) {
- NoOp(hello!);
- goto s|3;
-} else {
- NoOp(Goodbye!);
- goto s|12;
+You can also use the "aelparse" program to check your extensions.ael2
+file before feeding it to asterisk. Wouldn't it be nice to eliminate
+most errors before giving the file to asterisk?
+
+
+
+******************************
+* General Notes about Syntax *
+******************************
+
+Note that the syntax and style are a little more free-form. The
+opening '{' (curly-braces) do not have to be on the same line as the
+keyword that precedes them. Statements can be split across lines, as
+long as tokens are not broken by doing so. More than one statement can
+be included on a single line. Whatever you think is best!
+
+You can just as easily say,
+
+if(${x}=1) { NoOp(hello!); goto s|3; } else { NoOp(Goodbye!); goto s|12; }
+
+as you can say:
+
+if(${x}=1)
+{
+ NoOp(hello!);
+ goto s|3;
+}
+else
+{
+ NoOp(Goodbye!);
+ goto s|12;
}
or:
-if (${x}=1) {
- NoOp(hello!); goto s|3;
-} else {
- NoOp(Goodbye!); goto s|12;
+if(${x}=1) {
+ NoOp(hello!);
+ goto s|3;
+} else {
+ NoOp(Goodbye!);
+ goto s|12;
+}
+
+or:
+
+if (${x}=1) {
+ NoOp(hello!); goto s|3;
+} else {
+ NoOp(Goodbye!); goto s|12;
}
or even:
-if
+if
(${x}=1)
-{
-NoOp(hello!);
-goto s|3;
-}
-else
-{
-NoOp(Goodbye!);
-goto s|12;
-}
-
-Applications
-============
+{
+NoOp(hello!);
+goto s|3;
+}
+else
+{
+NoOp(Goodbye!);
+goto s|12;
+}
+
+
+************
+* Keywords *
+************
+
+The AEL keywords are case-sensitive. If an application name and a
+keyword overlap, there is probably good reason, and you should
+consider replacing the application call with an AEL2 statement. If you
+do not wish to do so, you can still use the application, by using a
+capitalized letter somewhere in its name. In the Asterisk extension
+language, application names are NOT case-sensitive.
+
+The following are keywords in the AEL2 language:
+
+ * abstract
+ * context
+ * macro
+ * globals
+ * ignorepat
+ * switch
+ * if
+ * ifTime
+ * else
+ * random
+ * goto
+ * jump
+ * return
+ * break
+ * continue
+ * regexten
+ * hint
+ * for
+ * while
+ * case
+ * pattern
+ * default NOTE: the "default" keyword can be used as a context name,
+ for those who would like to do so.
+ * catch
+ * switches
+ * eswitches
+ * includes
+
+
+
+*****************
+* Applications *
+*****************
The file /var/lib/asterisk/applist contains entries for over 140
-applications, including arguments, the names of variables the application
-can or will set, the options, and the list of arguments, optional and
-required. If you use an application that is not in the list, you can
-simply add one, following the syntax of other entries.
-
-Don't fall in love with the specs in the applist file. The format of the
-file, the entries themselves will change in time.
+applications, including arguments, the names of variables the
+application can or will set, the options, and the list of arguments,
+optional and required. If you use an application that is not in the
+list, you can simply add one, following the syntax of other entries.
+
+Don't fall in love with the specs in the applist file. The format of
+the file, the entries themselves will change in time.
+
+
+
Procedural Interface and Internals
==================================
@@ -265,166 +341,881 @@
<file> :== <objects>
<objects> :== <object>
- | <objects> <object>
+ | <objects> <object>
<object> :== <context>
- | <macro>
- | <globals>
- | ';'
-
-
-<context> :== 'context' <word> '{' <elements> '}'
- | 'context' <word> '{' '}'
- | 'context' 'default' '{' <elements> '}'
- | 'context' 'default' '{' '}'
-
-
-<macro> :== 'macro' <word> '(' <arglist> ')' '{' <macro_statements> '}'
- | 'macro' <word> '(' <arglist> ')' '{' '}'
- | 'macro' <word> '(' ')' '{' <macro_statements> '}'
- | 'macro' <word> '(' ')' '{' '}'
-
-
-<globals> :== 'globals' '{' <global_statements> '}'
- | 'globals' '{' '}'
+ | <macro>
+ | <globals>
+ | ';'
+
+
+<context> :== 'context' <word> '{' <elements> '}'
+ | 'context' <word> '{' '}'
+ | 'context' 'default' '{' <elements> '}'
+ | 'context' 'default' '{' '}'
+ | 'abstract' 'context' <word> '{' <elements> '}'
+ | 'abstract' 'context' <word> '{' '}'
+ | 'abstract' 'context' 'default' '{' <elements> '}'
+ | 'abstract' 'context' 'default' '{' '}'
+
+
+<macro> :== 'macro' <word> '(' <arglist> ')' '{' <macro_statements> '}'
+ | 'macro' <word> '(' <arglist> ')' '{' '}'
+ | 'macro' <word> '(' ')' '{' <macro_statements> '}'
+ | 'macro' <word> '(' ')' '{' '}'
+
+
+<globals> :== 'globals' '{' <global_statements> '}'
+ | 'globals' '{' '}'
<global_statements> :== <global_statement>
- | <global_statements> <global_statement>
-
-
-<global_statement> :== <word> '=' <collected-word> ';'
+ | <global_statements> <global_statement>
+
+
+<global_statement> :== <word> '=' <collected-word> ';'
<arglist> :== <word>
- | <arglist> ',' <word>
+ | <arglist> ',' <word>
<elements> :== <element>
- | <elements> <element>
+ | <elements> <element>
<element> :== <extension>
- | <includes>
- | <switches>
- | <eswitches>
- | <ignorepat>
- | <word> '=' <collected-word> ';'
- | ';'
-
-
-<ignorepat> :== 'ignorepat' '=>' <word> ';'
+ | <includes>
+ | <switches>
+ | <eswitches>
+ | <ignorepat>
+ | <word> '=' <collected-word> ';'
+ | ';'
+
+
+<ignorepat> :== 'ignorepat' '=>' <word> ';'
<extension> :== <word> '=>' <statement>
- | 'regexten' <word> '=>' <statement>
- | 'hint' '(' <word3-list> ')' <word> '=>' <statement>
- | 'regexten' 'hint' '(' <word3-list> ')' <word> '=>' <statement>
+ | 'regexten' <word> '=>' <statement>
+ | 'hint' '(' <word3-list> ')' <word> '=>' <statement>
+ | 'regexten' 'hint' '(' <word3-list> ')' <word> '=>' <statement>
<statements> :== <statement>
- | <statements> <statement>
+ | <statements> <statement>
<if_head> :== 'if' '(' <collected-word> ')'
<random_head> :== 'random' '(' <collected-word> ')'
<ifTime_head> :== 'ifTime' '(' <word3-list> ':' <word3-list> ':' <word3-list> '|' <word3-list> '|' <word3-list> '|' <word3-list> ')'
- | 'ifTime' '(' <word> '|' <word3-list> '|' <word3-list> '|' <word3-list> ')'
+ | 'ifTime' '(' <word> '|' <word3-list> '|' <word3-list> '|' <word3-list> ')'
<word3-list> :== <word>
- | <word> <word>
- | <word> <word> <word>
+ | <word> <word>
+ | <word> <word> <word>
<switch_head> :== 'switch' '(' <collected-word> ')' '{'
-
+
<statement> :== '{' <statements> '}'
- | <word> '=' <collected-word> ';'
- | 'goto' <target> ';'
- | 'jump' <jumptarget> ';'
- | <word> ':'
- | 'for' '(' <collected-word> ';' <collected-word> ';' <collected-word> ')' <statement>
- | 'while' '(' <collected-word> ')' <statement>
- | <switch_head> '}'
- | <switch_head> <case_statements> '}'
- | '&' macro_call ';'
- | <application_call> ';'
- | <application_call> '=' <collected-word> ';'
- | 'break' ';'
- | 'return' ';'
- | 'continue' ';'
- | <random_head> <statement>
- | <random_head> <statement> 'else' <statement>
- | <if_head> <statement>
- | <if_head> <statement> 'else' <statement>
- | <ifTime_head> <statement>
- | <ifTime_head> <statement> 'else' <statement>
- | ';'
-
-<target> :== <word>
- | <word> '|' <word>
- | <word> '|' <word> '|' <word>
- | 'default' '|' <word> '|' <word>
+ | <word> '=' <collected-word> ';'
+ | 'goto' <target> ';'
+ | 'jump' <jumptarget> ';'
+ | <word> ':'
+ | 'for' '(' <collected-word> ';' <collected-word> ';' <collected-word> ')' <statement>
+ | 'while' '(' <collected-word> ')' <statement>
+ | <switch_head> '}'
+ | <switch_head> <case_statements> '}'
+ | '&' macro_call ';'
+ | <application_call> ';'
+ | <application_call> '=' <collected-word> ';'
+ | 'break' ';'
+ | 'return' ';'
+ | 'continue' ';'
+ | <random_head> <statement>
+ | <random_head> <statement> 'else' <statement>
+ | <if_head> <statement>
+ | <if_head> <statement> 'else' <statement>
+ | <ifTime_head> <statement>
+ | <ifTime_head> <statement> 'else' <statement>
+ | ';'
+
+<target> :== <word>
+ | <word> '|' <word>
+ | <word> '|' <word> '|' <word>
+ | 'default' '|' <word> '|' <word>
<jumptarget> :== <word>
- | <word> ',' <word>
- | <word> ',' <word> '@' <word>
- | <word> '@' <word>
- | <word> ',' <word> '@' 'default'
- | <word> '@' 'default'
+ | <word> ',' <word>
+ | <word> ',' <word> '@' <word>
+ | <word> '@' <word>
+ | <word> ',' <word> '@' 'default'
+ | <word> '@' 'default'
<macro_call> :== <word> '(' <eval_arglist> ')'
- | <word> '(' ')'
+ | <word> '(' ')'
<application_call_head> :== <word> '('
-<application_call> :== application_call_head <eval_arglist> ')'
- | application_call_head ')'
+<application_call> :== <application_call_head> <eval_arglist> ')'
+ | <application_call_head> ')'
<eval_arglist> :== <collected-word>
- | <eval_arglist> ',' <collected-word>
+ | <eval_arglist> ',' <collected-word>
+ | /* nothing */
+ | <eval_arglist> ',' /* nothing */
<case_statements> :== <case_statement>
- | <case_statements> <case_statement>
+ | <case_statements> <case_statement>
<case_statement> :== 'case' <word> ':' <statements>
- | 'default' ':' <statements>
- | 'pattern' <word> ':' <statements>
- | 'case' <word> ':'
- | 'default' ':'
- | 'pattern' <word> ':'
+ | 'default' ':' <statements>
+ | 'pattern' <word> ':' <statements>
+ | 'case' <word> ':'
+ | 'default' ':'
+ | 'pattern' <word> ':'
<macro_statements> :== <macro_statement>
- | <macro_statements> <macro_statement>
+ | <macro_statements> <macro_statement>
<macro_statement> :== <statement>
- | 'catch' <word> '{' <statements> '}'
+ | 'catch' <word> '{' <statements> '}'
<switches> :== 'switches' '{' <switchlist> '}'
- | 'switches' '{' '}'
-
-eswitches :== 'eswitches' '{' <switchlist> '}'
- | 'eswitches' '{' '}'
+ | 'switches' '{' '}'
+
+<eswitches> :== 'eswitches' '{' <switchlist> '}'
+ | 'eswitches' '{' '}'
<switchlist> :== <word> ';'
- | <switchlist> <word> ';'
+ | <switchlist> <word> ';'
<includeslist> :== <includedname> ';'
- | <includedname> '|' <word3-list> ':' <word3-list> ':' <word3-list> '|' <word3-list> '|' <word3-list> '|' <word3-list> ';'
- | <includedname> '|' <word> '|' <word3-list> '|' <word3-list> '|' <word3-list> ';'
- | <includeslist> <includedname> ';'
- | <includeslist> <includedname> '|' <word3-list> ':' <word3-list> ':' <word3-list> '|' <word3-list> '|' <word3-list> '|' <word3-list> ';'
- | <includeslist> <includedname> '|' <word> '|' <word3-list> '|' <word3-list> '|' <word3-list> ';'
+ | <includedname> '|' <word3-list> ':' <word3-list> ':' <word3-list> '|' <word3-list> '|' <word3-list> '|' <word3-list> ';'
+ | <includedname> '|' <word> '|' <word3-list> '|' <word3-list> '|' <word3-list> ';'
+ | <includeslist> <includedname> ';'
+ | <includeslist> <includedname> '|' <word3-list> ':' <word3-list> ':' <word3-list> '|' <word3-list> '|' <word3-list> '|' <word3-list> ';'
+ | <includeslist> <includedname> '|' <word> '|' <word3-list> '|' <word3-list> '|' <word3-list> ';'
<includedname> :== <word>
- | 'default'
+ | 'default'
<includes> :== 'includes' '{' <includeslist> '}'
- | 'includes' '{' '}'
-
-
-
+ | 'includes' '{' '}'
+
+
+**************************
+* AEL2 Example USAGE *****
+**************************
+
+Comments
+========
+
+Comments begin with // and end with the end of the line.
+
+Comments are removed by the lexical scanner, and will not be
+recognized in places where it is busy gathering expressions to wrap in
+$ , or inside application call argument lists. The safest place to put
+comments is after terminating semicolons, or on otherwise empty lines.
+
+
+Context
+=======
+
+Contexts in AEL represent a set of extensions in the same way that
+they do in extensions.conf.
+
+
+context default {
+
+}
+
+
+A context can be declared to be "abstract", in which case, this
+declaration expresses the intent of the writer, that this context will
+only be included by another context, and not "stand on its own". The
+current effect of this keyword is to prevent "goto " statements from
+being checked.
+
+
+abstract context longdist {
+ _1NXXNXXXXXX => NoOp(generic long distance dialing actions in the US);
+}
+
+
+
+Extensions
+==========
+
+To specify an extension in a context, the following syntax is used. If
+more than one application is be called in an extension, they can be
+listed in order inside of a block.
+
+
+context default {
+ 1234 => Playback(tt-monkeys);
+ 8000 => {
+ NoOp(one);
+ NoOp(two);
+ NoOp(three);
+ };
+ _5XXX => NoOp(it's a pattern!);
+}
+
+
+Two optional items have been added to the AEL2 syntax, that allow the
+specification of hints, and a keyword, regexten, that will force the
+numbering of priorities to start at 2.
+
+
+context default {
+
+ regexten _5XXX => NoOp(it's a pattern!);
+}
+
+
+
+context default {
+
+ hint(Sip/1) _5XXX => NoOp(it's a pattern!);
+}
+
+
+
+context default {
+
+ regexten hint(Sip/1) _5XXX => NoOp(it's a pattern!);
+}
+
+
+The regexten must come before the hint if they are both present.
+
+
+
+Includes
+========
+
+Contexts can be included in other contexts. All included contexts are
+listed within a single block.
+
+
+context default {
+ includes {
+ local;
+ longdistance;
+ international;
+ }
+}
+
+
+Time-limited inclusions can be specified, as in extensions.conf
+format, with the fields described in the wiki page Asterisk cmd
+GotoIfTime.
+
+
+context default {
+ includes {
+ local;
+ longdistance|16:00-23:59|mon-fri|*|*;
+ international;
+ }
+}
+
+
+#include
+========
+
+You can include other files with the #include "filepath" construct.
+
+
+ #include "/etc/asterisk/testfor.ael2"
+
+
+An interesting property of the #include, is that you can use it almost
+anywhere in the .ael2 file. It is possible to include the contents of
+a file in a macro, context, or even extension. The #include does not
+have to occur at the beginning of a line. Included files can include
+other files, up to 50 levels deep. If the path provided in quotes is a
+relative path, the parser looks in the config file directory for the
+file (usually /etc/asterisk).
+
+
+
+Dialplan Switches
+=================
+
+Switches are listed in their own block within a context. For clues as
+to what these are used for, see Asterisk - dual servers, and Asterisk
+config extensions.conf.
+
+
+context default {
+ switches {
+ DUNDi/e164;
+ IAX2/box5;
+ };
+ eswitches {
+ IAX2/context@${CURSERVER};
+ }
+}
+
+
+
+Ignorepat
+=========
+
+ignorepat can be used to instruct channel drivers to not cancel
+dialtone upon receipt of a particular pattern. The most commonly used
+example is '9'.
+
+
+context outgoing {
+ ignorepat => 9;
+}
+
+
+
+
+Variables
+=========
+
+Variables in Asterisk do not have a type, so to define a variable, it
+just has to be specified with a value.
+
+Global variables are set in their own block.
+
+
+globals {
+ CONSOLE=Console/dsp;
+ TRUNK=Zap/g2;
+}
+
+
+
+Variables can be set within extensions as well.
+
+
+context foo {
+ 555 => {
+ x=5;
+ y=blah;
+ divexample=10/2
+ NoOp(x is ${x} and y is ${y} !);
+ }
+}
+
+
+NOTE: AEL wraps the right hand side of an assignment with $[ ] to allow expressions to be used If this is unwanted, you can protect the right hand side from being wrapped by using the Set() application. Read the README.variables about the requirements and behavior of $[ ] expressions.
+
+NOTE: These things are wrapped up in a $[ ] expression: The while() test; the if() test; the middle expression in the for( x; y; z) statement (the y expression); Assignments \u2014 the right hand side, so a = b -> Set(a=$[b])
+
+Writing to a dialplan function is treated the same as writing to a variable.
+
+
+context blah {
+ s => {
+ CALLERID(name)=ChickenMan;
+ NoOp(My name is ${CALLERID(name)} !);
+ }
+}
+
+
+
+Loops
+=====
+
+AEL has implementations of 'for' and 'while' loops.
+
+
+context loops {
+ 1 => {
+ for (x=0; ${x} < 3; x=${x} + 1) {
+ Verbose(x is ${x} !);
+ }
+ }
+ 2 => {
+ y=10;
+ while (${y} >= 0) {
+ Verbose(y is ${y} !);
+ y=${y}-1;
+ }
+ }
+}
+
+
+NOTE: The conditional expression (the "${y} >= 0" above) is wrapped in
+ $[ ] so it can be evaluated. NOTE: The for loop test expression
+ (the "${x} < 3" above) is wrapped in $[ ] so it can be evaluated.
+
+
+
+Conditionals
+============
+
+AEL2 supports if and switch statements, like AEL, but adds ifTime, and
+random. Unlike the original AEL, though, you do NOT need to put curly
+braces around a single statement in the "true" branch of an if(), the
+random(), or an ifTime() statement. The if(), ifTime(), and random()
+statements allow optional else clause.
+
+
+context conditional {
+ _8XXX => {
+ Dial(SIP/${EXTEN});
+ if ("${DIALSTATUS}" = "BUSY")
+ {
+ NoOp(yessir);
+ Voicemail(${EXTEN}|b);
+ }
+ else
+ Voicemail(${EXTEN}|u);
+ ifTime (14:00-25:00|sat-sun|*|*)
+ Voicemail(${EXTEN}|b);
+ else
+ {
+ Voicemail(${EXTEN}|u);
+ NoOp(hi, there!);
+ }
+ random(51) NoOp(This should appear 51% of the time);
+
+ random( 60 )
+ {
+ NoOp( This should appear 60% of the time );
+ }
+ else
+ {
+ random(75)
+ {
+ NoOp( This should appear 30% of the time! );
+ }
+ else
+ {
+ NoOp( This should appear 10% of the time! );
+ }
+ }
+ }
+ _777X => {
+ switch (${EXTEN}) {
+ case 7771:
+ NoOp(You called 7771!);
+ break;
+ case 7772:
+ NoOp(You called 7772!);
+ break;
+ case 7773:
+ NoOp(You called 7773!);
+ // fall thru-
+ pattern 777[4-9]:
+ NoOp(You called 777 something!);
+ default:
+ NoOp(In the default clause!);
+ }
+ }
+}
+
+
+NOTE: The conditional expression in if() statements (the
+ "${DIALSTATUS}" = "BUSY" above) is wrapped by the compiler in
+ $[] for evaluation.
+
+NOTE: Neither the switch nor case values are wrapped in $[ ]; they can
+ be constants, or ${var} type references only.
+
+NOTE: AEL2 generates each case as a separate extension. case clauses
+ with no terminating 'break', or 'goto', have a goto inserted, to
+ the next clause, which creates a 'fall thru' effect.
+
+NOTE: AEL2 introduces the ifTime keyword/statement, which works just
+ like the if() statement, but the expression is a time value,
+ exactly like that used by the application GotoIfTime(). See
+ Asterisk cmd GotoIfTime
+
+NOTE: The pattern statement makes sure the new extension that is
+ created has an '_' preceding it to make sure asterisk recognizes
+ the extension name as a pattern.
+
+NOTE: Every character enclosed by the switch expression's parenthesis
+ are included verbatim in the labels generated. So watch out for
+ spaces!
+
+NOTE: NEW: Previous to version 0.13, the random statement used the
+ "Random()" application, which has been deprecated. It now uses
+ the RAND() function instead, in the GotoIf application.
+
+
+Break, Continue, and Return
+===========================
+
+
+Three keywords, break, continue, and return, are included in the
+syntax to provide flow of control to loops, and switches.
+
+The break can be used in switches and loops, to jump to the end of the
+loop or switch.
+
+The continue can be used in loops (while and for) to immediately jump
+to the end of the loop. In the case of a for loop, the increment and
+test will then be performed. In the case of the while loop, the
+continue will jump to the test at the top of the loop.
+
+The return keyword will cause an immediate jump to the end of the
+context, or macro, and can be used anywhere.
+
+
+
+goto, jump, and labels
+======================
+
+This is an example of how to do a goto in AEL.
+
+
+context gotoexample {
+ s => {
+begin:
+ NoOp(Infinite Loop! yay!);
+ Wait(1);
+ goto begin; // go to label in same extension
+ }
+ 3 => {
+ goto s|begin; // go to label in different extension
+ }
+ 4 => {
+ goto gotoexample|s|begin; // overkill go to label in same context
+ }
+}
+
+context gotoexample2 {
+ s => {
+ end:
+ goto gotoexample|s|begin; // go to label in different context
+ }
+}
+
+You can use the special label of "1" in the goto and jump
+statements. It means the "first" statement in the extension. I would
+not advise trying to use numeric labels other than "1" in goto's or
+jumps, nor would I advise declaring a "1" label anywhere! As a matter
+of fact, it would be bad form to declare a numeric label, and it might
+confllict with the priority numbers used internally by asterisk.
+
+The syntax of the jump statement is: jump
+extension[,priority][@context] If priority is absent, it defaults to
+"1". If context is not present, it is assumed to be the same as that
+which contains the "jump".
+
+
+context gotoexample {
+ s => {
+begin:
+ NoOp(Infinite Loop! yay!);
+ Wait(1);
+ jump s; // go to first extension in same extension
+ }
+ 3 => {
+ jump s|begin; // go to label in different extension
+ }
+ 4 => {
+ jump s|begin at gotoexample; // overkill go to label in same context
+ }
+}
+
+context gotoexample2 {
+ s => {
+ end:
+ jump s at gotoexample; // go to label in different context
+ }
+}
+
+NOTE: goto labels follow the same requirements as the Goto()
+ application, except the last value has to be a label. If the
[... 287 lines stripped ...]
More information about the asterisk-commits
mailing list