* doc/return.n: Updated [return] docs to cover new TIP 90 features.

        * doc/break.n:          Added SEE ALSO references to return.n
        * doc/continue.n:

1 files changed, 172 insertions, 59 deletions

diff --git a/doc/return.n b/doc/return.n
index 2ea381d..0bcb6da 100644
--- a/doc/return.n
+++ b/doc/return.n
@@ -1,92 +1,205 @@
 '\"
 '\" Copyright (c) 1993 The Regents of the University of California.
 '\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
+'\" Contributions from Don Porter, NIST, 2003.  (not subject to US copyright)
 '\"
 '\" 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.3 2000/09/07 14:27:51 poenitz Exp $
+'\" RCS: @(#) $Id: return.n,v 1.4 2003/09/02 16:32:12 dgp Exp $
 '\" 
 .so man.macros
-.TH return n 7.0 Tcl "Tcl Built-In Commands"
+.TH return n 8.5 Tcl "Tcl Built-In Commands"
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
-return \- Return from a procedure
+return \- Return from a procedure, or set return code of a script
 .SH SYNOPSIS
-\fBreturn \fR?\fB\-code \fIcode\fR? ?\fB\-errorinfo \fIinfo\fR? ?\fB\-errorcode\fI code\fR? ?\fIstring\fR?
+\fBreturn \fR?\fIresult\fR?
+.sp
+\fBreturn \fR?\fB-code \fIcode\fR? ?\fIresult\fR?
+.sp
+\fBreturn \fR?\fIoption value \fR...? ?\fIresult\fR?
 .BE
 
 .SH DESCRIPTION
 .PP
-Return immediately from the current procedure
-(or top-level command or \fBsource\fR command),
-with \fIstring\fR as the return value.  If \fIstring\fR is not specified then
-an empty string will be returned as result.
+In its simplest usage, the \fBreturn\fR command is used without options
+in the body of a procedure to immediately return control to the caller
+of the procedure.  If a \fIresult\fR argument is provided, its value
+becomes the result of the procedure passed back to the caller.  
+If \fIresult\fR is not specified then an empty string will be returned
+to the caller as the result of the procedure.
+.PP
+The \fBreturn\fR command serves a similar function within script
+files that are evaluated by the \fBsource\fR command.  When \fBsource\fR
+evaluates the contents of a file as a script, an invocation of
+the \fBreturn\fR command will cause script evaluation
+to immediately cease, and the value \fIresult\fR (or an empty string)
+will be returned as the result of the \fBsource\fR command.
 
-.SH "EXCEPTIONAL RETURNS"
+.SH "EXCEPTIONAL RETURN CODES"
 .PP
+In addition to the result of a procedure, the return
+code of a procedure may also be set by \fBreturn\fR
+through use of the \fB-code\fR option.
 In the usual case where the \fB\-code\fR option isn't
-specified the procedure will return normally (its completion
-code will be TCL_OK).
+specified the procedure will return normally.
 However, the \fB\-code\fR option may be used to generate an
 exceptional return from the procedure.
 \fICode\fR may have any of the following values:
-.TP 10
-\fBok\fR
-Normal return:  same as if the option is omitted.
-.TP 10
-\fBerror\fR
-Error return: same as if the \fBerror\fR command were used to
-terminate the procedure, except for handling of \fBerrorInfo\fR
-and \fBerrorCode\fR variables (see below).
-.TP 10
-\fBreturn\fR
-The current procedure will return with a completion code of
-TCL_RETURN, so that the procedure that invoked it will return
-also.
-.TP 10
-\fBbreak\fR
-The current procedure will return with a completion code of
-TCL_BREAK, which will terminate the innermost nested loop in
-the code that invoked the current procedure.
-.TP 10
-\fBcontinue\fR
-The current procedure will return with a completion code of
-TCL_CONTINUE, which will terminate the current iteration of
-the innermost nested loop in the code that invoked the current
-procedure.
-.TP 10
+.TP 13
+\fBok (or 0)\fR
+Normal return:  same as if the option is omitted.  The return code
+of the procedure is 0 (TCL_OK).
+.TP 13
+\fBerror (1)\fR
+Error return: the return code of the procedure is 1 (TCL_ERROR).
+The procedure command behaves in its calling context as if it
+were the command \fBerror \fIresult\fR.  See below for additional
+options.
+.TP 13
+\fBreturn (2)\fR
+The return code of the procedure is 2 (TCL_RETURN).  The
+procedure command behaves in its calling context as if it
+were the command \fBreturn\fR (with no arguments).
+.TP 13
+\fBbreak (3)\fR
+The return code of the procedure is 3 (TCL_BREAK).  The
+procedure command behaves in its calling context as if it
+were the command \fBbreak\fR.
+.TP 13
+\fBcontinue (4)\fR
+The return code of the procedure is 4 (TCL_CONTINUE).  The
+procedure command behaves in its calling context as if it
+were the command \fBcontinue\fR.
+.TP 13
 \fIvalue\fR
 \fIValue\fR must be an integer;  it will be returned as the
-completion code for the current procedure.
+return code for the current procedure.
 .LP
-The \fB\-code\fR option is rarely used.
-It is provided so that procedures that implement
-new control structures can reflect exceptional conditions back to
-their callers.
+When a procedure wants to signal that it has received invalid
+arguments from its caller, it may use \fBreturn -code error\fR
+with \fIresult\fR set to a suitable error message.  Otherwise
+usage of the \fBreturn -code\fR option is mostly limited to
+procedures that implement a new control structure.
+.PP
+The \fBreturn -code\fR command acts similarly within script
+files that are evaluated by the \fBsource\fR command.  During the
+evaluation of the contents of a file as a script by \fBsource\fR,
+an invocation of the \fBreturn -code \fIcode\fR command will cause
+the return code of \fBsource\fR to be \fIcode\fR.
+
+.SH "RETURN OPTIONS"
+.PP
+In addition to a result and a return code, evaluation of a command
+in Tcl also produces a dictionary of return options.  In general
+usage, all \fIoption value\fR pairs given as arguments to \fBreturn\fR
+become entries in the return options dictionary, and any values at all
+are acceptable except as noted below.  The \fBcatch\fR command may be
+used to capture all of this information -- the return code, the result,
+and the return options dictionary -- that arise from evaluation of a script.
+.PP
+As documented above, the \fB-code\fR entry in the return options dictionary
+receives special treatment by Tcl.  There are other return options also
+recognized and treated specially by Tcl.  They are:
+.TP
+\fB-errorcode \fIlist\fR
+The \fB-errorcode\fR option receives special treatment only when the value
+of the \fB-code\fR option is TCL_ERROR.  Then the \fIlist\fR value, which
+must be a valid Tcl list, is stored in the global variable \fBerrorCode\fR.
+The \fIlist\fR value is meant to be additional information about the error,
+presented as a Tcl list for further processing by programs.
+If no \fB-errorcode\fR option is provided to \fBreturn\fR when
+the \fB-code error\fR option is provided, Tcl will set the value
+of both the \fB-errorcode\fR entry in the return options dictionary and
+the global variable \fBerrorCode\fR to the default value of \fBNONE\fR.
+.TP
+\fB-errorinfo \fIinfo\fR
+The \fB-errorinfo\fR option receives special treatment only when the value
+of the \fB-code\fR option is TCL_ERROR.  Then \fIinfo\fR is the initial
+stack trace, meant to provide to a human reader additional information
+about the context in which the error occurred.  The stack trace will
+also be stored in the global variable \fBerrorInfo\fR.  
+If no \fB-errorinfo\fR option is provided to \fBreturn\fR when
+the \fB-code error\fR option is provided, Tcl will provide its own
+initial stack trace value in the entry for \fB-errorinfo\fR.  Tcl's
+initial stack trace 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 \fIinfo\fR value is supplied from
+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-level \fIlevel\fR
+The \fB-level\fR and \fB-code\fR options work together to set the return
+code to be returned by one of the commands currently being evaluated.
+The \fIlevel\fR value must be a non-negative integer representing a number
+of levels on the call stack.  It defines the number of levels up the stack
+at which the return code of command currently being evaluated should
+be \fIcode\fR.  If no \fB-level\fR option is provided, the default value
+of \fIlevel\fR is 1, so that \fBreturn\fR sets the return code that the
+current procedure returns to its caller, 1 level up the call stack.  The
+mechanism by which these options work is described in more detail below.
+.TP
+\fB-options \fIoptions\fR
+The value \fIoptions\fR must be a valid dictionary.  The entries of that
+dictionary are treated as additional \fIoption value\fR pairs for the
+\fBreturn\fR command.
+
+.SH "RETURN CODE HANDLING MECHANISMS"
+.PP
+Return codes are used in Tcl to control program flow.  A Tcl script
+is a sequence of Tcl commands.  So long as each command evaluation
+returns a return code of TCL_OK, evaluation will continue to the next
+command in the script.  Any exceptional return code (non-TCL_OK)
+returned by a command evaluation causes the flow on to the next
+command to be interrupted.  Script evaluation ceases, and the
+exceptional return code from the command becomes the return code
+of the full script evaluation.  This is the mechanism by which
+errors during script evaluation cause an interruption and unwinding
+of the call stack.  It is also the mechanism by which commands
+like \fBbreak\fR, \fBcontinue\fR, and \fBreturn\fR cause script
+evaluation to terminate without evaluating all commands in sequence.
 .PP
-Two additional options, \fB\-errorinfo\fR and \fB\-errorcode\fR,
-may be used to provide additional information during error
-returns.
-These options are ignored unless \fIcode\fR is \fBerror\fR.
+Some of Tcl's built-in commands evaluate scripts as part of their
+functioning.  These commands can make use of exceptional return
+codes to enable special features.  For example, the built-in
+Tcl commands that provide loops -- such as \fBwhile\fR, \fBfor\fR,
+and \fBforeach\fR -- evaluate a script that is the body of the
+loop.  If evaluation of the loop body returns the return code
+of TCL_BREAK or TCL_CONTINUE, the loop command can react in such
+a way as to give the \fBbreak\fR and \fBcontinue\fR commands
+their documented interpretation in loops.
 .PP
-The \fB\-errorinfo\fR option specifies an initial stack
-trace for the \fBerrorInfo\fR variable;  if it is not specified then
-the stack trace left in \fBerrorInfo\fR will include the call to
-the procedure and higher levels on the stack but it will not include
-any information about the context of the error within the procedure.
-Typically the \fIinfo\fR value is supplied from the value left
-in \fBerrorInfo\fR after a \fBcatch\fR command trapped an error within
-the procedure.
+Procedure invocation also involves evaluation of a script, the body
+of the procedure.  Procedure invocation provides special treatment
+when evaluation of the procedure body returns the return code 
+TCL_RETURN.  In that circumstance, the \fB-level\fR entry in the
+return options dictionary is decremented.  If after decrementing,
+the value of the \fB-level\fR entry is 0, then the value of
+the \fB-code\fR entry becomes the return code of the procedure.
+If after decrementing, the value of the \fB-level\fR entry is
+greater than zero, then the return code of the procedure is
+TCL_RETURN.  If the procedure invocation occurred during the
+evaluation of the body of another procedure, the process will
+repeat itself up the call stack, decrementing the value of the
+\fB-level\fR entry at each level, so that the \fIcode\fR will
+be the return code of the current command \fIlevel\fR levels
+up the call stack.
 .PP
-If the \fB\-errorcode\fR option is specified then \fIcode\fR provides
-a value for the \fBerrorCode\fR variable.
-If the option is not specified then \fBerrorCode\fR will
-default to \fBNONE\fR.
+The return code of the \fBreturn\fR command itself triggers this
+special handling by procedure invocation.  If \fBreturn\fR
+is provided the option \fB-level 0\fR, then the return code
+of the \fBreturn\fR command itself will be the value \fIcode\fR
+of the \fB-code\fR option (or TCL_OK by default).  Any other value
+for the \fB-level\fR option (including the default value of 1)
+will cause the return code of the \fBreturn\fR command itself
+to be TCL_RETURN, triggering a return from the enclosing procedure.
 
 .SH "SEE ALSO"
-break(n), continue(n), error(n), proc(n)
+break(n), catch(n), continue(n), dict(n), error(n), proc(n), source(n), tclvars(n)
 
 .SH KEYWORDS
-break, continue, error, procedure, return
+break, catch, continue, error, procedure, return