TIP #348 IMPLEMENTATION - Substituted error stack

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
diff --git a/doc/info.n b/doc/info.n
index 246b83f..3076274 100644
--- a/doc/info.n
+++ b/doc/info.n
@@ -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