ael.tex

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

       | <word> '|' <word>
       | <word> '|' <word> '|' <word>
       | 'default' '|' <word> '|' <word>
       | <word> ',' <word>
       | <word> ',' <word> ',' <word>
       | 'default' ',' <word> ',' <word>

<jumptarget> :== <word>
               | <word> ',' <word>
               | <word> ',' <word> '@' <word>
               | <word> '@' <word>
               | <word> ',' <word> '@' 'default'
               | <word> '@' 'default'

<macro_call> :== <word> '(' <eval_arglist> ')'
       | <word> '(' ')'

<application_call_head> :== <word>  '('

<application_call> :== <application_call_head> <eval_arglist> ')'
       | <application_call_head> ')'

<eval_arglist> :==  <collected-word>
       | <eval_arglist> ','  <collected-word>
       |  /* nothing */
       | <eval_arglist> ','  /* nothing */

<case_statements> :== <case_statement>
       | <case_statements> <case_statement>


<case_statement> :== 'case' <word> ':' <statements>
       | 'default' ':' <statements>
       | 'pattern' <word> ':' <statements>
       | 'case' <word> ':'
       | 'default' ':'
       | 'pattern' <word> ':'

<macro_statements> :== <macro_statement>
       | <macro_statements> <macro_statement>

<macro_statement> :== <statement>
       | 'catch' <word> '{' <statements> '}'

<switches> :== 'switches' '{' <switchlist> '}'
       | 'switches' '{' '}'

<eswitches> :== 'eswitches' '{' <switchlist> '}'
       | 'eswitches' '{'  '}'

<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> :== <word>
        | 'default'

<includes> :== 'includes' '{' <includeslist> '}'
       | 'includes' '{' '}'
\end{verbatim}
\end{astlisting}

\section{AEL Example USAGE}

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


\subsection{Context}

Contexts in AEL represent a set of extensions in the same way that
they do in extensions.conf.
\begin{astlisting}
\begin{verbatim}
context default {

}
\end{verbatim}
\end{astlisting}

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.
\begin{astlisting}
\begin{verbatim}
abstract context longdist {
     _1NXXNXXXXXX => NoOp(generic long distance dialing actions in the US);
}
\end{verbatim}
\end{astlisting}

\subsection{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{astlisting}
\begin{verbatim}
context default {
    1234 => Playback(tt-monkeys);
    8000 => {
         NoOp(one);
         NoOp(two);
         NoOp(three);
    };
    _5XXX => NoOp(it's a pattern!);
}
\end{verbatim}
\end{astlisting}

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.

The ability to make extensions match by CID is preserved in
AEL; just use '/' and the CID number in the specification. See below.
\begin{astlisting}
\begin{verbatim}
context default {

    regexten _5XXX => NoOp(it's a pattern!);
}
\end{verbatim}
\end{astlisting}

\begin{astlisting}
\begin{verbatim}
context default {

    hint(Sip/1) _5XXX => NoOp(it's a pattern!);
}
\end{verbatim}
\end{astlisting}

\begin{astlisting}
\begin{verbatim}
context default {

    regexten hint(Sip/1) _5XXX => NoOp(it's a pattern!);
}
\end{verbatim}
\end{astlisting}

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{astlisting}
\begin{verbatim}
context zoombo
{
  819/7079953345 => { NoOp(hello, 3345); }
}
\end{verbatim}
\end{astlisting}

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
another 819 extension defined for all those who wish 819, that are not so lucky
as to have 7079953345 as their CallerID!


\subsection{Includes}

Contexts can be included in other contexts. All included contexts are
listed within a single block.

\begin{astlisting}
\begin{verbatim}
context default {
    includes {
         local;
         longdistance;
         international;
    }
}
\end{verbatim}
\end{astlisting}

Time-limited inclusions can be specified, as in extensions.conf
format, with the fields described in the wiki page Asterisk cmd
GotoIfTime.

\begin{astlisting}
\begin{verbatim}
context default {
    includes {
         local;
         longdistance|16:00-23:59|mon-fri|*|*;
         international;
    }
}
\end{verbatim}
\end{astlisting}

\subsection{\#include}

You can include other files with the \#include "filepath" construct.

\begin{astlisting}
\begin{verbatim}
   #include "/etc/asterisk/testfor.ael"
\end{verbatim}
\end{astlisting}

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
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 \path{/etc/asterisk}).



\subsection{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{astlisting}
\begin{verbatim}
context default {
    switches {
         DUNDi/e164;
         IAX2/box5;
    };
    eswitches {
         IAX2/context@${CURSERVER};
    }
}
\end{verbatim}
\end{astlisting}

\subsection{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{astlisting}
\begin{verbatim}
context outgoing {
    ignorepat => 9;
}
\end{verbatim}
\end{astlisting}

\subsection{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{astlisting}
\begin{verbatim}
globals {
    CONSOLE=Console/dsp;
    TRUNK=DAHDI/g2;
}
\end{verbatim}
\end{astlisting}

Variables can be set within extensions as well.

\begin{astlisting}
\begin{verbatim}
context foo {
    555 => {
         x=5;
         y=blah;
         divexample=10/2
         NoOp(x is ${x} and y is ${y} !);
    }
}
\end{verbatim}
\end{astlisting}

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.

\begin{astlisting}
\begin{verbatim}
context blah {
    s => {
         CALLERID(name)=ChickenMan;
         NoOp(My name is ${CALLERID(name)} !);
    }
}
\end{verbatim}
\end{astlisting}

You can declare variables in Macros, as so:

\begin{astlisting}
\begin{verbatim}
Macro myroutine(firstarg, secondarg)
{
  Myvar=1;
  NoOp(Myvar is set to ${myvar});
}
\end{verbatim}
\end{astlisting}

\subsection{Local Variables}

In 1.2, and 1.4, ALL VARIABLES are CHANNEL variables, including the function
arguments and associated ARG1, ARG2, etc variables. Sorry.

In trunk (1.6 and higher), we have made all arguments local variables to
a macro call. They will not affect channel variables of the same name.
This includes the ARG1, ARG2, etc variables.

Users can declare their own local variables by using the keyword 'local'
before setting them to a value;

\begin{astlisting}
\begin{verbatim}
Macro myroutine(firstarg, secondarg)
{
  local Myvar=1;
  NoOp(Myvar is set to ${Myvar}, and firstarg is ${firstarg}, and secondarg is ${secondarg});
}
\end{verbatim}
\end{astlisting}

In the above example, Myvar, firstarg, and secondarg are all local variables,
and will not be visible to the calling code, be it an extension, or another Macro.

If you need to make a local variable within the Set() application, you can do it this way:
\begin{astlisting}
\begin{verbatim}
Macro myroutine(firstarg, secondarg)
{
  Set(LOCAL(Myvar)=1);
  NoOp(Myvar is set to ${Myvar}, and firstarg is ${firstarg}, and secondarg is ${secondarg});
}
\end{verbatim}
\end{astlisting}

\subsection{Loops}

AEL has implementations of 'for' and 'while' loops.
\begin{astlisting}
\begin{verbatim}
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;
         }
    }
}
\end{verbatim}
\end{astlisting}

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.



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

\begin{astlisting}
\begin{verbatim}
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! );
                       }
          }