[asterisk-commits] branch murf/AEL2 r21276 - in /team/murf/AEL2:
doc/ utils/
asterisk-commits at lists.digium.com
asterisk-commits at lists.digium.com
Tue Apr 18 17:44:53 MST 2006
Author: murf
Date: Tue Apr 18 19:44:49 2006
New Revision: 21276
URL: http://svn.digium.com/view/asterisk?rev=21276&view=rev
Log:
Replaced the ael.txt in dec/ with the new AEL2 version, but
changed the AEL2 references to AEL instead. I edited
the text to reflect the fact that this code is the upgrade
and continuance of AEL, and not a separate work.
I still have to make a make a pass to handle removing the
semantic checking of application args...
The utils Makefile has been edited to reflect the new
paths under the pbx dir for aelparse. aelparse1 is no more.
Added:
team/murf/AEL2/doc/ael.txt (contents, props changed)
- copied, changed from r20758, team/murf/AEL2/doc/ael2.txt
Removed:
team/murf/AEL2/doc/ael2.txt
Modified:
team/murf/AEL2/utils/Makefile
Copied: team/murf/AEL2/doc/ael.txt (from r20758, team/murf/AEL2/doc/ael2.txt)
URL: http://svn.digium.com/view/asterisk/team/murf/AEL2/doc/ael.txt?p2=team/murf/AEL2/doc/ael.txt&p1=team/murf/AEL2/doc/ael2.txt&r1=20758&r2=21276&rev=21276&view=diff
==============================================================================
--- team/murf/AEL2/doc/ael2.txt (original)
+++ team/murf/AEL2/doc/ael.txt Tue Apr 18 19:44:49 2006
@@ -1,19 +1,22 @@
The Asterisk Extension Language - v 2
=====================================
-AEL2 is a new version of the AEL compiler, written by Steve Murphy.
-
-AEL2 (like AEL) is considered an EXPERIMENTAL Version. (yet is being
+AEL is a specialized language intended purely for
+describing Asterisk dial plans.
+
+The current version was written by Steve Murphy, and is a rewrite of
+the original version.
+
+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
+This new version 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
+AEL is really the merger of 4 different 'languages', or syntaxes:
+
+ * The first and most obvious is the AEL syntax itselft. A BNF is
provided near the end of this document.
* The second syntax is the Expression Syntax, which is normally
@@ -27,10 +30,10 @@
'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
+ * The last syntax that underlies AEL, and is not used
+ directly in AEL, is the Extension Language Syntax. The
+ extension language is what you see in extensions.conf, and AEL
+ compiles the higher level AEL 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
@@ -38,7 +41,7 @@
language, that AEL2 will compile into.
-Any programmer of AEL2 should be familiar with it's syntax, of course,
+Any programmer of AEL should be familiar with it's syntax, of course,
as well as the Expression syntax, and the Variable syntax.
**************************
@@ -122,25 +125,25 @@
* 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
+The AEL parser (pbx_ael.so) is completely separate from the module
+that parses extensions.conf (pbx_config.so). To use AEL, the only
+thing that has to be done is the module pbx_ael.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
+for 'extensions.ael' in /etc/asterisk/. extensions.conf and
+extensions.ael 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 -
+- Reloading extensions.ael -
------------------------------
-To reload extensions.ael2, the following command can be issued at the
+To reload extensions.ael, the following command can be issued at the
CLI:
- *CLI> ael2 reload
+ *CLI> ael reload
@@ -151,20 +154,20 @@
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
+Enable AEL contexts debug
+ *CLI> ael debug contexts
+
+Enable AEL macros debug
+ *CLI> ael debug macros
+
+Enable AEL read debug
+ *CLI> ael debug read
+
+Enable AEL tokens debug
+ *CLI> ael debug tokens
+
+Disable AEL debug messages
+ *CLI> ael no debug
If things are going wrong in your dialplan, you can use the following
facilities to debug your file:
@@ -173,17 +176,33 @@
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
+
+*****************************
+* About "aelparse" *
+*****************************
+
+You can also use the "aelparse" program to check your extensions.ael
file before feeding it to asterisk. Wouldn't it be nice to eliminate
most errors before giving the file to asterisk?
+aelparse has two optional arguments:
+
+-d - Override the normal location of the config file dir, (usually
+ /etc/asterisk), and use the current directory instead as the
+ config file dir. Aelparse will then expect to find the file
+ "./extensions.ael" in the current directory, and any included
+ files in the current directory as well.
+
+-n - don't show all the function calls to set priorities and contexts
+ within asterisk. It will just show the errors and warnings from
+ the parsing and semantic checking phases.
******************************
* General Notes about Syntax *
******************************
-Note that the syntax and style are a little more free-form. The
+Note that the syntax and style are now 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
@@ -245,7 +264,7 @@
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
+consider replacing the application call with an AEL 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.
@@ -282,26 +301,12 @@
-*****************
-* 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.
-
-
Procedural Interface and Internals
==================================
-AEL2 first parses the .ael2 file into a memory structure representing the file.
+AEL first parses the extensions.ael file into a memory structure representing the file.
The entire file is represented by a tree of "pval" structures linked together.
This tree is then handed to the semantic check routine.
@@ -319,7 +324,7 @@
=========================
- AEL2 BNF
+ AEL version 2 BNF
=========================
@@ -513,7 +518,7 @@
**************************
-* AEL2 Example USAGE *****
+* AEL Example USAGE *****
**************************
Comments
@@ -523,7 +528,7 @@
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
+$[] , or inside application call argument lists. The safest place to put
comments is after terminating semicolons, or on otherwise empty lines.
@@ -571,7 +576,7 @@
}
-Two optional items have been added to the AEL2 syntax, that allow the
+Two optional items have been added to the AEL syntax, that allow the
specification of hints, and a keyword, regexten, that will force the
numbering of priorities to start at 2.
@@ -636,11 +641,11 @@
You can include other files with the #include "filepath" construct.
- #include "/etc/asterisk/testfor.ael2"
+ #include "/etc/asterisk/testfor.ael"
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
+anywhere in the .ael 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
@@ -713,9 +718,15 @@
}
-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])
+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 - the right hand side, so a = b -> Set(a=$[b])
Writing to a dialplan function is treated the same as writing to a variable.
@@ -760,7 +771,7 @@
Conditionals
============
-AEL2 supports if and switch statements, like AEL, but adds ifTime, and
+AEL 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()
@@ -829,11 +840,11 @@
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
+NOTE: AEL 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
+NOTE: AEL 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
@@ -943,10 +954,10 @@
context|extension|label. There is a note about using goto's in a
switch statement below...
-NOTE AEL2 introduces the special label "1", which is the beginning
+NOTE AEL introduces the special label "1", which is the beginning
context number for most extensions.
-NOTE: A NEW addition to AEL2: you can now use ',' instead of '|' to
+NOTE: A NEW addition to AEL: you can now use ',' instead of '|' to
separate the items in the target address. You can't have a mix,
though, of '|' and ',' in the target. It's either one, or the other.
@@ -1046,7 +1057,7 @@
===============
-AEL2, after parsing, but before compiling, traverses the dialplan
+AEL, after parsing, but before compiling, traverses the dialplan
tree, and makes several checks:
* (if the application argument analyzer is working: the presence
@@ -1097,12 +1108,14 @@
Differences with the original version of AEL
============================================
- 1. It reads in "/etc/asterisk/extensions.ael2", instead of
- extensions.ael
+ 1. The $[...] expressions have been enhanced to inlcude the ==, ||,
+ and && operators. These operators are exactly equivalent to the
+ =, |, and & operators, respectively. Why? So the C, Java, C++
+ hackers feel at home here.
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 \u2014 by this I mean that any
+ 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
@@ -1110,22 +1123,22 @@
matching paren/bracket counts.
5. It runs several semantic checks after the parsing is over, but
before the compiling begins, see the list above.
- 6. It handles #include "filepath" directives. \u2014 ALMOST
+ 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.
+ 8. A pretty printer function is available within pbx_ael.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
+ the /etc/asterisk/extensions.ael 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", using the original
'pbx_ael.so' instead.
- 10. AEL2 supports the "jump" statement, and the "pattern" statement
+ 10. AEL 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
@@ -1169,10 +1182,6 @@
which should evaluate to an integer between 0 and 100. If the
<lucky-statement> isn't so lucky this time around, then the
<unlucky-statement> gets executed, if it is present.
- 21. The $[...] expressions have been enhanced to inlcude the ==, ||,
- and && operators. These operators are exactly equivalent to the
- =, |, and & operators, respectively. Why? So the C, Java, C++
- hackers feel at home here.
@@ -1191,13 +1200,13 @@
* Assignment vs. Set(). Keep in mind that setting a variable to
value can be done two different ways. If you choose say 'x=y;',
- keep in mind that AEL2 will wrap the right-hand-side with
+ keep in mind that AEL will wrap the right-hand-side with
$[]. So, when compiled into extension language format, the end
result will be 'Set(x=$[y])'. If you don't want this effect,
then say "Set(x=y);" instead.
-The Full Power of AEL and AEL2
+The Full Power of AEL
==============================
A newcomer to Asterisk will look at the above constructs and
Propchange: team/murf/AEL2/doc/ael.txt
------------------------------------------------------------------------------
svn:eol-style = native
Propchange: team/murf/AEL2/doc/ael.txt
------------------------------------------------------------------------------
svn:keywords = Author Date Id Revision
Propchange: team/murf/AEL2/doc/ael.txt
------------------------------------------------------------------------------
svn:mime-type = text/plain
Modified: team/murf/AEL2/utils/Makefile
URL: http://svn.digium.com/view/asterisk/team/murf/AEL2/utils/Makefile?rev=21276&r1=21275&r2=21276&view=diff
==============================================================================
--- team/murf/AEL2/utils/Makefile (original)
+++ team/murf/AEL2/utils/Makefile Tue Apr 18 19:44:49 2006
@@ -65,11 +65,8 @@
check_expr: check_expr.c ast_expr2.o ast_expr2f.o
$(CC) $(CFLAGS) -o $@ $^
-aelparse : ../pbx/aelflex.o ../pbx/aelbison.o ../pbx/pbx_ael2.o ael_main.o ../ast_expr2f.o ../ast_expr2.o ../pbx/argdesc.tab.o ../pbx/argdesc_lex.o
- $(CC) $(CFLAGS) -g -o aelparse ../pbx/aelflex.o ../pbx/aelbison.o ael_main.o ../pbx/pbx_ael2.o ../ast_expr2f.o ../ast_expr2.o ../pbx/argdesc.tab.o ../pbx/argdesc_lex.o
-
-aelparse1 : ../pbx/pbx_ael.o ael_main1.o
- $(CC) $(CFLAGS) -o aelparse1 ael_main1.o ../pbx/pbx_ael.o
+aelparse : ../pbx/ael/aelflex.o ../pbx/ael/aelbison.o ../pbx/pbx_ael.o ael_main.o ../ast_expr2f.o ../ast_expr2.o ../pbx/aal/argdesc.tab.o ../pbx/aal/argdesc_lex.o
+ $(CC) $(CFLAGS) -g -o aelparse ../pbx/ael/aelflex.o ../pbx/ael/aelbison.o ael_main.o ../pbx/pbx_ael.o ../ast_expr2f.o ../ast_expr2.o ../pbx/aal/argdesc.tab.o ../pbx/aal/argdesc_lex.o
ael_main.o : ael_main.c ../include/asterisk/ael_structs.h
$(CC) $(CFLAGS) -c -g -o ael_main.o ael_main.c
More information about the asterisk-commits
mailing list