Tcl 8.5 Network Programming

The great flexibility of Tcl comes from its ability to extend the available set of commands known to the interpreter by adding additional extensions, that is, Tcl packages. Packages can be written in pure Tcl, making them platform-independent, or in native code like C/C++, which is then compiled for a specific target platform. It is possible that a package will consist of both of these. There are a lot of packages available on the Internet, both free of use and commercial. A good place to start is Tcllib—Tcl Standard Library. This is a set of extensions written in pure Tcl, available at http://tcllib.sourceforge.net/. Soon you will notice that we will use various packages from this repository for the examples in this book.

What's more interesting is that if you find out that nobody created an extension you would like to use, you will be able to create your own one and share it with the community.

One of the extensions this chapter will cover is Tk, which was developed by John Osterhout. Tk is a cross-platform GUI framework, which provides the same functions for Tcl as AWT and Swing do for Java. In other words, it is a library that contains a set of typical basic elements (widgets) such as buttons, frames, a canvas, menus, and so on. Tk widgets are flexible in terms of their customization options; almost every aspect may be defined at time of creation or modified later. One of its features is a native "look and feel", which simply means that Tcl/Tk graphical applications do not differ significantly from other native applications in terms of the look and usage. As over the years, Tk appearance started to fall behind the looks of modern operating systems, a number of extensions were created. Also worth mentioning is the Tile Widget Set (http://tktable.sourceforge.net/tile/), which brings re-implementation of some Tk core widget, as well as addition of a few new widgets. Tile is also an engine that allows the usage of themes. According to the Tile documentation:

Tile has been incorporated into Tk core functionality in version 8.5, which means it is now available in all Tcl/Tk distributions. Although many Tk widgets have corresponding newer Tile equivalents, they can coexist in one application and the developer has the freedom of choice as to which version to use.

As an example, have a look at the following screenshot of SnackAmp that illustrates Tcl's possibilities in the field of GUI applications:

Tk became so popular that it is no longer Tcl-specific. It is now possible to use it in other scripting languages like Perl or Python.

In the case of Microsoft Windows, ActiveTcl is substantially the only choice. Installation is simple; the installer is distributed in the form of an executable file (named as something like ActiveTcl8.5.7.0.290198-win32-ix86-threaded.exe). Once you download and run it, you will be presented with a graphical installation wizard similar to the one shown in the following screenshot:

On subsequent screens, you will be presented with a detailed ActiveTcl License. You will also be able to specify installation directory—associate the application with the .tcl extension and configure some of the other details. For the rest of this chapter, we will assume that Tcl is installed in the C:\Tcl directory.

The installer updates system variable PATH with the path to the directory where Tcl binaries are located, that is C:\Tcl\bin. It allows you to execute commands like tclsh85.exe anywhere, without specifying the directory's full path. Note that, as usual, you are advised against using a path containing whitespaces.

We will consider Unix-compatible systems using Ubuntu 9.04 Linux as a popular, easy-to-get example. In the case of these systems, you have more choices than you do with Windows. One of the choices you have is to install ActiveTcl (there is a good chance it supports your platform), another is to search for a precompiled Tcl distribution. Ubuntu, for example, comes with a significant number of optional packages of additional software prepared by the community. Among them are of course binary compilations of Tcl. It is possible that your system already has the Tcl distribution installed, but even if not, it is extremely easy to install it, because Ubuntu will be able to suggest what packages should be installed based on the commands that these packages provide for the system. The following is a screenshot of such a situation:

The user wants to execute the tclsh command to get Tcl interactive shell. The package that provides this command is not yet installed, and the system informs the user what packages are available. In this case, we have decided to choose tcl8.5 and install it using the command-line command as follows:

sudo apt-get install tcl8.5

Once installed, you can run the tclsh command to get the interactive Tcl shell as follows:

To verify the detailed version of Tcl interpreter which you have just installed, use the info patchlevel command.

Tk comes in a separate Ubuntu package. You will be notified of this if you attempt to run an application that requires it, for example wish. Similarly, it can be installed with:

% sudo apt-get install tk8.5.

Just like core Tcl installation, extensions, that is Tcl packages, can also be installed in two ways: the first is to get the source code of an extension and build (compile) it, and the second one is to find, download, and install a pre-built package.

In order to be able to use the extension in your script, it must be available for the interpreter. There are several locations where Tcl can search for it, and these locations are kept in the special Tcl variable called auto_path. You can learn its value by starting the Tcl shell and executing the following command:

puts $auto_path

The puts command prints the content of the specified variable to standard output. In the case of Windows, the output appears as:

Now that you know this, you can put the packages you require under the C:\Tcl\lib location to make them available for the interpreter. The concept of the $auto_path variable and other packages will be described in more detail in the next chapter.

ActiveTcl comes with a handy utility called Teacup. This utility allows for easy installation of prebuilt Tcl extensions from external remote repositories called Tcl Extension Archives. These archives, also known as Teapot, are centrally managed sites. Currently, there is one public Teapot maintained by ActiveState. By using Teacup, you can install the package you need into your local repository and then use it in your scripts. It will automatically solve dependencies, localize package(s), and download and install them.

It is hardly possible that you have not heard about Eclipse nowadays. An open source IDE supporting a wide variety of languages, extensible with plugins is considered as one of the best programming environments, and it is all free. Due to the fact that Eclipse was developed in Java, the CPU/memory requirements may be slightly higher than in case of native applications, but in return, it is available for the Windows, Linux, and Mac platforms.

First you have to install the Java Runtime Environment (JRE), we strongly suggest installing latest version available (at the moment it is version 6 Update 17), you can get it from http://java.com. We will discuss Eclipse Classic 3.5.0 available for download at http://www.eclipse.org/downloads/. The installation process is simple—just download and unzip the file to a location of your choice and run eclipse.exe. The full description of Eclipse is out of scope of this book, we will present only the necessary steps to get it running for Tcl development purposes.

By default, Eclipse supports only Java development, so we have to install an additional extension called the Dynamic Languages Toolkit (DLTK) for Tcl support. In order to do this it, you have to navigate to the Help | Install New Software… menu. A new window will show up, as shown in the following screenshot:

First, select the Galileo site from the list at the top. Eclipse will download a list of all available extensions from this site; this may take a while. Once the list is visible, expand Programming Languages and select Dynamic Languages Toolkit TCL Development Tools. Once you click on Next, Eclipse will automatically resolve dependencies and select all the necessary plugins to install. In this case, it will choose to install the DLTK Core and Eclipse Modelling Framework (EMF) extensions, as shown in the following screenshot:

Following this, Eclipse will download and install all the necessary files, and ask you to restart. Once it is done, you have to configure installed Tcl interpreters. Eclipse requires at least one interpreter in order to be able to run scripts. To configure it, navigate to Window | Preferences to open the preferences dialog, and then go to Tcl | Interpreters. Click the Add… button on this pane, and then Browse… and navigate to the interpreter binary, which is installed at C:\Tcl\bin\tclsh85.exe. Once done, you should have configured the default interpreter like here, as shown in the following screenshot:

Now you have your Eclipse fully configured to create and run Tcl scripts! To get a taste of working with Eclipse, let's create the same Hello World example. Navigate to File | New | Project… and choose Tcl Project from the Tcl category and then create a project named TclHelloWorld—it will be shown in the Script Explorer view (by default, on the left of the Eclipse window). The next step is to right-click on the project name in this view and select Tcl File, and name it main.tcl. As a template, select Tcl File. Eclipse will create the file with a specific header that we will explain later. Add the puts command to that script, just as you did in the previous example. Now it is time to execute the script—right-click on it and select Run As | Tcl Script. The output of this execution will be visible in the Console view. The following screen illustrates it:

Komodo, available for download at http://www.activestate.com/komodo, comes in two flavors: free Komodo Edit and paid Komodo IDE. Both support a wide range of scripting languages, including PHP, Ruby, Python, and of course Tcl. The first one is a simple editor with syntax checking and coloring, and also Project Management abilities. The second one extends the offered functionality as it comes with a debugger.

Similar to Eclipse, you can create a project (using File | New | New Project…) and a file inside it (right-click on project name in the left pane and select Add | New file…). The new file is created based on a language-specific template, which comes with the universal header described later in this chapter.

To run the script, navigate to Tools | Run Command… and enter tclsh85 %F in the Run dialog, and then click on the Run button.

If you find the standard Tcl shell too primitive, you must definitely have a look at tkcon—a standard console replacement with many useful features including a command history and syntax highlighting. What is even more interesting is that it is implemented as another Tcl package, and therefore it is perfectly possible to embed tkcon in to your Tcl application. The following is a screenshot of tkcon console, with the puts $auto_path command's output:

Tkcon is, by default, included in the ActiveTcl distribution. To install it on Ubuntu, enter:

% sudo apt-get install tkcon .

In order to run it, simply execute the command tkcon.

The comprehensive documentation for Tcl 8.5 is located at http://www.tcl.tk/doc/. This section does not intend to replace or compete with it, but to briefly introduce Tcl's grammar and rules. Therefore, we strongly recommend reading the documentation, especially the descriptions of the main commands.

Let's revisit the main.tcl script which was introduced earlier in this chapter:

#my first Tcl script
puts "Hello World one more time!"

The first line is the comment. The second line has the puts command with one parameter —the text string—in quotations marks. As we mentioned previously, you can run the script with:

tclsh main.tcl

However, in some cases, it would be far more comfortable to run it as a standalone program. On Windows, you can associate the .tcl extension with the Tcl interpreter to achieve this. On Unix, the script will look like:

#!/usr/bin/tclsh
#my first Tcl script
puts "Hello World one more time!"

The first line starts with the #! sequence, often referred to as shebang. The presence of these two characters at the very beginning of the executable file informs the system's program loader that the file is a script and also specifies the interpreter which should be used to run it. In this case, the first line issues an instruction to Unix shell, specifying that the script should be interpreted by /usr/bin/tclsh. As the # character itself is often a comment marker, the line will be ignored by the interpreter. However, it is not a good idea to hardcode the path, because it may be different for other systems, thus making our code not non-portable. A better solution is:

#!/bin/sh
#my first Tcl script \
exec tclsh "$0" $@"
puts "Hello World one more time!"

In this case, the script is interpreted by standard sh shell. This shell is unable to run Tcl commands, but it will run the exec command perfectly, effectively launching tclsh, passing the script name and other arguments (if any). The trick is that we do not want the Tcl interpreter to process the exec command, as it was intended for sh only. In order to avoid this problem, the previous line ends with \, so both the second and third lines of that script are treated like comments by the interpreter.

Recently, also another solution has gained popularity, that is:

#!/usr/bin/env tclsh #my first Tcl script
puts "Hello World one more time!"

The env command searches for tclsh using system PATH variable and executes it, therefore, no direct path to it is required.

In the case of "one-liner" examples, we can also easily enter them directly into the Tcl shell—you will recognize them by the % prompt character. It is worth mentioning that the shell offers hints about the syntax of any command. This is extremely useful if you don't quite remember the required arguments or their order:

% puts
wrong # args: should be "puts ?-nonewline? ?channelId? string"

The syntax of such a hint is commonly used throughout the Tcl documentation. Question marks indicate optional arguments (in this example, nonewline or channelId are both optional).

As with any other language, Tcl allows us to define variables. Let's consider the following example:

set myVariable "someValue"
puts $myVariable

The first command set creates a variable named myVariable and sets its value to somevalue. The second command, that is puts, prints the variable's value on the screen. myVariable is the variable name and the $ operator is used to get its value. When the interpreter starts processing the second line, it will first substitute all the variable values, so the line will effectively be puts "someValue", and then it will execute it. This will result in the following output:

someValue

To delete a variable, use the unset command:

% unset myVariable
% puts $MyVariable
can't read "MyVariable": no such variable

In an earlier example, we used "" to group Hello world one more time! into one single argument. Without it, we would get a syntactical error, as each word would be treated as separate argument for the puts command:

% puts Hello world one more time!
wrong # args: should be "puts ?-nonewline? ?channelId? string"

It is also worth mentioning that whitespaces could be also escaped using the \ character, as shown in the following example:

% puts Hello\ world\ one\ more\ time!
Hello world one more time!

If the argument consists of only one word, grouping is not necessary, but it's still possible.

The text inside quotation marks is processed before being passed to the command. What this it means is that all references to variables are replaced with the variable's values, for example:

% set var World; puts "Hello $var"
Hello World

The substitution gets complicated if you don't want to have any whitespace between the variable's value and the text that follows. In this case, you can end the variable name with '\' or put it into {}, as in the following example:

% set var World; puts "Hello $vars!"
can't read "vars": no such variable
% puts "Hello $var\s!"
Hello Worlds!
% puts "Hello ${var}s!"
Hello Worlds!

The third option is the preferred one because of its readability.

Grouping is also possible with curly braces, that is, {}. The difference is that text inside the quotation marks is evaluated, and the text inside {} is not, consider the following:

% set var World; puts {Hello $var}
Hello $var

In the second case, $var was not substituted with its real value World, because it was inside {}.

One more unique feature of curly braces is that they allow multiple lines inside them. In the code:

% puts {Hello
World!}
Hello
World!

The new line character that terminates the first line is not processed, and therefore, it also breaks the output into two lines. Of course, it is legal to also use \:

% puts {Hello\
World!}
Hello World!

The ability to execute commands wouldn't be very valuable if there wasn't some way to provide the result of one command to another. In Tcl, we can use [] to execute a command and capture its return value:

% set var [info patchlevel]; puts "Current patchlevel is: $var"
Current patchlevel is: 8.5.6

In this example, the output of the info patchlevel command is used as the value for the var variable. It is also perfectly possible to use [] inside quotation marks, as its content will be processed by the interpreter:

% puts "Current patchlevel is: [info patchlevel]"
Current patchlevel is: 8.5.6

Basically, every variable in Tcl can be considered as a string. The internal representation of such a variable depends on its execution state (see Chapter 2, Advanced Tcl features for more details). Being a dynamic language, Tcl converts the value of a variable to a suitable type at runtime. Let's consider the following example:

% set x "2"; expr $x + 3
5
% set x "text"; expr $x + 3
invalid bareword "text"
in expression "text + 3";

We introduce the new Tcl command expr that allows arithmetic operations. In this example, the string"2" is converted to an integer by expr and it returns correct value, but the string text causes an error, because it cannot be converted.

To operate on strings, the string command is extremely useful. The convention of this command is that it accepts a subcommand name as the first argument. For example, if we assume that str is a Hello World! string, in order to get its length, you can use:

% string length $str
12

Also, in order to reverse it, use:

% string reverse $str
!dlroW olleH

The String match command can be used to verify if the given string matches the pattern. The pattern is basically another string, but apart from normal characters, some special sequences can be also used:

The command returns 1 if the string is successfully matched and it returns 0 otherwise:

% set str aStringToMatch
% string match *ToMatch $str
1
% string match ?StringToMatch $str
1
% string match {[a-c]StringToMatch} $str
1
% string match {[b-c]StringToMatch} $str
0

Note that in the last two cases, this pattern is put into curly braces to prevent the interpreter from considering the content of the [] braces as a command to be executed.

Describing every string subcommand is beyond the scope of this chapter, the details can be found in the manual at http://www.tcl.tk/man/tcl8.5/TclCmd/string.htm.

It is worth mentioning at this point that depending on the context, the variable's value may be treated as a text string, a number, or a logical value, just as we will see in the following examples.

More than pure strings, Tcl introduces the concept of two interesting data types—lists and arrays (hashmaps).

set myList [list element1 element2 element3]

set myList "element1 element2 element3"

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

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

% puts $myList
one two {another list here}

% llength [list one two three]
3

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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]"

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

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]

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

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

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$]"

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

lassign {1 2 3} a b c

set a 1
set b 2
set c 3

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

% array exists myArray
1
% array exists fictionalArray
0

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

array unset myArray prefix,*

% array get myArray
index1 element1 index2 element2 3 element3

array get myArray prefix,*

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

% array names myArray
index1 index2 3

array names myArray 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

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

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

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

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

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

Flow control and loop instructions

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

Flow control

The first one is the command if:

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

Depending on the boolean value of the condition variable, the first or the second part of the command is executed. In this case, the output is:

condition is true

Note that the entire if command call could be written in one line:

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

The first argument is an expression representing a logical condition. The value is evaluated in the same way as in case of the expr command.

It is possible to skip else and the second script body, or to add more conditions by using elseif with another condition, and a script to execute in case the condition is true.

The second command switch allows us to decide what action should be taken based on the value passed; for example, consider the following example code:

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

As the value of value variable is second, the second script body is passed to the Tcl interpreter, resulting in the output second value on the screen.

It is possible to skip the default section. Also, more than one acceptable value separated by the character may be defined for each of the sections:

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

The values 1, 1st, or first will all match with the first section.

Finally, it is possible to use patterns that we have used with string match command to match the appropriate section, by specifying the -glob option with the switch command:

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

In this case, both the values second and 2nd would match with the second option.

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.

Defining your own commands

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: