1 | '\" |
---|
2 | '\" Copyright (c) 1993 The Regents of the University of California. |
---|
3 | '\" Copyright (c) 1994-1996 Sun Microsystems, Inc. |
---|
4 | '\" |
---|
5 | '\" See the file "license.terms" for information on usage and redistribution |
---|
6 | '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. |
---|
7 | '\" |
---|
8 | '\" RCS: @(#) $Id: Tcl.n,v 1.18 2007/12/13 15:22:32 dgp Exp $ |
---|
9 | '\" |
---|
10 | .so man.macros |
---|
11 | .TH Tcl n "8.5" Tcl "Tcl Built-In Commands" |
---|
12 | .BS |
---|
13 | .SH NAME |
---|
14 | Tcl \- Tool Command Language |
---|
15 | .SH SYNOPSIS |
---|
16 | Summary of Tcl language syntax. |
---|
17 | .BE |
---|
18 | .SH DESCRIPTION |
---|
19 | .PP |
---|
20 | The following rules define the syntax and semantics of the Tcl language: |
---|
21 | .IP "[1] \fBCommands.\fR" |
---|
22 | A Tcl script is a string containing one or more commands. |
---|
23 | Semi-colons and newlines are command separators unless quoted as |
---|
24 | described below. |
---|
25 | Close brackets are command terminators during command substitution |
---|
26 | (see below) unless quoted. |
---|
27 | .IP "[2] \fBEvaluation.\fR" |
---|
28 | A command is evaluated in two steps. |
---|
29 | First, the Tcl interpreter breaks the command into \fIwords\fR |
---|
30 | and performs substitutions as described below. |
---|
31 | These substitutions are performed in the same way for all |
---|
32 | commands. |
---|
33 | The first word is used to locate a command procedure to |
---|
34 | carry out the command, then all of the words of the command are |
---|
35 | passed to the command procedure. |
---|
36 | The command procedure is free to interpret each of its words |
---|
37 | in any way it likes, such as an integer, variable name, list, |
---|
38 | or Tcl script. |
---|
39 | Different commands interpret their words differently. |
---|
40 | .IP "[3] \fBWords.\fR" |
---|
41 | Words of a command are separated by white space (except for |
---|
42 | newlines, which are command separators). |
---|
43 | .IP "[4] \fBDouble quotes.\fR" |
---|
44 | If the first character of a word is double-quote |
---|
45 | .PQ \N'34' |
---|
46 | then the word is terminated by the next double-quote character. |
---|
47 | If semi-colons, close brackets, or white space characters |
---|
48 | (including newlines) appear between the quotes then they are treated |
---|
49 | as ordinary characters and included in the word. |
---|
50 | Command substitution, variable substitution, and backslash substitution |
---|
51 | are performed on the characters between the quotes as described below. |
---|
52 | The double-quotes are not retained as part of the word. |
---|
53 | .VS 8.5 br |
---|
54 | .IP "[5] \fBArgument expansion.\fR" |
---|
55 | If a word starts with the string |
---|
56 | .QW {*} |
---|
57 | followed by a non-whitespace character, then the leading |
---|
58 | .QW {*} |
---|
59 | is removed |
---|
60 | and the rest of the word is parsed and substituted as any other |
---|
61 | word. After substitution, the word is parsed again without |
---|
62 | substitutions, and its words are added to the command being |
---|
63 | substituted. For instance, |
---|
64 | .QW "cmd a {*}{b c} d {*}{e f}" |
---|
65 | is equivalent to |
---|
66 | .QW "cmd a b c d e f" . |
---|
67 | .VE 8.5 |
---|
68 | .IP "[6] \fBBraces.\fR" |
---|
69 | If the first character of a word is an open brace |
---|
70 | .PQ { |
---|
71 | and rule [5] does not apply, then |
---|
72 | the word is terminated by the matching close brace |
---|
73 | .PQ } "" . |
---|
74 | Braces nest within the word: for each additional open |
---|
75 | brace there must be an additional close brace (however, |
---|
76 | if an open brace or close brace within the word is |
---|
77 | quoted with a backslash then it is not counted in locating the |
---|
78 | matching close brace). |
---|
79 | No substitutions are performed on the characters between the |
---|
80 | braces except for backslash-newline substitutions described |
---|
81 | below, nor do semi-colons, newlines, close brackets, |
---|
82 | or white space receive any special interpretation. |
---|
83 | The word will consist of exactly the characters between the |
---|
84 | outer braces, not including the braces themselves. |
---|
85 | .IP "[7] \fBCommand substitution.\fR" |
---|
86 | If a word contains an open bracket |
---|
87 | .PQ [ |
---|
88 | then Tcl performs \fIcommand substitution\fR. |
---|
89 | To do this it invokes the Tcl interpreter recursively to process |
---|
90 | the characters following the open bracket as a Tcl script. |
---|
91 | The script may contain any number of commands and must be terminated |
---|
92 | by a close bracket |
---|
93 | .PQ ] "" . |
---|
94 | The result of the script (i.e. the result of its last command) is |
---|
95 | substituted into the word in place of the brackets and all of the |
---|
96 | characters between them. |
---|
97 | There may be any number of command substitutions in a single word. |
---|
98 | Command substitution is not performed on words enclosed in braces. |
---|
99 | .IP "[8] \fBVariable substitution.\fR" |
---|
100 | If a word contains a dollar-sign |
---|
101 | .PQ $ |
---|
102 | followed by one of the forms |
---|
103 | described below, then Tcl performs \fIvariable |
---|
104 | substitution\fR: the dollar-sign and the following characters are |
---|
105 | replaced in the word by the value of a variable. |
---|
106 | Variable substitution may take any of the following forms: |
---|
107 | .RS |
---|
108 | .TP 15 |
---|
109 | \fB$\fIname\fR |
---|
110 | \fIName\fR is the name of a scalar variable; the name is a sequence |
---|
111 | of one or more characters that are a letter, digit, underscore, |
---|
112 | or namespace separators (two or more colons). |
---|
113 | .TP 15 |
---|
114 | \fB$\fIname\fB(\fIindex\fB)\fR |
---|
115 | \fIName\fR gives the name of an array variable and \fIindex\fR gives |
---|
116 | the name of an element within that array. |
---|
117 | \fIName\fR must contain only letters, digits, underscores, and |
---|
118 | namespace separators, and may be an empty string. |
---|
119 | Command substitutions, variable substitutions, and backslash |
---|
120 | substitutions are performed on the characters of \fIindex\fR. |
---|
121 | .TP 15 |
---|
122 | \fB${\fIname\fB}\fR |
---|
123 | \fIName\fR is the name of a scalar variable. It may contain any |
---|
124 | characters whatsoever except for close braces. |
---|
125 | .LP |
---|
126 | There may be any number of variable substitutions in a single word. |
---|
127 | Variable substitution is not performed on words enclosed in braces. |
---|
128 | .RE |
---|
129 | .IP "[9] \fBBackslash substitution.\fR" |
---|
130 | If a backslash |
---|
131 | .PQ \e |
---|
132 | appears within a word then \fIbackslash substitution\fR occurs. |
---|
133 | In all cases but those described below the backslash is dropped and |
---|
134 | the following character is treated as an ordinary |
---|
135 | character and included in the word. |
---|
136 | This allows characters such as double quotes, close brackets, |
---|
137 | and dollar signs to be included in words without triggering |
---|
138 | special processing. |
---|
139 | The following table lists the backslash sequences that are |
---|
140 | handled specially, along with the value that replaces each sequence. |
---|
141 | .RS |
---|
142 | .TP 7 |
---|
143 | \e\fBa\fR |
---|
144 | Audible alert (bell) (0x7). |
---|
145 | .TP 7 |
---|
146 | \e\fBb\fR |
---|
147 | Backspace (0x8). |
---|
148 | .TP 7 |
---|
149 | \e\fBf\fR |
---|
150 | Form feed (0xc). |
---|
151 | .TP 7 |
---|
152 | \e\fBn\fR |
---|
153 | Newline (0xa). |
---|
154 | .TP 7 |
---|
155 | \e\fBr\fR |
---|
156 | Carriage-return (0xd). |
---|
157 | .TP 7 |
---|
158 | \e\fBt\fR |
---|
159 | Tab (0x9). |
---|
160 | .TP 7 |
---|
161 | \e\fBv\fR |
---|
162 | Vertical tab (0xb). |
---|
163 | .TP 7 |
---|
164 | \e\fB<newline>\fIwhiteSpace\fR |
---|
165 | . |
---|
166 | A single space character replaces the backslash, newline, and all spaces |
---|
167 | and tabs after the newline. This backslash sequence is unique in that it |
---|
168 | is replaced in a separate pre-pass before the command is actually parsed. |
---|
169 | This means that it will be replaced even when it occurs between braces, |
---|
170 | and the resulting space will be treated as a word separator if it is not |
---|
171 | in braces or quotes. |
---|
172 | .TP 7 |
---|
173 | \e\e |
---|
174 | Backslash |
---|
175 | .PQ \e "" . |
---|
176 | .TP 7 |
---|
177 | \e\fIooo\fR |
---|
178 | . |
---|
179 | The digits \fIooo\fR (one, two, or three of them) give an eight-bit octal |
---|
180 | value for the Unicode character that will be inserted. The upper bits of the |
---|
181 | Unicode character will be 0. |
---|
182 | .TP 7 |
---|
183 | \e\fBx\fIhh\fR |
---|
184 | . |
---|
185 | The hexadecimal digits \fIhh\fR give an eight-bit hexadecimal value for the |
---|
186 | Unicode character that will be inserted. Any number of hexadecimal digits |
---|
187 | may be present; however, all but the last two are ignored (the result is |
---|
188 | always a one-byte quantity). The upper bits of the Unicode character will |
---|
189 | be 0. |
---|
190 | .TP 7 |
---|
191 | \e\fBu\fIhhhh\fR |
---|
192 | . |
---|
193 | The hexadecimal digits \fIhhhh\fR (one, two, three, or four of them) give a |
---|
194 | sixteen-bit hexadecimal value for the Unicode character that will be |
---|
195 | inserted. |
---|
196 | .LP |
---|
197 | Backslash substitution is not performed on words enclosed in braces, |
---|
198 | except for backslash-newline as described above. |
---|
199 | .RE |
---|
200 | .IP "[10] \fBComments.\fR" |
---|
201 | If a hash character |
---|
202 | .PQ # |
---|
203 | appears at a point where Tcl is |
---|
204 | expecting the first character of the first word of a command, |
---|
205 | then the hash character and the characters that follow it, up |
---|
206 | through the next newline, are treated as a comment and ignored. |
---|
207 | The comment character only has significance when it appears |
---|
208 | at the beginning of a command. |
---|
209 | .IP "[11] \fBOrder of substitution.\fR" |
---|
210 | Each character is processed exactly once by the Tcl interpreter |
---|
211 | as part of creating the words of a command. |
---|
212 | For example, if variable substitution occurs then no further |
---|
213 | substitutions are performed on the value of the variable; the |
---|
214 | value is inserted into the word verbatim. |
---|
215 | If command substitution occurs then the nested command is |
---|
216 | processed entirely by the recursive call to the Tcl interpreter; |
---|
217 | no substitutions are performed before making the recursive |
---|
218 | call and no additional substitutions are performed on the result |
---|
219 | of the nested script. |
---|
220 | .RS |
---|
221 | .LP |
---|
222 | Substitutions take place from left to right, and each substitution is |
---|
223 | evaluated completely before attempting to evaluate the next. Thus, a |
---|
224 | sequence like |
---|
225 | .CS |
---|
226 | set y [set x 0][incr x][incr x] |
---|
227 | .CE |
---|
228 | will always set the variable \fIy\fR to the value, \fI012\fR. |
---|
229 | .RE |
---|
230 | .IP "[12] \fBSubstitution and word boundaries.\fR" |
---|
231 | Substitutions do not affect the word boundaries of a command, |
---|
232 | except for argument expansion as specified in rule [5]. |
---|
233 | For example, during variable substitution the entire value of |
---|
234 | the variable becomes part of a single word, even if the variable's |
---|
235 | value contains spaces. |
---|