ael.tex

asterisk 是一个很有知名度开源软件

\section{Introduction}

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.

This new version further extends AEL, and
provides more flexible syntax, better error messages, and some missing
functionality.

AEL is really the merger of 4 different 'languages', or syntaxes:

\begin{itemize}
    \item The first and most obvious is the AEL syntax itself. A BNF is
      provided near the end of this document.

    \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 \$[ ... ]
     by AEL, and so are the if and while expressions, among others.

    \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.

    \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
      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 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.


\section{Asterisk in a Nutshell}

Asterisk acts as a server. Devices involved in telephony, like DAHDI
cards, or Voip phones, all indicate some context that should be
activated in their behalf. See the config file formats for IAX, SIP,
dahdi.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.

\subsection{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.

\subsection{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 stimuli, and there you have it.

\subsection{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.

\subsection{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!

\section{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
\path{/etc/asterisk/modules.conf}. When the module is loaded, it will look
for 'extensions.ael' in \path{/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.

To reload extensions.ael, the following command can be issued at the
CLI:

    *CLI> ael reload

\section{Debugging}

Right at this moment, the following commands are available, but do
nothing:

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:

1. The messages log in \path{/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.


\section{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
most errors before giving the file to asterisk?

aelparse is compiled in the utils directory of the asterisk release.
It isn't installed anywhere (yet). You can copy it to your favorite
spot in your PATH.

aelparse has two optional arguments:

\begin{itemize}
  \item -d
  \begin{itemize}
    \item Override the normal location of the config file dir, (usually
       \path{/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.
  \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.
  \end{itemize}
\end{itemize}

\section{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
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,

\begin{astlisting}
\begin{verbatim}
if(${x}=1) { NoOp(hello!); goto s,3; } else { NoOp(Goodbye!); goto s,12; }
\end{verbatim}
\end{astlisting}
as you can say:
\begin{astlisting}
\begin{verbatim}
if(${x}=1)
{
       NoOp(hello!);
   goto s,3;
}
else
{
       NoOp(Goodbye!);
       goto s,12;
}
\end{verbatim}
\end{astlisting}

or:

\begin{astlisting}
\begin{verbatim}
if(${x}=1) {
       NoOp(hello!);
   goto s,3;
} else {
       NoOp(Goodbye!);
       goto s,12;
}
\end{verbatim}
\end{astlisting}

or:

\begin{astlisting}
\begin{verbatim}
if (${x}=1) {
       NoOp(hello!); goto s,3;
} else {
       NoOp(Goodbye!); goto s,12;
}
\end{verbatim}
\end{astlisting}

\section{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 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.

The following are keywords in the AEL language:
\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 local
    \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.
    \item catch
    \item switches
    \item eswitches
    \item includes
\end{itemize}


\section{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.

This tree is then handed to the semantic check routine.

Then the tree is handed to the compiler.

After that, it is freed from memory.

A program could be written that could build a tree of pval structures, and
a pretty printing function is provided, that would dump the data to a file,
or the tree could be handed to the compiler to merge the data into the
asterisk dialplan. The modularity of the design offers several opportunities
for developers to simplify apps to generate dialplan data.


\subsection{AEL version 2 BNF}

(hopefully, something close to bnf).

First, some basic objects

\begin{astlisting}
\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>

<objects> :== <object>
           | <objects> <object>


<object> :==  <context>
         | <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> ';'


<arglist> :== <word>
         | <arglist> ',' <word>


<elements> :==  <element>
             | <elements> <element>


<element> :== <extension>
         | <includes>
         | <switches>
         | <eswitches>
         | <ignorepat>
         | <word> '='  <collected-word> ';'
         | 'local' <word> '='  <collected-word> ';'
         | ';'


<ignorepat> :== 'ignorepat' '=>' <word> ';'


<extension> :== <word> '=>' <statement>
           | 'regexten' <word> '=>' <statement>
           | 'hint' '(' <word3-list> ')' <word> '=>' <statement>
           | 'regexten' 'hint' '(' <word3-list> ')' <word> '=>' <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> ')'


<word3-list> :== <word>
       | <word> <word>
       | <word> <word> <word>

<switch_head> :== 'switch' '(' <collected-word> ')'  '{'


<statement> :== '{' <statements> '}'
       | <word> '='  <collected-word> ';'
       | 'local' <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>