diff options
Diffstat (limited to 'doc/interp.n')
| -rw-r--r-- | doc/interp.n | 133 |
1 files changed, 93 insertions, 40 deletions
diff --git a/doc/interp.n b/doc/interp.n index c986519..92113a6 100644 --- a/doc/interp.n +++ b/doc/interp.n @@ -6,10 +6,8 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: interp.n,v 1.41 2008/10/17 10:22:25 dkf Exp $ -'\" -.so man.macros .TH interp n 8.6 Tcl "Tcl Built-In Commands" +.so man.macros .BS '\" Note: do not modify the .SH NAME line immediately below! .SH NAME @@ -63,10 +61,18 @@ on how the alias mechanism works. A qualified interpreter name is a proper Tcl lists containing a subset of its ancestors in the interpreter hierarchy, terminated by the string naming the interpreter in its immediate master. Interpreter names are relative to the -interpreter in which they are used. For example, if \fBa\fR is a slave of -the current interpreter and it has a slave \fBa1\fR, which in turn has a -slave \fBa11\fR, the qualified name of \fBa11\fR in \fBa\fR is the list -\fBa1 a11\fR. +interpreter in which they are used. For example, if +.QW \fBa\fR +is a slave of the current interpreter and it has a slave +.QW \fBa1\fR , +which in turn has a slave +.QW \fBa11\fR , +the qualified name of +.QW \fBa11\fR +in +.QW \fBa\fR +is the list +.QW "\fBa1 a11\fR" . .PP The \fBinterp\fR command, described below, accepts qualified interpreter names as arguments; the interpreter in which the command is being evaluated @@ -110,10 +116,12 @@ invoking the command. interpreter. For example, .QW "\fBa b\fR" identifies an interpreter -\fBb\fR, which is a slave of interpreter \fBa\fR, which is a slave -of the invoking interpreter. An empty list specifies the interpreter -invoking the command. \fIsrcCmd\fR gives the name of a new -command, which will be created in the source interpreter. +.QW \fBb\fR , +which is a slave of interpreter +.QW \fBa\fR , +which is a slave of the invoking interpreter. An empty list specifies +the interpreter invoking the command. \fIsrcCmd\fR gives the name of +a new command, which will be created in the source interpreter. \fITargetPath\fR and \fItargetCmd\fR specify a target interpreter and command, and the \fIarg\fR arguments, if any, specify additional arguments to \fItargetCmd\fR which are prepended to any arguments specified @@ -138,12 +146,12 @@ as the current names of the commands). .TP \fBinterp bgerror \fIpath\fR ?\fIcmdPrefix\fR? . -This command either gets or sets the current background error handler +This command either gets or sets the current background exception handler for the interpreter identified by \fIpath\fR. If \fIcmdPrefix\fR is -absent, the current background error handler is returned, and if it is +absent, the current background exception handler is returned, and if it is present, it is a list of words (of minimum length one) that describes -what to set the interpreter's background error to. See the -\fBBACKGROUND ERROR HANDLING\fR section for more details. +what to set the interpreter's background exception handler to. See the +\fBBACKGROUND EXCEPTION HANDLING\fR section for more details. .TP \fBinterp\fR \fBcancel \fR?\fB\-unwind\fR? ?\fB\-\|\-\fR? ?\fIpath\fR? ?\fIresult\fR? .VS 8.6 @@ -186,6 +194,48 @@ given name already exists in this master. The initial recursion limit of the slave interpreter is set to the current recursion limit of its parent interpreter. .TP +\fBinterp\fR \fBdebug \fIpath\fR ?\fB\-frame\fR ?\fIbool\fR?? +. +Controls whether frame-level stack information is captured in the +slave interpreter identified by \fIpath\fR. If no arguments are +given, option and current setting are returned. If \fB\-frame\fR +is given, the debug setting is set to the given boolean if provided +and the current setting is returned. +This only effects the output of \fBinfo frame\fR, in that exact +frame-level information for command invocation at the bytecode level +is only captured with this setting on. +.RS +.PP +For example, with code like +.PP +.CS +\fBproc\fR mycontrol {... script} { + ... + \fBuplevel\fR 1 $script + ... +} + +\fBproc\fR dosomething {...} { + ... + mycontrol { + somecode + } +} +.CE +.PP +the standard setting will provide a relative line number for the +command \fBsomecode\fR and the relevant frame will be of type +\fBeval\fR. With frame-debug active on the other hand the tracking +extends so far that the system will be able to determine the file and +absolute line number of this command, and return a frame of type +\fBsource\fR. This more exact information is paid for with slower +execution of all commands. +.PP +Note that once it is on, this flag cannot be switched back off: such +attempts are silently ignored. This is needed to maintain the +consistency of the underlying interpreter's state. +.RE +.TP \fBinterp\fR \fBdelete \fR?\fIpath ...?\fR . Deletes zero or more interpreters given by the optional \fIpath\fR @@ -296,7 +346,7 @@ already trusted. Returns the maximum allowable nesting depth for the interpreter specified by \fIpath\fR. If \fInewlimit\fR is specified, the interpreter recursion limit will be set so that nesting -of more than \fInewlimit\fR calls to \fBTcl_Eval()\fR +of more than \fInewlimit\fR calls to \fBTcl_Eval\fR and related procedures in that interpreter will return an error. The \fInewlimit\fR value is also returned. The \fInewlimit\fR value must be a positive integer between 1 and the @@ -395,12 +445,12 @@ does not have to be equal to \fIsrcCmd\fR. .TP \fIslave \fBbgerror\fR ?\fIcmdPrefix\fR? . -This command either gets or sets the current background error handler +This command either gets or sets the current background exception handler for the \fIslave\fR interpreter. If \fIcmdPrefix\fR is -absent, the current background error handler is returned, and if it is +absent, the current background exception handler is returned, and if it is present, it is a list of words (of minimum length one) that describes -what to set the interpreter's background error to. See the -\fBBACKGROUND ERROR HANDLING\fR section for more details. +what to set the interpreter's background exception handler to. See the +\fBBACKGROUND EXCEPTION HANDLING\fR section for more details. .TP \fIslave \fBeval \fIarg \fR?\fIarg ..\fR? . @@ -748,9 +798,10 @@ This option (common for all limit types) specifies (if non-empty) a Tcl script to be executed in the global namespace of the interpreter reading and writing the option when the particular limit in the limited interpreter is exceeded. The callback may modify the limit on the interpreter if it wishes the limited -interpreter to continue executing. If the callback generates an error, it is -reported through the background error mechanism (see \fBBACKGROUND ERROR -HANDLING\fR). Note that the callbacks defined by one interpreter are +interpreter to continue executing. If the callback generates an exception, it +is reported through the background exception mechanism (see +\fBBACKGROUND EXCEPTION HANDLING\fR). +Note that the callbacks defined by one interpreter are completely isolated from the callbacks defined by another, and that the order in which those callbacks are called is undefined. .TP @@ -792,21 +843,23 @@ these conditions, it should hide the \fBinterp\fR command in the child and then use aliases and the \fBinterp invokehidden\fR subcommand to provide such access as it chooses to the \fBinterp\fR command to the limited master as necessary. -.SH "BACKGROUND ERROR HANDLING" +.SH "BACKGROUND EXCEPTION HANDLING" .PP -When an error happens in a situation where it cannot be reported directly up +When an exception happens in a situation where it cannot be reported directly up the stack (e.g. when processing events in an \fBupdate\fR or \fBvwait\fR call) -the error is instead reported through the background error handling mechanism. -Every interpreter has a background error handler registered; the default error +the exception is instead reported through the background exception handling mechanism. +Every interpreter has a background exception handler registered; the default exception handler arranges for the \fBbgerror\fR command in the interpreter's global -namespace to be called, but other error handlers may be installed and process -background errors in substantially different ways. +namespace to be called, but other exception handlers may be installed and process +background exceptions in substantially different ways. .PP -A background error handler consists of a non-empty list of words to which will +A background exception handler consists of a non-empty list of words to which will be appended two further words at invocation time. The first word will be the -error message string, and the second will a dictionary of return options (this -is also the sort of information that can be obtained by trapping a normal -error using \fBcatch\fR of course.) The resulting list will then be executed +interpreter result at time of the exception, typically an error message, +and the second will be the dictionary of return options at the time of +the exception. These are the same values that \fBcatch\fR can capture +when it controls script evaluation in a non-background situation. +The resulting list will then be executed in the interpreter's global namespace without further substitutions being performed. .SH CREDITS @@ -829,8 +882,8 @@ set i [\fBinterp create\fR -safe] \fBinterp hide\fR $i lappend \fBinterp alias\fR $i lappend {} loggedLappend $i proc loggedLappend {i args} { - puts "logged invocation of lappend $args" - \fBinterp invokehidden\fR $i lappend {*}$args + puts "logged invocation of lappend $args" + \fBinterp invokehidden\fR $i lappend {*}$args } \fBinterp eval\fR $i $someUntrustedScript .CE @@ -842,14 +895,14 @@ terminates. set i [\fBinterp create\fR] \fBinterp limit\fR $i command -value 1000 \fBinterp eval\fR $i { - set x 0 - while {1} { - puts "Counting up... [incr x]" - } + set x 0 + while {1} { + puts "Counting up... [incr x]" + } } .CE .SH "SEE ALSO" -bgerror(n), load(n), safe(n), Tcl_CreateSlave(3), Tcl_Eval(3) +bgerror(n), load(n), safe(n), Tcl_CreateSlave(3), Tcl_Eval(3), Tcl_BackgroundException(3) .SH KEYWORDS alias, master interpreter, safe interpreter, slave interpreter '\"Local Variables: |