With some corrections added over time.
############### ############ ###### ######
## ## ## ## ## ## ## ##
###### ###### ####### ## ## ### ##
## ## ## ## ## ##
## ## ####### ## ## ### ##
## ## ## ## ## ## ## ##
####### ############ ###### ######
A MINIMAL PROCEDURAL LANGUAGE
RELEASE 7
Nils M Holm, 1996-2019
1. Introduction
T3X is a small, portable, procedural, block-structured,
recursive, almost typeless, and to some degree object oriented
language. Its syntax is derived from Pascal and BCPL and its
object model is based solely on classes, objects, messages, and
full encapsulation. It is a tool for creating reusable packages
rather than data types. The structured approach to programming
is well-understood, provides a sufficient degree of abstraction,
and can easily be translated into native machine code at the
same time. The object model eases the development of general and
reusable code. T3X is an imperative language. This means that
a program consists of a set of instructions which tell the
computer in what way to manipulate the data defined by the
program. An instruction is also called a statement. In
structured programming languages, there are four fundamental
ways of formulating statements:
- Assignments
- Sequences
- Branches
- Iterations
The assignment is a fundamental property of imperative
languages. It is used to move data from one location to another
by assigning values to variables. In a sequence - which is
basically a list of statements - the statements are processed
from the top towards the bottom of the list. Each statement is
guaranteed to be completely processed before the next one is
interpreted. A branch is a statement which is executed only if
an associated condition applies. Iteration is the repetition of
a statement depending on a condition. In a block-structured
language, statements may be grouped in statement blocks or
compound statements. Each block may have its own local data
which cannot be affected by statements contained in other
blocks.
An additional layer of abstraction is added to an imperative,
block-structured language by providing user-defined procedures
or functions (in this document, these terms will be used
synonymously). A procedure is a statement or a set of statements
which is bound to a symbolic name. A procedure can be executed
by coding a call to that procedure. Most languages provide a
mechanism to transport data to a procedure and return a value to
the calling program. Some languages (like BCPL and Pascal) make
a distinction between procedures and functions, others (like C)
do not. In languages which make a distinction between procedures
and functions, only functions may return values. In T3X, all
procedures return values, but the caller is free to ignore them.
Therefore, procedures and functions are basically the same.
Another level of abstraction is provided by adding an object
model to the language. The object model of T3X consists solely
of
- Classes
- Objects
- Messages
Classes are used to encapsulate code and data of a program. A
class may contain any number of data objects and procedures.
Only public procedures (so-called methods) may be called by
procedures (or methods) outside of the class. Objects are used
to instantiate classes. Each instance of a class has its own
private data area. Hence the same class may be used as a
template for the creation of multiple independent objects.
Messages are used to activate methods of specific objects. T3X
does not provide inheritance or different levels of protection
(like public data or 'friend' relationships). All class-level
data objects are fully encapsulated in objects and only
accessible via methods.
T3X is an almost typeless language. There exist two different
types, so-called atomic variables, which may hold small data
objects, like characters, numbers and references to other data
objects, and vectors, which are used to store logically
connected groups of small data objects. In addition, there are
constants, templates for defining structured data objects and
classes, and different types of procedure declarations. The T3X
compiler does not allow some combinations of operators which do
not make sense (like assigning a value to a procedure or sending
a message to a vector). Consequently, T3X's type checking is
much more strict than, for example, BCPL's, but much less
restrictive than Pascal's or even C's. Weakly typed and typeless
languages have been exposed to a lot of criticism in the past,
because they are considered 'insecure', but the degree of
simplicity and flexibility which is bought by 'sacrificing' this
bit of security is immense.
The type checking mechanisms of the T3X language are limited to
the detection of
- wrong argument counts in procedure calls
- assignments to non-variables
- calls of non-procedures
- instantiations of non-classes
- sending messages to non-objects
- sending non-messages to objects
- dependencies on non-classes
BTW: during the development of an early version of T3X, a severe
error occurred in the compiler. After tracking it down, it
turned out that was limited to the (type-safe) ANSI C version of
the translator and did not affect the T3X version. Of course,
this was coincidence, but to some degree it contradicts the
proposition that typeless languages are per less insecure than
typed languages.
1.1 The History of T3X
The first version of T3X was created in the middle of the
1990's. Its primary design goals were
1. Simplicity and straight-forward syntax and semantics
2. Very high portability
3. A small (64KB text + 64KB data) and simple implementation,
preferably in written in itself
4. Suitable for both interpretation and native code generation
One might think that there must have been quite a few languages
providing these features, but obviously my search did not lead
to any satisfactory result, or T3X would not have been invented.
The language which came closest to these requirements was BCPL.
The typeless approach, which has been very consistently
implemented in this language, leads to clear, simple, and
flexible semantics. The language is portable, its implementation
is small and can easily be done in BCPL itself. The compiler
provided by Martin Richards, the inventor of BCPL, generates
code which is aimed at interpretation (for the purpose of
porting the compiler), but may be translated into native code as
well.
Unfortunately, the syntax of BCPL is rather hard to to parse by
a recursive descent parser (RD) and some precedence rules are
chosen in a way that the creator of T3X found hard to grasp. An
RD parser had always been a prerequisite for the language,
because they are very easy to implement. Of course, Richard's
BCPL compiler is small, elegant and easy to understand, even
though it does use syntax trees and a bottom up parsing
technique. However, RD parsers are still simpler.
Even if BCPL did not match the requirements exactly, it came
pretty close, and studying the language and compiler sources has
influenced the design of T3X a lot. Without BCPL, T3X would not
be the language it is today.
The most important thing when designing a programming language
might be to define its main purpose. The design goal of T3X was
to create a portable, simple, and easy to understand notation
for the description of algorithms. T3X was never aimed at
industrial software development. Its purpose is to support the
programmer in the process of reasoning about problems. It should
be a productivity tool in the sense that it provides a
playground for new ideas and allows the creator of these ideas
to share it with others using a formal notation. Such a
notation, of course, has to be clear, simple, easy to learn, and
it would be a great advantage, if a compiler for this notation
would be available in many different environments.
Naturally, my interpretation of productivity is not exactly the
same as in the rather profit-oriented 'real world' and the
design of the T3X language reflects this intention well. T3X is
not suitable for writing large scale application programs.
Originally, it was is more a notation than a programming
language. Because it is simple and straight-forward, it does not
force its user to pay too much attention to the language itself.
Instead, it provides some very basic building-stones which may
be used to construct a formal solution for a given problem.
So T3X provides only a very basic set of building-stones, but it
turns out that this set is suitable to solve a variety of
different problems in a convenient way - including, for example,
the creation of a compiler and runtime environment for the T3X
language itself.
2. A Tour through the T3X Language
T3X is an almost typeless, block-structured, procedural, object
oriented programming language. Programs, classes, procedures,
statements, and expressions form a hierarchy: Programs consist
of classes, procedures, and statements, classes contain
procedures and statements, procedures usually contain
statements, and statements mostly contain expressions. Variables
may be atoms (ordinal) or vectors (one-dimensional arrays).
Since there are no different types, composed data types - called
structures - are basically equal to vectors. Constants may be
used to represent frequently used or tunable values.
This chapter is written in bottom-up order, so that the building
stones of larger entities already have been explained when the
entities themselves are discussed.
2.1 The Input Alphabet
The T3X compiler expects its input in the form of an ASCII file
(a sequence of octets where the least significant seven bits of
each octet contain the ASCII code of one character and the high
bit is set to zero). The following characters will be treated as
white space (The C-style 0x-notation is used to represent
hexa-decimal numbers):
- blank (0x20)
- horizontal tab (0x09)
- line feed (0x0A)
- carriage return (0x0D)
- form feed (0x0C)
White space characters delimit tokens, but will otherwise be
ignored by the compiler.
Valid input characters are the upper and lower case alphabetic
characters A-Z, a-z, the decimal digits 0-9, and the following
special characters:
" # % & ( ) * + , - . / : ; < = > @ [ \ ] ^ _ | ~
Characters which are not contained in this alphabet may only
occur in string literals, character literals, and comments.
Otherwise they will cause an error during program compilation.
2.2 Comments
A comment may be introduced at almost any point in a T3X program
using an exclamation point (!). It extends up to, but not
including, the end of the current line. Therefore, a comment is
treated the same way as a single white space character, and
consequently,
WH! this is a comment
ILE(1) ;
is equal to
WH ILE(1) ;
and not to
WHILE(1) ;
Therefore, comments may not occur inside of a single token, but
only between two tokens. This is particularly valid for string
literals and character literals which are single tokens as well.
A ! character inside one of these literals is treated as an
ordinary character.
2.3 Naming Conventions
Symbolic names may contain alphabetic characters, the underscore
character (_), and decimal digits, where the first character
must be alphabetic or an underscore. Upper case characters will
be folded to lower case. Therefore, the names
abc abC aBc aBC Abc AbC ABc ABC
would all refer to the same symbol. The T3X compiler always uses
all characters contained in two symbols to distinguish them, so
very_very_very_long_symbol_number_one
and
very_very_very_long_symbol_number_two
are guaranteed to be different. The maximum length of symbol
names may be limited by other factors, though, like the maximum
length of a token.
2.4 Data Declarations
T3X is not a totally typeless language. It is called a
'typeless' language anyway, because even BCPL (which pushes the
typeless concept quite to its limit) has at least two types
(variables and MANIFEST constants) which require different
handling at compile time. In T3X, the following types exist:
- Atomic variables
- Constants
- Vectors
- Structures
- Procedures
- Methods
- Objects
- Classes
Vectors and structures are basically the same and there is no
big difference between methods and procedures, either. Atomic
variables are used to hold small numeric values or single ASCII
characters (which are represented by numbers) or pointers to
other objects. Constants are used to provide symbolic names for
immutable numeric values. Vectors are sequences of atomic
variables. A structure is a set of constants which is used to
give names to specific members of a vector. Procedures process
parameters and return values just like mathematical functions.
Since T3X is an imperative language, they usually have effects,
too. A method is a procedure which is used to query or alter the
state of an object. An object is an instance of a class.
Classes will be discussed in detail in the section about object
oriented programming.
2.4.1 Atomic Variables
Each (atomic) T3X variable allocates exactly one machine word.
When talking about variables in the remainder of this document,
the attribute atomic is implied. Vectors will be implicitly
referred to as vectors or arrays.
Variables are defined using a VAR statement. Any number of names
may be defined in a single statement:
VAR x_coord, y_coord, depth;
Although, it is recommended to define only logically connected
variables in a single statement.
All types of values may be stored in a variable: numeric values,
pointers to strings, pointers to vectors, pointers to
structures, pointers to objects, or single characters. The range
of numeric values which may be stored in a variable actually
depends upon the implementation. The Tcode engine uses only 16
bits to represent a 'cell' or a machine word - independently
from the underlying platform. Therefore, programs which use
values not in the range -32767...32767 should be considered
to be machine-dependent. The T3X compiler will not allow the
use of numeric literals outside of this range.
When a variable is placed in an expression (frequently also
called a 'right-hand side' (RHS) value, it evaluates to its
value. When it is placed on the left-hand side of an assignment,
however, it evaluates to its address (which will be dereferenced
immediately by the following assignment operator, though). The
assignment statement
X := 5;
would change the values stored in the variable X to 5.
2.4.2 Constants
Constants are variables that exist only at compile time
(so-called 'compile time variables'). Instead of an
automatically assigned address, they are initialized with an
explicitly specified value when they are declared. Since they
are compile time entities, the values of constants may not
change at run time. Any number of constants may be declared in a
single CONST statement:
CONST READ = 1, WRITE = 2, RDWR = READ | WRITE;
Each constant name must be followed by an equal sign (=) and a
constant expression that evaluates to the value of the constant.
Constant expressions will be explained in a later section.
Constants may occur only in RHS expressions, where they evaluate
to their values.
2.4.3 Vectors
Vectors are compile time variables, too. When they are declared,
they will be initialized with the address of an array of
subsequent machine words, the so-called vector members or vector
elements. The address of a vector is equal to the address of its
first member. Any number of vectors may be defined in a single
VAR statement. Declarations of vectors and atomic variables may
be mixed in one and the same statement:
VAR RingBuffer[SIZE], Head, Tail;
Vector declarations differ from atomic variable declarations by
the trailing square brackets containing a constant expression
which specifies the size of the vector in machine words. The
first member of a vector has an index value 0 and the last one
has an index of vectorsize-1 (SIZE-1in the above example). The
size of a vector may range from 1 to 32767 elements.
Since vector addresses are stored in compile time variables,
they may not change at run time. It is legal to change the
values of vector members, though. When occurring in RHS
expressions, vector names evaluate to the addresses of their
associated arrays.
Single members of a vector may be addressed using the subscript
operator []. The expression
v[5]
for example, evaluates to the fifth member of the vector V
(given that the first member of the vector is actually referred
to as the zeroth member). Subscripted vectors may occur on the
left sides of expressions, as well. The assignment
v[i] := 99;
would change the I'th member of V to 99. Like atomic variables,
the members of vectors may be used to store any data type, even
pointers to vectors. See the description of the []-operator for
details about nested vectors.
A special case of the vector is the byte vector. Like 'ordinary'
vectors (vector of machine words), they are declared in VAR
statements:
VAR Input::256, Output::256;
The only difference between a vector and a byte vector is the
computation of the required size. The size value after the
::-operator specifies the number of characters required. The
amount of memory actually allocated depends on the size of a
machine word on the target machine, which is returned by the
core class procedure T3X.BPW() (the method BPW of the class
T3X). For all Tcode programs, T3X.BPW()=2 applies. The size of a
byte vector is computed using the following formula (T being an
instance of the T3X class):
vectorsize + T.BPW() - 1
------------------------
T.BPW()
It allocates enough space for at least VECTORSIZE characters.
No further type information is associated with vectors.
Therefore, it is valid to access byte vector members using []
and word vector members using ::. The former is discouraged,
though, because the actual size of a vector might depend on a
specific implementation and alignment errors may occur at
runtime.
A byte vector may not be larger than 32767 bytes (16384 machine
words on the Tcode machine).
2.4.4 Structures
A structure is a composed data object. Only one structure may be
defined in a single STRUCT statement:
STRUCT POINT = PT_X, PT_Y;
Such a statement does not actually create a new data object, but
only the 'layout' of a structure. For example, to create an
actual POINT data object, an additional VAR statement is
required:
VAR point_a[POINT], point_b[POINT];
This statement creates two POINT entities, point_a and point_b.
The members of such structures can be addressed using the
subscript operator: point_a[PT_X] and point_a[PT_Y].
Structures do not really have an own type. As the declaration
and member access syntax already suggests, they are ordinary
arrays and the member names are constants. In fact, the
statement
STRUCT S = A, B, C;
is perfectly equal to
CONST S = 3, A = 0, B = 1, C = 2;
The STRUCT statement only defines symbolic names for accessing
vector members with a fixed position and known meaning. The
structure name is another constant which holds the number of
constants used to name the members (and therefore the size of
the entire structure in machine words).
2.5 Factors
This section describes the most basic elements of each T3X
program, the factors which may be used inside of expressions.
There are many different kinds of factors: symbols, numeric
literals, character literals, string literals, tables, procedure
calls, messages, and class constants. A factor may only occur in
expressions and a single factor is the minimum form of an
expression. Factors may be prefixed by unary operators and they
may be combined using binary or ternary operators. Basically,
all sorts of factors are exchangeable: where one of them may
occur, all others are allowed. The only exception is the symbol
which has some additional properties which make it special. For
example, symbols may be subscripted and it is possible to
compute their addresses. These operations are limited to
symbols. All other operations may be applied to any kind of
factor, even if it makes little sense, like the multiplication
of two strings (which will yield a highly environment-dependent
result):
"Hello" * "World"
The evaluation of a symbol depends on its type. Variables and
constants evaluate to their values, vectors and objects evaluate
to their addresses. Class names evaluate to instance sizes.
Structure names and structure member names are treated in the
same way as constants.
Class constants are public constants which are defined inside of
classes. To include a class constant in an expression, it must
be prefixed with the name of the defining class and a dot:
T3X.SYSOUT
Like 'ordinary' constants, class constants evaluate to their
values.
Numeric literals are written in decimal, hexa-decimal, or binary
notation and represent their own values. A percent sign may be
used to negate a number:
%123 = -123
The difference between %123 and -123 is that %123 is a factor
while -123 is an expression ('minus' applied to a numeric
factor). In fact, the percent sign has little meaning in T3X
today, since the compiler accepts ordinary minus prefixes in
constant expression contexts, too. In early T3X versions,
constant expressions were limited to single factors and
therefore, the percent sign was required to define negative
constant values. The % prefix is kept for compatibility. An
optimizing compiler might turn -N into %N, if N is a constant
numeric factor.
Hexa-decimal notation may be used to represent a numeric value
when prefixing the literal with the strings '0x' or '0X' (null,
X). No space is allowed between the prefix and the hexa-decimal
digits. The number 4095, for example, can be written as '0xfff'
or '0xFFF'. The characters 'A' through 'F' (alternatively
'a'...'f') are used to represent the hexa-decimal digits with
the values '10' to '15'. No difference is made between upper and
lower case characters. The literals
0x1f 0X1f 0x1F 0X1F
all express the decimal value 31. The percent prefix may be
combined with hexa-decimal factors as well, e.g. %0xf.
Numbers may be expressed in binary notation by prefixing the
literal with the strings '0b' or '0B' (null, B). No space is
allowed between the prefix and the binary digits. The number
165, for example, could be written as '0b10101010'.
Note: The literals 0x8000 and 0b1000000000000000 should not be
used to express the (decimal) value -32768. This value is not
defined in T3X. Since 0x8000 is useful to mask the most
significant bit of a pattern, though, the compiler will allow
its use, but it will not allow the notation -32768.
Character literals are single characters or escape sequences
enclosed by single quote characters, like
'a' '0' '\s' ''' '\'' '\\'
A character literal evaluates to the ASCII code of the enclosed
character. An escape sequence may be used to include certain
unprintable or special characters. The backslash character is
used to introduce such a sequence. The '\' itself and the
following character will be removed and replaced with the
associated special character. Note that no escape sequence is
required to represent an apostrophe: '''. Besides most C-style
sequences, the following translations will be performed:
\e->ESC, \q->", and \s->space. The latter has been included to
improve readability. Unlike C, T3X accepts uppercase sequences
as well: \s and \S both evaluate to space. The escape character
may be used to escape itself. Thereby, it loses its special
meaning and '\\' evaluates to a single literal backslash. A
summary of all escape sequences is listed in the quick reference
section.
String literals are sequences of characters delimited by double
quotes ("):
"Hello, World!\n"
Each character either represents itself or is part of an escape
sequence as described above. Each character is stored in a
single byte. String literals are terminated with a NUL
character, so N+1 bytes are required to store a string of the
length N (but sizes are always allocated in machine words).
Since a string is an array of subsequent bytes, the ::-operator
may be used to access its individual characters.
At runtime, each string literal evaluates to the address of its
first character.
A more general form of a literal vector is the table. A table is
a static initialized vector and a generalization of BCPL-style
TABLEs. Syntactically, it is a list of table members delimited
by square brackets:
[ 7, "MOD", @modulo ]
Each table member occupies exactly one machine word. A string,
for example, is included as a pointer, while the string literal
itself is placed outside of the table. Therefore, table members
can be accessed using the subscript operator []: if
x = [ 77,88,99 ]
then
x[2]
evaluates to 99. The square bracket notation was chosen for
delimiting tables because of the strong connection between
vectors and the subscript operator.
The type of each table member may be any out of the following:
- Constant expressions
- Strings
- Addresses of global data objects
- Addresses of procedures (including methods)
- Tables (packed or unpacked)
- Embedded expressions
Constant expressions include everything which has a value that
can be computed at compile time (like numeric literals). The
inclusion of strings has been explained above. Addresses of
global variables and procedures are represented by their symbol
name prefixed with the address operator @.
What makes tables particularly flexible is the possibility to
nest them:
[ [ 2, 9, 4 ],
[ 7, 5, 3 ],
[ 6, 1, 8 ] ]
Like strings, embedded tables are stored outside of the
surrounding table and included as pointers. If, for example, the
above table is assigned to the symbol V, the following
equations hold:
v[0] = [ 2, 9, 4 ]
v[1] = [ 7, 5, 3 ]
v[2] = [ 6, 1, 8 ]
Since the result of applying a subscript operator to a table
containing tables is another table (vector), the subscript
operator may be applied one more time, and consequently,
v[1][1]
would result in 5:
v = [ [2,4,9], [7,5,3], [6,1,8] ]
v[1] = [7,5,3]
v[1][1] = 5
(Remember that the first element of a vector has an index of 0.)
A table that contains at least one non-constant expression is
called a 'dynamic table'. Non-constant expressions must be put
in parentheses when they are contained in a table:
v := [ "a * b = ", (a*b) ];
When there are multiple subsequent dynamic values in a table,
a single pair of parentheses enclosing the entire set is
sufficient:
[ "sums", (a+b), (a+c), (b+c) ]
can be written more conveniently as
[ "sums", (a+b, a+c, b+c) ]
Embedded (non-constant) expressions are computed freshly each
time the flow of the program passes the table in which they are
contained. Therefore, the values of table members computed by
embedded expressions may be different each time the table is
evaluated. This is why such a table is called 'dynamic'. The
parentheses show the compiler that an expression is non-constant
and make it generate additional code to fill in the value of the
expression whenever the table is evaluated. Therefore, static
(constant) expressions should never be parenthesized in tables,
because doing so would result in inefficient code. For example,
v := [ "5 * 7 = ", (5*7) ];
works, but computes 5*7 each time the table is evaluated. Even
if the optimizing compiler folds 5*7 to 35, the value would
still have to be stored in the table each time it is passed.
On the other hand, including dynamic expressions in a table
without any parentheses will lead to an error:
v := [ "a * b = ", a*b ];
will not work unless both A and B are constant.
Tables may be prefixed with the keyword PACKED. Packed tables
may only contain byte-sized values. Therefore, their members are
limited to constant expressions with bit patterns where only the
least significant 8 bits contain values other than 0. Expressed
in numbers, this is the range from -128 to 255.
A string may be considered to be a special case of the packed
table. Consequently, each string may be written as a packed
table as well. For example,
"T3X"
is equal to
PACKED [ 'T', '3', 'X', 0 ]
Note the trailing zero in the vector literal! Both, strings and
packed tables will be padded with zeros up to the next word
boundary.
The maximum number of members per table may be limited, but at
least 128 elements per table must be allowed by any T3X
implementation. The elements contained in nested tables do not
count, but the entire embedded table counts as a single member.
The same limit may exist for packed tables and string literals.
Procedure calls are represented by a procedure name followed by
zero or more comma-separated arguments, enclosed by parentheses:
find(text, "word", 0, TEXT_SIZE);
Each argument may be any valid expression. When a procedure P
expects zero arguments, the parentheses must still be supplied:
P(). A procedure call evaluates to the return value of the
called procedure.
In T3X, only procedures may be called. Calls to absolute
addresses and computed calls - like in BCPL - are not allowed.
There is a mechanism to perform indirect calls, though: the CALL
operator. More detailed information on procedure calls and the
procedure call operators can be found in later sections.
A message is used to activate a method of a class. It is sent to
an instance of its class, also known as an object. The message
syntax is equal to a procedure call prefixed with the name of
the instance to which the message shall be sent, separated from
it by a dot:
t.write(T3X.SYSOUT, "Hello, World!\n", 14);
Details about messages can be found in the chapter on object
oriented programming.
2.5.1 Signed and Unsigned Values
Numeric entities usually carry a sign in T3X. This means that a
part of a bit pattern representing a number is reserved to
indicate the number's sign, positive or negative. On
two's-complement machines, the most significant bit (high bit)
contains the sign flag. If this bit is set, the number is
negative and otherwise it is positive. Therefore, the numeric
range on the Tcode machine includes the values -32767 to 32767
(in bit patterns 0xffff to 0x7fff; remember that -32768 is
excluded).
Under some circumstances, it is desirable to interpret a number
as an unsigned entity instead - for example when comparing
pointers. In this document, a leading dot is used to indicate
an unsigned number. In T3X itself, no such notation exists, but
some operators may be modified with a leading dot to turn them
into 'unsigned operators'. Unsigned operators treat the sign bit
as a part of the value. Therefore, the domain of these operators
is {0 ... 65535} rather than {-32767...32767}.
Note that not all unsigned values may be expressed in the form
of decimal numeric literals in T3X.
Since the modified operators operate on raw 'bit patterns', -1
and 65535 represent the same value to them on two's-complement
machines. To avoid confusion, signed and unsigned operators
should only be applied to the following ranges:
Range Operators
-------------- -----------------------------
-32767...32767 signed: * / < > <= >=
0...65535 unsigned: .* ./ .< .> .<= .>=
2.6 Expressions
In expressions, operators may be used to modify or combine
factors in various ways. Most operators may be applied to any
kind of operand (even if the resulting operation may not
result in any meaningful value).
There are different kinds of operators and, like procedures,
they are classified by the number of their arguments, which are
called 'operands' in this context. There are unary (prefix)
operators, binary (infix) operators, ternary (also infix)
operators, and then there is one variadic operator.
Operators may also be classified by their precedences. The
higher the precedence of an operator is, the stronger it binds
its operands. For example, the term operators (product,
quotient, remainder) bind stronger than the sum operators (sum,
difference). Therefore,
a * b + c * d
is equal to
(a * b) + (c * d)
Like in math expressions, parentheses may be used to override
the default grouping. The precedence rules are simple in T3X:
1. Postfix operators bind strongest.
2. Unary operators bind stronger than binary operators.
2. Binary operators bind stronger than the conditional operator.
4. The ascending order of precedence for binary operators is as
follows: disjunction (1), conjunction (2), equation (3),
ordering relation (4), bit (5), sum (6), and term (7)
operators
Although postfix operators are also 'binary', they are called
'postfix operators' in this text, while 'binary operators'
means binary infix operators.
The precedence rules in 4. are similar to the rules used in the
evaluation of common math expressions.
Another property of an operator is its associativity. An
operator associates to the left, when a sequence of identical
operations is evaluated from the left to the right and
associates to the right, when such sequences are evaluated
from the right to the left.
Associativity Expression Meaning
------------- ----------- -------------
left A op B op C (A op B) op C
right A op B op C A op (B op C)
In T3X, all binary operations with the sole exception of :: are
left-associative. The byte operator is right-associative.
In the remainder of this section, all available operators
will be explained. The appearance is ordered by descending
precedence.
2.6.1 Procedure Calls and Subscripts
The operators (), [], and :: are the only postfix operators.
They are always applied to primary factors in the form of
symbols, e.g.:
symbol()
symbol[expression]
symbol::factor
The ()-operator is a variadic operator. Given the procedure call
P(a1, ..., aN)
its arity is N+1 (P plus N arguments). The meaning of the
operator is the application of the procedure P to the (optional)
arguments a1 through aN. If P does not have any formal
arguments, its syntax is P().
The value of the operation depends on the semantics of P. See
the description of the RETURN statement for further details.
() may only be applied to symbols of the type 'procedure'. The
procedure must have been declared before its first application,
either by using a procedure declaration or a forward
declaration. The number of arguments to a procedure call will be
checked against the arity of the called procedure. If the
numbers do not match, an error will be signalled.
Each argument in a procedure call may be any valid expression
itself, which includes, of course, procedure calls. Given the
binary function P2, the following expression is perfectly valid:
P2( P2(1, 2), P2( 3, P2(4, 5) ) )
An indirect procedure call may be performed using the CALL
operator. The expression
CALL PP(a1, ..., aN)
evaluates to the result of the application of PP to a1...aN, but
in this case PP is a 'procedure pointer' instead of an actual
procedure. A procedure pointer is an ordinary variable which has
been assigned the address of a procedure by using the address
operator '@':
PP := @P;
In indirect procedure calls, no type checking (as described
above) will be performed. If PP is the name of a procedure
instead of a variable, the keyword CALL will be ignored.
In direct and indirect calls, the calling convention is 'call
by value'. This means that all arguments of the call will be
evaluated before control is transferred to the called procedure,
so that the value of each parametric expression will be
transported to the procedure.
Note: Since vectors evaluate to their addresses, passing a
vector by value will actually pass a reference to the vector.
Therefore, vectors are always passed by reference: Instead of
passing the entire vector, only the address of its first member
is transported to the called procedure. In the procedure the
address will be stored in an (atomic) parameter variable. Since
parameters are always atomic and therefore evaluate to their
values and vectors evaluate to their addresses, both the actual
vector and the parameter will reference the same memory location
and subsequently, the parameter may be used in the same way as
the original vector.
Procedure parameters are guaranteed to be evaluated in the order
of occurrence (from the left to the right). For example, given
the expression
P( Q(), R() );
the programmer may rely on the fact that Q() will be called
before R().
The subscript operator [] may be applied to vectors as well as
to atomic variables. The subscript in
symbol [subscript]
may be any valid expression. If A is a vector, the subscript
operation
a[b]
evaluates to the B'th member of A. If A is an atomic variable,
the operation evaluates to the B'th member of the vector pointed
to by A. This means that both subscripts in the following
example would evaluate to the same value:
var v[100], pv;
var a1, a2;
pv := v;
a1 := v[25];
a2 := pv[25];
Since there is no nesting limit for vectors, any number of
subscript operators may follow a single symbol. Assuming that V5
holds a vector containing five levels of nested vectors, the
expression
v4[i1][i2][i3][i4][i5]
could be used to access single elements at the deepest nesting
level. Chains of subscripts evaluate from the left to the right.
The 'byte subscript' operator :: differs from the ordinary
(word) subscript operator in several ways. First, it addresses
bytes in (byte) vectors and second, it is right-associative.
The expression
a::b
evaluates to the B'th byte of the vector A. Therefore, :: is
mostly used to access characters in strings. Since the results
of ::-operations are always limited to byte width, they cannot
be assumed to return valid addresses. For this reason, byte
subscripts associate to the right: their result may very well be
a valid subscript. If the expression
a :: b :: c
would evaluate from the left to the right, the result of a::b
would probably not be a valid address, since it is limited to
eight bits. In this case, however, the following subscript would
reference the C'th byte of a non-vector - which would certainly
not be the desired result. If the expression evaluates from the
right to the left, though, the subexpression b::c is evaluated
first and will probably return a valid subscript. This subscript
is then applied to the vector A.
Finally, the :: operator differs from [], because it has no
right-hand side delimiter. Therefore, the right-hand side of ::
is always a single factor and expressions like
a::b+c
actually evaluate to
(a::b)+c
since :: has the highest precedence. To address the b+c'th byte
in the array A, the subscript must be but in parentheses:
a::(b+c)
2.6.2 Unary Operators
All unary operators have a high precedence and bind to single
factors. Unless explicitly specified using parentheses, they
never affect subexpressions containing other operators (except
for postfix operators which have an even higher precedence). The
suffix operators must bind stronger than the prefix operators,
because this order leads to much more sensible semantics. For
example
-p(a,b)
means 'negate the result of applying P to A and B' and
~v[j]
means 'evaluate to the inverse value of the J'th member of V'.
If the order of precedence would be inversed, the meaning of the
first example would be 'apply whatever is at the negative
address of P to A and B' and the second one would mean 'evaluate
to the J'th member of the vector located at the address
expressed by the inverse value of V'.
Alt in all, there are four prefix operators. The minus sign (-)
(which exists as a binary operator, too) evaluates to the
negative value of its operand. Like in math expressions, any
even number of minus signs has no effect. The unary minus sign
is distinguished from the binary '-' by its context. When the
sign occurs between two operands, it is binary. If it occurs at
the place of a factor, it is unary and the factor itself
follows after the operator.
The tilde operator (~) results in the value of its operand with
all bits inverted. Since inverting a bit twice always yields the
original state, even numbers of ~-operators have no effect,
either.
The backslash (\) represents the logical NOT (while ~ represents
the bitwise NOT). This operator evaluates to logical truth (-1),
if its operand is logically false (0) and vice versa. Only the
value zero represents logical falsity in T3X and all non-zero
values represent logical truth. The canonical form of the 'true'
value is -1. Two (or any other even number of) subsequent
logical NOT operators may be used to create the normal form of an
arbitrary truth value.
The address operator (@) evaluates to the address of its
operand. Therefore, it may only be applied to symbol names. The
addresses of constants, structure member names, and classes may
not be computed using @, because such entities have no
addresses. Since the subscript operators bind stronger than the
address operator, @ may be used to compute addresses of vector
and structure members, and even the addresses of members of
nested tables:
@v[i][j]
computes the address of the J'th member of the embedded vector
v[i]. Of course, the address operator might be combined with
byte subsrcipts, as well:
@s::i
yields the address of the I'th byte of S.
It is theoretically possible to compute the address of the I'th
member of the bytevector S using
x := s+i;
and the I'th member of the vector V using
x := v + i*t.bpw();
but the expressions
x := @s::i;
x := @v[i];
are both more portable and more comprehensible.
2.6.3 Term Operators
The operation A*B evaluates to the product of A and B. If A*B
does not fit in a machine word, the result is undefined.
A/B results in the integer part of the quotient of A and B. The
result is undefined, if B is zero.
A MOD B evaluates to the difference between A and A./B.*B where
A./B is an unsigned integer division and .* is an unsigned
multiplication. Therefore, A MOD B is the division remainder of
A./B. Like /, MOD leads to an undefined result, if B=0.
All term operators respect the signs of both of their operands.
Two equally signed operands yield a positive result and operands
with different signs lead to a negative result.
However, the T3X language also provides some modified operators
which work on unsigned values. Modified versions of the
multiplication and division operator exist. Like all modified
operators, they are prefixed with a dot (.).
The operation A.*B evaluates to the product of the unsigned
values .A and .B. A./B results in the integer part of the
quotient of .A and .B.
The notation .X is used to denote the unsigned value of X. It
is not part of the T3X syntax.
2.6.4 Sum Operators
A+B evaluates to the sum of A and B and A-B evaluates to their
difference.
2.6.5 Bit Operators
In T3X, all bit operations have the same precedence. Grouping
such operations usually requires parentheses. Otherwise
evaluation is performed from the left to the right.
The operation A&B results in the bitwise AND of A and B. Each
bit is the result of computing the logical product of one bit in
A with the bit at the same position in B.
A|B yields the result of performing a bitwise OR on A and B.
Each bit in the result is a logical sum of a bit in A and the
bit at the same position in B.
A^B performs a bitwise exclusive OR (XOR). In this case, the
computation of a single bit is done by combining bits at the
equal positions using the logical negative equivalence ('not
equal') operation.
See the following table for the results of applying logical
operations to pairs of bits.
A B AND,* OR,+ XOR,\=
- - ----- ---- ------
0 0 0 0 0
0 1 0 1 1
1 0 0 1 1
1 1 1 1 0
A<<B evaluates to the value of A with all bits shifted to the
left by B positions. This is the same as an unsigned
multiplication with the B'th power of 2:
b
a << b = a .* 2
E.g.:
3
2<<3 = 2 .* 2 = 16
After such an operation, the sign of the result must be
considered to be undefined. This is not relevant, of course, if
A is used as a bit field where each bit represents a binary
state.
A>>B yields the result of shifting the bits of A to the right by
B positions. This is basically equal to the computation of the
quotient
b
a ./ 2
Like in left-shift operations, the sign must be considered
to be undefined after right-shift operations. The >>-operation
does clear the most significant bit of its result, though.
Technically speaking, one might say that the shift operators in
T3X perform bitwise rather than arithmetic shift operations.
2.6.6 Relational Operators
Relational operators are used to compare two operands. The
relation between the operands is expressed as a truth value: all
these operators return truth, if their meaning applies to their
operands and otherwise falsity. The following relational
operations exist (.X denotes the unsigned value of X):
Operator Description
-------- --------------------------------
A < B A is less than B
A > B A is greater than B
A <= B A is less than or equal to B
A >= B A is greater than or equal to B
A .< B .A is less than .B
A .> B .A is greater than .B
A .<= B .A is less than or equal to .B
A .>= B .A is greater than or equal to .B
-------- --------------------------------
A = B A is equal to B
A \= B A is not equal to B
Note: the operators expressing equivalence (=, \=) have a lower
precedence than operators expressing ordering (> , <, >=, <=,
.<, .>, .<=, .>=). For example,
A < B = C < D
is equal to
(A < B) = (C < D)
Consequently, the equation sign may be interpreted as 'logical
equivalence' when used between comparisons: the above expression
evaluates to true, if either
(A<B) AND (C<D)
or
\(A<B) AND \(C<D)
applies. Since the inequation operator \= has the same
precedence as =, it may be used as a negative logical
equivalence operator (aka an Exclusive OR):
A<0 \= B<0
becomes true, if either A or B is negative. If the signs of A
and B are equal, the expression yields the result 'false'.
Note, again, that any value may be considered a truth value in
T3X. Everything but the value zero is interpreted as 'truth',
and only 0 may be used to express the 'false' value.
2.6.7 Conjunction and Disjunction
The operators A/\B and A\/B implement logical conjunction (AND)
and disjunction (OR). Generally, the expression
A /\ B
evaluates to some true value, only if A AND B evaluate to
'truth'. Analogously,
A \/ B
yields a true result if either A OR B (or both of them) evaluate
to 'truth'.
More specifically, /\ and \/ are so-called 'short circuit
operators'. Since the expression A/\B can lead to a true result
only if all its operands are true, there is no actual need to
evaluate B, if A already has yielded 'false'. Therefore, the
second operand of a conjunction will never be evaluated by a T3X
program, if the first one already is false. The result will be
zero in this case. If, on the other hand, the first value is
true, the result of the entire operation will be the value of
the second operand. Therefore, the result of
A /\ B
can be specified more precisely as
zero, if A = 0
and
B, if A \= 0.
Similarly, the expression A\/B can never become 'false', if A
already has been found out to be true. Therefore, no T3X program
will ever evaluate B in such a case, and the meaning of the
disjunction
A \/ B
can be defined more precisely as
A, if A \= 0
B, if A = 0
Like in mathematical logic, conjunction binds stronger than
disjunction:
A /\ B \/ C /\ D
equals
(A /\ B) \/ (C /\ D)
In chains of equal logical operations, the order of evaluation
is from the left to the right (as in all binary infix
operations). This means that chains of conjunctions will be
evaluated up to the first 'false' operand and chains of
disjunctions will be processed up to the first 'true' operand.
In either case, the result of the entire chain is the value of
the last operand that was evaluated.
There exists a connection between the logical operators and
conditional statements: Because of their short circuit nature,
logical operators may be used to implement flow control inside
of expressions. The expression
A /\ B()
has almost the same meaning as
IF (A) B();
The only difference is that the expression yields a value, while
the statement only has an effect. Likewise, the expression
A \/ B()
has the same meaning as
IF (\A) B();
when ignoring the value of the expression. The IF-statement will
be explained in a later section.
2.6.8 Conditional Expressions
The ternary conditional operator has the least precedence.
Therefore, it may be used to combine any kind of expressions
without using parentheses. The following expression, for
example, implements the minimum function:
a < b -> a : b
Since the operator has three operands, it consists of two parts:
'->' and ':'. The meaning of the conditional operator is as
follows: In the expression
A-> B: C
the operand A (the condition) is evaluated first. If it
evaluates to some 'true' value, B will be evaluated and
otherwise, C will be evaluated. If B is evaluated, C will not be
evaluated and vice versa. The result of the expression is equal
to the value of the last evaluated operand.
Like the logical operators /\ and \/, the conditional operator
has a connection to conditional statements:
A-> B(): C()
is equivalent to
IE (A) B(); ELSE C();
except for the fact, of course, that the expression has a value,
while the statement only an effect. (IE means If/Else and
introduces a conditional statement with an alternative). The
IE-statement will be discussed in a later section.
2.6.9 Constant Expressions
Constant expressions are used wherever a value must be known at
compile time. Only a limited set of operators is allowed in
constant expressions and the order of evaluation is always from
the left to the right. Only one single unary operator is allowed
per factor. There are no precedence or associativity rules.
L+1*10
evaluates to (L+1)*10 and not to L+(1*10) like it would in
ordinary expressions. The reasons for this decision were (1)
simplicity of implementation and (2) the fact that most
conditional expressions contain only a single operator or none
at all.
The following operators are recognized inside of constant
expressions:
'+' is frequently required to increase the lengths of arrays.
For example, if a buffer has to be used as a string, an
additional machine word must be appended to hold the delimiting
NUL character, e.g.:
VAR buffer[BUFSIZE + 1];
The binary - has been added to avoid constructs like
CONST X = Y + %2;
which may now be written as
CONST X = Y - 2;
'*' can be used to allocate memory for arrays of structures, for
example:
VAR Points[POINT * NUMBER_OF_POINTS];
'|' is useful when creating constant bit maps:
CONST A = 8, B = 16, AorB = A | B;
'~' is also useful for creating constant bit maps:
CONST SignBit = 0x8000, ValueMask = ~SignBit;
The unary '-', finally, can be used to negate constants. This is
particularly useful when counting down in FOR loops where the
step width must be constant:
FOR (i=99, -1, -STEPWIDTH) p();
2.6.10 Order of Evaluation
While the associativity and precedence rules specify which
operation is to be performed first, the order of evaluation
determines which factor is to be evaluated first. For example,
in the expression
A * B
A may be evaluated before B or B may be evaluated before A. The
order of evaluation becomes important, if both A and B have
effects. If A had the effect of printing 'A' on the terminal
screen and B would print 'B', the terminal output of above
expression could be "AB" as well as "BA".
The order of evaluation is undefined in most operations, but
there are exceptions: the definitions of the conjunction,
disjunction, and conditional operators order the evaluation of
their operands explicitly. Therefore, the order of evaluation
of an expression like
A() /\ B()
is exactly defined. The left-hand side is always evaluated first
and the right-hand side is only evaluated, if the value of the
left-hand side is non-zero. Given the effects described above,
this expression would print "AB", if A() is non-zero and "A", if
it is zero. It would under no circumstances print "BA".
The other exception is the order of evaluation of procedure call
arguments and nested procedure calls. Procedure call arguments
are guaranteed to be evaluated from the left to the right and
nested calls are evaluated inside-out. The expression
P( A(), B() )
would invariably be evaluated in the order A, B, P. Therefore,
it is safe, for example, to format a string in a procedure call
argument in T3X and compute the length of the formatted string
in a following argument. The statement
t.write(1, str.format(b, "%S", [(a)]), str.length(b));
would be guaranteed to print the string in B, as formatted by
str.format(), correctly.
Note: A T3X programmer should never rely on any order of
evaluation not explicitly specified in this subsection! Even if
precedence rules may suggest a specific order of evaluation, it
may in fact be different and, even worse, it may change without
breaking any rules, for instance when turning optimizations on
or off or using a different compiler version.
2.7 Statements
Statements are the basic building stones of T3X programs. While
expressions just have a value, statements are used to 'tell the
computer to do something'. This is why T3X is called an
'imperative language'. Each program is a list of commands which
is executed in sequence. Each command is also called a statement
in the terminology of imperative programming.
There are different kinds of statements: assignments, procedure
calls, conditional statements, loop statements, branch
statements, and compound statements. The assignment is an
essential part of every imperative language. It is frequently
even used to characterize the imperative approach. Compound
statements do not have an own meaning, but they are used to
group statements to form the bodies of loops, conditionals, and
procedures. All other statement types control the flow of a
program.
In T3X, all statements have to be terminated with a semicolon.
This means that a semicolon must follow every statement in a
program, except for compound statements which are delimited by
the keywords DO and END. In other procedural languages (like
BCPL and Pascal), statements are 'separated' rather than
terminated. In such languages, a delimiter is only necessary, if
two or more statements are written in sequence - there may not
be any delimiter after the last statement. The separation rules
in some languages are rather complex and the saving in
delimiters is usually not worth the extra expense of having to
remember these rules. Therefore, the most simple form of
combining statements has been chosen in T3X:
Every (non-compound) statement has to be terminated.
2.7.1 Assignments
An assignment transfers the value of an expression to a specific
storage location. For example, the statement
A := B;
copies the value of B to A. After the assignment, both variables
will have the same value. The previous value of A is thereby
lost.
The right-hand side (RHS) of an assignment may be any valid
expression as described in the previous section. The left-hand
side is restricted to a subset of expressions that is often
referred to as LHS values or lvalues (left-hand side values).
In T3X, each lvalue may be any of the following:
- atomic variables
- vector members
- byte vector members
- structure members
where vector members and structure members are essentially the
same.
Assignments to vector members are not limited to direct members
of a vector. Addressing elements of multiply nested vectors is
perfectly valid. The evaluation of variables on left-hand and
right-hand sides of assignments was explained in detail in the
section about factors. In short, RHS variables evaluate to their
values and LHS variables evaluate to their addresses. The
assignment operator := first evaluates the expression on its
left side. Then it evaluates the expression to its right and
stores the result at the address denoted by the LHS.
A generalization of the evaluation of left-hand sides is the
following: All but the last reference on a left-hand side of an
assignment evaluates to its value. Only the last reference
evaluates to its address. Here are some examples:
A := B;
The symbol A references a specific storage location. Since it is
the only reference in the lvalue, it evaluates to its address.
In the statement
A[i] := B;
A is not the last reference and hence it yields its value (which
is its address, because A is a vector). The operation [i]
references the I'th member of A. Since it is the last reference
on the LHS, it evaluates to the address of A[i] instead of its
value. Consequently, the following assignment operator stores B
at the address of the I'th member of A. The same is valid for
accessing vector elements at any nesting level. The statement
A[i1][i2][i3][i4] := B;
for example, stores B in the i4'th member of A[i1][i2][i3].
Accessing byte vectors works in the same way:
A::i := B;
stores the least significant eight bits of B in the I'th byte of
A.
Since :: associates to the right, the last evaluated reference
is the leftmost one in chains of byte operators like
A::B::i := C;
Because B::i will be evaluated first in this example, it will
yield its value. Then, the address of A::(B::i) is computed.
Since no more references follow after A::, the (least
significant eight bits of the) value of C will be stored in the
(B::i)'th byte of A.
Note: Although the assignment symbol := looks like an operator
(and is frequently even referred to as such), it may not be used
inside of expressions, but only to combine expressions. It is a
command rather than an operator.
2.7.2 Procedure Calls
The application of a procedure may form a complete statement:
fill(a, 'X', 10);
In this case, the return value of the activated procedure will
be discarded and only the effects of the procedure will actually
take effect. The effect of the above statement, for example,
could be to fill the first 10 characters of the vector A with
the character 'X'.
Each procedure - no matter whether it returns a specific value
or not - may be used in a standalone procedure call. For details
on procedure calls, see the sections on factors and procedures
in this manual.
2.7.3 Conditional Statements
There are two forms of the conditional statement. The first one
is the IF statement which is available in most procedural
languages. Its general syntax is
IF (expression) statement
where 'expression' may be any expression and 'statement' may be
any statement. The IF statement itself does not have to be
terminated with a semicolon, because its 'body', which is a
complete statement by itself, already supplies the terminating
semicolon. The statement which forms the body of the IF
statement will be executed only, if 'expression' evaluates to a
'true' (non-zero) value. The following statement turns A into
its absolute value:
IF (a < 0) a := -a;
If A is less than zero, then A will be assigned the value -A,
thereby changing its sign. Since the body A := -A is executed
only if, A < 0 applies, this conditional statement always leaves
a positive value in A. The semicolon in the above example
belongs to the assignment.
The second form of the conditional statement is the IE
statement, which implements a conditional statement with an
alternative:
IE (expression) statement-T ELSE statement-F
Like in IF statements, any valid expression or statement
may be used in the places of 'expression', 'statement-T',
and 'statement-F'.
The meaning of the IE statement is equal to the one of the IF
statement as long as the expression becomes 'true'. In this
case, 'statement-T' will be executed. If the expression
evaluates to 'false', though, 'statement-F' will be executed,
while an IF statement would not have any effect in this case.
Therefore
IF (expr) stmt
is equal to
IE (expr) stmt ELSE ;
IE is an abbreviation for If/Else. In most languages, the IF
statement may or may not have an alternative. In T3X, there is a
separate type of statement for each variant. The reason for this
decision is the 'dangling else' problem, which cannot occur when
these statement types are separated. If no further information
is supplied, the following program written in a language which
allows optional alternatives would be ambiguous:
IF (condition1)
IF (condition2) statement1
ELSE statement2
The problem is to decide to which IF the ELSE branch belongs: is
it the alternative of IF (condition1) or IF (condition2)? I.e.,
does the above mean
IF (condition1) DO
IF (condition2) statement1
ELSE statement2
END
or
IF (condition1) DO
IF (condition2) statement1
END
ELSE statement2
In fact, most languages will associate the ELSE branch with the
most recently opened IF statement, and therefore implement the
second program fragment above. In T3X, such an ambiguity does
not exist:
IE (condition1)
IF (condition2) statement1
ELSE
statement2
Since the IF statement cannot have an alternative, the ELSE
branch must belong to IE (condition1).
2.7.4 Loop Statements
There are two kinds of loops: 'while' loops and 'for' loops
which represent two classes of problems: those which are
computable by algorithms with a known upper limit of iterations
(FOR-computable or primitive recursive functions) and problems
which cannot be computed by algorithms with a fixed number of
iterations (WHILE-computable or general recursive functions).
Since the FOR-computable functions are a subset of the
WHILE-computable ones, FOR statements may be considered to be a
special case of WHILE statements and in fact, it is possible to
express a FOR loop using WHILE, but not vice versa.
Note: in fact, WHILE and FOR are completely interchangeable on
computer systems with bounded memory. On an ideal machine with
unbounded memory, though, they represent two different classes
of problems. The Ackermann function, for example, is the
classical example of a function that is WHILE-computable, but
not FOR-computable.
There is a third kind of loop in many other languages, the
repetitive loop, but it turns out to be a special case of the
WHILE loop. Repeating loops are not very frequently needed and
if they are, they can easily be constructed using WHILE, IF and
LEAVE in T3X.
The WHILE loop has the following general form:
WHILE (expression) statement
where 'expression' may be any expression and 'statement' may be
any statement. The 'body' consisting of the statement will be
executed while the test expression in parentheses evaluates to
some 'true' value. Hence the name of this loop. If the
expression becomes 'false' before the statement has been passed
for the first time, the statement will never be executed.
However, a loop which tests its exit condition at the end of the
statement may be constructed using WHILE, IF, LEAVE, and a
compound statement (which will be explained later in this
chapter):
WHILE (-1) DO ! loop forever
statement
IF (\condition) LEAVE;
END
In this case, statement will be executed at least once, because
the exit condition -1 is a 'true' constant. In the subsequent IF
statement, the loop will be left if the condition does not
apply. LEAVE is used to branch out of a loop. It will also be
explained later in this chapter.
The FOR loop exists in two forms: an explicit form and a short
form. The explicit form looks as follows:
FOR (var=start, limit, step) statement
'Var' is an atomic variable that must be declared earlier in the
program. Unlike in BCPL, it will not be declared implicitly by
the FOR statement. 'Start' and 'limit' are expressions and
'step' is a constant expression. The FOR loop works this way:
First, 'var' is initialized with the value of 'start'.
Second, 'var' is compared against 'limit'. If either the
condition
var < limit /\ step >= 0
or
var > limit /\ step < 0
holds, the statement is executed. Otherwise the loop is left and
the statement will not be executed.
Finally, 'step' is added to 'var', and the loop will be repeated
from the point where the exit condition is checked. Like in a
WHILE loop, the statement will never be executed, if the exit
condition already is true when it is checked for the first time.
The following examples print the numbers from 0 to 9 using the
procedure 'print' (which is only defined in the first example).
('Print' uses some routines of the classes 't3x' and 'string',
which will be explained in a later chapter.)
MODULE example(t3x, string);
OBJECT t[t3x], str[string];
print(n) DO VAR b::10;
t.write(T3X.SYSOUT, str.format(b, "%D\n", [(n)]),
str.length(b));
END
! --- end of the common part ---
DO VAR i;
FOR (i=0, 10, 1) print(i);
END
This example counts down from 9 to 0:
DO VAR i;
FOR (i=9, -1, -1) print(i);
END
Special attention should be paid to the limits of the FOR loops
in these examples. They always specify the first value which
will NOT be applied to the statement. Another way to write the
second example would be the following one, where the FOR loop
is replaced by a WHILE loop:
DO VAR i;
i := 9;
WHILE (i > -1) DO
print(i);
i := i-1;
END
END
The meaning of this program fragment is completely equal to the
one employing a FOR loop, but the syntax of the FOR statement is
more compact and expresses the purpose of the statement clearer.
The step value is optional in FOR statements. In the short form
of the statement, it is omitted. If only two operands are
specified in FOR, the step width defaults to one. Therefore, the
statements
FOR (j=0, 100, 1) print(i);
and
FOR (j=0, 100) print(i);
have exactly the same meaning.
2.7.5 Branch Statements
A branch passes control to a specific point in a program.
Typical destinations for branch commands are the beginnings or
the ends of loops or the ends of procedures or programs. There
is no branch command with a freely definable destination like
Goto in BCPL.
The LEAVE command causes the immediate termination of the
innermost WHILE or FOR loop. There are no operands to LEAVE.
The following code compares the characters in two strings A and
B. The loop is left at the first position where the strings
differ, but in any case after 100 steps:
FOR (i=0, 100) IF (a::i \= b::i) LEAVE;
The loop is set up for 100 passes and the LEAVE statement makes
the loop terminate as soon as a mismatch is found.
The LOOP command transfers control to the beginning of the
innermost loop. Like LEAVE, it has does not have any operands.
If LOOP is used inside of a FOR loop, it branches to the
increment part where the value of the index variable is
modified. In WHILE loops, it branches directly to the point
where the exit condition is checked.
The following statement prints the numbers from 1 to 100, but
skips over those that are multiples of 7:
FOR (i=1, 101) DO
IF (i mod 7 = 0) LOOP;
print(i);
END
To return from a procedure, the RETURN statement may be used. It
has the general forms
RETURN expression;
and
RETURN;
The statement performs a branch to the end of the procedure,
where local storage is released and the procedure is left. It
the given expression, if any, and passes its value back to the
calling procedure. The value received by the calling procedure
is the value of that expression:
square(x) RETURN x*x;
Q() DO VAR y;
y := square(5);
END
In this short example program, 5 is passed as an argument to the
procedure 'square'. The procedure computes the square of its
argument and returns it to Q where the result (25) will be stored
in y. In 'square', the RETURN statement is the last statement in
the procedure, but in fact RETURN can be used anywhere in a
procedure.
When no expression is specified after RETURN, zero will be
returned;
RETURN;
is the short form of
RETURN 0;
All of the above branch statements take care of locally
allocated storage. If local symbols are defined in the bodies
of loops, for example, LOOP and LEAVE will release this storage
before branching to their respective destinations. This allows
the use of these commands in any loop context, even if local
symbols are present.
The HALT statement with the general forms
HALT constant-expression;
and
HALT;
branches to the end of an entire program.
If necessary, the command cleans up the runtime environment of
the program. The value of the specified constant expression is
returned to the calling process. Only the least significant
eight bits are guaranteed to be returned to the caller.
The argument of HALT may be omitted. In this case, zero will be
delivered to the caller.
2.7.6 Compound Statements
A compound statement (sometimes also called a block statement or
statement block) is a group of statements which is treated like
a single statement under some aspects. For example, a compound
statement may occur at any place where a simple statement is
expected. In commands like
IF (expression) statement
a compound statement can be used to extend the scope of the
conditional statement so that it is applied to a group of
statements instead of a single statement:
IF (a < '0' \/ a > '9') DO VAR b::3;
u.printf("Not a valid digit: %C\n", [(a)]);
RETURN -1;
END
In this example, both the u.printf() message and the RETURN
statement will processed only, if the IF-condition applies. (The
concept of sending messages will be explained in detail in the
chapter about object oriented T3X.) The keywords DO and END are
used to delimit the statement block. There is no terminating
semicolon after a compound statement. The line
DO p(); q(); END ;
would be recognized as a compound statement containing the
procedure calls P() and Q() followed by an empty statement
consisting of a single semicolon.
In T3X, compound statements are ordinary statements and they
may occur at any place where a statement is expected. Even
statements like
DO DO END DO END END
are perfectly valid. The use of compound statements in sequences
like the above becomes clear in the next sections where the
allocation of local storage in compound statements is explained.
2.7.7 Local Symbols
Besides the grouping of commands, compound statements provide a
mechanism for the definition of local symbols and the allocation
of dynamic storage. Declaration statements already have been
explained in a previous section. All data objects which can be
created globally in T3X may also be declared locally inside of
compound statements by placing their declarations at the
beginning of a statement block. Any number of declarations will
be accepted after the keyword DO.
The declaration statements themselves do not change when used in
local contexts. Only the position inside of a statement block
makes the declared symbols local to that block. The statement
DO VAR i; FOR (i=0, 10) print(i); END
for example, applies the procedure 'print' to the numbers from
0 to 9. The index variable is declared inside of a compound
statement that also contains the FOR loop generating the
sequence. The variable I does not exist before the compound
statement is entered. It will be created automatically at the
point of its declaration and it will cease to exist at the end
of the block in which it has been declared. Therefore, variables
which are local to compound statements are sometimes also called
'automatic variables'.
Atomic variables, vectors, structures, constants, and objects
may all be declared locally. Unlike BCPL, T3X does not support
nested procedure definitions, though. In the cases of atomic
variables and vectors, the storage required by the variables is
allocated when the symbol becomes valid and released when the
variable is destroyed. Automatic storage will be allocated on
the runtime stack.
To illustrate another application of local storage allocation,
imagine the following situation:
P() DO
VAR big_V[VERY_LARGE_1];
VAR big_W[VERY_LARGE_2]; ! Too big
task1(big_V);
task2(big_W);
END
In this procedure, two tasks requiring large amounts of storage
shall be run sequentially, but not enough memory for both arrays
is available. One solution would be the creation of two
procedures where each one creates local storage for only one of
the tasks. Another one would be to share the vector, but both
solutions only work at the cost of readability. T3X provides
another solution, since the compiler guarantees that local
storage is allocated exactly at the point of its declaration and
released immediately at the point of the destruction of the
associated symbol:
P() DO
DO VAR big_V[VERY_LARGE_1];
task1(big_V);
END ! big_V gets released here
DO VAR big_W[VERY_LARGE_2];
task2(big_W);
END ! big_W gets released here
END
Since compound statements may be nested, naming conflicts may
occur in many languages, like the following example (in C)
illustrates:
{ int x;
x = 123;
{ int x;
x = 456;
printf("%d\n", x);
}
printf("%d\n", x);
}
The variable X is defined in the inner and outer block statement
and assigned two different variables. So the variables has
different values in the inner and outer block. The inner
variable X is said to 'shadow' the outer X. The outer instance
of X becomes invisible inside of the inner block. Therefore, the
program fragment would print first 456 and then 123 when
executed.
T3X uses stricter scoping rules than most other languages:
Symbols generally may not be redefined in T3X programs. This
also applies to global symbols (symbols which are declared at
the top level, outside of procedure definitions, classes, or
statement blocks). Hence, shadowing can never happen in T3X. The
flexibility of local symbols remains, though, since names can be
reused as soon as a local data object has been destroyed:
F(x,y) DO VAR i, j;
! ...
END
G(x,y) DO VAR i, j; ! The names x,y,i,j are re-used
! ...
END
As shown in this example, symbol names may be reused in procedure
definitions (for formal argument names) as well as in subsequent
compound statements. Since the variables i and j will be
destroyed at the end of the compound statement forming the body
of F, they can be reused in G. The same is valid for the
argument names x and y.
The following example shows some local and global symbols and
their scopes.
+++ VAR GX, GY;
|
| CLASS A() +++
| STRUCT C = R,G,B; | C
| PROC | L
| P(x, y) +++ | A
| DO VAR x1, x2; +++ | | S
| END --- --- | S
| END BLOCK ---
|
G | P(x, y) DO VAR x1, y1; +++
L | |
O | STRUCT PT = PX, PY; |
B | BLOCK |
A | DO VAR i, j; +++ | P
L | DO VAR x2, y2; +++ | | R
| END --- | | O
| | | C
| DO VAR x2, y2; +++ | | E
| END --- | | D
| END --- | U
| | R
| DO CONST t=%1, f=~t; +++ | E
| DO VAR x2, y2; +++ | |
| END --- | |
| END --- |
--- END ---
Fig.1 Scopes (example)
Like all symbols, the global variables GX and GY are valid from
the point of their declaration, but unlike locally declared
names, they remain existent up to the end of the program. Their
scope is the entire program, from the point of their declaration
to the end of the file. The scopes of all symbols in the example
are illustrated using vertical bars. Plus signs indicate the
point where a symbol name becomes valid and its storage is
allocated, and minus signs mark the point of its destruction.
Note: the names X2 and Y2, which are used in different scopes,
denote different variables. A value stored in X1 within the
first scope, for example, cannot be retrieved in the second or
the third scope from X1, because the name references different
locations in different scopes. The variable that is created at
the beginning of the first scope containing X1 is deleted at the
end of this scope and the value stored in that variable is lost.
Assignments to local variables only remain valid between two
connected +++ and --- indicators.
All symbols that are defined in a so-called 'class contexts'
(between the keywords CLASS and the matching scope terminator
END) are only valid inside of this context. Both, the structure
C and the procedure P defined in the class A are only valid
inside of the class context of A. There exists no conflict
between A.P the method P of A and the procedure P which is
defined at the top level. Class contexts will be discussed in
detail in the section on object oriented programming in T3X,
later in this document.
2.7.8 Empty Statements
There are two forms of the 'empty statement' (aka 'null
statement') in T3X. The first form is the single semicolon
;
and the second one is the empty compound statement:
DO END
Both null statements have absolutely no effect. Their only
purpose is to fill a gap where a statement is required, but
nothing is to do. They are useful to negate the meanings of
complex conditions, for example. Instead of negating the
condition at the cost of making it harder to understand, one
might turn
IF (\(complex-condition)) statement
into
IE (complex-condition)
;
ELSE
statement
2.8 Procedures
Each procedure may be considered to be a separate small program.
It communicates with other procedures using parameters and
return values and/or through global variables. Each procedure
has access to all global data objects which have been declared
before itself. Generally, it is considered good style in
procedural languages to keep procedures self-contained and use
global storage as little as possible, but when data has to be
shared between a big number of different procedures, the use of
top-level definitions is very common and more efficient.
The definition of a procedure has only one single form in T3X.
Since there is no support for nested routines, all procedure
declarations and definitions must occur at the top level (the
space between the other global declarations) or in class
contexts. Public procedures declared in class contexts are
called methods. They will be explained later.
The only form of the procedure definition is
name(a1, ... aN) statement
where 'name' is the name of the procedure, 'a1', ... 'aN' are
the names of its formal arguments, and 'statement' is the body
of the procedure - the part which describes what it does.
The procedure name may be any valid symbol and it is declared in
the global context. Therefore, procedure names may not be reused
ever. One advantage of T3X's strict scoping rules is that
procedures cannot get shadowed. The arguments 'a1',... 'aN' are
local to the procedure (not local to the statement forming its
body). Their names will cease to exist after the statement has
been accepted. Hence, they may be reused after the procedure
declaration, but not inside of it. The parentheses around the
argument list must always be specified, even if the list is
empty:
name() statement
The number of arguments specified in a procedure declaration
determines the type of the procedure. The type of a procedure is
an integer number that specifies the number of its arguments. In
T3X, the argument counts of all procedure calls will be checked
against the procedure type. The compiler will not allow calls
with a wrong number of parameters. This is done because of T3X's
calling conventions: parameters are passed from the left to the
right, which places them on the stack in reverse order. Each
procedure must on receive the correct number of arguments, or
rhe mapping from local addresses to arguments does not work.
BCPL and C, on the other hand, pass arguments from the right to
the left, which allows to compensate for missing or superfluous
procedure parameters. The only real advantage of this approach,
however, is the option of defining variadic procedures -
procedures with a variable number of arguments. Variable
argument lists can also be realized in T3X, but using a
different mechanism that will be explained later.
When a procedure is called, it can receive data through its
arguments. This works in the following way. Given a procedure
P(x, a, b, c) RETURN a*x*x + b*x + c;
and a procedure call
Q() VAR y; y := P(2, 3, 5, -7); END
the caller (Q) places the values of the actual arguments 2, 3,
5, and -7 in a temporary storage location on the runtime stack,
saves the address of the following operation (in this case the
assignment) and then transfers control to the procedure P. In P,
the formal arguments x, a, b, and c reference storage locations
which exactly match the temporary locations of the values passed
to the routine, so that X=2, A=3, B=5, and C=-7.
The procedure P then computes a*x*x+b*x+c and returns the
resulting value to the caller. Each procedure returns
automatically when its body has been evaluated completely or
when an explicit RETURN statement is executed. In the above
example, both happens at the same time. It is not unusual to
specify a RETURN statement at the end of a procedure, since only
RETURN may pass an explicit value back to the caller. Procedures
that do not return through RETURN have an implicit return value
of zero. In the example above, though, the value of P is
explicitly specified. After passing control back to the caller,
the assignment takes place, and the result of the procedure call
is stored in Y. Between the procedure return and the subsequent
assignment, the temporary storage where the actual arguments
were held is released again.
The most frequently used form of the procedure has a body
consisting of a compound statement:
fib(n) DO VAR f, i, j, k;
f := 1;
j := 1;
FOR (i=1, n) DO
k := f;
f := j;
j := j+k;
END
RETURN f;
END
Note: The variables declared at the beginning of the procedure
VAR f, i, j, k;
belong to the compound statement rather than to the procedure.
Like in conditional statements and loops, the statement block is
used to extend the scope of the procedure: not only a single
statement, but a group of statements forms the body of the
routine.
2.8.1 Recursive Procedures
It is perfectly safe for a procedure to call itself. Since the
declaration of a procedure takes place while parsing its head
(consisting of its name and its argument list), the declaration
is already in place, when the compiler processes the body.
Therefore, a procedure may recurse:
factorial(n) RETURN n = 0-> 1: n * factorial(n-1);
This small example computes N! or 1 * 2 * ... * N. For the
trivial case N=0, it simply returns 1. To compute N! where N>0,
it first computes (N-1)! and then multiplies the result by N.
To compute the factorial of N-1, it calls itself. Since the
value of the argument of the recursive call is decremented by
one at each level of recursion, it will finally reach 0 and the
procedure will start returning.
Recursion is safe in T3X, because local variables (which include
formal arguments) are created freshly each time a declaration is
passed. Therefore, the symbol N in the above example denotes
different variables at each level of recursion. The following
program is a modified factorial procedure that illustrates this
principle.
MODULE visual_fac(util);
OBJECT u[util];
fac(n) DO VAR b::30;
IE (n = 1) DO
u.printf(" 1", 0);
RETURN 1;
END
ELSE DO
u.printf(" %D *", [(n)]);
RETURN n * fac(n-1);
END
END
DO VAR b::80;
u.printf("fac(7) =", 0);
u.printf(" = %D\n", [(fac(7))]);
END
When executed, this program will print
fac(7) = 7 * 6 * 5 * 4 * 3 * 2 * 1 = 5040
It is left as an entertaining exercise for the reader to find
out how the process works.
Of course, the usual caveats concerning the use of global memory
and other shared resources in recursive procedures also apply in
T3X,
2.8.2 Mutually Recursive Procedures
Recursive procedures which depend on each other are called
'mutually recursive'. Mutual recursion introduces the following
problem: Given the procedures
A(x) IF (x > 0) B(x-1);
B(x) IF (x > 0) A(x-1);
which depend on each other, it does not matter which one is
declared first - one will always be inaccessible from within the
other. In the above example, B is undefined in A because it is
declared after A. When swapping the definitions, A will become
undefined in B.
The problem is solved by introducing 'forward declarations',
which may introduce a procedure before actually declaring it.
A forward declaration makes a procedure symbol known to the
compiler, but does not associate any meaning with with it.
To forward-declare a procedure, the DECL statement is used:
DECL name(type);
Like in most declaration statements, any number of
comma-separated declarations may be included in a single DECL
statement. 'Name' is the name of a procedure to declare and
'type' is a constant expression specifying the number of formal
arguments of that procedure. This value is required to type
check forward calls to the procedure. The number of formal
arguments in a subsequent declaration must exactly match the
type specified in the forward declaration, or a redefinition
error will be signalled.
Each names used in a forward declaration may only be re-used in
one single procedure declaration. Declaring a procedure without
defining it later is an error, since this may leave forward
references to the forward-declared procedure unresolved.
To correct the above program fragment containing the mutually
recursive procedures A and B, a forward declaration of B has to
be inserted before the declaration of A:
DECL B(1);
A(x) IF (x > 0) B(x-1);
B(x) IF (x > 0) A(x-1);
Like procedure definitions, DECL statements are only allowed at
the top level and in class contexts, but not inside of local
scopes.
2.8.3 Variadic Procedures
All procedures have fixed numbers of arguments in T3X. It is
possible, however, to pass a variable number of arguments to a
procedure using a dynamic table. The following simple example
computes the average of N values stored in the vector V:
average(n, v) DO VAR i, k;
k := 0;
FOR (i=0, n) k := k + v[i];
RETURN k/n;
END
Since vectors are first-class objects in T3X, it is possible to
inline vectors in procedure applications, thereby forming an
elegant way of passing a variable number of values to a
procedure:
average(5, [ 2, 3, 5, 7, 11 ]);
average(3, [ (fib(10), fac(5)), 789 ]);
Another example is illustrated below. The T3X method PRINTF
of the utility class UTIL is a variadic procedure that
implements of a subset of of the standard C library procedure
printf(). The FIB procedure has been defined earlier in this
chapter. Using these procedures, it it possible to write the
following program that prints the line
fib(n) = m
for each N = 1,... 20 and M = fib(n):
MODULE print_fib(util);
OBJECT u[util];
DO VAR i;
FOR (i=1, 20)
u.printf("fib(%D) = %D\n", [(i, fib(i))]);
END
UTIL.PRINTF replaces each %D in its first argument with the
readable representation of one of the value in the table forming
its second argument. Each time a %D is processed, the procedure
advances to the next argument. A C version of the program would
use a variable number of arguments while the T3X version uses a
dynamic vector to transport a variable number of values.
BTW: both printf() and UTIL.PRINTF use the number of %-patterns
to determine the number of arguments passed to it.
2.9 The T3X Object Model
Like many popular object oriented languages T3X is a hybrid
language. A hybrid language is a language incorporating (at
least) two different paradigms. T3X uses the object oriented
approach at a rather abstract level and the procedural approach
at the lower levels. For example, numbers are no objects in T3X
and adding numbers is not done by sending messages. In a purely
object oriented language, the term
5 + 7
would be interpreted as send the message '+' with the argument
'7' to the object '5'. In a procedural language, however, adding
numbers is done by combining the factors '5' and '7' using the
'+' operator. Interpreting numbers as objects and expressions
as messages makes no sense in a procedural language, since
numbers and operators are not implemented this way. There are
many hybrid languages employing both the procedural and object
oriented approach. For example, C++, Java, and Object Pascal fit
in this category. A well-known member of the family of purely
object oriented languages would be Smalltalk.
2.9.1 Object Oriented Programming
There are various definitions of the object oriented programming
(OOP) paradigm. The term 'object oriented' has become an umbrella
term for all kinds of approaches to abstraction and code reuse.
At the very foundation, an object oriented language encapsulates
code and data declarations in templates called 'classes'. A
class contains data declarations, procedures, and public
procedures ('methods') that form an interface to the data
contain in the class. Each class can be instantiated by
declaring an 'object' or 'instance' of that class. Each object
contains all the data objects declared inside of its class. Note
that the term 'object' is used to refer to instances of classes
in this section. Variables and vectors are referred to as 'data
objects'. Only procedures defined in its class may access the
data contained in an object. No procedure that is not contained
the class of an object may ever access data of the object.
This principle is called encapsulation. It is a fundamental
property of the OOP paradigm. In T3X, encapsulation cannot be
broken or bypassed in any way. This property is called 'strict
encapsulation'
Each class may have multiple instances. In this case, each
object of the class has its own private data area that is
separate from the data areas of other instanced of the same
class. This is why classes can be reused. Manipulating the data
of one object has no effect on other objects of the same class.
Methods of classes are invoked by sending messages to objects of
that class. A message is similar to a procedure call. It may
transport arguments 'into' the object and the method may return
a value to the caller. Since the method is part of the class of
the object, it is allowed to access all data objects inside of
the object. Therefore, methods provide a clean and abstract
interface to the data of the object. The data structure itself
is hidden from the user and may change without changing the
interface.
Other OO languages define additional concepts like inheritance,
protected and public variables, friend relationships, class
variables, etc, but the T3X object model is limited to
- Classes
- Objects
- Messages
This is all that is needed to define reusable programs at a high
level of abstraction.
2.9.2 Classes
The general forms of the class declaration are as follows:
CLASS classname() declarations END
CLASS classname(required, ...) declarations END
The context of a class is delimited by the class header
(consisting of the keyword CLASS, the name of the class, and the
dependency list in parentheses) and the keyword END. Inside of
this context, there may be any number of declarations. These
types of declarations are allowed inside of class contexts:
- Variables
- Constants
- Structures
- Public constants
- Public structures
- Procedures
- Public procedures (methods)
- Forward declarations
- Objects
Nested classes are not defined in the T3X object model.
All declarations between CLASS and END are local to the class.
Therefore, classes add an additional level of scoping between
the global level and the procedural level. All data objects and
procedures declared inside of a class are only visible inside of
that class. The names of entities declared at class level may be
reused outside of the scope of the class. Hence different
classes may define data objects, procedures and even methods
with equal names. The following example illustrates this
principle.
CLASS a()
VAR flag;
PUBLIC flip() flag := \flag;
END
! the scope of class A ends here.
CLASS b()
VAR flag;
PUBLIC flop() flag := \flag;
END
This example defines two classes A and B each defining a
variable named 'flag'. At the end of the scope of A, all
declarations of A become invisible (encapsulated) and so the
name 'flag' may be reused in B. Since the procedure 'flip' is
contained in the same scope as 'flag', it may access the 'flag'
of A. In the same way, the procedure 'flop' may access the
'flag' of B. The two variables named 'flag' are different
entities, though, since they are contained in different classes.
Like structures, classes are merely templates for data objects.
They describe the layout of a data structure plus a set of
methods that may be used to access elements of the structure.
The size of a class is computed in the same way as the size of a
structure: it is equal to the sum of the sizes of all class
members. In expressions, the name of a class is a constant
evaluating to the size of the class. Classes without any
instance variables have a size of one machine word.
The only way to change the state of a class from the outside is
to send it a message. T3X supports a simplified form of the
method called a 'class constant'. Class constants may be thought
of as lightweight methods returning a constant value. They allow
to export values and structures without having to send a full
message. OO systems that do not allow to change the state of an
object without sending a message are said to employ strict
encapsulation. Strict encapsulation in T3X is illustrated in the
following figure.
+--------------------------------------------+
| |
| M e t h o d s |
| |
| +--------------+ |
| | Variables | |
| +--------------+ |
| | Constants | |
| +--------------+ |
|--------------| Structures |--------------|
| +--------------+ |
| | Procedures | |
| +--------------+ |
| | Objects | |
| +--------------+ |
| |
| C l a s s C o n s t a n t s |
| |
+--------------------------------------------+
Fig.2 Strict Encapsulation
No data objects of a class are visible from the outside. Only
methods (including class constants) are visible.
2.9.3 Objects
Objects are used to instantiate classes. An OBJECT statement is
to a CLASS declaration what a VAR statement is to a STRUCT
declaration. While the class defines the layout of an object,
the OBJECT statement actually creates an object in memory. The
general form of the object definition is as follows:
OBJECT an_object[a_class], ... ;
Any number of objects may be defined in a single OBJECT
statement. Each class may be instantiated any number of times
and different classes may be instantiated in the same statement.
The name of the object to create is specified before the square
brackets and the class of the object inside of the brackets:
OBJECT str[string];
creates an object of the class STRING named STR.
An object may be a factor in an expression. It evaluates to the
address of its first member. The notations
objectname
and
@objectname
are equivalent.
When creating multiple instances of a class, only space for the
data declarations of the class is created. The methods of a
class belong to the class itself rather than the object. They
are created when a class is declared.
The only way to alter the state of an object is to send it a
message. Therefore, in an ideal OO program the state of each
object is completely independent from the states of other
objects, even if they belong to the same class. In a hybrid
language like T3X, however, the procedures of a class may change
data objects defined in the global scope. Changing a global
object from within an object changes the state of all other
objects of the same class (and maybe even the state of objects
of other classes). Therefore, this technique is deprecated. Of
course, there are situations where an object has to change the
global state, for example when performing input/output
operations. Classes defining such objects are said to have
'global effects'.
2.9.4 Modules and Class Dependencies
In order to create an instance of a class A inside of a class B,
the class B must require the class A. In this case, B is said to
depend on A. The simplest scenario contains two classes which
are defined inside of the same file:
CLASS a()
! definitions of A
END
CLASS b(a)
OBJECT xa[a];
END
Since B instantiates A, it must require A. A class is required
by including its name in the dependency list of the class header
of the dependent class. Requiring a class has two effects:
- it embeds information about the required class in the name
space of the dependent class
- it allows procedures of the dependent class to send messages
to instances of the required class
Things get a little more complex, if the dependent class and the
required class are located in different files. Since class names
are contained in the global scope, they are lost as soon as the
compiler has finished the translation of the file in which they
are contained. Hence the required class would be unknown when
the compiler translates the file containing the dependent class.
To allow classes to be located in different files, an additional
level ABOVE the global scope is added. It is called the 'public
scope' and it persists even when compilation of a file finishes.
To add a class to the public scope, two steps are necessary.
First, the file must have a module header which names the file.
A MODULE statement has the following general form:
MODULE module_name (required, ...);
The module name specified in the module header must be the same
as the actual name of the file containing the module (but not
including the .t suffix). If, for example, the class A is
located in a file named tools.t, the module header would look
like this:
MODULE tools();
The parentheses after the module name serve the same purpose as
in class declarations: they delimit a dependency list. This list
may be ignored for now. The module header allows the compiler to
locate the definition of a class, even if multiple classes are
contained in a single file. If files were named after classes,
only a single public class could be declared per file.
The second step required to export a class to the public level
is to prefix its class header with the keyword PUBLIC:
PUBLIC CLASS a()
The following example shows the contents of two files 'file_a'
(containing the required class A) and 'file_b' (containing the
dependent class B). When compiling file_a, A is exported to the
public level. When compiling file_b, A is imported from the
public level when it is required by B.
MODULE file_a(); MODULE file_b();
PUBLIC CLASS a() CLASS b(a)
! definitions OBJECT xa[a];
END END
Another purpose of the MODULE statement is to provide an
interface between the procedural and the object oriented parts
of T3X. If only classes could require classes, it would be
impossible to instantiate a class inside of a T3X program, since
the main program is a procedure. To instantiate a class in a
procedural program, it is added to the dependency list of the
module wishing to instantiate the class. It does not matter
whether the required class is a public class contained in a
different module or a 'private' class contained in the same
module. In the latter case, however, the MODULE statement must
be located after the class declaration. The following example
shows a procedural program sending a message to a class.
CLASS A(t3x) ! class A depends on the T3X core class
OBJECT t[t3x]; ! instantiate T3X class
! The method M will print some text
! using the WRITE method of the T3X class
PUBLIC m() DO
t.write(T3X.SYSOUT, "A: received m.\n", 15);
END
END
MODULE main(A); ! the main module requires A,
DO OBJECT xa[A]; ! instantiates it,
xa.m(); ! and sends a message to it
END
2.9.5 Methods and Messages
Messages are used to access the data of an object from the
outside, which includes altering its state. Procedural programs
are sets of procedures calling each other. Object oriented
programs are a set of objects sending messages to each other.
Sending a message to an object activates a public procedure
defined in the class of the object. A method definition looks
like a procedure definition with the keyword PUBLIC attached:
PUBLIC name(arguments) statement
Method definitions are only valid in class-level scopes.
A message is sent to an object using the syntax
objectname.methodname(arguments)
Messages may be factors in expressions or standalone statements.
When used as statements, they must be terminated with a
semicolon:
objectname.methodname(arguments);
The arguments of a method are passed in the same way as the
arguments of a procedure and, like a procedure, a method returns
a value. The difference between an 'ordinary' procedure and a
method is that a method changes the 'instance context' upon
entry. The instance context points to an instance of the set of
data objects defined in a class. It is comparable to local
contexts of procedures: when a procedure is entered, it creates
a new local scope and when it leaves, it restores the caller's
context. Unlike a local scope, the instance context is
persistent, though. Therefore, methods do not create a new
instance context, but just activate an existing one. The
caller's context is saved upon entry on the runtime stack and
restored when the method returns. Since instance contexts are
persistent, the changes performed by methods are permanent.
Each object has its own instance context, which is divided into
the data objects declared in its class. Methods use the instance
context to access class-level data. By changing the instance
context upon entry, each object accesses only its own private
data. The instance context may be thought of as a multiplexer.
The principle is illustrated in the following figure:
Class A Access V
+------------+ |
| Method M | |
| ... | V
| Variable V | +----------------+
| ... | | Method M |
+------------+ +----------------+
|
|
V
+--------------------+
| Instance Context |
+--------------------+
| |
| |
,--------' '--------,
| |
V V
+---------------+ +---------------+
| V of X[A] | | V of y[A] |
| ... | | ... |
+---------------+ +---------------+
Object X[A] Object Y[A]
Fig.3 Multiplexing Method Applications
In this figure, class A defines a method M which accesses the
instance variable V that is also declared in A. The instance of
V accessed by M depends on the object to which the message is
sent. Sending X.M(), results in accessing the V of X and sending
Y.m() results in accessing the V of Y.
In T3X, the current instance (the currently active instance
context) can be referred to using the symbol SELF. SELF is a
pseudo-variable that always refers the object owning the current
instance context. Therefore, SELF may only be used inside of
procedures local to classes. Using SELF, an object may send a
message to itself, as shown in the next example
CLASS math()
PUBLIC prod(i, j) DO VAR p;
p := 1;
FOR (i=i, j+1) p := p*i;
RETURN p;
END
PUBLIC fac(n) RETURN self.prod(1, n);
END
In this example, the method 'fac' of the class 'math' uses the
method 'prod' of the same class to express the factorial of N by
sending the message prod(1,n) to itself. Methods may recurse,
too, since they are basically procedures. Therefore, 'fac' could
as well be defined in this way:
PUBLIC fac(n) RETURN n < 1-> 1: n * self.fac(n-1);
Because objects are basically vectors, they may be passed to
procedures (or methods) as parameters. By passing an object to a
procedure, however, the object loses its type information, since
the pointer to the object is stored in a typeless argument
variable by the callee. To be able to send messages to such
objects, the SEND operator is introduced. Its general form is
SEND(variable, classname, methodname(arguments))
This operator sends the message methodname(arguments) to the
object of the class 'classname' pointed to by 'variable'. For
example, the statement
y := m.fac(5);
is equal to
pm := @m;
y := SEND(pm, math, fac(5));
The caveats regarding indirect calls to procedures via CALL also
apply to the SEND operator. In addition to providing the correct
number of arguments, the programmer also has to make sure that
the message is sent to the right type of object.
2.9.6 Class Constants
Constants may be public as well:
PUBLIC CONST symbol = constant_expression;
Such constants can be accessed from outside the class by sending
a special form of a message to the class which defines the
constant. Given the constant MAXLEN of the class STRING:
PUBLIC CLASS STRING()
PUBLIC CONST MAXLEN = 32767;
END
the expression
STRING.MAXLEN
would be used to access the value of MAXLEN. So the general
form of the class constant access is
classname.constname
The 'classic' way of exporting such a constant would be to
define a method returning the constant:
PUBLIC maxlen() RETURN 32767;
Class constants have the advantage of saving a procedure call.
They can also also be used in constant expression contexts,
because their values are known at compile time.
Structures can be exported in the same way as constants:
PUBLIC STRUCT structname = member1, ..., memberN;
Public structures are useful for objects requiring arguments in
structured form or returning values in this form. For example,
the SYSTEM.STAT function (the function STAT of the SYSTEM class)
returns a structure containing information about a specific
file. In addition, the SYSTEM class provides a public structure
describing the layout of the structure returned by the STAT
function. This structure allows programs using the SYSTEM.STAT
function to decompose the returned information.
Since class constants cannot be altered, they do not break the
strict encapsulation principle. Public structures are an
interface and an implementation at the same time. Since the same
PUBLIC STRUCT statement is used to define the same structure
internally and externally, the interface changes automatically
when the implementation changes.
2.10 Interface Classes
An interface class is a class depending on an external object
file called an extension object. Extension objects may be linked
against the Virtual Tcode Machine or against native code
generated by the T3X compiler.
The declaration of an interface class begins with an ICLASS
statement. This statement has the following general form:
ICLASS class_name ("extension_object_name")
Class_name is the name of the class to declare and
'extension_object_name' is the name of the object file holding
the code of the interface class. The name of the object file
should be specified without any suffixes such as '.o' or '.lib'.
Like other class contexts, interface class contexts are
terminated with the keyword END.
2.10.1 Interface Declarations
In addition to the declarations allowed in class contexts,
interface classes may contain so called interface declarations.
An interface declaration describes an interface procedure
contained in an extension object. Any number of interface
procedures may be declared in a single IDECL statement:
IDECL name(type, call_map), ...;
'Name' is the name of an interface method to declare and type is
the number of arguments of that method. 'Call_map' describes the
types of the parameters passed to the interface procedure. It
is a bit map where each bit is associated with a procedure
argument as outlined in the following table.
Argument Call Map Argument Call Map
Number Value Number Value
-------- -------- -------- --------
1 0x0001 9 0x0100
2 0x0002 10 0x0200
3 0x0004 11 0x0400
4 0x0008 12 0x0800
5 0x0010 13 0x1000
6 0x0020 14 0x2000
7 0x0040 15 0x4000
8 0x0080 16 0x8000
Each bit with a value of zero denotes an atomic (numeric)
argument and each bit that is set to one denotes a vector
argument (a pointer in the argument list of a corresponding C
function). For example, the C function _spawn() of the
extension object system could be defined as follows:
xcell system__spawn S3(prog, args, wait)
SELF
char *prog;
char **args;
xcell wait;
{
/* code of system__spawn() */
}
The S3() macro is used to generate argument lists of three
arguments. Similar macros exist for declarations of functions
with up to 7 arguments. They are called S0(), ..., S7(). The
Sn() macros reverse the supplied argument lists to meet the T3X
calling conventions and supply a dummy argument to intercept the
additional instance context parameter that T3X programs pass to
each method.
Do use the Sn() and SELF macros. Otherwise, interface procedures
will not work.
'Xcell' is a macro expanding to the type of a signed cell
(integer) of the same size as a pointer.
All macros discussed here are defined in the 'txx.h' header
file. The file 'txx.h' also contains some other macros which are
useful for implementing interface procedures.
The first and second argument of _spawn() are pointers and so
the bits 0x0001 and 0x0002 in the call map have to be set. This
leads to the following interface declaration:
ICLASS system("system")
...
IDECL _spawn(3, 0x0003);
...
END
The call map is required to translate vector addresses to native
pointer size before passing them to interface procedures. Call
maps are limited to 16 bits, so interface procedures may not
have more than 16 arguments.
NOTE: when passing vectors of pointers to interface procedures
(like 'char **args' in system__spawn()), the vector of pointers
must be converted to native pointer size as well. The T3X core
method T3X.CVALIST performs this operation.
2.10.2 Calling Interface Procedures
To the T3X programmer, an interface procedure is a method of an
interface class. In order to invoke an interface procedure, the
interface class is instantiated a message is sent to the
resulting object:
ICLASS world("world_code")
IDECL hello(2, 1);
END
MODULE test(world);
OBJECT aworld[world];
DO
aworld.hello("Hello, world!\n");
END
2.10.3 A Sample Interface
The HELLO method used in the previous subsection could be
implemented as follows:
/* world_code.c */
#include <txx.h>
#include <string.h>
xcell world_hello S2(s, n)
SELF
char *s;
xcell n;
{
while (n--) {
write(1, s, strlen(s));
write(1, "\n", 1);
}
return 0;
}
The proper arguments to compile this code to an extension
object depends on the host environment. However, the following
requirements must be met:
- the code must be compiled to a relocatable object file
- the include path of the txx.h file must be specified
- the LIBRARY macro must be defined, if compiling to an
extension object
- the LIBRARY macro must be undefined, if the interface
procedures in the module will be linked against the Virtual
Tcode Machine
To compile the above interface code to an extension object on a
generic Unix system, a command like this may be used:
cc -o world_code.o -I /usr/local/include -DLIBRARY \
-c world_code.c
When compiling an object to be linked against TXX, -DLIBRARY
should be omitted.
2.11 Scoping Rules
Scoping rules define the contexts in which symbols are valid and
under which conditions they may be redefined. In T3X, there are
five different contexts and very strict and simple redefinition
rules:
(1) The public context contains public classes and the public
entities defined in their contexts. It contains all public
elements exported by a set of modules. The public context is
persistent. It is not even destroyed when the compilation of a
program ends. The public context may contain any number of
global contexts.
Technical point: To purge the public symbol table, the storage
holding the table (usually a file) must be cleared (e.g. by
deleting the file or truncating it to zero length).
(2) The global context covers a complete file or module. Its
declarations are located in the space between procedures and
class definitions. Each global context may contain any number of
class contexts or procedure contexts.
(3) A class context contains all symbols that belong to a
specific class. They are delimited by a class header (CLASS ...
or ICLASS ...) and the keyword END. Each class context may
contain any number of procedure contexts.
(4) A procedure context is equal to the argument list of a
procedure plus the statement forming the body of the procedure.
The argument list is a list of implicit atomic variable
declarations. No other entities may be defined in this context.
A single block context (forming the body of the procedure) may
be embedded in each procedure context.
(5) A block context begins with the keyword DO and ends with the
keyword END. Each block context may contain any number of nested
block contexts. Notice that this definition is recursive, so that
blocks may be nested to any level. A block context is called
block^N context, if there are N enclosing blocks.
The following redefinition rules apply:
(1) Each public class and the entities defined in its context
may be redefined once inside of the module containing the
original definition.
This happens when a module containing public classes is
recompiled. In this case, the definitions in the public context
are silently updated.
(2) Each symbol used in a forward declaration (DECL statement)
may be redefined by a one single matching procedure definition.
(3) Except for forward declarations and public entities, no
symbol may be redeclared or shadowed ever:
- Global names may not be reused at class level, procedure
level, or at block level.
- Class level names may not be reused at procedure level or at
block level.
- Procedure level names may not be reused at block level.
- Block level names may not be reused in embedded blocks.
The following figures illustrates the different scopes.
+-- Public ------------------------------------+
| +-- Global --------------------------------+ |
| | +-- Class -----------------------------+ | |
| | | +-- Procedure ---------------------+ | | |
| | | | +-- Block^0 -------------------+ | | | |
| | | | | +--- ... ------------------+ | | | | |
| | | | | | | | | | | |
| | | | | | +-- Block^N -----------+ | | | | | |
| | | | | | | | | | | | | |
| | | | | | | | | | | | | |
| | | | | | | | | | | | | |
| | | | | | +----------------------+ | | | | | |
| | | | | | ... | | | | | |
| | | | | +--------------------------+ | | | | |
| | | | | ... | | | | |
| | | | +------------------------------+ | | | |
| | | +----------------------------------+ | | |
| | +--------------------------------------+ | |
| +------------------------------------------+ |
+----------------------------------------------+
Fig.4 Scopes (overview)
2.11.1 Scoping Conflicts
At the end of a class context, all names contained in that class
context as well as the classname itself will be removed from the
global context. However, the class name will be memorized at a
different location and may never be reused in the same program.
This is a workaround for an ugly inconsistency resulting from an
interference with the module system. Imagine the following
situation:
CLASS A() ... END
A() DO ... END
CLASS B(A) ... END
In this case, the class B would depend upon the procedure A
which would be a type error. On the other hand, if the name A
would persist, the following code would be correct:
CLASS A() ... END
CLASS B()
OBJECT XA[A];
END
In this case, class B could use class A without being dependent
on it, which would break class dependencies, because the module
extension requires that B be dependent on A in this case.
Therefore, the (admittedly hackish) solution of not permitting
the reuse of (deleted) class names has been chosen.
2.12 Type Checking
In T3X, there are only very few type checking mechanisms to
detect things like assignments to constants, calls of
non-procedures, etc. Including the 'class' and 'object' meta
types, T3X has seven different types on which only specific
operations are allowed. Type-related semantic checks carried out
by the compiler intercept the following errors:
- Assigning values to constants
- Calling non-procedures
- Calling procedures with incorrect argument counts
- Creating objects of non-classes
- Sending messages to non-objects
- Sending non-messages to objects
- Sending messages with incorrect argument counts
- Creating dependencies on non-classes
In a truly object oriented language with first class objects,
however, more extensive type checking would be required. When,
for example, an object is passed to or returned by a function,
the passed value becomes a first class value which may be
assigned to a variable. No type information would be associated
with such a variable in T3X. Therefore, the compiler could not
determine the set of messages accepted by this object. This
problem has been solved by not allowing to send messages to any
type of data object other than the object, but the SEND operator
may be used to circumvent this restriction. Like the CALL
operator, SEND has to be used with special care.
The following table contains an overview over the operations
which may be applied to each type or entity:
Type / Oper. Asg Sub Call Inst Recv Send
---- ----- --- --- ---- ---- ---- ----
Constant no no no no no no
Variable yes yes yes (+) no yes (*) no
Vector no yes no no no no
Procedure no no yes no no no
Class no no no yes yes (#) no
Object no no no no yes no
Method no no no no no yes
Asg = assignment, Sub = subscript, Inst = instantiation,
Recv = receive messages, Send = send as message
(+) Using the CALL operator
(*) Using the SEND operator
(#) Using class constants
In addition, any of the above types can be evaluated, yielding a
value. This is the value assigned to a constant, the content of
an atomic variable, the size of a class or structure, and the
address of each other kind of entity (vector, packed vector,
procedure, method, object).
2.13 Meta Commands
Meta commands are used to control the behavior of the compiler.
No code will be generated for meta commands. Meta commands do
not even belong to the T3X language itself and different
implementations may provide different sets of meta commands. The
commands described in this section should be present in any
implementation of the language, though.
All meta commands begin with a hash sign (#) and like all other
statements, they are terminated with a semicolon. They may occur
at any place where a statement or a declaration (either local or
global) is expected, but not inside of statements or
declarations. The following meta commands exist:
#CLASSPATH "path";
This command specifies an alternative path for searching class
files. Normally, the translator searches class files in the
current working directory and in some compiled-in paths. When
bootstrapping the compiler or running it in some other
non-standard environment, it may be necessary to specify the
class path explicitly using this command. Only one path may be
specified. When using multiple #classpath commands, only the
last one will take effect. This solution is a makeshift and will
probably be combined with a more flexible technique in the
future. When a classpath is specified using this meta command,
it will take precedence over all other (built-in) class paths.
#DEBUG;
Turn on emission of debug information like source code line
numbers and variable names and addresses. When this option is
turned on, the T3X translator will generate a LINE instruction
at the beginning of each statement and LSYM, ISYM, or GSYM
instructions for each local variable, instance variable, or
global variable. Debug information is intended to be used by a
source level debugger.
2.14 The Main Program
Each program has an initial entry point where execution begins
at run time. In T3X, the entry point is a compound statement at
the top level which does not belong to any procedure context.
This compound statement is mandatory and it must always be the
last definition in the entire program. Subsequently, the
smallest valid T3X program is
DO END
The main procedure, like any other compound statement, may
declare its own local symbols. Since it has no name, it cannot
recurse, though. RETURN may not be used in it, because there is
no procedure to return to.
When execution reaches the end of the main procedure, the
program terminates and delivers a zero return code back to the
calling process.
Note that all modules have main procedures. When a program
consists of multiple modules, their main procedures will be
called in the order in which the modules are passed to the
Tcode loader. Hence the main module of a program should always
be compiled last (or at least be the last module passed to the
Tcode loader).
3. The Runtime Environment
Most of this chapter has been automatically generated from the
structured document 'classes.sd' which is contained in the T3X
Release 7 distribution.
There are three different types of classes: the core class,
native classes, and interface classes. To the programmer, there
is no difference between these types, but when implementing
additional runtime classes, it is important to know the
differences.
The T3X core class is in fact an ordinary interface class,
but it may contain special code to initialize the runtime
environment at startup time.
The native class is the most common type. Such classes are
written in T3X using the techniques described in the section
about the object oriented programming and modules. The major
part of the runtime system is implemented in this way. There is
no difference between a native class and a user-defined module.
Programs are linked against native classes by the Tcode linker.
Interface classes allow to add low-level (LL) functions to a
program. The LL functions themselves are written in a language
suitable for systems-level programming. The foreign language
code is compiled to a relocatable object or library.
Additionally, a native interface class must be defined to
describe the functions contained in the object holding the code.
A runtime class is linked into a program by requiring it either
at class level or at module level. For example,
CLASS foo(t3x, iostream)
would be the header of a class requiring the T3X core class and
the 'iostream' class, and the statement
module bar(t3x, char, string);
would require the core class plus the 'char' and 'string'
classes.
The following runtime classes belong to the T3X environment:
Name Type Description
-------- --------- ------------------------------
t3x core basic system routines
char native character manipulation
iostream native buffered I/O-streams
memory native dynamic memory management
string native string manipulation
system interface (mostly) portable system calls
ttyctl interface text terminal control
xmem interface external memory access
These classes will be explained in detail in the following
sections.
3.1 Meta Information
3.1.1 Object Names
The first section of each class description lists a sample
object declaration of the form
OBJECT objectname[classname];
where 'objectname' is used to form messages in the remainder of
the section.
Methods are referred to
- by a sample object name and their method name in descriptions
of their own class (eg T.OPEN in the description of the
T3X.CLOSE method)
- by their classname and their method name in other locations
(eg T3X.OPEN in the description of the SYSTEM class)
3.1.2 Argument Descriptions
Argument descriptions are given in the following format:
object.method(arg1, ..., argN) ! type1, ..., typeN => typeR
where
- 'object' is the name of the sample instance defined in the
first subsection of each class description
- 'method' is the name of the method described
- 'arg1' through 'argN' are symbolic names for the arguments of
the method
- 'type1' through 'typeN' are the types of 'arg1' through 'argN'
- 'typeR' is the type of value returned by the metod
In this context, 'type' is a rather weak attribute, since T3X is
a typeless language. In many cases 'type' means a pointer to a
structure with a specific layout.
The following types are used in this document:
Type Description
----- ---------------------------------------------
Bvec a vector of bytes
Char a byte, often representing an ASCII character
Ddesc a directory descriptor
Fdesc a file descriptor
IOS an I/O-stream
Num an integer value (a machine word)
Str a null-terminated string
Vec a vector
Return types may depend on the return status of a method. Such
cases are listed, for example, as
Fdesc | -1
meaning 'either a file descriptor or minus 1'. Literal numbers
in return types represent themselves.
3.2 T3X -- Core Routines
3.2.1 T3X Class Usage
OBJECT T[T3X];
The T3X class contains a set of procedures which provide access
to the most common operating system services, like opening,
reading, writing, and erasing files, copying and comparing
memory regions, receiving command line arguments, etc. The class
requires no explicit initialization or shutdown.
The T3X class does not contain any variables. Therefore, it is
sufficient to create a single instance per module.
3.2.2 T.BPW
T.BPW() ! => Num
Return the number of 'bytes per word' (BPW) on the host machine.
When running a Tcode program, this value will always be 2,
regardless of the host environment. When called by a native
machine program, the procedure will return the actual machine
word size of the target machine.
3.2.3 T.CLOSE
T.CLOSE(fdesc) ! Fdesc => Num
Close the file descriptor 'fdesc'. To obtain a valid file
descriptor, use T.OPEN.
T.CLOSE returns 0 on success and a negative value in case of an
error.
See also: T.OPEN, T.READ, T.WRITE, SYSTEM.DUP, SYSTEM.DUP2,
SYSTEM.PIPE
3.2.4 T.CVALIST
T.CVALIST(n, bmap, ilist, olist) ! Num,Num,Vec,Vec => 0
Convert a Tcode argument list to a native argument list. Since
the Tcode machine is a 16-bit architecture, argument lists may
need to be extended before passing them to machine code
procedures in non-16-bit environments.
Extending an argument list from 16 to 32 bits (or whatever is
appropriate on the host system) is done by zero-extending all
values in the argument vector to the size of a generic pointer
on the host machine and then adding the offset of the Tcode
machine's data area. The bitmap 'bmap' specifies the type of
each argument.
Argument lists must not be longer than 16 elements (plus a
trailing null word).
'N' specifies the number of elements in the argument list
'ilist'. If a trailing null is required, it must be included in
this number. 'Ilist' is a vector containing the arguments.
'Bmap' is a bit field where each bit is associated with an
argument of 'ilist'. A bit of 'bmap' is set if the associated
argument is a pointer: if bit #0 is set (bmap & 1), ilist[0] is
a pointer, if bit #1 is set (bmap & 2), ilist[1] is a pointer,
etc. 'Olist' will be filled with the extended argument list. It
must provide up to 18 times the size of a generic pointer in
bytes (which is usually equal to 18 machine words on the host
system). It may be allocated using:
VAR olist[18];
T.CVALIST may relocate 'olist' if it is not aligned to a native
machine word boundary. It returns the number of bytes 'olist'
was moved. This number should be used to compute the new address
of olist:
offset := t.cvalist(n, bmap, ilist, olist);
new_olist := @olist::offset.
When a negative count is supplied, the effect of T.CVALIST is
reversed. In this case, each member of 'olist' will be copied
to 'ilist', thereby truncating it to 16 bits. No pointers may
be processed in this direction. The 'bmap' argument is ignored
when converting argument lists this way.
T.CVALIST is used to prepare argument lists for passing them to
extension procedures. When a T3X program is run in an
environment where the size of a pointer is equal to the size of
a T3X machine word, T.CVALIST simply copies the argument vector.
SYSTEM.SPAWN uses T.CVALIST internally. Most programs do not
require its use.
See also: SYSTEM.SPAWN
3.2.5 T.GETARG
T.GETARG(n, buffer, size) ! Num,Str,Num => Num
Retrieve the 'n'th command line argument and store its first
'size'-1 characters in 'buffer'. If the length K of the
requested argument is less than 'size'-1, copy only K
characters. In either case, append a NUL character to the
argument string extracted.
T.GETARG returns the number of characters copied. A return code
of -1 indicates that a non-existing argument has been requested
('n' is too big).
See also: T.GETENV
3.2.6 T.GETENV
T.GETENV(name, buffer, size) ! Str,Str,Num => Num
Retrieve the value of the environment variable 'name' and store
up to 'size'-1 characters of its value in 'buffer'. Append a
NUL character to the text in 'buffer'.
T.GETENV returns the number of characters copied. A return code
of -1 indicates that a non-existent variable name has been
specified.
See also: T.GETARG
3.2.7 T.MEMCOMP
T.MEMCOMP(r1, r2, len) ! Bvec,Bvec,Num => Num
Compare up to 'len' bytes of the regions 'r1' and 'r2'. When a
mismatch is found during the comparison, the procedure returns
r1::p - r2::p
where 'p' is the position of the mismatch. When 'len' bytes
have been compared without encountering a mismatch, zero is
returned.
See also: T.MEMCOPY, T.MEMFILL, T.MEMSCAN
3.2.8 MEMCOPY
T.MEMCOPY(dest, src, len) ! Bvec,Bvec,Num => 0
Copy 'len' bytes from region 'src' to region 'dest'. The
regions may overlap.
See also: T.MEMCOMP, T.MEMFILL, T.MEMSCAN
3.2.9 T.MEMFILL
T.MEMFILL(region, val, len) ! Bvec,Num,Num => 0
Fill a region of 'len' bytes with the value of the least
significant byte of 'val'.
See also: T.MEMCOMP, T.MEMCOPY, T.MEMSCAN
3.2.10 T.MEMSCAN
T.MEMSCAN(region, val, len) ! Bvec,Num,Num => Num
Scan a region of 'len' bytes for 'val'. If the region contains
'val', return its offset (0...len-1) and otherwise return -1.
See also: T.MEMCOMP, T.MEMCOPY, T.MEMFILL
3.2.11 T.NEWLINE
T.NEWLINE(s) ! Str => Str
Write a system-dependent newline sequence to the string 's'.
The sequence will move the cursor to the beginning of a new
line when sent to terminal screens. The sequence written to 's'
will never be longer than four characters including the
terminating NUL character.
The result of writing T.NEWLINE to a screen may be undefined on
terminals in 'raw mode'.
T.NEWLINE returns a pointer to 's'.
See also: T.WRITE, TTYCTL.MODE
3.2.12 T.OPEN
T.OPEN(path, mode) ! Str,Num => Fdesc | -1
Open the file whose path is specified in 'path' in the given
'mode'. The exact format of 'path' depends on the operating
system. The following modes exist:
Mode constant ReadOK WriteOK Create Initial Position
------------- ------ ------- ------ ----------------
T3X.OREAD Yes No No 0
T3X.OWRITE No Yes Yes 0
T3X.ORDWR Yes Yes No 0
T3X.OAPPND Yes Yes No EOF
When T3X.OWRITE is specified and a file with the given name
already exists, it will be truncated to zero length.
T3X.OAPPND is like T3X.ORDWR, but the file pointer will be
positioned at the end of the file so that T.WRITE will append
its output to the file.
T.OPEN returns a file descriptor for accessing 'path' on success
and -1 in case of an error.
When a T3X program starts up, there already are some open file
descriptors which are by default connected to the user's
terminal:
Name Descriptor Mode
----------- --------------- ----------
T3X.SYSIN standard input read-only
T3X.SYSOUT standard output write-only
T3X.SYSERR standard error write-only
See also: T.CLOSE, T.READ, T.WRITE, T.SEEK
3.2.13 T.READ
T.READ(fdesc, buffer, count) ! Fdesc,Vec,Num => Num
Read up to 'count' characters from the file descriptor 'fdesc'
into 'buffer'. Return the number of characters read.
A return value less than zero indicates a severe error. A
return value which is less than 'count' usually indicates that
the end of the input has been reached.
When reading line oriented devices, such as terminals, a return
value below 'count' may indicate the end of a line. In this
case, a zero value indicates that the input stream is
exhausted.
For a summary of standard descriptors (system input and
output), see T.OPEN.
See also: T.OPEN, T.CLOSE, T.WRITE, SYSTEM.PIPE
3.2.14 T.REMOVE
T.REMOVE(path) ! Str => Num
Remove the directory entry specified in 'path'. The exact
format of 'path' depends on the operating system.
On systems supporting multiple links (names) for a single file,
this procedure will only remove the specified link. On such
systems, other links to the file may still be used to access
the file. Only when the last link is removed, the file will
become inaccessible. On other systems, T.REMOVE deletes the
given file immediately.
T.REMOVE returns zero, if the directory entry could be deleted
successfully and a negative value otherwise.
See also: T.RENAME, SYSTEM.OPENDIR
3.2.15 T.RENAME
T.RENAME(old, new) ! Str,Str => Num
Rename the directory entry whose path is specified in 'old' to
'new'. 'Old' and 'new' may describe names contained in
different paths. In this case, the directory entry will be
moved to the directory specified in 'new'. The old and the new
name of the directory entry must both reside on the same
physical device.
T.RENAME returns zero upon success and a negative value in case
of an error.
See also: T.REMOVE
3.2.16 T.SEEK
T.SEEK(fdesc, where, origin) ! Fdesc,Num,Num => Num
Move the file pointer associated with the file descriptor
'fdesc' to a new position. 'Where' specifies the desired
position and 'origin' specifies where the motion shall start.
The following origins are possible:
Constant Origin Distance
------------ --------------------- --------
T3X.SEEK_SET Beginning of the file +where
T3X.SEEK_FWD Current position +where
T3X.SEEK_END End of the file -where
T3X.SEEK_BCK Current position -where
T3X.SEEK_SET and T3X.SEEK_FWD move the file pointer forward,
T3X.SEEK_END and T3X.SEEK_BCK move it backward. In either case,
'where' is an unsigned value so that offsets may range from 0
to 65535 bytes.
T.SEEK returns zero upon success and -1 in case of an error.
The 'seek' operation may be undefined on sequential access
devices and pipes.
See also: T.OPEN, T.CLOSE, T.READ, T.WRITE
3.2.17 T.WRITE
T.WRITE(fdesc, buffer, count) ! Fdesc,Vec,Num => Num
Write 'count' characters from 'buffer' to the file descriptor
'fdesc'. Return the number of characters actually written.
A return value which is less than 'count' indicates a severe
error (such as insufficient space left on a device).
For a summary of standard descriptors (system input and
output), see T.OPEN.
See also: T.OPEN, T.CLOSE, T.READ, SYSTEM.PIPE
3.3 CHAR -- Character Functions
3.3.1 CHAR Class Usage
OBJECT CHR[CHAR];
CHR.INIT();
The CHAR class contains functions for determining character
types and converting characters. They all operate on ASCII
values.
This class must be initialized before its use by calling
CHR.INIT. An explicit shutdown is not required.
The CHAR class does not contain any variables. Therefore, it is
sufficient to create a single instance per module.
3.3.2 CHR.INIT
CHR.INIT() ! => 0
Initialize the character class by loading an internal pointer
with the character type map.
See also: CHR.MAP
3.3.3 CHR.ALPHA
CHR.ALPHA(c) ! Char => Num
Return TRUE (-1), if 'c' is an alphabetic character (in the
range 'a'...'z' or 'A'...'Z'). Otherwise return FALSE (0).
3.3.4 CHR.ASCII
CHR.ASCII(c) ! Char => Num
Return TRUE (-1), if 'c' is a valid ASCII value (in the range
0...127). Otherwise return FALSE (0).
3.3.5 CHR.CNTRL
CHR.CNTRL(c) ! Char => Num
Return TRUE (-1), if 'c' is a control character (in the range
0...31 or equal to 127). Otherwise return FALSE (0).
3.3.6 CHR.DIGIT
CHR.DIGIT(c) ! Char => Num
Return TRUE (-1), if 'c' is a decimal digit (in the range
'0'...'9'). Otherwise return FALSE (0).
3.3.7 CHR.LCASE
CHR.LCASE(c) ! Char => Char
If the character 'c' is an upper case character (see
CHR.UPPER), convert it to lower case and return it. Otherwise,
return it unchanged.
See also: CHR.UCASE
3.3.8 CHR.LOWER
CHR.LOWER(c) ! Char => Num
Return TRUE (-1), if 'c' is a lower case letter (in the range
'a'...'z'). Otherwise return FALSE (0).
See also: CHR.UPPER
3.3.9 CHR.MAP
CHR.MAP() ! => Bvec
Return the character description map used internally. This map
is a byte vector of 128 members containing flags for describing
each ASCII character. It can be used to implement fast
character class checks. For example,
IF (chr.lower(c)) ...
can be written as
chrmap := chr.map();
...
IF (chrmap::c & (CHAR.C_UPPER|CHAR.C_ALPHA) = CHAR.C_ALPHA)
...
which saves a procedure call each time a character is tested
for being lower case.
The following public constants are defined in the CHAR class
and can be used for testing character flags:
Flag Property
------------ --------
CHAR.C_ALPHA alphabetic
CHAR.C_UPPER upper case
CHAR.C_DIGIT decimal digit
CHAR.C_SPACE white space
CHAR.C_CNTRL control character
3.3.10 CHR.SPACE
CHR.SPACE(c) ! Char => Num
Return TRUE (-1), if 'c' is a space character (HT(9), LF(10),
VT(11), FF(12), CR(13), space(32)). Otherwise return FALSE (0).
3.3.11 CHR.UCASE
CHR.UCASE(c) ! Char => Char
If the character 'c' is a lower case character (see CHR.LOWER),
convert it to upper case and return it. Otherwise, return it
unchanged.
See also: CHR.LCASE
3.3.12 CHR.UPPER
CHR.UPPER(c) ! Char => Num
Return TRUE (-1), if 'c' is a upper case letter (in the range
'A'...'Z'). Otherwise return FALSE (0).
See also: CHR.LOWER
3.3.13 CHR.VALUE
| CHR.VALUE(c) ! Char => Num
Return the value of the decimal digit represented by the
character in 'c' or -1, if the character does not represent a
decimal digit.
3.4 IOSTREAM -- I/O-Streams
3.4.1 IOSTREAM Class Usage
OBJECT IOS[IOSTREAM];
The IOSTREAM class implements fully buffered I/O streams.
I/O streams provide a string/character-oriented interface to
the programmer while performing block-oriented I/O to the file
or device associated with a stream. This way, they combine the
speed of block-I/O with the flexibility of character-based I/O.
This class contains the I/O stream data structure and
procedures for creating, opening, closing, reading, and writing
streams.
A separate IOSTREAM object must be defined for each stream to
be used in a program.
3.4.2 IOS.CLOSE
IOS.CLOSE() ! => Num
Shutdown the I/O stream IOS by first flushing its buffer and
then closing the file associated with the stream. Flushing a
buffer means to write any pending output (if the stream has been
written to) and to discard any pending input (if the stream is
being read from).
IOS.CLOSE returns zero, if the stream could be closed and
otherwise -1. After successfully sending CLOSE, the receiving
stream becomes invalid immediately and should no longer be
accessed.
See also: IOS.CREATE, IOS.OPEN, IOS.FLUSH
3.4.3 IOS.CREATE
IOS.CREATE(fd, buffer, len, mode) ! Fdesc,Bvec,Num,Num => 0
Initialize the iostream IOS with the given parameters. 'Fd'
is an open file descriptor which will be associated with the
stream. 'Buffer' will be used for buffering read/write
operations on the stream. 'Len' specifies the size of 'buffer'
in bytes. 'Mode' controls the operations allowed on IOS. The
following flags may be used to build the mode value (by OR'ing
together their values):
Mode constant ReadOK WriteOK LF>CRLF CRLF>LF
---------------- ------ ------- ------- -------
IOSTREAM.FREAD Yes No - -
IOSTREAM.FWRITE No Yes - -
IOSTREAM.FRDWR Yes Yes - -
IOSTREAM.FKILLCR - - - Yes
IOSTREAM.FADDCR - - Yes -
IOSTREAM.FTRANS - - Yes Yes
CRLF>LF denotes that each CR character found in an input stream
will be silently discarded. This is useful when reading
DOS-style ASCII text files. LF>CRLF means that a CR character
will be added before each LF in the output stream. Since
IOSTREAM.FADDCR has no effect on input and IOSTREAM.FKILLCR has
no effect on output, IOSTREAM.FTRANS may be used safely on
input as well as output streams.
IOS.CREATE merely initializes an IOSTREAM object with the
supplied parameters. It cannot fail and therefore, it returns
always 0.
When using IOS.CREATE to create a stream for accessing standard
file descriptors (such as T3X.SYSIN and T3X.SYSOUT), these
streams should never be closed. IOS.FLUSH may be used to
synchronize them.
See also: IOS.OPEN, IOS.CLOSE, IOS.FLUSH
3.4.4 IOS.EOF
IOS.EOF() ! => Num
Return a flag indicating whether input has been exhausted on
the stream IOS. When EOF returns TRUE (-1), no more input can
be read from IOS. This is the case when the end of the
associated input file has been reached or when an EOF character
has been typed on a terminal.
See also: IOS.READ, IOS.READS, IOS.RDCH, IOS.RESET
3.4.5 IOS.FLUSH
IOS.FLUSH() ! => Num
Flush the stream IOS and return a value indicating whether
the operation was successful. Zero means success, -1 means
failure.
Flushing an output stream means to write all pending data to
the associated file. Flushing an input stream means to discard
all pending input. The operation performed on a combined
input/output stream depends on the type of the last operation
performed before flushing the stream.
See also: IOS.OPEN, IOS.CLOSE, IOS.READ, IOS.WRITE
3.4.6 IOS.MOVE
IOS.MOVE(offset, origin) ! Num,Num => Num
Move the file pointer of the file descriptor associated with
IOS to a new position. The position is computed using the
given 'offset' and 'origin'. 'Offset' is the number of bytes to
skip and 'origin' specifies where the motion shall begin. The
following origin values are available:
Constant Origin Direction
----------------- ----------------- ---------
IOSTREAM.SEEK_SET beginning of file forward
IOSTREAM.SEEK_FWD current position forward
IOSTREAM.SEEK_END end of file backward
IOSTREAM.SEEK_BCK current position backward
IOSTREAM.SEEK_SET and IOSTREAM.SEEK_FWD move the file pointer
forward, IOSTREAM.SEEK_END and IOSTREAM.SEEK_BCK move it
backward. In either case, 'where' is an unsigned value so that
offsets may range from 0 to 65535 bytes.
IOS.MOVE always flushes the stream buffer before changing the
file pointer.
It returns zero upon success and -1 in case of an error.
See also: IOS.FLUSH, T3X.SEEK
3.4.7 IOS.OPEN
IOS.OPEN(path, buffer, len, mode) ! Str,Vec,Num,Num => Num
Open the file specified in 'path' and initialize IOS with the
resulting file descriptor and the arguments 'buffer', 'len',
and 'mode'. See IOS.CREATE for details. The exact format of
'path' depends on the operating system. The following open modes
('mode' values) are common:
Mode constant ReadOK WriteOK Create
--------------- ----- ------- ------
IOSTREAM.FREAD Yes No No
IOSTREAM.FWRITE No Yes Yes
IOSTREAM.FRDWR Yes Yes No
For additional modes, see IOS.CREATE.
When creating a file, any existing file with the same name will
be truncated to zero length.
IOS.OPEN returns zero upon success and -1 in case of an error.
See also: IOS.CREATE, IOS.CLOSE, IOS.FLUSH, T3X.OPEN
3.4.8 IOS.RDCH
IOS.RDCH() ! => Char | -1
Read a single character from IOS and return it. When the EOF
condition is true on IOS, return -1 (which cannot be a valid
character).
See also: IOS.READ, IOS.READS, IOS.WRCH, IOS.EOF
3.4.9 IOS.READ
IOS.READ(buffer, len) ! Vec,Num => Num
Read up to 'len' characters from IOS into 'buffer'. Return the
number of characters actually read. A return value less than
'len' may indicate the end of input or the beginning of a new
line a on a terminal. A return value of zero always indicates
the EOF. A value below zero indicates a severe error.
See also: IOS.RDCH, IOS.READS, IOS.WRITE, IOS.EOF
3.4.10 IOS.READS
IOS.READS(buffer, len) ! Vec,Num => Num
Read up to 'len'-1 characters from IOS into 'buffer'. Return
the number of characters actually read. A return value of zero
indicates that the EOF has been reached. A value below zero
indicates a severe error.
Unlike IOS.READ, IOS.READS stops reading when it encounters a
line separator (LF) in input. If this happens, the LF character
will be inserted as the last character into 'buffer'.
See also: IOS.RDCH, IOS.READ, IOS.WRITE, IOS.EOF
3.4.11 IOS.RESET
IOS.RESET() ! => 0
Reset the error flag of the iostream IOS. Resetting the error
flag is necessary to access a stream after an error has
occurred (for example, after reading beyond the EOF).
See also: IOS.EOF, IOS.READ
3.4.12 IOS.WRCH
IOS.WRCH(c) ! Char => Char|Num
Write the character 'c' to the stream IOS. If the character
could be written, return its ASCII code and otherwise return
-1.
See also: IOS.WRITE, IOS.WRITES, IOS.FLUSH
3.4.13 IOS.WRITE
IOS.WRITE(buffer, len) ! Vec,Num => Num
Write 'len' characters from 'buffer' to IOS. Return the number
of characters actually written. A return value less than 'len'
indicates a severe error (such as no space left on the target
device).
See also: IOS.WRITES, IOS.WRCH, IOS.FLUSH
3.4.14 IOS.WRITES
IOS.WRITES(str) ! Str => Num
Write the string 'str' to IOS. Return the number of characters
actually written. A return value less than the length of 'str'
indicates a severe error (such as no space left on the target
device).
See also: IOS.WRITE, IOS.WRCH, IOS.FLUSH
3.5 MEMORY -- Dynamic Memory Management
3.5.1 MEMORY Class Usage
OBJECT MEM[MEMORY];
The MEMORY class implements dynamic memory pools. When
initialized, the address of a static data area is passed to a
MEMORY object. This area (called a 'pool') will be managed by
the MEMORY object. Vectors can be allocated from the pool and
released back to it when they are no longer required.
A first-match algorithm is used to allocate memory in a pool.
The algorithm is optimized for sequential allocation. The pool
is defragmented when releasing memory, but no compaction is
performed, so fragmentation may still happen.
MEMORY objects are ineffective when allocating a large number
of small vectors, since a free list entry has to be created for
each vector allocated.
Multiple memory pools may be defined using the MEMORY class,
but usually one pool per program is most effective.
3.5.2 MEM.ALLOC
MEM.ALLOC(size) ! Num => Vec | 0
Allocate 'size' bytes from the memory pool MEM and return a
pointer to the allocated vector. If the request could not be
satisfied due to insufficient memory, return 0.
Up to 32765 bytes may be allocated in a single request.
See also: MEM.FREE
3.5.3 MEM.FREE
MEM.FREE(vec) ! Vec => 0
Release the memory occupied by the vector 'vec' to MEM and
defragment MEM. The space of of 'vec' is be added to the free
memory pool of MEM.
'Vec' must be the address of a vector which has been previously
allocated in MEM. Otherwise, the calling program may be
terminated with an error message of the form
MEMORY CLASS: bad block in mem.free()
Accessing a freed vector is undefined.
See also: MEM.ALLOC
3.5.4 MEM.INIT
MEM.INIT(pool, size) ! Vec,Num => 0
Initialize the memory pool MEM and add 'size' bytes to its
internal freelist. 'Pool' must have a size of at least 'size'
bytes. 'Size' may not be larger than 32767.
All previously allocated vectors of MEM will be freed by
MEM.INIT.
MEM.INIT always returns 0.
See also: MEM.FREE
3.5.5 MEM.WALK
MEM.WALK(vec, sizep, statp) ! Vec,Vec,Vec => Vec
Traverse the list of vectors in MEM. This list contains both
allocated and free vectors. Traversing the list works as
follows:
When MEM.WALK is called for the first time, 'vec' must be zero:
v := mem.walk(0, @p, @s);
This call will return a pointer to the first vector of MEM.
The returned vector can be passed to MEM.WALK in a subsequent
call to retrieve a pointer to the next vector:
v := mem.walk(v, @p, @s);
When the 'vec' argument finally points to the last vector in
MEM, MEM.WALK will return zero.
The argument 'sizep' is a one-word vector which will be filled
with the size of the returned vector. 'Statp' is a one-word
vector which will be filled with the status of the vector
(1=free, 0=allocated). If either 'statp' or 'sizep' is zero, it
will be ignored by MEM.WALK.
3.6 STRING -- String Functions
3.6.1 STRING Class Usage
OBJECT STR[STRING];
The STRING class contains procedures for manipulating
NUL-terminated sequences of ASCII characters.
The STRING class does not contain any data, so a single
instance per module is sufficient. The class does not require
any explicit initialization or shutdown.
3.6.2 STR.COMP
STR.COMP(a, b) ! Str,Str => Num
Compare each character in 'a' with the character at the
corresponding position in 'b'. When a position 'i' is found
at which the characters of 'a' and 'b' differ, return
a::i - b::i
When no mismatch is encountered, return 0. Consequently, the
return value of STR.COMP can be interpreted as follows:
Value Meaning
----- -------
>0 'a' is lexically greater than 'b'
<0 'a' is lexically less than 'b'
=0 'a' is equal to 'b'
See also: STR.FIND, STR.SCAN, STR.RSCAN
3.6.3 STR.COPY
STR.COPY(a, b) ! Str,Str => 0
Copy the string stored at the location 'b' to the location 'a'.
Return zero.
See also: STR.FORMAT, STR.NCOPY
3.6.4 STR.FIND
STR.FIND(a, b) ! Str,Str => Num
Find the first occurrence of the string 'b' in the string 'a'.
Return the offset of the string found, if any. Return -1, if
'a' does not contain 'b'.
See also: STR.COMP, STR.SCAN, STR.RSCAN
3.6.5 STR.FORMAT
STR.FORMAT(buf, tmpl, list) ! => Str,Str,Vec => Str
Format the arguments contained in 'list' according to the
template 'tmpl' and store the resulting string in 'buf'.
'Tmpl' is a string containing literal characters as well as
'format descriptors'. A format descriptor is a substring that
begins with a percent sign and ends with one of the characters
in {C,D,S,X,%}. When 'tmpl' does not contain any format
descriptors, it will be copied to 'buf' and 'list' will be
ignored. When format descriptors exist, each descriptor will be
used to format one element of 'list'. Instead of the descriptor
itself, the result of formatting one member of 'list' will be
inserted into 'buf'.
A format descriptor has the following syntax:
%[len][:F][U][{LR}]{CDSX%}
([x] indicates an optional element 'x', {xyz} indicates one
element out of x, y, and z.)
- The percent sign '%' starts the descriptor.
- When a decimal number 'max' is specified after '%', this number
indicates the minimum field length of the current argument. If
formatting the current argument yields a result shorter than
'len', the field will be filled with blanks.
- ':F' denotes that the character F should be used for filling
fields instead of blank characters.
- When 'U' is specified together with 'D', an unsigned numeric
string will be generated (a signed representation will be
generated by default).
- 'L' instructs STR.FORMAT to left-justify the current field,
'R' instructs it to right-justify it. The default is to
left-justify strings and to right-justify numbers.
- The last character specifies the type of the current argument
in 'list'.
The following types exist ('i' denotes the index of the current
argument):
Type Insert list[i] as
---- ----------------------------
C character
D decimal numeric literal
S string
X hexa-decimal numeric literal
The string '%%' may be used to include a literal percent sign.
There must be one member in 'list' for each descriptor in 'tmpl'.
Examples:
Template Argument list Result
--------------------- ------------- ----------------------
"%D%% of %10:*D = %D" [10,200,20] 10% of *******200 = 20
"'%C' = 0X%X = %D" ['A','A','A'] 'A' = 0X41 = 65
"%:-9LS%:+9RS" ["ZZZ","YYY"] ZZZ------++++++YYY
STR.FORMAT returns the address of 'buf'.
See also: STR.PARSE, STR.COPY, STR.NFORMAT
3.6.6 STR.LENGTH
STR.LENGTH(a) ! Str => Num
Return the number of characters contained in 'a' (excluding the
terminating NUL character).
3.6.7 STR.NCOPY
STR.NCOPY(n, a, b) ! Num,Str,Str => 0
Copy up to 'n'-1 characters of the string stored at the
location 'b' to the location 'a'. When 'a' is shorter than
'n'-1 characters, copy the entire string. Always terminate
'a' with NUL. Return zero.
When 'n' = ~0, STR.NCOPY implements STR.COPY.
See also: STR.COPY, STR.NFORMAT
3.6.8 STR.NFORMAT
STR.NFORMAT(n, buf, tmpl, list) ! => Num, Str,Str,Vec => Str
STR.NFORMAT is like format, but never writes more than 'n'-1
characters to 'buf'. See STR.FORMAT for details.
When the given template and arguments would produce a resulting
string containing more than 'n'-1 characters, STR.NFORMAT will
return a result that is truncated at the 'n'-1'st character.
The result will still be NUL-terminated.
When a format descriptor that uses padding would cause the
length of 'buf' to be exceeded, first the padding will be
decreased and then the representation of the described object
will be truncated. This means that given N=5, the following
results would be obtained:
argument descriptor result
-------- ---------- -------
"123" "%10LS" "123 "
"123" "%10RS" " 123"
"1234567" "%10LS" "12345"
"1234567" "%10RS" "12345"
See also: STR.FORMAT, STR.NCOPY
3.6.9 STR.NUMTOSTR
STR.NUMTOSTR(buf, n, radix) ! Str,Num,Num => Str
Convert a number 'n' to a string representing that number
with respect to the given 'radix'. The resulting numeric
string will be stored in 'buf'.
If 'radix' and 'n' are both negative, a leading minus sign will
be generated. If 'radix' is positive, an unsigned value of
N will be assumed.
'Buf' must provide enough space to hold the resulting literal.
Valid values for 'radix' range from '2' (binary) to '16' (hexa-
decimal) and from '-2' (signed binary) to '-16' (signed hexa-
decimal).
STR.STRTONUM returns the address of the first character of the
resulting literal.
See also: STR.STRTONUM, STR.FORMAT
3.6.10 STR.PARSE
STR.PARSE(source, tmpl, list) ! Str,Str,Vec => Num
Extract patterns described in 'tmpl' from 'source' and store
the extracted objects in the members of 'list'. Patterns used
in 'tmpl' are similar to format descriptors used by
STR.FORMAT. Characters not belonging to patterns are matched
literally and not stored anywhere.
STR.PARSE compares each character contained in 'tmpl' with a
corresponding character in 'source' (like STR.COMP) until it
finds a '%'-character in 'tmpl'. A percent character indicates
the beginning of a pattern. Patterns match specific classes of
characters. Instead of matching the pattern itself, the
character class described by the pattern is matched.
Some patterns store the value of the matched substring in an
element of 'list' and some do not. Each pattern may consist of
the following parts:
%[len][:D]{CDSWX%}
([x] indicates an optional element 'x', {xyz} indicates one
element out of x, y, and z.)
The special form %[c1...cN] may be used to match any character
in the range 'c1'...'cN'. The matched characters are not
stored in this case.
- If a length 'len' is specified, UP TO 'len' characters will be
matched. Typically, this option is used together with %S.
- ':D' instructs STR.PARSE to recognize the character in the
place of 'D' as a delimiter (default = none).
The following pattern types exist:
Type Store as Matches
---- --------- ---------------------------------
C character any single character
D number a signed decimal number (+)
S string a string (*)
W - space (any number of '\s' or '\t'
. . characters)
X number a signed hexa-decimal number (+)
% - a percent sign
(+) These leading prefixes are accepted: {+-%}
(*) When no length is specified, %S matches the entire rest of
'source'. ':D' or a length may be specified to match a
substring.
Numbers and characters are stored in 'list[i][0]' (where 'i' is
the index of the current member of 'list') and strings are
copied to the location pointed to by 'list[i]'.
Example:
VAR name::50, speed, unit::10;
STR.PARSE("HAL9000 @ 500 MHz", "%:@S@ %D%W%S",
[ (name), (@speed), (unit)]);
will store
"HAL9000 " in 'name'
500 in 'speed'
"MHz" in 'unit'
STR.PARSE returns the number of patterns stored.
See also: STR.FORMAT, STR.COMP
3.6.11 STR.RSCAN
STR.RSCAN(s, c) ! Str,Num => Num
Find the rightmost occurrence of the character 'c' in the
string 's' and return the offset (position) of the character
found. If 'c' is not contained in 's', return -1.
See also: STR.SCAN, STR.FIND, STR.COMP
3.6.12 STR.SCAN
STR.SCAN(s, c) ! Str,Num => Num
Find the first occurrence of the character 'c' in the string
's' and return the offset (position) of the character found. If
'c' is not contained in 's', return -1.
See also: STR.RSCAN, STR.FIND, STR.COMP
3.6.13 STR.STRTONUM
STR.STRTONUM(s, radix, lastp) ! Str,Num,Vec => Num
Compute the value represented by the numeric strung stored in
the 's'. 'Radix' specifies the base of the literal in 's'. It
may range from '2' (binary) to '16' (hexa-decimal).
STR.STRTONUM performs the following steps:
- Leading TAB ('\t') and space ('\s') characters in 's' are
skipped.
- A plus (+) or minus (-,%) sign is recognized.
- Characters belonging to the specified number class (based
upon 'radix') are collected and converted to a numeric
value.
The following characters may represent the digits from 0 to 15:
"0123456789ABCDEF".
When the argument 'lastp' is non-zero, it will be filled with
the number of characters processed. Consequently, it is the
offset of the first non-numeric character in 's' when STRTONUM
returns.
STR.STRTONUM returns the computed value.
No overflow checking is performed.
See also: STR.NUMTOSTR, STR.PARSE
3.6.14 STR.XLATE
STR.XLATE(s, old, new) ! Str,Num,Num => Str
Replace each occurrence of the character 'old' in the string
's' with 'new'. Return the address of 's'.
See also: STR.SCAN, STR.RSCAN
3.7 TCODE -- Tcode Instruction Set
3.7.1 TCODE Class Usage
MODULE MODNAME(TCODE);
CLASS CLASSNAME(TCODE) ... END
The TCODE class contains a set of public constants describing
the instruction set of the Tcode machine. There is no need to
instantiate this class, since it does not contain any state or
methods. To access the opcode of a specific Tcode instruction,
use the class constant notation
TCODE.IINSTRUCTION
For example, to load the opcode of the JUMP instruction into the
variable I, use
I := TCODE.IJUMP;
The special constant IENDOFSET contains a value which is one
above the highest value representing a Tcode instructions. To
check if a variable J contains a valid instruction, the
following code may be used:
IF ((J & 0x7F) .>= TCODE.IENDOFSET)
; ! Call your illegal instruction handler here
3.8 UTIL -- Utilities
3.8.1 UTIL Class Usage
OBJECT U[UTIL];
The UTIL (utility) class contains utility procedures for
miscellaneous tasks. Currently, there are methods for sending
formatted output to various channels like the system output,
file descriptors or streams. Using the UTIL class simplifies
many frequently used code fragments. For example, the code
DO VAR buffer::256;
t.write(T3X.SYSOUT, str.format(buffer, "X = %D\N", [(x)]),
str.length(buffer));
END
could be replaced with
u.printf("X = %D\N", [(x)]);
in modules using the UTIL class.
3.8.2 UTIL.BUFLEN
UTIL.BUFLEN
This public constant holds the maximum length of strings
formatted by the PRINTF, WRITEF, and SWRITEF methods. The
length returned includes the terminating NUL character.
3.8.3 U.PRINTF
U.PRINTF(tmpl, args) ! Str,Vec => Num
Format the arguments contained in the vector 'args' using
STR.FORMAT(buffer, tmpl, args)
where 'buffer' is an internal buffer of the length UTIL.BUFLEN.
The buffer is then written to the system output device
T3X.SYSOUT.
U.PRINTF returns the number of characters written using
T3X.WRITE.
3.8.4 U.SWRITEF
U.SWRITEF(ios, tmpl, args) ! IOS,Str,Vec => Num
Format the arguments contained in the vector 'args' using
STR.FORMAT(buffer, tmpl, args)
where 'buffer' is an internal buffer of the length UTIL.BUFLEN.
The buffer is then sent to the output stream IOS.
U.SWRITEF returns the number of characters written using
IOSTREAM.WRITE.
3.8.5 U.WRITEF
U.WRITEF(fd, tmpl, args) ! FDesc,Str,Vec => Num
Format the arguments contained in the vector 'args' using
STR.FORMAT(buffer, tmpl, args)
where 'buffer' is an internal buffer of the length UTIL.BUFLEN.
The buffer is then written to the file descriptor 'fd'.
U.WRITEF returns the number of characters written using
T3X.WRITE.
3.9 SYSTEM -- System Interface
3.9.1 SYSTEM Class Usage
OBJECT SYS[SYSTEM];
SYS.INIT();
The SYSTEM class contains a set of procedures which form a
(more or less) portable interface to the operating system. Most
procedures have the same names and functions as Unix system
calls. Some functions may be unavailable on non-Unix systems.
The SYSTEM class must be initialized using SYS.INIT and shut
down by calling SYS.FINI.
SYSTEM does not contain any variables. Therefore, it is
sufficient to create a single instance per module.
3.9.2 SYS.INIT
SYS.INIT() ! => 0
Initialize the operating system interface.
See also: SYS.FINI
3.9.3 SYS.CHDIR
SYS.CHDIR(path) ! Str => Num
Change the current working directory to 'path'. The format of
'path' depends on the operating system.
SYS.CHDIR returns 0 on success and a negative value in case of
an error.
See also: SYS.MKDIR, SYS.RMDIR, SYS.OPENDIR
3.9.4 SYS.CLOSEDIR
SYS.CLOSEDIR(ddesc) ! Ddesc => Num
Close the directory descriptor 'ddesc'.
SYS.CLOSEDIR returns 0 on success and a negative value in case
of an error.
See also: SYS.OPENDIR, SYS.READDIR, SYS.STAT
3.9.5 SYS.DUP
SYS.DUP(oldfd) ! Fdesc => Fdesc | -1
Duplicate the file descriptor 'oldfd' and return a new
descriptor referencing the same file. All operations performed
on the new descriptor will also affect 'oldfd'.
SYS.DUP returns a new descriptor on success and a negative
number in case of an error.
See also: SYS.DUP2, SYS.PIPE, SYS.FORK, T3X.OPEN, T3X.CLOSE
3.9.6 SYS.DUP2
SYS.DUP2(oldfd, newfd) ! Fdesc,Fdesc => Num
Duplicate the file descriptor 'oldfd' and make 'newfd'
reference the same file. Thereafter, all operations performed
on one of them will also affect the other. If 'newfd' already
references a valid descriptor, it will be closed first by
calling T3X.CLOSE.
SYS.DUP2 returns zero upon success, and a negative number in
case of an error.
See also: SYS.DUP, SYS.PIPE, SYS.FORK, T3X.OPEN, T3X.CLOSE
3.9.7 SYS.FINI
SYS.FINI() ! => 0
Shutdown the operating system interface. After calling
SYS.FINI, the SYSTEM services become unavailable.
See also: SYS.INIT
3.9.8 SYS.FORK
SYS.FORK() ! => Num
Duplicate the calling process. The new process -- called the
child process -- will start running exactly at the point where
SYS.FORK returns. Each process has an own data segment and an
own set of file descriptors. Descriptors which where open when
SYS.FORK was called, will reference the same files in both
processes, though.
After the successful creation of the new process, SYS.FORK
returns zero to the child process and the process ID of the
child to the parent process.
In case of an error, SYS.FORK returns -1.
See also: SYS.KILL, SYS.SPAWN, SYS.WAIT, T3X.OPEN
3.9.9 SYS.GETDIR
SYS.GETDIR(buf, len) ! Str,Num => Num
Store the fully qualified path name of the current working
directory in 'buf'. Do not store more than the first 'len'-1
characters. Append a trailing NUL character to the path. 'Buf'
must be at least 'len' characters in length, and it may not be
smaller than 65 characters.
If 'len' is less than 65 or the function fails, -1 is returned.
Upon success, the number of characters stored is returned.
See also: SYS.MKDIR, SYS.RMDIR, SYS.OPENDIR
3.9.10 SYS.KILL
SYS.KILL(pid, sig) ! Num,Num => Num
Send a signal to the process with the process ID 'pid'. The
following constants may be used in the place of 'sig' to
specify which signal is to be sent to the process:
Constant Action
-------------- -------------------
SYSTEM.SIGTEST Test process
SYSTEM.SIGTERM Request termination
SYSTEM.SIGKILL Force termination
SYS.KILL returns zero, if the signal could be delivered
successfully, and a negative number in case of an error.
Delivering SYSTEM.SIGTEST does not have any effect on the
process with the given PID. Therefore, it can be used to check
whether the PID is valid.
SYSTEM.SIGTERM may be caught by the receiving process to
initiate a graceful shutdown.
SYSTEM.SIGKILL terminates the receiving process immediately.
See also: SYS.FORK, SYS.SPAWN
3.9.11 SYS.MKDIR
SYS.MKDIR(path) ! Str => Num
Create a directory with the name stored in 'path'. The format
of 'path' depends on the operating system.
SYS.MKDIR returns zero, if the directory could be created and
otherwise a negative value.
See also: SYS.CHDIR, SYS.RMDIR, SYS.OPENDIR, SYS.GETDIR
3.9.12 SYS.OPENDIR
SYS.OPENDIR(path) ! Str => Ddesc | -1
Open the directory specified in 'path'. The exact format of
'path' depends on the underlying operating system.
Upon success, SYS.OPENDIR returns a directory descriptor and in
case of an error, it returns -1.
See also: SYS.READDIR, SYS.CLOSEDIR, SYS.STAT
3.9.13 SYS.PIPE
SYS.PIPE(vec) ! Vec => Num
Create a pipe (a FIFO structure) and fill the vector 'vec' with
two file descriptors which can be used to access the pipe. Each
element of 'vec' will be filled with an ordinary file
descriptor as returned by T3X.OPEN. Therefore, ordinary I/O
operations like T3X.READ and T3X.WRITE can be used to read and
write a pipe.
After the successful creation of a pipe, 'vec[0]' will contain
the (read-only) output descriptor and 'vec[1]' will contain the
(write-only) input descriptor of the pipe.
Data written to 'vec[1]' can be read from 'vec[0]'. Write
requests will block, if the pipe is full and read requests will
block, if the pipe is empty. The size of the pipe depends on
the operating system.
SYS.PIPE returns zero when a pipe could be created and a
negative value in case of an error.
See also: T3X.OPEN, T3X.CLOSE, T3X.READ, T3X.WRITE
3.9.14 SYS.RDCHK
SYS.RDCHK(fdesc) ! Fdesc => Num
Check whether input is available from the file descriptor
'fdesc' (whether a read operation on 'fdesc' would NOT block).
SYS.RDCHK returns a non-zero value, if the operation would
succeed without blocking. If the read request would block, zero
is returned.
To check the status of a terminal, use TTYCTL.QUERY instead.
See also: T3X.READ, TTYCTL.QUERY
3.9.15 SYS.READDIR
SYS.READDIR(ddesc, buffer, lim) ! Ddesc,Str,Num => Num
Read the next directory entry from the directory descriptor
'ddesc' and fill 'buffer' with the name of that entry. If the
name is longer than 'lim'-1 characters, truncate it to 'lim'-1
characters. In any case, terminate the extracted string with a
NUL character.
SYS.READDIR returns the length of the extracted string upon
success, and -1 in case of an error. Reading beyond the end of
the directory will return -1.
See also: SYS.OPENDIR, SYS.CLOSEDIR, SYS.STAT
3.9.16 SYS.RMDIR
SYS.RMDIR(path) ! Str => Num
Remove the directory specified in 'path'. The format of 'path'
depends on the operating system.
SYS.RMDIR returns zero, if the directory could be removed and
a negative value otherwise.
See also: SYS.CHDIR, SYS.MKDIR, SYS.OPENDIR, SYS.GETDIR
3.9.17 SYS.SPAWN
SYS.SPAWN(prog, args, mode) ! Str,Vec,Num => Num
Create a new process by running the program 'prog' with the
command line options stored in 'args'. The format of the path
of 'prog' depends on the operating system.
'Args' is a vector of strings, each one containing one command
line argument. The last element of the vector must be zero.
'Mode' controls whether execution of the calling process will be
suspended until the spawned process exits. The following modes
exist:
Mode name Meaning
------------------- ------------------------------------
SYSTEM.SPAWN_NOWAIT Execute the new process concurrently
SYSTEM.SPAWN_WAIT Suspend the caller until the child
process terminates
NOTE: some operating systems may restrict the space which can
be used for passing command line arguments.
NOTE2: on non-multitasking systems, SYSTEM.SPAWN_NOWAIT may be
unimplemented.
SPAWN returns the exit code of the subprocess when called with
mode=SYSTEM.SPAWN_WAIT. It returns the process ID (PID) of the
spawned subprocess when called with mode=SYSTEM.SPAWN_NOWAIT.
In case of an error, it returns -1.
See also: SYS.FORK, SYS.WAIT
3.9.18 SYS.STAT
SYS.STAT(path, sb) ! Str,Vec => Num
Retrieve information about the file specified in 'path'. The
format of 'path' depends on the operating system. The retrieved
information will be stored in the SYSTEM.STATBUF structure 'sb'
which has the following format:
struct STATBUF =
ST_DEV, ! device ID
ST_INO, ! inode number
ST_MODE, ! access bits
ST_NLINK, ! number of links
ST_UID, ! user ID of owner
ST_GID, ! group ID of owner
ST_RDEV, ! device type
ST_SIZE, ! file size in bytes
ST_EXT64, ! file size in 64K blocks
ST_MTIME, ! date of last modification (8 bytes)
! Format: CYMDHMSh, see SYS.TIME.
ST_MT_2, ! \
ST_MT_3, ! > Buffer for ST_MTIME
ST_MT_4; ! /
For the layout of the MTIME structure, see SYS.TIME.
Depending on the operating system, some fields will be filled
with more or less meaningful standard values. For example,
systems not supporting multiple links will fill the ST_NLINK
field with 1.
The access field SYSTEM.ST_MODE may have the following flags
set:
Flag Description
--------------- ----------------------
SYSTEM.FM_RDOK file is readable
SYSTEM.FM_WROK file is writeable
SYSTEM.FM_EXOK file is executable (*)
SYSTEM.FM_ISDIR file is a directory
(*) Files on DOS file systems do not have an executable flag.
Therefore,
sb[SYSTEM.ST_MODE] | SYSTEM.FM_EXOK
is always zero on DOS systems.
SYS.STAT returns zero upon success and otherwise a negative
value.
See also: SYS.OPENDIR, SYS.READDIR, SYS.CLOSEDIR, SYS.GETDIR
3.9.19 SYS.TIME
SYS.TIME(tbuf) ! Bvec => 0
Fill the buffer 'tbuf' with the current system time. 'Tbuf'
must provide eight bytes of space which will be filled as
follows:
Field Value Range
------- ------------ ------
tbuf::0 year / 100 19...
tbuf::1 year mod 100 0...99
tbuf::2 month 1...12
tbuf::3 day 1...31
tbuf::4 hour 0...23
tbuf::5 minute 0...59
tbuf::6 second 0...59
tbuf::7 second/100 0...99
SYS.TIME never fails and always returns 0. It might return an
incorrect time, though, and on systems without a clock, it may
fill 'tbuf' with the same values each time it is called.
3.9.20 SYS.WAIT
SYS.WAIT(pid) ! => Num
Wait for a subprocess to terminate and return its exit code.
'Pid' contains the process ID of the process to wait for. It
must be a PID obtained from SYS.SPAWN or SYS.FORK.
WAIT returns the exit code of the process waited for. The exit
code is the value passed to the HALT command of T3X. When the
process waited for terminates abnormally, SYS.WAIT returns -1.
It also returns -1 when an invalid PID is passed to it.
NOTE: SYS.WAIT does not actually wait for a specific process to
terminate. Therefore, no more than a single subprocess should be
active at the same time.
See also: SYS.SPAWN, SYS.FORK
3.10 TTYCTL -- Video Terminal Control
3.10.1 TTYCTL Class Usage
OBJECT TTY[TTYCTL];
The TTYCTL class implements a set of routines for controlling
character-based video terminal screens and reading terminal
keyboards. Procedures contained in this class include writing
to the terminal screen, cursor movement, clearing and scrolling
screen regions, setting display colors (where available), and
decoding keyboard input.
NOTICE: It is generally a bad idea to mix writes to the
terminal screen using
T3X.WRITE(T3X.SYSOUT, buffer, length)
(or even to T3X.SYSERR) with the TTYCTL output functions. Doing
so may interfere with the internal state of the TTYCTL class
and cause messed up screen output or even undefined behavior.
The TTYCTL routines must be initialized by calling TTY.INIT and
shut down by calling TTY.FINI.
Although the TTYCTL class does have internal state, no more than
one instance should be created, because that state reflects the
state of the controlled video terminal.
3.10.2 TTY.INIT
TTY.INIT() ! => 0
Initialize the TTY control structures. This routine must be
called before any other procedures of this class can be used.
It performs the following steps. (Depending on the used
operating system, some of these steps may be skipped.)
- Open the controlling TTY (/dev/tty) for reading and writing.
- Determine the user's terminal type (by evaluating the $TERM
environment variable).
- Check the terminal's color capability. Assume color, if
either (1) the terminal's name contains the substring "color"
or (2) the terminal's name begins with the prefix "xterm".
- Check the $ANSICOLOR variable which may be set to YES or NO
to override the color capability detection.
- Extract some required properties, control strings, and
key codes from the termcap(5) database.
TTY.INIT may fail for any of the following reasons:
- $TERM is not defined
- The value of $TERM is not a known TTY type
- The terminal type does not define one or more of the
following termcap variables:
{co,li,ce,cl,cm,cs,sf,sr,se,so,rs}
In any of the above cases, an explanatory message will be
printed and the calling program will be terminated.
See also: TTY.MODE, TTY.RESET
3.10.3 TTY.CLEAR
TTY.CLEAR() ! => 0
Clear the terminal screen using the currently selected color.
See also: TTY.CLREOL, TTY.COLOR
3.10.4 TTY.CLREOL
TTY.CLREOL() ! => 0
Clear all characters from the cursor position to the end of the
current line using the currently selected color.
See also: TTY.CLEAR, TTY.COLOR
3.10.5 TTY.COLOR
TTY.COLOR(color) ! Num => 0
Select new foreground and background colors. 'Color' is created
by OR'ing together a foreground and a background color value.
The following values exist (F_ indicates 'foreground' and B_
indicates 'background'):
F_BLACK, F_BLUE, F_GREEN, F_CYAN, F_RED, F_MAGENTA,
F_YELLOW, F_GREY,
B_BLACK, B_BLUE, B_GREEN, B_CYAN, B_RED, B_MAGENTA,
B_YELLOW, B_GREY
The special value F_BRIGHT may be OR'ed in to increase the
intensity of the foreground color. For example,
tty.color(TTYCTL.F_CYAN | TTYCTL.B_BLUE | TTYCTL.F_BRIGHT)
selects bright cyan color on blue background.
On monochrome terminals, only the color values
F_GREY|B_BLACK and F_BLACK|B_GREY
should be considered to be defined.
See also: TTY.COLORS
3.10.6 TTY.COLORS
TTY.COLORS() ! => Num
Return a non-zero value, if the controlled terminal supports
color.
See also: TTY.COLUMNS, TTY.LINES
3.10.7 TTY.COLUMNS
TTY.COLUMNS() ! => Num
Return the number of columns per line on the screen of the
controlled terminal.
See also: TTY.COLORS, TTY.LINES
3.10.8 TTY.FINI
TTY.FINI() ! => 0
Shutdown the TTYCTL class. Restore the state of the TTY to the
state at initialization time. To restore all original settings,
TTY.RESET should be called before TTY.FINI.
See also: TTY.INIT, TTY.MODE
3.10.9 TTY.LINES
TTY.LINES() ! => Num
Return the number of lines on the screen of the controlled
terminal.
See also: TTY.COLORS, TTY.COLUMNS
3.10.10 TTY.MODE
TTY.MODE(rawflag) ! Num => 0
Switch the terminal to 'raw mode'. Some terminals (especially
in the Unix world) must be in 'raw mode' to allow to read
single characters from them. In non-raw ('cooked') mode,
reading a TTY device only returns when CR (ENTER,NL) is
pressed on the terminal's keyboard. To make the read call
return immediately after reading one single key, the TTY driver
must be put in raw mode.
TTY.MODE(1) selects raw mode and TTY.MODE(0) selects the mode
the controlled TTY was in when TTY.INIT was called.
These calls may have no effect on other platforms, but when
switching a TTY driver to raw mode, it should be switched back
to its original mode before terminating the program. Otherwise,
the TTY driver may be left in an undesired state and render the
controlled TTY inaccessible.
On some systems, cooked mode may not be implemented. In this
case, TTY.READC will always return after receiving a single key.
See also: TTY.READC
3.10.11 TTY.MOVE
TTY.MOVE(x, y) ! Num,Num => 0
Move the cursor to the specified location (column 'x', row
'y'). If the specified coordinates do not exist on the used
TTY, the result is undefined. Coordinates start at (0,0) in the
upper/left corner.
See also: TTY.COLUMNS, TTY.LINES
3.10.12 TTY.QUERY
TTY.QUERY() ! => Num
Check whether there are characters in the keyboard input buffer.
If there are any characters, TTY.READC would return when called
in that moment. Otherwise, it would block.
TTY.QUERY returns -1 if there are characters in the buffer and
otherwise 0.
See also: TTY.READC
3.10.13 TTY.READC
TTY.READC() ! => Num
Read a single character from the terminal's keyboard and return
its key code. For keys generating ASCII characters, the ASCII
code of the key will be returned. 'Special' keys like arrow
keys, PREVIOS PAGE, NEXT PAGE, INSERT, DELETE, and the
programmable function keys return values above 255. The
following symbols may be used to match special key codes:
Key code Label or Keys
------------- ----------------------
TTYCTL.K_HOME Home
TTYCTL.K_LEFT Left arrow
TTYCTL.K_RGHT Right arrow
TTYCTL.K_END End
TTYCTL.K_BKSP Backspace, <--, <X]
TTYCTL.K_DEL Del, Delete, Remove
TTYCTL.K_KILL Control + Backspace
TTYCTL.K_INS Ins, Insert
TTYCTL.K_CR CR, Enter, Return, <-'
TTYCTL.K_UP Up arrow
TTYCTL.K_DOWN Down arrow
TTYCTL.K_ESC ESC, Escape
TTYCTL.K_PREV Prev, PgUp, PageUp
TTYCTL.K_PGUP = K_PREV
TTYCTL.K_NEXT Next, PgDn, PageDn
TTYCTL.K_PGDN = K_NEXT
TTYCTL.K_F1 F1
TTYCTL.K_F2 F2
TTYCTL.K_F3 F3
TTYCTL.K_F4 F4
TTYCTL.K_F5 F5
TTYCTL.K_F6 F6
TTYCTL.K_F7 F7
TTYCTL.K_F8 F8
TTYCTL.K_F9 F9
TTYCTL.K_F10 F10
Some systems require to switch the TTY driver to raw mode (see
TTY.MODE) before single characters can be received from a
terminal.
See also: TTY.MODE, TTY.QUERY, TTY.WRITEC
3.10.14 TTY.RESET
TTY.RESET() ! => 0
Reset the terminal to a sane default state. Can be used to reset
the original color of the terminal before exiting. Note that
TTY.FINI should still be called after TTY.RESET. TTY.RESET may
be a null operation on terminals that do not support it.
See also: TTY.FINI
3.10.15 TTY.RSCROLL
TTY.RSCROLL(top, bottom) ! Num,Num => 0
Scroll the screen region from 'top' to 'bottom' down by one
line. At the top of the region, a blank line will be inserted
using the currently selected color. Line numbers start at 0.
See also: TTY.SCROLL, TTY.LINES, TTY.COLUMNS
3.10.16 TTY.SCROLL
TTY.SCROLL(top, bottom) ! Num,Num => 0
Scroll the screen region from 'top' to 'bottom' up by one line.
At the bottom of the region, a blank line will be inserted
using the currently selected color. Line numbers start at 0.
See also: TTY.RSCROLL, TTY.LINES, TTY.COLUMNS
3.10.17 TTY.WRITEC
TTY.WRITEC(c) ! Num => Num
Write the character 'c' to the terminal screen and return its
ASCII code. The character will be output at the current cursor
position. Writing a character advances the cursor. When the
cursor is at the rightmost column when writing a character, the
cursor position is undefined after the output operation.
See also: TTY.READC, TTY.WRITES
3.10.18 TTY.WRITES
TTY.WRITES(string) ! Str => 0
Write a string to the terminal screen as if each character of
the string had been written using TTY.WRITEC. However,
TTY.WRITES is usually faster than a series of character-based
TTY.WRITEC messages.
Writing to the screen does not necessarily wrap around at the
end of a line. When the given string does not fit in the space
between the current cursor position and the end of the line, the
result of the WRITES operation is undefined.
See also: TTY.WRITEC, TTY.READC
3.11 XMEM -- External Memory Interface
3.11.1 XMEM Class Usage
OBJECT XM[XMEM];
XM.INIT();
The XMEM class provides access to external memory blocks. An
external memory block is a continuous region of memory not
contained in the T3X data area. XM blocks are byte addressed.
Bytes in XM blocks can only be read and written using the
procedures XM.GET, XM.PUT, and friends, as defined by this
class.
The XMEM class does have state that is implemented in the
extension object part. Therefore, only one single instance of
the class may be loaded.
Since each external memory block must be completely addressable
using Tcode machine words, their sizes may not exceed 65536
bytes.
The XMEM class must be initialized by XM.INIT before its use
shut down by calling XM.FINI.
3.11.2 XM.INIT
XM.INIT() ! => 0
Initialize the external memory interface.
See also: XM.FINI
3.11.3 XM.ALLOC
XM.ALLOC(len) ! Num => Num | -1
Allocate a block of external memory of a size of 'len' bytes.
Upon success, return an identifier which may be used in
subsequent XM operations. In case of an error (out of memory /
out of IDs), return -1.
See also: XM.FREE
3.11.4 XM.COPY
XM.COPY(id, dest, source, len) ! => 0 | -1
Copy 'len' bytes from address 'source' to address 'dest' of the
external memory block referenced through ID. Neither 'dest' nor
'source' may exceed X-1-'len' where X is the size of the block
as specified at allocation time. 'Dest' and 'source' may overlap.
XM.COPY returns -1, if an invalid ID is passed to it.
See also: XM.ALLOC, XM.READ, XM.WRITE
3.11.5 XM.FINI
XM.FINI() ! => 0
Shut down the external memory interface.
See also: XM.INIT
3.11.6 XM.FREE
XM.FREE(id) ! Num => 0 | -1
Release a previously allocated external memory block. 'Id' is
an identifier returned by XM.ALLOC. GET returns -1, if an
invalid ID is passed to it.
See also: XM.ALLOC
3.11.7 XM.GET
XM.GET(id, index) ! Num,Num => Num | -1
Return the byte stored at address 'index' of the external
memory block referenced by 'id'. 'Index' may not exceed X-1
where X is the size of the block as specified at allocation
time. XM.GET returns -1, if an invalid ID is passed to it.
See also: XM.ALLOC, XM.PUT, XM.READ.
3.11.8 XM.PUT
XM.PUT(id, index, value) ! => Num | -1
Replace the value of the byte stored at address 'index' of the
external memory block referenced through 'id' with 'value'.
'Index' may not exceed X-1 where X is the size of the block as
specified at allocation time. All but the least significant 8
bits of 'value' will be discarded.
XM.PUT returns -1, if an invalid ID is passed to it.
See also: XM.ALLOC, XM.GET, XM.WRITE.
3.11.9 XM.READ
XM.READ(id, index, buffer, len) ! => 0 | -1
Copy 'len' bytes stored at address 'index' of the external
memory block referenced by 'id' into 'buffer'. 'Index' may not
exceed X-1-'len' where X is the size of the block as specified
at allocation time.
XM.READ returns -1, if an invalid ID is passed to it.
See also: XM.ALLOC, XM.COPY, XM.GET, XM.WRITE
3.11.10 XM.WRITE
XM.WRITE(id, index, buffer, len) ! => 0 | -1
Copy 'len' bytes from 'buffer' to the address 'index' of the
external memory block referenced through ID. 'Index' may not
exceed X-1-'len' where X is the size of the block as specified
at allocation time.
XM.WRITE returns -1, if an invalid ID is passed to it.
See also: XM.ALLOC, XM.COPY, XM.PUT, XM.READ
4. The Virtual Tcode Machine
The Tcode machine is the target of the reference implementation
of T3X. Tcode is suitable for both interpretation and
transformation to native code. It also provides mechanisms for
static linking so that multiple Tcode modules can be linked
together forming one single program. Since version 3, support
for object oriented programming is built into the virtual Tcode
machine. This chapter describes Tcode7 and its virtual machine
in detail.
4.1 The Architecture
The Tcode machine is a virtual 16-bit machine basically
consisting of the following parts:
+---------------+0xFFFF 0xFFFF+---------------+
| | | |
| | :-- 16 bits --: | Stack |
| U n u s e d | +-------------+ | and |
| S p a c e | +---| IP | | Dynamic |
| | | +-------------+ +--->| Storage |
| | | | RR | | | |
|- - - - - - - -| | +-------------+ | +->|- - - - - - - -|
| | | | FP |--+ | | F r e e |
| | | +-------------+ | | |
| Tcode Program |<--+ | SP |----+ | M e m o r y |
| | +-------------+ | |
| Instructions | | SELF |---+ |- - - - - - - -|
| | +-------------+ | | Static |
| | REGISTERS +-->| Data |
| | | |
+---------------+0x0000 0x0000+---------------+
CODE ARRAY DATA ARRAY
Fig.5 The Architecture of the Tcode Machine
There are two byte-addressable memory regions called the 'code
array' and the 'data array'. The code array holds the Tcode
program that is to be executed and the data array is used to
hold the data used by the program. Each cell in one of the
arrays is completely addressable using a 16-bit pointer, so
the maximum size for each array is 65536 bytes.
Machine words - which are always 2 bytes wide - are stored with
the least significant byte in the cell with the lower address:
0x1234 = 0x34 0x12 (little endian byte ordering). However, this
byte ordering applies only to the way machine words are stored
in Tcode programs. Native code back ends of the Tcode machine
may store machine words in any format, so the result of
accessing the individual bytes of a machine word is undefined.
The Tcode machine has five 16-bit wide special purpose registers
which are outlined in the following overview.
FP, the Frame Pointer.
The frame pointer always points to the stack frame (aka context)
of the currently running procedure. FP is implicitly referenced
by the instructions LDL, LDLV, SAVL, and INCL, which address
local objects. FP is modified only by HDR, END, MHDR, and ENDM
instructions. See also: 'calling conventions'.
IP, the Instruction Pointer.
This register always points to the instruction that will be
interpreted next. IP is interpreted as an offset into the code
array. It cannot be accessed directly and it is changed by
jump, call, and branch instructions.
RR, the Return Register.
This register is used to transport procedure results back to the
caller. The return register is loaded by the POP instruction and
saved by CLEAN. See also: 'calling conventions'.
SELF, the instance context pointer.
SELF points to the instance context that is currently in effect.
This is equal to the first byte of the data space of the object
that is currently receiving a message. Instance contexts are
static. They are established using MHDR and released using ENDM.
The SELF register is used by the LDI, LDIV, and INCI
instructions to compute the addresses of instance variables. See
also: 'instance contexts'.
SP, the Stack Pointer.
The stack pointer points to the object most recently placed on
the stack. Moving an object onto the stack implicitly decreases
SP by one machine word. Removing an object increases it by one
machine word. SP may be explicitly modified using the STACK
instruction.
The Tcode machine instructions can be divided into the following
nine groups:
- declarations
- context manipulation
- stack manipulation
- arithmetic
- predicates
- loading and storing
- flow control
- external linkage
- source level debugging
Declarations, external linkage, and debug instructions will be
processed only once (therefore, they may be resolved in a
preprocessing step). This means that an instruction like
STR 5 H e l l o
will not create a new string literal each time it is
interpreted, but only at the first time. (One might also think
of this behavior as creating the same object each time a
declaration executed).
Arithmetic instructions and predicates expect their arguments on
the runtime stack and also place their results there. Since
there are no general purpose registers, most operations are
performed on stack elements.
4.2 Calling Conventions
A procedure must always begin with a HDR instruction, which
saves the caller's context and creates a new stack frame. It
must end with an END instruction, which restores the saved stack
frame and jumps back to the caller.
A procedure call
p(a, b, c)
where a, b and c be global variables, is coded as follows:
LDG La LDG Lb LDG Lc CALL Lp CLEAN 3
Each LDG instruction loads the value of a global variable onto
the stack. 'Lx' denotes the label pointing at the memory
location 'x'. CALL performs the procedure call which returns
with its result in the Return Register (RR). 'Lp' denotes the
label tagging the procedure 'p'. The final CLEAN instruction
removes the three arguments from the stack and replaces them
with the value returned in RR so that the top stack element
finally holds the procedure return value.
Each procedure may expect the following stack configuration when
called:
FP+M Argument #1
... ...
FP+3 Argument #N-1
FP+2 Argument #N
FP+1 Return Address (saved by CALL or CALR)
FP+0 Old SP (saved by HDR)
FP-1 Local Variable #1
FP-2 Local Variable #2
... ...
SP FP-J Local Variable #K
(free memory starts here)
Note1: SP and FP-J point to the same address.
Note2: The arguments are passed to the procedure in reverse
order with the first argument at the highest address.
Both arguments and local variables may be accessed using LDL
instructions. Given the above context,
LDL -M
would access the first argument.
LDL -2
always loads the value of the last argument, if any. Local
storage is accessed using positive offsets:
NUM 25 SAVL 2
would store 25 in the second local variable.
Note: negative values in local storage instructions address
arguments, negative values address local variables!
4.3 Instance Contexts
A method is a procedure that is used to access the data of an
object. Instead of the usual procedure frame as described in
the previous section, it should contain instructions to build
destroy a local context and establish and restore the instance
context, which is held in the SELF register. The MHDR
instruction, which establishes the instance context, expects the
new context pointer at FP+2. ENDM is like END, but also restores
the instance context of the caller. The Tcode of a method looks
like this:
CLAB procedure-label
MHDR
... code ...
CLAB exit-label
ENDM
Passing a message M with three arguments to a global object O
o.m(1,2,3);
would be coded as follows:
NUM 1 NUM 2 NUM 3 LDGV Lo CALL Lm CLEAN 4
Each called method may expect the following stack configuration:
FP+M Argument #1
... ...
FP+4 Argument #N-1
FP+3 Argument #N
FP+2 Receiver's Address
FP+1 Return Address (saved by CALL or CALR)
FP+0 Old SP (saved by MHDR)
FP-1 Sender's Address (Old Instance Context, saved by MHDR)
FP-2 Local Variable #1
FP-3 Local Variable #2
... ...
SP FP-J Local Variable #K
( Free memory starts here )
4.4 Instruction Cycles
A cycle is the set of operations which is required to execute
one single Tcode instruction. Each cycle consists of the
following steps:
(1) Load the instruction pointed to by IP. Increment IP by 1.
(2) If the instruction has an operand (bit #7 is set), load the
machine word pointed to by IP into an internal register and
increment IP by 2.
(3) If the loaded instruction has an opcode which is equal to or
greater then the opcode of INIT, the instruction has two
operands. Load another machine word (pointed to by IP) into
another internal register and increment IP by 2.
(4) If the loaded instruction is valid, execute it, otherwise
signal an error and halt the machine.
These steps are repeated until the Tcode machine is halted by
executing HALT.
If an instruction modifies stack elements, first all its
operands are removed from the stack, then the operation denoted
by the instruction is performed, and finally the result is
placed back on the stack.
4.5 Startup Conditions
This section describes the state of the Tcode machine when it
is started.
* The contents of the code array and data array are undefined.
* The content of the Return Register RR is undefined.
* The content of the class context pointer SELF is undefined.
* The Instruction Pointer IP is set to zero. (Hence it is a good
idea to load programs at the bottom of the code array.)
* The Stack Pointer SP and the Frame Pointer FP are both set to
zero (or 65536 on non-16-bit hosts) so that decrementing them
by two will give the address of the highest addressable
machine word (65534).
4.6 Symbols Used to Describe Tcode
Size
Symbol (bits) Description
--------- ------ --------------------------------------------
M N 16 signed numeric values
.N .M 16 unsigned numeric values
L 16 a label tagging a data word or a procedure
A 16 an address tagged by a label
E 16 a label referencing an external procedure
I 16 a label referencing an interface procedure
C 8 a character
X1...XN 16*X a vector containing N elements of the type X
memory[X] 16 the content of the X'th machine word in the
data array
memory::X 8 the content of the X'th byte in the data
array
S0...SN 16 the N+1 elements most recently pushed onto
the stack
Annotations
Normally, the most significant bit of each machine word is
interpreted as a sign flag (1 indicates a negative number). The
leading dot notation .N indicates that the MSB of N should be
treated as a part of the value instead of a sign indicator.
An address is an offset into the code or data array where the
base (code or data array) is implicitly specified by the
associated instruction. Addresses are 16 bits wide.
External labels are used to create a connection between the name
of an external procedure and a reference to such a procedure.
Interface labels are used to create a connection between the
name of an interface procedure and a reference to such a
procedure.
S0 denotes the element most recently pushed onto the stack. When
popping elements from a stack holding N+1 elements, S0 will be
removed first and SN will be removed last.
4.7 Declarations
0x82 CLAB L - Code LABel
Define a label identified by the value L that tags a subsequent
procedure.
0x85 CREF L - Code REFerence
Define a word-size storage location holding the address of the
procedure tagged by the label L.
0x84 DATA N - DATA definition
Define a word-size storage location containing the value N.
0x87 VEC N - VECtor declaration
Define a vector with a length of N machine words and undefined
content.
0x83 DLAB L - Data LABel
Define a label identified by the value L that tags a subsequent
data object.
0x86 DREF L - Data REFerence
Define a word-size storage location holding the address of the
data object tagged by the label L.
0xCD INIT N L - INITialize
Originally used to initialize the Tcode environment - hence its
name. Each program must begin with this instruction. The
argument N specifies the Tcode version to which the program
complies. This document describes version 7 of the Tcode
language. L is a code label tagging the initial entry point of
the Tcode module containing the instruction.
0x88 STR N C1 ... CN - define STRing
Define a vector with a length of (N+2) / 2 machine words
containing the characters C1 through CN. Each character is
stored in a separate byte. All trailing bytes of the vector are
filled with zeros so that a properly terminated string is
created.
4.8 Context Manipulation
0x0A END - END procedure
Remove two elements S0 and S1 from the stack. Restore the
context of the calling procedure by loading FP with S0 and then
perform a branch to S1. S1 is a return address which has been
saved by a CALL or CALR instruction.
0x0C ENDM - END Method
First, load SELF with the value previously saved on the stack by
MHDR, thereby restoring the instance context of the sender. The
sender's context will be removed from the stack. Then, perform
END, as described above.
0x09 HDR - HeaDeR
Push the context of the calling procedure (FP) and create a
fresh procedure context by loading FP with SP.
0x0B MHDR - Method HeaDeR
First perform HDR, as described above. Then, push the context of
the sending method or procedure (SELF) and establish a new
instance context by loading SELF with the machine word pointed
to by FP+2 (the last argument passed to the answering method).
4.9 Stack Manipulation
0x91 CLEAN N - CLEAN up arguments
Remove N procedure arguments from the stack: SP := SP + N*2, and
then push the content of RR, the return register, to the stack.
0x0E DUP - DUPlicate
Push the current top of the stack (S0), thereby duplicating it.
0x0D POP
Pop the top element S0 and load it into the return register RR.
0x90 STACK N
Move the stack pointer SP by N machine words: SP := SP - N*2.
Moving the stack pointer 'down' (N>=1) allocates space on the
stack, moving it 'up' (N<=-1) deallocates space. STACK is
primarily used to allocate and release dynamic memory in
procedures.
0x0F SWAP
Exchange the values of S0 and S1.
4.10 Arithmetic Instructions
0x1A ADD
Remove two elements S0 and S1 and push their sum: S1 + S0.
0x1C BAND - Bitwise AND
Remove two elements S0 and S1, perform a bitwise AND on them and
push the result: S1 & S0.
0x14 BNOT - Bitwise NOT
Invert each bit of the top element: ~S0.
0x1D BOR - Bitwise OR
Remove two elements S0 and S1, perform a bitwise OR on them and
push the result: S1 | S0.
0x1F BSHL - Bitwise SHift Left
Remove two elements S0 and S1, shift the bits of S1 to the left
by S0 positions and push the result: S1 << S0.
0x20 BSHR - Bitwise SHift Right
Remove two elements S0 and S1, shift the bits of S1 to the right
by S0 positions, clear the most significant byte, and push the
result: S1 >> S0.
0x1E BXOR - Bitwise eXclusive OR
Remove two elements S0 and S1, perform a bitwise XOR on them and
push the result: S1 ^ S0.
0x16 DIV - integer DIVide
Remove two elements S0 and S1, compute the (signed) integer part
of their quotient and push it: S1 / S0. If S0 = 0, signal a
fatal error and halt.
0xCE INCG L N - INCrement Global
Add the value N to the memory cell tagged by the label L. This
is exactly the same as LDG L NUM N ADD SAVG L, but much more
efficient.
0xCF INCI M N - INCrement Instance variable
Add the value N to the memory cell whose absolute address is
SELF + M*2. INCI M N is equal to LDI M NUM N ADD SAVI M, but
much more efficient.
0xD0 INCL M N - INCrement Local
Add the value N to the memory cell whose absolute address is
FP - M*2. INCL M N is equal to LDL M NUM N ADD SAVL M, but much
more efficient.
0x13 LNOT - Logical NOT
If the top element is equal to zero, replace it with -1 and
otherwise replace it with zero: S0 = 0-> -1: 0.
0x19 MOD - MODulo
Remove two elements S0 and S1, compute their division remainder
and push it: S1 MOD S0. S1 MOD S0 is defined as S1 - S1./S0.*S0
If S0 = 0, signal a fatal error and halt.
0x15 MUL - MULtiply
Remove two elements S0 and S1, compute their (signed) product
and push it: S1 * S0. Do not perform any overflow checking.
0x12 NEG - NEGate
Negate the top element: -S0.
0x00 GLUE - GLUE (no operation)
Rest for a cycle.
0x1B SUB - SUBtract
Remove two elements S0 and S1 and push their difference:
S1 - S0.
0x18 UDIV - Unsigned integer DIVide
Remove two elements S0 and S1, compute the integer part of their
unsigned quotient and push it: S1 ./ S0. If S0 = 0, signal a
fatal error and halt.
0x17 UMUL - Unsigned MULtiply
Remove two elements S0 and S1, compute their unsigned product
and push it: S1 .* S0. Do not perform any overflow checking.
4.11 Predicates
0x21 EQU - EQUal
Remove two elements S0 and S1. Push true, if they are equal and
otherwise push false: S1 = S0-> -1: 0.
0x24 GRTR - GReaTeR than
Remove two elements S0 and S1. Push true, if S1 is greater than
S0 and otherwise oush false: S1 > S0-> -1: 0. S0 and S1 are both
signed.
0x26 GTEQ - Greater Than or EQual to
Remove two elements S0 and S1. Push true, if S1 is greater than
or equal to S0 and otherwise push false: S1 >= S0-> -1: 0. S0
and S1 are both signed.
0x23 LESS - LESS than
Remove two elements S0 and S1. Push true, if S1 is less than S0
and otherwise push false: S1 < S0-> -1: 0. S0 and S1 are both
signed.
0x25 LTEQ - Less Than or EQual to
Remove two elements S0 and S1. Push true, if S1 is less than or
equal to S0 and otherwise push false: S1 <= S0-> -1: 0. S0 and
S1 are both signed.
0x22 NEQU - Not EQUal
Remove two elements S0 and S1. Push true, if they are not equal
and otherwise push false: S1 \= S0-> -1: 0.
0x28 UGRTR - Unsigned GReaTeR than
Remove two elements S0 and S1. Push true, if .S1 is greater than
.S0 and otherwise push false: S1 .> S0-> -1: 0.
0x2A UGTEQ - Unsigned Greater Than or EQual to
Remove two elements S0 and S1. Push true, if .S1 is greater than
or equal to .S0 and otherwise push false: S1 .>= S0-> -1: 0.
0x27 ULESS - Unsigned LESS than
Remove two elements S0 and S1. Push true, if .S1 is less than
.S0 and otherwise push false: S1 .< S0-> -1: 0.
0x29 ULTEQ - Unsigned Less Than or EQual to
Remove two elements S0 and S1. Push true, if .S1 is less than or
equal to .S0 and otherwise push false: S1 .<= S0-> -1: 0.
4.12 Load and Store Instructions
0x34 DEREF - DEREFerence
Remove two values S0 and S1, load a machine word from
memory[S1/2+S0] and push it. A NORM instruction is implied.
It converts a pointer (S1) and an offset (S0) to a pointer.
0x35 DREFB - DeREFerence Byte
Remove two values S0 and S1, load a single byte from
memory::(S1+S0), and push it. A NORMB instruction is implied. It
converts a pointer (S1) and an offset (S0) to a pointer.
0xAB LDG L - LoaD Global
Push the value stored in the memory cell A tagged by the label
L: memory[A/2].
0xAC LDGV L - LoaD Global Vector
Push the address A tagged by the label L.
0xAF LDI N - LoaD Instance variable
Push the value located at memory[(SELF/2)+N]. This instruction
is used to load the content of an instance variable. N specifies
the offset of the variable relative to the beginning of the
object's data area.
0xB0 LDIV N - LoaD Instance Vector
Push the address SELF+N*2. This instruction is used to load the
address of an instance variable. N specifies the offset of the
variable relative to the beginning of the data area of the
currently instance context.
0xAD LDL N - LoaD Local
Push the value stored at the N'th position 'below' the stack
frame base. The address of the cell is computed using the
formula FP - N*2. Consequently, negative values of N may be
used to access locations 'above' the frame base.
0xB1 LDLAB L - LoaD LABel
Push the address A tagged by the label L. This instruction is
similar to LDGV, but more general. It may also be used to
load addresses of procedures.
0xAE LDLV N - LoaD Local Vector
Push the absolute address of a local object. N specifies the
offset of the object relative to the stack frame base. The
absolute address is computed using the formula FP - N*2.
0x36 NORM - NORMalize reference
Remove two elements S0 and S1 and compute the absolute address
of the S0'th member of the vector pointed to by S1: S1 + S0*2.
Push the computed address. This instruction converts a pointer
plus a machine word offset into a pure pointer that references
the same location.
0x37 NORMB - NORMalize Byte reference
Remove two elements S0 and S1 and compute the absolute address
of the S0'th byte of the vector pointed to by S1 (S0+S1). Push
the computed address. This instruction converts a pointer plus
a byte offset into a pure pointer which references the same
location. This instruction is technically the same as ADD, but
conceptionally different.
0xB2 NUM N - load NUMber
Push the value N.
0xB8 SAVG L - SAVe Global
Pop one element and save it in the memory cell A tagged by the
label L: memory[A/2] := S0.
0xBA SAVI N - SAVe Instance variable
Pop one element and save it in the memory cell
memory[(SELF/2)+N]. This instruction is used to alter the state
of an instance variable. N specifies the offset of the variable
relative to the beginning of the current instance context.
0xB9 SAVL N - SAVe Local
Pop one element and save it in the storage cell with the address
FP - N*2. See also LDL.
0x33 SELF - SELF reference
Push the content of the SELF register onto the stack.
0x3C STORB - STORe Byte
Pop two elements S0 and S1 and store the least significant 8
bits of S0 in the byte pointed to by S1: memory::S1 := S0.
0x3B STORE
Pop two elements S0 and S1 and store the value S0 in the memory
cell pointed to by S1: memory[S1/2] := S0.
4.13 Flow Control
0xBD BRF L - BRanch on False
Remove the element S0 and branch to the address A tagged by the
label L, if S0 is false.
0xBE BRT L - BRanch on True
Remove the element S0 and branch to the address A tagged by the
label L, if S0 is true.
0xC5 CALL L - procedure CALL
Push the current value of the instruction pointer IP and then
perform a branch to the address A tagged by the label L.
0x46 CALR - CALl through Register
Push the current value of the instruction pointer IP and then
remove the element S0 from the stack and perform a branch to the
location to which it points. The destination is implicitly
located in the code array of the program (branches to the data
array cannot be done).
0xC3 DNEXT L - Downward NEXT
Remove two elements S0 and S1 and branch to the address A tagged
by the label L, if S1 <= S0.
The instructions UNEXT and DNEXT have been designed for use in
counting loops (called FOR-NEXT loops in BASIC). The idea is as
follows: Before the loop and at the end of the loop, the current
loop index and the loop limit are both pushed onto the stack.
UNEXT compares the values and branches out of the loop, if
index>=limit. DNEXT branches, if index<=limit. Therefore, UNEXT
is used in upward counting loops and DNEXT is used in countdown
loops.
0xC8 SYS N - SYStem call (OBSOLETE)
Execute the system procedure associated with the index value N.
The index value is removed and a call-dependent number of
arguments is passed to the respective system procedure. The
system procedure may return a machine word size return value in
the Return Register. The stack must me cleaned up using CLEAN
after calling a system procedure. System procedures are
implemented as methods of the T3X core class. Therefore, they
should only be invoked by sending a message to an instance of
the T3X class. The exact semantics of SYS depend on the called
NOTE: **********************************************************
The SYS instruction in no longer required in T3X Release 7, and
implementations of the Tcode Machine are no longer required to
support it. Compilers should emit ICALL instead.
****************************************************************
0xCA ICALL N - Interface CALL
Call the interface procedure located at slot N. Slot values are
dynamically generated using IPROC, IREF, and ICALX. The
interface procedure may return a machine word size return value
in the Return Register. The stack must me cleaned up using CLEAN
after calling an interface procedure. System procedures are
normally implemented in languages other than T3X (such as C or
assembly language). They are used to extend the T3X runtime
environment. The exact semantics of ICALL depend on the called
procedure.
0xC4 HALT N
Instantly halt the Tcode machine. The least significant eight
bits of N will be delivered as a status code to the process that
invoked the Tcode Machine program.
0xC1 JUMP L
Unconditionally jump to the address A tagged by the label L.
0xBF NBRF L - Nondestructive BRanch on False
Branch to the address A tagged by the label L, if S0 is false.
Do not remove S0.
0xC0 NBRT L - Nondestructive BRanch on True
Branch to the address A tagged by the label L, if S0 is true. Do
not remove S0.
0xC2 UNEXT L - Upward NEXT
Remove two elements S0 and S1 and branch to the address A tagged
by the label L, if S1 >= S0. See also: DNEXT.
4.14 External Linkage
0xC7 CALX E - CALl eXternal procedure
Call a procedure contained in a different module. There must be
an EXT record defining the external label E in the same module
and a PUB record with the same name in another module. Both are
required for the external reference to be resolved.
0xD5 CMAP N M - Call MAP
Call maps describe the arguments of interface procedures. The
operands of CMAP are identical to the parameters of interface
declarations (see IDECL for details).
0xD2 EXT E N C1 ... CN - EXTernal reference
Create an external reference to the symbol represented by the
characters C1 through CN. E is a so-called external label. Such
labels are used to reference external symbols in CALX
instructions. See the section on loading Tcode for details.
Note: When interpreting a Tcode program, this instruction will
cause an error (unresolved external reference).
0xCB ICALX I - Interface CALl of eXternal procedure
Call the interface procedure described by the interface label I.
There must be an IREF record defining I in the same module. A
corresponding IPROC record with the same name as the IREF record
must be supplied to the Tcode loader to resolve the reference.
0xC9 ILIB N C1 ... CN - Interface LIBrary
Name the relocatable object file or library containing the
interface procedures described by the IPROC records in this
module. This name can be used for linking the necessary
libraries when translating Tcode to native code or to make
sure that a Tcode machine provides the required extensions.
0xD3 IPROC N M C1 ... CN - Interface PROCedure
Assign the interface procedure named by the characters C1 though
CM to the interface slot N. IPROC records are also used to
resolve ICALX instructions. See the section on resolving
interface references for details.
0xD4 IREF I N C1 ... CN - Interface REFerence
Create an interface reference to the symbol represented by the
characters C1 through CN. I is a so-called interface label. Such
labels are used to reference interface procedures in ICALX
instructions. See the section on resolving interface references
for details. Note: When interpreting a program containing IREF
by a Tcode machine, this instruction will lead to an error
(unresolved interface reference).
0xD1 PUB L N C1 ... CN - PUBlic reference
Signal the Tcode linker that the procedure tagged by the label L
is public and can be referenced externally using the name formed
by the characters C1 through CN. Again, see the section on
loading Tcode for details. When interpreting programs using a
Tcode machine, this instruction type may be ignored safely.
4.15 Source Level Debugging Support
0xD6 GSYM L N C1...CN - Global SYMbol
Name a global symbol. C1 through CN contain the characters of
the symbol name. L is the ID of the label which marks the named
symbol. GSYM instructions should be generated for global
variable names.
0xD8 ISYM M N C1...CN - Instance SYMbol
Name an instance variable. C1 through CN contain the characters
of the symbol name. M is the offset in machine words (into the
current class context) of the data object named by the symbol.
0xC6 LINE N - LINE number
Indicate that the following instructions were created from line
N of the source code from which the Tcode program was generated.
0xD7 LSYM M N C1...CN - Local SYMbol
Name a local symbol. C1 through CN contain the characters of the
symbol name. M is a signed number holding the position of the
variable relative to the Frame Pointer.
4.16 Meta Information
0x81 HINT N - pass a HINT
Pass some interesting information to later stages of the
compiler, like the optimizer or the code generator. The
information itself is encoded in a single machine word. Hint
instructions are null operations when executed by the Tcode
machine. When a program (like a code generator) detects a HINT
in a context where it does not expect one, it may safely ignore
it.
4.16.1 Generated Hints
The following hints are currently generated by Release 7 of the
the T3X translator
HDR HINT N
The number of formal arguments of the procedure being defined.
Note: This value is particularly useful when translating Tcode
back into a high level language, since they allow to create a
procedure header with the proper number of formal arguments
without having to scan the entire procedure body.
MHDR HINT N
The number of formal arguments of the method being defined plus
one. The new instance context passed to the method is also an
argument. Therefore, N is one higher than the number of
arguments defined in the original T3X source program. See also
the note in description of the HDR instruction.
VEC M HINT N
The size of an allocation unit in bytes. If this hint is
present, the VEC statement will allocate
M + ((BPW/N)-1)
M' = ---------------
BPW/N
machine words (where BPW = the size of bytes per machine word on
the target platform). Currently, N=2 is emitted for byte
vectors. Optionally, a value of N=0 may be considered equal to
N=BPW. On the Tcode machine, M'=M since BPW=2.
This hint is intended to avoid over-allocation of memory on
native platforms with large machine word sizes. Byte vector
sizes are always specified in 16-bit machine words, which would
lead to 2x over-allocation on 32-bit and 4x over-allocation on
64-bit machines. This hint allows non-16-but back ends to
allocate memory for byte vectors more efficiently.
4.17 Loading Tcode
The Tcode machine provides a set of instructions for linking
together modules that were compiled separately to Tcode.
External references are limited to procedure calls. This means
that a module can call procedures defined in an external module,
but it cannot access the data of an external module.
To call an external procedure, the label that tags the entry
point of the routine must be declared public (using a PUB
instruction) in the module containing the called routine. In the
module of the caller, it must be declared extern (using EXT).
The 'extern' declaration creates a so-called external label
which may be used in calls to external procedures (CALX
instructions).
The PUB instruction provides a symbolic name for a procedure.
This symbolic name may be referred to by an EXT instruction in a
different module. CALX is used to refer to an EXT instruction
defined in the same module as the EXT record. An external
reference is resolved in four steps:
(1) The external label, which is the operand of a CALX
instruction, is looked up in the external symbol table (a table
holding EXT records).
(2) The name contained in the EXT record is looked up in the
public symbol table (a table holding PUB records).
(3) The label contained in the matching PUB record replaces the
external label in the CALX instruction.
(4) CALX is replaced with CALL.
The following figure illustrates the principle of external
references.
+----------------------------+ +----------------------------+
| | | |
| ,--> EXT E 4 name >================> PUB L 4 name |
| | | | CLAB L HDR ... END |
| '-------.-.-----------, | | |
| | | | | | |
| CALX E >--' | CALX E >-' | | |
| | | | |
| CALX E >-' | | |
| | | |
+----------------------------+ +----------------------------+
Caller's Module Callee's Module
Fig.6 External References
Additional Notes
Since labels are represented by integers in Tcode, label
collisions will occur when linking two (or more) Tcode modules
together. Therefore, labels must be renamed in this case: When
a module A already has been loaded and a module B is to be
loaded, the highest label ID used in A must be added to each
(non-external) label in B.
Two or more EXT records with the same name may exist, because
the same symbol may be associated with different external labels
in different modules.
The existence of two PUB records with the same name is an error
(redefinition error).
There must be a matching PUB record for each EXT record.
Otherwise, an error is signalled (unresolved external).
4.18 Resolving Interface References
Interface references are references to procedures which are not
located in the code area of the Tcode machine. Modules can
provide interfaces by exporting IPROC records and request
interfaces using IREF records. ICALX instructions are used to
call unresolved interfaces and ICALL instructions are used to
call resolved interfaces.
Notice that resolving an interface means to assign a unique slot
number to the name of an interface procedure. It is in the
responsibility of the Tcode machine to place the correct
procedure in this slot. IPROC records are used to assign names
to slot numbers.
Since multiple modules may export IPROC records and each module
starts numbering interfaces at one, the Tcode loader must
relocate IPROCs by assigning unique slot numbers to them.
IPROC records and corresponding IREF records may be located in
the same module. In any case, though, the IPROC record must
precede the IREF record and the IREF record must precede any
ICALX instructions referencing the IREF record. In this
section, IPROC and IREF are assumed to be in a different
modules.
IPROC records provide a symbolic name for an interface
procedure. This symbolic name may be referred to by IREF records.
ICALX instructions are used to refer to IREF records defined in
the same module. An external reference is resolved in four
steps:
(1) The that which is the operand of a ICALX instruction is
looked up in a table holding IREF records.
(2) The name contained in the matching IREF record is looked up
in another table which holds IPROC records.
(3) The label contained in the matching IPROC record replaces
the external label in the ICALX instruction.
(4) ICALX is replaced with ICALL.
The following figure illustrates the principle of interface
references.
Caller's Module Callee's Module
+----------------------------+ +----------------------------+
| | | |
| ,--> IREF I 4 name >===============> IPROC L 4 name |
| | | | \/ |
| '-------.-.-----------, | | || |
| | | | | | || |
| ICALX I >--' | ICALX I >-' | | || |
| | | | || |
| ICALX I >-' | | || |
| | | || |
+----------------------------+ +----------||----------------+
||
Tcode Machine or external object ||
+----------------------------------------------||----------------+
| || |
| Interface procedure slot #0 || |
| ... || |
| Interface procedure slot #L <============' |
| ... |
| |
+----------------------------------------------------------------+
Fig.7 Interface References
The existence of two IPROC records with the same name is an
error (redefinition error).
5. Formal Definitions
5.1 Syntax Description Language
The syntax of the T3X language is described using a BNF-style
format similar to the one accepted by the YACC parser generator.
A more detailed description follows.
The T3X grammar is described as a set of rules of the following
format:
Name:
Pattern-1
| Pattern-2
| ...
| Pattern-N
;
It reads 'Name may also be written as Pattern-1 OR Pattern-2
OR ... OR Pattern-N'. Each pattern may consist of names of
rules or terminal symbols. Each terminal symbol is enclosed in
apostrophes, like '=', 'CONST', or '0x'. An apostrophe may be
included in a terminal (symbol) by doubling it. Consequently, a
terminal represented by an apostrophe is written ''''.
Here is an example: The rule
BinaryDigit: '0' | '1' ;
is read 'A BinaryDigit may be represented by either the string
'0' or the string '1'. A (recursive) rule to define
arbitrary-length binary numbers based upon BinaryDigit would
look like this:
BinaryNumber:
BinaryDigit
| BinaryDigit BinaryNumber
;
In this case, a BinaryNumber would be either a single
BinaryDigit or a BinaryDigit followed by another BinaryNumber
(and therefore more BinaryDigits).
The ampersand symbol (&) is used to indicate that no white space
is allowed between the elements of a pattern. While the above
rule would match the string
1 0 1 1 0 1 0 1
a rule containing the concatenation symbol would match the
string
10110101
Such a rule would be written as:
BinaryNumber:
BinaryDigit
| BinaryDigit & BinaryNumber
;
Ellipses (...) are used to represent obvious parts of sequences
in patterns. For example, the following two patterns are equal:
'0'|'1'|...|'8'|'9'
'0'|'1'|'2'|'3'|'4'|'5'|'6'|'7'|'8'|'9'
A special rule named <character>, which is not defined inside
of the formal grammar, is used to refer to an arbitrary ASCII
character.
Note that T3X is case-insensitive. Hence all alphabetic string
in the following grammar match any combination of upper and
lower case letters. E.g. 'WHILE' would match 'while', 'While',
'WHILE', 'wHiLe', and all other combinations.
5.2 The Formal Syntax
Program:
DeclList CompoundStmt
;
DeclList:
Declaration
| Declaration DeclList
;
Declaration:
'VAR' VarDeclList ';'
| 'CONST' ConstDeclList ';'
| 'DECL' ForwardDeclList ';'
| 'STRUCT' Symbol '=' StructMemList ';'
| ProcDecl
| ClassDecl
| 'PUBLIC' ClassDecl
| 'OBJECT' ObjDeclList ';'
| 'MODULE' Symbol '(' ModList ')' ';'
| 'MODULE' Symbol '(' ')' ';'
;
VarDeclList:
VarDecl
| VarDeclList ',' VarDecl
;
VarDecl:
Symbol
| Symbol '[' ConstValue ']'
| Symbol '::' ConstValue
;
ConstDeclList:
Symbol '=' ConstValue
| Symbol '=' ConstValue ',' ConstDeclList
;
ModList:
Symbol
| Symbol ',' ModList
;
StructMemList:
Symbol
| Symbol ',' StructMemList
;
ClassDecl:
'CLASS' Symbol '(' ModList ')' InstDeclList 'END'
| 'CLASS' Symbol '(' ')' InstDeclList 'END'
| 'ICLASS' Symbol '(' String ')' IClassInstDeclList 'END'
;
IClassInstDeclList:
IClassInstDecl
| IClassInstDecl IClassInstDeclList
;
InstDeclList:
InstDecl
| InstDecl InstDeclList
;
IClassInstDecl:
InterfaceDecl
| InstDecl
;
InstDecl:
'VAR' VarDeclList ';'
| 'CONST' ConstDeclList ';'
| 'DECL' ForwardDeclList ';'
| 'STRUCT' Symbol '=' StructMemList ';'
| ProcDecl
| 'OBJECT' ObjDeclList ';'
| 'PUBLIC' ProcDecl
| 'PUBLIC' 'CONST' ConstDeclList ';'
| 'PUBLIC' 'STRUCT' Symbol '=' StructMemList ';'
;
InterfaceDecl:
'IDECL' InfDeclList
;
InfDeclList:
InfDecl
| InfDecl ',' InfDeclList
;
InfDecl:
Symbol '(' ConstValue ',' ConstValue ')'
;
ObjDeclList:
Symbol '[' Symbol ']'
| Symbol '[' Symbol ']' ',' ObjDeclList
;
ForwardDeclList:
ForwardDecl
| ForwardDecl ',' ForwardDeclList
;
ForwardDecl:
Symbol '(' ConstValue ')'
;
ProcDecl:
Symbol '(' ArgumentList ')' Statement
| Symbol '(' ')' Statement
;
ArgumentList:
Symbol
| Symbol ',' ArgumentList
;
Statement:
CompoundStmt
| Symbol ':=' Expression ';'
| Symbol Subscripts ':=' Expression ';'
| ProcedureCall
| 'CALL' ProcedureCall ';'
| Symbol '.' ProcedureCall ';'
| 'SEND' '(' Symbol ',' Symbol ',' ProcedureCall ')' ';'
| 'IF' '(' Expression ')' Statement
| 'IE' '(' Expression ')' Statement 'ELSE' Statement
| 'WHILE' '(' Expression ')' Statement
| 'FOR' '(' Symbol '=' Expression ',' Expression ')'
Statement
| 'FOR' '(' Symbol '=' Expression ',' Expression ','
ConstValue ')'
Statement
| 'LEAVE' ';'
| 'LOOP' ';'
| 'RETURN' ';'
| 'RETURN' Expression ';'
| 'HALT' ';'
| 'HALT' ConstValue ';'
| ';'
;
CompoundStmt:
'DO' 'END'
| 'DO' LocalDeclList 'END'
| 'DO' StatementList 'END'
| 'DO' LocalDeclList StatementList 'END'
;
LocalDeclList:
LocalDecl
| LocalDecl LocalDeclList
;
LocalDecl:
'VAR' VarDeclList ';'
| 'CONST' ConstDeclList ';'
| 'STRUCT' Symbol '=' StructMemList ';'
| 'OBJECT' ObjDeclList ';'
;
StatementList:
Statement
| Statement StatementList
;
Expression:
Disjunction
| Disjunction '->' Expression ':' Expression
;
Disjunction:
Conjunction
| Disjunction '\/' Conjunction
;
Conjunction:
Equation
| Conjunction '/\' Equation
;
Equation:
Relation
| Equation '=' Relation
| Equation '\=' Relation
;
Relation:
BitOperation
| Relation '<' BitOperation
| Relation '>' BitOperation
| Relation '<=' BitOperation
| Relation '>=' BitOperation
| Relation '.<' BitOperation
| Relation '.>' BitOperation
| Relation '.<=' BitOperation
| Relation '.>=' BitOperation
;
BitOperation:
Sum
| BitOperation '&' Sum
| BitOperation '|' Sum
| BitOperation '^' Sum
| BitOperation '<<' Sum
| BitOperation '>>' Sum
;
Sum:
Term
| Sum '+' Term
| Sum '-' Term
;
Term:
Factor
| Term '*' Factor
| Term '/' Factor
| Term '.*' Factor
| Term './' Factor
| Term 'MOD' Factor
;
Factor:
Number
| String
| Table
| 'PACKED' PackedTable
| Symbol
| Symbol Subscripts
| Symbol '.' Symbol
| ProcedureCall
| 'CALL' ProcedureCall
| Symbol '.' ProcedureCall
| 'SEND' '(' Symbol ',' Symbol ',' ProcedureCall ')'
| '@' Symbol
| '-' Factor
| '\' Factor
| '~' Factor
| '(' Expression ')'
;
Subscripts:
'[' Expression ']'
| '::' Factor
| '[' Expression ']' Subscripts
;
Table:
'[' MemberList ']'
;
MemberList:
TableMember
| TableMember ',' MemberList
;
TableMember:
ConstValue
| String
| Table
| 'PACKED' PackedTable
| '@' Symbol
| '(' Expression ')'
;
PackedTable:
'[' PackedTableMembers ']'
;
PackedTableMembers:
PackedTableMember
| PackedTableMember ',' PackedTableMembers
;
PackedTableMember:
Symbol
| Number
;
ProcedureCall:
Symbol '(' ')'
| Symbol '(' ExprList ')'
;
ExprList:
Expression
| Expression ',' ExprList
;
ConstValue:
SimpleConst
| ConstValue '*' SimpleConst
| ConstValue '+' SimpleConst
| ConstValue '-' SimpleConst
| ConstValue '|' SimpleConst
;
SimpleConst:
Symbol
| Number
| '-' SimpleConst
| '~' SimpleConst
;
Number:
DecimalNumber
| '%' & DecimalNumber
| '0X' & HexNumber
| '0B' & BinaryNumber
| '%' & '0X' & HexNumber
| '%' & '0B' & BinaryNumber
| '''' & AnyChar & ''''
;
BinaryNumber:
BinaryDigit
| BinaryDigit & BinaryNumber
;
DecimalNumber:
DecimalDigit
| DecimalDigit & DecimalNumber
;
HexNumber:
HexDigit
| HexDigit & HexNumber
;
Symbol:
Letter
| Letter & SymbolChars
;
SymbolChars:
'_'
| Letter
| DecimalDigit
| Letter & SymbolChars
| DecimalDigit & SymbolChars
;
Letter:
'A'|'B'|...|'Y'|'Z'
;
HexDigit:
DecimalDigit
|'A'|'B'|'C'|'D'|'E'|'F'
;
DecimalDigit:
'0'|'1'|'2'|'3'|'4'|'5'|'6'|'7'|'8'|'9'
;
BinaryDigit:
'0'|'1'
;
String:
'"' & StringChars & '"'
;
StringChars:
AnyChar
| AnyChar & StringChars
;
AnyChar:
<character>
| '\' & <character>
;
6. Quick Reference
6.1 Language Overview
6.1.1 Declarations
Statement Description
------------------------------- ---------------------------
VAR name, ... ; Declare atomic variables
VAR name[cexpr], ... ; Declare vectors
VAR name::cexpr, ... ; Declare byte vectors
VAR name[structname], ...; Declare structured vectors
CONST name = cexpr, ... ; Declare constants
PUBLIC CONST ... Declare class constants
STRUCT sname = m1, ... mN ; Declare structure
PUBLIC STRUCT ... Declare class constants
CLASS cname(required, ...) Declare class
class-declarations
END
PUBLIC CLASS ... Declare public class
OBJECT name[cname], ... ; Declare instance
DECL pname(cexpr), ... ; Forward-declare procedures
pname(a1, ..., aN) stmt Declare procedure
PUBLIC pname(a1, ..., aN) stmt Declare method
ICLASS cname("object-name") ... Declare interface class
IDECL iname(args, cmap); Declare interface procedure
MODULE mname(required, ...); Declare module
6.1.2 Statements
Statement Description
------------------------------ ---------------------------
lvalue := expr; Assignment
IF (expr) stmt Conditional statement
IE (expr) stmt-T ELSE stmt-F IF with alternative
WHILE (expr) stmt Unbounded loop
FOR (var=start, limit, cexpr) Counting loop
stmt
FOR (var=start, limit) stmt Counting loop, step = 1
LEAVE; Leave innermost WHILE/FOR
LOOP; Restart innermost WHILE/FOR
RETURN expr; Exit procedure, return value
RETURN; Exit, return 0
HALT cexpr; Halt program, return status
HALT; Halt with 0
pname(a1, ..., aN); Procedure call
CALL ptr(a1, ..., aN); Indirect procedure call
oname.mname(a1, ..., aN) Send message
SEND(ptr, cname, mname(a1, ..., aN));
Send indirect message
DO decls ... stmts ... END Compound statement
; Empty statement
6.1.3 Operators
Operator Prec Assoc Description
----------- ---- ----- ----------------------------------
(expr) 0 - Grouping
p(a1, ...) 0 L Procedure call
v[expr] 0 L Array subscript
v::expr 0 R Byte subscript
@lvalue 1 - Address of lvalue
~X 2 - Bitwise complement
\X 2 - Logical complement
-X 2 - Negation
X * Y 3 L Product
X / Y 3 L Quotient (integer part)
X MOD Y 3 L Division remainder
X .* Y 3 L Product (unsigned)
X ./ Y 3 L Quotient (unsigned)
X + Y 4 L Sum
X - Y 4 L Difference
X & Y 5 L Bitwise product (AND)
X | Y 5 L Bitwise sum (OR)
X ^ Y 5 L Bitwise not-equal operation (XOR)
X << Y 5 L Bitwise left shift
X >> Y 5 L Bitwise right shift
X < Y 6 L Less than
X <= Y 6 L Less/equal
X > Y 6 L Greater than
X >= Y 6 L Greater/equal
X .< Y 6 L Less than (unsigned)
X .<= Y 6 L Less/equal (unsigned)
X .> Y 6 L Greater than (unsigned)
X .>= Y 6 L Greater/equal (unsigned)
X = Y 7 L Equal to
X \= Y 7 L Not equal to
X /\ Y 8 L Short circuit logical AND
X \/ Y 9 L Short circuit logical OR
X -> Y : Z 10 L Conditional expression
6.1.4 Meta Commands
Meta command Description
------------------ --------------------------------------
#CLASSPATH "path"; Alternative location for locating
class files.
#DEBUG; Emit debug information
6.2 Runtime Support Routines
6.2.1 T3X
Procedure Description
--------------------------- -----------------------------
T.BPW() Bytes per machine word
T.CLOSE(fd) Close file
T.CVALIST(n, bmap, in, out) Convert argument list
T.GETARG(n, buf, max) Copy command line argument
T.GETENV(name, buf, max) Copy environment variable
T.MEMCOMP(r1, r2, len) Compare memory regions
T.MEMCOPY(dest, src, len) Copy memory regions
T.MEMFILL(dest, char, len) Fill memory regions
T.MEMSCAN(src, char, lim) Search for bytes in memory
T.NEWLINE(buf) Retrieve newline sequence
T.OPEN(path, mode) Open file
T3X.OAPPND Append mode
T3X.ORDWR Read/write mode
T3X.OREAD Read-only mode
T3X.OWRITE Write-only mode
T.READ(fd, buf, len) Read file
T.REMOVE(path) Delete file
T.RENAME(old, new) Rename file
T.SEEK(fd, pos, org) Move file pointer
T3X.SEEK_BCK Origin: relative, go back
T3X.SEEK_END Origin: end, go back
T3X.SEEK_FWD Origin: relative, go forward
T3X.SEEK_SET Origin: beginning, go forward
T.WRITE(fd, buf, len) Write file
6.2.2 Char
Procedure Description
--------------- ------------------------------
CHR.INIT() Initialize CHAR class
CHAR.C_ALPHA property: alphabetic
CHAR.C_CNTRL property: control character
CHAR.C_DIGIT property: decimal digit
CHAR.C_SPACE property: white space
CHAR.C_UPPER property: upper case character
CHR.ALPHA(char) Alphabetic character test
CHR.ASCII(char) ASCII character test
CHR.CNTRL(char) Control character test
CHR.DIGIT(char) Numeric character test
CHR.LCASE(char) Convert to lower case
CHR.LOWER(char) Lower case character test
CHR.MAP() Return property map
CHR.SPACE(char) White space character test
CHR.UCASE(char) Convert to upper case
CHR.UPPER(char) Upper case character test
6.2.3 IOStream
Procedure Description
------------------------------ -------------------------------
IOS.CLOSE() Close stream
IOS.CREATE(fd, buf, len, mode) Create stream
IOS.EOF() EOF test
IOS.FLUSH() Write buffered data
IOS.MOVE(offset, origin) Move stream pointer
IOSTREAM.SEEK_BCK Current position, move back
IOSTREAM.SEEK_END End of file, move back
IOSTREAM.SEEK_FWD Current position, move forward
IOSTREAM.SEEK_SET Beginning of file, move forward
IOS.OPEN(path, buf, len, mode) Open file
IOSTREAM.FADDCR Add CR before LF on output
IOSTREAM.FKILLCR Remove CR from input
IOSTREAM.FRDWR Read/write mode
IOSTREAM.FREAD Read-only mode
IOSTREAM.FTRANS FADDCR and FKILLCR
IOSTREAM.FWRITE Write-only mode
IOS.RDCH() Read single character
IOS.READ(buf, len) Read data
IOS.RESET() Reset error flag
IOS.READS(buf, len) Read single line
IOS.WRCH(char) Write single character
IOS.WRITE(buf, len) Write data
IOS.WRITES(str) Write string
6.2.4 Memory
Procedure Description
----------------------------- ---------------
MEM.INIT(pool, size) Initialize pool
MEM.WALK(block, sizep, statp) Walk block list
MEM.ALLOC(size) Allocate block
MEM.FREE(block) Free block
6.2.5 String
Procedure Description
--------------------------- -------------------------
STR.COMP(s1, s2) Compare strings
STR.COPY(dest, src) Copy string
STR.FIND(str, pat) Find substring
STR.FORMAT(buf, tmpl, list) Format string
STR.LENGTH(str) Length of string
STRING.MAXLEN Maximum string length
STR.NUMTOSTR(buf, n, radix) Convert number to string
STR.PARSE(str, tmpl, list) Extract fields
STR.RSCAN(str, char) Find rightmost character
STR.SCAN(str, char) Find character
STR.STRTONUM(s, radix, lp) Convert string to number
STR.XLATE(str, old, new) Replace characters
6.2.6 Tcode
Procedure Description
------------------------ --------------------------------
TCODE.Iinstruction Tcode Instruction constants, see 6.3.2
6.2.7 Util
Procedure Description
-------------------------- --------------------------
UTIL.BUFLEN Maximum string length
U.PRINTF(tmpl, args) Format and write to SYSOUT
U.SWRITEF(ios, tmpl, args) Format and write to stream
U.WRITEF(fd, tmpl, args) Format and write to file
6.2.8 System
Procedure Description
---------------------------- ----------------------------------
SYS.INIT() Initialize system interface
SYS.FINI() Shut down system interface
SYS.CHDIR(path) Change current working directory
SYS.CLOSEDIR(dirfd) Close directory
SYS.DUP(fd) Duplicate file descriptor
SYS.DUP2(old, new) Duplicate FD to existing FD
SYS.FORK() Duplicate the calling process
SYS.KILL(pid, sig) Send signal to process
SYSTEM.SIGKILL Signal: kill process
SYSTEM.SIGTERM Signal: terminate process
SYSTEM.SIGTEST Signal: test process id
SYS.MKDIR(path) Create new directory
SYS.OPENDIR(path) Open directory
SYS.PIPE(fdvec) Create pipe
SYS.RDCHK(fd) Check FD for pending input
SYS.READDIR(dirfd, buf, max) Read directory entry
SYS.RMDIR(path) Remove directory
SYS.SPAWN(prog, args, mode) Spawn program
SYSTEM.SPAWN_NOWAIT Mode: create background process
SYSTEM.SPAWN_WAIT Mode: wait for process termination
SYS.STAT(path, sb) Retrieve file statistics
SYSTEM.STATBUF File statistics buffer (SB)
SYSTEM.ST_DEV SB: device ID
SYSTEM.ST_EXT SB: size of file / 64K
SYSTEM.ST_GID SB: group ID of owner
SYSTEM.ST_INO SB: inode number
SYSTEM.ST_MODE SB: permission flags
SYSTEM.ST_MTIME SB: modification time
SYSTEM.ST_MT_2 SB: 8-byte MTIME buffer
SYSTEM.ST_MT_3 SB: 8-byte MTIME buffer
SYSTEM.ST_MT_4 SB: 8-byte MTIME buffer
SYSTEM.ST_NLINK SB: number of links
SYSTEM.ST_RDEV SB: device type
SYSTEM.ST_SIZE SB: size mod 64K
SYSTEM.ST_UID SB: user ID of owner
SYS.TIME(tbuf) Get system time
SYS.WAIT(pid) Wait for subprocess termination
6.2.9 TTYCtl
Procedure Description
--------------------- -----------------------------------
TTY.INIT() Initialize TTY interface
TTY.FINI() Shut down TTY interface
TTY.CLEAR() Clear terminal screen
TTY.CLREOL() Clear to end of line
TTY.COLOR(color) Select color
TTYCTL.B_BLACK \
TTYCTL.B_BLUE |
TTYCTL.B_CYAN |
TTYCTL.B_GREEN | Background colors
TTYCTL.B_GREY |
TTYCTL.B_MAGENTA |
TTYCTL.B_RED |
TTYCTL.B_YELLOW /
TTYCTL.F_BLACK \
TTYCTL.F_BLUE |
TTYCTL.F_CYAN |
TTYCTL.F_GREEN | Foreground colors
TTYCTL.F_GREY |
TTYCTL.F_MAGENTA |
TTYCTL.F_RED |
TTYCTL.F_YELLOW /
TTYCTL.F_BRIGHT Foreground intensity flag
TTY.COLORS() Can the TTY do color?
TTY.COLUMNS() Number of columns on TTY screen
TTY.MODE(raw) Select raw or cooked mode
TTY.MOVE(x, y) Move cursor
TTY.LINES() Number of lines on TTY screen
TTY.QUERY() Check for pending keyboard input
TTY.READC() Read single character from keyboard
TTYCTL.K_BKSP Key code: Backspace
TTYCTL.K_CR Key code: Enter / CR / Return
TTYCTL.K_DEL Key code: Delete
TTYCTL.K_DOWN Key code: Down arrow
TTYCTL.K_END Key code: End
TTYCTL.K_ESC Key code: Escape
TTYCTL.K_F1 Key code: F1
TTYCTL.K_F2 Key code: F2
TTYCTL.K_F3 Key code: F3
TTYCTL.K_F4 Key code: F4
TTYCTL.K_F5 Key code: F5
TTYCTL.K_F6 Key code: F6
TTYCTL.K_F7 Key code: F7
TTYCTL.K_F8 Key code: F8
TTYCTL.K_F9 Key code: F9
TTYCTL.K_F10 Key code: F10
TTYCTL.K_HOME Key code: Home
TTYCTL.K_INS Key code: Insert
TTYCTL.K_KILL Key code: Kill, Erase line
TTYCTL.K_LEFT Key code: Left arrow
TTYCTL.K_NEXT Key code: Next, Page down
TTYCTL.K_PGDN Key code: Next, Page down
TTYCTL.K_PGUP Key code: Prev, Page up
TTYCTL.K_PREV Key code: Prev, Page up
TTYCTL.K_RIGHT Key code: Right arrow
TTYCTL.K_UP Key code: Up arrow
TTY.RSCROLL(top, bot) Scroll region down
TTY.SCROLL(top, bot) Scroll region up
TTY.WRITEC(char) Write single character to screen
TTY.WRITES(string) Write string to screen
6.2.10 XMem
Procedure Description
----------------------------- ------------------------------
XM.INIT() Initialize XMEM interface
XM.FINI() Shut down XMEM interface
XM.ALLOC(size) Allocate external memory block
XM.FREE(id) Release allocated block
XM.GET(id, index) Read single byte from block
XM.PUT(id, index, value) Write single byte from block
XM.READ(id, index, buf, len) Read region from block
XM.WRITE(id, index, buf, len) Write region to block
6.3 Miscellanea
6.3.1 Escape Sequences
Escape ASCII
Sequence Code Name Description
-------- ----- ---- --------------------------
\a \A 0x07 BEL Ring terminal bell
\b \B 0x08 BS Backspace
\e \E 0x1B ESC Introduce control sequence
\f \F 0x12 FF Form feed
\n \N 0x0A LF Line feed
\q \Q \" 0x22 - Literal quote character
\r \R 0x0D CR Carriage return
\t \T 0x09 HT Horizontal tabulator
\v \V 0x0B VT Vertical tabulator
\\ 0x5C - Literal backslash
6.3.2 The Tcode Instruction Set
0x 00/80 10/90 20/A0 30/B0 40/C0 50/D0
00 GLUE STACK* BSHR LDIV* NBRT* INCL**
01 HINT* CLEAN* EQU LDLAB* JUMP* PUB**S
02 CLAB* NEG NEQU NUM* UNEXT* EXT**S
03 DLAB* LNOT LESS SELF DNEXT* IPROC**S
04 DATA* BNOT GRTR DEREF HALT* IREF**S
05 CREF* MUL LTEQ DREFB CALL* CMAP**
06 DREF* DIV GTEQ NORM CALR GSYM**S
07 VEC* UMUL ULESS NORMB CALX* LSYM**S
08 STR*S UDIV UGRTR SAVG* SYS* ISYM**S
09 HDR MOD ULTEQ SAVL* ILIB*S
0A END ADD UGTEQ SAVI* ICALL*
0B MHDR SUB LDG* STORE ICALX*
0C ENDM BAND LDGV* STORB LINE*
0D POP BOR LDL* BRF* INIT**
0E DUP BXOR LDLV* BRT* INCG**
0F SWAP BSHL LDI* NBRF* INCI**
* instruction has an argument.
** instruction has two arguments.
S instruction has a string argument.
In any of these cases, add 0x80 to the opcode.
6.3.3 ASCII Table
hex 00 10 20 30 40 50 60 70
0 16 32 48 64 80 96 112 dec
00 NUL DLE 0 @ P ' p 00
01 SOH DC1 ! 1 A Q a q 01
02 STX DC2 " 2 B R b r 02
03 ETX DC3 # 3 C S c s 03
04 EOT DC4 $ 4 D T d t 04
05 ENQ NAK % 5 E U e u 05
06 ACK SYN & 6 F V f v 06
07 BEL ETB ' 7 G W g w 07
08 BS CAN ( 8 H X h x 08
09 HT EM ) 9 I Y i y 09
0A LF SUB * : J Z j z 10
0B VT ESC + ; K [ k { 11
0C FF FS , < L \ l | 12
0D CR GS - = M ] m } 13
0E SO RS . > N ^ n ~ 14
0F SI US / ? O _ o DEL 15
7. License
This manual is part of the T3X compiler package which is
distributed under the following terms.
T3X -- A Compiler for the Minimal Procedural Language T3X
Nils M Holm, 1996-2019
Redistribution and use in source and binary forms, with or
without modification, are permitted provided that the following
conditions are met:
(1) Redistributions of source code must retain the above
copyright notice, this list of conditions and the following
disclaimer.
(1) Redistributions in binary form must reproduce the above
copyright notice, this list of conditions and the following
disclaimer in the documentation and/or other materials
provided with the distribution.
THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS 'AS IS'
AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT
SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT,
INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF
THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
SUCH DAMAGE.