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's 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's meaningless for
a native Windows GUI application to run in "text" mode.
- Macintosh
interpreters generally ignore plain mode, because there's 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.
- -R
folder – set the root folder for individual
resources. When a resource (such
as a JPEG image or a sound file) is needed, and the resource can't be
found in the compiled game file or in any resource bundle file, the
interpreter will look for the resource as a separate file. By default, the interpreter looks for
these files in the directory containing the compiled game file, but if the
-R option is specified, then the interpreter will look in this folder
instead. (Note that this option
doesn't establish a "search path"; only one -R option can be in
effect. Also, this option only affects the individual resources; it
doesn't affect resource bundle (.3rN) files.)
- -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; the higher
the safety level, the more restrictions are imposed on the program's file
access. By default, the
interpreter uses level 2, which provides read/write access to the current
working directory only. If you
know the program comes from a trustworthy source, and for some reason it
needs more extensive disk access, you can manually set a lower (less
restrictive) level. If the source
of the program is dubious, you can set a higher level to reduce the
chances that the program can damage files on your system; setting the safety
level to 4 effectively prevents the program from performing any file
access at all. 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 on your system,
but it can only write to files contained in the same directory as the
image file itself.
- –s2
– The program will be allowed to read and write files only in the image
file directory. This is the
default setting, because it gives the program the flexibility to create
and read files of its own, but helps ensure the security of your overall
system by preventing the program from accessing any files outside of its
own directory.
- –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.