Show me an example

Show me an Example is a step-by-step guide to getting started with Tcl.

Hello, World!

There are two ways to experiment with Tcl. One can either take An Interactive Approach to Experimenting with Tcl, or one can write their Tcl scripts into text files and ask a Tcl interpreter to execute them, which is what this introduction describes.

The canonical first program (according to Brian Kernighan and Dennis Ritchie, creators of the C language) simply prints the message "hello, world". In Tcl, this program is:

#! /bin/env tclsh

puts {hello, world}

Using your favorite text editor, save the example above to a file named "hello.tcl".

The next step is to use the Tcl shell to interpret your program. Depending on your operating system, the particular version installation, etc. your Tcl shell could be named 'tclsh', 'tclsh8.3', or some other numbered variant.

If you are a Microsoft Windows user, running a scripts is a little more complicated. Windows distinguishes between "console" applications, which run in a terminal window environment, and "windows" applications, which have a GUI. The default Tcl/Tk installation on Windows runs all .tcl files in the wish shell, as a graphical application. Just put the file on the desktop or find it in the explorer and click on it. But since our simple script doesn't create any windows, and it isn't clear where the words "hello, world" would go, this program won't appear to do too much. You can run this program by starting tclsh from the start menu, then typing the command source c:/hello.tcl. Note that the traditional Windows \ is replaced with /.

RS: Another possibility on Windows: add the line

catch {console show}

to your script. This will open a console window which displays hello world, even if you just double-click the hello.tcl file.

For this example, we will assume the name of the interpreter is tclsh. From a command line, type

tclsh hello.tcl

, and you should see the message:

hello, world

The program you just ran was a complete Tcl script, comprised of one command, puts, and one word, hello world. Like English, Tcl normally separates words by looking for the whitespace between them, but the braces around hello, world tell Tcl that it is a single value, including the whitespace. Unlike English, in Tcl any single value is referred to as a word.

The first word of each command is the name of the command, and any additional words are the values that Tcl passes to the command when invoking it. These additional words are called arguments. puts accepts either one or two arguments, and in the script above, there was only one: hello world.

A Tcl script is nothing more than a sequence of Tcl commands. To interpret a script, Tcl reads the text of each command, looks up the command by the first word in the text, prepares the arguments to the command as described by any other words in the text, and invokes the command, passing it the prepared arguments.

A word can be assigned to a variable, which can then be used in place of the literal word:

set greeting hello
puts $greeting

set addressee world
puts "$greeting, $addressee"

The result is

hello
hello, world

$greeting and $addressee are both variables. The first word to set is the name of a variable, and the second word is the value to assign to that name. $ tells Tcl to retrieve the value out of some variable and substitute that value into the place of the variable. The double quotes, like the braces in the previous example, tell Tcl that $greeting, $addressee is a single word to be given to puts. Between double quotes, $ tells Tcl to do variable substitution, but between braces, $ is not special. It's just $.

Before it called set, Tcl substituted $greeting with hello and $addressee with world.

To substitute a variable, Tcl takes the sequence of alpha-numeric characters and underscores immediately following $. The comma after $greeting is not an alpha-numeric character or underscore, so Tcl knew where the end of the variable name was. Because $ is also not an alpha-numeric character, variables can be "smashed together". $hello$world would result in greetingworld.

Another way to specify the variable name is to put it in braces:

set -> world
puts $greeting,${->}

The result is

hello,world

It's a good idea to give variables understandable names, but as the example above illustrates, there's nothing stopping you from naming a variable something odd, like ->. There were no double quotes or braces around $greeting,${->} because it didn't have any spaces in it, so there was no need to do anything special to tell Tcl that it was a single value.

Hello, World: the GUI Version

One of the greatest things about Tcl is that you also get to use Tk. The "hello world" program for Tk is almost as simple. We just have to define a command button which will perform the printing action, then use one of the geometry managers to position it on the screen. The program looks like this:

#! /bin/env tclsh
package require Tk
button .b -text {Push Me} -command {tk_messageBox -message {hello, world}}
pack .b

And you run it using either tclsh or wish. (Windows users can just double click on the file.)

The first line of your program creates a pushbutton named .b with the label, Push Me. Instead of our favorite puts command, we create a Tk messageBox,which is a modal dialog, with our message. The second line instructs the pack geometry manager to display your pushbutton.

button returns the name of the button widget that it creates, .b in this case. This allows us to kill two birds with one stone:

#! /bin/env Tclsh
package require Tk
pack [button .b -text {Push Me} -command {
    tk_messageBox -message {hello, world}
}]

Hello, Windows!

If you're feeling really ambitious, with less than two dozen lines of Tcl/Tk code you can emulate the hello sample from the Microsoft Foundation Class, including comments and white space!

#! /bin/env tclsh
package require Tk
#  Create the main message window
message .m -text {Hello Tcl!} -background white
pack .m -expand true -fill both -ipadx 100 -ipady 40

#  Create the main menu bar with a Help-About entry
menu .menubar
menu .menubar.help -tearoff 0
.menubar add cascade -label Help -menu .menubar.help -underline 0
.menubar.help add command -label {About Hello ...} \
    -accelerator F1 -underline 0 -command showAbout

#  Define a procedure - an action for Help-About
proc showAbout {} {
    tk_messageBox -message "Tcl/Tk\nHello Windows\nVersion 1.0" \
        -title {About Hello}
}

#  Configure the main window 
wm title . {Hello Foundation Application}
. configure -menu .menubar -width 200 -height 150
bind . {<Key F1>} {showAbout}

This industrial strength GUI sample, including a popup dialog and a menu accelerator, is implemented in something like 250 lines of Win32 C++ code and resource files. The advantage to Tcl/Tk commands is, of course, that it also runs on UNIX (and maybe even on a Mac).

jcw: Yes, the Mac version works (but not F1, and the message box icon I see in the about box is weird - I'm using my own build of TclKit on Mac

rlb: Using Mac OS X and wish, F1 works in combination with fn key for me.

pps: This is obvously on a laptop(iBook). It works with F1 on my Mac G4 B&W. What Wish seems not to accept on MacOSX is a paste from a clipboard with CopyPaste installed (it just writes v after cmd-v). I have to type the commands (or quit CopyPaste).

Misc

escargo 2005-08-08: If you want a script that runs like a program on Windows you should look at DOS BAT magic or you want it to run on Linux or Unix you should look at exec magic.

RS: On Windows, installing ActiveTcl usually also associates the extension .tcl to running wish with it, so scripts can run by just double-clicking them. escargo: And using ActiveTcl is the suggested way....