util/X86LINUX64/man/man3/Tcl_NRExprObj.3

   1 .\"
   2 .\" Copyright (c) 2008 by Kevin B. Kenny.
   3 .\"
   4 '\" See the file "license.terms" for information on usage and redistribution
   5 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
   6 '\"
   7 .TH NRE 3 8.6 Tcl "Tcl Library Procedures"
   8 .\" The -*- nroff -*- definitions below are for supplemental macros used
   9 .\" in Tcl/Tk manual entries.
  10 .\"
  11 .\" .AP type name in/out ?indent?
  12 .\"     Start paragraph describing an argument to a library procedure.
  13 .\"     type is type of argument (int, etc.), in/out is either "in", "out",
  14 .\"     or "in/out" to describe whether procedure reads or modifies arg,
  15 .\"     and indent is equivalent to second arg of .IP (shouldn't ever be
  16 .\"     needed;  use .AS below instead)
  17 .\"
  18 .\" .AS ?type? ?name?
  19 .\"     Give maximum sizes of arguments for setting tab stops.  Type and
  20 .\"     name are examples of largest possible arguments that will be passed
  21 .\"     to .AP later.  If args are omitted, default tab stops are used.
  22 .\"
  23 .\" .BS
  24 .\"     Start box enclosure.  From here until next .BE, everything will be
  25 .\"     enclosed in one large box.
  26 .\"
  27 .\" .BE
  28 .\"     End of box enclosure.
  29 .\"
  30 .\" .CS
  31 .\"     Begin code excerpt.
  32 .\"
  33 .\" .CE
  34 .\"     End code excerpt.
  35 .\"
  36 .\" .VS ?version? ?br?
  37 .\"     Begin vertical sidebar, for use in marking newly-changed parts
  38 .\"     of man pages.  The first argument is ignored and used for recording
  39 .\"     the version when the .VS was added, so that the sidebars can be
  40 .\"     found and removed when they reach a certain age.  If another argument
  41 .\"     is present, then a line break is forced before starting the sidebar.
  42 .\"
  43 .\" .VE
  44 .\"     End of vertical sidebar.
  45 .\"
  46 .\" .DS
  47 .\"     Begin an indented unfilled display.
  48 .\"
  49 .\" .DE
  50 .\"     End of indented unfilled display.
  51 .\"
  52 .\" .SO ?manpage?
  53 .\"     Start of list of standard options for a Tk widget. The manpage
  54 .\"     argument defines where to look up the standard options; if
  55 .\"     omitted, defaults to "options". The options follow on successive
  56 .\"     lines, in three columns separated by tabs.
  57 .\"
  58 .\" .SE
  59 .\"     End of list of standard options for a Tk widget.
  60 .\"
  61 .\" .OP cmdName dbName dbClass
  62 .\"     Start of description of a specific option.  cmdName gives the
  63 .\"     option's name as specified in the class command, dbName gives
  64 .\"     the option's name in the option database, and dbClass gives
  65 .\"     the option's class in the option database.
  66 .\"
  67 .\" .UL arg1 arg2
  68 .\"     Print arg1 underlined, then print arg2 normally.
  69 .\"
  70 .\" .QW arg1 ?arg2?
  71 .\"     Print arg1 in quotes, then arg2 normally (for trailing punctuation).
  72 .\"
  73 .\" .PQ arg1 ?arg2?
  74 .\"     Print an open parenthesis, arg1 in quotes, then arg2 normally
  75 .\"     (for trailing punctuation) and then a closing parenthesis.
  76 .\"
  77 .\"     # Set up traps and other miscellaneous stuff for Tcl/Tk man pages.
  78 .if t .wh -1.3i ^B
  79 .nr ^l \n(.l
  80 .ad b
  81 .\"     # Start an argument description
  82 .de AP
  83 .ie !"\\$4"" .TP \\$4
  84 .el \{\
  85 .   ie !"\\$2"" .TP \\n()Cu
  86 .   el          .TP 15
  87 .\}
  88 .ta \\n()Au \\n()Bu
  89 .ie !"\\$3"" \{\
  90 \&\\$1 \\fI\\$2\\fP (\\$3)
  91 .\".b
  92 .\}
  93 .el \{\
  94 .br
  95 .ie !"\\$2"" \{\
  96 \&\\$1  \\fI\\$2\\fP
  97 .\}
  98 .el \{\
  99 \&\\fI\\$1\\fP
 100 .\}
 101 .\}
 102 ..
 103 .\"     # define tabbing values for .AP
 104 .de AS
 105 .nr )A 10n
 106 .if !"\\$1"" .nr )A \\w'\\$1'u+3n
 107 .nr )B \\n()Au+15n
 108 .\"
 109 .if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n
 110 .nr )C \\n()Bu+\\w'(in/out)'u+2n
 111 ..
 112 .AS Tcl_Interp Tcl_CreateInterp in/out
 113 .\"     # BS - start boxed text
 114 .\"     # ^y = starting y location
 115 .\"     # ^b = 1
 116 .de BS
 117 .br
 118 .mk ^y
 119 .nr ^b 1u
 120 .if n .nf
 121 .if n .ti 0
 122 .if n \l'\\n(.lu\(ul'
 123 .if n .fi
 124 ..
 125 .\"     # BE - end boxed text (draw box now)
 126 .de BE
 127 .nf
 128 .ti 0
 129 .mk ^t
 130 .ie n \l'\\n(^lu\(ul'
 131 .el \{\
 132 .\"     Draw four-sided box normally, but don't draw top of
 133 .\"     box if the box started on an earlier page.
 134 .ie !\\n(^b-1 \{\
 135 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
 136 .\}
 137 .el \}\
 138 \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
 139 .\}
 140 .\}
 141 .fi
 142 .br
 143 .nr ^b 0
 144 ..
 145 .\"     # VS - start vertical sidebar
 146 .\"     # ^Y = starting y location
 147 .\"     # ^v = 1 (for troff;  for nroff this doesn't matter)
 148 .de VS
 149 .if !"\\$2"" .br
 150 .mk ^Y
 151 .ie n 'mc \s12\(br\s0
 152 .el .nr ^v 1u
 153 ..
 154 .\"     # VE - end of vertical sidebar
 155 .de VE
 156 .ie n 'mc
 157 .el \{\
 158 .ev 2
 159 .nf
 160 .ti 0
 161 .mk ^t
 162 \h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n'
 163 .sp -1
 164 .fi
 165 .ev
 166 .\}
 167 .nr ^v 0
 168 ..
 169 .\"     # Special macro to handle page bottom:  finish off current
 170 .\"     # box/sidebar if in box/sidebar mode, then invoked standard
 171 .\"     # page bottom macro.
 172 .de ^B
 173 .ev 2
 174 'ti 0
 175 'nf
 176 .mk ^t
 177 .if \\n(^b \{\
 178 .\"     Draw three-sided box if this is the box's first page,
 179 .\"     draw two sides but no top otherwise.
 180 .ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
 181 .el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
 182 .\}
 183 .if \\n(^v \{\
 184 .nr ^x \\n(^tu+1v-\\n(^Yu
 185 \kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c
 186 .\}
 187 .bp
 188 'fi
 189 .ev
 190 .if \\n(^b \{\
 191 .mk ^y
 192 .nr ^b 2
 193 .\}
 194 .if \\n(^v \{\
 195 .mk ^Y
 196 .\}
 197 ..
 198 .\"     # DS - begin display
 199 .de DS
 200 .RS
 201 .nf
 202 .sp
 203 ..
 204 .\"     # DE - end display
 205 .de DE
 206 .fi
 207 .RE
 208 .sp
 209 ..
 210 .\"     # SO - start of list of standard options
 211 .de SO
 212 'ie '\\$1'' .ds So \\fBoptions\\fR
 213 'el .ds So \\fB\\$1\\fR
 214 .SH "STANDARD OPTIONS"
 215 .LP
 216 .nf
 217 .ta 5.5c 11c
 218 .ft B
 219 ..
 220 .\"     # SE - end of list of standard options
 221 .de SE
 222 .fi
 223 .ft R
 224 .LP
 225 See the \\*(So manual entry for details on the standard options.
 226 ..
 227 .\"     # OP - start of full description for a single option
 228 .de OP
 229 .LP
 230 .nf
 231 .ta 4c
 232 Command-Line Name:      \\fB\\$1\\fR
 233 Database Name:  \\fB\\$2\\fR
 234 Database Class: \\fB\\$3\\fR
 235 .fi
 236 .IP
 237 ..
 238 .\"     # CS - begin code excerpt
 239 .de CS
 240 .RS
 241 .nf
 242 .ta .25i .5i .75i 1i
 243 ..
 244 .\"     # CE - end code excerpt
 245 .de CE
 246 .fi
 247 .RE
 248 ..
 249 .\"     # UL - underline word
 250 .de UL
 251 \\$1\l'|0\(ul'\\$2
 252 ..
 253 .\"     # QW - apply quotation marks to word
 254 .de QW
 255 .ie '\\*(lq'"' ``\\$1''\\$2
 256 .\"" fix emacs highlighting
 257 .el \\*(lq\\$1\\*(rq\\$2
 258 ..
 259 .\"     # PQ - apply parens and quotation marks to word
 260 .de PQ
 261 .ie '\\*(lq'"' (``\\$1''\\$2)\\$3
 262 .\"" fix emacs highlighting
 263 .el (\\*(lq\\$1\\*(rq\\$2)\\$3
 264 ..
 265 .\"     # QR - quoted range
 266 .de QR
 267 .ie '\\*(lq'"' ``\\$1''\\-``\\$2''\\$3
 268 .\"" fix emacs highlighting
 269 .el \\*(lq\\$1\\*(rq\\-\\*(lq\\$2\\*(rq\\$3
 270 ..
 271 .\"     # MT - "empty" string
 272 .de MT
 273 .QW ""
 274 ..
 275 .BS
 276 .SH NAME
 277 Tcl_NRCreateCommand, Tcl_NRCallObjProc, Tcl_NREvalObj, Tcl_NREvalObjv, Tcl_NRCmdSwap, Tcl_NRExprObj, Tcl_NRAddCallback \- Non-Recursive (stackless) evaluation of Tcl scripts.
 278 .SH SYNOPSIS
 279 .nf
 280 \fB#include <tcl.h>\fR
 281 .sp
 282 Tcl_Command
 283 \fBTcl_NRCreateCommand\fR(\fIinterp, cmdName, proc, nreProc, clientData,
 284                     deleteProc\fR)
 285 .sp
 286 int
 287 \fBTcl_NRCallObjProc\fR(\fIinterp, nreProc, clientData, objc, objv\fR)
 288 .sp
 289 int
 290 \fBTcl_NREvalObj\fR(\fIinterp, objPtr, flags\fR)
 291 .sp
 292 int
 293 \fBTcl_NREvalObjv\fR(\fIinterp, objc, objv, flags\fR)
 294 .sp
 295 int
 296 \fBTcl_NRCmdSwap\fR(\fIinterp, cmd, objc, objv, flags\fR)
 297 .sp
 298 int
 299 \fBTcl_NRExprObj\fR(\fIinterp, objPtr, resultPtr\fR)
 300 .sp
 301 void
 302 \fBTcl_NRAddCallback\fR(\fIinterp, postProcPtr, data0, data1, data2, data3\fR)
 303 .fi
 304 .SH ARGUMENTS
 305 .AS Tcl_CmdDeleteProc *interp in
 306 .AP Tcl_Interp *interp in
 307 Interpreter in which to create or evaluate a command.
 308 .AP char *cmdName in
 309 Name of a new command to create.
 310 .AP Tcl_ObjCmdProc *proc in
 311 Implementation of a command that will be called whenever \fIcmdName\fR
 312 is invoked as a command in the unoptimized way.
 313 .AP Tcl_ObjCmdProc *nreProc in
 314 Implementation of a command that will be called whenever \fIcmdName\fR
 315 is invoked and requested to conserve the C stack.
 316 .AP ClientData clientData in
 317 Arbitrary one-word value that will be passed to \fIproc\fR, \fInreProc\fR,
 318 \fIdeleteProc\fR and \fIobjProc\fR.
 319 .AP Tcl_CmdDeleteProc *deleteProc in/out
 320 Procedure to call before \fIcmdName\fR is deleted from the interpreter.
 321 This procedure allows for command-specific cleanup. If \fIdeleteProc\fR
 322 is \fBNULL\fR, then no procedure is called before the command is deleted.
 323 .AP int objc in
 324 Count of parameters provided to the implementation of a command.
 325 .AP Tcl_Obj **objv in
 326 Pointer to an array of Tcl values. Each value holds the value of a
 327 single word in the command to execute.
 328 .AP Tcl_Obj *objPtr in
 329 Pointer to a Tcl_Obj whose value is a script or expression to execute.
 330 .AP int flags in
 331 ORed combination of flag bits that specify additional options.
 332 \fBTCL_EVAL_GLOBAL\fR is the only flag that is currently supported.
 333 .\" TODO: This is a lie. But kbk didn't grasp TCL_EVAL_INVOKE and
 334 .\"       TCL_EVAL_NOERR well enough to document them.
 335 .AP Tcl_Command cmd in
 336 Token for a command that is to be used instead of the currently
 337 executing command.
 338 .AP Tcl_Obj *resultPtr out
 339 Pointer to an unshared Tcl_Obj where the result of expression
 340 evaluation is written.
 341 .AP Tcl_NRPostProc *postProcPtr in
 342 Pointer to a function that will be invoked when the command currently
 343 executing in the interpreter designated by \fIinterp\fR completes.
 344 .AP ClientData data0 in
 345 .AP ClientData data1 in
 346 .AP ClientData data2 in
 347 .AP ClientData data3 in
 348 \fIdata0\fR through \fIdata3\fR are four one-word values that will be passed
 349 to the function designated by \fIpostProcPtr\fR when it is invoked.
 350 .BE
 351 .SH DESCRIPTION
 352 .PP
 353 This series of C functions provides an interface whereby commands that
 354 are implemented in C can be evaluated, and invoke Tcl commands scripts
 355 and scripts, without consuming space on the C stack. The non-recursive
 356 evaluation is done by installing a \fItrampoline\fR, a small piece of
 357 code that invokes a command or script, and then executes a series of
 358 callbacks when the command or script returns.
 359 .PP
 360 The \fBTcl_NRCreateCommand\fR function creates a Tcl command in the
 361 interpreter designated by \fIinterp\fR that is prepared to handle
 362 nonrecursive evaluation with a trampoline. The \fIcmdName\fR argument
 363 gives the name of the new command. If \fIcmdName\fR contains any
 364 namespace qualifiers, then the new command is added to the specified
 365 namespace; otherwise, it is added to the global namespace. \fIproc\fR
 366 gives the procedure that will be called when the interpreter wishes to
 367 evaluate the command in an unoptimized manner, and \fInreProc\fR is
 368 the procedure that will be called when the interpreter wishes to
 369 evaluate the command using a trampoline. \fIdeleteProc\fR is a
 370 function that will be called before the command is deleted from the
 371 interpreter. When any of the three functions is invoked, it is passed
 372 the \fIclientData\fR parameter.
 373 .PP
 374 \fBTcl_NRCreateCommand\fR deletes any existing command
 375 \fIname\fR already associated with the interpreter
 376 (however see below for an exception where the existing command
 377 is not deleted).
 378 It returns a token that may be used to refer
 379 to the command in subsequent calls to \fBTcl_GetCommandName\fR.
 380 If \fBTcl_NRCreateCommand\fR is called for an interpreter that is in
 381 the process of being deleted, then it does not create a new command,
 382 does not delete any existing command of the same name, and returns NULL.
 383 .PP
 384 The \fIproc\fR and \fInreProc\fR function are expected to conform to
 385 all the rules set forth for the \fIproc\fR argument to
 386 \fBTcl_CreateObjCommand\fR(3) (\fIq.v.\fR).
 387 .PP
 388 When a command that is written to cope with evaluation via trampoline
 389 is invoked without a trampoline on the stack, it will usually respond
 390 to the invocation by creating a trampoline and calling the
 391 trampoline-enabled implementation of the same command. This call is done by
 392 means of \fBTcl_NRCallObjProc\fR. In the call to
 393 \fBTcl_NRCallObjProc\fR, the \fIinterp\fR, \fIclientData\fR,
 394 \fIobjc\fR and \fIobjv\fR parameters should be the same ones that were
 395 passed to \fIproc\fR. The \fInreProc\fR parameter should designate the
 396 trampoline-enabled implementation of the command.
 397 .PP
 398 \fBTcl_NREvalObj\fR arranges for the script contained in \fIobjPtr\fR
 399 to be evaluated in the interpreter designated by \fIinterp\fR after
 400 the current command (which must be trampoline-enabled) returns. It is
 401 the method by which a command may invoke a script without consuming
 402 space on the C stack. Similarly, \fBTcl_NREvalObjv\fR arranges to
 403 invoke a single Tcl command whose words have already been separated
 404 and substituted. The \fIobjc\fR and \fIobjv\fR parameters give the
 405 words of the command to be evaluated when execution reaches the
 406 trampoline.
 407 .PP
 408 \fBTcl_NRCmdSwap\fR allows for trampoline evaluation of a command whose
 409 resolution is already known.  The \fIcmd\fR parameter gives a
 410 \fBTcl_Command\fR token (returned from \fBTcl_CreateObjCommand\fR or
 411 \fBTcl_GetCommandFromObj\fR) identifying the command to be invoked in
 412 the trampoline; this command must match the word in \fIobjv[0]\fR.
 413 The remaining arguments are as for \fBTcl_NREvalObjv\fR.
 414 .PP
 415 \fBTcl_NREvalObj\fR, \fBTcl_NREvalObjv\fR and \fBTcl_NRCmdSwap\fR
 416 all accept a \fIflags\fR parameter, which is an OR-ed-together set of
 417 bits to control evaluation. At the present time, the only supported flag
 418 available to callers is \fBTCL_EVAL_GLOBAL\fR.
 419 .\" TODO: Again, this is a lie. Do we want to explain TCL_EVAL_INVOKE
 420 .\"       and TCL_EVAL_NOERR?
 421 If the \fBTCL_EVAL_GLOBAL\fR flag is set, the script or command is
 422 evaluated in the global namespace. If it is not set, it is evaluated
 423 in the current namespace.
 424 .PP
 425 \fBTcl_NRExprObj\fR arranges for the expression contained in \fIobjPtr\fR
 426 to be evaluated in the interpreter designated by \fIinterp\fR after
 427 the current command (which must be trampoline-enabled) returns. It is
 428 the method by which a command may evaluate a Tcl expression without consuming
 429 space on the C stack.  The argument \fIresultPtr\fR is a pointer to an
 430 unshared Tcl_Obj where the result of expression evaluation is to be written.
 431 If expression evaluation returns any code other than TCL_OK, the
 432 \fIresultPtr\fR value is left untouched.
 433 .PP
 434 All of the routines return \fBTCL_OK\fR if command or expression invocation
 435 has been scheduled successfully. If for any reason the scheduling cannot
 436 be completed (for example, if the interpreter is unable to find
 437 the requested command), they return \fBTCL_ERROR\fR with an
 438 appropriate message left in the interpreter's result.
 439 .PP
 440 \fBTcl_NRAddCallback\fR arranges to have a C function called when the
 441 current trampoline-enabled command in the Tcl interpreter designated
 442 by \fIinterp\fR returns.  The \fIpostProcPtr\fR argument is a pointer
 443 to the callback function, which must have arguments and return value
 444 consistent with the \fBTcl_NRPostProc\fR data type:
 445 .PP
 446 .CS
 447 typedef int
 448 \fBTcl_NRPostProc\fR(
 449         \fBClientData\fR \fIdata\fR[],
 450         \fBTcl_Interp\fR *\fIinterp\fR,
 451         int \fIresult\fR);
 452 .CE
 453 .PP
 454 When the trampoline invokes the callback function, the \fIdata\fR
 455 parameter will point to an array containing the four one-word
 456 quantities that were passed to \fBTcl_NRAddCallback\fR in the
 457 \fIdata0\fR through \fIdata3\fR parameters. The Tcl interpreter will
 458 be designated by the \fIinterp\fR parameter, and the \fIresult\fR
 459 parameter will contain the result (\fBTCL_OK\fR, \fBTCL_ERROR\fR,
 460 \fBTCL_RETURN\fR, \fBTCL_BREAK\fR or \fBTCL_CONTINUE\fR) that was
 461 returned by the command evaluation. The callback function is expected,
 462 in turn, either to return a \fIresult\fR to control further evaluation.
 463 .PP
 464 Multiple \fBTcl_NRAddCallback\fR invocations may request multiple
 465 callbacks, which may be to the same or different callback
 466 functions. If multiple callbacks are requested, they are executed in
 467 last-in, first-out order, that is, the most recently requested
 468 callback is executed first.
 469 .SH EXAMPLE
 470 .PP
 471 The usual pattern for Tcl commands that invoke other Tcl commands
 472 is something like:
 473 .PP
 474 .CS
 475 int
 476 \fITheCmdOldObjProc\fR(
 477     ClientData clientData,
 478     Tcl_Interp *interp,
 479     int objc,
 480     Tcl_Obj *const objv[])
 481 {
 482     int result;
 483     Tcl_Obj *objPtr;
 484
 485     \fI... preparation ...\fR
 486
 487     result = \fBTcl_EvalObjEx\fR(interp, objPtr, 0);
 488
 489     \fI... postprocessing ...\fR
 490
 491     return result;
 492 }
 493 \fBTcl_CreateObjCommand\fR(interp, "theCommand",
 494         \fITheCmdOldObjProc\fR, clientData, TheCmdDeleteProc);
 495 .CE
 496 .PP
 497 To enable a command like this one for trampoline-based evaluation,
 498 it must be split into three pieces:
 499 .IP \(bu
 500 A non-trampoline implementation, \fITheCmdNewObjProc\fR,
 501 which will simply create a trampoline
 502 and invoke the trampoline-based implementation.
 503 .IP \(bu
 504 A trampoline-enabled implementation, \fITheCmdNRObjProc\fR.  This
 505 function will perform the initialization, request that the trampoline
 506 call the postprocessing routine after command evaluation, and finally,
 507 request that the trampoline call the inner command.
 508 .IP \(bu
 509 A postprocessing routine, \fITheCmdPostProc\fR. This function will
 510 perform the postprocessing formerly done after the return from the
 511 inner command in \fITheCmdObjProc\fR.
 512 .PP
 513 The non-trampoline implementation is simple and stylized, containing
 514 a single statement:
 515 .PP
 516 .CS
 517 int
 518 \fITheCmdNewObjProc\fR(
 519     ClientData clientData,
 520     Tcl_Interp *interp,
 521     int objc,
 522     Tcl_Obj *const objv[])
 523 {
 524     return \fBTcl_NRCallObjProc\fR(interp, \fITheCmdNRObjProc\fR,
 525             clientData, objc, objv);
 526 }
 527 .CE
 528 .PP
 529 The trampoline-enabled implementation requests postprocessing,
 530 and returns to the trampoline requesting command evaluation.
 531 .PP
 532 .CS
 533 int
 534 \fITheCmdNRObjProc\fR
 535     ClientData clientData,
 536     Tcl_Interp *interp,
 537     int objc,
 538     Tcl_Obj *const objv[])
 539 {
 540     Tcl_Obj *objPtr;
 541
 542     \fI... preparation ...\fR
 543
 544     \fBTcl_NRAddCallback\fR(interp, \fITheCmdPostProc\fR,
 545             data0, data1, data2, data3);
 546     /* \fIdata0 .. data3\fR are up to four one-word items to
 547      * pass to the postprocessing procedure */
 548
 549     return \fBTcl_NREvalObj\fR(interp, objPtr, 0);
 550 }
 551 .CE
 552 .PP
 553 The postprocessing procedure does whatever the original command did
 554 upon return from the inner evaluation.
 555 .PP
 556 .CS
 557 int
 558 \fITheCmdNRPostProc\fR(
 559     ClientData data[],
 560     Tcl_Interp *interp,
 561     int result)
 562 {
 563     /* \fIdata[0] .. data[3]\fR are the four words of data
 564      * passed to \fBTcl_NRAddCallback\fR */
 565
 566     \fI... postprocessing ...\fR
 567
 568     return result;
 569 }
 570 .CE
 571 .PP
 572 If \fItheCommand\fR is a command that results in multiple commands or
 573 scripts being evaluated, its postprocessing routine may schedule
 574 additional postprocessing and then request another command evaluation
 575 by means of \fBTcl_NREvalObj\fR or one of the other evaluation
 576 routines. Looping and sequencing constructs may be implemented in this way.
 577 .PP
 578 Finally, to install a trampoline-enabled command in the interpreter,
 579 \fBTcl_NRCreateCommand\fR is used in place of
 580 \fBTcl_CreateObjCommand\fR.  It accepts two command procedures instead
 581 of one. The first is for use when no trampoline is yet on the stack,
 582 and the second is for use when there is already a trampoline in place.
 583 .PP
 584 .CS
 585 \fBTcl_NRCreateCommand\fR(interp, "theCommand",
 586         \fITheCmdNewObjProc\fR, \fITheCmdNRObjProc\fR, clientData,
 587         TheCmdDeleteProc);
 588 .CE
 589 .SH "SEE ALSO"
 590 Tcl_CreateCommand(3), Tcl_CreateObjCommand(3), Tcl_EvalObjEx(3), Tcl_GetCommandFromObj(3), Tcl_ExprObj(3)
 591 .SH KEYWORDS
 592 stackless, nonrecursive, execute, command, global, value, result, script
 593 .SH COPYRIGHT
 594 Copyright (c) 2008 by Kevin B. Kenny