dintern.doc

Unix下的MUD客户端程序

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.