1NRE(3)                      Tcl Library Procedures                      NRE(3)
2
3
4
5______________________________________________________________________________
6

NAME

8       Tcl_NRCreateCommand,  Tcl_NRCallObjProc, Tcl_NREvalObj, Tcl_NREvalObjv,
9       Tcl_NRCmdSwap, Tcl_NRExprObj, Tcl_NRAddCallback - Non-Recursive (stack‐
10       less) evaluation of Tcl scripts.
11

SYNOPSIS

13       #include <tcl.h>
14
15       Tcl_Command
16       Tcl_NRCreateCommand(interp, cmdName, proc, nreProc, clientData,
17                           deleteProc)
18
19       int
20       Tcl_NRCallObjProc(interp, nreProc, clientData, objc, objv)
21
22       int
23       Tcl_NREvalObj(interp, objPtr, flags)
24
25       int
26       Tcl_NREvalObjv(interp, objc, objv, flags)
27
28       int
29       Tcl_NRCmdSwap(interp, cmd, objc, objv, flags)
30
31       int
32       Tcl_NRExprObj(interp, objPtr, resultPtr)
33
34       void
35       Tcl_NRAddCallback(interp, postProcPtr, data0, data1, data2, data3)
36

ARGUMENTS

38       Tcl_Interp *interp (in)                 The relevant Interpreter.
39
40       char *cmdName (in)                      Name of the command to create.
41
42       Tcl_ObjCmdProc *proc (in)               Called  in  order to evaluate a
43                                               command.  Is often just a small
44                                               wrapper that uses Tcl_NRCallOb‐
45                                               jProc to call nreProc  using  a
46                                               new trampoline.  Behaves in the
47                                               same way as the  proc  argument
48                                               to      Tcl_CreateObjCommand(3)
49                                               (q.v.).
50
51       Tcl_ObjCmdProc *nreProc (in)            Called instead of proc  when  a
52                                               trampoline is already in use.
53
54       ClientData clientData (in)              Arbitrary one-word value passed
55                                               to  proc,  nreProc,  deleteProc
56                                               and objProc.
57
58       Tcl_CmdDeleteProc *deleteProc (in/out)  Called    before   cmdName   is
59                                               deleted from  the  interpreter,
60                                               allowing  for  command-specific
61                                               cleanup. May be NULL.
62
63       int objc (in)                           Number of items in objv.
64
65       Tcl_Obj **objv (in)                     Words in the command.
66
67       Tcl_Obj *objPtr (in)                    A script or expression to eval‐
68                                               uate.
69
70       int flags (in)                          As described for Tcl_EvalObjv.
71
72       Tcl_Command cmd (in)                    Token  to  use  instead  of one
73                                               derived from the first word  of
74                                               objv  in  order  to  evaluate a
75                                               command.
76
77       Tcl_Obj *resultPtr (out)                Pointer to an unshared  Tcl_Obj
78                                               where the result of the evalua‐
79                                               tion is stored  if  the  return
80                                               code is TCL_OK.
81
82       Tcl_NRPostProc *postProcPtr (in)        A function to push.
83
84       ClientData data0 (in)
85
86       ClientData data1 (in)
87
88       ClientData data2 (in)
89
90       ClientData data3 (in)                   data0  through  data3  are four
91                                               one-word values  that  will  be
92                                               passed  to  the function desig‐
93                                               nated by postProcPtr when it is
94                                               invoked.
95______________________________________________________________________________
96

DESCRIPTION

98       These  functions  provide  an  interface  to the function stack that an
99       interpreter iterates through to evaluate commands.  The routine  behind
100       a  command  is  implemented  by  an initial function and any additional
101       functions that the routine pushes onto the stack as it progresses.  The
102       interpreter  itself pushes functions onto the stack to react to the end
103       of a routine and to exercise other forms of control such  as  switching
104       between in-progress stacks and the evaluation of other scripts at addi‐
105       tional levels without adding frames to the C stack.  To execute a  rou‐
106       tine,  the  initial function for the routine is called and then a small
107       bit of code called a trampoline iteratively  takes  functions  off  the
108       stack  and calls them, using the value of the last call as the value of
109       the routine.
110
111       Tcl_NRCallObjProc calls nreProc using a new trampoline.
112
113       Tcl_NRCreateCommand, an alternative to  Tcl_CreateObjCommand,  resolves
114       cmdName,  which  may contain namespace qualifiers, relative to the cur‐
115       rent namespace, creates a command by that name, and returns a token for
116       the  command  which  may be used in subsequent calls to Tcl_GetCommand‐
117       Name.  Except for a few cases noted below any existing command  by  the
118       same  name  is  first  deleted.   If  interp is in the process of being
119       deleted Tcl_NRCreateCommand does  not  create  any  command,  does  not
120       delete any command, and returns NULL.
121
122       Tcl_NREvalObj pushes a function that is like Tcl_EvalObjEx but consumes
123       no space on the C stack.
124
125       Tcl_NREvalObjv pushes a function that is like Tcl_EvalObjv but consumes
126       no space on the C stack.
127
128       Tcl_NRCmdSwap  is like Tcl_NREvalObjv, but uses cmd, a token previously
129       returned by Tcl_CreateObjCommand or Tcl_GetCommandFromObj,  instead  of
130       resolving the first word of objv.
131
132       Tcl_NRExprObj  pushes a function that evaluates objPtr as an expression
133       in the same manner as Tcl_ExprObj but without consuming space on the  C
134       stack.
135
136       All  of  the  functions  return TCL_OK if the evaluation of the script,
137       command, or expression has been scheduled successfully.  Otherwise (for
138       example  if the command name cannot be resolved), they return TCL_ERROR
139       and store a message as the interpreter's result.
140
141       Tcl_NRAddCallback pushes postProcPtr.  The signature for Tcl_NRPostProc
142       is:
143
144              typedef int
145              Tcl_NRPostProc(
146                      ClientData data[],
147                      Tcl_Interp *interp,
148                      int result);
149
150       data  is  a pointer to an array containing data0 through data3.  result
151       is the value returned by the previous function  implementing  part  the
152       routine.
153

EXAMPLE

155       The following command uses Tcl_EvalObjEx, which consumes space on the C
156       stack, to evalute a script:
157
158              int
159              TheCmdOldObjProc(
160                  ClientData clientData,
161                  Tcl_Interp *interp,
162                  int objc,
163                  Tcl_Obj *const objv[])
164              {
165                  int result;
166                  Tcl_Obj *objPtr;
167
168                  ... preparation ...
169
170                  result = Tcl_EvalObjEx(interp, objPtr, 0);
171
172                  ... postprocessing ...
173
174                  return result;
175              }
176              Tcl_CreateObjCommand(interp, "theCommand",
177                      TheCmdOldObjProc, clientData, TheCmdDeleteProc);
178
179       To avoid consuming space on the C stack, TheCmdOldObjProc is renamed to
180       TheCmdNRObjProc  and  the  postprocessing step is split into a separate
181       function, TheCmdPostProc, which is  pushed  onto  the  function  stack.
182       Tcl_EvalObjEx  is  replaced with Tcl_NREvalObj, which uses a trampoline
183       instead of consuming space on the C stack.  A  new  version  of  TheCm‐
184       dOldObjProc  is  just  a  a wrapper that uses Tcl_NRCallObjProc to call
185       TheCmdNRObjProc:
186
187              int
188              TheCmdOldObjProc(
189                  ClientData clientData,
190                  Tcl_Interp *interp,
191                  int objc,
192                  Tcl_Obj *const objv[])
193              {
194                  return Tcl_NRCallObjProc(interp, TheCmdNRObjProc,
195                          clientData, objc, objv);
196              }
197
198              int
199              TheCmdNRObjProc
200                  ClientData clientData,
201                  Tcl_Interp *interp,
202                  int objc,
203                  Tcl_Obj *const objv[])
204              {
205                  Tcl_Obj *objPtr;
206
207                  ... preparation ...
208
209                  Tcl_NRAddCallback(interp, TheCmdPostProc,
210                          data0, data1, data2, data3);
211                  /* data0 .. data3 are up to four one-word items to
212                   * pass to the postprocessing procedure */
213
214                  return Tcl_NREvalObj(interp, objPtr, 0);
215              }
216
217              int
218              TheCmdNRPostProc(
219                  ClientData data[],
220                  Tcl_Interp *interp,
221                  int result)
222              {
223                  /* data[0] .. data[3] are the four words of data
224                   * passed to Tcl_NRAddCallback */
225
226                  ... postprocessing ...
227
228                  return result;
229              }
230
231       Any function comprising a routine can push other functions,  making  it
232       possible implement looping and sequencing constructs using the function
233       stack.
234

SEE ALSO

236       Tcl_CreateCommand(3),    Tcl_CreateObjCommand(3),     Tcl_EvalObjEx(3),
237       Tcl_GetCommandFromObj(3), Tcl_ExprObj(3)
238

KEYWORDS

240       stackless,  nonrecursive,  execute,  command,  global,  value,  result,
241       script
242
244       Copyright (c) 2008 by Kevin B. Kenny.  Copyright  (c)  2018  by  Nathan
245       Coulter.
246
247
248
249Tcl                                   8.6                               NRE(3)
Impressum