part of Tcl for Web Nerds by Hal Abelson, Philip Greenspun, and Lydia Sandon; updated July 2011
If you're an MIT student reading this tutorial, you have a special advantage in learning Tcl, because you've read Structure and Interpretation of Computer Programs (Abelson and Sussman 1996; MIT Press). We're not going to try to redeliver the knowledge in SICP packaged up in Tcl syntax. However, we are going to try to show how some of the big ideas from SICP can be accomplished even in the comparatively impoverished Tcl language.

One of the strengths of Lisp, the programming language used to illustrate the principles in SICP, is that it has very simple syntax:

(procedure-name arg1 arg2 arg3)
(set! ten-factorial (factorial 10))
(set! checking-account-balance (+ 25 34 86))
(print "If you're so smart, why aren't you rich like Bill Gates?")
will set ten-factorial to the result of evaluating the factorial procedure with an argument of 10, then compute a graduate student's checking account balance, then print out some career advice to a computer science graduate student.

These examples are written in the Scheme dialect of Lisp, which is described in

How would you accomplish the same goals in Tcl? Tcl syntax is

procedure_name arg1 arg2 arg3
procedure_name arg1 [subprocedure subarg1 subarg2]
This is like Lisp, except that procedures invoked at top level need not be surrounded by delimeters. Procedures invoked from within other procedure calls must be surrounded by [] instead of ():
set ten_factorial [factorial 10]
set checking_account_balance [expr 25 + 34 + 86]
puts "If you're so smart, why aren't you rich like Bill Gates?"
Tcl variables can't include dashes; you have to use underscore instead. Note that doing arithmetic with Tcl requires escaping into a world of infix syntax with the expr procedure.

Evaluation and quoting

Each line of Tcl is interpreted as a separate command:
procedure_name arg1 arg2 arg3
Arguments are evaluated in sequence. The resulting values are then passed to procedure_name, which is assumed to be a system- or user-defined procedure. Tcl assumes that you're mostly dealing with strings and therefore stands some of the conventions of standard programming languages on their heads. For example, you might think that set foo bar would result in Tcl complaining about an undefined variable (bar). But actually what happens is that Tcl sets the variable foo to the character string "bar":
> tclsh
% set foo bar
% set foo 

The first command line illustrates that the set command returns the new value that was set (in this case, the character string "bar"), which is the result printed by the interpreter. The second command line uses the set command again, but this time with only one argument. This actually gets the value of the variable foo. Notice that you don't have to declare variables before using them.

By analogy with Scheme, you'd think that we could just type the command line $foo and have Tcl return and print the value. This won't work in Tcl, however, which assumes that every command line invokes a procedure. This is why we need to explicity use set or puts.

Does this mean that you never need to use string quotes when you've got string literals in your program? No. In Tcl, the double quote is a grouping mechanism. If your string literal contains any spaces, which would otherwise be interpreted as argument separators, you need to group the tokens with double quotes:

% set the_truth Lisp is the world's best computer language
wrong # args: should be "set varName ?newValue?"
% set the_truth "Lisp is the world's best computer language"
Lisp is the world's best computer language
In the first command above, the Tcl interpreter saw that we were attempting to call set with seven arguments. In the second command, we grouped all the words in our string literal with the double quotes and therefore the Tcl interpreter saw only two arguments to set. Note a stylistic point here: multi-word variable names are all-lowercase with underscores separating the words. This makes our Tcl code very compatible with relational database management systems where underscore is a legal character in a column name.

In this example, we invoked the Unix command "tclsh" to start the Tcl interpreter from the Unix shell. Later on we'll see how to use Tcl in other ways:

For now, let's stick with typing interactively at the shell. You can keep evaluating Tcl commands at the % prompt until you exit the Tcl shell by evaluating exit.

To indicate a literal string that contains a space, you can wrap the string in double quotes. Quoting like this does not prevent the interpreter from evaluating procedure calls and variables inside the strings:

% set checking_account_balance [expr 25 + 34 + 86]
% puts "your bank balance is $checking_account_balance dollars"
your bank balance is 145 dollars
% puts "ten times your balance is [expr 10 * $checking_account_balance] dollars"
ten times your balance is 1450 dollars
The interpreter looks for dollar signs and square brackets within quoted strings. This is known as variable interpolation What if you need to include a dollar sign or a square bracket? One approach is to escape with backslash:
% puts "your bank balance is \$$checking_account_balance"
your bank balance is $145
% puts "your bank balance is \$$checking_account_balance \[pretty sad\]"
your bank balance is $145 [pretty sad]

If we don't need Tcl to evaluate variables and procedure calls inside a string, we can use braces for grouping rather than double quotes:

% puts {your bank balance is $checking_account_balance dollars}
your bank balance is $checking_account_balance dollars
% puts {ten times your balance is [expr 10 * $checking_account_balance] dollars}
ten times your balance is [expr 10 * $checking_account_balance] dollars
Throughout the rest of this book you'll see hundreds of examples of braces being used as a grouping character for Tcl code. For example, when defining a procedure or using control structure commands, conditional code is grouped using braces.

Keep it all on one line!

The good news is that Tcl does not suffer from cancer of the semicolon. The bad news is that any Tcl procedure call or command must be on one line from the interpreter's point of view. Suppose that you want to split up
% set a_very_long_variable_name "a very long value of some sort..."
If you want to have newlines within the double quotes, that's just fine:
% set a_very_long_variable_name "a very long value of some sort... 
with a few embedded newlines
makes for rather bad poetry"
a very long value of some sort... 
with a few embedded newlines
makes for rather bad poetry
It also works to do it with braces
% set a_very_long_variable_name {a very long value of some sort... 
with a few embedded newlines
makes for rather bad poetry}
a very long value of some sort... 
with a few embedded newlines
makes for rather bad poetry
but if you were to try
set a_very_long_variable_name 
    "a very long value of some sort... 
     with a few embedded newlines
     makes for rather bad poetry"
Tcl would interpret this as two separate commands, the first a call to set to find the existing value of a_very_long_variable_name and the second a call to the procedure named "a very long value...":
can't read "a_very_long_variable_name": no such variable
invalid command name "a very long value of some sort... 
     with a few embedded newlines
     makes for rather bad poetry"
If you want to continue a Tcl command on a second line, it is possible to use the backslash to escape the newline that would otherwise terminate the command:
% set a_very_long_variable_name \
      "a very long value of some sort... 
       with a few embedded newlines
       makes for rather bad poetry"
a very long value of some sort... 
       with a few embedded newlines
       makes for rather bad poetry
Note that this looks good as code but the end-result is probably not what you'd want. The second and third lines of our poem contain seven spaces at the beginning of each line. You probably want to do something like this:
% set a_very_long_variable_name "a very long value of some sort... 
with a few embedded newlines
makes for rather bad poetry"
For completeness we note that semicolon will allow you to put multiple Tcl commands on one line:
% set x 2; set y 3; set z [expr $x+$y]
We never use this facility of the language.

Case Sensitivity, Poisonous Unix Heritage, and Naming Conventions

The great case-sensitivity winter descended upon humankind in 1970 with the Unix operating system.
% set MyAge 36
% set YearsToExpectedDeath [expr 80-$Myage]
can't read "Myage": no such variable
Variables and procedure names in Tcl are case-sensitive. We consider it very bad programming style to depend on this, though. For example, you shouldn't simultaneously use the variables Username and username and rely on the computer to keep them separate; the computer will succeed but humans maintaining the program in the future will fail. So use lowercase all the time with underscores to separate words!


One of the keys to making a large software system reliable and maintainable is procedural abstraction. The idea is to take a complex operation and encapsulate it into a function that other programmers can call without worrying about how it works.

Here's the factorial procedure in Tcl:

% #this is good old recursive factorial
% proc factorial {number} {
    if { $number == 0 } {
	return 1
    } else {                 
	return [expr $number * [factorial [expr $number - 1]]]
% factorial 10
At first glance, you might think that you've had to learn some new syntax here. In fact, the Tcl procedure-creation procedure is called like any other. The three arguments to proc are procedure_name arglist body. The creation command is able to extend over several lines not because the interpreter recognizes something special about proc but because we've used braces to group blocks of code. Similarly the if statement within the procedure uses braces to group its arguments so that they are all on one line as far as the interpreter is concerned.

As the example illustrates, we can use the standard base-case-plus-recursion programming style in Tcl. Our factorial procedure checks to see if the number is 0 (the base case). If so, it returns 1. Otherwise, it computes factorial of the number minus 1 and returns the result multiplied by the number. The # character signals a comment.

We'll have more to say about procedures later on. For now, examine the following example:

% set checking_account_balance [expr 25 + 34 + 86]
% puts "\nYour checking balance is \$$checking_account_balance.
If you're so smart, why aren't you rich like Bill Gates?
He probably has \$[factorial $checking_account_balance] by now."

Your checking balance is $145.
If you're so smart, why aren't you rich like Bill Gates?
He probably has $0 by now.
There are a few things to observe here: One of the reasons that commercial programmers work so hard and accomplish so little is that they use languages that can't even do arithmetic! Tcl's feeble brain is overwhelmed by the idea of an integer larger than one machine word (32 bits in this case). You'll have to go back to Scheme if you want to find Bill G's predicted worth:
(define (factorial number)
  (if (= number 0)
      (* number (factorial (- number 1)))))
;Value: factorial

(factorial 145)
;Value: 804792605747199194484902925779806277109997439007500616344745281047115412373646521410850481879839649227439298230298915019813108221651663659572441609408556917739149315905992811411866635786075524601835815642793302504243200000000000000000000000000000000000

Some powerful things about Tcl

A language that isn't powerful by itself can become powerful if a procedure can invoke the interpreter, i.e., if a program can write a program and then ask to have it evaluated. In Lisp, you do this by calling eval. In Tcl, you do this ... by calling eval! We'll see examples of this later.

Tcl also supports reflection: You can write a Tcl program that pokes around the run-time environment. One basic mechanism is

info exists foobar
which tests whether the variable foobar is defined. The info command can also tell a running program what local variables are defined (info local), what procedures are defined (info procs), what arguments a procedure takes (info args procedure_name), and what the source code for a procedure is (info body procedure_name).

One useful aspect of reflection extends the behavior of set described above: a Tcl procedure can examine the calling stack and set variables in its caller's environment. For example, in the ArsDigita Community System toolkit, there's a procedure called set_variables_after_query that looks at the last SQL query executed and sets local variables to the values retrieved from the database:

set selection [ns_db 1row $db "select first_names,
from users
where user_id = 37"]


ns_write "The above comment was made by $first_names $last_name.\n"
Note that this example uses procedures defined by AOLserver, e.g., ns_db to talk to the database and ns_write to send bytes back to the Web client. The prefixing of procedure names by a package name is a good convention that you should follow in your own programming. In this case, the "ns_" prefix alerts fellow programmers to the fact that you are calling API calls for the "NaviServer". NaviServer? That's what AOLserver was called before being purchased by America Online. The fact that the API prefixes were not changed illustrates another good programming practice: don't change things gratuitiously.

Tcl for Web Use

In most cases, rather than typing Tcl expressions at the interpreter you'll be using Tcl to generate dynamic Web pages. AOLserver provides two mechanisms for doing this:
  1. .tcl pages are Tcl programs that are executed by the webserver (in this case AOLServer). They typically generate character strings that are sent to the client browser with ns_write.
  2. .adp pages are like ordinary HTML pages, but they contain escapes to Tcl commands that are evaluated by the server.

Which option you choose depends largely on whether static HTML or Tcl constitutes the majority of the page you are creating. If you're printing fixed character strings with Tcl, you'll need to "quote" any embedded quotes by preceding them with backslash. E.g., to print to a Web page the string <a href="goodies.html"> you would use the Tcl command

ns_write "<a href=\"goodies.html\">"
So if the majority of your Tcl expressions are simply printing strings, you'll find it more convenient to avoid the hassles of quoting by using .adp pages rather than complete .tcl programs.

Why the use of ns_write instead of puts? The puts command writes to a program's standard output stream. If you were writing a Tcl CGI script, standard output would be linked through the Web server to the Web client and you could indeed use puts. This idea doesn't make sense with AOLserver, where all the Tcl scripts are running inside the Web server process. If the Web server is serving 100 clients simultaneously, to which client should bytes written with puts be sent?

Anyway, if you want to have some fun one night, try redefining puts to forward its argument to ns_write and see what happens.

Lisp Without a Brain

If in reading this introduction, you've come to realize that "Hey, Tcl is just like Lisp, but without a brain, and with syntax on steroids", you might wonder why Lisp isn't a more popular scripting language than Tcl. Lisp hasn't been a complete failure, by the way; it is used as an extension language by users of some popular programs, notably AutoCAD. But Tcl has been much more successful. It has been compiled into hundreds of larger programs, including AOLserver, which is why we wrote this book.

As a software developer, you're unlikely to get rich. So you might as well try to get through your life in such a way that you make a difference to the world. Tcl illustrates one way:

In the case of AOLserver, for example, Jim Davidson and Doug McKee had only a few months to build the whole server from scratch. They wanted users to be able to write small programs that ran inside the server process. They therefore needed a safe interpreted language so that a programming error by one user didn't crash the server and bring down all the Web services for an organization.

Tcl was available. Tcl was easy to download and designed to fit inside larger application programs. But the Tcl interpreter as distributed had one terrible bug: it wasn't thread safe, i.e., you couldn't have two copies of the Tcl interpreter running inside the same program at the same time. Doug and Jim had to read through the Tcl source code and modify it to be thread safe. So it was critically important for them that Tcl was open-source and simple enough so as to not require months or years of study to understand the whole system.

Compare this to Lisp. Some of the best and brightest computer scientists raised money to build commercial Lisp implementations that they then went out and hawked in an indifferent and confused marketplace. They succeeded only in breaking their hearts and their investors' wallets. A handful of academics produced free open-source implementations, notably CMU Common Lisp (see and various versions of Scheme (see the links from; Scheme 48 is the closest to Tcl in spirit). But these multi-megabyte monsters weren't designed to fit neatly into someone else's program. Nor was there any document explaining how to do it.

Lisp developers have the satisfaction of knowing that they got it right 30 years before anyone else. But that's about all they have to show for 40 years of hard work and hundreds of millions of dollars in government and private funding. These days, most former Lisp programmers are stuck using Unix and Microsoft programming environments and, not only do they have to put up with these inferior environments, but they're saddled with the mournful knowledge that these environments are inferior.

Continue on to string operations.

Return to Table of Contents