diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/catch.n | 48 | ||||
| -rw-r--r-- | doc/info.n | 12 | ||||
| -rw-r--r-- | doc/return.n | 18 |
3 files changed, 59 insertions, 19 deletions
diff --git a/doc/catch.n b/doc/catch.n index a21fabd..1efb082 100644 --- a/doc/catch.n +++ b/doc/catch.n @@ -6,7 +6,7 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: catch.n,v 1.23 2010/01/13 12:08:30 dkf Exp $ +'\" RCS: @(#) $Id: catch.n,v 1.24 2010/04/05 19:44:45 ferrieux Exp $ '\" .so man.macros .TH catch n "8.5" Tcl "Tcl Built-In Commands" @@ -54,22 +54,36 @@ Only when the return code is \fBTCL_RETURN\fR will the values of the \fB\-level\fR and \fB\-code\fR entries be something else, as further described in the documentation for the \fBreturn\fR command. .PP -When the return code from evaluation of \fIscript\fR is \fBTCL_ERROR\fR, -three additional entries are defined in the dictionary of return options -stored in \fIoptionsVarName\fR: \fB\-errorinfo\fR, \fB\-errorcode\fR, -and \fB\-errorline\fR. The value of the \fB\-errorinfo\fR entry -is a formatted stack trace containing more information about -the context in which the error happened. The formatted stack -trace is meant to be read by a person. The value of -the \fB\-errorcode\fR entry is additional information about the -error stored as a list. The \fB\-errorcode\fR value is meant to -be further processed by programs, and may not be particularly -readable by people. The value of the \fB\-errorline\fR entry -is an integer indicating which line of \fIscript\fR was being -evaluated when the error occurred. The values of the \fB\-errorinfo\fR -and \fB\-errorcode\fR entries of the most recent error are also -available as values of the global variables \fB::errorInfo\fR -and \fB::errorCode\fR respectively. +When the return code from evaluation of \fIscript\fR is +\fBTCL_ERROR\fR, four additional entries are defined in the dictionary +of return options stored in \fIoptionsVarName\fR: \fB\-errorinfo\fR, +\fB\-errorcode\fR, \fB\-errorline\fR, and \fB\-errorstack\fR. The +value of the \fB\-errorinfo\fR entry is a formatted stack trace +containing more information about the context in which the error +happened. The formatted stack trace is meant to be read by a person. +The value of the \fB\-errorcode\fR entry is additional information +about the error stored as a list. The \fB\-errorcode\fR value is +meant to be further processed by programs, and may not be particularly +readable by people. The value of the \fB\-errorline\fR entry is an +integer indicating which line of \fIscript\fR was being evaluated when +the error occurred. The value of the \fB\-errorstack\fR entry is an +even-sized list made of token-parameter pairs accumulated while +unwinding the stack. The token may be "CALL", in which case the +parameter is a list made of the proc name and arguments at the +corresponding level; or it may be "UP", in which case the parameter is +the relative [uplevel] of the previous CALL. The salient differences +wrt -errorinfo are that (1) it is a machine-readable form amenable to +[foreach {tok prm} ...], (2) it contains the true (substituted) values +passed to the functions, instead of the static text of the calling +sites, and (3) it is coarser-grained, with only one element per stack +frame (like procs; no separate elements for [foreach] constructs for +example). + +The values of the \fB\-errorinfo\fR and \fB\-errorcode\fR entries of +the most recent error are also available as values of the global +variables \fB::errorInfo\fR and \fB::errorCode\fR respectively. The +value of the \fB\-errorstack\fR entry surfaces as \fBinfo +errorstack\fR. .PP Tcl packages may provide commands that set other entries in the dictionary of return options, and the \fBreturn\fR command may be @@ -8,7 +8,7 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: info.n,v 1.36 2010/03/24 13:21:11 dkf Exp $ +'\" RCS: @(#) $Id: info.n,v 1.37 2010/04/05 19:44:45 ferrieux Exp $ '\" .so man.macros .TH info n 8.4 Tcl "Tcl Built-In Commands" @@ -94,6 +94,16 @@ does not have a default value then the command returns \fB0\fR. Otherwise it returns \fB1\fR and places the default value of \fIarg\fR into variable \fIvarname\fR. .TP +\fBinfo errorstack \fR?\fIinterp\fR? +. +Returns a list of lists made of the function names and arguments at +each level from the call stack of the last error in the given +\fIinterp\fR, or in the current one if not specified. This +information is also present in the -errorstack entry of the options +dictionary returned by 3-arg \fBcatch\fR; \fBinfo errorstack\fR is a +convenient way of retrieving it for uncaught errors at toplevel in an +interactive tclsh. +.TP \fBinfo exists \fIvarName\fR . Returns \fB1\fR if the variable named \fIvarName\fR exists in the diff --git a/doc/return.n b/doc/return.n index 4f77135..8d0d96c 100644 --- a/doc/return.n +++ b/doc/return.n @@ -6,7 +6,7 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: return.n,v 1.25 2010/01/20 13:42:17 dkf Exp $ +'\" RCS: @(#) $Id: return.n,v 1.26 2010/04/05 19:44:45 ferrieux Exp $ '\" .so man.macros .TH return n 8.5 Tcl "Tcl Built-In Commands" @@ -138,6 +138,22 @@ the value of \fB\-errorinfo\fR in a return options dictionary captured by the \fBcatch\fR command (or from the copy of that information stored in the global variable \fBerrorInfo\fR). .TP +\fB\-errorstack \fIlist\fR +. +The \fB\-errorstack\fR option receives special treatment only when the value +of the \fB\-code\fR option is \fBTCL_ERROR\fR. Then \fIlist\fR is the initial +error stack, recording actual argument values passed to each proc level. The error stack will +also be reachable through [info errorstack]. +If no \fB\-errorstack\fR option is provided to \fBreturn\fR when +the \fB\-code error\fR option is provided, Tcl will provide its own +initial error stack in the entry for \fB\-errorstack\fR. Tcl's +initial error stack will include only the call to the procedure, and +stack unwinding will append information about higher stack levels, but +there will be no information about the context of the error within +the procedure. Typically the \fIlist\fR value is supplied from +the value of \fB\-errorstack\fR in a return options dictionary captured +by the \fBcatch\fR command (or from the copy of that information from [info errorstack]). +.TP \fB\-level \fIlevel\fR . The \fB\-level\fR and \fB\-code\fR options work together to set the return |