summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authordkf <donal.k.fellows@manchester.ac.uk>2009-11-01 13:00:07 (GMT)
committerdkf <donal.k.fellows@manchester.ac.uk>2009-11-01 13:00:07 (GMT)
commit49e406bc1ce2d46e428fda956d146421c3d23ccb (patch)
tree8290b56987d17ec70596164a78fb91f39fae4903
parent4320ee4771f6a07f9a4a064f02de3e117df909ca (diff)
downloadtcl-49e406bc1ce2d46e428fda956d146421c3d23ccb.zip
tcl-49e406bc1ce2d46e428fda956d146421c3d23ccb.tar.gz
tcl-49e406bc1ce2d46e428fda956d146421c3d23ccb.tar.bz2
Apply a bit more polish
-rw-r--r--doc/NRE.3103
1 files changed, 57 insertions, 46 deletions
diff --git a/doc/NRE.3 b/doc/NRE.3
index 4103e3d..633733f 100644
--- a/doc/NRE.3
+++ b/doc/NRE.3
@@ -5,7 +5,7 @@
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\"
-'\" RCS: @(#) $Id: NRE.3,v 1.4 2009/08/12 16:06:38 dgp Exp $
+'\" RCS: @(#) $Id: NRE.3,v 1.5 2009/11/01 13:00:07 dkf Exp $
'\"
.so man.macros
.TH NRE 3 8.6 Tcl "Tcl Library Procedures"
@@ -17,7 +17,8 @@ Tcl_NRCreateCommand, Tcl_NRCallObjProc, Tcl_NREvalObj, Tcl_NREvalObjv, Tcl_NRCmd
\fB#include <tcl.h>\fR
.sp
Tcl_Command
-\fBTcl_NRCreateCommand\fR(\fIinterp, cmdName, proc, nreProc, clientData, deleteProc\fR)
+\fBTcl_NRCreateCommand\fR(\fIinterp, cmdName, proc, nreProc, clientData,
+ deleteProc\fR)
.sp
int
\fBTcl_NRCallObjProc\fR(\fIinterp, nreProc, clientData, objc, objv\fR)
@@ -38,7 +39,7 @@ void
\fBTcl_NRAddCallback\fR(\fIinterp, postProcPtr, data0, data1, data2, data3\fR)
.fi
.SH ARGUMENTS
-.AS Tcl_CmdDeleteProc *postProcPtr in
+.AS Tcl_CmdDeleteProc *interp in
.AP Tcl_Interp *interp in
Interpreter in which to create or evaluate a command.
.AP char *cmdName in
@@ -54,7 +55,7 @@ Arbitrary one-word value that will be passed to \fIproc\fR, \fInreProc\fR,
\fIdeleteProc\fR and \fIobjProc\fR.
.AP Tcl_CmdDeleteProc *deleteProc in/out
Procedure to call before \fIcmdName\fR is deleted from the interpreter.
-This procedure allows for command-specific cleanup. If \fIdeletProc\fR
+This procedure allows for command-specific cleanup. If \fIdeleteProc\fR
is \fBNULL\fR, then no procedure is called before the command is deleted.
.AP int objc in
Count of parameters provided to the implementation of a command.
@@ -139,7 +140,7 @@ and substituted. The \fIobjc\fR and \fIobjv\fR parameters give the
words of the command to be evaluated when execution reaches the
trampoline.
.PP
-\fBTcl_NRCmdSwap allows for trampoline evaluation of a command whose
+\fBTcl_NRCmdSwap\fR allows for trampoline evaluation of a command whose
resolution is already known. The \fIcmd\fR parameter gives a
\fBTcl_Command\fR object (returned from \fBTcl_CreateObjCmd\fR or
\fBTcl_GetCommandFromObj\fR) identifying the command to be invoked in
@@ -148,7 +149,7 @@ The remaining arguments are as for \fBTcl_NREvalObj\fR.
.PP
\fBTcl_NREvalObj\fR, \fBTcl_NREvalObjv\fR and \fBTcl_NRCmdSwap\fR
all accept a \fIflags\fR parameter, which is an OR-ed-together set of
-bits to control evaluation. At the present time, the only flag
+bits to control evaluation. At the present time, the only supported flag
available to callers is \fBTCL_EVAL_GLOBAL\fR.
.\" TODO: Again, this is a lie. Do we want to explain TCL_EVAL_INVOKE
.\" and TCL_EVAL_NOERR?
@@ -180,9 +181,9 @@ consistent with the \fBTcl_NRPostProc\fR data type:
.CS
typedef int
\fBTcl_NRPostProc\fR(
- \fBClientData\fR \fIdata\fR[],
- \fBTcl_Interp\fR *\fIinterp\fR,
- int \fIresult\fR);
+ \fBClientData\fR \fIdata\fR[],
+ \fBTcl_Interp\fR *\fIinterp\fR,
+ int \fIresult\fR);
.CE
.PP
When the trampoline invokes the callback function, the \fIdata\fR
@@ -206,22 +207,26 @@ The usual pattern for Tcl commands that invoke other Tcl commands
is something like:
.PP
.CS
-int \fITheCmdObjProc\fR(
- \fBClientData\fR \fIclientData\fR,
- \fBTcl_Interp\fR *\fIinterp\fR,
- int \fIobjc\fR,
- \fBTcl_Obj\fR *const \fIobjv\fR[])
+int
+\fITheCmdObjProc\fR(
+ ClientData clientData,
+ Tcl_Interp *interp,
+ int objc,
+ Tcl_Obj *const objv[])
{
- int \fIresult\fR;
- \fBTcl_Obj\fR *\fIobjPtr\fR;
+ int result;
+ Tcl_Obj *objPtr;
+
\fI... preparation ...\fR
- \fIresult\fR = \fBTcl_EvalObjEx\fR(\fIinterp\fR, \fIobjPtr\fR, 0);
+
+ result = \fBTcl_EvalObjEx\fR(interp, objPtr, 0);
+
\fI... postprocessing ...\fR
- return \fIresult\fR;
+
+ return result;
}
-\fBTcl_CreateObjCommand\fR(\fIinterp\fR, "theCommand",
- \fITheCmdObjProc\fR, \fIclientData\fR,
- \fITheCmdDeleteProc\fR);
+\fBTcl_CreateObjCommand\fR(interp, "theCommand",
+ \fITheCmdObjProc\fR, clientData, TheCmdDeleteProc);
.CE
.PP
To enable a command like this one for trampoline-based evaluation,
@@ -245,14 +250,14 @@ a single statement:
.PP
.CS
int
-TheCmdNewObjProc
- \fBClientData\fR \fIclientData\fR,
- \fBTcl_Interp\fR *\fIinterp\fR,
- int \fIobjc\fR,
- \fBTcl_Obj\fR *const \fIobjv\fR[])
+\fITheCmdNewObjProc\fR(
+ ClientData clientData,
+ Tcl_Interp *interp,
+ int objc,
+ Tcl_Obj *const objv[])
{
- return \fBTcl_NRCallObjProc\fR(\fIinterp, name,\fR
- \fITheCmdNRObjProc, clientData, objc, objv\fR);
+ return \fBTcl_NRCallObjProc\fR(interp, name,
+ \fITheCmdNRObjProc\fR, clientData, objc, objv);
}
.CE
.PP
@@ -261,18 +266,22 @@ and returns to the trampoline requesting command evaluation.
.PP
.CS
int
-TheCmdNRObjProc
- \fBClientData\fR \fIclientData\fR,
- \fBTcl_Interp\fR *\fIinterp\fR,
- int \fIobjc\fR,
- \fBTcl_Obj\fR *const \fIobjv\fR[])
+\fITheCmdNRObjProc\fR
+ ClientData clientData,
+ Tcl_Interp *interp,
+ int objc,
+ Tcl_Obj *const objv[])
{
+ Tcl_Obj *objPtr;
+
\fI... preparation ...\fR
- \fBTcl_NRAddCallback\fR(\fIinterp, TheCmdPostProc,\fR
- \fIdata0, data1, data2, data3\fR);
- /* \fIdata0 .. data3\fR are up to four one-word items
- * to pass to the postprocessing procedure */
- return \fBTcl_NREvalObj\fR(\fIinterp, objPtr, 0\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
@@ -281,14 +290,16 @@ upon return from the inner evaluation.
.PP
.CS
int
-TheCmdNRPostProc
- \fBClientData\fR \fIdata\fR[],
- \fBTcl_Interp\fR *\fIinterp\fR,
- int \fIresult\fR
+\fITheCmdNRPostProc\fR(
+ ClientData data[],
+ Tcl_Interp *interp,
+ int result)
{
- /* \fIdata[0] .. data[4]\fR are the four words of data
+ /* \fIdata[0] .. data[3]\fR are the four words of data
* passed to \fBTcl_NREvalObj\fR */
+
\fI... postprocessing ...\fR
+
return result;
}
.CE
@@ -306,9 +317,9 @@ of one. The first is for use when no trampoline is yet on the stack,
and the second is for use when there is already a trampoline in place.
.PP
.CS
-\fBTcl_NRCreateCommand\fR(\fIinterp\fR, "theCommand",
- \fITheCmdObjProc\fR, \fITheCmdNRObjProc\fR, \fIclientData\fR,
- \fITheCmdDeleteProc\fR);
+\fBTcl_NRCreateCommand\fR(interp, "theCommand",
+ \fITheCmdObjProc\fR, \fITheCmdNRObjProc\fR, clientData,
+ TheCmdDeleteProc);
.CE
.SH "SEE ALSO"
Tcl_CreateCommand(3), Tcl_CreateObjCommand(3), Tcl_EvalObjEx(3), Tcl_GetCommandFromObj(3), Tcl_ExprObj(3)