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