A Tcl list holds an ordered sequence of elements such as strings, other lists, and other variables. To create a list, you can use the list command:

set myList [list element1 element2 element3]

In this example, we create a list using three elements, separated with whitespaces, and assign the list to the myList variable.

What is interesting is that there is no straight demarcation between the list and the string, and therefore, the following code also creates a list:

set myList "element1 element2 element3"

Curly braces are also possible here. The conclusion is that every string may be considered as a list. The advantage of using the list command is that it takes care of correct formatting, adding braces and backslashes when necessary. Consider either of the following two commands:

set myList "one two {another list here}"
set myList {one two {another list here}}

They will create a list in which the third element will be another list consisting of elements specified in curly braces. The same effect can be achieved using the list command:

set myList [list one two [list another list here]]

From the user's point of view, a list is both a string and a list, because there is no visible difference:

% puts $myList
one two {another list here}

As you can see, the list command added the {} braces at the correct points.

So why even bother with lists? Lists allow you to organize and structure your data, and the benefits of using them are that Tcl offers a set of commands that operates on lists. Lists tend to be extremely useful in typical scripts, therefore, we will briefly review the possible operations on them.

To get the number of elements in your list, use llength. This command takes one parameter, that is, the list. The output is the number of elements in the list.

% llength [list one two three]
3

The command lindex retrieves an element from a list. In basic usage, it takes the list and the index of the element as arguments. Just as in other programming languages, indexes start from zero in Tcl.

% set myList [list one two three]; lindex $myList 0
one

We can also specify the index as the special keyword end, which indicates the last element. For example:

% set myList [list one two three]; lindex $myList end
three

We can also specify end-<n>, which indicates the nth element from the end. The value end-0 is the same as the end value; the value end-1 specifies the last but one item and so on. For example:

% set myList [list one two three]; lindex $myList end-1
two

If the retrieved element is another list, lindex also has the ability to retrieve its element by providing additional indexes:

% set myList [list one two [list another list here]]; lindex $myList 2 0
another

In this example, the third element (its index value is 2) of myList is, in turn, another embedded list, and we retrieve its first element—string another—by specifying an additional index value to lindex — 0.

The lrange command returns a subset of the original list. It accepts the list as the first argument followed by the index of the first and last items that should be included in the new list. Both the first and last elements are included in the resulting list. The index can be in the form of an integer or in the end or end-<n> forms.

This command returns a new list consisting of elements that is the start to end indexes:

% set myList {1 2 3 4 5}; puts [lrange $myList 1 3]
2 3 4

In this case, 1 is the starting index and 2 the ending one, so the returned list consists of the second and third elements of the original list.

We can use the lappend command to add one or more elements to an existing list. It accepts the variable name of the list, followed by any number of elements to be added to the list. The command inserts new elements at the end of the specified variable and does not return the new list—instead, it is automatically set as the new value of the specified variable.

For example:

% set myList {one two}; lappend myList 3 4; puts $myList
one two 3 4

This command can also be used to create new lists if the variable passed as the first argument does not exist.

The linsert command can be used to insert one or more elements into a list at the specified index. Unlike lappend, it takes the value of the list as its first argument, followed by the index to insert elements at and any number of elements to insert. For example:

% set myList {1 5}; set myList [linsert $myList 1 2 3 4]; puts $myList
1 2 3 4 5

As for any other list-related command, the index can be in the form of an integer or in the end or end-<n> forms.

The lset command allows you to replace the values of elements with new ones. It accepts a variable name, and one or more indexes, followed by the new value to set. The changed list is stored back in the variable specified as the first argument.

For example, we can specify a single index to modify the nth element of a list:

% set myList {1 2 3}; lset myList 1 0; puts $myList
1 0 3

Similar to lindex, this command can access and modify elements of sub-lists. For example:

% set myList [list one two [list another list here]]; lsert myList end 0 new; puts $mylist
One two {new list here}

The lreplace command is also similar to it, but allows replacing a set of elements. It accepts the list as the first argument, the start and end indexes to replace, and the new items to insert instead of the specified elements. The command removes elements between start and end inclusively and inserts new items in their place. Like linsert, it does not alter an existing list, but returns a new one. For example:

% set myList {1 2 3 4 5}; puts [lreplace $myList 1 3 0 0]
1 0 0 5

In case you don't specify new replacement items, the command will only remove elements within a range:

% set myList {1 2 3 4 5}; puts [lreplace $myList 1 3]
1 5

The lsort command can be used to sort lists in Tcl. For example:

% set myList {5 1 3 4 2}; puts [lsort $myList]
1 2 3 4 5

It is also possible to modify the sorting order by specifying additional options, for example -decreasing:

% set myList {5 1 3 4 2}; puts [lsort -decreasing $myList]
5 4 3 2 1

By default, the elements are compared as text values—therefore, when sorting 9, 10, 11, and, 2, the result would be 10, 11, 2, and 9. The following switches allow us to define how elements are compared, which affects the output of the sorting operation:

Dictionary-based sorting is similar to text-based comparison, except that character case is ignored here. An exception is when both the elements are the same, in that case, the uppercase elements are put before lowercase elements. If strings contain numbers, they are compared as integers, not characters. For example, when sorting 9, 10, 11, and 2 using the -dictionary switch, the result would be 2, 9, 10, and 11.

We can also tell lsort to use all elements in the list as sub-lists and compare them only using specified elements of these sub-lists, by using the -index option. The value for the option can be a single index or a list of indexes, where each element of the index list indicates an index in a sub-list. For example:

puts [lsort -integer -index 1 {{Alpha 2} {Beta 1} {Gamma 3}}]
{Beta 1} {Alpha 2} {Gamma 3}

Another option is to use your own custom implementation of the comparison algorithm. To do so, you have to define a command that accepts two arguments (items from the list that is being sorted) and returns the integer value by complying to the following rules:

It is illustrated in the following example:

proc compareStrings {s1 s2} { return [expr {[string length $s1] - [string length $s2]}]
}
set animals [list snake crocodile monkey cat]
puts "default: [lsort $animals]"
puts "custom: [lsort -command compareStrings $animals]"

We have the animals list that contains some animal names. The default implementation will sort it in the alphabetical order, but we will be able to define our own implementation in the form of the compareString procedure, which will sort it in the order of the word's length:

default: cat crocodile monkey snake
custom: cat snake monkey crocodile

An interesting property of the lsort command is that when two elements are considered as the same, their order in the output is the same as the order in which they were taken as inputs. This can be used to sort lists of lists using multiple orders. We need to sort the list by each element we want it to be sorted using, but in the reverse order.

For example, we can sort a list where each element is a sub-list consisting of first name, last name, and age. If we want to order it by the last name and the decreasing order of age for the same last names, we need to sort it by age first and later by the last name:

set list {{John Doe 32} {Joe Smith 29} {Jane Doe 35}}
set list [lsort -integer decreasing -index 2 $list]
puts [lsort -dictionary -index 1 $temp]

The result of this sort would be:

{John Doe 32} {Jane Doe 35} {Joe Smith 29}

You can search through your list to find the element(s) that match your pattern using lsearch:

% set myList {zero one two three}; puts [lsearch $myList three]
3

This command looks for the element three in myList, and returns the index of the first occurrence of the searched element—3 (or -1 if element is not found). It will be able to accept options such as:

These options can be combined together; for your convenience, here is an example of their usage:

set myList {zero one two three}
puts "First match (glob) : \
[lsearch -glob $myList *t*] -> \
[lsearch -inline -glob $myList *t*]"
puts "First match (regexp): \
[lsearch -regexp $myList e$] -> \
[lsearch -inline -regexp $myList e$]"
puts "All matches (glob) : \
[lsearch -all -glob $myList *t*] -> \
[lsearch -all -inline -glob $myList *t*]"
puts "All matches (regexp): \
[lsearch -all -regexp $myList e$] -> \
[lsearch -all -inline -regexp $myList e$]"

The expression *t* will match any string containing the letter t and the regular expression e$ will match any string that ends with the letter e.

The output will be:

First match (glob) : 2 -> two
First match (regexp): 1 -> one
All matches (glob) : 2 3 -> two three
All matches (regexp): 1 3 -> one three

The command lassign allows you to assign values from the list to different variables on a single line. For example:

lassign {1 2 3} a b c

The effect of this command is equal to the execution of the following:

set a 1
set b 2
set c 3

The first argument is a list, and the consecutive arguments are names of the variables. If there are more variables than list elements, the remaining elements will be set to empty strings.

Another important data type for storing a set of values is an array. In Tcl, arrays are essentially associative maps, because any string value is permitted as an array key (index). Consider the following example:

set myArray(key1) element1
set myArray(key2) element2
set myArray(3) element3

After looking at the first line, the interpreter knows that the myArray variable will be an array, because of presence of the () braces. Inside these braces, the array key key1 is written, and it is mapped to the string element1. We have three keys overall—key1, key2, and 3 (note that the last one is different from the first two, but still valid)—that point to three values: element1, element2, and element3 respectively. The key name can contain any character, and also spaces (of course, with the correct syntax, for example, by using the Esc key with a backslash).

To manipulate array variables, use the array command with the appropriate operator and arguments. The most common operations are:

The command array exists returns the value 1 only when the variable passed as an argument exists and is an array:

% array exists myArray
1
% array exists fictionalArray
0

Otherwise, the command will return 0.

We can use the array unset command to delete an array:

% array exists myArray
1
% array unset myArray; array exists myArray
0

We can also delete a specified key or keys by specifying the pattern to match the keys that we want to delete as follows:

array unset myArray prefix,*

This will delete all the elements of an array that starts with prefix,.

You can convert an array into a list using array get:

% array get myArray
index1 element1 index2 element2 3 element3

The list it returns consists of name-value pairs. This means that for each element in the array, this command returns its name as an element followed by its value as another element.

We can also use array get to get specific elements of an array, by adding a pattern to match keys, similar to array unset. For example:

array get myArray prefix,*

This will return information only for keys starting with prefix,.

To reverse this operation and set one or more keys in an array from the name-value pairs, we can use array set command:

% array set anotherArray "1 first 2 second"
% array exists anotherArray
1

If you want to get a list of key names existing in a particular array, the array names command comes handy:

% array names myArray
index1 index2 3

Similarly, we can get only a subset of names by running:

array names myArray prefix,*

This will return only the keys which start with prefix,.

% array size myArray
3

set myarray(somekey) "my value"

set myarray(somekey) "my value"
return $myarray

set my3DArray(0.0.0) element1
set my3DArray(0.0.1) element2
set my3DArray(1.0.1) element3

To address the previously mentioned drawbacks of arrays, a new data type was introduced, which is quickly gaining acceptance and popularity among Tcl developers—dictionary. Dictionaries are somewhat similar to arrays in that they keep mapping between key and value, but a dictionary is treated as an object. Dictionaries can also be truly multi-dimensional. The other difference is that dictionaries are significantly faster than arrays.

The new command dict was introduced to operate on dictionaries. The command is natively present in Tcl 8.5, but it can be also used in Tcl 8.4 by adding the dict package.

To create a dictionary, use the dict create command with the equal number of arguments; alternately, keys and values:

set myDict [dict create key1 value1 key2 value2 key3 value3]

The previous line creates a dictionary with three mappings and stores it in the myDict variable.

This command also allows us to create multi-level dictionaries:

set a [dict create 1 [dict create 2 [dict create 3 value]]]

Here, in dictionary a, the key 1 is mapped to other dictionary which has key 2 mapped to the third dictionary, wherein key 3 is mapped to value.

To access the mapped value, you can use the dict get command:

% dict get $myDict key2
value2
% dict get $a 1 2 3
value

The second command's invocation in this example demonstrates how to access a third-level variable.

These are only the basics, there are also many other operations available for dictionaries, these can be compared to the operations for arrays described earlier, because their concepts are similar. For the complete documentation of the dict command, you can refer to http://www.tcl.tk/man/tcl8.5/TclCmd/dict.htm.

There is a separate command called expr that handles all mathematical and logical operations. The command accepts an expression to evaluate. An interesting detail is that this expression can be passed as one argument, or as unlimited number of arguments. The following calls to expr will return the same result:

expr "3 + 7 * 2"
expr 3 + 7 * 2
expr {3 + 7 * 2}
expr 3+7*2

All the preceding operations return the value 17 as the result.

In case of logical expressions, values of arguments, such as 1 (or any other numeric non-zero value), true, TRUE, yes or YES are considered as logical true, and 0, false, FALSE, no, and NO as logical false. The following is an example of a logical AND (the&& operator) and OR (the operator || operator):

% expr yes && no
0
% expr yes || no
1

Like almost any other language, Tcl has a set of commands—conditional and iterational—to control the flow of the program.

set condition 1
if {$condition} {
puts "condition is true"
} else {
puts "condition is false"
}

condition is true

if {$condition} {puts "condition is true"} else {puts "condition is false"}

set value second
switch $value {
first {puts "first value"}
second {puts "second value"}
default {puts "some other value"}
}

switch $value {
1 1st - first {puts "first value"}
2 2nd - second {puts "second value"}
default {puts "some other value"}
}

switch -glob $value {
*st {puts "first value"}
*nd {puts "second value"}
default {puts "some other value"}
}

Loops

Tcl offers three commands that allow the iterational execution of code: for, while, and foreach.

The following example presents the usage of the for command:

for {set x 1} {$x < 4} {incr x} {puts "$x execution"}

The first argument is a code snippet executed at the beginning of the loop (in this example, it defines the counter variable x and initializes it with value 1). The second one is a condition that is checked to be logically true before each loop (if the counter is smaller than 4) and the third is the condition which is evaluated after each loop—in most cases, to increase the counter (for example, using the command incr). The last part of the statement is the body of the loop. The output of the example is:

The while command operates in a similar fashion, with the exception that the condition is evaluated after each loop, not before, and there is neither a start nor "after each loop" code section present. The equivalent of the previous example code written with while is:

set x 0
while {$x < 3} {incr x; puts "$x execution"}

The last command is foreach. The idea behind this command is to pass one (or more) lists, and the loop's body is executed for every element of the list:

The following example shows using two lists at the same time. In every loop, consecutive elements from both lists are assigned to the variables amount and item:

What is interesting here is that the lists are not required to be of the same length. If one of them is shorter, the empty value is used instead of using missing elements.

foreach also allows us to fetch multiple variables in one shot—for example, to put all data in a three-column table in HTML, it's just as easy as:

foreach {c1 c2 c3} $data {
append html "<tr><td>$c1</td><td>$c2</td><td>$c3</td></tr>"
}

Here $data is a list.

It is possible to control the flow of loops with the commands break and continue. Using the first one will cause the loop to exit permanently, even when the end condition is not met. The second command causes the skipping of the current loop and the immediate start of the next one, or the end of the loop if the command that was skipped was the last one.

Up until this moment, we have been using only commands delivered by 'someone'. It is time to create our own command for the first time:

proc myCommand {name} {
return "Hello $name, have a nice day!"
}

We use the proc command to define a new command (procedure) called myCommand. proc accepts three arguments: the procedure name, a list of arguments for this procedure, and its body. Note that just like any other argument, these have to be separated by whitespaces. In this case, myCommand accepts only one argument—name. The implementation is simple, because the command returns some greetings as its execution result. You can use this command in the same way as the others: