vt.doc

Unix下的MUD客户端程序

* in the primitive descriptions below and in prmtref.txt.


Current window and remote
-------------------------

The current window and current remote depend on how VT invokes a task.
VT can invoke a task for one of the following reasons: a key binding,
a command parser directive, an automatic call to redraw_hook(), an
automatic call to disconnect_hook(), a keyboard line passed to a
termread function, or a remote line or prompt passed to a netread or
promptread function.

For a key binding, a command parser directive, or an automatic call to
redraw_hook(), VT defines cur_win as the active window and cur_rmt as
the remote associated with cur_win.  If the active window changes
while the task executes or while the task is suspended, cur_win will
change with it, so you must assign its value to a variable if you wish
to retain the value across a primitive that runs another task or a
primitive that causes the task to be suspended.

In the case of a line passed to a window's termread function, VT
defines cur_win to be the window in question, and cur_rmt to be the
remote associated with that window.

In the case of an automatic call to disconnect_hook() or a remote line
or prompt passed to a remote's netread or promptread function, VT
defines cur_rmt to be the remote in question, and cur_win to be the
window associated with that remote.

More systematically:

			cur_win			cur_rmt
			-------			-------
	Key binding	active			win_rmt(active)
	Parser		active			win_rmt(active)
	Redraw		active			win_rmt(active)
	Disconnect	rmt_win(cur_rmt)	<defined>
	Termread	<defined>		win_rmt(cur_win)
	Netread		rmt_win(cur_rmt)	<defined>
	Promptread	rmt_win(cur_rmt)	<defined>

<defined> means that VT defines it when the task begins.  Otherwise,
evaluating cur_win or cur_rmt is equivalent to evaluating the
expression in the table.


Writing to a null window or remote
----------------------------------

In some situations, VT may attempt to write to a null window or
remote.	 This occurs most often when either cur_win or cur_rmt is NULL
as defined above.  For instance, if a remote has no netread function,
VT will write its output to the current window, which will be NULL if
it has no associated window.

Writing a line to a null remote is a null operation, but writing a
line to a null window is not.  VT will write the line to the active
window, prefixing it with "[background]".  This is not very
informative, but fortunately it can be avoided easily.


Broken pipes
------------

When a VTC task requests input from a window or a remote connection,
VT suspends it while the regular activities of the client continue.
If the window is closed or the remote is disconnected before input
becomes available, VT will resume all tasks which asked for input, and
the getch() or read() call which requested input will return NULL.

getch() and read() calls without window or remote arguments can never
return NULL, because they do not depend on a window which can be
closed.


Destroyed pipes
---------------

If you resize the space which VT is running in such that it cannot fit
as many windows on the screen as there were previously, VT has no
opportunity to resume the tasks which were waiting for input on that
window.  In this case, VT will destroy those tasks altogether.
Fortunately, this is rare.


I/O scheduling
--------------

If multiple tasks request input from a remote or window at the same
time using read(), the requests are placed on the tail of a dequeue
for that remote.  The reread() primitive acts like the read()
primitive but places requests at the head of the dequeue.  VT
processes requests starting at the head of the dequeue.

A routine that uses a read() and pass() loop should call read() to get
the first line and reread() to get subsequent lines.  For example:

	func waitfor(rmt, match) [line] {
		for (line = read(rmt); line; line = reread(rmt)) {
			pass(rmt, line);
			if (!strcmp(line, match))
				return; // Found it
		}
		abort(); /* Connection closed; abort */
	}

If several waitfor() functions are running, VT will plac them on the
dequeue in FIFO order, as is appropriate, but after they pass() a
line, VT replaces them on the dequeue in LIFO order using reread().
Otherwise, the dequeue would reverse order each time a line arrived.

For windows, VT places getch(HIGH) and getch(LOW) calls onto separate
queues, since they apply at different times.  Both read() and getch()
requests which depend on a particular window being active have lower
priority than those which do not.


Breaking
--------

If the current task has gone into an infinite loop or is taking too
long, you can use ^C B to break out of it.  ^C B breaks all currently
running tasks.  This includes tasks that are in the middle of a
primitive that runs another task, such as callv(), detach(),
load_file(), parse(), or insert(), but not suspended tasks.


Debugging
---------

There is a minimal debugging utility for the VTC compiler.  If you use
^C D to turn debugging on, the compiler will output a list of global
variables and undefined functions used by each function and command
that uses them.  This is to help prevent typos, since VT ordinarily
does not complain about such problems until runtime.


Console
-------

You can use the console to eliminate unwanted suspended tasks.  Use ^C
C to enter the console.  The console is a simple menu-driven system
for viewing I/O queues and timed events.  VT performs none of its
normal activities while the console is active.

In the console, VT assigns a number to each window and remote by their
ordering in the internal lists, starting at 0.  Window ordering is top
to bottom; remote ordering is by creation time.  This is the only time
that VT assigns a number to windows and remotes.

The (S)how option lists suspended tasks attached to the various I/O
functions or the timer.	 The (D)elete option aborts a selected
suspended task.


Screen resizing
---------------

If an external windowing task resizes the window that VT is running
in, VT will adapt by shrinking windows to take up roughly the same
percentage of screen space as they did before.	If the screen is too
small to hold the previous number of windows, then VT will discard
windows until there are few enough, and immediately terminate all
tasks waiting for input from discarded windows.  If the space VT runs
in becomes smaller than 4x15, VT will abort.


Primitives
----------

Following is a description of all of the primitives, grouped according
to type.  Preceding each group of primitives is a list of prototypes
for those primitives giving the types of the return value of the
primitive and the arguments it accepts.  A type specification of ??
indicates that the argument is not restricted to any specific types.
Square brackets delimit optional arguments to primitives.  Elipses
(...) usually indicate that you can give more arguments, as explained
in the description.

A * before the name of a primitive indicates that it sets the errflag
and errmsg builtins.


Arrays
------

These primitives deal with arrays:

	NULL		acopy(APTR dest, APTR src, INT n)
	APTR/PLIST/NULL alloc(INT size, [ASSOC assoc])
	APTR/SPTR	base(APTR/SPTR/PLIST ptr)
	INT		garbage()
	APTR/INT	lookup(ASSOC/PLIST/WIN/RMT plist, SPTR name)
	ASSOC		new_assoc()


NULL acopy(APTR dest, APTR src, INT n)

Copies <n> array elements from <src> to <dest>.	 If <n> is 0 or less,
no action is performed.	 If <dest> is an argument array and cannot be
extended to accomodate <n> elements, elements are copied until the end
of the argument array is reached.


APTR/PLIST/NULL alloc(INT size, [ASSOC assoc])

Allocates an array or plist.  <size> is the initial size of the array,
and should be an estimate of the number of data elements the array
will need.  Since the array will stretch if necessary, however, the
value of <size> does not affect program correctness.  If <assoc> is
specified, alloc() returns a plist using that association type;
otherwise, it returns an array.


APTR/SPTR base(APTR/SPTR/PLIST ptr)

Pointers are stored internally as an array and an offset.  The base()
primitive returns the array.  This allows you to avoid storing the
base of an array as a separate variable, if you are certain that the
pointer you began with pointed to the base of the array.  You can get
the offset of a pointer from the expression (ptr - base(ptr)).	base()
can also be used to get the base of an array associated with a plist.


INT garbage()

Calls the garbage collection routine.  This frees up memory from
groups of self-referential arrays that nothing is pointing to.
garbage() returns the number of leaked arrays that were freed.
Normally, this routine is only necessary if you are making regular use
of self-referential data structures such as linked lists with
backlinks.


APTR/INT lookup(ASSOC/PLIST/WIN/RMT plist, SPTR name)

Returns a pointer to the array element referenced by <name> in
<plist>.  If a WIN or RMT is given for <plist> and the object of that
window or remote is a plist, then that plist is used.  See the section
"Property lists and association types" for details.  If an ASSOC is
given for <plist>, then lookup() returns the offset of <name> for that
association type.


ASSOC new_assoc()

Returns a new association type, which can be used to generate property
lists using alloc().  Once an association type is created, it is never
destroyed, and thus should be kept track of.


Environment
-----------

These primitives have to do with the shell running VT:

	SPTR/NULL      *getenv(SPTR envvar)
	INT		system(SPTR cmd)


SPTR/NULL getenv(SPTR envvar)

Returns the value of <envvar> in the environment, or NULL if it does
not exist.


INT system(SPTR cmd)

Runs the shell command <cmd>.  VT is suspended while the command runs.
There is no screen preparation for the running the shell command; you
must prepare the screen yourself using the screen primitives.


Files
-----

These primitives handle I/O and related functions involving files in
the file system:

	NULL	       *fclose(FILE file)
	INT		feof(FILE file)
	SPTR		file_name(FILE file)
	FILE/NULL	find_file(SPTR name)
	INT		fflush(FILE file)
	INT	       *fgetc(FILE file)
	INT	       *fmtime(SPTR filename)
	FILE/NULL      *fopen(SPTR name, SPTR mode)
	INT	       *fputc(INT char, FILE file)
	SPTR/NULL      *fread(FILE file)
	INT	       *fseek(FILE file, INT offset, INT base)
	INT	       *fsize(SPTR filename)
	INT	       *ftell(FILE file)
	INT	       *fwrite(FILE file, SPTR text)
	INT	       *load_file(SPTR filename)
	FILE/NULL      *popen(SPTR cmd, SPTR mode)
	INT	       *unlink(SPTR filename)


NULL fclose(FILE file)

Closes <file>.	If <file> was a process, VT waits for the process to
finish before resuming execution.


INT feof(FILE file)

Returns nonzero if <file> has been read to its end.


SPTR file_name(FILE file)

Returns the name of <file> as given to fopen() or popen().


FILE/NULL find_file(SPTR name)

Searches the list of currently opened files for a file with name
<name>.	 <name> must match the filename given to fopen() or the
command given to popen().


INT fflush(FILE file)

Flushes output to the file <file> if text has been buffered.


INT fgetc(FILE file)

Reads a character from <file>.	Returns EOF if nothing could be read.


INT fmtime(SPTR filename)

Returns the last modification time of the file with the name
<filename> in the file system.	Returns -1 if the file was not found.


FILE or NULL fopen(SPTR name, SPTR mode)

Opens a file with name <name>.	<mode> is "r" for reading, "w" for
writing or "a" for appending, with a "+" added to indicate both
reading and writing.  fopen() returns NULL if the file could not be
opened.


INT fputc(INT char, FILE file)

Writes <char> to <file>.  Returns <char>.  Text is buffered by lines.


SPTR/NULL fread(FILE file)

Reads a line from <file>.  Returns T_NULL if nothing could be read.


INT fseek(FILE file, INT offset, INT ptrname)

Moves to a new position in a file.  <ptrname> is a starting position,
0, 1 or 2 (SEEK_SET, SEEK_CUR, or SEEK_END) for the beginning, current
position, or end of the file, respectively.  <offset> is added to
this position.  fseek() returns non-zero on error.


INT fsize(SPTR filename)

Returns the size of the file with the name <filename> in the file
system.	 Returns -1 if the file was not found.


INT ftell(FILE file)

Returns the current position in <file>.


INT fwrite(FILE file, SPTR text)

Writes <text> to <file>.  Returns the number of characters written.


INT load_file(SPTR filename)

Loads the file with the name <filename> in the file system into the
parser.	 Returns -1 if the file cannot be opened and 0 otherwise.


FILE/NULL popen(SPTR cmd, SPTR mode)

Starts a process with the shell command <cmd>.	<mode> is "r" to read
from the process or "w" to write to it.  Two-way communication is not
possible.  popen() returns NULL if the process cannot be started.


INT unlink(SPTR filename)

Deletes the file with the name <filename> in the file system.  Returns
-1 if the file was not found, 0 otherwise.


Functions
---------

These primitives deal with functions:

	NULL		abort()
	??		callv(FPTR/PPTR func, [<group>]...)