TIP#36 implementation. Also includes cleanup for subst option

handling and improved documentation for the subst command (in my
capacity as maintainer of the Commands M-Z functional area.)

2 files changed, 109 insertions, 6 deletions

diff --git a/doc/SubstObj.3 b/doc/SubstObj.3
new file mode 100644
index 0000000..c90cbca
--- /dev/null
+++ b/doc/SubstObj.3
@@ -0,0 +1,71 @@
+'\"
+'\" 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.
+'\" 
+'\" RCS: @(#) $Id: SubstObj.3,v 1.1 2001/07/12 13:15:09 dkf Exp $
+'\" 
+.so man.macros
+.TH Tcl_SubstObj 3 8.4 Tcl "Tcl Library Procedures"
+.BS
+.SH NAME
+Tcl_SubstObj \- perform substitutions on Tcl objects
+.SH SYNOPSIS
+.nf
+\fB#include <tcl.h>\fR
+.sp
+Tcl_Obj *
+\fBTcl_SubstObj\fR(\fIinterp, objPtr, flags\fR)
+.SH ARGUMENTS
+.AS Tcl_Interp **termPtr;
+.AP Tcl_Interp *interp in
+Interpreter in which to execute Tcl scripts and lookup variables.  If
+an error occurs, the interpreter's result is modified to hold an error
+message.
+.AP Tcl_Obj *objPtr in
+A Tcl object containing the string to perform substitutions on.
+.AP int flags in
+ORed combination of flag bits that specify which substitutions to
+perform.  The flags \fBTCL_SUBST_COMMANDS\fR,
+\fBTCL_SUBST_VARIABLES\fR and \fBTCL_SUBST_BACKSLASHES\fR are
+currently supported, and \fBTCL_SUBST_ALL\fR is provided as a
+convenience for the common case where all substitutions are desired.
+.BE
+
+.SH DESCRIPTION
+.PP
+The \fBTcl_SubstObj\fR function is used to perform substitutions on
+strings in the fashion of the \fBsubst\fR command.  It gets the value
+of the string contained in \fIobjPtr\fR and scans it, copying
+characters and performing the chosen substitutions as it goes to an
+output object which is returned as the result of the function.  In the
+event of an error occurring during the execution of a command or
+variable substitution, the function returns NULL and an error message
+is left in \fIinterp\fR's result.
+.PP
+Three kinds of substitutions are supported.  When the
+\fBTCL_SUBST_BACKSLASHES\fR bit is set in \fIflags\fR, sequences that
+look like backslash substitutions for Tcl commands are replaced by
+their corresponding character.
+.PP
+When the \fBTCL_SUBST_VARIABLES\fR bit is set in \fIflags\fR,
+sequences that look like variable substitutions for Tcl commands are
+replaced by the contents of the named variable.
+.PP
+When th \fBTCL_SUBST_COMMANDS\fR bit is set in \fIflags\fR, sequences
+that look like command substitutions for Tcl commands are replaced by
+the result of evaluating that script.  Where an uncaught continue
+exception occurs during the evaluation of a command substitution, an
+empty string is substituted for the command.  Where an uncaught break
+exception occurs during the evaluation of a command substitution, the
+result of the whole substitution on \fIobjPtr\fR will be truncated at
+the point immediately before the start of the command substitution,
+and no characters will be added to the result or substitutions
+performed after that point.
+
+.SH "SEE ALSO"
+subst(n)
+
+.SH KEYWORDS
+backslash substitution, command substitution, variable substitution
diff --git a/doc/subst.n b/doc/subst.n
index 36884eb..b76a70c 100644
--- a/doc/subst.n
+++ b/doc/subst.n
@@ -1,11 +1,12 @@
 '\"
 '\" 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.
 '\" 
-'\" RCS: @(#) $Id: subst.n,v 1.3 2000/09/07 14:27:51 poenitz Exp $
+'\" RCS: @(#) $Id: subst.n,v 1.4 2001/07/12 13:15:09 dkf Exp $
 '\" 
 .so man.macros
 .TH subst n 7.4 Tcl "Tcl Built-In Commands"
@@ -35,17 +36,48 @@ For example, if \fB\-nocommands\fR is specified, no command substitution
 is 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
+.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.)
+.VE
+.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
 .CS
 \fBset a 44
 subst {xyz {$a}}\fR
 .CE
-returns ``\fBxyz {44}\fR'', not ``\fBxyz {$a}\fR''.
+returns ``\fBxyz {44}\fR'', not ``\fBxyz {$a}\fR''
+.VS 8.4
+and the script
+.CS
+\fBset a "p\\} q \\{r"
+subst {xyz {$a}}\fR
+.CE
+return ``\fBxyz {p} q {r}\fR'', not ``\fBxyz {p\\} q \\{r}\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
+.CS
+\fBsubst {abc,[break],def}\fR
+.CE
+returns ``\fBabc,\fR'', not ``\fBabc,,def\fR'' and the script
+.CS
+\fBsubst {abc,[continue;expr 1+2],def}\fR
+.CE
+returns ``\fBabc,,def\fR'', not ``\fBabc,3,def\fR''.
+.VE
 
 .SH "SEE ALSO"
-eval(n)
+Tcl(n), eval(n), break(n), continue(n)
 
 .SH KEYWORDS
 backslash substitution, command substitution, variable substitution