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. This option reads the script in "quiet" mode, meaning that no output is displayed on the console while the script is running. See Script Files for information on how input scripts are interpreted.
- -I file - read command-line input from file. This is similar to the -i option, but -I reads the script in "echo" mode, meaning that output is displayed to the console while the script is being read, just as though the user were actually sitting at the keyboard typing the input.
- -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.
- -norand - do not "seed" the random number generator. By default, at startup, the interpreter automatically scrambles the starting point of the built-in rand() function using some truly random data obtained from the operating system. This ensures that rand() generates different random number sequences on each run. However, it's sometimes desirable for the "random" sequence to be predictable, such as when you're testing a program. If you use the -norand option, the system will use a fixed starting point for the rand() sequence. This means that rand() will return the same sequence of numbers every time you run the program, which is good for situations like testing because it makes the results repeatable on every run. Note that -norand doesn't make the rand() results appear any less random - rather, it makes the sequence repeatable, so that you get the same apparently random sequence of numbers on each run.
- -nslevel or
-nsCS - set the network safety levels for Client
and Server network features.
This lets you limit the ability of the game program to access network
functions. You can specify the Client and Server levels
separately, or, if you supply just one digit, the same
level applies to both client and server. Each level is given as a
digit from 0 to 2; higher digits mean higher safety, or more
restrictions on the program.
- The client setting controls the program's ability to
access network services as a client. This controls outgoing
connections, from the program to other services or other computers on
the network. For example, the program might want to download
information from a Web server via HTTP.
- 0 - Minimum safety. The program will be allowed to access any site on the network as a client.
- 1 - Local access only. The program will only be allowed to access network services on the same machine that the program is running on. No access will be allowed to other machines.
- 2 - No network access. The program will not be allowed to access network services as a client at all.
- The server setting controls the program's ability to
create network services that accept network connections from other
processes or other machines. This controls incoming
connections, where the program provides a network service that other
applications can access. For example, the program could create an
HTTP server that allows other machines to access Web pages served by
the program.
- 0 - Minimum safety. The program will be allowed to create network services that accept connections from any machine on the network.
- 1 - Local access only. The program will only be allowed to create servers that are accessible from other applications running on the same machine that the program is running on. For example, you could open a Web browser in another window to access the program's Web server, but you won't be able to access it from another machine on the network.
- 2 - No network access. The program will not be allowed to create network services or accept network connections at all.
For example, to allow the program to make outgoing connections to any other machine, but prohibit it from setting up any servers of its own, you'd specify -ns02 (minimum client safety, no server access). To allow local access for both client and server functions, use -ns1.
- The client setting controls the program's ability to
access network services as a client. This controls outgoing
connections, from the program to other services or other computers on
the network. For example, the program might want to download
information from a Web server via HTTP.
- -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.)
- -slevel or -sRW -
set the input/output safety level. The level is a digit from 0
to 4, or you can specify two digits, R for read access
and W for write access. If you provide only one digit, the
same level is used for both read and write access. This setting lets
you limit the access that the image file program has to your
computer's disk and file system. The higher the safety level, the
more restrictions are imposed on the program's file access. By
default, the interpreter uses level 2 for both read and write, 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
prohibits the program from performing any file access at all. The
possible level settings are:
- 0 - Minimum safety. The program is allowed to read and write files anywhere on your system.
- 1 - The program is 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, or in its subdirectories.
- 2 - The program is allowed to read and write files only in the image file directory (or its subdirectories). 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.
- 3 - The program is allowed to read files only from the same directory that contains the image file (or its subdirectories), and it won't be allowed to write files at all.
- 4 - The program is denied all access to the file system: it's not allowed to read or write files anywhere on your disk.