summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
-rw-r--r--doc/return.n12
1 files changed, 11 insertions, 1 deletions
diff --git a/doc/return.n b/doc/return.n
index bd9592f..55ddf96 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.7 2003/09/02 21:49:42 dgp Exp $
+'\" RCS: @(#) $Id: return.n,v 1.8 2003/09/03 16:24:31 dgp Exp $
'\"
.so man.macros
.TH return n 8.5 Tcl "Tcl Built-In Commands"
@@ -92,6 +92,7 @@ the return code of \fBsource\fR to be \fIcode\fR.
.SH "RETURN OPTIONS"
.PP
+.VS 8.5
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
@@ -99,6 +100,7 @@ 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.
+.VE 8.5
.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
@@ -133,6 +135,7 @@ by the \fBcatch\fR command (or from the copy of that information
stored in the global variable \fBerrorInfo\fR).
.TP
\fB-level \fIlevel\fR
+.VS 8.5
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
@@ -142,11 +145,14 @@ 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.
+.VE 8.5
.TP
\fB-options \fIoptions\fR
+.VS 8.5
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.
+.VE 8.5
.SH "RETURN CODE HANDLING MECHANISMS"
.PP
@@ -173,6 +179,7 @@ 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
+.VS 8.5
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
@@ -200,6 +207,7 @@ 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.
+.VE 8.5
.SH EXAMPLES
@@ -257,6 +265,7 @@ proc myBreak {} {
}
.CE
+.VS 8.5
With the \fB-level 0\fR option, \fBreturn\fR itself can serve
as a replacement for \fBbreak\fR.
@@ -295,6 +304,7 @@ proc myReturn {args} {
return -options $options $result
}
.CE
+.VE 8.5
.SH "SEE ALSO"
break(n), catch(n), continue(n), dict(n), error(n), proc(n), source(n), tclvars(n)