vt.doc

Unix下的MUD客户端程序

is usually set, but the remote connection can turn it out, in which
case VT will not display text in the input window while <rmt> is the
active window's remote connection.


INT rmt_eor(RMT rmt)

Returns 0 if <rmt>'s end-of-record flag is clear, or 1 if it is set.
If the remote host has turned this flag on, then VT will interpret
telnet IAC EOR sequences as prompt terminators; otherwise, it will
ignore them.


SPTR rmt_name(RMT rmt)

Returns the name of <rmt>.


FPTR/NULL rmt_netread(RMT rmt)

Returns the netread function associated with <rmt>, or NULL if 
there is none.


INT rmt_port(RMT rmt)

Returns the port number of <rmt>.


FPTR/NULL rmt_promptread(RMT rmt)

Returns the promptread function associated with <rmt>, or NULL if
there is none.


INT rmt_raw(RMT rmt)

Returns 0 if <rmt>'s raw flag is clear, or 1 if it is set.  VT will
not split up incoming text from <rmt> into lines if <rmt>'s raw flag
is set.


WIN/NULL rmt_win(RMT rmt)

Returns the window associated with <rmt>, or NULL if there is none.


INT send([RMT rmt], SPTR text, ...)

Accepts an optional remote, and any number of string arguments.
send() writes its string arguments to <rmt>, or to cur_rmt if <rmt> is
not specified.	If <rmt> is not specified and cur_rmt is null, the
text is discarded.  If send() fails, the remote is disconnected,
calling disconnect_hook() if it exists, and errflag and errmsg are set
appropriately.	However, the errmsg set in the call to
disconnect_hook() is more informative than the one set by the failed
send(), so it should be used instead.  send() returns 0 on success, -1
on error.


NULL set_back(RMT rmt, INT val)

Sets or clears <rmt>'s background flag.	 If this flag is set (<val> is
nonzero), text can be read from <rmt> while <rmt> is not associated
with a window.  A netread function attached to <rmt> will run with
cur_win == NULL when <rmt> is not associated with a window.  See the
echo() primitive for information on how VT handles writing to a null
window.  If <rmt>'s background flag is cleared, text will not be read
from <rmt> unless it is associated with a window.


NULL set_busy(RMT rmt, INT val)

Sets or clears <rmt>'s busy flag.  Text will not be read from <rmt>
under any circumstances as long as this flag is set.  This is useful
for pagers and other tasks which do not wish to have remote text
processed until the user hits a key.


NULL set_netread(RMT rmt, FPTR func or NULL)

Assigns a netread function to <rmt>.  When text is read from <rmt> and
is not intercepted by another task doing a read(), <func> will be run
with the text as an argument.  This text is a line with no terminating
newline if <rmt>'s "raw" flag is not set, and a block of up to 1024
characters of unprocessed text if it is set.  If the second argument
to set_netread() is NULL, the remote will have no netread function.


NULL set_obj(WIN/RMT thing, ?? object)

See the description under the section on window primitives.


NULL set_promptread(RMT rmt, FPTR func or NULL)

Assigns a promptread function to <rmt>.  When text is read from <rmt>
followed by an IAC GA, <func> will be run with the text as an
argument.  This text is a line with no terminating newline.  The
promptread function is meaningless in raw mode.  If the second
arugment to set_promptread() is NULL, the remote will have no
promptread function.


NULL set_raw(RMT rmt, INT val)

Sets or clears <rmt>'s raw flag.  This flag determines how text is
read by the remote.  If the raw flag is set, text is read as blocks of
up to 1024 characters of unprocessed characters, including carriage
returns and newlines.	This is the text that is intercepted by
read(), send to a netread function, or displayed on the screen.	 If
the raw flag is cleared, text is read as lines with no terminating
newline.

Raw mode is convenient for connecting to servers that do not
communicate in units of lines.


Screen
------

These primitives directly affect the screen, bypassing the window
interface:

	NULL		bold(INT state)
	NULL		clreol()
	NULL		clrscr()
	NULL		cmove(INT row, INT col)
	NULL		curs_reset()
	NULL		scroll(INT top, INT bottom)
	NULL		scr_fwd(INT lines)
	NULL		scr_rev(INT lines)
	NULL		write(SPTR text, ...)


NULL bold(INT state)

Turns boldfacing on or off on the terminal, depending on whether
<state> is nonzero or zero.


NULL clreol()

Clears text to the remainder of the current line.


NULL clrscr()

Clears the screen.  The statement, "edfunc(K_REDRAW);" can be used to
restore the screen.  Text previously in the output windows is lost.


NULL cmove(INT row, INT col)

Moves the cursor to the given row and column.  The upper left corner
of the screen is (0, 0), not (1, 1).  See the curs_reset() primitive
for ensuring that the cursor position is restored.  The cursor
position may be modified in any case between task executions and while
tasks are suspended.

Coordinates off the screen will usually be ignored, depending on your
terminal.


NULL curs_reset()

Schedules a cursor reset.  The cursor will be restored to the input
window during the next cycle of the main loop of the client, and the
scrolling area will be reset if necessary.  Either of these might
occur anyway.


NULL scroll(INT top, INT bottom)

Sets the scroll region of the terminal.	 The top of the screen is row
0.  Curs_reset() should be used to ensure that the scroll region is
restored.  The scroll region may be modified in any case between task
executions and while tasks are suspended.

Row numbers off the screen will usually be ignored, depending on your
terminal.


NULL scr_fwd(INT lines)

Scrolls the current region forward (up) by <lines> rows.  If this
region has not been set recently with scroll(), it may be any of the
output windows or the input window.


NULL scr_rev(INT lines)

Scrolls the current region backward (down) by <lines> rows.  If this
region has not been set recently with scroll(), it may be any of the
output windows or the input window.


NULL write(SPTR text, ...)

Accepts any number of string arguments, which are written directly to
the terminal one after another with no processing.  This is useful for
things such as terminal controls which would confuse the echo()
function.


Strings
-------

These primitives manipulate strings:

	INT		atoi(SPTR str)
	SPTR		itoa(INT num)
	INT		lcase(INT char)
	SPTR		strcpy(SPTR dest, SPTR src, [INT n])
	SPTR		strcat(SPTR dest, SPTR src, [INT n])
	SPTR		strdup(SPTR str)
	SPTR		strcmp(SPTR str1, SPTR str2, [INT n])
	SPTR		stricmp(SPTR str1, SPTR sptr2, [INT n])
	SPTR/NULL	strchr(SPTR str1, INT c, [INT n])
	SPTR/NULL	strrchr(SPTR str1, INT c, [INT n])
	INT		strcspn(SPTR text, SPTR search)
	SPTR/NULL	strstr(SPTR str1, SPTR str2)
	SPTR/NULL	stristr(SPTR str1, SPTR str2)
	SPTR		strupr(SPTR str)
	SPTR		strlwr(SPTR str)
	INT		strlen(SPTR str)
	INT		ucase(INT char)
	SPTR		wrap(SPTR text, INT margin, [INT indent],
						     [INT start])


INT atoi(SPTR str)

Returns <str> read as an integer.


SPTR itoa(INT num)

Returns a string containing a decimal representation of <num>.


INT lcase(INT char)

Returns <char> in lowercase if <char> is alphabetical, or <char> if it
is not.  The return value is always between 0 and 128.


SPTR strcpy(SPTR dest, SPTR src, [INT n])

Copies <src> into <dest>.  If <dest> points beyond the end of a
string, the string is lengthened before copying.  Returns <dest>.  If
a third integer argument is specified, a maximum of <n> characters are
copied.


SPTR strcat(SPTR dest, SPTR src, [INT n])

Copies <src> onto the end of <dest>.  If <dest> points beyond on the
end of a string, the string is lengthened before copying.  Returns
<dest>.	 If a third integer argument is specified, a maximum of <n>
characters are copied.


SPTR strdup(SPTR str)

Returns a duplicate copy of <str>.


SPTR strcmp(SPTR str1, SPTR str2, [INT n])

Compares <str1> to <str2>.  Returns a number greater than, equal to or
less than 0, reflecting whether <str1> is lexically greater than,
equal to or less than <str2>.  If a third integer argument is
specified, a maximum of <n> characters are compared.


SPTR stricmp(SPTR str1, SPTR sptr2, [INT n])

Compares <str1> to <str2>, ignoring case differences.  Returns a
number greater than, equal to or less than 0, reflecting whether
<str1> is lexically greater than, equal to or less than <str2>.	 If a
third integer argument is specified, a maximum of <n> characters are
compared.


SPTR/NULL strchr(SPTR str1, INT c, [INT n])

Searches <str1> for <c>.  Returns a pointer to an element in <str1>
containing <c>, or NULL if none is found.  If a third integer argument
is specified, a maximum of <n> characters are scanned.


SPTR/NULL strrchr(SPTR str1, INT c, [INT n])

Finds the last occurrance of <c> in <str1>.  Returns a pointer to an
element in <str1> containing <c>, or NULL if none is found.  If a
third integer argument is specified, a maximum of <n> characters are
scanned.


INT strcspn(SPTR text, SPTR search)

Returns the number of sequential characters in <text> that are not
contained in <search>.


SPTR/NULL strstr(SPTR str1, SPTR str2)

Searches for an occurrence of <str2> as a substring of <str1>.
Returns a pointer to an element in <str1> that is the beginning of a
substring that matches <str2>, or NULL if none is found.


SPTR/NULL stristr(SPTR str1, SPTR str2)

Searches for an occurrence of <str2> as a substring of <str1>,
ignoring case.	Returns a pointer to an element in <str1> that is the
beginning of a substring that matches <str2>, or NULL if none is
found.


SPTR strupr(SPTR str)

Converts all alphabetical elements of <str> to uppercase.  Returns
<str>.


SPTR strlwr(SPTR str)

Converts all alphabetical elements of <str> to lowercase.  Returns
<str>.


INT strlen(SPTR str)

Returns the length of str.  (Strings are stored internally as counted
strings, so this routine does not have to scan the string.)


INT ucase(INT char)

Returns <char> in uppercase if <char> is alphabetical, or <char> if it
is not.  The return value is always between 0 and 128.


SPTR wrap(SPTR text, INT margin, [INT indent], [INT start])

Returns a string containing <text> wrapped at <margin>, indenting
lines after the first by <indent> spaces (<indent> defaults to 0).
<text> is assumed to have no newlines or unprintable characters.
Spaces at the beginning of all lines after the first are stripped.
Wrapping occurs at spaces unless a line contains no spaces.  If
<start> is 0, the output will look like:

|------------------- margin -------------------|
... .... ...... ... .. ........ .. .... .. ....
	      .... ... .... .. ... ... .... ..
	      .. .. .. ... ...... .... ... .....
	      .... ....
|-- indent --|

If <start> is non-zero, the first line is shortened by <start>
characters.  For instance, if you want to output a long string of text
in 40-character lines all indented ten spaces from the left margin
(including the first line), you could write:

	echo("	    ", wrap(text, 50, 10, 10));

The final 10 tells wrap() to only allow 40 characters for the first
line, rather than the normal 50.


Windows
-------

These primitives manipulate the window interface:

	INT	       *close(WIN win, INT dir)
	NULL	       *display(WIN win, RMT/NULL rmt)
	NULL		echo([WIN/NULL win], SPTR text, ...)
	??		obj(WIN/RMT thing)
	NULL		pass(WIN/RMT thing, SPTR text)
	SPTR		read([WIN/RMT thing])
	SPTR		reread([WIN/RMT thing])
	INT	       *resize(WIN win, INT row)
	NULL		set_obj(WIN/RMT thing, ?? object)
	NULL		set_termread(WIN win, FPTR/NULL func)
	INT	       *split(WIN win, INT row)
	INT		win_bottom(WIN win)
	INT		win_col(WIN win)
	RMT/NULL	win_rmt(WIN win)
	FPTR/NULL	win_termread(WIN win)
	INT		win_top(WIN win)


INT close(WIN win, INT dir)

Closes the given window.  If <dir> is positive, the window is merged
with the window below it.  If <dir> is 0, the window is merged with
the window above it unless it is the top window, in which case it is
merged with the window below it.  If <dir> is negative, the window is
merged with the window below it.  Tasks waiting for I/O from the
window will be resumed, wit