summaryrefslogtreecommitdiffstats
path: root/doc/return.n
diff options
context:
space:
mode:
authordgp <dgp@users.sourceforge.net>2003-09-02 16:32:11 (GMT)
committerdgp <dgp@users.sourceforge.net>2003-09-02 16:32:11 (GMT)
commit1a883a5ff1a71ad3f73f9614fbb8b08b9e9271bb (patch)
treec5bbf3532bf88507889b412039c56cfb2a6609ba /doc/return.n
parente44ec783aff444ef9801fe5fd69decc876a89b8c (diff)
downloadtcl-1a883a5ff1a71ad3f73f9614fbb8b08b9e9271bb.zip
tcl-1a883a5ff1a71ad3f73f9614fbb8b08b9e9271bb.tar.gz
tcl-1a883a5ff1a71ad3f73f9614fbb8b08b9e9271bb.tar.bz2
* 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:
Diffstat (limited to 'doc/return.n')
-rw-r--r--doc/return.n231
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