This is Info file m3.info, produced by Makeinfo-1.55 from the input
file m3.texi.

   This file documents the DEC SRC Modula-3 compiler, release 3.3.

   Copyright (C) 1995 Stephen Schaub

   Permission is granted to make and distribute verbatim      copies
of this manual provided the copyright notice and      this permission
notice are preserved on all copies.

   Permission is granted to copy and distribute modified
versions of this manual under the conditions for      verbatim
copying, provided also that the sections      entitled "Copying" and
"GNU General Public License"      are included exactly as in the
original, and provided      that the entire resulting derived work is
distributed      under the terms of a permission notice identical to
this      one.

   Permission is granted to copy and distribute      translations of
this manual into another language,      under the above conditions
for modified versions,      except that this permission notice may be
stated in a      translation approved by the Free Software Foundation.


File: m3.info,  Node: Top,  Next: Writing Programs,  Prev: (dir),  Up: (dir)

SRC Modula-3
************

   This document provides an overview of the Modula-3 language as
implemented by the DEC Systems Research Center, version 3.3.  The full
distribution includes several libraries, most of which are not
described here.  This is not intended to provide an exhaustive or
even completely accurate coverage; it is to serve as a quick on-line
reference only.  For complete and up-to-date details, see the
Modula-3 home page at
`http://www.research.digital.com/SRC/modula-3/html/home.html'.

   Please mail comments or corrections to schaub@cs.unt.edu.

* Menu:

* Writing Programs::            Main module, m3makefile, user modules
* Language Elements::           Language features & syntax
* Compiling & Running::         Using m3makefiles and m3build
* Standard Library::            Strings, I/O, miscellaneous routines

 -- The Detailed Node Listing --

Writing Programs

* Main Module::
* Makefile::

The Makefile

* Simple Makefile::             A simple example of an m3makefile
* Basic Makefile Commands::     What goes in an m3makefile
* Other Makefile Commands::     More of what goes in an m3makefile

Language Elements

* Modules::                     Interfaces and modules
* Declarations::                Types, constants, variables, procedures...
* Statements::                  Selection, looping, error control
* Expressions::                 Identifiers, arithmetic, logic, etc.
* Pragmas::                     Compiler directives: <* INLINE *>, etc.

Modules

* Interface::                   Interface layout and example
* Implementation::              Module layout and example
* Imports::                     Using modules in programs

Imports

* IMPORT Stmt::

Declarations

* Decl Examples::               Examples of common declarations
* Constants::                   CONST <id> "=" <const expr> ";"
* Types::                       TYPE <id> "=" <type> ";"
* Variables::                   VAR <id> [ ":" <type> ] [ ":=" <expr> ] ";"
* Procedures::                  PROCEDURE <id> <sig> "=" <body> <id> ";"
* Exceptions::                  EXCEPTION <id> [ "(" <parm type> ")" ] ";"

Types

* Ordinal Types::               INTEGER, CARDINAL, BOOLEAN, CHAR, ...
* Array Types::                 ARRAY <indextype> OF <slottype>
* Record Types::                RECORD <fieldlist> END
* Object Types::                OBJECT-METHODS-OVERRIDES-END
* Set Types::                   SET OF <basetype>
* Reference Types::             REF <referent type>
* Procedure Types::             PROCEDURE (<parameter list>) { : <return type>}

Statements

* Assignment Stmts::            INC, DEC, and :=
* Call and Return Stmts::       Calling and returning from procedures
* Selection Stmts::             IF-THEN, CASE, TYPECASE
* Looping Stmts::               FOR, WHILE, REPEAT, LOOP, EXIT
* Compound Stmts::              BEGIN/END, WITH
* Error Stmts::                 RAISE, TRY-EXCEPT, TRY-FINALLY

Selection Statements

* IF Stmt::                     IF-THEN-ELSIF-ELSE-END
* CASE Stmt::                   CASE <expr> OF <cases> END
* TYPECASE Stmt::               TYPECASE <expr> OF <cases> END

Looping Statements

* FOR Stmt::                    FOR <id> ":=" <expr> TO <expr> [ BY <expr> ] <stmts> END
* WHILE Stmt::                  WHILE <expr> DO <stmts> END
* REPEAT Stmt::                 REPEAT <stmts> UNTIL <expr>
* LOOP Stmt::                   LOOP <stmts> END
* EXIT Stmt::                   EXIT

Compound Statements

* Block Stmt::
* WITH Stmt::                   WITH <id> "=" <expr> DO <stmts> END

Error Handling Statements

* RAISE Stmt::                  RAISE <exception> [ "(" <except parm> ")" ]
* TRY-EXCEPT Stmt::             TRY <stmts> EXCEPT <handlers> END
* TRY-FINALLY Stmt::            TRY <stmts> FINALLY <stmts> END

Expressions

* Expr Build Blocks::           Format of identifiers and literals
* Arithmetic Expressions::      a + b, MAX(x,y), ABS(x), ...
* Logical Expressions::         a AND b, NOT c, ...
* Relational Expressions::      a = b, a <= c, c IN charSet, ...
* Constructors::
* Precedence::                  Operator precedence chart

Constructors

* Set Constructor::
* Array Constructor::
* Record Constructor::

Pragmas

* INLINE Pragma::
* ASSERT Pragma::
* TRACE Pragma::
* FATAL Pragma::
* UNUSED Pragma::
* OBSOLETE Pragma::
* NOWARN Pragma::

Compiling and Running Programs

* Simple Compile Example::      How to organize and compile a simple program
* Multiple-Package Example::    Managing larger programs
* m3build Options::             Command-line options for m3build

Standard Library

* String Routines::
* I/O Routines::
* Misc Routines::

String Routines

* Text Interface::              Compare strings, get length of string, etc.
* Fmt Interface::               Convert INTEGER/REAL/BOOLEAN to TEXT
* Scan Interface::              Convert TEXT values to INTEGER/REAL/BOOLEAN

I/O Routines

* I/O Examples::
* IO Interface::
* Rd Interface::
* Wr Interface::
* Lex Interface::

Misc Routines

* Params Interface::            Access command-line parameters
* Env Interface::               Access environment variables
* Word Interface ::             Unsigned integer datatype, bitwise logical operations


File: m3.info,  Node: Writing Programs,  Next: Language Elements,  Prev: Top,  Up: Top

Writing Programs
****************

   Modula-3 programs are composed of one or more module files, along
with a makefile that tells the compiler how to put everything
together.  All of these files must be located in a subdirectory
called `src'.

IMPORTANT: Case is significant in Modula-3 programs.  This means that

   * All keywords and reserved words must be in uppercase letters.

   * Identifiers such as variables, constants, and procedure names
     must always appear in the same case as the one used in the
     definition.  For example, `Main' and `main' are two different
     identifiers.

* Menu:

* Main Module::
* Makefile::


File: m3.info,  Node: Main Module,  Next: Makefile,  Prev: Writing Programs,  Up: Writing Programs

The Main Module
===============

   Every Modula-3 program must have a single main module.  For small
programs, the main module may be the only module.  Here is a short
example.

     MODULE Main;
     
     IMPORT IO; (* So we can print things *)
     
     VAR name: TEXT;  (* a string called `name' *)
     
     BEGIN
       IO.Put("Enter your name: ");
       IO.GetLine(name);
       IO.Put("Your name is: " & name & "\n");
     END Main.


File: m3.info,  Node: Makefile,  Prev: Main Module,  Up: Writing Programs

The Makefile
============

   An SRC Modula-3 makefile (named `m3makefile') contains instructions
(one per line) that instruct the compiler how to build a program or
library.  A makefile instruction is followed by one or more arguments
in parenthesis, like a procedure call.  Each instruction generally
specifies a library, interface, or module to be included as part of
the final library or program.  Comments are denoted by `%'.

* Menu:

* Simple Makefile::             A simple example of an m3makefile
* Basic Makefile Commands::     What goes in an m3makefile
* Other Makefile Commands::     More of what goes in an m3makefile


File: m3.info,  Node: Simple Makefile,  Next: Basic Makefile Commands,  Prev: Makefile,  Up: Makefile

A Simple Makefile
-----------------

   Here is a simple m3makefile:

     % Makefile for Modula-3 program 'myprog'
     
     import(libm3)
     implementation(main)
     program(myprog)

   The first line is a comment.  Text after `%' is ignored by the
compiler in m3makefiles.

   The `import' command tells the compiler that the program uses
routines in the library `libm3'.  This command is present in most
m3makefiles.  If you use routines from other libraries, you must
include other `import' commands that tell the compiler which
libraries to include.

   There must be one `implementation' command for each .m3 file in
your program.  In this case, there was only one such file: `main.m3'.

   Finally, the `program' command tells the compiler what to name the
resulting executable file.  The compiler will name this program's
executable `myprog'.


File: m3.info,  Node: Basic Makefile Commands,  Next: Other Makefile Commands,  Prev: Simple Makefile,  Up: Makefile

Basic Makefile Commands
-----------------------

   The following are some of the commands that may be used in an
m3makefile.  They declare their arguments as private: visible only
within the current package.  To declare an interface or module as
public, use the capitalized version (e.g., Interface(),
Implementation(), etc.).

interface(X) / generic_interface(X)
     Declares that the file X.i3 (or X.ig for generics) contains an
     interface.  All interface files that you create must appear in
     interface commands.  Leave the .i3/.ig extension off.

implementation(X) / generic_implementation(X)
     Declares that the file X.m3 (or X.mg for generics) contains a
     module.  All module files that you create must appear in
     implementation commands.  Leave the .m3/.mg extension off.

module(X) / generic_module(X)
     Declares X.i3 and X.m3 with one command (X.ig and X.mg for
     generics).

program(<name>)
     An m3makefile generally has one program command.  This specifies
     what to name the program executable.

library(<name>)
     If the m3makefile describes a collection of interfaces and
     modules that are designed to be a library instead of a program,
     use this command instead of program().

import(<lib>)
     This command specifies packages to be imported.  The `libm3'
     package must be included in all Modula-3 programs with the import
     command.


File: m3.info,  Node: Other Makefile Commands,  Prev: Basic Makefile Commands,  Up: Makefile

Other Makefile Commands
-----------------------

override(P, D)
     Look in directory D/P for the package P instead of in the public
     repository.  Use this command in conjunction with the import(P)
     command when you want to build and use your own private
     libraries.

c_source(X)
     Declares that the file X.c contains C source code.

import_lib(X, P)
     If P/libX.a is a library, includes -LP -lX in the final link
     command. Otherwise, includes -lX in the final link command.

import_obj(X)
     Include X in the final link command.

m3_option(X) / remove_m3_option(X)
     Add or remove option X to/from list of compiler options.  X
     should be a string (enclosed in "") containing one of the
     following:
    -why
          Explain why each compilation is needed (default).

    -commands
          Print the compilation commands as they are started.

    -verbose
          Print what happens to each file.

    -times
          Print a breakdown of elapsed time.

    -g
          Generate debugging symbols (default).

    -O
          Optimize code.

    -a
          Turn off <*ASSERT*> checking.

    -keep
          Preserve intermediate files.

    -once
          Don't recompile modules with new opaque info.


File: m3.info,  Node: Language Elements,  Next: Compiling & Running,  Prev: Writing Programs,  Up: Top

Language Elements
*****************

   Modula-3 programs include declarations, statements, expressions,
and pragmas.

* Menu:

* Modules::                     Interfaces and modules
* Declarations::                Types, constants, variables, procedures...
* Statements::                  Selection, looping, error control
* Expressions::                 Identifiers, arithmetic, logic, etc.
* Pragmas::                     Compiler directives: <* INLINE *>, etc.


File: m3.info,  Node: Modules,  Next: Declarations,  Prev: Language Elements,  Up: Language Elements

Modules
=======

   Modules are the basic building blocks of Modula-3 programs.  A
"module" is a named collection of declarations, including constants,
types, variables, and procedures.  A module can make its facilities
available to other modules, called clients.

   Modules are composed of two pieces: one public, the other private.
The public part is called an "interface" and gives only the types and
procedure interfaces that are needed for clients to use the module.
The private section, called the "implementation" or "module", fills
in the details with procedure definitions and other private
declarations that are hidden from clients.

* Menu:

* Interface::                   Interface layout and example
* Implementation::              Module layout and example
* Imports::                     Using modules in programs


File: m3.info,  Node: Interface,  Next: Implementation,  Prev: Modules,  Up: Modules

Interface
---------

   The interface is the public portion of a module.  All declarations
in the interface are visible to clients of the module.

   Interface files have the name of the module with an `.i3'
extension, and have the following format:

     INTERFACE <interface-name>;
     
     {Imports}      (* *Note Imports:: *)
     
     {Declarations} (* *Note Declarations:: *)
     
     END <interface-name>.

   Generally, <interface-name> is the same as the name of the
corresponding module.

   Here is an example of an interface for a module `MyModule' which is
in a file called `MyModule.i3':

     INTERFACE MyModule;
     
     CONST MaxEntries = 53;
     TYPE Thing = RECORD name: TEXT; size: INTEGER END;
     
     PROCEDURE PrintThing(READONLY r: Thing);
     PROCEDURE MakeThing(n: TEXT; s: INTEGER): Thing;
     
     END MyModule.


File: m3.info,  Node: Implementation,  Next: Imports,  Prev: Interface,  Up: Modules

Implementation
--------------

   The implementation is the private portion of a module.
Implementation files have the name of the module with an `.m3'
extension, and have the following format:

     MODULE <module-name> [ EXPORTS <interface> { "," <interface> ... } ];
     
     {Imports}      (* *Note Imports:: *)
     
     {Declarations} (* *Note Declarations:: *)
     
     BEGIN  (* Optional Module startup code; BEGIN required *)
     END <module-name>.

   Generally, <module-name> is the same as the name of the interface
being implemented, but if not, the EXPORTS clause can be used to
specify which interface(s) are being implemented.

   Here is an example of an implementation file MyModule.m3 that
implements MyModule:

     MODULE MyModule;
     
     IMPORT IO;
     
     PROCEDURE PrintThing(READONLY r: Thing) =
       BEGIN
         IO.Put(r.name&"\t");
         IO.PutInt(r.size);
         IO.Put("\n");
       END PrintThing;
     
     PROCEDURE MakeThing(n: TEXT; s: INTEGER): Thing =
       BEGIN
         RETURN Thing{n, s};
       END MakeThing;
     
     END MyModule.


File: m3.info,  Node: Imports,  Prev: Implementation,  Up: Modules

Imports
-------

   Modules gain access to declarations in other modules via the
"import" mechanism.  For example, a main module cannot use types or
procedures defined in the IO Interface until it explicitly imports
the definitions using the IMPORT statement like this:

     IMPORT IO;

   Once a module's declarations are imported, they are referenced by
prefixing their names with the name of the module and a period (.)
like this:

     IO.Put("Hello, world.");

* Menu:

* IMPORT Stmt::


File: m3.info,  Node: IMPORT Stmt,  Prev: Imports,  Up: Imports

IMPORT Statement
................

     IMPORT <module-name> [ AS <alias> ] { "," ... } ";"
       or
     FROM <module-name> IMPORT <decl-name> { "," <decl-name>...} ";"

   The "IMPORT" statement allows a module to see declarations such as
procedures and types that appear in another module's interface.
IMPORT statements must appear after the MODULE or INTERFACE statement
and before any declarations.

   When using declarations imported from another module, the nonlocal
declaration name must be qualified with the name of the module it was
imported from unless the second form of the IMPORT statement is used.
For example:

     INTERFACE Box;
     
     CONST Size = 30;
     
     END Box;
     
     (* Client Module *)
     MODULE Toys;
     
     IMPORT Box;
     
     VAR boxSize := Box.Size;  (* Nonlocal declaration `Size' qualified
                                  by module name `Box' *)
     END Toys.
     
     (* Another Client Module *)
     MODULE Toys2;
     
     FROM Box IMPORT Size;
     
     VAR boxSize := Size; (* Nonlocal reference `Size' not qualified *)
     
     END Toys2;


File: m3.info,  Node: Declarations,  Next: Statements,  Prev: Modules,  Up: Language Elements

Declarations
============

   "Declarations" bind names with values or types.  They appear in the
outermost level of module interfaces and implementations after the
IMPORT statement, as well as at the beginning of blocks.  Kinds of
declarations include constants, types, variables, procedures, and
exceptions.  They can appear in any order.

* Menu:

* Decl Examples::               Examples of common declarations
* Constants::                   CONST <id> "=" <const expr> ";"
* Types::                       TYPE <id> "=" <type> ";"
* Variables::                   VAR <id> [ ":" <type> ] [ ":=" <expr> ] ";"
* Procedures::                  PROCEDURE <id> <sig> "=" <body> <id> ";"
* Exceptions::                  EXCEPTION <id> [ "(" <parm type> ")" ] ";"


File: m3.info,  Node: Decl Examples,  Next: Constants,  Prev: Declarations,  Up: Declarations

Declarations Examples
---------------------

     CONST
     	Pi = 3.14;		(* REAL *)
     	Maxsize = 30;		(* INTEGER *)
     	Space = ' ';		(* CHAR *)
     
     TYPE
     	Index = [1..Maxsize];	                (* Subrange *)
     	Letters = ['a'..'z'];	                (* Subrange *)
     	Colors = {Red, Green, Blue, Yellow};	(* Enumerated *)
     	ArrType = ARRAY Colors OF INTEGER;	(* ARRAY *)
     	ArrType2 = ARRAY [1..5] OF CHAR;	(* ARRAY *)
     	SetType = SET OF Letters;	        (* SET *)
     	Ptr = REF Student;		        (* Pointer *)
     	Student = RECORD		        (* RECORD *)
     	   name : TEXT;
     	   id   : INTEGER;
     	   gpa  : REAL;
     	   next : Ptr;
     	END;
     
     VAR
     	n	: INTEGER	:= -15;	                (* INTEGER *)
     	nonneg	: CARDINAL	:= 5;	                (* CARDINAL *)
     	x	: REAL	        := 3.0;	                (* REAL *)
     	ch	: CHAR	        := 'Q';	                (* CHAR *)
     	done	: BOOLEAN	:= TRUE;	        (* BOOLEAN *)
     	str	: TEXT	        := "Test";	        (* TEXT *)
     	arr	: ArrType	:= ArrType{0,1,2,3};	(* ARRAY *)
     	arr2	: ArrType2	:= ArrType2{' ', ..};	(* ARRAY *)
     	inFile	: Rd.T;		                        (* Reader *)
     	outFile	: Wr.T;		                        (* Writer *)
     	ltrSet	: SetType := SetType{'a'..'d','z'};	(* SET *)
     	head	: Ptr	        := NIL	                (* Pointer *)
     	st	: Student		                (* RECORD *)
     		:= Student{"Joe", 15426, 3.35, NIL};
     
     PROCEDURE One(y: REAL; VAR c: ArrType; x: INTEGER := 5) =
     (* Sample procedure definition.  y is a value parameter;
        c is a variable parameter; x is a value parameter with
        a default value *)
     VAR i: INTEGER;	(* local var *)
     BEGIN		(* procedure body *)
       <statement1>;
       .
       .
       .
       <statementn>;
     END One;
     
     PROCEDURE Max(a, b: INTEGER): INTEGER =
     (* Sample function definition. *)
     VAR max: INTEGER;
     BEGIN
        max := a;
        IF a < b THEN max := b END;
        RETURN max;
     END Max;


File: m3.info,  Node: Constants,  Next: Types,  Prev: Decl Examples,  Up: Declarations

Constants
---------

     CONST <identifier> [ ":" <type> ] "=" <constant expression> ";"

   Constant declarations are used to give names to values that can be
computed at compile time.  Here are some examples:

     CONST
       MaxValue: INTEGER = 5 * (25 - 3);       (* INTEGER *)
       MinValue = 2;                           (* INTEGER *)
       RangeValue = MaxValue - MinValue + 1;   (* INTEGER *)
       Name = "Arnie Shoestring";              (* TEXT *)
       Caps = SET OF CHARACTER{'A'..'Z'};    (* SET OF CHARACTER *)


File: m3.info,  Node: Types,  Next: Variables,  Prev: Constants,  Up: Declarations

Types
-----

     TYPE <identifier> "=" <type> ";"

   It is convenient to be able to give names to types, and the TYPE
declaration allows you to do this.  <type> may be one of the
following:

   * Ordinal: INTEGER, CARDINAL, BOOLEAN, CHAR, subrange, enumerated

   * Floating point: REAL, LONGREAL, EXTENDED

   * Array: a structure containing a fixed number of elements of the
     same type

   * Record: a structure containing a fixed number of elements

   * Object: a record paired with a method suite

   * Set: a collection of ordinal values

   * Reference: a pointer to something

   * Procedure: a procedure signature

* Menu:

* Ordinal Types::               INTEGER, CARDINAL, BOOLEAN, CHAR, ...
* Array Types::                 ARRAY <indextype> OF <slottype>
* Record Types::                RECORD <fieldlist> END
* Object Types::                OBJECT-METHODS-OVERRIDES-END
* Set Types::                   SET OF <basetype>
* Reference Types::             REF <referent type>
* Procedure Types::             PROCEDURE (<parameter list>) { : <return type>}


File: m3.info,  Node: Ordinal Types,  Next: Array Types,  Prev: Types,  Up: Types

Ordinal Types
.............

     INTEGER | CARDINAL | BOOLEAN | CHAR       (* Built-in *)
     "{" <id>"," <id>"," ... "}" ";"    (* Enumerated types *)
     "[" <lo>..<hi> "]" ";"         (* Subrange types *)

   "Ordinal" types denote sets of values in which each value has a
unique successor.

INTEGER
     The set of 32-bit signed integers (positive and negative).

CARDINAL
     A synonym for the subrange [0..LAST(INTEGER)]

BOOLEAN
     The enumeration {FALSE, TRUE}

CHAR
     The set of ISO-Latin-1 characters (an extension of ASCII)

Enumerated
     An enumerated type is an ordered set of values whose names are
     specified by the user, as follows:

          TYPE Day = {Sunday, Monday, Tuesday, Wednesday, Thursday,
                      Friday, Saturday};

     Values of an enumeration are specified as <typename>.<value>: for
     example, `Day.Sunday' rather than just `Sunday'.  Thus, you
     should keep enumeration type names short.

Subrange
     A subrange is a subset of the values of the base type specified
     by the range <lo>..<hi>.  <lo> and <hi> must both be values of
     the same ordinal type.  Integer subranges are the most common:

          TYPE Digit = [0 .. 9];         (* subrange of INTEGER *)
               WeekDay = [Day.Monday .. Day.Friday];   (* subrange of Day *)


File: m3.info,  Node: Array Types,  Next: Record Types,  Prev: Ordinal Types,  Up: Types

Array Types
...........

     ARRAY { <indextype> "," ... } OF <slottype> ";"

   `<indextype>' must be an ordinal type (*note Ordinal Types::.).
The common case is an integer subrange such as [1..numslots], but
Modula-3 programs frequently use user-defined enumerations as well.

   `<slottype>' can be any Modula-3 type, even another array.

   Here are some examples of array types:

     TYPE
       OneDimArray  = ARRAY [1..20] OF REAL;
       OneDimArray2 = ARRAY ['A'..'Z'] OF INTEGER;
       TwoDimArray  = ARRAY [1..20], [1..40] OF BOOLEAN;
       TwoDimArray2 = ARRAY [1..20] OF ARRAY [1..40] OF BOOLEAN;

   The built-in functions `FIRST', `LAST', and `NUMBER' can be used
with array types and variables to return the index of the first and
last slot and number of slots, respectively.  For example,
`FIRST(OneDimArray)' = 1; `NUMBER(OneDimArray2)' = 26.


File: m3.info,  Node: Record Types,  Next: Object Types,  Prev: Array Types,  Up: Types

Record Types
............

     RECORD <fieldDecl> { ";" <fieldDecl> ... } END ";"
     
     where
     
     <fieldDecl> = <id> [ ":" <type> ]  [ ":=" <constant expr> ]

   Record types group related data items together in a unified data
structure.  Each data item, or field, has a name, a type, and an
optional constant initializer.  If you supply the constant
initializer, you can omit the type; it will be inferred from the
constant.  Here are some examples:

     TYPE
       (* Record type with uninitialized fields *)
       Rec1 = RECORD
         x, y: INTEGER;
         name: TEXT
       END;
     
       (* Record type with initialized fields *)
       Rec2 = RECORD
         x, y := 0; (* Type is INTEGER *)
         name := "" (* Type is TEXT *)
       END;


File: m3.info,  Node: Object Types,  Next: Set Types,  Prev: Record Types,  Up: Types

Object Types
............

     [ <parentObjType> ] OBJECT
                           <fields>
                         [ METHODS <methods> ]
                         [ OVERRIDES <overrides> ]
                         END

   An object is a record paired with a "method suite": a collection of
procedures that operate on the object.  The fields of an object are
specified just like those of records (*note Record Types::.).  Methods
are fields that hold procedure values.  They are specified as follows:

     <methods> = { <method> ";" ... }
       where
     <method> = <id> <sig> [ ":=" <proc id> ]

   A method signature <sig> is a procedure signature (*note Procedure
Types::.).  If a procedure identifier <proc id> is given, it must
refer to a procedure which takes as its first parameter the object
being defined, and other parameters as specified by the signature
<sig>.

   Overrides specify new procedures for methods of the supertype:

     <overrides> = { <override> ";" ... }
       where
     <override> = <id> ":=" <proc id>


File: m3.info,  Node: Set Types,  Next: Reference Types,  Prev: Object Types,  Up: Types

Set Types
.........

     SET OF <basetype>

   <basetype> can be any ordinal type (*note Ordinal Types::.) with a
"reasonable" number of elements.  For example, CHAR has 256 elements,
a reasonable number, but a (32-bit) INTEGER has over 4 billion, an
unreasonable number.  So SET OF INTEGER is not possible, but SET OF
[-100..100] is legal.


File: m3.info,  Node: Reference Types,  Next: Procedure Types,  Prev: Set Types,  Up: Types

Reference Types
...............

     REF <type>

   <type> can be any type, even a reference type.  This specifies a
reference (pointer) to a value of type <type>.  For example:

     TYPE
       IntPtrType = REF INTEGER;                 (* A pointer to an integer *)
       ArrPtrType = REF ARRAY [1..5] OF CHAR;    (* A pointer to an array *)


File: m3.info,  Node: Procedure Types,  Prev: Reference Types,  Up: Types

Procedure Types
...............

     PROCEDURE <sig>
       where
     <sig> = "(" { <formal> ";" ... } ")"
                [ ":" <result type> ]
                [ RAISES ( ANY | "{" { <exception> "," ... } "}" ) ]
     
     <formal> = [ VAR | READONLY | VALUE ] <id> { "," <id> ... }
                [ ":" <type> ] [ ":=" <const expr> ]

   If a result type for the procedure is specified, then the
procedure must return a value of that type.

   If a constant expression <const expr> is supplied as a default
value for a formal parameter, the type may be omitted, and when the
procedure is called, if an argument is not supplied for a formal with
a default value, the default value is used to initialize the formal.

   The RAISES section specifies which exceptions the procedure is
allowed to raise.  Any exceptions that occur in the procedure,
possibly as the result of a call to another procedure, that are not
handled by the procedure and that do not appear in the RAISES clause
cause a checked run-time error.  If the RAISES section is omitted,
then any exceptions raised cause a checked run-time error.

   The VAR, VALUE, and READONLY parameter modes determine how the
actual argument is associated with the formal parameter:

*VALUE
     This is the default mode, and means "call by value."  The formal
     parameter contains a copy of the value of the actual argument.
     Changes to the formal parameter do not affect the actual
     argument.

*VAR
     This means "call by reference."  The formal parameter is linked
     to the actual argument.  Changes to the formal parameter are
     reflected in the actual argument.  In general, the actual
     argument must be a variable.  No default value may be specified.

*READONLY
     This means generally "call by reference," but the procedure may
     not modify the formal parameter.  This provides the protection of
     call by value with the efficiency of call by reference, and
     should be used when large arrays or records need to be passed as
     parameters but should not be changed.


File: m3.info,  Node: Variables,  Next: Procedures,  Prev: Types,  Up: Declarations

Variables
---------

     VAR <id> { "," <id> ... } [ ":" <type> ] [ ":=" <expr> ] ";"

   Declaring variables in Modula-3 is much like Pascal, except that
the type can be omitted if an initialization expression is provided.
The initialization expression <expr> need not be constant.  Here are
some examples:

     VAR
       x: INTEGER;
       s := "Hello";    (* type TEXT is implied *)
       chars := SET OF CHAR{'a'..'z'};    (* type SET OF CHAR is implied *)
       y, z := 0;       (* both y and z are INTEGER initialized to 0 *)


File: m3.info,  Node: Procedures,  Next: Exceptions,  Prev: Variables,  Up: Declarations

Procedures
----------

     PROCEDURE <id> <sig> "="
       <decls>
       BEGIN
         <stmts>
       END <id> ";"

   A procedure declaration is composed of an identifier, a signature
(*note Procedure Types::.), optional local declarations, and
statements.  The identifier <id> at the end of the procedure must
match the id at the beginning.  Declarations made in a procedure are
local to the procedure: they exist only while the procedure is
executing.

   If the procedure signature specifies a result type, the procedure
is called a function procedure, and it must include a RETURN statement
which returns an expression of the specified type.  It is a checked
runtime error for a function procedure to fail to return a result.


File: m3.info,  Node: Exceptions,  Prev: Procedures,  Up: Declarations

Exceptions
----------

     EXCEPTION <id> [ "(" <parm type> ")" ] ";"

   Exceptions can only be declared at the top-level of a module or
interface.  If they will take an argument, a parameter type <parm
type> must be specified in parentheses.

     EXCEPTION
       UserAbort(TEXT);
       EndOfFile;


File: m3.info,  Node: Statements,  Next: Expressions,  Prev: Declarations,  Up: Language Elements

Statements
==========

   Statements appear in procedures and in a module's top-level block.
The statement terminator is the semicolon, which may be omitted
after the last statement in a sequence (in which case it is a
"statement separator").

   Constructs such as FOR, WHILE, REPEAT, WITH, etc. can contain
multiple statements and must be terminated by END.  In general,
whenever a Modula-3 language construct requires an END, it can
contain zero, one, or more elements.

* Menu:

* Assignment Stmts::            INC, DEC, and :=
* Call and Return Stmts::       Calling and returning from procedures
* Selection Stmts::             IF-THEN, CASE, TYPECASE
* Looping Stmts::               FOR, WHILE, REPEAT, LOOP, EXIT
* Compound Stmts::              BEGIN/END, WITH
* Error Stmts::                 RAISE, TRY-EXCEPT, TRY-FINALLY


File: m3.info,  Node: Assignment Stmts,  Next: Call and Return Stmts,  Prev: Statements,  Up: Statements

Assignment Statements
---------------------

     <v> ":=" <e>

   Sets <v> to the value of <e>.  <v> must be a writable designator
(generally, a variable or non-READONLY procedure parameter).

     INC "(" x { "," n} ")"
     DEC "(" x { "," n} ")"

   These are shortcuts for `x := x + n' and `x := x - n',
respectively.  If omitted, `n' defaults to 1.  `x' must be an ordinal
value (INTEGER, CHAR, or enumerated value).  `n' must be an integer
expression.  Some examples are in order;

     intvar := 53;
     DEC(intvar);     (* intvar = 52 *)
     
     charvar := 'a';
     INC(charvar, 3); (* charvar = 'd' *)


File: m3.info,  Node: Call and Return Stmts,  Next: Selection Stmts,  Prev: Assignment Stmts,  Up: Statements

Procedure Call and Return Statements
------------------------------------

   To call a procedure, use one of the following two forms:

     1) <procexpr> "(" { <arg> "," ... } ")"
          where
        <arg> = [ <argname> ":=" ] <expr>
     
     2) EVAL <expr>

   The first form is used to call a "proper procedure" (one that does
not specify a return type and thus has no return value).  The second
is used to call a function procedure when you want to throw away the
return value.  For example:

     IO.Put("Hello");    (* Call a proper procedure *)
     EVAL IO.EOF();      (* Call a function procedure and throw away result *)

   To return from a procedure, use the following statement:

     RETURN [ <expr> ]

   The RETURN statement is used inside procedures only to return
control to the caller.  A return value must be supplied if the
procedure is a function procedure, but may not appear if the
procedure is a proper procedure.


File: m3.info,  Node: Selection Stmts,  Next: Looping Stmts,  Prev: Call and Return Stmts,  Up: Statements

Selection Statements
--------------------

* Menu:

* IF Stmt::                     IF-THEN-ELSIF-ELSE-END
* CASE Stmt::                   CASE <expr> OF <cases> END
* TYPECASE Stmt::               TYPECASE <expr> OF <cases> END


File: m3.info,  Node: IF Stmt,  Next: CASE Stmt,  Prev: Selection Stmts,  Up: Selection Stmts

IF Statement
............

     IF <expr> THEN <stmts> { ELSIF <expr> THEN <stmts> ... }
     [ ELSE <stmts> ] END

   <expr> must be a boolean-valued expression.  Here is an example:

     IF Text.Equal(txt,"Strawberry") THEN
       IO.Put("Not bad")
     ELSIF Text.Equal(txt,"Avacado") THEN
       IO.Put("Yuck!")
     ELSIF Text.Equal(txt,"Chocolate") THEN
       IO.Put("Yum")
     ELSE
       IO.Put("Nah.")
     END


File: m3.info,  Node: CASE Stmt,  Next: TYPECASE Stmt,  Prev: IF Stmt,  Up: Selection Stmts

CASE Statement
..............

     CASE <expr> OF { "|" <case> ... } [ ELSE <stmts> ] END
       where
         <case> = { <label> "," ... } "=>" <stmts>
         <label> = <const expr> [ ".." <const expr> ]

   The case statement is a specialization of the IF/THEN/ELSIF
statement that allows discrimination among a set of possible values
of some ordinal expression <expr>.  If a case is encountered that is
not handled by one of the arms of the case statement, the ELSE arm is
taken; if no ELSE arm is present in this situation, a checked
run-time error occurs.

     CASE IO.GetChar() OF
     | 'a'..'z' => IO.Put("Lowercase");
     | 'A'..'Z' => IO.Put("Uppercase");
     | '0'..'9' => IO.Put("Digit");
     | '!', '.', ':', ';', '?' => IO.Put("Punctuation");
     ELSE
       IO.Put("Other")
     END

   The compiler will generate a warning if no ELSE arm appears and
not all cases are covered.  This can be ignored at risk of a possible
runtime error, or an empty ELSE arm can be inserted to pacify the
compiler and runtime system.


File: m3.info,  Node: TYPECASE Stmt,  Prev: CASE Stmt,  Up: Selection Stmts

TYPECASE Statement
..................

     TYPECASE <ref expr> OF { "|" <case> ... } [ ELSE <stmts> ] END
       where
         <case> = { <type> "," ... } { "(" <id> ")" } "=>" <stmts>

   <ref expr> is a pointer of some sort, and <id> is bound to the
value of the reference if specified.  For example:

     VAR ptrVar: REFANY;
     
     TYPECASE ptrVar OF
     | NULL =>  (* <ptrVar> contains NIL *)
     | REF CHAR =>  (* <ptrVar> is a pointer to a character *)
     | REF INTEGER(intPtr) =>  (* <ptrVar> is a pointer to an integer, and
                                  <intPtr> gets bound to that pointer value *)
     ELSE
       (* <ptrVar> points to something else *)
     END;


File: m3.info,  Node: Looping Stmts,  Next: Compound Stmts,  Prev: Selection Stmts,  Up: Statements

Looping Statements
------------------

   Modula-3 provides the Pascal loop constructs FOR, WHILE and
REPEAT, as well as the LOOP statement, which loops infinitely.  In
addition, the EXIT statement can appear in any loop construct, and
causes the innermost loop to terminate when it is executed.

* Menu:

* FOR Stmt::                    FOR <id> ":=" <expr> TO <expr> [ BY <expr> ] <stmts> END
* WHILE Stmt::                  WHILE <expr> DO <stmts> END
* REPEAT Stmt::                 REPEAT <stmts> UNTIL <expr>
* LOOP Stmt::                   LOOP <stmts> END
* EXIT Stmt::                   EXIT


File: m3.info,  Node: FOR Stmt,  Next: WHILE Stmt,  Prev: Looping Stmts,  Up: Looping Stmts

FOR Statement
.............

     FOR <id> ":=" <expr1> TO <expr2> [ BY <stepval> ] DO <stmts> END

   Initializes <id> to <expr1>, evaluates <expr1> and <expr2>, then
executes <stmts>, increments <id> by <stepval> (by 1 if <stepval> is
not specified), and loops if <id> <= <expr2>.  If <stepval> is
negative, then loops while <id> >= <expr2>.

   <expr1> and <expr2> must both be of the same ordinal type (*note
Ordinal Types::.).  <id> is defined locally by the FOR loop as a
READONLY variable, and its type is the type common to <expr1> and
<expr2>.  For example:

     VAR i: INTEGER := 5;
         x: INTEGER;
     BEGIN
       FOR i := 1 TO 10 DO  x := i;  END; (* FOR *)
       IO.PutInt(i);   (* Puts '5', because the 'i' in the FOR loop isn't the same
                          as this 'i' *)
       IO.PutInt(x);   (* Puts '10' because 'x' was assigned the value of the 'i'
                          in the FOR loop *)
     END

   Another example prints the letters 'A'..'E' using the CHAR ordinal
type for the FOR limits:

     FOR i := 'A' TO 'E' DO IO.PutChar(i); END  (* 'i' is of type CHAR *)


File: m3.info,  Node: WHILE Stmt,  Next: REPEAT Stmt,  Prev: FOR Stmt,  Up: Looping Stmts

WHILE Statement
...............

     WHILE <expr> DO <stmts> END

   <expr> must be a boolean-valued expression.  <stmts> are executed
until <expr> becomes FALSE.  If <expr> is FALSE at the start <stmts>
are not executed at all.


File: m3.info,  Node: REPEAT Stmt,  Next: LOOP Stmt,  Prev: WHILE Stmt,  Up: Looping Stmts

REPEAT Statement
................

     REPEAT <stmts> UNTIL <expr>

   <expr> must be a boolean-valued expression.


File: m3.info,  Node: LOOP Stmt,  Next: EXIT Stmt,  Prev: REPEAT Stmt,  Up: Looping Stmts

LOOP Statement
..............

     LOOP <stmts> END

   The LOOP statement executes <stmts> repeatedly in an infinite loop.
Normally an EXIT statement appears in some IF statement in <stmts> to
exit the loop when some condition becomes true.  The following example
prints "Hello" forever.

     LOOP
       IO.Put("Hello\n");
     END (* LOOP *)


File: m3.info,  Node: EXIT Stmt,  Prev: LOOP Stmt,  Up: Looping Stmts

EXIT Statement
..............

     EXIT

   The EXIT statement must appear inside a WHILE, REPEAT, or LOOP
statement.  It causes the flow of execution to branch to the statement
immediately following the innermost loop in which it appears.  For
example:

     FOR x := 1 TO 5 DO
       i := 1;
       WHILE i < 3 DO
         i := i + 1;
         IF CheckIt(i, x) THEN
           EXIT  (* Transfers control to the IO.Put below *)
         END
       END; (* WHILE *)
       IO.Put("x = " & Fmt.Int(x) & "\n")
     END; (* FOR *)


File: m3.info,  Node: Compound Stmts,  Next: Error Stmts,  Prev: Looping Stmts,  Up: Statements

Compound Statements
-------------------

   The following statements allow local declarations that are visible
only within the scope of the statement.

* Menu:

* Block Stmt::
* WITH Stmt::                   WITH <id> "=" <expr> DO <stmts> END


File: m3.info,  Node: Block Stmt,  Next: WITH Stmt,  Prev: Compound Stmts,  Up: Compound Stmts

Block Statement
...............

     <decls>
     BEGIN
       <stmts>
     END

   The block statement is not needed nearly as frequently in Modula-3
as in other languages because Modula-3 loops, if/then statements,
etc. can contain multiple statements.  It allows the declaration of
local variables that are visible only within the block.  For example:

     VAR b := FALSE;
         x := 0;
     BEGIN (* block *)
       WHILE NOT b DO
         INC(x);
         b := (x > 5);
       END (* while *)
     END (* block *)


File: m3.info,  Node: WITH Stmt,  Prev: Block Stmt,  Up: Compound Stmts

WITH Statement
..............

     WITH <id> "=" <expr> { "," <id> "=" <expr> ... } DO <stmts> END

   The WITH statement binds identifiers <id> to the value of
expressions <expr>.  The expressions are evaluated once at the
beginning of the statement, and the identifiers are defined only
within the scope of the WITH statement.  If <expr> is a variable or
other writable designator, <id> becomes an alias for it, so modifying
<id> modifies the variable it is bound to.

   The following example prints the contents of a file "data.txt" on
standard output.

     WITH rd = IO.OpenRead("data.txt") DO
       WHILE NOT IO.EOF(rd) DO
         IO.Put(IO.GetLine(rd) & "\n");
       END; (* WHILE *)
       Rd.Close(rd);
     END; (* WITH *)


File: m3.info,  Node: Error Stmts,  Prev: Compound Stmts,  Up: Statements

Error Handling Statements
-------------------------

   Modula-3 provides an exception mechanism for raising and handling
error conditions that occur in programs.

* Menu:

* RAISE Stmt::                  RAISE <exception> [ "(" <except parm> ")" ]
* TRY-EXCEPT Stmt::             TRY <stmts> EXCEPT <handlers> END
* TRY-FINALLY Stmt::            TRY <stmts> FINALLY <stmts> END


File: m3.info,  Node: RAISE Stmt,  Next: TRY-EXCEPT Stmt,  Prev: Error Stmts,  Up: Error Stmts

RAISE Statement
...............

     RAISE <exception> [ "(" <exception parm> ") ]

   Use the RAISE statement to raise an exception <exception>.  If
<exception> as defined requires a parameter, one must be supplied in
parenthesis.


File: m3.info,  Node: TRY-EXCEPT Stmt,  Next: TRY-FINALLY Stmt,  Prev: RAISE Stmt,  Up: Error Stmts

TRY-EXCEPT Statement
....................

     TRY
       <guarded stmts>
     EXCEPT
     "|" <exception id> { "," <exception id> ... } "=>" <stmts>
         (* Non-parameterized exceptions *)
     
     "|" <exception id> "(" <parm id> ")" "=>" <stmts>
         (* Parameterized exception handler *)
     
     [ ELSE <stmts> ]
     END

   The TRY-EXCEPT statement guards statements between TRY and EXCEPT
with the exception handlers between EXCEPT and END.  An exception
raised by a <guarded stmt> is handled by <stmts> in the corresponding
handler, or by ELSE <stmts>, if present, and execution continues with
the statement following END.

     EXCEPTION Failure(Severity);
     TYPE Severity = {Low, Medium, High};
     ...
     
     TRY
       ...
     EXCEPT
     | IO.Error =>
         IO.Put("An I/O error occurred.")
     | Lex.Error =>
         IO.Put("Unable to convert datatype.")
     | Severity(x) =>
         IF x = Severity.Low THEN IO.Put("Not bad") ELSE IO.Put("Bail out") END
     END;


File: m3.info,  Node: TRY-FINALLY Stmt,  Prev: TRY-EXCEPT Stmt,  Up: Error Stmts

TRY-FINALLY Statement
.....................

     TRY
       <guarded stmts>
     FINALLY
       <cleanup stmts>
     END

   When an exception occurs in a <guarded stmt>, control is
transferred to <cleanup stmts>, and when they have completed, the
exception is re-raised.  Thus, the TRY-FINALLY statement does not
trap exceptions as TRY-EXCEPT does; it merely allows some "cleaning
up" before the exception is passed up to be handled by a TRY-EXCEPT
statement in a calling routine.

   NOTE: The TRY-FINALLY statement catches internal exceptions raised
by all EXIT and RETURN statements.


File: m3.info,  Node: Expressions,  Next: Pragmas,  Prev: Statements,  Up: Language Elements

Expressions
===========

   Modula-3 supports a rich variety of strongly type-checked
expressions.

* Menu:

* Expr Build Blocks::           Format of identifiers and literals
* Arithmetic Expressions::      a + b, MAX(x,y), ABS(x), ...
* Logical Expressions::         a AND b, NOT c, ...
* Relational Expressions::      a = b, a <= c, c IN charSet, ...
* Constructors::
* Precedence::                  Operator precedence chart


File: m3.info,  Node: Expr Build Blocks,  Next: Arithmetic Expressions,  Prev: Expressions,  Up: Expressions

Expression Building Blocks
--------------------------

Literal
     A literal is a constant value that can be either a number, a
     character, or a string.
          Number | CharLiteral | TextLiteral

Identifier
     Identifiers are names given to types, procedures, constants,
     etc.  They consist of a letter followed by one or more letters,
     digits, and underscores.  Modula-3 is case sensitive, so
     identifiers with the same letters in different cases are
     different identifiers.  Example: test, a_5
          Letter { Letter | Digit | "_" ... }

CharLiteral
     A character literal represents a single ASCII character (type
     CHAR).  Example: 'A', '\n', '\015'
          "'" (PrintingChar | Escape | ") "'"

     A "PrintingChar" is a letter, digit, punctuation mark, or any
     ISO-Latin-1 code in [ 160..255 ].  An "Escape" is one of the
     following:
        * "\n": a newline character

        * "\t": a tab character

        * "\r": a carriage return character

        * "\f": a formfeed character

        * "\\": a \ character

        * "\"": a " character

        * "\'": a ' character

        * "\" OctalDigit OctalDigit OctalDigit: a specific CHAR
          value, where "OctalDigit" is a digit in the range [0..7].
          Example: \015 (char 13)

TextLiteral
     A text literal represents a value of type TEXT (a string).
     Example: "Hello.\n"
          " { PrintingChar | Escape | "'" ... } "

     `PrintingChar' and `Escape' have the same meanings as given
     above.

Number
     A number is an integer or floating point number.  Integers can be
     expressed in any base [2..16] by writing the base followed by
     "_" and the number in that base.  Example: `2_1010' (base 2) =
     `8_12' (base 8) = `10' (base 10) = `16_A' (base 16).

     Floating point numbers can be expressed in the conventional
     scientific notation as follows:
          Digit { Digit ... } "." Digit { Digit ... } [ Exponent ]
            where
          Exponent = "E" | "D" | "X" [ "+" | "-" ] Digit { Digit ... }


File: m3.info,  Node: Arithmetic Expressions,  Next: Logical Expressions,  Prev: Expr Build Blocks,  Up: Expressions

Arithmetic Expressions
----------------------

   The usual arithmetic operators are available for numeric
computation.  Some of the operators work for both INTEGERs and REALs,
but an INTEGERs and REALs may not be mixed in an expression.  For
example, the expression `5 + 6.9' is illegal.  Instead, use `FLOAT(5)
+ 6.9' or `5.0 + 6.9'.  Here are the common infix binary operators:

    + (addition)
          computes sum of operands

    - (subtraction)
          computes difference of operands

    * (multiplication)
          computes product of operands

    DIV (integer division)
          computes integer quotient of operands

    / (REAL division)
          computes floating point quotient of operands

    MOD (modulus)
          computes integer remainder after a division

The following built-in arithmetic functions are also useful:

    ABS(a)
          returns -a if a < 0; otherwise, returns a

    MAX(a,b)
          returns the greater of a and b

    MIN(a,b)
          returns the lesser of a and b

For converting between INTEGERs and REALs, use the following built-in
functions:

    FLOAT(x [ "," REAL | LONGREAL | EXTENDED ])
          converts any kind of numeric value x to a floating point
          value (REAL is the default).

    ROUND(x)
          converts a floating point value x to the nearest integer

    TRUNC(x)
          converts a floating point value x to the nearest integer in
          the direction of 0.0

    FLOOR(x)
          returns the greatest integer not exceeding a floating point
          value x

    CEILING(x)
          returns the least integer not less than a floating point
          value x


File: m3.info,  Node: Logical Expressions,  Next: Relational Expressions,  Prev: Arithmetic Expressions,  Up: Expressions

Logical Expressions
-------------------

   Modula-3 supports the usual boolean operators.  Short-circuit
(conditional) evaluation is used.  From highest to lowest precedence,
they are:

    NOT <expr>
          TRUE if <expr> is FALSE; FALSE if <expr> is TRUE

    <expr1> AND <expr2>
          TRUE iff <expr1> and <expr2> are both TRUE, otherwise FALSE

    <expr1> OR <expr2>
          TRUE iff either <expr1> or <expr2> is TRUE, otherwise FALSE

   Modula-3 also supports bitwise logical computation on unsigned
numbers using the procedures in the Word interface (*note Word
Interface::.).