#$EPIC: using_symbolctl.txt,v 1.1 2008/11/30 19:14:38 jnelson Exp $
======Things you can do with symbolctl:======

=====Create your own SETs======
You can create your own [[set]] with symbolctl.  The [[addset]] script makes
this very simple for you.

   alias addset (name, type, ...) {
        if (@name && type) {
                @ symbolctl(create $name);
                @ symbolctl(set $name 1 builtin_variable type $type);
                if (@) {
                        @ symbolctl(set $name 1 builtin_variable script $*);
                };
        };
   };

Creating a set requires three steps:
    @ symbolctl(create $name)
First you have to make sure that the symbol name exists in the symbol table.
You can't manipulate a symbol name that doesn't exist.

    @ symbolctl(set $name 1 builtin_variable type $type)
Next you have to define the type of [[set]] that your [[set]] will be.  This
can either be BOOL, CHAR, INT, or STR.  BOOL mean you can [[set]] it to OFF 
or ON.  CHAR means you can set it to a single character.  INT means you can 
set it to a number.  STR means you can set it to any string.   By defining
its type, you implicitly create the [[set]].

    @ symbolctl(set $name 1 builtin_variable script $*)
Finally you can give it some code that you want to have executed every time the
[[set]] is changed.  You would ordinarily pass in a block statement, surrounded
by curly braces {....}.  The new value is already set, and is passed in as $*,
and you can overrule it by changing the set in your own code.

=====Example:=====
    addset cantturnmeoff bool {
        if (* == [ON]) {
	    echo Sorry dave, I can't let you do that.
	    set cantturnmeoff off
	}
    }

=====Doing command completion:=====
$symbolctl(PMATCH <type> <pattern>)
   $symbolctl(PMATCH BUILTIN_COMMANDS li*)
returns 
   "LICENSE LINKS LIST"


=====Checking to see if something exists before using it:=====
====Usage:====
$symbolctl(GET <symbol> <level> BUILTIN_COMMAND) \\
$symbolctl(GET <symbol> <level> BUILTIN_FUNCTION) \\
$symbolctl(GET <symbol> <level> BUILTIN_EXPANDO)
====Synopsis:====
Returns 0 if these types are not in use (ie, if there is not a 
built in command), and returns non-zero if there is.  If you're 
smart, you won't try to do anything with the non-zero value.