%
%  This is chapter two of hppa release notes
%	also for hp68k and Apollos
%  Latest update 28-Jul-90 (kjg)
%  		 28-Dec-90 (kjg) hp68k bits added
%
\chapter{New in this release}

\section{Changes since the first native code releases}
\subsection{Multi-dimensional open arrays supported}
Open arrays of multiple dimensions are now supported, as specified in
the draft international standard.  Details of this feature are given
in the section~\ref{multidim}

\subsection{Standard-conformant implementations of VAL}
The implementation of {\em VAL\/} now conforms to the full generality
of the draft standard.  In fact, \gpm\ actually allows slightly greater
generality than the standard, issuing a warning if the extensions are used.
The details are given in section~\ref{valinfo}.

\subsection{New parameter passing strategy}
Native code versions of \gpm\ now allow actual arrays to be passed to
value open arrays, provided the elements of the actual array are
{\em assignment compatible\/} with the formal array element type.
This change is necessitated by a semantic change in the draft international
standard.  There are significant implementation consequences.

Actual arrays passed to value-mode open arrays must now be copied in the
stack frame of the {\em caller}, since only the caller knows if the 
copying requires a change in size.  This might happen, for example, if
a subrange array is passed to a formal array of compatible but differently
sized elements.  In any case, whenever the actual and formal element types
do not match the copy may involve element-by-element range checking.

{\bf Beware:} New object files can safely call old libraries which 
use the previous parameter passing strategy, but old object code cannot safely
call newly compiled modules that export procedures with value open array parameters.
BUILD will issue a warning if new and old object files are being mixed.

\subsection{More general casts are allowed}
\gpm\ now allows a much wider range of values to be cast to other types.
Except for numeric literals, which are expressly forbidden in the standard,
almost any value can be cast to any type.  Previously \gpm\ only allowed
casts which did not violate the value alignment requirements of the 
target machine.  Now, the compiler will move the value through an
appropriately aligned intermediate storage location if that is necessary.

{\bf Beware:} None of these changes removes the intrinsically unsafe nature
of the casting operation.  The operation deliberately subverts the type-safety
of the language, and almost always produces an implementation dependent result.

\subsection{Extended assignment semantics for system types}
\gpm\ extends the assignment semantics to allow any word-sized value to
be assigned to a variable of type {\em SYSTEM.WORD\/}.  Likewise,
any byte-sized value may be assigned to a variable of type {\em SYSTEM.BYTE\/}, 
and any pointer value may be assigned to a variable of type 
{\em SYSTEM.ADDRESS\/}.  The semantics of assignement to these system types
is thus identical to the semantics of substitution of such values to
formal parameters of such types.

{\bf Beware:} These extensions are not standard, and are thus not portable,
except to other versions of \gpm.   The compiler will issue a
warning 494 on a first use of any of these non-standard assignments in a 
module.  If the {\bf --X} or {\bf --V} flags are used, every such violation
will be marked with a warning.

\section{Changes since the first ({\em HP-UX\/}) release}
% note changes to gpmake, new gpxrf, fwd refs to later material 

\subsection{Optional case sensitivity\label{namecase}}
\gpm\ and all the associated utility programs normally create filenames 
based on module names by moving the
names to lower case.  When looking up filenames based on module names,
\gpm\ looks for a lower case name, then checks for an {\em MSDOS\/}-length
name.  It is possible to customize this behaviour by using the environment
variable {\em GPNAMES\/}.  The value~---
\begin{verbatim}
          GPNAMES=mixed
\end{verbatim}
causes all utilities to create and search for mixed case names, while the
default, equivalent to~---
\begin{verbatim}
          GPNAMES=lower
\end{verbatim}
creates lower case names.  The value string in the environment variable
is not case sensitive, so ``MixeD'' works equivalently.

For either setting, the strategy for searching for filenames is as follows: 
first the
name is sought at full length in the  specified case regime, if that lookup
fails the full length name with the alternative case regime is sought, finally
the dos-length name is sought in lower case.  The library which incapsulates
this behaviour is supplied with the distribution. The definition of the module
{\tt gpfiles.def} has further information.

\subsection{New order of reading symbol files}
When compiling an implementation part, \gpm\  now reads the module's
own symbol file first, rather than last as previously. This avoids a number
of difficulties with indirect imports, and allows conformance with the
proper order of initialization at runtime.

Due to this change, \gpm\ is now more strict in its enforcement of 
the rules for the import of typenames into implementation parts. Previously,
the re-import of a typename imported into the definition part was optional. 
It is now mandatory. This is in comformance with the proposed draft standard.

This change will break some programs which relied on the implicit import
from the definition part. To fix these programs, simply ensure that the
implementation also imports the typename.

\subsection{Less restrictive forward references}
The proposed draft standard distinguishes two variations on the 
{\em declaration before use} theme. Compilers with so-called single-pass
restrictions require declaration before {\em any\/} use of the name.
Other compilers only demand declaration before use {\em in a declaration}.

Previous releases of \gpm\ only demanded declaration before use in a 
declaration, but treated import into a nested module as use in a declaration.
This is much less restrictive than the single pass compilers, but was
more restrictive than compilers based on the ETH multi-pass 
front-end\footnote{This includes all LogiTech compilers before
version 4, the SUN Microsystems compilers, and many others.}.
The \gpm\ front-end now does not treat the occurrence of a name in a
module import list as a use in a declaration. We believe that \gpm\ now
is actually more lenient in this regard than the old multi-pass compilers.

\subsection{User guide includes gpm-pc debug information}
All versions of \gpm\ documentation now include a small section on the 
stack unwind format for the freeware version gpm-pc.

% here starts the additions for the Feb 1991 additions

\subsection{Enhanced interactive mode}
The interactive ({\bf --I}) mode of the compiler now allows more information
to be requested. In case of errors in which type mismatches are
involved, the type names are given. This facility is only possible in
interactive mode, as the error buffering of the compiler does not store
the type contexts, for  later display. However, the rest of the
expanation of the error message is available in the normal batch mode
by using the explain {\bf --X} option.

\subsection{New libraries}
These release notes contain details of three new libraries
not listed in the current version of the {\em User guide}.
These are {\em TextInOut} which provides file input-output
with similar functionality to the traditional library {\em InOut},
{\em SysClock}, a preliminary implementation of a proposed
standard module, and {\em AsciiTime} a string time utility.
These are described later.

\subsection{User-selected editor for interactive mode}
The compiler driver program now permits the editor used in
interactive mode to be set by a user-defined environment string.
The environment variable {\em GPMEDITOR} is of the form
\mbox{{\em edName} \{{\em arg} $|$ \%\}}, 
where as ususal the braces denote
optional repetition, and the vertical bar denotes choice.
In the case of the editor {\em vi} the variable might have been
defined to the Bourne shell by the command
\begin{verbatim}
      GPMEDITOR="vi +# %"
\end{verbatim}
In this format {\em edName} is the name of the chosen editor,
such as {\em vi} or {\em emacs}.\footnote{In the case of {\bf gpm-pc} or
\gpmdj\ do not forget that if the set command is placed in a DOS batch file,
the above command would appear as {\tt set GPMEDITOR=vi +\# \%\%}, since the batch 
processor strips the first percent sign.}
The remaining arguments may appear 
in any order, with the following macro substitutions --- the 
percent sign \% is replaced by the name of the file to edit,
while any embedded \# sign denotes the line number on which 
the editor is to be started. Thus with the above definition, if the 
program {\em foo.mod} has an error on line 23, interactive mode
will invoke the editor {\em vi} with command string
\verb!"vi +23 foo.mod"!. As a second example, if the environment
string was \verb+"uemacs -g# %"+ the same program would have
invoked the editor {\em uemacs} with the command string
\verb+"uemacs -g23 foo.mod"+.

In the event that the variable {\em GPMEDITOR} is undefined, 
the default editor {\em vi} is invoked exactly as before.

Finally, use of the environment variable allows users to retain
some functionality with simple editors. Suppose an editor
{\em simple} has no facility for sending a starting point 
from the control line. In this case the string just omits
any mention of the line number --
\begin{verbatim}
      GPMEDITOR="simple %"
\end{verbatim}
% end of additions for Feb 1991 additions

\subsection{New options for build}
{\bf build} has some minor relaxation of the rules for entering
command line options, has a minor change to effect of one option,
and has a new major option.
\subsubsection{Format of options to build}
Options to {\bf build} may now be placed in any order, and may be
arbitrarily grouped. This is now similar to the case for \gpm.
Note however that the {\bf --L} option, described below,
must be separated from
other options so that the directory name is not confused with
other options.

\subsubsection{Option --L{\em dir} for archive directories}
The builder now accepts an option which forces the linker to search
a given directory for archive libraries. This allows the use of archive
libraries which are not on the default path (usually {\tt /usr/lib}
and {\tt /usr/local/lib}). This option uses exactly the same format 
as does the linker itself, so that the operating system documentation 
may be referred to for further details. The option consists of
{\bf --L}{\em dir-name}, where {\em dir-name} is the name of
the directory which is to be searched for the archive.

Suppose an archive library {\tt libexample.a} is in the directory
{\tt /usr/henry/lib}. It is presumed that some module in the program
{\tt foo} has a interface import line which reads
\begin{verbatim}
        IMPORT IMPLEMENTATION FROM "-lexample";
\end{verbatim}
This archive will now be correctly searched after the command line
\begin{quote}
{\tt build} {\em other-options} {\tt -L/usr/henry/lib foo}
\end{quote}
other options may be placed either before or after the {\bf --L} option.

\subsubsection{New debug option --D}
On versions using the {\em MIPS} and {\em Intel iapx86\/} processors 
(including {\em DECstation})
there is a new  build
{\bf --D D}ebug option.  {\bf gpm-pc} has this option as the default.

The option causes a runtime procedure call
chain library to be linked. If a program linked with 
this option traps to the runtime system with an error, the procedure
call chain is displayed on the standard error stream. 
Other {\em RISC} processor versions may have this feature added later.

The display is equivalent, in general terms, to that produced by the
{\em where} command of {\bf dbx} or the {\em bt} command of \gdb.

\subsubsection{Different behaviour for build --S}
The builder option -S (a{\bf S}sembler) now has slightly different behaviour.
The option creates temporary files {\tt modbase.c} and {\tt modbase} that
contain the initialization call chain and linker script respectively. This
allows manual editing of the linker script for those experimental situations
where some manual intervention is desired. Previously this option activated 
the linker after creating the files. It now does not do so.

\subsection{Compiler limits}
\subsubsection{Number of identifiers}
Most of the limits referred to in the {\em User guide and reference 
manual} have been relaxed. The number of indentifiers permitted in a 
single compilation unit (including imported identifiers) has been 
increased to 6000, with string table space correspondingly increased.
For {\bf gpm-pc} the limits are correspondingly smaller.

\subsection{Long linker names}
External names which are exported to the linker are now up to 31 
characters in length. These names are formed from the first 10 characters 
of the module name, followed by an underscore character, followed by the 
first 20 characters of the external identifier. Thus procedure {\em 
WriteString} from module {\em StdError} will have the external name
\verb+StdError_WriteString+.

\subsubsection*{Linker name aliases}
In the case of names defined in {\em INTERFACE} definition modules,
as explained below, the name of the defined symbol is exactly as it
is known to the linker. It may be of any length which the linker
itself will allow, and may contain arbitrary underscores. This
change corrects a difficulty which arises with some Xlib external
symbols which only differ after more than twenty characters.  There
is an additional format which allows arbitrary character strings
to be defined as the external names of {\em INTERFACE\/} procedures.

If a module has the following heading~---
\begin{verbatim}
      INTERFACE DEFINITION MODULE Example;
        IMPORT IMPLEMENTATION FROM ...
        ...
        PROCEDURE Foo["CraZy%Name##!!-*&"](...);
        ...
\end{verbatim}
then the exported procedure is referenced as {\em Example.Foo\/} everywhere
in the importing modules, but has the external name 
\verb~CraZy%Name##!!-*&~.  Of course, it is doubtful if any current linker
would accept such a name. The point is \gpm\ doesn't care, {\em any\/} literal
string of any length is acceptable as such an external alias.

\subsection{Short whole-number types}
Early versions of Modula often had various sizes of whole number types 
with names such as {\em SHORTINT, LONGCARD} and so on. The current ISO 
proposals do not support a multiplicity of such types. In principle there 
are only two whole number host types: {\em INTEGER} and {\em CARDINAL},
and all others are subranges of these, with the expected rules regarding 
expression and assignment compatability. \gpm\ supports this model, but 
until this release has always allocated storage based on the full sized 
type.

The current release allocates 4 bytes for the whole number host types, 
but only allocates 2 bytes for subranges if that is sufficient. These 
shortened types  may be used in records and arrays, and allow easy 
linkage to foreign language routines which use the types 
{\bf short int} and {\bf short unsigned}. Even shorter subranges only
require a single byte, and are equivalent to C's signed and unsigned 
characters.

For the convenience of users, the following definitions are supplied.
\begin{verbatim}
    (* !SYSTEM! *) DEFINITION MODULE Types;
      TYPE
        BYTEINT   = [-127 .. 128];
        BYTECARD  = [0 .. 255];
        LONGINT   = INTEGER;
        LONGCARD  = CARDINAL;
        SHORTINT  = [-32768 .. 32767];
        SHORTCARD = [0 .. 65535];
    END Types.
\end{verbatim}
Here are some examples of subrange declarations and their corresponding 
sizes and host-type. Note that if either range limit goes outside the 
limit for the short types defined above, the type will occupy the full 
four bytes.
\begin{verbatim}
    TYPE Sub1 = [3 .. 17]             (* 1 byte,  CARDINAL *)
         Sub2 = INTEGER [3 .. 17];    (* 1 byte,  INTEGER  *)
         Sub3 = [0 .. 40000];         (* 2 bytes, CARDINAL *)
         Sub4 = INTEGER [0 .. 40000]; (* 4 bytes, INTEGER  *)
         Sub5 = [40000 .. 70000];     (* 4 bytes, CARDINAL *)
         Sub6 = [-40000 .. 17];       (* 4 bytes, INTEGER  *)
\end{verbatim}

\subsection{Value-constructors}
Value constructors for records and arrays (as well as for the traditional 
sets) are part of the language standard.  Native code versions of \gpm\ 
implement such constructors for 
constants and variable values. The syntax and use of this feature are 
detailed in the syntax diagrams of the {\em User Guide} and in the 
{\em Technical Reference Manual}.

\subsection{Functions returning arrays}
Native code versions of \gpm\ allow functions to return arbitrary values,
including arrays. Earlier versions of \gpm\ allowed functions to return
records, but not to return arrays.  The two last additions may be used
together for good effect, allowing programs to be written in a very
functional style.

\subsection{New utilities {\em gpxrf, grepdef, decode}}
The source code of the compiler parent process 
``gpm.mod'' is now released with the 
distribution. It is a good example of the use of the {\em UxProcesses}
module to control {\em UNIX} processes. The source code for the
corresponding root process of the load builder,
``build.mod'' is included also.

The functionality of {\bf gpmake} has been significantly increased.
The new version of {\bf gpmake} performs optimized partial recompilation.
The main 
documentation covers the new version in detail. 

A new utility {\bf gpxrf} supplies handy cross-reference listings with 
various optional features. The main documentation has the details.

Another new utility is {\bf grepdef}. This allows the library directory 
path \$M2SYM to be searched for occurences of particular regular 
expressions. This allows exported objects to be easily located in the
libraries.

Yet another new utility is {\bf decode}. This program understands the
format of the symbol files, and is able to turn them back into 
human readable form. It is called with the module name as argument,
and has three levels of verbosity. An online manual file has 
further details.

\subsection{Interface to ANSI C libraries}
Most \gpm\ environments have $C$ compilers which conform to the
{\em ANSI\/} standard. Such environments may contain functions with
floating point formal parameters of type {\tt float}, rather than the normal
default of type {\tt double}, and may expect parameters of type {\tt char}
to not be converted to {\tt int}.  

If you are writing interfaces to foreign libraries written in $C$, you should
be aware that native code versions of \gpm\ pass parameters exactly as would
be expected by an  {\em ANSI-C\/} compiler.  Thus any foreign implementations
in $C$ must be correctly declared with appropriate prototypes.

%% new insert for warning on ANSI C libraries
\subsubsection{WARNING}
There is a potential for difficulty in the use of {\em FOREIGN}
modules in {\em ANSI-C} environments. In such a case, \gpm\ creates
code as if the foreign functions were declared using {\em ANSI-C
prototypes}. If the foreign implementations use traditional C 
declarations, parameters may be incorrectly passed. Problems arise
in the case of {\em value} parameters of types {\em SHORTREAL,
CHAR}, short subranges, and enumeration types. Traditional C performs
implicit conversions on parameters of these types, while the use
of prototypes prevents this. The calling and called code must agree
on this convention. In the case of machine architectures which pass
parameters in registers such errors may go unnoticed, but the code will
fail when moved to machines which pass parameters on the stack and do
not use quad-byte alignment. All such difficulties are avoided by
ensuring that foreign implementations in {\em ANSI-C} environments
{\em always} use prototypes.

\subsection{Miscellaneous features}
\subsubsection{Yet another extension to literal string syntax}
{\em ISO WG-13} has agreed to a significant extension to the syntax of 
literal strings, which provide a concatenation 
operator. This allows strings to be longer than the line length 
of the source file, and allows non-graphic characters to be embedded 
in strings.  The embedding of control characters depends on the treating of
single character constants as (length = 1) strings in the concatenation.
The symbol for string concatenation is the plus sign ``+''.

Thus, character 
constants are treated uniformly with character literals in contexts where 
literal strings are used. Previously, Modula allowed only
the first of the following assignment statements, now all four are 
legal.
\begin{verbatim}
      VAR str1, str2, str3 : ARRAY [0 .. max] OF CHAR;
    BEGIN
      str1 := 'a';      (* char literal treated as a string  *)
      str2 := 15C;      (* char const also treated as string *)
      str3 := Ascii.cr; (* imported const treated as string  *)
      str4 := "hello world" + Ascii.lf;    (* unix specific! *)
\end{verbatim}

\subsubsection{Improved recovery from syntactic errors}
\gpm\ originally implemented an extremely aggressive policy in recovery 
from syntax errors. This policy worked well in many cases, but in some 
instances lead to multiple false restarts. An extreme example is the 
following, in which a single substitution error leads to no less 
than four separate error messages ---
\begin{verbatim}
    1   DEFINITION MODULE Foo;
    2     VAR thing := CHAR; (* should be ":" *)
 ****   ............^ Syntax Error #  110
 ****   ...................^ Syntax Error #  117
    3   END Foooo.
 ****   ^ Syntax Error #  134
 ****   ^ Syntax Error #  105
 ****   ....^ SemanticError #  200
\end{verbatim}
The new error recovery algorithm is less aggressive in its assumptions, 
and does not notify further apparent syntax errors until at least 
three tokens have been successfully parsed following an initial syntax 
error. Equivalent output from the release version is ---
\begin{verbatim}
    1   DEFINITION MODULE Foo;
    2     VAR thing := CHAR; (* should be ":" *)
 ****   ............^ Syntax Error #  117
    3   END Foooo.
 ****   ....^ SemanticError #  200
\end{verbatim}
Note that the semantic error 200 is still detected and notified.

\subsubsection{Multiple file arguments}
\gpm\ now allows input options to be arbitrarily split into groups, and 
allows multiple files to be processed by the same command. For example
The command \verb+gpm -I *.mod+ will compile all Modula files in the 
current directory, in interactive mode. A more complex example is
\mbox{\tt gpm `grep -l Terminal *.mod`}, which will compile all the modules 
in the current directory which import the {\em Terminal} library.

\subsubsection{Assert procedure}
A new built-in procedure {\em Assert\/} allows for very low overhead Boolean 
tests, and specific, compiler generated messages on failure. See the main 
documentation for further details.

\subsubsection{GPM now returns a result code}
\gpm\ now returns a result code, to make shell programming simpler.
The result codes have the following meaning
\begin{itemize}
\item[0] normal completion without error, object code produced
\item[0] normal completion, no object code --- either the module was
         a definition part or the {\bf --S} or {\bf --n}
         options were in force
\item[2] abnormal completion, errors detected in source code
\item[4] the compiler aborted with a core dump
\item[5] arguments to \gpm\ were bad, or source file not found
\end{itemize}
The value returned in the no-object-code case was previously 1,
but is now set to zero in order to fit in with the normal 
conventions of makefiles.

\subsubsection{Different behaviour for gpm -d}
The {\bf -d}angerous flag suppresses warning messages from the compiler.
In previous releases if errors occurred then both warnings and error 
messages would be displayed. In the current release, if both errors and 
warnings occur, the {\bf -d} flag on the command line will ensure that
only the errors are displayed.

\subsubsection{New lexical conventions for identifiers}
\gpm\ now implements the ISO WG-13 proposals for identifiers. Underscores 
are permitted, but adjacent underscores, trailing and leading underscores 
are flagged with an error message. This rule is relaxed for modules which 
are declared to be interfaces to the library system, or which import such 
modules.

\subsubsection{Keyword FORWARD}
\gpm\ does not require forward declarations, but allows them in the 
interests of portability of source code from 
compiler environments with single-pass restrictions.

\subsubsection{Pervasive procedure LENGTH}
This built-in procedure returns the length of character strings. It may 
be used in declarations, and it is evaluated at compile-time if possible, 
or at runtime, if necessary.

\subsubsection{Return type of MIN and MAX}
These functions return the so-called {\em ZZ} type which is compatible with 
both {\em INTEGER} and {\em CARDINAL} if the actual parameter is the name of a 
whole number type.

\subsubsection{New output for Super-Verbose option}
The {\bf --V} compiler flag retains its previous functionality, but
now traces symbol file key values as well. This feature is 
valuable for tracing the origin of inconsistent-key error messages.

The verbose option of the {\bf build} program now prints out the absolute 
path name of each reference file which it reads. This allows the user 
to check whether (for example) the version used is taken from the current 
directory, or from the library path {\em \$M2LIB}.

\subsubsection{New verbose explanations}
The {\bf --X} (eXplain) compiler flag causes error messages to be 
super-verbose, to the same level as {\bf --V}, but without the import and
filename tracing.  This flag also causes the front and backends to identify
their version dates, and the driver program to echo the command lines
sent to each tool.

\subsubsection{Procedure constants}
It is now possible to define a constant which is equated to a procedure 
name. The newly defined constant is a procedure, and designates the same 
procedure as the value to which it was equated. This mechanism is useful 
for renaming procedures for various purposes.

\subsubsection{Uplevel threats to FOR loop control variables}
The testing of threats to control variables is now strengthened.
If a loop control variable is threatened by an uplevel access from a 
procedure nested in the scope of the loop an error is emitted. 
According to ISO WG-13, {\em any} such 
threat is an error, even if the threatening procedure is not called 
within the body of the loop.

\subsubsection{New system functions ENTIER and ROUND}
The {\em SYSTEM\/} module has two non-standard functions, which make the
writing of numerical software much more simple.  Further information on
these tests is in the general chapter on native code versions.

The function {\em ENTIER\/} truncates real values to the greatest 
integer less than the real value.  This function thus rounds toward 
minus infinity.  It is overflow tested by default, and is controlled by the
\$T flag, as for all other overflow tests.

The function {\em ROUND\/} rounds real values to the nearest 
integer to the real value.  This function thus performs a traditional
rounding.  It is overflow tested by default, and is controlled by the
\$T flag, as for all other overflow tests.

\subsubsection{New warning 495}
A special warning message 495 is issued for 
built-in procedures which are expected to change their name, 
functionality, location or type in the next release.
In this release these are the following
\begin{itemize}
\item[] {\em ABORT} --- to be replaced by {\em HALT} next release
\item[] {\em SHIFT, ROTATE} --- become only function procedures next release.
	This release allows either function or pure procedure use of these
	procedures
\item[] {\em INCADR, DECADR} --- names will disappear next release.
	The current release recognises the new synonyms {\em ADDADR, SUBADR}
\end{itemize}

\subsubsection{New error mesages 319, 320}
It is illegal to attempt to manipulate a formal open array except element 
by element. For example the following is illegal ---
\begin{verbatim}
        PROCEDURE Foo(VAR str : ARRAY OF CHAR);
        BEGIN
          str := "some string"; (* !! illegal !! *)
\end{verbatim}
Errors such as this previously gave rise to an incompatible type message, 
but now have a specific error message associated with them.

There are several changes in the internal compiler structure associated 
with coroutines. One of these is a limit to the depth of static nesting
which is allowed for procedure declarations.
This limit is currently 18. Any attempt to declare procedures more deeply 
nested than this will be flagged with an error 320.

\section{New library modules}
  \subsection{Filename lookup strategy}
The module-name to filename conversion, based on environmental variable
{\em GPNAMES\/}, is described in section \ref{namecase}. The library which
supports this behaviour is named {\em GpFiles}, and is
supplied for the convenience of users who wish to
write further utilities to manipulate programs in the \gpm\ environment. The 
definition contains procedures to create filenames from module names, and
to implement the standard lookup strategy either in the current directory, 
or on a specified directory path.

  \subsection{Cardinal sequences}
The {\em CardSequences} module provides an extremely useful set of 
operations on traversible sequences of cardinals. It is invaluable for 
such things as building programs like {\bf gpxrf}. 

In general terms, the facilities (and the internal code) are identical to 
that of the module {\em GenSequenceSupport}, which builds sequences of 
{\em any} type compatible with the amorphous {\em ADDRESS} type. 
However, note the very important difference that a {\em GetNext} 
operation on an empty generic sequence returns the ``NotAValue'' NIL.
The same error with a cardinal sequence will cause a memory-error
exception to be raised.

Unlike {\em GenSequenceSupport}, this module is type-safe.

\subsection{Numeric conversions}
The numeric conversion routines form an important part of the proposed
ISO standard libraries. They define flexible 
formatting of numeric quantities for output, and the format of acceptable 
input strings. Compared to traditional input-output routines, these 
conversion facilities are exceptionally functional, robust and 
semantically well-defined.

  \subsubsection{Overview, formatting and ConvTypes}
The conversion facilities of the library are implemented by providing a 
separate module for each type, containing various procedures for 
converting between that type and character strings. There are currently 
three such modules for the types {\em CARDINAL, INTEGER,} and {\em REAL}.
All three modules use a uniform set of definitions, provided by a lower 
level module called {\em ConvTypes}.

Because all modules of this type share procedures with the same or 
similar names, programs which import more than one module will usually
use qualified names. Thus programs will refer unambiguously to procedures as
{\em CardStr.Value} and {\em RealStr.Value} and the like.

Module {\em ConvTypes} defines an enumeration which gives names to the 
possible result of string to number conversions, 
and another which specifies field 
alignment for numeric to string conversions. 

There are certain uniform 
rules which apply to all procedures of these modules. For numeric to 
string conversions, on output
\begin{itemize}
\item the output string is placed within the specified field-width,
      aligned as requested, and padded with blanks if needed
\item if the output string is too wide for the specified field-width
      the field is extended to the right
\item the special case of a requested output field-width of zero 
      {\em always} causes a leading blank to be emitted, followed by 
      whatever extra space is required by the previous rule. Thus,
      writing a stream of numbers with field-width zero guarantees that 
      there will be a single separating blank between numbers
\item if the output string is too wide for the actual output string 
      variable parameter,
      the string is silently truncated without an exception being raised
\item for signed types, a sign is emitted only if the value is negative
\item for {\em centre} alignment the {\em units digit} is placed (if possible)
      in the center of the specified output field
\end{itemize}

On input the following rules apply
\begin{itemize}
\item leading whitespace is skipped in numeric conversions, but trailing 
      space is an error. This means that if the string is read from an 
      input stream, the terminating character must not be copied
\item correctly formatted strings which exceed the numeric range of the 
      output type return the ``closest'' value of the type, either
      {\em MAX\/} or {\em MIN\/}, or $\pm${\em HUGE\/} in the case of 
      the {\em REAL} type
\item incorrectly formatted strings cause the {\em Value} function 
      procedure to  raise an exception, and the {\em Format} or 
      {\em Take} procedures to return the {\em wrongFormat} value
\end{itemize}

{\em ConvTypes} also defines a recursive procedure type {\em ScanProc},
instances of which may be used to implement lexical scanners for 
the prescribed type. The module for each type contains one such procedure for
each state of the finite state automaton which recognizes the format of 
the type. Each module exports just one procedure of the type: the one 
which implements the {\em starting state}.

Scanners may use these procedures to classify characters from an input 
stream so that substrings corresponding to valid numeric data may be 
extracted from the stream even in the absence of delimiting characters.
This technique is used within other modules of the ISO proposed 
libraries, not supplied with this distribution. It is probable that this 
particular aspect of the string conversion libraries will be little used 
in this distribution.

  \subsubsection{CardStr}
This module provides conversions between character 
strings and the unsigned type.

As with all of the modules in this set there is a procedure which tests 
strings for correct format {\em prior} to an attempted conversion, and 
another which determines the field-width required to output a number as
a string. These allow a pre-tested style of input/output to be employed.

The procedure {\em Value} attempts conversion without a test, 
while {\em Take} returns an additional variable parameter 
indicating the outcome of the attempt. Procedure {\em Give} converts a 
number to a string with the usual rules on field-width and parameter 
length applying.

  \subsubsection{IntStr}
This module provides conversions between character 
strings and the signed type. The semantics are similar to those for
the previous module.

  \subsubsection{RealStr}
This module is similar in general form to the whole number types.
There are three different output routines however.

{\em Float} output gives output with significand in the range
1.0 to (just less than) 10.0. The exponent is not printed if it is zero
and the number of significant places is specified, as well as the field 
width. Significant places of zero gives maximum accuracy, in this case 16 
decimal places.

{\em Eng} output gives output with significand in the range 1.0 to
(just less than) 1000.0. The exponent is always a multiple of 3, and is 
suppressed if zero. Number of significant places obey similar rules
as for float output.

{\em Fixed} output gives fixed point, rounded to the requested place, 
with positive values being rounded to the right of the decimal point,
negative values to the left. If the integer part of the result will not 
fit into the field, the output string is all \verb+*+'s. This is not exactly
what ISO suggests, but avoids unexpected 308 digit numbers.

Preliminary testing shows these conversions to be numerically stable
and accurate. Future versions may try for a bit more speed.

  \subsection{Character information}
Module {\em CharInfo} 
classifies characters {\em IsDigit, IsUpper, ...} and so on.
The implementation is by macro expansion for those cases where the 
compiler can {\em prove} that it is safe and efficient to do so, 
otherwise by function call.

  \subsection{Output to {\em stderr}}
Module {\em StdError} duplicates the output facilities of {\em Terminal}
but sends its output to the {\em stderr} stream. Best used for error 
messages. If both {\em StdError} and {\em Terminal} are imported, at 
least one of them must use qualified import, since the names are 
identical.

  \subsection{Low-level floating point operations}
Module {\em FREXP} supplies low level manipulation of floating point 
numbers. It is simply an interface to the standard $C$ library 
functions with names {\em frexp, ldexp, modf}. It is used within
{\em RealStr}, and should probably be left there.

  \subsection{Input and output using pipes}
Module {\em PipeUtilities} provides facilities to open and close pipes,
and to make these pipes the standard input or output stream of the 
process. When used in conjunction with the processes module
{\em UxProcesses} it is possible to create pipes and processes,
which are then able to communicate using the pipes. The definition module 
listing demonstrates a typical usage.

Module {\em ShellPipes} provides a mechanism based on the standard
{\em popen} facility of the C library. Using the procedures 
{\em InputFrom} and {\em OutputTo} it is possible to pipe standard input 
from a shell command, or to pipe standard output to a shell command.
The definition module listing outlines a typical usage.

\section{Modified library modules}
  \subsection{Enhancements to UxProcesses}
{\em UxProcesses} has some new facilities not in the previous release.
It now provides {\em sleep} as well as {\em fork, wait}, and two flavors 
of {\em exec}.

New procedures provide access to process, process-group and  
parent-process identifiers, 
and to real and effective user and group identifiers. 
These are all value returning functions.

  \subsection{Assertions and ProgArgs}
The new built-in procedure {\em Assert} is placed in module {\em 
ProgArgs}. The procedure takes a Boolean expression as parameter, 
has an open array as an optional second argument, and
generates no runtime overhead except the expression evaluation.

If the expression evaluates to {\em false}, the program is aborted with a 
compiler generated error message which identifies the module and 
source-code line number at which the error occurred. All assertion tests
may be turned off with a compile time option {\bf --a}. If a message string
is supplied as the optional second argument, this string will replace 
the module-name/line-number message which is generated by default.

  \subsection{Changes to SYSTEM}
The system module is very much along the lines currently proposed by
ISO WG-13. However, it is believed that the following changes are likely 
in the next release. {\em SHIFT} and {\em ROTATE} will become value 
returning functions rather than the proper procedures in this release.
The address modifying function procedures {\em INCADR} and {\em DECADR} 
will have their names changed to avoid confusion arising from the fact 
that the analogously named pervasive procedures {\em INC} and 
{\em DEC} are proper procedures. The new names are
{\em ADDADR} and {\em SUBADR}.

\subsection{End-of-file procedures for Terminal}
The {\em Terminal} library is sufficient for many ``filter''-style UNIX 
programs which read from the standard input and write to the standard 
output. For programs of this very common kind,
the possibility exists that the actual input 
and output streams will be files or pipes. One new function procedure 
gives a systematic way of testing if the input stream has ended. 
The other new procedure can close the output stream without terminating,
for the rare occasions when such functionality is needed.
% =====================================================
% =====================================================
% =====================================================
\input{coroutin}
% =====================================================
% =====================================================
% =====================================================

