Tcl stands for ``tool command language'' and is pronounced ``tickle.'' It is actually two things: a language and a library. First, Tcl is a simple textual language, intended primarily for issuing commands to interactive programs such as text editors, debuggers, illustrators, and shells. It has a simple syntax and is also programmable, so Tcl users can write command procedures to provide more powerful commands than those in the built-in set.
Second, Tcl is a library package that can be embedded in application programs. The Tcl library consists of a parser for the Tcl language, routines to implement the Tcl built-in commands, and procedures that allow each application to extend Tcl with additional commands specific to that application. The application program generates Tcl commands and passes them to the Tcl parser for execution. Commands may be generated by reading characters from an input source, or by associating command strings with elements of the application's user interface, such as menu entries, buttons, or keystrokes. When the Tcl library receives commands it parses them into component fields and executes built-in commands directly. For commands implemented by the application, Tcl calls back to the application to execute the commands. In many cases commands will invoke recursive invocations of the Tcl interpreter by passing in additional strings to execute (procedures, looping commands, and conditional commands all work in this way).
An application program gains three advantages by using Tcl for its command language. First, Tcl provides a standard syntax: once users know Tcl, they will be able to issue commands easily to any Tcl-based application. Second, Tcl provides programmability. All a Tcl application needs to do is to implement a few application-specific low-level commands. Tcl provides many utility commands plus a general programming interface for building up complex command procedures. By using Tcl, applications need not re-implement these features. Third, Tcl can be used as
a common language for communicating between applications. Inter-application communication is not built into the Tcl core described here, but various add-on libraries, such as the Tk toolkit, allow applications to issue commands to each other. This makes it possible for applications to work together in much more powerful ways than was previously possible.
This manual page focuses primarily on the Tcl language. It describes the language syntax and the built-in commands that will be available in any application based on Tcl. The individual library procedures are described in more detail in separate manual pages, one per procedure.
Tcl supports only one type of data: strings. All commands, all arguments to commands, all command results, and all variable values are strings. Where commands require numeric arguments or return numeric results, the arguments and results are passed as strings. Many commands expect their string arguments to have certain formats, but this interpretation is up to the individual commands. For example, arguments often contain Tcl command strings, which may get executed as part of the commands. The easiest way to understand the Tcl interpreter is to remember that everything is just an operation on a string. In many cases Tcl constructs will look similar to more structured constructs from other languages. However, the Tcl constructs are not structured at all; they are just strings of characters, and this gives them a different behavior than the structures they may look like.
Although the exact interpretation of a Tcl string depends on who is doing the interpretation, there are three common forms that strings take: commands, expressions, and lists. The major sections below discuss these three forms in more detail.
The Tcl language has syntactic similarities to both the Unix shells and Lisp. However, the interpretation of commands is different in Tcl than in either of those other two systems. A Tcl command string consists of one or more commands separated by newline characters or semi-colons. Each command consists of a collection of fields separated by white space (spaces or tabs). The first field must be the name of a command, and the additional fields, if any, are arguments that will be passed to that command. For example, the command
set a 22
has three fields: the first, set, is the name of a Tcl command, and the last two, a and 22, will be passed as arguments to the set command. The command name may refer either to a built-in Tcl command, an application-specific command bound in with the library procedure Tcl_CreateCommand, or a command procedure defined with the proc built-in command. Arguments are passed literally as text strings. Individual commands may interpret those strings in any fashion they wish. The set command, for example, will treat its first argument as the name of a variable and its second argument as a string value to assign to that variable. For other commands arguments may be interpreted as integers, lists, file names, or Tcl commands.
"COMMENTS"
If the first non-blank character in a command is #, then everything from the # up through the next newline character is treated as a comment and ignored. When comments are embedded inside nested commands (e.g. fields enclosed in braces) they must have properly-matched braces (this is necessary because when Tcl parses the top-level command it doesn't yet know that the nested field will be used as a command so it cannot process the nested comment character as a comment).
"GROUPING ARGUMENTS WITH DOUBLE-QUOTES"
Normally each argument field ends at the next white space, but double-quotes may be used to create arguments with embedded space. If an argument field begins with a double-quote, then the argument isn't terminated by white space (including newlines) or a semi-colon (see below for information on semi-colons); instead it ends at the next double-quote character. The double-quotes are not included in the resulting argument. For example, the command
set a "This is a single argument"
will pass two arguments to set: a and This is a single argument. Within double-quotes, command substitutions, variable substitutions, and backslash substitutions still occur, as described below. If the first character of a command field is not a quote, then quotes receive no special interpretation in the parsing of that field.
"GROUPING ARGUMENTS WITH BRACES"
Curly braces may also be used for grouping arguments. They are similar to quotes except for two differences. First, they nest; this makes them easier to use for complicated arguments like nested Tcl command strings. Second, the substitutions described below for commands, variables, and backslashes do not occur in arguments enclosed in braces, so braces can be used to prevent substitutions where they are undesirable. If an argument field begins with a left brace, then the argument ends at the matching right brace. Tcl will strip off the outermost layer of braces and pass the information between the braces to the command without any further modification. For example, in the command
set a {xyz a {b c d}}
the set command will receive two arguments: a and xyz a {b c d}.
When braces or quotes are in effect, the matching brace or quote need not be on the same line as the starting quote or brace; in this case the newline will be included in the argument field along with any other characters up to the matching brace or quote. For example, the eval command takes one argument, which is a command string; eval invokes the Tcl interpreter to execute the command string. The command
eval { set a 22 set b 33 }
will assign the value 22 to a and 33 to b.
If the first character of a command field is not a left brace, then neither left nor right braces in the field will be treated specially (except as part of variable substitution; see below).
"COMMAND SUBSTITUTION WITH BRACKETS"
If an open bracket occurs in a field of a command, then command substitution occurs (except for fields enclosed in braces). All of the text up to the matching close bracket is treated as a Tcl command and executed immediately. Then the result of that command is substituted for the bracketed text. For example, consider the command
set a [set b]
When the set command has only a single argument, it is the name of a variable and set returns the contents of that variable. In this case, if variable b has the value foo, then the command above is equivalent to the command
set a foo
Brackets can be used in more complex ways. For example, if the variable b has the value foo and the variable c has the value gorp, then the command
set a xyz[set b].[set c]
is equivalent to the command
set a xyzfoo.gorp
A bracketed command may contain multiple commands separated by newlines or semi-colons in the usual fashion. In this case the value of the last command is used for substitution. For example, the command
set a x[set b 22 expr $b+2]x
is equivalent to the command
set a x24x
If a field is enclosed in braces then the brackets and the characters between them are not interpreted specially; they are passed through to the argument verbatim.
"VARIABLE SUBSTITUTION WITH $"
The dollar sign ($) may be used as a special shorthand form for substituting variable values. If $ appears in an argument that isn't enclosed in braces then variable substitution will occur. The characters after the $, up to the first character that isn't a number, letter, or underscore, are taken as a variable name and the string value of that variable is substituted for the name.
For example, if variable foo has the value test, then the command C set a $foo.c
is equivalent to the command C set a test.c
There are two special forms for variable substitution. If the next character after the name of the variable is an open parenthesis, then the variable is assumed to be an array name, and all of the characters between the open parenthesis and the next close parenthesis are taken as an index into the array. Command substitutions and variable substitutions are performed on the information between the parentheses before it is used as an index. For example, if the variable x is an array with one element named first and value 87 and another element named 14 and value more, then the command C set a xyz$x(first)zyx
is equivalent to the command C set a xyz87zyx
If the variable index has the value 14, then the command C set a xyz$x($index)zyx
is equivalent to the command C set a xyzmorezyx
For more information on arrays, see VARIABLES AND ARRAYS below.
The second special form for variables occurs when the dollar sign is followed by an open curly brace. In this case the variable name consists of all the characters up to the next curly brace. Array references are not possible in this form: the name between braces is assumed to refer to a scalar variable. For example, if variable foo has the value test, then the command C set a abc${foo}bar
is equivalent to the command C set a abctestbar
Variable substitution does not occur in arguments that are enclosed in braces: the dollar sign and variable name are passed through to the argument verbatim.
The dollar sign abbreviation is simply a shorthand form. $a is completely equivalent to [set a]; it is provided as a convenience to reduce typing.
"SEPARATING COMMANDS WITH SEMI-COLONS"
Normally, each command occupies one line (the command is terminated by a newline character). However, semi-colon (``;'') is treated as a command separator character; multiple commands may be placed on one line by separating them with a semi-colon. Semi-colons are not treated as command separators if they appear within curly braces or double-quotes.
"BACKSLASH SUBSTITUTION"
Backslashes may be used to insert non-printing characters into
command fields and also to insert special characters like
braces and brackets into fields
without them being interpreted specially as described above.
The backslash sequences understood by the Tcl interpreter are
listed below. In each case, the backslash
sequence is replaced by the given character:
\b
Backspace (0x8).
\f
Form feed (0xc).
\n
Newline (0xa).
\r
Carriage-return (0xd).
\t
Tab (0x9).
\v
Vertical tab (0xb).
\{
Left brace (``{'').
\}
Right brace (``}'').
\[
Open bracket (``['').
\]
Close bracket (``]'').
\$
Dollar sign (``$'').
\
\;
Semi-colon: doesn't terminate command.
\"
Double-quote.
\
For example, in the command
set a \{x\[\\0yz\141
the second argument to set will be ``{x[\0yza''.
If a backslash is followed by something other than one of the options
described above, then the backslash is transmitted to the argument
field without any special processing, and the Tcl scanner continues
normal processing with the next character. For example, in the
command
set \*a \\\{foo
The first argument to set will be \*a and the second
argument will be \{foo.
If an argument is enclosed in braces, then backslash sequences inside
the argument are parsed but no substitution occurs (except for
backslash-newline): the backslash
sequence is passed through to the argument as is, without making
any special interpretation of the characters in the backslash sequence.
In particular, backslashed braces are not counted in locating the
matching right brace that terminates the argument.
For example, in the
command
set a {\{abc}
the second argument to set will be \{abc.
This backslash mechanism is not sufficient to generate absolutely
any argument structure; it only covers the
most common cases. To produce particularly complicated arguments
it is probably easiest to use the format command along with
command substitution.
[1] A command is just a string.
[2] Within a string commands are separated by newlines or semi-colons
(unless the newline or semi-colon is within braces or brackets
or is backslashed).
[3] A command consists of fields. The first field is the name of the command.
The other fields are strings that are passed to that command as arguments.
[4] Fields are normally separated by white space.
[5] Double-quotes allow white space and semi-colons to appear within
a single argument.
Command substitution, variable substitution, and backslash substitution
still occur inside quotes.
[6] Braces defer interpretation of special characters.
If a field begins with a left brace, then it consists of everything
between the left brace and the matching right brace. The
braces themselves are not included in the argument.
No further processing is done on the information between the braces
except that backslash-newline sequences are eliminated.
[7] If a field doesn't begin with a brace then backslash,
variable, and command substitution are done on the field. Only a
single level of processing is done: the results of one substitution
are not scanned again for further substitutions or any other
special treatment. Substitution can
occur on any field of a command, including the command name
as well as the arguments.
[8] If the first non-blank character of a command is a #, everything
from the # up through the next newline is treated as a comment
and ignored.
The second major interpretation applied to strings in Tcl is
as expressions. Several commands, such as expr, for,
and if, treat one or more of their arguments as expressions
and call the Tcl expression processors (Tcl_ExprLong,
Tcl_ExprBoolean, etc.) to evaluate them.
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
8.2 + 6
evaluates to 14.2.
Tcl expressions differ from C expressions in the way that
operands are specified, and in that Tcl expressions support
non-numeric operands and string comparisons.
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.
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:
[1] As an numeric value, either integer or floating-point.
[2] As a Tcl variable, using standard $ notation.
The variable's value will be used as the operand.
[3] As a string enclosed in double-quotes.
The expression parser will perform backslash, variable, and
command substitutions on the information between the quotes,
and use the resulting value as the operand
[4] As a string enclosed in braces.
The characters between the open brace and matching close brace
will be used as the operand without any substitutions.
[5] As a Tcl command enclosed in brackets.
The command will be executed and its result will be used 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.
For some examples of simple expressions, suppose the variable
a has the value 3 and
the variable b has the value 6.
Then the expression on the left side of each of the lines below
will evaluate to the value on the right side of the line:
3.1 + $a 6.1
2 + "$a.$b" 5.6
4*[llength "6 2"] 8
{word one} < "word $a" 0
The valid operators are listed below, grouped in decreasing order
of precedence:
- ~ !.
Unary minus, bit-wise NOT, logical NOT. None of these operands
may be applied to string operands, and bit-wise NOT may be
applied only to integers.
* / %
Multiply, divide, remainder. None of these operands may be
applied to string operands, and remainder may be applied only
to integers.
+ -
Add and subtract. Valid for any numeric operands.
<< >>
Left and right shift. Valid for integer operands only.
< > <= >=
Boolean less, greater, less than or equal, and greater than or equal.
Each operator produces 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.
== !=
Boolean equal and not equal. Each operator produces a zero/one result.
Valid for all operand types.
&
Bit-wise AND. Valid for integer operands only.
^
Bit-wise exclusive OR. Valid for integer operands only.
|
Bit-wise OR. Valid for integer operands only.
&&
Logical AND. Produces a 1 result if both operands are non-zero, 0 otherwise.
Valid for numeric operands only (integers or floating-point).
||
Logical OR. Produces a 0 result if both operands are zero, 1 otherwise.
Valid for numeric operands only (integers or floating-point).
x?y:z
If-then-else, as in C. If x
evaluates to non-zero, then the result is the value of y.
Otherwise the result is the value of z.
The x operand must have a numeric value.
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 expression
4*2 < 7
evaluates to 0.
The &&\fP, ||\fP, and ?:\fP 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
$v ? [a] : [b]
only one of [a] or [b] will actually be evaluated,
depending on the value of $v\fP.
All internal computations involving integers are done with the C type
long\fP, and all internal computations involving floating-point are
done with the C type double\fP.
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, overflow and underflow are generally not detected
reliably for intermediate results.
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,
5 / 4
yields the result 1, while
5 / 4.0
5 / ( [string length "abcd"] + 0.0 )
both yield the result 1.25.
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\fP format specifier
%d for integers and %g for floating-point values.
For example, the expressions
"0x03" > "2"
"0y" < "0x12"
both evaluate to 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''.
In general it is safest to enclose an expression in braces when
entering it in a command: otherwise, if the expression contains
any white space then the Tcl interpreter will split it
among several arguments. For example, the command
C
expr $a + $b
results in three arguments being passed to expr: $a,
+, and $b. In addition, if the expression isn't in braces
then the Tcl interpreter will perform variable and command substitution
immediately (it will happen in the command parser rather than in
the expression parser). In many cases the expression is being
passed to a command that will evaluate the expression later (or
even many times if, for example, the expression is to be used to
decide when to exit a loop). Usually the desired goal is to re-do
the variable or command substitutions each time the expression is
evaluated, rather than once and for all at the beginning. For example,
the command
C
for {set i 1} $i<=10 {incr i} {...} *** WRONG ***
is probably intended to iterate over all values of i from 1 to 10.
After each iteration of the body of the loop, for will pass
its second argument to the expression evaluator to see whether or not
to continue processing. Unfortunately, in this case the value of i
in the second argument will be substituted once and for all when the
for command is parsed. If i was 0 before the for
command was invoked then for's second argument will be 0<=10
which will always evaluate to 1, even though i's value eventually
becomes greater than 10. In the above case the loop will never
terminate. Instead, the expression should be placed in braces:
C
for {set i 1} {$i<=10} {incr i} {...} *** RIGHT ***
This causes the substitution of i's
value to be delayed; it will be re-done each time the expression is
evaluated, which is the desired result.
The third major way that strings are interpreted in Tcl is as lists.
A list is just a string with a list-like structure
consisting of fields separated by white space. For example, the
string
Al Sue Anne John
is a list with four elements or fields.
Lists have the same basic structure as command strings, except
that a newline character in a list is treated as a field separator
just like space or tab. Conventions for braces and quotes
and backslashes are the same for lists as for commands. For example,
the string
a b\ c {d e {f g h}}
is a list with three elements: a, b c, and d e {f g h}.
Whenever an element
is extracted from a list, the same rules about braces and quotes and
backslashes are applied as for commands. Thus in the example above
when the third element is extracted from the list, the result is
d e {f g h}
(when the field was extracted, all that happened was to strip off
the outermost layer of braces). Command substitution and
variable substitution are never
made on a list (at least, not by the list-processing commands; the
list can always be passed to the Tcl interpreter for evaluation).
The Tcl commands concat, foreach,
lappend, lindex, linsert, list, llength,
lrange, lreplace, lsearch, and lsort allow
you to build lists,
extract elements from them, search them, and perform other list-related
functions.
Tcl provides two commands that support string matching using
egrep-style regular expressions: regexp and regsub.
Regular expressions are implemented using Henry Spencer's package,
and the description of regular expressions below is copied verbatim
from his 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 null 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 null string at the
beginning of the input string), ``$'' (matching the null 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.
If a regular expression could match two different parts of a string,
it will match the one which begins earliest.
If both begin in the same place but match different lengths, or match
the same length in different ways, life gets messier, as follows.
In general, the possibilities in a list of branches are considered in
left-to-right order, the possibilities for ``*'', ``+'', and ``?'' are
considered longest-first, nested constructs are considered from the
outermost in, and concatenated constructs are considered leftmost-first.
The match that will be chosen is the one that uses the earliest
possibility in the first choice that has to be made.
If there is more than one choice, the next will be made in the same manner
(earliest possibility) subject to the decision on the first choice.
And so forth.
For example, ``(ab|a)b*c'' could match ``abc'' in one of two ways.
The first choice is between ``ab'' and ``a''; since ``ab'' is earlier, and does
lead to a successful overall match, it is chosen.
Since the ``b'' is already spoken for,
the ``b*'' must match its last possibility\(emthe empty string\(emsince
it must respect the earlier choice.
In the particular case where no ``|''s are present and there is only one
``*'', ``+'', or ``?'', the net effect is that the longest possible
match will be chosen.
So ``ab*'', presented with ``xabbbby'', will match ``abbbb''.
Note that if ``ab*'' is tried against ``xabyabbbz'', it
will match ``ab'' just after ``x'', due to the begins-earliest rule.
(In effect, the decision on where to start the match is the first choice
to be made, hence subsequent choices must respect it even if this leads them
to less-preferred alternatives.)
Tcl allows you to extend the command interface by defining
procedures. A Tcl procedure can be invoked just like any other Tcl
command (it has a name and it receives one or more arguments).
The only difference is that its body isn't a piece of C code linked
into the program; it is a string containing one or more other
Tcl commands. See the proc command for information on
how to define procedures and what happens when they are invoked.
Tcl allows the definition of variables and the use of their values
either through $-style variable substitution, the set
command, or a few other mechanisms.
Variables need not be declared: a new variable will automatically
be created each time a new variable name is used.
Tcl supports two types of variables: scalars and arrays.
A scalar variable has a single value, whereas an array variable
can have any number of elements, each with a name (called
its ``index'') and a value.
Array indexes may be arbitrary strings; they need not be numeric.
Parentheses are used refer to array elements in Tcl commands.
For example, the command
C
set x(first) 44
will modify the element of x whose index is first
so that its new value is 44.
Two-dimensional arrays can be simulated in Tcl by using indexes
that contain multiple concatenated values.
For example, the commands
C
set a(2,3) 1
set a(3,6) 2
set the elements of a whose indexes are 2,3 and 3,6.
In general, array elements may be used anywhere in Tcl that scalar
variables may be used.
If an array is defined with a particular name, then there may
not be a scalar variable with the same name.
Similarly, if there is a scalar variable with a particular
name then it is not possible to make array references to the
variable.
To convert a scalar variable to an array or vice versa, remove
the existing variable with the unset command.
The array command provides several features for dealing
with arrays, such as querying the names of all the elements of
the array and searching through the array one element at a time.
Variables may be either global or local. If a variable
name is used when a procedure isn't being executed, then it
automatically refers to a global variable. Variable names used
within a procedure normally refer to local variables associated with that
invocation of the procedure. Local variables are deleted whenever
a procedure exits. The global command may be used to request
that a name refer to a global variable for the duration of the current
procedure (this is somewhat analogous to extern in C).
AUTHOR
John Ousterhout, University of California at Berkeley
(ouster@sprite.berkeley.edu)
Many people have contributed to Tcl in various ways, but the following
people have made unusually large contributions:
Bill Carpenter
Peter Da Silva
Mark Diekhans
Karl Lehenbauer
Mary Ann May-Pumphrey
VARIABLES - SCALARS AND ARRAYS
Home