summaryrefslogtreecommitdiffstats
path: root/doc
diff options
context:
space:
mode:
authordgp <dgp@users.sourceforge.net>2003-11-14 20:44:43 (GMT)
committerdgp <dgp@users.sourceforge.net>2003-11-14 20:44:43 (GMT)
commit17f540b256d78b8a6fc8bd9121a633dac6c23b19 (patch)
tree1abdc7a020d4095171e8cb7f16def9be025cb664 /doc
parentf745c9aa31bbdf8f71589fa25d30ce50cad94652 (diff)
downloadtcl-17f540b256d78b8a6fc8bd9121a633dac6c23b19.zip
tcl-17f540b256d78b8a6fc8bd9121a633dac6c23b19.tar.gz
tcl-17f540b256d78b8a6fc8bd9121a633dac6c23b19.tar.bz2
* doc/ParseCmd.3: Implementation of TIP 157. Adds recognition
* doc/Tcl.n: of the new leading {expand} syntax on words. * generic/tcl.h: Parses such words as the new Tcl_Token type * generic/tclBasic.c: TCL_TOKEN_EXPAND_WORD. Updated Tcl_EvalEx * generic/tclCompile.c: and the bytecode compiler/execution engine * generic/tclCompile.h: to recognize the new token type. New opcodes * generic/tclExecute.c: INST_LIST_VERIFY and INST_INVOKE_EXP and a new * generic/tclParse.c: operand type OPERAND_ULIST1 are defined. Docs * generic/tclTest.c: and tests are included. * tests/basic.test: * tests/compile.test: * tests/parse.test: * library/auto.tcl: Replaced several [eval]s used to perform * library/package.tcl: argument expansion with the new syntax. * library/safe.tcl: In the test files lindex.test and lset.test, * tests/cmdInfo.test: replaced use of [eval] to force direct * tests/encoding.test: string evaluation with use of [testevalex] * tests/execute.test: which more directly and robustly serves the * tests/fCmd.test: same purpose. * tests/http.test: * tests/init.test: * tests/interp.test: * tests/io.test: * tests/ioUtil.test: * tests/iogt.test: * tests/lindex.test: * tests/lset.test: * tests/namespace-old.test: * tests/namespace.test: * tests/pkg.test: * tests/pkgMkIndex.test: * tests/proc.test: * tests/reg.test: * tests/trace.test: * tests/upvar.test: * tests/winConsole.test: * tests/winFCmd.test:
Diffstat (limited to 'doc')
-rw-r--r--doc/ParseCmd.320
-rw-r--r--doc/Tcl.n30
2 files changed, 37 insertions, 13 deletions
diff --git a/doc/ParseCmd.3 b/doc/ParseCmd.3
index 34826d9..aa243d2 100644
--- a/doc/ParseCmd.3
+++ b/doc/ParseCmd.3
@@ -4,7 +4,7 @@
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\"
-'\" RCS: @(#) $Id: ParseCmd.3,v 1.11 2003/03/19 20:07:17 dgp Exp $
+'\" RCS: @(#) $Id: ParseCmd.3,v 1.12 2003/11/14 20:44:43 dgp Exp $
'\"
.so man.macros
.TH Tcl_ParseCommand 3 8.3 Tcl "Tcl Library Procedures"
@@ -286,6 +286,16 @@ of \fBTCL_TOKEN_VARIABLE\fR and \fBTCL_TOKEN_BS\fR tokens.
This token has the same meaning as \fBTCL_TOKEN_WORD\fR, except that
the word is guaranteed to consist of a single \fBTCL_TOKEN_TEXT\fR
sub-token. The \fInumComponents\fR field is always 1.
+.VS 8.5
+.TP
+\fBTCL_TOKEN_EXPAND_WORD\fR
+This token has the same meaning as \fBTCL_TOKEN_WORD\fR, except that
+the command parser notes this word began with the expansion
+prefix \fB{expand}\fR, indicating that after substitution,
+the list value of this word should be expanded to form multiple
+arguments in command evaluation. This
+token type can only be created by Tcl_ParseCommand.
+.VE
.TP
\fBTCL_TOKEN_TEXT\fR
The token describes a range of literal text that is part of a word.
@@ -375,12 +385,16 @@ is always 0.
After \fBTcl_ParseCommand\fR returns, the first token pointed to by
the \fItokenPtr\fR field of the
Tcl_Parse structure always has type \fBTCL_TOKEN_WORD\fR or
-\fBTCL_TOKEN_SIMPLE_WORD\fR. It is followed by the sub-tokens
+.VS 8.5
+\fBTCL_TOKEN_SIMPLE_WORD\fR or \fBTCL_TOKEN_EXPAND_WORD\fR.
+It is followed by the sub-tokens
that must be concatenated to produce the value of that word.
The next token is the \fBTCL_TOKEN_WORD\fR or \fBTCL_TOKEN_SIMPLE_WORD\fR
-token for the second word, followed by sub-tokens for that
+of \fBTCL_TOKEN_EXPAND_WORD\fR token for the second word,
+followed by sub-tokens for that
word, and so on until all \fInumWords\fR have been accounted
for.
+.VE 8.5
.PP
After \fBTcl_ParseExpr\fR returns, the first token pointed to by
the \fItokenPtr\fR field of the
diff --git a/doc/Tcl.n b/doc/Tcl.n
index af6bd69..b1c8f6c 100644
--- a/doc/Tcl.n
+++ b/doc/Tcl.n
@@ -5,7 +5,7 @@
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\"
-'\" RCS: @(#) $Id: Tcl.n,v 1.9 2003/02/01 19:48:23 kennykb Exp $
+'\" RCS: @(#) $Id: Tcl.n,v 1.10 2003/11/14 20:44:43 dgp Exp $
'\"
.so man.macros
.TH Tcl n "8.1" Tcl "Tcl Built-In Commands"
@@ -49,8 +49,17 @@ as ordinary characters and included in the word.
Command substitution, variable substitution, and backslash substitution
are performed on the characters between the quotes as described below.
The double-quotes are not retained as part of the word.
-.IP "[5] \fBBraces.\fR"
-If the first character of a word is an open brace (``{'') then
+.IP "[5] \fBArgument expansion.\fR"
+If a word starts with the string ``{expand}'' followed by a
+non-whitespace character, then the leading ``{expand}'' is removed
+and the rest of the word is parsed and substituted as any other other
+word. After substitution, the word is parsed again without
+substitutions, and its words are added to the command being
+substituted. For instance, ``cmd a {expand}{b c} d {expand}{e f}'' is
+equivalent to ``cmd a b c d e f''.
+.IP "[6] \fBBraces.\fR"
+If the first character of a word is an open brace (``{'') and
+rule [5] does not apply, then
the word is terminated by the matching close brace (``}'').
Braces nest within the word: for each additional open
brace there must be an additional close brace (however,
@@ -63,7 +72,7 @@ below, nor do semi-colons, newlines, close brackets,
or white space receive any special interpretation.
The word will consist of exactly the characters between the
outer braces, not including the braces themselves.
-.IP "[6] \fBCommand substitution.\fR"
+.IP "[7] \fBCommand substitution.\fR"
If a word contains an open bracket (``['') then Tcl performs
\fIcommand substitution\fR.
To do this it invokes the Tcl interpreter recursively to process
@@ -75,7 +84,7 @@ substituted into the word in place of the brackets and all of the
characters between them.
There may be any number of command substitutions in a single word.
Command substitution is not performed on words enclosed in braces.
-.IP "[7] \fBVariable substitution.\fR"
+.IP "[8] \fBVariable substitution.\fR"
If a word contains a dollar-sign (``$'') then Tcl performs \fIvariable
substitution\fR: the dollar-sign and the following characters are
replaced in the word by the value of a variable.
@@ -102,7 +111,7 @@ characters whatsoever except for close braces.
There may be any number of variable substitutions in a single word.
Variable substitution is not performed on words enclosed in braces.
.RE
-.IP "[8] \fBBackslash substitution.\fR"
+.IP "[9] \fBBackslash substitution.\fR"
If a backslash (``\e'') appears within a word then
\fIbackslash substitution\fR occurs.
In all cases but those described below the backslash is dropped and
@@ -173,14 +182,14 @@ inserted.
Backslash substitution is not performed on words enclosed in braces,
except for backslash-newline as described above.
.RE
-.IP "[9] \fBComments.\fR"
+.IP "[10] \fBComments.\fR"
If a hash character (``#'') appears at a point where Tcl is
expecting the first character of the first word of a command,
then the hash character and the characters that follow it, up
through the next newline, are treated as a comment and ignored.
The comment character only has significance when it appears
at the beginning of a command.
-.IP "[10] \fBOrder of substitution.\fR"
+.IP "[11] \fBOrder of substitution.\fR"
Each character is processed exactly once by the Tcl interpreter
as part of creating the words of a command.
For example, if variable substitution occurs then no further
@@ -201,8 +210,9 @@ set y [set x 0][incr x][incr x]
.CE
will always set the variable \fIy\fR to the value, \fI012\fR.
.RE
-.IP "[11] \fBSubstitution and word boundaries.\fR"
-Substitutions do not affect the word boundaries of a command.
+.IP "[12] \fBSubstitution and word boundaries.\fR"
+Substitutions do not affect the word boundaries of a command,
+except for argument expansion as specified in rule [5].
For example, during variable substitution the entire value of
the variable becomes part of a single word, even if the variable's
value contains spaces.