<!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. 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>
"show application XXXX" for each one, and looked at the argument<BR>
descriptions. To be specific, I was interested in the first line of <BR>
the "[Description]" 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 "architectural" 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 "[Description]", 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 "NoOp(rawString)" <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 "Stop playing a tone list". it should <BR>
have a call summary like almost every other app... it <BR>
should at least explicitly state "StopPlayTones()". It might <BR>
also be nice if it explicitly said something like "Will stop <BR>
playing any Tonelist that might be currently playing on <BR>
the current channel."...<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>
[|minimumWordLength][|betweenWordsSilence][|maximumNumberOfWords]<BR>
[|silenceThreshold])<BR>
<BR>
My GUESS at what the syntax really might be would be more like this:<BR>
<BR>
AMD( [initialSilence] | [greeting] | [afterGreetingSilence] | [totalAnalysisTime]<BR>
| [minimumWordLength] | [betweenWordsSilence] | [maximumNumberOfWords]<BR>
| [silenceThreshold] )<BR>
<BR>
Better yet,<BR>
<BR>
AMD( [ [initialSilence] | [greeting] | [afterGreetingSilence] | [totalAnalysisTime]<BR>
| [minimumWordLength] | [betweenWordsSilence] | [maximumNumberOfWords]<BR>
| [silenceThreshold] ] )<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] [ | [afterGreetingSilence] [ | [totalAnalysisTime]<BR>
[ | [minimumWordLength] [ | [betweenWordsSilence] [ | [maximumNumberOfWords]<BR>
[ | [silenceThreshold] ] ] ] ] ] ] ] )<BR>
<BR>
which would allow you to drop any <BR>
trailing "|"'s from after the last non-empty arg...? <BR>
For instance, if you wanted to override JUST the <BR>
"betweenWordsSilence" 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>
Background(filename1[&filename2...] [ |options [ | langoverride ] [ | context ] ] ):<BR>
<BR>
Again, the way it's written, if only one value follows "options", <BR>
is it langoverride, or context? Is it really not meant to say:<BR>
<BR>
Background(filename1[&filename2...] [ | [options] [ | [ langoverride ] [ | context ] ] ] )<BR>
<BR>
Which, if you just wanted to specify a context, with no options <BR>
or override, you would say:<BR>
<BR>
Background(zeeble&Zorkfest||mycontext)<BR>
<BR>
or, just to supply an option, and leave out any trailing | separators:<BR>
<BR>
Background(zeeble&Zorkfest|x)<BR>
<BR>
Am I right?<BR>
<BR>
<BR>
Next, ControlPlayback:<BR>
<BR>
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>
ControlPlayback(file [ | [skipms] [ | [ ff ] [ | [rew] [ | [ stop] [ | [pause] [ | [restart] [ | options ] ] ] ] ] ] ] )<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>
Dial(Technology/resource[&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>
Dial(Technology/resource[&Tech2/resource2...] [ | [timeout ] [ | [ options ] [ | URL ] ] ] ) <BR>
<BR>
<BR>
<BR>
Next, Read:<BR>
<BR>
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>
Read(variable [ | [filename ] [ | [ maxdigits ] [ | [ option ] [ | [ attempts ] [ | timeout ] ] ] ] ] )<BR>
<BR>
So, if all you want to do is specify a timeout, then it would be:<BR>
<BR>
Read(x|||||15)<BR>
<BR>
And if just specify a filename, it would be:<BR>
<BR>
Read(bigfile)<BR>
<BR>
<BR>
Next, RxFAX:<BR>
<BR>
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>
RxFAX(filename [ | [caller ] [ | debug ] ] )<BR>
<BR>
<BR>
<BR>
And, lastly, for now, SMS:<BR>
<BR>
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>