karl@sugar.hackercorp.com (Karl Lehenbauer) (03/19/90)
Page 1 (printed 2/26/90) Tcl_CreateCommand(tcl) AMIGA 1.3 Tcl_CreateCommand(tcl) NAME Tcl_CreateCommand - define an application-specific command binding SYNOPSIS #include <tcl.h> Tcl_CreateCommand(interp, cmdName, proc, clientData, deleteProc) ARGUMENTS Tcl_Interp *interp (in) Interpreter in which to create new command. char *cmdName (in) Name of new command. Tcl_CreateCommand makes a copy of this value for its own use. int (*proc)() (in) Implementation of new command: proc will be called whenever cmdName is invoked as a command. ClientData clientData (in) Arbitrary one-word value to pass to proc and deleteProc. void (*deleteProc)() (in) Procedure to call before cmdName is deleted from the interpreter; allows for command- specific cleanup. If NULL, then no procedure is called before the command is deleted. DESCRIPTION Tcl_CreateCommand defines a new command in interp and associates it with procedure proc such that whenever cmdName is invoked as a Tcl command (via a call to Tcl_Eval) the Tcl interpreter will call proc to process the command. If there is already a command cmdName associated with the interpreter, it is deleted. Proc should have the following Page 1 (printed 2/26/90) Tcl_CreateCommand(tcl) AMIGA 1.3 Tcl_CreateCommand(tcl) structure: int proc(clientData, interp, argc, argv) ClientData clientData; Tcl_Interp *interp; int argc; char *argv[]; { } The clientData and interp parameters are copies of the clientData and interp arguments given to Tcl_CreateCommand. Typically, clientData points to an application-specific data structure that describes what to do when the command procedure is invoked. Argc and argv describe the arguments to the command, argc giving the number of arguments (including the command name) and argv giving the values of the arguments as strings. The argv array will contain argc+1 values; the first argc values point to the argument strings, and the last value is NULL. Proc must return an integer code that is either TCL_OK, TCL_ERROR, TCL_RETURN, TCL_BREAK, or TCL_CONTINUE. See the Tcl overview man page for details on what these codes mean. Most normal commands will only return TCL_OK or TCL_ERROR. In addition, proc must set interp->result to point to a string value; in the case of a TCL_OK return code this gives the result of the command, and in the case of TCL_ERROR it gives an error message. The Tcl_Return procedure provides an easy interface for setting the return value; for complete details on how the interp->result field is managed, see the Tcl_Interp man page. Before invoking a command procedure, Tcl_Eval sets interp->result to point to an empty string, so simple commands can return an empty result by doing nothing at all. The contents of the argv array are copies made by the Tcl interpreter for the use of proc. Proc may alter any of the strings in argv. However, the argv array is recycled as soon as proc returns, so proc must not set interp->result to point anywhere within the argv values (call Tcl_Return with status TCL_VOLATILE if you want to return something from the argv array). DeleteProc will be invoked when (if) cmdName is deleted. This can occur through a call to Tcl_DeleteCommand or Tcl_DeleteInterp, or by replacing cmdName in another call to Tcl_CreateCommand. DeleteProc is invoked before the command is deleted, and gives the application an opportunity to release any structures associated with the command. DeleteProc should have the following form: void deleteProc(clientData) Page 2 (printed 2/26/90) Tcl_CreateCommand(tcl) AMIGA 1.3 Tcl_CreateCommand(tcl) ClientData clientData; { } The clientData argument will be the same as the clientData argument passed to Tcl_CreateCommand. KEYWORDS bind, command, create, interpreter Page 3 (printed 2/26/90) Tcl_CreateInterp(tcl) AMIGA 1.3 Tcl_CreateInterp(tcl) NAME Tcl_CreateInterp - set up a new Tcl command interpreter SYNOPSIS #include <tcl.h> Tcl_Interp * Tcl_CreateInterp() DESCRIPTION Tcl_CreateInterp creates a new interpreter structure and returns a token for it. The token is required in calls to most other Tcl procedures, such as Tcl_CreateCommand, Tcl_Eval, and Tcl_DeleteInterp. Clients are only allowed to access the fields of Tcl_Interp structures related to command return values; see the Tcl_Interp and Tcl_CreateCommand man pages for details. The new interpreter is initialized with no defined variables and only the built-in Tcl commands. To bind in additional commands, call Tcl_CreateCommand. KEYWORDS command, create, interpreter Page 1 (printed 2/26/90) Tcl_CreateTrace(tcl) AMIGA 1.3 Tcl_CreateTrace(tcl) NAME Tcl_CreateTrace - arrange for command execution to be traced SYNOPSIS #include <tcl.h> Tcl_Trace Tcl_CreateTrace(interp, level, proc, clientData) ARGUMENTS Tcl_Interp *interp (in) Interpreter in which to create new command. int level (in) Only commands at or below this nesting level will be traced. 1 means top-level commands only, 2 means top- level commands or those that are invoked as immediate consequences of executing top-level commands (procedure bodies, bracketed commands, etc.) and so on. void (*proc)() (in) Procedure to call for each command that's executed. See below for details on the calling sequence. ClientData clientData (in) Arbitrary one-word value to pass to proc. DESCRIPTION Tcl_CreateTrace arranges for command tracing. From now on, proc will be invoked before Tcl calls command procedures to process commands in interp. The return value from Tcl_CreateTrace is a token for the trace, which may be passed to Tcl_DeleteTrace to remove the trace. There may be many traces in effect simultaneously for the same command interpreter. Proc should have the following structure: Page 1 (printed 2/26/90) Tcl_CreateTrace(tcl) AMIGA 1.3 Tcl_CreateTrace(tcl) void proc(clientData, interp, level, command, cmdProc, cmdClientData, argc, argv) ClientData clientData; Tcl_Interp *interp; int level; char *command; int (*cmdProc)(); ClientData cmdClientData; int argc; char *argv[]; { } The clientData and interp parameters are copies of the corresponding arguments given to Tcl_CreateTrace. ClientData typically points to an application-specific data structure that describes what to do when proc is invoked. Level gives the nesting level of the command (1 for top- level commands passed to Tcl_Eval by the application, 2 for the next-level commands passed to Tcl_Eval as part of parsing or interpreting level-1 commands, and so on). Command points to a string containing the text of the command, before any argument substitution. CmdProc contains the address of the command procedure that will be called to process the command (i.e. the proc argument of some previous call to Tcl_CreateCommand) and cmdClientData contains the associated client data for cmdProc (the clientData value passed to Tcl_CreateCommand). Argc and argv give the final argument information that will be passed to cmdProc, after command, variable, and backslash substitution. Proc must not modify the command or argv strings. Tracing will only occur for commands at nesting level less than or equal to the level parameter (i.e. the level parameter to proc will always be less than or equal to the level parameter to Tcl_CreateTrace). Calls to proc will be made by the Tcl parser immediately before it calls the command procedure for the command (cmdProc). This occurs after argument parsing and substitution, so tracing for substituted commands occurs before tracing of the commands containing the substitutions. If there is a syntax error in a command, or if there is no command procedure associated with a command name, then no tracing will occur for that command. If a string passed to Tcl_Eval contains multiple commands (bracketed, or on different lines) then multiple calls to proc will occur, one for each command. The command string for each of these trace calls will reflect only a single command, not the entire string passed to Tcl_Eval. KEYWORDS Page 2 (printed 2/26/90) Tcl_CreateTrace(tcl) AMIGA 1.3 Tcl_CreateTrace(tcl) command, create, interpreter, trace Page 3 (printed 2/26/90) Tcl_DeleteCommand(tcl) AMIGA 1.3 Tcl_DeleteCommand(tcl) NAME Tcl_DeleteCommand - remove a command from a Tcl interpreter SYNOPSIS #include <tcl.h> Tcl_DeleteCommand(interp, cmdName) ARGUMENTS Tcl_Interp *interp (in) Interpreter in which to delete command. char *cmdName (in) Name of command to be deleted. DESCRIPTION This procedure deletes a command from a command interpreter. Once the call completes, attempts to invoke cmdName in interp will result in errors. If cmdName isn't bound as a command in interp then Tcl_DeleteCommand does nothing. There are no restrictions on cmdName: it may refer to a built-in command, an application-specific command, or a Tcl procedure. KEYWORDS command, delete, interpreter Page 1 (printed 2/26/90) Tcl_DeleteInterp(tcl) AMIGA 1.3 Tcl_DeleteInterp(tcl) NAME Tcl_DeleteInterp - destroy a Tcl command interpreter SYNOPSIS #include <tcl.h> Tcl_DeleteInterp(interp) ARGUMENTS Tcl_Interp *interp (in) Token for interpreter to be destroyed. DESCRIPTION This procedure destroys a command interpreter and releases all of the resources associated with it, including variables, procedures, and application-specific command bindings. After Tcl_DeleteInterp returns the caller should never again use the interp token. KEYWORDS command, delete, interpreter Page 1 (printed 2/26/90) Tcl_DeleteTrace(tcl) AMIGA 1.3 Tcl_DeleteTrace(tcl) NAME Tcl_DeleteTrace - remove a previously-established command trace SYNOPSIS #include <tcl.h> Tcl_DeleteTrace(interp, trace) ARGUMENTS Tcl_Interp *interp (in) Interpreter containing trace. Tcl_Trace trace (in) Token for trace to be removed (return value from previous call to Tcl_CreateTrace). DESCRIPTION This procedure removes a trace, so that no future calls will be made to the procedure associated with the trace. After Tcl_DeleteTrace returns, the caller should never again use the trace token. KEYWORDS delete, interpreter, trace Page 1 (printed 2/26/90) Tcl_Eval(tcl) AMIGA 1.3 Tcl_Eval(tcl) NAME Tcl_Eval - execute a Tcl command string SYNOPSIS #include <tcl.h> int Tcl_Eval(interp, cmd, flags, termPtr) ARGUMENTS Tcl_Interp *interp (in) Interpreter in which to execute the command. String result will be stored in interp- >result. char *cmd (in) Command (or sequence of commands) to execute. char flags (in) Either TCL_BRACKET_TERM or 0. If 0, then | Tcl_Eval will process | commands from cmd until | it reaches the null | character at the end of | the string; newlines | will be treated as | command separators. If | TCL_BRACKET_TERM, then | Tcl_Eval will process | comands from cmd until | either it reaches a null | character or it | encounters a close | bracket that isn't | backslashed or enclosed | in braces, at which | point it will return; | newlines will treated as | white space, not as | command separators. | Under normal conditions, | flags should be 0. char **termPtr (out) If termPtr is non-NULL, | Tcl_Eval fills in | *termPtr with the | address of the character | just after the last one | in the last command | successfully executed | (normally the null | Page 1 (printed 2/26/90) Tcl_Eval(tcl) AMIGA 1.3 Tcl_Eval(tcl) character at the end of | cmd). If an error | occurs in the first | command in cmd, then | *termPtr will be set to | cmd. DESCRIPTION Tcl_Eval parses commands from cmd and executes them in order until either an error occurs or Tcl_Eval reaches a terminating character (']' or ' ', depending on the value of flags). The return value from Tcl_Eval is one of the Tcl return codes TCL_OK, TCL_ERROR, TCL_RETURN, TCL_BREAK, or TCL_CONTINUE, and interp->result will point to a string with additional information (result value or error message). This return information corresponds to the last command executed from cmd. During the processing of a command it is legal to make nested calls to Tcl_Eval (this is how conditionals, loops, and procedures are implemented). If a code other than TCL_OK is returned from a nested Tcl_Eval invocation, then the caller should normally return immediately, passing that same return code back to its caller, and so on until the top-level application is reached. A few commands, like for, will check for certain return codes, like TCL_BREAK and TCL_CONTINUE, and process them specially without returning. Tcl_Eval keeps track of how many nested Tcl_Eval invocations are in progress for interp. If a code of TCL_RETURN, TCL_BREAK, or TCL_CONTINUE is about to be returned from the topmost Tcl_Eval invocation for interp, then Tcl_Eval converts the return code to TCL_ERROR and sets interp- >result to point to an error message indicating that the return, break, or continue command was invoked in an inappropriate place. This means that top-level applications should never see a return code from Tcl_Eval other then TCL_OK or TCL_ERROR. KEYWORDS command, execute, interpreter Page 2 (printed 2/26/90) Tcl_Expr(tcl) AMIGA 1.3 Tcl_Expr(tcl) NAME Tcl_Expr - evaluate an expression SYNOPSIS #include <tcl.h> int Tcl_Expr(interp, string, valuePtr) ARGUMENTS Tcl_Interp *interp (in) Interpreter in whose context to evaluate string. char *string (in) Expression to be evaluated. int *valuePtr (out) The expression's (integer) value will be stored here. DESCRIPTION Tcl_Expr is a utility procedure used by several of the Tcl commands. Given a string whose contents are an expression of the form accepted by the expr command, this procedure evaluates the expression and returns the integer result in *valuePtr. Normally Tcl_Expr returns TCL_OK as its result. However, if the expression contains a syntax error then Tcl_Expr returns TCL_ERROR and sets interp->result to point to an error message in the usual fashion. Tcl_Expr may make nested calls to Tcl_Eval while parsing the expression; if any of these calls returns an error then Tcl_Expr will return that same error information. If an error is returned, then *valuePtr will not be modified. KEYWORDS evaluate, expression Page 1 (printed 2/26/90) Tcl_GetVar(tcl) AMIGA 1.3 Tcl_GetVar(tcl) NAME Tcl_GetVar - return the value of a Tcl variable SYNOPSIS #include <tcl.h> char * Tcl_GetVar(interp, varName, global) ARGUMENTS Tcl_Interp *interp (in) Interpreter in which to check for variable. char *varName (in) Name of desired variable. int global (in) If non-zero, then insist that varName be interpreted as a global variable regardless of whether a procedure invocation is in progress. DESCRIPTION Tcl_GetVar is a utility procedure used by several of the Tcl commands. It returns the value of variable varName in interpreter interp. If there isn't a Tcl command procedure being interpreted right now, or if global is non-zero, then varName is always treated as the name of a global variable. Otherwise, if a procedure is being interpreted, then varName will be treated as a local variable name, unless it has been declared global using the global command. If no variable by the name varName exists right now, then the empty string is returned. KEYWORDS interpreter, global, local, variable Page 1 (printed 2/26/90) Tcl_Interp(tcl) AMIGA 1.3 Tcl_Interp(tcl) NAME Tcl_Interp - client-visible fields of interpreter structures SYNOPSIS #include <tcl.h> typedef struct { char *result; int dynamic; int errorLine; } Tcl_Interp; DESCRIPTION The Tcl_CreateInterp procedure returns a pointer to a Tcl_Interp structure. This pointer is then passed into other Tcl procedures to process commands in the interpreter and perform other operations on the interpreter. Interpreter structures contain many many fields that are used by Tcl, but only three that may be accessed by clients: result and dynamic. These fields are used by Tcl command procedures to return strings that form part of the result of each command. When Tcl_Eval returns, the string pointed to be the result field will be used by Tcl_Eval's caller as a return value or error message. The easiest way for command procedures to manipulate the result and dynamic fields is to call Tcl_Return; Tcl_Return will hide all the details of managing these fields. The description below is for those procedures that manipulate the fields directly. Whenever a command procedure returns, it must ensure that the result field of its interpreter points to the string being returned by the command. Normally, these strings are assumed to be statically allocated; in this case, the dynamic field must be zero. As an alternative, a command procedure may dynamically allocate its return value and store a pointer to it in interp->result. In this case, the command procedure must also set interp->dynamic to non-zero. If interp->dynamic is non-zero, then Tcl will free the space pointed to by interp->result before it invokes the next command. If a client procedure overwrites interp->result field when interp->dynamic is non-zero, then it is responsible for freeing the old interp->result. Once again, if clients use the Tcl_Result procedure to manage these fields, they need not worry about these issues. As part of processing each command, Tcl_Eval initializes interp->result and interp->dynamic just before calling the command procedure for the command. The dynamic field will be initialized to zero, and interp->result will point to an Page 1 (printed 2/26/90) Tcl_Interp(tcl) AMIGA 1.3 Tcl_Interp(tcl) empty string. Commands that do not return any value can simply leave the fields alone. Furthermore, the empty string pointed to by result is actually part of an array of TCL_RESULT_SIZE characters (approximately 200). If a command wishes to return a short string, it can simply copy it to the area pointed to by interp->result. Or, it can use the sprintf procedure to generate a short result string at the location pointed to by interp->result. If a command procedure calls a lower-level procedure that sets interp->result and interp->dynamic (such as a recursive instance of Tcl_Eval), then the command procedure must reset interp->result if it wishes to return a value different than that returned by the lower-level procedure. As part of resetting interp->result, it must free the space if interp- >dynamic is set. Once again, the easiest way to make sure this gets done right is to call Tcl_Result. The errorLine field is valid only after Tcl_Eval returns a | TCL_ERROR return code. In this situation the errorLine | field identifies the line number of the command being | executed when the error occurred. The line numbers are | relative to the command being executed: 1 means the first | line of the command passed to Tcl_Eval, 2 means the second | line, and so on. ErrorLine should not normally be modified | except by Tcl_Eval. KEYWORDS dynamic, interpreter, result Page 2 (printed 2/26/90) Tcl_Merge(tcl) AMIGA 1.3 Tcl_Merge(tcl) NAME Tcl_Merge - generate a Tcl list from a collection of strings SYNOPSIS #include <tcl.h> char * Tcl_Merge(argc, argv) ARGUMENTS int argc (in) Number of strings. char *argv[] (in) Array of strings to combine into list. Must have argc entries. DESCRIPTION Tcl_Merge is a utility procedure used by several of the Tcl commands. Given a collection of strings, it generates a result string that has proper list structure, such that the index Tcl command may be used to extract out the original strings. In order to do this, Tcl_Merge may have to add braces and/or backslashes. The result string is dynamically allocated using malloc(); the caller must eventually release the space using free(). KEYWORDS list, strings Page 1 (printed 2/26/90) Tcl_Return(tcl) AMIGA 1.3 Tcl_Return(tcl) NAME Tcl_Return - set up a Tcl result string SYNOPSIS #include <tcl.h> Tcl_Return(interp, string, status) ARGUMENTS Tcl_Interp *interp (out) Interpreter for which a return value is to be established. char *string (in) String value to be returned, or NULL. int status (in) Indicates the nature of string. Must be either TCL_STATIC, TCL_DYNAMIC, or TCL_VOLATILE. DESCRIPTION Tcl_Return is a convenience routine used by several of the Tcl commands. It arranges for string to be the return string for the current Tcl command in interp. If status is TCL_STATIC it means that string refers to an area of static storage that is guaranteed to remain untouched until at least the next call to Tcl_Eval. If status is TCL_DYNAMIC it means that string was allocated with a call to malloc() and is now the property of the Tcl system. Tcl_Return will arrange for the string's storage to be released by calling free() when it is no longer needed. The third possibility is for status to be TCL_VOLATILE. This means that string points to an area of memory that is likely to be overwritten when Tcl_Return returns. In this case Tcl_Return makes a copy of the string and arranges for the copy to be the return string for the current Tcl command. If string is NULL, then status is ignored and Tcl_Return re-initializes interp's result to point to the pre-allocated result area, with an empty string in the result area. In any of the above cases, if interp holds a dynamically- allocated result at the time of the Tcl_Return call, the old result's storage is released by calling free(). KEYWORDS command, result, return value, interpreter Page 1 (printed 2/26/90) Tcl_SetVar(tcl) AMIGA 1.3 Tcl_SetVar(tcl) NAME Tcl_SetVar - change the value of a Tcl variable SYNOPSIS #include <tcl.h> Tcl_SetVar(interp, varName, newValue, global) ARGUMENTS Tcl_Interp *interp (in) Interpreter in which to change variable. char *varName (in) Name of variable. char *newValue (in) New value for varName int global (in) If non-zero, then insist on interpreting varName as a global variable, regardless of whether a procedure invocation is in progress. DESCRIPTION This is a utility procedure used by many of the Tcl commands. It changes the value of variable varName in interpreter interp, such that future calls to Tcl_GetVar will return newValue as the value of varName. Tcl_SetVar uses the same rules for selecting a global or local variable as Tcl_GetVar. If varName doesn't already exist, then a new variable is created. Tcl_SetVar copies both varName and newValue into its own private storage, so the caller may change the contents of these strings after Tcl_SetVar returns without affecting the variable's value. KEYWORDS interpreter, variable Page 1 (printed 2/26/90) Tcl_SplitList(tcl) AMIGA 1.3 Tcl_SplitList(tcl) NAME Tcl_SplitList - break a Tcl list up into fields SYNOPSIS #include <tcl.h> int Tcl_SplitList(interp, list, argcPtr, argvPtr) ARGUMENTS Tcl_Interp *interp (out) Interpreter to use for error reporting. char *list (in) Pointer to a string with proper list structure. int *argcPtr (out) Filled in with number of elements in list. char ***argvPtr (out) *argvPtr will be filled in with the address of an array of pointers to the strings that are the extracted elements of list. There will be *argcPtr valid entries in the array. DESCRIPTION Tcl_SplitList is the inverse of Tcl_Merge. Given a list, it extracts all of the elements of the list and returns an array of pointers to them using argcPtr and argvPtr. While extracting the arguments, Tcl_SplitList obeys the usual rules for backslash substitutions and braces. The area of memory pointed to by *argvPtr is dynamically allocated; in addition to the array of pointers, it also holds copies of all the list elements. It is the caller's responsibility to free up all of this storage by calling free((char *) *argvPtr) when the list elements are no longer needed. Tcl_SplitList normally returns TCL_OK, which means the list was successfully parsed. If there was a syntax error in list, then TCL_ERROR is returned and interp->result will point to an error message describing the problem. KEYWORDS list, split, strings Page 1 (printed 2/26/90) Tcl_SplitList(tcl) AMIGA 1.3 Tcl_SplitList(tcl) Page 2 (printed 2/26/90) Tcl_StringMatch(tcl) AMIGA 1.3 Tcl_StringMatch(tcl) NAME | Tcl_StringMatch - test whether a string matches a pattern | SYNOPSIS | #include <tcl.h> | int | Tcl_StringMatch(string, pattern) | ARGUMENTS | char *string (in) || String to test. | char *pattern (in) || Pattern to match against | string. May contain | special characters from | the set *?\[]. | DESCRIPTION | This utility procedure determines whether a string matches a | given pattern. If it does, then Tcl_StringMatch returns 1. | Otherwise Tcl_StringMatch returns 0. The algorithm used for | matching is the same algorithm used in the ``string match'' | Tcl command and is similar to the algorithm used by the C- | shell for file name matching; see the Tcl manual entry for | details. | KEYWORDS | match, pattern, string Page 1 (printed 2/26/90) Tcl_WatchInterp(tcl) AMIGA 1.3 Tcl_WatchInterp(tcl) NAME | Tcl_WatchInterp - arrange for callback when interpreter is | deleted. | SYNOPSIS | #include <tcl.h> | Tcl_WatchInterp(interp, proc, clientData) | ARGUMENTS | Tcl_Interp *interp (in) || Interpreter whose | deletion should be | monitored. | char *cmdName (in) || Name of new | command. | void (*proc)() (in) || Procedure to invoke | just before interp | is deleted. | ClientData clientData (in) || Arbitrary one-word | value to pass to | proc. | DESCRIPTION | Tcl_WatchInterp arranges for proc to be called by | Tcl_DeleteInterp if/when interp is deleted at some future | time. Proc will be invoked just before the interpreter is | deleted, but the interpreter will still be valid at the time | of the call. Proc should have the following structure: | void | proc(clientData, interp) | ClientData clientData; | Tcl_Interp *interp; | { | } | The clientData and interp parameters are copies of the | clientData and interp arguments given to Tcl_WatchInterp. | Typically, clientData points to an application-specific data | structure that proc uses to perform cleanup when an | interpreter is about to go away. Proc does not return a | value. | KEYWORDS | callback, delete, interpreter Page 1 (printed 2/26/90) -- -- uunet!sugar!karl "As long as there is a legion of superheros, all else -- can surely be made right." -- Sensor Girl -- Usenet access: (713) 438-5018