diff options
| -rw-r--r-- | ChangeLog | 6 | ||||
| -rw-r--r-- | doc/subst.n | 60 |
2 files changed, 57 insertions, 9 deletions
@@ -1,3 +1,9 @@ +2002-04-18 Don Porter <dgp@users.sourceforge.net> + + * doc/subst.n: Clarified documentation on handling unusual return + codes during substitution, and on variable substitutions implied + by command substitution, and vice versa. [Bug 536838] + 2002-04-18 Donal K. Fellows <fellowsd@cs.man.ac.uk> * generic/tclCmdIL.c (InfoBodyCmd): diff --git a/doc/subst.n b/doc/subst.n index b76a70c..829b077 100644 --- a/doc/subst.n +++ b/doc/subst.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: subst.n,v 1.4 2001/07/12 13:15:09 dkf Exp $ +'\" RCS: @(#) $Id: subst.n,v 1.5 2002/04/18 16:31:40 dgp Exp $ '\" .so man.macros .TH subst n 7.4 Tcl "Tcl Built-In Commands" @@ -32,17 +32,33 @@ again by the \fIsubst\fR command. If any of the \fB\-nobackslashes\fR, \fB\-nocommands\fR, or \fB\-novariables\fR are specified, then the corresponding substitutions are not performed. -For example, if \fB\-nocommands\fR is specified, no command substitution -is performed: open and close brackets are treated as ordinary characters +For example, if \fB\-nocommands\fR is specified, command substitution +is not performed: open and close brackets are treated as ordinary characters with no special interpretation. .PP .VS 8.4 -If a break exception occurs during the evaluation of a command -substitution, the result of the substitution will be the string (as -substituted) up to the start of the command substitution. If a -continue exception occurs during the evaluation of a command -substitution, an empty string will be substituted for that entire -command substitution (as long as it is well-formed Tcl.) +Note that the substitution of one kind can include substitution of +other kinds. For example, even when the \fB-novariables\fR option +is specified, command substitution is performed without restriction. +This means that any variable substitution necessary to complete the +command substitution will still take place. Likewise, any command +substitution necessary to complete a variable substitution will +take place, even when \fB-nocommands\fR is specified. See the +EXAMPLES below. +.PP +If an error occurs during substitution, then \fBsubst\fR will return +that error. If a break exception occurs during command or variable +substitution, the result of the whole substitution will be the +string (as substituted) up to the start of the substitution that +raised the exception. If a continue exception occurs during the +evaluation of a command or variable substitution, an empty string +will be substituted for that entire command or variable substitution +(as long as it is well-formed Tcl.) If a return exception occurs, +or any other return code is returned during command or variable +substitution, then the returned value is substituted for that +substitution. See the EXAMPLES below. In this way, all exceptional +return codes are ``caught'' by \fBsubst\fR. The \fBsubst\fR command +itself will either return an error, or will complete successfully. .VE .SH EXAMPLES .PP @@ -62,6 +78,22 @@ subst {xyz {$a}}\fR .CE return ``\fBxyz {p} q {r}\fR'', not ``\fBxyz {p\\} q \\{r}\fR''. .PP +When command substitution is performed, it includes any variable +substitution necessary to evaluate the script. +.CS +\fBset a 44 +subst -novariables {$a [format $a]}\fR +.CE +returns ``\fB$a 44\fR'', not ``\fB$a $a\fR''. Similarly, when +variable substitution is performed, it includes any command +substitution necessary to retrieve the value of the variable. +.CS +\fBproc b {} {return c} +array set a {c c [b] tricky} +subst -nocommands {[b] $a([b])}\fR +.CE +returns ``\fB[b] c\fR'', not ``\fB[b] tricky\fR''. +.PP The continue and break exceptions allow command substitutions to prevent substitution of the rest of the command substitution and the rest of \fIstring\fR respectively, giving script authors more options @@ -74,6 +106,16 @@ returns ``\fBabc,\fR'', not ``\fBabc,,def\fR'' and the script \fBsubst {abc,[continue;expr 1+2],def}\fR .CE returns ``\fBabc,,def\fR'', not ``\fBabc,3,def\fR''. +.PP +Other exceptional return codes substitute the returned value +.CS +\fBsubst {abc,[return foo;expr 1+2],def}\fR +.CE +returns ``\fBabc,foo,def\fR'', not ``\fBabc,3,def\fR'' and +.CS +\fBsubst {abc,[return -code 10 foo;expr 1+2],def}\fR +.CE +also returns ``\fBabc,foo,def\fR'', not ``\fBabc,3,def\fR''. .VE .SH "SEE ALSO" |