An introduction to the Tcl programming language

Sponsored Project: The Jim interpreter
A small footprint implementation of Tcl

Send a comment to the author


2.1 Anatomy of a command

Tcl programs are composed of commands, hence the name Tcl (pronounced Tickle): Tool Command Language. A command is a list of space separated words, like in the following example:

puts Hello

The first word, is the name of a Tcl procedure (more or less the same of a function in C), and the words following it are the arguments. In the example there is only the "Hello" argument.

The above command tells Tcl to call the puts procedure with the argument "Hello". Because the puts procedure is used to output the argument to the terminal, the effect of this command is to write "Hello".

If you want to try this command (and I strongly suggest you to do so with the examples in this book), run the tclsh, that is the Tcl shell, a program where you can type Tcl commands and see the result on the screen interactively, and type: "puts Hello" followed by the <Enter> key. Tcl will execute the command and will output "Hello" to the terminal:

% puts Hello Hello %

There is a set of standard procedures that are included in Tcl, like puts, but the user can define his own procedures. Unlike many other languages, there is no real difference from the programmer point of view between a procedure that comes with Tcl for default, and a user defined one as we will see better later. We will refer to procedures that are included in Tcl for default as Core Procedures. Actually Tcl users often call procedures commands, even if a command is actually the sum of the procedure name and the arguments. But because this is the used terminology we will also refer to Core Procedures as Core Commands, and in general will use command and procedure in an interchangable manner.

An important core command is set, that takes two arguments: the name of a variable, and a string. Set assigns the string to the variable, and returns the value assigned. Every Tcl command returns a value, but some commands where the return value is not important at all, return an empty string, like puts, because we are interested on the work that a call to puts does, and not on the value it returns.

This is an example of usage of the set command:

% set a apple apple %

Now, the variable named a, contains the string "apple". As you can see, the set command returned the string that was assigned to a, that's why the tclsh prints "apple" on the terminal. You may have noticed that entering this commands in the tclsh, with both puts and set the effect was to see the argument printed on the screen, but actually what happened in the two cases is a bit different.

In the first case, with puts, the printed value was the effect of the invocation of the command itself, because it's job is to print things on the screen, and to return an empty string (that's not printed by the tclsh because it's empty).

In the case of set instead, the printed value is the return value of the command, that's the string just assigned to the varialble a. Because tclsh uses to print return values of called commands, we saw "apple" calling set.

The set command can be also called with a single argument, the name of a variable. In such a case, instead to assign a new value to a variable it will return the value contained in it.

% set a apple

If we specify a variable that does not exists, the result is an error:

% set b can't read "b": no such variable while evaluating {set b}

In Tcl variables don't have a default value. If you try to use a variable never defined, the result is an error.

2.2 Grouping

May we write a program to print "Hello World!"? sure, but there is something more to learn, called grouping. For the puts command to work, the programmer needs to pass a string as a single argument. If we write:

puts Hello World!

actually the command is called with two arguments. The first being "Hello" and the second "World!", so the result is an error. To group strings containing spaces in a single argument, quotation marks are used:

% puts "Hello World!" Hello World!

This way the program works perfectly. There is another way to quote, as we will see in the next section talking about substitutions.

2.3 Program structure

There is some other information you should know about the basic structure of a Tcl program. First of all, that different commands in a program are separeted with newlines, so you can edit a text file, and write this program:

puts "Hello World" puts "Ciao Mondo"

Save it as hello.tcl, and execute it. If you are a unix user, you may call it from the unix shell as:

tclsh hello.tcl

and see the output. The other thing to know, is that commands can be also separated with a ";", in order to make it possible to write more commands in a single line. So the following program is perfectly equivalent to the previous:

puts "Hello World"; puts "Ciao Mondo"

In the next chapters we will write more complex programs that are uncomfortable to type directly in the tclsh, so you may like to type the code into a file, and run the program passing the file name as argument to tclsh.

2.4 Substitution of commands

You may need to use the puts command in order to print the value of a variable on the screen. In order to do this, we need a way to use the value of the variable as argument of the puts command. This is how to do it:

% puts [set a] apple %

What happened it's called command substitution. In short, Tcl commands can contain other commands nested inside the [ and ] brackets: Tcl will first compute the result of this commands, substitute this result in place of everything is between [ and ] (brackets included) and finally call the puts command. This is, step by step, how the Tcl interpreter will process the command.

Tcl try to process the command:

puts [set a]

It will substitute [set a] with the value it returns, to obtain:

puts apple

And finally will call the puts command *as if it was called directly with "apple" as argument*. Substituted commands may in turn contain more commands to substitute. Of course many arguments, or part of arguments in a command may be commands to substitute. See this example, directly typed into the tclsh as usually:

% set a apple apple % set b orange orange % puts "I want an [set a] and an [set b]" I want an apple and an orange

Both the commands are substituted, from left to right. As you can see command substitution works inside quotation marks, actually in the example there are two commands substitutions inside a single argument, and they are mixed with other strings. This is called interpolation.

2.5 Substitution of variables

You may think that command substitution is a bit verbose and hard to type if you just need to substitute a variable as in the previous example. This is why Tcl supports also substitution of variables as a special case. So instead to write [set a], you can just write $a like in the following example (assuming a and b vars are already set to a value):

% puts "I want an $a and an $b" I want an apple and an orange

As you can see Tcl interpolation abilties are not limited to variables, but to full commands. This, and other features we will explore later makes Tcl very convenient when working with strings, and today many things are strings: from xml, html, to many networking protocols, configuration files, and so on.

Now that commands and variables substitutions concepts should be clear, we may like to know how to not substitute. Do you remember that the quotation marks are used to group, but as it was anticipated, there is another form of grouping, using { and } in place of quotation marks. It works the same, but don't allow commands and variables substitutions:

% puts {I want $a and $b} I want $a and $b

"$a" and "$b" are now printed verbatim, without to be processed in any way.

2.6 More on interpolation

It's important to realize that the interpolation is done after the arguments are isolated, so for example to write:

set a "puts Hello" $a

will not work, Tcl will try to call a command with name "puts Hello". Instead the following will work:

set a "pu" set b "ts" $a$b Hello

The above script will print Hello on the screen, because Tcl will expand $a and $b, concatenated in the same argument, obtained "puts", but as you can see $a$b is already an unique argument before of the interpolation stage.


As in many different languages you can write comments inside Tcl code that are just skipped by the interpreter: they are useful for humans in order to better understand some part of a program that may not be simple to understand just looking at the code. In Tcl a comment starts with a # character, and ends when a newline character is encountered:

# This is a comment, the next line will print Hello puts "Hello"

Comments can start where a Tcl command is expected, so it's possible to comment a line of code in the same line it appears:

puts "Hello" ; # This is a comment, this line will print Hello

To do a judicious use of comments, try to avoid to comment trivial things, like:

set a 5; # Set 5 as value of a

What is self evident from the code does not need comments.

2.8 That's it

Belive it or not, you almost know Tcl already. Of course there are many other things to learn to become an experienced Tcl programmer, but the main ideas of Tcl where already exposed: the concept of command, grouping, and substitution of commands and variables.

The next step is to learn some more command in order to be able to write more interesting programs. Commands are central in Tcl, even conditionals like if are commands, and every argument of this commands are strings, that are interpreted by the commands as they like to interpret it.

Other Tcl/Tk books
2.1 Anatomy of a command
2.2 Grouping
2.3 Program structure
2.4 Substitution of commands
2.5 Substitution of variables
2.6 More on interpolation
2.8 That's it
3.1 User defined procedures
3.2 The if command
4.1 Tcl list
4.2 The foreach command
4.3 The lrange command
4.4 The lappend command
4.5 The lset command
4.6 The lsort command
4.7 List values against variable names
5.1 The append command
5.2 The string command
5.3 string range
5.4 string index
5.5 string equal
5.6 string compare
5.7 string match
5.8 string map
5.9 string is
5.10 More string subcommands
5.11 Advanced string matching
6.1 Converting strings to lists
6.2 From strings to list of chars
6.3 Converting lists to strings
6.4 Manipulating strings as lists
7.1 Local variables
7.2 Top level
7.3 Global variables
7.4 Procedures arguments and pass by value
7.5 Procedures with a variable number of arguments
7.6 Procedures with default arguments
7.7 Recursion
7.8 Recursion limit
8.1 The switch command
8.2 The for command
8.3 break and continue
8.4 The lack of goto
9.1 Programs executing programs: the eval command
9.2 Breaking the rules with uplevel
9.3 Passing variable names to procedures
9.4 Mapping scripts to lists
9.5 The rename command
9.6 Expanding lists into arguments in Tcl 8.5
Additional 20 chapters in the printed version.

Related man pages

Author Home
Tclers Wiki

Copyright 2004 Salvatore Sanfilippo. All rights reserved.
This online book is for personal use only.
It cannot be copied to other web sites or further distributed in any form.