Site Tools


symbolctl
no way to compare when less than two revisions

Differences

This shows you the differences between two versions of the page.


symbolctl [2008/11/30 19:14] (current) – created - external edit 127.0.0.1
Line 1: Line 1:
 +#$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 | [[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 <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.
 +
 +
  
symbolctl.txt · Last modified: 2008/11/30 19:14 by 127.0.0.1