diff options
| -rw-r--r-- | doc/return.n | 12 |
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) |