vt.doc

Unix下的MUD客户端程序

After the above example, base(p)[0] would be "Druid" and base(p)[1]
would be 673.

You can use the lookup() operator with windows, remotes, and
association types in addition to plists.  "lookup(win, str)" and
"lookup(rmt, str)" are short for "lookup(obj(win), str)" and
"lookup(obj(rmt), str)" respectively.  "lookup(assoc, str)" returns
the integer offset of <str> for the association type <assoc>.  You can
"lookup(assoc, str)" to force the order of associations for an
association type.  For instance:

	world_type = new_assoc();
	&world_type->name; &world_type->addr; &world_type->port;
	world = alloc(3, world_type);
	acopy(base(world), table("Name", "Addr", 1111), 3);

By forcing the order of associations after creating the association
type, we can initialize new worlds directly by using acopy() and
base().	 (The table() function comes from the distribution.)  Note
that "&world_type->name" is an abbreviation for "&(*lookup(world_type,
"name"))", which is the same as "lookup(world_type, "name")".  If you
leave out the &, you will be dereferencing an integer, which is an
illegal operation.


Strings
-------

Strings are treated in much the same as arrays.	 They will extend with
an attempt to write past their ends using a primitive or an assignment
operator.  Intervening elements are initialized to spaces.  That is,

	[a] a = ""; a[10] = '#'; echo(a);

writes a string of ten spaces followed by a '#'.  Strings are
null-terminated, so setting a string element to 0 shortens the string
if the string previously stretched being the array element in
question.  Elements past the new end of the string are irretrievably
lost.  A string constant in VTC code is inviolate.  Each reference to
that constant produces a different copy of the string.  That is, the
following code:

	[a, i] {
		a = alloc(2);
		for (i = 0; i < 2; i++)
			a[i] = "foobar";
		*a[0] = 'g';
		echo(a[1]);
	}

will produce the output "foobar," not "goobar."	 String elements
beyond the end of a string or before the beginning have the value 0.
Assigning to an element before the beginning of a string results in a
runtime error.

When a primitive takes a string argument, it accepts a string pointer,
which is taken to be the beginning of the string.


Functions
---------

You define functions using the parser.  You cannot undefine functions,
although you can redefine them.  Your VTC code can contain a call to
an undefined function or a pointer to an undefined function, but this
will produce a runtime error if you do not define the function before
executing that part of the code.

Function declarations contain zero or more parameter variables.
Calling a function with fewer arguments than there are parameters
results in a fatal error.  You can call a function with more arguments
than there are parameter variables.  The function can use the argc and
argv builtins to access these arguments.  The argc builtin returns the
number of arguments passed to the function, and the argv builtin
returns an array that contains all of the arguments, including the
declared parameters.

You can declare some of your function's parameters to be optional, by
preceding them with a '/'.  For instance, in the parameter list "(foo,
bar / baz, quux)", baz and quux are optional arguments.  These
parameters have the value NULL if you do not specify them in a call to
the function.

Functions return a value specified by a return statement, or NULL if
they exit normally.

Many functions have the form:

	func name(args) { return expr; }

where <expr> is a short expression.  A shortcut for this is:

	func name(args) --> expr

If <expr> takes several lines, you must escape each newline explicitly
with a '\', so this construct is best only for short expressions.


Windows
-------

VT divides the screen into two areas: an input window occupying
several lines at the bottom of the screen, and an output region, which
is further divided into one or more output windows.  Each output
window has a divider line below it.  When VT starts up, the input
window occupies three lines, and the rest of the screen is used for
one output window.

At all times, one of the output windows is 'active'.  This window has
an asterix (*) in the first column of the divider line below it.  To
change the active window, use the ^XO key combination defined by the
distribution VTC code.

The input window can be in either VTC mode or text mode.  In VTC mode,
a line entered in the input window will be parsed, while in text mode
it will be passed to the active window.  To change modes, use the ESC
ESC key bombination defined by the distribution.

VT checks each character typed against a list of key bindings.  If a
character completes any one of these bindings, VT executes an editing
function or a VTC function.  If the character only partially matches a
multiple-character key binding, then VT holds onto it to see if
following characters match the rest of the sequence.  If they do not,
or if a character does not match a key binding at all, then VT
displays it in the input window.

Following is a list of editing functions, along with the bindings
assigned to them by the distribution.  The mnemonics are named
constants in the VTC compiler.  To get a list of key bindings from
with the client, use the command "/list_keys" defined by the
distribution.

	Mnemonic	Keys		Description
	--------	----		-----------
	K_CUP		ESC [A		Cursor up
	K_CDOWN		ESC [B		Cursor down
	K_CLEFT		ESC [C		Cursor left
	K_CRIGHT	ESC [D		Cursor right
	K_CHOME		^A or ^[[H	Cursor to start of line
	K_CEND		^E or ^[[K	Cursor to end of line
	K_CWLEFT	ESC B		Cursor word left
	K_CWRIGHT	ESC F		Cursor word right
	K_BSPC		^H or DEL	Delete character left
	K_BWORD		^W		Delete word left
	K_BHOME		^[K		Delete to start of line
	K_DBUF		^X or ^U	Delete input buffer
	K_DCH		^D		Delete character right
	K_DWORD		ESC W		Delete word right
	K_DEND		^K		Delete to end of line
	K_REFRESH	^R		Rewrite the input window
	K_REDRAW	^L		Redraw the screen
	K_MODE		ESC ESC		Toggle input window mode
	K_PROCESS	newline		Process input buffer

VTC tasks can intercept keystrokes using the getch() primitive.
getch() takes a priority argument to determine whether to check key
bindings before returning the keypress, and an optional window
argument specifying which window must be active in order for a
keypress to be intercepted.  VT dispatches keypresses as follows:

	Resume task that called getch(HIGH) if any, or
	Resume task that called getch(HIGH, window) if any, or
	Execute key binding, if matched, or
	Hold key, if key partially matched key binding, or
	Resume task that called getch(LOW) if any, or
	Resume task that called getch(LOW, window) if any, or
	Insert in input buffer

When the user enters a line in text mode, VT "passes" it to the active
window.  A VTC task can also do this with the pass() primitive.  VTC
tasks can intercept lines passed to a window using the read()
primitive.  read() with no arguments will intercept a line entered
while any window is active; read() with a window argument will
intercept a line entered while that window is active.  Windows have a
"termread" function to handle unintercepted lines.  VT dispatches user
input lines as follows:

	Parse, if the input window is in VTC mode, or
	Resume task that called read() with no arguments, if any, or
	Resume task that called read(window), if any, or
	Run active window's termread function, if it exists, or
	Send to active window's remote connection, if it exists, or
	Discard

VT calls the window's termread function with one argument, the line
passed to the window, with no newline character at the end.

The builtin variable "prompt" contains a string which VT displays in
the input window.  A VTC task can set this prompt using a statement
like:

	prompt = "> ";

The K_PROCESS editing function resets the prompt to an empty string.


Remote connections
------------------

VTC tasks can open connections to remote hosts with the connect()
primitive.  VT associates three VTC-settable flags with each remote: a
"busy" flag signalling that VT should not process any input from that
remote, a "background" flag controlling whether VT should process
input from the remote connection when it is not associated with a
window, and a "raw" flag which determines how VT will process input
from the remote host.  To set these flags, use the set_busy(),
set_back(), and set_raw() primitives.  To read them, use the
rmt_busy(), rmt_back(), and rmt_raw() primitives.

A VT connection is said to be in raw mode when the raw flag is on, and
in line mode when the raw flag is off.  In line mode, VT breaks up
incoming server data into lines before dispatching it.  In raw mode,
VT dispatches the text in blocks.  In both modes, VT will dispatch a
prompt if it sees a prompt terminator, which is a telnet IAC GA
sequence or possibly a telnet IAC EOR sequence.

VT supports the telnet protocol and the telnet options ECHO and EOR.
Remote connections have two non-user-settable flags, "echo" and "eor".
You can check the state of the echo and eor flags with rmt_echo() and
rmt_eor().

The "echo" flag determines whether VT will display input in the input
window, and defaults to on.  If the server sends an IAC WILL ECHO
while the echo flag is set, VT will reply with an IAC DO ECHO and
clears the echo flag.  While the flag is clear, if the server sends an
IAC WONT ECHO, VT responds with an IAC DONT ECHO and sets the echo
flag.  VT will not display input in the input window while the echo
flag is clear.

The "eor" flag defaults to off.  The remote server can turn it on with
an IAC WILL EOR, which VT will respond to with an IAC DO EOR.  When
the eor flag is on, VT will accept an IAC EOR sequence as a prompt
terminator.  The remote server can turn the flag off with an IAC WONT
EOR, which VT will respond to with an IAC DONT EOR.  While the flag is
off, or if the connection is in raw mode, VT ignores IAC EOR.

VT interprets IAC GA as a prompt terminator regardless of the eor
flag.

In line mode, VT interprets a newline as a line terminator, and
ignores carriage returns entirely.  In raw mode, VT uses newlines only
to determine the beginning of a prompt when it encounters a prompt
terminator.

The display() primitive associates a remote connection with a window
and vice versa.  You can only associate one remote connection with a
window and vice versa.

VTC tasks can intercept lines or blocks from a remote using the read()
primitive, but they cannot intercept prompts.  Remote connections have
"promptread" and "netread" functions to handle prompts and
unintercepted lines or blocks.

Blocks (in raw mode) and lines (in line mode) are dispatched as
follows:

	Resume task that called read(remote), if any, or
	Run remote's netread function, if it exists, or
	Write to the remote's window, if it exists, or
	Write to the active window with a "[background] " prefix

Prompts are dispatched as follows:

	Run remote's promptread function, if it exists, or
	Write to the remote's window, if it exists, or
	Write to the active window with a "[background] " prefix


Hooks
-----

VT has two "hooks", or functions it calls automatically in certain
situations.

When VT redraws the screen automatically (that is, after returning
from a SIGTSTP (^Z) signal or after the screen is resized), if there
is a function redraw_hook(), VT will call that function rather than
redraw the screen.  The function can call edfunc(K_REDRAW) to redraw
the screen normally.

Second, whenever a remote connection is closed, whether through the
disconnect() primitive or due to a read error or a foreign host, VT
will call disconnect_hook() if it exists.


Named constants
---------------

There are several reserved words in VTC that are translated directly
into integer constants.	 These numbers have some meaning to certain
primitives in the compiler.  The constants are:

	Name		Value	Description
	----		-----	-----------
	T_INT		 0	Data types
	T_PPTR		 1
	T_BPTR		 2
	T_RMT		 3
	T_WIN		 4
	T_KEY		 5
	T_FILE		 6
	T_SPTR		 7
	T_APTR		 8
	T_FPTR		 9
	T_REG		10
	T_ASSOC		11
	T_PLIST		12
	T_NULL		13
	K_CUP		 0	Editing functions
	K_CDOWN		 1
	K_CLEFT		 2
	K_CRIGHT	 3
	K_CHOME		 4
	K_CEND		 5
	K_CWLEFT	 6
	K_CWRIGHT	 7
	K_BSPC		 8
	K_BWORD		 9
	K_BHOME		10
	K_DBUF		11
	K_DCH		12
	K_DWORD		13
	K_DEND		14
	K_REFRESH	15
	K_REDRAW	16
	K_MODE		17
	K_PROCESS	18
	SEEK_SET	 0	For fseek(): beginning of file
	SEEK_CUR	 1		     current position in file
	SEEK_END	 2		     end of file
	HIGH		 0	For getch() primitive
	LOW		 1
	INTR		 2
	EOF		-1	For reading files
	NSUBEXP		10	Max. number of regexp sub-expressions


Built-in objects (builtins)
---------------------------

Most built-in objects act like variables whose values are tied to
functions of the client.  Their values can change automatically.  Here
is a complete list:

	Name		Type	Description
	----		----	-----------
	active		WIN	Active window
	prompt		SPTR	Input window prompt
	kbuf		SPTR	Key buffer in input window
	kpos		INT	Offset of cursor in key buffer
	cur_win		WIN	Current window (see below)
	cur_rmt		RMT	Current remote (see below)
	argc		INT	Number of arguments to current function
	argv		APTR	Current function's argument array
	time		INT	Current time (seconds since Jan 1, 1980)
	wd		SPTR	Current working directory
	rnd		INT	A random integer from 0 to max int value
	version		SPTR	Version number
	errflag		INT	Error flag (1 or 0)
	errmsg		SPTR	Error message for last error
	NULL		NULL	Null value

You can assign to the builtins active, prompt, kbuf, kpos, argc, argv,
and wd.	 Assigning to argc and argv affects only the current function
and is a convenience for functions that traverse their argument array.
Assignments to argv also do not affect which arguments the parameter
variables refer to.  Assigning to other builtins has an immediate
effect.	 Assigning to the wd builtin will sometimes fail, in which
case the errflag and errmsg builtins are set as with primitives that
can fail.  Attempting to assign an object of the wrong type to a
builtin, or assigning to a builtin that cannot be written to, results
in an "Illegal builtin assignment" runtime error.  This also occurs if
you attempt to assign an array pointer to the argv builtin that does
not point into the current function's parameter array.  The & operator
can be used to get a pointer to a builtin object (of type BPTR), just
as with variables.

The prompt, kbuf and wd builtins store strings, not pointers to
strings, so that while "kbuf++" is legal, the first character of the
keyboard buffer is lost, and a subsequent "kbuf--" will not allow you
to recover it (it will instead clear the keyboard buffer).  Also, any
nonprintable characters will be stripped from a string you assign to
the kbuf or prompt builtins.

The prompt builtin applies to the input window only in text mode, and
the prompt persists only until one line is entered, at which time it
reverts to the empty string.


Non-fatal errors
----------------

A number of primitives can fail with a non-fatal error if their
arguments are invalid or some other condition occurs.  These
primitives return an error code under such conditions.	The errflag
builtin is nonzero if the last error-returning primitive failed.  If
errflag is nonzero, then errmsg contains a string with some
information as to why the error occurred.

errflag and errmsg are also set when the bobj assignment to the wd
builtin fails, and when VT calls the disconnect_hook() primitive.  In
the latter case, errflag is 0 if the remote was disconnected through
the disconnect() primitive, and 1 if it was disconnected because of a
failed send or receive or a closed connection.

Primitives that set the errflag and errmsg builtins are marked with a