This appendix presents the same information available in the Tool
Command Language (Tcl) reference-manual entries ("man pages"); we
include it in the DejaGnu manual for convenient reference. The author
of Tcl, and of the reference-manual entries where this information
originally appeared, is John Ousterhout, of the University of California
at Berkeley (ouster@sprite.berkeley.edu).
The following copyright terms apply to the documentation in this Appendix:
Copyright (C) 1993 The Regents of the University of California. All rights reserved.
Permission is hereby granted, without written agreement and without license or royalty fees, to use, copy, modify, and distribute this documentation for any purpose, provided that the above copyright notice and the following two paragraphs appear in all copies.
IN NO EVENT SHALL THE UNIVERSITY OF CALIFORNIA BE LIABLE TO ANY PARTY FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF THE UNIVERSITY OF CALIFORNIA HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
THE UNIVERSITY OF CALIFORNIA SPECIFICALLY DISCLAIMS ANY WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE SOFTWARE PROVIDED HEREUNDER IS ON AN "AS IS" BASIS, AND THE UNIVERSITY OF CALIFORNIA HAS NO OBLIGATION TO PROVIDE MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS.
The following rules define the syntax and semantics of the Tcl language:
") then the
word is terminated by the next double-quote character. If semicolons,
close brackets, or whitespace characters (including newlines) appear
between the quotes then they are treated 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.
{) 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, if an open brace or close brace within
the word is quoted with a backslash then it is not counted in locating
the matching close brace). No substitutions are performed on the
characters between the braces except for backslash-newline substitutions
described below, nor do semicolons, newlines, close brackets, or
whitespace have any special interpretation. The word will consist of
exactly the characters between the outer braces, not including the
braces themselves.
[) then Tcl performs command
substitution. To do this it invokes the Tcl interpreter recursively to
process the characters following the open bracket as a Tcl script. The
script may contain any number of commands and must be terminated by a
close bracket (]). The result of the script (i.e. the result of its
last command) is 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.
$) then Tcl performs variable
substitution: the dollar-sign and the following characters are replaced
in the word by the value of a variable. Variable substition may take
any of the following forms:
$name
$name(index)
${name}
\) appears within a word then backslash substitution
occurs. In all cases but those described below the backslash is dropped
and the following character is treated as an ordinary character and
included in the word. This allows characters such as double quotes,
close brackets, and dollar signs to be included in words without
triggering special processing. The following table lists the backslash
sequences that are handled specially, along with the value that replaces
each sequence.
\a
0x7).
\b
0x8).
\f
0xc).
\n
0xa).
\r
0xd).
\t
0x9).
\v
0xb).
\newline whitespace
\\
\).
\ooo
\xhh
\newline as described above.
#) 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.
A Tcl expression consists of a combination of operands, operators, and parentheses. White space may be used between the operands and operators and parentheses; it is ignored by the expression processor.
The command expr evaluates expressions with no further effect.
See section Evaluate an expression: expr. The conditional command
if, and two of the looping commands (for and while)
also evaluate Tcl expressions to test conditions.
For some examples of simple expressions, suppose the variable a
has the value 3 and the variable b has the value 6.
Then the command on the left side of each of the lines below will
produce the value on the right side of the line:
expr 3.1 + $a 6.1
expr 2 + "$a.$b" 5.6
expr 4*[llength "6 2"] 8
expr {{word one} < "word $a"} 0
Where possible, operands are interpreted as integer values. Integer values may be specified in decimal (the normal case), in octal (if the first character of the operand is `0'), or in hexadecimal (if the first two characters of the operand are `0x'). If an operand does not have one of the integer formats given above, then it is treated as a floating-point number if that is possible. Floating-point numbers may be specified in any of the ways accepted by an ANSI-compliant C compiler (except that the `f', `F', `l', and `L' suffixes will not be permitted in most installations). For example, all of the following are valid floating-point numbers: `2.1', `3.', `6e4', `7.91e+16'. If no numeric interpretation is possible, then an operand is left as a string (and only a limited set of operators may be applied to it).
Operands may be specified in any of the following ways:
"). The expression parser
will perform backslash, variable, and command substitutions on the
information between the quotes, and use the resulting value as the
operand.
Where substitutions occur above (e.g. inside quoted strings), they are performed by the expression processor. However, an additional layer of substitution may already have been performed by the command parser before the expression processor was called. As discussed below, it is usually best to enclose expressions in braces to prevent the command parser from performing substitutions on the contents.
The operators Tcl recognizes in expressions are listed below, grouped in decreasing order of precedence:
- ~ !
* / %
+ -
<< >>
< > <= >=
1 if the condition is true, 0
otherwise. These operators may be applied to strings as well as numeric
operands, in which case string comparison is used.
== !=
&
^
|
&&
1 result if both operands are
non-zero, 0 otherwise. Valid for numeric operands only (integers
or floating-point).
||
0 result if both operands are zero,
1 otherwise. Valid for numeric operands only (integers or
floating-point).
x ? y : z
See the C manual for more details on the results produced by each operator. All of the binary operators group left-to-right within the same precedence level. For example, the command
expr 4*2 < 7
returns 0.
The &&, ||, and ?: operators have "lazy
evaluation", just as in C, which means that operands are not evaluated
if they are not needed to determine the outcome. For example, in the
command
expr {$v ? [a] : [b]}
only one of `[a]' or `[b]' will actually be evaluated,
depending on the value of `$v'. Note, however, that this is only
true if the entire expression is enclosed in braces; otherwise the Tcl
parser will evaluate both `[a]' and `[b]' before invoking the
expr command.
Tcl supports the following mathematical functions in expressions:
acos cos hypot sinh asin cosh log sqrt atan exp log10 tan atan2 floor pow tanh ceil fmod sin
Each of these functions invokes the C math library function of the same name; see the manual entries for the library functions for details on what they do. Tcl also implements the following functions for conversion between integers and floating-point numbers:
abs(arg)
double(arg)
int(arg)
round(arg)
All internal computations involving integers are done with the C type
long, and all internal computations involving floating-point are
done with the C type double. When converting a string to
floating-point, exponent overflow is detected and results in a Tcl
error. For conversion to integer from string, detection of overflow
depends on the behavior of some routines in the local C library, so it
should be regarded as unreliable. In any case, integer overflow and
underflow are generally not detected reliably for intermediate results.
Floating-point overflow and underflow are detected to the degree
supported by the hardware, which is generally pretty reliable.
Conversion among internal representations for integer, floating-point, and string operands is done automatically as needed. For arithmetic computations, integers are used until some floating-point number is introduced, after which floating-point is used. For example,
expr 5 / 4
returns 1, while
expr 5 / 4.0 expr 5 / ( [string length "abcd"] + 0.0 )
both return 1.25. Floating-point values are always returned with
a `.' or an `e' so that they will not look like integer
values. For example,
expr 20.0/5.0
returns `4.0', not `4'. The global variable
tcl_precision determines the the number of significant digits
that are retained when floating values are converted to strings (except
that trailing zeroes are omitted). If tcl_precision is unset
then 6 digits of precision are used. To retain all of the significant
bits of an IEEE floating-point number set tcl_precision to
17; if a value is converted to string with 17 digits of precision
and then converted back to binary for some later calculation, the
resulting binary value is guaranteed to be identical to the original
one.
String values may be used as operands of the comparison operators,
although the expression evaluator tries to do comparisons as integer or
floating-point when it can. If one of the operands of a comparison is a
string and the other has a numeric value, the numeric operand is
converted back to a string using the C sprintf format specifier
`%d' for integers and `%g' for floating-point values. For
example, the commands
expr {"0x03" > "2"}
expr {"0y" < "0x12"}
both return 1. The first comparison is done using integer
comparison, and the second is done using string comparison after the
second operand is converted to the string `18'.
Here are descriptions of all the commands built into the Tcl language itself.
append@begingroup @let@nonarrowing=@comment
append varname value [ value ... ]
@endgroup
Append all of the value arguments to the current value of variable
varname. If varname doesn't exist, it is given a value
equal to the concatenation of all the value arguments. This
command provides an efficient way to build up long variables
incrementally. For example, `append a $b' is much more efficient
than `set a $a$b' if $a is long.
array@begingroup @let@nonarrowing=@comment
array option arrayname [ arg ... ]
@endgroup
This command performs one of several operations on the variable given by arrayname. arrayname must be the name of an existing array variable. The option argument determines what action is carried out by the command. The options (which may be abbreviated) are:
array names arrayname
array size arrayname
array startsearch arrayname
array nextelement arrayname srchid
array anymore arrayname srchid
1 if there are any more elements left to be processed in
an array search, 0 if all elements have already been returned.
srchid indicates which search on arrayname to check, and
must have been the return value from a previous invocation of
`array startsearch'. This option is particularly useful if an
array has an element with an empty name, since the return value from
`array nextelement' won't indicate whether the search has been
completed.
array donesearch arrayname srchid
break@begingroup @let@nonarrowing=@comment
break
@endgroup
This command may be invoked only inside the body of a looping command
such as for or foreach or while. It returns a
TCL_BREAK code to signal the innermost containing loop command to
return immediately.
case
case str [ in] patlist body [ patlist body ...]
case str [ in] {patlist body [ patlist body ...]}
Warning: the
casecommand is obsolete, and is supported only for backward compatibility. At some point in the future it may be removed entirely. You should use theswitchcommand instead.
The case command matches str against each of the
patlist arguments in order. Each patlist argument is a list
of one or more patterns. If any of these patterns matches str
then case evaluates the following body argument by passing
it recursively to the Tcl interpreter and returns the result of that
evaluation. Each patlist argument consists of a single pattern or
list of patterns. Each pattern may contain any of the wild-cards
described under `string match' (see section Manipulate strings: string). If a patlist argument is the word default,
the corresponding body will be evaluated if no patlist
matches str. If no patlist argument matches str and
no default is given, then the case command returns an empty
string.
Two syntaxes are provided for the patlist and body
arguments. The first uses a separate argument for each of the patterns
and commands; this form is convenient if substitutions are desired on
some of the patterns or commands. The second form places all of the
patterns and commands together into a single argument; the argument must
have proper list structure, with the elements of the list being the
patterns and commands. The second form makes it easy to construct
multi-line case commands, since the braces around the whole list
make it unnecessary to include a backslash at the end of each line.
Since the patlist arguments are in braces in the second form, no
command or variable substitutions are performed on them; this makes the
behavior of the second form different than the first form in some cases.
catch@begingroup @let@nonarrowing=@comment
catch script [ varname ]
@endgroup
The catch command may be used to prevent errors from aborting
command interpretation. catch calls the Tcl interpreter
recursively to execute script, and always returns a TCL_OK
code, regardless of any errors that might occur while executing
script. The return value from catch is a decimal string
giving the code returned by the Tcl interpreter after executing
script. This will be 0 (TCL_OK) if there were no errors in
script; otherwise it will have a non-zero value corresponding to
one of the exceptional return codes (see section Return from a procedure: return, for descriptions of exception code values).
If the varname argument is given, then it gives the name of a
variable; catch will set the variable to the string returned from
script (either a result or an error message).
cd@begingroup @let@nonarrowing=@comment
cd [ dirname ]
@endgroup
Change the current working directory to dirname, or to the home
directory (as specified in the HOME environment variable) if
dirname is not given. Returns an empty string.
If dirname starts with a tilde, then tilde-expansion is done: the
first element of dirname is replaced with the location of the home
directory for the given user. The substitution is carried out in the
same way that it would be done by csh. If the tilde is followed
immediately by a slash, then the HOME environment variable is
substituted. Otherwise the characters between the tilde and the next
slash are taken as a user name, which is looked up in the password file;
the user's home directory is retrieved from the password file and
substituted.
close@begingroup @let@nonarrowing=@comment
close fileid
@endgroup
Closes the file given by fileid. fileid must be the return
value from a previous invocation of the open command; after this
command, it should not be used anymore. If fileid refers to a
command pipeline instead of a file, then close waits for the children to
complete. The normal result of this command is an empty string, but
errors are returned if there are problems in closing the file or waiting
for children to complete.
concat@begingroup @let@nonarrowing=@comment
concat [ arg ... ]
@endgroup
This command treats each argument as a list and concatenates them into a single list. It also eliminates leading and trailing spaces in each arg and adds a single separator space between each arg. It permits any number of arguments. For example, the command
concat a b {c d e} {f {g h}}
will return as its result
a b c d e f {g h}
If no arg is supplied, the result is an empty string.
continue@begingroup @let@nonarrowing=@comment
continue
@endgroup
This command may be invoked only inside the body of a looping command
such as for or foreach or while. It returns a
TCL_CONTINUE code to signal the innermost containing loop command
to skip the remainder of the loop's body but continue with the next
iteration of the loop.
eof@begingroup @let@nonarrowing=@comment
eof fileid
@endgroup
Returns 1 if an end-of-file condition has occurred on fileid, 0
otherwise. fileid must be the return value from a previous call
to open, or it may be stdin, stdout, or
stderr to refer to one of the standard I/O channels.
error@begingroup @let@nonarrowing=@comment
error message [ info ] [ code ]
@endgroup
Returns a TCL_ERROR code, which causes command interpretation to
be unwound. message is a string that is returned to the
application to indicate what went wrong.
If the info argument is provided and is non-empty, it is used to
initialize the global variable errorInfo. errorInfo is
used to accumulate a stack trace of what was in progress when an error
occurred; as nested commands unwind, the Tcl interpreter adds
information to errorInfo. If the info argument is present,
it is used to initialize errorInfo and the first increment of
unwind information will not be added by the Tcl interpreter. In other
words, the command containing the error command will not appear in
errorInfo; in its place will be info. This feature is most
useful in conjunction with the catch command. If a caught error
cannot be handled successfully, info can be used to return a stack
trace reflecting the original point of occurrence of the error:
catch { ... } errMsg
set savedInfo $errorInfo
...
error $errMsg $savedInfo
If the code argument is present, then its value is stored in the
errorCode global variable. This variable is intended to hold a
machine-readable description of the error in cases where such
information is available; see section Variables built into Tcl, for information on the proper format for the variable. If the
code argument is not present, then errorCode is
automatically reset to `NONE' by the Tcl interpreter as part of
processing the error generated by the command.
eval@begingroup @let@nonarrowing=@comment
eval arg [ arg ... ]
@endgroup
eval takes one or more arguments, which together comprise a Tcl
script containing one or more commands. eval concatenates all
its arguments in the same fashion as the concat command, passes
the concatenated string to the Tcl interpreter recursively, and returns
the result of that evaluation (or any error generated by it).
exec@begingroup @let@nonarrowing=@comment
exec [ opts ] arg [ arg ... ]
@endgroup
This command treats its arguments as the specification of one or more subprocesses to execute. The arguments take the form of a standard shell pipeline where each arg becomes one word of a command, and each distinct command becomes a subprocess.
If the initial arguments to exec start with `-' then they
are treated as command-line options and are not part of the pipeline
specification. The following options are currently supported:
-keepnewline
--
If an arg (or pair of arg strings) has one of the forms
described below then it is used by exec to control the flow of
input and output among the subprocess(es). Such arguments will not be
passed to the subprocess(es). In forms such as `< fname'
fname may either be in a separate argument from `<' or in the
same argument with no intervening space (i.e. `<fname').
|
|&
< fname
<@ fileid
open. It is used as the standard
input for the first command in the pipeline. fileid must have
been opened for reading.
<< value
> fname
2> fname
>& fname
>> fname
2>> fname
>>& fname
> fileid
open. Standard output from the
last command is redirected to the corresponding file, which must have
been opened for writing.
2> fileid
open. Standard error from all
commands in the pipeline is redirected to the corresponding file. The
file must have been opened for writing.
>& fileid
open. Both standard output from
the last command and standard error from all commands are redirected to
the corresponding file. The file must have been opened for writing.
If standard output has not been redirected then the exec command
returns the standard output from the last command in the pipeline. If
any of the commands in the pipeline exit abnormally or are killed or
suspended, then exec will return an error and the error message
will include the pipeline's output followed by error messages describing
the abnormal terminations; the errorCode variable will contain
additional information about the last abnormal termination encountered.
If any of the commands writes to its standard error file and that
standard error isn't redirected, then exec will return an error;
the error message will include the pipeline's standard output, followed
by messages about abnormal terminations (if any), followed by the
standard error output.
If the last character of the result or error message is a newline then that character is normally deleted from the result or error message. This is consistent with other Tcl return values, which don't normally end with newlines. However, if `-keepnewline' is specified then the trailing newline is retained.
If standard input isn't redirected with `<' or `<<' or `<@' then the standard input for the first command in the pipeline is taken from the application's current standard input.
If the last arg is `&' then the pipeline will be executed in
background. In this case the exec command will return a list whose
elements are the process identifiers for all of the subprocesses in the
pipeline. The standard output from the last command in the pipeline
will go to the application's standard output if it hasn't been
redirected, and error output from all of the commands in the pipeline
will go to the application's standard error file unless redirected.
The first word in each command is taken as the command name;
tilde-substitution is performed on it, and if the result contains no
slashes then the directories in the PATH environment variable are
searched for an executable by the given name. If the name contains a
slash then it must refer to an executable reachable from the current
directory. No wildcard ("glob") expansion or other shell-like
substitutions are performed on the arguments to commands.
exit@begingroup @let@nonarrowing=@comment
exit [ returncode ]
@endgroup
Terminate the process, returning returncode to the system as the exit status. If returncode isn't specified then it defaults to 0.
expr@begingroup @let@nonarrowing=@comment
expr arg ?arg arg ...?
@endgroup
Concatenates arg's (adding separator spaces between them), evaluates the result as a Tcl expression, and returns the value. The operators permitted in Tcl expressions are a subset of the operators permitted in C expressions, and they have the same meaning and precedence as the corresponding C operators. Expressions almost always yield numeric results (integer or floating-point values). For example, the expression
expr 8.2 + 6
evaluates to 14.2. Tcl expressions differ from C expressions in the way that operands are specified. Also, Tcl expressions support non-numeric operands and string comparisons.
file@begingroup @let@nonarrowing=@comment
file opt fname [ arg ... ]
@endgroup
This command provides several operations on a file's name or attributes.
fname is the name of a file; if it starts with a tilde, then tilde
substitution is done before executing the command (as for cd;
see section Change working directory: cd). opt indicates
what to do with the file name. Any unique abbreviation for opt is
acceptable. The options currently implemented are:
file atime fname
file dirname fname
file executable fname
1 if file fname is executable by the current
user, 0 otherwise.
file exists fname
1 if file fname exists and the current user has
search privileges for the directories leading to it, 0 otherwise.
file extension fname
file isdirectory fname
1 if file fname is a directory, 0 otherwise.
file isfile fname
1 if file fname is a regular file, 0 otherwise.
file lstat fname varname
lstat kernel
call instead of stat. This means that if fname refers to a
symbolic link the information returned in varname is for the link
rather than the file it refers to. On systems that don't support
symbolic links this option behaves exactly the same as the stat
option.
file mtime fname
file owned fname
1 if file fname is owned by the current user,
0 otherwise.
file readable fname
1 if file fname is readable by the current user,
0 otherwise.
file readlink fname
file rootname fname
file size fname
file stat fname varname
atime, ctime,
dev, gid, ino, mode, mtime,
nlink, size, type, uid. Each element except
type is a decimal string with the value of the corresponding
field from the stat return structure; see the operating system
reference manual entry for stat for details on the meanings of
the values. The type element gives the type of the file in the
same form returned by the command `file type'. This command
returns an empty string.
file tail fname
file type fname
file writable fname
1 if file fname is writable by the current user,
0 otherwise.
flush@begingroup @let@nonarrowing=@comment
flush fileid
@endgroup
Flushes any output that has been buffered for fileid.
fileid must be the return value from a previous call to
open, or it may be stdout or stderr to access one
of the standard I/O streams; it must refer to a file that was opened for
writing. The command returns an empty string.
for@begingroup @let@nonarrowing=@comment
for start tst nxt body
@endgroup
for is a looping command, similar in structure to the C
for statement. The start, nxt, and body
arguments must be Tcl command strings, and tst is an expression
string. The for command first invokes the Tcl interpreter to
execute start. Then it repeatedly evaluates tst as an
expression; if the result is non-zero it invokes the Tcl interpreter on
body, then invokes the Tcl interpreter on nxt, then repeats
the loop. The command terminates when tst evaluates to 0.
If a continue command is invoked within body then any
remaining commands in the current execution of body are skipped;
processing continues by invoking the Tcl interpreter on nxt, then
evaluating tst, and so on. If a break command is invoked
within body or nxt, then the for command will return
immediately. The operation of break and continue are
similar to the corresponding statements in C. for returns an
empty string.
foreach@begingroup @let@nonarrowing=@comment
foreach varname list body
@endgroup
In this command varname is the name of a variable, list is a
list of values to assign to varname, and body is a Tcl
script. For each element of list (in order from left to right),
foreach assigns the contents of the field to varname as if
the lindex command had been used to extract the field, then calls
the Tcl interpreter to execute body. The break and
continue statements may be invoked inside body, with the
same effect as in the for command. foreach returns an
empty string.
sprintf: format@begingroup @let@nonarrowing=@comment
format fstr [ arg ... ]
@endgroup
This command generates a formatted string in the same way as the
ANSI C sprintf procedure (it uses sprintf in its
implementation). fstr indicates how to format the result, using
`%' conversion specifiers as in sprintf, and the additional
arguments, if any, provide values to be substituted into the result.
The return value from format is the formatted string.
Details on formatting. The command operates by scanning
fstr from left to right. Each character from the format string is
appended to the result string unless it is a percent sign. If the
character is a `%' then it is not copied to the result string.
Instead, the characters following the `%' character are treated as
a conversion specifier. The conversion specifier controls the
conversion of the next successive arg to a particular format and
the result is appended to the result string in place of the conversion
specifier. If there are multiple conversion specifiers in the format
string, then each one controls the conversion of one additional
arg. The format command must be given enough args to
meet the needs of all of the conversion specifiers in fstr.
Each conversion specifier may contain up to six different parts: an XPG3(6) position specifier, a set of flags, a minimum field width, a precision, a length modifier, and a conversion character. Any of these fields may be omitted except for the conversion character. The fields that are present must appear in the order given above. The paragraphs below discuss each of these fields in turn.
If the `%' is followed by a decimal number and a `$', as in
`%2$d', then the value to convert is not taken from the next
sequential argument. Instead, it is taken from the argument indicated
by the number, where 1 corresponds to the first arg. If
the conversion specifier requires multiple arguments because of *
characters in the specifier then successive arguments are used, starting
with the argument given by the number. This follows the XPG3
conventions for positional specifiers. If there are any
positional specifiers in fstr, then all of the specifiers
must be positional.
The second portion of a conversion specifier may contain any of the following flag characters, in any order:
-
+
space
0
#
The third portion of a conversion specifier is a number giving a minimum
field width for this conversion. It is typically used to make columns
line up in tabular printouts. If the converted argument contains fewer
characters than the minimum field width then it will be padded so that
it is as wide as the minimum field width. Padding normally occurs by
adding extra spaces on the left of the converted argument, but the
`0' and `-' flags may be used to specify padding with zeroes
on the left or with spaces on the right, respectively. If the minimum
field width is specified as `*' rather than a number, then the next
argument to the format command determines the minimum field
width; it must be a numeric string.
The fourth portion of a conversion specifier is a precision, which
consists of a period followed by a number. The number is used in
different ways for different conversions. For `e', `E', and
`f' conversions it specifies the number of digits to appear to the
right of the decimal point. For `g' and `G' conversions it
specifies the total number of digits to appear, including those on both
sides of the decimal point (however, trailing zeroes after the decimal
point will still be omitted unless the # flag has been specified). For
integer conversions, it specifies a mimimum number of digits to print
(leading zeroes will be added if necessary). For s conversions it
specifies the maximum number of characters to be printed; if the string
is longer than this then the trailing characters will be dropped. If
the precision is specified with `*' rather than a number then the
next argument to the format command determines the precision; it
must be a numeric string.
The fourth part of a conversion specifier is a length modifier, which must be `h' or `l'. If it is `h' it specifies that the numeric value should be truncated to a 16-bit value before converting. This option is rarely useful. The `l' modifier is ignored.
The last thing in a conversion specifier is an alphabetic character that determines what kind of conversion to perform. The following conversion characters are currently supported:
d
u
i
o
x
X
c
s
f
e
E
g
G
%
For the numerical conversions the argument being converted must be an
integer or floating-point string; format converts the argument to
binary and then converts it back to a string according to the conversion
specifier.
Differences from ANSI sprintf. The behavior of the
format command is the same as the ANSI C sprintf procedure
except for these differences:
double is
used for the internal representation). If the `h' modifier is
specified then integer values are truncated to short before
conversion.
gets@begingroup @let@nonarrowing=@comment
gets fileid [ varname ]
@endgroup
This command reads the next line from the file given by fileid and
discards the terminating newline character. If varname is
specified then the line is placed in the variable by that name and the
return value is a count of the number of characters read (not including
the newline). If the end of the file is reached before reading any
characters then `-1' is returned and varname is set to an
empty string. If varname is not specified then the return value
will be the line (minus the newline character) or an empty string if the
end of the file is reached before reading any characters. An empty
string will also be returned if a line contains no characters except the
newline, so eof may have to be used to determine what really
happened. If the last character in the file is not a newline character
then gets behaves as if there were an additional newline
character at the end of the file. fileid must be stdin or
the return value from a previous call to open; it must refer to a
file that was opened for reading. Any existing end-of-file or error
condition on the file is cleared at the beginning of the gets
command.
glob@begingroup @let@nonarrowing=@comment
glob [ opts ] ptrn [ ptrn ... ]
@endgroup
This command performs file name wildcard expansion ("globbing") in a
fashion similar to the csh shell. It returns a list of the files
whose names match any of the patterns specified as ptrn arguments.
If the initial arguments to glob start with `-' then they are treated as options. The following options are currently supported:
-nocomplain
--
The ptrn arguments may contain any of the following special characters:
?
*
[chars]
\x
{a,b,...}
As with csh, a `.' at the beginning of a filename or just
after a `/' must be matched explicitly or with a {...}
construct. In addition, all `/' characters must be matched
explicitly.
If the first character in a pattern is `~' then it refers to the
home directory for the user whose name follows the `~'. If the
`~' is followed immediately by `/' then the value of the
HOME environment variable is used.
The glob command differs from csh wildcard expansion in
two ways. First, it does not sort its result list (use the lsort
command if you want the list sorted). Second, glob only returns
the names of files that actually exist; in csh no check for
existence is made unless a pattern contains a `?', `*', or
`[...]' construct.
global@begingroup @let@nonarrowing=@comment
global varname [ varname ... ]
@endgroup
This command is ignored unless a Tcl procedure is being interpreted. If so then it declares each given varname listed to be a global variable, rather than a local one. For the duration of the current procedure (and only while executing in the current procedure), any reference to any varname will refer to the global variable by the same name.
history@begingroup @let@nonarrowing=@comment
history [ operation ] [ arg ... ]
@endgroup
The history command performs one of several operations related to recently-executed commands recorded in a history list. Each of these recorded commands is referred to as an event. When specifying an event to the history command, the following forms may be used:
-1 refers to the
previous event, -2 to the one before that, and so on).
The history command can take any of the following forms:
history
history add command [ exec ]
exec is specified (or abbreviated) then the command is also
executed and its result is returned. If exec isn't specified
then an empty string is returned as result.
history change newval [ event ]
-1). This command is intended for use in commands that
implement new forms of history substitution and wish to replace the
current event (which invokes the substitution) with the command created
through substitution. The return value is an empty string.
history event [ event ]
-1. This command causes history revision to occur.
See section History revision, for details.
history info [ n ]
history keep n
history nextid
history redo [ evt ]
-1. This command results in history
revision. See section History revision, for details.
history substitute old new [ evt ]
-1 by default), replace
any occurrences of old by new in the command (only simple
character equality is supported; no wild cards), execute the resulting
command, and return the result of that execution. This command results
in history revision. See section History revision, for details.
history words sel [ evt ]
-1 by default) the
words given by sel, and return those words in a string separated
by spaces. The sel argument has three forms. If it is a single
number then it selects the word given by that number (0 for the
command name, 1 for its first argument, and so on). If it
consists of two numbers separated by a dash, then it selects all the
arguments between those two. Otherwise sel is treated as a
pattern; all words matching that pattern (in the sense of `string
match') are returned. In the numeric forms `$' may be used to
select the last word of a command. For example, suppose the most recent
command in the history list is
@begingroup
@let@nonarrowing=@comment
format {%s is %d years old} Alice [expr $ageInMonths/12]
@endgroup
Here are some history commands and the results they would produce (the
result of each command is shown indented below it):
history words $
[expr $ageInMonths/12]
history words 1-2
{%s is %d years old} Alice
history words *a*o*
{%s is %d years old} [expr $ageInMonths/12]
`history words' results in history revision.
The history options event, redo, substitute,
and words result in history revision. When one of these
options is invoked then the current event is modified to eliminate the
history command and replace it with the result of the
history command. For example, suppose that the most recent
command in the history list is
set a [expr $b+2]
and suppose that the next command invoked is one of the ones on the left side of the table below. The command actually recorded in the history event will be the corresponding one on the right side of the table.
history redo set a [expr $b+2] history s a b set b [expr $b+2] set c [history w 2] set c [expr $b+2]
History revision is needed because event specifiers like -1 are
only valid at a particular time: once more events have been added to the
history list a different event specifier would be needed. History
revision occurs even when history is invoked indirectly from the
current event (e.g. a user types a command that invokes a Tcl procedure
that invokes history): the top-level command whose execution
eventually resulted in a history command is replaced. If you
wish to invoke commands like `history words' without history
revision, you can use `history event' to save the current history
event and then use `history change' to restore it later.
if@begingroup @let@nonarrowing=@comment
if expr1 [ then ] body1 elseif expr2 [ then ] body2 elseif ... [ else ] [ bodyN ]
@endgroup
The if command evaluates expr1 as an expression (in the
same way that expr evaluates its argument). The value of the
expression must be a Boolean (a numeric value, where 0 is false and
anything is true, or a string value such as `true' or `yes'
for true, and `false' or `no' for false); if it is true then
body1 is executed by passing it to the Tcl interpreter. Otherwise
expr2 is evaluated as an expression and if it is true then
body2 is executed, and so on. If none of the expressions
evaluates to true then bodyN is executed. The then and
else arguments are optional "noise words" to make the command
easier to read. There may be any number of elseif clauses,
including zero. bodyN may also be omitted as long as else
is omitted too. The return value from the command is the result of the
body script that was executed, or an empty string if none of the
expressions was non-zero and there was no bodyN.
incr@begingroup @let@nonarrowing=@comment
incr varname [ n ]
@endgroup
Increments the value stored in the variable whose name is varname. The value of the variable must be an integer. If n is supplied then its value (which must also be an integer) is added to the value of variable varname; otherwise 1 is added to varname. The new value is stored as a decimal string in variable varname and also returned as result.
info@begingroup @let@nonarrowing=@comment
info op [ arg ... ]
@endgroup
This command provides information about various internals of the Tcl interpreter. Recognized values for op (which may be abbreviated) are:
info args procname
info body procname
info cmdcount
info commands [ ptn ]
proc command. If ptn
is specified, only those names matching ptn are returned.
Matching is determined using the same rules as for `string match'.
info complete cmd
1 if cmd is a complete Tcl command in the sense of
having no unclosed quotes, braces, brackets or array element names. If
the command doesn't appear to be complete then 0 is returned.
This command is typically used in line-oriented input environments to
allow users to type in commands that span multiple lines; if the command
isn't complete, the script can delay evaluating it until additional
lines have been typed to complete the command.
info default procname arg varname
0. Otherwise it
returns 1 and places the default value of arg into variable
varname.
info exists varname
1 if the variable named varname exists in the
current context (either as a global or local variable); returns 0
otherwise.
info globals [ ptn ]
info level [ n ]
0 if the command is
invoked at top-level. If n (a number) is specified, then the
result is a list consisting of the name and arguments for the procedure
call at level n on the stack. If n is positive then it
selects a particular stack level (1 refers to the top-most active
procedure, 2 to the procedure it called, and so on); otherwise it
gives a level relative to the current level (0 refers to the
current procedure, -1 to its caller, and so on). See section Execute in another stack frame: uplevel, for more information on what
stack levels mean.
info library
TCL_LIBRARY environment
variable. If there is no TCL_LIBRARY variable and no compiled-in
value then an error is generated. See section Tcl standard library, for details of the facilities provided by the Tcl script
library. Normally each application will have its own
application-specific script library in addition to the Tcl script
library; I suggest that each application set a global variable with a
name like app_library (where app is the application's
name) to hold the location of that application's library directory.
info locals [ ptn ]
global and
upvar commands will not be returned. If ptn is specified,
only those names matching ptn are returned. Matching is
determined using the same rules as for `string match'.
info patchlevel
info procs [ ptn ]
proc; not built-in
commands). If ptn is specified, only those names matching
ptn are returned. Matching is determined using the same rules as
for `string match'.
info script
info tclversion
info vars [ ptn ]
join@begingroup @let@nonarrowing=@comment
join lst [ delim ]
@endgroup
The lst argument must be a valid Tcl list. This command returns the string formed by joining all of the elements of lst together with the string delim separating each adjacent pair of elements. The delim argument defaults to a space character.
lappend@begingroup @let@nonarrowing=@comment
lappend varname val [ val ... ]
@endgroup
This command treats the variable given by varname as a list and
appends each of the val arguments to that list as a separate
element, with spaces between elements. If varname doesn't exist,
it is created as a list with elements given by the val arguments.
lappend is similar to append except that the values are
appended as list elements rather than raw text. This command provides a
relatively efficient way to build up large lists. For example,
`lappend a $b' is much more efficient than `set a [concat $a
[list $b]]' when `$a' is long.
lindex@begingroup @let@nonarrowing=@comment
lindex lst ix
@endgroup
This command treats lst as a Tcl list and returns the element
indexed by ix from it (0 refers to the first element of the
list). In extracting the element, lindex observes the same rules
concerning braces and quotes and backslashes as the Tcl command
interpreter; however, variable substitution and command substitution do
not occur. If ix is negative or greater than or equal to the
number of elements in lst, then an empty string is returned.
linsert@begingroup @let@nonarrowing=@comment
linsert lst ix elt [ elt ... ]
@endgroup
This command produces a new list from lst by inserting all of the elt arguments just before the element at position ix of lst. Each elt argument will become a separate element of the new list. If ix is less than or equal to zero, then the new elements are inserted at the beginning of the list. If ix is greater than or equal to the number of elements in lst, then the new elements are appended to the list.
list@begingroup @let@nonarrowing=@comment
list [ arg ... ]
@endgroup
This command returns a list composed of all the arg values, or an
empty string if no arg is specified. Braces and backslashes get
added as necessary, so that the index command may be used on the
result to re-extract the original arguments, and also so that
eval may be used to execute the resulting list, with the first
arg comprising the command's name and the other args comprising
its arguments. list produces slightly different results than
concat: concat removes one level of grouping before
forming the list, while list works directly from the original
arguments. For example, the command
list a b {c d e} {f {g h}}
will return
a b {c d e} {f {g h}}
while concat with the same arguments will return
a b c d e f {g h}
llength@begingroup @let@nonarrowing=@comment
llength lst
@endgroup
Treats lst as a list and returns a decimal string giving the number of elements in it.
lrange@begingroup @let@nonarrowing=@comment
lrange lst first last
@endgroup
lst must be a valid Tcl list. This command will return a new list consisting of elements first through last, inclusive. last may be `end' (or any abbreviation of it) to refer to the last element of the list. If first is less than zero, it is treated as if it were zero. If last is greater than or equal to the number of elements in the list, then it is treated as if it were `end'. If first is greater than last then an empty string is returned. Note: `lrange lst first first' does not always produce the same result as `lindex lst first' (although it often does for simple fields that aren't enclosed in braces); it does, however, produce exactly the same results as `list [lindex lst first]'.
lreplace@begingroup @let@nonarrowing=@comment
lreplace lst first last [ elt ... ]
@endgroup
lreplace returns a new list formed by replacing one or more
elements of lst with the elt arguments. first gives
the index in lst of the first element to be replaced. If
first is less than zero then it refers to the first element of
lst; the element indicated by first must exist in the list.
last gives the index in lst of the last element to be
replaced; it must be greater than or equal to first. last
may be end (or any abbreviation of it) to indicate that all elements
between first and the end of the list should be replaced. The
elt arguments specify zero or more new arguments to be added to
the list in place of those that were deleted. Each elt argument
will become a separate element of the list. If no elt arguments
are specified, then the elements between first and last are
simply deleted.
lsearch@begingroup @let@nonarrowing=@comment
lsearch [ mode ] lst ptn
@endgroup
This command searches the elements of the list lst to see if one
of them matches ptn. If so, the command returns the index of the
first matching element. If not, the command returns -1. The
mode argument indicates how the elements of the list are to be
matched against ptn and it must have one of the following values:
-exact
-glob
-regexp
regexp command.
If mode is omitted then it defaults to `-glob'.
lsort@begingroup @let@nonarrowing=@comment
lsort [ opts ] lst
@endgroup
This command sorts the elements of a list lst, returning a new list in sorted order. By default ASCII sorting is used with the result returned in increasing order. However, any of the following options may be specified before lst to control the sorting process (unique abbreviations are accepted):
-ascii
-integer
-real
-command cmd
-increasing
-decreasing
open@begingroup @let@nonarrowing=@comment
open fname [ access ] [ perm ]
@endgroup
This command opens a file and returns an identifier that may be used in
future invocations of commands like read, puts, and
close. fname gives the name of the file to open; if it
starts with a tilde then tilde substitution is performed (see section Change working directory: cd). If the first character of
fname is `|' then the remaining characters of fname are
treated as a command pipeline to invoke, in the same style as for
exec. In this case, the identifier returned by open may
be used to write to the command's input pipe or read from its output
pipe.
The access argument indicates the way in which the file (or
command pipeline) is to be accessed. It may take two forms, either a
string in the form that would be passed to the fopen library
procedure or a list of POSIX access flags. It defaults to
`r'. In the first form access may have any of the following
values:
r
r+
w
w+
a
a+
In the second form, access consists of a list of any of the
following flags, all of which have the standard POSIX meanings.
One of the flags must be either RDONLY, WRONLY or
RDWR.
RDONLY
WRONLY
RDWR
APPEND
CREAT
EXCL
CREAT is specified also, an error is returned if the file
already exists.
NOCTTY
NONBLOCK
open system call
O_NONBLOCK flag.
TRUNC
If a new file is created as part of opening it, perm (an integer)
is used to set the permissions for the new file in conjunction with the
process's file mode creation mask. perm defaults to 0666.
If a file is opened for both reading and writing then seek must be
invoked between a read and a write, or vice versa (this restriction does
not apply to command pipelines opened with open). When fname
specifies a command pipeline and a write-only access is used, then
standard output from the pipeline is directed to the current standard
output unless overridden by the command. When fname specifies a
command pipeline and a read-only access is used, then standard input
from the pipeline is taken from the current standard input unless
overridden by the command.
pid@begingroup @let@nonarrowing=@comment
pid [ fileid ]
@endgroup
If the fileid argument is given then it should normally refer to a
process pipeline created with the open command. In this case the
pid command will return a list whose elements are the process
identifiers of all the processes in the pipeline, in order. The list
will be empty if fileid refers to an open file that isn't a
process pipeline. If no fileid argument is given then pid
returns the process identifier of the current process. All process
identifiers are returned as decimal strings.
proc@begingroup @let@nonarrowing=@comment
proc pname arglist body
@endgroup
The proc command creates a new Tcl procedure named pname,
replacing any existing command or procedure there may have been by that
name. Whenever the new command is invoked, the contents of body will be
executed by the Tcl interpreter. arglist specifies the formal
arguments to the procedure. It consists of a list, possibly empty, each
of whose elements specifies one argument. Each argument specifier is
also a list, with either one or two fields. If there is only a single
field in the specifier then it is the name of the argument; if there are
two fields, then the first is the argument name and the second is its
default value.
When pname is invoked a local variable will be created for each of the
formal arguments to the procedure; its value will be the value of
corresponding argument in the invoking command or the argument's default
value. Arguments with default values need not be specified in a
procedure invocation. However, there must be enough actual arguments
for all the formal arguments that don't have defaults, and there must
not be any extra actual arguments. There is one special case to permit
procedures with variable numbers of arguments. If the last formal
argument has the name args, then a call to the procedure may contain
more actual arguments than the procedure has formals. In this case, all
of the actual arguments starting at the one that would be assigned to
args are combined into a list (as if the list command had been used);
this combined value is assigned to the local variable args.
When body is being executed, variable names normally refer to local
variables, which are created automatically when referenced and deleted
when the procedure returns. One local variable is automatically created
for each of the procedure's arguments. Global variables can only be
accessed by invoking the global command or the upvar command.
The proc command returns an empty string. When a procedure is
invoked, the procedure's result is the value specified in a
return command. If the procedure doesn't execute an explicit
return, then its result is the value of the last command executed
in the procedure's body. If an error occurs while executing the
procedure body, then the procedure as a whole will return that same
error.
puts@begingroup @let@nonarrowing=@comment
puts [ -nonewline ] [ fileid ] str
@endgroup
Writes the characters given by str to the file given by
fileid. fileid must have been the return value from a
previous call to open, or it may be stdout or
stderr to refer to one of the standard I/O channels; it must
refer to a file that was opened for writing. If no fileid is
specified then it defaults to stdout. puts normally
outputs a newline character after str, but this feature may be
suppressed by specifying the `-nonewline' switch. Output to files
is buffered internally by Tcl; the flush command may be used to
force buffered characters to be output.
pwd@begingroup @let@nonarrowing=@comment
pwd
@endgroup
Returns the path name of the current working directory.
read@begingroup @let@nonarrowing=@comment
read [ -nonewline ] fileid read fileid numbytes
@endgroup
In the first form, all of the remaining bytes are read from the file
given by fileid; they are returned as the result of the command.
If the `-nonewline' option is specified then the last character of
the file is discarded if it is a newline. In the second form, the extra
argument specifies how many bytes to read; exactly this many bytes will
be read and returned, unless there are fewer than numbytes bytes
left in the file; in this case, all the remaining bytes are returned.
fileid must be stdin or the return value from a previous
call to open; it must refer to a file that was opened for
reading. Any existing end-of-file or error condition on the file is
cleared at the beginning of the read command.
regexp@begingroup @let@nonarrowing=@comment
regexp [ opts ] rexp str [ mvar ] [ subvar ... ]
@endgroup
Determines whether the regular expression rexp matches part or all
of the string str and returns 1 if it does, 0 if it
doesn't.
If additional arguments are specified after str then they are treated as the names of variables in which to return information about which parts of str matched rexp. mvar will be set to the range of str that matched all of rexp. The first subvar will contain the characters in str that matched the leftmost parenthesized subexpression within rexp, the next subvar will contain the characters that matched the next parenthesized subexpression to the right in rexp, and so on.
If the initial arguments to regexp start with `-' then they
are treated as options. The following options are currently supported:
-nocase
-indices
--
If there are more names in the subvar list than there are parenthesized subexpressions within rexp, or if a particular subexpression in rexp doesn't match the string (e.g. because it was in a portion of the expression that wasn't matched), then the corresponding subvar will be set to `-1 -1' if `-indices' has been specified or to an empty string otherwise.
Regular expressions are implemented using Henry Spencer's package (thanks, Henry!), and much of the description of regular expressions below is copied verbatim from his reference manual entry.
A regular expression is zero or more branches, separated by `|'. It matches anything that matches one of the branches.
A branch is zero or more pieces, concatenated. It matches a match for the first, followed by a match for the second, etc.
A piece is an atom possibly followed by `*', `+', or `?'. An atom followed by `*' matches a sequence of 0 or more matches of the atom. An atom followed by `+' matches a sequence of 1 or more matches of the atom. An atom followed by `?' matches a match of the atom, or the empty string.
An atom is a regular expression in parentheses (matching a match for the regular expression), a range (see below), `.' (matching any single character), `^' (matching the empty string at the beginning of the input string), `$' (matching the empty string at the end of the input string), a `\' followed by a single character (matching that character), or a single character with no other significance (matching that character).
A range is a sequence of characters enclosed in `[]'. It normally matches any single character from the sequence. If the sequence begins with `^', it matches any single character not from the rest of the sequence. If two characters in the sequence are separated by `-', this is shorthand for the full list of ASCII characters between them (e.g. `[0-9]' matches any decimal digit). To include a literal `]' in the sequence, make it the first character (following a possible `^'). To include a literal `-', make it the first or last character.
In general there may be more than one way to match a regular expression to an input string. For example, consider the command
regexp (a*)b* aabaaabb x y
Considering only the rules given so far, x and y could end
up with the values `aabb' and `aa', `aaab' and
`aaa', `ab' and `a', or any of several other
combinations. To resolve this potential ambiguity regexp chooses among
alternatives using the rule "first then longest". In other words, it
consders the possible matches in order working from left to right across
the input string and the pattern, and it attempts to match longer pieces
of the input string before shorter ones. More specifically, the
following rules apply in decreasing order of priority:
In the example above, `(a*)b*' matches `aab': the `(a*)' portion of the pattern is matched first and it consumes the leading `aa'; then the `b*' portion of the pattern consumes the next `b'. Or consider the following example:
regexp (ab|a)(b*)c abc x y z
After this command x will be `abc', y will be
`ab', and z will be an empty string. Rule 4 specifies that
`(ab|a)' gets first shot at the input string and Rule 2 specifies
that the `ab' subexpression is checked before the `a'
sub-expression. Thus the `b' has already been claimed before the
`(b*)' component is checked and `(b*)' must match an empty
string.
regsub@begingroup @let@nonarrowing=@comment
regsub [ opts ] rexp str repl varname
@endgroup
This command matches the regular expression rexp against
str, and it copies str to the variable whose name is given
by varname. The command returns 1 if there is a match and
0 if there isn't. If there is a match, then while copying
str to varname the portion of str that matched
rexp is replaced with repl. If repl contains a
`&' or `\0', that character or string is replaced in the
substitution with the portion of str that matched rexp. If
repl contains a `\n', where n is a digit between
1 and 9, then it is replaced in the substitution with the portion of
str that matched the nth parenthesized subexpression of
rexp. Additional backslashes may be used in repl to prevent
special interpretation of `&' or `\0' or `\n' or
backslash. The use of backslashes in repl tends to interact badly
with the Tcl parser's use of backslashes, so it's generally safest to
enclose repl in braces if it includes backslashes.
If the initial arguments to regsub start with `-' then they
are treated as options. The following options are currently supported:
-all
-nocase
--
See section Match a regular expression: regexp, for details on
the interpretation of regular expressions.
rename@begingroup @let@nonarrowing=@comment
rename oldname newname
@endgroup
Rename the command that used to be called oldname so that it is
now called newname. If newname is an empty string then
oldname is deleted. The rename command returns an empty
string as result.
return@begingroup @let@nonarrowing=@comment
return [ -code c ] [ -errorinfo i ] [ -errorcode e ] [ str ]
@endgroup
Return immediately from the current procedure (or top-level command or source command), with str as the return value. If str is not specified then an empty string will be returned as result.
Exceptional returns. In the usual case where the `-code'
option isn't specified the procedure will return normally (its
completion code will be TCL_OK). However, the `-code
c' option may be used to generate an exceptional return from the
procedure. c may have any of the following values:
ok
error
error command were used to terminate
the procedure, except for handling of errorInfo and
errorCode variables (see below).
return
TCL_RETURN, so that the procedure that invoked it will return
also.
break
TCL_BREAK, which will terminate the innermost nested loop in the
code that invoked the current procedure.
continue
TCL_CONTINUE, which will terminate the current iteration of the
innermost nested loop in the code that invoked the current procedure.
val
The `-code' option is rarely used. It is provided so that procedures that implement new control structures can reflect exceptional conditions back to their callers.
Two additional options, `-errorinfo' and `-errorcode', may be used to provide additional information during error returns. These options are ignored unless you specify `-code error'.
The `-errorinfo i' option specifies an initial stack trace
for the errorInfo variable; if it is not specified then the stack
trace left in errorInfo will include the call to the procedure
and higher levels on the stack but it will not include any information
about the context of the error within the procedure. Typically the
i value is supplied from the value left in errorInfo after
a catch command trapped an error within the procedure.
If the `-errorcode e' option is specified then e
provides a value for the errorCode variable. If the option is
not specified then errorCode will default to `NONE'.
sscanf: scan@begingroup @let@nonarrowing=@comment
scan str fmt varname [ varname ... ]
@endgroup
This command parses fields from an input string in the same fashion as
the ANSI C sscanf procedure and returns a count of the
number of fields sucessfully parsed. str gives the input to be
parsed and fmt indicates how to parse it, using `%'
conversion specifiers as in sscanf. Each varname gives the
name of a variable; when a field is scanned from str the result is
converted back into a string and assigned to the corresponding variable.
Details on scanning. scan operates by scanning str
and fmt together. If the next character in fmt is a blank
or tab then it is ignored. Otherwise, if it isn't a `%' character
then it must match the next non-white-space character of str.
When a `%' is encountered in fmt, it indicates the start of a
conversion specifier. A conversion specifier contains up to three
fields after the `%': a `*', which indicates that the
converted value is to be discarded instead of assigned to a variable; a
number indicating a maximum field width; and a conversion character.
All of these fields are optional except for the conversion character.
When scan finds a conversion specifier in fmt, it first skips any
white-space characters in str. Then it converts the next input
characters according to the conversion specifier and stores the result
in the variable given by the next argument to scan. The
following conversion characters are supported:
d
o
x
c
s
e
f
g
[chars]
[^chars]
The number of characters read from the input for a conversion is the largest number that makes sense for that particular conversion (e.g. as many decimal digits as possible for `%d', as many octal digits as possible for `%o', and so on). The input field for a given conversion terminates either when a white-space character is encountered or when the maximum field width has been reached, whichever comes first. If a `*' is present in the conversion specifier then no variable is assigned and the next scan argument is not consumed.
Differences from ANSI sscanf.
The behavior of the scan command is the same as the behavior of the
ANSI C sscanf function except for these differences:
double is used for the internal
representation).
seek@begingroup @let@nonarrowing=@comment
seek fileid offset [ origin ]
@endgroup
Change the current access position for fileid. fileid must
be the return value from a previous call to open, or it may be
stdin, stdout, or stderr to refer to one of the
standard I/O channels. The offset and origin arguments
specify the position at which the next read or write will occur for
fileid. offset must be an integer (which may be negative)
and origin must be one of the following:
start
current
end
The origin argument defaults to start. This command
returns an empty string.
set@begingroup @let@nonarrowing=@comment
set varname [ val ]
@endgroup
Returns the value of variable varname. If val is specified, then set the value of varname to val, creating a new variable if one doesn't already exist, and return its value. If varname contains an open parenthesis and ends with a close parenthesis, then it refers to an array element: the characters before the first open parenthesis are the name of the array, and the characters between the parentheses are the index within the array. Otherwise varname refers to a scalar variable. If no procedure is active, then varname refers to a global variable. If a procedure is active, then varname refers to a parameter or local variable of the procedure unless the global command has been invoked to declare varname to be global.
source@begingroup @let@nonarrowing=@comment
source fname
@endgroup
Read file fname and pass the contents to the Tcl interpreter as a
script to evaluate in the normal fashion. The return value from source
is the return value of the last command executed from the file. If an
error occurs in evaluating the contents of the file then the source
command will return that error. If a return command is invoked from
within the file then the remainder of the file will be skipped and the
source command will return normally with the result from the return
command. If fname starts with a tilde, then it is tilde-substituted
as described in section Change working directory: cd.
split@begingroup @let@nonarrowing=@comment
split str [ splitchars ]
@endgroup
Returns a list created by splitting a string str at each character that is in the splitchars argument. Each element of the result list will consist of the characters from str that lie between instances of the characters in splitchars. Empty list elements will be generated if str contains adjacent characters in splitchars, or if the first or last character of str is in splitchars. If splitchars is an empty string then each character of str becomes a separate element of the result list. splitchars defaults to the standard white-space characters. For example,
split "comp.unix.misc" .
returns `comp unix misc' and
split "Hello world" {}
returns `H e l l o { } w o r l d'.
string@begingroup @let@nonarrowing=@comment
string op arg [ arg ... ]
@endgroup
Performs one of several string operations, depending on op. The recognized alternatives for op (which may be abbreviated) are:
string compare str1 str2
strcmp procedure. Return
-1, 0, or 1, depending on whether str1 is
lexicographically less than, equal to, or greater than str2.
string first str1 str2
-1.
string index str charix
string last str1 str2
-1.
string length str
string match ptn str
1 if it does, 0 if it doesn't. Matching is done in a
fashion similar to that used by the C-shell. For the two strings to
match, their contents must be identical except that the following
special sequences may appear in ptn:
*
?
[chars]
x-y appears in chars, then any character
between x and y, inclusive, will match.
\x
string range str first last
0 refers to the first
character of the string. last may be end (or any
abbreviation of it) to refer to the last character of the string. If
first is less than zero then it is treated as if it were zero, and
if last is greater than or equal to the length of the string then
it is treated as if it were end. If first is greater than
last then an empty string is returned.
string tolower str
string toupper str
string trim str [ chars ]
string trimleft str [ chars ]
string trimright str [ chars ]
switch@begingroup @let@nonarrowing=@comment
switch [ opts ] str ptn body [ ptn body ... ]
switch [ opts ] str {ptn body [ ptn body ... ] }
@endgroup
The switch command matches its str argument against each of
the patterns in the ptn arguments, in the order specified. As
soon as it finds a pattern that matches str it evaluates the
following body argument by passing it recursively to the Tcl
interpreter and returns the result of that evaluation. If the last
ptn argument is default then it matches anything. If no
ptn argument matches str and no default is given,
then the switch command returns an empty string.
If the initial arguments to switch start with `-' then they
are treated as options. The following options are currently recognized:
-exact
-glob
-regexp
regexp command).
--
Two syntaxes are provided for the ptn and body arguments.
The first uses a separate argument for each of the patterns and
commands; this form is convenient if substitutions are desired on some
of the patterns or commands. The second form places all of the patterns
and commands together into a single argument; the argument must have
proper list structure, with the elements of the list being the patterns
and commands. The second form makes it easy to construct multi-line
switch commands, since the braces around the whole list make it
unnecessary to include a backslash at the end of each line. Since the
ptn arguments are in braces in the second form, no command or
variable substitutions are performed on them; this makes the behavior of
the second form different than the first form in some cases.
If a body is specified as `-' it means that the body for the next pattern should also be used as the body for this pattern (if the next pattern also has a body of `-' then the body after that is used, and so on). This feature makes it possible to share a single body among several patterns.
Below are some examples of switch commands:
switch abc a - b {format 1} abc {format 2} default {format 3}
will return 2,
switch -regexp aaab {
^a.*b$ -
b {format 1}
a* {format 2}
default {format 3}
}
will return 1, and
switch xyz {
a
-
b
{format 1}
a*
{format 2}
default
{format 3}
}
will return 3.
tell@begingroup @let@nonarrowing=@comment
tell fileid
@endgroup
Returns a decimal string giving the current access position in
fileid. fileid must be the return value from a previous
call to open, or it may be stdin, stdout, or
stderr to refer to one of the standard I/O channels.
time@begingroup @let@nonarrowing=@comment
time script [ n ]
@endgroup
This command will call the Tcl interpreter n times to evaluate script (or once if n isn't specified). It will then return a string of the form
503 microseconds per iteration
which indicates the average amount of time required per iteration, in microseconds. Time is measured in elapsed time, not CPU time.
trace@begingroup @let@nonarrowing=@comment
trace option [ arg ... ]
@endgroup
This command causes Tcl commands to be executed whenever certain operations are invoked. At present, only variable tracing is implemented. The recognized options (which may be abbreviated) are:
trace variable name ops cmd
r
w
u
unset command, or implicitly when procedures
return (all of their local variables are unset). Variables are also
unset when interpreters are deleted, but traces will not be invoked then
because there is no interpreter in which to execute them.
cmd name1 name2 opname1 and name2 give the name(s) for the variable being accessed: if the variable is a scalar then name1 gives the variable's name and name2 is an empty string; if the variable is an array element then name1 gives the name of the array and name2 gives the index into the array; if an entire array is being deleted and the trace was registered on the overall array, rather than a single element, then name1 gives the array name and name2 is an empty string. op indicates what operation is being performed on the variable, and is one of `r', `w', or `u' as defined above. cmd executes in the same context as the code that invoked the traced operation: if the variable was accessed as part of a Tcl procedure, then cmd will have access to the same local variables as code in the procedure. This context may be different than the context in which the trace was created. If cmd invokes a procedure (which it normally does) then the procedure will have to use
upvar or uplevel if it wishes to access the traced
variable. Note also that name1 may not necessarily be the same as
the name used to set the trace on the variable; differences can occur if
the access is made through a variable defined with the upvar
command.
For read and write traces, cmd can modify the variable to affect the
result of the traced operation. If cmd modifies the value of a
variable during a read or write trace, then the new value will be
returned as the result of the traced operation. The return value from
cmd is ignored except that if it returns an error of any sort then
the traced operation also returns an error with the same error message
returned by the trace command (this mechanism can be used to implement
read-only variables, for example). For write traces, cmd is invoked
after the variable's value has been changed; it can write a new value
into the variable to override the original value specified in the write
operation. To implement read-only variables, cmd will have to
restore the old value of the variable.
While cmd is executing during a read or write trace, traces on the
variable are temporarily disabled. This means that reads and writes
invoked by cmd will occur directly, without invoking cmd (or any
other traces) again. However, if cmd unsets the variable then unset
traces will be invoked.
When an unset trace is invoked, the variable has already been deleted:
it will appear to be undefined with no traces. If an unset occurs
because of a procedure return, then the trace will be invoked in the
variable context of the procedure being returned to: the stack frame of
the returning procedure will no longer exist. Traces are not disabled
during unset traces, so if an unset trace command creates a new trace
and accesses the variable, the trace will be invoked. Any errors in
unset traces are ignored.
If there are multiple traces on a variable they are invoked in order of
creation, most-recent first. If one trace returns an error, then no
further traces are invoked for the variable. If an array element has a
trace set, and there is also a trace set on the array as a whole, the
trace on the overall array is invoked before the one on the element.
Once created, the trace remains in effect either until the trace is
removed with the `trace vdelete' command described below, until the
variable is unset, or until the interpreter is deleted. Unsetting an
element of array will remove any traces on that element, but will not
remove traces on the overall array.
This command returns an empty string.
trace vdelete name ops cmd
trace vinfo name
unknown@begingroup @let@nonarrowing=@comment
unknown cmd [ arg ... ]
@endgroup
This command doesn't actually exist as part of Tcl, but Tcl will invoke
it if it does exist. If the Tcl interpreter encounters a command name
for which there is not a defined command, then Tcl checks for the
existence of a command named unknown. If there is no such
command, then the interpreter returns an error. If the unknown
command exists, then it is invoked with arguments consisting of the
fully-substituted name and arguments for the original non-existent
command. The unknown command typically does things like
searching through library directories for a command procedure with the
name cmd, or expanding abbreviated command names to full-length,
or automatically executing unknown commands as sub-processes. In some
cases (such as expanding abbreviations) unknown will change the
original command slightly and then (re-)execute it. The result of the
unknown command is used as the result for the original
non-existent command.
unset@begingroup @let@nonarrowing=@comment
unset varname [ varname ... ]
@endgroup
This command removes one or more variables. Each varname is a
variable name, specified in any of the ways acceptable to the set
command. If a varname refers to an element of an array then that
element is removed without affecting the rest of the array. If a
varname consists of an array name with no parenthesized index,
then the entire array is deleted. The unset command returns an
empty string as result. An error occurs if any of the variables doesn't
exist, and any variables after the non-existent one are not deleted.
uplevel@begingroup @let@nonarrowing=@comment
uplevel [ lev ] arg [ arg ... ]
@endgroup
All of the arg arguments are concatenated as if they had been
passed to concat; the result is then evaluated in the variable
context indicated by lev. uplevel returns the result of
that evaluation.
If lev is an integer then it gives a distance (up the procedure calling stack) to move before executing the command. If lev consists of `#' followed by a number then the number gives an absolute level number. If lev is omitted then it defaults to 1. lev cannot be defaulted if the first command argument starts with a digit or `#'.
For example, suppose that procedure a was invoked from top-level,
and that it called b, and that b called c. Suppose
that c invokes the uplevel command. If lev is
1 or #2 or omitted, then the command will be executed in
the variable context of b. If lev is 2 or #1
then the command will be executed in the variable context of a.
If lev is 3 or #0 then the command will be executed
at top-level (only global variables will be visible).
The uplevel command causes the invoking procedure to disappear
from the procedure calling stack while the command is being executed.
In the above example, suppose c invokes the command
uplevel 1 {set x 43; d}
where d is another Tcl procedure. The set command will
modify the variable x in the context of b, and d
will execute at level 3, as if called from b. If it in turn
executes the command
uplevel {set x 42}
then the set command will modify the same variable x in
the context of b: the procedure c does not appear to be on
the call stack when d is executing. The command `info
level' may be used to obtain the level of the current procedure.
uplevel makes it possible to implement new control constructs as
Tcl procedures (for example, uplevel could be used to implement
the while construct as a Tcl procedure).
upvar@begingroup @let@nonarrowing=@comment
upvar [ lev ] other mine [ other mine ... ]
@endgroup
This command arranges for one or more local variables in the current
procedure to refer to variables in an enclosing procedure call or to
global variables. lev may have any of the forms permitted for the
uplevel command, and may be omitted if the first letter of the
first other isn't `#' or a digit (it defaults to 1). For
each other argument, upvar makes the variable by that name
in the procedure frame given by lev (or at global level, if
lev is #0) accessible in the current procedure by the name given
in the corresponding mine argument. The variable named by
other need not exist at the time of the call; it will be created
the first time mine is referenced, just like an ordinary variable.
upvar may only be invoked from within procedures. mine may
not refer to an element of an array, but other may refer to an
array element. upvar returns an empty string.
The upvar command simplifies the implementation of call-by-name
procedure calling and also makes it easier to build new control
constructs as Tcl procedures. For example, consider the following
procedure:
proc add2 name {
upvar $name x
set x [expr $x+2]
}
add2 is invoked with an argument giving the name of a variable,
and it adds two to the value of that variable. Although add2
could have been implemented using uplevel instead of
upvar, upvar makes it simpler for add2 to access
the variable in the caller's procedure frame.
If an upvar variable is unset (e.g. x in add2
above), the unset operation affects the variable it is linked to, not
the upvar variable. There is no way to unset an upvar
variable except by exiting the procedure in which it is defined.
However, it is possible to retarget an upvar variable by
executing another upvar command.
while@begingroup @let@nonarrowing=@comment
while tst body
@endgroup
The while command evaluates tst as an expression
(see section Writing expressions in Tcl). The value of the
expression must a proper Boolean value; if it is a true value then
body is executed by passing it to the Tcl interpreter. Once
body has been executed then tst is evaluated again, and the
process repeats until eventually tst evaluates to a false Boolean
value. continue commands may be executed inside body to
terminate the current iteration of the loop, and break commands
may be executed inside body to cause immediate termination of the
while command. The while command always returns an empty
string.
The following global variables are created and managed automatically by Tcl. Except where noted below, these variables should normally be treated as read-only by application-specific code and by users.
env
env will remove the corresponding environment variable. Changes
to the env array will affect the environment passed to children
by commands like exec. If the entire env array is unset
then Tcl will stop monitoring env accesses and will not update
environment variables.
errorCode
errorCode consists of a Tcl list with one or more
elements. The first element of the list identifies a general class of
errors, and determines the format of the rest of the list. The
following formats for errorCode are used by the Tcl core;
individual applications may define additional formats.
ARITH code msg
expr command). code identifies the
precise error and msg provides a human-readable description of the
error. code will be either DIVZERO (for an attempt to
divide by zero), DOMAIN (if an argument is outside the domain of
a function, such as `acos(-3)'), IOVERFLOW (for integer
overflow), OVERLFLOW (for a floating-point overflow), or
UNKNOWN (if the cause of the error cannot be determined).
CHILDKILLED pid signame msg
errorCode will be the process
identifier (in decimal). The third element will be the symbolic name of
the signal that caused the process to terminate; it will be one of the
names from the include file `signal.h', such as SIGPIPE.
The fourth element will be a short human-readable message describing the
signal, such as `write on pipe with no readers' for SIGPIPE.
CHILDSTATUS pid code
errorCode will be the process
identifier (in decimal) and the third element will be the exit code
returned by the process (also in decimal).
CHILDSUSP pid signame msg
errorCode will be the process
identifier, in decimal. The third element will be the symbolic name of
the signal that caused the process to suspend; this will be one of the
names from the include file `signal.h', such as SIGTTIN.
The fourth element will be a short human-readable message describing the
signal, such as `background tty read' for SIGTTIN.
NONE
errorCode will consist of a list containing a single
element whose contents are NONE.
POSIX errname msg
errorCode is POSIX, then the error
occurred during a POSIX kernel call. The second element of the
list will contain the symbolic name of the error that occurred, such as
ENOENT; this will be one of the values defined in the include
file `errno.h'. The third element of the list will be a
human-readable message corresponding to errname, such as `no
such file or directory' for the ENOENT case.
errorCode, applications may invoke the error
command (or an equivalent Tcl library subroutine). Otherwise the Tcl
interpreter will reset the variable to NONE after the next error.
errorInfo
tcl_precision
Tcl includes a library of Tcl procedures for commonly-needed functions.
The procedures defined in the Tcl library are generic ones suitable for
use by many different applications. The location of the Tcl library is
returned by the `info library' command. In addition to the Tcl
library, each application will normally have its own library of support
procedures as well; the location of this library is normally given by
the value of the app_library global variable, where
app is the name of the application. For example, the location of
the Tk library is kept in the variable tk_library.
To access the procedures in the Tcl library, an application should run the file `init.tcl' in the library, for example with the Tcl command
source [info library]/init.tcl
This will define the unknown procedure and arrange for the other
procedures to be loaded on demand using the auto-load mechanism defined
below.
The following procedures are provided in the Tcl library:
auto_execok cmd
PATH environment variable) to see if there is an
executable file named cmd in any of those directories. If so, it
returns 1; if not it returns 0. auto_execok
remembers information about previous searches in an array named
auto_execs; this avoids the path search in future calls for the
same cmd. The command auto_reset may be used to force
auto_execok to forget its cached information.
auto_load cmd
auto_path if it exists. If there is no auto_path
variable, then the TCLLIBPATH environment variable is used, if it
exists. Otherwise the auto-load path consists of just the Tcl library
directory. Within each directory in the auto-load path there must be a
file `tclIndex' that describes one or more commands defined in that
directory and a script to evaluate to load each of the commands. The
`tclIndex' file should be generated with the auto_mkindex
command. If cmd is found in an index file, then the appropriate
script is evaluated to create the command. The auto_load command
returns 1 if cmd was successfully created. The command
returns 0 if there was no index entry for cmd or if the
script didn't actually define cmd (e.g. because index information
is out of date). If an error occurs while processing the script, then
that error is returned. auto_load only reads the index
information once and saves it in the array auto_index; future
calls to auto_load check for cmd in the array rather than
rereading the index files. The cached index information may be deleted
with the command auto_reset. This will force the next
auto_load command to reload the index database from disk.
auto_mkindex dir ptn [ ptn ... ]
auto_load. The command
searches dir for all files whose names match any of the ptn
arguments (matching is done with the glob command), generates an
index of all the Tcl command procedures defined in all the matching
files, and stores the index information in a file named `tclIndex'
in dir. For example, the command
auto_mkindex foo *.tclwill read all the `.tcl' files in subdirectory `foo' and generate a new index file `foo/tclIndex'.
auto_mkindex parses the Tcl scripts in a relatively
unsophisticated way: if any line contains the word proc as its
first characters then it is assumed to be a procedure definition and the
next word of the line is taken as the procedure's name. Procedure
definitions that don't appear in this way (e.g. they have spaces before
the proc) will not be indexed.
auto_reset
auto_execok and
auto_load. This information will be re-read from disk the next
time it is needed. auto_reset also deletes any procedures listed
in the auto-load index, so that fresh copies of them will be loaded the
next time that they're used.
parray arrayname
parray. It may be either local or global.
unknown cmd [ arg ... ]
auto_load to load the command. If this succeeds,
then it executes the original command with its original arguments. If
the auto-load fails then unknown calls auto_execok to see if
there is an executable file by the name cmd. If so, it invokes
the Tcl exec command with cmd and all the instances of
arg as arguments. If cmd can't be auto-executed,
unknown checks to see if the command was invoked at top-level and
outside of any script. If so, then unknown takes takes two
additional steps. First, it sees if cmd has one of the following
three forms: `!!', `!event', or
`^old^new[^]'. If so, then unknown
carries out history substitution in the same way that csh would
for these constructs. Second, and last, unknown checks to see if
cmd is a unique abbreviation for an existing Tcl command. If so,
it expands the command name and executes the command with the original
arguments. If none of the above efforts is able to execute the command,
unknown generates an error return. If the global variable
auto_noload is defined, then the auto-load step is skipped. If
the global variable auto_noexec is defined then the auto-exec
step is skipped. Under normal circumstances the return value from
unknown is the return value from the command that was eventually
executed.
The following global variables are defined or used by the procedures in the Tcl library:
auto_execs
auto_execok to record information about whether
particular commands exist as executable files.
auto_index
auto_load to save the index information read from disk.
auto_noexec
unknown will not attempt to auto-exec
any commands.
auto_noload
unknown will not attempt to auto-load
any commands.
auto_path
env(TCL_LIBRARY)
env(TCLLIBPATH)
auto_path is not defined.
unknown_active
unknown to indicate that it is active.
It is used to detect errors where unknown recurses on itself
infinitely. The variable is unset before unknown returns.