Getting Started: Tcl/Tk Basics

Tcl is pronounced "tickle" and Tk is pronounced "tee-kay". Tcl/Tk is "tickle tee-kay".

Lens uses Tcl/Tk version 8.3.4. Tcl was written by John Ousterhout and is now owned by Sun, but the wonderful people there allow it to be used freely, even in commercial applications.

To fully understand the Tcl language, you may need to read a book like Tcl and the Tk Toolkit, by John Ousterhout, Addison-Wesley Publishing, 1994. However, this section plus the Tcl/Tk manual pages should help you get by.

As you read through this document, try typing in the examples to the Lens interpreter and see if you get the right results. Probably the best way to figure out a language, though, is to just look at sample code. So once you have a grasp of the basics, you may want to try reading through the scripts in the "Examples/" directory or the file Src/shell.tcl.


A Tcl script consists of a series of commands. Commands are separated by newlines or semicolons. A command may be continued from one line to the next by ending the first line with a backslash ("\"). If the first character of a command is a pound or hash mark ("#"), the rest of the line will be treated as a comment and ignored. Note that the hash mark can't be just anywhere on a line, it must be at the beginning of a command, which is generally the beginning of the line.

Each command has a return code and a return value. Normally you need not be concerned with the code. It's used for errors, primarily. The return value is the important part. If the command is typed directly into the shell, the return value will be printed out. Otherwise, the return value of a command is used by surrounding the command with square brackets and using this as an argument to another command. In this case, the first command will be evaluated and replaced by its return value. See the next section for more on command substitution.

The words "command" and "procedure" will be used almost interchangeably. A procedure is really just a command that is written in Tcl, while some commands, including most of the Lens commands, are written in C. Procedures are executed by simply following the name of the procedure with its arguments. Parentheses are not used as in C. What we would write in C this way:

    f(x, y);
We write in Tcl this way:
    f $x $y

The arguments to a command are separated by whitespace. An argument may contain whitespace if it is surrounded by quotation marks, curly braces, or square braces. Many commands take a fixed number of arguments but some take a flexible number.

Essentially, everything in Tcl is a string. Variables need not be given types. Integers and reals will be converted to and from strings when it is appropriate, but the user need not be concerned with this. The null string is the universal empty value. It can be written as "" or {}. It is not the same as 0. Think of 0 as the non-null string "0".

Variable and Command Substitution

The previous example called the command f with the arguments $x and $y. The dollar sign indicates variable substitution. It means to replace the variable name x with the value of variable x. This is necessary because everything in Tcl is a string and if we just wrote x it would be the string "x" and not the value of the variable x. A variable is assigned a value with the set command. set also returns this value, as in the following:

    lens> set x 5
    5                                   (this is the return value here)
    lens> set y "hello there"
    hello there
    lens> set z $y$x
    hello there5

The first command sets x to the string 5. Later we might use $x in some arithmetic, but only then will it matter that x happens to hold an integer. The second command sets y to the string "hello there". Because of the quotes, "hello there" is treated as a single argument. The last command sets z to be the concatenation of the string held by y and the string held by x. Again, this is just one argument.

Now what if we wanted to set z to the value of y immediately followed by 5, but we didn't have 5 stored in a variable? We might try the following:

    lens> set z $y5
    can't read "y5": no such variable   (this is an error)
But this will try to dereference the variable "y5", which doesn't exist. We can avoid this problem by surrounding the y with curly braces:
    lens> set z ${y}5
    hello there5

If a variable has a funny name, such as one containing periods, we may also need to surround the variable name with curly braces when dereferencing it:

    lens> set a.b c
    lens> return $a.b
    can't read "a": no such variable
    lens> return ${a.b}

Variables need not be declared explicitly. When a variable is first set it will be created automatically.

Along with simple variables, Tcl also supports associative arrays. Associative arrays don't have a finite number of integer indexes, like ordinary arrays, but arbitrary strings as indexes. Array elements are accessed using parentheses rather than square brackets, as in C. This is because square brackets were reserved for command substitution. Observe the following examples:

    lens> set mother(Bill) Jane
    lens> set brother(Jane) Bob
    lens> set sister(Bob) $mother(Bill)
    lens> set uncle(Bill) $brother($mother(Bill))
Tcl does not really support multi-dimensional arrays, but you can pretend to have them by placing a comma or something else between the indexes, as in:
    lens> set relationship(Bill,Jane) mother

Avoiding Substitutions

It is often necessary to avoid substitutions or to delay them until later. This can become very complicated and is the weakest aspect of the Tcl language. The usual cases are not too bad, however. The simplest method of avoiding a substitution is using a backslash:

    lens> set z $x
    lens> set z \$x
    lens> set z "\$x is equal to $x"
    $x is equal to 5

The double quotes in the last command combine the separate words into a single argument, but they allow command substitutions to continue. Curly braces, {}, are similar to double quotes but stronger, in that they prevent command substitutions from going on inside them. However, putting quotes around the curly braces will turn them off:

    lens> set z {\$x is equal to $x}
    \$x is equal to $x
    lens> set z "{\$x is equal to $x}"
    {$x is equal to 5}

The choice between double quotes and braces is important when setting variables to commands. Using quotes causes substitution to occur immediately while using braces defers it to later:

    lens> set x 5
    lens> set y "return $x"
    return 5
    lens> set z {return $x}
    return $x
    lens> set x 6
    lens> $y
    lens> $z
    6                                    (notice the difference)
    lens> set y "return \"old x = $x  new x = \$x\""
    return "old x = 6  new x = $x"
    lens> set x 7
    lens> $y
    old x = 6  new x = 7

It is sometimes necessary to do an extra level of substitution on the arguments of a command, particularly after having avoided some substitutions. This can be done by using the eval command. In the following example, the value of y is the variable name x. We would like to set z to the value of the variable name that is stored in y. To do this in one step we need an extra level of substitutions:

    lens> set x 5
    lens> set y x
    lens> set z $$y
    $x                                   (oops)
    lens> eval set z $$y
    lens> return "$x $y $z"
    5 x 5

When you have variable names stored in other variables, sometimes it is easier to use set to access the value of the variable rather than $. Instead of "eval set z $$y", you could do:

    lens> set z [set $y]

Command Substitution

Just as the value of a variable can be substituted for its name, the result of a command can be substituted for the command. This is done by embedding the command in square brackets. For example, expr is a command for evaluating mathematical and logical expressions. It returns the value of the expression. We can store the result of a calculation in a variable as follows:

    lens> set x [expr 3 + 4]
Substitutions will occur within square brackets, just like they do within double quotes:
    lens> set z [expr [set y [expr [set x 2] + 1]] * 2]
    lens> set values "$x $y $z"
    2 3 6

It is often necessary to escape command substitutions just as we escape variable substitutions. This can be done by preceding both the opening and closing brackets with a backslash or by enclosing the brackets in curly braces:

    lens> set y "return [expr $x + 2]"
    return 4
    lens> set z "return \[expr \$x + 2\]"
    return [expr $x + 2]
    lens> set w {return [expr $x + 2]}
    return [expr $x + 2]                 (equivalent but cleaner)
    lens> set x 10
    lens> return "[$y] [$z] [$w]"
    4 12 12

File Name Expansion

One related thing to note is that file name globbing does not occur automatically in Tcl. The following does not work because *.c does not get expanded:

    lens> rm *.c
    /bin/rm: *.c: No such file or directory
    child process exited abnormally
glob is a command for doing file name expansion:
    lens> glob *.c foo.c bar.c

However, glob returns all of the filenames as a single argument so this will not work:

    lens> rm [glob *.c]
    /bin/rm: foo.c bar.c: No such file or directory
    child process exited abnormally
That is because "foo.c bar.c" is treated as a single file name. Therefore, an extra evaluation is needed so that the single argument becomes two arguments:
    lens> eval rm [glob *.c]

When you combine the complexity of command substitutions, arrays and variables having strange names, variables containing other variable names, and the need to delay or force evaluation, substitutions can become very complex. In fact, there are a few things that are simply impossible given the Tcl syntax. This can sometimes be avoided by dividing a step into several sub-steps and storing the intermediate results. But when it comes down to it, sometimes trial and error is the only way to get a tricky piece of code correct.


As mentioned, virtually everything in Tcl is a string, so string manipulation is rather important. Simple string concatenation occurs when two strings are placed side-by-side. A string can also be appended to the end of a variable using the append command:
    lens> set x howdy
    lens> set x "$x $x"
    howdy howdy
    lens> append x " $x"
    howdy howdy howdy howdy
If you want to get more sophisticated than concatenation, the format command can be used to form strings. It is similar to the C sprintf() function and is able to alter the representation of numeric variables, rounding the decimals or changing base:
    lens> set y 3.14159
    lens> format "%-10.3f %.0f %x" $y $y 100
         3.142 3 64
A number of other commands are used to manipulate strings. regexp does regular expression matching given an expression and a string. regsub does regular expression matching and substitution. scan parses a string in a similar way to sscanf. Finally, the string command does a number of other operations on strings, such as returning a string's length, comparing strings, doing substring lookup, and trimming the head and tail of a string. The puts command prints strings to standard output (or to another channel). It is like the echo used in other shell languages. The string given to puts must be in a single argument, as follows:
    lens> puts "$x.  Look, I'm a cowboy!"
    howdy howdy howdy howdy.  Look, I'm a cowboy!
Note, that printing a string is very different from returning a string:
    lens> set x [expr 3 + 4]
    lens> set x
    lens> set x [puts 7]
    lens> set x
                                       (there is no value here because puts
                                        didn't return anything)


Lists are used to store collections of things. Lists are strings with a special structure. The simplest list is just a string with several words separated by spaces. Each word is an element in a list. We can make multiple word elements by enclosing the elements in braces or double quotes. The lindex command returns a selected element of a list. Observe the following examples:

    lens> lindex {Snoopy Linus Sally "the girl with red hair"} 1
    lens> set x {Snoopy Linus Sally "the girl with red hair"}
    Snoopy Linus Sally "the girl with red hair"
    lens> lindex $x 3
    the girl with red hair
    lens> lindex [lindex $x 3] 4

There are a number of commands for handling lists. llength returns the length of a list. concat concatenates multiple lists. Note that this is can also be done using ordinary string concatenation. lappend adds new elements to the end of a list. linsert adds new elements to the middle of a list. lrange returns part of a list. split breaks a string into a list at specified characters. And there are a few more list commands described in the Tcl/Tk manual.


Expressions combine numeric or logical values to produce new values. Expressions are ordinarily evaluated using the expr command. Expressions are also evaluated automatically when they are in the "test" argument of if statements and other control structures.

Most C expressions are valid in Tcl. However, you must remember to use a dollar sign to perform variable substitution on each occurrence of a variable. All of the standard math library functions are available in Tcl expressions. Note that in Tcl these are not procedures as they are in C. Using these mathematical functions is the only case where C-like function syntax, f(), is used, rather than Tcl command syntax. Here are some expressions:

    lens> set x 0.5
    lens> set y 2
    lens> expr ($x + $y) / $y
    lens> expr pow(35 % 4, $y)
    lens> expr 2 | 1
    3                                  (bitwise operations!)
    lens> expr (3.14 > 3) && (round(3.14) == 3)
    1                                  (logic!)
    lens> expr {[format "%d %d" 3 4] == "3 4"}
    1                                  (easy string comparisons!)

Note that in the last example curly braces were used around the expression. This is necessary to prevent an extra level of substitution to occur before the expression itself is evaluated. Leaving them out would have caused problems because the expression would have read 3 4 == "3 4" rather than "3 4" == "3 4". This is a bit tricky, but you will almost always be fine if you surround all expressions with curly braces.

Logical true is 1 and logical false is 0. Note that the empty string is not logical false. To test if a string is empty, you should do:

    lens> if {$s == {}} {...}

When performing division and possibly other procedures, Tcl will attempt to detect whether the numerator is an integer or a real number. If the numerator is an integer, integer division will be performed and the result truncated. To prevent this, constants that should be treated as real numbers should always be given at least one decimal, even if it is zero. Furthermore, double() should be used on variables to ensure that they are not treated as integers. For example:

    lens> expr 8 / 5
    lens> expr 8.0 / 5
    lens> set x 8
    lens> expr $x / 5
    lens> expr double($x) / 5

Control Structures

Control structures are implemented in Tcl like normal commands. There is an if statement, which uses the special arguments else and elseif for alternatives. Note that there can't be a space in elseif:

    if {$x < 0} {set x 0}

    if {$y == "hello"} {
        puts $y

    if {(sin($x) < 0.5) || $x < 0} \
        {puts hi}

    if {$x == $y} {
        puts y
    } elseif {$x == $z} {
        puts z
    } else {puts huh?}
There is a for loop:
    for {set i 0} {$i < 10} {incr i} {
        puts $i
and a while loop:
    while {$i > 0} {
        puts [incr i -1]
The foreach command iterates over elements of a list:
    foreach i {a b c d e} {
        puts $i

break and continue can be used in loops in the same way they are used in C.

Finally, the switch statement is like the C version but it takes a single argument specifying the value and then a list of even length. The even elements of the list are case values and the odd elements are commands that are executed if the preceding case is met. Breaks are implicit following any match, unlike in C. The special case default matches everything. The special command - causes switch to fall through to the next command, avoiding the break. Here are some examples:

    switch $x "a {puts hi} b {puts bye} $y {puts arghhhh}"
    switch [expr $x + 3] {
        2 -
        3 {puts "2 or 3"}
        4 {puts 4!!!}
        default {puts "What you talkin' 'bout, Willis?"}

If you want to get fancy, it is possible to make switch do regular expression matching rather than simple string matching.


The proc command is used to define new procedures. It takes three arguments: the name of the new procedure, a list of arguments, and the body of the command. The list of arguments can be the name of a single argument, foo, or a list of arguments, {foo bar}. An argument can either be a single name or a pair consisting of a name and a default value. If a default value is given, the argument is optional. All optional arguments must be at the end of the argument list.

The return value of a procedure is the value of the last command executed. The return and error commands can be used to return normally or abnormally at any point in the execution of the procedure.

Here is a command that returns the natural log of a value if given one argument or the log to a particular base if given two arguments. Note that the default value for base is the null string, but there is no default value for x so it must be specified:

    proc superLog {x {base {}}} {
        if {$base == {}} {
            return [expr log($x)]
        } else {
            return [expr log($x) / log($base)]

    lens> superLog 100
    lens> superLog 100 10
The scope of variables in procedures does not automatically extend to the global environment. Variables are by default local. The global command, when used inside a procedure, instructs the interpreter that one or more variables are to be global:
    proc area radius {
        global PI
        expr $radius * $radius * $PI

    lens> set PI 3.14159
    lens> area [expr sqrt(2)]

Procedures can deleted by renaming them to the empty string, as in:

    lens> rename myproc {}

Errors and Exceptions

As mentioned before, commands return both a code and a value. Ordinarily the code is 0 and is ignored. If an error occurs in the command (or if the error command is called inside a procedure) it will return with the code 1. The interpreter will ordinarily catch this error and propagate it up through the call stack until the top level is reached. Then the value associated with the error is reported to the user.

However, the catch command can be used to intercept errors and to deal with them in a less destructive way. For example, if you wanted to make sure that the variable x does not exist, you would use the command unset x. However, this will result in an error if x didn't already exist. This error would terminate any scripts invoking this command. Therefore, it is good practice to protect such commands as follows:

    lens> catch {unset x}
catch will return the code from the unset command as its value. If x existed it would return 0 and if x didn't exist, it would return 1.

The return, break, and continue commands give the return codes 2, 3, and 4, respectively. These are each handled differently by the interpreter. The return command is also able to return with a particular code.

The one potentially useful variant is "return -code return <string>". If invoked anywhere inside a Tcl script, even inside of a procedure called by the script, this will cause the script to exit. This is somewhat like the quit command in some scripting languages.


Subprocesses may be started in one of several ways. If a command name is used that doesn't match a valid Tcl command, the interpreter will see if the name matches an executable program. If so, the program will be invoked with the specified arguments.

The normal way to run subprocesses, however, is with the exec command. exec supports input and output redirection as well as pipes. The usage is best understood by reading the official manual page. One thing of interest is that a single < will make the command read from a file while a double << will make the command read from a variable. The exec command will only return when the subprocesses terminate, unless the last argument is &.

Finally, open may be used to create perpetual pipelines that can be written to or read from and must be terminated with the close command.

Douglas Rohde
Last modified: Mon Mar 1 23:51:52 EST 1999