237 lines
7.7 KiB
Groff
237 lines
7.7 KiB
Groff
|
.\"
|
||
|
.\" Copyright (c) 2008 Kevin B. Kenny.
|
||
|
.\" Copyright (c) 2018 Nathan Coulter.
|
||
|
.\"
|
||
|
'\" See the file "license.terms" for information on usage and redistribution
|
||
|
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
|
||
|
'\"
|
||
|
.TH NRE 3 8.6 Tcl "Tcl Library Procedures"
|
||
|
.so man.macros
|
||
|
.BS
|
||
|
.SH NAME
|
||
|
Tcl_NRCreateCommand, Tcl_NRCallObjProc, Tcl_NREvalObj, Tcl_NREvalObjv, Tcl_NRCmdSwap, Tcl_NRExprObj, Tcl_NRAddCallback \- Non-Recursive (stackless) evaluation of Tcl scripts.
|
||
|
.SH SYNOPSIS
|
||
|
.nf
|
||
|
\fB#include <tcl.h>\fR
|
||
|
.sp
|
||
|
Tcl_Command
|
||
|
\fBTcl_NRCreateCommand\fR(\fIinterp, cmdName, proc, nreProc, clientData,
|
||
|
deleteProc\fR)
|
||
|
.sp
|
||
|
int
|
||
|
\fBTcl_NRCallObjProc\fR(\fIinterp, nreProc, clientData, objc, objv\fR)
|
||
|
.sp
|
||
|
int
|
||
|
\fBTcl_NREvalObj\fR(\fIinterp, objPtr, flags\fR)
|
||
|
.sp
|
||
|
int
|
||
|
\fBTcl_NREvalObjv\fR(\fIinterp, objc, objv, flags\fR)
|
||
|
.sp
|
||
|
int
|
||
|
\fBTcl_NRCmdSwap\fR(\fIinterp, cmd, objc, objv, flags\fR)
|
||
|
.sp
|
||
|
int
|
||
|
\fBTcl_NRExprObj\fR(\fIinterp, objPtr, resultPtr\fR)
|
||
|
.sp
|
||
|
void
|
||
|
\fBTcl_NRAddCallback\fR(\fIinterp, postProcPtr, data0, data1, data2, data3\fR)
|
||
|
.fi
|
||
|
.SH ARGUMENTS
|
||
|
.AS Tcl_CmdDeleteProc *interp in
|
||
|
.AP Tcl_Interp *interp in
|
||
|
The relevant Interpreter.
|
||
|
.AP "const char" *cmdName in
|
||
|
Name of the command to create.
|
||
|
.AP Tcl_ObjCmdProc *proc in
|
||
|
Called in order to evaluate a command. Is often just a small wrapper that uses
|
||
|
\fBTcl_NRCallObjProc\fR to call \fInreProc\fR using a new trampoline. Behaves
|
||
|
in the same way as the \fIproc\fR argument to \fBTcl_CreateObjCommand\fR(3)
|
||
|
(\fIq.v.\fR).
|
||
|
.AP Tcl_ObjCmdProc *nreProc in
|
||
|
Called instead of \fIproc\fR when a trampoline is already in use.
|
||
|
.AP ClientData clientData in
|
||
|
Arbitrary one-word value passed to \fIproc\fR, \fInreProc\fR, \fIdeleteProc\fR
|
||
|
and \fIobjProc\fR.
|
||
|
.AP Tcl_CmdDeleteProc *deleteProc in/out
|
||
|
Called before \fIcmdName\fR is deleted from the interpreter, allowing for
|
||
|
command-specific cleanup. May be NULL.
|
||
|
.AP int objc in
|
||
|
Number of items in \fIobjv\fR.
|
||
|
.AP Tcl_Obj **objv in
|
||
|
Words in the command.
|
||
|
.AP Tcl_Obj *objPtr in
|
||
|
A script or expression to evaluate.
|
||
|
.AP int flags in
|
||
|
As described for \fITcl_EvalObjv\fR.
|
||
|
.PP
|
||
|
.AP Tcl_Command cmd in
|
||
|
Token to use instead of one derived from the first word of \fIobjv\fR in order
|
||
|
to evaluate a command.
|
||
|
.AP Tcl_Obj *resultPtr out
|
||
|
Pointer to an unshared Tcl_Obj where the result of the evaluation is stored if
|
||
|
the return code is TCL_OK.
|
||
|
.AP Tcl_NRPostProc *postProcPtr in
|
||
|
A function to push.
|
||
|
.AP ClientData data0 in
|
||
|
.AP ClientData data1 in
|
||
|
.AP ClientData data2 in
|
||
|
.AP ClientData data3 in
|
||
|
\fIdata0\fR through \fIdata3\fR are four one-word values that will be passed
|
||
|
to the function designated by \fIpostProcPtr\fR when it is invoked.
|
||
|
.BE
|
||
|
.SH DESCRIPTION
|
||
|
.PP
|
||
|
These functions provide an interface to the function stack that an interpreter
|
||
|
iterates through to evaluate commands. The routine behind a command is
|
||
|
implemented by an initial function and any additional functions that the
|
||
|
routine pushes onto the stack as it progresses. The interpreter itself pushes
|
||
|
functions onto the stack to react to the end of a routine and to exercise other
|
||
|
forms of control such as switching between in-progress stacks and the
|
||
|
evaluation of other scripts at additional levels without adding frames to the C
|
||
|
stack. To execute a routine, the initial function for the routine is called
|
||
|
and then a small bit of code called a \fItrampoline\fR iteratively takes
|
||
|
functions off the stack and calls them, using the value of the last call as the
|
||
|
value of the routine.
|
||
|
.PP
|
||
|
\fBTcl_NRCallObjProc\fR calls \fInreProc\fR using a new trampoline.
|
||
|
.PP
|
||
|
\fBTcl_NRCreateCommand\fR, an alternative to \fBTcl_CreateObjCommand\fR,
|
||
|
resolves \fIcmdName\fR, which may contain namespace qualifiers, relative to the
|
||
|
current namespace, creates a command by that name, and returns a token for the
|
||
|
command which may be used in subsequent calls to \fBTcl_GetCommandName\fR.
|
||
|
Except for a few cases noted below any existing command by the same name is
|
||
|
first deleted. If \fIinterp\fR is in the process of being deleted
|
||
|
\fBTcl_NRCreateCommand\fR does not create any command, does not delete any
|
||
|
command, and returns NULL.
|
||
|
.PP
|
||
|
\fBTcl_NREvalObj\fR pushes a function that is like \fBTcl_EvalObjEx\fR but
|
||
|
consumes no space on the C stack.
|
||
|
.PP
|
||
|
\fBTcl_NREvalObjv\fR pushes a function that is like \fBTcl_EvalObjv\fR but
|
||
|
consumes no space on the C stack.
|
||
|
.PP
|
||
|
\fBTcl_NRCmdSwap\fR is like \fBTcl_NREvalObjv\fR, but uses \fIcmd\fR, a token
|
||
|
previously returned by \fBTcl_CreateObjCommand\fR or
|
||
|
\fBTcl_GetCommandFromObj\fR, instead of resolving the first word of \fIobjv\fR.
|
||
|
. The name of this command must be the same as \fIobjv[0]\fR.
|
||
|
.PP
|
||
|
\fBTcl_NRExprObj\fR pushes a function that evaluates \fIobjPtr\fR as an
|
||
|
expression in the same manner as \fBTcl_ExprObj\fR but without consuming space
|
||
|
on the C stack.
|
||
|
.PP
|
||
|
All of the functions return \fBTCL_OK\fR if the evaluation of the script,
|
||
|
command, or expression has been scheduled successfully. Otherwise (for example
|
||
|
if the command name cannot be resolved), they return \fBTCL_ERROR\fR and store
|
||
|
a message as the interpreter's result.
|
||
|
.PP
|
||
|
\fBTcl_NRAddCallback\fR pushes \fIpostProcPtr\fR. The signature for
|
||
|
\fBTcl_NRPostProc\fR is:
|
||
|
.PP
|
||
|
.CS
|
||
|
typedef int
|
||
|
\fBTcl_NRPostProc\fR(
|
||
|
\fBClientData\fR \fIdata\fR[],
|
||
|
\fBTcl_Interp\fR *\fIinterp\fR,
|
||
|
int \fIresult\fR);
|
||
|
.CE
|
||
|
.PP
|
||
|
\fIdata\fR is a pointer to an array containing \fIdata0\fR through \fIdata3\fR.
|
||
|
\fIresult\fR is the value returned by the previous function implementing part
|
||
|
the routine.
|
||
|
.SH EXAMPLE
|
||
|
.PP
|
||
|
The following command uses \fBTcl_EvalObjEx\fR, which consumes space on the C
|
||
|
stack, to evalute a script:
|
||
|
.PP
|
||
|
.CS
|
||
|
int
|
||
|
\fITheCmdOldObjProc\fR(
|
||
|
ClientData clientData,
|
||
|
Tcl_Interp *interp,
|
||
|
int objc,
|
||
|
Tcl_Obj *const objv[])
|
||
|
{
|
||
|
int result;
|
||
|
Tcl_Obj *objPtr;
|
||
|
|
||
|
\fI... preparation ...\fR
|
||
|
|
||
|
result = \fBTcl_EvalObjEx\fR(interp, objPtr, 0);
|
||
|
|
||
|
\fI... postprocessing ...\fR
|
||
|
|
||
|
return result;
|
||
|
}
|
||
|
\fBTcl_CreateObjCommand\fR(interp, "theCommand",
|
||
|
\fITheCmdOldObjProc\fR, clientData, TheCmdDeleteProc);
|
||
|
.CE
|
||
|
.PP
|
||
|
To avoid consuming space on the C stack, \fITheCmdOldObjProc\fR is renamed to
|
||
|
\fITheCmdNRObjProc\fR and the postprocessing step is split into a separate
|
||
|
function, \fITheCmdPostProc\fR, which is pushed onto the function stack.
|
||
|
\fITcl_EvalObjEx\fR is replaced with \fITcl_NREvalObj\fR, which uses a
|
||
|
trampoline instead of consuming space on the C stack. A new version of
|
||
|
\fITheCmdOldObjProc\fR is just a a wrapper that uses \fBTcl_NRCallObjProc\fR to
|
||
|
call \fITheCmdNRObjProc\fR:
|
||
|
.PP
|
||
|
.CS
|
||
|
int
|
||
|
\fITheCmdOldObjProc\fR(
|
||
|
ClientData clientData,
|
||
|
Tcl_Interp *interp,
|
||
|
int objc,
|
||
|
Tcl_Obj *const objv[])
|
||
|
{
|
||
|
return \fBTcl_NRCallObjProc\fR(interp, \fITheCmdNRObjProc\fR,
|
||
|
clientData, objc, objv);
|
||
|
}
|
||
|
.CE
|
||
|
.PP
|
||
|
.CS
|
||
|
int
|
||
|
\fITheCmdNRObjProc\fR
|
||
|
ClientData clientData,
|
||
|
Tcl_Interp *interp,
|
||
|
int objc,
|
||
|
Tcl_Obj *const objv[])
|
||
|
{
|
||
|
Tcl_Obj *objPtr;
|
||
|
|
||
|
\fI... preparation ...\fR
|
||
|
|
||
|
\fBTcl_NRAddCallback\fR(interp, \fITheCmdPostProc\fR,
|
||
|
data0, data1, data2, data3);
|
||
|
/* \fIdata0 .. data3\fR are up to four one-word items to
|
||
|
* pass to the postprocessing procedure */
|
||
|
|
||
|
return \fBTcl_NREvalObj\fR(interp, objPtr, 0);
|
||
|
}
|
||
|
.CE
|
||
|
.PP
|
||
|
.CS
|
||
|
int
|
||
|
\fITheCmdNRPostProc\fR(
|
||
|
ClientData data[],
|
||
|
Tcl_Interp *interp,
|
||
|
int result)
|
||
|
{
|
||
|
/* \fIdata[0] .. data[3]\fR are the four words of data
|
||
|
* passed to \fBTcl_NRAddCallback\fR */
|
||
|
|
||
|
\fI... postprocessing ...\fR
|
||
|
|
||
|
return result;
|
||
|
}
|
||
|
.CE
|
||
|
.PP
|
||
|
Any function comprising a routine can push other functions, making it possible
|
||
|
implement looping and sequencing constructs using the function stack.
|
||
|
.PP
|
||
|
.SH "SEE ALSO"
|
||
|
Tcl_CreateCommand(3), Tcl_CreateObjCommand(3), Tcl_EvalObjEx(3), Tcl_GetCommandFromObj(3), Tcl_ExprObj(3)
|
||
|
.SH KEYWORDS
|
||
|
stackless, nonrecursive, execute, command, global, value, result, script
|
||
|
.SH COPYRIGHT
|
||
|
Copyright \(co 2008 Kevin B. Kenny.
|
||
|
Copyright \(co 2018 Nathan Coulter.
|