dintern.doc

Unix下的MUD客户端程序

NULL edit_trig(SPTR name, INT pri, INT enabled, INT rearm, INT style,
	       PLIST/NULL/0 world)

Edits a trigger's characteristics.  If an argument is NULL, that
characteristic is unchanged.  To set the world to NULL, pass 0 as
<world>.


INT check_triggers(SPTR text)

Checks <text> against the triggers.  Returns the style that the
triggers indicate the text should be treated in.


util.vtc
--------

Data type: List
	A distribution list is an array whose first element (*l) is
	the number of items in the list and whose remaining elements
	(l[1] .. l[*l]) are the list items.


NULL nothing()

Does nothing.  Sometimes it is helpful to be able to pass .nothing to
a function that expects a function pointer as an argument.


NULL fill_array(APTR array, ...)

Copies the arguments after the first one into the location specified
by <array>.


APTR adup(INT size, APTR array)

Returns a duplicate copy of the first <size> elements of <array>.


INT isdigit(INT c)
INT isalpha(INT c)
INT isprint(INT c)
INT isupper(INT c)
INT islower(INT c)

Predicates returning true of 'c' is in the named category and false if
not.


NULL echoln(...)

Calls echo() with its arguments, plus an additional "\n" at the end.


SPTR field(SPTR str, INT len)

Returns a copy of <str> which is <len> characters long.  This is
achieved by either truncating <str> or adding spaces to it.


INT mod(INT a, INT b)

Returns the positive <a> modulo <b>, assuming <b> is positive.  (a %
b) is negative if a is negative.


INT min(INT a, INT b)
INT max(INT a, INT b)

Returns the minimum or maximum of <a> and <b>.


SPTR skipspaces(SPTR s)

Returns a pointer to the first non-space character after s.


NULL fcloseall()

Closes all open files.


NULL ptable(ASSOC a, ...)

Creates a plist of type <a> and fills its array with the remaining
arguments.  Using this requires you to know the order of the
associations in <a>.  You can force the order with something like:
	a = new_assoc();
	&a->foo; &a->bar; &a->baz;


NULL new_list(...)

Returns a new list containing the arguments.


NULL add_list(APTR list, ?? data, [INT pos])

Inserts <data> into <list> at <pos>.  If <pos> is not specified,
<data> is inserted at the end of the list.


NULL del_list(APTR list, INT pos)

Deletes the element at <pos> from <list>.


INT/NULL list_find_eq(APTR list, ?? elem)
INT/NULL list_find_strcmp(APTR list, ?? elem)
INT/NULL list_find_stricmp(APTR list, ?? elem)
INT/NULL list_find_gen(APTR list, ?? elem, FPTR/PPTR compare_func)

Searches for <elem> in a list, using the == operator, strcmp(),
stricmp(), or an arbitrary function to compare the elements,
respectively.  Returns the position of the element in the list if it
is found, or NULL if it is not.


SPTR ctrl(SPTR str)

Returns a copy of <str> with two-character sequences starting with "^"
substituted with the corresponding control character.  The sequence
"^^" will be substituted with a single "^".


SPTR dispstr(SPTR str)

Returns a copy of <str> with nonprintables substituted with an
appropriate sequence beginning with "^".


SPTR reverse(SPTR str)

Returns a reversed copy of <str>.


SPTR rotn(SPTR str, INT n)

Returns a copy of <str> with all letters in <str> rotated forward in
the alphabet by <n>.


APTR explode(SPTR str, SPTR separator)
APTR explo(SPTR str, SPTR separator)

Returns a list of the substrings of <str> exploded with <separator>.
explode() will put empty strings in the list if there are adjacent
occurrances of <separator>; explo() will not.


SPTR stringconst(SPTR str)

Returns copy of <str> as a VTC-readable string constant.  This
function does not translate nonprintables except for newlines.


SPTR arglist(...)

Returns a VTC-readable argument list, without '(' and ')' delimiters,
containing the arguments, which can be integers, strings, or function
pointers.  For instance:

	arglist("foo", 6, .somefunc)

returns "\"foo\", 6, .somefunc".


INT get_flag(SPTR s)

Returns 0 if <s> is "off" or "0", "on" if <s> is "on" or "1", and 2 if
<s> is anything else.


SPTR bprintf(SPTR fmt, ...)
NULL sprintf(SPTR s, SPTR fmt, ...)
NULL printf([WIN w], SPTR fmt, ...)
NULL sendf([RMT r], SPTR fmt, ...)
NULL fprintf(FILE f, SPTR fmt, ...)

Formats the output in <fmt> using the remaining arguments.  bprintf()
returns the formatted string, sprintf() copies it into a string,
printf() outputs it to a window using output(), sendf() sends it to a
remote using dispatch(), and fprintf() writes it to a file.

The substitutions in <fmt> are:

	%%	Literal %
	%s	String from arguments
	%d	Integer from arguments
	%c	Character from arguments

The %s and %d substitutions accept a length between the "%" and the
"s" or "d", which determines the field width to which the string or
integer will be truncated or extended.


SPTR getopt(SPTR str, SPTR switches, APTR args)

Parses option switches on a line.  <str> is a string containing
switches.  The return value will be a pointer into the same string at
the end of the switches.  <switches> is a string containing the
allowable switch characters.  Lowercase characters are flag switches;
uppercase characters are argument switches.  <args> is an array
pointer into which the switch values will be placed.

getopt() scans through <str> as long as it sees substrings beginning
with "-" or "+" separated by spaces.  For instance, if <str> contains
"+abcd -nfoobar baz", then getopt() will parse the "+abcd" and
"-nfoobar" and return a pointer to "baz".  There is one exception to
this rule: getopt() will skip spaces after it sees an argument switch,
so if "-n" was an argument switch in the above example, the string
"+abcd -n foobar baz" would be parsed in the same way.

Within the switch strings, getopt() looks for each character in
<switches>, ignoring case.  If the character is a flags switch,
getopt() sets the corresponding entry in <args> to 0 if the flag is in
a switch string beginning with "+", 1 if the flag is lowercase and in
a switch string beginning with "-", and 2 if the flag is not lowercase
and in a switch string beginning with "-".  If the character is an
argument switch, getopt() copies from the next nonspace character to
the next space after the next nonspace character into the
corresponding entry in <args>.

Examples:

	getopt("-g1 +e -nfoo rest", "g1feN", args = alloc(5));
	args is { 1, 1, NULL, 0, "foo" }

	getopt("-A +bn foo rest", "abcdN", args = alloc(5));
	args is { 2, 0, NULL, NULL, "foo" }

In both cases, getopt() returns "rest".


window.vtc
----------

window.vtc defines redraw_hook() and disconnect_hook(), which VT
executes on an automatic screen redraw or any remote disconnection.


Hook: display_hook
	These functions are called as (*f)(win, rmt, oldrmt) at the
	end of each call to std_display().


Data type: Window object (Twin)
	win->status	Status line
	win->pstate	Pager state (PG_ON, PG_OFF, PG_PAUSED)
	win->pcount	Pager counter (lines since last pause)
	win->buffer	Buffer for when pager is paused


Globals:
	default_pager_state
		When a window is newly created, its pager state is
		initialized to the value of this global.


Commands:
	/close
	/isize
	/more
	/resize
	/split


WIN/NULL std_split(WIN win, INT row)

Splits <win> and <row> and initializes the new window.  Returns NULL
if <win> could not be split.


NULL init_win(WIN win)

Initializes the window object for <win>.


NULL add_status(WIN win, SPTR msg, [INT left])

Adds <msg> to <win>'s status line.  If <left> is given and positive,
the message is added to the left side of the status line; otherwise,
it is added to the right side.


NULL/-1 change_status(WIN win, SPTR msg, SPTR new)

Changes <msg> to <new> in <win>'s status line.  If <msg> is not found,
change_status() returns -1.  If <msg> or <new> is the empty string,
change_status() calls add_status() or del_status() appropriately, or
does nothing if both are empty.


NULL/-1 std_display(WIN win, RMT rmt, [INT suppress])

This is the distribution's interface to display().  It updates the
status line of <win>, and displays a message unless <suppress> is
given.  It also executes the hook display_hook.


NULL output(SPTR text, [INT style], [WIN win])

Outputs <text>.  The primary difference between the functions of
output() and echo() is that the former goes through the pager system.
output() also displays <text> in boldface if <style> is S_HILITE.


NULL reset_pager([WIN win])

Resets the line count in the pager, and unpauses it if it is paused.
Equivalent to pressing <tab> with the distribution bindings.


NULL discard_pager_buffer([WIN win])

Resets the line count in the papger and unpauses it, discarding any
text which has accumulated while the window was paused.


NULL perror(SPTR s)

Displays the current error message, prefixed with <s>.


world.vtc
---------

Data type: World type (Twtype)
	wtype->name	"Raw", "Line", "Mud" in dist
	wtype->init	Function to initialize and possibly log in
	wtype->netread	Function to process incoming remote lines
	wtype->save	Function to save a world
	wtype->list	Function to list world (one-line format)
	wtype->print	Function to print world (multi-line format)
	wtype->outbound	Function to process lines to send to remote
	wtype->add	Function to add a world
	<other fields as functions are added to various types>


Function interfaces for world type functions:
	(*wtype->init)(PLIST world, RMT rmt, INT login)
	(*wtype->netread)(SPTR line) [cur_rmt is the remote]
	(*wtype->save)(PLIST world, FILE fp)
	(*wtype->list)(PLIST world)
	(*wtype->print)(PLIST world)
	(*wtype->outbound)(RMT rmt, SPTR line)
	(*wtype->add)(SPTR name, SPTR addr, INT port, [maybe others])


Data type: World (Tworld)
	world->type
	world->name
	world->addr	Can be hostname or IPs
	world->port	An integer


Commands:
	/list_worlds
	/unworld


PLIST new_world(PLIST type, SPTR name, SPTR addr, INT port)

Returns a new world.  It may be necessary to assign more fields to the
Resulting World Than those assigned by new_world().


NULL add_world(PLIST world)

Inserts <world> in the worlds tree.


PLIST/NULL find_world(SPTR name)
PLIST Find_world(SPTR name)

Finds the world <name>.  find_world() will return NULL if it cannot
find the world; Find_world() will display an error message and abort.