All commands return values. For example, the pid command returns the process id of the current process. To evaluate a command and use its return value as an argument or inside an argument, embed the command in brackets. The bracketed command is replaced by its return value.

set p "My pid is [pid]."

The set command returns its second argument. The following command sets b and a to 0.

set b "[set a 0]"

When it comes to deciding what are arguments, brackets are a special case. Tcl groups everything between matching brackets, so it is not necessary to quote arguments that only have spaces inside brackets. The following are all legal.

set b [set a 0]
set b "[set a 0]"
set b "[set a 0]hello world"
set b [set a 0]hello

After execution of this last command, a is set to "0" and b is set to "0hello“.

With only one argument, set returns the value of its first argument.

set c [set b]

Calling set with one argument is similar to using the dollar sign. Indeed, the previous command can be rewritten as "set c $b“. However they are not always interchangeable. Consider the two commands:

set $phello
set [set p]hello

The first returns the value of the variable phello. The second returns the value of the variable p concatenated with the string "hello“.

The $ syntax is shorter but does not automatically terminate the end of the variable. In the rare cases where the variable just runs right into more alphanumeric characters, the one-argument set command in brackets is useful.

The one-argument set command is also useful when entering commands interactively. For example, here is what it looks like when I type a command to the Tcl interpreter:^[8]

tclsh> set p
12389

After entering "set p“, the return value was printed. When using Tcl interactively, you will always see the return value printed. When executing commands from a script, the return values are discarded. Inside scripts, use the puts command to print to the standard output.

You can print values out with the puts command. In its simplest form, it takes a single string argument and prints it followed by a newline.

puts "Hello word!"
puts "The value of name is $name"

The while command loops until an expression is false. It looks very similar to a while in the C language. The following while loop computes the factorial of the number stored in the variable count.

set total 1

while {$count > 0} {
    set total [expr $total * $count]
    set count [expr $count−1]
}

The body of the loop is composed of the two set commands between the braces. The body is executed as long as $count is greater than 0.

Taking a step back, the while command has two arguments. The first is the controlling expression. The second is the body. Notice that both arguments are enclosed in braces. That means that no $ substitutions or bracket evaluations are made. For instance, this while command literally gets the string "$count > 0" as its first argument. Similarly, for the body. So how does anything happen?

The answer is that the while command itself evaluates the expression. If true (nonzero), the while command evaluates the body. The while command then re-evaluates the expression. As long as the expression keeps re-evaluating to a nonzero value, the while command keeps re-evaluating the body.

It is useful to compare this with the set command. The set command does not do any evaluation of its second argument. Consider this command:

set count [expr $count−1]

The [expr ...] part is evaluated before the set command even begins. If count is 7, the set command sees an argument of 6. In contrast, the while command sees the argument "$count > 0“. It would not make any sense to evaluate that expression before the while command, since it has to change every time through the loop.

Using braces this way is fundamental toward the correct use of Tcl’s control structures. You will see that all the other ones follow easily from this.

Many loops use a counter of some sort. Incrementing or decrementing a counter is so common that there is a command to simplify it. It is called incr. It modifies the variable given as its first argument. With no other argument incr adds one, otherwise incr adds the remaining argument.

The two commands are equivalent:

set count [expr $count−1]
incr count −1

The for command is similar to the while command. The for command has a controlling expression and a body. However, before the expression is a “start” argument, and after the expression is a “next” argument.

for start expression next {
    # commands here make up
    # the body of the for
}

Both the start and next arguments are commands. The start argument is executed before the first evaluation of the controlling expression. The next argument is evaluated immediately after the body of the loop.

The code shown earlier to compute a factorial can be simplified using the incr command and a for loop as follows:

for {set total 1} {$count > 0} {incr count −1} {
    set total [expr $total * $count]
}

Either of the start or next argument can be empty, but you have to leave a placeholder. For example, you could express an infinite loop as:

for {} {1} {} {
    ... some command ...
}

In its simplest form, the if command takes a controlling expression and a body to execute if the expression is nonzero. It looks a lot like a while command, but the body is executed at most once.

if {$count < 0} {
    set total 1
}

If present, an optional else fragment is executed only if the expression evaluates to zero. Here is an example:

if {$count < 5} {
    puts "count is less than five"
} else {
    puts "count is not less than five"
}

It is also possible to add more conditions using elseif arguments. Any number of elseif arguments may be used.

if {$count < 0} {
    puts "count is less than zero"
} elseif {$count > 0} {
    puts "count is greater than zero"
} else {
    puts "count is equal to zero"
}

In the while and for commands, the controlling expressions are written with braces to defer their evaluation. Their evaluation is deferred because they need to be re-evaluated repeatedly. The expression in an if is not re-evaluated and so it does not need to be deferred. The braces are still useful to group the arguments of the expression together but if the grouping behavior is not needed, then the braces can be omitted entirely. For example, the following two commands are equivalent:

if $a {incr a}
if {$a} {incr a}

The following two commands are not equivalent.

while $a {incr a}
while {$a} {incr a}

It does not hurt to write braces around all expressions; however, if you frequently read other people’s code, you must get used to seeing the braces omitted in some expressions.

The switch command is similar to the if command but is more specialized. Instead of evaluating a mathematical expression, the switch command compares a string to a set of patterns. Each pattern is also associated with a body of Tcl commands. The first pattern that matches has its associated body evaluated.

Here is a fragment that sets the variable type depending on the value of count. For example, if count is the string big, then type is set to array. If count matches none of the choices, the special default body is used.

switch -- $count 
  1 {
    set type byte
} 2 {
    set type word
} big {
    set type array
} default {
    puts "$count is not a valid type"
}

By default, shell-style pattern matching is used. For example "?" matches any single character and "*" matches any string. I will describe the different types of pattern matching in more detail later.

The "--" immediately after "switch" is a placeholder for several flags that can modify the way the switch command works. The flags are rarely used so I will not describe them; nevertheless it is still a good idea to use the "--“. This will prevent your string from inadvertently matching a flag.

By default, commands do not continue beyond the end of a line. However, there are several exceptions to this. One is that a backslash at the end of a line continues the command. I used this in the previous example where the first line of the switch had a backslash to continue the command. Without it, the command would have ended after $count and the 1 on the next line would have mistakenly been interpreted as another command.

Another exception is that open braces cause commands to continue across lines. This is precisely how I have written all of the other multi-line examples so far. Fortunately, this style looks a lot like another common style—the C language. Even if you are not used to C, it will be helpful if you adopt the C formatting style—just leave an open brace at the end of the current line and you can omit the backslashes.

Consider the following three if commands:

if {$count < 0} {
    puts "count is less than zero"
}

if {$count < 0} 
    { puts "count is less than zero"
}

if {$count < 0}
{
    puts "count is less than zero"
}

The first two examples are correct. The third one is incorrect—the if command is missing a body.

Open braces nest, so this guideline works if you write braced commands inside of braces. Later in this chapter and in the next, I will return to the subject of braces and how to use them effectively.

Double quotes and brackets also cause commands to continue across lines. As before, a or literal newline is retained and a backslash-newline-whitespace sequence is replaced by a single space. Compare the following two commands:

set oneline "hello
     world"
set twolines "hello
     world."

After execution, oneline is set to "hello world“, while twolines is set to "hello<newline><space><space><space><space>world“.

The break and continue commands change the normal flow inside control structure commands such as for and while.

The break command causes the current loop command to return so that the next command after the loop can run. For example, the following would loop infinitely except for the break command in the middle. If a ever equals three, the break command will execute and the while command will return.

set a 0
while {1} {
    incr a
    if {$a == 3} break
    puts "hello"
}

The continue command drives control back to the top of the loop so that no more commands are executed during the current iteration. In the following example, the continue is executed whenever the the value of a modulo three is not equal to zero. This has the effect of printing "hello" three times for every "there" printed.

set a 0
while {1} {
    incr a
    puts "hello"
    if {$a%3 != 0} continue
    puts "there"
}

It is possible to create your own commands using the proc command. Such commands are called procedures but they behave the same as if they were built-in commands.

The proc command takes three arguments. The first argument is a command name. The second argument is a list of variables, each initalized to an argument of the procedure when it is called. (The variables are occasionally called formal parameters or just parameters to distinguish them from the actual arguments to which they are set.) The third argument of proc is a body of code.

The following command defines a procedure called fib that computes the nth Fibonacci number given any two starting numbers. Fibonacci numbers are sequences of numbers where each new number in the sequence is generated by adding the most recent two together. The starting two numbers are the first two arguments. The last argument defines which element of the sequence to return.

proc fib {pen ult n} {
    for {set i 0} {$i<$n} {incr i} {
        set new [expr $ult+$pen]
        set pen $ult                        ;# new penultimate value
        set ult $new                        ;# new ultimate value
    }
    return $pen
}

The return command in the last line takes its argument and makes the procedure fib itself return with that value. Once defined, fib can then be used as a command. For example, it could be called as:

set m [fib 0 1 9]

Although fib always returns a number, any string can be returned using return. A lot of procedures do not have a need to return anything—they just need to return. In this case, it is not necessary to provide return with an argument. The return command itself may be omitted if it would otherwise be the last command in a procedure. Then, the procedure returns with whatever is returned by the last command executed within the procedure.

You can force a single procedure to return by using return. In contrast, use the exit command to make the script (i.e., process) end and return to the shell (or whatever invoked the original script). The exit command works even inside of a procedure. The exit command can only return a number because that is all that UNIX permits. For example:

exit 1

Procedures can be called only after they are defined. Procedures share a single namespace with no name scoping. That means that once a procedure is defined, it can be called from any procedure, including itself. Here is another version of fib. This one is recursive—it calls itself.

proc fib {pen ult n} {
    if {$n == 0} {
        return $pen
    }
    return [fib $ult [expr $pen+$ult] [expr $n−1]]
}

In contrast, variables are usually local to the current procedure. In the example above, the variables ult, pen, and n, are not visible to any procedures that call fib such as expr. They are not even visible to other invocations of the fib procedure. The fib procedure calls expr, passing it the value of ult but not the string "ult“. The expr command cannot modify the variable ult. Computer scientists call this pass by value.

It is possible for a procedure to change a variable in the caller’s scope. The set and incr commands handle their first argument this way. This technique is called pass by reference, and I will explain how to write procedures that do this on page 56. Another technique to communicate values between commands is to use global variables. Using a lot of global variables can be confusing, but since most scripts are short, global variables are a very popular technique.

The global command identifies variables to consider global. This means that references to those variables inside the procedure are the same as references to those variables outside all the procedures.

For example, you could define the constant pi as a global variable outside any procedure. A procedure that needed the value would then access it using the global command.

proc area_of_circle {radius} {
    global pi

    return [expr 2*$pi*$radius]
}

You can list additional variable names as arguments to a global command, and you can have multiple global commands in a procedure.

global pi e golden_ratio

The return command may be omitted if it is the last command in a procedure. In that case, the procedure returns the last value computed. For example, the previous procedure could be simplified as follows:

proc area_of_circle {radius} {
    global pi

    expr 2*$pi*$radius
}

Procedures and variables that are used in numerous scripts can be stored in other files, allowing them to be conveniently shared. A file of commands can be read with the source command. Its argument is the name of a file to read. Tcl understands the tilde convention from the C shell. For example, the following command reads the file definitions.tcl from your home directory:

source ~/definitions.tcl

As the file is read, the commands are executed. So if the file contains procedure definitions, the procedures will be callable after the source command returns. Tcl’s source command is similar to the C shell’s source command.

Tcl’s library facility provides a way to automatically source files as needed. It is described on page 66.

The return command can be used to make a source command return. Otherwise, source returns only after executing the last command in the file.

The lindex and lrange commands select elements from a list by their index. The lindex command selects a single element. The lrange command selects a set of elements. Elements are indexed starting from zero.^[11]

tclsh> lindex "a b c d e" 0
a
tclsh> lindex "a b c d e" 2
c
tclsh> lrange "a b c d e" 0 2
a b c
tclsh> llength [lrange "a b c d e" 0 2]
3

You can step through the members of a list using an index and a for loop. Here is a loop to print out the elements of a list in reverse.

for {set i [expr [llength $list]−1]} {$i>=0} {incr $i −1} {
    puts [lindex $list $index]
}

Iterating from front to back is much more common than the reverse. In fact, it is so common, there is a command to do it called foreach. The first argument is a variable name. Upon each iteration of the loop, the variable is set to the next element in the list, provided as the second argument. The third argument is the loop body.

For example, this fragment prints each element in list.

foreach element $list {
    puts $element
}

After execution, the variable element remains set to the last element in the list.

Usually procedures must be called with the same number of arguments as they have formal parameters. When a procedure is called, each parameter is set to one of the arguments. However, if the last parameter is named args, all the remaining arguments are stored in a list and assigned to args. For example, imagine a procedure p1 definition that begins:

proc p1 {a b args} {

If you call it as "p1 red box cheese whiz“, a is set to red, b is set to box, and args is set to "cheese whiz“. If called as "p1 red box“, args is set to the empty list.

Here is a more realistic example. The procedure sum takes an arbitrary number of arguments, adds them together, and returns the total.

proc sum {args} {
    set total 0
    foreach int $args {
        incr total $int
    }
    return $total
}

I will show another example of a procedure with varying arguments on page 57.

List elements can themselves be lists. This is a concern in several situations, but the simplest is when elements contain whitespace. For example, there must be a way to distinguish between the list of "a" and "b" and the list containing the single element "a b“.

Assuming an argument has begun with a double quote, the next double quote ends the argument. It is possible to precede double quotes with backslashes inside a list, but this is very hard to read, given enough levels of quoting. Here is a list of one element.

set x ""a b""

As an alternative, Tcl supports braces to group lists inside lists. Using braces, it is easy to construct arbitrarily complex lists.

set a "a b {c d} {e {f g {xyz}}}"

Assuming you do not need things like variable substitution, you can replace the top-level double quotes with braces as well.

set a {a b {c d} {e {f g {xyz}}}}

This looks more consistent, so it is very common to use braces at the top level to write an argument consisting of a list of lists.

The reason braces work so much better for this than double quotes is that left and right braces are distinguishable. There is no such thing as a right double quote, so Tcl cannot tell when quotes should or should not match. But it is easy to tell when braces match. Tcl counts the left-hand braces and right-hand braces. When they are equal, the list is complete.

This is exactly what happens when Tcl sees a for, while, or other control structure. Examine the while command below. The last argument is the body. There is one open brace on the first line and another on the fourth. The close brace on the sixth line matches one, and the close brace on the last line matches the other, terminating the list and hence the argument.

while {1} {                        ;# one open brace
    incr a
    puts "hello"
    if {$a%3 != 0} {                    ;# two open braces
        continue
    }                    ;# one open brace
    puts "there"
}                        ;# zero open braces

Double quotes and brackets have no special meaning inside of braces and do not have to match. But braces themselves do. To embed a literal brace, you have to precede it with a backslash.

Here are some examples of lists of lists:

set x  { a b c }
set y  { a b {Hello world!}}
set z  { a [ { ] } }

All of these are three-element lists. The third element of y is a two-element list. The first and second elements of y can be considered one-element lists even though they have no grouping braces around them.

tclsh> llength $y
3
tclsh> llength [lindex $y 2]
2
tclsh> llength [lindex $y 0]
1

The second and third elements of z are both one-element lists.

tclsh> lindex $z 1
[
tclsh> lindex $z 2
 ]

Notice the spacing. Element two of z is a three-character string. The first and last characters are spaces, and the middle character is a right bracket. In contrast, element one is a single character. The spaces separating the elements of z were stripped off when the elements were extracted by lindex. The braces are not part of the elements.

The braces are, however, part of the string z. Considered as a string, z has eleven characters including the inner braces. The outer braces are not part of the string.

Similarly, the string in y begins with a space and ends with a right brace. The last element of y has only a single space in the middle.

tclsh> lindex $y 2
Hello world!

The assignment to y could be rewritten with double quotes.

tclsh> set y2 { a b "Hello World" }
 a b "Hello World"
tclsh> lindex $y2 2
Hello world!

In this case, the last element of y2 is the same. But more complicated strings cannot be stored this way. Tcl will complain.

tclsh> set y3 { a b "My name is "Goofy"" }
 a b "My name is "Goofy""
tclsh> lindex $y3 2
list element in quotes followed by "Goofy""" instead of space

There is nothing wrong with y3 as a string. However, it is not a list.

This section may seem confusing at first. You might want to come back to it after you have written some Tcl scripts.

With care, lists can be created with the set command or with any command that creates a string with the proper structure. To make things easier, Tcl provides three commands that create strings that are guaranteed to be lists. These commands are list, lappend, and linsert.

The list command takes all of its arguments and combines them into a list. For example:

tclsh> list a b "Hello world"
a b {Hello world}

In this example, a three-element list is returned. Each element corresponds to one of the arguments. The double quotes have been replaced by braces, but that does not affect the contents. When the third element is extracted, the braces will be stripped off.

tclsh> lindex [list a b "Hello World"] 2
Hello World

The list command is particularly useful if you need to create a list composed of variable values. Simply appending them is insufficient. If either variable contains embedded whitespace, for example, the list will end up with more than two elements.

tclsh> set a "foo bar "hello""
foo bar "hello"
tclsh> set b "gorp"
gorp
tclsh> set ab "$a $b"                            ;# WRONG
foo bar "hello" gorp
tclsh> llength $ab
4

In contrast, the list command correctly preserves the embedded lists. The list command also correctly handles things such as escaped braces and quotes.

If you want to append several lists together, use the concat command.

tclsh> concat a b "Hello world"
a b Hello world

The concat command treats each of its arguments as a list. The elements of all of the lists are then returned in a new list. Compare the output from concat (above) and list (below).

tclsh> list a b "Hello world"
a b {Hello world}

Here is another example of concat. Notice that whitespace inside elements is preserved.

tclsh> concat a {b {c d}}
a b {c d}

In practice, concat is rarely used. However, it is helpful to understand concat because several commands exhibit concat-like behavior. For example, the expr command concatenates its arguments together before evaluating them—much in the style of concat. Thus, the following commands produce the same result:

tclsh> expr 1 - {2 - 3}
-4
tclsh> expr 1 - 2 - 3
-4

Building up lists is a common operation. For example, you may want to read in lines from a file and maintain them in memory as a list. Assuming the existence of commands get_a_line and more_lines_in_file, your code might look something like this:

while {[more_lines_in_file]} {
    set list "$list [get_a_line]"
}

The body builds up the list. Each time through the loop, a new line is appended to the end of the list.

This is such a common operation that Tcl provides a command to do this more efficiently. The lappend command takes a variable name as its first argument and appends the remaining arguments. The example above could be rewritten:

while {[more_lines_in_file]} {
    lappend list [get_a_line]
}

Notice that the first argument is not passed by value. Only the name is passed. Tcl appends the remaining arguments in place—that is, without making a copy of the original list. You do not have to use set to save the new list. This behavior of modifying the list in place is unusual—the other list commands require the list to be passed by value.

Like its name implies, the linsert command inserts elements into a list. The first argument is the name of a list. The second argument is a numeric index describing where to insert into the list. The remaining arguments are the arguments to be inserted.

tclsh> set list {a b c d}
a b c d
tclsh> set list [linsert $list 0 new]
new a b c d
tclsh> linsert $list 1 foo bar {hello world}
new foo bar {hello world} a b c d

The lreplace command is similar to the linsert command except that lreplace deletes existing elements before inserting the new ones. The second and third arguments identify the beginning and ending indices of the elements to be deleted, and the remaining arguments are inserted in their place.

tclsh> set list {a b c d e}
a b c d e
tclsh> lreplace $list 1 3 x y
a x y e

The lsearch command is the opposite of the lindex command. The lsearch command returns the index of the first occurrence of an element in a list. If the element does not exist, −1 is returned.

tclsh> lsearch {a b c d e} "c"
2
tclsh> lsearch {a b c d e} "f"
−1

The lsearch command uses the element as a shell-style pattern by default. If you want an exact match, use the -exact flag.

tclsh> lsearch {a b c d ?} "?"
0
tclsh> lsearch -exact {a b c d ?} "?"
4

The lsort command sorts a list. By default, it sorts in increasing ASCII order.

tclsh> lsort {one two three four five six}
five four one six three two

Several flags are available including -integer, -real, and -decreasing to sort in ways suggested by their names.

It is also possible to supply lsort with a comparison procedure of your own. This is useful for lists with elements that are lists in themselves. However, lists of more than a hundred or so elements are sorted slowly enough that it is more efficient to have them sorted by an external program such as the UNIX sort command.^[12]

The split and joincommands are useful for splitting strings into lists, and vice versa—joining lists into strings.

The split command splits a string into a list. The first argument is the string to be split. The second argument is a string of characters, each of which separates elements in the first argument.

For example, if the variable line contained a line from /etc/passwd, it could be split as:

tclsh> split $line ":"
root Gw19QKxuFWDX7 0 1 Operator / /bin/csh

The directories of a file name can be split using a "/“.

tclsh> split "/etc/passwd" "/"
{} etc passwd

Notice the empty element because of the / at the beginning of the string.

The join command does the opposite of split. It joins elements in a list together. The first argument is a list to join together. The second argument is a string to place between all the elements.

tclsh> join {{} etc passwd} "/"
/etc/passwd

With an empty second argument, split splits between every character, and join joins the elements together without inserting any separating characters.

tclsh> split "abc" ""
a b c
tclsh> join {a b c} ""
abc

The scan and format commands extract and format substrings corresponding to low-level types such as integers, reals, and characters. scan and format are good at dealing with filling, padding, and generating unusual characters. These commands are analogous to sscanf and sprintf in the C language, and most of the C conventions are supported.

As an example, the following command assigns to x a string composed of a ^A immediately followed by "foo==1700.000000" (the number of zeros after the decimal point may differ on your system). The string is left-justified in an eight-character field.

set x [format "%1c%-8s==%f" 1 foo 17.0e2]

The first argument is a description of how to print the remaining arguments. The remaining arguments are substituted for the fields that begin with a "%“. In the example above, the "-" means “left justify” and the 8 is a minimum field width. The "c“, "s“, and "f" force the arguments to be treated as a character, a string, and a real number (f stands for float), respectively. The "==" is passed through literally since it does not begin with a "%“.

The scan command does the opposite of format. For example, the output above can be broken back down with the following command:

scan $x "%c%8s%*[ =]%f" char string float

The first argument, $x, holds the string to be scanned. The first character is assigned to the variable char. The next string (ending at the first whitespace or after eight characters, whichever comes first) is assigned to the variable string. Any number of blanks and equal signs are matched and discarded. The asterisk suppresses the assignment. Finally, the real is matched and assigned to the variable float. The scan command returns the number of percent-style formats that matches.

I will not describe scan and format further at this point, but I will return to them later in the book. For a complete discussion, you can also consult the Tcl reference material or any C language reference.

The string command is a catchall for a number of miscellaneous but very useful string manipulation operations. The first argument to the string command names the particular operation. While discussing these operations, I will refer to the remaining arguments as if they were the only arguments.

As with the list commands, the string commands also use zero-based indices. So the first character in a string is at position 0, the second character is at position 1, and so on.

The compare operation compares the two arguments lexicographically (i.e., dictionary order). The command returns −1, 0, or 1, depending on if the first argument is less than, equal to, or greater than the second argument.

As an example, this could be used in an if command like so:

if {[string compare $a $b] == 0} {
    puts "strings are equal"
} else {
    puts "strings are not equal"
}

The match operation returns 1 if the first argument matches the second or 0 if it does not match. The first argument is a pattern similar in style to the shell, where * matches any number of characters and ? matches any single character.

tclsh> string match "*.c" "main.c"
1

I will cover these patterns in more detail in Chapter 4 (p. 87). The regexp command provides more powerful patterns. I will describe regexp in Chapter 5 (p. 107).

The first operation searches for a string (first argument) in another string (second argument). It returns the first position in the second argument where the first argument is found. −1 is returned if the second string does not contain the first.

tclsh> string first "uu" "uunet.uu.net"
0

The last operation returns the last position where the first argument is found.

tclsh> string last "uu" "uunet.uu.net"
6

The length operation returns the number of characters in the string.

tclsh> string length "foo"
3
tclsh> string length ""
0

The index operation returns the character corresponding to the given index (second argument) in a string (first argument). For example:

tclsh> string index "abcdefg" 2
c

The range operation is analogous to the lrange command, but range works on strings. Indices correspond to character positions. All characters between the indices inclusive are returned. The string "end" may be used to refer to the last position in the string.

tclsh> string range "abcdefg" 2 3
cd

The tolower and toupper operations convert an argument to lowercase and uppercase, respectively.

tclsh> string tolower "NeXT"
next

The trimleft operation removes characters from the beginning of a string. The string is the first argument. The characters removed are any which appear in the optional second argument. If there is no second argument, then whitespace is removed.

string trimleft $num "-"     ;# force $num nonnegative

The trimright operation is like trimleft except that characters are removed from the end of the string. The trim operation removes characters from both the beginning and the end of the string.

The following command appends a string to another string in a variable.

set var "$var$string"

Appending strings is a very common operation. For example, it is often used in a loop to read the output of a program and to create a single variable containing the entire output.

Appending occurs so frequently that there is a command specifically for this purpose. The append command takes a variable as the first argument and appends to it, all of the remaining strings.

tclsh> append var "abc"
abc
tclsh> append var "def" "ghi"
abcdefghi

Notice that the first argument is not passed by value. Only the name is passed. Tcl appends the remaining arguments in place—that is, without making a copy of the original list. This allows Tcl to take some shortcuts internally. Using append is much more efficient than the alternative set command.

This behavior of modifying the string in place is unusual—none of the string operations work this way. However, the lappend command does. So just remember that append and lappend work this way. It might be helpful to go back to the lappend description (page 42) now and compare its behavior with append.

Both append and lappend share a few other features. Neither requires that the variable be initialized. If uninitialized, the first string argument is set rather than appended (as if the set command had been used). append and lappend also return the final value of the variable. However, this return value is rarely used since both commands already store the value in the variable.

Tcl provides the info command to obtain assorted pieces of internal information about Tcl. The most useful of the info operations is "info exists“. Given a variable name, "info exists" returns 1 if the variable exists or 0 otherwise. Only variables accessible from the current scope are checked. For example, the following command shows that haha has not been defined. An attempt to read it would fail.

tclsh> info exists haha
0

Three related commands are "info locals“, "info globals“, and "info vars“. They return a list of local, global, and all variables respectively. They can be constrained to match a subset by supplying an optional pattern (in the style of the "string match" command). For example, the following command returns a list of all global variables that begin with the letters "mail“.

info globals mail*

Tcl has similar commands for testing whether commands and procedures exist. "info commands" returns a list of all commands. "info procs" returns a list of just the procedures (commands defined with the proc command).

"info level" returns information about the stack. With no arguments, the stack depth is returned. "info level 0" returns the command and arguments of the current procedure. "info level −1" returns the command and arguments of the calling procedure of the current procedure. −2 indicates the next previous caller, and so on.

The "info script" command returns the file name of the current script being executed. This is just one of a number of other information commands that give related types of information useful in only the most esoteric circumstances. See the Tcl reference material for more information.

While the info command can be used on arrays, Tcl provides some more specialized commands for this purpose. For example, "array size b" returns the number of elements in an array.

tclsh> set color(pavement) black
black
tclsh> set color(snow) white
white
tclsh> array size color
2

The command "array names" returns the element names of an array.

tclsh> array names color
pavement snow

Here is a loop to print the elements of the array and their values.

tclsh> foreach name [array names color] {
    puts "The color of $name is $color($name)."
}
The color of snow is white.
The color of pavement is black.

The unset command unsets a variable. After being unset, a variable no longer exists. You can unset scalar variables or entire arrays. For example:

unset a
unset array(elt)
unset array

After a variable is unset, it can no longer be read and "info exists" returns 0.

Variable accesses can be traced with the trace command. Using trace, you can evaluate procedures whenever a variable is accessed. While this is useful in many ways, I will cover trace in more detail in the discussion on debugging (Chapter 18 (p. 402)) since that is almost always where trace first shows its value. In that same chapter, I will also describe how to trace commands.

The error command is used to create error conditions which can be caught with the catch command. error is useful inside of procedures that return errors naturally already.

For example, if you wanted to restrict the qf routine so that a could not be larger than 100, you could rewrite the beginning of it as:

proc qf {a b c} {
    if {$a > 100} {error "a too large"}
    set s [expr sqrt($b*$b-4*$a*$c)]
    . . .

Now if a is greater than 100, "catch {qf ...}" will return 1. The message "a too large" will be stored in the optional variable name supplied to catch as the second argument.

The uplevel command is similar in spirit to upvar. With uplevel, commands can be evaluated in the scope of the calling procedure. The syntax is similar to eval. For example, the following command increments x in the scope of the calling procedure.

uplevel incr x

The uplevel command can be used to create new control structures such as variations on if and while or even more powerful constructs. Space does not permit a discussion of this technique, so I refer you to the Tcl reference material.

The following procedure (written by Karl Lehenbauer with a modification by Allan Brighton) provides static variables in the style of C. Like variables declared global, variables declared static are accessible from other procedures. However, the same static variables cannot be accessed by procedures in different files. This can be helpful in avoiding naming collisions between two programmers—both of whom unintentionally choose the same names for global variables that are private to their own files.

proc static {args} {
    set unique [info script]
    foreach var $args {
        uplevel 1 "upvar #0 static($unique:$var) $var"
    }
}

The procedure makes its arguments be references into an array (appropriately called static). Because of the uplevel command, all uses of the named variable after the static call become references into the array. The array elements have the file name embedded in them. This prevents conflicts with similarly-named variables in other files. By setting unique to "[lindex [info level −1] 0]“, static can declare persistent variables that cannot be accessed by any other procedure even in the same file.

If you have significant amounts of Tcl code, you may want to consider even more sophisticated scoping techniques. For instance, [incr Tcl], written by Michael McLennan, is a Tcl extension that supports object-oriented programming in the style of C++. [incr Tcl] provides mechanisms for data encapsulation within well-defined interfaces, greatly increasing code readability while lessening the effort to write such code in the first place. The Tcl FAQ describes how to obtain [incr Tcl]. For more information on how to get the FAQ, see Chapter 1 (p. 20).

If a file name starts with a tilde character and a user name, the open command translates this to the named user’s home directory. If the tilde is immediately followed by a slash, it is translated to the home directory of the user running the script. This is the same behavior that most shells support.

However, the open command does not do anything special with other metacharacters such as "*" and "?“. The following command opens a file with a "*" at the end of its name!

open "/tmp/foo*" "w"

The glob command takes file patterns as arguments and returns the list of files that match. For example, the following command returns the files that end with .exp and .c in the current directory.

glob *.exp *.c

The result of glob can be passed to open (presuming that it only matches one file). An error occurs if no files are matched. Using glob as the source in a foreach loop provides a way of opening each file separately.

foreach filename [glob *.exp] {
    set file [open $filename]
    # do something with $file
    close $file
}

The characters understood by glob are * (matches anything), ? (matches any single character), [] (matches a set or range of characters), {} (matches a choice of strings), and (matches the next character literally). I will not go into details on these—they are similar to matching done by many shells such as csh. Plus I will be talking about most of them in later chapters anyway.

If file names do not begin with a "~" or "/“, they are relative to the current directory. The current directory can be set with cd. It is analogous to the cd command in the shell. As in the open command, the tilde convention is supported but all other shell metacharacters are not. There is no built-in directory stack.

tclsh> cd ~libes/bin
tclsh> pwd
/usr/libes/bin

The file command does a large number of different things all related to file names. The first argument names the function and the second argument is the file name to work on.

Four functions are purely textual. The same results can be accomplished with the string functions, but these are very convenient.

The "file dirname" command returns the directory part of the file name. (It returns a "." if there is no slash. It returns a slash if there is only one slash and it is the first character.) For example:

tclsh> file dirname /usr/libes/bin/prog.exp
/usr/libes/bin

The opposite of "file dirname" is "file tail“. It returns everything after the last slash. (If there is no slash, it returns the original file name.)

The "file extension" command returns the last dot and anything following it in the file name. (It returns the empty string if there is no dot.) For example:

tclsh> file extension /usr/libes/src/my.prog.c
.c

The opposite of "file extension" is "file rootname“. It returns everything but the extension.

tclsh> file rootname /usr/libes/src/my.prog.c
/usr/libes/src/my.prog

While these functions are very useful with file names, they can be used on any string where dots and slashes are separators.

For example, suppose you have an IP address in addr and want to change the last field to the value stored in the variable new. You could use split and join, but the file name manipulation functions do it more easily.

tclsh> set addr
127.0.1.2
tclsh> set new
42
tclsh> set addr [file rootname $addr].$new
127.0.1.42

When you need to construct arbitrary compound names, consider using dots and slashes so that you can use the file name commands. You can also use blanks, of course, in which case you can use the string commands. However, since blanks are used as argument separators, you have to be much more careful when using commands such as eval.

The file command can be used to test for various attributes of a file. Listed below are a number of predicates and their meanings. Each variation returns a 0 if the condition is false for the file or 1 if it is true. Here is an example to test whether the file /tmp/foo exists:

tclsh> file exists /tmp/foo
1

The predicates are:

All the predicates return 0 if the file does not exist.

While the predicates make it very easy to test whether a file meets a condition, it is occasionally useful to directly ask for file information. Tcl provides a number of commands that do that. Each of these takes a file name as the last argument.

The "file size" command returns the number of bytes in a file. For example:

tclsh> file size /etc/motd
63

The "file atime" command returns the time in seconds when the file was last accessed. The "file mtime" command returns the time in seconds when the file was last modified. The number of seconds is counted starting from January 1, 1970.

The "file type" command returns a string describing the type of the file such as file, directory, characterSpecial, blockSpecial, link, or socket. The "file readlink" command returns the name to which the file points to, assuming it is a symbolic link.

The "file stat" command returns the raw values of a file’s inode. Each value is written as elements in an array. The array name is given as the third argument to the file command. For example, the following command writes the information to the array stuff.

file stat /etc/motd stuff

Elements are written for atime, ctime, mtime, type, uid, gid, ino, mode, nlink, dev, size. These are all written as integers except for the type element which is written as I described before. Most of these values are also accessible more directly by using one of the other arguments to the file command. However, some of the more unusual elements (such as nlink) have no corresponding analog. For example, the following command prints the number of links to a file:

file stat $filename fileinfo
puts "$filename has $fileinfo(nlink) links"

If the file is a symbolic link, "file stat" returns information about the file to which it points. The "file lstat" command works similarly to "file stat" except that it returns information about the link itself. See the UNIX stat documentation for more information on stat and lstat.

All of these file information commands require the file to exist or else they will generate an error. This error can be caught using catch.