<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 TRANSITIONAL//EN">
<HTML>
<HEAD>
  <META HTTP-EQUIV="Content-Type" CONTENT="text/html; CHARSET=UTF-8">
  <META NAME="GENERATOR" CONTENT="GtkHTML/3.3.2">
</HEAD>
<BODY>
Hello--<BR>
<BR>
First of all, this post is in HTML mode, because it is almost totally unreadable in plain ascii! My <BR>
mail package is in the habit of forcing lines to be less than 80 columns, which destroys the<BR>
readability. So please, bear with me.<BR>
<BR>
I'm beginning work on AAL (Asterisk Argument Language)... at least, <BR>
I'm thinking about it. What is that, why should you care about it? Well, <BR>
my intention is to have it be a formal specification of the arguments an <BR>
app or function will expect to be passed. AAL will supply functions to <BR>
automatically split the incoming string into the separate arguments, and <BR>
do argument checking.&nbsp; It could easily serve as a source for generating <BR>
documentation about the app/function, at least a part of it. It will also <BR>
allow automatic argument checking to be done at load time, instead <BR>
of at invocation time.<BR>
<BR>
I've got a crude attempt at it in AEL2, but, it's just not right. (See the applist file).<BR>
<BR>
To get a an idea of what its full scope needs to be, I need to understand <BR>
all the args of all the apps and funcs. And the descriptions provided for <BR>
some of them are just PLAIN WRONG.<BR>
<BR>
I've gone thru all 145 apps in the trunk branch. I've done a<BR>
 &quot;show application XXXX&quot; for each one, and looked at the argument<BR>
 descriptions. To be specific, I was interested in the first line of <BR>
the &quot;[Description]&quot; category. I separated out the apps that <BR>
have problems.<BR>
<BR>
Now, I guess I could file bugs against each problem I outline <BR>
below, but really, that wouldn't be appropriate. In the end, I think <BR>
AAL could replace the document strings I'm pointing out, and <BR>
therefore, the point is not to fix the problems I'm pointing out, but to <BR>
collect the proper info, and come up with something that will be <BR>
more formal, and correct by design, so speak. <BR>
<BR>
It would be nice if the experts/authors/heavy users of the below <BR>
apps would respond to the comments I make, affirming my <BR>
assumptions, or correcting them, then I will have some reliable <BR>
info to refer to. Telling me to study the source for 145 apps is not <BR>
a very nice, nor a very practical thing to do!<BR>
<BR>
And, lastly, AAL is definitely an &quot;architectural&quot; thing. Therefore, <BR>
I guess it's a target for 1.5 or 1.6, as I just recently saw that 1.4 i<BR>
s architecturally closed...<BR>
<BR>
Now, on to the issues!<BR>
<BR>
First of all, is it completely true that none of the following take any <BR>
arguments? For instance, I KNOW that NoOp is a lie! It takes args <BR>
and it prints them out to the console when it is invoked...<BR>
<BR>
<BR>
GetCPEID<BR>
LookupCIDName<BR>
StopPlayTones() <BR>
NBScat<BR>
NoOp()<BR>
PauseMonitor<BR>
StopMonitor<BR>
StopMusicOnHold<BR>
UnpauseMonitor<BR>
<BR>
Technically, based on convention, in that first line of <BR>
the &quot;[Description]&quot;, I'd expect to see something like () <BR>
after the name if the app indeed takes no args. For an <BR>
app like NoOp(), I'd expect it to say &quot;NoOp(rawString)&quot; <BR>
or something. It wasn't super clear that the 9 apps above <BR>
were really argument free, at least not from just reading. <BR>
But, for the purposes of documentation, they should <BR>
be accurate...<BR>
<BR>
For instance, StopPlayTones doesn't follow convention<BR>
 at all. All it says is &quot;Stop playing a tone list&quot;.&nbsp; it should <BR>
have a call summary like almost every other app... it <BR>
should at least explicitly state &quot;StopPlayTones()&quot;. It might <BR>
also be nice if it explicitly said something like &quot;Will stop <BR>
playing any Tonelist that might be currently playing on <BR>
the current channel.&quot;...<BR>
<BR>
<BR>
<BR>
Next, AMD: The way the args are written, any of the <BR>
args could simply dropped, along with its separator, <BR>
but this is nonsense! There is no way to tell, if say, <BR>
only one arg is included, which it could be. They all <BR>
seem to be numeric.<BR>
<BR>
AMD([initialSilence][|greeting][|afterGreetingSilence][|totalAnalysisTime]<BR>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; [|minimumWordLength][|betweenWordsSilence][|maximumNumberOfWords]<BR>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; [|silenceThreshold])<BR>
<BR>
My GUESS at what the syntax really might be would be more like this:<BR>
<BR>
AMD( [initialSilence] | [greeting]&nbsp; | [afterGreetingSilence] |&nbsp; [totalAnalysisTime]<BR>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; |&nbsp; [minimumWordLength]&nbsp; | [betweenWordsSilence] |&nbsp; [maximumNumberOfWords]<BR>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; | [silenceThreshold] )<BR>
<BR>
Better yet,<BR>
<BR>
AMD( [&nbsp; [initialSilence] | [greeting]&nbsp; | [afterGreetingSilence] |&nbsp; [totalAnalysisTime]<BR>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; |&nbsp; [minimumWordLength]&nbsp; | [betweenWordsSilence] |&nbsp; [maximumNumberOfWords]<BR>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; | [silenceThreshold]&nbsp;&nbsp; ]&nbsp; )<BR>
<BR>
Because I get the feel that if what's in the config file <BR>
is OK, you don't have to supply any args at all. But if <BR>
you just want to override one value, you'd best use <BR>
separators to indicate which one....<BR>
<BR>
Perhaps this might be even more accurate:<BR>
<BR>
AMD( [initialSilence] [ | [greeting]&nbsp; [ | [afterGreetingSilence]&nbsp; [&nbsp; |&nbsp; [totalAnalysisTime]<BR>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; [&nbsp; |&nbsp; [minimumWordLength]&nbsp; [ | [betweenWordsSilence]&nbsp; [&nbsp; |&nbsp; [maximumNumberOfWords]<BR>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; [&nbsp; |&nbsp; [silenceThreshold]&nbsp; ] ] ] ] ] ] ]&nbsp; )<BR>
<BR>
which would allow you to drop any <BR>
trailing &quot;|&quot;'s from after the last non-empty arg...? <BR>
For instance, if you wanted to override JUST the <BR>
&quot;betweenWordsSilence&quot; to 2928, you would write:<BR>
<BR>
AMD(|||||2928)<BR>
<BR>
Which is it really?<BR>
<BR>
<BR>
Next, the Background app's description:<BR>
<BR>
&nbsp; Background(filename1[&amp;filename2...]&nbsp;&nbsp; [ |options [ | langoverride ] [ | context ]&nbsp;&nbsp; ] ):<BR>
<BR>
Again, the way it's written, if only one value follows &quot;options&quot;, <BR>
is it&nbsp; langoverride, or context?&nbsp; Is it really not meant to say:<BR>
<BR>
&nbsp; Background(filename1[&amp;filename2...] [ | [options]&nbsp; [ | [ langoverride ]&nbsp; [ |&nbsp; context&nbsp; ] ] ]&nbsp; )<BR>
<BR>
Which, if you just wanted to specify a context, with no options <BR>
or override, you would say:<BR>
<BR>
Background(zeeble&amp;Zorkfest||mycontext)<BR>
<BR>
or, just to supply an option, and leave out any trailing | separators:<BR>
<BR>
Background(zeeble&amp;Zorkfest|x)<BR>
<BR>
Am I right?<BR>
<BR>
<BR>
Next, ControlPlayback:<BR>
<BR>
&nbsp; ControlPlayback(file[|skipms[|ff[|rew[|stop[|pause[|restart|options ] ] ] ] ] ] ] )<BR>
<BR>
First of all, there are 6 opening brackets, and 7 closing. <BR>
Next, the options arg is not optional, which <BR>
really doesn't make much sense, and binds it to the <BR>
restart value-- basically, if you specify a restart<BR>
value, you MUST supply the options, even if it is empty...<BR>
<BR>
This may be a simple omission, in which case, the spec would be:<BR>
<BR>
&nbsp; ControlPlayback(file [ | [skipms] [ | [ ff ]&nbsp; [ |&nbsp; [rew]&nbsp; [ |&nbsp; [ stop]&nbsp; [ |&nbsp; [pause]&nbsp; [ |&nbsp; [restart]&nbsp; [ | options ] ] ] ] ] ] ]&nbsp; )<BR>
<BR>
So, if all you want to do is specify an option, you have to toss 7 separators in front of it.<BR>
<BR>
(And, of course, my insertion of spaces is purely for readability!)<BR>
<BR>
<BR>
<BR>
Next, Dial:<BR>
<BR>
&nbsp; Dial(Technology/resource[&amp;Tech2/resource2...][|timeout][|options][|URL])<BR>
<BR>
Again, according to this syntax, I could leave out the <BR>
timeout and options, and just specify the URL by saying:<BR>
<BR>
Dial(Zap/1|<A HREF="http://whatever.com/whatever.gif)">http://whatever.com/whatever.gif)</A><BR>
<BR>
or did I just specify a nonsense timeout?<BR>
<BR>
Isn't the syntax really:<BR>
<BR>
&nbsp; Dial(Technology/resource[&amp;Tech2/resource2...] [ | [timeout ] [ | [ options ]&nbsp; [&nbsp; | URL ] ] ] ) <BR>
<BR>
<BR>
<BR>
Next, Read:<BR>
<BR>
&nbsp; Read(variable[|filename][|maxdigits][|option][|attempts][|timeout])<BR>
<BR>
Again, since the separator is included with each <BR>
optional arg, you can drop any of them, and<BR>
there's no practical way of telling which is which. <BR>
This can't be right, so perhaps the real syntax is:<BR>
<BR>
&nbsp; Read(variable [ |&nbsp; [filename ]&nbsp; [ | [ maxdigits ]&nbsp; [ | [ option ]&nbsp; [ | [ attempts ]&nbsp; [ | timeout ]&nbsp; ]&nbsp; ] ] ] )<BR>
<BR>
So, if all you want to do is specify a timeout, then it would be:<BR>
<BR>
&nbsp; Read(x|||||15)<BR>
<BR>
And if just specify a filename, it would be:<BR>
<BR>
&nbsp; Read(bigfile)<BR>
<BR>
<BR>
Next, RxFAX:<BR>
<BR>
&nbsp; RxFAX(filename[|caller][|debug])<BR>
<BR>
Same sort of complaint as in previous apps... if <BR>
just one of caller or debug is stated, how<BR>
can the app tell which it is?<BR>
<BR>
The real syntax is perhaps:<BR>
<BR>
&nbsp; RxFAX(filename [ | [caller ] [ | debug ] ] )<BR>
<BR>
<BR>
<BR>
And, lastly, for now, SMS:<BR>
<BR>
&nbsp; SMS(name|[a][s])<BR>
<BR>
Now, this seems like either or both the letters a and s <BR>
 could appear after the name argument.<BR>
Are these not options, and should be specified as<BR>
 such (as nearly every other app has, even when<BR>
 there's only one of them)?<BR>
<BR>
<BR>
<BR>
<BR>
<BR>
</BODY>
</HTML>