[Asterisk-Dev] Astcl - tcl flavored extensions configuration module for Asterisk

[Reed Wade]

I speculated a while back on the list about using tcl to configure 
Asterisk but never had time to pursue this until recently. I've put 
together a first cut at this that actually works pretty well from what I 
can tell.

See-

http://file.cadre5.com/asterisk/

Here's the README-

------------------------

Astcl 0.1
13 April 2004

------------------------
Reed Wade
reed at cadre5.com
------------------------


This version of Astcl is very early. It seems to work without problems
but I haven't tested it in a large installation nor over a long period
of time.

This is a first try and it seems likely to change some.

I'm using it today in a small office (8 people) with an empty
extensions.conf file.


--

Astcl

Astcl works alongside or as a replacement for the standard extensions
configuration (extensions.conf) mechanism. Contexts and extensions can
be created then referenced in either.

Astcl lives with the rest of the Asterisk modules:
	/usr/lib/asterisk/modules/pbx_astcl.so

Two other files are needed:
	/etc/asterisk/astcllib.tcl
	/etc/asterisk/astcl.conf

astcllib.tcl contains a library of useful tcl functions and should
not need to change for your installation. At the moment it contains
the definitions for the ext and user functions.

astcl.conf contains the specific configuration for your installation

If you're not familiar with TCL, see http://www.tcl.tk/doc/
TCL is a lightweight scriptable control interface for systems of
all sorts. At first glance, it seems like a perfect match for
Asterisk.


INSTALLATION

At this time, the installation may be a little twitchy. I'd like
to hear from folks on that. I've only ever built and run this on
one machine (running fedora). It had the 8.3 tcl library installed
already. I did have to download the tcl8.3 sources in order to have a
set of header files to compile against.

Edit the Makefile, you'll probably need to change TCLINCLUDES and
ASTINCLUDES to reflect your locations for tcl and asterisk sources.

TCLINCLUDES     = -I/root/reed/tcl8.3.4/generic
ASTINCLUDES     = -I/root/asterisk/asterisk/include 
-I/root/asterisk/asterisk

You shouldn't need to change anything else.

Type 'make clean all' to build pbx_astcl.so

If that works, type 'make install' to copy it to the asterisk modules
directory.

('make test' doesn't work right now.)

Copy astcllib.tcl and astcl.conf to /etc/asterisk/

Edit astcl.conf (see below) to fit your installation.

Start up Asterisk....


CONFIGURATION

At startup, astcl does this:
	- creates an interpreter instance
	- sets a global tcl variable AST_CONFIG_DIR to the value of
	  the Asterisk config directory (normally /etc/asterisk)
	- creates a command named "context"
	- evaluates $AST_CONFIG_DIR/astcllib.tcl
	- evaluates $AST_CONFIG_DIR/astcl.conf

astcl.conf evaluates as a normal tcl script but has access to the
AST_CONFIG_DIR variable and three new commands: context, user and ext

The context command takes one argument, the name of a new context to
be created. It creates the context, then it creates a new tcl command
with the same name as the context. If you're familiar with TK, this is
similar to the widget creation scheme.

This new command is used in four different ways: to create extensions,
to includes other contexts, add a switch and to set the ignorepat.
Normally, you will not create extensions directly, the "ext" convenience
function provides a sweeter interface.


Example (see samples/astcl.conf for a better one):

set TRUNK Zap/g2

context demo

demo includes othercontext
demo ignorepat 9
demo switch IAX2/blah


ext demo _91NXXNXXXXXX {
	SetCallerID 8656904442|a
	Dial $TRUNK/${EXTEN:1}
	Congestion ""
}


user TYS \
         "Reed Wade" reed at cadre5.com \
         310 Zap/3&IAX2/reedwade
user TYS \
         "Chris Luttrell" cgluttrell at cadre5.com \
         303 Zap/2


context staffExtensions

ext staffExtensions TYS {
         Dial $line|20|r
         ifbusy {
                 Voicemail b$extension
                 Goto default|s|1
         }
         Voicemail u$extension
         Goto default|s|1
}





The ext command takes two forms--

	ext contextName extensionList plan
		OR
	ext contextName gangList plan

Gangs are sets of users created using the "user" command.

	user gang name email ext line


The plan argument to the ext command is a list of commands. The plan
argument is processed as a tcl list, two elements at a time--one command
plus one command argument. So, commands like Hangup and Congestion that
don't normally take arguments need to be provided with a "" per the
example above.

If used to process a gang, the variables $extension and $line are set
to the values associated with the user. If used to process an extension,
$extension is set to the value of the extension passed to the function.
The is the raw extension value (_91NXXNXXXXXX, not 911231234567).

Variables of the form ${var} are treated specially. Though this could
represent a valid tcl variable, the ext command escapes the ${ so that
variables of this form are passed in to the dial plan so you'll still
have access to things like ${EXTEN} when you need it.

The ifbusy command takes a list of commands and associates them with
a priority +100. It only goes one level deep, you can't nest these.

The ext command (and really Astcl itself) is intended to improve the
maintainability of extensions configurations.

Review samples/astcl.conf for more and better examples.


NEED SUGGESTIONS

Let me know what you think, I'll be poking at this further.

The documentation is light so feel free to send mail if you'd like
anything clarified. This will help me add to the docs.



KNOWN BUGS & FUTURE WORK

"reload" is not handled. You must stop and restart Asterisk to rerun the
config evaluater.

There is no mechanism to create macros. (This is not on my todo list.)

The "includes" command doesn't deal with time/date.

Need to improve error checking/reporting all around.

Need to improve logging.

Need to improve this documentation.

'make test' doesn't work.

Can't nest ifbusy.

Need to understand Asterisk internals better to make sure I'm not doing
anything in too broken a way.

Better coordination with contexts created in extensions.conf to improve
cross referencing. (Use name lookups instead of ptr references, notice if
a context already exists before attempting to create a new one.)

Would like to infect other config files (like voicemail) with tcl so that
the entire config can be done this way.

Asterisk db interface.

Asterisk global variable interface.

Find our what other folks would want it to do.

Really, really want to add AGI command interface so I can register
commands as little tcl procs.