CrtObjCmd.3
上传用户:rrhhcc
上传日期:2015-12-11
资源大小:54129k
文件大小:13k
- '"
- '" Copyright (c) 1996-1997 Sun Microsystems, Inc.
- '"
- '" See the file "license.terms" for information on usage and redistribution
- '" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
- '"
- '" RCS: @(#) $Id: CrtObjCmd.3,v 1.7.2.1 2004/05/05 20:54:47 dkf Exp $
- '"
- .so man.macros
- .TH Tcl_CreateObjCommand 3 8.0 Tcl "Tcl Library Procedures"
- .BS
- .SH NAME
- Tcl_CreateObjCommand, Tcl_DeleteCommand, Tcl_DeleteCommandFromToken, Tcl_GetCommandInfo, Tcl_GetCommandInfoFromToken, Tcl_SetCommandInfo, Tcl_SetCommandInfoFromToken, Tcl_GetCommandName, Tcl_GetCommandFullName, Tcl_GetCommandFromObj - implement new commands in C
- .SH SYNOPSIS
- .nf
- fB#include <tcl.h>fR
- .sp
- Tcl_Command
- fBTcl_CreateObjCommandfR(fIinterp, cmdName, proc, clientData, deleteProcfR)
- .sp
- int
- fBTcl_DeleteCommandfR(fIinterp, cmdNamefR)
- .sp
- int
- fBTcl_DeleteCommandFromTokenfR(fIinterp, tokenfR)
- .sp
- int
- fBTcl_GetCommandInfofR(fIinterp, cmdName, infoPtrfR)
- .sp
- int
- fBTcl_SetCommandInfofR(fIinterp, cmdName, infoPtrfR)
- .sp
- .VS 8.4
- int
- fBTcl_GetCommandInfoFromTokenfR(fItoken, infoPtrfR)
- .sp
- int
- fBTcl_SetCommandInfoFromTokenfR(fItoken, infoPtrfR)
- .VE
- .sp
- .VS 8.4
- CONST char *
- .VE
- fBTcl_GetCommandNamefR(fIinterp, tokenfR)
- .sp
- void
- fBTcl_GetCommandFullNamefR(fIinterp, token, objPtrfR)
- .sp
- Tcl_Command
- fBTcl_GetCommandFromObjfR(fIinterp, objPtrfR)
- .SH ARGUMENTS
- .AS Tcl_ObjCmdProc *deleteProc in/out
- .AP Tcl_Interp *interp in
- Interpreter in which to create a new command or that contains a command.
- .VS 8.4
- .AP char *cmdName in
- .VE
- Name of command.
- .AP Tcl_ObjCmdProc *proc in
- Implementation of the new command: fIprocfR will be called whenever
- fIcmdNamefR is invoked as a command.
- .AP ClientData clientData in
- Arbitrary one-word value to pass to fIprocfR and fIdeleteProcfR.
- .AP Tcl_CmdDeleteProc *deleteProc in
- Procedure to call before fIcmdNamefR is deleted from the interpreter;
- allows for command-specific cleanup. If NULL, then no procedure is
- called before the command is deleted.
- .AP Tcl_Command token in
- Token for command, returned by previous call to fBTcl_CreateObjCommandfR.
- The command must not have been deleted.
- .AP Tcl_CmdInfo *infoPtr in/out
- Pointer to structure containing various information about a
- Tcl command.
- .AP Tcl_Obj *objPtr in
- Object containing the name of a Tcl command.
- .BE
- .SH DESCRIPTION
- .PP
- fBTcl_CreateObjCommandfR defines a new command in fIinterpfR
- and associates it with procedure fIprocfR
- such that whenever fInamefR is
- invoked as a Tcl command (e.g., via a call to fBTcl_EvalObjExfR)
- the Tcl interpreter will call fIprocfR to process the command.
- .PP
- fBTcl_CreateObjCommandfR deletes any existing command
- fInamefR 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 fBTcl_GetCommandNamefR.
- If fInamefR contains any fB::fR namespace qualifiers,
- then the command is added to the specified namespace;
- otherwise the command is added to the global namespace.
- If fBTcl_CreateObjCommandfR 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.
- fIprocfR should have arguments and result that match the type
- fBTcl_ObjCmdProcfR:
- .CS
- typedef int Tcl_ObjCmdProc(
- ClientData fIclientDatafR,
- Tcl_Interp *fIinterpfR,
- int fIobjcfR,
- .VS
- Tcl_Obj *CONST fIobjvfR[]);
- .CE
- When fIprocfR is invoked, the fIclientDatafR and fIinterpfR parameters
- will be copies of the fIclientDatafR and fIinterpfR arguments given to
- fBTcl_CreateObjCommandfR. Typically, fIclientDatafR points to an
- application-specific data structure that describes what to do when the
- command procedure is invoked. fIObjcfR and fIobjvfR describe the
- arguments to the command, fIobjcfR giving the number of argument objects
- (including the command name) and fIobjvfR giving the values of the
- arguments. The fIobjvfR array will contain fIobjcfR values, pointing to
- the argument objects. Unlike fIargvfR[fIargvfR] used in a
- string-based command procedure, fIobjvfR[fIobjcfR] will not contain NULL.
- .PP
- Additionally, when fIprocfR is invoked, it must not modify the contents
- of the fIobjvfR array by assigning new pointer values to any element of the
- array (for example, fIobjvfR[fB2fR] = fBNULLfR) because this will
- cause memory to be lost and the runtime stack to be corrupted. The
- fBCONSTfR in the declaration of fIobjvfR 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
- fBTcl_GetIntFromObjfR on fIobjvfR[fB2fR] to obtain the integer
- representation of that object; that call may change the type of the object
- that fIobjvfR[fB2fR] points at, but will not change where
- fIobjvfR[fB2fR] points.
- .VE
- .PP
- fIprocfR must return an integer code that is either fBTCL_OKfR,
- fBTCL_ERRORfR, fBTCL_RETURNfR, fBTCL_BREAKfR, or fBTCL_CONTINUEfR.
- See the Tcl overview man page
- for details on what these codes mean. Most normal commands will only
- return fBTCL_OKfR or fBTCL_ERRORfR.
- In addition, if fIprocfR needs to return a non-empty result,
- it can call fBTcl_SetObjResultfR to set the interpreter's result.
- In the case of a fBTCL_OKfR return code this gives the result
- of the command,
- and in the case of fBTCL_ERRORfR this gives an error message.
- Before invoking a command procedure,
- fBTcl_EvalObjExfR 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.
- .PP
- The contents of the fIobjvfR array belong to Tcl and are not
- guaranteed to persist once fIprocfR returns: fIprocfR should
- not modify them.
- Call fBTcl_SetObjResultfR if you want
- to return something from the fIobjvfR array.
- .PP
- Ordinarily, fBTcl_CreateObjCommandfR deletes any existing command
- fInamefR already associated with the interpreter.
- However, if the existing command was created by a previous call to
- fBTcl_CreateCommandfR,
- fBTcl_CreateObjCommandfR does not delete the command
- but instead arranges for the Tcl interpreter to call the
- fBTcl_ObjCmdProcfR fIprocfR in the future.
- The old string-based fBTcl_CmdProcfR associated with the command
- is retained and its address can be obtained by subsequent
- fBTcl_GetCommandInfofR calls. This is done for backwards compatibility.
- .PP
- fIDeleteProcfR will be invoked when (if) fInamefR is deleted.
- This can occur through a call to fBTcl_DeleteCommandfR,
- fBTcl_DeleteCommandFromTokenfR, or fBTcl_DeleteInterpfR,
- or by replacing fInamefR in another call to fBTcl_CreateObjCommandfR.
- fIDeleteProcfR is invoked before the command is deleted, and gives the
- application an opportunity to release any structures associated
- with the command. fIDeleteProcfR should have arguments and
- result that match the type fBTcl_CmdDeleteProcfR:
- .CS
- typedef void Tcl_CmdDeleteProc(ClientData fIclientDatafR);
- .CE
- The fIclientDatafR argument will be the same as the fIclientDatafR
- argument passed to fBTcl_CreateObjCommandfR.
- .PP
- fBTcl_DeleteCommandfR deletes a command from a command interpreter.
- Once the call completes, attempts to invoke fIcmdNamefR in
- fIinterpfR will result in errors.
- If fIcmdNamefR isn't bound as a command in fIinterpfR then
- fBTcl_DeleteCommandfR does nothing and returns -1; otherwise
- it returns 0.
- There are no restrictions on fIcmdNamefR: it may refer to
- a built-in command, an application-specific command, or a Tcl procedure.
- If fInamefR contains any fB::fR namespace qualifiers,
- the command is deleted from the specified namespace.
- .PP
- Given a token returned by fBTcl_CreateObjCommandfR,
- fBTcl_DeleteCommandFromTokenfR 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
- fIinterpfR will result in errors.
- If the command corresponding to fItokenfR
- has already been deleted from fIinterpfR then
- fBTcl_DeleteCommandfR does nothing and returns -1;
- otherwise it returns 0.
- .PP
- fBTcl_GetCommandInfofR checks to see whether its fIcmdNamefR argument
- exists as a command in fIinterpfR.
- fIcmdNamefR may include fB::fR 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 fBTcl_CmdInfofR structure
- pointed to by fIinfoPtrfR and returns 1.
- A fBTcl_CmdInfofR structure has the following fields:
- .CS
- 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;
- .CE
- The fIisNativeObjectProcfR field has the value 1
- if fBTcl_CreateObjCommandfR was called to register the command;
- it is 0 if only fBTcl_CreateCommandfR was called.
- It allows a program to determine whether it is faster to
- call fIobjProcfR or fIprocfR:
- fIobjProcfR is normally faster
- if fIisNativeObjectProcfR has the value 1.
- The fields fIobjProcfR and fIobjClientDatafR
- have the same meaning as the fIprocfR and fIclientDatafR
- arguments to fBTcl_CreateObjCommandfR;
- they hold information about the object-based command procedure
- that the Tcl interpreter calls to implement the command.
- The fields fIprocfR and fIclientDatafR
- hold information about the string-based command procedure
- that implements the command.
- If fBTcl_CreateCommandfR was called for this command,
- this is the procedure passed to it;
- otherwise, this is a compatibility procedure
- registered by fBTcl_CreateObjCommandfR
- that simply calls the command's
- object-based procedure after converting its string arguments to Tcl objects.
- The field fIdeleteDatafR is the ClientData value
- to pass to fIdeleteProcfR; it is normally the same as
- fIclientDatafR but may be set independently using the
- fBTcl_SetCommandInfofR procedure.
- The field fInamespacePtrfR holds a pointer to the
- Tcl_Namespace that contains the command.
- .PP
- fBTcl_GetCommandInfoFromTokenfR is identical to
- fBTcl_GetCommandInfofR except that it uses a command token returned
- from fBTcl_CreateObjCommandfR in place of the command name. If the
- fItokenfR parameter is NULL, it returns 0; otherwise, it returns 1
- and fills in the structure designated by fIinfoPtrfR.
- .PP
- fBTcl_SetCommandInfofR is used to modify the procedures and
- ClientData values associated with a command.
- Its fIcmdNamefR argument is the name of a command in fIinterpfR.
- fIcmdNamefR may include fB::fR namespace qualifiers
- to identify a command in a particular namespace.
- If this command does not exist then fBTcl_SetCommandInfofR returns 0.
- Otherwise, it copies the information from fI*infoPtrfR to
- Tcl's internal structure for the command and returns 1.
- .PP
- fBTcl_SetCommandInfoFromTokenfR is identical to
- fBTcl_SetCommandInfofR except that it takes a command token as
- returned by fBTcl_CreateObjCommandfR instead of the command name.
- If the fItokenfR parameter is NULL, it returns 0. Otherwise, it
- copies the information from fI*infoPtrfR to Tcl's internal structure
- for the command and returns 1.
- .PP
- Note that fBTcl_SetCommandInfofR and
- fBTcl_SetCommandInfoFromTokenfR both allow the ClientData for a
- command's deletion procedure to be given a different value than the
- ClientData for its command procedure.
- .PP
- Note that neither fBTcl_SetCommandInfofR nor
- fBTcl_SetCommandInfoFromTokenfR will change a command's namespace.
- Use fBTcl_EvalfR to call the fBrenamefR command to do that.
- .PP
- fBTcl_GetCommandNamefR provides a mechanism for tracking commands
- that have been renamed.
- Given a token returned by fBTcl_CreateObjCommandfR
- when the command was created, fBTcl_GetCommandNamefR returns the
- string name of the command. If the command has been renamed since it
- was created, then fBTcl_GetCommandNamefR returns the current name.
- This name does not include any fB::fR namespace qualifiers.
- The command corresponding to fItokenfR must not have been deleted.
- The string returned by fBTcl_GetCommandNamefR 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.
- .PP
- fBTcl_GetCommandFullNamefR 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 fIobjPtrfP.
- .PP
- fBTcl_GetCommandFromObjfR returns a token for the command
- specified by the name in a fBTcl_ObjfP.
- The command name is resolved relative to the current namespace.
- Returns NULL if the command is not found.
- .SH "SEE ALSO"
- Tcl_CreateCommand, Tcl_ResetResult, Tcl_SetObjResult
- .SH KEYWORDS
- bind, command, create, delete, namespace, object