Table of Contents

#$EPIC: symbolctl.txt,v 1.6 2008/11/30 19:14:38 jnelson Exp $

Synopsis:

$symbolctl(TYPES)
$symbolctl(PMATCH <type> <pattern>)
$symbolctl(CREATE <symbol>)
$symbolctl(DELETE <symbol>)
$symbolctl(DELETE <symbol> <type>)
$symbolctl(CHECK <symbol>)
$symbolctl(GET <symbol> LEVELS)
$symbolctl(GET <symbol> <level>)
$symbolctl(GET <symbol> <level> <type> <operation>)
$symbolctl(SET <symbol> <level> <type> <operation> <value>)

Description:

This function is a low-level interface to the unified symbol table. For practical uses, read using symbolctl.

The TYPES operation

Usage:

$symbolctl(TYPES)

Synopsis:

The TYPES operation returns a list of types that are supported by this function. At the time this was written, that list is:

Type Description
ALIAS Commands and functions you create with alias
ASSIGN Variables you create with assign, but not local
BUILTIN_COMMAND Commands that are built in like msg or alias
BUILTIN_FUNCTION Functions that are built in like word or symbolctl.
BUILTIN_EXPANDO Variables that are built in like $E and $Z and $T
BUILTIN_VARIABLE Sets that are built in like set high_bit_escape and set mail_interval

More types may be supported in the future, so for forwards and backwards compatability it is useful to check this to make sure you are operating on a valid type.

Examples:

 $symbolctl(TYPES)

returns

 "ALIAS ASSIGN BUILTIN_COMMAND BUILTIN_FUNCTION BUILTIN_EXPANDO BUILTIN_VARIABLE"

The PMATCH operation

Usage:

$symbolctl(PMATCH <type> <pattern>)

Synopsis:

Given a <type> that was returned by $symbolctl(TYPES), or the literal string “*” to mean all types, and a wildcard pattern <pattern>, the PMATCH operation returns all of the symbols of that type that are matched by the pattern. If no symbols match the pattern, then the empty string is returned.

This is very handy for doing command completion at the input line!

Examples:

 $symbolctl(PMATCH BUILTIN_COMMANDS li*)

returns

 "LICENSE LINKS LIST"

The CREATE operation

Usage:

@ symbolctl(CREATE <symbol>)

Synopsis:

Ensure that <symbol> exists in the global symbol table. When symbols are first created, they do not contain any actual values, but act as placeholders in case you want to set values. It is necessary to ensure that a symbol exists before you try to change any of its type values. CREATEing a symbol that already exists is harmless; feel free to do it.

Examples:

 @ symbolctl(CREATE frobnitz)
 @ symbolctl(SET frobnitz 1 BUILTIN_VARIABLE)

This creates a /set frobnitz as a boolean value with default value of OFF. If you didn't do the CREATE first, then the SET would fail if “frobnitz” did not exist in the symbol table.

The DELETE operation:

Usage:

@ symbolctl(DELETE <symbol>) @ symbolctl(DELETE <symbol> <type>)

Synopsis:

Delete all of the values of a particular symbol (first form) or just one type (second form). WARNING: You are permitted to delete built in variables, commands, and functions with this! There is no way to restore them back if you make a mistake! Take caution!

Examples:

 @ symbolctl(DELETE booya ALIAS)

The CHECK operation

Usage:

@ symbolctl(CHECK <symbol>)

Synopsis:

Inspects <symbol> to see if it has any values left. If there are no values left for <symbol>, it is DELETEd from the global symbol table. You must then CREATE it again if you want to use it later. Why do you want to CHECK values? Because empty symbols still take up space in the symbol table and still effect lookup/insert/delete performance.

AN IMPORTANT NOTE ABOUT "LEVELS"

In order to “get” or “set” a symbol's values, the symbol needs to exist. If you try to “get” or “set” a symbol that doesn't exist, symbolctl will return the empty string to tell you that it failed. You need to use the CREATE operation above to bootstrap a new symbol before using it.

Now, /STACK PUSH and /STACK POP work by manipulating “levels” in the symbol table. By rule, <level> == 1 always refers to the “current” value of a symbol. If you do /STACK PUSH, then the value you pushed will be copied to <level> == 2. If you /STACK PUSH something else, that original value moves to <level> == 3, and the second value you pushed because the new <level> == 2.

So what you can do is use $symbolctl(GET <symbol> LEVELS) to find out how many levels a symbol has, and then use $symbolctl(GET <symbol> <num>) to find out what types are available at that level so you can see if any of them are interesting to you. IN THIS WAY you can directly manipulate the stack push values without having to actually use the stack command.

In general, <level> is always 1 for everything you want to do, unless you are intentionally monkeying around with your /stack values.

NOW BACK TO YOUR REGULARLY SCHEDULED HELP

Getting information about the symbol table

Usage:

$symbolctl(GET <symbol> LEVELS)

Synopsis:

Return the number of levels of <symbol> that are /STACKed. This value is always 1 unless you have /STACK PUSHed something.

Usage:

$symbolctl(GET <symbol> <level>)

Synopsis:

Return all of the <type>s that are defined for <symbol> at <level>. If <level> is 1, it gets the current value(s). If <level> is > 1, it starts looking at the /STACK PUSHed values.

Getting information about ALIAS symbols

Usage:

$symbolctl(GET <symbol> <level> ALIAS VALUE)
$symbolctl(GET <symbol> <level> ALIAS STUB)
$symbolctl(GET <symbol> <level> ALIAS PACKAGE)
$symbolctl(GET <symbol> <level> ALIAS ARGLIST)

Synopsis:

Retrieve one of the values for one of your aliases

Getting information about ASSIGN symbols

Usage:

$symbolctl(GET <symbol> <level> ASSIGN VALUE)
$symbolctl(GET <symbol> <level> ASSIGN STUB)
$symbolctl(GET <symbol> <level> ASSIGN PACKAGE)

Synopsis:

Retrieve one of the values for one of your assigns

Getting information about ASSIGN symbols

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.

Getting information about BUILTIN VARIABLE (/SET) symbols

Usage:

$symbolctl(GET <symbol> <level> BUILTIN_VARIABLE TYPE)
$symbolctl(GET <symbol> <level> BUILTIN_VARIABLE DATA)
$symbolctl(GET <symbol> <level> BUILTIN_VARIABLE BUILTIN)
$symbolctl(GET <symbol> <level> BUILTIN_VARIABLE SCRIPT)
$symbolctl(GET <symbol> <level> BUILTIN_VARIABLE FLAGS)

Synopsis:

Retrieve information about a SET. The “TYPE” is one of “STR”, “INT”, “BOOL”, or “CHAR” Generally, either “BUILTIN” or “SCRIPT” is set, but not both.

CHANGING information about ALIAS symbols

Usage:

@ symbolctl(SET <symbol> <level> ALIAS VALUE <string>)
@ symbolctl(SET <symbol> <level> ALIAS STUB <string>)
@ symbolctl(SET <symbol> <level> ALIAS PACKAGE <string>)
@ symbolctl(SET <symbol> <level> ALIAS ARGLIST <string>)

Synopsis:

Change one of the values for one of your aliases. If you omit the <string>, it will clear the value.

Usage:

@ symbolctl(SET <symbol> <level> ASSIGN VALUE <string>)
@ symbolctl(SET <symbol> <level> ASSIGN STUB <string>)
@ symbolctl(SET <symbol> <level> ASSIGN PACKAGE <string>)

Synopsis:

Change one of the values for one of your assigns. If you omit the <string>, it will clear the value.

CREATING A NEW [[SET]]

Usage:

@ symbolctl(SET <symbol> <level> BUILTIN_VARIABLE)

Syopsis:

Create a new user-created /SET with default values (type == BOOL, data == OFF, script is <empty>.)

Changing the information about BUILTIN VARIABLE (/SET) symbols

@ symbolctl(SET <symbol> <level> BUILTIN_VARIABLE TYPE <set-type>)
@ symbolctl(SET <symbol> <level> BUILTIN_VARIABLE DATA <string>)
@ symbolctl(SET <symbol> <level> BUILTIN_VARIABLE BUILTIN)
@ symbolctl(SET <symbol> <level> BUILTIN_VARIABLE SCRIPT <code>)
@ symbolctl(SET <symbol> <level> BUILTIN_VARIABLE FLAGS)

Synopsis:

Change one of the values for one of your set's. You cannot change values for system set's, sorry. Setting the TYPE value changes the DATA value to a default (<empty> for strings, 0 for everything else) so always set DATA after setting TYPE. Yes, you can change the TYPE of a set after you create it! It's probably a bad idea to set FLAGS for the present.