diff options
Diffstat (limited to 'doc/subst.n')
| -rw-r--r-- | doc/subst.n | 144 |
1 files changed, 130 insertions, 14 deletions
diff --git a/doc/subst.n b/doc/subst.n index 7a19b91..990b9d3 100644 --- a/doc/subst.n +++ b/doc/subst.n @@ -1,14 +1,13 @@ '\" '\" Copyright (c) 1994 The Regents of the University of California. '\" Copyright (c) 1994-1996 Sun Microsystems, Inc. +'\" Copyright (c) 2001 Donal K. Fellows '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" SCCS: @(#) subst.n 1.9 96/03/25 20:24:17 -'\" -.so man.macros .TH subst n 7.4 Tcl "Tcl Built-In Commands" +.so man.macros .BS '\" Note: do not modify the .SH NAME line immediately below! .SH NAME @@ -16,7 +15,6 @@ subst \- Perform backslash, command, and variable substitutions .SH SYNOPSIS \fBsubst \fR?\fB\-nobackslashes\fR? ?\fB\-nocommands\fR? ?\fB\-novariables\fR? \fIstring\fR .BE - .SH DESCRIPTION .PP This command performs variable substitutions, command substitutions, @@ -31,18 +29,136 @@ 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 -Note: when it performs its substitutions, \fIsubst\fR does not -give any special treatment to double quotes or curly braces. For -example, the script +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 +\fBEXAMPLES\fR 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 \fBEXAMPLES\fR below. In this way, all exceptional +return codes are +.QW caught +by \fBsubst\fR. The \fBsubst\fR command +itself will either return an error, or will complete successfully. +.SH EXAMPLES +.PP +When it performs its substitutions, \fIsubst\fR does not give any +special treatment to double quotes or curly braces (except within +command substitutions) so the script +.PP +.CS +set a 44 +\fBsubst\fR {xyz {$a}} +.CE +.PP +returns +.QW "\fBxyz {44}\fR" , +not +.QW "\fBxyz {$a}\fR" +and the script +.PP +.CS +set a "p\e} q \e{r" +\fBsubst\fR {xyz {$a}} +.CE +.PP +returns +.QW "\fBxyz {p} q {r}\fR" , +not +.QW "\fBxyz {p\e} q \e{r}\fR". +.PP +When command substitution is performed, it includes any variable +substitution necessary to evaluate the script. +.PP +.CS +set a 44 +\fBsubst\fR -novariables {$a [format $a]} +.CE +.PP +returns +.QW "\fB$a 44\fR" , +not +.QW "\fB$a $a\fR" . +Similarly, when +variable substitution is performed, it includes any command +substitution necessary to retrieve the value of the variable. +.PP .CS -\fBset a 44 -subst {xyz {$a}}\fR +proc b {} {return c} +array set a {c c [b] tricky} +\fBsubst\fR -nocommands {[b] $a([b])} .CE -returns ``\fBxyz {44}\fR'', not ``\fBxyz {$a}\fR''. - +.PP +returns +.QW "\fB[b] c\fR" , +not +.QW "\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 +when processing text using \fIsubst\fR. For example, the script +.PP +.CS +\fBsubst\fR {abc,[break],def} +.CE +.PP +returns +.QW \fBabc,\fR , +not +.QW \fBabc,,def\fR +and the script +.PP +.CS +\fBsubst\fR {abc,[continue;expr {1+2}],def} +.CE +.PP +returns +.QW \fBabc,,def\fR , +not +.QW \fBabc,3,def\fR . +.PP +Other exceptional return codes substitute the returned value +.PP +.CS +\fBsubst\fR {abc,[return foo;expr {1+2}],def} +.CE +.PP +returns +.QW \fBabc,foo,def\fR , +not +.QW \fBabc,3,def\fR +and +.PP +.CS +\fBsubst\fR {abc,[return -code 10 foo;expr {1+2}],def} +.CE +.PP +also returns +.QW \fBabc,foo,def\fR , +not +.QW \fBabc,3,def\fR . +.SH "SEE ALSO" +Tcl(n), eval(n), break(n), continue(n) .SH KEYWORDS -backslash substitution, command substitution, variable substitution +backslash substitution, command substitution, quoting, substitution, variable substitution +.\" Local Variables: +.\" mode: nroff +.\" End: |