diff options
author | William Joye <wjoye@cfa.harvard.edu> | 2018-12-25 19:56:49 (GMT) |
---|---|---|
committer | William Joye <wjoye@cfa.harvard.edu> | 2018-12-25 19:56:49 (GMT) |
commit | d5a4b3667e9d26b9c13905ccb51021d13ce87c58 (patch) | |
tree | fc0f3692516c8c3e8090df20223d342a1b64df93 /tcl8.6/doc/subst.n | |
parent | ff51550ee89b473c63df78de6b2a413f21105687 (diff) | |
download | blt-d5a4b3667e9d26b9c13905ccb51021d13ce87c58.zip blt-d5a4b3667e9d26b9c13905ccb51021d13ce87c58.tar.gz blt-d5a4b3667e9d26b9c13905ccb51021d13ce87c58.tar.bz2 |
update tcl/tk
Diffstat (limited to 'tcl8.6/doc/subst.n')
-rw-r--r-- | tcl8.6/doc/subst.n | 164 |
1 files changed, 164 insertions, 0 deletions
diff --git a/tcl8.6/doc/subst.n b/tcl8.6/doc/subst.n new file mode 100644 index 0000000..4518140 --- /dev/null +++ b/tcl8.6/doc/subst.n @@ -0,0 +1,164 @@ +'\" +'\" 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. +'\" +.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 +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, +and backslash substitutions on its \fIstring\fR argument and +returns the fully-substituted result. +The substitutions are performed in exactly the same way as for +Tcl commands. +As a result, the \fIstring\fR argument is actually substituted twice, +once by the Tcl parser in the usual fashion for Tcl commands, and +again by the \fIsubst\fR command. +.PP +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, command substitution +is not performed: open and close brackets are treated as ordinary characters +with no special interpretation. +.PP +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 +proc b {} {return c} +array set a {c c [b] tricky} +\fBsubst\fR -nocommands {[b] $a([b])} +.CE +.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, quoting, substitution, variable substitution +.\" Local Variables: +.\" mode: nroff +.\" End: |