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
FixedSubrangeSize	Size of subrange types (cf. 5.3.1)	7
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)
Variadic	Variadic parameter allocation (see below)
AlignBorder	Alignment control (see below)
ARCH	target architecture	6
OptLevel	Optimization level (see below)
p1	Always TRUE	6, 7
StonyBrook	Always FALSE	6, 7

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

If TRUE is assigned to the pragma variable "Variadic", variadic parameter allocation is used for the next parameter. This prama variable is meaningfull iff the current calling convention is "CCalling" and Arm64 code is produced.

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 "a64" (Arm 64-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 "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).

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.
• 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).
• 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 system wide standard calling conventions used especially by the programming language. C
2. Modified C calling conventions where large parameters are passed via reference.

Examples for interfacing to C are given by the Core Definition Files which are derived from the core definition header files written in C.
These definition files 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 Special issues for Arm code generation

	PROCEDURE ioctl (fd: INT32; cmd: CARD32<*ASSIGN(Variadic, TRUE)*>; arg: ADDRESS): INT32;

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 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)