Running Programs: The TADS 3 Interpreter
The TADS 3 Interpreter is the application that executes a
TADS 3 program.
The name of the interpreter varies by platform, and some
platforms might have more than one interpreter. On Windows systems, for example, there are two versions: t3run, a
plain-text version that runs in an MS-DOS console window; and htmlt3, a
graphical version that includes support for full HTML display, including
pictures and sounds. In the examples
below, we'll show the name of the DOS interpreter; you should substitute the
appropriate name for your platform.
Interpreter Command Syntax
For systems with a graphical user interface, you will
usually start the TADS 3 interpreter by selecting an image file program in your
system's desktop or other graphical interface.
The exact method varies by system, so you should check your
system-specific release notes for details.
For command-line systems, the interpreter accepts this
command syntax:
t3run options imageName imageParams
The options, if present, let
you modify the interpreter's default behavior.
You don't have to specify any options, and options you do specify can be
listed in any order, as long as they all preceded the name of the image file
you want to run.
The imageName is the name of
the program you want to run.
The imageParams are additional
parameters that you wish to send to the image file program itself. The interpreter doesn't do anything with
these parameters except pass them to the image file. The image file program interprets these parameters, so what you
specify here depends entirely on the program you're running.
The interpreter options are:
- -banner
– show the interpreter's name and version banner. By default, the interpreter doesn't
show its own banner unless there is an error in the command-line syntax,
so that the image file program has more complete control over what appears
on the display. You can use this
option if you want to check the interpreter version (which might be useful
information if you're reporting a bug, for example, or if you're
encountering a problem running a program and suspect that the problem is
due to a version incompatibility).
- -cs
xxx – use xxx as the keyboard and display
character set. By default, the
interpreter will attempt to determine the correct character set
automatically, so in most cases you will not need to specify this
option. However, in some cases, it
might not be possible for the operating system to determine the correct
character set; for example, if you're connected via a remote terminal, the
operating system might not be able to read the terminal's configuration,
in which case the OS would not know what character set the terminal is
using. You can use this option in
such cases to specify the correct character set. Note that this option only selects the "mapping"
that the interpreter uses to convert text between your terminal's
character set and the interpreter's internal Unicode characters; this
option does not change your terminal's character set. If you want to change your terminal's
character set, you must use whatever method that your operating system or
terminal provides for making this change.
Refer to the section on character sets for
more details.
- -i
file – read command-line input from file, rather
than reading from the keyboard. If
you specify this option, the interpreter will read commands from the given
file whenever the inputLine() method (in the "tads-io"
function set) is invoked.
- -l
file – log all console input and output to file. Text will also be shown on the
display. The –i and –l options are
useful for creating test scripts, because you can read a set of
pre-written commands from an input file with –i, and capture the resulting
output to another file with –l.
You can later compare the logging file with a reference copy to
check for changes.
- -o
file – log all console input (but not output) to file. This option lets you easily prepare a
command file for later use with –i.
- -plain
– run in "plain" mode, which displays text without any cursor
positioning, highlighting, terminal control sequences, or other non-text
operations. The exact behavior of
plain mode varies by platform, and some interpreters ignore this mode
entirely. Here are some examples:
- The
DOS interpreter normally uses BIOS calls to display characters, position
the cursor, and change text colors.
In plain mode, it uses standard DOS output instead, and does not
attempt to position the cursor or change colors.
- The
Unix interpreter normally uses terminal escape sequences and control
characters to position the cursor and control output. In plain mode, the Unix interpreter
does not generate any control characters or escape sequences.
- The
Windows HTML interpreter ignores plain mode, because it is meaningless
for a native Windows GUI application to run in "text" mode.
- Macintosh
interpreters generally ignore plain mode, because there is no such thing
as "text" mode on the Macintosh.
Note that plain mode
has nothing to do with character sets – plain mode is not "ASCII"
mode or "7-bit" mode, and doesn't affect how accented characters are
displayed. The main purpose of plain mode
is to allow users to route the text that the interpreter displays through a
separate processing program; for example, sight-impaired uses might wish to
send the interpreter's output through a text-to-speech device. Plain mode makes it easier to use this kind
of additional processing by eliminating extraneous control sequences that could
confuse the processing program.
- -r
file – restore the saved state from file
and resume execution. If this
is specified, the image file's main entrypoint will never be called;
instead, the program will begin execution as though it had just returned
from the call to the save() function that created the saved state
file. If this option is specified,
the image file need not be specified, because the interpreter can
automatically determine the image file to load from the saved state file
(each saved state file records the name of the image file that created it). However, if the image file name is
specified, the image filename information stored in the saved state file
is ignored and the specified image file is used instead.
- -s
level – set the input/output safety level to level,
which must be a digit from 0 to 4.
The safety level lets you limit the amount of access that the image
file program will have to the file system on your hard disk. By default, the interpreter uses level
0, which imposes no restrictions on the image file program; while level 0
gives the program maximum flexibility, you might not always feel
comfortable allowing programs of questionable origin to have this much
access to your hard disk. The
possible level settings are:
- –s0
– Minimum safety. The program
will be allowed to read and write files anywhere on your system.
- –s1
– The program will be allowed to read files from anywhere in your system,
but it can only write to files contained in the same directory as the
image file itself. This setting
lets you limit the locations where the program can write files, but still
allows the program some degree of access to the file system.
- –s2
– The program will be allowed to read files from anywhere in your system,
but it cannot write files at all.
- –s3
– The program will be allowed to read files only from the same directory
that contains the image file, and it won't be allowed to write files at
all.
- –s4
– The program will not be allowed any access to the file system:
it will not be allowed to read or write files anywhere on your disk.