Site Tools


symbolctl

Differences

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

Link to this comparison view

symbolctl [2008/11/30 19:14] (current)
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 (external edit)