Партнёры:
Хостинг:
Tcl_CreateObjCommand, Tcl_DeleteCommand, Tcl_DeleteCommandFromToken, Tcl_GetCommandInfo, Tcl_SetCommandInfo, Tcl_GetCommandName - implement new commands in C
#include <tcl.h> Tcl_Command Tcl_CreateObjCommand(interp, cmdName, proc, clientData, deleteProc) int Tcl_DeleteCommand(interp, cmdName) int Tcl_DeleteCommandFromToken(interp, token) int Tcl_GetCommandInfo(interp, cmdName, infoPtr) int Tcl_SetCommandInfo(interp, cmdName, infoPtr) char * Tcl_GetCommandName(interp, token)
Tcl_CreateObjCommand defines a new command in interp and associates it with procedure proc such that whenever name is invoked as a Tcl command (e.g., via a call to Tcl_EvalObjEx) the Tcl interpreter will call proc to process the command.
Tcl_CreateObjCommand deletes any existing command name already associated with the interpreter (however see below for an exception where the existing command is not deleted). It returns a token that may be used to refer to the command in subsequent calls to Tcl_GetCommandName. If name contains any :: namespace qualifiers, then the command is added to the specified namespace; otherwise the command is added to the global namespace. If Tcl_CreateObjCommand is called for an interpreter that is in the process of being deleted, then it does not create a new command and it returns NULL. proc should have arguments and result that match the type Tcl_ObjCmdProc:
typedef int Tcl_ObjCmdProc( ClientData clientData, Tcl_Interp *interp, int objc, Tcl_Obj *CONST objv[]);
Additionally, when proc is invoked, it must not modify the contents of the objv array by assigning new pointer values to any element of the array (for example, objv[2] = NULL) because this will cause memory to be lost and the runtime stack to be corrupted. The CONST in the declaration of objv will cause ANSI-compliant compilers to report any such attempted assignment as an error. However, it is acceptable to modify the internal representation of any individual object argument. For instance, the user may call Tcl_GetIntFromObj on objv[2] to obtain the integer representation of that object; that call may change the type of the object that objv[2] points at, but will not change where objv[2] points.
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, if proc needs to return a non-empty result, it can call Tcl_SetObjResult to set the interpreter's result. In the case of a TCL_OK return code this gives the result of the command, and in the case of TCL_ERROR this gives an error message. Before invoking a command procedure, Tcl_EvalObjEx sets interpreter's result to point to an object representing an empty string, so simple commands can return an empty result by doing nothing at all.
The contents of the objv array belong to Tcl and are not guaranteed to persist once proc returns: proc should not modify them. Call Tcl_SetObjResult if you want to return something from the objv array.
Ordinarily, Tcl_CreateObjCommand deletes any existing command name already associated with the interpreter. However, if the existing command was created by a previous call to Tcl_CreateCommand, Tcl_CreateObjCommand does not delete the command but instead arranges for the Tcl interpreter to call the Tcl_ObjCmdProc proc in the future. The old string-based Tcl_CmdProc associated with the command is retained and its address can be obtained by subsequent Tcl_GetCommandInfo calls. This is done for backwards compatibility.
DeleteProc will be invoked when (if) name is deleted. This can occur through a call to Tcl_DeleteCommand, Tcl_DeleteCommandFromToken, or Tcl_DeleteInterp, or by replacing name in another call to Tcl_CreateObjCommand. 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 arguments and result that match the type Tcl_CmdDeleteProc:
typedef void Tcl_CmdDeleteProc(ClientData clientData);
Tcl_DeleteCommand 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 and returns -1; otherwise it returns 0. There are no restrictions on cmdName: it may refer to a built-in command, an application-specific command, or a Tcl procedure. If name contains any :: namespace qualifiers, the command is deleted from the specified namespace.
Given a token returned by Tcl_CreateObjCommand, Tcl_DeleteCommandFromToken deletes the command from a command interpreter. It will delete a command even if that command has been renamed. Once the call completes, attempts to invoke the command in interp will result in errors. If the command corresponding to token has already been deleted from interp then Tcl_DeleteCommand does nothing and returns -1; otherwise it returns 0.
Tcl_GetCommandInfo checks to see whether its cmdName argument exists as a command in interp. cmdName may include :: namespace qualifiers to identify a command in a particular namespace. If the command is not found, then it returns 0. Otherwise it places information about the command in the Tcl_CmdInfo structure pointed to by infoPtr and returns 1. A Tcl_CmdInfo structure has the following fields:
typedef struct Tcl_CmdInfo {
int isNativeObjectProc;
Tcl_ObjCmdProc *objProc;
ClientData objClientData;
Tcl_CmdProc *proc;
ClientData clientData;
Tcl_CmdDeleteProc *deleteProc;
ClientData deleteData;
Tcl_Namespace *namespacePtr;
} Tcl_CmdInfo;
Tcl_SetCommandInfo is used to modify the procedures and ClientData values associated with a command. Its cmdName argument is the name of a command in interp. cmdName may include :: namespace qualifiers to identify a command in a particular namespace. If this command does not exist then Tcl_SetCommandInfo returns 0. Otherwise, it copies the information from *infoPtr to Tcl's internal structure for the command and returns 1. Note that this procedure allows the ClientData for a command's deletion procedure to be given a different value than the ClientData for its command procedure. Note that Tcl_SetCmdInfo will not change a command's namespace; you must use Tcl_RenameCommand to do that.
Tcl_GetCommandName provides a mechanism for tracking commands that have been renamed. Given a token returned by Tcl_CreateObjCommand when the command was created, Tcl_GetCommandName returns the string name of the command. If the command has been renamed since it was created, then Tcl_GetCommandName returns the current name. This name does not include any :: namespace qualifiers. The command corresponding to token must not have been deleted. The string returned by Tcl_GetCommandName is in dynamic memory owned by Tcl and is only guaranteed to retain its value as long as the command isn't deleted or renamed; callers should copy the string if they need to keep it for a long time.
|
Закладки на сайте Проследить за страницей |
Created 1996-2024 by Maxim Chirkov Добавить, Поддержать, Вебмастеру |