On Apache
Under GNU General Public License
2024-04-19 15:10 @18.217.73.187 CrawledBy Mozilla/5.0 AppleWebKit/537.36 (KHTML, like Gecko; compatible; ClaudeBot/1.0; +claudebot@anthropic.com)
Tcl_CreateObjCommand(3) Tcl Library Procedures Tcl_CreateObjCommand(3)
_________________________________________________________________________________________________
NAME
Tcl_CreateObjCommand, Tcl_DeleteCommand, Tcl_DeleteCommandFromToken, Tcl_GetCommandInfo,
Tcl_GetCommandInfoFromToken, Tcl_SetCommandInfo, Tcl_SetCommandInfoFromToken, Tcl_GetCom-
mandName, Tcl_GetCommandFullName, Tcl_GetCommandFromObj - implement new commands in C
SYNOPSIS
#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)
int
Tcl_GetCommandInfoFromToken(token, infoPtr)
int
Tcl_SetCommandInfoFromToken(token, infoPtr)
const char *
Tcl_GetCommandName(interp, token)
void
Tcl_GetCommandFullName(interp, token, objPtr)
Tcl_Command
Tcl_GetCommandFromObj(interp, objPtr)
ARGUMENTS
Tcl_Interp *interp (in) Interpreter in which to create a new command
or that contains a command.
char *cmdName (in) Name of command.
Tcl_ObjCmdProc *proc (in) Implementation of the 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.
Tcl_CmdDeleteProc *deleteProc (in) Procedure to call before cmdName is deleted
from the interpreter; allows for command-spe-
cific cleanup. If NULL, then no procedure is
called before the command is deleted.
Tcl_Command token (in) Token for command, returned by previous call
to Tcl_CreateObjCommand. The command must not
have been deleted.
Tcl_CmdInfo *infoPtr (in/out) Pointer to structure containing various infor-
mation about a Tcl command.
Tcl_Obj *objPtr (in) Object containing the name of a Tcl command.
_________________________________________________________________
DESCRIPTION
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 inter-
preter (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_Get-
CommandName. 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[]);
When proc is invoked, the clientData and interp parameters will be copies of the client-
Data and interp arguments given to Tcl_CreateObjCommand. Typically, clientData points to
an application-specific data structure that describes what to do when the command proce-
dure is invoked. Objc and objv describe the arguments to the command, objc giving the num-
ber of argument objects (including the command name) and objv giving the values of the
arguments. The objv array will contain objc values, pointing to the argument objects.
Unlike argv[argv] used in a string-based command procedure, objv[objc] will not contain
NULL.
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 repre-
sentation of any individual object argument. For instance, the user may call Tcl_GetInt-
FromObj 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_Eval-
ObjEx 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 some-
thing 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);
The clientData argument will be the same as the clientData argument passed to Tcl_Cre-
ateObjCommand.
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 is not 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 qual-
ifiers, 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 informa-
tion 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;
The isNativeObjectProc field has the value 1 if Tcl_CreateObjCommand was called to regis-
ter the command; it is 0 if only Tcl_CreateCommand was called. It allows a program to
determine whether it is faster to call objProc or proc: objProc is normally faster if
isNativeObjectProc has the value 1. The fields objProc and objClientData have the same
meaning as the proc and clientData arguments to Tcl_CreateObjCommand; they hold informa-
tion about the object-based command procedure that the Tcl interpreter calls to implement
the command. The fields proc and clientData hold information about the string-based com-
mand procedure that implements the command. If Tcl_CreateCommand was called for this com-
mand, this is the procedure passed to it; otherwise, this is a compatibility procedure
registered by Tcl_CreateObjCommand that simply calls the command's object-based procedure
after converting its string arguments to Tcl objects. The field deleteData is the Client-
Data value to pass to deleteProc; it is normally the same as clientData but may be set
independently using the Tcl_SetCommandInfo procedure. The field namespacePtr holds a
pointer to the Tcl_Namespace that contains the command.
Tcl_GetCommandInfoFromToken is identical to Tcl_GetCommandInfo except that it uses a com-
mand token returned from Tcl_CreateObjCommand in place of the command name. If the token
parameter is NULL, it returns 0; otherwise, it returns 1 and fills in the structure desig-
nated by infoPtr.
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.
Tcl_SetCommandInfoFromToken is identical to Tcl_SetCommandInfo except that it takes a com-
mand token as returned by Tcl_CreateObjCommand instead of the command name. If the token
parameter is NULL, it returns 0. Otherwise, it copies the information from *infoPtr to
Tcl's internal structure for the command and returns 1.
Note that Tcl_SetCommandInfo and Tcl_SetCommandInfoFromToken both allow the ClientData for
a command's deletion procedure to be given a different value than the ClientData for its
command procedure.
Note that neither Tcl_SetCommandInfo nor Tcl_SetCommandInfoFromToken will change a com-
mand's namespace. Use Tcl_Eval to call the rename command 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_GetCom-
mandName 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 is not deleted or renamed;
callers should copy the string if they need to keep it for a long time.
Tcl_GetCommandFullName produces the fully qualified name of a command from a command
token. The name, including all namespace prefixes, is appended to the object specified by
objPtr.
Tcl_GetCommandFromObj returns a token for the command specified by the name in a Tcl_Obj.
The command name is resolved relative to the current namespace. Returns NULL if the com-
mand is not found.
SEE ALSO
Tcl_CreateCommand, Tcl_ResetResult, Tcl_SetObjResult
KEYWORDS
bind, command, create, delete, namespace, object
Tcl 8.0 Tcl_CreateObjCommand(3)
Generated by $Id: phpMan.php,v 4.55 2007/09/05 04:42:51 chedong Exp $ Author: Che Dong
On Apache
Under GNU General Public License
2024-04-19 15:10 @18.217.73.187 CrawledBy Mozilla/5.0 AppleWebKit/537.36 (KHTML, like Gecko; compatible; ClaudeBot/1.0; +claudebot@anthropic.com)