Summary:ASTERISK-06814: [branch][post 1.4] AAL -- Asterisk Argument Language
Reporter:Steve Murphy (murf)Labels:
Date Opened:2006-04-19 09:18:21Date Closed:2006-08-05 03:01:00
Versions:Frequency of
Description:An interface to publish facts about the inputs and outputs of
asterisk applications and functions, for usage both internally by
asterisk and its apps and funcs, and externally by other applications, such
as documentation generation, syntax/semantics checking, etc.

An interface to provide "conformant" apps and funcs with a simple way
to parse, extract, and access the data passed to them, issue warnings
and errors concerning missing and unexpected inputs.

An interface to provide all apps and funcs with an uniform "look and feel" as far as the argument processing is concerned.

Design goal: Minimal functional impact. All apps should be upward compatible, no users should have to change their existing dialplans, unless the app is breaking some fundamental rule and desperately needs to be fixed anyway. Hopefully the set of such apps/funcs is very small or empty.


See working branch https://origsvn.digium.com/svn/asterisk/team/murf/AAL
or: http://svn.digium.com/svn/asterisk/team/murf/AAL, for the casual user.
Comments:By: Steve Murphy (murf) 2006-04-19 15:05:32

Dear Diary:

I will here set down my thoughts on the architecture and high level implementation of AAL, and perhaps those wiser than I, but foolish enough to read this, may offer some input.

Initial Thinking on the Architecture of AAL:

1. Each function and application will define a single string, stored within its source files, that describes its arguments in order and type, and name, it's output in the form of channel variables, and their type and possible values. A list of options that app/func accepts, and any args the opts accept, and any return values a function may return.

This string may end up being a new module attribute (like description, or key), or it could be embedded within the description string. Personally, I like the thought of embedding it in the description string... no new attrs, no big changes, except to filter it out if you want to print the description to the user. A special sequence of characters would mark its beginning and end.

2. If an app has no AAL description it is "AAL non-compliant". If it does, have such a string, and is using it to parse its args, then it would be "AAL compliant". It's compliancy could be another property that a module could assert...

3. The AAL string would be compiled into a binary format at load time. and the memory could be freed at unload/reload time.

4. For external usage, the build process of Asterisk would include a process to find all the AAL strings defined by possibly using grep and/or sed on the sources, and generating the "applist" file. A file parser will be made available to read this file format and provide the same binary structures that would be available to the apps.  (Sorry, can't think of anything better! Requiring Asterisk to be running nearby and using the manager iface to fetch the data is impracticable in many cases; Supplying a separate server to serve this data plain overkill. If anyone has a "better idea", best speak up soon!)

5. Apps and funcs would use an AAL function to convert the arg data string into values stored in a list of variable pointer, much like sscanf, only way different ;^). The input would be AAL description for that app/func, and the arg data string, and a list of pointers to variables to set (vararg). The result, a count of how variables were assigned values, how many errors found in the input, perhaps the logs would contain notices about problems. If any cacheing of arguments, etc. is done, it would be done here, to speed up the processing of the data.
 Along this line, I've noticed some args are LISTS, and that some funcs accept the same sort of lists as some others. I'll try to enumerate these sorts of args, and perhaps we can treat these value types as an object, and split such data into a list of pre-parsed data. For instance, Dial() takes tech specs, like "Zap/3r2&Zap/5r1&Zap/4r3"... these can be preparsed, and simple AAL funcs provided to walk the list of structures where all the data is stored for each item. Why have duplicated code in what could be several apps, doing the same (and possibly buggy) thing as others?

That's it for now. Perhaps more later.

By: Russell Bryant (russell) 2006-08-05 03:01:00

I think it would be best if we start to discourage the use of mantis as a discussion forum.  It is just a horrible tool for that purpose.

If you would like to discuss further development on this, let's do it on the asterisk-dev list.  If you'd like to keep a "diary" of development notes, you could do it in a file in your svn branch, and it would live in the svn history for forever.

Thanks ...