% Haskell 98 Addendum: Hierarchical Module Namespace Extension
% [ Addendum to the Definition of Haskell 98 ]
%
% Editor: Simon Marlow <simonmar@microsoft.com>
%
% Copyright 2003 Simon Marlow
%
% The authors intend this Report to belong to the entire Haskell community, and
% so we grant permission to copy and distribute it for any purpose, provided
% that it is reproduced in its entirety, including this Notice.  Modified
% versions of this Addendum may also be copied and distributed for any purpose,
% provided that the modified version is clearly presented as such, and that it
% does not claim to be a definition of The Haskell~98 Hierarchical
% Module Namespace Extension.
%

\documentclass[a4paper,twoside]{article}

\usepackage{a4wide}
\usepackage{url}
\usepackage{code}

\newcommand{\clearemptydoublepage}{%
  \newpage{\pagestyle{empty}\cleardoublepage}}

\begin{document}

\makeatactive

\title{%
  DRAFT: The Hierarchical Module Namespace Extension, version 0.0\\
  An Addendum to the Haskell~98 Report%
}
\author{
  Simon Marlow, Microsoft Research, Cambridge\\
  Malcolm Wallace, University of York
}

\date{}
\maketitle
\par\vfill
\noindent
Copyright (c) 2003 Simon Marlow
\par\noindent
\emph{The authors intend this Report to belong to the entire Haskell
community, and so we grant permission to copy and distribute it for
any purpose, provided that it is reproduced in its entirety, including
this Notice.  Modified versions of this Addendum may also be copied
and distributed for any purpose, provided that the modified version is
clearly presented as such, and that it does not claim to be a
definition of The Haskell~98 Hierarchical
Module Namespace Extension.}

\par\bigskip\noindent The master version of Hierarchical Module
Namespace Extension is at \url{haskell.org}. Any corrections or
changes in the report are found there.
\thispagestyle{empty}

\clearemptydoublepage
\pagenumbering{roman}
%\tableofcontents

\clearemptydoublepage
\section*{Preface}

Haskell~98 defines a module system with a \emph{flat} module
namespace.  That is, module names are just identifiers, and all module
names occupy the same namespace.  This creates two problems for the
Haskell programmer: 

\begin{itemize}
\item
  There is no consistent naming scheme for modules, so it is hard to
  locate functionality within a library.

\item
  Module names are likely to clash with each other.  It is not
  possible to choose a module name for a library that is guaranteed
  not to clash with other library modules.
\end{itemize}

The purpose of this document is to define a modest extension to
Haskell~98 that extends the module namespace and gives it a
hierarchical structure.  

On the face of it, this extension solves neither of the above two
problems!  However, it is an important first step: in having a way to
arrange modules into a hierarchy, we have a \emph{mechanism} to avoid
name clashes, and a way to organise libraries into a tree by
functionality.  The policy by which the hierarchy itself is organised
is not in the scope of this specification, but we expect it to be the
subject of future specification(s).

This document is an \emph{addendum} to the Haskell~98 definition,
which means that it has undergone extensive peer-review by the Haskell
community prior to publication\footnote{or at least it will have done,
by the time version 1.0 is published}.

The hierarchical module namespace extension depends on no other
Haskell~98 extensions.

\subsection*{Acknowledgements}

We would like to thank everyone on the mailing list
@libraries@\verb+@+@haskell.org@ who has contributed in some way to this
proposal, and also those Haskell system implementors who have added
this extension to their compilers and interpreters.

\clearemptydoublepage
\pagenumbering{arabic}
\section{The Language Extension}

The key concept is to map the module namespace into a hierarchical
directory-like structure. We propose using the dot as a separator,
analogous to Java's usage for namespaces.

This is a surface change to the module naming convention. It does not
introduce nested definition of modules.  One change is required to the
lexical syntax of Haskell, namely that \textit{modid} is redefined
from:

\[
  \textit{modid} \rightarrow \textit{conid}
\]

\noindent to:

\[
  \textit{modid} \rightarrow \textit{qconid}
\]

\noindent for reference, the definition of \textit{qconid} is:

\[
   \textit{qconid} \rightarrow [ \textit{modid} @.@ ] \textit{conid}
\]

\noindent Note that the new syntax is recursive, a \textit{modid} may contain
multiple components separated by dots, where the final component is a
\textit{conid}.

A consequence of using the dot as the module namespace separator is
that it steals one extremely rare construction from Haskell~98:

\begin{code}
   A.B.C.D 
\end{code}

\noindent in Haskell'98 means the composition of constructor D from
module C, with constructor B from module A:

\begin{code}
   (.)  A.B  C.D 
\end{code}

\noindent With the hierarchical module namespace extension, @A.B.C.D@
would instead be interpreted as the identifier @D@ from module
@A.B.C@.  If the original Haskell~98 interpretation is intended, then
it must be written with extra spaces, as @A.B . C.D@.

\section{Modules and the filesystem}
      
This section describes possible implementation techniques, and how we
expect the hierarchical namespace to be exposed to the programmer by
Haskell implementations.  What follows is \emph{not} part of the
specification of the hierarchical module namespace extension; Haskell
implementations are still free to implement any mapping between
modules and filenames they choose (as in plain Haskell~98).

For most compilers and interpreters, we expect that the hierarchical
module namespace will map directly to a directory/file structure in
which the modules are stored.  For example, a module @Foo.Bar.Baz@
might be stored in the file @Foo/Bar/Baz.hs@ if @/@ is the directory
separator.

Note that the hierarchical module namespace is far simpler than a file
directory structure, in that hierarchical module names do not provide
any operations such as relative paths or parent directory.

In the hierarchical module namespace, a particular module name may
also be a node in the hierarchy.  For example, we might have modules
names both @Data.Array@ and @Data.Array.IO@.  It is therefore
important that directories are distinguished form Haskell source
modules, for example by using the @.hs@ suffix: @Data.Array@ would be
stored in @Data/Array.hs@ and @Data.Array.IO@ in @Data/Array/IO.hs@.

\end{document}
