[asterisk-commits] russell: branch russell/LaTeX_docs r58909 -
/team/russell/LaTeX_docs/doc/
asterisk-commits at lists.digium.com
asterisk-commits at lists.digium.com
Wed Mar 14 15:04:57 MST 2007
Author: russell
Date: Wed Mar 14 17:04:56 2007
New Revision: 58909
URL: http://svn.digium.com/view/asterisk?view=rev&rev=58909
Log:
progress thus far, up to 59 pages, with at least 40 individual documents not yet integrated
Added:
team/russell/LaTeX_docs/doc/ael.tex
- copied, changed from r58903, team/russell/LaTeX_docs/doc/ael.txt
team/russell/LaTeX_docs/doc/asterisk.pdf (with props)
team/russell/LaTeX_docs/doc/asterisk.tex (with props)
team/russell/LaTeX_docs/doc/configuration.tex
- copied, changed from r58903, team/russell/LaTeX_docs/doc/configuration.txt
team/russell/LaTeX_docs/doc/extensions.tex
- copied, changed from r58903, team/russell/LaTeX_docs/doc/extensions.txt
team/russell/LaTeX_docs/doc/freetds.tex
- copied, changed from r58903, team/russell/LaTeX_docs/doc/freetds.txt
team/russell/LaTeX_docs/doc/hardware.tex (with props)
team/russell/LaTeX_docs/doc/ip-tos.tex
- copied, changed from r58903, team/russell/LaTeX_docs/doc/ip-tos.txt
team/russell/LaTeX_docs/doc/realtime.tex
- copied, changed from r58903, team/russell/LaTeX_docs/doc/realtime.txt
team/russell/LaTeX_docs/doc/security.tex
- copied, changed from r58903, team/russell/LaTeX_docs/doc/security.txt
Removed:
team/russell/LaTeX_docs/doc/00README.1st
team/russell/LaTeX_docs/doc/ael.txt
team/russell/LaTeX_docs/doc/configuration.txt
team/russell/LaTeX_docs/doc/extconfig.txt
team/russell/LaTeX_docs/doc/extensions.txt
team/russell/LaTeX_docs/doc/freetds.txt
team/russell/LaTeX_docs/doc/hardware.txt
team/russell/LaTeX_docs/doc/ip-tos.txt
team/russell/LaTeX_docs/doc/realtime.txt
team/russell/LaTeX_docs/doc/security.txt
Modified:
team/russell/LaTeX_docs/doc/sla.pdf
team/russell/LaTeX_docs/doc/sla.tex
Copied: team/russell/LaTeX_docs/doc/ael.tex (from r58903, team/russell/LaTeX_docs/doc/ael.txt)
URL: http://svn.digium.com/view/asterisk/team/russell/LaTeX_docs/doc/ael.tex?view=diff&rev=58909&p1=team/russell/LaTeX_docs/doc/ael.txt&r1=58903&p2=team/russell/LaTeX_docs/doc/ael.tex&r2=58909
==============================================================================
--- team/russell/LaTeX_docs/doc/ael.txt (original)
+++ team/russell/LaTeX_docs/doc/ael.tex Wed Mar 14 17:04:56 2007
@@ -1,5 +1,4 @@
-The Asterisk Extension Language - v 2
-=====================================
+\subsection{Introduction}
AEL is a specialized language intended purely for
describing Asterisk dial plans.
@@ -13,21 +12,22 @@
AEL is really the merger of 4 different 'languages', or syntaxes:
- * The first and most obvious is the AEL syntax itself. A BNF is
+\begin{itemize}
+ \item The first and most obvious is the AEL syntax itself. A BNF is
provided near the end of this document.
- * The second syntax is the Expression Syntax, which is normally
+ \item 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 $[ ... ]
+ \$[...]. 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
+ \item 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, and is not used
+ \item 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
@@ -36,14 +36,13 @@
commands, of which one application call per step, or priority
can be made. You can think of this as a "macro assembler"
language, that AEL will compile into.
-
+\end{itemize}
Any programmer of AEL should be familiar with it's syntax, of course,
as well as the Expression syntax, and the Variable syntax.
-**************************
-* Asterisk in a Nutshell *
-**************************
+
+\subsection{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
@@ -52,8 +51,7 @@
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
---------
+\subsubsection{Contexts}
Contexts are a grouping of extensions.
@@ -61,8 +59,7 @@
merge operation at runtime, whereby the included context's extensions
are added to the contexts making the inclusion.
-Extensions and priorities
--------------------------
+\subsubsection{Extensions and priorities}
A Context contains zero or more Extensions. There are several
predefined extensions. The "s" extension is the "start" extension, and
@@ -94,8 +91,7 @@
extensions in other contexts. Conditionals provide the ability to
react to different stimuli, and there you have it.
-Macros
-------
+\subsubsection{Macros}
Think of a macro as a combination of a context with one nameless
extension, and a subroutine. It has arguments like a subroutine
@@ -104,8 +100,7 @@
execution returns to the next statement after the macro call. Macros
can call other macros. And they work just like function calls.
-Applications
-------------
+\subsubsection{Applications}
Application calls, like "Dial()", or "Hangup()", or "Answer()", are
available for users to use to accomplish the work of the
@@ -117,14 +112,11 @@
Hopefully, the above objects will allow you do anything you need to in
the Asterisk environment!
-
-*******************
-* Getting Started *
-*******************
-
-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
+\subsection{Getting Started}
+
+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.ael' in /etc/asterisk/. extensions.conf and
@@ -133,9 +125,7 @@
extensions.conf for the features that are configured in the 'general'
section of extensions.conf.
-------------------------------
-- Reloading extensions.ael -
-------------------------------
+Reloading extensions.ael
To reload extensions.ael, the following command can be issued at the
CLI:
@@ -143,10 +133,7 @@
*CLI> ael reload
-
-*************
-* Debugging *
-*************
+\subsection{Debugging}
Right at this moment, the following commands are available, but do
nothing:
@@ -174,9 +161,7 @@
3. the standalone executable, "aelparse" built in the utils/ dir in the source.
-*****************************
-* About "aelparse" *
-*****************************
+\subsection{About "aelparse"}
You can use the "aelparse" program to check your extensions.ael
file before feeding it to asterisk. Wouldn't it be nice to eliminate
@@ -188,20 +173,24 @@
aelparse has two optional arguments:
--d - Override the normal location of the config file dir, (usually
+\begin{itemize}
+ \item -d
+ \begin{itemize}
+ \item 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
+ \end{itemize}
+ \item -n
+ \begin{itemize}
+ \item 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 *
-******************************
+ \end{itemize}
+\end{itemize}
+
+\subsection{General Notes about Syntax}
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
@@ -211,10 +200,13 @@
You can just as easily say,
+\begin{verbatim}
if(${x}=1) { NoOp(hello!); goto s|3; } else { NoOp(Goodbye!); goto s|12; }
+\end{verbatim}
as you can say:
+\begin{verbatim}
if(${x}=1)
{
NoOp(hello!);
@@ -225,9 +217,11 @@
NoOp(Goodbye!);
goto s|12;
}
+\end{verbatim}
or:
+\begin{verbatim}
if(${x}=1) {
NoOp(hello!);
goto s|3;
@@ -235,33 +229,19 @@
NoOp(Goodbye!);
goto s|12;
}
+\end{verbatim}
or:
+\begin{verbatim}
if (${x}=1) {
NoOp(hello!); goto s|3;
} else {
NoOp(Goodbye!); goto s|12;
}
-
-or even:
-
-if
-(${x}=1)
-{
-NoOp(hello!);
-goto s|3;
-}
-else
-{
-NoOp(Goodbye!);
-goto s|12;
-}
-
-
-************
-* Keywords *
-************
+\end{verbatim}
+
+\subsection{Keywords}
The AEL keywords are case-sensitive. If an application name and a
keyword overlap, there is probably good reason, and you should
@@ -271,41 +251,38 @@
language, application names are NOT case-sensitive.
The following are keywords in the AEL 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,
+\begin{itemize}
+ \item abstract
+ \item context
+ \item macro
+ \item globals
+ \item ignorepat
+ \item switch
+ \item if
+ \item ifTime
+ \item else
+ \item random
+ \item goto
+ \item jump
+ \item return
+ \item break
+ \item continue
+ \item regexten
+ \item hint
+ \item for
+ \item while
+ \item case
+ \item pattern
+ \item default NOTE: the "default" keyword can be used as a context name,
for those who would like to do so.
- * catch
- * switches
- * eswitches
- * includes
-
-
-
-
-
-Procedural Interface and Internals
-==================================
+ \item catch
+ \item switches
+ \item eswitches
+ \item includes
+\end{itemize}
+
+
+\subsection{Procedural Interface and Internals}
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.
@@ -323,25 +300,19 @@
for developers to simplify apps to generate dialplan data.
-
-=========================
- AEL version 2 BNF
-=========================
-
-
+\subsubsection{AEL version 2 BNF}
(hopefully, something close to bnf).
First, some basic objects
+\begin{verbatim}
------------------------
-
<word> a lexical token consisting of characters matching this pattern: [-a-zA-Z0-9"_/.\<\>\*\+!$#\[\]][-a-zA-Z0-9"_/.!\*\+\<\>\{\}$#\[\]]*
<word3-list> a concatenation of up to 3 <word>s.
<collected-word> all characters encountered until the character that follows the <collected-word> in the grammar.
-
-------------------------
<file> :== <objects>
@@ -517,29 +488,27 @@
<includes> :== 'includes' '{' <includeslist> '}'
| 'includes' '{' '}'
-
-**************************
-* AEL Example USAGE *****
-**************************
-
-Comments
-========
+\end{verbatim}
+
+
+\subsection{AEL Example USAGE}
+
+\subsubsection{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
+\$[] , or inside application call argument lists. The safest place to put
comments is after terminating semicolons, or on otherwise empty lines.
-Context
-=======
+\subsubsection{Context}
Contexts in AEL represent a set of extensions in the same way that
they do in extensions.conf.
-
+\begin{verbatim}
context default {
}
@@ -551,21 +520,20 @@
current effect of this keyword is to prevent "goto " statements from
being checked.
-
+\begin{verbatim}
abstract context longdist {
- _1NXXNXXXXXX => NoOp(generic long distance dialing actions in the US);
-}
-
-
-
-Extensions
-==========
+ _1NXXNXXXXXX => NoOp(generic long distance dialing actions in the US);
+}
+\end{verbatim}
+
+
+\subsubsection{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.
-
+\begin{verbatim}
context default {
1234 => Playback(tt-monkeys);
8000 => {
@@ -575,7 +543,7 @@
};
_5XXX => NoOp(it's a pattern!);
}
-
+\end{verbatim}
Two optional items have been added to the AEL syntax, that allow the
specification of hints, and a keyword, regexten, that will force the
@@ -584,36 +552,38 @@
The ability to make extensions match by CID is preserved in
AEL; just use '/' and the CID number in the specification. See below.
-
+\begin{verbatim}
context default {
regexten _5XXX => NoOp(it's a pattern!);
}
-
-
-
+\end{verbatim}
+
+\begin{verbatim}
context default {
hint(Sip/1) _5XXX => NoOp(it's a pattern!);
}
-
-
-
+\end{verbatim}
+
+\begin{verbatim}
context default {
regexten hint(Sip/1) _5XXX => NoOp(it's a pattern!);
}
-
+\end{verbatim}
The regexten must come before the hint if they are both present.
CID matching is done as with the extensions.conf file. Follow the extension
name/number with a slash (/) and the number to match against the Caller ID:
+\begin{verbatim}
context zoombo
{
819/7079953345 => { NoOp(hello, 3345); }
}
+\end{verbatim}
In the above, the 819/7079953345 extension will only be matched if the
CallerID is 7079953345, and the dialed number is 819. Hopefully you have
@@ -621,13 +591,12 @@
as to have 7079953345 as their CallerID!
-Includes
-========
+\subsubsection{Includes}
Contexts can be included in other contexts. All included contexts are
listed within a single block.
-
+\begin{verbatim}
context default {
includes {
local;
@@ -635,13 +604,13 @@
international;
}
}
-
+\end{verbatim}
Time-limited inclusions can be specified, as in extensions.conf
format, with the fields described in the wiki page Asterisk cmd
GotoIfTime.
-
+\begin{verbatim}
context default {
includes {
local;
@@ -649,20 +618,19 @@
international;
}
}
-
-
-#include
-========
-
-You can include other files with the #include "filepath" construct.
-
-
+\end{verbatim}
+
+\subsubsection{\#include}
+
+You can include other files with the \#include "filepath" construct.
+
+\begin{verbatim}
#include "/etc/asterisk/testfor.ael"
-
-
-An interesting property of the #include, is that you can use it almost
+\end{verbatim}
+
+An interesting property of the \#include, is that you can use it almost
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
+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
@@ -670,14 +638,13 @@
-Dialplan Switches
-=================
+\subsubsection{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.
-
+\begin{verbatim}
context default {
switches {
DUNDi/e164;
@@ -687,43 +654,40 @@
IAX2/context@${CURSERVER};
}
}
-
-
-
-Ignorepat
-=========
+\end{verbatim}
+
+
+\subsubsection{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'.
-
+\begin{verbatim}
context outgoing {
ignorepat => 9;
}
-
-
-
-
-Variables
-=========
+\end{verbatim}
+
+
+\subsubsection{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.
-
+\begin{verbatim}
globals {
CONSOLE=Console/dsp;
TRUNK=Zap/g2;
}
-
+\end{verbatim}
Variables can be set within extensions as well.
-
+\begin{verbatim}
context foo {
555 => {
x=5;
@@ -732,36 +696,35 @@
NoOp(x is ${x} and y is ${y} !);
}
}
-
-
-NOTE: AEL wraps the right hand side of an assignment with $[ ] to allow
+\end{verbatim}
+
+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;
+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])
+(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.
-
+\begin{verbatim}
context blah {
s => {
CALLERID(name)=ChickenMan;
NoOp(My name is ${CALLERID(name)} !);
}
}
-
-
-
-Loops
-=====
+\end{verbatim}
+
+
+\subsubsection{Loops}
AEL has implementations of 'for' and 'while' loops.
-
+\begin{verbatim}
context loops {
1 => {
for (x=0; ${x} < 3; x=${x} + 1) {
@@ -776,16 +739,15 @@
}
}
}
-
-
-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
-============
+\end{verbatim}
+
+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.
+
+
+
+\subsubsection{Conditionals}
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
@@ -793,7 +755,7 @@
random(), or an ifTime() statement. The if(), ifTime(), and random()
statements allow optional else clause.
-
+\begin{verbatim}
context conditional {
_8XXX => {
Dial(SIP/${EXTEN});
@@ -847,14 +809,14 @@
}
}
}
-
+\end{verbatim}
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.
+ "\${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: AEL generates each case as a separate extension. case clauses
with no terminating 'break', or 'goto', have a goto inserted, to
@@ -866,7 +828,7 @@
Asterisk cmd GotoIfTime
NOTE: The pattern statement makes sure the new extension that is
- created has an '_' preceding it to make sure asterisk recognizes
+ 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
@@ -878,9 +840,7 @@
the RAND() function instead, in the GotoIf application.
-Break, Continue, and Return
-===========================
-
+\subsubsection{Break, Continue, and Return}
Three keywords, break, continue, and return, are included in the
syntax to provide flow of control to loops, and switches.
@@ -898,12 +858,11 @@
-goto, jump, and labels
-======================
+\subsubsection{goto, jump, and labels}
This is an example of how to do a goto in AEL.
-
+\begin{verbatim}
context gotoexample {
s => {
begin:
@@ -925,6 +884,7 @@
goto gotoexample|s|begin; // go to label in different context
}
}
+\end{verbatim}
You can use the special label of "1" in the goto and jump
statements. It means the "first" statement in the extension. I would
@@ -938,7 +898,7 @@
"1". If context is not present, it is assumed to be the same as that
which contains the "jump".
-
+\begin{verbatim}
context gotoexample {
s => {
begin:
@@ -960,6 +920,7 @@
jump s at gotoexample; // go to label in different context
}
}
+\end{verbatim}
NOTE: goto labels follow the same requirements as the Goto()
application, except the last value has to be a label. If the
@@ -980,15 +941,14 @@
-Macros
-======
+\subsubsection{Macros}
A macro is defined in its own block like this. The arguments to the
macro are specified with the name of the macro. They are then referred
to by that same name. A catch block can be specified to catch special
extensions.
-
+\begin{verbatim}
macro std-exten( ext , dev ) {
Dial(${dev}/${ext},20);
switch(${DIALSTATUS) {
@@ -1004,26 +964,25 @@
return;
}
}
-
+\end{verbatim}
A macro is then called by preceding the macro name with an
ampersand. Empty arguments can be passed simply with nothing between
comments(0.11).
-
+\begin{verbatim}
context example {
_5XXX => &std-exten(${EXTEN}, "IAX2");
_6XXX => &std-exten(, "IAX2");
_7XXX => &std-exten(${EXTEN},);
_8XXX => &std-exten(,);
}
-
-
-
-Examples
-========
-
-
+\end{verbatim}
+
+
+\subsection{Examples}
+
+\begin{verbatim}
context demo {
s => {
Wait(1);
@@ -1067,117 +1026,121 @@
t => goto #|hangup;
i => Playback(invalid);
}
-
-
-Semantic Checks
-===============
+\end{verbatim}
+
+
+\subsection{Semantic Checks}
AEL, after parsing, but before compiling, traverses the dialplan
tree, and makes several checks:
- * Macro calls to non-existent macros.
- * Macro calls to contexts.
- * Macro calls with argument count not matching the definition.
- * application call to macro. (missing the '&')
- * application calls to "GotoIf", "GotoIfTime", "while",
+\begin{itemize}
+ \item Macro calls to non-existent macros.
+ \item Macro calls to contexts.
+ \item Macro calls with argument count not matching the definition.
+ \item application call to macro. (missing the '\&')
+ \item 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.
- * goto a label in an empty extension.
- * goto a non-existent label, either a within-extension,
+ \item goto a label in an empty extension.
+ \item goto a non-existent label, either a within-extension,
within-context, or in a different context, or in any included
contexts. Will even check "sister" context references.
- * All the checks done on the time values in the dial plan, are
+ \item All the checks done on the time values in the dial plan, are
done on the time values in the ifTime() and includes times:
o the time range has to have two times separated by a dash;
o the times have to be in range of 0 to 24 hours.
o The weekdays have to match the internal list, if they are provided;
o the day of the month, if provided, must be in range of 1 to 31;
o the month name or names have to match those in the internal list.
- * (0.5) If an expression is wrapped in $[ ... ], and the compiler
+ \item (0.5) If an expression is wrapped in \$[ ... ], and the compiler
will wrap it again, a warning is issued.
- * (0.5) If an expression had operators (you know,
- +,-,*,/,%,!,etc), but no ${ } variables, a warning is
+ \item (0.5) If an expression had operators (you know,
+ +,-,*,/,%,!,etc), but no \${ } variables, a warning is
issued. Maybe someone forgot to wrap a variable name?
- * (0.12) check for duplicate context names.
- * (0.12) check for abstract contexts that are not included by any context.
- * (0.13) Issue a warning if a label is a numeric value.
+ \item (0.12) check for duplicate context names.
+ \item (0.12) check for abstract contexts that are not included by any context.
+ \item (0.13) Issue a warning if a label is a numeric value.
+\end{itemize}
There are a subset of checks that have been removed until the proposed
AAL (Asterisk Argument Language) is developed and incorporated into Asterisk.
These checks will be:
- * (if the application argument analyzer is working: the presence
+\begin{itemize}
+ \item (if the application argument analyzer is working: the presence
of the 'j' option is reported as error.
- * if options are specified, that are not available in an
+ \item if options are specified, that are not available in an
application.
- * if you specify too many arguments to an application.
- * a required argument is not present in an application call.
- * Switch-case using "known" variables that applications set, that
+ \item if you specify too many arguments to an application.
+ \item a required argument is not present in an application call.
+ \item 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.
- * a Switch construct is used, which is uses a known variable, and
+ \item 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...
- * Calls to applications not in the "applist" database (installed
+ \item Calls to applications not in the "applist" database (installed
in /var/lib/asterisk/applist" on most systems).
- * In an assignment statement, if the assignment is to a function,
+ \item In an assignment statement, if the assignment is to a function,
the function name used is checked to see if it one of the
currently known functions. A warning is issued if it is not.
-
+\end{itemize}
Differences with the original version of AEL
============================================
- 1. The $[...] expressions have been enhanced to include the ==, ||,
- and && operators. These operators are exactly equivalent to the
- =, |, and & operators, respectively. Why? So the C, Java, C++
+\begin{enumerate}
+ \item The \$[...] expressions have been enhanced to include 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,
+ \item 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
+ \item 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
+ \item 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
+ \item 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. -- ALMOST
+ \item 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
+ \item 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_ael.so.
- 9. In the utils directory, two standalone programs are supplied for
+ \item A pretty printer function is available within pbx\_ael.so.
+ \item 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.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. AEL supports the "jump" statement, and the "pattern" statement
+ 'pbx\_ael.so' instead.
+ \item 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
+ \item 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
+ \item 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. See the
example above. (Note: all the other time-dependent Applications
can be used via ifTime)
- 13. Added the optional time spec to the contexts in the includes
+ \item Added the optional time spec to the contexts in the includes
construct. See examples above.
- 14. You don't have to wrap a single "true" statement in curly
+ \item You don't have to wrap a single "true" statement in curly
braces, as in the original AEL. An "else" is attached to the
closest if. As usual, be careful about nested if statements!
When in doubt, use curlies!
- 15. Added the syntax [regexten] [hint(channel)] to precede an
+ \item Added the syntax [regexten] [hint(channel)] to precede an
extension declaration. See examples above, under
"Extension". The regexten keyword will cause the priorities in
the extension to begin with 2 instead of 1. The hint keyword
@@ -1185,51 +1148,49 @@
the hint priority. They are both optional, of course, but the
order is fixed at the moment-- the regexten must come before the
hint, if they are both present.
- 16. Empty case/default/pattern statements will "fall thru" as
+ \item Empty case/default/pattern statements will "fall thru" as
expected. (0.6)
- 17. A trailing label in an extension, will automatically have a
+ \item A trailing label in an extension, will automatically have a
NoOp() added, to make sure the label exists in the extension on
Asterisk. (0.6)
- 18. (0.9) the semicolon is no longer required after a closing brace!
- (i.e. "];" ===> "}". You can have them there if you like, but
+ \item (0.9) the semicolon is no longer required after a closing brace!
+ (i.e. "];" ===> "\}". You can have them there if you like, but
they are not necessary. Someday they may be rejected as a syntax
error, maybe.
- 19. (0.9) the // comments are not recognized and removed in the
+ \item (0.9) the // comments are not recognized and removed in the
spots where expressions are gathered, nor in application call
arguments. You may have to move a comment if you get errors in
existing files.
- 20. (0.10) the random statement has been added. Syntax: random (
+ \item (0.10) the random statement has been added. Syntax: random (
<expr> ) <lucky-statement> [ else <unlucky-statement> ]. The
probability of the lucky-statement getting executed is <expr>,
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.
-
-
-
-Hints and Bugs
-==============
-
- * The safest way to check for a null strings is to say $[ "${x}" =
+\end{enumerate}
+
+
+\subsection{Hints and Bugs}
+
+ The safest way to check for a null strings is to say \$[ "\${x}" =
"" ] The old way would do as shell scripts often do, and append
- something on both sides, like this: $[ ${x}foo = foo ]. The
+ something on both sides, like this: \$[ \${x}foo = foo ]. The
trouble with the old way, is that, if x contains any spaces, then
problems occur, usually syntax errors. It is better practice and
safer wrap all such tests with double quotes! Also, there are now
some functions that can be used in a variable reference,
ISNULL(), and LEN(), that can be used to test for an empty string:
- ${ISNULL(${x})} or $[ ${LEN(${x}) = 0 ].
-
- * Assignment vs. Set(). Keep in mind that setting a variable to
+ \${ISNULL(\${x})} or \$[ \${LEN(\${x}) = 0 ].
+
+ 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 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,
+ \$[]. 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
-==============================
+\subsection{The Full Power of AEL}
A newcomer to Asterisk will look at the above constructs and
descriptions, and ask, "Where's the string manipulation functions?",
@@ -1239,22 +1200,23 @@
The answer is that the rich capabilities of Asterisk are made
available through AEL, via:
- * Applications: See Asterisk - documentation of application
+\begin{itemize}
+ \item Applications: See Asterisk - documentation of application
commands
- * Functions: Functions were implemented inside ${ .. } variable
+ \item Functions: Functions were implemented inside \${ .. } variable
references, and supply many useful capabilities.
- * Expressions: An expression evaluation engine handles items
- wrapped inside $[...]. This includes some string manipulation
+ \item Expressions: An expression evaluation engine handles items
+ wrapped inside \$[...]. This includes some string manipulation
facilities, arithmetic expressions, etc.
- * Application Gateway Interface: Asterisk can fork external
+ \item Application Gateway Interface: Asterisk can fork external
processes that communicate via pipe. AGI applications can be
written in any language. Very powerful applications can be added
this way.
- * Variables: Channels of communication have variables associated
+ \item Variables: Channels of communication have variables associated
with them, and asterisk provides some global variables. These can be
manipulated and/or consulted by the above mechanisms.
-
+\end{itemize}
Added: team/russell/LaTeX_docs/doc/asterisk.pdf
URL: http://svn.digium.com/view/asterisk/team/russell/LaTeX_docs/doc/asterisk.pdf?view=auto&rev=58909
==============================================================================
Binary file - no diff available.
Propchange: team/russell/LaTeX_docs/doc/asterisk.pdf
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Added: team/russell/LaTeX_docs/doc/asterisk.tex
URL: http://svn.digium.com/view/asterisk/team/russell/LaTeX_docs/doc/asterisk.tex?view=auto&rev=58909
==============================================================================
--- team/russell/LaTeX_docs/doc/asterisk.tex (added)
+++ team/russell/LaTeX_docs/doc/asterisk.tex Wed Mar 14 17:04:56 2007
@@ -1,0 +1,106 @@
+\documentclass[12pt,a4]{article}
+\usepackage{hyperref}
+
+\author{Asterisk Development Team \\ Asterisk.org}
+\title{Asterisk Reference Information}
+
+\begin{document}
+\maketitle
+
+\tableofcontents
+
+\section{Introduction}
+
+This document contains various pieces of information that are useful for
+reference purposes.
+
+\section{License Information}
+\input{../LICENSE}
+
+\section{Security}
+\input{security.tex}
+
+\section{Hardware}
+\input{hardware.tex}
+
+\section{General Configuration Information}
+ \subsection{Configuration Parser}
+ \input{configuration.tex}
+
+ \subsection{Extensions}
+ \input{extensions.tex}
+
+ \subsection{IP Type of Service}
+ \input{ip-tos.tex}
+
+\section{Database Support}
+
+ \subsection{Realtime Database Configuration}
+ \input{realtime.tex}
+
+ \subsection{FreeTDS}
+ \input{freetds.tex}
+
+\section{AEL, Asterisk Extension Language}
+\input{ael.tex}
+
+\section{SLA (Shared Line Appearances)}
+\input{sla.tex}
+
+% This is a list of files not yet integrated into this document:
+%
+%Misc
+%----
+%PEERING The General Peering Agreement for Dundi
+%ajam.txt About the HTTP-based manager interface
+%app_sms.txt How to configure the SMS application
+%asterisk.conf.txt Documentation of various options in asterisk.conf
+%callingpres.txt Settings for Caller ID presentation
+%billing.txt Call Data Record information
+%cliprompt.txt How to change the Asterisk CLI prompt
+%dundi.txt Dundi - a discovery protocol
+%enum.txt Enum support in Asterisk
+%ices.txt Integrating ICEcast streaming in Asterisk
+%jitterbuffer.txt About the IAX2 jitterbuffer implementation
+%math.txt About the math() application
+%mp3.txt About MP3 support in Asterisk
+%musiconhold-fpm.txt Free Music On Hold music
+%mysql.txt About MYSQL support in Asterisk
+%odbcstorage.txt Voicemail storage of messages in UnixODBC
+%privacy.txt Privacy enhancements in Asterisk
+%queuelog.txt Agent and queue logging
+%channelvariables.txt Channel variables
+%cdrdrivers.txt About CDR storage in various databases (needs update)
+%asterisk-mib.txt SNMP mib for Asterisk (net-snmp)
+%digium-mib.txt SNMP mib for Asterisk (net-snmp)
+%
+%Channel drivers
+%---------------
+%misdn.txt The mISDN channel driver for ISDN BRI cards
[... 916 lines stripped ...]
More information about the asterisk-commits
mailing list