dist.doc

Unix下的MUD客户端程序

VTC Distribution Documentation
------------------------------

This documentation describes the operation of the VTC code that comes
with the VT distribution.  This code creates a higher-level user
interface for the client than the VT program, and provides useful
utilities for VTC programs.


Files
-----

In addition to looking for its own files in the directories specified
in load_path in main.vtc, the distribution also attempts to load
~/.local.vtc and ~/.settings.vtc (the default save file, defined in
misc.vtc).


Key bindings
------------

The distribution sets up the following key bindings:

ESC [A		Cursor up
ESC [B		Cursor down
ESC [D or ^B	Cursor left
ESC [C or ^F	Cursor right
ESC [H or ^A	Cursor to start of line
ESC [K or ^E	Cursor to end of line
ESC B		Cursor left one word
ESC F		Cursor right one word
^H or DEL (^?)	Delete one character left
^W or ESC DEL	Delete one word left
ESC K		Delete left to beginning of line
^U		Delete entire line
^D		Delete character under cursor
ESC W		Delete word at cursor
^K		Delete to end of buffer
^R		Refresh line
^L		Redraw screen
ESC ESC		Toggle mode (text mode or VTC mode)
^XO		Switch to next window
ESC P		Switch to previous background remote connection
ESC N		Switch to next backround remote connection
^P		Recall previous line in keyboard history
^N		Recall next line in keyboard history
^XP		Add current line to keyboard history and clear, 
		without processing
<Return>	Process current line


These are in bind.vtc and are easy to modify if you wish to use 
different keys.


Keyboard lines
--------------

Keyboard lines are processed in one of three ways.  A line 
beginning with a slash (/) is processed as a command.  A line 
beginning with a backslash (\) is sent to the VTC parser.  Any 
other line is sent to the current remote connection, or discarded 
if there is no current remote connection.


Command substitutions
---------------------

Commands (lines beginning with /), as well as macro and trigger
bodies, are substituted as follows:

	%* or %0		The whole argument line
	%1, %2, ... %9		Arguments 1, 2, ... 9
	%+1, %+2, ... %+9	Arguments 1, 2, ... 9 and the rest,
				separated by spaces (%+2 is the 
				second argument through the last)
	%{<line number>}	The line numbered <line number> from
				the history buffer
	%; or %\		Separates commands.  Text after %;
				or %\ is treated as a new line.
	%%			A single %

%+1 differs from %* in that %+1 inserts all the arguments separated 
by single spaces, while %* inserts the unprocessed argument line, 
which may contain more than one space between each argument.

For each of the argument substitutions (%*, %1..%9, %+1..%+9), 
there is an analagous substitution that produces a VTC-readable 
string constant.  These substitutions are obtained by placing a '"' 
immediately after the '%'.  For instance, the following macro:
	/def echo_hilite=\bold_on();%;/echo %*%;\bold_off();
could be written:
	/def echo_hilite=\bold_on(); output(%"* + "\n"); bold_off();
as the %"* is substituted with a string constant containing the 
argument string passed to the macro.

Note that because the parser may not always be ready for text, macros
that send text to the parser are dangerous.  It is better to use
commands, or to create a macro that invokes a compiled function; see
the internals documentation on add_macro() to do the latter.

The text after %; or %\ is treated as a new line.  This means that if
the line is a command entered at the keyboard (as opposed to being a
macro or trigger body), it will only undergo substitution if it is
also a command.

The /def, /trig, /hilite, /gag, and /repeat commands, because they
have command arguments, are excepted from the substitution rules and
do not undergo substitutions if they are entered from the keyboard.
They are not excepted in the body of a macro.  These exceptions are
case-sensitive, so a command starting with "/Def", for instance, will
undergo substitutions.  You would only use /Def if you wanted to
define a macro and do something else in the same command.

Finally, /:<text> and /"<text> are abbreviations for the /send
command, so that /:<text> or /"<text> is equivalent to :<text> or 
"<text> with % substitutions.

Some examples, with the result(s) each one produces after 
substitutions:

	:%1 %* %; %\ %% %c		:%1 %* %; %\ %% %c
	\a();%\\b();			\a();%\\b();
	/parse a();%\/parse b();	/parse a();
					/parse b();
	/def foo=/bar%;/baz		/def foo=/bar%;/baz
	/Def foo=/bar%;/baz		/def foo=/bar
					/baz
	/Def foo=/bar%%;/baz%;/book	/def foo /bar%;/baz
					/book
	/def a=/def b=c%;/d		/def a=/def=b c%;/d
	/a				/def b=c
					/d
	/def foo=/echo %*		/def foo=/echo %*
	/foo a	b  c			/echo a	 b  c
	/def foo=/echo %+1		/def foo=/echo %+1
	/foo a	b  c			/echo a b c
	:| %{12024}			:| %{12024}
	/:| %{12024}			/:| hugh laughs.

The last example assumes that line #12024 in the history buffer 
is, "hugh laughs."  Note that the /def commands, although some of 
them contained % sequences, were unchanged after substitutions 
(until the macros were run), while the /Def command did undergo 
substitutions before defining the macro, as did the /def inside the
macro in the seventh example.


Wildcard matches
----------------

Most commands in the distribution that accept patterns make use of
wildcard matching patterns.  This type of pattern is not case-
sensitive and has two wildcards: * and ?.  * matches any sequence of
zero or more characters, while ? matches exactly one character.	 For
instance, "d*g" matches "dg", "dog" and "drag", while "d?g" matches
only "dog".  Wildcard match patterns are anchored to the beginning 
and end of lines.


Regexps
-------

A number of commands in the distribution make use of regexps.  VT 
is packaged with a manual page for regexps that provide a precise 
description of them.  What follows is a partial list of the special 
characters used in regexps:

	.	    Matches any character
	*	    Matches previous character 0 or more times
	+	    Matches previous character 1 or more times
	?	    Matches previous character 0 or 1 times
	[abc]	    Matches a, b or c
	[a-tA-T]    Matches a through t in upper or lower case
	[^a-cAB]    Matches anything but a, b, c, A or B
	(r1|...|rn) Matches any one of regexps r1 through rn
	^ at start  Anchors regexp to beginning of line
	$ at end    Anchors regexp to end of line

If you wish to use any of the characters .*+?[](), you should 
escape them with a backslash, or place the characters in non-ambiguous
positions.  For instance, [])] matches ] or ), and [^])] matches
anything but ] or ).  Regexps are case-sensitive.


Commands
--------

You can get a list of command formats by typing /help within the 
client.


/add_line <name> <addr> <port>

Adds a line-based world.  Line-based world support includes triggers
(/trig), hilites (/hilite), gags (/gag), history (/recall), logging
(/log), and display of line numbers (see "obscure features").  <addr>
is the Internet address of the world, and can be in either name format
or numeric format.  See also /list_worlds, /unworld, and /world.


/add_lp <name> <addr> <port> <char> <pwd>

Adds an LP world.  LP worlds are intended for LPmuds and Dikumuds.  LP
worlds display partial lines as they appear, echo the text that you
type, and display prompts in the input window if the server supports a
prompt protocol.  LP worlds support all of the features in line-based
worlds except for hilites, gags, and displayed line numbers.  When you
connect to an LP world with /world, VT automatically logs in by
sending two lines, one containing <char> and one containing <pwd>.


/add_mud <name> <addr> <port> <char> <pwd>

Adds a mud world.  A mud world is a line-based world with the addition
of automatic login.  When you connect to a mud with /world, VT sends
the line "connect <char> <pwd>".


/add_raw <name> <addr> <port>

Adds a raw world.  VT does not process raw world output before
displaying it.  Raw world support includes everything in line-based
support except for hilites, gags, and displayed line numbers.


/beep [<num>]

Beeps <num> times, or one time if <num> is not specified.


/close [1]

Closes the active window (see /split, /resize, and /isize).  "/close"
with no arguments closes the active window into the window above it;
"/close 1" closes it into the window below it.


/dc

Disconnects the current world.


/def <name> = <body>

Defines a new macro <name> that performs <body>.  A macro is a
shortcut for a command or a sequence of commands.  <body> undergoes
percent (%) substitutions as described in "command substitutions"
above.	The macro is invoked as
	/name arg1 arg2 ...
The first nine arguments can be retrieved with %1 through %9; the rest
appear in %+1 through %+9 and %*.

You may omit the '=' character in the /def command, e.g.
	/def foo /echo bar


/echo <text>

Displays text on the screen.  If you want <text> to be treated as a
line from the remote server (checking for triggers, wrapping, display
of line numbers, etc.), see "obscure features".


/edit [+|-e1hgn] [-p<pri>] [-w[<world>]] <name>

Edits the settings for the trigger with the name <name>.  The settings
are:
	-e	Enabled
	+e	Disabled
	-1	Executes only once
	+1	Executes continuously
	-h	Hilite
	-g	Gag
	-n	Normal (neither hilite nor gag)
	-p	Priority level
	-w	World that trigger is specific to

See /trig for an explanation of these features.


/gag [<switches>] <pattern> [=<result>]

Creates a gag trigger.	In the simplest case (/gag <pattern>), creates
a trigger that suppresses all lines matching <pattern>, a wildcard
pattern.  For example, "/gag Claire*" suppresses all lines starting
with "Claire".	It is also possible to execute a command on the match
by specifying <result>.	 For instance, "/gag Huh?* = /echo <!> Error"
will replace lines beginning with "Huh?" with the message "<!> Error".
The switches are explained under /trig.	 Notably, -r makes <pattern> a
regexp rather than a wildcard match, and -n<name> gives the gag a name
for use in listings any by /untrig.

/help

Displays a short list of command formats.


/hilite [<switches>] <pattern> [=<result>]

Creates a hilite trigger.  This is the same as a gag trigger, but
instead of suppressing the text, it is displayed in boldface.  For
instance, "/hilite cool*" hilites all lines beginning with "cool".


/isize <size>

Sets the input window size by moving the divider line of the bottom
window.	 The default is /isize 3.