\input texinfo @c -*-texinfo-*-
@c %**start of header
@setfilename bibopalica.info
@settitle BIBLIOTHECA OPALICA
@c %**end of header
@ifinfo
This file contains documentation on the use of BIBLIOTHECA OPALICA
as delivered with OPAL-2.1e-p1 / 1 August 1995

Copyright 1994, 1995, 1996 by The OPAL Group

@end ifinfo
@finalout
@titlepage
@title @sc{@titlefont{Bibliotheca Opalica}}
@subtitle A Document on Structured Use And Abuse
@author The OPAL Group
@author written by Klaus Didrich

@page

Copyright @copyright{} 1994, 1995, 1996 The OPAL Group
@end titlepage

@ifinfo
@node Top, BIBLIOTHECA OPALICA, (dir), (dir)
@comment  node-name,  next,  previous,  up

@menu
* BIBLIOTHECA OPALICA::         
* Introduction::                
* Structuring ::                
* Survey::                      
* Special Features::            
* Acknowledgement::             
* Bugs And Flaws::              
* Changes::                     
* Style Guide::                 
* Not For User Purpose::        BIBLIOTHECA OPALICA


Structuring Principles


BIBLIOTHECA OPALICA


Structuring Principles


BIBLIOTHECA OPALICA


Structuring Principles


BIBLIOTHECA OPALICA


Structuring Principles

* Naming of Structures::        
* Orthogonality::               

Survey of Structures

* Internal::                    
* BasicTypes::                  
* Functions::                   
* AggregateTypes::              
* System::                      

Internal

* Strange::                     

Functions

* General::                     
* Orderings::                   
* Special::                     

AggregateTypes

* ProductLike::                 
* UnionLike::                   
* SeqLike::                     
* TreeLike::                    
* SetLike::                     
* MapLike::                     

System

* Debugging::                   
* Commands::                    
* Streams::                     
* Unix::                        

Special Features in @sc{Bibliotheca Opalica}

* Handcoded::                   
* Numbers::                     
* Text::                        
* ABORT::                       

Changes in @sc{Opal} programs necessitated by @sc{Bibliotheca Opalica}

* Incompatibilities::           
* List of Old Structures::      
* Treatment of Text::           

Incompatibilities

* Bitset::                      
* Conversion::                  
* denotation constants::        
* Natural Numbers::             
* Section::                     
* Suspend::                     
@end menu

@node BIBLIOTHECA OPALICA, Introduction, Top, Top
@majorheading BIBLIOTHECA OPALICA
This is the first edition of 
"BIBLIOTHECA OPALICA - A Document on Structured Use And Abuse"

@menu
@end menu

@end ifinfo

@node Introduction, Structuring , BIBLIOTHECA OPALICA, Top
@chapter Introduction

A library is one of the integral components of modern languages. Its
function is to relieve the user of the task of constantly redefining
standard structures. This is especially true for @sc{Opal}, since only two
structures, @code{BOOL} and @code{DENOTATION} are predefined. A library for
@sc{Opal}, containing most data types and functions needed for everyday use,
has been developed in recent years.


These structures do belong to the @sc{Opal} release, but they are not part
of the language. Most of them are written in @sc{Opal} and only some are
substituted by handwritten code (@pxref{Handcoded}) for reasons of
efficiency (both space and time). This difference is not apparent to the
@sc{Opal} user.

This paper offers you an overview of @sc{Bibliotheca Opalica}, so that you
will be able to use (and abuse) the structures in the library. That is, you
will not find explanations of the functions, but you will learn where these
explanations are located. If you need information about a particular
function, please have a look at the signature parts.

It is not the purpose of this paper to give you an introduction to
@sc{Opal}; for this you are referred to @cite{The Programming Language
@sc{Opal} --- The Implementation Language} and @cite{The @sc{Opal}
Tutorial}. Neither does the paper serve as an introduction to the
compilation system, which is explained in @cite{A User's Guide to the
@sc{Opal} Compilation System}.

We first outline the structuring principles which were used in the
design of the library. Then, we proceed through the library
structures explaining what types are defined and what additional structures
are available. Last, we turn to some particularities of @sc{Bibliotheca
Opalica}. The appendix contains, among other topics, a list of the currently
known bugs and an aid to converting programs from the old library to
@sc{Bibliotheca Opalica}.

The @sc{Opal} library has matured in recent years and summarizes the
experience of several years of functional programming. We would like to
also include @emph{your} experience in @sc{Bibliotheca Opalica}. So, if you
have any suggestions or contributions to make, please do not hesitate to
drop us a line or send us a piece of code which may appear in the next
release of @sc{Bibliotheca Opalica}.

@noindent
The @sc{Opal} Group is reachable via email: @code{opal@@.cs.tu-berlin.de}.

@noindent
The @sc{Opal} distribution is available via @code{WWW}
at the URL @code{http://uebb.cs.tu-berlin.de/~opal/}

@node Structuring , Survey, Introduction, Top
@chapter Structuring Principles

@sc{Bibliotheca Opalica} consists of more than 100 different
structures. Lest the user get lost, this multitude of structures clearly
requires a structure of its own.

The first principle of structuring is of course the division of structures
according to their kind, i.e. predefined structures, parameterized
structures, environment access structures and the like. This is detailed in
@ref{Survey}.

There are, however, other structuring principles which are valid across
these divisions. One of them is the naming of structures which follows
certain principles and allows you to conclude some information about a
structure from its name.

The other is the principle that similar functions have the same name in
@sc{Opal}, even if they work on different data types. Typical examples of
such functions are functions for converting data types to textual
representation.

@menu
* Naming of Structures::        
* Orthogonality::               
@end menu

@node Naming of Structures, Orthogonality, Structuring , Structuring
@section What's in a Name? --- Naming of Structures

Roses smell as sweet by any other name, and likewise the semantics of a
structure is not affected by its name. To the user, however, the name of a
structure provides valuable clues about the content. By adhering to naming
principles, the task of remembering the existing structures is also made
easier.

In @sc{Bibliotheca Opalica} the following principles are used:

@table @asis
@item @var{Type}
This is always the basic structure for the mentioned @var{type}. It contains
the type definition, if possible with a free type declaration, and the most
basic functions that are needed for using this @var{type}. Note that types
always start with lowercase (e.g. @code{nat}), while structure names are
capitalized (e.g. @code{Nat}).

@item @var{Type}Conv
These structures (e.g. @code{CharConv}, @code{SetConv}) contain functions
that convert from data type @var{type} into another type, while preserving
information; i.e. they are (in principle) invertible. Typical examples are
conversions to text or converting different types of numbers.

This also works the other way round: If you are looking for a function which
converts members of type @var{type}, it is usually found in Structure
@var{Type}Conv. There are, however, exceptions to this rule:

There is no Structure @code{DenotationConv}. Conversions from
@code{denotation} to @var{type} are considered to be a kind of 
"pseudo-constructor" and are therefore placed in Structure @var{Type}.

Conversions from sequences to another aggregate type
(@pxref{AggregateTypes}) are likewise not included in @code{SeqConv} but in
@var{Type}Conv. 

@c @item @var{Type}Compare
@c Here, functions for ordering or testing for equivalence are summarized. You
@c will usually have to give an additional ordering or equivalence relation,
@c since the standard relation on the components is not deducible. Examples are
@c @code{PairCompare} and @code{SeqCompare}.
@c 
@c If the ordering relation is known (e.g. strings), then the usual comparison
@c operators are declared in Structure @var{Type}.

@item @var{Type}Filter
Functions in these kind of structures (like @code{SetFilter}) take a
bool-valued function and an aggregate type and remove those elements which
--- as required -- either fulfill or do not fulfill the given predicate.

@item @var{Type}Fold
@itemx @var{Type}Reduce
These structures (@code{SeqFold}, @code{SeqReduce}, and so on) contain
functions which connect every element of an aggregate type with a given
function. Reducing requires a start value while folding does not, but the
latter is more restrictive, e.g. it is not defined on empty objects.

@item @var{Type}Map
In structures like @code{SeqMap}, @code{SetMap}, and their counterparts for
other aggregate types, we find functions for applying one or several
functions to every element of the aggregate type.

@item @var{Name}By@var{Attr}
These structures give hints about different kinds of implementation of
@var{Name}. This applies to data types (e.g. sets: @code{SetByPred}) or
different methods for defining certain functions (e.g. orderings:
@code{OrderingByInjection}).

@end table

Other kinds of structures are still in the development stage and will be
added in later releases.



@node Orthogonality,  , Naming of Structures, Structuring
@section Orthogonality

Orthogonality means that functions which perform similar tasks are named
similarly. The principles of structuring structures obviously support
sticking to the "Principle of Least Astonishment".

Also note that differently implemented types have the same name, and can
therefore easily be replaced by another implementation: simply change the
imported structure and recompile the code. So for sets of natural numbers
you can choose whether to use the ordinary implementation or the
bitstring-oriented implementation by switching from @code{IMPORT Set[nat]
ONLY set @{@} + in @dots{}} to @code{IMPORT Bitset ONLY set @{@} + in
@dots{}}.

The reader should particularly note the following:

@itemize @bullet
@item 
There is always a function @code{` :}@var{type}@code{-> denotation}. If the
type is parameterized, the functionality is augmented by functions for
converting the parameter type, e.g. sequences: 
@w{@code{` : (data -> denotation) -> seq -> denotation}}.
The only exception is the type
@code{denotation} itself. Even for types like 
@code{set'SetByPred} (@pxref{AggregateTypes}) which do
not provide a sensible textual representation,
a function which returns a fixed text
describing the type is supplied.

The function @code{`} is located in Structure @var{Type}Conv.

@item
If a conversion from @code{denotation} to @var{type} is given, this function
is called @code{!} and located in Structure @var{Type}.

@item
Functions which convert one type into another type are called
@code{as}@var{Type}, e.g. @code{asNat} for a function which converts type
@code{int} to type @code{nat}. The exceptions are the functions @code{`} and
@code{!} (see above).

@item 
Aggregate types (@pxref{AggregateTypes}) have many similarities which are
exploited in the naming of functions. 

@table @code
@item !
Selection of one of the components.

@item #
The size of the aggregate object.

@item %
Combining up to eight elements to produce an aggregate.

@item .. iter
Generating elements with the help of a function.

@item *
The mapping operator(s).

@item / (\)
Reducing and folding. If order of elements matters, then both functions
(left and right reduce or fold) are given.

@item |
Filtering out elements with a given predicate.

@item exist? forall? 
Applying predicates to all elements of an aggregate.

@end table
@end itemize



@node Survey, Special Features, Structuring , Top
@chapter Survey of Structures

We will now take a look at the structures in @sc{Bibliotheca Opalica}. We
will not examine each and every structure, rather will provide explanations
concerning each group of structures. There will be no further comment on
structures whose purpose is explained by the naming principles
(@pxref{Naming of Structures}).

The structures of @sc{Bibliotheca Opalica} have been grouped into five
subsystems, some of which have been further divided into subsubsystems. The
user need not be aware of the structure of @sc{Bibliotheca Opalica} for
using @sc{Opal} and the @sc{Opal} Compilation System. Searching for
information about the library is made easier, though, if you know about the
structure.

@iftex
@table @code
@item Internal 
The subsystem @code{Internal} contains structures which are dependent on the
actual implementation.

@item BasicTypes
In this subsystem the "bread-and-butter" structures are compiled. This
includes structures for handling booleans, denotations (@pxref{Text}),
characters and numbers (@pxref{Numbers}). 

@item Functions
This subsystem contains structures for creating functions from other
functions.

@item AggregateTypes
Aggregates allow you to group elements together and treat them
as a single entity. There are heterogeneous aggregates, such as Cartesian
products and disjoint union, as well as homogeneous aggregates, such as
sequences (a.k.a. lists), binary trees, sets, mappings and the like.

@item System
Structures in the Subsystem @code{System} provide access to the
environment. This encompasses structures for debugging, access to the
facilities of the operating system and, last but not least, structures for
input and output.

@end table
@end iftex


@menu
* Internal::                    
* BasicTypes::                  
* Functions::                   
* AggregateTypes::              
* System::                      
@end menu

@node Internal, BasicTypes, Survey, Survey
@section Internal

The subsystem @code{Internal} is divided into further subsystems. The user sees only the subsubsystem @code{Strange}.

@menu
* Strange::                     
@end menu


@node Strange,  , Internal, Internal
@unnumberedsubsec Strange

As the name suggests, these structures are not for everyday use. They do
have their purpose, but think twice before you use them. They are not
semantically safe and, in most cases, you will be able to do very well
without them.

@table @code

@item CAST
gives you the possibility of lying about the type of an expression. There is
no guarantee about any properties of the result. In particular, you may not
assume that @code{cast[a,b](cast[b,a](x))} yields @code{x} again, and be
assured that casting, say @code{pair[nat, char]} to
@code{seq[option[string]]}, will cause considerable confusion.

@item EQUALITY
provides a generic equality on data types which do not
contain functions. Note that this constraint is not checked by the
compiler.

@item INLINE
provides an interface to usage of C macros. This is only useful in
connection with handcoding(@pxref{Handcoded}).

@end table

@node BasicTypes, Functions, Internal, Survey
@section BasicTypes

Basic Types are finitely or infinitely enumerable types. Currently, the
following types are members of this subsystem:

@table @code

@item bool
@tindex bool
As noted before, @code{bool} is a built-in sort. The predefined functions
can be looked up in structure @code{BOOL}. Another structure allows for
converting @code{bool} to @code{denotation}.

@item char
@tindex char
Apart from the basic operations, there is a structure @code{PrintableChar}
which contains definitions for the ASCII character set.

@item denotation
@tindex denotation
The type @code{denotation} is predefined. The predefined signature is called
@code{DENOTATION}.  The structure @code{Denotation} supplies additional
functions which make usage of denotations possible.

@item nat, int, real
@tindex nat
@tindex int
@tindex real
These structures deliver the usual functions on the different kinds of
numbers. Note that identifiers like @code{64} are not special to @sc{Opal} ---
they are like any other identifier. Hence you have to define other
numbers for yourself. The advice is to define a constant with an appropriate
name, e.g. @samp{DEF hashtablesize == "497"!}.

The functions @code{!} are very strict and do not accept anything besides
the indicated characters ("anything" includes whitespace!). This is to
prevent you from typing mistakes@footnote{The old library was less strict
about this, which sometimes led to confusing results.}.

@item rel, subrel
@tindex rel
@tindex subrel
These structures contain types which are used to indicate a result of a
comparison with functions found in a @var{Type}Compare structure.

@item void
@tindex void
This is the simplest data type. It consists of exactly one constant
constructor @code{nil}.

@item ABORT
is sort of an annotated "undefined". Use this structure to give the user of
your @sc{Opal} programs hints as to what might have gone wrong. It is a good
idea to add the source, that is, name and origin of the function, to the
message. @xref{ABORT}.

@end table


@node Functions, AggregateTypes, BasicTypes, Survey
@section Functions

The @code{Functions} subsystem is divided into three parts: @code{General}
for composition, iteration and the like, @code{Orderings} for constructing
ordering relations, and @code{Special} for structures which need special
care in their usage.

@menu
* General::                     
* Orderings::                   
* Special::                     
@end menu

@node General, Orderings, Functions, Functions
@unnumberedsubsec General

@table @code

@item funct
@tindex funct[from, to]
This structure allows a function type to be "packed" in a data type.

@item Compose, ComposePar
These structures define functions for composing two functions either
sequentially or concurrently.

@item Control
This structure offers you basic control structures for iterating functions.

@item Predicate
This structure allows you to combine bool-valued functions almost the same
way boolean values can be combined. Of course, no equality on functions can
be defined in @sc{Opal}.

@end table


@node Orderings, Special, General, Functions
@unnumberedsubsec Orderings

When defining an (enumerated) type, defining the ordering relations by
yourself can often be both tedious and lead to errors. The structures in
this subsystem facilitate the task:

@table @code

@item OrderingByInjection
This structure is to be instantiated with an injection into the natural
numbers and then yields the usual ordering relations.

@item OrderingByLess
Use of this structure requires still to define the "less" relation, but
relieves you of defining the other operations.

@item InducedRel
This structure is more general than the previous two. You may translate any
relation to another type by supplying an appropriate translation function.

@end table

@node Special,  , Orderings, Functions
@unnumberedsubsec Special

Functions provided by structures of this subsystem generally come with the
warnings "handle with care" and "use only, if you know what you are doing".

@table @code

@item AcceleratorC, AcceleratorF
The purpose of these structures is a cost-effective evaluation of binary
functions, which is often available if both arguments are known to be
equal. Sometimes it is possible to apply a quick (but somewhat dirty) test
for equality, which may fail even if both arguments are equal, but which
never yields true if they are not.

@end table



@node AggregateTypes, System, Functions, Survey
@section AggregateTypes

The concept of aggregating elements to a single entity is one of the most
important in functional programming. @sc{Bibliotheca Opalica} offers you
many different ways to do this:

@itemize @bullet
@item
Product types correspond to Cartesian products of different data types.

@item
Union types allow for the disjoint union of data types.

@item
Sequence-like types comprehend elements of a single data type while
preserving order.

@item
Tree-like data types structure data in the form of binary trees.

@item 
Set-like data types differ from sequence-like data types in that order does
not matter.

@item
Map-like data types contain pairs of data types which constitute finite
mappings.

@c @item
@c Graph-like data types comprise multi-dimensional types.

@end itemize


@menu
* ProductLike::                 
* UnionLike::                   
* SeqLike::                     
* TreeLike::                    
* SetLike::                     
* MapLike::                     
@end menu

@node ProductLike, UnionLike, AggregateTypes, AggregateTypes
@unnumberedsubsec ProductLike

This subsystem contains structures for the use of Cartesian products of
types. Our experience is that more than four sorts are usually not needed.

Type @code{void} may be considered as the empty product (@pxref{BasicTypes}).

@table @code

@item pair, triple, quad
@tindex pair[data1, data2]
@tindex triple[data1, data2, data3]
@tindex quad'Quadruple[data1, data2, data3, data4]
For these structures functions are provided to build and to unbuild objects,
to select components, to map a function onto the components. Additionally,
@code{pair} can be compared. Note, that type @code{quad} is defined in the
Structure @code{Quadruple}.

@item AnonPair, AnonTriple, AnonQuadruple
These "anonymous" structures are like their named counterparts, but they
refer to the built-in tupling of data types in @sc{Opal} which are denoted
by the keyword @code{**}. Hence, only the selectors are defined.

@end table


@node UnionLike, SeqLike, ProductLike, AggregateTypes
@unnumberedsubsec UnionLike

This subsystem contains structures for disjoint union of data types.

Type @code{void} may be considered as the empty union (@pxref{BasicTypes}).

@table @code

@item option
@tindex option[data]
This is the most important type in this subsystem. It is the disjoint union
of type @code{void} (@pxref{BasicTypes}) with an arbitrary other data type.

This type is useful for fusing two functions like @code{test? : some ->
bool} and @*@w{@code{select: some -> data}} (where @code{select} is undefined
when @code{test?} fails) into a single function @code{testAndSelect: some ->
option[data]}.

@item union
@tindex union'Union2[data1, data2]
@tindex union'Union3[data1, data2, data3]
@tindex union'Union4[data1, data2, data3, data4]
This type comes in three flavours: as union of two, three or four data types.

@end table


@node SeqLike, TreeLike, UnionLike, AggregateTypes
@unnumberedsubsec SeqLike

Here you will find structures for dealing with aggregate types where number
and ordering of elements matters.

@table @code

@item seq
@tindex seq[data]
By far the most frequently used type in functional programming is the
sequence (or list) type. Consequently, this type is well supported by many
structures. Besides the structures which are explained by their names
(@pxref{Naming of Structures}), there are structures for indexing sequences
(@code{SeqIndex}), special variants of mapping (@code{SeqMapEnv}),
structures for dealing with nested sequences (@code{SeqOfSeq}), for sorting
sequences (@code{SeqSort}) and for combining sequences of equal length
(@code{SeqZip}).

@item string
@tindex string
The type @code{string} can essentially be treated as an instantiation of
type @code{seq} with type @code{char}. Some additional functions, which
ensure backwards compatibility with the old library, are also available.
There is no structure for nested strings or for combining two strings of the
same length; the comparison operators are defined in the base structure.

For a discussion about the difference to type @code{denotation}, see
@ref{Text}.

@item union
@tindex union'BTUnion
This type is defined in structure @code{BTUnion} and is a disjoint union of
basic types, i.e. @code{bool, nat, int, real, char, string} and
@code{denotation}. It is used in the structures for formatted input and
output.

@item StringFormat, StringScan
These structures contain functions for formatted input and output of the
types which are combined in the type @code{union'BTUnion}. The usage is
similar to that of the functions @code{printf} and @code{scanf} from
@code{C}, so that usage of the functions from @sc{Bibliotheca Opalica}
should be no more difficult than use of the functions from @code{stdio} of
ANSI-C.

@end table

@node TreeLike, SetLike, SeqLike, AggregateTypes
@unnumberedsubsec TreeLike

Tree-like aggregates store the data in binary trees. We have general binary
trees (in the following often simply called @dfn{trees}), heaps and balanced
search trees.

@table @code

@item tree
@tindex tree[data]
Structures of this family implement functions for binary
trees. @code{~'TreeCompare} compares trees of differenty types. The other
members of this family are standard (@pxref{Naming of Structures}). Note that
there are more variants of mapping and reducing functions than e.g. on
sequences. 

@item IndexingOfTrees
This structure contains functions which handle indices of trees and are
independent of the element type. Trees are indexed by the followign scheme:
The root node is assigned index @i{0}, and if any node has index @i{i}, the
left child has index @i{2i+1}, the right child has index @i{2i+2}. (This
differs from other indexing schemes, since we assign @i{0} to the root node.)

@item heap
@tindex heap[data, <]
Heaps are trees whose root value is less or equal than either one of the
children's values. In addition to trees, we can combine heaps and extract
the minimum, so you may use this data type for a priority queue.

@item bstree'BSTree
@tindex bstree'BSTree[data, <]
Balanced search trees are trees whose root value is greater than the value
of the left child and is less than the value of the right child. The trees
are balanced, that is, sizes of both subtrees must be similar. (Actually,
the criterion is @code{1/w <= size(left) / size(right) <= w}, where @code{w}
is a small positive natural number.)

@end table

@node SetLike, MapLike, TreeLike, AggregateTypes
@unnumberedsubsec SetLike

Set-like aggregates are similar to sequences, but order of elements does not
matter, and in most cases it also does not matter how often an element is
added to an aggregate.

There are five different implementations of sets. This plentifulness shows
that there is no ideal implementation for every purpose. The advantages and
disadvantages of the additional implementations are given below.

@table @code

@item set'Set
@tindex set'Set[data, <]
This family of structures defines functions for finite
sets. @code{SetConstr} comprises functions for Cartesian product and
disjoint union of sets, the other structures adhere to the naming principles
(@pxref{Naming of Structures}). All structures take as an additional
parameter an ordering predicate, otherwise functions like @code{subset} or
@code{in} cannot be implemented@footnote{An equality predicate would have
been sufficient too, but an ordering results in a more efficient
implementation.}.

@item set'SetByInj
@tindex set'SetByInj[data, #]
These structures provide a slightly different interface. Instead of an
ordering predicate you must supply an injection into the natural numbers. 

@item set'SetByPred
@tindex set'SetByPred[data]
These sets are defined by a describing predicate. This is useful if you want
to perform operations on big sets with short descriptive predicates, and it
is a device for dealing with infinite sets in @sc{Opal}. The disadvantage
is that many functions on sets (e.g. equality, subset) are not computable for
these sets and can therefore not be implemented.

@item set'SetByBST
@tindex set'SetByBST[data, <]
These sets are represented internally by balanced search trees and are more
efficient in including, excluding and searching single elements than the
standard implementation.

@item set'Bitset
@tindex set'Bitset
The naming of this family of structures is really an anachronism --- a
better name would be @code{SetOfNat}. This type is handcoded and provides an
efficient (with respect to time and space) device for dealing with sets of
small natural numbers.

@item bag
@tindex bag[data, <]
Bags (sometimes called multi-sets) are similar to sets, but the frequency of
elements matters. So some additional functions on bags are available;
otherwise they are treated in the same way as the standard implementation of
sets (@code{set'Set}).

@end table


@node MapLike,  , SetLike, AggregateTypes
@unnumberedsubsec MapLike

Here you can find structures which implement finite mappings.

@table @code

@item map
@tindex map[dom, <, codom]
This is the type for general finite mappings. For an efficient
implementation, an ordering relation on the domain type must be
provided. Reducing and mapping is defined on the codomain, filtering checks
both components of a pair. Additional functions are provided for inverting a
map (@code{MapInvert}) and for composing two maps (@code{MapCompose}).

@item array
@tindex array[data]
This is a handcoded mapping from natural numbers to an arbitrary data
type. Indices start at 0. The order on natural numbers induces an order of
elements, so both variations of fold and reduce are available

@end table



@c @node GraphLike,  , MapLike, AggregateTypes
@c @unnumberedsubsec GraphLike
@c 
@c This subsystem is still under construction. The only structures currently to
@c be found here are inherited from the former library and are only retained
@c for backwards compatibility.
@c 
@c @table @code
@c 
@c @item avl 
@c @tindex avl[data, <]
@c These structures implement AVL trees. As with other types, an ordering
@c relation must be provided for some operations which cannot be implemented
@c otherwise.
@c 
@c @end table 


@node System,  , AggregateTypes, Survey
@section System

This subsystem subsumes all structures which provide functions for
communicating in some manner with the environment. It is in turn divided
into four subsystems: @code{Debugging} contains structures for support in
debugging @sc{Opal} programs (surprise, surprise!), @code{Commands} provides
the basic declarations for the @sc{Opal} Command Script I/O, the structures
in @code{Streams} define a simple interface for accessing files, and
@code{Unix} contains structures tailored for @sc{Opal} programs which run
under @code{Unix}.


@menu
* Debugging::                   
* Commands::                    
* Streams::                     
* Unix::                        
@end menu

@node Debugging, Commands, System, System
@unnumberedsubsec Debugging

This subsystem contains just one structure, which in our opinion could not
be assigned to any of the other subsystems.

@table @code

@item DEBUG
This structure contains functions which aid in debugging by means of
side-effect output of messages. This constitutes dirty programming style and
should not be used in your ready-to-be-shipped program, but sometimes
debugging is quicker when you don't quite stick to the rules.

@end table


@node Commands, Streams, Debugging, System
@unnumberedsubsec Commands

This subsystem comprises structures which define functions on
@var{commands} which are the base type for the @sc{Opal} Command Script I/O,
and some structures for communicating with the environment which are
independent from the underlying operating system.

@table @code

@item com
@tindex com[data]
The command type @code{com} is essential for I/O in @sc{Opal}. It is
always parameterized with the type which is to be passed to the next
command. If there is no such type, you have to use type @code{void}
(@pxref{BasicTypes}). @code{ComAction} defines abbreviations for the
instance @code{com[void]}. Means for composing commands are given in
@code{ComCompose} and @code{ComCheck}; @code{ComSeqReduce} reduces a
sequence to a single command. @code{ComChoice} finally provides external
choice between two commands.

@c @item thread
@c @tindex thread
@c The structure @code{Thread} provides support for co-processes as you know
@c them from @sc{Modula 2}, for example.


@c @item pipe
@c @tindex pipe[data]
@c @code{Pipe} defines functions for communicating between threads.

@item agent'ComAgent[result]
@tindex agent'ComAgent[result]
An agent executes a monadic command concurrently with other
agents. Communication between agents is supported by synchronization
with the termination of an agent and by client/server oriented
communication via service access points (see structure
@code{ComService}). A special command for delaying an agent is provided
in the structure @code{ComTimeout}.

@item sap'ComService[in, out]
@tindex sap'ComService[in, out]
This structure provides a model for agent communication based on the
client / server approach.  Client and servers communicate via so-called
service access points (SAPs).

@item Env
This structure provides access to arguments with which the program was
called, and to the environment variables. 

@item Random
This structure implements a pseudo random number generator.
@end table


@node Streams, Unix, Commands, System
@unnumberedsubsec Streams

Streams are a simple and abstract means for reading or writing data from or
to a file.

@table @code

@item Stream
This is the basic structure and contains functions for text input and output.

@item BinStream
This structure contains functions for reading and writing arbitrary data
types. Since the files contain no information about the type which was
written into them, strong typing is violated. You can use a tag to identify
the correct file type for yourself. Note that this tag is internally
augmented to ensure that the binary format used by internal routines is the
same.

@end table

@node Unix,  , Streams, System
@unnumberedsubsec Unix

The structures described here are tailored especially for the Unix operating
system. If @sc{Opal} is ever run under another operating system, these
structures will most likely be missing.

For the current release, several structures have been added, which provide
Posix conformant access to system calls. See below under @code{ProcessCtrl},
@code{Signal}, @code{UserAndGroup} and @code{Wait}.

@c This subsystem is still under construction. The number of structures and
@c number of functions listed here will increase in later releases of
@c @sc{Bibliotheca Opalica}.

@table @code

@item file
@tindex file
The structures @code{File} and @code{BinFile} correspond roughly to
@code{Stream} and @code{BinStream} (@pxref{Streams}). They provide functions
for input and output to and from files but are more flexible than the
structures in the subsystem @code{Stream}.

@c @item process
@c @tindex process
@c This structure supports the use of Unix processes.

@item FileSystem
@tindex inode'FileSystem
@tindex device'FileSystem
@tindex filetype'FileSystem
@tindex permission'FileSystem
@tindex filemode'FileSystem
@tindex filestat'FileSystem
This structure provides access to the Unix file system. This structure
contains functions for accessing Unix file attributes like file types,
file modes, inodes, devices, atime, ctime, mtime; working with (hard and
symbolic) links,
renaming files, changing access permissions, working on directories and
creating named pipes.

@code{FileSystemFun} contains some convenient functions for dealing with
file modes.

@item ProcessCtrl
@tindex process'ProcessCtrl
@tindex procstat'ProcessCtrl
@tindex fission'ProcessCtrl
This structure is the successor of @code{Process} which is no longer
supported but still contained. It provides functions for creating,
terminating, mutate processes, getting information about one's own process,
and changing some of the attributes of a Unix process (group ids, working
directory and the like).

@item Signal
@tindex signal
@tindex sigmask'Signal
@tindex sighandler'Signal
@tindex sigaction'Signal
This structure enables the user to deal with signals from an @sc{OPAL}
program. There exist functions for masking signals, sending signals, waiting
for signals and there is also a limited capability for handling signals.

@item time
@tindex time
@tindex wday'Time
These structures allow you to access system time from within @sc{Opal}.

@item UserAndGroup
@tindex userid'UserAndGroup
@tindex user'UserAndGroup
@tindex groupid'UserAndGroup
@tindex group'UserAndGroup
This structure provides functions for managing information about Unix users,
Unix groups and their ids.


@item UnixFailures
This structure contains definitions for constants which describe all
possible causes of failure.

@item Wait
@tindex childstat'Wait
In this structure you will find functions which enable you to wait for the
children of the current process.

@end table


@node Special Features, Acknowledgement, Survey, Top
@chapter Special Features in @sc{Bibliotheca Opalica}

@menu
* Handcoded::                   
* Numbers::                     
* Text::                        
* ABORT::                       
@end menu

@node Handcoded, Numbers, Special Features, Special Features
@section Handcoded Structures

Some structures in @sc{Bibliotheca Opalica} are not implemented in @sc{Opal}, rather are handcoded and implemented in the target language of the @sc{Opal}
compiler. This is done for two different reasons.

One reason is that access to the environment must be provided by some kind
of runtime system. This runtime system is not one monolithic block of code
with which every @sc{Opal} program is burdened. Instead, each structure
which accesses different parts of the environment adds only the
necessary code.

The other reason is that some basic data types are already supported by the
target language. So, for reasons of efficiency, some data types have been
handcoded. In contrast to the structures which provide access to the
environment, these structures could have been implemented in @sc{Opal}.

If, for either of these reasons, you wish to add some handcoded structures
to your system, you are kindly referred to the @cite{Handcoder's Guide}
which is included in the @sc{Opal} distribution.


@node Numbers, Text, Handcoded, Special Features
@section Numbers

Numbers belong to the family of handcoded structures
(@pxref{Handcoded}). You should never make assumptions about possible sizes
of numbers, since these may change in later releases of @sc{Bibliotheca
Opalica}. Use the constants @code{min} and @code{max} wherever possible.

The following (in)equalities are guaranteed to hold
in every implementation of @sc{Opal}:

@noindent
@code{min'Nat = 0}@*
@code{max'Nat >= 1073741822}@*
@*
@code{min'Int <= -536870911}@*
@code{max'Int >=  536870910}@*
@*
@code{min'Real <= -1e+37}@*
@code{max'Real >=  1e+37}

The current implementation exceeds these bounds.


@node Text, ABORT, Numbers, Special Features
@section String vs. Denotation

In @sc{Bibliotheca Opalica} two types designed for textual representation
are available namely @code{denotation} and
@code{string}. Both are implemented differently.

The type @code{denotation} should be used for text which does not change
very often, since insertions and deletions are relatively expensive. Space
requirements, on the other hand, are low. This type is best used for
messages and constant strings.

The type @code{string} has a user interface which is almost identical to
that of sequences. In particular, all higher-order functions are available
for strings, so operations on texts can now directly be defined on type
@code{string}.  Note that strings are implemented differently than
sequences, so operations on strings are faster than operations on sequences
of character, and space consumption is lower.

@node ABORT,  , Text, Special Features
@section ABORT

@code{ABORT} is a special function. It is essentially a function which
yields the undefined value of the parameter type. Hence, you can use this
function to replace the automatically inserted error messages with your own
messages, which may provide more information about the real cause.

The most interesting feature about @code{ABORT} is that tests for
@code{ABORT} are eliminated completely if the optimization switch @code{-op}
is set. Thus, you can develop your program with informative error messages,
then turn on the compiler switch and eliminate all the (expensive) checks
for definedness.


@node Acknowledgement, Bugs And Flaws, Special Features, Top
@appendix Acknowledgement

@sc{Bibliotheca Opalica} is only the latest development of the @sc{Opal}
library.

The predecessor of @sc{Bibliotheca Opalica} was designed by @i{Wolfram
Schulte}, together with @i{Andreas Fett} and @i{Gottfried Egger}; the
structures which are now found in subsystem @code{Commands} were designed by
@i{Gottfried Egger} and @i{Wolfram Schulte}.

The restructuring of the library is the result of fruitful discussions with
@i{Wolfgang Grieskamp}, @i{Joachim Faulhaber},
@iftex
@i{Mario S@"udholt}
@end iftex
@ifinfo
@i{Mario Suedholt}
@end ifinfo
and @i{Sabine Dick}.

The library has profited from many suggestions from (in alphabetical order)
@i{Olaf Brandes}, @i{Christoph Breitkopf}, @i{Gottfried Egger}, @i{Sebastian
Erdmann}, @i{Andreas Fett}, @i{Christian Maeder} and @i{Burkhart Wolff}.

The text was carefully proofread by @i{Niamh Warde}.

@node Bugs And Flaws, Changes, Acknowledgement, Top
@appendix Bugs And Flaws

There are currently no known bugs or flaws in @sc{Bibliotheca Opalica}.


@node Changes, Style Guide, Bugs And Flaws, Top
@appendix Changes in @sc{Opal} programs necessitated by @sc{Bibliotheca Opalica}

When a new library for @sc{Opal} was announced, some people feared they
would have to forget all they knew about the old version, and learn the
whole new library from scratch. This is not the case.

The most important change is the finer structuring. The old library was
divided into three subsystems, two of which were of no interest for ordinary
users. Now, @sc{Bibliotheca Opalica} is divided into many sub- and
subsubsystems. 
@c This shall guide you through the structures of the library. 
The structuring has no significance for the user as far as the
@sc{Opal} Compilation System is concerned.

The other important change is the treatment of text, which involves the
types @code{denotation} and @code{string}. This is detailed in @ref{Text}.


@sc{Bibliotheca Opalica} is highly, but not fully compatible with the former
library. Code which was written using the old library has to be
adapted. We distinguish two kinds of adaptations:

@itemize @bullet

@item 
Relocations involve only @code{IMPORT} statements. You will have to add some
@code{IMPORT} statements which reflect the finer structuring of
@sc{Bibliotheca Opalica}.

@item 
Incompatibilities require change of code in function declarations and
definitions.

@end itemize

We will first specify the incompatibilities and then list old library
structures with the changes they each require. The treatment of text is
considered in a separate section.

@menu
* Incompatibilities::           
* List of Old Structures::      
* Treatment of Text::           
@end menu

@node Incompatibilities, List of Old Structures, Changes, Changes
@appendixsec Incompatibilities

@menu
* Bitset::                      
* Conversion::                  
* denotation constants::        
* Natural Numbers::             
* Section::                     
* Suspend::                     
@end menu


@node Bitset, Conversion, Incompatibilities, Incompatibilities
@appendixsubsec Bitset

The name of the sort has changed from @code{bitset} to @code{set}. The
function @code{maxBit} no longer exists, since these sets are no longer
bounded.

@node Conversion, denotation constants, Bitset, Incompatibilities
@appendixsubsec Conversion

The @code{format} and @code{scan} functions from @code{Conversion} (which have
been relocated) formerly interpreted the backslash combinations
(@code{\n}, @code{\x41}, etc.)
themselves, even in strings. Since denotation
constants are interpreted differently now, this feature has been removed.

The functions @code{! :} @var{basictype}@code{ -> string} (where
@var{basictype} is one of @code{bool, char, nat, int, real}) have been
replaced by @code{ ` : }@var{basictype}@code{-> denotation} in structure
@var{Basictype}@code{Conv} (@pxref{Naming of Structures}).  So you need to
change all applications of these functions, e.g. @code{5!} to @code{!(5`)}
(where the first @code{!} has origin @code{String}) in order to get an
equivalent expression. For treatment of text, see also @ref{Treatment of
Text}.

@node denotation constants, Natural Numbers, Conversion, Incompatibilities
@appendixsubsec Constants of type @code{denotation}

Denotation constants are now interpreted in a C-like way, i.e. combinations
like @code{\n}, @code{\x41}, etc. are now interpreted as a single
character. The only exception is @code{\"}, which is interpreted as end of
text. To denote a single @code{\}, write @code{\\}.

@node Natural Numbers, Section, denotation constants, Incompatibilities
@appendixsubsec Natural Numbers

The constant @code{max'Nat} was raised and is no longer convertible to an
object of type @code{int}. Strictly speaking, this is not an
incompatibility, since this was never guaranteed, but since quite a few
people seem to have relied on this fact we record it here.

If you assumed @code{asInt(max'Nat)} to be defined, you will get a runtime
error message which says @code{asInt'NatConv: natural too large}. A quick
remedy is to replace occurrences of @code{max'Nat} by @code{asNat(max'Int)},
but this is a little bit awkward. A better (but more time consuming)
solution is to check whether your program needs either objects of type
@code{int} or of type @code{nat} and to change it as required.


@node Section, Suspend, Natural Numbers, Incompatibilities
@appendixsubsec Section

The structure @code{Section} no longer exists. Use lambda expressions
instead of the functions which were supplied by @code{Section}.

@node Suspend,  , Section, Incompatibilities
@appendixsubsec Suspend

The structure @code{Suspend} no longer exists. Use lambda expressions
instead of the functions which were supplied by @code{Suspend}.


@node List of Old Structures, Treatment of Text, Incompatibilities, Changes
@appendixsec List of Old Structures

This section contains a list of those structures from the old library which
were modified, and thus necessitate changes in your program.


Structures which are "split into" no longer exist. Structures which are
marked "split off" still exist, but some functions now have to be imported
from different structures.


Functions which are marked "old fashioned" in @sc{Bibliotheca Opalica}
are marked with (+) in the following list.

@table @code

@item ArrayMapReduce
split into @code{ArrayMap} with function @code{*}, and @code{ArrayReduce}
with function @code{/}.

@item Bag
split off @code{BagFilter} with function @code{|}, and @code{BagConv} with
functions @code{explode(+), implode(+), explodeCt(+), implodeCt(+)}.

@item Bitset
sort @code{bitset} renamed @code{set}, function @code{maxBit} no
longer exists.

@item Char
split off @code{CharConv} with function @code{ord(+)}, and @code{NatConv}
with function @code{chr(+)}.

@item ComData
renamed @code{BinStream}.

@item ComEnv
structure is renamed @code{Env}, function @code{random} relocated to
@code{Random}, function @code{localtime} will be relocated to structure
@code{Time}.

@item ComProcess
has been reimplemented differently. See structures @code{Process} and
@code{Pipe} for adapting your code.

@item ComSocket
will be renamed @code{Socket}.

@item ComStream
renamed @code{Stream}.

@item Conversion
split into @code{NatConv} with function @code{! : nat -> string} renamed
@code{` 'NatConv: nat -> denotation}, (similar for type @code{int, bool,
real} and @code{char}); into @code{BTUnion} with type @code{union} and
function @code{u}; into @code{StringFormat} with function @code{format} and
@code{StringScan} with function @code{scan}.

@item Int
split off @code{IntConv} with function @code{asNat}, and @code{NatConv} with
function @code{asInt}.

@item Map
split off @code{MapConv} with function @code{explode(+)} and @code{implode(+)}.

@item MapMapReduce
split into @code{MapMap} with function @code{*}, and @code{MapReduce} with
function @code{/}.

@item PrintableChar
function @code{_} renamed @code{underscore}.

@item Real
split off @code{RealConv} with function @code{trunc(+)}, and @code{NatConv}
with function @code{asReal}.

@item Section
no longer exists.

@item Seq
split off @code{SeqFilter} with functions @code{|, partition, take, drop,
split}, and @code{SeqIndex} with functions @code{!, slice}.

@item SeqFun
split into @code{SeqCompare} with type @code{rel} and functions @code{<, =,
>, <?, =?, >?, cmp} and @code{eq?}, into @code{SeqOfSeq} with function
@code{flat}, and @code{SeqSort} with functions @code{msort} and @code{merge}.

@item SeqMapReduce
split into @code{SeqMap} with function @code{*}, and @code{SeqReduce} with
functions @code{/, \}.

@item Set
split off @code{SetConv} with functions @code{explode(+)} and
@code{implode(+)}, and @code{SetFilter} with functions @code{|} and
@code{partition}.

@item SocketInterNet
will be renamed @code{Internet}.

@item String
split off @code{StringConv} with functions @code{implode(+)} and
@code{explode(+)}, and @code{StringIndex} with functions @code{!, slice,
insert, delete} and @code{:=}.

@item Suspend
no longer exists.

@end table

@node Treatment of Text,  , List of Old Structures, Changes
@appendixsec Treatment of Text

One of the novelties in @sc{Bibliotheca Opalica} is the different treatment
of the types @code{string} and @code{denotation}. We will discuss here why
we made this change and advise which type to choose in which circumstances. 

The situation in the old library was unsatisfactory. First you had the type
@code{denotation}, which was almost unusable, since no functions operated on
denotations (well, one did). Then there was the @code{string} type which,
while it provided a usable interface for simple treatment of text, was not
equipped with a free type. So whenever you wrote an "interesting" function
on text, you first had to convert the string into a sequence of characters,
and, after performing two expensive conversions, you finally had access
to the nice higher-order functions like map, reduce and the like.

This has changed in @sc{Bibliotheca Opalica}.

In principle, the only change you need to make is to adapt the @code{IMPORT}
lines, since all functions on strings have been retained in @sc{Bibliotheca
Opalica}.

However, you should examine your code, and depending on the usage of text,
choose one of the following approaches:

If you have strings that are not changed very often you should
consider changing type @code{string} to type @code{denotation} and 
the @code{IMPORT} line from @code{IMPORT String ONLY} @dots{} to
@code{IMPORT Denotation ONLY} @dots{}

The other possibility is that you are working on the text, and will
therefore perform an @code{explode} on the text before you really start
applying functions. In this case you should replace type @code{seq[char]}
with type @code{string} and remove the @code{explode} and @code{implode}
function calls. You will now have to import the functions which you used on
sequences from the corresponding string structures.


@node Style Guide, Not For User Purpose, Changes, Top
@appendix Designing Structures For Your Own Data Types

When designing structures for your own data types, you should follow the
principles used for structuring the library itself (@pxref{Naming of
Structures}).

First have a look at the library and search for the most similar type
already available. Perhaps you are missing another arithmetic type, or your
new type can be considered as an aggregate type, or you want to give a
different implementation for a data type which already exists.

If you find a similar data type, try to copy the interfaces of the
corresponding structures as far as reasonable. If you give a different
implementation for an existing data type, keep the name of the type.

If you want to define a totally new data type, you should nevertheless try
to use names from existing structures which perform a similar task. If
you somehow "select" elements, call that function @code{!}. The
concatenation is called @code{++}, composition is named @code{o} and no
doubt you will find other functions which resemble functions on the new data
type.

@emph{Always} define a function @code{` : type -> denotation} (appropriately
augmented if the type is parameterized). There are first experimental
tools, which exploit the fact that for every type @code{type} a conversion
function @code{`} exists in @code{TypeConv}.

Try to keep interfaces small. Give a base structure which contains the most
necessary function declarations. Group additional functions into separate
structures. 

And do not forget to send us the product of your efforts if you think it 
fills a gap in @sc{Bibliotheca Opalica}.



@node Not For User Purpose,  , Style Guide, Top
@appendix Efficiency: What "Not For User Purpose" Really Means

There are some functions in @sc{Bibliotheca Opalica} which are marked "not
for user purpose". The functions in these sections provide access to
internal representations; these are needed for the efficient implementation
of other functions on the same date type, when the data type is located in
another structure.

In principle, you may use these functions as you do other functions and
perhaps you gain some additional performance in doing so. You do this at
your own risk, however. We do not guarantee anything about the behaviour of
functions which are marked "not for user purpose"; moreover these functions
are subject to change in later releases of @sc{Bibliotheca Opalica} without
further notice.


@unnumbered Index of Types
@printindex tp

@contents
@bye


