Manual Pages for UNIX Darwin command on man Tcl

Manual Pages for UNIX Darwin command on man Tcl_SetCommandInfoFromToken

TclCreateObjCommand(3) Tcl Library Procedures TclCreateObjCommand(3)

NAME

TclCreateObjCommand, TclDeleteCommand, TclDeleteCommandFromToken, TclGetCommandInfo, TclGetCommandInfoFromToken, TclSetCommandInfo,

TclSetCommandInfoFromToken, TclGetCommandName, TclGetCommandFull-

Name, TclGetCommandFromObj - implement new commands in C

SYNOPSIS

##iinncclluuddee <>

TclCommand TTccllCCrreeaatteeOObbjjCCoommmmaanndd(interp, cmdName, proc, clientData, deleteProc) int TTccllDDeelleetteeCCoommmmaanndd(interp, cmdName) int TTccllDDeelleetteeCCoommmmaannddFFrroommTTookkeenn(interp, token) int TTccllGGeettCCoommmmaannddIInnffoo(interp, cmdName, infoPtr) int TTccllSSeettCCoommmmaannddIInnffoo(interp, cmdName, infoPtr) int | TTccllGGeettCCoommmmaannddIInnffooFFrroommTTookkeenn(token, infoPtr) | int | TTccllSSeettCCoommmmaannddIInnffooFFrroommTTookkeenn(token, infoPtr) | CONST char * | TTccllGGeettCCoommmmaannddNNaammee(interp, token) void TTccllGGeettCCoommmmaannddFFuullllNNaammee(interp, token, objPtr) TclCommand TTccllGGeettCCoommmmaannddFFrroommOObbjj(interp, objPtr) AARRGGUUMMEENNTTSS TclInterp *interp (in) Interpreter in which to create a new command or that contains a command. |

char *cmd- |

Name (in) | | Name of command.

TclObjCmdProc *proc (in) Implementation of the new com-

mand: proc will be called whenever cmdName is invoked as a command.

ClientData clientData (in) Arbitrary one-word value to

pass to proc and deleteProc. TclCmdDeleteProc *deleteProc(in)

Procedure to call before cmd-

Name is deleted from the

interpreter; allows for com-

mand-specific cleanup. If

NULL, then no procedure is called before the command is deleted. TclCommand token (in) Token for command, returned by

previous call to TTccllCCrreeaatteeOObb-

jjCCoommmmaanndd. The command must not have been deleted.

TclCmdInfo *infoPtr (in/out) Pointer to structure contain-

ing various information about a Tcl command. TclObj *objPtr (in) Object containing the name of a Tcl command.

DESCRIPTION

TTccllCCrreeaatteeOObbjjCCoommmmaanndd 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 TTccllEEvvaallOObbjjEExx) the Tcl interpreter will call proc to process the command.

TTccllCCrreeaatteeOObbjjCCoommmmaanndd deletes any existing command name already associ-

ated 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 TTccllGGeettCCoommmmaannddNNaammee. 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 TTccllCCrreeaatteeOObbjjCCoommmmaanndd is called for an interpreter that

is in the process of being deleted, then it does not create a new com-

mand and it returns NULL. proc should have arguments and result that match the type TTccllOObbjjCCmmddPPrroocc: typedef int TclObjCmdProc( ClientData clientData, TclInterp *interp, int objc, TclObj *CONST objv[]); | When proc is invoked, the clientData and interp parameters will be |

copies of the clientData and interp arguments given to TTccllCCrreeaatteeOObbjj- |

CCoommmmaanndd. Typically, clientData points to an application-specific data |

structure that describes what to do when the command procedure is |

invoked. Objc and objv describe the arguments to the command, objc giv- |

ing the number 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[22] = NNUULLLL) because this will cause memory to |

be lost and the runtime stack to be corrupted. The CCOONNSSTT in the decla- |

ration 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 TTccllGGeettIInnttFFrroommOObbjj on objv[22] to obtain the | integer representation of that object; that call may change the type of | the object that objv[22] points at, but will not change where objv[22] | points. proc must return an integer code that is either TTCCLLOOKK, TTCCLLEERRRROORR, TTCCLLRREETTUURRNN, TTCCLLBBRREEAAKK, or TTCCLLCCOONNTTIINNUUEE. See the Tcl overview man page for details on what these codes mean. Most normal commands will only return TTCCLLOOKK or TTCCLLEERRRROORR. In addition, if proc needs to return a

non-empty result, it can call TTccllSSeettOObbjjRReessuulltt to set the interpreter's

result. In the case of a TTCCLLOOKK return code this gives the result of the command, and in the case of TTCCLLEERRRROORR this gives an error message. Before invoking a command procedure, TTccllEEvvaallOObbjjEExx 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 TTccllSSeettOO-

bbjjRReessuulltt if you want to return something from the objv array. Ordinarily, TTccllCCrreeaatteeOObbjjCCoommmmaanndd deletes any existing command name

already associated with the interpreter. However, if the existing com-

mand was created by a previous call to TTccllCCrreeaatteeCCoommmmaanndd, TTccllCCrreeaatteeOObb-

jjCCoommmmaanndd does not delete the command but instead arranges for the Tcl interpreter to call the TTccllOObbjjCCmmddPPrroocc proc in the future. The old

string-based TTccllCCmmddPPrroocc associated with the command is retained and

its address can be obtained by subsequent TTccllGGeettCCoommmmaannddIInnffoo calls. This is done for backwards compatibility. DeleteProc will be invoked when (if) name is deleted. This can occur through a call to TTccllDDeelleetteeCCoommmmaanndd, TTccllDDeelleetteeCCoommmmaannddFFrroommTTookkeenn, or

TTccllDDeelleetteeIInntteerrpp, or by replacing name in another call to TTccllCCrreeaatteeOObb-

jjCCoommmmaanndd. DeleteProc is invoked before the command is deleted, and

gives the application an opportunity to release any structures associ-

ated with the command. DeleteProc should have arguments and result that match the type TTccllCCmmddDDeelleetteePPrroocc: typedef void TclCmdDeleteProc(ClientData clientData); The clientData argument will be the same as the clientData argument passed to TTccllCCrreeaatteeOObbjjCCoommmmaanndd. TTccllDDeelleetteeCCoommmmaanndd 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

TTccllDDeelleetteeCCoommmmaanndd does nothing and returns -1; otherwise it returns 0.

There are no restrictions on cmdName: it may refer to a built-in com-

mand, 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 TTccllCCrreeaatteeOObbjjCCoommmmaanndd, TTccllDDeelleetteeCCoommmmaannddFFrroomm-

TTookkeenn deletes the command from a command interpreter. It will delete a

command even if that command has been renamed. Once the call com-

pletes, attempts to invoke the command in interp will result in errors. If the command corresponding to token has already been deleted from

interp then TTccllDDeelleetteeCCoommmmaanndd does nothing and returns -1; otherwise it

returns 0. TTccllGGeettCCoommmmaannddIInnffoo 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 TTccllCCmmddIInnffoo structure pointed to by infoPtr and returns 1. A TTccllCCmmddIInnffoo structure has the following fields: typedef struct TclCmdInfo { int isNativeObjectProc; TclObjCmdProc *objProc; ClientData objClientData; TclCmdProc *proc; ClientData clientData; TclCmdDeleteProc *deleteProc; ClientData deleteData; TclNamespace *namespacePtr; } TclCmdInfo; The isNativeObjectProc field has the value 1 if TTccllCCrreeaatteeOObbjjCCoommmmaanndd was called to register the command; it is 0 if only TTccllCCrreeaatteeCCoommmmaanndd 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 TTccllCCrreeaatteeOObbjjCCoommmmaanndd;

they hold information 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 command procedure

that implements the command. If TTccllCCrreeaatteeCCoommmmaanndd was called for this

command, this is the procedure passed to it; otherwise, this is a com-

patibility procedure registered by TTccllCCrreeaatteeOObbjjCCoommmmaanndd that simply

calls the command's object-based procedure after converting its string

arguments to Tcl objects. The field deleteData is the ClientData value to pass to deleteProc; it is normally the same as clientData but may be set independently using the TTccllSSeettCCoommmmaannddIInnffoo procedure. The field namespacePtr holds a pointer to the TclNamespace that contains the command. TTccllGGeettCCoommmmaannddIInnffooFFrroommTTookkeenn is identical to TTccllGGeettCCoommmmaannddIInnffoo except that it uses a command token returned from TTccllCCrreeaatteeOObbjjCCoommmmaanndd in place of the command name. If the token parameter is NULL, it returns 0; otherwise, it returns 1 and fills in the structure designated by infoPtr.

TTccllSSeettCCoommmmaannddIInnffoo is used to modify the procedures and ClientData val-

ues 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 TTccllSSeettCCoommmmaannddIInnffoo returns 0. Otherwise, it copies the information from *infoPtr to Tcl's internal structure for the command and returns 1. TTccllSSeettCCoommmmaannddIInnffooFFrroommTTookkeenn is identical to TTccllSSeettCCoommmmaannddIInnffoo except that it takes a command token as returned by TTccllCCrreeaatteeOObbjjCCoommmmaanndd 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 TTccllSSeettCCoommmmaannddIInnffoo and TTccllSSeettCCoommmmaannddIInnffooFFrroommTTookkeenn both allow

the ClientData for a command's deletion procedure to be given a differ-

ent value than the ClientData for its command procedure. Note that neither TTccllSSeettCCoommmmaannddIInnffoo nor TTccllSSeettCCoommmmaannddIInnffooFFrroommTTookkeenn will change a command's namespace. Use TTccllEEvvaall to call the rreennaammee command to do that. TTccllGGeettCCoommmmaannddNNaammee provides a mechanism for tracking commands that have been renamed. Given a token returned by TTccllCCrreeaatteeOObbjjCCoommmmaanndd when the command was created, TTccllGGeettCCoommmmaannddNNaammee returns the string name of the command. If the command has been renamed since it was created, then TTccllGGeettCCoommmmaannddNNaammee 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 TTccllGGeettCCoomm-

mmaannddNNaammee 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.

TTccllGGeettCCoommmmaannddFFuullllNNaammee 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. TTccllGGeettCCoommmmaannddFFrroommOObbjj returns a token for the command specified by the

name in a TTccllOObbjj. The command name is resolved relative to the cur-

rent namespace. Returns NULL if the command is not found.