vt.doc

Unix下的MUD客户端程序

	NULL		detach(FPTR/PPTR func, args...)
	FPTR/NULL	find_func(SPTR name)
	PPTR/NULL	find_prmt(SPTR name)
	SPTR		func_name(FPTR func)


NULL abort()

Terminates the currently-running task.


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

Runs <func> with a variable number of parameters.  The arguments to
callv() come in groups.	 A group's first argument must be an integer
specifying the number of parameters to add to the count.  If this
integer is zero or more, then the parameters are taken from an array
contained in the next argument to callv(); if it is negative, they are
taken from the next arguments to callv().  This is best illustrated
with an example:

	callv(.f, 10, array, -3, a, b, c);
		  (group 1)  ( group 2 )

This calls function f with 13 arguments, ten of which are taken from
locations starting at <array>, and the remaining three of which are a,
b, and c.

As an example, an echoln() function that takes a variable number of
string arguments could be written as follows without callv():

	func echoln() [w, i] {
		if (type(*argv) == T_WIN) {
			w = *argv++;
			argc++;
		} else
			w = cur_win;
		while (argc--)
			echo(w, *argv++);
		echo(w, "\n");
	}

The following function does the same thing more simply and more
quickly:

	func echoln() {
	       callv(.echo, argc, argv, -1, "\n");
	}

callv() returns the return value of <func>.


NULL detach(FPTR/PPTR func, args...)

Runs <func> detached.  That is, if <func> is suspended or exits due to
a fatal error or abort(), the activities of the task that calls
detach() will continue.  The calling task will wait for <func> to be
suspended or to exit before resuming execution.


FPTR/NULL find_func(SPTR name)

Searches for a function with the name <name>.  Returns NULL if no such
function exists.


PPTR/NULL find_prmt(SPTR name)

Searches for a primitive with the name <name>.	Returns NULL if no
such primitive exists.


SPTR func_name(FPTR func)

Returns the name of <func>.


Key Bindings
------------

These primitive handle binding of key sequences to commands:

	KEY/NULL	bind(SPTR sequence, INT/FPTR func)
	KEY/NULL	find_key(SPTR sequence)
	FPTR/INT	key_func(KEY key)
	SPTR		key_seq(KEY key)
	NULL		unbind(KEY key)


KEY/NULL bind(SPTR sequence, INT/FPTR kfunc)

Binds a key sequence to an editing function or VTC function.  If
<sequence> is a blank string, bind_edit() returns NULL; otherwise, it
returns a pointer to the key binding.  <kfunc> can be specified with
the named constants beginning with "K_" if it is an editing function.
Binding a key to an integer that is not an editing function causes the
key to do nothing.  If <sequence> matches the sequence of a key that
has already been bound, that binding is replaced.


KEY/NULL find_key(SPTR sequence)

Searches for a key with sequence <sequence>.  Returns T_NULL if no
such key exists.


FPTR/INT key_func(KEY key)

Returns the function of key, which is either a VTC function pointer or
an editing function.  You can use type() to determine what type of
function was returned.


SPTR key_seq(KEY key)

Returns the key sequence of <key>.


NULL unbind(KEY key)

Deletes the key binding <key>.


Key Buffer
----------

These primitives are related to the key buffer in the input window:

	NULL		edfunc(INT kfunc)
	INT		getch(INT type, [WIN win])
	NULL		insert(SPTR text)


NULL edfunc(INT kfunc)

Runs the editing function <kfunc>.  The named constants K_* are of use
in specifying <kfunc>.  No action is taken if <kfunc> is out of range.


INT getch(INT type, [WIN win])

Reads a character from the keyboard.  If <win> is specified, the task
will only intercept a character when <win> is the active
window.	 If <win> is deleted while the task is suspended, getch()
returns NULL.  Non-window-specific requests have higher priority than
window-specific requests.

<type> determines whether the incoming character will be checked to
see if it is part of an editing key before it is intercepted.  For
instance, a pager would probably only wish to accept a key if it is
not an editing function.  The named constants HIGH (0) and LOW (1) can
be used to specify this type, with HIGH intercepting the key before
checking for editing functions, and LOW intercepting it afterwards.
HIGH requests have a higher priority than LOW requests, even if the
LOW request would ordinarily have higher priority because it is
non-window-specific and the HIGH request is window-specific.

If a window argument is not specified, <type> can be INTR (2).	In
this case, client operations are interrupted until a key is pressed.


NULL insert(SPTR text)

Mimicks <text> being typed by the user.


Miscellaneous
-------------

These primitives perform miscellaneous functions:

	SPTR		ctime(INT time)
	APTR		find_var(SPTR name)
	??		head(INT type)
	??		next(?? node)
	NULL		parse(SPTR str)
	??		prev(?? node)
	NULL		quit()
	NULL		rndseed(INT seed)
	NULL		sleep(INT seconds)
	??		tail(INT type)
	INT		type(?? data)


SPTR ctime(INT time)

Converts <time> into a string format.  For instance:
	"Sun Oct 20 23:58:34 PDT 1991\n"


APTR find_var(SPTR name)

Returns a pointer to a global variable with name <name>.  find_var()
always succeeds, creating a new variable initialized to NULL if no
previous variable with name <name> existed.


?? head(INT type)

Returns the first node in the internal linked list of type <type>.
<type> can be T_RMT, T_WIN, T_KEY or T_FILE.  Returns NULL if the list
is empty or if <type> is invalid.


?? next(?? node)

Returns the next node in the internal linked list of the same type as
<node>.  <node> can be of type T_RMT, T_WIN, T_KEY or T_FILE.  Returns
NULL if <node> is the last entry in the list.


NULL parse(SPTR str)

Parses the string <str> as if it were a line of text entered from the
keyboard preceeded by a backslash (\).  Do not include newlines in
this string.


?? prev(?? node)

Returns the previous node in the internal linked list of the same type
as <node>.  <node> can be of type RMT, WIN, KEY or FILE.  Returns NULL
if <node> is the first entry in the list.


NULL quit()

Exits the client.


NULL rndseed(INT seed)

Seeds the random number generator with <seed>.	Random numbers can be
obtained through the builtin "rnd".


NULL sleep(INT seconds)

Suspends task execution for <seconds> seconds.


?? tail(INT type)

Returns the last node in the internal linked list of type <type>.
<type> can be T_RMT, T_WIN, T_KEY or T_FILE.  Returns NULL if the list
is empty or if <type> is invalid.


INT type(?? data)

Returns the type of <data>, as per the named constants.


Regexps
-------

These primitives are involved with regular expressions:

	REG/NULL       *regcomp(SPTR regstr)
	INT		regexec(REG regexp, SPTR text)
	SPTR/NULL	regmatch(REG regexp, INT num)
	INT		smatch(SPTR pattern, SPTR text)


REG/NULL regcomp(SPTR regstr)

Compiles <regstr> into a regexp.  If <regstr> is not a valid regexp,
regcomp() returns NULL and sets errflag and errmsg.


INT regexec(REG regexp, SPTR text)

Matches <text> against <regexp>.  Returns nonzero if successful.


SPTR/NULL regmatch(REG regexp, INT num)

Returns the string that matched the <num>th parenthesized expresion in
<regexp> in the last match.  If <num> is 0, the string that matched
the regular expression is returned.  The string is copied, so pointer
comparisons cannot be used among different return values of regmatch()
or the text given to regexec().  regmatch() returns NULL if the
substring requested has not been intialized.  <num> must be between 0
and NSUBEXP - 1.


INT smatch(SPTR pattern, SPTR text)

Matches <text> against <pattern>.  Returns 1 if successful.  Patterns
for smatch() are simplified forms of the patterns sh uses to match
files.	The pattern is anchored to the start and end of <text> unless
'*' is used at the start or end.  The character '*' in a pattern
matches any number of characters, while '?' matches exactly one
character.  Any other character in a pattern matches itself.  The
smatch() routine is not case-sensitive.	 smatch() patterns are much
less powerful and general than regular expressions but are easier to
write, usually faster, and often easier to work with.


Remotes
-------

These primitives deal with I/O with remotes:

	RMT	       *connect(SPTR address, INT port)
	NULL		disconnect(RMT rmt)
	INT		input_waiting(RMT/FILE/0 stream)
	RMT/NULL	find_rmt(SPTR name)
	??		obj(WIN/RMT thing)
	NULL		pass(WIN/RMT thing, SPTR text)
	SPTR		read([WIN/RMT thing])
	SPTR		reread([WIN/RMT thing])
	SPTR		rmt_addr(RMT rmt)
	INT		rmt_back(RMT rmt)
	INT		rmt_busy(RMT rmt)
	INT		rmt_echo(RMT rmt)
	INT		rmt_eor(RMT rmt)
	SPTR		rmt_name(RMT rmt)
	FPTR/NULL	rmt_netread(RMT rmt)
	INT		rmt_port(RMT rmt)
	FPTR/NULL	rmt_promptread(RMT rmt)
	INT		rmt_raw(RMT rmt)
	WIN/NULL	rmt_win(RMT rmt)
	NULL	       *send([RMT/NULL rmt], SPTR text, ...)
	NULL		set_back(RMT rmt, INT val)
	NULL		set_busy(RMT rmt, INT val)
	NULL		set_netread(RMT rmt, FPTR func or NULL)
	NULL		set_obj(WIN/RMT thing, ?? object)
	NULL		set_promptread(RMT rmt, FPTR func or NULL)
	NULL		set_raw(RMT rmt, INT val)


RMT connect(SPTR address, INT port)

Attempts to open a new remote connection.  <address> is either a
numeric IP address or a name address.  <port> is the port to connect
to.  After connecting, it may be desirable to use display() to
associate the connection with a window.	 If connect() fails, it sets
errflag and errmsg accordingly.


NULL disconnect(RMT rmt)

Closes the given remote connection.  read() requests on <rmt> will be
resumed with return values of NULL.  Any text not read from the remote
is lost.  The data object on the remote is freed.


INT input_waiting(RMT/FILE/0) stream

Passing input_waiting() an integer argument other than 0 results in a
fatal invalid argument error.  input_waiting() tests whether <rmt> or
<file> or the keyboard (specified by 0) is ready for reading. [Check
to see how files behave.]  It returns 1 if any input is waiting, or 0
if not.


RMT/NULL find_rmt(SPTR name)

Searches the list of remotes for <name>.  If more than one remote has
the name <name>, find_rmt() returns the first one opened.  find_rmt()
returns NULL if the name is not found.


?? obj(WIN/RMT thing)

See the description under the section on window primitives.


NULL pass(WIN/RMT thing, SPTR text)

See the description under the section on window primitives.


SPTR read([WIN/RMT thing])

See the description under the section on window primitives.


SPTR reread([WIN/RMT thing])

See the description under the section on window primitives.


SPTR rmt_addr(RMT rmt)

Returns the address of <rmt> as it was given to the connect() 
primitive.


INT rmt_back(RMT rmt)

Returns 0 if <rmt>'s background flag is clear, or 1 if it is set.  If
this flag is set, then VT will process input from the remote while it
is not associated with a window; otherwise, it will not.


INT rmt_busy(RMT rmt)

Returns 0 if <rmt>'s busy flag is clear, or 1 if it is set.  VT will
not process input from <rmt> when its busy flag is set.


INT rmt_echo(RMT rmt)

Returns 0 if <rmt>'s echo flag is clear, or 1 if it is set.  This flag