4 Extensions to the Language in p1 Modula-2

4.2 Pragmas

The following pragma variables are already known to the compiler (cf. 4.3.3):

Name	Meaning	Notes
IndexCheck	Monitor array indices (for under-/overflow)	1, 4
PointerCheck	Test for NIL pointer / EMPTY reference (on deref)	1, 4
RangeCheck	Monitor subrange values (for under-/overflow)	1, 4
ComplexCheck	Separate checks for complex arithmetic (see below)	1, 4
OverflowCheck	Test for overflow in whole-number arithmetic	1, 4
DivZeroCheck	Test for division by 0
StackCheck	Test for stack overflow	4
Warnings	Include warnings in compiler error-output
CopyRefparams	Copy reference (i.e. value) parameters	1, 5
PragmaCheck	Issue warnings if unknown pragmas encountered
SpecialStrings	Interpret "\" as meta-symbol in strings	2
CastRegister	Type casting in registers (see below)
FixedSubrangeSize	Size of subrange types (cf. 5.3.1)	7
Vector	AltiVec extensions (cf. 4.6)	6
Floatopt	Floating point optimization (see below)
Foreign	Generate foreign module	2
UpperCaseNames	Completely capitalize variable names for linker	3
Calling	Use different calling sequence (see below)
Reference	Reference parameter (see below)
ForeignEntry	External module initialization (cf. 4.4.2.3)
EntryName	Linker name (see below)
AlignBorder	Alignment control (see below)
InvertBranches	Control of branch prediction (cf. 5.3.14)
ISA	target code	6
ARCH	target architecture	6
OptLevel	Optimization level (see below)
p1	Always TRUE	6, 7
StonyBrook	Always FALSE	6, 7

The value of the pragma variable "CastRegister" effects only ppc code as for Power processors, byte ordering differs between registers and memory. If the value "TRUE" is assigned to the pragma variable "CastRegister", then casting of ordinal types is performed according to register allocation conventions instead of memory allocation conventions. As variables are allocated left justified in memory but right justified in a register, a call of e. g. "CAST (CAST16, card32variable)" accesses the two rightmost bytes in register, but the two leftmost bytes in memory.

The values ""CCalling"", ""CByRef"", ""Pascal"" and ""Default"" can be specified for the pragma variable "Calling" (cf. 4.4.1).

If "TRUE" is assigned to the pragma variable "Reference" the following (value) parameter is passed by reference (cf. 5.3.4).

Any string which is usable as an external linker name can be specified for the pragma variable "EntryName". (see also section 4.4.2.1 / 4.4.2.2).

The values "ALIGN1", "ALIGN2", "ALIGN4", "ALIGN8", and "ALIGN16" can be specified for the pragma variable "AlignBorder" (cf. 5.3.1).

The pragma variable "ARCH" allows to check for the target architecture. Actually, the values "ppc" (PowerPC code generation), "i386" (Intel 32-bit code generation), and "x86" (Intel 64-bit code generation) may be returned.
These values are meaningful if the C back end is used too.

The pragma variable "ISA" (Instruction Set Architecture) is still supported for backward compatibility. Actually, the values "ISAPPC" (PowerPC code generation), "ISAi386" (Intel 32-bit code generation), and "ISAx86" (Intel 64-bit code generation) may be returned.

The pragma variable "OptLevel" allows to check for or set the actual optimization level. In the current implementation the values 0, 1, and 2 are accepted (cf. section 1.2).

If the pragma variable "Floatopt " is set to "TRUE ", multiply add / multiply subtract instructions are used in PowerPC code where possible.

All the other pragma variables take logical values.

If the pragma variable "ComplexCheck" is set to "TRUE", additional code is generated to distinguish between exceptions in real arithmetic and exceptions in complex arithmetic. If this variable is set to "FALSE", complex arithmetic exceptions are reported as real arithmetic exceptions. In standard mode "ComplexCheck" always has the value "TRUE".

Notes:

1. In standard mode always has the value "TRUE".
2. In standard mode always has the value "FALSE".
3. Can only be used when "Foreign" is set to "TRUE". This means that in standard mode "ASSIGN (UpperCaseNames, FALSE)" and "ASSIGN (Calling, "Default")" are both implicitly set without warning cf. 4.4.1).
4. The corresponding run-time tests can be turned on ("TRUE") and off ("FALSE") using these pragmas.
5. Controls the way large value parameters are passed (cf. 5.3.4).
6. Read only variable.
7. Useful if the same sources are also compiled with other compilers, especially Stony Brook Modula-2.

4.3 Conditional Compilation

Compilation is controlled by so-called compile-time variables which can be assigned values using special pragmas (and also from the command line). Their values can then be determined using relational expressions. The values "TRUE" and "FALSE" have special meanings. Variables which can take on these and only these values behave like "BOOLEAN" variables. Expressions used in conditions always have to have the type "BOOLEAN".

4.3.1 Syntax of Conditional Compilation Directives

4.3.2 Compile-Time Variables

4.3.3 Examples

FROM <* IF LONG THEN *> LongMath <* ELSE *> RealMath <* END *> IMPORT sqrt;
The function "sqrt" is imported either from "LongMath" or from "RealMath" depending on the value of compile-time variable "LONG".

<* IF RANGE THEN RangeCheck (TRUE); END *>
If "RANGE" is specified, subrange monitoring is turned on.

<* ENVIRON (TARGET, "MAC") *>
The variable "TARGET" is defined and given the value ""MAC"", unless it was assigned a value in the command line, in which case it receives that value.

<* IF NOT test THEN *> x := 1; <* END *>
The assignment will only be included in the program if the compile-time variable "test" has the value "FALSE".

4.4 Interfacing to Other Languages

4.4.1 Calling Foreign Code Modules from Modula-2

An interface module consists solely of a definition module. It is in fact impossible to compile a corresponding Modula-2 implementation module (the foreign software takes its place after all). Textually an interface module differs from a simple definition module only in having the normal module head preceded by the pragma "<* ASSIGN (Foreign, TRUE) *>". For example:

    <* ASSIGN (Foreign, TRUE) *>
    DEFINITION MODULE Memory;

All programming languages which pass parameters via standard conventions are supported. The programmer is responsible for ensuring that the interface ties in correctly by appropriately mapping parameter types (and possibly also their order) in the foreign software segment. One limitation worth mentioning: no other popular programming language has anything corresponding to Modula-2's concept of open arrays. (see also sections 5.3.2 / 5.3.3 parameter passing.)

• Linker symbols generated by the compiler for procedures from interface modules are identical in all respects to the procedures' names in the module. (Exceptions: see Pascal and C procedures.)
• Variables can also be declared in interface modules. In such cases the compiler uses the usual system mechanisms for references instead of the special p1 Modula-2 method.
• Normal register usage is assumed by the compiler for procedures from interface modules (cf. 5.3.9 / 5.3.10 Register Usage). Exceptions: see Pascal and C procedures.
• The pragma "<* ASSIGN (Calling, method) *>" can be used to make allowances for the specific parameter-passing peculiarities of individual languages.

In particular, two different kinds of procedure interface are supported by the compiler:

1. The programming language C
2. The programming language Pascal

Examples for interfacing to Pascal are given by the Universal Definition Files which are (for the most part automatically) derived from the universal header files written in Pascal.
The definition files for HIToolbox give an example for converting C header files to Modula-2. They contain the original C code as comments, so that the more complex type matching can be followed.

4.4.1.1 Interfacing to C

• The calling of C procedures may be specified by the calling conventions "CCalling" and "CByRef".
• The calling conventions "CCalling" corresponds to the "standard C conventions". If "CByRef" is specified, for large value parameters (size of more than 4 bytes, except parameters of type "LONGREAL") only the address is passed on the stack (as with Modula-2 or Pascal). This allows to avoid the pointers typically used in C programs for this case. Examples for interfacing to C:

          <* ASSIGN (Calling, "CCalling") *>
          PROCEDURE exit (code: INT32);
          <* ASSIGN (Calling, "CByRef") *>
          PROCEDURE useThisRect (r: Rect);
          (* void useThisRect (const Rect *r); *)

• If you need to have explicit control whether a parameter is passed by value or by reference you specify <* ASSIGN (Calling, "CCalling") *> and additionally <* ASSIGN (Reference, TRUE) *> before every parameter you want to pass by reference. Examples can be found in the Universal Definition files.
• All stack and register conventions are identical.
• The types "COMPLEX" / "LONGCOMPLEX" have no corresponding type in C and have to be passed as RECORDs.
• Open array parameters are passed without the "HIGH" value and so correspond exactly to pointers in C.

4.4.1.2 Interfacing to Pascal

• Calling conventions for procedures written in Pascal are specified by assigning "Pascal" to the pragma variable "Calling". Parameters are passed with the same conventions as used for Modula-2.
• The types "COMPLEX" / "LONGCOMPLEX" have no corresponding type in Pascal and have to be passed as RECORDs.

4.4.2 Calling Modula-2 Procedures from Other Languages

In this case, the main procedure must not be defined in the Modula-2 runtime, so the Modula-2 library has to be replaced by "libm2libforeign.a".

4.4.2.1 Calling Conventions

    <* ASSIGN (Calling, "CCalling") *>
    PROCEDURE name (...);

Similarly, procedure types can be declared like this:

    <* ASSIGN (Calling, "CCalling") *>
    TYPE name = PROCEDURE (...);

A procedure type of this kind is not compatible to procedures with default calling conventions. If only the address shall be passed for value parameters of structured types, the calling convention "CByRef" may be specified instead of "CCalling". In this case the parameters have to be declared as "const MyType *", "const MyType&", or something similar in the corresponding C header file.

Modula-2 procedures which conform to C calling conventions (like the examples above) can also be called from Modula-2 without taking any special precautions: the compiler automatically takes these conventions into account when such procedures are called.

The pragma variable "EntryName" allows to specify a linker name in addition to the internal compiler name, e.g. the original procedure name:

    <* ASSIGN (Calling, "CCalling") *>
    <* ASSIGN (EntryName, "MyExternalName") *>
    PROCEDURE MyName (...);

Defined this way, the procedure "MyName" may be called from a C program also via "MyExternalName".

4.4.2.2 Runtime- and module initialization

When required, the initialization of the Modula-2 runtime system (including the execution of the module initialization parts) can be invoked manually. The runtime system provides for the following auxiliary procedures (the headings are written according to Modula-2 conventions):

• PROCEDURE M2InitModule ()
  Calls the initialization parts of all Modula-2 modules, but it does not initialize the p1 Modula-2 trap handling, i. e. no hardware traps will be processed by the Modula-2 runtime system.
  
• PROCEDURE M2InitAll (handler: PROC)
  Like "M2InitModule", but Modula-2 trap handling is always initialized and a global exception handler may be passed (NIL for none). This parameterless handler procedure will be called for unhandled exceptions. If the handler returns, the program will be terminated by a call to "exit".
• PROCEDURE M2Terminate ()
  Calls the finalization parts of all initialized Modula-2 modules, but does not terminate the program. The module order is the reverse initialization order (like with ordinary Modula-2 programs).
• PROCEDURE M2SetHaltProc (halt: PROC)
  When a call to HALT ist made for Modula-2 code that is initialized by "M2InitModule" or "M2InitAll", the program merely terminates (without invoking the termination chain). With "M2SetHaltProc" a procedure may be specified that is called instead of terminating. This procedure is allowed to do whatever is appropriate, especially invoke the termination chain. If execution is to be stopped, this procedure has to call "exit" itself, otherwise the program is continued. Recursive calls to "M2Terminate" are allowed, as each module guarantees itself to terminate only once.

4.5 Dynamic Arrays

4.5.1 Declaration of the Data Structure

For multi-dimensional arrays "ARRAY OF" is specified according to the number of dimensions. The declaration of dynamic arrays is a normal type declaration, it may be used in any place a type declaration is possible.

Like with open arrays the index range starts at "0", is a subrange of "CARDINAL", and reaches up to the top index specified on allocation (cf. 4.5.2).

4.5.2 Allocation / Deallocation of Storage

VAR
    matrix: POINTER TO ARRAY OF ARRAY OF REAL;
BEGIN
    NEW (matrix, 5, 10);

Using "ALLOCATE"directly to allocate storage for a dynamic array is not allowed and results in an illegal program as the data structure for the index descriptors is not set up, though the compiler cannot check whether "ALLOCATE" is used directly to allocate storage.

Deallocation of storage is done by "DISPOSE" as usual.

4.5.3 Operations on Dynamic Arrays

• Indexing (i.e. access by element)
• Use of "HIGH"
• Use as actual parameter for an open array formal parameter.
• "SIZE" may be used but returns only the amount of space used by the data (excluding the index descriptors). "SIZE (matrix^)" in the above example returns the value of "264".

4.6 Support for the AltiVec instruction set

The AltiVec instruction set for vector operations available on G4 and G5 processors is supported by p1 Modula-2 in a wide range. The new key word "VECTOR" is used to define the according data types. As far as appropriate the predefined index operations are overloaded for vector types. Additionally, procedures or functions are defined in the pseudo module "VECTORS" to make available each machine instruction. This functions expand with one exception to exactly one AltiVec instruction so that no code overhead is produced. The necessary alignment to 16 byte boundaries for vector variables is forced automatically; only for dynamically allocated storage the allocation mechanism has to guarantee alignment on 16 byte boundaries (cf. 4.6.3).

4.6.1 New language elements for vector operations

To make the language elements for vector operations available, the given module has to be compiled with the command line option "-VECTOR". The pragma variable "Vector" reflects the value of this command line option to allow conditional compilation depending on activated vector support.

Vector data types are very similar to array types. The type declaration has the form:
VECTOR OF ElementType
where "ElementType" denotes one of the following types: "REAL", "CARD8", "CARD16", "CARD32", "INT8", "INT16", "INT32", "SET8", "SET16", "SET32", or any compatible type.

Access to vector elements is possible by indexing, the index range is
[0 .. TSIZE (VectorType) / TSIZE (ElementType) - 1].
Value constructors are supported, the syntax is equal to the syntax of value constructors of arrays.

The following operators are overloaded for vector operations with the given element type:

4.6.2 The Module "VECTORS"

Like "SYSTEM", "VECTORS" is also a pseudo-module and therefore does not have a symbol file in p1 Modula-2.

4.6.2.1 The Pseudo Definition-Module "VECTORS"

DEFINITION MODULE VECTORS;
TYPE
    INT8VECTOR = VECTOR OF INT8;
    INT16VECTOR = VECTOR OF INT16;
    INT32VECTOR = VECTOR OF INT32;
    CARD8VECTOR = VECTOR OF CARD8;
    CARD16VECTOR = VECTOR OF CARD16;
    CARD32VECTOR = VECTOR OF CARD32;
    SET8VECTOR = VECTOR OF SET8;
    SET16VECTOR = VECTOR OF SET16;
    SET32VECTOR = VECTOR OF SET32;
    REALVECTOR = VECTOR OF REAL;

    VecAbs (<vector>): <vector>;
    VecAbss (<vector>): <vector>;
    VecAdd  (<vector>, <vector>): <vector>;
    VecAddc  (<vector>, <vector>): <vector>;
    VecAdds  (<vector>, <vector>): <vector>;
    VecAnd  (<vector>, <vector>): <vector>;
    VecAndc  (<vector>, <vector>): <vector>;
    VecAvg  (<vector>, <vector>): <vector>;
    VecCeil (<vector>): <vector>;
    VecCmpb  (<vector>, <vector>): <vector>;
    VecCmpeq  (<vector>, <vector>): <vector>;
    VecCmpge  (<vector>, <vector>): <vector>;
    VecCmpgt  (<vector>, <vector>): <vector>;
    VecCmple  (<vector>, <vector>): <vector>;
    VecCmplt  (<vector>, <vector>): <vector>;
    VecCtf  (<vector>, <vector>): <vector>;
    VecCts  (<vector>, <vector>): <vector>;
    VecCtu  (<vector>, <vector>): <vector>;
    VecExpte (<vector>): <vector>;
    VecFloor (<vector>): <vector>;
    VecLoge (<vector>): <vector>;
    VecMadd (<vector>, <vector>, <vector>): <vector>;
    VecMadds (<vector>, <vector>, <vector>): <vector>;
    VecMax  (<vector>, <vector>): <vector>;
    VecMergeh  (<vector>, <vector>): <vector>;
    VecMergel  (<vector>, <vector>): <vector>;
    VecMfvscr  (<vector>, <vector>): <vector>;
    VecMin  (<vector>, <vector>): <vector>;
    VecMladd (<vector>, <vector>, <vector>): <vector>;
    VecMradds (<vector>, <vector>, <vector>): <vector>;
    VecMsum (<vector>, <vector>, <vector>): <vector>;
    VecMsums (<vector>, <vector>, <vector>): <vector>;
    VecMule  (<vector>, <vector>): <vector>;
    VecMulo  (<vector>, <vector>): <vector>;
    VecLd (INTEGER, POINTER TO <vector>): <vector>;
    VecLde (INTEGER, POINTER TO <vector>): <vector>;
    VecLdl (INTEGER, POINTER TO <vector>): <vector>;
    VecLvsl (INTEGER, POINTER TO <vector>): <vector>;
    VecLvsr (INTEGER, POINTER TO <vector>): <vector>;
    VecNmsub (<vector>, <vector>, <vector>): <vector>;
    VecNor  (<vector>, <vector>): <vector>;
    VecOr  (<vector>, <vector>): <vector>;
    VecPack  (<vector>, <vector>): <vector>;
    VecPackpx  (<vector>, <vector>): <vector>;
    VecPacks  (<vector>, <vector>): <vector>;
    VecPacksu  (<vector>, <vector>): <vector>;
    VecPerm  (<vector>, <vector>): <vector>;
    VecRe (<vector>): <vector>;
    VecRl  (<vector>, <vector>): <vector>;
    VecRound (<vector>): <vector>;
    VecRsqrte (<vector>): <vector>;
    VecSel (<vector>, <vector>, <vector>): <vector>;
    VecSl  (<vector>, <vector>): <vector>;
    VecSld  (<vector>, <vector>): <vector>;
    VecSll  (<vector>, <vector>): <vector>;
    VecSlo  (<vector>, <vector>): <vector>;
    VecSplat (<vector>): <vector>;
    VecSplats8 (<vector>): <vector>;
    VecSplats16 (<vector>): <vector>;
    VecSplats32 (<vector>): <vector>;
    VecSplatu8 (<vector>): <vector>;
    VecSplatu16 (<vector>): <vector>;
    VecSplatu32 (<vector>): <vector>;
    VecSr  (<vector>, <vector>): <vector>;
    VecSra  (<vector>, <vector>): <vector>;
    VecSrl  (<vector>, <vector>): <vector>;
    VecSro  (<vector>, <vector>): <vector>;
    VecSub  (<vector>, <vector>): <vector>;
    VecSubc  (<vector>, <vector>): <vector>;
    VecSubs  (<vector>, <vector>): <vector>;
    VecSum4s  (<vector>, <vector>): <vector>;
    VecSum2s  (<vector>, <vector>): <vector>;
    VecSums  (<vector>, <vector>): <vector>;
    VecTrunc (<vector>): <vector>;
    VecUnpackh  (<vector>, <vector>): <vector>;
    VecUnpackl  (<vector>, <vector>): <vector>;
    VecUnpackhpx  (<vector>, <vector>): <vector>;
    VecUnpacklpx  (<vector>, <vector>): <vector>;
    VecXor  (<vector>, <vector>): <vector>;
    VecAlleq  (<vector>, <vector>): BOOLEAN;
    VecAllge  (<vector>, <vector>): BOOLEAN;
    VecAllgt  (<vector>, <vector>): BOOLEAN;
    VecAllin  (<vector>, <vector>): BOOLEAN;
    VecAllle  (<vector>, <vector>): BOOLEAN;
    VecAlllt  (<vector>, <vector>): BOOLEAN;
    VecAllnan  (<vector>, <vector>): BOOLEAN;
    VecAllne  (<vector>, <vector>): BOOLEAN;
    VecAllnge  (<vector>, <vector>): BOOLEAN;
    VecAllngt  (<vector>, <vector>): BOOLEAN;
    VecAllnle  (<vector>, <vector>): BOOLEAN;
    VecAllnlt  (<vector>, <vector>): BOOLEAN;
    VecAllnumeric  (<vector>, <vector>): BOOLEAN;
    VecAnyeq  (<vector>, <vector>): BOOLEAN;
    VecAnyge  (<vector>, <vector>): BOOLEAN;
    VecAnygt  (<vector>, <vector>): BOOLEAN;
    VecAnyle  (<vector>, <vector>): BOOLEAN;
    VecAnylt  (<vector>, <vector>): BOOLEAN;
    VecAnynan  (<vector>, <vector>): BOOLEAN;
    VecAnyne  (<vector>, <vector>): BOOLEAN;
    VecAnynge  (<vector>, <vector>): BOOLEAN;
    VecAnyngt  (<vector>, <vector>): BOOLEAN;
    VecAnynle  (<vector>, <vector>): BOOLEAN;
    VecAnynlt  (<vector>, <vector>): BOOLEAN;
    VecAnynumeric  (<vector>, <vector>): BOOLEAN;
    VecAnyout  (<vector>, <vector>): BOOLEAN;

    VecDss (CARDINAL);
    VecDssall ();
    VecDst (ADDRESS, CARDINAL, <Cardinal constant>);
    VecDstst (ADDRESS, CARDINAL, <Cardinal constant>);
    VecDststt (ADDRESS, CARDINAL, <Cardinal constant>);
    VecDstt (ADDRESS, CARDINAL, <Cardinal constant>);
    VecMtvscr (CARDINAL);
    VecSt (<vector>, INTEGER, ADDRESS);
    VecSte ((<vector>, INTEGER, ADDRESS);
    VecStl ((<vector>, INTEGER, ADDRESS);
END VECTORS.

4.6.3 Alignment of dynamically allocated storage

For objects the storage of which is allocated by the runtime system ("TRACED CLASS") correct alignment is guaranteed.

For manually allocated storage area the p1 Modula-2 library provides for a module "VectorStorage". The semantics of this module is similar to that of the module "Storage". Additionally all returned addresses point to a storage area aligned on a 16 byte boundary.

4.7 Further Extensions

Importing all items from a module
"FROM Module_Ident IMPORT *;" has the effect of importing from a module every single (exported) entity declared in its definition module. The extension "FROM Module_Ident IMPORT * EXCEPT ident1, ident2, ...;" allows to import all entities but "ident1", "ident2", etc. Too frequent use of this feature is however discouraged, as it can reduce the readability of a module considerably.

Open arrays
Not only arrays having the same element type are compatible to open-array parameters, but also variables and expressions of the array-element type.

String constants
String constants may be indexed like a constant of type ARRAY someRange OF CHAR.
They may be used within value constructores to build an array of character.

Constant "NILPROC"
"NILPROC" is compatibel to every procedure type. If a procedure variable containing the value "NILPROC" is called, the exception "invalidLocation" is raised (cf. 2.11.3).

Function "HIGH"
The standard function "HIGH" can be used not only with open arrays but also with dynamic arrays and arrays of known size. In the case of a multidimensional array, the type of the "constexpr" used to indicate the dimension must be assignment compatible to the corresponding array index type.

Undefined variables
The compiler checks statically whether a local variable used in an expression has actually been assigned a value beforehand. If neither a direct assignment nor an indirect one resulting from use as a "VAR" parameter has taken place a warning is issued. In rare cases ("IF" statements within loops, assignments resulting from side effects of internal procedures) the compiler cannot recognize an assignment as having occurred "before" and issues a warning superfluously. Such warnings can be suppressed locally using "<* Warnings (FALSE) *>".

chapter 3 (compiler)

start page

chapter 5 (compiler)