4 Relationship to ISO 7185

4.1 Pascaline as a series of extensions

The Pascaline standard accepts the entire language defined in the standard defined in ISO 7185 such that the set of features defined by Pascaline qualify as extensions under ISO 7185 3.2 “Extension”.

4.2 Additional reserved word-symbols

As allowed in ISO 7185 3.2 “extension”, the following additional spellings of identifiers are prohibited because of their use as word-symbols in the Pascaline standard:

forward module uses private external

view fixed process monitor share

class is xor overload override

reference joins static inherited self

virtual try except extends on

result operator start thread atom

property channel liaison out

These word-symbols are all new word-symbols defined by Pascaline. The fact that certain identifiers are prohibited in Pascal may cause ISO 7185 compliant programs to fail to compile for this reason. To use a Pascaline implementation for such programs, one of two methods are used:

1. The ISO 7185 compliance switch is enabled (see ISO 7185 5.1 “Processors” note 2).

2. The identifiers in the program that overlap the above list are changed.

4.3 Character escapes

Annex E “Character Escapes”, if implemented by the target system, can affect the behavior of character strings in an ISO 7185 implementation. Although ISO 7185 does not specify the character set or contents of strings in a complying program, it is reasonable for a given program to assume that all visible characters are treated equally.

If the program contains the character ‘\’, the escape sequence introduction character, this will be treated differently than other characters. To use a Pascaline implementation that implements Annex E for such programs, one of three methods are used:

1. The ISO 7185 compliance switch is enabled (see ISO 7185 5.1 “Processors” note 2).

2. A switch that enables or disables character escapes is set to disable.

3. All instances of ‘\’ within character strings are changed to ‘\\’.

4.4 Compliance with ISO 7185

ISO 7185 5.2 “Processors” allows an implementation to be considered compliant if it is accompanied by a list of the requirements for which it does not comply. Pascaline specifically does not allow such exceptions. A processor is Pascaline compliant only if it has the following characteristics:

1. The complete requirements of ISO 7185 are followed, without exception.

2. The complete requirements of Pascaline, in this document, are followed without exception.

That is, the “list of requirements not complied with” from ISO 7185 5.2 “processors” is neither allowed as a starting point for Pascaline, nor carried forward into the language Pascaline.

4.5 ISO 7185 level 0 only

Pascaline is compliant with “level 0” Pascal only, as allowed for by the ISO 7185 standard (ISO 7185 5 “Compliance”). Conformant arrays are not specified in Pascaline, nor are they specified as an option under Pascaline. However, such conformant arrays could well be implemented as an extension to Pascaline.

4.6 Extensions to Pascaline

Extensions to Pascaline are changes to language features in this standard that do not cause a program complying with this standard to fail to compile, interpret, run or otherwise function with the exception that one or more additional spellings of symbols may be reserved to the processor. That is, additional reserved word-symbols may be defined.

An example of an extension that does not comply with this standard is a modal change such as redefining the functionality of the “mod” operator. This would cause otherwise complying programs to fail to function.

4.7 Compliance statement

Complying processors with Pascaline shall issue the statement:

<This processor> complies with the requirements of Pascaline version X.X [and the annexes A, B, C…]

Where:

<This processor> Is the name of the complying processor

X.X Is the version number of the Pascaline specification complied with.

[and the annexes A, B, C..] Is an optional list of the annexes also compiled with]

There is no minimum requirement for the number of annexes complied with. The processor may comply with any number from zero to all of them. In some cases, it may be inappropriate for a particular implementation to have compliance with a particular annex. For example, the graphical display annex K in conjunction with a system that has no graphical display. Just as compliance with the basic Pascaline standard implies that a program will or will not run, the presence or absence of an annex a program relies on may cause it to compile and run, or fail to do so.

4.8 Compliance switch

If the processor complying with this standard contains extensions (defined in 4.6 “Extensions to Pascaline”), it shall contain a switch for compliance with Pascaline with the following characteristics:

On:

1. Causes the Pascaline compliance statement to be issued (4.7 “Compliance statement”).

2. Causes any restriction on spelling of identifiers to be removed (no additional reserved words beyond those of Pascaline).

3. Causes any extension to the Pascaline standard to be removed.

Off:

1. Causes the Pascaline compliance statement to be removed (4.7 “Compliance statement”).

2. Enables any extensions to the Pascaline standard.

3. Does not cause any program complying with the Pascaline standard to fail to compile, interpret, run or otherwise function, with the exception of restriction of spelling of identifiers (additional reserved words).

Note that if the processor contains extensions that do not comply with the Pascaline definition of extensions (4.6 “Extensions to Pascaline”), the processor will, by definition, not comply with the “Off” switch requirement above.

4.9 Similarities with the ISO 7185 standard document

In general much of the form and manner of the original ISO 7185 standard document was followed in this document. However, in one case there is a distinct difference. The original ISO 7185 document does not distinguish between errors at compile time and at runtime, which sometimes overlap. In this standard, all runtime errors are represented as exceptions, and a list of exceptions appears as an annex.

The use of “equivalent code” occurs many times in this document. That is, a built-in or standard operation or statement is explained in terms of other statements in ISO 7185 Pascal or Pascaline. This creates a concrete and exact explanation of standard actions.

5 Relationship to the Pascal-P6 series compiler

In 1972 A project was begun to create a portable compiler that accepted and processed a subset of the original Jensen and Wirth Pascal standard. This compiler went through several versions, and ended as the Pascal-P4 compiler. In its final iteration, it still a subset compiler, with several features of J&W left out. This compiler was extensively documented by both the Zurich originators and in “Pascal Implementation: the P4 Compiler” [S. Pemberton and M.C. Daniels].

In 1982, the ISO 7185 standard was issued, and this was accompanied by the ISO 7185 compiler in A model Implementation of Standard Pascal [Welsh], and by a BSI (British Standards Institute) test suite designed to fully test existing compilers.

In 2009 a project was begun to improve the original Zurich Pascal-P compiler to accept and process the ISO 7185 Pascal standard. This resulted in Pascal-P5, which replaces the model implementation. It was accompanied by an extensive document and by a new test suite designed to replace the BSI test suite, which is no longer available.

In 2011 a project was begun to implement the Pascaline language as an increment to the Pascal-P5 compiler, and create a new test suite to verify the result, and also a new working document for the compiler.

The Pascal-P6 implementation provides a freely available, public domain example implementation of Pascaline whose test suite is also freely available. This can be used as an example for a new Pascaline implementation, as a starting point for such an implementation, and/or as a source of tests for such an implementation, or simply as a reasonable implementation in its own right.

Pascal-P6 and its associated tests provide the proving system for the Pascaline language. It is expected that when the Pascal-P6 implementation is complete and tested, that this standard will reach a 1.0 version.

6 Language extensions for Pascaline

6.1 Word-symbols

Notes:

1. The directives "external" and "forward" in ISO 7185 Pascal are promoted to word-symbols in Pascaline.

2. The function of the directive “external” in Pascaline is not defined, just as it was not defined in ISO 7185 Pascal.

6.2 Special symbols

special-symbol = '+' | '-' | '*' | '/' | '=' | '<' | '>' | '[' | ']' | '.' | ',' | ':' | ';' | '^' | '(' | ')' | '<>' | '<=' | '>=' | ':=' | '..' | '(.' | '.)' | '@' | word-symbol .

Note that the alternative symbols ‘(.’, ‘.)’, and ‘@’ were optional in ISO 7185 Pascal, and remain optional in Pascaline.

6.3 Comments

The character ‘!’ introduces a “Line Comment”. All characters up to and including the next end of line are ignored. This allows a comment form that is short, and automatically terminated by the end of line:

! A simple program

program p;

begin

writeln(‘Hello, world’) ! print to console

end.

Notes:

1. The ‘!’ character must appear between Pascaline symbols and not within any symbol.

2. Any other comment characters within a line comment are ignored, ‘{‘, ‘}’, ‘(*’, or ‘*)’.

6.4 Identifiers

Identifiers in Pascaline are identical to ISO 7185 Pascal, with the addition of the break character '_'. An identifier can start with any of 'a'..'z' or '_', and continue with 'a'..'z', '_' and '0'..'9'. As in ISO 7185 Pascal, identifiers are not case sensitive.

identifier = letter | '_' { letter | digit | '_' }.

Example identifiers:

one_more_time

_last_time

6.5 Labels

Labels, used for goto purposes, can use the same format as identifiers under Pascaline. The original "apparent value" numeric labels of ISO 7185 Pascal are accepted as well.

label = digit-sequence | identifier .

Example label:

program p;

label exit;

{ declarations }

begin

goto exit

{ statements to be skipped }

exit:

end.

6.6 Numeric constants

unsigned-integer = decimal-integer | hex-integer | octal-integer | binary-integer .

decimal-integer = digit-sequence .

hex-integer = '$' hex-digit-sequence .

octal-integer = '&' octal-digit-sequence .

binary-integer = '%' binary-digit-sequence .

digit-sequence = digit { digit } .

hex-digit-sequence = hex-digit { hex-digit }

octal-digit-sequence = octal-digit { octal-digit }

binary-digit-sequence = octal-digit { binary-digit }

digit = '0' | '1' | '2' | '3' | '4' | '5' | '6' | '7' | '8' | '9' '_'.

hex-digit = '0' | '1' | '2' | '3' | '4' | '5' | '6' | '7' | '8' | '9' | 'a' | 'b' | 'c' | 'd' | 'e' | 'f' | '_' .

octal-digit = '0' | '1' | '2' | '3' | '4' | '5' | '6' | '7' | '_' .

binary-digit = '0' | '1' | '_' .

Both standard integer and real specifications are available. In addition, three "radix specifier" formats are available:

$1234 - Specifies hexadecimal format (base 16)

&1234 - Specifies octal format (base 8)

%1010 - Specifies binary format (base 2)

Each alternative format is specified with a "radix introduction" character. These formats can be specified anywhere the Pascaline construct unsigned-constant is specified.

Pascaline accepts a "break character" within numeric constants. The "_" character can be used anywhere within a number:

123_456_789

It cannot be used as the first character of a number, which would make it an identifier.

The meaning of the number is considered without the break characters. The number:

1_2_3

is equivalent to:

123

Break characters can be used in any radix. They are useful for grouping digits so that the result is more readable:

12_334_222 { marked in thousands }

$5566_1212 { marked in 16 bit sections }

6.7 Constant expressions

constant = [ sign ] constant-term { adding-operator constant-term } .

constant-term = constant-factor { multiplying-operator constant-factor } .

constant-factor = '(' constant ')' | 'not' constant-factor | character-string | constant-identifier | unsigned-integer .

multiplying-operator = '*' | '/' | 'div' | 'mod' | 'and' .

adding-operator = '+' | '-' | 'or' | 'xor' .

Whenever a constant appears in Pascal, Pascaline is able to accept a constant expression. Constant expression expressions have a syntax that is similar, but not identical to standard expressions in Pascal. Constant expressions can only operate on other constants or constant expression, and cannot include variables.

Note:

1. The operator xor is defined in 6.8 “Boolean integer operations”.

6.8 Boolean integer operations

expression = simple-expression [ relational-operator simple-expression ] .

simple-expression = [ sign ] term { adding-operator term } .

term = factor { multiplying-operator factor } .

multiplying-operator = '*' | '/' | 'div' | 'mod' | 'and' .

adding-operator = '+' | '-' | 'or' | 'xor' .

Besides the use of and, or and not on Booleans in Pascal, Pascaline allows the use of and, or and not with integer operands. The result is the bitwise 'and', ‘or’ or ‘not’of the bits in the integer.

Pascaline defines a new operator, xor, which has the same precedence as and. It gives the bitwise exclusive or of integers. It can also be used on boolean types, but in that case is equivalent to the operation a <> b.

Boolean operations on negative values are not defined, and may be treated as errors, caught at either compile time or run time, by the implementation.

The boolean integer or operation is equivalent to:

function bor(a, b: integer): integer;

var i, r, p: integer;

begin

if (a < 0) or (b < 0) throw(NegativeInteger);

r := 0; { clear result }

p := 1; { set 1st power }

i := maxint; { set maximium positive number }

while i <> 0 do begin

if odd(a) or odd(b) then r := r+p; { add in power }

a := a div 2; { set next bits of operands }

b := b div 2;

i := i div 2; { count bits }

if i > 0 then p := p*2 { find next power }

end;

bor := r { return result }

end;

The boolean integer and operation is equivalent to:

function band(a, b: integer): integer;

var i, r, p: integer;

begin

if (a < 0) or (b < 0) throw(NegativeInteger);

r := 0; { clear result }

p := 1; { set 1st power }

i := maxint; { set maximum positive number }

while i <> 0 do begin

if odd(a) and odd(b) then r := r+p; { add in power }

a := a div 2; { set next bits of operands }

b := b div 2;

i := i div 2; { count bits }

if i > 0 then p := p*2 { find next power }

end;

band := r { return result }

end;

The boolean integer xor operation is equivalent to:

function bxor(a, b: integer): integer;

var i, r, p: integer;

begin

if (a < 0) or (b < 0) throw(NegativeInteger);

r := 0; { clear result }

p := 1; { set 1st power }

i := maxint; { set maximum positive number }

while i <> 0 do begin

if odd(a) <> odd(b) then r := r+p; { add in power }

a := a div 2; { set next bits of operands }

b := b div 2;

i := i div 2; { count bits }

if i > 0 then p := p*2 { find next power }

end;

bxor := r { return result }

end;

6.9 View and out parameters

formal-parameter-list = '(' formal-parameter-section { ';' formal-parameter-section } ')' .

value-parameter-specification = identifier-list ':' type-identifier .

variable-parameter-specification = 'var' identifier-list ':' type-identifier .

view-parameter-specification = 'view' identifier-list ':' type-identifier .

out-parameter-specification = 'out' identifier-list ':' type-identifier .

procedural-parameter-specification = procedure-heading .

functional-parameter-specification = function-heading .

A parameter to a procedure or function has a type and a "mode", that indicates the method of its passage.

Besides the Pascal parameter modes of var and value, Pascaline adds a mode introduced by view:

program p;

type a = packed array [1..100] of char;

procedure x(view b: a);

begin

{ use, but don’t change, b }

end;

begin

end.

view parameters have the same characteristics as value parameters, and can be treated identically to value parameters. A view parameter cannot be modified or "threatened" in the procedure or function it belongs to. The meaning of "threatened" is the same as for for index variables of ISO 7185 6.8.3.9, and means that the parameter cannot be assigned, used as an index in a for loop, or passed to another routine as a var parameter.

view parameters enable the underlying implementation to create more efficient code in many cases. If the above example was:

program p;

type a = packed array [1..100] of char;

procedure x(b: a);

begin

{ code to use array b }

end;

begin

end.

The code would have to copy the actual parameter to b, which can be very inefficient for large arrays. The use of the view parameter allows the system to treat the parameter as a var parameter, but allow any expression to be passed as a value parameter would.

An out parameter is functionally identical to a var parameter except that it indicates that the parameter will be used only to return results to the caller, and that the contents of the variable passed will not be initialized on entry. This allows the processor to check for accesses to the variable before it has been assigned.

program p;

type a = packed array [1..100] of char;

procedure x(out b: a);

begin

{ set new contents for the array }

for i := 1 to 100 do b[i] := i+10

end;

begin

end.

6.10 Extended case statements

case-statement = 'case' case-index 'of' case-list-element { ';' case-list-element } [ ';' ] 'end' .

case-list-element = case-list-statement | case-list-default .

case-list-statement = case-constant-list ':' statement .

case-list-default = 'else' statement .

case-constant-list = case-constant-range { ',' case-constant-range } .

case-constant-range = case-constant [ '..' case-constant ] .

case-index = expression .

A case statement can feature an else clause at the end of all case selects for a given case statement:

program p(output);

var y: integer;

begin

{ code that sets y }

case y of

1: write('one');

2: write('two')

else write('value unknown')

end

end.

The statement indicated as else will be executed if the case select value does not match any of the values in the case list.

A case select value can appear as a range of values:

program x;

var y: integer;

begin

case x of

1: write('one');

2: write('two');

3..5: write('three to five')

end

end.

Is equivalent to:

program p;

var y: integer;

begin

{ statements that set y }

case y of

1: write('one');

2: write('two');

3, 4, 5: write('three to five')

end

end.

6.11 Variant record case ranges

The case constants on a variant record specification can appear as ranges:

record-type = 'record' field-list 'end' .

field-list = [ ( fixed-part [ ';' variant-part ] | variant-part ) [ ';' ] ] .

variant-part = 'case' variant-selector 'of' variant { ';' variant } .

variant = case-constant-list ':' '(' field-list ')' .

case-constant-list = case-constant-range { ',' case-constant-range } .

case-constant-range = case-constant [ '..' case-constant ] .

program p;

type sr = 1..5;

var r: record

i: integer;

case s: sr of

1: (q: integer; b: boolean);

2: (z: real; t: array 10 of integer);

3..5: (o: set of char; j: integer)

end;

begin { program p }

end.

Is equivalent to:

program p;

type sr = 1..5;

var r: record

i: integer;

case s: sr of

1: (q: integer; b: boolean);

2: (z: real; t: array 10 of integer);

3, 4, 5: (o: set of char; j: integer)

end;

begin { program p }

end.

Notes:

1. For each case range, the starting constant must be less than or equal to the ending constant.

2. The ISO 7185 Pascal requirement that all values of the tagfield be present remains.

6.12 Array type shorthand

array-type = 'array' [ dimension-specifier ] 'of' component-type .

dimension-specifier = index-specifier | range-specifier .

index-specifier = '[' index-type { ',' index-type } ']' .

range-specifier = unsigned-integer { ',' unsigned-integer } .

Pascaline features a special declaration format for the most common case of integer indexed arrays:

type x = packed array 10 of char;

type y = array 20,10 of integer;

are equivalent to:

type x = packed array [1..10] of char;

type y = array [1..20,1..10] of integer;

Denoting an array index by size, instead of by an index specification, uses a different syntax, without the '[' and ']' characters, to make it clear what kind of array specification is being used.

6.13 Container arrays

array-type = 'array' [ dimension-specifier ] 'of' component-type .

The specification of only fixed arrays in ISO 7185 Pascal caused several practical issues with the language. Pascaline has the concept of "container arrays", which are array types specified without index specifications.

type a = array of integer;

Container arrays are a "template type" which cannot be used to directly specify a static variable without qualification. For example:

{ incorrect example }

program p;

type a = array of integer;

var b: a;

begin

end.

Would not be correct because type a does not contain enough information, namely the size of the array, to define the static variable b.

The power of container arrays is their ability to be bound to a fully defined static array at a time later than when the program is compiled. This can happen in three different ways:

1. When a parameter is accepted for a procedure or function.

2. As a result of the creation of an anonymous array in dynamic storage.

3. By use of a parameterized variable declaration (see 6.14 “Parameterized variables”).

It is important to understand that Pascaline does not specify what are called "dynamic arrays", which is the ability to resize an array at runtime. Pascaline simply provides the means to create fixed arrays of any size at runtime and bind to them, or to create generate purpose procedures or functions that can bind to any size array at runtime. This distinction may seem to be unnecessary, but in practice it dramatically simplifies implementation of the concept.

Container types can have multiple index levels:

type a = array of array of array of boolean;

Container array types are compatible with other container and fixed array types that:

1. Have the same base types.

2. Have the same packed/unpacked status.

3. Have the same number of index levels.

Thus, the following types are compatible:

type a = packed array [1..100] of char;

and

type b = packed array of char;

type a = array [1..10, 1..100] of integer;

and

type b = array of array of integer;

A container array can be used for a procedure or function parameter:

type string = packed array of char;

procedure x(var s: string);

And can use any mode.

As with ISO 7185 Pascal array parameters, if the parameter is passed by value, there can be considerable expense associated with copying the array to private location for the procedure or function.

When container arrays are used as parameters, they are simply serving as holders for an existing array. In the case of variable parameters, the array was created elsewhere in the code and the parameter simply points to it. In the case of value parameters, the array is created anew in a private location, and the existing array copied to it. In both cases, the information needed to complete the template for the array exists elsewhere.

Another way to allocate a container array is to use new to allocate it dynamically:

program p;

type ap = ^a;

a = packed array of char;

var b: ap;

begin

new(b, 10);

b := 'hi there ';

end.

The call of new must specify the size of all indices, in the same order as the indices appear in the declaration.

Container arrays have the interesting property that they are free of index typing. Container arrays are considered to be compatible with other arrays (standard or container) that have the same number of base elements.

This means that the following assignments are possible:

program p;

type a = packed array [20..120] of char;

b = array of char;

c = ^b;

var q: a;

x: c;

begin

new(x, 100);

x^ := q;

q := x^;

end.

It does not matter what the first or last element of the array is. When elements are copied from or to a compatible container, or when a container is used to reference a standard array, the elements are matched up from the first to the last without regard to the exact number of the index used. In the last example, q[20] and x[1] refer to the same element. The equivalent of the above copy operation is:

program p;

type a = packed array [20..120] of char;

b = array of char;

c = ^b;

var q: a;

x: c;

begin

new(x, 100);

{ x := q; }

for i := 1 to 100 do x^[i] := q[i+20-1];

{ q := x; }

for i := 1 to 100 do q[i+20-1] := x^[i]

end.

When a container array is indexed, the method of specifying its indices is always the integers 1 to n, where n is last element of the array. The last element of a container array, which happens to also be its length, can be found by the predefined function:

max(a, l);

Where a is the container array, and l is the indexing level. For example:

program p;

type a = array of array of array of integer;

b = ^a;

var c: b;

i: integer;

begin

new(c, 10, 20, 30);

i := max(c, 2)

end.

Finds the second level index length of b, which is 20.

Specifying a level for max is optional. The function call:

max(a);

is equivalent to:

max(a, 1);

Container arrays make it possible to have a type that represents a string, or packed array of characters with a starting index of 1:

type string = packed array of char;

This is a standard system definition in Pascaline. In addition, a pointer to a string is also standard:

type pstring = ^string;

6.14 Parameterized Variables

Although containers cannot be directly used as the type of a variable, or part of a variable, they can be used for the type of a parameterized variable declaration:

variable-declaration = identifier-list [ ‘(‘ expression { ‘,’ expression ‘)’ ] ':' type-denoter .

variable-declaration-part = [ 'var' variable-declaration ';' { variable-declaration ';' } ] .

program p;

type z = array of integer;

procedure q(v: z);

var a(max(v)): array of integer;

i: integer;

begin

for i := 1 to max(v) do a[i] := v[i]+1

end;

begin

end.

Variables which are declared using containers use a parameterized form that takes one or more expressions on the left side, which are used to fulfill the indices that appear in the type of the variable on the right side.

The parameter expressions must be integer.

Each expression will be used to match an index in the type. If the type is formed from a nested declaration, the indices are processed from the outermost declaration to innermost. If multiple dimension arrays exist, the indices appear from major to minor.

Every index in the type must be matched. If there are more or fewer index expressions that there are indices in the type, it is an error.

The expression used for an index parameter is not limited. Variables, parameters and functions can be used, but all of the elements used must be fully defined.

The evaluation of the index parameters is performed before the code in the block for which the variable is declared is executed. The indices do not vary during the execution of the declaring block. This means the following variant of the above code would function correctly:

program p;

type z = array of integer;

procedure q(l: integer; v: z);

var a(l): array of integer;

i: integer;

begin

l := 5;

for i := 1 to l do a[i] := v[i]+1

end;

var r(10): z;

i: integer;

begin

for i := 1 to 10 do r[i] := i+10;

q(10, r)

end.

If a parameterized variable statement contains only constant parameters, the compiler may treat the variable as equivalent to a fixed type with the same parameters. This allows a container type to be used as a “template” type to create static variables:

program p;

type z = array of integer;

var a(10): z; ! an array of 10 integers

b(20): z; ! an array of 20 integers

begin

end.

If the parameterized variable expression contains local variables, it is an error, since such variables are, by definition, undefined at the start of the block. Note that this does not apply to parameters, which are initialized externally to the procedure or function that contains the parameterized variable statement.

Parameterized variables allow the specification of fixed types from abstract types. This allows both the use of types for general classes of types, as well as moving the sizes of arrays out of type descriptions.

6.15 Extended write/writeln statements

Pascaline extends the meaning of field width parameters in ISO 7185 6.9.3.1 to include negative or zero field widths. The appearance of a negative value as a field width has the same effect as the absolute value of the field width, except that the resulting character translation is set left justified within its field. i.e., the spaces that are specified to pad each output format to the field width are output after the contents of the field, not before.

program p(output);

var i: integer;

begin

write(i:-10)

end.

Would output the integer i in 10 spaces at least, with any padding to the right side of the number.

The behavior of a fielded write for integers is equivalent to:

program p(output);

procedure WriteInteger(var f: text; i: integer; fl: integer);

var c: integer;

p: integer;

begin

if fl < 0 then begin ! left justified

! determine the number of required characters

c := 0;

if i < 0 then c := c+1; ! count sign

p = maxint; ! set maximum power

! count digits

while p > 0 do

begin if abs(i) >= p then c := c+1; p := p div 10 end;

write(f, i:1); ! output minimum format

if f > c then write(f, ‘ ‘:fl-c) ! complete justification

end else write(f, i:fl); ! output regular format

end;

begin

WriteInteger(output, 20, -10)

end.

For real values in the floating point format, there is no change for left justified formatting. This occurs because there are no blanks used to justify such a number. The precision of the fraction is simply extended to fill the field. Thus:

program p(output);

var r: real;

begin

write(r:-20)

end.

Is equivalent to:

program p(output);

var r: real;

begin

write(r:20)

end.

There is no difference between the left justified format for a floating point representation, but there is also no error.

For a real value output in fixed point format:

program p(output);

var r: real;

begin

write(r:-20:5)

end.

The equivalent code is:

program p(output);

procedure WriteRealFixed(var f: text; r: real; fl: integer;

fr: integer);

var c: integer;

p: real;

begin

if fl < 0 then begin ! left justified

! determine the number of required characters

c := 2; ! minimum field includes ‘0.’

if r < 0 then c := c+1; ! count sign

p = 10.0; ! set minimum for extra digits

! calculate digits beyond ‘0.’

while p <= abs(r) do begin c := c+1; p := p*10 end;

write(f, i:c:fr); ! output minimum format

if f > c then write(f, ‘ ‘:f-(c+fr)) ! complete justification

end else write(f, i:f); ! output regular format

end;

begin

WriteRealFixed(output, r, -20, 5)

end.

A zero field parameter has practical use only with string type and character type parameters. This is because integer and real types have minimum output format sizes. An example of use with strings is:

program p(output);

var i: integer;

begin

for i := 11 downto 0 do writeln(‘hello there’: i)

end.

Hello there

Hello ther

Hello the

Hello th

Hello t

Hello

Hell

Hel

(blank)

In the code:

program p(output);

procedure WriteSpaces(s: integer);

begin

write(‘ ‘: s)

end;

begin

WriteSpaces(10)

end.

Serves to output a given number of spaces, from 0 to N.

6.16 Extended read/readln statements

read/readln statements are symmetrical with their write/writeln counterparts for text files. Variable parameters can accept field specifications. String variables can be read. Constant string parameters can appear, to be matched to input.

The net effect of symmetrical read/readln operations is to allow files generated by write/writeln statements to also be read by read/readln statements.

A standard ISO 7185 Pascal string variable or Pascaline string variable can appear as a read/readln parameter:

program p(input);

var s: packed array 10 of char;

begin

read(s);

end.

The equivalent code is:

program p(input);

var s: packed array 10 of char;

procedure ReadString(var f: text; var s: string);

var i: integer;

begin

for i := 1 to max(s) do read(f, s[i]);

end;

begin

ReadString(input, s)

end.

If the end of line is encountered, it is read as a space and the read operation continues. If end of file is encountered, it is an error.

For fielded read parameters, an integer value field, which can be any expression, appears after the read parameter:

program p;

var f: text;

i: integer;

begin

read(f, i:10);

end.

The fielded read requires the input integer to be complete within the specified number of characters, disregarding any leading or trailing blanks.

The equivalent code to read an integer is:

program p;

var f: text;

i: integer;

procedure ReadInteger(var f: text; var i: integer; fl: integer);

var s: integer;

function NextChar: char;

begin

{ if past the field, terminate with space }

if fl = 0 then NextChar := ‘ ‘

else NextChar := f^

end;

procedure GetChar;

begin

get(f);

fl := fl-1

end;

begin

s := +1; { set sign }

{ skip leading spaces }

while (NextChar = ‘ ‘) and not eoln(f) do GetChar;

if not (NextChar in [‘+’, ‘-‘, ‘0’..’9’]) then

throw(InvalidIntegerFormat);

if NextChar = ‘+’ then GetChar

else if NextChar = ‘-‘ then begin GetChar(f); s := -1 end;

if not (NextChar in [‘0’..’9’]) then throw(InvalidIntegerFormat);

i := 0; { clear initial value }

while (NextChar in [‘0’..’9’]) do begin { parse digit }

i := i*10+ord(NextChar)-ord(‘0’); { add in new digit }

GetChar

end;

{ make sure the rest of the field is spaces }

while fl > 0 do begin

if NextChar <> ‘ ‘ then throw(InvalidIntegerFormat);

GetChar

end

end;

begin

ReadInteger(f, i, 10)

end.

Reading a character with a field is similar

program p;

var f: text;

c: char;

begin

read(f, c:10);

end.

The equivalent code is:

program p;

var f: text;

c: char;

procedure ReadChar(var f: text; var c: char; fl: integer);

begin

read(f, c); ! get the character

! make sure the rest of the field is spaces

while fl > 0 do begin

if f^ <> ‘ ‘ then throw(FieldNotBlank);

get(f);

fl := fl-1

end

end;

begin

ReadChar(f, c, 10)

end.

When reading a string, the default field is equivalent to the number of characters in the string. If a field is present, and is greater than the number of characters in the string, then the string is expected to appear with a number of leading blanks. To specify a number of trailing blanks, a negative field is specified.

In both cases, if the field is smaller than the number of characters in the string, only that number of characters will be read. There is no initialization implied for characters in the string past the number of characters in the field.

If the field is 0, the space padded string mode is entered. In this mode, all characters that are present in the input before any end of line or end of file are read into the string, then the remaining characters in the string are set to blanks. In this mode it is an error if there are more characters present before the end of line or end of file than there are available in the string.

program p;

var f: text;

s: packed array [1..20] of char;

begin

read(f, s:10);

end.

The equivalent code is:

program p;

var f: text;

s: packed array [1..20] of char;

procedure ReadString(var f: text; var s: string; fl: integer);

var l: integer; { net length of string }

i: integer;

procedure SkipSpaces(c: integer);

begin

while c > 0 do begin

if f^ <> ‘ ‘ then throw(FieldNotBlank);

get(f);

c := c-1

end

end;

begin

if fl = 0 then begin { padded mode }

i := 1; { set start of string }

while not eoln(f) and not eof(f) do begin

if i > max(s) do throw(InputExceedsString);

read(s[i]);

end;

{ clear the rest of the string to blanks }

while i < max(s) do s[i] := ‘ ‘

end else begin

l := max(s); { find net length of string }

if abs(fl) < l then l := fl;

{ skip leading spaces }

if -fl > max(s) then SkipSpaces(max(s)+fl);

for i := 1 to l do read(f, s[i]); { get string characters }

{ skip trailing spaces }

if fl > max(s) then SkipSpaces(max(s)-fl)

end

end;

begin

ReadString(f, s, 10)

end.

For real variables, the results are similar to that of integer:

program p;

var f: text;

r: real;

begin

read(f, r:10);

end.

The equivalent code is:

program p;

var f: text;

r: real;

procedure ReadReal(var f: text; var r: real; fl: integer);

var i: integer;

{ find power of ten efficiently }

function pwrten(e: integer): real;

var t: real; { accumulator }

p: real; { current power }

begin

p := 1.0e+1; { set 1st power }

t := 1.0; { initalize result }

repeat

if odd(e) then t := t*p; { if bit set, add this power }

e := e div 2; { index next bit }

p := sqr(p) { find next power }

until e = 0;

pwrten := t

end;

function NextChar: char;

begin

{ if past the field, terminate with space }

if fl = 0 then NextChar := ‘ ‘

else NextChar := f^

end;

procedure GetChar;

begin

get(f);

fl := fl-1

end;

procedure ReadInteger(var i: integer);

var s: integer;

begin

s := +1; { set sign }

if not (NextChar in [‘+’, ‘-‘, ‘0’..’9’]) then

throw(InvalidRealFormat);

if NextChar = ‘+’ then GetChar

else if NextChar = ‘-‘ then begin GetChar(f); s := -1 end;

if not (NextChar in [‘0’..’9’]) then throw(InvalidRealFormat);

i := 0; { clear initial value }

while (NextChar in [‘0’..’9’]) do begin { parse digit }

i := i*10+ord(NextChar)-ord(‘0’); { add in new digit }

GetChar

end

end;

begin { ReadReal }

{ skip leading spaces }

while (NextChar = ‘ ‘) and (fl > 0) do GetChar;

ReadInteger(i); { read integer section }

r := i; { convert integer to real }

if NextChar in ['.', 'e', 'E'] then begin { it's a real }

if NextChar = '.' then begin { decimal point }

GetChar; { skip '.' }

if not (NextChar in ['0'..'9']) then

throw(InvalidRealFormat');

p := 1.0; { initialize power }

while NextChar in ['0'..'9'] do begin { parse digits }

p := p/10.0; { find next scale }

{ add and scale new digit }

r := r+(p * (ord(NextChar) - ord('0')));

GetChar { next }

end

end;

if NextChar in ['e', 'E'] then begin { exponent }

GetChar; { skip 'e' }

if not (NextChar in ['0'..'9', '+', '-']) then

throw(InvalidRealFormat);

ReadInteger(i); { get exponent }

{ find with exponent }

if i < 0 then r := r/pwrten(i) else r := r*pwrten(i)

end

end;

{ make sure the rest of the field is spaces }

while fl > 0 do begin

if NextChar <> ‘ ‘ then throw(InvalidRealFormat);

GetChar

end

end;

begin

ReadReal(f, r, 10)

end.

Constant strings are allowed to appear in the read/readln parameter list:

program p;

var f: text;

i: integer;

begin

read(f, ‘The answer is: ‘, a, ‘ resulting in: ‘, b);

end.

The effect of such a constant is that each character of the input is matched to the characters in the string, in turn, regardless of if the end of line is true. If the character is matched, it is read and thrown away. If the character is not matched, it is an error.

The following code shows the equivalent of such a match.

program p;

var f: text;

i: integer;

procedure ReadConstant(var f: text; view s: string);

begin

for i := 1 to max(s) do

if f^ <> s[i] then throw(UnmatchedConstantCharacter);

get(f)

end;

begin

ReadConstant(f, ‘The answer is: ‘)

end.

6.17 Type converters/restrictors

expression = simple-expression [ relational-operator simple-expression ] .

simple-expression = [ sign ] term { adding-operator term } .

term = factor { multiplying-operator factor } .

multiplying-operator = '*' | '/' | 'div' | 'mod' | 'and' .

adding-operator = '+' | '-' | 'or' | 'xor' .

Pascal defines the function ord to convert any scalar or character type to integer, and defines the function chr to convert integer to character. Pascaline extends this system to include enumerated types "type converter":

program p;

type a = (one, two, three);

var x: a;

begin

x := a(1);

end.

In the example the result of a(1) is the enumerated type constant two. Transfer from an integer to an enumerated type is the only new type conversion defined in Pascaline.

A similar appearing construct is the “type restrictor”:

program p;

type a = 20..30;

var y: integer;

begin

y := a(y+1);

end.

The assignment y := a(y+1) would seem to have no function. However, the compiler can take this as a hint that instead of promoting the expression y+1 to the full size of an integer, that the operation can be performed in only the precision required for values within 20..30. This can enable more efficient processing of expressions on some machines.

When a type restrictor appears, the compiler can generate an error for values in the restricted value that cannot fit in the range of the target type. Type converters and restrictors never simply discard values.

The value within a type restrictor must be assignment compatible with the type specified in the type restrictor.

6.18 Fixed types

block = { declaration } [ 'private' declaration ] statement-part [ ';' statement-part ] .

fixed-declaration-part = [ 'fixed' fixed-declaration ';' { fixed-declaration ';' } ] .

fixed-declaration = identifier-list ':' type-denoter '=' value-constructor.

value-constructor = array-value-constructor | record-value-constructor | constant .

array-value-constructor = 'array' value-constructor { ',' value-constructor } 'end' .

record-value-constructor = 'record' value-constructor { ',' value-constructor } 'end' .

In addition to declaring variables, Pascaline can declare a program construct that appears anywhere a variable can, but is defined completely at compile time:

program p;

fixed a: integer = 1;

b: array [1..10] of integer =

array 5, 6, 8, 2, 3, 5, 9, 1, 12, 85 end;

c: record a: integer; b: char end = record 1, 'a' end;

d: array [1..5] of packed array [1..5] of char = array

'tooth',

'trap ',

'same ',

'fall ',

'radio'

end;

begin

end.

The declaration of a fixed is similar to a var declaration, but each variable is given a "value" part that contains a value constructor. A value constructor is a series of constants or other value constructors separated by ‘,’s. As in the case of character array constant assignment to character array variables, a constant string can be used to specify the value of a fixed character array, and must have the same number of characters as the definition.

Fixed types can be used anywhere a variable type can, but a fixed type cannot be "threatened" in the sense of the for variable threat of ISO 7185 6.8.3.9.

6.19 Extended file procedures and functions

Pascaline defines several additional functions dealing with files. Files that are not declared as external via the program header are normally given the property that they are anonymous and may be deleted at the end of the program. In Pascaline, such files can also be named using the function assign:

program p;

var f: text;

begin

assign(f, 'myfile');

reset(f);

{ statements to use file f }

close(f)

end.

assign takes any string (defined in ISO 7185 Pascal as a packed array of characters with a starting index of 1 and any length). The format of the file name contained in the string is entirely implementation dependent, but implementations will honor, at minimum, the conventions that:

1. Leading and trailing spaces in the name are ignored, and removed if required.

2. That the characters in the set ['a'..'z', 'A'..'Z', '0'..'9', '_'] are valid in a filename.

3. The filename must begin with characters from the set ['a'..'z', 'A'..'Z','_'].

Notes:

1. These are the same conventions as used for identifiers in Pascaline.

2. This is only a subset of implementation defined filename conventions. The particular Pascaline implementation may have its own additional requirements for the formatting of filenames that are a superset of the above conventions.

The Pascaline standard library services has a higher level structuring of filenames that are upward compatible with the above conventions. See Annex G.

The existence of a named file implies, but does not require, that the file is not deleted at the end of the program run. It further implies that applying reset to a named file will allow its preexisting contents to be accessed.

As in ISO 7185 Pascal, applying reset or rewrite to a file causes the file to change from the "undefined" state to "read" for reset, and "write" for rewrite. It is an error to apply assign to a file that is not in the undefined state, that is, to rename it while it is active.

A file must be in the undefined state to have assign applied to it. The effect of multiple assign operations applied to the same file while in the undefined state is itself undefined.

To allow the processing of multiple files by name, the procedure close exists:

program p;

var f: text;

names: array 5 of packed array 10 of char = array

‘myfile ‘,

‘thisfile ‘,

‘thatfile ‘,

‘nextfile ‘,

‘lastfile ‘

end;

i: integer;

begin

for i := 1 to 5 do begin

assign(f, names[i]);

{ statements that use file f }

close(f)

end

end.

close causes bond between the file variable and the named file itself to be broken, and the file state to be returned back to undefined. In this state, it can have assign applied again. In this way, a sequence of named files can be processed. close implies that if the file is anonymous, it is deleted, and that the file returns to being anonymous unless assigned again.

Because in Pascaline, a named file is implied to persist beyond the end of a program, it is also implied that each file that exists in a read or write state has a close performed on it automatically either when the program ends, or when the file variable falls out of activation.

ISO 7185 Pascal defines files as a series of elements which can be examined in turn. Pascaline defines the standard function length to give the number of elements within a file:

program p(output);

var f: file of integer;

begin

assign(f, ‘myfile’);

writeln('The length of the file is: ', length(f));

close(f)

end.

The function length is equivalent to:

program p(output);

type fi: file of integer;

var f: fi;

function length(var f: fi): lcardinal;

var l, r, p: integer;;

begin

l := 0; { clear length }

r := 0; { clear remainder }

{ find remaining elements }

while not eof(f) do begin get(f); r := r+1 end;

{ rewind and count the total elements }

reset(f);

while not eof(f) do begin get(f); l := l+1 end;

p := l-r; { find position from length – remainder }

{ find original position }

reset(f);

while p > 0 do begin get(f); p := p-1 end;

length := l { return length }

end;

begin

assign(f, ‘myfile’);

reset(f);

writeln(‘Length of myfile: ‘, length(f))

close(f)

end.

The length function cannot be applied to a file of type text, because the length of line endings is implementation defined, so the length of a text file is implementation defined as well.

Each element of a Pascal file can be enumerated. In Pascaline, the elements of a file that is not of type text are numbered from 1 to n, where n is the last element of the file. The current location within the file is found with the built in function location:

program p(output);

var f: file of integer;

begin

writeln('The location in the file is: ', location(f));

end.

The function location is equivalent to:

program p;

type fi: file of integer;

var f: fi;

function location(var f: fi): lcardinal;

var l, r, p, c: integer;

begin

l := 0; { clear length }

r := 0; { clear remainder }

{ find remaining elements }

while not eof(f) do begin get(f); r := r+1 end;

{ rewind and count the total elements }

reset(f);

while not eof(f) do begin get(f); l := l+1 end;

p := l-r; { find position from length – remainder }

{ find original position }

reset(f);

c := p; { set count from position }

while c > 0 do begin get(f); c := c-1 end;

location := p { return location }

end;

begin

assign(f, ‘myfile’);

reset(f);

writeln(‘Location of myfile: ‘, location(f))

close(f)

end.

The current location within a file can be set by the built in procedure position:

program p;

var f: file of integer;

begin

assign(f, ‘myfile’);

reset(f);

position(f, 10)

{ statements to use f }

close(f)

end.

The procedure position is equivalent to:

program p;

type fi: file of integer;

var f: fi;

procedure position(var f: fi; p: integer);

begin

reset(f);

while p > 1 do begin get(f); p := p-1 end

end;

begin

assign(f, ‘myfile’);

reset(f);

position(f, 10);

{ statements to use f }

close(f)

end.

position will work with any element from 1 to n+1, where n is the last element of the file. position allows the location to be set one beyond the length of the file so that the file can be extended at the end.

As with length, there is no way to apply either location or position to a text file.

It is an error to apply position to an undefined file.

In ISO 7185 Pascal, there is no way to update a preexisting file with new data. In Pascaline the procedure update can be used instead of rewrite:

program p;

var f: file of integer;

begin

assign(f, 'myfile');

update(f);

{ statements to use f }

end.

The procedure update for integers is equivalent to:

program p;

type fi: file of integer;

procedure update(var f: fi);

var cpy: fi;

i: integer;

begin

! copy previous contents of file

reset(f);

rewrite(cpy);

while not eof(f) do begin read(f, i); write(cpy, i) end;

! change modes and copy back to original file

rewrite(f);

reset(cpy);

while not eof(cpy) do begin read(cpy, i); write(fi, i) end

end;

var f: fi;

begin

assign(f, 'myfile');

update(f);

! statements to use f

end.

The file that update is applied to must exist.

As for rewrite, update places the file in write mode. However, update does not clear the previous contents of the file. Update sets the location within the file at 1, just as reset does. If the common operation of updating a file at the end is wanted, the following code does this:

program p;

var f: file of integer;

begin

assign(f, 'myfile');

update(f);

position(f, length(f)+1);

! statements to use f

end.

update only works with non-text files. The built in procedure append performs the same action as above, but works with both text and non-text files:

program p(output);

var f: text;

begin

assign(f, 'myfile');

append(f);

writeln(f, 'hi there');

end.

The procedure append for text files is equivalent to:

program p;

procedure append(var f: text);

var cpy: text;

c: char;

begin

! copy previous contents of file

reset(f);

rewrite(cpy);

while not eof(f) do begin

if eoln(f) then begin readln(f); writeln(cpy) end

else begin read(f, c); write(cpy, c) end

end;

! change modes and copy back to original file

rewrite(f);

reset(cpy);

while not eof(cpy) do begin

if eoln(cpy) then begin readln(cpy); writeln(f) end

else begin read(cpy, c); write(f, c) end

end

end;

var f: text;

begin

assign(f, 'myfile');

append(f);

! statements to use f

end.

The file that append is applied to must exist.

To determine if a file by name exists in the system, the function exists can be used:

program p(output);

var f: text;

begin

if exists(‘thisfile’) then

{ operate on ‘thisfile’ }

end.

The exists function takes a variable reference to a Pascaline string, and returns a boolean value that is true if the file exists.

The exists function can be used to determine beforehand if a reset will yield an error because of a non-existent file.

To delete a file by name, the delete procedure is used:

program p(output);

begin

delete('oldfile')

end.

delete accepts a variable reference to a string, and causes the file to be removed from the system. It is an error if the file does not exist.

To change the name of an existing file, the change procedure is used:

program p(output);

begin

change('newname', 'oldname')

end.

The file with the name of the second parameter is changed to be the first parameter. Both parameters are variable references to strings. It is an error if the second parameter does not exist in the system, and also if the first parameter exists before the change call. It is also an error if any differences exist in the names besides just their principal names. This rule forbids, for example, the changing of the location or system parameters of the file using the change call.

6.20 Added program header standard bindings

Besides the ISO 7185 Pascal textfile external bindings of input and output, there are three new external bindings defined by Pascaline:

error

This file can be used to output error messages or warnings to. It may be aliased to output by an implementation. The purpose of the error file is to provide a output file that will always go to the user's console, and cannot be redefined as routed to another display device.

list

This file is used to output for what is assumed to be printout from any attached hard copy device. The implementation may alias this file to the output file if such a device is not available, or if hard copy is not desired.

command

The command file is a text line or series of text line that deliver instructions to the running program. Most commonly, it carries a single line containing the remaining text of the command line that activated the running program, after the command name itself is discarded. However, it can contain any instruction line, and can even be directed to be an entire file containing such commands.

The exact format of the commands and parameters contained in file are implementation dependent. If the implementation has no concept of a command line, the file can be assigned to another file, or may appear empty.

Since on many systems a command line exists as a line of text in memory, not as part of a file system, it is understood that the implementation will simulate the access to such a line as a file, if that is required.

In the Pascaline specification, implementers are reminded of the requirements of ISO 7185 6.10 "Programs" wherein it is an error if a program parameter is acted on and cannot complete that action. This clause of ISO 7185 Pascal specifically forbids ignoring the program parameters.

Further, in Pascaline it is strongly suggested that the program parameters which are common text files be connected, or can be caused to connect, to external files by binding to command file names. (See Annex C).

6.21 Redeclaration of forwarded procedures and functions

In Pascaline, the parameters of a forwarded procedure or function can be repeated. As in ISO 7185 Pascal, the names of the parameters are the same as the original names in the forwarded header. The new names, if they happen to be different in the repeated header, are ignored. However, the two parameter lists are checked for "congruency" using the same rules as procedure and function parameters in ISO 7185 6.6.3.6 “Parameter list congruity”.

Repeating the parameters in a forwarded procedure or function both increases the self documenting nature of a program, by keeping the parameters close to the actual body of the procedure or function, as well as making it easier to create such headers, by simple block copy.

6.22 Anonymous function result

Pascaline has an alternate method to indicate a function result:

function-declaration = function-heading ';'directive | function-identification ';' function-block | function-heading ';' function-block .

function-block = block .

block = { declaration } [ 'private' { declaration } ] statement-part [ ';' statement-part ] .

compound-statement = 'begin' statement-sequence [ ‘result’ expression ] 'end' .

At the end of the main block of a function, a result statement can appear:

program p;

function y(a, b: integer): integer;

begin

result a+b

end;

The result statement is an alternative to the ISO 7185 arrangement of assigning the result to the name of a function that is active. It can only be used in a function, and it can only be used at the end of the function. It can only give the result of the enclosing function (in contrast to ISO 7185 Pascal function results). It cannot be used in conjunction with a ISO 7185 Pascal assignment to the name of the function appearing in either the block of the function whose result is to be set, nor any nested block. Thus, the following example is illegal:

{ illegal example }

program p;

function y(a, b: integer): integer;

procedure q;

begin

y := 1

end;

begin

result a+b

end;

But this example is legal:

program p;

function y(a, b: integer): integer;

function q: integer;

begin

y := a+b;

result 1

end;

begin

a := q

end;

The assignment to the function result y is legal in q, even though q is using the result method, because the function y is using the ISO 7185 named function result method.

Unnamed function results give a clear way to indicate the function result, that obeys the single entry/single exit rule with the function result formed at the exit. They are also required in order to indicate the result of an operator overload function (See 6.25 “Operator overloads”).

6.23 Extended Function results

Function results can be any type, including structured:

program p;

type a: array 10 of integer;

function y: a;

var z: a;

i: integer;

begin

for i = 1 to 10 do z[i] := i+10;

y := a

end;

begin

end.

Such extended function results imply greater costs due to the need to copy the structure back to the caller.

A function result cannot be a file, nor a structure having any part that is a file..

Function results can be container arrays, but must be compatible with the result.

The ISO 7185 rule that function results must be assignment compatible with the function result type remains.

6.24 Halt procedure

A standard Pascaline procedure halt exists:

program p;

begin

if not exists(‘myfile’) begin

writeln(‘needed file does not exist’);

halt

end

end.

The halt procedure causes the program, and all of its threads, to immediately terminate. It is equivalent to throwing the unspecified global exception.

The equivalent code for a program block is:

program p;

label 99;

begin

if not exists(‘myfile’) begin

writeln(‘needed file does not exist’);

goto 99

end;

99:

end.

The halt procedure will terminate the enclosing program no matter which module it appears in.

6.25 Overloading of procedures and functions

procedure-heading = attribute 'procedure' identifier [ formal-parameter-list ].

function-heading = attribute 'function' identifier [ formal-parameter-list ] ':' result-type.

attribute = 'overload' | 'static' | 'virtual' | 'override' | ‘operator’ .

The attribute overload can be used to specify that one procedure or function forms an overload group with another:

program p;

procedure x(y: integer);

begin

{ statements to operate on parameter y }

end;

overload procedure x(c: char);

begin

{ statements to operate on parameter c }

end;

Any number of procedures or functions with the same name can be joined this way into an overload group. When the procedure or function is called, the compiler determines which of the procedures or functions in the overload group is to be used to satisfy the call. Thus, both of these calls are possible with the definitions above:

x(1);

x('c');

The compiler considers three things when determining which procedure or function of an overload group is meant:

1. If the called context is a procedure or function call.

2. The number of parameters.

3. The type compatibility of the parameters.

Overload groups are not allowed to be ambiguous. There is no "preference" or "priority" involved with overloads. If two overloads are ambiguous with respect to each other, then an error will result at the time of the definition of the conflicting overload.

Two calls are ambiguous with each other if they match for procedure/function status, have the same number of parameters, and the parameters are compatible between lists, using the ISO 7185 definition of compatibility according to 6.4.6 “Assignment-compatibility” (where either parameter could be assignment compatible with the other), and also if one parameter is char while the other is a single character string. This means, for example, that having one parameter of type real, and the other of type integer, means those parameters are ambiguous with each other.

When parameter lists are compared, the mode of the parameter, or its var, view or value status is ignored.

It is an error if two parameter lists "converge" with different modes. Two parameter lists are said to converge at any point in the list if that parameter and all parameters to the left of it are found to be compatible using the rules above. An example of an overload declaration that is invalid by this rule is:

! invalid program

program p;

procedure a(i: integer; c: char; b: boolean);

begin

{ statements of first overload of a }

end;

overload procedure a(i: integer; var c: char; b: boolean; r: real);

begin

{ statements of second overload of a }

end;

begin

end.

Even though the two parameter lists would be distinct because they differ in number, the lists are convergent at parameter c, and parameter c has conflicting modes, the first being value, and the second being var.

The purpose of the convergence rule is to relieve compilers from having to store all the parameters in a procedure or function call before determining which routine of an overload group matches the call.

Overload groups must be completed within the same declaration block. Different modules, classes, procedures and functions cannot add to each other’s overload groups.

6.26 Operator overloads

operator-declaration = operator-identifier operator-heading ‘[ ‘:’ result-type] .

operator-heading = ‘operator' formal-identifier [ formal-parameter-list ] .

operator-identifier = ‘not’ | ‘+’ | ‘-‘ | ‘*’ | ‘/’ | ‘div’ | ‘mod’ | ‘and’ | ‘or’ | ‘< ‘ | ‘>’ | ‘=’ | ‘<=’ | ‘>=’ | ‘in’ | ‘is’ | ‘:=’ .

Besides overloading procedures and functions, it is also possible to overload expression operators:

program p;

type string = packed array of integer;

pstring = ^string;

operator +(a, b: string): pstring;

begin

{ code to concatenate strings a and b }

end;

operator :=(a, b: string);

begin

{ code to assign string b to a }

end;

begin

end.

Where “+” and “:=”are the operators to overload. The following operator overloads are possible:

Program p;

type x: record i, r: integer end;

operator +(a: x): x; begin result a end;

operator –(a: x): x; begin result a end;

operator not (a: x): x; begin result a end;

operator +(a, b: x): x; begin result a end;

operator -(a, b: x): x; begin result a end;

operator *(a, b: x): x; begin result a end;

operator /(a, b: x): x; begin result a end;

operator div(a, b: x): x; begin result a end;

operator mod(a, b: x): x; begin result a end;

operator and(a, b: x): x; begin result a end;

operator or(a, b: x): x; begin result a end;

operator xor(a, b: x): x; begin result a end;

operator <(a, b: x): x; begin result a end;

operator >(a, b: x): x; begin result a end;

operator =(a, b: x): x; begin result a end;

operator <=(a, b: x): x; begin result a end;

operator >=(a, b: x): x; begin result a end;

operator in(a, b: x): x; begin result a end;

operator is(a, b: x): x; begin result a end;

operator :=(out a: x; b: x): x; begin end;

begin

end.

The ‘-‘ and ‘+’ operators can be both unary and binary, and they have different priorities. The exact type of operator is indicated by the number of parameters that appear. There is only one operator procedure, which is assignment (‘:=’).

The parameters to an operator function can be any type, but cannot be var parameters.

The parameters to the operator procedure ‘:=’ can be any type, but the first parameter must use out mode.

The results of an operator function cannot be established via a ISO 7185 by name function result assignment. Instead, the unnamed result form is used (see 6.22 “Anonymous function result”).

The existence of an operator overload does not change the priority of the operator.

Operator overloads follow the same rules as standard overloads. Specifically, operator overloads cannot be ambiguous with either each other, or the parameters of standard , built in operators.

The types of built in operators with the exception of is appears in ISO 7185 6.7.2 “Operators”.

The existence of an operator overload will not cause the built-in operator to be altered in any way. An operator overload simply adds behavior where the built-in operator would indicate a type error.

Note that since the system definition for is is defined for any object, it is not possible to overload the is operator for objects.

The use of an operator overload function to introduce so-called “side effects” will result in ambiguity as to when the side effect occurs, since Pascaline does not specify expression evaluation order.

6.27 Static procedures and functions

procedure-heading = attribute 'procedure' identifier [ formal-parameter-list ].

function-heading = attribute 'function' identifier [ formal-parameter-list ] ':' result-type.

attribute = 'overload' | 'static' | 'virtual' | 'override' | ‘operator’ .

Pascaline defines a static attribute that is used before any function or procedure to indicate that it is used statically.

program p;

static procedure z;

var x, y: integer;

begin

{ statements of z }

end;

static function y;

begin

{ statements of y }

end;

begin

end.

The static word-symbol is used to indicate to the compiler that the procedure or function with that attribute will not recursively call itself, nor be called by any subprocedure or subfunction.

On some processors with limited addressing resources, using static can result in smaller and faster executable programs, sometimes dramatically so. Compilers targeting more advanced processors typically ignore the static word-symbol.

In the case where the procedure or function is contained entirely within a module, and is not visible outside the module (it is within the private section), the compiler can automatically determine the static status of a procedure or function. However, if it is visible outside the module, the compiler must assume it may be recursively called. In this case, the static attribute is required to obtain the improved code.

Note:

1. The compiler may also detect that a static attributed procedure or function calls itself, either directly or indirectly via another procedure or function, and issue an error.

6.28 Relaxation of declaration order

block = { declaration } statement-part .

The declaration order in ISO 7185 Pascal of labels, constants, types, variables, then procedures and functions is relaxed. These constructs can appear in any order. However, the rule remains that each identifier must be declared before its use, with the normal ISO 7185 Pascal exception for pointer declarations.

Pointer forward references must resolve within the same var declaration.

Relaxing declaration order in Pascaline is a more natural match for modular compilation.

6.29 Exception handling

try-statement = 'try' (statement-sequence) try-end .

try-end = (except-series | except-unconditional) [ 'else' statement ] .

except-series = except-specifier { except-specifier } [ except-unconditional ] .

except-unconditional = ‘except’ statement .

except-specifier = ‘on’ exception-identifier { ‘,’ exception-identifier } ‘except’ statement .

block = { declaration } [ 'private' { declaration } ] statement-part [ ';' statement-part ] .

statement-part = compound-statement .

compound-statement = 'begin' [try-end] statement-sequence [ ‘result’ expression ] 'end' .

The most common use for interprocedure gotos is to handle error returns easily from deep nested procedures. Pascaline provides an alternative structure. The try statement executes one or more statements with an "exception guard":

program p;

var myexception: exception;

begin

try

{ ... }

throw(myexception)

{ ... }

on myexception except { statement to execute on myexception }

except { statement to be executed on any exception }

else { statement to be executed if no exception occurs }

end.

If anywhere within the guarded execution the statement:

throw(myexception);

throw;

is executed, any active procedures or nested statements are removed, and execution resumes with the statement after either the exception clause that matches the given exception, or the general exception statement. If no exception occurs, execution continues either with the else statement, if specified, or the next statement after the try statement.

The program:

program p(output);

var myexception: exception;

begin

try

{ ... }

throw(myexception)

{ ... }

on myexception except writeln(‘The operation failed’)

else writeln(‘The operation succeeded’)

end.

Is equivalent to:

program p(output);

label 1;

var myexception: boolean;

begin

myexception := false;

begin

{ ... }

myexception := true; goto 1;

{ ... }

end;

if myexception writeln(‘The operation failed’)

else writeln(‘The operation succeeded’)

end.

The try statement may carry a specific list of exceptions, followed by an optional unconditional exception, or simply an unconditional exception. An unconditional exception matches any exception. A specific exception only matches the named exception.

When an unspecified exception is thrown, the result is as if an exception was thrown that does not appear anywhere in the program. It is the “master” exception handler that always exists in any program.

try statements may nest. The result of executing throw is to return to the innermost try statement currently executing. If a goto is used to branch outside of the try statement, then it will be effectively removed from activation, and any throw statements will go to the next outer try statement.

If an exception is thrown, and either there is no try statement active, or no try statement matches the exception indicated, then the result is an error. The result of unhandled exceptions is as if a try statement exists outside of the program that catches any exceptions that are not handled within it, and handles the exception by termination.

Exceptions are represented by a special variable defined at the system level called the exception type:

module throwit;

var myexception: exception;

procedure fault;

begin

throw(myexception)

end;

begin { throwit }

end. { throwit }

In order to throw an exception, both the thrower and the catcher must be able to see the same exception variable. The exception to this rule is the unspecified exception, which is available program wide.

An exception is a predefined type. If an exception is passed as a parameter, it must be passed with var mode.

The exception handler itself can throw another exception, including an unspecified one. However, exceptions do not stack, nor is there any state, such as handled or unhandled, associated with exceptions.

Note:

Exceptions do not cross thread or process boundaries. A thrown exception will only return to the same thread, and only to an active outer block of that thread.

A special version of the try statement exists for module constructor sections (see 6.36 “Modularity”). It is common for modules, which only execute when the program starts up and shuts down, to register handlers for all of the exceptions that are thrown in that module. The reason is to allow the program and other nested modules to handle the exceptions, but ultimately handle the exception in the originating module.

module m(output);

var FaultException: exception;

procedure doit;

begin

throw(FaultException)

end;

begin { constructor }

end; { constructor }

begin { destructor }

on FaultException except writeln(‘*** module fault occurred’)

end. { destructor }

The constructor for the module behaves as if it performed a try statement at the end of the constructor. The destructor then finishes the try statement. Note that the on construct must appear immediately after the begin for the destructor block.

The primary purpose of a constructor/destructor exception handler is to handle exceptions defined within the module. It is possible to handle exceptions created by other modules, but it is an error to throw an exception to an exception variable whose module is not active.

Note that when an unhandled exception occurs in a separate process, that causes the entire program to terminate.

Being a variable, an exception cannot be shared across process, monitor and channel barriers. This means that monitor exceptions are self-contained and go back to the monitor itself. General exceptions go back to the process, monitor or channel that contains them. An unhandled exception always terminates the program, no matter what thread the exception occurs on.

6.30 Assert Procedure

The assert procedure generates a runtime error if its expression is not true:

assert-statement = 'assert' '(' expression [‘,’ character-string]')'

The expression can be any expression with a boolean result type. If the expression evaluates at runtime as false, then the program faults, otherwise it continues to run.

If a string constant is present after the exception boolean expression, it will serve to “annotate” the assert. Typically it contains the reason for the exception. It may be printed as part of any error message. Alternatively, it may have no effect.

The program:

program p(output);

var pi: ^integer;

begin

pi := nil;

assert(p <> nil, ‘The pointer was nil’)

end.

Is equivalent to:

program p(output);

label 99;

var pi: ^integer;

begin

pi := nil;

if p = nil begin

writeln(‘The pointer was nil’);

goto 99

end;

{... }

99:

end.

The assert procedure enables placing a large number of consistency checks within a program being developed that can be automatically removed from the code by a compiler option.

In addition, an implementation can provide extended debugging information when the assert occurs, such as program location, registers, etc.

6.31 Extended range types

ISO 7185 Pascal defines the results of integer expressions to lie within the range -maxint..maxint. The size of an integer is by definition chosen to be the size that is most efficient and natural on the target machine. Just as Pascaline defines operations to restrict results to numbers smaller than integer, it defines the ability to find results larger than a standard integer. If larger than integer variables and operations are specified, it is assumed that some penalty in terms of time, space or both will be added.

To specify an extended range value, a subrange is specified outside of the range -maxint..maxint. For example:

var li: 0..maxint*2;

Pascaline does not define the maximum length of such extended range types.

When an extended range value appears in an expression, the range of the result will have a range according to the following rules:

1. If either type is signed, the result is a signed type.

2. If either type is extended range, the result is an extended range type.

Operations with extended types are not guaranteed to be able to hold all the values of both operands. The implementation is only required to maintain at least the range of values in integer.

In addition, the programmer can specify the exact length of result at any point in the evaluation of an expression using range specifications. The only way to achieve an exact range of values throughout a calculation is to specify it.

Pascaline predefines three new types of integer.

cardinal

Cardinal types represent the positive integers only. The range of cardinal is:

0..maxcrd;

Where maxcrd is a predefined constant. maxcrd is the maximum unsigned value of a machine word on the target machine. It could also be equal to maxint on an implementation that does support extended cardinal types.

linteger

Long integer types represent an extended, signed integer type, defined as:

-maxlint..maxlint;

Where maxlint is a predefined constant. maxlint is typically the maximum value of a "double length" result on the target machine, that is, a value formed using two machine words. It can also be equal to maxint on an implementation that does not support extended linteger types.

lcardinal

Long cardinal types represent the positive integers only. The range of lcardinal is defined as:

0..maxlcrd;

Where maxlcrd is a predefined constant. maxlcrd is the maximum unsigned value of a "double length" result on the target machine, that is, a value formed using two machine words. It can also be equal to maxint on an implementation that does not support extended lcardinal types.

The interactions of binary operators on all integer based types is as follows:

TYPE A	TYPE B	RESULT TYPE
integer	integer	integer
cardinal	cardinal	cardinal
linteger	linteger	linteger
lcardinal	lcardinal	lcardinal
integer	cardinal	integer
linteger	lcardinal	linteger
linteger	cardinal	linteger
integer	lcardinal	linteger
linteger	integer	linteger
lcardinal	cardinal	lcardinal

Unary operators simply deliver the same type as the operand.

Note:

The lack of defined maximum for integer representation in Pascaline can be interpreted to implement so called “N-length integers”, which can be any length up to the size of memory in the implemented machine. This is the analog of arbitrary length sets in ISO 7185 Pascal.

6.32 Extended real types

Pascaline defines two new real types, sreal and lreal:

program p;

var sr: sreal;

lr: lreal;

begin

end.

Unlike integers, Pascaline cannot set ranges for real types. Also unlike integers, there is no “natural” size of a real for most machines, as in the native type that is inherent to the word size of the machine.

sreal defines a real type that smaller and has less precision than a ISO 7185 real. lreal defines a real type that is larger and has greater precision than a standard ISO 7185 real. An sreal has a precision that is less than or equal to real, and lreal has a precision that is greater than or equal to real. In practice, sreals can be equivalent to reals, and lreals can be equalent to reals.

The use of an sreal implies that the programmer wishes to save space, and perhaps execution time over the use of an ISO 7185 Pascal real, in exchange for less precision and total range. The use of an lreal implies that the programmer wishes to obtain more precision and total range than an ISO 7185 Pascal real, in exchange for using more space and perhaps longer execution time. The word “perhaps” is used here because it is common to simply extend all real types to the same length on some machines and process them identically.

All real types are compatible with each other, and behave as reals in all contexts. In equations, reals are always “value conserving”. The result of mixing two different types of reals is the larger of the two.

The result of using different real types in combination is:

Type A	Type B	Result type
real	real	real
sreal	sreal	sreal
lreal	lreal	lreal
sreal	real	real
lreal	real	lreal
Sreal	lreal	lreal

6.33 Real Limit Determination

Several new system defined constants are defined to express the limits of real numbers:

Type	Low Limit	High Limit
real	-maxreal	maxreal
sreal	-maxsreal	maxsreal
lreal	-maxlreal	maxlreal

6.34 Character limit determination

Pascaline provides a constant for character set implementation limits:

maxchr

This character constant defines the maximum value of a character in the range:

chr(0)..maxchr;

maxchr is of type char.

6.35 Matrix mathematics

One dimensional arrays of integers or reals and two dimensional arrays of integers or reals can participate in expression operations:

Operator	Function
+a	matrix affirmation
-a	Matrix negation
a+b	matrix Addition
a-b	matrix Subtraction
*ab**	matrix Multiplication

program p;

type ai: array 10 of integer;

var ai1, ai2: ai;

begin

ai1 := ai1+ai2;

ai1 := ai1+1

end.

Is equivalent to:

program p;

type ai: array 10 of integer;

var ai1, ai2: ai;

i: integer;

begin

for i := 1 to 10 do ai1[i] := ai1[i]+ai2[i];

for i := 1 to 10 do ai1[i] := ai1[i]+1

end.

For a matrix case:

program p;

type ai: array 10, 10 of integer;

var ai1, ai2: ai;

begin

ai1 := ai1+ai2;

ai1 := ai1+1

end.

Is equivalent to:

program p;

type ai: array 10 of integer;

var ai1, ai2: ai;

x, y: integer;

begin

for x := 1 to 10

for y := 1 to 10 do ai1[x, y] := ai1[x, y]+ai2[x, y];

for x := 1 to 10

for y := 1 to 10 do ai1[x, y] := 1;

end.

Any single dimension array of integers or reals with an integer starting index of 1 qualifies as a vector. Any two dimensional array of integers or reals with both integer starting indexes of 1 and equal major and minor dimensions qualifies as a matrix. The allowable operands are:

Operator	Operands
a+b	a or b may be matrix, integer or real.
a-b	a or b may be matrix, integer or real.
*ab**	a or b may be matrix, integer or real.

For two vector or matrix operands to be compatible with each other, they must be of the same type, or aliases of that type. The result is the same type as the operands.

One of the operands of +, -, or * can be an integer or real when the other side is a vector or a matrix. The result of this is a vector or matrix with the given operation performed on each element of the matrix using the single real or integer. However, a single real cannot be used with a integer matrix, as this would imply conversion of real to integer.

program p;

type ai: array 10 of integer;

var ai1: ai;

begin

ai1 := ai1*2

end.

Is equivalent to:

program p;

type ai: array 10 of integer;

var ai1: ai;

i: integer;

begin

for i := 1 to 10 do ai1[i] := ai1[i]*2

end.

And

program p;

type ai: array 10, 10 of integer;

var ai1: ai;

begin

ai1 := ai1*2

end.

Is equivalent to:

program p;

type ai: array 10, 10 of integer;

var ai1: ai;

x, y: integer;

begin

for x := 1 to 10

for y := 1 to 10 do ai1[x, y] := ai1[x, y]*2

end.

Vectors or matrices can also be assigned as a whole:

program p;

type ai: array 10 of integer;

var ai1: ai;

begin

ai1 := 1

end.

Is equivalent to:

program p;

type ai: array 10 of integer;

var ai1: ai;

i: integer;

begin

for i := 1 to 10 do ai1[i] := 1

end.

And

program p;

type ai: array 10, 10 of integer;

var ai1: ai;

begin

ai1 := 1

end.

Is equivalent to:

program p;

type ai: array 10, 10 of integer;

var ai1: ai;

x, y: integer;

begin

for x := 1 to 10

for y := 1 to 10 do ai1[x, y] := 1

end.

Such a vector or matrix assignment causes the expression to be assigned to each of the elements of the vector or matrix. The assignment compatibility rules are the same as non-vector or matrix assignment. If individual elements of the vector or matrix are assignment compatible with the expression, then the entire vector or matrix is also assignment compatible.

Vector or matrix expression operators do not perform a function that could not be added to Pascaline as a library function. Their primary reason for being here is that such operations can often be translated to efficient operations directly in the target hardware.

6.36 Properties

property-identifier = qualified-identifier .

property-declaration = attribute property-identifier ‘:’ type-denoter ‘;’ read-block ‘;’ write-block ‘;’

read-block = block .

write-block = block .

A property is declared object that appears as a variable, but has the reading and writing of its contents completely defined by the program that contains it:

program p;

var sum: integer;

property myval: integer;

begin { read definition }

myval := sum

end;

begin { write definition }

sum := sum+myval

end;

begin

sum := 0;

myval := 10;

myval := 5;

writeln(‘myval is ‘, myval)

end.

The property declaration is followed by two blocks, the first being the read definition block, and the second being the write definition block. During the read and write definition blocks, the identifier that is the same as the property carries the value that is written or read, and acts as an ordinary variable within the definition block that can be read or written. Outside of the property definition, the identifier is defined by the actions in the read and write definition.

At the end of the read definition, the content of the property identifier variable is used to satisfy the read request.

At the start of the write definition, the content of the property identifier variable is set from the write request.

Thus in the example, two write requests are made to myval which sums them starting with zero, and the final read request returns the resulting sum, 15.

Properties are a step beyond operator overloading, which can define the calculation of values for entire classes of variables with a given type. Properties can set the exact behavior of individual objects, even if they all have the same type.

Notes:

1. The property can be any type, including structured types, with the exception that it cannot be a file or be a structure containing a file, because a file cannot be the target of an assignment.

2. Each of the read and write blocks of a property can have its own declaration section. The declaration for each of the read or write blocks applies only to that block.

3. Properties can be forwarded just as procedures and functions can.

6.37 Modularity

module = module-heading ';' module-block '.' .

module-heading = module-type identifier [ '(' module-parameter-list ')' ] .

module-block = uses-declaration-part { module-declaration } [ 'private' { module-declaration } ] statement-part [ ';' statement-part ] .

module-declaration = declaration | class-declaration .

uses-declaration-part = [ link-specification module-name { ',' module-name } ] .

link-specification = 'uses' | 'joins' .

module-name = identifier .

ISO 7185 Pascal expresses programs as a series of nested blocks, from programs to procedures and functions. Unfortunately, this model tends to require compilation as a single unit.

Pascaline defines a series of modules which have the same status and level as a program block, but exist in separate files. The basic module appears as:

module x(input, output);

uses mymodule;

var x: integer;

private

var y: integer;

begin

end.

A module appears very much like a program block. It exists in a separate file. It can have header parameters. It has a main block. It also has an "ending" block. Unlike the program block, Modules are not typically designed to execute for the duration of the program, but rather to run at some time before the program block. A module initializes its variables, then passes control on either to other modules, or the program block. If the module has a termination block, this will be executed sometime after the program block completes. This allows the module to perform clean up on termination, such as closing files, etc.

Modules allow a collection of resources to be created, such as labels, constants, types, variables, fixed, procedures, and functions. These are collected as a unit to serve the program. A program block can be thought of as a special case of a module that has no termination block.

The bonding of modules and programs into an executable unit, as well as the order in which the startup blocks and termination blocks are executed is implementation defined.

The use of a module by another module or program is specified by the uses or joins declaration:

uses mod1,mod2;

joins mod1,mod2;

The uses and joins specifiers must precede any other declaration within a program or module. There can be only one uses and one join specifier per program or module.

Both a uses and a joins specification cause the declarations contained within the specified module to be imported to the outer block declarations of the importing module or program. This importation is logically done as if the source file itself were actually read. However, the equivalent of this action may be performed instead by reading a preprocessed equivalent of the target program or module.

A uses or joins specification only imports that specific module. If the imported module itself imports further modules, which it may require to complete its declarations, any such import must occur without exposing that secondary module to the original importing module. This is a so-called "incidental import", and necessary. Such imports will be completed such that their declarations are available to the requesting module, but not the original importing module. This can create the situation that the importing module receives declarations of which it cannot access the component declarations within. If the importing module must access such components, it must specify the containing module in a uses or joins specification. This prevents "zipper effect", where a importing module gets an unintended series of submodules included.

Imported and importing modules can contain loops or mutually referring modules. However, the ISO 7185 Pascal rule remains that an identifier must be defined before its use, with the exception of pointers. Further, pointer declarations must complete within the same module. Import loops can create non-obvious definition problems:

module x;

uses y;

type q = integer;

begin

end.

module y;

uses x;

type r = q;

begin

end.

Will result in an undefined declaration error because module x has not completed the declaration of q at the time module y is processed.

Note that module x and y are in different files. Only one module may appear in a file.

Note that implementations may optionally flag module loops as errors.

All of the declarations of a module can be exported, including constants, types, variables, fixed, procedures, functions and classes with one exception. goto labels cannot be exported, and a goto statement cannot target a module other than its own.

However, it is simple to “bridge” a goto into a given module:

module m;

label quit;

procedure abort;

begin

goto quit

end;

begin

{ ... }

quit:

end.

The reason this is required is because the procedure abort was compiled at the same time as the goto target quit. The information required to adjust program parameters such as the stack are available at that time.

Imports obey the rule that no module is read twice. This prevents the continuous processing of modules.

The appearance of a uses specification causes the identifiers within the imported module to be merged without qualification to the importing module or programs name space. The identifiers can be directly used, and an error will be flagged if there is a duplicate name between importing and imported modules.

The appearance of a joins specification causes the identifiers to be made available in "qualified" form. A qualification appears as follows:

qualified-identifier = module-name { ‘.’ identifier }

For example:

mod1.alpha

Qualification prevents the collision of name spaces and is the preferred method of importing modules.

Notes:

1. Without a uses or joins specification, modules and programs will not conflict even if there are one or more names that are identical between them.

2. Because of the circular nature of imports, it is possible to refer to the components of a module before it has executed its start block. This is an error that may or may not be caught at runtime.

3. It is an error to call a procedure or function that is not active. This is an error that may or may not be caught at runtime.

Pascaline provides a way to create declarations in a module that are not visible by importing modules or programs with the private specification:

module x;

type alpha = array 10 of char;

private

var x: alpha;

begin

end.

The private word-symbol can appear anywhere between declarations. It indicates that all further declarations in in a module cannot be exported. The appearance of the private word-symbol essentially divides the outer declarations of a module into a "public" section that appears first, and a private section that follows. The declarations for a module can thus be set up as a set of public declarations that define the external interface for the module, and a set of private declarations that perform the work of defining the functionality of the module.

The public and private areas cannot be mixed or changed in order. Specifically, it is not possible to create a public definition that is built with private declarations in Pascaline (so called "opaque" types). However, the converse is possible, private declarations based on public declarations.

Procedures and functions can be forwarded across from the public area to the private area. Thus, it is possible to create procedures and functions that use private declarations such as variables and other procedures and functions.

Pascaline does not enforce the structure of intermodule links, nor is this within the power of a language. However, the most reliable structure for modules is a tree with the program module at the top, and successive layers of service and support routines below that. This kind of structure necessarily excludes loops, the allowance of which was required to enable intermodule gotos to process exceptions. The modern means to do that is with exceptions.

6.37.1 Definition vs. implementation modules

Pascaline does not define a special definition as opposed to an implementation module. An implementation module, a module containing all of the source code required to define the contents of the module, also serves as its definition module.

If it is required to construct a module containing just the definitions within a module, and not the implementation source, the common method used is to "strip" the module to arrive at a defacto definition module. Stripping means to remove all definitions that are private, and to remove the contents of any public procedure or function. This will give a module that can be used to define the interface to the module for other modules, but cannot be used to build the module. It is typically used in conjunction with modules that have already been completely processed to object code in the target processor.

Such definition modules can be manually or automatically constructed by the implementation. Definition modules can be verified by compilation with sufficient options to ignore unreferenced definitions, and lack of function result assignments.

Definition modules can also be used to represent modules written in another language, or even assembly language. It is this facility, defined entirely by the Pascaline processor, that takes the place of the external directive defined in ISO 7185 Pascal.

6.37.2 Overrides

procedure-heading = attribute 'procedure' identifier [ formal-parameter-list ].

function-heading = attribute 'function' identifier [ formal-parameter-list ] ':' result-type.

property-declaration = attribute property-identifier ‘:’ type-denoter ‘;’ read-block ‘;’ write-block ‘;’

attribute = 'overload' | 'static' | 'virtual' | 'override' | ‘operator’ .

Overrides give the ability for new modules to add to or replace the functionality of older modules. This may give, for example, the ability for a new module that implements graphical operations on a printer the ability to add to an existing graphical module that implements such operations on a user terminal.

A function or procedure can be specified as capable of being overridden by higher level modules (or even the same module). In order to be overridable, the procedure or function must specify that capability using the virtual word-symbol:

module m;

virtual procedure x;

begin

end;

begin

end.

When specifying a procedure, function or property as virtual, the user should realize that there is a small cost in program run time, program space, or both to handle the requirements of a virtual procedure, function or property.

To override the procedure, function or property, the word-symbol override is used:

module m;

override procedure x;

begin

end;

begin

end.

In many cases, a procedure, function or property that overrides another will extend or change it by handling the new features of the procedure, function or property itself, but then send the unchanged part of the service back to the overridden procedure or function. This can be done via the inherited word-symbol:

module m;

override procedure x(q: integer);

begin

if q = 1 then inherited x(q) else { perform here }

end;

begin

end.

The inherited word-symbol specifies that the following procedure, function or property call is to be sent back to the original overridden version.

If multiple overrides of a function, procedure or property exist, they will nest. The procedure, function or property that is actually performed is the last procedure or function overridden. The function or procedure that is performed when inherited is specified is the function or procedure that was current at the time of the override.

Only one override for the same procedure, function or property can exist in a module. The inherited version of a procedure, function or property can only be called from the module that overrides it.

The order in which overrides are executed is the same as the order of module or object initializations.

Override procedures, functions and properties can only exist at the outer block of a module. They may not be nested.

The overridden virtual procedure, function or property must be external.

The virtual procedure or function and its overrider must be congruous.

No overloads can exist to a virtual or override procedure or function.

A virtual procedure, function or property need not contain useful code. A typical design paradigm is to use a declaration with no useful implementation to define an “abstract” module whose functionality will be defined by further overrider modules:

program graphics;

var notimplemented: exception;

virtual procedure setpixel(x, y: integer);

begin

throw(notimplemented)

end;

virtual procedure line(x, y: integer);

begin

throw(notimplemented)

end;

begin

end.

Only a monitor can override other monitors. Share modules cannot contain overrides.

6.37.3 Parallel modules

A module in Pascaline forms the basic structure of a program. The program block itself is actually a special instance of a module which has no ending block. Together, program modules and common modules form a group that runs the main task of the program.

The process module appears just as a program module. It has only a starting code block, and no ending code block. It can accept header parameters. The difference between a process and a program is that the process defines a new task within the program that runs in parallel with the main task, or any other process blocks.

process mythread(input, output);

uses mymonitor;

var x, y;

procedure q;

begin

end;

begin

while true do writeln(‘I am another thread’)

end.

A process can run "forever", in which case it simply terminates when the main task terminates, or it can run for a time and then stop. A process stops when it exits from its startup block.

A process can have a uses statement, but it cannot use just any module. To do so would be to conflict with the main task run by the program module. No other module can use a process module. A process can use its own globals or routines, and can use a monitor.

A monitor module appears just as normal, program callable module:

monitor m(output);

procedure locked; forward;

private

var x, y;

procedure locked;

begin

x := 1

end;

begin

{ startup statements }

end;

begin

{ shutdown statements }

end.

The monitor module is a multitask "hard" module. Each of its publicly callable procedures, functions and properties have a special locking function that is executed on entry to the routine, and unlocked on exit. The net effect is that only one task running under Pascaline is allowed within a monitor at one time. This prevents the data corruption that would otherwise occur in a multitasking system.

Monitors have other special requirements that prevent data corruption. A monitor cannot have global variable definitions. All global variables must be defined within the private section. Procedures and functions can be defined in the global section, which means that they are multitask locked procedures and functions, but to accomplish useful work, they must typically be forwarded into the private section.

Finally, monitors cannot use var or call by reference for any call to another, external procedure or function. This is to protect the locking of a monitor. Monitors can have a public procedure or function with var parameters. This means that a monitor routine can access the variables of its calling task, but cannot export such references, nor export the monitors own data in a var passed variable.

Monitors can use other monitors, atoms, channels and liaisons, but cannot use a process, program or module. However there is a final module form that can be used by any other module, all of process, program, module and monitor, known as a share module:

share mylibrary(output);

procedure x;

begin

end;

begin

end.

share modules cannot have any global variables at all. Because of this, it also has no startup or shutdown code blocks. There is nothing in a share to set up or to shut down.

The advantage to a share is that it can contain a series of support routines that can be accessed by any caller. A share acts as a monitor without any global data, but does not have the locking overhead of a monitor.

6.37.4 Monitor signaling

Monitors serve as more than just a library of procedures and functions callable by any task. Because a module has state in the form of globals, it can serve as a communications method between tasks. In Pascaline, the monitor is how multiple tasks coordinate their actions.

Given just the definition of monitors above, it would be possible for tasks to communicate by using status routines to flag conditions between them. However, each task would have to poll, or continually call a monitor function to find out that status. This wastes computer time that multitasking is supposed to use efficiently.

Instead, Pascaline defines a special variable called a semaphore, and a few special routines that can be used with them, the signal, signalone, and wait procedures.

monitor queue;

type byte = 0..255; { data type for queue }

procedure inqueue(b: byte); forward;

procedure outqueue(var b: byte); forward;

private

const maxque = 100; { maximum length of queue }

type queinx = 1..maxque; { pointers for queue }

var fifo: array [queinx] of byte; { fifo for queue }

inptr: queinx; { in pointer }

outptr: queinx; { out pointer }

notempty: semaphore; { not empty signal }

notfull: semaphore; { not full signal }

{ queue pointer iterator }

function next(i: queinx): queinx;

begin

if i = maxque then i := 1 { queue has wrapped }

else i := i+1; { next location }

next := i { return result }

end;

{ test queue is full }

function empty: boolean;

begin

empty := inptr = outptr { pointers are equal }

end;

{ test queue is empty }

function full: boolean;

begin

full := next(inptr) = outptr { next input location is out

location }

end;

{ place byte in queue }

procedure inqueue(b: byte);

begin

{ if full, wait until a byte clears }

while full do wait(notfull);

{ place input byte }

fifo[inptr] := b;

{ set next input location }

inptr := next(inptr);

{ signal queue is now not empty }

signal(notempty)

end;

{ get byte from queue }

procedure outqueue(var b: byte);

begin

{ if empty, wait until a byte is available }

while empty do wait(notempty);

{ get output byte }

b := fifo[outptr];

{ set next output location }

outptr := next(outptr);

{ signal queue is now not full }

signal(notfull)

end;

begin { constructor }

{ set input = output, and queue is empty }

inptr = 1;

outptr = 1

end.

The wait procedure acts just as a loop to poll if the condition represented by the semaphore has occurred, but it is implemented efficiently under Pascaline. Typically, the calling task is put to sleep until the signal occurs, then it is woken up again to continue.

When a signal call is made, this causes any and all tasks waiting on the signal to be freed to run. If the signaling tasks knows that only one task can actually use the signal, it can use the signalone call instead. This will only free up a single task, and leave the rest to wait for the next signal.

Semaphores give tasks an easy method to flag a given event between them. They are most commonly used to pass data between tasks. A "data provider" task would place data into global structures in the monitor, then signal to any "data consumer" tasks that the monitor has data.

Semaphores can only be used within a monitor, which is the only place they have meaning. A wait call would not be useful if it left the monitor lock in effect, blocking any other task from signaling to it. The wait call releases the lock on the monitor that calls it until it is signaled and emerges from the wait. Then it reasserts the lock and continues.

Semaphores are implemented under Pascaline as "fair", or having the property that tasks that wait for a semaphore receive the signal on a "first come-first serve" basis. However, if the signal procedure is used to signal multiple tasks (as opposed to a signalone call), it is possible that one or more of the signaled tasks could find that the condition being waited on is no longer true, since another task has serviced it first. For this reason, wait is used in a loop that checks for the condition being true.

monitor lock;

procedure getlock; forward;

procedure putlock; forward;

private

var lockactive: boolean;

lockfreed: semaphore;

procedure getlock;

begin

while lockactive do wait(mysignal);

lockactive := true

end;

procedure putlock;

begin

lockactive := false;

signalone(lockfreed)

end;

begin

lockactive := false

end.

Note that signalone could be implemented as signal. This means that the wait loop method should be used even with signalone.

The equivalent code for semaphore, wait, signal and signal one is:

module signal;

private

type semaphore = record

one: boolean; ! single/multiple signal flag

inq: integer; ! input queue pointer

outq: integer ! output queue pointer

end;

var s: semaphore;

! Find next queue circular position

function next(i: integer): integer;

begin

if i = maxint then i := 0 else i := i+1

result i

end;

! Test for queue empty

function empty(var s: semaphore): boolean;

begin

result s.outq = s.inq

end;

! Test for queue full

function full(var s: semaphore): boolean;

begin

result s.outq = next(s.inq)

end;

procedure wait(var s: semaphore);

var p: integer; ! our place in queue

begin

! if queue is full, wait for entry

while full(s) do escape;

s.inq := next(s.inq); ! advance input queue

p := s.inq; ! save that position

while s.outq <> p do escape; ! wait for our turn

! if there are more in queue and not single mode, advance

if not (s.one and not empty(s)) then s.outq := next(s.outq)

end;

procedure signal(var s: semaphore);

begin

! flag signal complete

if not empty(s) then s.outq := next(s.outq);

s.one := false ! set multiple waiters ok

end;

procedure signalone(var s: semaphore);

begin

! flag signal complete

if not empty(s) then s.outq := next(s.outq);

s.one := true ! set single waiters

end;

begin ! initializer block for signal

! set no signal active

s.inq := 0;

s.outq := 0

end.

The procedure escape exists in another module. Its only purpose is to break the monitor lock in signal, which is satisfied by exiting the module and returning. It could do more, for example it could make a system call to release the rest of its task time.

share other;

procedure escape;

begin

end;

The equivalence implements a fair locking scheme. Each of the waiters for a signal is placed in a first in, first out queue. For signalone, only the head task or first in receives the signal. For signal, all of the waiters in the queue receive the signal.

The difference between this equivalent implementation of semaphore, wait, signal and signalone is that the system specific implementation can arrange for only the prime entry waiting on a signal is scheduled to run. Thus, there is no polling and no wasted CPU time.

6.38 Channels

A channel is one step beyond a monitor. It does not allow any procedure or subroutine to appear as public, but instead only allows properties to be exposed publically. As with a monitor, the read and write blocks of an property are locked.

channel ticketbin;

property ticket: integer; forward;

private

const ticketmax = 100;

var ticketbin: array ticketmax of boolean;

ticketfree: semaphore;

i: 1..ticketmax;

property ticket: integer6;

var i, f: 0..ticketmax;

begin ! read

while notickets do wait(ticketfree); { wait if no tickets }

! find the free ticket

for i := 1 to ticketmax do if ticketbin[i] := false then f := I;

ticketbin[f] := true; ! allocate ticket

ticket := f ! place ticket

end;

begin ! write

ticketbin[ticket] := false;

signalone(ticketfree) ! signal one ticket was freed

end;

begin ! constructor

for i := 1 to 100 do ticketbin[i] := false

end;

Channels are a more advanced multitasking object than monitors because:

1. They don’t have or need the pointer passing restrictions of a monitor, since there are no parameter lists for procedures or functions.

2. The “client” and “server” of a channel can be implemented in different threads on the same processor, different shared memory processors, wholly separate processors, and even geographically separated processors connected by a network, without the overhead and problems of remote procedure calls. The server can even be implemented in hardware.

6.39 Classes

class-declaration = ('class' | ‘thread’| ‘atom’) identifier ' [ class-parameter-list ] ;' [ 'extends' class-name ';' ] block '.' .

class-parameter-list = ‘(‘ class-parameter { ‘;’ class-parameter } ‘)’ .

class-parameter = [ ‘view’ ] identifier-list ‘;’ type-idenifier .

class-name = qualified-identifier .

block = { declaration } [ 'private' { declaration } ] statement-part [ ';' statement-part ] .

Modules in Pascaline provide a way to package types, variables, procedures, functions and other definitions together as a unit to be used by other parts of the program. Classes extend this further by providing a general description of a module that the program can create any number of instances.

In the Pascaline model, modules are both a description of a class, and the only instance of it.

Classes fit in the program hierarchy between modules and procedures/functions:

Modules

\_/

Classes

\_/

Procedures/functions

The class is a collection of types, variables and procedures called "members", and it has per-instance data.

A class is declared by the word-symbol "class", and it can appear anywhere in the declarations of a global module such as a program or module, etc.

program p(input, output);

uses mylib;

class myclass;

label 1, 2;

type a = char;

var c, d: integer;

procedure x;

begin

end;

private

procedure y;

begin

{ optional constructor }

end;

begin

{ optional destructor }

end.

begin { program }

end.

When a procedure or function appears in a class, it is referred to as a method. A class can refer to any of the declarations in the surrounding module. The methods of a class can refer to both the variables inside the class as well as the variables in the module that surrounds it.

As a module can, a class can use the private word-symbol to specify declarations within the class that are private.

A class does not create any actual variables, procedures and functions when it is defined. A class is a template for an object. To create an “object” from a class, it must be instantiated, which means to give the class a complete set of locations in memory. If that memory is static, the instance is static. If the memory is allocated dynamically, the instance is dynamic.

6.39.1 Static objects

To create a static instance, the class is used to form a type as follows:

type si = instance of c;

Which can be used to form static instances of the class:

var z: si;

The class c is not itself a type, nor can it be used as such. si, however, is a type. To use a class as a type, the compiler must know if a static or dynamic instance is meant.

A static instance is static even if it is a local of a procedure or function, or instantiated within another class. An instance does not become dynamic unless it is allocated dynamically via new.

6.39.2 Dynamic objects

To create a dynamic instance, the class is used to form a type as follows:

type di = reference to c;

Which can be used to form a dynamic reference to objects of the class:

var z: di;

Where c is a class. This creates a special variable used to access the "object" that "instantiates" the class. The actual creation of the object is done by the standard procedures new and dispose:

new(z); { create new object, referred to by z }

dispose(z); { destroy existing object referred to by z }

The definitions for the object referenced by z can be accessed by the same notation as for a joins module:

z.c := 1; { assign value to object variable }

z.x; { call object procedure x }

A reference variable can point to any object defined with a compatible class. It can also point to no object at all:

z := nil;

Just as a pointer variable can. Further, two references can be compared, or assigned, just as pointers can:

program p;

class c;

begin

end.

var z, q: reference to c;

begin

z := nil; q := z;

if z = nil then { perform actions on nil }

if q = z then { perform actions on q = jejez }

end.

In fact, a reference behaves just as a pointer, but without the need to specify a dereference ("^"). Anytime a qualifier (".") follows a reference, it is understood that the object referenced is being accessed.

Just as for pointers, a reference can appear in a with statement:

program p;

class c;

begin

end.

var z: reference to c;

begin

with z do { statements }

end.

This effectively opens up the scope of the object within the code.

Notes:

1. References are treated as pointers with respect to monitors. A reference cannot be exported by a monitor routine.

6.39.3 Classes as parameters

When a class is passed as a parameter, its dynamic or static form is irrelevant to its parameter status. Only the var mode can be used on a class as a parameter. The type used for the parameter is the class itself.

program p;

class c;

var i: integer;

begin

end.

procedure x(var y: c);

begin

y.i := 1

end;

begin

with z do { statements }

end.

6.39.4 Class parameters

Classes accept parameters that are a subset of procedure and function parameters. Only value and view parameters are accepted in a class parameter list (with the exception of file parameters, which must always be var under ISO 7185 Pascal rules)[1].

program p(output)

class stringc(size: integer);

type string: packed array of char;

var data: ^string; ! string data buffer

len: integer; ! current length

operator := (d: stringc; view s: string);

var i: integer;

begin

if max(s) > size then begin ! string is larger than our buffer

dispose(data);

new(sdata, max(s));

size := max(s)

end;

for i := 1 to max(s) do d.sdata[i] := s[i];

d.len := max(s)

end;

procedure print;

begin

for i := 1 to len do write(sdata[i])

end;

begin ! constructor for string

new(sdata, size) ! allocate string data

len := 0 ! clear string

end;

begin ! destructor for string

dispose(sdata) ! release space for string data

end.

var mystring(100): instance of string;

begin

mystring := ‘hi there’;

mystring.print

end.

Class parameters are special in that they are specified when the object formed from the class template is instantiated. The class parameters are evaluated, and kept as long as the object exists. The constructor, the destructor, and all of the methods of the class can access the class parameters.

program p

class filelist(size: integer);

var filearray: array of text; ! array of text files

procedure open(i: integer);

begin

rewrite(filearray[i])

end;

begin ! constructor

new(filearray, size) ! allocate file array

end;

begin ! destructor

for i := 1 to size do close(filearray[i]);

dispose(filearray) ! release space for string data

end.

var files(100): instance of filelist;

i: integer;

begin

for i := 1 to 100 do files.open;

for i := 1 to 100 do write(files.filearray[i], i)

end.

Note that the actual parameter list for the class appears where it is instantiated. For static instances, this is the variable declaration for it. For dynamic instances, it is the new statement that creates the object.

Typically, class parameters perform a “geometry” change within the object. That is what makes a class parameter different from just applying a method to it after its constructor executes. A method could not specify the creation of the parameterized array filelist above. Class parameters have many uses, and be used to specify any class configuration parameter.

The parameters for the class appear after any parameters for array template geometries. This would occur if the object was part of a container array:

program p

class filelist(size: integer);

var filearray: array of text; ! array of text files

procedure open(i: integer);

begin

rewrite(filearray[i])

end;

begin ! constructor

new(filearray, size) ! allocate file array

end;

begin ! destructor

for i := 1 to size do close(filearray[i]);

dispose(filearray) ! release space for string data

end.

var files(10, 100): array of instance of filelist;

i, j: integer;

begin

for j := 1 to 10 do begin

for i := 1 to 100 do files[j].open;

for i := 1 to 100 do write(files[j].filearray[i], i)

end

end.

6.39.5 Inheritance

class-declaration = ('class' | ‘thread’ | ‘atom’ | ‘liaison’) identifier ' [ class-parameter-list ] ;' [ 'extends' class-name ';' ] block '.' .

expression = simple-expression [ relational-operator simple-expression ] .

relational-operator = '=' | '<> | '<' | '>' | '<=' | '>=' | 'in' | 'is' .

Classes can "inherit" the definitions contained in other classes:

program p;

class x;

begin

end.

class y;

extends x;

begin

end.

begin { program main block }

end.

The extends word-symbol is followed by the class that is inherited.

The meaning of this is that the new class receives all of the definitions present in the inherited class, and can then add its own. Objects have the special property that all references to a class are compatible with any class that is built by inheriting definitions from its reference class. Because class references can be freely assigned between compatible classes, this means that references are effectively compatible with the classes that it inherits, as well. This means that it is possible for some part of the definitions for a referenced class to be non-existent. Pascaline can detect and flag an error for an access to a missing definition in a referenced object either at compile time or runtime.

When a program needs to determine if the definitions it needs to access in an object exist can use a special expression operator:

program p;

class x;

begin

end.

class y;

extends x;

begin

end.

var yr: reference to x;

begin { program main block }

new(yr);

{ code to set up and process yr }

if yi is x then { access members of x inherited in y }

end.

The is operator is true if the referenced object either is the indicated class, or is a class that inherits from that class. In either case, it means that all of the definitions from the class defined as the base of the reference exist.

When a new member of a class is defined that has the same name as a member of the inherited class, the original member of the inherited class is “shadowed”, and becomes inaccessible in the derived class.

6.39.6 Overrides for objects

Just as static modules can, classes can override inherited procedures and functions.

program p;

class x;

virtual procedure y;

begin

end;

begin { constructor for x }

end.

class z;

extends x;

override procedure y;

begin

end;

begin { constructor for z }

end.

begin { main block for p }

end.

The main difference for the use of overrides with objects from the use of overrides with modules is that the instances of the original object keep their original procedures and functions, and only derived classes have the procedure or function replaced. Static modules have the original procedure or function replaced for all callers.

Just as for a module, the original definition of a procedure or function can be accessed by using the inherited word-symbol:

inherited y; { call the original definition of member procedure y }

Only one override can exist for the same method in an object. The inherited version of a method can only be accessed within the object where the override exists.

6.39.7 Self referencing

Within the code that makes up the object, its procedures, functions and start and exit blocks, referring to definitions within the object is done as for any module, dynamic or static. However, an object frequently needs to access the reference that defines access to it, as well. This is most common in the case where the object exists in a list of objects, and is done via the word-symbol self:

program p;

! General purpose list class

class list;

type ref = reference to list; ! reference to type

var next: ref; ! next item link in list

! Insert node to list at head

procedure insert(var root: ref);

begin

next := root; ! link this to next

root := self ! link root to this

end;

! Index next entry in list

procedure iterate;

begin

self := next ! go next entry

end;

! Remove node

procedure remove(var root: ref);

var lp: ref;

begin

if self = root then root := root.next ! gap from top

else begin

lp := root; ! index top of list

while lp.next <> self do lp.iterate; ! find last entry

lp.next := next ! gap from list

end;

next := nil ! clear link

end;

begin ! constructor

next := nil ! clear next link

end.

! list of integer data values

class dlist;

extends list; ! based on list class

type ref = reference to dlist; ! reference to type

var data: integer; ! data value

! Find a list entry by value

function find(value: integer): ref;

var lp: ref;

begin

lp := self; ! index here to search forward

if lp <> nil do begin ! the whole list is not nil

while (lp.data <> value) and (lp.next <> nil) do lp.iterate;

if lp.data <> value then lp := nil ! not found

end;

result lp ! resulting in found value or nil

end;

begin ! constructor

data := 0 ! clear data value

end.

var mylist, lp: dlist.ref; ! our data list

procedure newvalue(value: integer);

begin

new(lp);

data := value;

lp.insert(mylist)

end;

begin

! place some test values in a list

newvalue(123);

newvalue(42);

newvalue(1);

! Find an entry

lp := mylist.find(42);

! And remove it

lp.remove(root);

dispose(lp);

! print remaining list entries

writeln('The list contains:');

lp := mylist;

while not (lp = nil) do begin

writeln('Value: ', lp.data);

lp.iterate

end

end.

self stands in for the reference that the object being operated on is based from.

6.39.8 Constructors and destructors

If a constructor or constructor and destructor exists for a class, they are executed when the object is created by new, or at the start of the object’s defining block, and when the object is disposed of by dispose, or at the end of the object’s defining block. The constructor is executed on a new, and the destructor is executed on dispose. Just as for a static module, constructors give an opportunity to set up and tear down an object.

When an object has inherited classes, the derived class must specifically call the base class constructor. The derived class cannot access the members of the base class until its constructor is called:

program p;

class x(i: integer);

begin

end.

class y(c: char);

extends x;

begin

x(ord(c));

{ statements accessing members of x }

end.

var yi(‘a’): instance of y;

xi(42): instance of x;

begin { program main block }

end.

The constructor of a derived class is the only place such an explicit constructor call can take place. The base class is called specifically by name with the constructor parameter list. Outside of the derived class constructor, the base class parameter list is used as normal for classes.

The explicit call of base class constructors gives two important abilities:

1. It allows the derived class to set up the parameters it needs for the base class.

2. It allows the derived class to have a different list of parameters than the base class.

Only the constructors of base classes are called explicitly. The destructor is called automatically, in the reverse order of construction, when the object is disposed. When an object is torn down, the derived class has the ability to deactivate itself before the class it is based on is deactivated.

6.39.9 Operator overloads in classes

When an operator overload occurs in a class, it can use the general form to refer to the specific object at hand:

program p;

class complex;

type ci = instance of complex;

var r, i: real;

operator +(var lv, rv: ci);

begin

lv.r := lv.r+rv.r; ! add real part

lv.i := lv.i+rv.i ! add imaginary part

end;

begin ! initializer for complex

end.

begin ! program main block

end.

Pascaline allows a short form where the left side of the operator always is the class of the execution context:

program p;

class complex;

type ci = instance of complex;

var r, i: real;

operator +(var rv: ci);

begin

r := r+rv.r; ! add real part

i := i+rv.i ! add imaginary part

end;

begin ! initializer for complex

end.

begin ! program main block

end.

That is, the leftmost operand of the operator function parameters is left off. The result is that the left side of the operator is performed in the context of the object on the left. The result is just as if the present class was declared as the first parameter of the operator function. For unary functions + and -, no parameter is specified.

6.39.10Derivation vs. composition

Pascaline supports new classes formed from old classes by either derivation or composition. Derivation is a class that has another class as its base class. Composition is a class that includes an instance of the class:

program p;

class base;

var i: integer;

class composition;

var bi: instance of base;

var ci: instance of composition;

begin

ci.bi.i := 10

end.

Building classes by composition is a powerful technique, and sometimes is more appropriate than building classes by derivation. Multiple inherence in Pascaline is not possible using derived classes, but it can be done with composition.

6.39.11Parallel classes

Just as modules have different versions for parallel tasking, classes come in different forms to enable tasking. The following classes are the functional equivalents of the module types:

Module type	Class type
process	thread
monitor	atom
channel	liaison
share	<none>

A thread class has no visible members at all. Its constructor starts and is executed within a new thread. All members must be private:

program p;

uses mymonitor;

thread lighttask;

private

var a: integer;

begin ! constructor for lighttask

a := getdata;

putdata(a)

end.

begin ! main block

end.

A process module is limited to creating only a single parallel thread of execution within the program. The thread class can create an unlimited number of threads.

Unlike a process, a thread class can have a destructor. The destructor is executed in the context of the thread. At the end of the destructor, the thread is terminated.

thread classes can use either monitor modules, or can use a special form of class known as the atom:

program p;

atom fairlockc;

procedure get; forward;

procedure put; forward;

private

const maxque = 255; { maximum number of queued entries }

type queptr = 0..maxque;

var released: semaphore;

inp, outp: queptr;

procedure incptr(var p: queptr);

begin

if p < maxque then p := p+1 else p := 0

end;

procedure get;

var inps: 0..maxque;

begin

inps := inp; { save the current queue position }

incptr(inp); { advance the input pointer }

while inps <> outp do wait(released);

end;

procedure put;

begin

incptr(outp); { advance the output pointer }

signalone(released) { signal the release of the lock }

end;

begin

inp := 0; { clear input and output pointers }

outp := 0

end.

var lock: instance of fairlockc; ! create a lock

thread printtaskc;

private

begin { constructor for printtaskc }

while true do begin

lock.get; ! aquire lock to output

writeln(‘I am a thread’); ! print

lock.put ! release lock

end

end.

var t: instance of printtaskc;

begin { main block }

while true do begin

lock.get; ! aquire lock to output

writeln(‘I am the main program’); ! print

lock.put ! release lock

end

end.

Note: this program implements a “second order” parallel task lock to allow for the fact that prints of whole lines are not atomic in Pascaline. The action of the program is to alternately print whole lines from the main and the subthread.

An atom cannot have variables in its public section. It is “sealed” and must perform all of its actions via methods.

Each of the methods of an atom acquires a lock specific to the atom before performing its work. Semaphores and signals are available to an atom. Thus, it can serve as a go-between for thread classes, processes, and the main program.

A liaison goes further still than an atom, and allows only properties to be present in its interface section.

program p;

liason stringdictionary;

const bufmax = 100;

type cmdval = (none, writestring, readstring);

cmdrec = record

idlen: 1..bufmax;

idstr: packed array [1..bufmax];

strlen: 1..bufmax;

strdat: packed array [1..bufmax]

end;

property command: cmdval; forward;

property params: cmdrec; forward;

private

type string: packed array of char;

strptr: ^strrec;

strrec: record

next: strptr;

data: pstring ! data contained in string

end;

var strlst: strptr; ! list of current string entries

p: strptr; ! pointer to iterate list

cr: cmdrec; ! this is the class global copy of the params

! Compare strings with length

function strcmp(len: integer; var a, b: string): boolean;

var r: boolean;

begin

r := true; ! set default equal

if len <> max(b) then

r := false ! return false if lengths unequal

else for i := 1 to len do if a[i] <> b[i] then r := false;

result r ! return compare result

end;

! Operate the command interface

property command: commandval;

begin ! read definition

command := none ! read is a meaningless request here

end;

var i: 1..bufmax;

begin ! write definition

if command = writestring then begin ! write string request

new(p); ! get a new string entry

new(p^.name, cr.idlen); ! create identifier string

new(p^.data, cr.strlen); ! create data string

! copy name to string entry

for i := 1 to cr.idlen do p^.name[i] := idstr[i];

! copy data to a string

for i := 1 to cr.strlen do p^.data[i] := strdat[i];

p^.next := strlst; ! push to string list

strlst := p

end else if commandval = readstring then begin

! read string request

for i := 1 to bufmax do cr.idstr[i] := ‘ ‘; ! clear result

p := strlst; ! find string in list

while p <> nil do begin

if strcmp(cr.idlen, cr.idstr, p^.name) then begin

! found, copy data back to transfer record

cr.idlen := max(p^.name);

for i := 1 to max(p^.name) do cr.idstr[i] := p^.name[i]

end;

p := p^.next ! next string entry

end

end;

! operate the parameters

property params: cmdrec;

begin ! read definition

params := cr ! copy local definition to client

end;

begin ! write definition

cr := params ! copy client definition to local

end;

begin ! stringdictionary constructor

strlst := nil ! clear string list

end;

begin ! stringdictionary destructor

! dispose of string list

while strlst <> nil do begin

p := strlst; ! gap top entry from list

strlst := strlst^.next;

dispose(p^.name); ! dispose of string name

dispose(p^.data); ! dispose of string data

end

end.

var strdic: instance of stringdictionary; ! instantiate dictionary

cr: cmdrec; ! our copy of the parameter record

procedure putstr(var len: integer; var d, s: string);

begin

len := max(s); ! place length

for i := 1 to len do d[i] := s[i] ! copy string

end;

begin

! add a string to the dictionary

putstr(cr.idlen, cr.idstr, ‘userdata’);

putstr(cr.strlen, cr.strdat, ‘John H. Weston’);

strdic.params := cr; ! set up string data

strdic.command := writestring; ! write the string record

! find existing record

putstr(cr.idlen, cr.idstr, ‘userdata’);

strdic.params := cr; ! set up string data

strdic.command := readstring; ! write the string record

! now recovered data is in record, or is blank if none found

end.

In this example, named strings are transferred across an interface, possibly to a remote process or processor. The client program sets up a parameter record for the liaison based server and then commands the server to perform it.

The example illustrates many of the challenges of property based design. The liaison cannot export the definitions in the parameter record, and that property is even sealed from the other methods in the same liaison. That is why the only job of the params property is to export the read or written data to the liaison itself. The reward for enduring the difficulties of property based design is programs that can be modularized across multiple processors, perhaps in distant locations, and also the ability of Pascaline to unify accesses to software, servers, and low level hardware under a single model.

Notes:

1. The rule that accesses external to the property activate the read or write blocks of the property mean that other properties in the same surrounding block activate each other.

2. Because properties can be structured types, any amount of data can been arranged as a single property.

3. A structured property implies nothing about the accesses to its substructure. It is only meaningful as a whole structure assignment.

There is no class based version of a share module. Since a share module contains no variables, there would be no point to an instantiation of such a class.

G Annex G: System Services Library

Services contains common operating system related tasks, including directory access, time and date, files and paths, file attributes, environment strings, the local option character, and execution of external programs.

G.1 Filenames and Paths

A file specification is composed of a path, name and extension:

The exact format of a file specification changes with the operating system. The routine brknam takes a file specification and breaks it down into its path, name and extension components. The routine maknam does the opposite, creating a composite name from the three components. When a file specification has no path, it means that it refers to the default path. When a file specification needs to be printed or saved in an absolute format, with the path always specified, the fulnam routine is used to "normalize" the file specification by filling out the complete path.

To parse file specifications from the user, the routine filchar returns a character set of all possible characters in a filename. This can be used to get a sequence of characters from a string or file that can constitute a file specification. Once the potential file specification has been loaded into a string, it can be checked for validity as a file specification by validfile, and as a path by validpath.

Filenames are based on the idea that there is a set of characters that may be used for filenames in a particular installation, and the characters outside that set are used to delimit between filenames. This characteristic of filenames allows a program to load the filename into a string, then check it’s proper structure using subsequent calls. The program may remove certain characters from the set of filename characters to be able to parse command lines.

A common method used to represent filenames in command lines and other text when the characters allowed in a filename are essentially unlimited is to quote the filename. Using this method, the filename appears as:

“myfile”

‘myfile’

This can work together with limited character set filenames by recognizing the leading quote. If both types of quotes are allowed, then the leading quote should match the trailing quote. Additionally, the program should be able to recognize a “quote image” of the forms:

Character sequence	Result
“”	Double quote “
‘’	Single quote ‘
\”	Forced double quote “
\’	Force single quote ‘

A robust program would recognize all of these forms.

Note that services does not contain any method to parse filenames.

If a file specification contains wildcards, this can be determined by wild. services does not define what wildcards characters or specifiers are used, or their format. wild simply indicates that the filename contains a wildcard specification that may result in multiple files being indicated by the same file specification.

G.2 Predefined paths

To find common objects that a program needs, three predefined paths are provided:

Program path

Is the path that the program was executed from. This is used to find data that accompanied the program, and system wide option files. getpgm is used to read the path.

User Path

This is the path for the current user's home directory. This is used to store options that only apply to the current user. getusr is used to read the path.

Current Path

The default path is used to find options that apply only to the current file being worked on. Unlike the other path types, the current path can be both read and set. Setting the current path will set the default path used to finish incomplete file specifications. getcur is used to read the path, and setcur is used to set it.

Note that if the system has no concept of a current path, this property is used to form full path names from default path names in services.

G.3 Time and Date

Time is kept in two different formats in services. The first is seconds time, and the second is "clock" time. Seconds time is literally a count of the number of seconds since a fixed reference time. Clock time is a free running clock that ticks every 100 Microseconds.

Seconds time is returned by the time function. It is in a format called "S2000", and it is the number of seconds relative to midnight on the morning of January 1, year 2000. This means that S2000 has a negative value for years before 2000, and a positive value after that. S2000 time is dependent on the representation of an linteger. This results in the following limits according to bit size:

Bits	Farthest year into the past	Farthest year into the future
32	1932	2068
64	1608591645726	1608591649726

Note that these times don’t account for leap years, which are less than a year of error in 32 bits in any case. 16 bits cannot reasonably be used to represent a time, since the seconds in a year exceed the format.

This represents a reasonable range of time for 32 bits, and by the year 2068 it is likely that the time will universally be 64 bits or better. Note that it does not matter how many bits are returned by time, so that transition will occur seamlessly. Because 64 bits is already in excess of what is needed for computer based timekeeping, it is likely that time in 64 or more bits will actually contain fewer bits, despite the linteger representation.

S2000 is self-relative, meaning that times relative to the year 2000 are measured by a fixed number of seconds. S2000 only matched UTC time once, exactly at midnight on the morning of January 1, year 2000. All times after that or before that or after that are increasingly diverge from UTC. In particular, this means that the current time and date will not match current UTC.

There are two types of calculations that can be applied to UTC, fixed and dynamic. The fixed calculation typically finds UTC by applying leap year corrections, then a fixed table of leap second years. The fixed calculation will fall out of accuracy from the time that the system is released. It is impossible for it to be otherwise, since UTC is based on astronomical observation.

The dynamic calculation relies on receiving a current table of corrections from the network or other communications method. This is typically the same calculation as fixed time, but with a continually updated table of leap seconds.

When an S2000 time is not available, it is customary to set it to -maxlint, which makes it clear that the time was not set.

The time returned by time is in GMT or "universal" time. To convert to local time, the function local is used. It takes the given GMT S2000 time, and offsets it by the local time zone offset, and by daylight savings time, and returns the adjusted local time.

The time can be placed, in character format, to a string by times, and written to either an output file, or the standard output file by writetime. The date can be placed, in character format, to a string by dates, and written to either an output file, or the standard output by writedate. These procedures format the time and date using the current internationalization settings of the host.

clock time is typically derived from a free running counter kept in the host computer, and it is represented by lcardinal values. It may or may not be synchronized to the values returned by time. For this reason, clock should be treated as self-relative and not compared to time in any way.

clock time is treated differently from time. Since it free runs, you must be prepared for it to "wrap", or suddenly start counting up from zero. This can be determined by if any stored time is greater, or later in time, than the current clock value. The function elapsed takes a reference time, and determines how much time has passed from that, including compensation for wraparound. The exact count at which the clock count wraps is system dependent.

The total amount of time that can be represented with clock is determined not only by the bit size of the clock return value, but also by the size of the counter the host computer maintains. All that is guaranteed is that clock will be able to keep a unique time for at least 24 hours.

The actual increment of time for each tick of the clock is determined by the host computer. If the host cannot time to 100 microsecond accuracy, then the clock time will increment in multiples > 1, or effectively a running approximation of the actual timer. For this reason, there may not be an exact time length between successive counts of the timer.

G.4 Directory Structures

The list procedure takes a file specification, including wildcards, and returns a linked list of all of the matching directory entries:

{ attributes }

attribute = (atexec, { is an executable file type }

atarc, { has been archived since last modification }

atsys, { is a system special file }

atdir, { is a directory special file }

atloop); { contains heriarchy loop }

attrset = set of attribute; { attributes in a set }

{ permissions }

permission = (pmread, { may be read }

pmwrite, { may be written }

pmexec, { may be executed }

pmdel, { may be deleted }

pmvis, { may be seen in directory listings }

pmcopy, { may be copied }

pmren); { may be renamed/moved }

permset = set of permission; { permissions in a set }

{ standard directory format }

filptr = ^filrec; { pointer to file records }

filrec = record

size: lcardinal; { size of file }

alloc: lcardinal; { allocation of file }

attr: attrset; { attributes }

create: linteger; { time of creation }

modify: linteger; { time of last modification }

access: linteger; { time of last access }

backup: linteger; { time of last backup }

user: permset; { user permissions }

group: permset; { group permissions }

other: permset; { other permissions }

next: filptr { next entry in list }

end;

Each directory file entry has the name of the file, along with a series of descriptive data for the file. These are divided into attributes and permissions. An attribute is a characteristic of the file, and generally does not change. Permissions indicate what can be done with the file, and are divided into the user, group and other permissions.

Not all attributes nor all permissions are available on every operating system. If a particular permission or attribute is not implemented on a given operating system, then setting it will have no effect, and reading it will always return unset.

The size of the file is its size in bytes. The allocation is the total space it occupies on the storage medium, which may be different from its size for several reasons. The blocking may be such that the size is rounded up to the nearest block. The operating system may have the ability to reserve space for the file beyond what it is currently using, or may not release space back to the free space pool if the file is truncated.

The times of interesting events in the files life are available, in "S2000" format (already discussed). If a particular time is not available, then it is set to -maxlint.

The file structure is a collection of items that may be implemented on any given operating system. The way to prevent the need to decide what is and what is not implemented on a particular system is to focus on what is essential for all systems. For example, the size of a file is usually present, as well as the last modification time. The last modification time can be used to determine when to back up files, by comparing it to the date of the backup copy of the same file, or to the modification date of the archive containing the file. Similarly, a "make" style program can determine when to remake a file by looking at the modification time.

G.5 File Attributes and Permissions

The attributes of a file can be set by name with the setatr command. It takes a set of attributes and the filename, and sets all the given attributes on the file. The routine resatr resets attributes. The user permissions for a file are set and reset by setuper and resuper. The group permissions are set and reset by setgper and resgper. The other permissions for a file are set and reset by setoper and resoper.

G.6 Environment Strings

The environment is a collection of strings that is kept by the executive, and passed to programs when they are started. Each string has a name and a value, both of which are arbitrary strings. An environment string can be retrieved by name by getenv, and set by setenv. The entire environment string set can be retrieved at one time by the allenv routine, which uses a linked list to represent the environment strings:

{ environment strings }

envptr = ^envrec; { pointer to environment record }

envrec = packed record

data: pstring; { data in string }

next: envptr { next entry in list }

end;

The standard format for environment string names is the same for Pascaline identifiers, i.e., a character in the sequence 'A'..'Z', 'a'..'z', '_', followed by any number of characters in the sequence 'A'..'Z', 'a'..'z', '_', '0'..'9'. The data in the string can be a series of any valid characters.

The reason for retrieving the entire environment is to pass it on to other programs in an exec statement.

Although most available operating systems implement the environment string concept, it has fallen out of favor in modern programs. Placing the needed configuration strings for a particular program into a place where the executive will use it both requires special calls, and places individual program data into a pool where it can be deleted or corrupted.

Some current systems use a repository concept where program data is kept in a central tree structured database. This is not covered in services, and would be covered in another library.

A better method is to use a file containing the configuration information for the program in its startup directory, then optionally another version in the user directory, and finally one in the current directory. This allows options that affect all runs on the current machine to be kept in one file, while the options for a particular user are kept in another file, and lastly the options in use in the current project in the current directory. This system has the advantage that it addresses concerns in a multiuser operating system, and allows each program to maintain its own startup data.

For systems that do not implement an environment string capability, implementations of Pascaline commonly keep a file in the user path area that contains the strings. This is then used just for that program, that is, the set of environment strings are kept just for the accessing program.

G.7 Executing Other Programs

An external program can be executed by exec, which takes the command line for the program, including the program name, and all of its parameters and other options on the same line after one or more spaces:

cmd parameter parameter... parameter

This is passed as a string to the exec routine. When programs are executed this way, the executing program does not need to await the finish of the program, nor can it find out if the program ran correctly. If this is required, the routine execw is used. execw will wait for the program to complete, then place the error return for the program in a variable. This variable will be 0 if the program ran correctly, or non-zero if it didn't. The exact numerical meaning of the error is up to the program executed.

If the system cannot execute programs in parallel, exec is equivalent to execw, but without the return code.

If the environment is to be set for the executed program, the call exece can be used, which takes an environment list. This allows the environment to be retrieved from the current environment or created as new, modified or added to as needed, then passed to the executed program. execew does the same thing, but waits for the program to finish, and returns an error code.

If a command line concept does not exist on the target system, an implementation can pass it via another means, such as a file or environmental variable. Alternately, it could simply be ignored.

G.8 Error Return Code

Each program, when it completes, returns an error code. By convention, if the error code is 0, then no error occurred. If the code is not 0, then an error occurred, and the meaning of the number is defined by the application.

When a program under Pascaline exits, it returns a code that was set to 0 by default when the program started. The procedure seterr can be used to set a non-zero code, which will be returned when the program exits. Note that it does not cause the current program to exit, it simply sets the code that will be returned when it does. It does not matter how the program exits, from the main program block, or a halt statement or exception.

G.9 Creating or Removing Paths

A file path, or directory, is created by makpth, and removed by rempth. If the directory has files in it, then it cannot be removed until all the files (and directories) under it have been removed. This means by implication that each section of a path must be removed separately, and a tree structured delete would have to repeatedly remove the contents of one element of the path, then remove the path section itself, and so on.

G.10 Option Character

When parsing commands, the option character for the current operating system is found with optchr. Services does not define the exact format of command line options. The option character is an aid to portability.

G.11 Path Character

The path character is used to separate path components, usually directories in a tree structured file system, within a path for the given system. It can be found with the pthchr function. services does not define the contents, structure or meaning of a path. The path division character is an aid to portability.

G.12 Location

The functions latitude and longitude exist to give the location of the host computer in geographic coordinates, and return integers. The measurements are ratioed to maxint.

The longitude is 0 at the Prime Meridian, a line passing thought Greenwich, UK. The longitudes 0 to maxint are east of the line (or in the future timewise), and longitudes 0 to –maxint are west of the line. Thus maxint and –maxint meet on the opposite side of the world from Greenwich. This means for a 32 bit integer that there is 0.0000000838190317 degrees for each step or 9.3306920025 millimeters per step.

The latitude is 0 at the equator and maxint at the north pole, and –maxint at the south pole.

The longitude and latitude in minutes and seconds can be found with:

program location;

var degrees_longitude: integer;

minutes_longitude: integer;

second_longitude: integer;

degrees_latitude: integer;

minutes_latitude: integer;

seconds_latitude: integer;

west: boolean;

north: boolean;

begin

degrees_longitude := round(longitude * 0.0000000838190317);

minutes_longitude := round(xlongitude mod

11930465/198841.078518519);

seconds_longitude := round(longitude mod

198841/3314,0179753086400000);

if degrees< 0 then west := true else west := false;

degrees_latitude := round(longitude *

0.0000000838190317);

minutes_latitude := round(longitude mod

11930465/198841.078518519);

seconds_latitude := round(longitude mod

198841/3314,0179753086400000);

if degrees_latitude < 0 then north := false else north := true

end.

[need to correct this for ellipsoid]

The shape of the world is approximated as an ellipsoid. This means that the circumference of the earth at the equator is a longer distance than the circumference of the earth on the prime meridian (by about 68 kilometers).

The altitude of the host in MSL or Mean Sea Level is given by altitude. It is 0 for the mean surface of the ocean (sea level averaged over a long period of time), and maxint at 100 kilometers in height (the altitude at which space begins). It is –maxint 100 kilometers in depth.

The altitude of 0 (MSL) is typically defined as height above a model of the geoid, or idealized model of the earth. This means it would have to be calculated against the latitude and longitude to find the actual distance from true center of the earth. However, in the majority of cases it can be accepted as a relative measurement.

The location of the host can be entered by the user or determined automatically by instrumentation (GPS). The host could even be mobile, in which case it is possible to determine speed and direction from the coordinates against time.

If there is no location, it is indicated by longitude equal to –maxint. This value of longitude is redundant to maxint. Both longitude and latitude are considered unavailable by the value of longitude.

Altitude is available separate from longitude and latitude. It is not available when altitude is –maxint.

The country of location is found with country, which gives a string corresponding to the English name of the country. At this writing, the following countries exist, in alphabetical order:

#	Name	#	Name	#	Name	#	Name
1	Afghanistan	4	Dhekelia	131	Kyrgyzstan	196	Saint Kitts and Nevis
2	Aland Islands	248	Djibouti	132	Laos	197	Saint Lucia
3	Albania	8	Dominica	133	Latvia	198	Saint Pierre and Miquelon
4	Algeria	12	Dominican Republic	134	Lebanon	199	Saint Vincent and the Grenadines
5	American Samoa	16	Ecuador	135	Lesotho	200	Samoa
6	Andorra	20	Egypt	136	Liberia	201	San Marino
7	Angola	24	El Salvador	137	Libya	202	Sao Tome and Principe
8	Anguilla	660	Equatorial Guinea	138	Liechtenstein	203	Saudi Arabia
9	Antarctica	10	Eritrea	139	Lithuania	204	Senegal
10	Antigua and Barbuda	28	Estonia	140	Luxembourg	205	Serbia and Montenegro
11	Argentina	32	Ethiopia	141	Macau	206	Seychelles
12	Armenia	51	Europa Island	142	Macedonia	207	Sierra Leone
13	Aruba	533	Falkland Islands (Islas Malvinas)	143	Madagascar	208	Singapore
14			Faroe Islands	144	Malawi	209	Slovakia
15	Australia	36	Fiji	145	Malaysia	210	Slovenia
16	Austria	40	Finland	146	Maldives	211	Solomon Islands
17	Azerbaijan	31	France	147	Mali	212	Somalia
18	Bahamas, The	44	French Guiana	148	Malta	213	South Africa
19	Bahrain	48	French Polynesia	149	Marshall Islands	214	South Georgia and the South Sandwich Islands
20	Bangladesh	85	French Southern and Antarctic Lands	150	Martinique	215	Spain
21	Barbados	86	Gabon	151	Mauritania	216	Spratly Islands
22	Bassas da India	87	Gambia, The	152	Mauritius	217	Sri Lanka
23	Belarus	88	Gaza Strip	153	Mayotte	218	Sudan
24	Belgium	89	Georgia	154	Mexico	219	Suriname
25	Belize	90	Germany	155	Micronesia, Federated States of	220	Svalbard
26	Benin	91	Ghana	156	Moldova	221	Swaziland
27	Bermuda	92	Gibraltar	157	Monaco	222	Sweden
28	Bhutan	93	Glorioso Islands	158	Mongolia	223	Switzerland
29	Bolivia	94	Greece	159	Montserrat	224	Syria
30	Bosnia and Herzegovina	95	Greenland	160	Morocco	225	Taiwan
31	Botswana	96	Grenada	161	Mozambique	226	Tajikistan
32	Bouvet Island	97	Guadeloupe	162	Namibia	227	Tanzania
33	Brazil	98	Guam	163	Nauru	228	Thailand
34	British Indian Ocean Territory	99	Guatemala	164	Navassa Island	229	Timor-Leste
35	British Virgin Islands	100	Guernsey	165	Nepal	230	Togo
36	Brunei	101	Guinea	166	Netherlands	231	Tokelau
37	Bulgaria	102	Guinea-Bissau	167	Netherlands Antilles	232	Tonga
38	Burkina Faso	103	Guyana	168	New Caledonia	233	Trinidad and Tobago
39	Burma	104	Haiti	169	New Zealand	234	Tromelin Island
40	Burundi	105	Heard Island and McDonald Islands	170	Nicaragua	235	Tunisia
41	Cambodia	106	Holy See (Vatican City)	171	Niger	236	Turkey
42	Cameroon	107	Honduras	172	Nigeria	237	Turkmenistan
43	Canada	108	Hong Kong	173	Niue	238	Turks and Caicos Islands
44	Cape Verde	109	Hungary	174	Norfolk Island	239	Tuvalu
45	Cayman Islands	110	Iceland	175	Northern Mariana Islands	240	Uganda
46	Central African Republic	111	India	176	Norway	241	Ukraine
47	Chad	112	Indonesia	177	Oman	242	United Arab Emirates
48	Chile	113	Iran	178	Pakistan	243	United Kingdom
49	China	114	Iraq	179	Palau	244	United States
50	Christmas Island	115	Ireland	180	Panama	245	Uruguay
51	Clipperton Island	116	Isle of Man	181	Papua New Guinea	246	Uzbekistan
52	Cocos (Keeling) Islands	117	Israel	182	Paracel Islands	247	Vanuatu
53	Colombia	118	Italy	183	Paraguay	248	Venezuela
54	Comoros	119	Jamaica	184	Peru	249	Vietnam
55	Congo, Democratic Republic of the	120	Jan Mayen	185	Philippines	250	Virgin Islands
56	Congo, Republic of the	121	Japan	186	Pitcairn Islands	251	Wake Island
57	Cook Islands	122	Jersey	187	Poland	252	Wallis and Futuna
58	Coral Sea Islands	123	Jordan	188	Portugal	253	West Bank
59	Costa Rica	124	Juan de Nova Island	189	Puerto Rico	254	Western Sahara
60	Cote d'Ivoire	125	Kazakhstan	190	Qatar	255	Yemen
61	Croatia	126	Kenya	191	Reunion	256	Zambia
62	Cuba	127	Kiribati	192	Romania	257	Zimbabwe
63	Cyprus	128	Korea, North	193	Russia
64	Czech Republic	129	Korea, South	194	Rwanda
65	Denmark	130	Kuwait	195	Saint Helena

If the country is not set, an empty string (not a nil string) is returned.

The ordinal number of the country is given by countryord, which returns the number of the language from the table above. These ordinal numbers are given by the standard ISO 3166-1.

The current time zone, is given by timezone. It gives hours in the range of -12 to +14, which indicate the offset in hours from GMT or Greenwich Mean Time. The function daylightsav is true if daylight savings is in effect in the current host location.

If 24 hour time is used in the current host location, the function time24hour will return true, otherwise false. The accepted format for 24 hour time is with hours from 0 to 23.

Both the current time zone and daylight savings time are factored into the calculation of local, and that is the preferred method to find local time.

G.13 Internationalization

The current language in use on the host count be found with language, which gives a string corresponding to the English name of the language. The languages used are according to the ISO 639-1 standard:

#	Name	#	Name	#	Name	#	Name
1	Afan	36	French	71	Lithuanian	106	Siswati
2	Abkhazian	37	Frisian	72	Macedonian	107	Slovak
3	Afar	38	Galician	73	Malagasy	108	Slovenian
4	Afrikaans	39	Georgian	74	Malay	109	Somali
5	Albanian	40	German	75	Malayalam	110	Spanish
6	Amharic	41	Greek	76	Maltese	111	Sudanese
7	Arabic	42	Greenlandic	77	Maori	112	Swahili
8	Armenian	43	Guarani	78	Marathi	113	Swedish
9	Assamese	44	Gujarati	79	Moldavian	114	Tagalog
0	Aymara	45	Hausa	80	Mongolian	115	Tajik
11	Azerbaijani	46	Hebrew	81	Nauru	116	Tamil
12	Bashkir	47	Hindi	82	Nepali	117	Tatar
13	Basque	48	Hungarian	83	Norwegian	118	Tegulu
14	Bengali	49	Icelandic	84	Occitan	119	Thai
15	Bhutani	50	Indonesian	85	Oriya	120	Tibetan
16	Bihari	51	Interlingua	86	Pashto	121	Tigrinya
17	Bislama	52	Interlingue	87	Persian	122	Tonga
18	Breton	53	Inupiak	88	Polish	123	Tsonga
19	Bulgarian	54	Inuktitut	89	Portuguese	124	Turkish
20	Burmese	55	Irish	90	Punjabi	125	Turkmen
21	Byelorussian	56	Italian	91	Quechua	126	Twi
22	Cambodian	57	Japanese	92	Rhaeto-Romance	127	Uigur
23	Catalan	58	Javanese	93	Romanian	128	Ukrainian
24	Chinese	59	Kannada	94	Russian	129	Urdu
25	Corsican	60	Kashmiri	95	Samoan	130	Uzbek
26	Croatian	61	Kazakh	96	Sangro	131	Vietnamese
27	Czech	62	Kinyarwanda	97	Sanskrit	132	Volapuk
28	Danish	63	Kirghiz	98	ScotsGaelic	133	Welch
29	Dutch	64	Kirundi	99	Serbian	134	Wolof
30	English	65	Korean	100	Serbo-Croatian	135	Xhosa
31	Esperanto	66	Kurdish	101	Sesotho	136	Yiddish
32	Estonian	67	Laothian	102	Setswana	137	Yoruba
33	Faeroese	68	Latin	103	Shona	138	Zhuang
34	Fiji	69	Latvian	104	Sindhi	139	Zulu
35	Finnish	70	Lingala	105	Singhalese

The ordinal number of the language is given by languageord, which returns the number of the language from the table above. Note that even if the languages are added to or subtracted to in future implementations, the ordinal numbers will not be changed, simply extended at the end, with any removed entries set to an empty string.

The decimal point character in use can be found with decimal. The current number separator in use is defined with numberseparator.

The time and date formats can be derived the country of the host. The main difference between formats is the order of the elements in time and date. The functions timeorder and dateorder give the ordering:

dateorder Code	Date format
1	year-month-day (ISO 8601 standard format)
2	year-day-month
3	month-day-year
4	month-year-day
5	day-month-year
6	day-year-month

timeorder Code	Time format
1	Hour:minute:second (ISO 8601 standard format.
2	Hour:second:minute
3	Minute:hour:second
4	Minute:second:hour
5	Second:hour:minute
6	Second:minute:hour

The separator character for fields in the date is given by dateseparator, which is ‘-‘ in ISO 8601 date formats. The separator character for fields in time is given by timeseparator, which is ‘:’ in ISO 8601 time formats.

The number of digits in each section of the time and date formats is:

Section	Digits
Year	4
Month	2
Day	2
Hour	2
Minute	2
Second	2

If the time and date format is not set, it defaults to the ISO 8601 standard for time and date formatting. This is the correct format for output that can be read across international boundaries.

Note that the procedures times, dates, writetime and writedate automatically use the internationalization settings of the host to arrive at the host computers natural time and date formatting.

The symbol for the currency used in the country of host is given by currencychr.

G.14 Exceptions

The following exceptions are generated in services:

Identifier	Meaning
NameTooLong	The filename passed was too long for a services internal buffer.
FileSizeTooLarge	The file(s) being processed were too large.
StringNil	The string passed was nil.
StringTooSmallForTime	The string result buffer was too small to hold the time.
StringTooSmallForDate	The string result buffer was too small to hold the date.
EnvironmentStringTooLarge	A system environment string was too large for a services buffer.
CommandStringEmpty	The command string passed was empty.
ProgramNotFound	External program not found.
CurrentPathTooLong	Current path is too long for a services buffer.
FilenameStringEmpty	The filename passed was empty.
CannotDetermineProgramPath	The program path could not be determined.

Services establishes a series of exception handlers for each of the above exceptions during startup. Exceptions not handled by a client program of services will go back to services, then print a message specific to the error, then the general exception will be thrown.

Not all procedures and functions throw all exceptions. See each procedure or function description for a list of exceptions thrown. A client of services need only capture the exceptions occurring in the procedure or function that is called.

G.15 Functions and procedures in services

For all of the following calls, where an output file is used, it can be left off. The result is to default to the standard output file.

procedure list(fn: [p]string; var l: filptr);

Form a file list from the filename fn, and return in the file entry list l. The filename fn may contain wildcards, and may be fully pathed, or refer to the current directory. If no files are found, then the list pointer is returned nil.

Exceptions: FileSizeTooLarge, StringNil

procedure times(var s: string; t: linteger);

function times(t: linteger): pstring;

Place time from S2000 time t in string s.

Exceptions: StringTooSmallForTime

procedure dates(var s: string; t: linteger);

function dates(t: linteger): pstring;

Place date from S2000 time t in string s.

Exceptions: StringTooSmallForDate

procedure writetime([var f: text;] t: linteger);

Write time from S2000 time t to text file f, or by default, the standard output file.

Exceptions: None

procedure writedate([var f: text;] t: linteger);

Write date from S2000 time t to text file f, or by default, the standard output file.

Exceptions: None

function time: linteger;

Returns current S2000 time in GMT

Exceptions: None

function local(t: linteger): linteger;

Converts the given GMT S2000 time t to local time, using the time zone offset and daylight savings status in the host computer, and returns the result.

Exceptions: None

function clock: lcardinal;

Returns 100 microsecond, free running time.

Exceptions: None

function elapsed(r: lcardinal): lcardinal;

Given a stored clock time r, will check the current clock time and find the total number of 100 microsecond ticks since the given time, then return that. Accounts for timer wraparound.

Exceptions: None

function validfile(s: [p]string): boolean;

Parses and checks the file specification s for a valid filename on the current system. Returns true if valid.

Exceptions: StringNil

function validpath(s: [p]string): boolean;

Parses and checks the file specification s for a valid path on the current system. Returns true if valid, otherwise false.

Exceptions: StringNil

function wild(s: [p]string): boolean;

Checks if the file specification s contains wildcards. Returns true if so, otherwise false.

Exceptions: StringNil

procedure getenv(ls: string; var ds: string);

function getenv(ls: string): pstring;

Finds and returns an environment string. ls contains the name of the string to look up, ds or the return value contains the resulting string as found. If there is no environment string by that name, the return is either all blanks, or nil.

Exceptions: EnvironmentStringTooLarge

procedure setenv(sn: [p]string; sd: [p]string);

Finds and sets an environment string. sn contains the string name to set, and sd contains the contents to set it to. If there is no string by that name, it is created, otherwise the old string is replaced.

Exceptions: StringNil

procedure allenv(var el: envptr);

Returns a complete list of the strings in the environment to el.

Exceptions: None

procedure remenv(sn: [p]string);

Remove a string sn from the environment. The string is found by name, and removed from the environment. No error results if the string does not exist.

Exceptions: StringNil

procedure exec(cmd: [p]string);

Execute external program, with parameters, from the string cmd. Does not wait for the program to finish, and cannot detect if it finished with an error.

Exceptions: CommandStringEmpty, ProgramNotFound, StringNil

procedure exece(cmd: [p]string; el: envptr);

Execute external program, with parameters from the string cmd and full environment. The environment is passed as a list in el. Does not wait for the program to finish, and cannot detect if it finished with an error.

Exceptions: CommandStringEmpty, ProgramNotFound, StringNil

procedure execw(cmd: [p]string; var e: integer);

Execute external program, with parameters from the string cmd. Waits for the program to finish, and returns its error code in e. The error code is 0 for no error, otherwise the error is a code specified by the program executed.

Exceptions: CommandStringEmpty, ProgramNotFound, StringNil

procedure execew(cmd: [p]string; el: envptr; var e: integer);

Execute external program, with parameters from the string cmd and full environment. The environment is passed as a list in el. Waits for the program to finish, and returns its error code in e. The error code is 0 for no error, otherwise the error is a code specified by the program executed.

Exceptions: CommandStringEmpty, ProgramNotFound, StringNil

procedure getcur(var fn: string);

function getcur: pstring;

Get current path to fn or the result. Returns the current directory path.

Exceptions: CurrentPathTooLong

procedure setcur(fn: [p]string);

Set current path from string fn. Sets the default path for all file specifications.

Exceptions: StringNil

procedure getpgm(var s: string);

function getpgm: pstring;

Get the program path to s or returns it. Returns the program path, which is the path the program running was loaded from.

Exceptions: CannotDetermineProgramPath

procedure getusr(var fn: string);

function getusr: pstring;

Get user path to fn or returns it. Return the user path, which is a path specific to each user.

Exceptions: None

procedure brknam(fn: [p]string; var p, n, e: [p]string);

Break down file specification. Breaks the file specification fn down into path p, name n, and extension e. Note that any one of the resulting components could be blank, if it does not exist in the name.

Exceptions: FilenameStringEmpty, StringNil

procedure maknam(var fn: string; view p, n, e: string);

function maknam(p: [p]string; n: [p]string; e: [p]string): pstring;

Create file specification from components. Creates file specification fn from path p, name n, and extension e. Components may be blank, but the path and the name cannot both be blank.

Exceptions: NameTooLong, StringNil

procedure fulnam(var fn: string);

function fulnam(fn: string): pstring;

Create full file specification from a partial file specification fn. Given a file specification with an incomplete path (either by using the default path, or mnemonic shortcuts for things like parent directory), creates a fully pathed name of standard form. This can "normalize" file specifications, for comparisons, and to store the complete path for the file. The fully pathed result is returned in fn or as the function result.

Exceptions: None

procedure setatr(fn: [p]string; a: attrset);

Set attributes. Given a file by name fn, the attributes in the set a are set true for the file.

Exceptions: StringNil

procedure resatr(fn: [p]string; a: attrset);

Reset attributes. Given a file by name fn, the attributes in the set a are set false for the file.

Exceptions: StringNil

procedure bakupd(fn: [p]string);

Set backup time current. Given a file by name fn, sets the backup time for the file as current. Backup programs should also reset the archive bit to show that backup has occurred.

Exceptions: StringNil

procedure setuper(fn: [p]string; p: permset);

Set user permissions. Given a file by name fn, the permissions in the set p are set true for the file.

Exceptions: StringNil

procedure resuper(fn: [p]string; p: permset);

Reset user permissions. Given a file by name fn, the permissions in the set p are set false for the file.

Exceptions: StringNil

procedure setgper(fn: [p]string; p: permset);

Set group permissions. Given a file by name fn, the permissions in the set p are set true for the file.

Exceptions: StringNil

procedure resgper(fn: [p]string; p: permset);

Reset group permissions. Given a file by name fn, the permissions in the set p are set false for the file.

Exceptions: StringNil

procedure setoper(fn: [p]string; p: permset);

Set other permissions. Given a file by name fn, the permissions in the set p are set true for the file.

Exceptions: StringNil

procedure resoper(fn: [p]string; p: permset);

Reset group permissions. Given a file by name fn, the permissions in the set p are set false for the file.

Exceptions: StringNil

procedure seterr(e: integer);

Set program return error e. The error code returned by the current program is set. This has no effect until the program exits.

Exceptions: None

procedure makpth(fn: [p]string);

Make path using fn. Creates a new path or directory. If the path already exists, it's an error.

Exceptions: StringNil

procedure rempth(fn: [p]string);

Remove path fn. Removes a path, or directory. The directory must exist, and must be empty of any files or other directories, or an error results.

Exceptions: StringNil

procedure filchr(var fc: chrset);

Returns the set of valid filename characters in fc.

Exceptions: None

function optchr: char;

Find the option character. Returns the character that is used to introduce options in command liens on the current system.

Exceptions: None

function pthchr: char;

Returns the character used to separate components in a path in the current system.

Exceptions: None

J Annex J: Terminal Interface Library

Standard ISO 7185 Pascal uses an I/O paradigm that is serial, or more correctly "line oriented". Each line is built up in sections, then output to the I/O device with an appended "end of line". The end of line causes the current line to be completed, and the next line begins.

The next level of paradigm is the presentation of lines onto a 2d text surface. This can simply be an emulation of the serial only system or “virtual paper” using a screen that scrolls up from the bottom. The next step is to allow full addressing of the 2d surface and allowing text to be placed anywhere within that surface. To this is added colors, different text presentation modes, and finally advanced, multiple device input.

terminal starts in ISO 7185 Pascal compatible mode, then allows the program to move to a full addressable surface without automatic scrolling. In advanced mode, terminal emulates an infinite virtual surface where the terminal exists as a window clipped to the origin. This is the most consistent model of such a surface.

Because terminal overrides the interface between the program and the operating system it runs on, all of the ISO 7185 Pascal defined serial I/O works compatibly to the terminal presented surface. It is also modal, meaning that changes to character modes affect all further output to the terminal.

terminal introduces the concept that several devices can be used for input at the same time. The normal user keyboard is supplemented by a mouse, timers and a joystick. These are all implemented via the event concept, which unifies the input and removes the need to poll multiple devices.

terminal gives a set of logical events for common control keys from the keyboard that allow the program to avoid direct recognition of implementation dependent key codes.

In addition to the default presentation surface, terminal is capable of switching between multiple display surfaces. This capability has several uses.

J.1 ISO 7185 Pascal Compatible Mode

To write data to the terminal screen, ISO 7185 Pascal write calls are used. A write statement places each character on the screen, then moves the cursor to the right, obeying any automatic line wrapping. If a writeln is called, then the cursor is returned to the left side of the screen, one line down. If the end of the line is reached, and automatic scrolling is enabled, then the screen will scroll upwards.

The page procedure, which causes a printer to move to the next (blank) page, is emulated by waiting for the user to acknowledge the contents of the screen, then the screen is cleared and the cursor moves to the upper left hand position (1,1).

J.2 Basic Cursor Positioning

The cursor is the point where text is entered onto the screen. It’s usually marked with a blinking block or underline. To move the cursor one character up, down, left or right, the up, down, left and right procedures are used. To move the cursor anywhere on the screen, the cursor call is used. To find out where the cursor currently is, the functions curx and cury return the current x and y coordinates of it.

The character cells on the screen are labeled from 1 to N, where in x 1 is the left side of the screen, and N is the right side of the screen. In y 1 is the top of the screen, and N is the bottom of the screen.

The actual size of the screen is system specific, and can be found by maxx and maxy, which return the maximum index in x and y for the screen. When a terminal is emulated in a windowing system, it usually by default 25 lines of 80 characters each, because that was a very common size in terminals.

The cursor can be moved to the home, or 1,1 position, by the home procedure. The entire display can be cleared with the cursor moved to the home position by the clear procedure.

J.3 Automatic Mode

Automatic mode is the mode that causes terminal to scroll upwards when the bottom of the screen is reached, and an eoln is written. Line wrap, or the wrapping of characters back to the left at the next line if text is written off the right hand side, is an automatic mode. The automatic mode is useful for emulating ISO 7185 Pascal serial mode programs, but rapidly gets in the way for advanced programs.

Automatic mode can be turned off with auto. Turning auto off converts (or actually, reveals) the screen as a character surface that goes from -maxint to +maxint in both x and y, and has its origin at 1,1, and the screen is a "viewport" on this surface that extends from 1,1 to maxx, maxy. Text can be drawn anywhere, including off screen, but the characters outside of the 1,1 to maxx, maxy box will not be seen, and are "clipped out" of view. It can be determined if the cursor lies within the screen's bounds by curbnd.

The "virtual screen" that appears with auto off is a good match for today's windowing environments. Text can be drawn without worrying if it will cause the line to wrap, or the screen to scroll. And if a line of text happens to extend off the screen, that does not cause an error.

J.4 Tabbing

terminal will keep track of tabs set in x, for any character position. When terminal starts, the tabs are set to every 8th position on the screen, i.e., positions x= 9, 17, etc.

Outputting a tab character will cause the cursor to move to the next tab position on the line. If the cursor is at a tab position, then it will move to the next one. Tab positions can be set by settab, and cleared by restab. clrtab clears all set tabs.

J.5 Scrolling

The screen can be scrolled by the scroll procedure, which implements arbitrary direction scrolling. If the x value given is positive, then the screen data scrolls up. If the x value is negative, then the screen data scrolls down. If the y value is positive, the screen data scrolls left, and if it's negative, the screen data scrolls right. If either x or y is 0, then there is no movement in that direction.

J.6 Colors

There are two colors to set for text. One is the foreground, and the other is the background. The foreground is the color within the character itself. The background is the space behind the character. The possible colors are chosen from the two sets of primary colors:

type color = (black, white, red, green, blue, cyan, yellow, magenta);

Characters are written in the currently set foreground and background colors. The foreground color is set by fcolor, and the background color by bcolor.

The current background color is also used to set the color of any blanked out areas caused by other commands. For example, the clear procedure clears the screen to the background color. Scrolls, either programmer selected or automatic, use the background color for any uncovered areas that are blanked out.

J.7 Attributes

terminal provides many attribute controls, each of which can be switched on or off individually.

Attribute	Result
reverse	Enables reverse video.
underline	Underlines each character.
superscript	Gives a smaller and higher character for subscripting.
subscript	Gives a smaller and lower character for superscripting.
italic	Prints in italic or slanted characters.
bold	Prints in extra dark, or bold characters.
Strikeout	Prints characters with a horizontal bar through them.
blink	Blinks each character on and off.

For programs to maintain portability, the programmer should assume two things. First, that only a single attribute at one time can be set. This would mean that setting a second attribute after a first one is set, would cause the first attribute to be unset.

Second, the programmer should not assume that any one particular attribute is available. Many older terminals do have more than one or two attributes. Superscript, subscript, italic and strikeout are rare in standalone terminals. Superscript, subscript, italic and bold are rare today on graphical windowing systems because they alter the geometry of the characters such that it is difficult or impossible to emulate a character cell in such a system. blink is also rare in graphical systems because of the computational work required.

For this reason, there is a general mode, standout, that can be enabled or disabled just like an attribute. What standout does is enable an attribute the terminal does have, so that the program does not have to select a specific attribute.

J.8 Multiple Surface Buffering

terminal implements the ability to have logical screens in buffers. This is a copy of the characters on the screen, saved in a buffer of the same size as the screen. Logical buffers have many uses. Multiple screens can be kept, and quickly switched to the user. A program, like an editor, that wants to save the screen as it was before it started, can switch away to a second screen to do its work, then switch back to the original screen to restore its contents. Buffers can also be used to accomplish animation.

The select procedure sets both the current screen to be displayed, and also the screen that updates are to go to. When terminal starts, these are both set to the same screen, number 1. Any screen can be selected, and the display screen and the update screen can be different. If the update screen is not the one in display, then all of the write statements will place characters in the buffer, but not on screen. This "split mode" is typically used for animation.

Implementations are free to limit the total number of logical screens available. The user should assume no more than 10 logical screens are available.

J.9 Advanced Input

terminal implements an advanced output model that is upward compatible with the ISO 7185 Pascal serial model. Similarly, an advanced input model is also implemented that meets the needs of newer systems.

Today's deal with multiple input devices, not just the keyboard. Devices include a mouse, a joystick, timers, and other future devices. The standard method on small computers was to poll for such devices, or accept interrupts from them. The difficulty with those solutions was that these methods did not fit well with modern multitasking systems.

One method would be to use a multitask thread per device. However, this complicates small programs unnecessarily. The common solution today is "events", and the "event loop". The event model takes advantage of the fact that user input devices don't generate a lot of high bandwidth data. Each of the devices attached to the input from the user have their data packaged as "messages", which are small records, which are the description of the event. These events are then placed in a queue, and the program pulls the events, one at a time, from the queue and acts on them.

The description of an event record is:

module terminal;

const maxtim = 10; { maximum number of timers available }

type

joyhan = 1..4; { joystick handles }

joynum = 0..4; { number of joysticks }

joybut = 1..4; { joystick buttons }

joybtn = 0..4; { joystick number of buttons }

joyaxn = 0..3; { joystick axies }

mounum = 0..4; { number of mice }

mouhan = 1..4; { mouse handles }

moubut = 1..4; { mouse buttons }

timhan = 1..maxtim; { timer handle }

funky = 1..100; { function keys }

{ events }

evtcod = (etchar, { ANSI character returned }

etup, { cursor up one line }

etdown, { down one line }

etleft, { left one character }

etright, { right one character }

etleftw, { left one word }

etrightw, { right one word }

ethome, { home of document }

ethomes, { home of screen }

ethomel, { home of line }

etend, { end of document }

etends, { end of screen }

etendl, { end of line }

etscrl, { scroll left one character }

etscrr, { scroll right one character }

etscru, { scroll up one line }

etscrd, { scroll down one line }

etpagd, { page down }

etpagu, { page up }

ettab, { tab }

etenter, { enter line }

etinsert, { insert block }

etinsertl, { insert line }

etinsertt, { insert toggle }

etdel, { delete block }

etdell, { delete line }

etdelcf, { delete character forward }

etdelcb, { delete character backward }

etcopy, { copy block }

etcopyl, { copy line }

etcan, { cancel current operation }

etstop, { stop current operation }

etcont, { continue current operation }

etprint, { print document }

etprintb, { print block }

etprints, { print screen }

etfun, { function key }

etmenu, { display menu }

etmouba, { mouse button assertion }

etmoubd, { mouse button deassertion }

etmoumov, { mouse move }

ettim, { timer matures }

etjoyba, { joystick button assertion }

etjoybd, { joystick button deassertion }

etjoymov, { joystick move }

etterm); { terminate program }

{ event record }

evtrec = record

case etype: evtcod of { event type }

{ ANSI character returned }

etchar: (char: char);

{ timer handle that matured }

ettim: (timnum: timhan);

etmoumov: (mmoun: mouhan; { mouse number }

moupx, moupy: integer); { mouse movement }

etmouba: (amoun: mouhan; { mouse handle }

amoubn: moubut); { button number }

etmoubd: (dmoun: mouhan; { mouse handle }

dmoubn: moubut); { button number }

etjoyba: (ajoyn: joyhan; { joystick number }

ajoybn: joybut); { button number }

etjoybd: (djoyn: joyhan; { joystick number }

djoybn: joybut); { button number }

etjoymov: (mjoyn: joyhan; { joystick number }

joypx, joypy, joypz: integer); { joystick

coordinates }

etfun: (fkey: funky); { function key }

etup, etdown, etleft, etright, etleftw, etrightw, ethome,

ethomes, ethomel, etend, etends, etendl, etscrl, etscrr,

etscru, etscrd, etpagd, etpagu, ettab, etenter, etinsert,

etinsertl, etinsertt, etdel, etdell, etdelcf, etdelcb, etcopy,

etcopyl, etcan, etstop, etcont, etprint, etprintb, etprints,

etmenu, etterm: (); { normal events }

{ end }

end;

begin ! terminal

end.

The next event for the program is retrieved via the event call. The basis of the event system is that events must be retrieved often enough that the input queue does not fill up. Thus, an "event model" program will be centered around the event loop that gets the next event, acts on it, and returns to the top for more events.

An important principle of event handling is that events that are not defined for a compliant program are ignored. That is, if an event not defined for terminal is received, it will be ignored. This is the basis of upward compatibility. If a new event is defined, existing programs will simply ignore it.

A typical event loop is as follows.

program p;

joins terminal;

var er: evtrec;

begin

repeat

terminal.event(er); ! get next event

case er.etype of

etchar: if er.char = ‘g’ then ; ! perform character action

etmoumov: ! perform mouse move action

else ! do nothing

end

until er.etype = etterm ! until user orders terminate

end.

Note the final default case that does nothing.

J.10 Event callbacks

An alternative to receiving events as records are the event based virtual methods:

module terminal;

virtual procedure evchar(c: char); begin end;

virtual procedure evtim(t: timhan); begin end;

virtual procedure evmoumov(m: mouhan); begin end;

virtual procedure evmouba(h: mouhan; b: moubut); begin end;

virtual procedure evmoubd(h: mouhan; b: moubut); begin end;

virtual procedure evjoyba(h: joyhan; b: joybut); begin end;

virtual procedure evjoybd(h: joyhan; b: joybut); begin end;

virtual procedure evjoymov(h: joyhan; x, y, z: integer); begin end;

virtual procedure evfun(k: funky); begin end;

virtual procedure evup; begin end;

virtual procedure evdown; begin end;

virtual procedure evleft; begin end;

virtual procedure evright; begin end;

virtual procedure evleftw; begin end;

virtual procedure evrightw; begin end;

virtual procedure evhome; begin end;

virtual procedure evhomes; begin end;

virtual procedure evhomel; begin end;

virtual procedure evend; begin end;

virtual procedure evends; begin end;

virtual procedure evendl; begin end;

virtual procedure evscrl; begin end;

virtual procedure evscrr; begin end;

virtual procedure evscru; begin end;

virtual procedure evscrd; begin end;

virtual procedure evpagd; begin end;

virtual procedure evpagu; begin end;

virtual procedure evtab; begin end;

virtual procedure eventer; begin end;

virtual procedure evinsert; begin end;

virtual procedure evinsertl; begin end;

virtual procedure evinsertt; begin end;

virtual procedure evdel; begin end;

virtual procedure evdell; begin end;

virtual procedure evdelcf; begin end;

virtual procedure evdelcb; begin end;

virtual procedure evcopy; begin end;

virtual procedure evcopyl; begin end;

virtual procedure evcan; begin end;

virtual procedure evstop; begin end;

virtual procedure evcont; begin end;

virtual procedure evprint; begin end;

virtual procedure evprintb; begin end;

virtual procedure evprints; begin end;

virtual procedure evmenu; begin end;

virtual procedure evterm; begin end;

begin ! terminal

end.

Each event procedure corresponds to an event from the evtrec record. When event has an event to return to the calling program, it first calls the default implementation of the corresponding virtual procedure, which flags that the event is unhandled, and should be returned to the caller.

The alternative method is activated by overriding the virtual procedure corresponding to the event that is to be received directly. event directly calls the overriding procedure, and the event is processed there. If the overriding procedure does not want to handle the event, then the inherited version of the procedure is called in the overrider. This accomplishes two things. First, any other overriders that are chained to the procedure are executed, so that they may handle the event. Finally, if none of the overriders wish to handle the event, the chain ends with the default implementation, which then flags that the event is to be returned to the caller of event. In this way, if none of the overriders handle the event, it is returned as a normal record back to the event caller.

There is no parallel execution implied in such event callbacks. The event function still must be called to activate the event procedures, and all such procedures run in the context of the current process.

The event procedures are prefixed with “ev” (event) to prevent them from colliding with the names of the normal terminal procedures.

The event procedures are a way to break the rigid formalism of event loop design. In the event loop model, the event loop must be changed anytime there is new code that needs to handle events. Using event procedures, new handlers can be added without such modification. This enhances modularity, since the new code may be in a different module. This aids the extendibility of the system.

Event procedures are also a way to obfuscate a program by making it less obvious where the flow of control is in the program. The advantage to the event loop model is that it creates clear flow of control, even when handling asynchronous user generated events.

J.11 Timers

Timers allow a terminal program to perform periodic events, such as screen updates, and keeping track of time. From 1 to 10 timers are available, numbered 1..10. Each timer is given a time to measure, in 100 Microsecond counts (see G.3 “Time and Date” in services for more details). When the timer is done, it sends an event to the event queue.

Timers can either simply stop when their time is done, or they can automatically start timing their original set time again. This is the "recurrent" mode, and it's useful when an activity needs to be performed periodically for the life of the program. For example, updating the screen on an active program, or checking when to update a clock display.

Timers are set by timer. A timer can be stopped or "killed" by killtimer. Killing a timer that is not active will not generate an error. This allows a single run timer to be killed without timing out during the call.

Due to the queuing nature of the event system, there is no guarantee about the accuracy of a timer. It can arrive later than its set time. If the program is late getting back to the event queue, or is busy with other events that occur before the timer, receipt of the timer event can be very late. All that receiving a timer event does is indicate that the time it measured has passed.

An example of timer use is the display of a clock, using the services time call. If a recurrent timer is set to go off on every second, the program should not simply advance the second on each timer event. Instead, the timer event should tell the program to read time to determine if the second has changed, and what value it currently has.

Implementations are free to limit the number of timers. Users should assume no more than 10 timers are available.

J.12 The Frame Timer

When performing animation, it is common to flip between screen buffers with select. The ideal time to perform a buffer flip is during the retrace time for the display, or the time it takes the display drawing hardware to reset to the top of the screen, and start drawing from the top again. Hiding the buffer flip in the retrace time can be key to making animations appear smooth.

The frame timer is a timer much like the standard timers, except that it is set automatically by the implementation. It is simply enabled or disabled, and gives an etframe event when it times out. On hardware that is capable, the etframe event is triggered by the beginning of the retrace cycle.

If an interrupt for the start of the retrace cycle is not available, then the frame timer is simply defaulted to a reasonable rate of redraw for animation, for example, 30 times per second.

J.13 Mouse

The mouse gives a position x,y on the screen, as well as from 1 to 4 buttons on it. A mouse actually gives its position as relative movements in x and y, but the system converts this to a screen position. The function mouse returns the number of mice attached to the system.

Mice generate two events. First, when the mouse moves, it generates position changes via the etmoumov event. The program does not have to worry about where it is going. Each time the position changes, a new x, y position is posted as an event.

The second event generated by a mouse is mouse button asserts and deasserts, etmouba and etmoubd. An "assert" means a press of the button, and a "deassert" is the release of the button. Note that instead of an on/off status check as polled by the program, the assert and deassert events give exact notice of when the button changes state, and what it is changing to.

When there is more than one mouse per system, the default behavior should be to treat them as separate, but equal controls on the screen from the same user. When a mouse moves or changes button state, it gets control of the program. This matches the common use of multiple pointing devices, where two devices are alternated by one user. For example, a trackball and a mouse may be just two different input methods from one user.

Alternately, a second mouse could be a remote mouse over a network. This "collaborative computing" model allows two users to look at the same document, with separate mice. Advanced implementations of multiple mice such as these should be selected by the user.

Mice are subject to “rate limiting”. This means that the number of events per second reported by the mouse can be limited to no more than what the human viewer can perceive. This prevents the number of mouse events from affecting program performance.

J.14 Joysticks

From 0 to 4 joysticks may be supported. Each joystick can have from 0 to 3 "axes" of directions of travel. In addition, each joystick can have 0 to 4 buttons. The function joystick returns the number of joysticks in the system. The function joyaxis gives the number of axes on a given joystick. The function joybutton gives the number of buttons on a given joystick.

The messages etjoyba or joystick button assert, and etjoybd or joystick button deassert, give events for the assertion and deassertion of the buttons on a joystick. When any axis on a joystick moves, it generates a etjoymov, or joystick movement, event. This event gives the relative setting of each axis of the joystick.

Unlike a mouse, a joystick is entirely relative. Each axis is represented by an integer. If the axis is not implemented it always reads 0. If the axis is deflected left, up or in, depending on the type of axis, then it is negative. If it is right, down, or out, it is positive. The axis is determined in its amount of deflection. If it is in the middle, it is 0. If it is deflected to the maximum, it is maxint, with the sign giving the direction.

By convention, the axes on a joystick are:

1. Left/right, or slider.

2. Up/down

3. In/out

Joysticks are "rate limited" devices. This means that no matter how fast the joystick is "slewed", it will only produce an event about every 10 milliseconds at maximum rate. The reason for this is that humans cannot generally perceive events like movement of a pointer across the screen at a faster rate than this, so there is no point in updating faster than that, and flooding the input event queue.

J.15 Function Keys

The system may have function keys, which are keys whose function are determined by the program. The number of function keys implemented are found with funkey. Function key messages are sent by the message etfun.

J.16 Automatic “hold” Mode

terminal implements a feature to help with legacy programs designed to the ISO 7185 Pascal serial I/O model. When a program exits that is unaware of the terminal model, the terminal window can abruptly close. This means that any printout from the program is lost.

The automatic hold mode keeps the window open unless a etterm event is received, until the user specifically closes the window. This mode is enabled by default in systems were it is valuable, i.e., windowing systems.

There are times when the automatic hold mode can be a problem. For example, if a user displayed menu features a “quit” option, it would be incorrect to hold that window after the user has already closed the program.

To solve this, the autohold procedure can be used to set automatic hold mode off or on. With automatic hold mode off, the window exits immediately when the program does.

J.17 Direct Writes

terminal accepts all standard ISO 7185 Pascal output methods, write, writeln, and page. However, it can be faster to output characters to the console directly, bypassing the normal file protocol layers inherent in the system. The procedure wrtstr outputs a character string directly to the terminal without any interpretation of control characters. It cannot be used with auto on.

J.18 Printers

Terminal can be used to operate a printer using a subset of the terminal functionality. To model a printer, terminal uses a one page buffer that can be written using normal terminal commands to write to this “virtual screen” contained within the buffer. When the page procedure is executed, the contents of the buffer is output to the printer as a whole page, then a new page can be written.

When terminal is connected to a printer file, the following conditions are true:

1. There is no input file associated with the printer, neither event or virtual event methods function. event gives an exception. None of the input devices work, and timer, mouse, joystick, function keys, the frame timer and the autohold set procedure all give exceptions.

2. The select call does not function, and gives an exception.

3. The dimensions given by maxx and maxy reflect the size of the printed page.

4. The exact set of attributes will be dependent on the printer. blink, of course, is never available.

A printer device is viewed as accepting a series of pages to be printed. The last page should be followed by a page procedure call, to insure that a partial page is not left in the page buffer, similar to the way ISO 7185 Pascal does not allow partial lines in a text file. terminal may automatically add a page call if that is not the last operation to the printer.

Printer devices are not associated with other, active screen terminal devices. It is up to the program how to reformat printout to fit the printed page. Specifically, when printing a copy of an onscreen page, extensive reformatting may be required.

Since printer device mode is a subset of terminal functionality, it is possible for any program designed to output to a printer to have its output viewed on a terminal screen. Each page will then be presented to the user in turn.

Printer devices are determined by the system, which knows which files are associated with printer devices and which are not. Specifically, the list file which appears as a standard Pascaline header file may be a printer device, a terminal, or a normal file.

J.19 Metafiles

A terminal metafile operates identically to a printer file except that all output is written to a file, and not to an external device. The metafile contains not only the standard characters, eoln, page commands, but can also represent the other output functions in terminal.

A metafile is opened with the procedure openmeta(f, x, y), where f is the file to open, and x and y are the number of characters in the x and y character grid dimensions. A metafile is closed using the standard Pascaline close procedure.

A metafile has the same restrictions on input, event, select and other functions as a printer file does. It does not have an input file or any input functions, nor a select procedure.

A metafile contains a complete representation of output to from terminal. It should be possible to render a metafile to either a printer or a display, either by directly copying the file to a suitable printer, or by using a conversion utility.

The format of a metafile is not defined. The only requirement is that all of the output operations, including write/writeln and page, are encoded in the file.

J.20 Remote display

terminal is compatible with the use of “remote display” of presentation text. In this mode, the output from terminal is encoded and sent over a communications channel. This is done for both input and output functionality, and thus remote display mode is implemented without restriction of functionality (unlike printer and metafile mode). In order for remote display mode to work, the following conditions must be true:

1. All output functions must be applied in the order they were issued by the program.

2. All input events must be received in the order they were generated by the user.

Any synchronization between output and input is up to the program using terminal, just as it is in local mode. For example having the user attempt to select a moving target with the mouse would be highly dependent on the overall display rate of the system.

The exact format of the data passing over the communications channel to allow remote mode to function is system dependent.

Terminal is designed to operate efficiently with such remote displays. For example, there is no ability to read characters from the display.

J.21 Terminal objects

All of the procedures, functions and other declarations in terminal are also available in a terminal object of the form:

module terminal;

class screen(var input, output: file);

var er: evtrec; ! event record

! Executive methods

procedure cursor(x, y: integer); begin end;

function maxx: integer; begin end;

function maxy: integer; begin end;

procedure home; begin end;

procedure del; begin end;

procedure up; begin end;

procedure down; begin end;

procedure left; begin end;

procedure right; begin end;

procedure blink(e: boolean); begin end;

procedure reverse(e: boolean); begin end;

procedure underline(e: boolean); begin end;

procedure superscript(e: boolean); begin end;

procedure subscript(e: boolean); begin end;

procedure italic(e: boolean); begin end;

procedure bold(e: boolean); begin end;

procedure strikeout(e: boolean); begin end;

procedure standout(e: boolean); begin end;

procedure fcolor(c: color); begin end;

procedure bcolor(c: color); begin end;

procedure auto(e: boolean); begin end;

procedure curvis(e: boolean); begin end;

procedure scroll(x, y: integer); begin end;

function curx: integer; begin end;

function cury: integer; begin end;

function curbnd: boolean; begin end;

procedure select(u, d: integer); begin end;

procedure event; begin end;

procedure timer(i: timhan; t: integer; r: boolean); begin end;

procedure killtimer(i: timhan); begin end;

function mouse: mounum; begin end;

function mousebutton(m: mouhan): moubut; begin end;

function joystick: joynum; begin end;

function joybutton(j: joyhan): joybtn; begin end;

function joyaxis(j: joyhan): joyaxn; begin end;

procedure settab(t: integer); begin end;

procedure restab(t: integer); begin end;

procedure clrtab; begin end;

function funkey: funky; begin end;

function frametimer(e: boolean); begin end;

procedure autohold(e: boolean); begin end;

procedure wrtstr(s: string); begin end;

! Event callbacks

virtual procedure evchar(c: char); begin end;

virtual procedure evtim(t: timhan); begin end;

virtual procedure evmoumov(m: mouhan); begin end;

virtual procedure evmouba(h: mouhan; b: moubut); begin end;

virtual procedure evmoubd(h: mouhan; b: moubut); begin end;

virtual procedure evjoyba(h: joyhan; b: joybut); begin end;

virtual procedure evjoybd(h: joyhan; b: joybut); begin end;

virtual procedure evjoymov(h: joyhan; x, y, z: integer); begin end;

virtual procedure evfun(k: funky); begin end;

virtual procedure evup; begin end;

virtual procedure evdown; begin end;

virtual procedure evleft; begin end;

virtual procedure evright; begin end;

virtual procedure evleftw; begin end;

virtual procedure evrightw; begin end;

virtual procedure evhome; begin end;

virtual procedure evhomes; begin end;

virtual procedure evhomel; begin end;

virtual procedure evend; begin end;

virtual procedure evends; begin end;

virtual procedure evendl; begin end;

virtual procedure evscrl; begin end;

virtual procedure evscrr; begin end;

virtual procedure evscru; begin end;

virtual procedure evscrd; begin end;

virtual procedure evpagd; begin end;

virtual procedure evpagu; begin end;

virtual procedure evtab; begin end;

virtual procedure eventer; begin end;

virtual procedure evinsert; begin end;

virtual procedure evinsertl; begin end;

virtual procedure evinsertt; begin end;

virtual procedure evdel; begin end;

virtual procedure evdell; begin end;

virtual procedure evdelcf; begin end;

virtual procedure evdelcb; begin end;

virtual procedure evcopy; begin end;

virtual procedure evcopyl; begin end;

virtual procedure evcan; begin end;

virtual procedure evstop; begin end;

virtual procedure evcont; begin end;

virtual procedure evprint; begin end;

virtual procedure evprintb; begin end;

virtual procedure evprints; begin end;

virtual procedure evmenu; begin end;

virtual procedure evterm; begin end;

begin ! terminal

end.

The description of each method in a screen object appears with the same methods as the module terminal in J.23.

When a screen object is instantiated, it accepts an input and an output file as parameters. Normally these are the standard input and standard output files of the program. However, these can be different files in derived objects.

A screen object contains an event record, so it is not necessary to specify an external event record in the event procedure (nor possible).

A screen object can be created as follows:

program p;

joins terminal;

var si(input, output): instance of terminal.screen;

begin

si.home; { send cursor to home position }

writeln(si.output, ‘hello, terminal world’);

repeat { event loop }

si.event; { get next event }

{ process events }

until si.er.type = etterm { loop until program cancelled }

end.

Where terminal is the terminal module, and si is the screen object. screen objects can be instantiated statically or dynamically.

screen objects contain their own state for the following:

1. Location of cursor.

2. Current attributes and colors.

3. Buffer working/display status.

4. Tab stops.

5. Timer numbers.

However, each screen object gets the complete state of the module terminal when it is created.

Having each screen object possess its own state means that each object can be writing to its own section of the screen in its own mode. Each object can even have its own private screen buffer, but this must be specifically selected using the select procedure.

When multiple screen objects exist, and all have the cursor visibility on, the cursor will remain at the last place it was specifically directed to. This can mean that the cursor will rapidly appear to swap back and forth between the active drawing screen objects. This can be improved by only selecting one of the screen objects as having a visible cursor. Typically, a the cursor should be placed to attract user attention to where text is being entered, or if none is being entered, it should be turned off.

As in the procedural interface to terminal, events in the screen class can be registered as callbacks via the virtual procedures. However, just as in the procedural interface, such callbacks do not function unless the event method for the screen object is called.

J.22 Exceptions

The following exceptions are generated in terminal:

Identifier	Meaning
TooManyFiles	The total number of open files possible was exceeded.
NoJoyStick	No joystick access was available.
NoTimer	No timer access was available.
ToManyTimers	The total number of timers available was exceeded.
FilenameEmpty	Filename specified was empty.
InvalidScreenNumber	Screen number specified was invalid.
InvalidHandle	An invalid handle was specified.
InvalidTab	An invalid tab position was specified.
CannotCreateScreenBuffer	Cannot create a buffer for the screen.
CannotQueryJoystick	Could not get information on joystick.
InvalidJoystickHandle	Invalid handle specified for joystick.
InvalidTimerHandle	Invalid handle specified for timer.
CannotWriteDirect	Cannot write direct string with auto on.

terminal establishes a series of exception handlers for each of the above exceptions during startup. Exceptions not handled by a client program of terminal will go back to terminal, then print a message specific to the error, then the general exception will be thrown.

Not all procedures and functions throw all exceptions. See each procedure or function description for a list of exceptions thrown. A client of terminal need only capture the exceptions occurring in the procedure or function that is called.

Besides the exceptions on terminal procedures, the terminal module also can throw new exceptions on existing standard calls read, readln, write, writeln, page, reset, rewrite, assign, close, length, location, position, update, append, exists, change and delete, all of which are overridden by terminal.

J.23 Procedures, functions and methods in terminal

For all of the following module calls, If the screen file f is not present, the default is the standard output file, except for event, which defaults to the standard input file. If the procedure or function is a method, neither the input nor output screen file can be specified, since it is inherent in the object.

procedure cursor([var f: text;] x, y: integer);

Set cursor location for output surface file f in x and y.

Exceptions: None

function maxx[(var f: text)]: integer;

Find maximum screen location x in output surface file f.

Exceptions: None

function maxy[(var f: text)]: integer;

Find maximum screen location y in output surface file f.

Exceptions: None

procedure home[(var f: text)];

Send cursor to 1,1 location (upper left of screen) in output surface file f.

Exceptions: None

procedure clear[(var f: text)];

Clears the screen to the current background color and sends the cursor to 1,1 location (upper left of screen) in output surface file f.

Exceptions: None

procedure del[(var f: text)];

Back up cursor by one character in output surface file f, and erase character at that location. If the cursor is at the left side of the screen, and automatic mode is on, the cursor will be moved up one line, and to the right of screen. If the cursor is at the top of the screen, extreme left, then the screen will be scrolled down one line, and the cursor moves to the right side of the screen.

Exceptions: None

procedure up[(var f: text)];

Move cursor up one line in output surface file f. If the cursor is already at the top line, and automatic mode is on, the screen will be scrolled down, and the cursor remains at the same position.

Exceptions: None

procedure down[(var f: text)];

Move cursor down one line in output surface file f. If the cursor is already at the bottom line, and automatic mode is on, the screen will be scrolled up, and the cursor remains at the same position.

Exceptions: None

procedure left[(var f: text)];

Back up cursor by one character in output surface file f. If the cursor is at the left side of the screen, and automatic mode is on, the cursor will be moved up one line, and to the right of screen. If the cursor is at the top of the screen, left, then the screen will be scrolled down one line, and the cursor moves to the right side of the screen.

Exceptions: None

procedure right[(var f: text)];

Move forward by one character in output surface file f. If the cursor is at the right side of the screen, and automatic mode is on, the cursor will be moved down one line, and to the left of screen. If the cursor is at the bottom of the screen, right, then the screen will be scrolled up one line, and the cursor moves to the left side of the screen.

Exceptions: None

procedure blink([var f: text;] e: boolean);

If e is true, causes all further characters written to the screen to appear in blinking text in output surface file f.

Exceptions: None

procedure reverse([var f: text;] e: boolean);

If e is true, causes all further characters written to the screen to appear in reverse text in output surface file f.

Exceptions: None

procedure underline([var f: text;] e: boolean);

If e is true, causes all further characters written to the screen to appear in underlined text in output surface file f.

Exceptions: None

procedure superscript([var f: text;] e: boolean);

If e is true, causes all further characters written to the screen to appear in superscript text in output surface file f.

Exceptions: None

procedure subscript([var f: text;] e: boolean);

If e is true, causes all further characters written to the screen to appear in subscript text in output surface file f.

Exceptions: None

procedure italic([var f: text;] e: boolean);

If e is true, causes all further characters written to the screen to appear in italic text in output surface file f.

Exceptions: None

procedure bold([var f: text;] e: boolean);

If e is true, causes all further characters written to the screen to appear in bold text in output surface file f.

Exceptions: None

procedure strikeout([var f: text;] e: boolean);

If e is true, causes all further characters written to the screen to appear in strikeout text in output surface file f.

Exceptions: None

procedure standout([var f: text;] e: boolean);

If e is true, causes all further characters written to the screen to appear in standout text in output surface file f. Standout is assigned to the first mode possible from the following order:

Reverse.

Underline.

Bold

Italic.

Strikeout.

Blink.

If none of those modes are available, standout is a no-op.

Exceptions: None

procedure fcolor([var f: text;] c: color);

Sets the foreground, or text color, to the color c in output surface file f.

Exceptions: None

procedure bcolor([var f: text;] c: color);

Sets the background, or space color, to the color c in output surface file f.

Exceptions: None

procedure auto([var f: text;] e: boolean);

Turns automatic mode on or off, according to e in output surface file f.

Exceptions: None

procedure curvis([var f: text;] e: boolean);

Turns cursor visibility on or off, according to e in output surface file f.

Exceptions: None

procedure scroll([var f: text;] x, y: integer);

Scroll in arbitrary directions. The screen is scrolled according to the differences in x and y. Uncovered areas on the screen appear in the current background color.

Exceptions: None

function curx[(var f: text)]: integer;

Find the current x location of the cursor in output surface file f.

Exceptions: None

function cury[(var f: text)]: integer;

Find the current y location of the cursor in output surface file f.

Exceptions: None

function curbnd[(var f: text)]: boolean;

Check cursor in bounds. Returns true if the cursor is currently within the bounds of the screen in output surface file f.

Exceptions: None

procedure select([var f: text;] u, d: integer);

Select buffer to update and display. Selects the active buffer for update u, and display d in output surface file f. The update buffer will receive the result of all writes. The display buffer will be shown on screen.

Exceptions: CannotCreateScreenBuffer

procedure event[([var f: text;] var er: evtrec)];

Get next event. Retrieves the next event from the input queue from the terminal input file f to event record er. If there is no event ready, the program will wait.

Note that specification of the event record is optional only for the terminal class method.

Exceptions: None

procedure timer([var f: text;] i: timhan; t: integer; r: boolean);

Set timer active in output surface file f. The timer i will be set to run for time t. If the repeat flag r is set, then the timer will automatically repeat when the time expires. If the timer is already in use, then it will cease its current timing, and perform the new time.

Exceptions: InvalidHandle

procedure killtimer([var f: text;] i: timhan);

Stop timer in output surface file f. Stops the timer i. If the timer is not active, no error is reported.

Exceptions: InvalidHandle

function mouse[(var f: text)]: mounum;

Returns the number of mice in output surface file f.

Exceptions: None

function mousebutton([var f: text;] m: mouhan): moubut;

Returns the number of buttons on a given mouse m in output surface file f.

Exceptions: None

function joystick[(var f: text)]: joynum;

Returns the number of joysticks in the system in output surface file f.

Exceptions: None

function joybutton([var f: text;] j: joyhan): joybtn;

Returns the number of buttons on the given joystick j in output surface file f.

Exceptions: None

function joyaxis([var f: text;] j: joyhan): joyaxn;

Returns the number of axes on the given joystick j in output surface file f.

Exceptions: None

procedure settab([var f: text;] t: integer);

Set new tab. Sets a new tab location at t in output surface file f.

Exceptions: InvalidTab

procedure restab([var f: text;] t: integer);

Reset tab. Removes the tab at location t in output surface file f. If there is not a tab set there, it is not an error.

Exceptions: InvalidTab

procedure clrtab[(var f: text)];

Clear all tabs. All tabs are removed from the tabbing table in output surface file f.

Exceptions: None

function funkey[(var f: text)]: funky;

Returns the number of function keys available in output surface file f.

Exceptions: None

function frametimer([var f: text;] e: boolean);

Enables or disables the framing timer in output surface file f. If e is true, the frame timer is enabled, otherwise disabled. The frame timer gives frame timer events, which occur approximately on each refresh of the display screen. It may be tied to the refresh hardware, or may be simulated via a timer.

Exceptions: NoTimer

procedure autohold([var f: text;] e: boolean);

Sets the state of automatic hold in output surface file f. If e is true, autohold is enabled, otherwise disabled. autohold determines if the window will exit immediately if the program self terminates. If an exit was not ordered via the user interface, the display is held until it is.

Exceptions: None

procedure wrtstr([var f: text;] s: string);

Writes the string s directly to the output surface file f. No control character interpretation is done. This procedure is used to perform efficient writes to the display surface without per-character overhead.

It is an error to call this routine when auto is enabled.

Exceptions: CannotWriteDirect

K Annex K: Graphical Interface Library

The graphical library graphics extends the terminal model by adding graphical output procedures.

Since it is completely upward compatible with terminal, and standard ISO 7185 Pascal serial output modes, any program from ISO 7185 Pascal, or terminal compliant Pascaline will run under graphics. In the most advanced modes of graphics, ordinary Pascal write statements can still be used to output text, so all of the output formatting procedures of ISO 7185 Pascal still work.

graphics will handle any graphics task. Besides drawing features, it supports double page animation. Combined with the sound library sound, full graphical games are possible.

K.1 Terminal model

graphics emulates terminal by setting up a "character grid" across the pixel based screen. Each "cell" on the grid matches the pixel height and width of a character. The character font is set to a fixed font by default when graphics starts. This gives every character in the font the same height and width. Finally, the text drawing mode is set such that both the foreground (the inside of the characters) and the background (the space behind the characters) are drawn, overwriting any content of each character cell as it is written.

This mode can be kept, while drawing other figures on the same text surface. Alternately, the cursor can be set to any arbitrary pixel on the screen, and text written anywhere, down to the pixel. Also, the font can be changed to a proportional one for a more pleasing look. Because automatic mode relies on characters being neatly placed on the grid, it must be turned off before the cursor leaves the grid or becomes a proportional font.

When auto is turned off, the grid is still useful. Although the character spacing varies, the line spacing is still valid. This means that the grid is no longer useful in the x direction, but it is still useful in the y direction. In addition, the origin in x is still valid. The result is that a series of lines printed with end-of-lines will do the right thing with auto off, namely present a series of left justified lines at the x origin (flush left) with the correct spacing.

K.2 Graphics Coordinates

The total size of the graphics screen is found by maxxg and maxyg, which return the maximum pixel index in x and y. The pixel coordinates on the screen are from 1,1 to maxxg(f), maxyg(f). The cursor can be set to any pixel position by cursorg(f, x, y). The current location of the cursor in pixel terms is found by curxg and curyg.

K.3 Character Drawing

There can be any number of fonts available on the system, including both fixed space fonts, and proportional fonts that vary in the width of characters. The number of fonts in the system can be found with the font function. Fonts are chosen by logical number with font(f, c), where c is the font code, 1 to font. There are two methods to determine what font is assigned to a particular font code. The first is the standard font codes, the second is the font name system. Standard fonts are numbers for commonly used fonts in the system. These are commonly available fonts the program may need.

Font 1: Terminal Font

This is the default font set up by graphics when it starts. It's a fixed font. It also cannot be superscripted, subscripted, bold or italic, because these modes change the size of the font.

Font 2: Book Font

This is a serif font, and is good for general purpose text such as what a paragraph in a book is written in. This is the most common proportional font.

Font 3: Sign Font

This is a no serif font (sans serif), and is best for headings, titles and similar uses, as in road signs and other signs. It's a proportional font.

Font 4: Technical Font

The technical font is a fixed font that is guaranteed to be able to scale to any arbitrary size. This font is used to label drawings and engineering documents. Before the technology existed to create arbitrary fonts in any point size, the technical font was done with stroked vector graphics. Now, it is more likely to be equivalent to the sign font.

Beyond the standard fonts, the name of an installed font can be found by fontnam(f, fc, fns), where fc is the font code, 1 to font, and fns returns the descriptive string for the font, such as "Helvetica". The application should use the standard fonts by default, then present the system fonts, by name to the user, and let the user choose one of them.

The size of each character is set by fontsiz(f, n), where n is the height of the font in pixels. The reason character sizes are set by their height is because proportional fonts vary in the width of the character. The height never varies. The current height of the font is found by chrsizy. Its width is found with chrsizx. When a proportional font is active, chrsizx returns the width of a space in that font, which is always as wide or wider than the widest character in that font.

Besides the basic font, extra space can be added between lines (known as "leading" in typography, for the lead strips used between type lines) with chrspcy(f, n). n is the number of pixels of extra space to add between lines. Extra space between characters is added with chrspcx(f, n), where n is the number of pixels of extra space to add between characters.

The graphical cursor is placed at the upper left of the character box for the next character to be drawn. If it is needed to know exactly where the character will rest if drawn on a line. The offset from the top of the character box to the baseline of the text is found with the function baseline.

In typography, fonts and characters are measured by points, of which there are 28.35 points per centimeter. Point measurement implies that the exact size of objects drawn on the screen is known. This can be determined by the functions dpmx and dpmy, which return the "dots per meter" or pixels in one meter for both x and y. The reason it can be two different measures for the two different axes is that the display may not have square pixels or a 1:1 aspect ratio.

To find a given point size in terms of the height needed for the character, it is found by:

dpmy/2835*point size

The screen aspect ratio can also be found from these calls, it is:

dpmx/dpmy

K.4 String Sizes and Kerning

When writing text to the screen in proportional font, it is often needed to know exactly how much space the string will take up on the screen, down to the pixel. This amount of space can change not only because of the variable width of proportional fonts, but also because of an effect called "kerning". When a string of characters is draw together, the system can apply "kerning" to characters in the string. Kerning means to fit the individual letters together, like puzzle pieces, to come up with a tighter spacing than is normally possible. For example, "A" and "V" together as "AV" can typically be kerned together to take less space because they can overlap. To find the exact number of pixels in x that a string will occupy, the function strsiz(f, s) is used, where s is the string. The size of the string in y does not change, and can be found with chrsizy. To find the exact position, in pixels offset from the beginning of the string in x, of a given character, use chrpos(f, s, n), where s is the string, and n is the index of the character to find the x offset of.

K.5 Justification

Justification is the spreading of spacing through a string of characters to fit a given space. If the string will fit into the space is found with strsiz(f, s), and checking if the resulting pixels required are less than or equal to the space they will occupy as justified. The character string is written in justified mode with writejust(f, s, n), where s is the string to write, and n is the number of pixels to fit it in. If the number of pixels allowed for is not enough, the string will be larger than the requested number. The offset, in x, of a given justified character, is found with justpos(f, s, p, n), where s is the string, p is the offset of the character you are interested in, and n is the total number of pixels to fit the string in, as in writejust.

K.6 Effects

graphics expands the effects in terminal. For smaller character baselines, condensed(f, b), is used. For larger character baselines, extended(f, b) is used.

In addition to normal bold, there are also light(f, b), xlight(f, b), and xbold(f, b) effects. For lighter than normal, extra light, and extra bold modes.

Characters will have an embossed look with hollow(f, b) and raised(f, b). Hollow makes the character look sunken, and raised makes it look as if coming off the page.

K.7 Tabs

graphics extends the character level of tabbing in terminal with procedures that can set tabs on an individual pixel. settabg(f, x) sets a tab at the pixel x. restabg(f, x) resets the tab at pixel x. The terminal procedure clrtab(f) clears all tabs, including pixel level tabs.

K.8 Colors

The simple eight colors from terminal are still available, with the addition of two new calls that allow access to the full range of colors an advanced graphic system provides. fcolorg(f, r, g, b) sets the foreground color from values of red r, green g, and blue b. Similarly, bcolorg(f, r, g, b) sets the background color from rgb values. The values of the colors are ratioed. This means that instead of an absolute number, the possible colors are ratioed from 0 to maxint, where 0 is dark, and maxint is saturated color. Color ratios allow the true color range implemented by the system to be hidden.

K.9 Drawing Modes

When colors, background or foreground, are drawn on the screen, they can be in a number of mixing modes. Mixing modes govern how the new color is laid over the old. The modes are mutually exclusive, so the setting of a new mix mode for a given color deactivates the old mode. If the old color is simply to be overwritten, then fover(f) or bover(f) is appropriate. If the new color is to be xor'ed with the old color, then fxor(f) or bxor(f) is used. If the new color is to be ignored, leaving the old color underneath intact, use finvis(f) or binvis(f). There is also fand(f), band(f), for(f) and bor(f).

There might not seem to be a use for an "invisible" color, but there are actually several uses. First, if the background is set invisible, the text can be overlaid on another pattern. In fact, this is the most common drawing mode, and most programmers will prefer to turn the background off and lay the backgrounds themselves. Similarly, leaving the background on, then setting the foreground invisible can be used to "stencil" letters with arbitrary patterns inside the letters.

Xor mode is good for several things. First, if a series of figures, say rectangles, are to be laid, but the intersections between them are to be left visible, xor is the right mode. Second, xor can be used to place, and then remove a pattern, even a complex one, easily. This is used to allow the user to place figures by dragging them with the mouse to a new location. It can be used to draw "rubber band" boxes around selections.

Xor mode has two rules of interest:

1. Any two colors, even the same colors, xored together, will give a third color, with the exception of black.

2. Having xored a drawing into the viewplane, xoring the same color and drawing into the viewplane again will restore the old drawing.

Xor can be used for several special effects. However, Xor does not tolerate inaccuracy. Xoring something back off the screen has to be done the same way it was put on, with the same parameters. Also, the mode of drawing in graphics is not compatible with some uses of the xor mode. Drawing a rectangle, for example, will result in "corner errors", because the rectangles are built from lines, and lines start and end at the coordinates of the box corners. Because one line starts at the same point another ends, they will xor mix together. The result is a recognizable point of off-color on each corner.

The best way to use xor is to xor a single figure onto the screen, then xor it back off. If complex figures are to be xored on and off the screen, xor is run backwards, that is, from the last figure drawn back to the first.

And and or modes are used to create stencils and other effects. For example, a drawing and’ed with a black stencil will remain black in the stencil area, and intact elsewhere.

K.10 Drawing Graphics

A graphics element that is not a character is referred to as a "figure". What graphics tries to do is provide a small toolset, that does not include figures that you could reasonably construct from the lower level figures. For example, there is no circle figure in graphics, because that is simply a special case of ellipse.

A parameter that applies to almost all figures is the width of lines. The width of a line usually defaults to 1, but may be more if a single line is unusable on the current display. This can easily happen on a very high resolution display. The line width can be set by the procedure linewidth(f, n), where n is the number of pixels for the line to use. There is no limit on the width of a line, and in fact, lines are a defacto way to draw arbitrary angle filled rectangles.

When the line width is set to an even number of pixels, an effect called "even line uncertainty" exists. If you draw a line between two points, and the line width is say, 2, one of the 2 pixels is going to be on the line, and the other could be to either side of it. It literally depends on how the math happens to round off.

To prevent this, line width should always be set to an odd number.

K.11 Figures

The fundamental figure in graphics is the line. A line is drawn, in the current linewidth, by line(f, x1, y1, x2, y2). A rectangle is drawn with rect(f, x1, y1, x2, y2), whose borders have the current linewidth. A filled rectangle is drawn with frect(f, x1, y1, x2, y2), whose interior is the foreground color. An ellipse is drawn with ellipse(f, x1, y1, x2, y2). The x and y parameters define a rectangle that contains the figure. The procedure fellipse(f, x1, y1, x2, y2) draws a filled ellipse.

The procedure arc(f, x1, y1, x2, y2, rs, re) draws an arc line around the ellipse formed by the rectangle formed by the x and y parameters. The start and end points of the arc are described by a special ratio notation that gives the angle. The angles in a 360 degree circle are described by a number from 0 to maxint. 0 is the 0 degree, or top center, of the ellipse. The angles around the circle clockwise then go from 0 to maxint, at which time a full 360 degrees have been traversed. For example, maxint div 2 is 180 degrees, maxint div 4 is 90 degrees, etc. The parameter rs gives the angle where the arc starts. The parameter re gives the angle where the arc ends. Arcs can be specified to cross maxint back to zero, or use negative degrees, or any combination.

The procedure farc(f, x1, y1, x2, y2, rs, re) draws a filled arc. The procedure fcord(f, x1, y1, x2, y2, rs, re) draws a filled cord (a line bisecting the circle).

Rectangles with rounded corners can be drawn with rrect(f, x1, y1, x2, y2, xw, yw). The x and y parameters describe the bounding box, The xw and yw parameters describe the size of the ellipses that are placed in the corners to round the edges of the box. To draw a filled rounded rectangle, use frrect(f, x1, y1, x2, y2, xw, yw).

The general purpose shape ftriangle(f, x1, y2, x2, y2, x3, y3) draws a filled triangle. Parting with convention, graphics does not give complex polygon procedures. Rather, you can build up polygons from triangles, and in any case, a high speed drawing engine in hardware would accept triangles only, so the lower level software would have to break up the polygon for you.

Single pixels can be set with setpixel(f, x, y).

K.12 Predefined Pictures

A picture, or a bitmap, is defined outside the program by a drawing application. Its format is typically operating system specific. graphics considers pictures to be a cached resource. A picture is loaded from a file by loadpict(f, p, fs). The string fs indicates the file name for the picture file. p is a logical picture number, from 1 to n, and indicates how you want to refer to the picture while its loaded into memory.

A logical picture is drawn onto the screen with picture(f, p, x1, y1, x2, y2). The parameter p indicates the logical picture to draw. The x and y parameters indicate the box that the picture is to be drawn into. graphics will scale or stretch the picture as needed to make the picture fit into the space given.

In order to determine the parameters of a picture, such as native size and aspect, the functions pictsizx(f, p) and pictsizy(f, p) are used. These give the native size of the picture in x and y, and the aspect ratio of the picture is then found with pictsizex(f, p)/pictsizey(f, p).

K.13 Scrolling

As in terminal, graphics can scroll in arbitrary directions. It can also scroll down to the pixel, using the call scrollg(f, x, y). The parameters work the same way as the character position parameters of scroll, except that pixels are specified instead of characters.

K.14 Clipping

Clipping is completely automatic in graphics. Any figure drawn is clipped to the edges of the screen. If a figure is drawn entirely outside the screen bounds, it is completely clipped out.

K.15 Mouse Graphical Position

A new event, etmoumovg, exists that gives mouse movements in pixels, not just characters. The old etmoumov still occurs, and carries the character grid message. The etmoumovg message happens when the mouse moves a pixel, and the etmoumov message happens when the mouse moves a whole character cell. If you don't need the etmoumov message, you simply ignore it.

K.16 Animation

In terminal, the select call was introduced, that switches between multiple screen buffers. This call is tailor made for double buffer animation, it works in graphics the same way. Double buffer animation works by having two screen buffers. One of them is drawn, and the other one is displayed. When a "frame" is drawn, i.e., the picture in the buffer currently being draw is complete, the drawing and display buffers are swapped, and then drawing begins on what used to be the display buffer, clearing it if necessary.

Double buffering removes any of the ongoing drawing operations from the active screen. Although computers do this quite fast, seeing drawing operations in progress tends to produce annoying flashing effects, sparkles and other effects during the drawing. In addition, although the worst interactions with the painting of the graphics card memory to the display screen have disappeared, there can still be odd effects from the fact that the display is being refreshed across the image being drawn.

graphics supports more than double buffering (triple, quad or better). However, the advantages of this typically diminish as the amount of data being managed grows without a compensating gain in drawing speeds.

To reduce flicker effects the buffer is flipped when the display enters its retrace period. Syncing with the display eliminates the effects that occur when writing to the display while the display is drawing across it. The retrace period is when the refresh cycle has finished the last lines on the screen, and will head back to the top of the screen. This gives a short time while the display is not doing anything, so if the buffer swap can occur within the retrace, no effects will appear on the screen at all.

The solution is the etframe message. etframe is sent when the display enters refresh. If the system does not allow notification for retrace, the etframe message is generated by a timer that keeps either the screen refresh rate, or 30 cycles per second if that cannot be determined.

K.17 Copy between buffers

Blocks of pixels can be copied between buffers with procedure blockcopyg(f, s, d, sx1, sy1, sx2, sy2, dx1, dy1, dx2, dy2). This copies a pixel block from a source bounding box to a destination box in the same or a different buffer. It is capable of both resizing the block, as well as using the write mode to place the pixels.

Copying between buffers is a very powerful technique to speed animation. Pictures can be constructed and processed in a non-displayed buffer, then copied quickly to a target buffer for display. A program with a lot of animation will typically have an offline buffer just to keep sprites and other drawn objects ready to present. The drawing mode can be used to create stencils and other drawing tools.

K.18 Printers

As with terminal, graphics can output to a printer if the printer is graphics capable. The one page buffer contains sufficient pixels to allow a complete page with graphics to be rendered in the buffer, then output to the printer with a page operation.

See terminal for a list of restrictions on printer operation.

K.19 Metafiles

Metafiles can be written in graphics. The same comments that apply to metafiles in terminal apply to metafiles in graphics.

K.20 Remote display

Graphics is capable of using a remote display as in terminal. The same comments as in terminal apply to graphics.

K.21 Declarations

The declarations for graphics are very similar to terminal, with the addition of the mouse move graphical event, and the standard font codes.

module graphics;

const

maxtim = 10; { maximum number of timers available }

maxbuf = 10; { maximum number of buffers available }

font_term = 1; { terminal font }

font_book = 2; { book font }

font_sign = 3; { sign font }

font_tech = 4; { technical font (vector font) }

type

{ colors displayable in text mode }

color = (black, white, red, green, blue, cyan, yellow, magenta);

joyhan = 1..4; { joystick handles }

joynum = 0..4; { number of joysticks }

joybut = 1..4; { joystick buttons }

joybtn = 0..4; { joystick number of buttons }

joyaxn = 0..3; { joystick axies }

mounum = 0..4; { number of mice }

mouhan = 1..4; { mouse handles }

moubut = 1..4; { mouse buttons }

timhan = 1..maxtim; { timer handle }

funky = 1..100; { function keys }

{ events }

evtcod = (etchar, { ANSI character returned }

etup, { cursor up one line }

etdown, { down one line }

etleft, { left one character }

etright, { right one character }

etleftw, { left one word }

etrightw, { right one word }

ethome, { home of document }

ethomes, { home of screen }

ethomel, { home of line }

etend, { end of document }

etends, { end of screen }

etendl, { end of line }

etscrl, { scroll left one character }

etscrr, { scroll right one character }

etscru, { scroll up one line }

etscrd, { scroll down one line }

etpagd, { page down }

etpagu, { page up }

ettab, { tab }

etenter, { enter line }

etinsert, { insert block }

etinsertl, { insert line }

etinsertt, { insert toggle }

etdel, { delete block }

etdell, { delete line }

etdelcf, { delete character forward }

etdelcb, { delete character backward }

etcopy, { copy block }

etcopyl, { copy line }

etcan, { cancel current operation }

etstop, { stop current operation }

etcont, { continue current operation }

etprint, { print document }

etprintb, { print block }

etprints, { print screen }

etfun, { function key }

etmenu, { display menu }

etmouba, { mouse button assertion }

etmoubd, { mouse button deassertion }

etmoumov, { mouse move }

ettim, { timer matures }

etjoyba, { joystick button assertion }

etjoybd, { joystick button deassertion }

etjoymov, { joystick move }

etterm, { terminate program }

etmoumovg, { mouse move graphical }

etframe); { frame sync }

{ event record }

evtrec = record

case etype: evtcod of { event type }

{ ANSI character returned }

etchar: (char: char);

{ timer handle that matured }

ettim: (timnum: timhan);

etmoumov: (mmoun: mouhan; { mouse number }

moupx, moupy: integer); { mouse movement }

etmouba: (amoun: mouhan; { mouse handle }

amoubn: moubut); { button number }

etmoubd: (dmoun: mouhan; { mouse handle }

dmoubn: moubut); { button number }

etjoyba: (ajoyn: joyhan; { joystick number }

ajoybn: joybut); { button number }

etjoybd: (djoyn: joyhan; { joystick number }

djoybn: joybut); { button number }

etjoymov: (mjoyn: joyhan; { joystick number }

joypx, joypy, joypz: integer); { joystick

coordinates }

etfun: (fkey: funky); { function key }

etmoumovg: (mmoung: mouhan; { mouse number }

moupxg, moupyg: integer); { mouse movement }

etup, etdown, etleft, etright, etleftw, etrightw, ethome,

ethomes, ethomel, etend, etends, etendl, etscrl, etscrr,

etscru, etscrd, etpagd, etpagu, ettab, etenter, etinsert,

etinsertl, etinsertt, etdel, etdell, etdelcf, etdelcb, etcopy,

etcopyl, etcan, etstop, etcont, etprint, etprintb, etprints,

etmenu, etterm, etframe: (); { normal events }

{ end }

end;

begin ! graphics

end.

Note that the name of the graphical terminal module retains the name of the original terminal module, but has graphical functionality added.

K.22 Event callbacks

As in terminal, the events can also be accessed via a series of virtual procedures. Only one new event procedure exists in the graphics module over the original event procedures in terminal:

module graphics;

virtual procedure evmoumov(h: mouhan; x, y: integer); begin end;

begin ! graphics

end.

K.23 Graphical Terminal Objects

All of the procedures, functions and other declarations in graphics are also available in a class of the form:

module graphics;

class surface(var input, output: file);

extends screen;

var er: evtrec; ! event record

! Executive methods

procedure cursor(x, y: integer); begin end;

function maxx: integer; begin end;

function maxy: integer; begin end;

procedure home; begin end;

procedure del; begin end;

procedure up; begin end;

procedure down; begin end;

procedure left; begin end;

procedure right; begin end;

procedure blink(e: boolean); begin end;

procedure reverse(e: boolean); begin end;

procedure underline(e: boolean); begin end;

procedure superscript(e: boolean); begin end;

procedure subscript(e: boolean); begin end;

procedure italic(e: boolean); begin end;

procedure bold(e: boolean); begin end;

procedure strikeout(e: boolean); begin end;

procedure standout(e: boolean); begin end;

procedure fcolor(c: color); begin end;

procedure bcolor(c: color); begin end;

procedure auto(e: boolean); begin end;

procedure curvis(e: boolean); begin end;

procedure scroll(x, y: integer); begin end;

function curx: integer; begin end;

function cury: integer; begin end;

function curbnd: boolean; begin end;

procedure select(u, d: integer); begin end;

procedure event; begin end;

procedure timer(i: timhan; t: integer; r: boolean); begin end;

procedure killtimer(i: timhan); begin end;

function mouse: mounum; begin end;

function mousebutton(m: mouhan): moubut; begin end;

function joystick: joynum; begin end;

function joybutton(j: joyhan): joybtn; begin end;

function joyaxis(j: joyhan): joyaxn; begin end;

procedure settab(t: integer); begin end;

procedure restab(t: integer); begin end;

procedure clrtab; begin end;

function funkey: funky; begin end;

function frametimer(e: boolean); begin end;

procedure autohold(e: boolean); begin end;

procedure wrtstr(s: string); begin end;

function maxxg: integer; begin end;

function maxyg: integer; begin end;

function curxg: integer; begin end;

function curyg: integer; begin end;

procedure line(x1, y1, x2, y2: integer); begin end;

overload procedure line(var f: text; x2, y2: integer); begin end;

overload procedure line(x2, y2: integer); begin end;

overload procedure linewidth(w: integer); begin end;

procedure rect(x1, y1, x2, y2: integer); begin end;

procedure frect(x1, y1, x2, y2: integer); begin end;

procedure rrect(x1, y1, x2, y2, xs, ys: integer); begin end;

procedure frrect(x1, y1, x2, y2, xs, ys: integer); begin end;

procedure ellipse(x1, y1, x2, y2: integer); begin end;

procedure fellipse(x1, y1, x2, y2: integer); begin end;

procedure arc(x1, y1, x2, y2, sa, ea: integer); begin end;

procedure farc(x1, y1, x2, y2, sa, ea: integer); begin end;

procedure fchord(x1, y1, x2, y2, sa, ea: integer); begin end;

procedure ftriangle(x1, y1, x2, y2, x3, y3: integer); begin end;

overload procedure ftriangle(var f: text; x2, y2, x3, y3: integer); begin end;

overload procedure ftriangle(x2, y2, x3, y3: integer); begin end;

overload procedure ftriangle(var f: text; x3, y3: integer); begin end;

overload procedure ftriangle(x3, y3: integer); begin end;

procedure cursorg(x, y: integer); begin end;

function baseline: integer; begin end;

procedure setpixel(x, y: integer); begin end;

procedure fover; begin end;

procedure bover; begin end;

procedure finvis; begin end;

procedure binvis; begin end;

procedure fxor; begin end;

procedure bxor; begin end;

function chrsizx: integer; begin end;

function chrsizy: integer; begin end;

function fonts: integer; begin end;

procedure font(fc: integer); begin end;

procedure fontnam(fc: integer; var fns: string); begin end;

procedure fontsiz(s: integer); begin end;

procedure chrspcy(s: integer); begin end;

procedure chrspcx(s: integer); begin end;

function dpmx: integer; begin end;

function dpmy: integer; begin end;

function strsiz(view s: string): integer; begin end;

function strsizp(view s: string): integer; begin end;

function chrpos(view s: string; p: integer): integer; begin end;

procedure writejust(view s: string; n: integer); begin end;

function justpos(view s: string; p, n: integer): integer; begin end;

procedure condensed(e: boolean); begin end;

procedure extended(e: boolean); begin end;

procedure xlight(e: boolean); begin end;

procedure light(e: boolean); begin end;

procedure xbold(e: boolean); begin end;

procedure hollow(e: boolean); begin end;

procedure raised(e: boolean); begin end;

procedure settabg(t: integer); begin end;

procedure restabg(t: integer); begin end;

procedure fcolorg(var f: text; r, g, b: integer); begin end;

procedure fcolor(var f: text; r, g, b: integer); begin end;

overload procedure fcolor(r, g, b: integer); begin end;

procedure bcolorg(r, g, b: integer); begin end;

procedure bcolor(var f: text; r, g, b: integer); begin end;

overload procedure bcolor(r, g, b: integer); begin end;

procedure loadpict(p: integer; view fn: string); begin end;

function pictsizx(p: integer): integer; begin end;

function pictsizy(p: integer): integer; begin end;

procedure picture(p: integer; x1, y1, x2, y2: integer); begin end;

procedure delpict(p: integer); begin end;

procedure scrollg(x, y: integer); begin end;

! Event callbacks

virtual procedure evchar(c: char); begin end;

virtual procedure evtim(t: timhan); begin end;

virtual procedure evmoumov(m: mouhan); begin end;

virtual procedure evmouba(h: mouhan; b: moubut); begin end;

virtual procedure evmoubd(h: mouhan; b: moubut); begin end;

virtual procedure evjoyba(h: joyhan; b: joybut); begin end;

virtual procedure evjoybd(h: joyhan; b: joybut); begin end;

virtual procedure evjoymov(h: joyhan; x, y, z: integer); begin end;

virtual procedure evfun(k: funky); begin end;

virtual procedure evup; begin end;

virtual procedure evdown; begin end;

virtual procedure evleft; begin end;

virtual procedure evright; begin end;

virtual procedure evleftw; begin end;

virtual procedure evrightw; begin end;

virtual procedure evhome; begin end;

virtual procedure evhomes; begin end;

virtual procedure evhomel; begin end;

virtual procedure evend; begin end;

virtual procedure evends; begin end;

virtual procedure evendl; begin end;

virtual procedure evscrl; begin end;

virtual procedure evscrr; begin end;

virtual procedure evscru; begin end;

virtual procedure evscrd; begin end;

virtual procedure evpagd; begin end;

virtual procedure evpagu; begin end;

virtual procedure evtab; begin end;

virtual procedure eventer; begin end;

virtual procedure evinsert; begin end;

virtual procedure evinsertl; begin end;

virtual procedure evinsertt; begin end;

virtual procedure evdel; begin end;

virtual procedure evdell; begin end;

virtual procedure evdelcf; begin end;

virtual procedure evdelcb; begin end;

virtual procedure evcopy; begin end;

virtual procedure evcopyl; begin end;

virtual procedure evcan; begin end;

virtual procedure evstop; begin end;

virtual procedure evcont; begin end;

virtual procedure evprint; begin end;

virtual procedure evprintb; begin end;

virtual procedure evprints; begin end;

virtual procedure evmenu; begin end;

virtual procedure evterm; begin end;

virtual procedure evmoumovg(m: mouhan); begin end;

virtual procedure evframe; begin end;

begin ! surface

end.

begin ! graphics

end.

The complete catalog of procedures and functions from graphics are available as methods in the surface class. There are minor differences, which are detailed with the procedure and function descriptions in J.23.

The class screen as specified in terminal is carried forward into graphics and extended to become surface.

When a surface object is instantiated, it accepts an input and an output file as parameters. Normally these are the standard input and standard output files of the program. However, this can be different files in derived objects.

A surface object also contains an event record, so it is not necessary to specify an external event record in the event procedure.

A surface object can be created as follows:

program p;

joins graphics;

var si(input, output): instance of graphics.surface;

begin

si.home; { send cursor to home position }

writeln(si.output, ‘hello, terminal world’);

repeat { event loop }

si.event; { get next event }

{ process events }

until si.er.type = etterm { loop until program cancelled }

end.

Where si is the surface object. surface objects can be instantiated statically or dynamically.

surface objects contain their own state for the following:

1. Location of cursor.

2. Current attributes and colors.

3. Current font and size.

4. Buffer working/display status.

5. Tab stops.

6. Timer numbers.

7. Cached pictures.

However, each surface object gets the complete state of the module graphics when it is created.

Having each surface object possess its own state means that each object can be writing to its own section of the screen in its own mode. Each object can even have its own private screen buffer, but this must be specifically selected using the select procedure.

When multiple surface objects exist, and all have the cursor visibility on, the cursor will remain at the last place it was specifically directed to. This can mean that the cursor will rapidly appear to swap back and forth between the active drawing screen objects. This can be improved by only selecting one of the screen objects as having a visible cursor. Typically, a the cursor should be placed to attract user attention to where text is being entered, or if none is being entered, it should be turned off.

K.24 Exceptions

The following exceptions are generated in graphics:

Identifier	Meaning
TooManyFiles	The total number of open files possible was exceeded.
NoJoyStick	No joystick access was available.
NoTimer	No timer access was available.
ToManyTimers	The total number of timers available was exceeded.
CannotPerformSpecial	Cannot perform operation on special file. A system file cannot be positioned, etc.
FilenameEmpty	Filename specified was empty.
InvalidScreenNumber	Screen number specified was invalid.
InvalidHandle	An invalid handle was specified.
InvalidTab	An invalid tab position was specified.
CannotCreateScreenBuffer	Cannot create a buffer for the screen.
CannotQueryJoystick	Could not get information on joystick.
InvalidJoystickHandle	Invalid handle specified for joystick.
InvalidTimerHandle	Invalid handle specified for timer.
CannotWriteDirect	Cannot write direct string with auto on.
CannotPositionTextByPixel	Cannot position text by pixel with auto on.
CannotPositionOutsideScreen	Cannot position outside screen with auto on.
CannotReenableAutoOffGrid	Cannot re-enable auto off grid
CannotReenableAutoOutsideScreen	Cannot re-enable auto outside screen.
InvalidFontNumber	Invalid font number.
NoValidTerminalFont	Valid terminal font not found.
CannotResizeFontWithAuto	Cannot resize a font with auto enabled.
CannotChangeFontsWithAuto	Cannot change fonts with auto enabled.
InvalidFontNumber	Invalid font number.
NoFontForNumber	Logical font number has no font assigned.
CannotSizeTerminalFont	Cannot change the size of the terminal font.
TooManyTabs	Too many tabs are set.
CannotTabGraphicalWithAuto	Cannot set a graphical tab with auto enabled.
StringIndexOutOfRange	String index out of range.
PictureFileNotFound	No picture file was found by filename.
PictureFilenameToLarge	The specified picture filename was too large.
CannotJustifySystemFont	Cannot justify system font.

graphics establishes a series of exception handlers for each of the above exceptions during startup. Exceptions not handled by a client program of graphics will go back to graphics, then print a message specific to the error, then the general exception will be thrown.

Not all procedures and functions throw all exceptions. See each procedure or function description for a list of exceptions thrown. A client of graphics need only capture the exceptions occurring in the procedure or function that is called.

K.25 Procedures and functions in graphics

See terminal for the basic text functions. These are all implemented in graphics.

For all of the following calls, If the screen file f is not present, the default is the standard output or standard input file. If the procedure or function is a method, neither the input nor output screen file should be specified, since it is inherent in the object.

function maxxg[(var f: text)]: integer;

Returns the maximum pixel index x in output surface file f.

Exceptions: None

function maxyg[(var f: text)]: integer;

Returns the maximum pixel index y in output surface file f.

Exceptions: None

function curxg[(var f: text)]: integer;

Returns the current location of the cursor, in pixel units, for x in output surface file f.

Exceptions: None

function curyg[(var f: text)]: integer;

Returns the current location of the cursor, in pixel units, for y in output surface file f.

Exceptions: None

procedure line([var f: text;] x1, y1, x2, y2: integer);

Draw line. Draws a line between the point x1,y1 to x2,y2, using the current line width, color and mode in output surface file f.

Exceptions: None

procedure linewidth([var f: text;] w: integer);

Set line width. Sets the line drawing width at w pixels wide in output surface file f. Use of an odd number of pixels is recommended.

Exceptions: None

procedure rect([var f: text;] x1, y1, x2, y2: integer);

Draw rectangle. Draws a rectangle whose opposite corners are x1,y1 and x2,y2. Uses the current line width, color and mode in output surface file f.

Exceptions: None

procedure frect([var f: text;] x1, y1, x2, y2: integer);

Draw filled rectangle. Draws a solid rectangle, whose opposite corners are x1,y1 and x2,y2. Uses the current color and mode.

Exceptions: None

procedure rrect([var f: text;] x1, y1, x2, y2, xs, ys: integer);

Draw rounded rectangle. Draws a rectangle with rounded corners. The opposite corners of the bounding box are specified as x1,y1 to x2,y2. The ellipses that specify the rounded corners are xs and ys, which specify the width and height of the ellipse. Uses the current line width, color and mode.

Exceptions: None

procedure frrect([var f: text;] x1, y1, x2, y2, xs, ys: integer);

Draw filled rounded rectangle. Draws a rectangle with rounded corners. The opposite corners of the bounding box are specified as x1,y1 to x2,y2. The ellipses that specify the rounded corners are xs and ys, which specify the width and height of the ellipse. Uses the current color and mode.

Exceptions: None

procedure ellipse([var f: text;] x1, y1, x2, y2: integer);

Draw an ellipse. Draws an ellipse bonded by a box whose opposite corners are x1,y1 to x2,y2. Uses the current line width, color and mode.

Exceptions: None

procedure fellipse([var f: text;] x1, y1, x2, y2: integer);

Draw a filled ellipse. Draws a solid ellipse bonded by a box whose opposite corners are x1,y1 to x2,y2. Uses the current color and mode.

Exceptions: None

procedure arc([var f: text;] x1, y1, x2, y2, sa, ea: integer);

Draw an arc. Draws an arc on an ellipse, whose bounding box is x1,y1 to x2,y2. The arc starts on the ellipse from the angle sa, to the angle ea. The angles are given in 360 degree to maxint ratio form. Uses the current color and mode.

Exceptions: None

procedure farc([var f: text;] x1, y1, x2, y2, sa, ea: integer);

Draw a filled arc. Draws a filled arc on an ellipse, whose bounding box is x1,y1 to x2,y2. The arc starts on the ellipse from the angle sa, to the angle ea. The angles are given in 360 degree to maxint ratio form. Uses the current color and mode.

Exceptions: None

procedure fchord([var f: text;] x1, y1, x2, y2, sa, ea: integer);

Draw a filled cord. Draws a filled cord on an ellipse, whose bounding box is x1,y1 to x2,y2. The cord starts on the ellipse from the angle sa, to the angle ea. The angles are given in 360 degree to maxint ratio form. Uses the current color and mode.

Exceptions: None

procedure ftriangle([var f: text;] x1, y1, x2, y2, x3, y3: integer);

Draw a filled triangle. Draws a filled triangle given the three points x1,y1,x2,y2, and x3,y3. Uses the current color and mode.

Exceptions: None

procedure cursorg([var f: text;] x, y: integer);

Position the cursor graphically. Moves the cursor to the pixel position x and y.

Exceptions: CannotPositionTextByPixel

function baseline[(var f: text)]: integer;

Find baseline of current font. Finds the baseline, or line on which all characters of the current font sit upon, in terms of offset from the character bounding box origin in y.

Exceptions: None

procedure setpixel([var f: text;] x, y: integer);

Set single pixel. Sets a single pixel at the point x,y, using the current color and mode.

Exceptions: None

procedure fover[(var f: text)];

Set overwrite mode foreground. Sets all new drawing to overwrite old colors on the foreground.

Exceptions: None

procedure bover[(var f: text)];

Set overwrite mode background. Sets all new drawing to overwrite old colors on the background.

Exceptions: None

procedure finvis[(var f: text)];

Set invisible mode foreground. Sets all new drawing to discard colors on the foreground.

Exceptions: None

procedure binvis[(var f: text)];

Set invisible mode background. Sets all new drawing to discard colors on the background.

Exceptions: None

procedure fxor[(var f: text)];

Set xor mode foreground. Sets all new drawing to xor old colors with new colors on the foreground.

Exceptions: None

procedure bxor[(var f: text)];

Set xor mode background. Sets all new drawing to xor old colors with new colors on the background.

Exceptions: None

procedure fand[(var f: text)];

Set and mode foreground. Sets all new drawing to and old colors with new colors on the foreground.

Exceptions: None

procedure band[(var f: text)];

Set and mode background. Sets all new drawing to and old colors with new colors on the background.

Exceptions: None

procedure for[(var f: text)];

Set or mode foreground. Sets all new drawing to or old colors with new colors on the foreground.

Exceptions: None

procedure bor[(var f: text)];

Set or mode background. Sets all new drawing to or old colors with new colors on the background.

Exceptions: None

function chrsizx[(var f: text)]: integer;

Find character size in x. Returns the x size, in pixels, of the characters in the current font. If the font is proportional, its x size will vary per character. The size will then be the space character, which is guaranteed to be the widest character in the font.

Exceptions: None

function chrsizy[(var f: text)]: integer;

Find character size in y. Returns the y size, in pixels, of the characters in the current font.

Exceptions: None

function fonts[(var f: text)]: integer;

Find number of fonts. Returns the number of fonts installed on the system.

Exceptions: None

procedure font([var f: text;] fc: integer);

Select logical font. Selects a font by logical number fc, where fc is 1..fonts.

Exceptions: CannotChangeFontsWithAuto

procedure fontnam([var f: text;] fc: integer; var fns: string);

Find name of logical font. Returns the name of the logical font fc in the string fns.

Exceptions: InvalidFontNumber

procedure fontsiz([var f: text;] s: integer);

Set font size. Sets the height of the current font, in pixels.

Exceptions: CannotResizeFontWithAuto, CannotSizeTerminalFont

procedure chrspcy([var f: text;] s: integer);

Set character y spacing. Sets the line to line spacing to s, in pixels.

Exceptions: None

procedure chrspcx([var f: text;] s: integer);

Set character x spacing. Sets the character to character spacing s, in pixels.

Exceptions: None

function dpmx[(var f: text)]: integer;

Find dots per meter x. Finds the dots per meter in x of the current display device.

Exceptions: None

function dpmy[(var f: text)]: integer;

Find dots per meter y. Finds the dots per meter in y of the current display device.

Exceptions: None

function strsiz([var f: text;] s: string): integer;

Find pixel size of string. Finds the total x size of the string s, in pixels. Accounts for all sizes and spacing.

Exceptions: None

function chrpos([var f: text;] s: string; p: integer): integer;

Find pixel offset of character. Finds the pixel offset from the start of a string s in terms of x pixels, to the character by the index p.

Exceptions: StringIndexOutOfRange

procedure writejust([var f: text;] s: string; n: integer);

Write string justified. Writes the given string s into the number of x pixels n. If the space is more than is required, the extra space will be distributed between the characters. If the space given is insufficient for the characters to be drawn, it will be drawn in the minimum amount of space for the entire string.

Exceptions: CannotPositionTextByPixel, CannotJustifySystemFont

function justpos([var f: text;] s: string; p, n: integer): integer;

Find justified pixel off set of character. Finds the pixel offset from the start of a string s, in terms of x pixels, to the character by the index p, for a string justified to fit into n pixels. The rules of justification are the same as for writejust.

Exceptions: StringIndexOutOfRange

procedure condensed([var f: text;] e: boolean);

Set condensed mode. Sets the current font to occupy a shorter baseline than normal. Note that this effect may not be implemented.

Exceptions: None

procedure extended([var f: text;] e: boolean);

Set extended mode. Sets the current font to occupy a longer baseline than normal. Note that this effect may not be implemented.

Exceptions: None

procedure xlight([var f: text;] e: boolean);

Set extra light mode. Sets the current font to extra light printing. Note that this effect may not be implemented.

Exceptions: None

procedure light([var f: text;] e: boolean);

Set light mode. Sets the current font to light printing. Note that this effect may not be implemented.

Exceptions: None

procedure xbold([var f: text;] e: boolean);

Set extra bold mode. Sets the current font to extra bold printing. Note that this effect may not be implemented.

Exceptions: None

procedure hollow([var f: text;] e: boolean);

Set hollow mode. Sets the current font to hollow, or sunken look, printing. Note that this effect may not be implemented.

Exceptions: None

procedure raised([var f: text;] e: boolean);.

Set raised mode. Sets the current font to raised, or relief look, printing. Note that this effect may not be implemented.

Exceptions: None

procedure settabg([var f: text;] t: integer);

Set graphical tab. Sets a tab to the pixel t.

Exceptions: TooManyTabs

procedure restabg([var f: text;] t: integer);

Reset graphical tab. The tab at pixel t is removed. If no tab is set at t, no error will result.

Exceptions: InvalidTab

procedure fcolorg([var f: text;] r, g, b: integer);

Set foreground color graphical. The foreground color is set to the red r, green g and blue b color. The colors are in 0..maxint ratios, with 0 = black, and maxint = saturated. The nearest color to the one given is found and set active as the foreground color. The exact color that results will depend on the total number of colors implemented in the system, and could well be black and white in a system so equipped.

Exceptions: None

procedure bcolorg([var f: text;] r, g, b: integer);

Set background color graphical. The background color is set to the red r, green g and blue b color. The colors are in 0..maxint ratios, with 0 = black, and maxint = saturated. The nearest color to the one given is found and set active as the foreground color. The exact color that results will depend on the total number of colors implemented in the system, and could well be black and white in a system so equipped.

Exceptions: None

procedure loadpict([var f: text;] p: integer; fn: string);

Load picture. Loads the picture from the filename fn to logical picture number p, which is 1..n. The file must be in a format that the system understands, and is converted to an in memory format that is optimal for the system, such as a direct match for the graphics device in use.

Exceptions: InvalidHandle, PictureFilenameToLarge

function pictsizx([var f: text;] p: integer): integer;

Find picture size x. Returns the size, in pixels of x, of the logical picture p.

Exceptions: InvalidHandle

function pictsizy([var f: text;] p: integer): integer;

Find picture size y. Returns the size, in pixels of y, of the logical picture p.

Exceptions: InvalidHandle

procedure picture([var f: text;] p: integer; x1, y1, x2, y2: integer);

Draw picture. The logical picture p is drawn into the bounding box formed by x1,y1 to x2,y2. The picture is stretched or compressed as required to fix into the destination bounding box. The method used to stretch or compress may depend on how much computing power is available on the system. There is no attention paid to aspect ratio. If the aspect ratio is to be preserved, it must be calculated. The current foreground mode is used.

Exceptions: InvalidHandle

procedure delpict([var f: text;] p: integer);

Remove logical picture from use. The logical picture p is removed from the picture queue, and will no longer take up memory space.

Exceptions: InvalidHandle

procedure scrollg([var f: text;] x, y: integer);

Scroll in arbitrary directions. The screen is scrolled according to the differences in x and y, which are in pixels. Uncovered areas on the screen appear in the current background color.

Exceptions: None

procedure blockcopyg([var f: text;] s, d, sx1, sy1, sx2, sy2, dx1, dy1, dx2, dy2 : integer);

Copy a pixel block between buffers. Copies a block of pixels from the source buffer s with the bounding box sx1, sy1 to sx2, sy2 to the destination buffer d in bounding box dx1, dy1 to dx2, dy2. The current foreground write mode is used. The picture is stretched or compressed as required to fit into the destination bounding box. The method used to stretch or compress may depend on how much computing power is available on the system. There is no attention paid to aspect ratio. If the aspect ratio is to be preserved, it must be calculated. The current foreground mode is used.

Scroll in arbitrary directions. The screen is scrolled according to the differences in x and y, which are in pixels. Uncovered areas on the screen appear in the current background color.

Exceptions: None

K.26 Events and Callbacks In graphics

For each item, both the event record section and the virtual procedure is presented. See the description of the event record (K.21 “Declarations”) for the format of the entire record.

Event: etmoumovg

virtual procedure evmoumovg(h: mouhan; x, y: integer);

The mouse with handle h has moved, to the graphical position indicated by x and y.

L Annex L: Windows Management Library

windows is completely upward compatible with terminal and graphics. Given a single fixed screen, windows subdivides the screen into virtual windows, which can be set to any size or position. A terminal compatible program sees its window as a "virtual screen", and does not know that some or all of the contents of that screen may be hidden. A windows aware program can participate in the benefits of a windowed environment.

L.1 Screen Appearance

The idea of windows management is to take a program that thinks it is talking to an ordinary terminal, and allow the presentation of multiple such windows within a single screen.

By default, windows emulates a terminal interface for each window that is identical to the behavior of a full screen window from the programs' point of view. A standard size screen is implemented for the program of 80 characters by 25 lines (even if the real display has a different size). windows accepts program writes, and places that information in a buffer that looks like an ideal screen. Then, the contents of that buffer are placed on the screen in various arrangements to complete the desktop for the user.

L.2 Window Modes

A window can be any actual size on the display. A window can also be off the display entirely, so that it accepts changes to its buffer, but does not display those changes. In addition, a window can be active, inactive, or overlapped, or even completely covered by other windows on the display.

L.3 Buffered Mode

A window comes up by default in the "buffered" mode. In buffered mode, the program has a "virtual display surface" that it writes to. windows maintains this surface in memory, and maintains the actual onscreen window as a scrolled window on that. The program is unconcerned with what part of its screen is being displayed, or even if it is displayed at all. The user operates the window using the frame controls.

Buffered mode is designed to allow the program to be unconcerned with the management of the display. However, the program can set the size of the virtual display using sizbuf[g](f, x, y). When a buffer is resized, its contents is cleared to the current background color.

The buffer is a display surface that the buffer handler keeps for the program. The buffered mode allows a program to "think" it has a window of size N, but the appearance of the window on the actual display is a window on that virtual display that is maintained by the buffer handler.

Because from the programs point of view the window size does not change, and is always the complete window, the resize events are performed transparently to the program. Similarly, the minimize and maximize events are handled for the program (see L.4 “Unbuffered Mode”). Discovery is when a window or part of a window is uncovered on the display.

When in buffered mode, the window manager is may use scroll bars to display within a screen view that is smaller than the buffer.

Although buffered mode automatically handles window status events (covered in L.4 “Unbuffered Mode”), these events are still sent through. For maximum compatibility, the using program should ignore any events not relevant to the mode it is in.

L.4 Unbuffered Mode

The program can leave buffered mode by using buffer(f, b). Unbuffered mode has no display buffer, and no default actions for events. Instead, the onscreen appearance of the window is set dynamically by the program.

When unbuffered mode is entered, the buffer for the window is discarded, and it becomes entirely up to the program to manage its own window by watching events. The size of the window no longer reflects the buffer, but instead is the size of the onscreen window. In contrast to buffered mode, this can change many times as the window is resized under user control.

Buffered mode can be reentered at any time. The contents of the buffer are cleared to spaces.

When running unbuffered, it is assumed that the program will manage the update of the on-screen display surface itself. When running unbuffered, the program handles events that are normally handled automatically.

The etredraw event contains the limits of an update rectangle that shows what part of the client area needs to be redrawn on the screen. The program can ignore the update rectangle, and simply redraw the entire screen, or it may only redraw the figures that overlap the update rectangle. The latter is usually more time efficient. etredraw gives its update rectangle in character coordinates. There is also a pixel version of that, etredrawg, which uses pixel coordinates. On a graphical system, both messages will be sent, and they duplicate each other. The character coordinate etredraw will contain a rectangle of characters that at least covers the pixels that need to be redrawn in a graphical system. Since etredraw and etredrawg duplicate each other, only one of them should be obeyed, and the other ignored.

The etresize event indicates that the onscreen window has changed its size. Its purpose is to let the program update any calculations based on the size of the window. This event can be ignored, used to update stored maxx[g] and maxy[g] values, or it could even cause the entire arrangement of the screen to be reformed.

etresize is not normally used to redraw areas of the screen. If a resize event causes new screen area to be uncovered, then one or more etredraw events will also be sent. There is no way to determine exactly which redraw operations correspond to the resize event, so some redundancy is possible with applications that repack their window's contents on a resize.

The etmin event indicates that the window has been minimized. When a window is minimized, it will not be displayed, and won't receive etredraw events. On the desktop, the window is represented by a small icon. An alternative form of minimization is for the window to receive an etmin message, followed by a etresize message, and continued etredraw messages. This a hint for the window to display vital information in a much smaller format that fits into the minimized icon.

The etmax event indicates that the window has been maximized, or covers the entire desktop. If the window needs to be updated, this event may be accompanied by etresize and etredraw events.

The etnorm event indicates a normal window mode has been resumed from etmin or etmax.

L.5 Defacto transparency

Using unbuffered mode, it is possible to achieve window transparency. Transparency means that some parts of the window will show through to the display surface underneath the window. This can be used to implement advanced effects like non-rectangular windows, and it is the basis for widgets (which appear in M “Widget Library”). For defacto transparency to work, the drawing order of windows must be tightly controlled.

L.6 Delayed Window Display

When a window is created, it is not displayed until an actual write operation is made to it. This allows the window to be changed in configuration by the program before it is displayed, and prevents the window being rapidly changed on screen as that happens. For example, the program might want to take the window out of buffered mode, change its size, remove the frame, or add menus.

L.7 Window Frames

Under most window systems, each window has a "window frame", which has various window management functions. These include:

· Move bars to resize and move the window.

· A title bar that indicates what program is running in the window.

· A "minimize" button.

· A "maximize" button.

· A "menu" bar.

· Vertical and horizontal scroll bars.

When a window is in buffered mode, none of the frame features are under the control of the program, but instead are managed by the buffering software.

The appearance, or even the existence, of any of these items can be customized by the program. The frame can be enabled or disabled by frame(f, e), where f is the window file, and e is true to enable the frame. The title can be set by title(f, e). The title, minimize and maximize buttons are considered part of the "system bar", which can be enabled or disabled by sysbar(f, e). The resize bars are enabled or disabled by sizable(f, e). The scroll bars are enabled and disabled by scrollv(f, e) and scrollh(f, e).

The frame control functions frame, title, sysbar and sizable are optional within an implementation. The system may not allow an application to, for example, disable its sizing bars, or it may not have a set of system controls on the window. The program must be ready for these commands not to have an effect. For example, after the sizeable function is set false, it should still be ready to receive a new size. If, for example, the size of the graphic to be presented is a fixed size, it would be filled out or clipped to fit the resulting window.

L.8 Scroll Bars

A window can optionally have vertical and/or horizontal scroll bars. The actual meaning of the scroll bars is up to the program. Each of the scroll bars can generate several events. The vertical scroll bar generates etsclvul and etsclvdl for line up and line down, and etsclvup and etsclvdp for page up and page down. The horizontal scroll bar generates etsclhll and etsclhrl for line left and line right, and etsclhlp and etsclhrp for page left and page right. The meaning of these messages are oriented around text. Line movements mean to move a single character (even though for left right the term “line” is close to a misnomer). Page movements mean to move a complete screens worth.

When the slider bar for a scroll bar is moved, the new position is indicated with etsclvpos and etsclhpos, for vertical and horizontal scroll bar positions. The position is given as a maxint ratio, where 0 means the top or left of the scroll bar, and maxint means the bottom or right of the scroll bar.

It is common that when one or both of the scroll bars is present on a window that the space where they intersect is occupied by a “move tab”. This serves to resize the window in two directions, and generates standard resize messages to the window.

L.9 Multiple Windows

If the output file appears in the program header, then that is output as the main window by default. A window can also be explicitly opened by openwin(inw, outw, id). When a new window is opened, it is placed on the desktop with the other windows. The text files inw and outw specify the input and output files attached to the window. The input file receives all user input and events from the window, and all of the write and other drawing operations are sent to the output file. The id is a number, from 1 to N, that specifies the logical window. The logical window number 1 is reserved for the standard input and output pair, even if it is not specifically opened, since it can be opened by the program at any time.

The output side of a window must always be unique, but the input side can be shared. Multiple windows can be attached to a single input file, and that input file will receive all of the input and events from all attached windows. The logical window number is returned with each event, so that the source of the input or event can be determined. This forms the bases of “class window handling” (L.13 “Class Window Handling”), or using one input handler as to handle multiple windows.

To completely decouple separate windows, another thread is used to run the separate window. This can be done, for example, to create a widget library that does not depend on the event handler of the calling module.

Windows can be closed using the standard Pascaline close call. Only the output side of a window is used to close that window. The input side is automatically closed when there is no longer a window that references it.

L.10 Parent/Child Windows

Windows systems are tree structured, and each window is a child of a parent window, with the exception of a "root" or master window, which is usually the window that contains the entire desktop. The methods introduced create windows that live side by side on the desktop, and have the desktop as their parents. However, it is possible to nest windows within each other.

A window is opened as a child by openwin(inw, outw, par, id), which is the same openwin call with a parent specified. The parent file par is the text file that is attached to the output window of the parent. To be a child window means to move as one within it. It maintains its position within the parent, even as the parent itself moves. It always is in front of the Z ordering for the parent. It is minimized, maximized and closed with the parent.

All windows have their position given in relative terms to the parent's client area origin. Any position operation is also relative to the parent.

The common use of the parent is to create "sibling" windows, or windows equivalent to the default program window in status, that are positioned independently within the parent. A program starts as the child of an external parent window. This could be an actual program, such as a program acting as a manager, or it could be the desktop root. There is no difference between these for the program.

Programs do not have direct access to the parent window in which the program was created. That parent window is usually the desktop.

L.11 Moving and Sizing Windows

Moving a window is done with the setpos[g](f, x, y) procedure. The position is given in parent coordinates. When a window is on the desktop, it is necessary to find the size of the desktop, which is found with scnsiz[g](f, x, y). When the desktop size is returned for character sizes, this is calculated using the current character sizes for the window. This is for comparative purposes only. The desktop may use a completely different set of characters and sizes. The purpose of giving the parent sizes is only to allow the program to determine the relative size and placement of the child window in the parent.

Sizing a window is done with setsiz(f, x, y) procedure. This sets the size of the entire window, and so does not indicate the resulting size of its client area. To find out what window size is needed for a given client area, before actually sizing the window, the function winclient[g](f, cx, cy, wx, wy, ms) is used. It returns the window size needed to contain that client. winclient[g] takes a set of the current modes of the window to enable it to make the size determination.

The mode set declaration is:

{ windows mode sets }

winmod = (wmframe, { frame on/off }

wmsize, { size bars on/off }

wmsysbar, { system bar on/off }

wmscrollv, { vertical scroll bar on/off }

wmscrollh); { horizontal scroll bar on/off }

winmodset = set of winmod;

To find the current size of a window, in parent terms, the procedure getsiz[g](f, x, y) is used. This procedure is useful when you need to find the size of a window on the desktop.

L.12 Z Ordering

The Z ordering, or back to front ordering of windows, is determined by default to be newest created windows to the front, oldest to the back. This order can be modified by the users when they select windows towards the back to come to the front. The program can also reorder windows at will by sending them to the front or back. Note that the Z ordering is always relative within a parent.

To send a window to the front, the call front(f) is used. To send a window to the back, the call back(f) is used. To achieve a specific order within a set of windows, they should be send to the front in the opposite order from which they are to appear, i.e., the backmost first, and the frontmost last. Alternately, the windows can be sent to the back in the order they appear.

There are other reasons besides reordering windows that these functions might be useful. When an error in encountered, it is common to send a window containing the error message to the front of the parent Z order, and to send the entire window to the front. Placing an active display or a background pattern in a frameless maximized window can create wallpaper. Placing the same window in the back can be a screen saver.

L.13 Class Window Handling

windows handles windows as a set of two files, the input and output. However, these don't need to always be a set. It is possible to reuse an already open input file as the input side of any new window. This is possible because the user id supplied when the window is opened is passed with all messages to the event procedure.

Allowing a single program thread to handle multiple open windows allows the creation of multiple window programs without the need to create a multitask program. For each message, the id is examined, and the action performed on the appropriate output file.

Because the output file is unique, it is always the handle used to refer to the window in management calls.

L.14 Parallel Windows

Parallel tasking is a natural match to a multiwindowing system. With a task created to operate each window, the program is simplified, and user response is generally better.

To increase the responsiveness of user interfaces, the recommended program design for windowing programs is to create two tasks for each window, the "foreground" and the "background" tasks. The foreground task performs the event loop and the redraw, resize, move and other user interface tasks. The background task would handle computation tasks and other tasks related to performing actions or changing the drawing surface. The foreground task determines if an action that requires the background task is required, then sends a command to the background task via a monitor queue or other IPC (Interprocess communication).

The reason for this construction is that the things the user sees, such as keeping the client area redrawn, or obeying a move, resize, minimize or similar command always have a task waiting to perform them. This means that elementary user desktop management appears responsive to the user, while data manipulation and computation tasks simply delay client area updates. Users will be much more willing to tolerate client area slowdowns than having a window apparently lock stubbornly in position.. Ideally, the client area should also have an indication that computation is taking place. The most modern method for this is a progress indicator that gives estimates as to when a task will complete, if the task will take longer than about 1 second.

A parallel foreground task is automatically provided for a buffered mode window. It needs to be created in the case of an unbuffered window.

If the work performed in a client area is trivial, only a foreground task need be provided. But be aware that it is very easy to slip into a mode where essential updates are held off. Calling a file procedure, waiting on a timer, or other simple task compromises the response time for window management. Better to leave the window in buffered mode, or structure with foreground/background from program creation than to have to add it later.

L.15 Menus

The menu is a series of buttons labeled with text for user action. The buttons can either have a direct effect on the program, or they can activate a series of submenus in a tree structure.

The exact location of a menu is system dependent. It may or may not affect the client area.

A menu is described to windows by constructing a data structure:

menuptr = ^menurec;

menurec = record

next: menuptr; { next menu item in list }

branch: menuptr; { menu branch }

onoff: boolean; { on/off highlight }

oneof: boolean; { "one of" highlight }

bar: boolean; { place bar under }

id: integer; { id of menu item }

face: pstring { text to place in button }

end;

The menu is activated by menu(f, m) where m is the data structure for the menu.

Menu buttons are highlighted when pointed to. Additionally, a button can have "on/off" highlighting. In this mode, a state is kept for the button that is flipped on or off as the button is pressed. The highlighting for on and off states is different. The data structure that defines a menu is not used or updated after it is used to create a menu.

The onoff field true selects on/off highlighting. After the menu is activated, the state of the button can be changed with menusel(f, id, e). The button state is not automatically changed by a user menu select. The program must specifically change the state of the button.

Another highlight mode is "one of" or "checklist" highlighting. In this case, a group of related buttons are joined by setting the oneof flag on each item in the list but the last. The highlighting for a button that is selected is different from one that is not, and only one item will be active in the list.

Like on/off buttons, user selection does not automatically change the state of the buttons in the list. It must be specifically changed by a menusel call.

Typically, neither on/off nor one/of switching is available for top level (horizontal) menus, and the program should not count on them.

Menu items can be grouped in a vertical list by setting the bar field active. This causes a horizontal bar to be drawn under the menu item. Vertical lists are described next in "menu sublisting".

A button can be enabled or disabled. A disabled button is highlighted specially, typically as greyed out. It indicates a button that is entirely inactive, because that function is not available. This is done to allow the same menu to be used regardless of the availability of the functions on the menu. Also, some functions come and go. For example, a "save" button (for "save file") might only be active if the file has changed, and needs to be saved.

The enable status can be changed after the menu is activated by menusel.

Each button in a menu can have a numeric id. This is used by several functions to change the state of buttons. It is an error to have two buttons with the same id.

The face text string indicates what text will appear on the face of the button. The system will automatically size the buttons to fit the largest text of a button, so care should be taken not to have a single button's text so long as to cause a lot of white space in the menu.

L.16 Setting Menu Active

A menu is constructed by the program as a list using the menu data structure, then set active by calling menu, which can also turn the menu back off.

When a menu data structure is activated, all of the fields are copied and placed into an internal form. After the activation, the menu data has no function, and changing its fields will have no effect. The menu data structure can be recycled immediately after the menu call.

L.17 Setting Menu States

For an on/off button, the procedure menuena(f, id, e) is used to enable or disable the button after it has been placed in a menu. For oneof highlighting, the procedure menusel is used. This removes any other select active, and either sets the given button active, or no button active.

L.18 Standard Menus

Besides presenting a menu in the method standard for the implementation, it is also likely that there exists a standard arrangement of commonly used buttons in the menu. windows defines a series of such standard buttons.

{ standardized menu entries }

smnew = 1; { new file }

smopen = 2; { open file }

smclose = 3; { close file }

smsave = 4; { save file }

smsaveas = 5; { save file as name }

smpageset = 6; { page setup }

smprint = 7; { print }

smexit = 8; { exit program }

smundo = 9; { undo edit }

smcut = 10; { cut selection }

smpaste = 11; { paste selection }

smdelete = 12; { delete selection }

smfind = 13; { find text }

smfindnext = 14; { find next }

smreplace = 15; { replace text }

smgoto = 16; { goto line }

smselectall = 17; { select all text }

smnewwindow = 18; { new window }

smtilehoriz = 19; { tile child windows horizontally }

smtilevert = 20; { tile child windows vertically }

smcascade = 21; { cascade windows }

smcloseall = 21; { close all windows }

smhelptopic = 22; { help topics }

smabout = 23; { about this program }

smmax = 23; { maximum defined standard menu entries }

{ standard menu selector }

stdmenusel = set of smnew..smmax;

Standard menu button definitions should be used whenever possible. To create a menu using standard menu buttons, the procedure stdmenu is used. The arrangement of the menu is chosen to match the implementation, and the non-standard buttons provided are integrated into the menu in the normal place for the implementation. When standard buttons are used, the button ids are set to the values shown above, so these values should not be used by the program.

Note that stdmenu simply constructs a menu, it does not set it active.

L.19 Menu Sublisting

When there is not enough room to represent the entire menu on a window, or anytime the size of a menu must be compressed, the tree structure of menus can be used with "pulldown" menus. A pulldown menu is a vertical menu list that appears under the selected button. This is done by placing a submenu in the branch pointer of the menu structure. The branch defines the pulldown menu items. The branch menu item is specially indicated to show that it is a branch, and not an immediate button, usually with an arrow pointing towards where the branch pulldown will appear. Any number of levels of pulldown menus can be created. The levels under the topmost branch are generally placed to the right of the branch button.

If a branch pulldown cannot be placed where it should, due to the proximity of the button to the edge of the display, it instead goes back in the other direction, up or down, or both, until space is found for it. If the entire pulldown cannot be displayed, it is truncated. This would only happen if the pulldown was too large for the display.

When a branch button is pressed, no event is generated for it. The button is strictly used to activate the pulldown.

L.20 Advanced Windowing

The features of a window besides the client area are designed to be the minimum features implemented across platforms. To implement more advanced windows appearances with custom menus, controls and status lines, the standard method is to turn off frames and menus for child windows, and use them as building blocks for more advanced client areas with multiple subwindows and features.

It is recommended that at least one menu appear for a program, even if the functions duplicate some of the advanced controls provided. The reason for this is that the menu has different presentation methods in different systems, so providing the standard "top" menu will help programs' portability.

L.21 Events

New event types are added for the management mode. As usual, events beyond the definition here should be ignored.

module windows;

type

{ events }

evtcod = (etchar, { ANSI character returned }

etup, { cursor up one line }

etdown, { down one line }

etleft, { left one character }

etright, { right one character }

etleftw, { left one word }

etrightw, { right one word }

ethome, { home of document }

ethomes, { home of screen }

ethomel, { home of line }

etend, { end of document }

etends, { end of screen }

etendl, { end of line }

etscrl, { scroll left one character }

etscrr, { scroll right one character }

etscru, { scroll up one line }

etscrd, { scroll down one line }

etpagd, { page down }

etpagu, { page up }

ettab, { tab }

etenter, { enter line }

etinsert, { insert block }

etinsertl, { insert line }

etinsertt, { insert toggle }

etdel, { delete block }

etdell, { delete line }

etdelcf, { delete character forward }

etdelcb, { delete character backward }

etcopy, { copy block }

etcopyl, { copy line }

etcan, { cancel current operation }

etstop, { stop current operation }

etcont, { continue current operation }

etprint, { print document }

etprintb, { print block }

etprints, { print screen }

etfun, { function key }

etmenu, { display menu }

etmouba, { mouse button assertion }

etmoubd, { mouse button deassertion }

etmoumov, { mouse move }

ettim, { timer matures }

etjoyba, { joystick button assertion }

etjoybd, { joystick button deassertion }

etjoymov, { joystick move }

etterm, { terminate program }

etmoumovg, { mouse move graphical }

etframe, { frame sync }

etresize, { window was resized }

etredraw, { window redraw }

etmin, { window was minimized }

etmax, { window was maximized }

etnorm, { window set normal }

etmenus, { menu item selected }

etsclvul, { scroll vertical up line }

etsclvdl, { scroll vertical down line }

etsclvup, { scroll vertical up page }

etsclvdp, { scroll vertical down page }

etsclvpos, { scroll vertical bar position }

etsclhll, { scroll horizontal left line }

etsclhrl, { scroll horizontal right line }

etsclhlp, { scroll horizontal left page }

etsclhrp, { scroll horizontal right page }

etsclhpos, { scroll horizontal bar position }

{ event record }

evtrec = record

winid: ss_filhdl; { identifier of window for event }

case etype: evtcod of { event type }

{ ANSI character returned }

etchar: (char: char);

{ timer handle that matured }

ettim: (timnum: timhan);

etmoumov: (mmoun: mouhan; { mouse number }

moupx, moupy: integer); { mouse movement }

etmouba: (amoun: mouhan; { mouse handle }

amoubn: moubut); { button number }

etmoubd: (dmoun: mouhan; { mouse handle }

dmoubn: moubut); { button number }

etjoyba: (ajoyn: joyhan; { joystick number }

ajoybn: joybut); { button number }

etjoybd: (djoyn: joyhan; { joystick number }

djoybn: joybut); { button number }

etjoymov: (mjoyn: joyhan; { joystick number }

joypx, joypy, joypz: integer); { joystick coords }

etfun: (fkey: funky); { function key }

etmoumovg: (mmoung: mouhan; { mouse number }

moupxg, moupyg: integer); { mouse movement }

etredraw: (rsx, rsy, rex, rey: integer); { redraw screen }

etmenus: (menuid: integer); { menu item

selected }

etup, etdown, etleft, etright, etleftw, etrightw, ethome,

ethomes, ethomel, etend, etends, etendl, etscrl, etscrr,

etscru, etscrd, etpagd, etpagu, ettab, etenter, etinsert,

etinsertl, etinsertt, etdel, etdell, etdelcf, etdelcb, etcopy,

etcopyl, etcan, etstop, etcont, etprint, etprintb, etprints,

etmenu, etterm, etframe, etresize, etmin, etmax,

etnorm: (); { normal events }

{ end }

end;

begin ! windows

end.

L.22 Event callbacks

As in terminal, the events can also be accessed via a series of virtual procedures. Only one new event procedure exists in the graphics module over the original event procedures in terminal:

module windows;

virtual procedure etresize; begin end;

virtual procedure etredraw(rsx, rsy, rex, rey: integer); begin end;

virtual procedure etmin; begin end;

virtual procedure etmax; begin end;

virtual procedure etnorm; begin end;

virtual procedure etmenus(menuid: integer); begin end;

virtual procedure etsclvul; begin end;

virtual procedure etsclvdl; begin end;

virtual procedure etsclvup; begin end;

virtual procedure etsclvdp; begin end;

virtual procedure etsclvpos(p: integer); begin end;

virtual procedure etsclhll; begin end;

virtual procedure etsclhrl; begin end;

virtual procedure etsclhlp; begin end;

virtual procedure etsclhrp; begin end;

virtual procedure etsclhpos; begin end;

virtual procedure etsclhpos(p: integer); begin end;

begin ! graphics

end.

L.23 Window Objects

All of the procedures, functions and other declarations in windows are also available in a window object. of the form:

module windows;

class window;

var input, output: text; ! input and output files

er: evtrec; ! event record

winid: ss_filhdl; ! window logical identifier