Writing and Running Your First Script

Part I · Module 1 · Chapter 1.6 · Writing and Running Your First Script

1. The Loop You Are About to Enter

Four steps. You will repeat them for as long as you write Tcl.

2. Write the File

Open any text editor — VS Code, Vim, Emacs, Notepad, whatever you already use. Nothing here needs a particular one.

Type exactly this, and nothing else:

puts "starting"

Save it as check.tcl. The .tcl ending is a convention rather than a requirement — Tcl will run a file called anything — but every Tcl programmer uses it, your editor will colour the file correctly because of it, and the rest of this track assumes it.

3. Make Sure You Are Where the File Is

Most tutorials skip this. It is where most first attempts fail.

Your terminal is always "in" a directory. When you ask it to run check.tcl, it looks for that file in the directory it is currently in — not wherever your editor happened to save it.

Ask where you are:

pwd

/home/asaifi/work

List what is there, and check check.tcl is among them:

ls

check.tcl   notes.txt

If check.tcl is not listed, you are in the wrong directory. Move to the one you saved it in and look again:

cd work
ls

4. Run It

With check.tcl in the directory you are in:

tclsh check.tcl

starting

That is a working Tcl program. The interpreter read your file, carried out the single command in it, and the text appeared.

Two things worth noticing about what just happened, both of which you already know the reasons for:

• No build step. You saved and ran. Nothing was compiled, and there is no second file that could be out of date. That is Chapter 1.2 §3.
• Only puts produced output. Had you written expr {2 + 2} instead, the script would have computed 4 and shown you nothing. That is Chapter 1.5 §3, and it is why puts is the first command anyone learns.

5. Change One Thing

Now the part that turns a recipe into understanding.

Predict. You are going to change the text between the quotes. Before you do, decide what you expect to see.

puts "all checks passed"

Run. Save, and run the same command again:

tclsh check.tcl

Observe.

all checks passed

The text between the quotes is yours; Tcl displayed what you put there. Nothing else about the line changed, and you did not have to rebuild anything between saving and running.

6. Two Commands, In Order

Add a second line:

puts "starting"
puts "finished"

Predict which appears first. Then run it:

starting
finished

The first command ran to completion, then the second ran. Swap the lines in the file and the output order swaps with them. This is Chapter 1.1 §2 in action — one command per line, carried out in the order written.

7. When It Does Not Work

Three failures account for nearly every unsuccessful first run. None of them is a problem with your Tcl.

couldn't read file "check.tcl": no such file or directory

The interpreter started correctly and could not find your file. Either you are in the wrong directory — §3 — or the file is not named what you think. Some editors silently append .txt, giving you check.tcl.txt. Run ls and read the name that is actually there rather than the name you intended.

tclsh: command not found

The interpreter itself was not found, so nothing was even attempted. That is Chapter 1.4 §6 — go back, establish which command your machine has, then return.

An error mentioning a line number

Tcl found and started reading your file but could not make sense of part of it. For example, with a quote left off the end:

puts "starting"
puts "oops

starting
missing "
    while executing
"puts "oops
"
    (file "broken.tcl" line 2)

Note what that shows: starting printed first. Line 1 ran normally and the problem on line 2 only stopped things when Tcl got there — Chapter 1.2 §4 again. The (file ... line 2) is the useful part, and Chapter 1.9 is about reading these properly.

8. Did It Actually Succeed?

One more habit, and it is the one that distinguishes someone who has written a script from someone who can be relied on to have written a working one.

Chapter 1.2 proved something uncomfortable: a Tcl script can print exactly the output you expected and then fail. So "I saw output" is not a test of success.

The test is the exit status — a number every program hands back to whatever started it. Zero means success; anything else means failure. Your shell keeps the last one in ?:

tclsh check.tcl
echo $?

starting
0

Now the broken file from §7:

tclsh broken.tcl
echo $?

starting
missing "
    while executing
"puts "oops
"
    (file "broken.tcl" line 2)
1

0 and 1. Both runs printed starting; only one of them succeeded.

9. Naming Files

Two rules now, so you do not form a habit you later have to break.

• End the name in .tcl. Universal convention; editors and colleagues both assume it.
• Keep names short, lowercase, and descriptive, with underscores rather than spaces — check.tcl, parse_report.tcl. A space in a filename has to be quoted on every command line that mentions it, which is a small tax paid forever.

A third rule applies later and is worth knowing exists: once you start writing reusable Tcl files that other files load, naming one after something Tcl already provides can cause the wrong file to be found. It cannot affect you today, and Module 15 covers it when it becomes relevant.

10. Exercises

Exercise 1 — three lines, predicted first. Edit check.tcl to display three different messages. Before running it, write down the exact three lines you expect. Run it and compare. Anything surprising?

Exercise 2 — cause the directory error deliberately. Move somewhere else and run it:

cd ..
tclsh check.tcl

Read the error. Which word in it tells you this is a file problem rather than a Tcl problem? Then go back and confirm it works again. Deliberately causing this once means recognising it instantly later.

Exercise 3 — reorder. Swap your first and last lines. Predict the output before running. Worth doing even though you are confident, because it is the last cheap chance to confirm that order means exactly what it appears to.

Exercise 4 — break it on purpose, then read the number. Delete the closing quote from one line. Run it. Note the line number Tcl reports, then run echo $? and confirm you get 1. Put the quote back and confirm you get 0 again. You have now seen both halves of §8 on your own machine.

Exercise 5 — the silent script. Make check.tcl contain only expr {2 + 2}. Predict the output, then run it. Explain the result using Chapter 1.5 §3, and then make the 4 appear.

11. Summary

• The loop is write → save → run → read. Everything in Part I is a variation on it.
• A .tcl file is an ordinary text file. The extension is convention, not a requirement, and everyone follows it.
• tclsh check.tcl is a terminal command, not a line that goes inside the file.
• Your terminal has a current directory and looks for the file there. pwd says where you are, ls says what is there, cd moves you. Most first-run failures are this.
• Commands run in the order written, one per line.
• Only commands that produce output produce output. A silent script has usually worked.
• Three first-run failures: wrong directory or wrong filename, interpreter not found, or a syntax problem reported with a line number.
• Exit status is the real success test — 0 succeeded, anything else failed, and echo $? reads it. Output alone proves nothing.
• Change one thing, predict, run, observe. That is how the rest of this track is meant to be read.

You have written and run a Tcl program. The next chapter returns to the one command you have been using on trust since the first page and takes apart exactly what it does with the words you give it.