$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>)

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

$symbolctl(TYPES)

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

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.

 $symbolctl(TYPES)

returns

 "ALIAS ASSIGN BUILTIN_COMMAND BUILTIN_FUNCTION BUILTIN_EXPANDO BUILTIN_VARIABLE"

$symbolctl(PMATCH <type> <pattern>)

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!

 $symbolctl(PMATCH BUILTIN_COMMANDS li*)

returns

 "LICENSE LINKS LIST"

@ symbolctl(CREATE <symbol>)

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.

 @ 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.

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

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!

 @ symbolctl(DELETE booya ALIAS)

@ symbolctl(CHECK <symbol>)

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.

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.

$symbolctl(GET <symbol> LEVELS)

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

$symbolctl(GET <symbol> <level>)

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.

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

Retrieve one of the values for one of your aliases

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

Retrieve one of the values for one of your assigns

$symbolctl(GET <symbol> <level> BUILTIN_COMMAND)
$symbolctl(GET <symbol> <level> BUILTIN_FUNCTION)
$symbolctl(GET <symbol> <level> BUILTIN_EXPANDO)

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.

$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)

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.

@ 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>)

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

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

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

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

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

@ 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)

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.