tfio

TF normally does its output through "streams", which are analagous to the streams of C stdio.

Output from most tf commands, including /echo, are output to the "tfout" stream, which is normally attached to the screen. tfout may be redirected with a command /quote, $() command substitution, or %| pipe.

Tf error messages, hook messages, and the output of "/echo -e" are output to the "tferr" stream, which is always attached to the screen, and may not be redirected.

Text from a world or "/echo -w" is sent to a stream for that world. Text sent to a world stream will be stored in the history of that world. If that world is the foreground world, the text is sent to the screen immediately; otherwise, it will not be displayed until world is brought into the foreground.

Commands that read input (using tfread()) read by default from "tfin", which is normally attached to the keyboard. tfin may be redirected with a %| pipe.

All streams have a handle which can be used as an argument to the tfio functions. The handles for tfin, tfout, and tferr are "i", "o", and "e", respectively. The handles for streams opened with tfopen() are integers.

tfopen()

The tfopen(name, mode) function can be used to open arbitrary streams. If called with no arguments, tfopen() opens an unnamed "q" mode stream. The mode argument describes the usage of the stream:

"w": Open a file "name" for writing. Write operations will overwrite existing file contents, if any.
"a": Open a file "name" for appending. Write operations will occur after existing file contents, if any.
"r": Open a file "name" for reading. (see also: "/quote '").
"p": Execute a shell command "name" and read its output (see also: "/quote !").
"q": Open a queue for reading and writing. The name argument will appear in the output of /liststreams, but has no other meaning.

A "q" mode stream may be thought of as a place to hold lines for passing between two or more commands.

If successful, the tfopen() function returns a positive number which is the handle of the new stream, which should be used in subsequent calls to tfread(), tfwrite(), and tfclose(). If it fails, the tfopen() function returns -1.

A call to tfwrite() or tfread() on a stream opened with a mode that does not allow that operation will return -1.

The /liststreams command will display a list of open streams.

tfclose()

When a stream opened by tfopen() is no longer needed, it should be closed with tfclose(handle), which will flush the stream and release its resources. tfclose() can be used on the tfout stream (handle "o") within a macro body to prevent further output from subsequent commands in that macro body; closing the tfin stream (handle "i") will prevent further reads; and closing the tferr stream (handle "e") is not allowed.

tfwrite()

The tfwrite(handle, line) function writes a line of text to the stream designated by handle. If handle is omitted, the tfout stream is used (so tfwrite(line) is equivalent to echo(line)).

If an OS file (mode "w" or "a") is set to autoflush (the default), then each line written is flushed to the file immediately. If you are writing a large number of lines, it is more efficient to disable autoflushing with tfflush(handle, "off"), and manually force a flush with tfflush(handle) or tfclose(handle) after writing the large block. tfflush() has no meaning on files of mode "p", "q", or "r". Streams are flushed automatically when closed.

tfread()

The tfread(handle, variable) function reads a line from the stream designated by handle. If handle is omitted, the tfin stream is used. If successful, the line is assigned to variable, and tfread() returns the (non-negative) length of the line. If variable did not already exist, it is created at the global level, as if by /set. If there are no lines available to read, or an error occurs, tfread() returns -1. For "r" and "p" mode streams, a -1 return value indicates end-of-file; the only valid operation on the stream after that is tfclose(). But for a "q" mode stream, a -1 return value may just mean there are currently no lines in the queue; more lines may be added by tfwrite(), and then tfread() will be able to read them.

Keyboard Reading

tfread() from the keyboard is special. It can only be done from a command line command; trying to do it directly or indirectly from a trigger, hook, keybinding, or process is an error, and will make the tfread() return -1. It reads a line of input from the keyboard until the newline key is pressed or "/dokey newline" is executed. During the read, all existing keybindings continue to work normally. Any text already in the input buffer is not cleared when the read starts. Text entered after the read starts is appended to the existing text, and when the read ends, its result is the entire input buffer. Lines entered during a read are not saved in the input history (but you can use "/recordline -i" to save them explicitly).

A read from the keyboard (and the macro that called it) can be interrupted with a SIGINT, normally generated by typing CTRL-C.

During a keyboard read, if a macro calls /dokey newline, the newline will not be executed immediately, but will be held until the rest of the commands in the macro are processed. For example, consider the keybinding "/def -b'^[^M' = /dokey newline%; /send go". Normally, typing ^[^M would execute the current input buffer, then send "go" to the server. But during a keyboard read, typing ^[^M would send "go" first, and then do the newline that completes the read.

The library file textutil.tf defines several commands that are useful with tfio.

See: interface, /liststreams, /input, expressions, nread(), functions, textutil.tf

Back to index
Back to tf home page