util/src/TclTk/tcl8.6.12/doc/Tcl.n

   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 .TH Tcl n "8.6" Tcl "Tcl Built-In Commands"
   9 .so man.macros
  10 .BS
  11 .SH NAME
  12 Tcl \- Tool Command Language
  13 .SH SYNOPSIS
  14 Summary of Tcl language syntax.
  15 .BE
  16 .SH DESCRIPTION
  17 .PP
  18 The following rules define the syntax and semantics of the Tcl language:
  19 .IP "[1] \fBCommands.\fR"
  20 A Tcl script is a string containing one or more commands.
  21 Semi-colons and newlines are command separators unless quoted as
  22 described below.
  23 Close brackets are command terminators during command substitution
  24 (see below) unless quoted.
  25 .IP "[2] \fBEvaluation.\fR"
  26 A command is evaluated in two steps.
  27 First, the Tcl interpreter breaks the command into \fIwords\fR
  28 and performs substitutions as described below.
  29 These substitutions are performed in the same way for all
  30 commands.
  31 Secondly, the first word is used to locate a command procedure to
  32 carry out the command, then all of the words of the command are
  33 passed to the command procedure.
  34 The command procedure is free to interpret each of its words
  35 in any way it likes, such as an integer, variable name, list,
  36 or Tcl script.
  37 Different commands interpret their words differently.
  38 .IP "[3] \fBWords.\fR"
  39 Words of a command are separated by white space (except for
  40 newlines, which are command separators).
  41 .IP "[4] \fBDouble quotes.\fR"
  42 If the first character of a word is double-quote
  43 .PQ \N'34'
  44 then the word is terminated by the next double-quote character.
  45 If semi-colons, close brackets, or white space characters
  46 (including newlines) appear between the quotes then they are treated
  47 as ordinary characters and included in the word.
  48 Command substitution, variable substitution, and backslash substitution
  49 are performed on the characters between the quotes as described below.
  50 The double-quotes are not retained as part of the word.
  51 .IP "[5] \fBArgument expansion.\fR"
  52 If a word starts with the string
  53 .QW {*}
  54 followed by a non-whitespace character, then the leading
  55 .QW {*}
  56 is removed and the rest of the word is parsed and substituted as any other
  57 word. After substitution, the word is parsed as a list (without command or
  58 variable substitutions; backslash substitutions are performed as is normal for
  59 a list and individual internal words may be surrounded by either braces or
  60 double-quote characters), and its words are added to the command being
  61 substituted. For instance,
  62 .QW "cmd a {*}{b [c]} d {*}{$e f {g h}}"
  63 is equivalent to
  64 .QW "cmd a b {[c]} d {$e} f {g h}" .
  65 .IP "[6] \fBBraces.\fR"
  66 If the first character of a word is an open brace
  67 .PQ {
  68 and rule [5] does not apply, then
  69 the word is terminated by the matching close brace
  70 .PQ } "" .
  71 Braces nest within the word: for each additional open
  72 brace there must be an additional close brace (however,
  73 if an open brace or close brace within the word is
  74 quoted with a backslash then it is not counted in locating the
  75 matching close brace).
  76 No substitutions are performed on the characters between the
  77 braces except for backslash-newline substitutions described
  78 below, nor do semi-colons, newlines, close brackets,
  79 or white space receive any special interpretation.
  80 The word will consist of exactly the characters between the
  81 outer braces, not including the braces themselves.
  82 .IP "[7] \fBCommand substitution.\fR"
  83 If a word contains an open bracket
  84 .PQ [
  85 then Tcl performs \fIcommand substitution\fR.
  86 To do this it invokes the Tcl interpreter recursively to process
  87 the characters following the open bracket as a Tcl script.
  88 The script may contain any number of commands and must be terminated
  89 by a close bracket
  90 .PQ ] "" .
  91 The result of the script (i.e. the result of its last command) is
  92 substituted into the word in place of the brackets and all of the
  93 characters between them.
  94 There may be any number of command substitutions in a single word.
  95 Command substitution is not performed on words enclosed in braces.
  96 .IP "[8] \fBVariable substitution.\fR"
  97 If a word contains a dollar-sign
  98 .PQ $
  99 followed by one of the forms
 100 described below, then Tcl performs \fIvariable
 101 substitution\fR:  the dollar-sign and the following characters are
 102 replaced in the word by the value of a variable.
 103 Variable substitution may take any of the following forms:
 104 .RS
 105 .TP 15
 106 \fB$\fIname\fR
 107 .
 108 \fIName\fR is the name of a scalar variable;  the name is a sequence
 109 of one or more characters that are a letter, digit, underscore,
 110 or namespace separators (two or more colons).
 111 Letters and digits are \fIonly\fR the standard ASCII ones (\fB0\fR\(en\fB9\fR,
 112 \fBA\fR\(en\fBZ\fR and \fBa\fR\(en\fBz\fR).
 113 .TP 15
 114 \fB$\fIname\fB(\fIindex\fB)\fR
 115 .
 116 \fIName\fR gives the name of an array variable and \fIindex\fR gives
 117 the name of an element within that array.
 118 \fIName\fR must contain only letters, digits, underscores, and
 119 namespace separators, and may be an empty string.
 120 Letters and digits are \fIonly\fR the standard ASCII ones (\fB0\fR\(en\fB9\fR,
 121 \fBA\fR\(en\fBZ\fR and \fBa\fR\(en\fBz\fR).
 122 Command substitutions, variable substitutions, and backslash
 123 substitutions are performed on the characters of \fIindex\fR.
 124 .TP 15
 125 \fB${\fIname\fB}\fR
 126 .
 127 \fIName\fR is the name of a scalar variable or array element.  It may contain
 128 any characters whatsoever except for close braces.  It indicates an array
 129 element if \fIname\fR is in the form
 130 .QW \fIarrayName\fB(\fIindex\fB)\fR
 131 where \fIarrayName\fR does not contain any open parenthesis characters,
 132 .QW \fB(\fR ,
 133 or close brace characters,
 134 .QW \fB}\fR ,
 135 and \fIindex\fR can be any sequence of characters except for close brace
 136 characters.  No further
 137 substitutions are performed during the parsing of \fIname\fR.
 138 .PP
 139 There may be any number of variable substitutions in a single word.
 140 Variable substitution is not performed on words enclosed in braces.
 141 .PP
 142 Note that variables may contain character sequences other than those listed
 143 above, but in that case other mechanisms must be used to access them (e.g.,
 144 via the \fBset\fR command's single-argument form).
 145 .RE
 146 .IP "[9] \fBBackslash substitution.\fR"
 147 If a backslash
 148 .PQ \e
 149 appears within a word then \fIbackslash substitution\fR occurs.
 150 In all cases but those described below the backslash is dropped and
 151 the following character is treated as an ordinary
 152 character and included in the word.
 153 This allows characters such as double quotes, close brackets,
 154 and dollar signs to be included in words without triggering
 155 special processing.
 156 The following table lists the backslash sequences that are
 157 handled specially, along with the value that replaces each sequence.
 158 .RS
 159 .TP 7
 160 \e\fBa\fR
 161 Audible alert (bell) (Unicode U+000007).
 162 .TP 7
 163 \e\fBb\fR
 164 Backspace (Unicode U+000008).
 165 .TP 7
 166 \e\fBf\fR
 167 Form feed (Unicode U+00000C).
 168 .TP 7
 169 \e\fBn\fR
 170 Newline (Unicode U+00000A).
 171 .TP 7
 172 \e\fBr\fR
 173 Carriage-return (Unicode U+00000D).
 174 .TP 7
 175 \e\fBt\fR
 176 Tab (Unicode U+000009).
 177 .TP 7
 178 \e\fBv\fR
 179 Vertical tab (Unicode U+00000B).
 180 .TP 7
 181 \e\fB<newline>\fIwhiteSpace\fR
 182 .
 183 A single space character replaces the backslash, newline, and all spaces
 184 and tabs after the newline.  This backslash sequence is unique in that it
 185 is replaced in a separate pre-pass before the command is actually parsed.
 186 This means that it will be replaced even when it occurs between braces,
 187 and the resulting space will be treated as a word separator if it is not
 188 in braces or quotes.
 189 .TP 7
 190 \e\e
 191 Backslash
 192 .PQ \e "" .
 193 .TP 7
 194 \e\fIooo\fR
 195 .
 196 The digits \fIooo\fR (one, two, or three of them) give a eight-bit octal
 197 value for the Unicode character that will be inserted, in the range
 198 \fI000\fR\(en\fI377\fR (i.e., the range U+000000\(enU+0000FF).
 199 The parser will stop just before this range overflows, or when
 200 the maximum of three digits is reached.  The upper bits of the Unicode
 201 character will be 0.
 202 .TP 7
 203 \e\fBx\fIhh\fR
 204 .
 205 The hexadecimal digits \fIhh\fR (one or two of them) give an eight-bit
 206 hexadecimal value for the Unicode character that will be inserted.  The upper
 207 bits of the Unicode character will be 0 (i.e., the character will be in the
 208 range U+000000\(enU+0000FF).
 209 .TP 7
 210 \e\fBu\fIhhhh\fR
 211 .
 212 The hexadecimal digits \fIhhhh\fR (one, two, three, or four of them) give a
 213 sixteen-bit hexadecimal value for the Unicode character that will be
 214 inserted.  The upper bits of the Unicode character will be 0 (i.e., the
 215 character will be in the range U+000000\(enU+00FFFF).
 216 .TP 7
 217 \e\fBU\fIhhhhhhhh\fR
 218 .
 219 The hexadecimal digits \fIhhhhhhhh\fR (one up to eight of them) give a
 220 twenty-one-bit hexadecimal value for the Unicode character that will be
 221 inserted, in the range U+000000\(enU+10FFFF.  The parser will stop just
 222 before this range overflows, or when the maximum of eight digits
 223 is reached.  The upper bits of the Unicode character will be 0.
 224 .RS
 225 .PP
 226 The range U+010000\(enU+10FFFD is reserved for the future.
 227 .RE
 228 .PP
 229 Backslash substitution is not performed on words enclosed in braces,
 230 except for backslash-newline as described above.
 231 .RE
 232 .IP "[10] \fBComments.\fR"
 233 If a hash character
 234 .PQ #
 235 appears at a point where Tcl is
 236 expecting the first character of the first word of a command,
 237 then the hash character and the characters that follow it, up
 238 through the next newline, are treated as a comment and ignored.
 239 The comment character only has significance when it appears
 240 at the beginning of a command.
 241 .IP "[11] \fBOrder of substitution.\fR"
 242 Each character is processed exactly once by the Tcl interpreter
 243 as part of creating the words of a command.
 244 For example, if variable substitution occurs then no further
 245 substitutions are performed on the value of the variable;  the
 246 value is inserted into the word verbatim.
 247 If command substitution occurs then the nested command is
 248 processed entirely by the recursive call to the Tcl interpreter;
 249 no substitutions are performed before making the recursive
 250 call and no additional substitutions are performed on the result
 251 of the nested script.
 252 .RS
 253 .PP
 254 Substitutions take place from left to right, and each substitution is
 255 evaluated completely before attempting to evaluate the next.  Thus, a
 256 sequence like
 257 .PP
 258 .CS
 259 set y [set x 0][incr x][incr x]
 260 .CE
 261 .PP
 262 will always set the variable \fIy\fR to the value, \fI012\fR.
 263 .RE
 264 .IP "[12] \fBSubstitution and word boundaries.\fR"
 265 Substitutions do not affect the word boundaries of a command,
 266 except for argument expansion as specified in rule [5].
 267 For example, during variable substitution the entire value of
 268 the variable becomes part of a single word, even if the variable's
 269 value contains spaces.
 270 .SH KEYWORDS
 271 backslash, command, comment, script, substitution, variable
 272 '\" Local Variables:
 273 '\" mode: nroff
 274 '\" fill-column: 78
 275 '\" End: