Distribution Internals
----------------------

This file documents some useful functions in the distribution VTC
code.  It does not document functions and globals that are not
intended for outside use, or for functions which are essentially
command handlers.


avl.vtc
-------

Data type: Tree (Ttree)
	A tree is a data structure for associating keys with values.
	Insertions, deletions, and searches are performed in O(ln n)
	time.  Because the tree is an AVL tree, there is no problem
	with inserting pre-sorted data.

	tree->cfunc	Comparison function
	tree->root	Root node


PLIST make_tree(FPTR/PPTR compare_func)

This returns a new tree, using <compare_func> to compare keys.
<compare_func> is expected to act like strcmp(), that is, returning
less than zero, zero, or greater than zero depending on the ordering
of the two arguments.


NULL insert_tree(PLIST tree, ?? key, ?? data)

Inserts <data> in <tree>, associated with <key>.  If <key> is already
present in the tree, the data associated with it will be replaced.
<data> should not be NULL.


?? find_tree(PLIST tree, ?? key)

Searches for <key> in <tree> and returns the associated data if it is
found.  If <key> is not found, find_tree() returns NULL.


NULL/1 delete_tree(PLIST tree, ?? key)

Deletes the data value associated with <key> in <tree>.  If
delete_tree() is successful, it returns true (1); otherwise, it
returns false (NULL).


NULL traverse_tree(PLIST tree, FPTR/PPTR map_func, [...])

Applies <map_func> to each element of <tree>.  Any arguments beyond
the second passed to traverse_tree() will also be passed after the
tree element to <map_func>.


bind.vtc
--------

It's worth noting that the newline key is bound to accept(), so
anything you want to have done every time you press return can go in
there.  For instance, you might put a call to reset_pager() inside
accept().


Commands:
	/list_keys


command.vtc
-----------

Data type: Command (Tcommand)
		command->name
		command->args	Number of args or -1
		command->fptr	Function to run when invoked
		command->fmt	For /help


Commands:
	/def
	/help
	/list_defs
	/undef


?? efind(FPTR/PPTR fptr, SPTR thing, SPTR s)

efind() calls (*fptr)(s) and returns the result, if it is true.  If
the result is false, indicating a failure to find <s>, efind()
displays an error message and aborts the current process.  efind() is
used for building find functions that can be relied on to return
successfully or not at all.  For instance:
	func Find_world(s) { efind(.find_world, "world", s); }


NULL add_cmd(SPTR name, INT args, FPTR/PPTR fptr, SPTR fmt)

Adds a new command, named by <name>, taking <args> args.  If <args> is
negative, <fptr> is called with one string containing the entire
argument line.  If <args> is nonnegative, <fptr> is called with one
string for each argument on the argument line.

The <fmt> shows up in /help.  To make a command that does not show up
on the /help list, use add_macro() with a function macro body.


PLIST/NULL find_cmd(SPTR name)
PLIST Find_cmd(SPTR name)

Returns the command with the name <name>.  find_cmd() will return NULL
if the command is not found; Find_cmd() will display an error message
and abort.


NULL add_macro(SPTR name, SPTR/FPTR cmd)

Adds a new macro.  When the macro is invoked, if <cmd> is a string
pointer, it will be evaluated according to the rules in dist.doc.  If
<cmd> is a function pointer, it will be called as (*cmd)(line, args),
where <line> is the unprocessed argument string and <args> is an array
with args[0] == line and args[1..n] are the space-separated arguments
in the argument string.


SPTR/FPTR/NULL find_macro(SPTR name)
SPTR/FPTR Find_macro(SPTR name)

Returns the command string of the macro with the name <name>.
find_macro() will return NULL if the macro is not found; Find_cmd()
will display an error mesage and abort.


NULL process_cmdline(SPTR line, [SPTR full, APTR args])

Processes a line <line> according to the rules in dist.doc.  If the
line is a macro or trigger body, <full> should be the unprocessed
argument string and <args> should be a table of arguments for
substitution (%0 --> args[0], etc.)


hist.vtc
--------

Data type: History line (Tline)
	line->text	(*text) is style, (text + 1) is line
	line->world


Globals:
	lineno		Line number of next line to go in history


Commands:
	/recall

NULL add_hist(SPTR line, [INT style, ?? PLIST world])

Adds a line to the history.  <style> defaults to S_NORM and <world>
defaults to the current world.


SPTR/NULL get_histline(INT num)

Gets the line numbered <num> in the history, or NULL if it isn't
stored in the history.


NULL recall(INT num, SPTR pattern, INT all, INT gag, INT hilite,
	    INT names, INT linenos, PLIST/NULL world)

Recalls <num> lines matching <pattern>.  <all>, <gag>, <hilite>,
<names>, and <linenos> are flags corresponding to the /recall options
-a, -g, -h, -n, and -l.  If <world> is NULL, then the current world is
used (unless <all> is true).


NULL histdump(INT start, INT end)

This function displays an interval of lines.  The display style
corresponds to /recall -ahnl.


hook.vtc
--------

A "hook" is a list of function pointers to be called when a particular
event occurs.  The arguments passed to the functions depends on the
particular hook.


APTR make_hook(...)

Creates a new hook.  Any arguments are included in the hook.


NULL add_to_hook(APTR hook, FPTR/PPTR fptr)

Adds a function to a hook, so that it will be run whenever the hook is
executed.


NULL del_from_hook(APTR hook, FPTR/PPTR fptr)

Removes a function from a hook.


NULL exec_hook(APTR hook, ...)

Calls each function in <hook> with the remaining arguments.


line.vtc
--------

Commands:
	/add_line


NULL add_line(SPTR name, SPTR addr, INT port)

Adds a line-based world to the worlds tree.


main.vtc
--------

Commands:
	/load


NULL load_cmd(SPTR fname) 

Loads in the file <fname> as if it were a list of commands typed by
the user.  Lines beginning with '#' are treated as comments and
ignored.


misc.vtc
--------

Hook: save_hook
	Each function in save_hook is called as (*f)(fp) when the
	/save command is given.


Commands:
	/beep
	/echo
	/parse
	/path
	/quit
	/receive
	/save
	/sh
	/shw
	/version


NULL save_one(FPTR funcptr, SPTR fname)

Attempts to open a file <fname> for writing.  If successful, calls
(*funcptr)(fp) and closes the file.  <funcptr> is usually one of
.save_worlds, .save_macros, or .save_trigs, or a similar function.


mud.vtc
-------

Commands:
	/add_line


NULL add_mud(SPTR name, SPTR addr, INT port, SPTR char, SPTR pwd)

Adds a mud world to the worlds tree.


quote.vtc
---------

Commands:
	/quote
	/repeat


raw.vtc
-------

Commands:
	/add_raw


NULL add_raw(SPTR name, SPTR addr, INT port)

Adds a raw world to the worlds tree.


remote.vtc
----------

Remote objects under the distribution code are always worlds.  See
world.vtc.


Commands:
	/dc
	/log
	/world
	/wrapspace


PLIST/NULL cur_world()

Returns the current remote's world, or NULL if there is no current
remote.


NULL dispatch(SPTR line, [RMT rmt])

Calls the remote's outbound function on <line>.  This is the preferred
way of sending a line to a remote.


NULL receive(SPTR line)

Acts as if <line> were received by cur_rmt.  Is equivalent to
pass(line, cur_rmt).


RMT/NULL world(PLIST world, [INT login, WIN win])

Attempts to open a connection to <world>.  If successful, initializes
the world and displays it in <win>.  <login> should be 1 for world()
to intruct the initialization function to automatically log in.


resident.vtc
------------

Globals:
	mailcheck_interval	Seconds between mail checks


trig.vtc
--------

Data type: Trigger (Ttrig)
	trig->name	Possibly an empty string
	trig->pattern	Pattern string
	trig->reg	Compiled regexp, for regexp triggers only
	trig->cmd	String or function pointer
	trig->pri	Trigger priority
	trig->world	NULL if not restricted to a world
	trig->enabled	Trigger does not function if 0
	trig->rearm	If 0, trigger turns off after hit
	trig->style	S_NORM, S_GAG, S_NOHISTGAG, S_HILITE


Commands:
	/edit
	/gag
	/hilite
	/list_gags
	/list_hilites
	/list_norms
	/list_trigs
	/trig
	/untrig


NULL add_trig(SPTR name, SPTR pattern, SPTR/FPTR cmd, INT pri,
	      PLIST/NULL world, INT enabled, INT rearm, INT style,
	      INT isreg)

Adds a new trigger.  <enabled>, <rearm>, and <isreg> are flags
corresponding to the -e, +1, and -r options of /trig.  <style> is
S_NORM, S_GAG, S_NOHISTGAG, or S_HILITE, where the latter three
correspond to the -g, -G, and -h options of /trig.  The <name>, <pri>,
and <world> arguments correspond to the -n, -p, and -w options of
/trig.


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.