% Title:   The Tycoon System and Library Manual
% Author:  Bernd Mathiske, Florian Matthes, Sven Muessig
% Date:    16-jan-1995
% Updates: 20-jan-1996 FM
%          24-jan-1996 GS
 
\documentstyle[tycoon]{article}

\setcounter{tocdepth}{2}

\newcommand{\r}{$\Rightarrow$}
\newcommand{\bold}[1]{{\bf #1}}
\newcommand{\engl}[1]{{\em #1\/}}

\newcommand{\bslop}{\begin{sloppypar}}
\newcommand{\eslop}{\end{sloppypar}}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\title{The Tycoon System \\
       and Library Manual}

\author{Bernd Mathiske \\
        Florian Matthes \\
        Sven M\"u{\ss}ig}

\titleid{DBIS Tycoon Report 101-96}

\titlestatus{Revised for system version TL (tl0-dyn 2.0)}

\date{January 1996}

\titledescription{This document provides a practical introduction to the 
interactive Tycoon system environment and an overview of its polymorphic 
libraries.  It explains how to bind external C libraries to Tycoon programs 
and how to work with persistent stores.  Moreover, it proposes formatting 
und naming guidelines for Tycoon programs.}

\titlerelated{Definition of the Tycoon Language TL: \\
              A Preliminary Report \cite{MaSc92a} \\
              Persistent Object Systems \cite{Matt93} \\
              Online documentation shipped with the Tycoon system software
              (Unix, MacOS, Windows) \\
              Tycoon WWW home page \cite{Tyco92}}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\begin{document}

\maketitle


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\pagenumbering{Roman}
\setcounter{page}{1}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\tableofcontents
\newpage


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\pagenumbering{arabic}
\setcounter{page}{1}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Introduction}
\label{Sec. Introduction}

Tycoon\footnote{Tycoon: \engl{Typed communicating objects in open 
environments}.} is a polymorphic persistent programming environment for the 
development of data-intensive applications in open environments.  The 
Tycoon system emphasizes system scalability and interoperability with 
commercial servers like Ingres, Oracle, ObjectStore, O2, Inquery, SAP R/3, 
NeWS, StarView, C and C++ libraries, Sun-RPC, DCE-RPC and Kerberos.  
Flexible and safe interoperation between these servers in heterogeneous 
distributed environments is supported by

\begin{itemize} 

\item an elaborate higher-order type system (precise and generic 
service definitions),

\item orthogonal persistence (longevity for objects of arbitrary complexity 
and size), and

\item orthogonal mobility (unrestricted migration of data, code and threads 
between multiple system platforms).

\end{itemize}

Tycoon is a long-term research project at DBIS, Hamburg University that 
started in 1992.  Tycoon is the most recent member of the family of 
database programming languages and multi-user database systems developed by 
our group since 1978 (Pascal/R, Modula-R, DBPL).

The Tycoon programming language TL is described in several publications 
\cite{MMS94,MaSc94,Matt95,MSW95,MMS95a,MMS95b} and in a formal language report
\cite{MaSc92a}.  This text complements these publications and provides guidance
for programmers during their first steps with the Tycoon system and also some
practical programming hints for advanced Tycoon programmers.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\section{The Interactive Tycoon Development Environment}
\label{Sec. The Interactive Tycoon Development Environment}

TL is implemented as an interactive compiler.  This means that the system 
behaves very much like an interpreter.  The user inputs a phrase in order 
to evaluate a term and the system produces a reply.  In between, the term 
is parsed, type-checked, translated into portable Tycoon machine code and 
linked with other TL values or external machine code.

Larger TL programs are typically divided into modules, interfaces and 
libraries that are compiled separately, then linked and executed.  Larger 
fragments of TL source code are usually stored in text files.  However, 
there is no distinction between input read from files or interactively from 
a terminal.  In particular, it is possible to enter modules, interfaces and 
libraries interactively and to read expressions and commands from files.

The level of interaction at which the user enters a phrase and receives an 
answer is called the \e{top level interface} of the system.  The details of 
the top level user interface depend on the host operating system (Unix, 
Windows, MacOS, Linux, \ldots) and are described in the online 
documentation that is shipped with the Tycoon system software. 

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Components of the Tycoon System}

The Tycoon system consists of two parts:
\begin{itemize}

\item The Tycoon store contains program code, persistent data and 
persistent threads (descriptions of programs in the process of being 
executed) in a platform-neutral format;

\item The platform-specific Tycoon application is responsible for 
multi-threaded program execution, persistent store management and for host 
operating system access (MacOS, Windows, Unix, Linux,\ldots). The online 
documentation describes how to invoke the Tycoon application with a given 
Tycoon store.

\end{itemize}

The evaluation of expressions and the linking of programs takes place in a 
persistent store.  Bindings established in one Tycoon session can be made 
accessible for later Tycoon sessions.  Furthermore, the persistent store is 
shared.  Multiple TL application programs can have access to a linked 
module.  Assignments to shared variables defined in such a module are 
visible to all importers of that module.

A Tycoon store contains a set of linked modules and interfaces as well as 
value and type bindings entered at the top level.  Within a persistent 
store there is a single name space for modules, interfaces and libraries.  
However, every user can set up a private name space for top level bindings.  
This name space is called a \e{top level}.

During (interactive) program development, a Tycoon store also contains the 
Tycoon compiler, linker and library manager which are loaded from a 
precompiled boot file whenever a fresh store is created.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Entering Top Level Phrases}

The Tycoon top level interface prompt looks as follows:

\begin{verbatim}
|>
\end{verbatim}

Once at the top level, \e{top level phrases} can be entered, for example
to bind a value to a variable:

\begin{xple}
\k{let} peter = \k{tuple} ''Peter'' 5000 \k{end};
\r tuple ''Peter'' 5000 end :Tuple ? :String ? :Int end
\end{xple}

The system displays the value computed for the last binding and its 
(inferred) type. Note that all input at the top level interface has to be 
terminated by a semicolon.  If the semicolon is omitted, the Tycoon system 
prompts for further input by:

\begin{verbatim}
..
\end{verbatim}

It is also possible to bind types to variables:

\begin{xple} 
\k{Let} Person = \k{Tuple} name :String  salary :Int \k{end}; 
\r :Tuple name :String salary :Int  end
\end{xple}

A function binding is entered as follows:

\begin{xple}
\k{let} rich(p :Person) :Bool = p.salary $>$ 4000;
\r fun(p :Person) :Bool $<$hidden$>$ :Fun(p :Person) :Bool
\end{xple}

Variables introduced in bindings can be used in subsequent bindings:

\begin{xple}
rich(peter);
\r true :Bool
\end{xple}

A top level phrase that starts with the keyword \k{do} is not parsed and
executed as a TL compilation unit but as a top level command. The top
level commands control various aspects of the Tycoon system components.

\begin{xple}
\k{do} help;
\end{xple}

The latter command prints a list with the syntax and the description of all 
available top level commands. 

Sequences of Tycoon top level phrases can be stored in files that by 
convention have the extension \p{.tyc}. Assuming that the file
\p{Test.tyc} contains the phrases above, the command

\begin{xple}
\k{do} ''Test.tyc''; 
\r (Including input from 'Test.tyc')
\end{xple}

reads and immediately executes the phrases.  Nested include files are 
admissible.  Files or pipes of top-level commands are a primitive mechanism 
to access the Tycoon system from other programs.  However, their use in normal 
program development is discouraged.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Understanding Compile-Time Error Messages}

All compile-time error messages start with a source position.  For example:

\begin{xple}
stdenv/string.tm:66.13 Syntax error: expecting 'then', found ''end''
\end{xple}

indicates that a syntax error was found on the symbol \k{end} that starts 
in column 13 of line 66 in the source file \p{stdenv/string.tm} where the 
symbol \k{then} was expected.

Each individual top level input terminated with a semicolon is viewed as an 
anonymous, numbered source file.  For example:

\begin{xple}
a \k{end}
\r \#15:1.3 Syntax error: expecting $<$end-of-input$>$, found ''end''
\end{xple}

indicates a syntax error in colum 3 of line 1 of the top level input 
number 15.

Some effort has been devoted to the generation of informative type error messages:

\begin{xple}
\k{Let} Address = \k{Tuple} street :String \k{end}
\k{Let} Person = \k{Tuple} name :String  age :Int  address :Address \k{end}
\k{let} f(x :Person) = \k{ok}
\k{let} address = \k{tuple} \k{let} street = 3 \k{end}
f(\k{tuple} ''Peter'' 40 address \k{end});
\#25:6.2 Argument type mismatch: '\_builtin.String' expected, '\_builtin.Int' found
\#25:5.25 [while checking tuple field 'street']
\#25:6.20 [while checking tuple field 'address']
\#25:6.3 [while checking function argument 'x']
\end{xple}

In the example above, a type error occurs because the type \p{Int} of
the \p{address.street} attribute of the argument passed to the function
\p{f} does not match the type \p{String} specified for the
\p{address.street} field of the variable \p{x} in the signature of the
function.

The first line of a type error message prints the error context (\p{Argument
type mismatch}) followed by a description of the type expected by the type
checker (\p{\_builtin.\-String} is the type defined for the \p{street} field in
type \p{Address}). The next line prints the offending type found in the program
(\p{\_builtin.\-Int} is the type inferred by the compiler for the number 3).

If a type mismatch occurs inside a composite type expression, further
error messages in square brackets give a \e{traceback} that help to
localize the error. Source position specifications preceding the square
brackets refer to the declaration point of the respective subexpression.
In the example above, the error occurs while checking the field
\p{x.address.street} and the faulty binding \p{\k{let} street = 3} is
found in line 5, column 25.

In a long error listing it is a good idea to look at the non-bracketed
error messages first and to consult the type error traceback only if
needed.

In addition to syntax and type errors, the Tycoon compiler also flags lexical
errors. Beginners sometimes find it difficult to localize these errors. For
example, if a piece of input contains a string constant that is not properly
delimited by a closing \p{"}, the compiler flags a large number of lexical
errors since it assumes that the string extends upto the end of the input and
since it encounters several line breaks which are not allowed inside string
constants: 

\begin{xple}
Lexical error: illegal character in source file
\end{xple}
A similar problem occurs if a closing comment bracket \p{*)} is omitted 
since the compiler will continue to prompt the user at the top level for 
additional input until a closing comment bracket is entered. A standard 
solution to recognize such situations is to enter "3;" several times at the 
top level and to check which output is produced by the compiler.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Understanding Run-Time Error Messages}

By virtue of Tycoon's static type system, many run-time errors of other 
languages like \p{message not understood}, \p{nil dereference error} or 
\p{dynamic type test error} can be avoided.  Other run-time errors like 
\p{division by zero error} or \p{array index out of bounds error} are 
mapped to Tycoon exceptions with typed arguments that can be handled 
selectively with \k{try} expressions.

Unhandled exceptions that propagate to the Tycoon top level are displayed 
by the Tycoon compiler and their arguments are printed in a raw data 
format, for example:

\begin{xple}
   \k{let} a = \k{array} "1" "2" "3" \k{end}
   a[400];
\r *** Exception: \{"indexOutOfBoundsError" 2 2 "\#9" \{"1" "2" "3"\} 400\}
\end{xple}

The signatures of all language-defined exceptions are defined in the file 
\p{boot.tyc}.  Each of these exceptions provides also the detailed source 
code position of the faulty expression as an explicit argument which can be 
inspected with a \k{try} expression, for example:\footnote{The identifier 
\p{fmt} denotes a standard formatting module that can be imported with 
the command \p{import fmt}.}

\begin{xple}
\k{try}
   \k{let} a = \k{array} "1" "2" "3" \k{end}
   a[400]
\k{when} indexOutOfBoundsError \k{with} exc \k{then}
   "cannot access index " $<>$ fmt.int(exc.index) $<>$
   " in line " $<>$ fmt.int(exc.line) $<>$
   " of source file " $<>$ exc.where
\k{end}
\r "cannot access index 400 in line 5..." :String
\end{xple}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Using Modules and Libraries}

Much of Tycoon's functionality (data types like \p{String}, \p{Date} or 
\p{Time}, file input and output, bulk data management, etc.) are 
factored-out into library modules that can be imported into applications as 
needed.  This section describes how to work with modules and interfaces.

\subsubsection{Syntax for Interfaces and Modules}

An interface defines signatures for values and types exported by a module.
Modules that match the following interface (\p{Counter}) export an abstract
type \p{T} and operations on values of this type:

\begin{xple}
\k{interface} Counter
\k{export}
   T $<$:\k{Ok}
   new(init :Int) :T
   dec(counter :T) :\k{Ok}
   isZero(counter :T) :Bool
\k{end};
\end{xple}

A possible implementation of this interface is the following module
\p{counter}:

\begin{xple}
\k{module} counter
\k{import} int
\k{export}
   \k{Let} T = \k{Tuple} \k{var} value :Int \k{end}
   \k{let} new(init :Int) = \k{tuple} \k{let var} value = init \k{end}
   \k{let} dec(counter :T) = counter.value := counter.value -- 1
   \k{let} isZero(counter :T) = counter.value == 0
\k{end};
\end{xple}

In Tycoon, there can be multiple modules implementing the same interface.

\subsubsection{Libraries and Import Relationships}

Modules and interfaces can import other modules and interfaces by listing 
their names in an import clause. The name space for modules and interfaces 
is defined by a root library. A root library lists the names of all
components that make up a persistent object system. There are three kinds
of library component declarations:

\begin{center}
  \begin{tabular}{|l|l|}
    \hline
    \bold{Component}                & \bold{Description} \\
    \hline
    \p{\k{library} stdenv}          & a (nested) library named \p{stdenv} \\
    \p{\k{interface} Counter}       & an interface named \p{Counter} \\
    \p{\k{module} counter :Counter} & a module named \p{counter} implementing \\
                                    & interface \p{Counter} \\
    \hline
  \end{tabular}
\end{center}

Since the module \p{int} imported by \p{counter} is defined in the Tycoon
standard library \p{stdenv}, a root library declaration for the example
above has to include the name of the standard library:

\begin{xple}
\k{library} Root
\k{with}
   \k{library} stdenv
   \k{interface} Counter
   \k{module} counter :Counter
\k{end};
\end{xple}

The declaration order of library components is significant since types 
and values exported from a library component can be imported only into
components that follow its declaration.

For example, the library definition for \p{stdenv} has the following form:

\begin{xple}
\k{library} stdenv
\k{with}
   \k{interface} RuntimeCore
   \k{module} runtimeCore :RuntimeCore
   \ldots
   
   \k{hide} RuntimeCore runtimeCore
\k{end};
\end{xple}

A library exports all its locally declared components excluding those
interfaces and modules listed  explicitly in the \k{hide} clause.

\subsubsection{Compiling a Library}

The first step in developing a modular application is to write and compile
its root library definition. By convention, library definitions are stored
in files with the suffix \p{.tl}. Compiled library definitions are 
consulted by the compiler during the compilation of modules, interfaces and 
other library definitions to validate inter-module scoping constraints and
to locate compiled components. Library definitions have to be compiled 
inside out. For example, the library definition of \p{stdenv} has to 
be compiled before compilation of the library definition \p{Root}.

By default, compiled library definitions, interfaces and modules are stored
as binary files in the file system (and cached in the object store). The 
components of separate libraries are stored in separate directories. The 
name of the directory is derived from the name of its enclosing 
library.

The command \p{\k{do} makeLibraries} automatically reads and (re-)compiles 
library de\-fi\-ni\-tions reachable from the current root library. It
inspects the file modification date of library source files to determine 
which library definitions require recompilation. The name of the
current root library can be changed with the command \p{\k{do} 
setRootLibrary L} or by the command \p{\k{do} makeLibraries L}.

\subsubsection{Compiling Interfaces and Modules}

Interface and module definitions are stored in files with the suffix
\p{.ti} and \p{.tm}, re\-spec\-ti\-ve\-ly. Imported interfaces and the
interfaces of imported modules have to be compiled before the importing
module or interface can be compiled. In the example above, the interface
\p{IntOp} for the module \p{int} has to be compiled before the module
\p{counter} can be compiled.

The command \p{\k{do} makeComponent x} automatically reads and
(re-)compiles the com\-po\-nent \p{x} and all its transitively imported
interfaces that are out of date. The command \p{\k{do} make x}
automatically reads and (re-)compiles the component \p{x} and all its
transitively imported interfaces and modules that are out of date.
There are other \k{do} commands to control separate compilation and
module linkage, use the command \p{\k{do} help} to find out more about these
commands. 

The compiler assigns time stamps to compiled interfaces to validate that 
all components of a system have been compiled with a consistent set of
interfaces. Version conflicts are reported by printing the conflicting
time stamps valid at compilation and import-time. For example, if the 
interface \p{Counter} has been recompiled without recompiling the 
dependent module \p{counter}, the following error message is printed:

\begin{xple}
17.18 'counter' was compiled with version 8535d 22h 46m 23.361s 
        of interface 'Counter'
17.18 [Current version of 'Counter' is 8536d 2h 50m 9.15s]
\end{xple}

The command \p{\k{do} link x} reads the compiled modules that are
imported transitively by x into the object store (if they are not
cached) and then executes their module bodies. If a module \p{y}
is imported by another module \p{x} then the module body of \p{y} is
executed before the module body of \p{x}. Linking aborts as soon as the
execution of a module body raises an unhandled exception. The module bodies
of modules that are already linked are not re-executed. This makes it
possible to share (persistent) variables between multiple applications.

The command \p{\k{do} unlink x} marks the module \p{x} as unlinked. A 
subsequent import operations on \p{x} (or on another module \p{y} importing 
\p{x}) returns a fresh instance of \p{x} by re-executing its module code. 
Unlinking is performed automatically as soon as a module is recompiled.

\subsubsection{Using Modules and Interfaces at the Top Level}

The \p{\k{do} link} command is sufficient for main programs that do not
export any bindings. To get access to exported bindings and signatures
it is also possible to import module and interface identifiers into the
top level:

\begin{xple}
\k{import} counter;
\r (':Counter' defined)
    ('counter' defined)
\end{xple}

This command links the module \p{counter} and imports its identifier 
\p{counter} into the top level. Notice that also the name of its interface 
\p{Counter} is made accessible. More precisely, the import of a module
forces the import of all modules and interfaces transitively imported by 
its interface. This import is necessary to type-check further access
to the module value via top-level commands. 

The import of an interface \p{X} with export signatures \p{S} is equivalent
to the declaration \p{\k{Let} X = \k{Tuple} S \k{end}}. The import of a
module \p{x} with interface \p{X} defines a value binding with signature
\p{x :X}. Therefore, access to exported module components requires 
qualification by the module identifier:

\begin{xple}
\k{let} c = counter.new(2);
counter.dec(c);
counter.dec(c);
counter.isZero(c);
\r true :Bool
\end{xple}

A \p{open} expression can be used to access module components without
qualification.

\begin{xple}
\k{import} counter;
\k{open} counter;
\k{let} c = new(2)  dec(c)  dec(c)  isZero(c);
\r true :Bool
\end{xple}

The disadvantage of \p{open} is that the top level will be \e{polluted} 
with names that may hide other bindings.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsubsection{Organizing Source and Object Files}

In order to support the exchange of compiled library definitions, interfaces 
and (unlinked) module code between autonomous object stores, all 
information derived during compilation of a library component is also 
stored outside the persistent object store in operating system files.  The 
following naming conventions are imposed by the compiler.  The base 
directories \p{librarySourceDir}, and \p{libraryObjectDir} can be defined 
via \p{\k{do} set} commands.

\begin{tabular}{|l|l|l|}
  \hline
  \bold{Directory}            & \bold{Files} & \bold{Contents} \\
  \hline
  \p{librarySourceDir}/\p{L}/ & \p{L}.tl   & source code for library definition \p{L} \\
                              & \p{X}.ti   & source code for interface \p{X} in library \p{L} \\
                              & \p{x}.tm   & source code for module \p{x} in library \p{L} \\
  \p{libraryObjectDir}/\p{L}/ & \p{L}.tl.x & compiled library definition for library \p{L} \\
                              & \p{X}.ti.x & compiled interface \p{X} in library \p{L} \\
                              & \p{x}.tm.x & compiled module \p{x} in library \p{L} (portable) \\
  \hline
\end{tabular}

By convention scripts of Tycoon commands and TL code fragments that can be interpreted by the Tycoon compiler toplevel (e.g. for cut \& paste in a demo) use the extension \p{tyc}, e.g. \p{demo.tyc}.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Layout and Naming Conventions}
\label{Sec. Layout and Naming Conventions}

Common formatting conventions are worth a lot, especially when several
people work together on large projects. In addition to the communication
inefficiencies caused by differing conventions, newcomers to a programming
language often spend a significant amount of time incrementally developing
and retrofitting their own style, usually re-learning what turn out to be
simple lessons that others have already learned. While this is not always
wasteful, it is clearly worthwhile to have a good set of guidelines at
hand, if only for reference. Also adherence to common conventions makes
automatic formatting tools easier to provide and more useful \cite{RLW85}.

This section offers a complete set of conventions for formatting
TL modules and interfaces. Such conventions address indentation,
capitalization, punctuation, comments, etc. The following points of style
produce a visually pleasing program. Consistently applied, they also
provide syntactic cues to semantics that make a program easier to read.

Furthermore, a subsection presents naming conventions for TL programs.
To simplify the usage of the TL libraries it is necessary to standardize
the names of value, type, function and exception identifiers.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Spelling}
\label{Sec. Spelling}

Identifiers that name \e{values} (e.g.\ variables, functions, modules and
exceptions) start with a lower-case character and identifiers that name
\e{types} (e.g.\ type operators and interfaces) start with an upper-case
character. All following characters are entirely lower case, except for 
composed identifiers. Each first character of a subcomponent is 
capitalized (e.g.\ \p{longNameForAValue}).

Reserved keywords that are used in \e{value contexts} are entirely
lower-case and keywords that are used in \e{type contexts} start with an
upper-case character.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Punctuation}
\label{Sec. Punctuation}

A space (\verb*| |) appears before and after a binary operator in infix 
notation and in a \k{let}-binding or destructive assignment.

\begin{xple}
3\verb*| |+\verb*| |4  ''con''\verb*| |$<>$\verb*| |''cat''
\k{let} a\verb*| |=\verb*| |3
a\verb*| |:=\verb*| |5
\end{xple}

A space appears before but not after a colon or a subtype sign.

\begin{xple}
\k{let} p\verb*| |:Person = \dots
\k{let} n\verb*| |$<$:\k{Ok} = \dots
\end{xple}

A space appears after but not before a comma or a semicolon.

\begin{xple}
add(x,\verb*| |y :Int) = \dots 
\k{module} \dots \k{end};
\end{xple}

A space appears neither before nor after a point, a question-mark or
an exclamation-mark.

\begin{xple}
person.name
address?national
address!national
\end{xple}

Except as required by adjacent tokens, no spaces appear before or after
left and right parenthesis, left and right sqare brackets and left and
right curly brackets.

\begin{xple}
fac(3)  get(peter).name
a[3]  p[3].name
\{3 + 4\}
\end{xple}

Two spaces appears between two signatures, e.g.\ in function or tuple
signatues. Two spaces also appears between \k{let}-bindings function
applications or tuple components.

\begin{xple}
get(E $<$:\k{Ok}\verb*|  |coll :T(E)\verb*|  |index :Int) :E
\k{Tuple} name :String\verb*|  |age :Int \k{end}
f(\k{let} x = 2\verb*|  |\k{let} y = 7)
\k{tuple} \k{let} a = 6\verb*|  |\k{let} b = ''hallo'' \k{end}
\end{xple}

A single space appears between actual parameters in function
applications and between tuple components (anonymous bindings).

\begin{xple}
get(:Person\verb*| |persons\verb*| |7)
\k{tuple} ''Peter''\verb*| |29 \k{end}
\k{array} 1\verb*| |2\verb*| |3 \k{end}
\end{xple}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Indentation}
\label{Sec. Indentation}

Indenting is used to emphasize program structure. Each nesting level is two
spaces wide. A statement sequence is indented under the construct that
introduces it. Section \ref{Sec. Indentation Examples} gives indentation
examples for all TL syntatic forms.

These forms only apply to contructs that do not fit on a single line.
For example, if the statement sequence following a \k{then} or \k{else} 
fits on a single line, it can appear on the same line with the tokens that
introduce and terminate it. Similary, if the statement sequence of a loop
body is short, it can be moved up to the line that introduces the loop,
along with the trailing \k{end}.

\begin{xple}
\k{if} z $>$ 10 \k{then} x := z  y := z \k{end}
\k{for} i = 1 \k{upto} 10 \k{do} a[i] := 0 \k{end}
\end{xple}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Comments}
\label{Sec. Comments}

The text of a multiline comment begins on the same line as the opening
left-comment. Subsequent lines are indented the same as the first word
of the comment. The terminating right-comment appears on the last line of
the comment.

\begin{xple}
(* A comment that fits entirely on one line by itself. *)

(* A long comment that does not fit on one line. A long
    comment that does not fit on one line. A long comment
    that does not fit on one line. *)
\end{xple}

By convention, comments which refer to a group of items appear before the
group. Comments associated with a single definition or declaration appear
immediately after it. This comments starts at the same indentation level
as the definition or declaration begins.

\begin{xple}
\dots
(* Exceptions:
    This is a comment for a group of items. *)

error, overflow :\k{Exception} data :Int \k{end}
(* Standard exceptions. *)
   
test :\k{Exception end}    (* Only for debugging. *)
\dots
\end{xple}

Interfaces and modules have a multiline comment with predefined fields.
This comment is placed immediately after the interface respectively the
module name. It is used to give some initial information about the contents.
The terminating right-comment stands on a separate line.

\begin{xple}
\k{interface} Editor
(* System:  editenv
   File:       Editor.ti
   Author:   Florian Matthes, Sven Muessig
   Date:      02-dec-91
   Purpose:  Generic data editor and browser.
*)
\k{import}
   \dots
\k{export}
   \dots
\k{end};
\end{xple}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Naming}
\label{Sec. Naming}

This section gives guidelines how to name variables, types, functions and
exceptions.

\begin{description}
  \item [variables:]
        Locally used variables are named like the first character of its
        type, like \p{i} for an integer or \p{s} for a string variable. The
        iteration-variable in \k{for}-loops is named \p{i}. 
        
  \item [types:]
        The exported type of a library module is named \p{T}, for example
        \p{int.T}.

  \item [functions:]
        A large number of functions has a \e{historically} grown meaning (See
        also the files of \p{stdenv}). These
        functions are presented in the following table.

  \begin{center}
  \begin{tabular}{ll}
    \hline
    \bold{Function} & \bold{Description} \\
    \hline
    \p{copy}          & create a shallow copy \\
    \p{create}        & create a collection by an enumeration of its components \\
    \p{default}       & default value \\
    \p{elements}      & iteration over elements of a collection \\
    \p{empty}         & test for emptiness \\
    \p{equal}, \p{==} & test the equality of two values \\
    \p{fmt}           & conversion to string \\
    \p{free}          & deallocation of volatile resources \\
    \p{get}           & access by index \\
    \p{hash}          & hash function \\
    \p{new}           & create a new object possibly with local state \\
    \p{nil}           & empty element \\
    \p{notEqual}, \p{!=} & negation of \p{equal}, \p{==} \\
    \p{order}         & defines a linear order \\
    \p{set}           & destructive update by index \\
    \p{setSub}        & subcollection update by index range \\
    \p{size}          & size of a collection \\
    \p{sub}           & subcollection selection by index range \\
    \hline
  \end{tabular}
  \end{center}

  \item [exceptions:]
        If a module provides exception handling, the major exception is
        named \p{error}, for example \p{int.error}.
\end{description}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Indentation Examples}
\label{Sec. Indentation Examples}

The following sections illustrate the recommended form of the TL 
constructs.  A statement sequence (\p{ss} in the following examples) is 
indented under the construct that introduces it, which lines up vertically 
with its corresponding \k{end}.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\begin{maxipage}
\begin{minipage}[t]{8cm}
\begin{xple}
\k{let} a = 4
\k{let} a = 123 / 3  \k{and} \k{var} b = a + 2

\k{let} t = \k{tuple} ''Peter'' 3 \k{end}
    
\k{let} t = 
   \k{tuple}
      \k{let} name = ''Peter''
      \k{let} age = 3
   \k{end}

\k{let} address =
   \k{tuple\_case} national \k{of} Address \k{with}
      \k{let} street = ''Johnsallee 21''
      \k{let} city = ''Hamburg''
      \k{let} zip = 21234
   \k{end}



   
\k{let} paul :Student =
   \k{tuple}
      \k{open} peter
      \k{let} semester = 6
   \k{end}
\end{xple}
\end{minipage} 
\begin{minipage}[t]{8cm}
\begin{xple}
\k{Let} T = Int
\k{Let} T = String \k{and} U = T

\k{Let} Person = \k{Tuple} :String :Int \k{end}
    
\k{Let} Person = 
   \k{Tuple}
      name :String
      age :Int
   \k{end}

\k{Let} Address =
   \k{Tuple}
      street, city :String
      \k{case} national \k{with}
         zip :Int
      \k{case} international \k{with}
         state :String
         zip :String
   \k{end}

\k{Let} Student =
   \k{Tuple}
      \k{Repeat} Person
      semester :Int
   \k{end}
\end{xple}
\end{minipage}
\end{maxipage}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\begin{maxipage}
\begin{minipage}[t]{8cm}
\begin{xple}
\k{let} \k{rec} fac(n :Int) :Int =
   \k{if} n == 0 \k{then} 1 \k{else} n * fac(n -- 1) \k{end}

\k{let} swap(A $<$:\k{Ok}  \k{var} x, y :A) :\k{Ok} =
   \k{begin}
      \k{let} temp = x
      x := y
      y := temp
   \k{end}
\end{xple}
\end{minipage} 
\begin{minipage}[t]{8cm}
\begin{xple}
\k{Let} Fac = \k{Fun}(n :Int) :Int 

newSubWindow(client :Canvas.T
             label :DisplayItem
             dismiss, unpin :Action.T
             super :Window.T) :Popup.T
\end{xple}
\end{minipage}
\end{maxipage}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\begin{maxipage}
\begin{minipage}[t]{4cm}
\begin{xple}
setisum(x + y
        z
        a)
\end{xple}
\end{minipage} 
\begin{minipage}[t]{4cm}
\begin{xple}
iter.enum \k{of}
             1
             2
             3
          \k{end}
\end{xple}
\end{minipage}
\end{maxipage}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\begin{maxipage}
\begin{minipage}[t]{4cm}
\begin{xple}
\k{begin}
   ss
\k{end}

\k{loop}
   ss
\k{end}
\end{xple}
\end{minipage}
\begin{minipage}[t]{4cm}
\begin{xple}
\k{if} bool \k{then}
   ss
\k{elsif} bool \k{then}
   ss
\k{else}
   ss
\k{end}
\end{xple}
\end{minipage}
\begin{minipage}[t]{6cm}
\begin{xple}
\k{case} address
\k{when} national \k{with} n \k{then}
   fmt.int(n.zip)
\k{else}
   ''not national''
\k{end}
\end{xple}
\end{minipage}

\vspace{1cm}

\begin{minipage}[t]{4cm}
\begin{xple}
\k{while} bool \k{do}
   ss
\k{end}

\k{for} i = x \k{upto} y \k{do}
   ss
\k{end}
\end{xple}
\end{minipage}
\begin{minipage}[t]{4cm}
\begin{xple}
\k{if} bool
\k{andif} bool
\k{orif} bool \k{then}
   ss
\k{else}
   ss
\k{end}
\end{xple}
\end{minipage}

\vspace{1cm}

\begin{minipage}[t]{8cm}
\begin{xple}
\k{let} noCredit =
   \k{exception} ''No Credit'' \k{with} od :Int \k{end}
\end{xple}
\end{minipage}
\begin{minipage}[t]{7cm}
\begin{xple}
\k{try}
   withdraw(petersAccount  300)
   print.string(''Transfer succeded'')
\k{when} noCredit \k{with} exc \k{then}
   print.string(''Overdrawn'')
\k{else}
   print.string(''Unexpected exception'')
\k{end}
\end{xple}
\end{minipage}
\end{maxipage}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\begin{maxipage}
\begin{minipage}[t]{5cm}
\begin{xple}
\k{interface} name
\k{import}
   importList
\k{export}
   ss
\k{end}
\end{xple}
\end{minipage}
\begin{minipage}[t]{5cm}
\begin{xple}
\k{module} name
\k{import}
   importList
\k{export}
   ss
\k{end}
\end{xple}
\end{minipage}
\begin{minipage}[t]{5cm}
\begin{xple}
\k{library} name
\k{import}
   importList
\k{with}
   \k{library}
      list
   \k{interface} 
      list
   \k{module}
      list
   \k{hide}
      list
\k{end}
\end{xple}
\end{minipage}
\end{maxipage}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Overview of the Tycoon Libraries}

A significant part of the Tycoon system functionality is defined in an open 
set of libraries.  Currently, the following libraries are available:

\begin{center}
\begin{tabular}{lll}
  \hline
  \bold{Library} & \bold{Description}                &  \\
  \hline
  \p{stdenv}     & basic data types and operations   & \\
  \p{machineenv} & low level, os specific functions  & \\
  \p{bulkenv}    & bulk data types                   & \\
  \p{compenv}    & compiler toolkit (scanner and parser generator) & \\
  \p{egrammar}   & extensible grammar package        & \\
  \p{tl_reflective} & reflective compiler interface, dynamic types & \\
  \p{dbenv}      & transaction and integrity support & \\
  \p{sqlenv}     & interface to SQL databases Oracle and Ingres & \\
  \p{commenv}    & communication support (RPC)       & \\
  \p{csenv}      & client-server progamming toolkit  & \\
  \p{wwwenv}     & toolkit for World Wide Web programming & \\
  \p{newsenv}    & interface to The NeWS Toolkit (TNT) \\
  \p{editenv}    & generic data visualization using NeWS & \\
  \p{svenv}      & interface to StarView & \\
  \p{sveditenv}  & generic data visualization using StarView & \\
  \p{authorizationenv} & authorization manager & \\
  \p{authenticationenv} & authentication using Kerberos and PGP & \\
  \p{mailenv}    & access to mail services including PGP & \\
  \hline
\end{tabular}
\end{center}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Resolving Cyclic Import Relationships}

The current Tycoon library concept does not allow libraries with cyclic import
relationships. The main problem with cyclic imports is that the compiler should
ensure that the module initialization code of a module \p{M} only accesses
modules \p{M$_i$} that are already properly initialized. This check is analogous
to the checks performed by the TL compiler on recursive value bindings.

In the following, a systematic approach to circumvent this limitation is
described. 

Suppose the following recursive module system is to be implemented (note that the phrase \k{rec module} is not allowed in TL):
\begin{xple}
\k{library} Test
  \k{interface} A B
  \k{rec module} a :A   b :B
\k{end}

\k{module} a \k{import} b \k{export let} f(): Int = b.g() \k{end}
\k{module} b \k{import} a \k{export let} g(): Int = a.f() \k{end}
\end{xple}

First, it is necessary to determine a correct initialization sequence. For
example, if \p{a} has to be initialized prior to \p{b}, one has to write:
\begin{xple}
\k{library} Test
  \k{interface} A' B
  \k{module} a :A'
  \k{module} b :B
\k{end}
\end{xple}
where \p{A'} is defined as follows:
\begin{xple}
\k{interface} A'
\k{export}
  (* All signatures of interface B needed in module a prefixed with "var": *)
  pre :\k{Tuple}
    \k{var} g() :Int
  \k{end}

  (* All remaining declarations of A without changes: *)
  f() :Int
end

\k{module} a (* import of b no longer required here! *)
\k{export}
  \k{let} pre = 
  \k{tuple}
    \k{let var} g() :Int = \k{raise} "module b not yet initialized"
  \k{end}

  \k{let} f() = pre.g()
\k{end}

\k{module} b \k{import} a 
\k{export} 
  (* All bindings of module b without changes: *)
  \k{let} g(): Int = a.f() 

  (* Fixup of forward-references in all other modules: *)
  a.pre.g:= g
\k{end}
\end{xple}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Using Dynamic Types}

This section describes how to use dynamic types in the current TL language
implementation. It also gives some background information on the rationale
behind these TL language mechanisms.

\subsection{Motivation}

Programmers of data-intensive and long-lived applications are faced with
situations that cannot be handled with static type checking alone:

\begin{enumerate}

\item The inspection of type information at run-time is needed, for example,
to write a schema browser or to dynamically generate a type-specific
user-interface for a complex run-time data value.

\item The manipulation of values with a dynamic type that cannot be
determined statically at compile-time is necessary whenever values generated
outside the static scope of the type checker have to be manipulated by strongly
typed code. For example, the type of a data value retrieved from disk or
received via a communication channel from a different network node has to be
checked at run-time against the type information utilized at compile-time.

\end{enumerate}
     
It is important to note that most language proposals for dynamic typing only
address issue (2) but not issue (1). In such languages it is not possible to
inspect a type without having a run-time instance of that type available.

\subsection{The Initial Proposal for Dynamic Typing}

The original TL language report [MaSc92] defines the following language
constructs to address the issues raised in the previous section:

\begin{itemize}

\item The signature of a type variable \p{T} can be prefixed by the keyword
\k{Dyn}. Such a type variable can be inspected (like a value variable) at run-time to obtain information about the actual type bound to \p{T}.

\item Type variables can be inspected using a \k{typecase} expression. In the
branches of a \k{typecase} expression, the type variable is narrowed to a
statically-known type. Therefore, it becomes possible to statically type-check
the access to values of that dynamic type.

\end{itemize}

For example, the following polymorphic function \p{f} receives a dynamic type
representation \p{T} and a value \p{x} of that type as its argument. The result
type of the function is statically known to be identical to the type of the
argument. Furthermore, in each of the typecase branches, the type \p{T} is
known to be a subtype of the type in its when clause.

\begin{xple}
\k{let} f(\k{Dyn} T $<$:\k{Ok}  x :T) :T =
  \k{typecase} T
  \k{when} Int \k{then} x + 1
  \k{when} String \k{then} x $<>$ "Test"
  \k{else} "unknown type"
  \k{end}
\end{xple}

The first TL compiler already implemented the type rules necessary to type
check \k{typecase} expressions and to verify the matching of signatures and
bindings including \k{Dyn} keywords. However, the run-time support for these
language constructs required a bootstrap of the TL compiler to re-use the
subtype test algorithm of the compiler also for the run-time subtype tests.

During the implementation of this run-time support code the following
limitations of the original approach became clear:

\begin{itemize}
\item The facilities of the typecase expression are not sufficient for highly
     generic type-directed (reflective) programming techniques where it is
     necessary to dynamically explore the structure of a type representation
     using algorithmically-complete code. The typecase expression is
     essentially limited to programming situations where a dynamic type is
     verified to be a subtype of a fixed static type.

\item Due to the higher-order nature of Tycoon, it is desirable to be able to
     inspect types (Int, Person, PersonList), type operators (Array, List, Bag)
     and higher-order type operators (e.g., mapping type operators to other
     type operators) in a uniform way. However, TL does not provide a kind
     specification to quantify over the universe of types and higher-order type
     operators. For example, in TL one has to write different functions to
     inspect types (subtypes of the top type \k{Ok}), unary type operators
     (subtypes of the type \p{\k{Oper}(X $<$:\k{Nok}) \k{Ok}}), and binary type
     operators (subtypes of the type \p{\k{Oper}(X $<$:\k{Nok} Y $<$:\k{Nok})
     \k{Ok}}):
\begin{xple}
     \k{let} inspectType(\k{Dyn} T $<$:\k{Ok}) = \dots
     \k{let} inspectTypeOper1(\k{Dyn} T $<$:\k{Oper}(X $<$:\k{Nok}) \k{Ok}) = \dots
     \k{let} inspectTypeOper2(\k{Dyn} T $<$:\k{Oper}(X $<$:\k{Nok} Y $<$:\k{Nok}) \k{Ok}) = \dots
\end{xple}
     Instead of this one would like to write a single generic piece of code
     with an appropriate signature, e.g.
\begin{xple}
     \k{let} inspectAnyType(\k{Dyn} T $<$:???) = \dots
\end{xple}

\item The code generation for dynamic type variables (passed as parameters,
     bound to local variables or embedded as components of aggregates)
     introduces quite some hidden complexity into the TL language
     processors.
\end{itemize}
     
Following the minimalistic add-on approach of Tycoon, we therefore decided
to make the management of type representations at run-time much more
explicit and factor it out into ordinary TL libraries.

\subsection{The New Approach to Dynamic Typing}

Support for the inspection of type information at run-time (task 1 described
above) is provided by the module \p{typeRep} defined in the Tycoon standard
library \p{tl\_reflective}. It exports the following (semi-abstract) types and
functions

\begin{itemize}
\item The type \p{T} is the type of a run-time type representation for an
     arbitrary Tycoon type or (higher-order) type operator. A type
     representation is a first-class-value representing a static type.
     Contrary to static types, type representations do not need an
     environment in which they are valid.

     \item The type \p{Expansion} gives a more detailed description of a type
     representation.

     \item The function \p{inspect(type :T) :Expansion} returns more detailed
     information on a type that is represented by a type representation. It
     returns a one-level unfolding of a type representation.

     \item A number of type representations is provided that match the standard
     TL types defined in the initial environment (\p{Int, String, \ldots}).

     \item A number of constructor functions support the dynamic creation of
     type representation for structured types (arrays, ...).
\end{itemize}

The function to construct a type representation for a given static type cannot
be exported by the add-on module \p{typeRep} since its implementation requires
special compiler support to access static type descriptions.  Therefore, this
function is not named \p{typeRep.new}, but \k{typeRep\_new} and it is available
without explicit import at the top level and in every module.

As explained in the previous section, the signature of this function cannot
be expressed completely in the TL type system:
\begin{xple}
typeRep\_new(T $<$:???) :typeRep.T
\end{xple}

Here are some examples how to create values of type \p{typeRep.T}.

\begin{xple}
typeRep\_new(:Int)                      (* builtin type *)
typeRep\_new(:\k{Tuple} :String :Real \k{end})  (* structured type *)
typeRep\_new(:\k{Fun}(:String) :Int)        (* function type *)
typeRep\_new(:Array(Int))               (* type operator application *)
typeRep\_new(:list.T)                   (* type operator *)
typeRep\_new(\k{Oper}($<$:\k{Oper}() \k{Ok}) \k{Ok})       (* higher-order type operator *)
\end{xple}

Support for the manipulation of values with a dynamic type (task 2 described
above) is provided by the module \p{dynamic}, also located in the library
\p{tl\_reflective}. This module exports types and functions on dynamic values,
such as:

\begin{itemize}

\item The type \p{T} is the type of dynamic values in TL. A dynamic value is a
pair consisting of a value \p{x} of type \p{T} and a type representation
\p{t\_RT} for \p{T}. The module \p{dynamic} ensures that each access to
\p{x} respects the type \p{T}.

\item The type \p{Expansion} gives a more detailed description of a dynamic
value. 

\item The function \p{inspect(value :T) :Expansion} performs a one-level
unfolding of a structured value. This function is particularly useful in cases
where the programmer does not have any knowledge of the static type of a
dynamic value.

\item The function \p{typeOf(value :T) :typeRep.T} returns the type
representation component of a dynamic value.

\item A number of constructor functions is provided that return structured
dynamic values. 
\end{itemize}

In addition to these library functions there are two predefined functions
that require compile-time support by the TL language processors. These
functions are available without explicit import at the top level and in
every module:

\begin{itemize}

\item The constructor \p{dynamic\_new(T $<$:\k{Ok}  d :T) :dynamic.T} takes a value
\p{d} of a closed type \p{T} and returns a new dynamic value consisting of a type representation for \p{T} and the value \p{d}.

Here are some examples how to create dynamic values:

\begin{xple}
dynamic\_new(3)                      (* integer value *)
dynamic\_new(\k{tuple} 3 4 \k{end})          (* structured value *)
dynamic\_new(\k{fun}(x :Int) :Int x + 1) (* function value *)
dynamic\_new(\k{array} 1 2 3 \k{end})        (* built-in parameterized type *)
dynamic\_new(list.new(:Int))         (* user-defined parameterized type *)
\end{xple}

\item The function \p{dynamic\_be(d :dynamic.T  T $<$:\k{Ok}) :T} takes a
dynamic value \p{d} and a type variable \p{T} which has to be a closed type and
returns \p{d}'s value component. A run-time exception (\p{dynamic.error}) is
raised if the value component's static type is not a subtype of \p{T}. This
function provides the core functionality of the \k{typecase} construct of the
original TL language design.
\end{itemize}

Here are some examples how to extract the value component of a dynamic value:

\begin{xple}
     \k{let} i = dynamic\_new(3)
     \k{let} a = dynamic\_new(\k{array} 1 2 3 \k{end})
     \k{let} t = dynamic\_new(\k{tuple} 1 2 3 \k{end})
     dynamic\_be(i :Int)                (* \r 3 *)
     dynamic\_be(a :Array(Int))         (* \r array 1 2 3 end *)
     dynamic\_be(t :Tuple :Int end)     (* \r tuple 1 end *)
     \k{try}
       dynamic\_be(i :String)           (* \r raises dynamic.error *)
     \k{when} dynamic.error \k{then}
       "error occured"
     \k{end}
\end{xple}


\subsection{Current Restrictions}

\comment{To change}

\k{Naming issues:}
     Due to historic reasons, the identifiers and keywords supported by the
     current TL compiler still differ from the names used in the previous
     section:
\begin{itemize}     
\item The module \p{dynamic} is currently called \p{dynamics}.
\item The type identifier \p{typeRep\_T} is currently called \p{DynType}.
\item The type identifier\p{ dynamic\_T} is currently called \p{DynValue}.
\item The value identifier \p{dynamic.error} is also available through the
          name \p{typecaseError} in the initial environment.
\end{itemize}	  
     However, the next public release of the system will use the names
     described in this text.

\k{Type unification variables:} 
     The type of a dynamic value may not contain type unification variables
     introduced by the TL type checker during type argument synthesis. For
     example, it is not possible to package the polymorphic empty list
     directly into a dynamic value:
\begin{xple}
     \p{dynamic\_new}(list.new())             (* \r compile-time error *)
\end{xple}
     Instead of this, one has to explicitly instantiate the type parameter
     of the list.new function:

\begin{xple}
     dynamic\_new(list.new(:Int))          or
     dynamic\_new(list.new(:String))
\end{xple}
     However, explicit polymorphic functions (like the polymorphic identity
     function) can be turned freely into dynamic values.
\begin{xple}
     dynamic\_new(\k{fun}(A $<$:\k{Ok}  a :A) a)
\end{xple}

\k{Universally quantified type variables}:
     The type of a dynamic value may not contain (free) universally quantified
     type variable, for example,
\begin{xple}
     \k{let} f(T $<$:\k{Ok}  x :T) :dynamic.T = dynamic\_new(x)
\end{xple}

     is rejected at compile-time since the type of \p{x} depends on the free,
     universally quantified type variable \p{T}. Alternatively, the compiler
     could construct a dynamic value with a type representation describing
     the statically-known bound type \k{Ok} of \p{T}, but we prefer to warn the
     programmer that this function does not exhibit the desired run-time
     behavior.

     To obtain the desired behaviour, the keyword \k{Dyn} has to be added in
     front of the type variable \p{T} to ensure that at run-time a
     representation of the actual type of the value bound to \p{x} is available:
\begin{xple}
     \k{let} f(\k{Dyn} T $<$:\k{Ok}  x :T) :dynamic.T = dynamic\_new(x)
\end{xple}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Programming with External C Libraries}
\label{Sec. External C Libraries}

Tycoon provides a bidirectional programming interface between TL and C that
features a seamless integration of both languages' function paradigms.
External C functions can be integrated into TL as ordinary function values. TL
functions can be wrapped in a way that makes it possible to use them as C
function pointers.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Function Calls from Tycoon to External C Libraries}
\label{Sec. Function Calls from Tycoon to External C Libraries}

Tycoon provides a generic mechanism to use system functionality implemented in 
external languages. The binding of TL identifiers to external function
values is achieved by the predefined function \p{bind}. This function has
the following signature:

\begin{xple}
bind(Function $<$:\k{Ok}  library, label, format :String) :Function
\end{xple}

The parameters of the \p{bind} function have the following meaning:
\p{Function} describes the type of the resulting TL function. It has to
be of the form \p{\k{Fun}(\dots) :A}. The \p{library} parameter is a string
that identifies the library file that contains the required external C
function. This can either be the full path name\footnote{If the same shared
library is referenced several times the path should always be exactly the
same. Otherwise the dynamic linker loads several instances of the shared
object. This means not only consuming more process memory than necessary,
but leads to subtle bugs when global C variables are defined multiple times
in the same process.} of a dynamic library or the string result of one of
the functions exported by the module \p{runtimeCore} (see the following 
table) belonging to the Tycoon library \p{stdenv}. 

\begin{center}
  \begin{tabular}{|l|l|}
    \hline
    \bold{Function} & \bold{Description} \\
    \hline
    \p{library}         & identifies the core of the Tycoon run-time system \\
    \p{cLibrary}        & identifies the standard C library \\
    \p{dynamicLibrary}  & identifies dynamically bound libraries \\
    \p{staticLibrary}   & identifies statically bound libraries \\
    \hline
  \end{tabular}
\end{center}

The \p{label} parameter is a string that contains the original C source
text name of the C function. The \p{format} parameter is a string that
specifies the assumed parameter format of the C function. Every single 
character of this string corresponds to one parameter. It specifies the
conversions between tagged and untagged data representations to happen
before and after a call. The parameter order is \e{from left to right} like
in C, except for the function result type. It is given by the last
character that is mandatory. The following table contains the set of
characters that denote parameter formats.

\begin{center}
  \begin{tabular}{|l|l|l|l|}
    \hline
    \bold{Format} & \bold{TL type} & \bold{C type} & \bold{Description} \\
    \hline
    \p{i}  & \p{Int}        & \k{long}      & integer number \\
    \p{r}  & \p{Real}       & \k{double}    & floating point number \\
    \p{c}  & \p{Char}       & \k{char}      & ASCII character \\
    \p{b}  & \p{Bool}       & \k{long}      & boolean value (see text) \\
    \p{v}  & \k{Ok}         & \k{void}      & return value only \\
    \p{=}  & \p{$<$:}\k{Ok} & \k{void} *    & Tycoon value, no conversion \\
    \p{\&} & \p{address.T}  & \k{void} *    & memory address (see text) \\
    \p{s}  & \p{String}     & \k{char} *    & zero-terminated string \\
    \p{w}  & \p{word.T}     & \k{void} *    & 32-bit word \\
    \hline
  \end{tabular}
\end{center}

There is no predefined type for boolean values in C. Boolean TL values are
converted to C long values as follows.

\begin{xple}
true   $\rightarrow$   1
false   $\rightarrow$   0
\end{xple}

A C value x produces the following TL boolean values:

\begin{xple}
x != 0   $\rightarrow$   true
x == 0   $\rightarrow$   false
\end{xple}

\comment{Check:}

When \p{s} is used as a format character for a parameter, it acts exactly
like \p{\&}, because all Tycoon strings are represented with zero-termination.
Specifying \p{s} instead of \p{\&} means just to provide a little
documentation. In case of return values this is different. Stings returned
from C are copied into newly created store objects (\e{copy-out}).

For Tycoon store objects (strings, tuples, arrays, etc.) that are passed to C
by using the format character \p{\&}, every call is enclosed
by automatic fix and unfix operations for the argument. The result of the fix
operation is passed to C.

Suppose a library \p{/usr/lib/libexample.so} contains a function 
\p{example} that takes a string argument and returns a 32 bit integer
number. Thus, \p{example} can be assumed to match the following 
declaration:

\begin{xple}
\k{extern} \k{long} example(\k{char} *s);
\end{xple}

An appropriate binding for \p{example} in TL is:
 
\begin{xple}
\k{let} cCallExample =
   bind(:\k{Fun}(:String) :Int  ''/usr/lib/libexample.so''  ''example''  ''si'')
\end{xple}

The value \p{cCallExample} has the type \p{\k{Fun}(:String) :Int}. 
Therefore, the C function can be called as follows.

\begin{xple}
\k{let} result :Int = cCallExample(''My favorite String'')
\end{xple}

Note that external bindings are persistent and portable across host
architectures. For example, if the value \p{cCallExample} is transferred
with \p{dynamic.extern}/\p{intern}, the C binding would be reestablished
automatically.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Function Calls from External C Libraries to Tycoon}
\label{Sec. Function Calls from External C Libraries to Tycoon}

The programming interface between TL and C is bidirectional. It is not
only possible to call C functions from TL, but also to \e{call back} from
C to TL.

In order to minimize the programming effort for callbacks on the C side, it
is desirable to make TL functions appear like ordinary C function 
pointers. Moreover, this is indispensable in situations where an external
software component requires C callbacks but cannot be changed.

The module \p{cCallback} exports an abstract type \p{cCallback.T} which
represents C function pointers that refer to callbacks. The creation
function for values of type \p{cCallback.T} has the following signature:

\begin{xple}
new(Function $<$:\k{Ok}  function :Function  format :String) :T(Function)
\end{xple}

The first value argument (\p{function}) of \p{new} must always be a 
function, although this restriction is not checked. Nevertheless, the
function's signature has to be mirrored in the \p{format} string that
specifies how C arguments of the resulting callback are converted into TL
values. Every single character of the string corresponds to one parameter.
The parameter order is \e{from left to right} like in C, except for the
function result type which is given by the last character. The latter is
mandatory. The format characters are shown in the table in section 
\ref{Sec. Function Calls from Tycoon to External C Libraries}.

\comment{Check:}

If the format character \p{s} is used for a parameter, a C string argument
will be copied into a newly created store object (\e{copy-in}). In case of
a return value, a C string is copied into a chunk of memory allocated by 
\p{malloc}. Hence the parameter passing semantics are \e{copy-out} instead 
of \e{call by reference} which apply when the format character \p{\&} is
chosen. 

The format character \p{\&} does not apply to function return parameters.

The format character \p{v} specifies a function result value of \k{ok}
irrespective of the actual C value returned by C. For

A simple example follows:

\begin{xple}
\k{import} cCallback fmt

\k{let} myMessage(n :Int  r :Real) :String =
   fmt.int(n) $<>$ '' = '' $<>$ fmt.real(r)

\k{let} myMessageCallback =
   cCallback.new(myMessage  ''irs'')

\k{let} test =
   bind(:\k{Fun}(n :Int  messageCallback :cCallback.T) :\k{Ok}
         ''.../example.so.1.0''  ''test''  ''i\&v'')

test(2  myMessageCallback)
\end{xple}

The resulting console output would be

\begin{xple}
 ''pi * 2 = 6.28''
 \k{ok}
\end{xple}

assuming that the corresponding C program \p{\dots{}/example.c} looks like 
this:

\begin{xple}
\#include $<$stdio.h$>$

\k{void} test(\k{long} n, \k{char} *message(\k{long} n, \k{double} r))
\{
  printf(''pi * \%s$\backslash$n'', message(n, n * 3.14));
\}
\end{xple}

As callbacks can be transferred to address spaces which are not under
control of the Tycoon system, there is in general no way to determine their
temporal extent automatically. Callbacks are never persistent.
Callbacks occupy some memory resources that can only be released
explicitly:

\begin{xple}
cCallback.free(myMessageCallback)
\end{xple}

After freeing a callback it is invalid. Any subsequent usage is most likely
to cause strange system behaviour (e.g. crashes). Attentive readers may
have noticed some more problems in the example: In what manner does the
result string of the function \p{message} get allocated on the C side 
before it is passed to \p{printf}, who is in charge of releasing its memory
and how can this be done?

The current solution is that the format character \p{s} in a return value
position causes the allocation of an appropriate memory block by calling
\p{malloc}. This block has to be released by the C programmer by a call to
\p{free}. Thus, the C program in the example should be written as follows:

\begin{xple}
\#include $<$stdio.h$>$
\#include $<$malloc.h$>$

\k{void} test(\k{long} n, \k{char} *message(\k{long} n, \k{double} r))
\{
  \k{char} *p;

  p = message(n, n * 3.14);
  printf(''pi * \%s$\backslash$n'', p);
  free(p);
\}
\end{xple}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Creating Standalone Tycoon Applications}
\label{Sec. Creating Standalone Tycoon Applications}

The development of Tycoon applications widely involves the Tycoon compiler toplevel where Tycoon code fragments and modules are interactively compiled, imported and executed. A ready-to-run application can be executed in several ways in the Tycoon context:

\begin{description}
\item[Pipes:] The Tycoon compiler toplevel reads input from stdin and writes output to stdout. So commands can be piped to the Tycoon compiler toplevel. Example (using Unix shell commands, e.g. in a shell script):
\begin{xple}
cat "do makeLibraries testLib;" >command.tyc
cat "import test :Main;" >>command.tyc
cat "test.main(array \"test\" end);" >>command.tyc
cat "do exit;" >>command.tyc
tycoon -create <command.tyc
\end{xple}
A Tycoon store is created and the Tycoon Compiler \p{tycoon.x} executed. The compiler toplevel interpretes the commands read through stdin from the file \p{command.tyc}.

\item[Boot-file:] A function that fulfills the signature \p{Fun(:Array(String)) :Int} (see interface \p{Main.ti} in library \p{stdenv}) can be saved as a boot-file through the module \p{dynamic}. This boot-file is loaded and executed by the Tycoon Machine in a fresh store like the Tycoon compiler \p{tycoon.x} (in fact \p{tycoon.x} was generated this way). The following script shows how a boot-file \p{main.x} is created from the function \p{main} on the Tycoon compiler toplevel:
\begin{exple}
import dynamic print;
\k{let} main(argv :Array(String)) :Int =
\k{begin}
  \k{for} i = 0 \k{upto} extent(argv)-1 \k{do}
   print.string(argv[i]) print.ln()
  \k{end}
  0
\k{end};
dynamic.bootFile(main "main.x" dynamic.portable); (* ## *)
\end{xple}
A new Tycoon store \p{main.ts} is created and the boot-file \p{main.x} is executed in this store by the following command (using a Unix shell):
\begin{exple}
tycoon -create -store main.ts -boot main.x -user test
\r test
\end{xple}
The arguments after the parameter \p{-user} are passed to the function \p{main}, so the function prints in this case the argument \p{test} on the screen. The return code (0 in this case) can be interpreted by the shell like for C applications.

\item[Persistent thread:] If you want to keep persistent data between two executions of your application program you can use threads. The Tycoon Machine is started with the parameter \p{-restart} that keeps all data in the store and continues the application at the last checkpoint using the module \p{checkpoint} of \p{stdenv}. This is a main loop of an application:
\begin{exple}
\k{let} main(argv :Array(String)) :Int =
\k{begin}
    (* -- initialize your application: *)
    \k{for} i = 0 \k{upto} extent(argv)-1 \k{do}
      print.string(argv[i]) print.ln()
    \k{end}
    \k{loop} (* -- main loop *)
      \k{if} checkpoint.commit() == checkpoint.commitVia \k{then}
        (* -- on commit we continue here: *)
    \k{exit}
      \k{else}
        (* -- on restart we continue here: *)
        \k{let} actualArgv = parameters.get()
        \k{for} i = extent(actualArgv)-1 \k{downto} 0 \k{do}
          print.string(actualArgv[i]) print.char(' ')
        \k{end}
        print.ln()
      \k{end} (* if *)
    \k{end} (* loop *)
    0
\k{end};
\end{xple}
This functions prints on the first invocation it's parameters \p{argv} and commits because \p{checkpoint.commit} returns \p{checkpoint.commitVia}. On the second (and all following invocations) the execution begins with the return from \p{checkpoint.commit}, but this time the value \p{checkpoint.restartVia} is returned, so the \k{else} branch is executed. The actual command line parameters (given by \p{-user}) of this invocation can be fetched using the function \p{get} of the module \p{parameters} of \p{stdenv} while \p{argv} still holds the command line parameters of the first invocation.
\begin{exple}
tycoon -create -store main.ts -boot main.x -user test
\r test
tycoon restart -store main.ts -user who am i
\r i am who
\end{xple}
\end{description}

\newpage

\bibliographystyle{alpha}
\bibliography{../Referenzen/florian-macros,../Referenzen/florian}

\end{document}
