--- /dev/null
+<?xml version="1.0" encoding="iso-8859-1"?>
+<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+ "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
+ <!ENTITY libtable SYSTEM "libtable.xml">
+]>
+
+<article id="libraries">
+ <articleinfo>
+ <title>Hierarchical Haskell Libraries</title>
+ <orgname>The Haskell Libraries Mailing List</orgname>
+ <address><email>libraries@haskell.org</email></address>
+ </articleinfo>
+
+ <sect1 id="introduction">
+ <title>Introduction</title>
+
+ <para>The <ulink
+ url="http://www.haskell.org/hierarchical-modules/">Hierarchical
+ Module Namespace Extension</ulink> is a modest extension to Haskell 98
+ which replaces the existing flat module namespace with a
+ hierarchy.</para>
+
+ <para>This document constitutes a proposal for how the new
+ hierarchical namespace should be used. It is
+ <emphasis>not</emphasis> an addendum to the Haskell 98 report: the
+ contents of this document are still under discussion on the
+ <ulink
+ url="http://www.haskell.org/mailman/listinfo/libraries"><literal>libraries@haskell.org</literal></ulink>
+ mailing list, and are subject to change.</para>
+
+ <para>The most up to date version of this document can be found in
+ the <ulink
+ url="http://www.haskell.org/ghc/docs/latest/html/building/sec-cvs.html">GHC
+ CVS repository</ulink> in the directory
+ <literal>fptools/libraries/doc</literal>.</para>
+
+ <para>The proposal has several parts: </para>
+
+ <itemizedlist>
+ <listitem>
+ <para>An allocation of the new module namespace to existing
+ and non-existent libraries, people, organisations, and local
+ use.</para>
+ </listitem>
+ <listitem>
+ <para>A policy and procedure for allocating new parts of the
+ namespace.</para>
+ </listitem>
+ <listitem>
+ <para>A set of libraries which are under the control of the
+ community and have reference implementations. These libraries
+ will vary from almost completely stable (eg. the
+ <literal>Prelude</literal>) to experimental libraries with
+ fast-changing APIs. Throughout this document, these libraries
+ shall be referred to as the <firstterm>Reference
+ Libraries</firstterm>. The reference libraries serve to both
+ define the library APIs, and provide implementations; in most
+ cases this will be the primary implementation of that
+ library.</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>In addition, this document also describes:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>Guidelines and conventions for organising the
+ hierarchy.</para>
+ </listitem>
+ <listitem>
+ <para>Our policy with respect to the design and evolution of
+ library APIs, versioning of library APIs, and maintenance of
+ the reference implementation.</para>
+ </listitem>
+ <listitem>
+ <para>A set of conventions for coding style and portability
+ within the libraries.</para>
+ </listitem>
+ </itemizedlist>
+ </sect1>
+
+ <sect1 id="contributing">
+ <title>How to contribute</title>
+
+ <para>This project is driven by the Haskell community, so
+ contributions of all kinds are welcome. The first step is to join
+ the <ulink
+ url="http://www.haskell.org/mailman/listinfo/libraries">Haskell
+ libraries mailing list</ulink>, and maybe <ulink
+ url="http://www.haskell.org/pipermail/libraries/">browse the list
+ archives</ulink>. Some of the ways you can contribute are:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>By donating code: for libraries which don't yet have a
+ reference implementation, code is always welcome. Code that
+ conforms to the design guidelines (which aren't very strict,
+ see <xref linkend="library-design"/>) and comes with documentation
+ (<xref linkend="documentation"/>) and a test suite (<xref
+ linkend="testing"/>) is better, but these aren't essential. As
+ a library progresses through the stability scale (<xref
+ linkend="stability"/>) these things become more important, but
+ for an experimental library we're not going to worry too much
+ about this stuff.</para>
+
+ <para>See section <xref
+ linkend="contributing-reference-libraries"/> for details on
+ contributing new library code.</para>
+ </listitem>
+ <listitem>
+ <para>By porting code for an existing library to a new
+ compiler or architecture. A library is classed as portable if
+ it should be available regardless of which compiler/platform
+ combination you're using; however, many libraries are
+ non-portable for one reason or another (see <xref
+ linkend="portability"/>), and broadening the scope of these
+ libraries is always welcome.</para>
+ </listitem>
+ <listitem>
+ <para>Become a library maintainer: if you have a particular
+ interest in and/or knowledge about a certain library, and have
+ the time to spare, and the library in question doesn't already
+ have a maintainer, then you may be a suitable maintainer for
+ the library. The responsibilities of library maintainers are
+ given in <xref linkend="maintainership"/>. </para>
+ </listitem>
+ <listitem>
+ <para>Participating in the design process for new libraries,
+ and suggesting improvements to existing libraries. Everyone
+ on the <ulink
+ url="http://www.haskell.org/mailman/listinfo/libraries">Haskell
+ libraries mailing list</ulink> is invited to
+ participate in the design process, so get involved!</para>
+ </listitem>
+ </itemizedlist>
+
+ </sect1>
+
+<!--
+ <sect2>
+ <title>A possible extension</title>
+
+ <para>The use of qualified imports has become more verbose: for
+ instance</para>
+
+<programlisting>
+ import qualified XmlParse
+ ... XmlParse.element f ...
+</programlisting>
+
+ <para>becomes</para>
+
+<programlisting>
+ import qualified Text.Xml.Parse
+ ... Text.Xml.Parse.element f ...
+</programlisting>
+
+ <para>It is usually more convenient to make use of Haskell's
+ <literal>as</literal> keyword to shorten qualified identifiers:</para>
+
+<programlisting>
+ import qualified Text.Xml.Parse as Parse
+ ... Parse.element f ...
+</programlisting>
+
+ <para>A possible extension to the proposal is to make this use
+ of <literal>as</literal> implicit, unless overridden by the
+ programmer with her own <literal>as</literal> clause. The
+ implicit <literal>as</literal> clause always uses the final
+ subdivision of the module name. So for instance, either the
+ fully-qualified or abbreviated-qualified names</para>
+
+<programlisting>
+ Text.Xml.Parse.element
+ Parse.element
+</programlisting>
+
+ <para>would be accepted and have the same referent, but a
+ partial qualification like</para>
+
+<programlisting>
+ Xml.Parse.element
+</programlisting>
+
+ <para>would not be accepted.</para>
+ </sect2>
+
+ <sect2>
+ <title>Renaming subtrees</title>
+
+ <para>Various proposals have been made to allow you to rename a
+ whole subtree. This may occasionally be convenient: for example
+ suppose there are several libraries under
+ <literal>Org.Com.Microsoft</literal> that I need to import, it
+ would be easier to rename this subtree to just
+ <literal>Microsoft</literal> for use in future import
+ declarations. For example:</para>
+
+<programlisting>
+ import Org.Com.Microsoft.* as Microsoft.*
+ import Microsoft.Foo
+ import Microsoft.Bar
+ ...
+</programlisting>
+
+ <para>The exact syntax of the renaming declaration is up for
+ debate (as is whether we need it at all), please send
+ suggestions to <email>libraries@haskell.org</email>.</para>
+ </sect2>
+-->
+
+
+ <sect1 id="layout">
+ <title>The hierarchy</title>
+
+ <para>We first classify each node in the hierarchy according to
+ one of the following terms:</para>
+
+ <variablelist>
+ <varlistentry>
+ <term>Allocated</term>
+ <listitem>
+ <para>Nodes in the hierarchy can be allocated to a library.
+ The currently allocated nodes are specified in <xref
+ linkend="allocated-names"/>.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>User</term>
+ <listitem>
+ <para>The <literal>User</literal> hierarchy is reserved for
+ users: a user may always use the portion of the hierarchy
+ which is formed from his/her email address as follows:
+ replace any <quote><literal>.</literal></quote>s in the
+ username (before the <literal>@</literal>) with
+ <quote><literal>_</literal></quote>, replace the
+ <quote><literal>@</literal></quote> by a
+ <quote><literal>.</literal></quote>, reverse the order of
+ the components, capitalise the first letter of each
+ component, and prepend
+ <quote><literal>User.</literal></quote>. For example,
+ <literal>simonmar@microsoft.com</literal> becomes
+ <literal>User.Com.Microsoft.Simonmar</literal>.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Organisation</term>
+ <listitem>
+ <para>The <literal>Org</literal> hierarchy is reserved for
+ organisations. Any organisation with a DNS domain name owns
+ a unique space in the hierarchy formed by reversing the
+ components of the domain, capitalising the first character
+ of each component, and prepending <literal>Org.</literal>.
+ <emphasis>ToDo: the Org name isn't great, especially when
+ the domain name also ends with Org (eg. Org.Org.Haskell?).
+ Contrib has also been suggested.</emphasis></para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Local</term>
+ <listitem>
+ <para>The <literal>Local</literal> hierarchy is reserved for
+ libraries which are local to the current site. Libraries
+ which are to be distributed outside the current site should
+ not be placed in the <literal>Local</literal>
+ hierarchy.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Unallocated</term>
+ <listitem>
+ <para>Any node which doesn't belong to any of the above
+ categories is currently unallocated, and is available for
+ use by Haskell programs.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>A node in the hierarchy may be both a specific library and a
+ parent node for a number of child nodes. For example,
+ <literal>Foreign</literal> is a library, and so is
+ <literal>Foreign.Ptr</literal>.</para>
+
+ <sect2 id="hierarchy-design-guidelines">
+ <title>Hierarchy design guidelines</title>
+
+ <para>Apart from the <literal>User</literal>,
+ <literal>Local</literal> and <literal>Org</literal> top-level
+ categories, the rest of the hierarchy is organised with a single
+ principle in mind:</para>
+
+ <blockquote>
+ <para>Modules are grouped by
+ <emphasis>functionality</emphasis>, since this is the single
+ property that is most helpful for a user of the library - we
+ want users to be able to find out where to obtain
+ functionality easily, and to easily find all the modules that
+ provide relevant functionality.</para>
+
+ <para>So, if two modules provide similar functionality, or
+ alternative interfaces to the same functionality, then they
+ should be children of the same node in the hierarchy. Modules
+ should not be grouped by standards compliance, portability,
+ stability, or any other property.</para>
+ </blockquote>
+
+ <para>It should be noted that this is a guideline rather than a
+ rule: sometimes it just isn't the right thing. For example, the
+ <literal>DotNet</literal> top-level name contains a mirror of
+ the Microsoft .NET base class library; if we had gone purely by
+ functionality then these libraries would have to be scattered
+ around the hierarchy, resulting in a situation where it would
+ probably be <emphasis>harder</emphasis> for a programmer to find
+ the functionality he or she is interested in.</para>
+
+ <para>There are some other considerations when choosing where to
+ place libraries. Where possible, choose a layout that finds a
+ good compromise between depth of nesting and logical grouping of
+ functionality; for example, although the <literal>Text</literal>
+ hierarchy could logically be placed as a child of
+ <literal>FileFormat</literal>, we choose not to because
+ <literal>Text</literal> is ubiquitous and we don't want to have
+ to type the extra component all the time.</para>
+
+ <para>Also consider consistency: if a particular sub-hierarchy
+ provides similar functionality to another sub-hierarchy in the
+ tree, then preferably the structure of the two subtrees should
+ also be similar. For example: under
+ <literal>Language.Haskell</literal> we have children
+ <literal>Syntax</literal>, <literal>Lexer</literal>,
+ <literal>Parser</literal> etc., so under
+ <literal>Language.C</literal> we should have a similar
+ structure.</para>
+ </sect2>
+
+ <sect2 id="module-naming-convention">
+ <title>Module naming conventions</title>
+
+ <itemizedlist>
+ <listitem>
+ <para>A module defining a data type or type class
+ <replaceable>X</replaceable> has itself the name
+ <replaceable>X</replaceable>, e.g.
+ <literal>StablePtr</literal>.</para>
+ </listitem>
+
+ <listitem>
+ <para>A module which re-exports the modules in a subtree of
+ the hierarchy has the same name as the root of that subtree,
+ eg. <literal>Foreign</literal> re-exports
+ <literal>Foreign.Ptr</literal>,
+ <literal>Foreign.Marshal.Utils</literal> etc.</para>
+ </listitem>
+
+ <listitem>
+ <para>If a subtree of the hierarchy contains several modules
+ which provide similar functionality (eg. there are several
+ pretty-printing libraries under
+ <literal>Text.PrettyPrinter</literal>), then the module at
+ the root of the subtree generally re-exports just
+ <emphasis>one</emphasis> of the modules in the subtree
+ (possibly the most popular or commonly-used
+ alternative).</para>
+ </listitem>
+
+ <listitem>
+ <para>In Haskell you sometimes publish
+ <emphasis>two</emphasis> interfaces to your libraries; one
+ for users, and one for library writers or advanced users who
+ might want to extend things. Typically the advanced users
+ need to be able to see past certain abstractions.</para>
+
+ <para>The current proposal is for a module named
+ <literal>M</literal>, the <quote>advanced</quote> version
+ would be named <literal>M.Internals</literal>. eg.</para>
+
+<programlisting>
+import Text.HTML -- The library
+import Text.HTML.Internals -- The non-abstract library
+</programlisting>
+ </listitem>
+
+ <listitem>
+ <para>Acronyms are fully capitalised in a module name.
+ eg. <literal>HTML</literal>, <literal>URI</literal>,
+ <literal>CGI</literal>, etc. Exceptions may be made for
+ acronyms which have an existing well-established alternative
+ capitalisation, or acronyms which are also valid words, and
+ are more often used as such.</para>
+ </listitem>
+
+ <listitem>
+ <para>A module name should be made plural only if the module
+ actually defines multiple entities of a particular kind:
+ eg. <literal>Foreign.C.Types</literal>. Most module names
+ which define a type or class will follow the name of the
+ type or class, so whether to pluralize is not an
+ issue.</para>
+ </listitem>
+ </itemizedlist>
+ </sect2>
+
+ <sect2 id="top-level-names">
+ <title>The top-level names</title>
+
+ <para>The currently allocated nodes in the hierarchy are listed
+ in the next section (<xref linkend="allocated-names"/>). In
+ addition, for each top-level name we describe its intended
+ purpose below:</para>
+
+ <variablelist>
+ <varlistentry>
+ <term><literal>Control</literal></term>
+ <listitem>
+ <para>Libraries which provide functions, types or classes
+ whose purpose is primarily to express control
+ structure.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>Data</literal></term>
+ <listitem>
+ <para>Libraries which provide data types, operations over
+ data types, or type classes, except for libraries for
+ which one of the other more specific categories is
+ appropriate.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>Database</literal></term>
+ <listitem>
+ <para>Libraries for providing access to or operations for
+ building databases.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>Debug</literal></term>
+ <listitem>
+ <para>Support for debugging Haskell programs.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>DotNet</literal></term>
+ <listitem>
+ <para>Mirrors the Microsoft .NET base class hierarchy, for
+ systems providing access to the .NET libraries.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>Edison</literal></term>
+ <listitem>
+ <para>The Edison data structure library.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>Codec</literal></term>
+ <listitem>
+ <para>Support for (en)coding and decoding data in various
+ formats. <literal>Codec</literal> encompasses compression
+ (both lossy and non-lossy) codings, transport
+ codings, and encryption.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>Foreign</literal></term>
+ <listitem>
+ <para>Interaction with code written in a foreign
+ programming language.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>Graphics</literal></term>
+ <listitem>
+ <para>Libraries for producing graphics or providing
+ graphical user interfaces.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>Language</literal></term>
+ <listitem>
+ <para>Libraries for operating on or generating source code
+ in various programming languages, including parsers,
+ pretty printers, abstract syntax definitions etc.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>Local</literal></term>
+ <listitem>
+ <para>Available for site-local use.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>Numeric</literal></term>
+ <listitem>
+ <para>Functions and classes which provide operations over
+ numeric data.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>Network</literal></term>
+ <listitem>
+ <para>Libraries for communicating over a network,
+ including implementations of network protocols.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>Org</literal></term>
+ <listitem>
+ <para>Allocated to organisations on a domain-name
+ basis (see <xref linkend="layout"/>).</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>Prelude</literal></term>
+ <listitem>
+ <para>Haskell98 Prelude (mostly just re-exports other
+ parts of the tree).</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>System</literal></term>
+ <listitem>
+ <para>Libraries for communication with the system on which
+ the Haskell program is running (including the runtime
+ system).</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>Text</literal></term>
+ <listitem>
+ <para>Libraries for parsing and generating data in a
+ textual format (including structured textual formats such
+ as XML, HTML, but not including programming language
+ source, which lives in Language).</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>GHC</literal></term>
+ <listitem>
+ <para>Libraries specific to the GHC/GHCi system.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>Nhc</literal></term>
+ <listitem>
+ <para>Libraries specific to the Nhc compiler.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>Hugs</literal></term>
+ <listitem>
+ <para>Libraries specific to the Hugs system.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>User</literal></term>
+ <listitem>
+ <para>Allocated to individual users, using email
+ addresses (see <xref linkend="layout"/>).</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </sect2>
+
+ <sect2 id="allocated-names">
+ <title>Allocated libraries</title>
+
+ <informaltable>
+ <tgroup cols="3" align="left" colsep="1" rowsep="1">
+ <thead>
+ <row>
+ <entry>Library</entry>
+ <entry>Maintainer</entry>
+ <entry>URL</entry>
+ </row>
+ </thead>
+ <tbody>
+ &libtable;
+ </tbody>
+ </tgroup>
+ </informaltable>
+ </sect2>
+ </sect1>
+
+ <sect1 id="reference-libraries">
+ <title>Reference libraries</title>
+
+ <para>There are reference implementations for many of the
+ libraries allocated in the hierarchy (see <xref
+ linkend="allocated-names"/>). These reference libraries serve to define
+ the API for each library, and also in most cases provide the
+ primary implementation of that library. We don't discount the
+ possibility that multiple implementations of libraries may exist,
+ but there is only ever one reference implementation.</para>
+
+ <para>Many of the reference libraries live in the CVS repository
+ on <literal>cvs.haskell.org</literal> under the directory <ulink
+ url="http://cvs.haskell.org/cgi-bin/cvsweb.cgi/fptools/libraries"><literal>fptools/libraries</literal></ulink>,
+ but others are maintained and distributed separately by members of
+ the Haskell community. <xref linkend="allocated-names"/> lists the
+ maintainer for each reference library, and a location from which
+ the code can be obtained.</para>
+
+ <sect2 id="installing">
+ <title>Installing libraries</title>
+
+ <para>Compilers are normally distributed with a number of
+ libraries, which may or may not be built from the reference
+ implementations.</para>
+
+ <para>Currently, the procedure for installing a library which is
+ not distributed with your compiler is currently dependent on a
+ number of things: platform, compiler, and how much support is
+ provided by the library maintainer. We aim to standardise this
+ procedure to a certain extent by providing a library
+ infrastructure which automates the building, installation and
+ packaging of libraries for all architectures and compilers. The
+ means by which we might achieve this are being actively
+ discussed: see the <ulink
+ url="http://www.haskell.org/pipermail/libraries/">libraries
+ mailing list archives</ulink>.</para>
+ </sect2>
+
+ <sect2 id="contributing-reference-libraries">
+ <title>Contributing new reference libraries</title>
+
+ <para>The process for contributing a new library is as
+ follows:</para>
+
+ <variablelist>
+ <varlistentry>
+ <term>Allocate module names.</term>
+ <listitem>
+ <para>If you want a library in the <literal>User</literal>
+ or <literal>Org</literal> part of the hierarchy, then
+ nothing needs to be done: just go ahead and distribute
+ your library.</para>
+
+ <para>If, however, you are providing a library for any
+ other part of the hierarchy, then the module names in the
+ should be allocated. <xref linkend="allocated-names"/>
+ lists the parts of the hierarchy that are currently
+ allocated.</para>
+
+ <para>There are several reasons for allocating module
+ names centrally in this way:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>Haskell users have the guarantee that libraries
+ never conflict with each other by using the same
+ module name.</para>
+ </listitem>
+ <listitem>
+ <para>There is always one place to obtain a given
+ library, each library has a single reference
+ implementation, and there is a single point of contact
+ for the implementor(s).</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>Remember that this only applies to libraries: code
+ in a <emphasis>program</emphasis> can use whatever module
+ names it chooses (but it's probably a good idea to avoid
+ conflicting with any libraries that might be installed:
+ avoiding the allocated module names is a good way to
+ ensure that).</para>
+
+ <para>To allocate module names for a new library, send
+ mail to <email>libraries@haskell.org</email> describing
+ your library and which module names you are proposing to
+ allocate. Provided there is no conflict, then the names
+ will normally be allocated and added to the list above. A
+ conflict might arise if for example someone else wants to
+ provide a library with the same name; conflicts will be
+ resolved by consensus on a case-by-case basis.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Distribute the library.</term>
+ <listitem>
+ <para>The mechanism by which libraries should be
+ distributed is currently being discussed; we hope in the
+ future to make the process much easier for library
+ writers. Currently you have to do all the work yourself:
+ write a build system (or steal one), installation scripts
+ and support for packaging on each platform that you wish
+ to support.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </sect2>
+
+ <sect2 id="licensing">
+ <title>Licensing</title>
+
+ <para>Following some discussion on the mailing list related to
+ how we should license the libraries, the viewpoint that was
+ least offensive to all involved seems to be the
+ following:</para>
+
+ <para>We wish to accommodate source code from different
+ contributors, and with different licenses. However, a library
+ of modules where each module is released under a different
+ license, and where the dependencies between modules aren't
+ clear, isn't workable (it's too hard for a user of the library
+ to tell whether they're violating the terms of the each license
+ or not).</para>
+
+ <para>So the solution is as follows: code under different
+ licenses will be clearly separate in the repository (i.e. in
+ separate subdirectories), and compilers are expected to present
+ packages of modules where all modules in a package fall under
+ the same license, and where the dependencies between packages
+ are clear.</para>
+
+ <para>It was decided that certain essential functionality should
+ be available under a BSD style license. Hence, the BSD part of
+ the repository will contain implementations of at least the
+ following modules: <literal>Prelude</literal>,
+ <literal>Foreign</literal>, <emphasis>ToDo: what
+ else?</emphasis>.</para>
+
+ <para>There is one further requirement: reference libraries must
+ be available under a license approved by the Open Source
+ Initiative. See <ulink url="http://www.opensource.org//">The
+ Open Source Initiative</ulink> for a list of approved
+ licensees.</para>
+ </sect2>
+
+ <sect2 id="versioning">
+ <title>Versioning</title>
+ <para><emphasis>ToDo</emphasis></para>
+ </sect2>
+
+ <sect2 id="stability">
+ <title>Library stability</title>
+
+ <para>The stability of a library relates primarily to its API.
+ Stability provides an indication of how often the API is likely
+ to change (or whether it may even go away entirely).</para>
+
+ <para>The stability scale is also a measure of how strictly the
+ conventions in this document are applied to the library: an
+ experimental library isn't subject to any restrictions regarding
+ coding style and documentation, but a stable library is expected
+ to adhere to the guidelines, and come with full documentation
+ and tests.</para>
+
+ <para>To help with the stability issue, library maintainers are
+ allowed to mark functions, types or classes as
+ <firstterm>deprecated</firstterm><footnote><para>Compilers may
+ have extra support for warning about the use of a deprecated
+ feature, for example GHC's <literal>DEPRECATED</literal>
+ pragma.</para> </footnote>, which means simply that the feature
+ will be removed at a later date. Just how long it will stick
+ around for depends on the stability category of the library (see
+ below). A feature is marked as deprecated in the documentation
+ for the library, and optionally in an implementation-dependent
+ way which enables the system to warn about the use of deprecated
+ features.</para>
+
+ <para>The current stability categories are:</para>
+
+ <variablelist>
+ <varlistentry>
+ <term><firstterm>experimental</firstterm></term>
+ <listitem>
+ <para>An experimental library is unrestricted in terms of
+ API changes: the API may change between minor revisions
+ and there is no requirement to retain old interfaces for
+ compatibility. Documentation and tests aren't required
+ for an experimental library.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><firstterm>provisional</firstterm></term>
+ <listitem>
+ <para>A provisional library is moving towards stability,
+ and the rate of change of the API is slower. API changes
+ between minor revisions must be accompanied by deprecated
+ versions of the old features where possible. API changes
+ between major versions are unrestricted. The library
+ should come with at least rudimentary
+ documentation.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><firstterm>stable</firstterm></term>
+ <listitem>
+ <para>A stable library has an essentially fixed API.
+ Additions to the API may be made for a minor release,
+ deprecated features must be retained for at least one
+ major revision, and small changes only may be made to the
+ existing API semantics for a major revision. A stable
+ library is expected to include full documentation and
+ tests.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ </sect2>
+
+ <sect2 id="portability">
+ <title>Portability considerations</title>
+
+ <para>The portability status of a library affects which
+ platforms and compilers the library will be available on. The
+ precise meaning of the terms portable and non-portable for our
+ purposes are given below:</para>
+
+ <variablelist>
+ <varlistentry>
+ <term><firstterm>Portable</firstterm></term>
+ <listitem>
+ <para>A library which is available on all platforms and
+ with all Haskell implementations is portable.</para>
+
+ <para>A portable library may make use of non-portable
+ features or import non-portable libraries in its
+ implementation, as long as it does so conditionally and
+ provides the same interface on all platforms and with all
+ Haskell implementations.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><firstterm>Non-portable</firstterm></term>
+ <listitem>
+ <para>A non-portable library may be non-portable for one
+ or more of the following reasons:</para>
+ <variablelist>
+ <varlistentry>
+ <term><firstterm>Requires extensions</firstterm></term>
+ <listitem>
+ <para>A library which uses non-approved language
+ extensions in its implementation, and has no
+ portable fallback implementation.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><firstterm>Requires nonportable libraries</firstterm></term>
+ <listitem>
+ <para>A library which depends (directly or indirectly)
+ on other non-portable libraries.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><firstterm>OS-specific</firstterm></term>
+ <term><firstterm>Platform-specific</firstterm></term>
+ <listitem>
+ <para>A library which depends on features or APIs
+ particular to a certain OS or platform is
+ non-portable for that reason.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ <sect3 id="approved-extensions">
+ <title>Approved extensions</title>
+
+ <para>Very few of the reference libraries can be implemented
+ using pure Haskell 98. For this reason, we decided to raise
+ the baseline for portable libraries to include a few common
+ extensions; the following language extensions can be
+ <emphasis>assumed</emphasis> to be present when writing
+ libraries:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>The <ulink
+ url="http://haskell.org/ghc/docs/latest/set/ffi.html">Foreign
+ Function Interface</ulink>.</para>
+ </listitem>
+ <listitem>
+ <para>Mutable variables
+ (<literal>Data.IORef</literal>).</para>
+ </listitem>
+ <listitem>
+ <para>Unsafe IO monad operations
+ (<literal>System.IO.Unsafe</literal>).</para>
+ </listitem>
+ <listitem>
+ <para>Packed strings
+ (<literal>Data.PackedString</literal>).</para>
+ </listitem>
+ <listitem>
+ <para>Bit operations (<literal>Data.Bits</literal>).</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>Extensions which we'd like to be standard, but aren't
+ currently implemented by one or more of the target
+ compilers:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>Exceptions (synchronous only), defined by the
+ <literal>Control.Exception</literal> interface.</para>
+ </listitem>
+ <listitem>
+ <para>The ST monad, defined by
+ <literal>Control.Monad.ST</literal>, and the associated
+ <literal>Data.Array.ST</literal> and
+ <literal>Data.STRef</literal> libraries. ST requires a
+ small typechecker extension for the
+ <literal>runST</literal> function.</para>
+ </listitem>
+ <listitem>
+ <para>Concurrent Haskell (pre-emptive multitasking
+ optional). GHC and Hugs implement this, but Nhc currently
+ does not.</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>The following extensions are not likely to become part
+ of the baseline, but are nevertheless used by one or more
+ libraries in the reference set (which are thus designated
+ non-portable):</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>Multi-parameter type classes.</para>
+ </listitem>
+ <listitem>
+ <para>Local universal and existential quantification.</para>
+ </listitem>
+ <listitem>
+ <para>Concurrent Haskell with pre-emptive multitasking.</para>
+ </listitem>
+ <listitem>
+ <para>Asynchronous exceptions.</para>
+ </listitem>
+ <listitem>
+ <para>Stable Names.</para>
+ </listitem>
+ <listitem>
+ <para>Weak Pointers.</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>Other extensions are supported by a single compiler
+ only, and can be accessed by libraries under the top level
+ hierarchy for that compiler,
+ eg. <literal>GHC.UnboxedTypes</literal>.</para>
+ </sect3>
+ </sect2>
+
+ <sect2 id="maintainership">
+ <title>Library maintainers</title>
+
+ <para>This is a collaborative project, so we like to devolve
+ control of the design and implementation of libraries to those
+ with an interest or appropriate expertise (or maybe just the
+ time!). A maintainer isn't necessarily a single person - for
+ example, the listed maintainer for most of the reference
+ libraries is <email>libraries@haskell.org</email>, indicating
+ that the library is under the control of the community as a
+ whole. The maintainer for the <literal>Foreign</literal>
+ hierarchy is <email>ffi@haskell.org</email>, the mailing list
+ for discussion of the Haskell FFI standard.</para>
+
+ <para>The responsibilities of a library maintainer include:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>Most importantly: act as a single point of contact for
+ issues relating to the library API and its
+ implementation.</para>
+ </listitem>
+ <listitem>
+ <para>Manage any discussion related to the library (which
+ can take place on <email>libraries@haskell.org</email> if
+ necessary), and summarise the results. Make final
+ decisions, and implement them.</para>
+ </listitem>
+ <listitem>
+ <para>Maintain the implementation, including: fixing bugs,
+ updating to keep up with changes in other libraries, porting
+ to new compilers/platforms, and integrating code from other
+ contributors. The maintainer is expected to be the only
+ person/group to make functional changes to the source code
+ (non-functional or trivial changes don't count).</para>
+ </listitem>
+ <listitem>
+ <para>Maintain/write the documentation and tests.</para>
+ </listitem>
+ <listitem>
+ <para>If you can't maintain the library any more for
+ whatever reason, tell <email>libraries@haskell.org</email>
+ and we'll revert the maintainer status of the library to the
+ default.</para>
+ </listitem>
+ </itemizedlist>
+ </sect2>
+
+ <sect2 id="documentation">
+ <title>Documentation</title>
+
+ <para>We are using <ulink
+ url="http://www.haskell.org/haddock/">Haddock</ulink> to
+ document the libraries. Haddock generates nice hyperlinked HTML
+ output directly from the Haskell source, and understands
+ comments written in a particular style as documentation
+ annotations, which are merged with the generated
+ documentation.</para>
+
+ <para>Before submitting code to the libraries project, please
+ ensure that it passes through Haddock without complaint. Even
+ if it contains no actual documentation annotations, we'll get
+ useful documentation out of the source alone (type signatures,
+ data types, etc.).</para>
+ </sect2>
+
+ <sect2 id="coding-style">
+ <title>Coding style</title>
+
+ <sect3 id="module-header">
+ <title>Standard module header</title>
+
+ <para>Using a standard module header makes it easy to
+ automatically extract meta-information from library source
+ code, such as the stability/portability of individual modules.
+ We recommend using the following module header for reference
+ libraries:</para>
+
+<programlisting>
+-----------------------------------------------------------------------------
+-- |
+-- Module : <replaceable>module</replaceable>
+-- Copyright : (c) <replaceable>author</replaceable> <replaceable>year</replaceable>
+-- License : <replaceable>license</replaceable>
+--
+-- Maintainer : libraries@haskell.org | <replaceable>email-address</replaceable>
+-- Stability : experimental | provisional | stable
+-- Portability : portable | non-portable (<replaceable>reason(s)</replaceable>)
+--
+-- $Id$
+--
+-- <replaceable>Description</replaceable>
+-----------------------------------------------------------------------------
+</programlisting>
+
+ <para>where:</para>
+
+ <variablelist>
+ <varlistentry>
+ <term><literal>$Id: libraries.xml,v 1.2 2004/08/18 16:42:56 panne Exp $</literal></term>
+ <listitem>
+ <para>is optional, but may be included if the module is
+ under CVS or RCS control (however, current wisdom
+ suggests that using
+ <literal>$Id$</literal> tags are not such
+ a great idea).</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><replaceable>module</replaceable></term>
+ <listitem>
+ <para>is the fully qualified module name of the
+ module</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><replaceable>author</replaceable>/<replaceable>year</replaceable></term>
+ <listitem>
+ <para>Is the primary author and copyright holder of the
+ module, and the year in which copyright is
+ claimed.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><replaceable>license</replaceable></term>
+ <listitem>
+ <para>Specifies the license on the file (see <xref
+ linkend="licensing"/>).</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><replaceable>email-address</replaceable></term>
+ <listitem>
+ <para>The email address of the maintainer, or
+ maintainers, of the library (see <xref
+ linkend="maintainership"/>).</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><replaceable>reason(s)</replaceable></term>
+ <listitem>
+ <para>The reasons for non-portability must be listed
+ (see <xref linkend="portability"/>).</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><replaceable>description</replaceable></term>
+ <listitem>
+ <para>A short description of the module.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </sect3>
+ </sect2>
+
+ <sect2 id="testing">
+ <title>Testing</title>
+ <para><emphasis>ToDo</emphasis></para>
+ </sect2>
+ </sect1>
+
+ <sect1 id="Migration-path">
+ <title>Migration path</title>
+
+ <para>How compatible will a compiler using the new libraries be
+ with code written for Haskell 98 or older library systems (such as
+ the <literal>hslibs</literal> suite and GHC's package system), and
+ for how long will compatibility be maintained?</para>
+
+ <para>Our current plan for GHC is as follows: by default, with the
+ <option>-fglasgow-exts</option> flag, you'll get access to the
+ following libraries from the CVS repository: those under
+ <literal>base</literal>, <literal>network</literal>,
+ <literal>unix</literal>, <literal>readline</literal>,
+ <literal>template-haskell</literal>, and
+ <literal>haskell-src</literal>. Compatibility with Haskell 98
+ code will be maintained using a separate package of wrappers
+ presenting interfaces for the Haskell 98 libraries
+ (<literal>IO</literal>, <literal>Ratio</literal>,
+ <literal>Directory</literal>, etc.). The Haskell 98 compatibility
+ package will be enabled by default, but we plan to add an option
+ to disable it if necessary. For code that uses <literal>-package
+ lang</literal>, we could also provide a compatibility wrapper
+ package (so <literal>-package lang</literal> will continue to work
+ as before and present the same library interfaces), but this may
+ prove too much work to maintain - we haven't decided whether to do
+ this or not. It is unlikely that compatibility wrappers for any
+ of the other <literal>hslibs</literal> packages will be
+ provided.</para>
+ </sect1>
+
+ <sect1 id="library-design">
+ <title>Library design</title>
+
+ <sect2 id="naming-conventions">
+ <title>Naming conventions</title>
+
+ <para>These naming conventions are pulled straight from the
+ <literal>hslibs</literal> documentation. They were formed after
+ lengthy discussions and are heavily based on an initial
+ suggestion from Marcin Kowalczyk
+ <email>qrczak@knm.org.pl</email>.</para>
+
+ <para>Note that the conventions are not mutually exclusive,
+ e.g. should the function creating a set from a list of elements
+ have the name <literal>set</literal> or
+ <literal>listToSet</literal>? (Alas, it currently has neither
+ name.)</para>
+
+ <para> The following nomenclature is used: Pure,
+ i.e. non-monadic functions are simply called, well,
+ <emphasis>functions</emphasis>. Monadic functions,
+ i.e. functions having a type <literal>... -> m a</literal>
+ for some Monad <literal>m</literal> are called
+ <emphasis>actions</emphasis>.</para>
+
+ <sect3 id="sec-library-constructor-names">
+ <title>Constructor names</title>
+ <indexterm><primary>Constructor names</primary></indexterm>
+
+ <itemizedlist>
+ <listitem>
+ <para>Empty values of type <replaceable>X</replaceable>
+ have the name <literal>empty<replaceable>X</replaceable></literal>,
+ e.g. <literal>emptySet</literal>.</para>
+ </listitem>
+
+ <listitem>
+ <para>Actions creating a new empty value of type
+ <replaceable>X</replaceable> have the name
+ <literal>newEmpty<replaceable>X</replaceable></literal>,
+ e.g. <literal>newEmptyMVar</literal>.</para>
+ </listitem>
+
+ <listitem>
+ <para>Functions creating an arbitrary value of type
+ <replaceable>X</replaceable> have the name
+ <replaceable>X</replaceable> itself (with the first letter
+ downcased),
+ e.g. <literal>array</literal>. (<emphasis>TODO</emphasis>:
+ This often collides with <literal>xToY</literal>
+ convention, how should this be resolved?)
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>Actions creating new values arbitrary values of type
+ <replaceable>X</replaceable> have the name
+ <literal>new<replaceable>X</replaceable></literal>,
+ e.g. <literal>newIORef</literal>.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </sect3>
+
+ <sect3 id="sec-library-accessor-names">
+ <title>Accessor names</title>
+ <indexterm><primary>Accessor names</primary></indexterm>
+
+ <itemizedlist>
+ <listitem>
+ <para>Functions getting an attribute of a value or a part
+ of it have the name of the attribute itself,
+ e.g. <literal>length</literal>, <literal>bounds</literal>.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para> Actions accessing some kind of reference or state
+ have the name
+ <literal>get<replaceable>X</replaceable></literal>, where
+ <replaceable>X</replaceable> is the type of the contents
+ or the name of the part being accessed,
+ e.g. <literal>getChar</literal>,
+ <literal>getEnv</literal>. An alternative naming scheme is
+ <literal>read<replaceable>Y</replaceable></literal>,
+ where <replaceable>Y</replaceable> is the type of the
+ reference or container, e.g. <literal>readIORef</literal>.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>Functions or actions getting a value via a
+ pointer-like type <replaceable>X</replaceable> should be
+ named
+ <literal>deRef<replaceable>X</replaceable></literal>,
+ e.g. <literal>deRefStablePtr</literal>,
+ <literal>deRefWeak</literal>.</para>
+ </listitem>
+ </itemizedlist>
+ </sect3>
+
+ <sect3 id="sec-library-modifier-names">
+ <title>Modifier names</title>
+ <indexterm><primary>Modifier names</primary></indexterm>
+
+ <itemizedlist>
+ <listitem>
+ <para>Functions returning a value with attribute
+ <replaceable>X</replaceable> set to a new value should be
+ named
+ <literal>set<replaceable>X</replaceable></literal>. (<emphasis>TODO</emphasis>:
+ Add Examples.)</para>
+ </listitem>
+
+ <listitem>
+ <para> Actions setting some kind of reference or state
+ have the name
+ <literal>put<replaceable>X</replaceable></literal>, where
+ <replaceable>X</replaceable> is the type of the contents
+ or the name of the part being accessed,
+ e.g. <literal>putChar</literal>. An alternative naming
+ scheme is
+ <literal>write<replaceable>Y</replaceable></literal>,
+ where <replaceable>X</replaceable> is the type of the
+ reference or container,
+ e.g. <literal>writeIORef</literal>. </para></listitem>
+
+ <listitem>
+ <para> Actions in the <literal>IO</literal> monad setting
+ some global state <replaceable>X</replaceable> are
+ traditionally named <literal>setX</literal>, too, although
+ <literal>put<replaceable>X</replaceable></literal> would
+ be more appropriate,
+ e.g. <literal>setReadlineName</literal>.</para>
+ </listitem>
+
+ <listitem>
+ <para> Actions modifying a container
+ <replaceable>X</replaceable> by a function of type
+ <literal>a -> a</literal> have the name
+ <literal>modify<replaceable>X</replaceable></literal>,
+ e.g. <literal>modifySTRef</literal>.</para>
+ </listitem>
+ </itemizedlist>
+ </sect3>
+
+ <sect3 id="sec-library-predicate-names">
+ <title>Predicate names</title>
+ <indexterm><primary>Predicate names</primary></indexterm>
+
+ <itemizedlist>
+ <listitem>
+ <para>Predicates, both non-monadic and monadic, testing a
+ property <replaceable>X</replaceable> have the name
+ <literal>is<replaceable>X</replaceable></literal>.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </sect3>
+
+ <sect3 id="sec-library-naming-conversions">
+ <title>Names for conversions</title>
+ <indexterm><primary>Names for conversions</primary></indexterm>
+
+ <itemizedlist>
+ <listitem>
+ <para>Functions converting a value of type
+ <replaceable>X</replaceable> to a value of type
+ <replaceable>Y</replaceable> have the name
+ <literal><replaceable>X</replaceable>To<replaceable>Y</replaceable></literal>
+ with all leading uppercase characters of
+ <replaceable>X</replaceable> converted to lower case,
+ e.g. <literal>stToIO</literal>.</para>
+ </listitem>
+
+ <listitem>
+ <para>Overloaded conversion functions of type
+ <literal>C a => a -> <replaceable>X</replaceable></literal>
+ have the name
+ <literal>to<replaceable>X</replaceable></literal>,
+ e.g. <literal>toInteger</literal>.</para>
+ </listitem>
+
+ <listitem>
+ <para> Overloaded conversion functions of type
+<literal>C a => <replaceable>X</replaceable> -> a</literal>
+ have the name <literal>from<replaceable>X</replaceable></literal>,
+e.g. <literal>fromInteger</literal>.</para>
+ </listitem>
+ </itemizedlist>
+ </sect3>
+
+ <sect3 id="sec-library-misc-names">
+ <title>Miscellaneous naming conventions</title>
+ <indexterm><primary>Miscellaneous naming
+ conventions</primary></indexterm>
+
+ <itemizedlist>
+ <listitem>
+ <para> An action that is identical to another one called
+ <replaceable>X</replaceable>, but discards the return
+ value has the name
+ <literal><replaceable>X</replaceable>_</literal>,
+ e.g. <literal>mapM</literal> and <literal>mapM_</literal>.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>Functions and actions which are potentially
+ dangerous to use and leave some kind of proof obligation
+ to the programmer have the name
+ <literal>unsafe<replaceable>X</replaceable></literal>,
+ e.g. <literal>unsafePerformIO</literal>.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>There are two conventions for binary and N-ary
+ variants of an associative operation: One convention uses
+ an operator or a short name for the binary operation and a
+ long name for the N-ary variant,
+ e.g. <literal>(+)</literal> and <literal>sum</literal>,
+ <literal>max</literal> and <literal>maximum</literal>. The
+ other convention suffixes the N-ary variant with
+ <literal>Many</literal>. (<emphasis>TODO</emphasis>: Add
+ Examples.)</para>
+ </listitem>
+
+ <listitem>
+ <para>If possible, names are chosen such that either plain
+ application or <literal>arg1 `operation` arg2</literal> is
+ correct English, e.g. <literal>isPrefixOf</literal> is
+ good for use in backquotes.</para>
+ </listitem>
+ </itemizedlist>
+ </sect3>
+ </sect2>
+
+ <sect2 id="sec-library-misc-conventions">
+ <title>Library design guidelines</title>
+
+ <itemizedlist>
+ <listitem>
+ <para>Actions setting and modifying a kind of reference or
+ state return <literal>()</literal>, getting the value is
+ separate, e.g. <literal>writeIORef</literal> and
+ <literal>modifyIORef</literal> both return
+ <literal>()</literal>, only <literal>readIORef</literal>
+ returns the value in an <literal>IORef</literal>
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>A function or action taking a some kind of state and
+ returning a pair consisting of a result and a new state, the
+ result is the first element of the pair and the new state is
+ the second, see e.g. <literal>Random</literal>.</para>
+ </listitem>
+
+ <listitem>
+ <para>When the type <literal>Either</literal> is used to
+ encode an error condition and a normal result,
+ <literal>Left</literal> is used for the former and
+ <literal>Right</literal> for the latter, see
+ e.g. <literal>Control.Monad.Error</literal>.</para>
+ </listitem>
+
+ <listitem>
+ <para>A module corresponding to a class
+ (e.g. <literal>Bits</literal>) contains the class
+ definition, perhaps some auxiliary functions, and all
+ sensible instances for Prelude types, but nothing
+ more. Other modules containing types for which an instance
+ for the class in question makes sense contain the code for
+ the instance itself.</para>
+ </listitem>
+
+ <listitem>
+ <para>Record-like C bit fields or structs have a
+ record-like interface, i.e. pure getting and setting of
+ fields. (<emphasis>TODO</emphasis>: Clarify a little
+ bit. Add examples.)</para>
+ </listitem>
+
+ <listitem>
+ <para>Although the possibility of partial application
+ suggests the type
+
+<literal><replaceable>attr</replaceable> -> <replaceable>object</replaceable> -> <replaceable>object</replaceable></literal>
+
+ for functions setting an attribute or value, infix notation
+ with backquotes implies
+
+<literal><replaceable>object</replaceable> -> <replaceable>attr</replaceable> -> <replaceable>object</replaceable></literal>.
+
+ (<emphasis>TODO</emphasis>: Add Examples.)</para>
+ </listitem>
+
+ <listitem>
+ <para>Conditional interfaces: a library interface should
+ vary between versions of the library only, not between
+ platforms or Haskell implementations. Such differences may
+ be visible at the module level only, so for example module
+ <literal>System.Win32</literal> would be available on Win32
+ systems only, and <literal>GHC.Exts</literal> would only be
+ available when compiling with GHC.</para>
+ </listitem>
+ </itemizedlist>
+ </sect2>
+
+ </sect1>
+
+ <sect1>
+ <title>Changes to standard Haskell 98 libraries</title>
+
+ <para>Some changes have been made to the standard Haskell 98
+ libraries in the new library scheme, both in the names of the
+ modules themselves and in their exported interfaces. Below is a
+ summary of those changes - at this time, the new libraries are
+ marked as provisional and are maintained by
+ <email>libraries@haskell.org</email>, so changes in the interfaces
+ are all up for discussion.</para>
+
+<screen>
+modules with interface changes
+------------------------------
+
+Array -> Data.Array
+ added instance Typeable (Array ix a)
+
+Char -> Data.Char
+ no interface changes (should have instance Typeable?)
+
+Complex -> Data.Complex
+ added instance Typeable (Complex a)
+
+IO -> System.IO
+ added
+ hPutBuf :: Handle -> Ptr a -> Int -> IO ()
+ hGetBuf :: Handle -> Ptr a -> Int -> IO Int
+ fixIO :: (a -> IO a) -> IO a
+ hSetEcho :: Handle -> Bool -> IO ()
+ hGetEcho :: Handle -> IO Bool
+ hIsTerminalDevice :: Handle -> IO Bool
+
+List -> Data.List
+ exports [](..)
+
+System -> System.Exit, System.Environment, System.Cmd
+ split into three modules
+
+just renamed, no interface changes:
+-----------------------------------
+
+CPUTTime -> System.CPUTime
+Directory -> System.IO.Directory
+Ix -> Data.Ix
+Locale -> System.Locale
+Maybe -> Data.Maybe
+Monad -> Data.Monad
+Numeric -> Numeric
+Random -> System.Random
+Ratio -> Data.Ratio
+Time -> System.Time
+</screen>
+ </sect1>
+ <index/>
+</article>
projects / ghc-hetmet.git / blobdiff