vt.doc

Unix下的MUD客户端程序

VT Program Documentation


Description
-----------

Vaportalk (VT) is an Internet client program.  Its main features are
an I/O scheduler for communication with remote hosts, a minimal
windowing system, and a C-like language called VTC.

VT and its documentation were written by Greg Hudson, who can be
reached via Internet email at [e-mail].

This file documents the VT program.  It makes reference to the
distribution VTC code from time to time, but does not describe it
fully.  Most users of VT will initially be more concerned with the
distribution documentation in dist.doc.


Startup
-------

VT must read a startup file to initialize key bindings and other
parameters.  The startup file is a VTC file

	1. If VT is invoked with an argument, it loads that file.
	2. If the environment variable VTSTART exists, VT loads that
		file.
	3. VT searches for the following files, in order:
		~/main.vtc
		~/vt/dist/main.vtc
		~/vt/main.vtc
		/usr/local/lib/vt/main.vtc

Once one file is loaded, VT stops searching for others.  If VT is
invoked with an argument or the VTSTART environment variable exists,
and VT cannot load either of those files, then it will print a warning
message.  VT will exit if it cannot find any startup file.


Environment variables
---------------------

Apart from the VTSTART environment variable, VT looks in the VTBOLDON
and VTBOLDOFF variables for the names of the terminal capabilities to
use for turning boldface text on or off.  These default to "md" and
"me", which are the usual boldface capabilities.  (A common
alternative pair is "so" and "se", which turn inverse text on and
off.)


The Compiler
------------

VTC is a C-like language.  It does not feature strong typing, type
definitions, or a switch statement.  It does feature pointers and
pointer arithmetic, structures in modified form, and dynamic
allocation of arrays and strings.


VTC Syntax
----------

VTC tokens are of five types: string constants, integer constants,
operators, reserved words, and identifiers.  Reserved words and
identifiers are case-sensitive.

The VTC compiler ignores spaces and tabs, except as they separate
tokens.	 It also ignores text between C comment delimiters (/* and
*/), and the rest of a line after a pair of slashes (//).

VT character and string literals are similar to old-style C character
and string literals.  A character literal is a single character inside
single quotes ('c'), while a string literal is a sequence of
characters inside double quotes ("This is a string literal").  To
specify an unprintable or special character in a character or string
literal, use one of the following codes:

	\n	Newline
	\t	Tab
	\v	Vertical tab
	\b	Backspace
	\r	Carriage return
	\f	Form feed
	\\	Backspace
	\'	Single quote
	\"	Double quote

You do not need to escape single quotes, and you only need to escape
double quotes within string literals.  You may also follow a backslash
with up to three octal digits specifying the ASCII code for the
character.  The parser will ignore a newline preceded by a backslash,
allowing the string literal to continue on the next line.

An integer constant is a series of digits with no suffix.  To specify
an integer in octal, begin the series of digits with 0.  To specify an
integer in hexidecimal, prefix the series of digits with 0x or 0X.

The compiler reserves the following words:

	do while if else for func goto break continue return

The compiler also reserves the names of builtin objects and named
constants (q.v.).  The compiler does not reserve the names of VTC or
primitive functions.  You may use those names as variables, although
this may make your code confusing to read.

An identifier is a sequence of letters, numbers, and underscores,
beginning with a letter or an underscore.  Use identifiers to refer to
variable and function names.  Identifiers are significant to 32
characters and are case-sensitive.

A directive to the VTC parser is either a function definition or a
command.  These have the formats:

	definition:	func ident (params) [local vars] compound
			func ident (params) --> expr ;
	command:	[local vars] statements

[local vars] may be omitted in either case, but the square brackets
are literal.  Command directives are executed immediately, while
function definitions are saved so that you can call the functions
later.  "--> expr ;" is a shorthand for "{ return expr ; }" in a
function definition.

Parameters and local vars are sequences of zero or more identifiers
separated by commas ("foo, bar, baz").  Parameters can also be two
such sequences separated by a slash ("foo, bar / baz, quux"), in which
case the identifiers in the second sequence denote optional
parameters.  Calling a function with fewer arguments than it has
non-optional parameters results in a runtime error, although calling
a function with more arguments than it has parameters is legal.

Some examples:

	func echoln(line) { echo(line, "\n"); } /* Echo a line */
	[i] for (i = 0; i < 5; i++) echoln(itoa(i)); // Count to 5

A statement can be one of the following:

	statement:	compound
			expression;
			if (expression) statement
			if (expression) statement else statement
			while (expression) statement
			do statement while (expression)
			for (expression; expression; expression)
				statement
			label: statement
			goto label;
			break;
			continue;
			return expression;

You can omit the expressions in the expression statement and the
return statement, as well as any of the expressions in the for
statement.  ";", "for (;;);", and "return;" are all valid statements.

A compound statement, as in C, is zero or more statements contained in
{ and }.

All the flow control statements are identical their counterparts in C.

Expressions are as follows:

	lvalue:		* expression
			identifier
			expression[expression]
			expression->identifier
			(lvalue)

	expression:	lvalue
			constant
			builtin-object
			. identifier
			identifer(args)
			(lvalue)(args)
			(expression)
			prefix-operator expression
			expression postfix-operator
			expression binop expression
			lvalue assign-op expression
			expression ? expression : expression
			expression ? : expression
			! expression
			~ expression
			- expression
			+ expression
			& lvalue
			++ lvalue
			-- lvalue
			lvalue ++
			lvalue --

". identifer" indicates a pointer to the function named by the
identifier.  In C, you might write:

	extern int bar();
	int (*foo)() = bar;
	(*foo)(args); /* or foo(args); for most compilers */

In VTC you would write:

	foo = .bar;
	(*foo)(args);

In most C compilers, you can write "foo(args)" instead of
"(*foo)(args)".  VTC does not permit this.

Expressions are mostly the same in VTC as in C.	 The logical
operators, as in C, only evaluate their right-hand arguments if their
left-hand arguments are not sufficient to determine their truth
values.  The operators are, in order of precedence from highest to
lowest:

	unary:		.
	unary:		! ~ ++ -- + - * &
	binary:		* / %
	binary:		+ -
	binary:		<< >>
	binary:		< <= > >=
	binary:		== !=
	binary:		&
	binary:		^
	binary:		|
	binary:		&&
	binary:		||
	binary:		?:
	assignment:	= += -= *= /= %= &= != <<= >>= ?:=
	binary:		,

The unary, assignment, and conditional operators associate right to
left.  All other operators associate left to right.  The interpreter
evaluates arguments and binary expressions left to right.

'args' refers to zero or more expressions separated by commas.	The
comma binary operator does not apply to expressions in an argument
list.  Outside of an argument list, a list of expressions separated by
commas takes the value of the last expression in the list, as in C.

As noted in the expression syntax, you can omit the middle argument of
a conditional expression, in which case it evaluates to the value of
the left argument if the left argument is true, and to the value of
the right argument if the left argument is false.  There is also a ?:=
operator; '(a ?:= b)' is equivalent to '((a) = (a) ? : (b))'.

The + operator can take two string pointer arguments, producing a
concatenated string.

The form of input to the parser is slightly restricted.	 The parser
must know when the user has completed a parser directive (command or
function definition) because of the way it accepts input.  The parser
assumes that this is true at the end of a line unless one of the
following conditions holds:

	(1) You escape the newline with a backslash.
	(2) You have entered more { tokens than } tokens (you are in
	    the middle of a compound statement).
	(3) You have entered a func token but not a --> token or a {
	    token (you are declaring a function and have not begun the
	    function body).
	(4) You have entered a "/*" but no matching "*/".

The following is a syntactically legal sequence of input:

	func foo()
	{
		bar();
	}
	{
		foo(); bar();
	}
	foo(); bar();
	if (foo()) \
		bar();

Note that a line like:

	foo(); bar();

is somewhat different than two separate lines:

	foo();
	bar();

The intepreter treats the first as a single task and the second as two
tasks.  In the first case, if foo() aborts, bar() will not be
executed, and if foo() is suspended due to an input request or sleep()
primitive, bar() will wait until foo() exits before running.  In the
second case, bar(); will run right after foo() terminates or is
suspended.

The parser will become confused if a directive contains unbalanced
left and right brace tokens.  A sufficiently long series of right
braces will rectify this situation.


Fatal Errors
------------

VT will abort a task whenever the task passes arguments of the wrong
type to a primitive, attempts to assign to a negative array or string
element, passes too few arguments to a VTC function, calls or makes a
pointer to an undefined function, or makes an illegal assignment to a
builtin variable.

See the section on "non-fatal errors" below for information on how VT
deals with other error conditions.


Data
----

VT has eleven data types, each associated with a named constant:

	Type		Description
	----		-----------
	T_INT		Integer
	T_PPTR		Primitive pointer
	T_BPTR		Builtin object pointer
	T_RMT		Remote pointer
	T_WIN		Window pointer
	T_KEY		Key binding pointer
	T_FILE		File pointer
	T_SPTR		String pointer
	T_APTR		Array (or variable) pointer
	T_FPTR		Function pointer
	T_REG		Regexp pointer
	T_ASSOC		Association type
	T_PLIST		Property list pointer
	T_NULL		No value

Use NULL to refer to the data object with type T_NULL.  0 and NULL are
false.  Every other data value is true.


Variables
---------

There are three types of variables: parameters, local variables, and
globals variables.  You declare parameters in a function declaration,
and local variables in the square brackets at the beginning of a
function declaration or command.

You can store any type of data in a variable.  You can take its
address with the & operator.  The address of a variable is an object
of type T_APTR.  VT will reset any data value holding the address of a
parameter or local variable when those variables go out of scope.

To refer to a global variable, simply use its name in a variable
context, assuming you are not in the scope of a local or parameter
variable with the same name.  If the global variable does not already
exist, VT will create it and initialize it to NULL.


Arrays
------

Arrays are sequences of variables.  They are of three classes: arrays
returned by the alloc() primitive, local and parameter variable
arrays, and the global variable array.  The first and third type of
array will stretch if the user attempts to assign values to an array
element past the current amount of allocated space, so those arrays
can be thought of as an infinite storage space with a fixed beginning.
Uninitialized array elements and an elements before the beginning of
an array have the value NULL.  Assigning to an element before the
beginning of an array results in a runtime error.

You cannot explicitly free an array.  VT frees a function's local and
parameter arrays when the function exits.  VT frees arrays returned by
alloc() when there is nothing pointing to them.  VT will not
automatically free a self-referential array or group of arrays if
nothing external is pointing to them, but you can free all such groups
of arrays by calling the garbage() primitive at any time.

alloc() takes a size argument.  This number will not affect program
correctness, since the array will stretch if necessary.  It is only
for reducing wasted space and unnecessary resizing.


Property lists and association types
------------------------------------

Property lists vaguely mirror structures in C.	Here is an example
using of using a property list:

	Tmytype = new_assoc();
	p = alloc(2, Tmytype);
	p->name = "Druid";
	p->num = 673;
	echo("p->name: ", p->name, ", p->num: ", itoa(p->num), "\n");

A property list consists of an array and an association type.  To
create a new association type, use the new_assoc() primitive.  All
plists with a given association type will have the same associations
between element names and array offsets.  Each time you use a new
element name with a plist of a given association type, it assigns an
array offset to it, starting at 0.

To retrieve an element of a plist, you can use the lookup() primitive.
"lookup(plist, str)" returns a pointer to the array element in
<plist>'s array containing the element <str>.  If <str> is a simple
string constant, you can use "plist->str" as an abbreviation for
abbreviation for "*lookup(plist, str)".

You can retrieve the array part of a plist using the base() primitive.