doc/libraries.sgml

   1 <!DOCTYPE ARTICLE PUBLIC "-//OASIS//DTD DocBook V3.1//EN">
   2
   3 <article id="libraries">
   4   <artheader>
   5     <title>Haskell Libraries</title>
   6     <orgname>The Haskell Libraries Mailing List</orgname>
   7     <address><email>libraries@haskell.org</email></address>
   8   </artheader>
   9
  10   <sect1 id="introduction">
  11     <title>Introduction</title>
  12
  13     <para>This document consistutes a proposal for an extension to the
  14     <ulink url="http://www.haskell.org/onlinereport/">Haskell
  15     98</ulink> language.  The proposal has several parts: </para>
  16
  17     <itemizedlist>
  18       <listitem>
  19         <para>A modest language extension to Haskell 98 that adds the
  20         character <quote>.</quote> to the lexical syntax for a module
  21         name, allowing a hierarchical module namespace where a module
  22         name is a sequence of components separated by periods.  The
  23         extension is described in <xref
  24         linkend="language-extension">.</para>
  25       </listitem>
  26       <listitem>
  27         <para>An allocation of the new module namespace to existing
  28         and non-existent libraries, people, organisations, and local
  29         use.</para>
  30       </listitem>
  31       <listitem>
  32         <para>A policy and procedure for allocating new parts of the
  33         namespace.</para>
  34       </listitem>
  35       <listitem>
  36         <para>A set of libraries which are under the control of the
  37         community, have reference implementations kept in a standard
  38         place, and conform to a set of guidelines and policies set out
  39         in this document.  We shall call this set of libraries the
  40         <firstterm>core libraries</firstterm>.</para>
  41       </listitem>
  42     </itemizedlist>
  43
  44     <para>In addition, this document also describes:</para>
  45
  46     <itemizedlist>
  47       <listitem>
  48         <para>Guidelines and conventions for organising the
  49         hierarchy.</para>
  50       </listitem>
  51       <listitem>
  52         <para>Our policy with respect to the design and evolution of
  53         library APIs, versioning of library APIs, and maintenance of
  54         the reference implementation.</para>
  55       </listitem>
  56       <listitem>
  57         <para>A set of conventions for coding style and portability
  58         within the core libraries.</para>
  59       </listitem>
  60     </itemizedlist>
  61   </sect1>
  62
  63   <sect1 id="contributing">
  64     <title>How to contribute</title>
  65
  66     <para>This project is driven by the Haskell community, so
  67     contributions of all kinds are welcome.  The first step is to join
  68     the <ulink
  69     url="http://www.haskell.org/mailman/listinfo/libraries">Haskell
  70     libraries mailing list</ulink>, and maybe <ulink
  71     url="http://www.haskell.org/pipermail/libraries/">browse the list
  72     archives</ulink>.  Some of the ways you can contribute are:</para>
  73
  74     <itemizedlist>
  75       <listitem>
  76         <para>By donating code: for libraries in the core set which
  77         don't yet have a reference implementation, or for new
  78         contributions to the core set, code is always welcome.  Code
  79         that conforms to the style guidelines (which aren't very
  80         strict, see <xref linkend="conventions">) and comes with
  81         documentation (<xref linkend="documentation">) and a test
  82         suite (<xref linkend="testing">) is better, but these aren't
  83         essential.  As a library progresses through the stability
  84         scale (<xref linkend="stability">) these things become more
  85         important, but for an experimental library we're not going to
  86         worry too much about this stuff.</para>
  87       </listitem>
  88       <listitem>
  89         <para>By porting code for an existing library to a new
  90         compiler or architecture.  A library is classed as portable if
  91         it should be available regardless of which compiler/platform
  92         combination you're using; however, many libraries are
  93         non-portable for one reason or another (see <xref
  94         linkend="portability">, and broadening the scope of these
  95         libraries is always welcome.</para>
  96       </listitem>
  97       <listitem>
  98         <para>Become a library maintainer: if you have a particular
  99         interest in and/or knowledge about a certain library, and have
 100         the time to spare, and the library in question doesn't already
 101         have a maintainer, then you may be a suitable maintainer for
 102         the library.  The responsibilities of library maintainers are
 103         given in <xref linkend="maintainership">. </para>
 104       </listitem>
 105       <listitem>
 106         <para>Participating in the design process for new libraries,
 107         and suggesting improvements to existing libraries.  Everyone
 108         on the <ulink
 109         url="http://www.haskell.org/mailman/listinfo/libraries">Haskell
 110         libraries mailing list</ulink> is invited to
 111         participate in the design process, so get involved!</para>
 112       </listitem>
 113     </itemizedlist>
 114   </sect1>
 115
 116   <sect1 id="language-extension">
 117     <title>The language extension</title>
 118
 119     <para>The key concept here is to map the module namespace into a
 120     hierarchical directory-like structure. We propose using the dot as
 121     a separator, analogous to Java's usage for namespaces.</para>
 122
 123     <para>For most compilers and interpreters, this extended module
 124     namespace maps directly to a directory/file structure in which the
 125     modules are stored. Storing unrelated modules in separate
 126     directories (and related modules in the same directory) is a
 127     useful and common practice when engineering large systems.</para>
 128
 129     <para>(But note that, just as Haskell'98 does not insist that
 130     modules live in files of the same name, this proposal does not
 131     insist on it either. However, we expect most tools to use the
 132     close correspondance to their advantage.)</para>
 133
 134     <para>There are several issues arising from this proposal
 135     proposal here. </para>
 136
 137     <para>This is a surface change to the module naming convention. It
 138     does not introduce nested definition of modules.  The syntax we
 139     propose (a dot separator) is familiar from other languages such as
 140     Java, but could in principle be something else, for instance a
 141     prime <literal>'</literal>, underscore <literal>_</literal> or
 142     centred dot <literal>&cdot;</literal> or something different
 143     again.  Of the choices of separator, dot requires a change to the
 144     Haskell'98 lexical syntax, allowing</para>
 145
 146 <programlisting>
 147    modid   -> qconid
 148    qconid  -> [modid .] conid
 149 </programlisting>
 150
 151     <para>where currently the syntax is</para>
 152
 153 <programlisting>
 154    modid   ->  conid
 155    qconid  -> [modid .] conid
 156 </programlisting>
 157
 158     <para>Note that the new syntax is recursive, a
 159     <literal>modid</literal> may contain multiple components separated
 160     by dots, where the final component is a <literal>conid</literal>.</para>
 161
 162     <para>A consequence of using the dot as the module namespace
 163     separator is that it steals one extremely rare construction from
 164     Haskell'98:</para>
 165
 166 <programlisting>
 167    A.B.C.D
 168 </programlisting>
 169
 170     <para>in Haskell'98 means the composition of constructor D from
 171     module C, with constructor B from module A:</para>
 172
 173 <programlisting>
 174    (.)  A.B  C.D
 175 </programlisting>
 176
 177     <para>No-one so far thinks this is any great loss, and if you
 178     really want to say the latter, you still can by simply inserting
 179     spaces:</para>
 180
 181 <programlisting>
 182    A.B . C.D
 183 </programlisting>
 184
 185     <sect2>
 186       <title>A possible extension</title>
 187
 188       <para>The use of qualified imports has become more verbose: for
 189       instance</para>
 190
 191 <programlisting>
 192    import qualified XmlParse
 193                       ... XmlParse.element f ...
 194 </programlisting>
 195
 196       <para>becomes</para>
 197
 198 <programlisting>
 199    import qualified Text.Xml.Parse
 200                       ... Text.Xml.Parse.element f ...
 201 </programlisting>
 202
 203       <para>It is usually more convenient to make use of Haskell's
 204       <literal>as</literal> keyword to shorten qualified identifiers:</para>
 205
 206 <programlisting>
 207    import qualified Text.Xml.Parse as Parse
 208                       ... Parse.element f ...
 209 </programlisting>
 210
 211       <para>A possible extension to the proposal is to make this use
 212       of <literal>as</literal> implicit, unless overridden by the
 213       programmer with her own <literal>as</literal> clause. The
 214       implicit <literal>as</literal> clause always uses the final
 215       subdivision of the module name. So for instance, either the
 216       fully-qualified or abbreviated-qualified names</para>
 217
 218 <programlisting>
 219    Text.Xml.Parse.element
 220             Parse.element
 221 </programlisting>
 222
 223       <para>would be accepted and have the same referent, but a
 224       partial qualification like</para>
 225
 226 <programlisting>
 227    Xml.Parse.element
 228 </programlisting>
 229
 230       <para>would not be accepted.</para>
 231     </sect2>
 232
 233     <sect2>
 234       <title>Renaming subtrees</title>
 235
 236       <para>Various proposals have been made to allow you to rename a
 237       whole subtree.  This may occasionally be convenient: for example
 238       suppose there are several libraries under
 239       <literal>Org.Com.Microsoft</literal> that I need to import, it
 240       would be easier to rename this subtree to just
 241       <literal>Microsoft</literal> for use in future import
 242       declarations.  For example:</para>
 243
 244 <programlisting>
 245    import Org.Com.Microsoft.* as Microsoft.*
 246    import Microsoft.Foo
 247    import Microsoft.Bar
 248    ...
 249 </programlisting>
 250
 251       <para>The exact syntax of the renaming declaration is up for
 252       debate (as is whether we need it at all), please send
 253       suggestions to <email>libraries@haskell.org</email>.</para>
 254     </sect2>
 255
 256   </sect1>
 257
 258   <sect1 id="layout">
 259     <title>The hierarchy layout</title>
 260
 261     <para>We first classify each node in the hierarchy according to
 262     one of the following terms:</para>
 263
 264     <variablelist>
 265       <varlistentry>
 266         <term>Allocated</term>
 267         <listitem>
 268           <para>Nodes in the hierarchy can be allocated to a library
 269           (whether the library actually exists or not).  The currently
 270           allocated nodes are specified in <xref
 271           linkend="hierarchy">.</para>
 272         </listitem>
 273       </varlistentry>
 274
 275       <varlistentry>
 276         <term>User</term>
 277         <listitem>
 278           <para>The <literal>User</literal> hierarchy is reserved for
 279           users: a user may always use the portion of the hierarchy
 280           which is formed from his/her email address as follows:
 281           replace the <literal>@</literal> by a <literal>.</literal>,
 282           reverse the order of the components, capitalise the first
 283           letter of each component, and prepend
 284           <literal>User.</literal>.  For example,
 285           <literal>simonmar@microsoft.com</literal> becomes
 286           <literal>User.Com.Microsoft.Simonmar</literal>.</para>
 287         </listitem>
 288       </varlistentry>
 289
 290       <varlistentry>
 291         <term>Organisation</term>
 292         <listitem>
 293           <para>The <literal>Org</literal> hierarchy is reserved for
 294           organisations.  Any organisation with a DNS domain name owns
 295           a unique space in the hierarchy formed by reversing the
 296           components of the domain, capitalising the first character
 297           of each component, and prepending <literal>Org.</literal>.
 298           <emphasis>ToDo: the Org name isn't great, especially when
 299           the domain name also ends with Org (eg. Org.Org.Haskell?).
 300           Contrib has also been suggested.</emphasis></para>
 301         </listitem>
 302       </varlistentry>
 303
 304       <varlistentry>
 305         <term>Local</term>
 306         <listitem>
 307           <para>The <literal>Local</literal> hierarchy is reserved for
 308           libraries which are local to the current site.  Libraries
 309           which are to be distributed outside the current site should
 310           not be placed in the <literal>Local</literal>
 311           hierarchy.</para>
 312         </listitem>
 313       </varlistentry>
 314
 315       <varlistentry>
 316         <term>Top-level</term>
 317         <listitem>
 318           <para>All top-level names (i.e. module names that don't
 319           contain a <quote><literal>.</literal></quote>) that are
 320           otherwise unallocated, are available for use by the program.
 321           Note that for compabibility with Haskell 98, some modules in
 322           this namespace are reserved
 323           (eg. <literal>Directory</literal>, <literal>IO</literal>,
 324           <literal>Time</literal> etc.).</para>
 325         </listitem>
 326       </varlistentry>
 327
 328       <varlistentry>
 329         <term>Unallocated</term>
 330         <listitem>
 331           <para>Any node which doesn't belong to any of the above
 332           categories is currently unallocated, and is not available
 333           for use.</para>
 334         </listitem>
 335       </varlistentry>
 336     </variablelist>
 337
 338     <para>A node in the hierarchy may be both a specific library and a
 339     parent node for a number of child nodes.  For example,
 340     <literal>Foreign</literal> is a library, and so is
 341     <literal>Foreign.Ptr</literal>.</para>
 342
 343     <sect2 id="hierarchy-design-guidelines">
 344       <title>Hierarchy design guidelines</title>
 345       <para>Apart from the User, Local and Organisation top-level
 346       categories, the rest of the hierarchy is organised with a single
 347       principle in mind:</para>
 348
 349       <blockquote>
 350         <para>Modules are grouped by
 351         <emphasis>functionality</emphasis>, since this is the single
 352         property that is most helpful for a user of the library - we
 353         want users to be able to find out where to obtain
 354         functionality easily, and to easily find all the modules that
 355         provide relevant functionality.</para>
 356
 357         <para>So, if two modules provide similar functionality, or
 358         alternative interfaces to the same functionality, then they
 359         should be children of the same node in the hierarchy.  Modules
 360         are never grouped by standards compliance, portability,
 361         stability, or any other property.</para>
 362       </blockquote>
 363     </sect2>
 364
 365     <sect2 id="module-naming-convention">
 366       <title>Module Naming Conventions</title>
 367
 368       <itemizedlist>
 369         <listitem>
 370           <para>A module defining a data type or type class
 371           <replaceable>X</replaceable> has itself the name
 372           <replaceable>X</replaceable>, e.g.
 373           <literal>StablePtr</literal>.</para>
 374         </listitem>
 375
 376         <listitem>
 377           <para>A module which re-exports the modules in a subtree of
 378           the hierarchy has the same name as the root of that subtree,
 379           eg. <literal>Foreign</literal> re-exports
 380           <literal>Foreign.Ptr</literal>,
 381           <literal>Foreign.Marshal.Utils</literal> etc.</para>
 382         </listitem>
 383
 384         <listitem>
 385           <para>If a subtree of the hierarchy contains several modules
 386           which provide similar functionality (eg. there are several
 387           pretty-printing libraries under
 388           <literal>Text.PrettyPrinter</literal>), then the module at
 389           the root of the subtree generally re-exports just
 390           <emphasis>one</emphasis> of the modules in the subtree
 391           (possibly the most popular or commonly-used
 392           alternative).</para>
 393         </listitem>
 394
 395         <listitem>
 396           <para>In Haskell you sometimes publish
 397           <emphasis>two</emphasis> interfaces to your libraries; one
 398           for users, and one for library writers or advanced users who
 399           might want to extend things.  Typically the advanced users
 400           need to be able to see past certain abstractions.</para>
 401
 402           <para>The current proposal is for a module named
 403           <literal>M</literal>, the <quote>advanced</quote> version
 404           would be named <literal>M.Internals</literal>. eg.</para>
 405
 406 <programlisting>
 407 import Text.HTML           -- The library
 408 import Text.HTML.Internals -- The non-abstract library
 409 </programlisting>
 410         </listitem>
 411
 412         <listitem>
 413           <para>Acronyms are fully capitalised in a module name.
 414           eg. <literal>HTML</literal>, <literal>URI</literal>,
 415           <literal>CGI</literal>, etc.  Exceptions may be made for
 416           acronyms which have an existing well-established alternative
 417           capitalisation, or acronyms which are also valid words, and
 418           are more often used as such.</para>
 419         </listitem>
 420
 421         <listitem>
 422           <para>A module name should be made plural only if the module
 423           actually defines multiple entities of a particular kind:
 424           eg. <literal>Foreign.C.Types</literal>.  Most module names
 425           which define a type or class will follow the name of the
 426           type or class, so whether to pluralize is not an
 427           issue.</para>
 428         </listitem>
 429       </itemizedlist>
 430     </sect2>
 431
 432     <sect2 id="hierarchy">
 433       <title>The hierarchy</title>
 434
 435       <para>The currently allocated top-level names are:</para>
 436
 437       <variablelist>
 438         <varlistentry>
 439           <term><literal>Prelude</literal></term>
 440           <listitem>
 441             <para>Haskell98 Prelude (mostly just re-exports other
 442             parts of the tree).</para>
 443           </listitem>
 444         </varlistentry>
 445
 446         <varlistentry>
 447           <term><literal>Control</literal></term>
 448           <listitem>
 449             <para> Libraries which provide functions, types or classes
 450             whose purpose is primarily to express control
 451             structure.</para>
 452           </listitem>
 453         </varlistentry>
 454
 455         <varlistentry>
 456           <term><literal>Data</literal></term>
 457           <listitem>
 458             <para>Libraries which provide data types, operations over
 459             data types, or type classes, except for libraries for
 460             which one of the other more specific categories is
 461             appropriate.</para>
 462           </listitem>
 463         </varlistentry>
 464
 465         <varlistentry>
 466           <term><literal>Database</literal></term>
 467           <listitem>
 468             <para>Libraries for providing access to or operations for
 469             building databases.</para>
 470           </listitem>
 471         </varlistentry>
 472
 473         <varlistentry>
 474           <term><literal>Debug</literal></term>
 475           <listitem>
 476             <para>Support for debugging Haskell programs.</para>
 477           </listitem>
 478         </varlistentry>
 479
 480         <varlistentry>
 481           <term><literal>Edison</literal></term>
 482           <listitem>
 483             <para>The Edison data structure library.</para>
 484           </listitem>
 485         </varlistentry>
 486
 487         <varlistentry>
 488           <term><literal>FileFormat</literal></term>
 489           <listitem>
 490             <para>Support for reading and/or writing various file
 491             formats (except: programming language source code which
 492             lives in <literal>Language</literal>, database formats
 493             which live in <literal>Database</literal>, and textual
 494             file formats which are catered for in
 495             <literal>Text</literal>).</para>
 496           </listitem>
 497         </varlistentry>
 498
 499         <varlistentry>
 500           <term><literal>Foreign</literal></term>
 501           <listitem>
 502             <para>Interaction with code written in a foreign
 503             programming language.</para>
 504           </listitem>
 505         </varlistentry>
 506
 507         <varlistentry>
 508           <term><literal>Graphics</literal></term>
 509           <listitem>
 510             <para>Libraries for producing graphics or providing
 511             graphical user interfaces.</para>
 512           </listitem>
 513         </varlistentry>
 514
 515         <varlistentry>
 516           <term><literal>Language</literal></term>
 517           <listitem>
 518             <para>Libraries for operating on or generating source code
 519             in various programming languages, including parsers,
 520             pretty printers, abstract syntax definitions etc.</para>
 521           </listitem>
 522         </varlistentry>
 523
 524         <varlistentry>
 525           <term><literal>Local</literal></term>
 526           <listitem>
 527             <para>Available for site-local use.</para>
 528           </listitem>
 529         </varlistentry>
 530
 531         <varlistentry>
 532           <term><literal>Numeric</literal></term>
 533           <listitem>
 534             <para>Functions and classes which provide operations over
 535             numeric data.</para>
 536           </listitem>
 537         </varlistentry>
 538
 539         <varlistentry>
 540           <term><literal>Network</literal></term>
 541           <listitem>
 542             <para>Libraries for communicating over a network,
 543             including implementations of network protocols.</para>
 544           </listitem>
 545         </varlistentry>
 546
 547         <varlistentry>
 548           <term><literal>Org</literal></term>
 549           <listitem>
 550             <para>Allocated to organisations on a domain-name
 551             basis (see <xref linkend="layout">).</para>
 552           </listitem>
 553         </varlistentry>
 554
 555         <varlistentry>
 556           <term><literal>System</literal></term>
 557           <listitem>
 558             <para>Libraries for communication with the system on which
 559             the Haskell program is running (including the runtime
 560             system).</para>
 561           </listitem>
 562         </varlistentry>
 563
 564         <varlistentry>
 565           <term><literal>Text</literal></term>
 566           <listitem>
 567             <para>Libraries for parsing and generating data in a
 568             textual format (including structured textual formats such
 569             as XML, HTML, but not including programming language
 570             source, which lives in Language).</para>
 571           </listitem>
 572         </varlistentry>
 573
 574         <varlistentry>
 575           <term><literal>GHC</literal></term>
 576           <listitem>
 577             <para>Libraries specific to the GHC/GHCi system.</para>
 578           </listitem>
 579         </varlistentry>
 580
 581         <varlistentry>
 582           <term><literal>Nhc</literal></term>
 583           <listitem>
 584             <para>Libraries specific to the Nhc compiler.</para>
 585           </listitem>
 586         </varlistentry>
 587
 588         <varlistentry>
 589           <term><literal>Hugs</literal></term>
 590           <listitem>
 591             <para>Libraries specific to the Hugs system.</para>
 592           </listitem>
 593         </varlistentry>
 594
 595         <varlistentry>
 596           <term><literal>User</literal></term>
 597           <listitem>
 598             <para>Allocated to individual users, using email
 599             addresses (see <xref linkend="layout">).</para>
 600           </listitem>
 601         </varlistentry>
 602       </variablelist>
 603     </sect2>
 604   </sect1>
 605
 606   <sect1 id="licensing">
 607     <title>Licensing</title>
 608
 609     <para>Following some discussion on the mailing list related to how
 610     we should license the libraries, the viewpoint that was least
 611     offensive to all involved seems to be the following:</para>
 612
 613     <para>We wish to accomodate source code from different
 614     contributors, and with different licenses.  However, a library of
 615     modules where each module is released under a different license,
 616     and where the dependencies between modules aren't clear, isn't
 617     workable (it's too hard for a user of the library to tell whether
 618     they're violating the terms of the each license or not).</para>
 619
 620     <para>So the solution is as follows: code under different licenses
 621     will be clearly separate in the repository (i.e. in separate
 622     subdirectories), and compilers are expected to present packages of
 623     modules where all modules in a package fall under the same
 624     license, and where the dependencies between packages are
 625     clear.</para>
 626
 627     <para>It was decided that certain essential functionality should
 628     be available under a BSD style license.  Hence, the BSD part of
 629     the repository will contain implementations of at least the
 630     following modules: <literal>Prelude</literal>,
 631     <literal>Foreign</literal>, <emphasis>ToDo: what
 632     else?</emphasis>.</para>
 633
 634     <para><emphasis>ToDo: include a prototype BSD license
 635     here</emphasis>.</para>
 636   </sect1>
 637
 638   <sect1 id="versioning">
 639     <title>Versioning</title>
 640     <para></para>
 641   </sect1>
 642
 643   <sect1 id="stability">
 644     <title>Library Stability</title>
 645
 646     <para>The stability of a library relates primarily to its API.
 647     Stability provides an indication of how often the API is likely to
 648     change (or whether it may even go away entirely).</para>
 649
 650     <para>The stability scale is also a measure of how strictly the
 651     conventions in this document are applied to the library: an
 652     experimental library isn't subject to any restrictions regarding
 653     coding style and documentation, but a stable library is expected
 654     to adhere to the guidelines, and come with full documentation and
 655     tests.</para>
 656
 657     <para>To help with the stability issue, library maintainers are
 658     allowed to mark functions, types or classes as
 659     <firstterm>deprecated</firstterm><footnote><para>Compilers may have
 660     extra support for warning about the use of a deprecated feature, for
 661     example GHC's <literal>DEPRECATED</literal> pragma.</para>
 662       </footnote>, which means simply that the
 663     feature will be removed at a later date.  Just how long it will
 664     stick around for depends on the stability category of the library
 665     (see below).  A feature is marked as deprecated in the
 666     documentation for the library, and optionally in an
 667     implementation-dependent way which enables the system to warn
 668     about the use of deprecated features.</para>
 669
 670     <para>The current stability categories are:</para>
 671
 672     <variablelist>
 673       <varlistentry>
 674         <term><firstterm>experimental</firstterm></term>
 675         <listitem>
 676           <para>An experimental library is unrestricted in terms of
 677           API changes: the API may change between minor revisions and
 678           there is no requirement to retain old interfaces for
 679           compatibility.  Documentation and tests aren't required for
 680           an experimental library.</para>
 681         </listitem>
 682       </varlistentry>
 683       <varlistentry>
 684         <term><firstterm>provisional</firstterm></term>
 685         <listitem>
 686           <para>A provisional library is moving towards stability, and
 687           the rate of change of the API is slower.  API changes
 688           between minor revisions must be accompanied by deprecated
 689           versions of the old features where possible.  API changes
 690           between major versions are unrestricted.  The library should
 691           come with at least rudimentary documentation.</para>
 692         </listitem>
 693       </varlistentry>
 694       <varlistentry>
 695         <term><firstterm>stable</firstterm></term>
 696         <listitem>
 697           <para>A stable library has an essentially fixed API.
 698           Additions to the API may be made for a minor release,
 699           deprecated features must be retained for at least one major
 700           revision, and small changes only may be made to the existing
 701           API semantics for a major revision.  A stable library is
 702           expected to include full documentation and tests.</para>
 703         </listitem>
 704       </varlistentry>
 705     </variablelist>
 706
 707   </sect1>
 708
 709   <sect1 id="portability">
 710     <title>Portability Considerations</title>
 711
 712     <para>The portability status of a library affects under which
 713     platforms and compilers the library will be available on.  Haskell
 714     implementations are expected to provide all of the portable core
 715     libraries, and those non-portable core libraries which are
 716     appropriate for that particular platform/compiler
 717     implementation.</para>
 718
 719     <para>The precise meaning of the terms portable and non-portable
 720     for our purposes are given below:</para>
 721
 722     <variablelist>
 723       <varlistentry>
 724         <term><firstterm>Portable</firstterm></term>
 725         <listitem>
 726           <para>A portable library may use only Haskell 98 features
 727           plus approved extensions, and may not use any
 728           platform-specific features.  It may make use of other
 729           portable libraries only.</para>
 730         </listitem>
 731       </varlistentry>
 732       <varlistentry>
 733         <term><firstterm>Non-portable</firstterm></term>
 734         <listitem>
 735           <para>A non-portable library may be non-portable for one or
 736           more of the following reasons:</para>
 737           <variablelist>
 738             <varlistentry>
 739               <term><firstterm>Requires extensions</firstterm></term>
 740               <listitem>
 741                 <para>A library which uses non-approved language
 742                 extensions.</para>
 743               </listitem>
 744             </varlistentry>
 745             <varlistentry>
 746               <term><firstterm>Requires nonportable libraries</firstterm></term>
 747               <listitem>
 748                 <para>A library which depends (directly or indirectly)
 749                 on other non-portable libraries.</para>
 750               </listitem>
 751             </varlistentry>
 752             <varlistentry>
 753               <term><firstterm>OS-specific</firstterm></term>
 754               <term><firstterm>Platform-specific</firstterm></term>
 755               <listitem>
 756                 <para>A library which depends on features or APIs
 757                 particular to a certain OS or platform is non-portable
 758                 for that reason.</para>
 759               </listitem>
 760             </varlistentry>
 761           </variablelist>
 762         </listitem>
 763       </varlistentry>
 764     </variablelist>
 765
 766     <sect2>
 767       <title>Approved Extensions</title>
 768
 769       <para>Very few of the core libraries can be implemented using
 770       pure Haskell 98.  For this reason, we decided to raise the
 771       baseline for portable libraries to include a few common
 772       extensions; the following langauge extensions can be
 773       <emphasis>assumed</emphasis> to be present when writing
 774       libraries:</para>
 775
 776       <itemizedlist>
 777         <listitem>
 778           <para>The <ulink
 779           url="http://haskell.org/ghc/docs/latest/set/ffi.html">Foreign
 780           Function Interface</ulink>.</para>
 781         </listitem>
 782         <listitem>
 783           <para>Mutable variables
 784           (<literal>Data.IORef</literal>).</para>
 785         </listitem>
 786         <listitem>
 787           <para>Unsafe IO monad operations
 788           (<literal>System.IO.Unsafe</literal>).</para>
 789         </listitem>
 790         <listitem>
 791           <para>Packed strings
 792           (<literal>Data.PackedString</literal>).</para>
 793         </listitem>
 794       </itemizedlist>
 795
 796       <para>Extensions which we'd like to be standard, but aren't
 797       currently implemented by one or more of the target
 798       compilers:</para>
 799
 800       <itemizedlist>
 801         <listitem>
 802           <para>Bit operations (<literal>Data.Bits</literal>).</para>
 803         </listitem>
 804         <listitem>
 805           <para>Exceptions (synchronous only), defined by the
 806           <literal>Control.Exception</literal> interface.</para>
 807         </listitem>
 808         <listitem>
 809           <para>The ST monad, defined by
 810           <literal>Control.Monad.ST</literal>, and the associated
 811           <literal>Data.Array.ST</literal> and
 812           <literal>Data.STRef</literal> libraries.  ST requires a
 813           small typechecker extension for the <literal>runST</literal>
 814           function.</para>
 815         </listitem>
 816         <listitem>
 817           <para>Concurrent Haskell (pre-emptive multitasking
 818           optional).  GHC and Hugs implement this, but Nhc currently
 819           does not.</para>
 820         </listitem>
 821       </itemizedlist>
 822
 823       <para>The following extensions are not likely to become part of
 824       the baseline, but are nevertheless used by one or more libraries
 825       in the core set (which are thus designated non-portable):</para>
 826
 827       <itemizedlist>
 828         <listitem>
 829           <para>Multi-parameter type classes.</para>
 830         </listitem>
 831         <listitem>
 832           <para>Local unversal and existential quantification.</para>
 833         </listitem>
 834         <listitem>
 835           <para>Concurrent Haskell with pre-emptive multitasking.</para>
 836         </listitem>
 837         <listitem>
 838           <para>Asynchronous exceptions.</para>
 839         </listitem>
 840         <listitem>
 841           <para>Stable Names.</para>
 842         </listitem>
 843         <listitem>
 844           <para>Weak Pointers.</para>
 845         </listitem>
 846       </itemizedlist>
 847
 848       <para>Other extensions are supported by a single compiler only,
 849       and can be accessed by libraries under the top level hierarchy
 850       for that compiler,
 851       eg. <literal>GHC.UnboxedTypes</literal>.</para>
 852     </sect2>
 853   </sect1>
 854
 855   <sect1 id="maintainership">
 856     <title>Library Maintainers</title>
 857
 858     <para>This is a collaborative project, so we like to devolve
 859     control of the design and implementation of libraries to those
 860     with an interest or appropriate expertise (or maybe just the
 861     time!).  A maintainer isn't necessarily a single person - for
 862     example, the listed maintainer for most of the core libraries is
 863     <email>libraries@haskell.org</email>, indicating that the library
 864     is under the control of the community as a whole.  The maintainer
 865     for the <literal>Foreign</literal> hierarchy is
 866     <email>ffi@haskell.org</email>, the mailing list for discussion of
 867     the Haskell FFI standard.</para>
 868
 869     <para>The responsibilities of a library maintainer include:</para>
 870
 871     <itemizedlist>
 872       <listitem>
 873         <para>Most importantly: act as a single point of contact for
 874         issues relating to the library API and its
 875         implementation.</para>
 876       </listitem>
 877       <listitem>
 878         <para>Manage any discussion related to the library (which can
 879         take place on <email>libraries.haskell.org</email> if
 880         necessary), and summarise the results.  Make final decisions,
 881         and implement them.</para>
 882       </listitem>
 883       <listitem>
 884         <para>Maintain the implementation, including: fixing bugs,
 885         updating to keep up with changes in other libraries, porting
 886         to new compilers/platforms, and integrating code from other
 887         contributors.  The maintainer is expected to be the only
 888         person/group to make functional changes to the source code
 889         (non-functional or trivial changes don't count).</para>
 890       </listitem>
 891       <listitem>
 892         <para>Maintain/write the documentation and tests.</para>
 893       </listitem>
 894       <listitem>
 895         <para>If you can't maintain the library any more for whatever
 896         reason, tell <email>libraries@haskell.org</email> and we'll
 897         revert the maintainer status of the library to the
 898         default.</para>
 899       </listitem>
 900     </itemizedlist>
 901
 902     <sect2 id="core-team">
 903       <title>The Core Team</title>
 904
 905       <para>The core team is responsible for making final decisions
 906       about the project as a whole and resolving disputes where
 907       necessary.  We expect that needing to invoke the core team will
 908       be a rare occurrence.</para>
 909
 910       <para>The core team is also responsible for approving
 911       maintainership requests.</para>
 912
 913       <para>Currently, the core team consists of one person from each
 914       of the compiler camps, and these are also the people that will
 915       primarily be maintaining the library framework for their
 916       respective compiler projects:</para>
 917
 918       <itemizedlist>
 919         <listitem>
 920           <para>Simon Marlow
 921           <email>simonmar@microsoft.com</email> (GHC representative)</para>
 922         </listitem>
 923         <listitem>
 924           <para>Malcolm Wallace
 925           <email>Malcolm.Wallace@cs.york.ac.uk</email> (Nhc representative)</para>
 926         </listitem>
 927         <listitem>
 928           <para>Andy Gill
 929           <email>andy@galconn.com</email> (Hugs representative)</para>
 930         </listitem>
 931       </itemizedlist>
 932     </sect2>
 933
 934   </sect1>
 935
 936   <sect1 id="documentation">
 937     <title>Documentation</title>
 938     <para></para>
 939   </sect1>
 940
 941   <sect1 id="testing">
 942     <title>Testing</title>
 943     <para></para>
 944   </sect1>
 945
 946   <sect1 id="Migration-path">
 947     <title>Migration path</title>
 948
 949     <para>How compatible will a compiler using the new libraries be
 950     with code written for Haskell 98 or older library systems (such as
 951     the <literal>hslibs</literal> suite and GHC's package system), and
 952     for how long will compatibility be maintained?</para>
 953
 954     <para>Our current plan for GHC is as follows: by default, with the
 955     <option>-fglasgow-exts</option> flag, you'll get access to the
 956     core libraries.  Compatibility with Haskell 98 code will be
 957     maintained using a separate package of wrappers presenting
 958     interfaces for the Haskell 98 libraries (<literal>IO</literal>,
 959     <literal>Ratio</literal>, <literal>Directory</literal>, etc.).
 960     The Haskell 98 compatibility package will be enabled by default,
 961     but we plan to add an option to disable it if necessary.  For code
 962     that uses <literal>-package lang</literal>, we could also provide
 963     a compatibility wrapper package (so <literal>-package
 964     lang</literal> will continue to work as before and present the
 965     same library interfaces), but this may prove too much work to
 966     maintain - we haven't decided whether to do this or not.  It is
 967     unlikely that compatibility wrappers for any of the other
 968     <literal>hslibs</literal> packages will be provided.</para>
 969   </sect1>
 970
 971   <sect1 id="conventions">
 972     <title>Programming Conventions</title>
 973
 974     <sect2 id="module-header">
 975       <title>Standard Module Header</title> <para>The following module
 976       header will be used for all core libraries, and we recommend
 977       using it for library source code in general:</para>
 978
 979 <programlisting>
 980 -----------------------------------------------------------------------------
 981 --
 982 -- Module      :  <replaceable>module</replaceable>
 983 -- Copyright   :  (c) <replaceable>author</replaceable> <replaceable>year</replaceable>
 984 -- License     :  <replaceable>license</replaceable>
 985 --
 986 -- Maintainer  :  libraries@haskell.org | <replaceable>email-address</replaceable>
 987 -- Stability   :  experimental | provisional | stable
 988 -- Portability :  portable | non-portable (<replaceable>reason(s)</replaceable>)
 989 --
 990 -- $Id: libraries.sgml,v 1.5 2001/08/30 13:36:00 simonmar Exp $
 991 --
 992 -- <replaceable>Description</replaceable>
 993 -----------------------------------------------------------------------------
 994 </programlisting>
 995
 996       <para>where:</para>
 997
 998       <variablelist>
 999         <varlistentry>
1000           <term><literal>$Id: libraries.sgml,v 1.5 2001/08/30 13:36:00 simonmar Exp $</literal></term>
1001           <listitem>
1002             <para>is optional, but usually included if the module is
1003             under CVS or RCS control.</para>
1004           </listitem>
1005         </varlistentry>
1006
1007         <varlistentry>
1008           <term><replaceable>module</replaceable></term>
1009           <listitem>
1010             <para>is the fully qualified module name of the
1011             module</para>
1012           </listitem>
1013         </varlistentry>
1014
1015         <varlistentry>
1016           <term><replaceable>author</replaceable>/<replaceable>year</replaceable></term>
1017           <listitem>
1018             <para>Is the primary author and copyright holder of the
1019             module, and the year in which copyright is claimed.</para>
1020           </listitem>
1021         </varlistentry>
1022
1023         <varlistentry>
1024           <term><replaceable>license</replaceable></term>
1025           <listitem>
1026             <para>Specifies the license on the file (see <xref
1027             linkend="licensing">).</para>
1028           </listitem>
1029         </varlistentry>
1030
1031         <varlistentry>
1032           <term><replaceable>email-address</replaceable></term>
1033           <listitem>
1034             <para>The email address of the maintainer, or maintainers,
1035             of the library (see <xref linkend="maintainership">).</para>
1036           </listitem>
1037         </varlistentry>
1038
1039         <varlistentry>
1040           <term><replaceable>reason(s)</replaceable></term>
1041           <listitem>
1042             <para>The reasons for non-portability must be listed (see
1043             <xref linkend="portability">).</para>
1044           </listitem>
1045         </varlistentry>
1046
1047         <varlistentry>
1048           <term><replaceable>description</replaceable></term>
1049           <listitem>
1050             <para>A short description of the module.</para>
1051           </listitem>
1052         </varlistentry>
1053       </variablelist>
1054
1055     </sect2>
1056
1057     <sect2 id="naming-conventions">
1058       <title>Naming Conventions</title>
1059
1060       <para>These naming conventions are pulled straight from the
1061       <literal>hslibs</literal> documentation.  They were formed after
1062       lengthy discussions and are heavily based on an initial
1063       suggestion from Marcin Kowalczyk
1064       <email>qrczak@knm.org.pl</email>.</para>
1065
1066       <para>Note that the conventions are not mutually exclusive,
1067       e.g. should the function creating a set from a list of elements
1068       have the name <Literal>set</Literal> or
1069       <Literal>listToSet</Literal>?  (Alas, it currently has neither
1070       name.)</para>
1071
1072       <para> The following nomenclature is used: Pure,
1073       i.e. non-monadic functions are simply called, well,
1074       <emphasis>functions</emphasis>.  Monadic functions,
1075       i.e. functions having a type <Literal>... -&#62; m a</Literal>
1076       for some Monad <Literal>m</Literal> are called
1077       <emphasis>actions</emphasis>.</para>
1078
1079       <sect3 id="sec-library-constructor-names">
1080         <title>Constructor names</title>
1081         <indexterm><primary>Constructor names</primary></indexterm>
1082
1083         <itemizedlist>
1084           <listitem>
1085             <para>Empty values of type <replaceable>X</replaceable>
1086             have the name <Literal>empty<replaceable>X</replaceable></Literal>,
1087             e.g. <literal>emptySet</literal>.</para>
1088           </listitem>
1089
1090           <listitem>
1091             <para>Actions creating a new empty value of type
1092             <replaceable>X</replaceable> have the name
1093             <literal>newEmpty<replaceable>X</replaceable></literal>,
1094             e.g. <literal>newEmptyMVar</literal>.</para>
1095           </listitem>
1096
1097           <listitem>
1098             <para>Functions creating an arbitrary value of type
1099             <replaceable>X</replaceable> have the name
1100             <replaceable>X</replaceable> itself (with the first letter
1101             downcased),
1102             e.g. <literal>array</literal>. (<emphasis>TODO</emphasis>:
1103             This often collides with <literal>xToY</literal>
1104             convention, how should this be resolved?)
1105             </para>
1106           </listitem>
1107
1108           <listitem>
1109             <para>Actions creating new values arbitrary values of type
1110             <replaceable>X</replaceable> have the name
1111             <literal>new<replaceable>X</replaceable></literal>,
1112             e.g. <literal>newIORef</literal>.
1113             </para>
1114           </listitem>
1115         </itemizedlist>
1116       </sect3>
1117
1118     <sect3 id="sec-library-accessor-names">
1119         <title>Accessor names</title>
1120         <indexterm><primary>Accessor names</primary></indexterm>
1121
1122         <itemizedlist>
1123           <listitem>
1124             <para>Functions getting an attribute of a value or a part
1125             of it have the name of the attribute itself,
1126             e.g. <literal>length</literal>, <literal>bounds</literal>.
1127             </para>
1128           </listitem>
1129
1130           <listitem>
1131             <para> Actions accessing some kind of reference or state
1132             have the name
1133             <literal>get<replaceable>X</replaceable></literal>, where
1134             <replaceable>X</replaceable> is the type of the contents
1135             or the name of the part being accessed,
1136             e.g. <literal>getChar</literal>,
1137             <literal>getEnv</literal>. An alternative naming scheme is
1138             <literal>read<replaceable>Y</replaceable></literal>,
1139             where <replaceable>Y</replaceable> is the type of the
1140             reference or container, e.g. <literal>readIORef</literal>.
1141             </para>
1142           </listitem>
1143
1144           <listitem>
1145             <para>Functions or actions getting a value via a
1146             pointer-like type <replaceable>X</replaceable> should be
1147             named
1148             <literal>deRef<replaceable>X</replaceable></literal>,
1149             e.g. <literal>deRefStablePtr</literal>,
1150             <literal>deRefWeak</literal>.</para>
1151           </listitem>
1152         </itemizedlist>
1153       </sect3>
1154
1155       <sect3 id="sec-library-modifier-names">
1156         <title>Modifier names</title>
1157         <indexterm><primary>Modifier names</primary></indexterm>
1158
1159         <itemizedlist>
1160           <listitem>
1161             <para>Functions returning a value with attribute
1162             <replaceable>X</replaceable> set to a new value should be
1163             named
1164             <literal>set<replaceable>X</replaceable></literal>. (<emphasis>TODO</emphasis>:
1165             Add Examples.)</para>
1166           </listitem>
1167
1168           <listitem>
1169             <para> Actions setting some kind of reference or state
1170             have the name
1171             <literal>put<replaceable>X</replaceable></literal>, where
1172             <replaceable>X</replaceable> is the type of the contents
1173             or the name of the part being accessed,
1174             e.g. <literal>putChar</literal>. An alternative naming
1175             scheme is
1176             <literal>write<replaceable>Y</replaceable></literal>,
1177             where <replaceable>X</replaceable> is the type of the
1178             reference or container,
1179             e.g. <literal>writeIORef</literal>.  </para></listitem>
1180
1181           <listitem>
1182             <para> Actions in the <literal>IO</literal> monad setting
1183             some global state <replaceable>X</replaceable> are
1184             traditionally named <literal>setX</literal>, too, although
1185             <literal>put<replaceable>X</replaceable></literal> would
1186             be more appropriate,
1187             e.g. <literal>setReadlineName</literal>.</para>
1188           </listitem>
1189
1190           <listitem>
1191             <para> Actions modifying a container
1192             <replaceable>X</replaceable> by a function of type
1193             <literal>a -> a</literal> have the name
1194             <literal>modify<replaceable>X</replaceable></literal>,
1195             e.g. <literal>modifySTRef</literal>.</para>
1196           </listitem>
1197         </itemizedlist>
1198       </sect3>
1199
1200       <sect3 id="sec-library-predicate-names">
1201         <title>Predicate names</title>
1202         <indexterm><primary>Predicate names</primary></indexterm>
1203
1204         <itemizedlist>
1205           <listitem>
1206             <para>Predicates, both non-monadic and monadic, testing a
1207             property <replaceable>X</replaceable> have the name
1208             <literal>is<replaceable>X</replaceable></literal>.
1209             </para>
1210           </listitem>
1211         </itemizedlist>
1212       </sect3>
1213
1214       <sect3 id="sec-library-naming-conversions">
1215         <title>Names for conversions</title>
1216         <indexterm><primary>Names for conversions</primary></indexterm>
1217
1218         <itemizedlist>
1219           <listitem>
1220             <para>Functions converting a value of type
1221             <replaceable>X</replaceable> to a value of type
1222             <replaceable>Y</replaceable> have the name
1223             <literal><replaceable>X</replaceable>To<replaceable>Y</replaceable></literal>
1224             with all leading uppercase characters of
1225             <replaceable>X</replaceable> converted to lower case,
1226             e.g. <literal>stToIO</literal>.</para>
1227           </listitem>
1228
1229           <listitem>
1230             <para>Overloaded conversion functions of type
1231             <literal>C a => a -> <replaceable>X</replaceable></literal>
1232             have the name
1233             <literal>to<replaceable>X</replaceable></literal>,
1234             e.g. <literal>toInteger</literal>.</para>
1235           </listitem>
1236
1237           <listitem>
1238             <para> Overloaded conversion functions of type
1239 <literal>C a => <replaceable>X</replaceable> -> a</literal>
1240             have the name <literal>from<replaceable>X</replaceable></literal>,
1241 e.g. <literal>fromInteger</literal>.</para>
1242           </listitem>
1243         </itemizedlist>
1244       </sect3>
1245
1246       <sect3 id="sec-library-misc-names">
1247         <title>Miscellaneous naming conventions</title>
1248         <indexterm><primary>Miscellaneous naming
1249         convetions</primary></indexterm>
1250
1251         <itemizedlist>
1252           <listitem>
1253             <para> An action that is identical to another one called
1254             <replaceable>X</replaceable>, but discards the return
1255             value has the name
1256             <literal><replaceable>X</replaceable>_</literal>,
1257             e.g. <literal>mapM</literal> and <literal>mapM_</literal>.
1258             </para>
1259           </listitem>
1260
1261           <listitem>
1262             <para>Functions and actions which are potentially
1263             dangerous to use and leave some kind of proof obligation
1264             to the programmer have the name
1265             <literal>unsafe<replaceable>X</replaceable></literal>,
1266             e.g. <literal>unsafePerformIO</literal>.
1267             </para>
1268           </listitem>
1269
1270           <listitem>
1271             <para>There are two conventions for binary and N-ary
1272             variants of an associative operation: One convention uses
1273             an operator or a short name for the binary operation and a
1274             long name for the N-ary variant,
1275             e.g. <literal>(+)</literal> and <literal>sum</literal>,
1276             <literal>max</literal> and <literal>maximum</literal>. The
1277             other convention suffixes the N-ary variant with
1278             <literal>Many</literal>.  (<emphasis>TODO</emphasis>: Add
1279             Examples.)</para>
1280           </listitem>
1281
1282           <listitem>
1283             <para>If possible, names are chosen such that either plain
1284             application or <literal>arg1 `operation` arg2</literal> is
1285             correct English, e.g. <literal>isPrefixOf</literal> is
1286             good for use in backquotes.</para>
1287           </listitem>
1288         </itemizedlist>
1289       </sect3>
1290     </sect2>
1291
1292     <sect2 id="sec-library-misc-conventions">
1293       <title>Library design conventions</title>
1294
1295       <itemizedlist>
1296         <listitem>
1297           <para>Actions setting and modifying a kind of reference or
1298           state return <literal>()</literal>, getting the value is
1299           separate, e.g. <literal>writeIORef</literal> and
1300           <literal>modifyIORef</literal> both return
1301           <literal>()</literal>, only <literal>readIORef</literal>
1302           returns the value in an <literal>IORef</literal>
1303           </para>
1304         </listitem>
1305
1306         <listitem>
1307           <para>A function or action taking a some kind of state and
1308           returning a pair consisting of a result and a new state, the
1309           result is the first element of the pair and the new state is
1310           the second, see e.g. <literal>Random</literal>.</para>
1311         </listitem>
1312
1313         <listitem>
1314           <para>When the type <literal>Either</literal> is used to
1315           encode an error condition and a normal result,
1316           <literal>Left</literal> is used for the former and
1317           <literal>Right</literal> for the latter, see
1318           e.g. <literal>Control.Monad.Error</literal>.</para>
1319         </listitem>
1320
1321         <listitem>
1322           <para>A module corresponding to a class
1323           (e.g. <literal>Bits</literal>) contains the class
1324           definition, perhaps some auxiliary functions, and all
1325           sensible instances for Prelude types, but nothing
1326           more. Other modules containing types for which an instance
1327           for the class in question makes sense contain the code for
1328           the instance itself.</para>
1329         </listitem>
1330
1331         <listitem>
1332           <para>Record-like C bit fields or structs have a
1333           record-like interface, i.e. pure getting and setting of
1334           fields. (<emphasis>TODO</emphasis>: Clarify a little
1335           bit. Add examples.)</para>
1336         </listitem>
1337
1338         <listitem>
1339           <para>Although the possibility of partial application
1340           suggests the type
1341
1342 <literal><replaceable>attr</replaceable> -> <replaceable>object</replaceable> -> <replaceable>object</replaceable></literal>
1343
1344           for functions setting an attribute or value, infix notation
1345           with backquotes implies
1346
1347 <literal><replaceable>object</replaceable> -> <replaceable>attr</replaceable> -> <replaceable>object</replaceable></literal>.
1348
1349           (<emphasis>TODO</emphasis>: Add Examples.)</para>
1350         </listitem>
1351       </itemizedlist>
1352     </sect2>
1353
1354     <sect2 id="coding-style">
1355       <title>Coding style conventions</title>
1356       <para></para>
1357     </sect2>
1358
1359   </sect1>
1360
1361   <sect1>
1362     <title>Changes to standard Haskell 98 libraries</title>
1363
1364     <para>Some changes have been made to the standard Haskell 98
1365     libraries in the new library scheme, both in the names of the
1366     modules themselves and in their exported interfaces.  Below is a
1367     summary of those changes - at this time, the new libraries are
1368     marked as provisional and are maintained by
1369     <email>libraries@haskell.org</email>, so changes in the interfaces
1370     are all up for discussion.</para>
1371
1372 <screen>
1373     modules with interface changes
1374     ------------------------------
1375
1376     Array -> Data.Array
1377        added instance Typeable (Array ix a)
1378
1379     Char  -> Data.Char
1380        no interface changes (should have instance Typeable?)
1381
1382     Complex -> Data.Complex
1383        added instance Typeable (Complex a)
1384
1385     IO -> System.IO
1386        added
1387         hPutBuf :: Handle -> Ptr a -> Int -> IO ()
1388         hGetBuf :: Handle -> Ptr a -> Int -> IO Int
1389         fixIO   :: (a -> IO a) -> IO a
1390
1391     List -> Data.List
1392        exports [](..)
1393
1394     Numeric -> Numeric
1395        added showHex, showOct, showBin & showIntAtBase from NumExts,
1396        but left out floatToDouble & doubleToFloat (realToFrac is more general).
1397
1398     System    -> System.Exit, System.Environment, System.Cmd
1399        split into three modules
1400
1401     just renamed, no interface changes:
1402     -----------------------------------
1403
1404     CPUTTime  -> System.CPUTime
1405     Directory -> System.IO.Directory
1406     Ix        -> Data.Ix
1407     Locale    -> System.Locale
1408     Monad     -> Data.Monad
1409     Random    -> System.Random
1410     Ratio     -> Data.Ratio
1411     Time      -> System.Time
1412 </screen>
1413   </sect1>
1414
1415 </article>