The Interactive Prompt vs a .tcl File

Part I · Module 1 · Chapter 1.5 · The Interactive Prompt vs a .tcl File

1. Two Ways In

The interpreter you found in Chapter 1.4 accepts work in two forms.

Give it a file, and it runs the commands in that file from top to bottom and exits:

tclsh check.tcl

Give it nothing, and it starts a prompt and waits for you to type commands one at a time:

tclsh

%

That % is Tcl's interactive prompt. You are no longer talking to your operating-system shell — you are talking to Tcl, and everything you type is read as Tcl.

2. The Prompt Answers You

Start tclsh and type these lines one at a time. This is a real session:

% expr {40 * 15}
600
% puts "hello"
hello
% set greeting "good morning"
good morning
% set greeting
good morning
% string length "hello"
5
% exit

Look carefully, because something is happening that a script does not do.

The puts "hello" line printed hello — that is puts doing its job, and a script would do the same. But expr {40 * 15} printed 600, and nothing in that line asked for any output. string length "hello" printed 5, and it did not ask either.

The interactive prompt displays the result of every command you type. That is a courtesy of the prompt, not a behaviour of the commands.

This also explains the line that confuses people most. set greeting "good morning" printed good morning, which looks like it announced what it did. It did not: set returns the value it stored, and the prompt displayed that return value. The same line in a script prints nothing at all.

3. The Same Lines in a File

Put exactly those commands in a file, leaving out exit:

expr {40 * 15}
puts "hello"
set greeting "good morning"
string length "hello"

tclsh echo-demo.tcl

hello

One line of output, where the prompt gave five.

Nothing has gone wrong. expr computed 600 and returned it, and the script discarded it. set stored the value and returned it, and the script discarded that too. string length counted five characters and the result went nowhere. Only puts produced output, because producing output is what puts is for.

This is the first real difference, and it is the one that catches people out in the other direction: a script that "does nothing" very often computed everything correctly and simply never asked to be shown anything. In a script, if you want to see a value, you must puts it.

4. Errors Look Different, and Behave Differently

Now compare how the two contexts handle a mistake. At the prompt:

% putz oops
invalid command name "putz"
% puts $nope
can't read "nope": no such variable
% puts "still here"
still here
% exit

Two errors, each reported in a single line, and the session carried on. After both failures the prompt was still there and the next command ran.

The same two mistakes in a file:

putz oops
puts "do we reach this line?"

invalid command name "putz"
    while executing
"putz oops"
    (file "two-errors.tcl" line 1)

Three differences in one output:

1. The message is longer. A script error includes while executing, the command text, and the file and line number. The prompt gave you only the first line, because you were looking at the command you had just typed and did not need to be told where it was.
2. The script stopped. puts "do we reach this line?" never ran.
3. The exit status is 1 rather than 0 — which your shell can test, and which nothing at an interactive prompt can.

That file-and-line detail is the thing you will actually use when debugging, and Chapter 1.9 is about reading it properly.

5. The Difference That Can Mislead You

The two differences so far are conveniences. This one is a trap, and it is the reason this chapter is longer than it looks like it needs to be.

At the interactive prompt, try a command Tcl does not have — an ordinary operating-system one:

% ls
b.tcl       c.tcl       check.tcl   echo-demo.tcl
% exit

It listed the directory. But ls is not a Tcl command; Chapter 1.3 §6 gave you the tool to confirm that, and info commands ls returns empty.

What happened is that the interactive prompt, finding no Tcl command by that name, looked for an external program instead and ran it. It is a deliberate convenience: it makes the prompt usable as a working shell.

Now the same line in a script:

puts "before"
ls
puts "after"

before
invalid command name "ls"
    while executing
"ls"
    (file "autoexec.tcl" line 2)

The script refused. Same interpreter, same version, same line — and the opposite outcome.

6. Asking Which Context You Are In

A script can find out whether it is being run interactively. Tcl sets tcl_interactive to 1 at the prompt and 0 when running a file:

puts "interactive? $tcl_interactive"

tclsh which-context.tcl

interactive? 0

And at the prompt:

% puts "interactive? $tcl_interactive"
interactive? 1
% exit

This is genuinely useful later — a script that might be either run in a batch or sourced into a live session can use it to decide whether to print progress or ask a question. For now it is enough to know the two contexts are distinguishable, and that Tcl itself knows which one it is in.

7. The Comparison, Collected

8. Which to Use, and When

The division of labour is not a matter of taste.

Use the prompt to find something out. What does string length return for an empty string? Does this command take the options in the order I think? Does that return a list or a string? These are questions with one-line answers, and typing one line is faster than editing, saving, and running a file. The automatic result display in §2 is precisely what makes this efficient — you see the answer without writing anything to show it.

Put it in a file the moment it matters. A file can be re-run tomorrow, read by a colleague, committed to version control, diffed when it breaks, and run by something other than a human. A prompt session can do none of those: close the window and the work is gone, with nothing to show what you did or why.

The practical workflow is both, in that order — explore at the prompt, then write the file. Keep in mind §5 while you do it: the prompt is where you form a hypothesis, and the file is where you confirm it.

9. Failure Modes Worth Meeting Now

Typing shell commands at % and expecting shell behaviour. §5 covers why some of them appear to work. Pipes, redirections and shell variables will not behave the way your shell behaves, because Tcl is not your shell.

Trying to start a script from inside Tcl. At the % prompt, tclsh check.tcl is the external-program behaviour from §5 again — it starts a second Tcl interpreter as a child process. It is not how you run a script from a session. The Tcl command for that is source, which Module 15 covers.

Forgetting which prompt you are at. If your commands are suddenly not recognised, check whether you are looking at $ or %. This is common enough to be worth checking first rather than last.

Expecting a script to show its work. §3. A silent script has usually succeeded.

10. Exercises

Exercise 1 — reproduce the echo difference. Start tclsh, type the five lines from §2, and count the output lines. Then put the same four commands in echo-demo.tcl, run it, and count again. Explain the difference in one sentence without using the word "print".

Exercise 2 — make a script show its work. Edit echo-demo.tcl so that it produces all the values the prompt displayed. You will need puts and the square brackets from Chapter 1.1 §4. If you get 600 and 5 to appear, you have understood §3.

Exercise 3 — the two error shapes. Trigger putz oops at the prompt, then in a file. Write down which pieces of information the file version gave you that the prompt version did not, and say why the prompt does not need them.

Exercise 4 — prove §5 on your own machine. Run ls at the % prompt, then run it from a file. Confirm you get a directory listing and then invalid command name. This is the exercise to actually do rather than read, because it is the one that will save you an afternoon.

Exercise 5 — the error that does not stop. In a file, put a bad command on line 1 and a puts on line 2. Confirm line 2 does not run. Then do the same two lines at the prompt and confirm the second one does run. What does that tell you about using the prompt to check whether a sequence of commands works?

11. Summary

• Two contexts: tclsh with no arguments gives the interactive % prompt; tclsh file.tcl runs a file and exits. exit leaves the prompt.
• The prompt displays every command's result; a script discards results. In a script you must puts what you want to see, and a silent script has usually worked.
• set x "value" echoing at the prompt is the prompt showing a return value, not the command announcing itself.
• Script errors carry file and line, stop execution, and exit 1. Prompt errors are one line and the session continues.
• The prompt may run an external program when no Tcl command matches. A script will not. So a command working at the prompt is not proof it works in a script — confirm from a file before building on it.
• tcl_interactive is 1 at the prompt and 0 in a script, which is how a script can tell. It does not control the external-program behaviour.
• Explore at the prompt; keep it in a file. Only the file can be re-run, reviewed, diffed or automated.

You now know which of the two contexts the rest of this track uses, and why. The next chapter is the one everything so far has been preparing for: writing a file, running it, and fixing it when the run fails.