vtc.doc

Unix下的MUD客户端程序

Usually, that code would be written:

	if (a)
		b;
	else if (c)
		d;
	else if (e)
		f;
	else
		g;

This more elegantly conveys the effect of the code, which is to
evaluate the conditions (<a>, <c> and <e>) until one is true, and
execute either <b>, <d>, <f> or <g> accordingly.

The while statement is a loop statement, and has the following format:

	while (expression) statement

This causes the statement to be executed as long as the expression is
true.  If the expression is false the first time it is evaluated, the
statement is never executed.  The do-while loop:

	do statement while (expression)

also executes a statement as long as an expression is true, but the
statement is always executed at least once, before the expression is
ever evaluated.

Different types of flow control statements can be combined:

	while (input_waiting(rmt)) {
		if (line = read(rmt))
			add_hist(obj(rmt)[1], line);
		else
			abort();
	}

The for statement is a loop statement with the format:

	for (expr1; expr2; expr3) statement

expr1 is evaluated immediately and its value is discarded.  The
interpreter then executes the statement as long as expr2 is true.
expr3 is evaluated after each iteration of statement.  For-loops can
be rewritten as while loops (this is not a perfect isomorphism, since
break and continue statements will not behave quite the same):

	expr1;
	while (expr2) {
		statement;
		expr3;
	}

The logic behind the organization of the for statement is: expr1 is
the initialization expression.	If you are writing a for statement to
count from 1 to 10, using the variable "i" as a counter, then expr1
would be "i = 1".  expr2 is the condition; for our example, we would
use, "i <= 10".	 expr3 is the increment expression.  In this case, it
would be "i++".	 The statement is the body of the loop; if we wanted
to output the value of i on a line each time it counted, we would use
"echo(itoa(i), "\n");" for our statement.  So, we have:

	for (i = 1; i <= 10; i++)
		echo(itoa(i), "\n");

For statements are convenient for separating the information about how
long the loop will run from the action that is taken at each stage of
the loop.

A label can be attached to any statement:

	label : statement

The label is an identifier.  You can jump to a statement using a goto
statement:

	goto label;

Goto statements can confuse the meaning of code and should be avoided
as much as possible.  A goto label must be in the same function or
command as the goto statement that jumps to it.

The break and continue statements can be used within the statement
part of while, do-while and for loops.	They have the forms

	break;

and

	continue;

The break statement terminates the loop.  The continue statement jumps
to the end of the statement part of the loop and continues execution
of the loop.  In a for-loop, this means evaluating the iteration
expression before checking the condition expression.

The return statement can be either:

	return;

or

	return expression;

This instructs the interpreter to exit the current function, returning
the value of expression if one is given.  If the return statement is
used inside a command (rather than a function), it will terminate the
command.


Functions
---------

Functions are blocks of code that are associated with a name, and can
be used run by calling them by name.  The form of a function
definition is:

	func name(parameters) [local vars] compound statement

The word "func" is literal.  The parameter names are a list of
identifiers separated by commas, as are the local variable names.

If a function does nothing but return an expression, there is a short
form:

	func name(parameters) --> expr

Parameter variables refer to the arguments to the function.  It is a
run-time error to call a function with fewer arguments than there are
parameter variables in the function's definition.  All arguments are
passed by value, so a function can reassign to its parameter variables
without affecting the values of any variables whose values were passed
to the function as arguments.	As an example, the following:

	func switch(a, b) [temp] {
		temp = a;
		a = b;
		b = temp;
	}

will perform no useful task, since switch() knows only the values of
the arguments.

It is okay to call a function with more arguments than it has
parameter variables.  A function can use the argc and argv builtins
(see vt.doc) to access its arguments directly.

Local variables are variables whose scope (the area one can use them
in) is restricted to the function.  They are also distinct from any
other variable in the program in each invocation of the function.  A
local variable "i" in one function will not conflict with a local
variable "i" in some other function, and the local variables of a
function that calls itself, or of two functions that call each other,
will not conflict with each other.  This is important for creating
recursive functions, which can call themselves repeatedly.


Pointers and lvalues
--------------------

VTC has several types of pointers.  These can be categorized into two
classes.  Pointers to primitives, remote connections, windows, key
bindings, files, functions, regexps, association types, and property
lists are used by the interpreter to refer to objects, and can only be
manipulated by use of primitives (except for the -> operator in the
case of association types and property lists, q.v.).  For instance,
the primitive split() returns a pointer to the window that it creates,
and other primitives such as win_top() and close() will accept this
pointer as an argument.

Strings and arrays are used for storing data.  A string pointer points
to a character value within a string, and an array pointer points to a
data element within an array.  Both can both be dereferenced by the *
unary operator to yield the value that they point to.

A string constant such as "foobar" is an expression with a string
pointer type.  If we set:

	stringvar = "foobar";

Then stringvar's value will be a string pointer, which can be
visualized like so:

	-------------------------
	| f | o | o | b | a | r |
	-------------------------
	  ^---stringvar

Now *stringvar has the value 'f'.

You can access further elements of foobar using pointer 
arithmetic.  In the above example, (stringvar + 4) is a string 
pointer pointing to the 'b' in "foobar".  If we set:

	stringvar += 4;

Then we can visualize foobar as:

	-------------------------
	| f | o | o | b | a | r |
	-------------------------
		      ^---stringvar

And *stringvar has the value 'b'.  One can access string elements
behind stringvar by subtracting from it; *(stringvar - 2) has the
value 'o', since (stringvar - 2) points to the first 'o' in "foobar".

A third operation on pointers is pointer subtraction.  Suppose we set:

	stringvar2 = stringvar - 2;

Now stringvar points to the 'b' and stringvar2 points to the 'o' two
spaces behind it.  We can find the distance between stringvar and
stringvar2 by subtracting them: (stringvar2 - stringvar) has the value
2.  The - operator can only be used on string pointers that point to
the same string.

Pointer arithmetic has the following operations:

	pointer + integer --> pointer
	pointer - integer --> pointer
	pointer - pointer --> integer

These operations apply to string pointers and array pointers.  An
array pointer acts just like a string pointer, except that array
elements are not restricted to being characters.

Relational and equality operators (<, <=, >=, >, ==, !=) also apply to
pointers that point inside the same string or array.  It is a run-time
error to use <, <=, >=, or > on pointers that point inside different
strings or arrays.  The == and != operators will always return false
if their arguments are pointers from different strings or arrays, or
are of different types.

The [] brackets are used to do array references.  The expression:

	a[b]

is equivalent to:

	*((a) + (b))

That is, in the example above, stringvar[2] would have the value 'r',
since it is the same as *(stringvar + 2).

An lvalue is defined as an object that one can meaningfully find the
address of.  The two types of lvalues are variable names and
dereferenced pointers.	Since 'stringvar' is a variable name, it was
legal to use it on the left-hand side of the '=' operator.  One could
also write:

	*stringvar = 'm'

which changes the 'b' in "foobar" to 'm'.

The & operator can be used to get the address of an lvalue.  This is
usually an array pointer, since variables are treated as elements in
an array.  We could set:

	ptrtostringvar = &stringvar;

Now we could do:

	*ptrtostringvar = "snafu";

And stringvar would now point to the 's' in "snafu".  & can also
return a string pointer; for instance,

	&(*(stringvar + 2))

would be a string pointer pointing to the 'a' in "snafu".  This is
more commonly written:

	&stringvar[2]

It could, of course, also be written as (stringvar + 2).

We can write a swap() function using pointers:

	func swap(a, b) [t] {
		t = *a;
		*a = *b;
		*b = t;
	}

Now if we wanted to switch the values of stringvar and stringvar2, we
would write:

	swap(&stringvar1, &stringvar2);


Strings
-------

Strings are blocks of data containing character values.	 A character
value is an integer data value restricted (usually) to 256 values, of
which 0-127 are the most commonly used.  Character constants are in
this range, and are the most common thing stored in a string.

A string is null-terminated; that is, it has meaningful data values
only up to its first 0 value.  So if we write:

	stringvar = "foobar";
	stringvar[2] = 0;

Then stringvar now points to "fo", and the rest of the contents of the
string are irrecoverable.

The length of a string pointed to by a string pointer is defined as
the number of characters between the pointer and a 0 value, and is
returned by the strlen() primitive.  After the above code has been
executed, strlen(stringvar) is 2, and strlen(stringvar + 1) is 1.

Reading before the beginning or beyond the end of a string yields a 0
value.  This means stringvar[3] and stringvar[-1] have the value 0,
and both strlen(&stringvar[3]) and strlen(&stringvar[-1]) are 0.

Attempting to write (assign) before the beginning of a string is a
run-time error.	 Writing beyond the end of a string is legal, and
causes the string to be lengthened, using spaces to fill in the
intervening values.  The statement:

	stringvar[10] = 'a';

causes stringvar to point to "fo	a".

The + operator can be used to concatenate springs.  Two string
pointers can be added together to return another string.  For
instance, one could write:

	a = "foo";
	b = "bar";
	c = a + b;

and c would point to a string "foobar";.

It is important to distinguish between separate copies of a
string.	 The strdup() primitive returns a copy of a string.  If we
write:

	a = "foo"; b = a + 1; *b = 'b'; a++;

then *a is 'b'.	 We could also write:

	a = "foo"; b = strdup(a + 1); *b = 'b'; a++;

and *a is still 'o', since it was a copy of a that was modified, not
the original.

The += operator can be used with strings.  If we write:

	stringvar += stringexpr;

then stringexpr is concatenated onto the contents of stringvar.	 This
is equivalent to:

	stringvar = stringvar + (stringexpr);

Note that this is not quite the same as

	strcat(stringvar, stringexpr);

because the += operator produces a new string, while strcat() acts on
the old string.  If we write:

	a = "foo"; b = a + 4; strcat(a, "bar");

then b points to the "ar" at the end of "foobar".  If we write:

	a = "foo"; b = a + 4; a += "bar";

then *b is 0, since it's beyond the end of "foo".  a no longer points
within the same string as b.


Property lists
--------------

Property lists vaguely mirror structures in C.  The idea is, you
define an association type, use it to create a property list, and then
you can refer to elements in the property list by name.  For instance,
suppose we wanted to create a data type called "pair", with a "car"
and a "cdr" element.  We would write:

	Tpair = new_assoc();
	// ...
	some_pair = alloc(2, Tpair);
	some_pair->car = ...;
	some_pair->cdr = ...;

The alloc(number, assoc) call creates a property list.  A plist is
composed of an array and an association type.  The association type is
not terribly important; it contains the size of the array ('car' in
this plist might point to element 0 in the array, whereas 'name' might
also point to element 0 in another plist of another association type)
and defines the order of elements in the array, which is useful when
we want to get at the array directly using the base() primitive.  See
vt.doc for details.


Other data types
----------------

The other data types are generally related to specific client
features, and are described in vt.doc.  See the sections in that file.
vt.doc also contains documentation on primitives.


Operators
---------

This is a list of the ways binary operators can be used in VTC,
excluding the assignment operators.  "ptr" refers to an array pointer
or string pointer.  With the exception of the + operator, operations
involving two pointer types require that the pointers by of the same
type, and that they point inside the same array or string.  The +
operator can take two string pointers that point inside different
strings, but cannot operate on two array pointers.  "int" refers to an
integer, and "bool" refers to a boolean value.  As a result, a boolean
value is either 0 or 1; as an argument, it can be any data type.

int  *	int	-->	int	(integer multiplication)
int  /	int	-->	int	(integer division)
int  %	int	-->	int	(integer modulus)
int  +	int	-->	int	(integer addition)
ptr  +	int	-->	ptr	(pointer addition)
ptr  +	ptr	-->	ptr	(string concatenation)
int  -	int	-->	int	(integer subtraction)
ptr  -	int	-->	ptr	(pointer subtraction)
ptr  -	ptr	-->	int	(distance between pointers)
int  << int	-->	int	(bitwise left shift)
int  >> int	-->	int	(bitwise right shift)
int  <	int	-->	bool	(integer comparison)
ptr  <	ptr	-->	bool	(pointer comparison)
(<=, >=, >, ==, and != act in the same way as <)
int  &	int	-->	int	(bitwise and)
int  ^	int	-->	int	(bitwise xor)
int  |	int	-->	int	(bitwise or)
bool && bool	-->	bool	(logical and)
bool ^^ bool	-->	bool	(logical xor)
bool || bool	-->	bool	(logical or)

The == and != operators can also be used to test for equality of
pointers other than string and array pointers, and of course NULL ==
NULL.  Expressions of two different data types are always unequal.