vtc.doc

Unix下的MUD客户端程序

VTC Language Description


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

This file is intended mainly as a description of the VTC extension
language for users not familiar with C.	 The file vt.doc contains a
fairly complete description of VTC for those who already know C.
Learning VTC might help to learn some of the basics of C, but readers
should be aware that VTC is a very simplified and less restrictive
language.

This file assumes that the user knows how to enter commands to the VTC
interpreter.  Read vt.doc for instructions on basic operations in the
client.  vt.doc also contains more in-depth descriptions of some VTC
features.


VTC SYNTAX

Constants
---------

One of the basic building blocks of VTC is constants.  VTC has three
types of constants: integer constants, character constants, string
constants, and named constants.

Integer constants can be specified in three ways: in decimal, in
hexadecimal, or in octal.  A decimal integer constant is just a series
of decimal digits not beginning with 0, e.g. 12, 273, or 65.  An octal
integer constant is a series of octal digits beginning with 0.	For
instance, 0100 is the same as the decimal integer constant 64.	A
hexadecimal constant is a series of hexadecimal digits beginning with
0x or 0X.  For instance, 0xA00 is the same as the decimal constant
2560.  The alphabetical hexadecimal digits can be either uppercase or
lowercase, so the previous example could have been written 0xa00.  The
following are all valid integer constants:

	26 040 0x7b4 14

Most integer constants are entered in decimal.	Once the compiler has
read an integer constant, it does not remember what form it is in; the
integer constants 0100 and 64 act exactly the same.

Character constants are integer constants written in ASCII form.
Character constants are written as single quotes surrounding an ASCII
character.  For instance, 'a' and 'd' specify the ASCII codes for a
and d.  The backslash (\) is treated specially.  The following
backslash codes can be used as character constants:

	'\n'	Newline (line feed)
	'\t'	Tab
	'\b'	Backspace
	'\v'	Vertical tab
	'\r'	Carriage return
	'\f'	Form feed
	'\\'	Literal backslash (\)
	'\''	'
	'\"'	"

The ' and " characters do not need to be escaped with a backslash in
character constants, although the " character needs to be escaped
inside a string constant (q.v.).  A sequence like '\(' which is not
defined above is not translated, and is thus illegal as a character
constant because it is two separate characters.

You can specify an ASCII value directly by using \ followed by up to
three octal digits.  For instance, '\33' codes for the ASCII escape
character.

String constants are a sequence of characters inside double quotes
(").  For instance, "foo", "\33[H", or "Done.\n".  A sequence like
"\(" in a string constant is legal, and is left as a backslash
followed by a left parenthesis.

Named constants are integer constants with names attached to them.
They are built into the compiler, and are in all capital letters. For
instance, K_BPSC is a named constant that translates to 8, a number
which has a special meaning to some primitives like bind().  The named
constants are listed in vt.doc.


Identifiers
-----------

Names of variables, functions, and some other objects are all
expressed by identifiers.  An identifier is an alphabetical letter or
underline followed by a sequence of alphabetical letters, underlines,
or digits.  The following are valid identifiers:

	abcde	_foo_bar	The2ndThingOnTheList

The following are invalid identifiers:

	2ndThingOnTheList	Charles'sName	My-Foot

Identifiers are case-sensitive, so "Foobar" and "foobar" are
different.


Expressions
-----------

A major part of the VTC syntax are constructs called expressions.
Expressions are defined recursively, so expressions can contain other
expressions.  Every expression has a data type and a value.  Constants
are the simplest type of expression.  An integer constant has a data
type of "integer" and a value corresponding to the value of the
integer constant.  A string constant has a data type of string
pointer; its value is a pointer to a copy of the string.

The evaluation of an expression can involve performing an action.  For
instance, the expression "++a" increases the value of a by one, and
returns the new value.  This is called a side-effect.  Side-effects
are important considerations when considering whether certain control
structures will evaluate certain expressions.  One 'side-effect' we
usually try to avoid is a run-time error, and so we try to avoid
evaluating expressions which will result in them.

VTC has the following data types:

	Integer
	Primitive pointer
	Remote pointer
	Window pointer
	Key binding pointer
	File pointer
	String pointer
	Array (or variable) pointer
	Function pointer
	Regexp pointer
	Association type
	Property list pointer
	Null (no value)

The simplest type of directive to the VTC parser is an
expression-statement.  This consists of an expression followed by a
';'.  The result of an expression-statement is to evaluate the
expression and discard the value.  The following parser directives
have no effect because they are expression-statements whose
expressions have no side-effects:

	4;
	10;
	"foobar";


Function calls and built-in variables
-------------------------------------

A function call is a type of expression with the form:

	function-name(argument, argument, ...)

The function name can be the name of a primitive function (a function
predefined by VT) or of a uesr-defined function.  Each argument is an
expression.  The following is a syntactically correct expression:

	foo(1, bar(3, 4, baz(), "a"), "b")

A function may perform an action.  This is a side-effect of the
expression which calls the function.  A function also returns a value,
which can be used as part of another expression.  In the above
example, the return value of the function call to baz() is used as an
argument to the function call to bar(), which has four arguments.  The
return value of bar() is used in turn as an argument in the function
call to foo(), which has three arguments.

Closely related to function calls are built-in variables.  These have
return values which can vary from invocation to invocation, but never
take any arguments.  They have the simple form:

	builtin-name

As an example, consider the statement:

	split(active, 10);

"split" is the name of a primitive function that splits an output
window.	 "active" is the name of a built-in variable that returns a
pointer to the active window.  The effect of the statement is to split
the active window at line 10.


Variables
---------

VTC has several types of variables: global variables, parameter
variables, and local variables.	 Parameter variables and local
variables are similar to global variables, and will be discussed in
the section about functions.

Variables are named constructs that contain a data value.  They can be
assigned a value using the assignment operator:

	variable-name = expression

The above pattern is an expression involving the binary operator '='.
The '=' operator assigns the value of the expression on the right hand
side to the variable on the left hand side, and returns that value.

Global variables do not need to be declared.  They are created
automatically as their names are used and initialized to NULL, the
data value of null type.

A variable's value can be used in other expressions by referring to it
by its name.  A variable name is an expression whose value is the
contents of the variable.  For example, using "foo" as a variable
name:

	foo = "Hello, world.\n";
	echo(foo);

This would write the line "Hello, world." to the active window.


Binary operators
----------------

Function calls are written in prefix order, so that compiler reads the
name of a function and then a list of arguments to operate on.  Binary
operators are called in infix order.  They operate on two arguments,
with the operator placed between them.

A commonly-used group of binary operators are the arithmetic
operators: * / % + - (multiplication, division, modulus, addition and
subtraction).  They can be used to write familiar-looking mathematical
formulae.  For instance, (3 + 4) is an integer expression with the
value 7, and (9 % 4) is an integer expression with the value 1.

Infix notation is ambiguous; for instance, the expression (3 - 4 - 5)
could be evaluated as (3 - (4 - 5)) or as ((3 - 4) - 5).  Ambiguities
in the binary operator notation are resolved by two properties of
operators, precedence and association.  Parentheses can also be used
to group expressions to resolve conflicts.

Operators are grouped into precedence levels.  The multiplicative
arithmetic operators *, / and % are all on the same level of
precedence.  They have higher precedence than the additive operators +
and -.  So the expression (3 + 4 * 5) is evaluated as (3 + 20) and not
as (7 * 5).  One could write "((3 + 4) * 5)" to force the compiler to
evaluate the addition first.

Within precedence groups, operators can associate left-to-right or
right-to-left.	All binary operators except for the assignment
operators associate left-to-right.  (3 - 4 - 5) is the same as ((3 -
4) - 5), and evaluates to -6.

VTC has the following binary operators, in order of precedence, from
highest to lowest:

	Multiplication:		* / %
	Addition:		+ -
	Bitwise shift:		<< >>
	Relational:		< <= > >=
	Equality:		== !=
	Bitwise and:		&
	Bitwise xor:		^
	Bitwise or:		|
	Logical and:		&&
	Logical or:		||
	Lookup:			->
	Assignment:		= += -= *= /= %= &= != <<= >>= ?:=

The relational and equality operators return a result of 1 if the
condition they test for is true, and 0 if not.	So, the expression (-1
== 3) has the value 0, while the expression (3 < 6) has the value 1.

The logical and and logical or operators (&& and ||) behave specially.
If the left-hand argument is sufficient to determine the value of the
expression--that is, if the expression to the left of a && is false,
or the expression to the left of || is true--then the right hand side
is not evaluated.  Errors and side-effects that would have ocurred in
evaluating the right-hand expression will not occur in this case.  All
three operators return 1 if the logical relationship is true and 0 if
the relationship is false.

The assignment operators are different from other binary operators in
three ways.  First, they associate right-to-left.  "a = b = 3;"
assigns 3 to both a and b and is the same as "a = (b = 3);".  Second,
the argument on the left hand side of an assignment operator is not an
expression but an lvalues.  An lvalue is usually a variable name.  "b
= 3;" is a valid VTC statement, while "b + 1 = 3;" is not.  Third, the
assignment operators have side-effects as their primary purpose.  The
other operators can produce run-time errors, and the -> operator can
have a side-effect relating to order of name association in property
lists, but these effects incidental to the functions of the
non-assignment operators.

The assignment operators other than = are abbreviations.  "a -= 3;" is
equivalent to "a = a - (3);" and so forth.  "a ?:= 3;" is equivalent
to "a = a ? : (3);", described below.

The comma (,) is a binary operator with lower precedence than the
assignment operators.  Inside an argument list, it separates
arguments.  Outside of an argument list, a list of expressions
separated by commas evaluates to the value of the last expression,
after all the other expressions are evaluated and their values
discarded.  For example, (3, 4, x + 2, itoa(7), 6) evaluates to 6.


Unary operators
---------------

VTC also has unary operators that apply to only one argument.  They
are appended to the left side of an expression.	 They have higher
precedence than binary operators, and are evaluated right-to-left.
They are:

	++ --	increment and decrement (lvalues only)
	!	Negation (true --> 0, false --> 1)
	~	Bitwise one's complement
	+	Nothing (no operation)
	-	Additive inverse (3 --> -3)
	*	Dereference (see pointers, below)
	&	Address (lvalues only; see pointers)

The ++ and -- operators can also be appended to the right side of an
lvalue.	 They are called the postdecrement or postincrement operators
when appended to the right side of an lvalue, and the predecrement or
preincrement operators when appended to the left side.  If a is a
variable, then "++a" increments the contents of a by one (a
side-effect) and has the value of a after the increment operation.
"a++" increments the contents of a by one and has the value of a
before the increment operation.	 The same applies to decrement.	 So
the following code produces the output "3":

	a = 3;
	echo(itoa(a++));

While this code produces the output "4":

	a = 3;
	echo(itoa(++a));

In both cases, a has the value 4 after the code is executed.


The conditional operator and expression truth
---------------------------------------------

An expression is false if it is NULL or the integer 0.  Otherwise, it
is true.

The conditional operator takes three arguments in the form "a ? b :
c", where <a>, <b>, and <c> are expressions.  If <a> is true, then <b>
is evaluated and its value is returned.  Otherwise, <c> is evaluated
and its value is returned.  The conditional operator associates
right-to-left and has lower priority than all of the binary operators
except the assignment operators and the comma operator.

The second argument to the conditional can be omitted.	The expression

	a ? : c

has the value of <a> if <a> is true, and the value of <c> otherwise.
The interpreter only evaluates <c> if <a> is false.


Order of evaluation
-------------------

Arguments to binary operators and the conditional operator are
evaluated left-to-right.  Any side-effects in the left argument occur
before side-effects in the right argument.  Arguments to functions are
also evaluated left-to-right.


Statements
----------

Statements are directives to the VTC interpreter.  Like expressions,
they are defined recursively, so statements can contain other
statements.

The expression-statement has already been described.  The following
are examples of useful expression-statements:

	a = 3;
	echo(itoa(a++));

Another form of statement is the compound statement.  It is a list of
any number of statements surrounded by { and }.

	{ a = 3; echo(itoa(a++)); }

is a valid compound statement.

There are two kinds of conditional statements:

	if (expression) statement

causes statement to be executed if expression is true.

	if (expression) statement1 else statement2

causes statement1 to be executed if expression is true, and statement2
to be executed otherwise.  Any of these statements could be compound
statements.  For example:

	if (new = split(win, row)) {
		set_obj(new, new_pager(new));
		set_termread(win, .std_termread);
	}

A common pitfall with if-else statements is:

	if (a)
		if (b)
			c;
	else
		d;

The indentation would suggest that the "else" is supposed to associate
with the first if statement.  It will instead associate with the
second if statement.  There are two ways to resolve this:

	if (a) {
		if (b)
			c;
	} else
		d;

or:

	if (!(a))
		d;
	else if (b)
		c;

The second method uses a common construction, the "else if".  This is
used often enough that the indentation scheme is usually changed to
account for it.	 According to common indentation system, according to
which a line is indented by a tab for each level of nested
flow-control depth, you might write the following code:

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