diff options
| -rw-r--r-- | ChangeLog | 7 | ||||
| -rw-r--r-- | doc/break.n | 4 | ||||
| -rw-r--r-- | doc/continue.n | 4 | ||||
| -rw-r--r-- | doc/return.n | 231 |
4 files changed, 183 insertions, 63 deletions
@@ -1,3 +1,10 @@ +2003-08-31 Don Porter <dgp@users.sourceforge.net> + + * 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: + 2003-09-01 Donal K. Fellows <fellowsd@cs.man.ac.uk> * doc/Namespace.3: Basic documentation for the TIP#139 functions. diff --git a/doc/break.n b/doc/break.n index 32432eb..3b71c71 100644 --- a/doc/break.n +++ b/doc/break.n @@ -5,7 +5,7 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: break.n,v 1.3 2000/09/07 14:27:46 poenitz Exp $ +'\" RCS: @(#) $Id: break.n,v 1.4 2003/09/02 16:32:12 dgp Exp $ '\" .so man.macros .TH break n "" Tcl "Tcl Built-In Commands" @@ -31,7 +31,7 @@ as the \fBcatch\fR command, Tk event bindings, and the outermost scripts of procedure bodies. .SH "SEE ALSO" -catch(n), continue(n), for(n), foreach(n), while(n) +catch(n), continue(n), for(n), foreach(n), return(n), while(n) .SH KEYWORDS abort, break, loop diff --git a/doc/continue.n b/doc/continue.n index 698f9c9..0771831 100644 --- a/doc/continue.n +++ b/doc/continue.n @@ -5,7 +5,7 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: continue.n,v 1.3 2000/09/07 14:27:46 poenitz Exp $ +'\" RCS: @(#) $Id: continue.n,v 1.4 2003/09/02 16:32:12 dgp Exp $ '\" .so man.macros .TH continue n "" Tcl "Tcl Built-In Commands" @@ -31,7 +31,7 @@ as the \fBcatch\fR command and the outermost scripts of procedure bodies. .SH "SEE ALSO" -break(n), for(n), foreach(n), while(n) +break(n), for(n), foreach(n), return(n), while(n) .SH KEYWORDS continue, iteration, loop 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 |