Running Programs: The 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.
- -csl xxx - use xxx as the log file character set. By default, the interpreter uses a suitable default that depends on local conventions. This option lets you override the default to choose a specific character set for log file output.
- -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.
- -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. The given
level must be a digit from 0 to 4. This setting 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.