The "tads-io" function set provides access to the user interface provided by the TADS 3 Interpreter host applications, as well as file input/output functions. The "tads-io" function set is available only in T3 implementations that are hosted within a TADS 3 Interpreter environment, so a program that uses this function set will only run in a TADS Interpreter.
The "tads-io" function set is separate from the "tads-gen" function set to allow programmers to choose an alternative input/output and user interface function set, if desired, while still using the more general "tads-gen" functions. Most programs will probably want to use the "tads-gen" set because of the many data conversion and manipulation functions it contains, even if they're using an alternative user interface.
To use the "tads-io" function set in a program, #include "tadsio.h", or simply #include "tads.h" (which includes both "tadsio.h" and "tadsgen.h" for the full set of TADS intrinsics).
clearScreen() – clear the main console window, if possible. The actual effect of this function varies by system; some interpreters clear the window, some display enough newlines to scroll any existing text off the top of the window, and some ignore the call completely.
fileClose(filenum) – close the given file. The filenum is a file number returned by a previous call to fileOpen(). The program should close a file as soon as it's done operating on the file, since each open file consumes some system resources. In addition, if the program is writing to a file, it is necessary to close the file to ensure that the on-disk information for the file is properly updated.
fileGetPos(filenum) – returns the current seek position for the given file, as an integer value.
fileOpen(fname, mode, charmap?) – open the file with name fname in the given mode. The following modes are allowed:
If the file doesn't exist, and the mode doesn't allow creating a new file, the function returns nil. Otherwise, the function returns a number that can be used in subsequent file operations to manipulate the open file.
If charmap is specified, it indicates the name of the character map to use to translate characters in the file into Unicode (if reading the file) or to translate Unicode characters into characters in the file (if writing the file). Characters read from or written to the file must be converted between the character set used by the operating system to store external files and the Unicode character set that T3 uses internally. If charmap is not specified, a plain ASCII mapping is used by default. Mapping names are platform-specific, because different types of computers use different character sets. The following special charmap values can be used:
fileRead(filenum) – read a value from the given file. Returns the value read. If the file is open in text mode, this reads one line of text from the file and returns a string containing the line of text. If the file is open in binary mode, this reads one value, as previously written by fileWrite(), and returns the value.
Note that binary files use a special file format that TADS 3 defines. Arbitrary binary files created by other software cannot be read using fileRead(), because they almost certainly do not use the format that TADS 3 defines. If you want to exchange data with other software, you should use text files, since fileRead() and fileWrite() in text mode use a simple textual format that most other software will be able to recognize.
fileSeek (filenum, pos) – seeks to the given position (an integer value) in the given file. The seek position is a byte offset within the file. For text files, it is usually only safe to seek to a position previous obtained from fileGetPos(), because certain locations in the file might not be valid seek positions due to character translations and newline conventions.
fileSeekEnd(filenum) – seek to the end of the given file.
fileWrite(filenum, val) – write the given value to the file. If the file is open in text mode, the value must be a string or be convertible to a string (using the same rules as toString()). In binary mode, the value can be an integer, a string, an enumerator, or true (nil is not allowed, because the fileRead() interface would have no way to return it).
Writing an enumerator value to a binary file ties the file to the particular version of your program that wrote the file. When you compile your program, the compiler assigns an arbitrary internal identifier value to each enumerator, and it is this arbitrary internal value that the fileWrite() function stores in the file. When you use fileRead() to read an enumerator value, the system uses the current internal enumerator value assignments made by the compiler. Because these values are arbitrary, they can vary from one compilation to the next, so it is not guaranteed that a file containing enumerators can be correctly read after you have recompiled your program. For this reason, you should never write enumerators to a file unless you are certain that the file will only be used by the identical version of your program (so it's safe, for example, to use enumerators in a temporary file that will be read back in during the same run of the program). If you must store enumerators in a file that might be read by a future version of your program, you should use a switch statement or other mechanism to translate enumerator values into integers, strings, or other values that you define and can therefore keep stable as you modify your program.
inputDialog(icon, prompt, buttons, defaultButton, cancelButton) – display a dialog and wait for the user to respond. This works the same as TADS 2's inputdialog() function, but note that the constants have been changed to names of the form INDLG_xxx.
inputEvent(timeout?) – wait for an event, with the optional timeout, in milliseconds. Uses the same result code as TADS 2's inputevent() function, but note that the constants have been changed to names of the form INEVT_xxx.
inputFile(prompt, dialogType, fileType, flags) – display a file selector dialog and wait for the user to respond. This works the same as TADS 2's askfile() function, except that the flags argument is now mandatory, the ASKFILE_EXT_RESULT flag is no longer used, and the list-style extended return value is always used (this is why ASKFILE_EXT_RESULT was deleted: the extended results format is now the only option). Note also that the constants have been changed to names of the form INFILE_xxx.
There are no flags currently defined, so flags should always be set to zero for compatibility with any flags added in the future.
The return value is a list. The first element is always the integer result code. If a filename was successfully obtained, the second element is the filename string.
inputKey() – read a keystroke from the user. Waits for the user to press a key, then returns a string with the key the user pressed. This function uses the same result codes as the TADS 2 inputkey() function.
inputLine() – read a line of input from the user. Returns the text of the input as a string. (The returned string will not contain a newline character.) Returns nil if the console is at end-of-file, which usually indicates that the user has closed the interpreter application.
morePrompt() – display the MORE prompt on the main console window, and wait for the user to respond. This can be used when you want to pause execution and wait for the user to acknowledge some output before proceeding.
resExists(resname) – check to see if the given resource can be found. Returns true if the resource is present, nil if not. For HTML TADS 3, this looks for an HTML resource; text-only TADS 3 interpreters always return nil for this function, since they don't use multi-media resources at all. The resource name should be specified as a URL-style name. The interpreter will look for the resource using the same searching rules that it uses for normal resource loading; the HTML interpreter will thus look for the resource bundled into the image file, in any external resource files (image.3r0 through image.3r9), and finally in an external file whose name is derived from the URL according to local system conventions.
tadsSay(val, ...) – display one or more values. Each value is displayed on the console, starting with the first argument; the displayed values are not separated by any spaces or other delimiters. Each value can be a string, an integer (in which case its decimal representation is displayed), or nil, in which case nothing is displayed. The function throws a run-time error (BAD_TYPE_BIF) for any other type. No return value.
setLogFile(fname) – turn on logging of the console output to a file whose name is given by fname. If fname is nil, this turns off any logging currently in effect. All of the text displayed to the main console (including text read via command line input) is copied to the file. If the console is in HTML mode, HTML sequences are parsed and rendered to plain text, so raw HTML sequences will not appear in the log file.
setScriptFile(filename, flags?) – start reading commands from the script file, or, if filename is nil, close any current script file. The optional flags value lets you specify how to read the script file:
If the flags argument isn't specified, a default value of zero will be used, so none of the flags will be set.
When the end of the file is reached, the interpreter will automatically close the file and return to normal keyboard input, so calling this function with filename set to nil isn't necessary unless you want to stop reading the script file early.
statusMode(mode) – set the status line mode. This can be used to control the status line in non-HTML mode and for text-only (non-HTML) interpreters. The status mode controls where text is displayed. In status mode STATMODE_NORMAL, text is displayed in the main text area. In status mode STATMODE_STATUS, text is displayed to the left portion of the status line. Other status modes are not currently used; any text written to the console in other status modes is not displayed anywhere.
To write to the status line in non-HTML mode and on text-only interpreters, set the status mode to STATMODE_STATUS, write the status line text as though it were ordinary display output, and set the status mode back to STATMODE_NORMAL:
statusMode(STATMODE_STATUS);
"Loud Room";
statusMode(STATMODE_NORMAL);
statusRight(txt) – write the text string txt to the right half of the status line. This can be used to control the right portion of the status line in non-HTML mode and on text-only interpreters.
systemInfo(info_type, ...) – retrieve information about the TADS 3 application environment. This function works the same way it did in TADS 2.
timeDelay(delay_ms) – pause execution for the given number of milliseconds. Note that the precision of system timers varies, so the actual delay might differ from the exact time specified on some systems according to the available hardware timer precision.