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