#$EPIC: symbolctl.txt,v 1.6 2008/11/30 19:14:38 jnelson Exp $ ======Synopsis:====== $__symbolctl__(TYPES) \\ $__symbolctl__(PMATCH ) \\ $__symbolctl__(CREATE ) \\ $__symbolctl__(DELETE ) \\ $__symbolctl__(DELETE ) \\ $__symbolctl__(CHECK ) \\ $__symbolctl__(GET LEVELS) \\ $__symbolctl__(GET ) \\ $__symbolctl__(GET ) \\ $__symbolctl__(SET ) \\ =====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 | [[Set]]s 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 ) ====Synopsis:==== Given a that was returned by $symbolctl(TYPES), or the literal string "*" to mean all types, and a wildcard 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 ) ====Synopsis:==== Ensure that 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 ) @ symbolctl(DELETE ) ====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 ) ====Synopsis:==== Inspects to see if it has any values left. If there are no values left for , 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, == 1 always refers to the "current" value of a symbol. If you do /[[STACK]] PUSH, then the value you pushed will be copied to == 2. If you /[[STACK]] PUSH something else, that original value moves to == 3, and the second value you pushed because the new == 2. So what you can do is use $symbolctl(GET LEVELS) to find out how many levels a symbol has, and then use $symbolctl(GET ) 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, 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 LEVELS) ====Synopsis:==== Return the number of levels of that are /STACKed. This value is always 1 unless you have /STACK PUSHed something. ====Usage:==== $symbolctl(GET ) ====Synopsis:==== Return all of the s that are defined for at . If is 1, it gets the current value(s). If is > 1, it starts looking at the /STACK PUSHed values. =====Getting information about ALIAS symbols===== ====Usage:==== $symbolctl(GET ALIAS VALUE) \\ $symbolctl(GET ALIAS STUB) \\ $symbolctl(GET ALIAS PACKAGE) \\ $symbolctl(GET ALIAS ARGLIST) ====Synopsis:==== Retrieve one of the values for one of your aliases =====Getting information about ASSIGN symbols===== ====Usage:==== $symbolctl(GET ASSIGN VALUE) \\ $symbolctl(GET ASSIGN STUB) \\ $symbolctl(GET ASSIGN PACKAGE) ====Synopsis:==== Retrieve one of the values for one of your assigns =====Getting information about ASSIGN symbols===== ====Usage:==== $symbolctl(GET BUILTIN_COMMAND) \\ $symbolctl(GET BUILTIN_FUNCTION) \\ $symbolctl(GET 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 BUILTIN_VARIABLE TYPE) \\ $symbolctl(GET BUILTIN_VARIABLE DATA) \\ $symbolctl(GET BUILTIN_VARIABLE BUILTIN) \\ $symbolctl(GET BUILTIN_VARIABLE SCRIPT) \\ $symbolctl(GET 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 ALIAS VALUE ) \\ @ symbolctl(SET ALIAS STUB ) \\ @ symbolctl(SET ALIAS PACKAGE ) \\ @ symbolctl(SET ALIAS ARGLIST ) ====Synopsis:==== Change one of the values for one of your aliases. If you omit the , it will clear the value. ====Usage:==== @ symbolctl(SET ASSIGN VALUE ) \\ @ symbolctl(SET ASSIGN STUB ) \\ @ symbolctl(SET ASSIGN PACKAGE ) ====Synopsis:==== Change one of the values for one of your assigns. If you omit the , it will clear the value. =====CREATING A NEW [[SET]] ===== ====Usage:==== @ symbolctl(SET BUILTIN_VARIABLE) ====Syopsis:==== Create a new user-created /SET with default values (type == BOOL, data == OFF, script is .) =====Changing the information about BUILTIN VARIABLE (/SET) symbols===== @ symbolctl(SET BUILTIN_VARIABLE TYPE ) \\ @ symbolctl(SET BUILTIN_VARIABLE DATA ) \\ @ symbolctl(SET BUILTIN_VARIABLE BUILTIN) \\ @ symbolctl(SET BUILTIN_VARIABLE SCRIPT ) \\ @ symbolctl(SET 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 ( 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.