1 <?xml version="1.0" encoding="iso-8859-1"?>
2 <!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
3 "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
4 <!ENTITY libtable SYSTEM "libtable.xml">
7 <article id="libraries">
9 <title>Hierarchical Haskell Libraries</title>
10 <orgname>The Haskell Libraries Mailing List</orgname>
11 <address><email>libraries@haskell.org</email></address>
14 <sect1 id="introduction">
15 <title>Introduction</title>
18 url="http://www.haskell.org/hierarchical-modules/">Hierarchical
19 Module Namespace Extension</ulink> is a modest extension to Haskell 98
20 which replaces the existing flat module namespace with a
23 <para>This document constitutes a proposal for how the new
24 hierarchical namespace should be used. It is
25 <emphasis>not</emphasis> an addendum to the Haskell 98 report: the
26 contents of this document are still under discussion on the
28 url="http://www.haskell.org/mailman/listinfo/libraries"><literal>libraries@haskell.org</literal></ulink>
29 mailing list, and are subject to change.</para>
31 <para>The most up to date version of this document can be found in
33 url="http://www.haskell.org/ghc/docs/latest/html/building/sec-cvs.html">GHC
34 CVS repository</ulink> in the directory
35 <literal>fptools/libraries/doc</literal>.</para>
37 <para>The proposal has several parts: </para>
41 <para>An allocation of the new module namespace to existing
42 and non-existent libraries, people, organisations, and local
46 <para>A policy and procedure for allocating new parts of the
50 <para>A set of libraries which are under the control of the
51 community and have reference implementations. These libraries
52 will vary from almost completely stable (eg. the
53 <literal>Prelude</literal>) to experimental libraries with
54 fast-changing APIs. Throughout this document, these libraries
55 shall be referred to as the <firstterm>Reference
56 Libraries</firstterm>. The reference libraries serve to both
57 define the library APIs, and provide implementations; in most
58 cases this will be the primary implementation of that
63 <para>In addition, this document also describes:</para>
67 <para>Guidelines and conventions for organising the
71 <para>Our policy with respect to the design and evolution of
72 library APIs, versioning of library APIs, and maintenance of
73 the reference implementation.</para>
76 <para>A set of conventions for coding style and portability
77 within the libraries.</para>
82 <sect1 id="contributing">
83 <title>How to contribute</title>
85 <para>This project is driven by the Haskell community, so
86 contributions of all kinds are welcome. The first step is to join
88 url="http://www.haskell.org/mailman/listinfo/libraries">Haskell
89 libraries mailing list</ulink>, and maybe <ulink
90 url="http://www.haskell.org/pipermail/libraries/">browse the list
91 archives</ulink>. Some of the ways you can contribute are:</para>
95 <para>By donating code: for libraries which don't yet have a
96 reference implementation, code is always welcome. Code that
97 conforms to the design guidelines (which aren't very strict,
98 see <xref linkend="library-design"/>) and comes with documentation
99 (<xref linkend="documentation"/>) and a test suite (<xref
100 linkend="testing"/>) is better, but these aren't essential. As
101 a library progresses through the stability scale (<xref
102 linkend="stability"/>) these things become more important, but
103 for an experimental library we're not going to worry too much
104 about this stuff.</para>
106 <para>See section <xref
107 linkend="contributing-reference-libraries"/> for details on
108 contributing new library code.</para>
111 <para>By porting code for an existing library to a new
112 compiler or architecture. A library is classed as portable if
113 it should be available regardless of which compiler/platform
114 combination you're using; however, many libraries are
115 non-portable for one reason or another (see <xref
116 linkend="portability"/>), and broadening the scope of these
117 libraries is always welcome.</para>
120 <para>Become a library maintainer: if you have a particular
121 interest in and/or knowledge about a certain library, and have
122 the time to spare, and the library in question doesn't already
123 have a maintainer, then you may be a suitable maintainer for
124 the library. The responsibilities of library maintainers are
125 given in <xref linkend="maintainership"/>. </para>
128 <para>Participating in the design process for new libraries,
129 and suggesting improvements to existing libraries. Everyone
131 url="http://www.haskell.org/mailman/listinfo/libraries">Haskell
132 libraries mailing list</ulink> is invited to
133 participate in the design process, so get involved!</para>
141 <title>A possible extension</title>
143 <para>The use of qualified imports has become more verbose: for
147 import qualified XmlParse
148 ... XmlParse.element f ...
154 import qualified Text.Xml.Parse
155 ... Text.Xml.Parse.element f ...
158 <para>It is usually more convenient to make use of Haskell's
159 <literal>as</literal> keyword to shorten qualified identifiers:</para>
162 import qualified Text.Xml.Parse as Parse
163 ... Parse.element f ...
166 <para>A possible extension to the proposal is to make this use
167 of <literal>as</literal> implicit, unless overridden by the
168 programmer with her own <literal>as</literal> clause. The
169 implicit <literal>as</literal> clause always uses the final
170 subdivision of the module name. So for instance, either the
171 fully-qualified or abbreviated-qualified names</para>
174 Text.Xml.Parse.element
178 <para>would be accepted and have the same referent, but a
179 partial qualification like</para>
185 <para>would not be accepted.</para>
189 <title>Renaming subtrees</title>
191 <para>Various proposals have been made to allow you to rename a
192 whole subtree. This may occasionally be convenient: for example
193 suppose there are several libraries under
194 <literal>Org.Com.Microsoft</literal> that I need to import, it
195 would be easier to rename this subtree to just
196 <literal>Microsoft</literal> for use in future import
197 declarations. For example:</para>
200 import Org.Com.Microsoft.* as Microsoft.*
206 <para>The exact syntax of the renaming declaration is up for
207 debate (as is whether we need it at all), please send
208 suggestions to <email>libraries@haskell.org</email>.</para>
214 <title>The hierarchy</title>
216 <para>We first classify each node in the hierarchy according to
217 one of the following terms:</para>
221 <term>Allocated</term>
223 <para>Nodes in the hierarchy can be allocated to a library.
224 The currently allocated nodes are specified in <xref
225 linkend="allocated-names"/>.</para>
232 <para>The <literal>User</literal> hierarchy is reserved for
233 users: a user may always use the portion of the hierarchy
234 which is formed from his/her email address as follows:
235 replace any <quote><literal>.</literal></quote>s in the
236 username (before the <literal>@</literal>) with
237 <quote><literal>_</literal></quote>, replace the
238 <quote><literal>@</literal></quote> by a
239 <quote><literal>.</literal></quote>, reverse the order of
240 the components, capitalise the first letter of each
241 component, and prepend
242 <quote><literal>User.</literal></quote>. For example,
243 <literal>simonmar@microsoft.com</literal> becomes
244 <literal>User.Com.Microsoft.Simonmar</literal>.</para>
249 <term>Organisation</term>
251 <para>The <literal>Org</literal> hierarchy is reserved for
252 organisations. Any organisation with a DNS domain name owns
253 a unique space in the hierarchy formed by reversing the
254 components of the domain, capitalising the first character
255 of each component, and prepending <literal>Org.</literal>.
256 <emphasis>ToDo: the Org name isn't great, especially when
257 the domain name also ends with Org (eg. Org.Org.Haskell?).
258 Contrib has also been suggested.</emphasis></para>
265 <para>The <literal>Local</literal> hierarchy is reserved for
266 libraries which are local to the current site. Libraries
267 which are to be distributed outside the current site should
268 not be placed in the <literal>Local</literal>
274 <term>Unallocated</term>
276 <para>Any node which doesn't belong to any of the above
277 categories is currently unallocated, and is available for
278 use by Haskell programs.</para>
283 <para>A node in the hierarchy may be both a specific library and a
284 parent node for a number of child nodes. For example,
285 <literal>Foreign</literal> is a library, and so is
286 <literal>Foreign.Ptr</literal>.</para>
288 <sect2 id="hierarchy-design-guidelines">
289 <title>Hierarchy design guidelines</title>
291 <para>Apart from the <literal>User</literal>,
292 <literal>Local</literal> and <literal>Org</literal> top-level
293 categories, the rest of the hierarchy is organised with a single
294 principle in mind:</para>
297 <para>Modules are grouped by
298 <emphasis>functionality</emphasis>, since this is the single
299 property that is most helpful for a user of the library - we
300 want users to be able to find out where to obtain
301 functionality easily, and to easily find all the modules that
302 provide relevant functionality.</para>
304 <para>So, if two modules provide similar functionality, or
305 alternative interfaces to the same functionality, then they
306 should be children of the same node in the hierarchy. Modules
307 should not be grouped by standards compliance, portability,
308 stability, or any other property.</para>
311 <para>It should be noted that this is a guideline rather than a
312 rule: sometimes it just isn't the right thing. For example, the
313 <literal>DotNet</literal> top-level name contains a mirror of
314 the Microsoft .NET base class library; if we had gone purely by
315 functionality then these libraries would have to be scattered
316 around the hierarchy, resulting in a situation where it would
317 probably be <emphasis>harder</emphasis> for a programmer to find
318 the functionality he or she is interested in.</para>
320 <para>There are some other considerations when choosing where to
321 place libraries. Where possible, choose a layout that finds a
322 good compromise between depth of nesting and logical grouping of
323 functionality; for example, although the <literal>Text</literal>
324 hierarchy could logically be placed as a child of
325 <literal>FileFormat</literal>, we choose not to because
326 <literal>Text</literal> is ubiquitous and we don't want to have
327 to type the extra component all the time.</para>
329 <para>Also consider consistency: if a particular sub-hierarchy
330 provides similar functionality to another sub-hierarchy in the
331 tree, then preferably the structure of the two subtrees should
332 also be similar. For example: under
333 <literal>Language.Haskell</literal> we have children
334 <literal>Syntax</literal>, <literal>Lexer</literal>,
335 <literal>Parser</literal> etc., so under
336 <literal>Language.C</literal> we should have a similar
340 <sect2 id="module-naming-convention">
341 <title>Module naming conventions</title>
345 <para>A module defining a data type or type class
346 <replaceable>X</replaceable> has itself the name
347 <replaceable>X</replaceable>, e.g.
348 <literal>StablePtr</literal>.</para>
352 <para>A module which re-exports the modules in a subtree of
353 the hierarchy has the same name as the root of that subtree,
354 eg. <literal>Foreign</literal> re-exports
355 <literal>Foreign.Ptr</literal>,
356 <literal>Foreign.Marshal.Utils</literal> etc.</para>
360 <para>If a subtree of the hierarchy contains several modules
361 which provide similar functionality (eg. there are several
362 pretty-printing libraries under
363 <literal>Text.PrettyPrinter</literal>), then the module at
364 the root of the subtree generally re-exports just
365 <emphasis>one</emphasis> of the modules in the subtree
366 (possibly the most popular or commonly-used
371 <para>In Haskell you sometimes publish
372 <emphasis>two</emphasis> interfaces to your libraries; one
373 for users, and one for library writers or advanced users who
374 might want to extend things. Typically the advanced users
375 need to be able to see past certain abstractions.</para>
377 <para>The current proposal is for a module named
378 <literal>M</literal>, the <quote>advanced</quote> version
379 would be named <literal>M.Internals</literal>. eg.</para>
382 import Text.HTML -- The library
383 import Text.HTML.Internals -- The non-abstract library
388 <para>Acronyms are fully capitalised in a module name.
389 eg. <literal>HTML</literal>, <literal>URI</literal>,
390 <literal>CGI</literal>, etc. Exceptions may be made for
391 acronyms which have an existing well-established alternative
392 capitalisation, or acronyms which are also valid words, and
393 are more often used as such.</para>
397 <para>A module name should be made plural only if the module
398 actually defines multiple entities of a particular kind:
399 eg. <literal>Foreign.C.Types</literal>. Most module names
400 which define a type or class will follow the name of the
401 type or class, so whether to pluralize is not an
407 <sect2 id="top-level-names">
408 <title>The top-level names</title>
410 <para>The currently allocated nodes in the hierarchy are listed
411 in the next section (<xref linkend="allocated-names"/>). In
412 addition, for each top-level name we describe its intended
413 purpose below:</para>
417 <term><literal>Control</literal></term>
419 <para>Libraries which provide functions, types or classes
420 whose purpose is primarily to express control
426 <term><literal>Data</literal></term>
428 <para>Libraries which provide data types, operations over
429 data types, or type classes, except for libraries for
430 which one of the other more specific categories is
436 <term><literal>Database</literal></term>
438 <para>Libraries for providing access to or operations for
439 building databases.</para>
444 <term><literal>Debug</literal></term>
446 <para>Support for debugging Haskell programs.</para>
451 <term><literal>DotNet</literal></term>
453 <para>Mirrors the Microsoft .NET base class hierarchy, for
454 systems providing access to the .NET libraries.</para>
459 <term><literal>Edison</literal></term>
461 <para>The Edison data structure library.</para>
466 <term><literal>Codec</literal></term>
468 <para>Support for (en)coding and decoding data in various
469 formats. <literal>Codec</literal> encompasses compression
470 (both lossy and non-lossy) codings, transport
471 codings, and encryption.</para>
476 <term><literal>Foreign</literal></term>
478 <para>Interaction with code written in a foreign
479 programming language.</para>
484 <term><literal>Graphics</literal></term>
486 <para>Libraries for producing graphics or providing
487 graphical user interfaces.</para>
492 <term><literal>Language</literal></term>
494 <para>Libraries for operating on or generating source code
495 in various programming languages, including parsers,
496 pretty printers, abstract syntax definitions etc.</para>
501 <term><literal>Local</literal></term>
503 <para>Available for site-local use.</para>
508 <term><literal>Numeric</literal></term>
510 <para>Functions and classes which provide operations over
516 <term><literal>Network</literal></term>
518 <para>Libraries for communicating over a network,
519 including implementations of network protocols.</para>
524 <term><literal>Org</literal></term>
526 <para>Allocated to organisations on a domain-name
527 basis (see <xref linkend="layout"/>).</para>
532 <term><literal>Prelude</literal></term>
534 <para>Haskell98 Prelude (mostly just re-exports other
535 parts of the tree).</para>
540 <term><literal>System</literal></term>
542 <para>Libraries for communication with the system on which
543 the Haskell program is running (including the runtime
549 <term><literal>Text</literal></term>
551 <para>Libraries for parsing and generating data in a
552 textual format (including structured textual formats such
553 as XML, HTML, but not including programming language
554 source, which lives in Language).</para>
559 <term><literal>GHC</literal></term>
561 <para>Libraries specific to the GHC/GHCi system.</para>
566 <term><literal>Nhc</literal></term>
568 <para>Libraries specific to the Nhc compiler.</para>
573 <term><literal>Hugs</literal></term>
575 <para>Libraries specific to the Hugs system.</para>
580 <term><literal>User</literal></term>
582 <para>Allocated to individual users, using email
583 addresses (see <xref linkend="layout"/>).</para>
589 <sect2 id="allocated-names">
590 <title>Allocated libraries</title>
593 <tgroup cols="3" align="left" colsep="1" rowsep="1">
596 <entry>Library</entry>
597 <entry>Maintainer</entry>
609 <sect1 id="reference-libraries">
610 <title>Reference libraries</title>
612 <para>There are reference implementations for many of the
613 libraries allocated in the hierarchy (see <xref
614 linkend="allocated-names"/>). These reference libraries serve to define
615 the API for each library, and also in most cases provide the
616 primary implementation of that library. We don't discount the
617 possibility that multiple implementations of libraries may exist,
618 but there is only ever one reference implementation.</para>
620 <para>Many of the reference libraries live in the CVS repository
621 on <literal>cvs.haskell.org</literal> under the directory <ulink
622 url="http://cvs.haskell.org/cgi-bin/cvsweb.cgi/fptools/libraries"><literal>fptools/libraries</literal></ulink>,
623 but others are maintained and distributed separately by members of
624 the Haskell community. <xref linkend="allocated-names"/> lists the
625 maintainer for each reference library, and a location from which
626 the code can be obtained.</para>
628 <sect2 id="installing">
629 <title>Installing libraries</title>
631 <para>Compilers are normally distributed with a number of
632 libraries, which may or may not be built from the reference
633 implementations.</para>
635 <para>Currently, the procedure for installing a library which is
636 not distributed with your compiler is currently dependent on a
637 number of things: platform, compiler, and how much support is
638 provided by the library maintainer. We aim to standardise this
639 procedure to a certain extent by providing a library
640 infrastructure which automates the building, installation and
641 packaging of libraries for all architectures and compilers. The
642 means by which we might achieve this are being actively
643 discussed: see the <ulink
644 url="http://www.haskell.org/pipermail/libraries/">libraries
645 mailing list archives</ulink>.</para>
648 <sect2 id="contributing-reference-libraries">
649 <title>Contributing new reference libraries</title>
651 <para>The process for contributing a new library is as
656 <term>Allocate module names.</term>
658 <para>If you want a library in the <literal>User</literal>
659 or <literal>Org</literal> part of the hierarchy, then
660 nothing needs to be done: just go ahead and distribute
663 <para>If, however, you are providing a library for any
664 other part of the hierarchy, then the module names in the
665 should be allocated. <xref linkend="allocated-names"/>
666 lists the parts of the hierarchy that are currently
669 <para>There are several reasons for allocating module
670 names centrally in this way:</para>
674 <para>Haskell users have the guarantee that libraries
675 never conflict with each other by using the same
679 <para>There is always one place to obtain a given
680 library, each library has a single reference
681 implementation, and there is a single point of contact
682 for the implementor(s).</para>
686 <para>Remember that this only applies to libraries: code
687 in a <emphasis>program</emphasis> can use whatever module
688 names it chooses (but it's probably a good idea to avoid
689 conflicting with any libraries that might be installed:
690 avoiding the allocated module names is a good way to
693 <para>To allocate module names for a new library, send
694 mail to <email>libraries@haskell.org</email> describing
695 your library and which module names you are proposing to
696 allocate. Provided there is no conflict, then the names
697 will normally be allocated and added to the list above. A
698 conflict might arise if for example someone else wants to
699 provide a library with the same name; conflicts will be
700 resolved by consensus on a case-by-case basis.</para>
705 <term>Distribute the library.</term>
707 <para>The mechanism by which libraries should be
708 distributed is currently being discussed; we hope in the
709 future to make the process much easier for library
710 writers. Currently you have to do all the work yourself:
711 write a build system (or steal one), installation scripts
712 and support for packaging on each platform that you wish
719 <sect2 id="licensing">
720 <title>Licensing</title>
722 <para>Following some discussion on the mailing list related to
723 how we should license the libraries, the viewpoint that was
724 least offensive to all involved seems to be the
727 <para>We wish to accommodate source code from different
728 contributors, and with different licenses. However, a library
729 of modules where each module is released under a different
730 license, and where the dependencies between modules aren't
731 clear, isn't workable (it's too hard for a user of the library
732 to tell whether they're violating the terms of the each license
735 <para>So the solution is as follows: code under different
736 licenses will be clearly separate in the repository (i.e. in
737 separate subdirectories), and compilers are expected to present
738 packages of modules where all modules in a package fall under
739 the same license, and where the dependencies between packages
742 <para>It was decided that certain essential functionality should
743 be available under a BSD style license. Hence, the BSD part of
744 the repository will contain implementations of at least the
745 following modules: <literal>Prelude</literal>,
746 <literal>Foreign</literal>, <emphasis>ToDo: what
747 else?</emphasis>.</para>
749 <para>There is one further requirement: reference libraries must
750 be available under a license approved by the Open Source
751 Initiative. See <ulink url="http://www.opensource.org//">The
752 Open Source Initiative</ulink> for a list of approved
756 <sect2 id="versioning">
757 <title>Versioning</title>
758 <para><emphasis>ToDo</emphasis></para>
761 <sect2 id="stability">
762 <title>Library stability</title>
764 <para>The stability of a library relates primarily to its API.
765 Stability provides an indication of how often the API is likely
766 to change (or whether it may even go away entirely).</para>
768 <para>The stability scale is also a measure of how strictly the
769 conventions in this document are applied to the library: an
770 experimental library isn't subject to any restrictions regarding
771 coding style and documentation, but a stable library is expected
772 to adhere to the guidelines, and come with full documentation
775 <para>To help with the stability issue, library maintainers are
776 allowed to mark functions, types or classes as
777 <firstterm>deprecated</firstterm><footnote><para>Compilers may
778 have extra support for warning about the use of a deprecated
779 feature, for example GHC's <literal>DEPRECATED</literal>
780 pragma.</para> </footnote>, which means simply that the feature
781 will be removed at a later date. Just how long it will stick
782 around for depends on the stability category of the library (see
783 below). A feature is marked as deprecated in the documentation
784 for the library, and optionally in an implementation-dependent
785 way which enables the system to warn about the use of deprecated
788 <para>The current stability categories are:</para>
792 <term><firstterm>experimental</firstterm></term>
794 <para>An experimental library is unrestricted in terms of
795 API changes: the API may change between minor revisions
796 and there is no requirement to retain old interfaces for
797 compatibility. Documentation and tests aren't required
798 for an experimental library.</para>
802 <term><firstterm>provisional</firstterm></term>
804 <para>A provisional library is moving towards stability,
805 and the rate of change of the API is slower. API changes
806 between minor revisions must be accompanied by deprecated
807 versions of the old features where possible. API changes
808 between major versions are unrestricted. The library
809 should come with at least rudimentary
810 documentation.</para>
814 <term><firstterm>stable</firstterm></term>
816 <para>A stable library has an essentially fixed API.
817 Additions to the API may be made for a minor release,
818 deprecated features must be retained for at least one
819 major revision, and small changes only may be made to the
820 existing API semantics for a major revision. A stable
821 library is expected to include full documentation and
829 <sect2 id="portability">
830 <title>Portability considerations</title>
832 <para>The portability status of a library affects which
833 platforms and compilers the library will be available on. The
834 precise meaning of the terms portable and non-portable for our
835 purposes are given below:</para>
839 <term><firstterm>Portable</firstterm></term>
841 <para>A library which is available on all platforms and
842 with all Haskell implementations is portable.</para>
844 <para>A portable library may make use of non-portable
845 features or import non-portable libraries in its
846 implementation, as long as it does so conditionally and
847 provides the same interface on all platforms and with all
848 Haskell implementations.</para>
852 <term><firstterm>Non-portable</firstterm></term>
854 <para>A non-portable library may be non-portable for one
855 or more of the following reasons:</para>
858 <term><firstterm>Requires extensions</firstterm></term>
860 <para>A library which uses non-approved language
861 extensions in its implementation, and has no
862 portable fallback implementation.</para>
866 <term><firstterm>Requires nonportable libraries</firstterm></term>
868 <para>A library which depends (directly or indirectly)
869 on other non-portable libraries.</para>
873 <term><firstterm>OS-specific</firstterm></term>
874 <term><firstterm>Platform-specific</firstterm></term>
876 <para>A library which depends on features or APIs
877 particular to a certain OS or platform is
878 non-portable for that reason.</para>
886 <sect3 id="approved-extensions">
887 <title>Approved extensions</title>
889 <para>Very few of the reference libraries can be implemented
890 using pure Haskell 98. For this reason, we decided to raise
891 the baseline for portable libraries to include a few common
892 extensions; the following language extensions can be
893 <emphasis>assumed</emphasis> to be present when writing
899 url="http://haskell.org/ghc/docs/latest/set/ffi.html">Foreign
900 Function Interface</ulink>.</para>
903 <para>Mutable variables
904 (<literal>Data.IORef</literal>).</para>
907 <para>Unsafe IO monad operations
908 (<literal>System.IO.Unsafe</literal>).</para>
912 (<literal>Data.PackedString</literal>).</para>
915 <para>Bit operations (<literal>Data.Bits</literal>).</para>
919 <para>Extensions which we'd like to be standard, but aren't
920 currently implemented by one or more of the target
925 <para>Exceptions (synchronous only), defined by the
926 <literal>Control.Exception</literal> interface.</para>
929 <para>The ST monad, defined by
930 <literal>Control.Monad.ST</literal>, and the associated
931 <literal>Data.Array.ST</literal> and
932 <literal>Data.STRef</literal> libraries. ST requires a
933 small typechecker extension for the
934 <literal>runST</literal> function.</para>
937 <para>Concurrent Haskell (pre-emptive multitasking
938 optional). GHC and Hugs implement this, but Nhc currently
943 <para>The following extensions are not likely to become part
944 of the baseline, but are nevertheless used by one or more
945 libraries in the reference set (which are thus designated
946 non-portable):</para>
950 <para>Multi-parameter type classes.</para>
953 <para>Local universal and existential quantification.</para>
956 <para>Concurrent Haskell with pre-emptive multitasking.</para>
959 <para>Asynchronous exceptions.</para>
962 <para>Stable Names.</para>
965 <para>Weak Pointers.</para>
969 <para>Other extensions are supported by a single compiler
970 only, and can be accessed by libraries under the top level
971 hierarchy for that compiler,
972 eg. <literal>GHC.UnboxedTypes</literal>.</para>
976 <sect2 id="maintainership">
977 <title>Library maintainers</title>
979 <para>This is a collaborative project, so we like to devolve
980 control of the design and implementation of libraries to those
981 with an interest or appropriate expertise (or maybe just the
982 time!). A maintainer isn't necessarily a single person - for
983 example, the listed maintainer for most of the reference
984 libraries is <email>libraries@haskell.org</email>, indicating
985 that the library is under the control of the community as a
986 whole. The maintainer for the <literal>Foreign</literal>
987 hierarchy is <email>ffi@haskell.org</email>, the mailing list
988 for discussion of the Haskell FFI standard.</para>
990 <para>The responsibilities of a library maintainer include:</para>
994 <para>Most importantly: act as a single point of contact for
995 issues relating to the library API and its
996 implementation.</para>
999 <para>Manage any discussion related to the library (which
1000 can take place on <email>libraries@haskell.org</email> if
1001 necessary), and summarise the results. Make final
1002 decisions, and implement them.</para>
1005 <para>Maintain the implementation, including: fixing bugs,
1006 updating to keep up with changes in other libraries, porting
1007 to new compilers/platforms, and integrating code from other
1008 contributors. The maintainer is expected to be the only
1009 person/group to make functional changes to the source code
1010 (non-functional or trivial changes don't count).</para>
1013 <para>Maintain/write the documentation and tests.</para>
1016 <para>If you can't maintain the library any more for
1017 whatever reason, tell <email>libraries@haskell.org</email>
1018 and we'll revert the maintainer status of the library to the
1024 <sect2 id="documentation">
1025 <title>Documentation</title>
1027 <para>We are using <ulink
1028 url="http://www.haskell.org/haddock/">Haddock</ulink> to
1029 document the libraries. Haddock generates nice hyperlinked HTML
1030 output directly from the Haskell source, and understands
1031 comments written in a particular style as documentation
1032 annotations, which are merged with the generated
1033 documentation.</para>
1035 <para>Before submitting code to the libraries project, please
1036 ensure that it passes through Haddock without complaint. Even
1037 if it contains no actual documentation annotations, we'll get
1038 useful documentation out of the source alone (type signatures,
1039 data types, etc.).</para>
1042 <sect2 id="coding-style">
1043 <title>Coding style</title>
1045 <sect3 id="module-header">
1046 <title>Standard module header</title>
1048 <para>Using a standard module header makes it easy to
1049 automatically extract meta-information from library source
1050 code, such as the stability/portability of individual modules.
1051 We recommend using the following module header for reference
1055 -----------------------------------------------------------------------------
1057 -- Module : <replaceable>module</replaceable>
1058 -- Copyright : (c) <replaceable>author</replaceable> <replaceable>year</replaceable>
1059 -- License : <replaceable>license</replaceable>
1061 -- Maintainer : libraries@haskell.org | <replaceable>email-address</replaceable>
1062 -- Stability : experimental | provisional | stable
1063 -- Portability : portable | non-portable (<replaceable>reason(s)</replaceable>)
1065 -- $Id$
1067 -- <replaceable>Description</replaceable>
1068 -----------------------------------------------------------------------------
1075 <term><literal>$Id: libraries.xml,v 1.2 2004/08/18 16:42:56 panne Exp $</literal></term>
1077 <para>is optional, but may be included if the module is
1078 under CVS or RCS control (however, current wisdom
1080 <literal>$Id$</literal> tags are not such
1081 a great idea).</para>
1086 <term><replaceable>module</replaceable></term>
1088 <para>is the fully qualified module name of the
1094 <term><replaceable>author</replaceable>/<replaceable>year</replaceable></term>
1096 <para>Is the primary author and copyright holder of the
1097 module, and the year in which copyright is
1103 <term><replaceable>license</replaceable></term>
1105 <para>Specifies the license on the file (see <xref
1106 linkend="licensing"/>).</para>
1111 <term><replaceable>email-address</replaceable></term>
1113 <para>The email address of the maintainer, or
1114 maintainers, of the library (see <xref
1115 linkend="maintainership"/>).</para>
1120 <term><replaceable>reason(s)</replaceable></term>
1122 <para>The reasons for non-portability must be listed
1123 (see <xref linkend="portability"/>).</para>
1128 <term><replaceable>description</replaceable></term>
1130 <para>A short description of the module.</para>
1137 <sect2 id="testing">
1138 <title>Testing</title>
1139 <para><emphasis>ToDo</emphasis></para>
1143 <sect1 id="Migration-path">
1144 <title>Migration path</title>
1146 <para>How compatible will a compiler using the new libraries be
1147 with code written for Haskell 98 or older library systems (such as
1148 the <literal>hslibs</literal> suite and GHC's package system), and
1149 for how long will compatibility be maintained?</para>
1151 <para>Our current plan for GHC is as follows: by default, with the
1152 <option>-fglasgow-exts</option> flag, you'll get access to the
1153 following libraries from the CVS repository: those under
1154 <literal>base</literal>, <literal>network</literal>,
1155 <literal>unix</literal>, <literal>readline</literal>,
1156 <literal>template-haskell</literal>, and
1157 <literal>haskell-src</literal>. Compatibility with Haskell 98
1158 code will be maintained using a separate package of wrappers
1159 presenting interfaces for the Haskell 98 libraries
1160 (<literal>IO</literal>, <literal>Ratio</literal>,
1161 <literal>Directory</literal>, etc.). The Haskell 98 compatibility
1162 package will be enabled by default, but we plan to add an option
1163 to disable it if necessary. For code that uses <literal>-package
1164 lang</literal>, we could also provide a compatibility wrapper
1165 package (so <literal>-package lang</literal> will continue to work
1166 as before and present the same library interfaces), but this may
1167 prove too much work to maintain - we haven't decided whether to do
1168 this or not. It is unlikely that compatibility wrappers for any
1169 of the other <literal>hslibs</literal> packages will be
1173 <sect1 id="library-design">
1174 <title>Library design</title>
1176 <sect2 id="naming-conventions">
1177 <title>Naming conventions</title>
1179 <para>These naming conventions are pulled straight from the
1180 <literal>hslibs</literal> documentation. They were formed after
1181 lengthy discussions and are heavily based on an initial
1182 suggestion from Marcin Kowalczyk
1183 <email>qrczak@knm.org.pl</email>.</para>
1185 <para>Note that the conventions are not mutually exclusive,
1186 e.g. should the function creating a set from a list of elements
1187 have the name <literal>set</literal> or
1188 <literal>listToSet</literal>? (Alas, it currently has neither
1191 <para> The following nomenclature is used: Pure,
1192 i.e. non-monadic functions are simply called, well,
1193 <emphasis>functions</emphasis>. Monadic functions,
1194 i.e. functions having a type <literal>... -> m a</literal>
1195 for some Monad <literal>m</literal> are called
1196 <emphasis>actions</emphasis>.</para>
1198 <sect3 id="sec-library-constructor-names">
1199 <title>Constructor names</title>
1200 <indexterm><primary>Constructor names</primary></indexterm>
1204 <para>Empty values of type <replaceable>X</replaceable>
1205 have the name <literal>empty<replaceable>X</replaceable></literal>,
1206 e.g. <literal>emptySet</literal>.</para>
1210 <para>Actions creating a new empty value of type
1211 <replaceable>X</replaceable> have the name
1212 <literal>newEmpty<replaceable>X</replaceable></literal>,
1213 e.g. <literal>newEmptyMVar</literal>.</para>
1217 <para>Functions creating an arbitrary value of type
1218 <replaceable>X</replaceable> have the name
1219 <replaceable>X</replaceable> itself (with the first letter
1221 e.g. <literal>array</literal>. (<emphasis>TODO</emphasis>:
1222 This often collides with <literal>xToY</literal>
1223 convention, how should this be resolved?)
1228 <para>Actions creating new values arbitrary values of type
1229 <replaceable>X</replaceable> have the name
1230 <literal>new<replaceable>X</replaceable></literal>,
1231 e.g. <literal>newIORef</literal>.
1237 <sect3 id="sec-library-accessor-names">
1238 <title>Accessor names</title>
1239 <indexterm><primary>Accessor names</primary></indexterm>
1243 <para>Functions getting an attribute of a value or a part
1244 of it have the name of the attribute itself,
1245 e.g. <literal>length</literal>, <literal>bounds</literal>.
1250 <para> Actions accessing some kind of reference or state
1252 <literal>get<replaceable>X</replaceable></literal>, where
1253 <replaceable>X</replaceable> is the type of the contents
1254 or the name of the part being accessed,
1255 e.g. <literal>getChar</literal>,
1256 <literal>getEnv</literal>. An alternative naming scheme is
1257 <literal>read<replaceable>Y</replaceable></literal>,
1258 where <replaceable>Y</replaceable> is the type of the
1259 reference or container, e.g. <literal>readIORef</literal>.
1264 <para>Functions or actions getting a value via a
1265 pointer-like type <replaceable>X</replaceable> should be
1267 <literal>deRef<replaceable>X</replaceable></literal>,
1268 e.g. <literal>deRefStablePtr</literal>,
1269 <literal>deRefWeak</literal>.</para>
1274 <sect3 id="sec-library-modifier-names">
1275 <title>Modifier names</title>
1276 <indexterm><primary>Modifier names</primary></indexterm>
1280 <para>Functions returning a value with attribute
1281 <replaceable>X</replaceable> set to a new value should be
1283 <literal>set<replaceable>X</replaceable></literal>. (<emphasis>TODO</emphasis>:
1284 Add Examples.)</para>
1288 <para> Actions setting some kind of reference or state
1290 <literal>put<replaceable>X</replaceable></literal>, where
1291 <replaceable>X</replaceable> is the type of the contents
1292 or the name of the part being accessed,
1293 e.g. <literal>putChar</literal>. An alternative naming
1295 <literal>write<replaceable>Y</replaceable></literal>,
1296 where <replaceable>X</replaceable> is the type of the
1297 reference or container,
1298 e.g. <literal>writeIORef</literal>. </para></listitem>
1301 <para> Actions in the <literal>IO</literal> monad setting
1302 some global state <replaceable>X</replaceable> are
1303 traditionally named <literal>setX</literal>, too, although
1304 <literal>put<replaceable>X</replaceable></literal> would
1305 be more appropriate,
1306 e.g. <literal>setReadlineName</literal>.</para>
1310 <para> Actions modifying a container
1311 <replaceable>X</replaceable> by a function of type
1312 <literal>a -> a</literal> have the name
1313 <literal>modify<replaceable>X</replaceable></literal>,
1314 e.g. <literal>modifySTRef</literal>.</para>
1319 <sect3 id="sec-library-predicate-names">
1320 <title>Predicate names</title>
1321 <indexterm><primary>Predicate names</primary></indexterm>
1325 <para>Predicates, both non-monadic and monadic, testing a
1326 property <replaceable>X</replaceable> have the name
1327 <literal>is<replaceable>X</replaceable></literal>.
1333 <sect3 id="sec-library-naming-conversions">
1334 <title>Names for conversions</title>
1335 <indexterm><primary>Names for conversions</primary></indexterm>
1339 <para>Functions converting a value of type
1340 <replaceable>X</replaceable> to a value of type
1341 <replaceable>Y</replaceable> have the name
1342 <literal><replaceable>X</replaceable>To<replaceable>Y</replaceable></literal>
1343 with all leading uppercase characters of
1344 <replaceable>X</replaceable> converted to lower case,
1345 e.g. <literal>stToIO</literal>.</para>
1349 <para>Overloaded conversion functions of type
1350 <literal>C a => a -> <replaceable>X</replaceable></literal>
1352 <literal>to<replaceable>X</replaceable></literal>,
1353 e.g. <literal>toInteger</literal>.</para>
1357 <para> Overloaded conversion functions of type
1358 <literal>C a => <replaceable>X</replaceable> -> a</literal>
1359 have the name <literal>from<replaceable>X</replaceable></literal>,
1360 e.g. <literal>fromInteger</literal>.</para>
1365 <sect3 id="sec-library-misc-names">
1366 <title>Miscellaneous naming conventions</title>
1367 <indexterm><primary>Miscellaneous naming
1368 conventions</primary></indexterm>
1372 <para> An action that is identical to another one called
1373 <replaceable>X</replaceable>, but discards the return
1375 <literal><replaceable>X</replaceable>_</literal>,
1376 e.g. <literal>mapM</literal> and <literal>mapM_</literal>.
1381 <para>Functions and actions which are potentially
1382 dangerous to use and leave some kind of proof obligation
1383 to the programmer have the name
1384 <literal>unsafe<replaceable>X</replaceable></literal>,
1385 e.g. <literal>unsafePerformIO</literal>.
1390 <para>There are two conventions for binary and N-ary
1391 variants of an associative operation: One convention uses
1392 an operator or a short name for the binary operation and a
1393 long name for the N-ary variant,
1394 e.g. <literal>(+)</literal> and <literal>sum</literal>,
1395 <literal>max</literal> and <literal>maximum</literal>. The
1396 other convention suffixes the N-ary variant with
1397 <literal>Many</literal>. (<emphasis>TODO</emphasis>: Add
1402 <para>If possible, names are chosen such that either plain
1403 application or <literal>arg1 `operation` arg2</literal> is
1404 correct English, e.g. <literal>isPrefixOf</literal> is
1405 good for use in backquotes.</para>
1411 <sect2 id="sec-library-misc-conventions">
1412 <title>Library design guidelines</title>
1416 <para>Actions setting and modifying a kind of reference or
1417 state return <literal>()</literal>, getting the value is
1418 separate, e.g. <literal>writeIORef</literal> and
1419 <literal>modifyIORef</literal> both return
1420 <literal>()</literal>, only <literal>readIORef</literal>
1421 returns the value in an <literal>IORef</literal>
1426 <para>A function or action taking a some kind of state and
1427 returning a pair consisting of a result and a new state, the
1428 result is the first element of the pair and the new state is
1429 the second, see e.g. <literal>Random</literal>.</para>
1433 <para>When the type <literal>Either</literal> is used to
1434 encode an error condition and a normal result,
1435 <literal>Left</literal> is used for the former and
1436 <literal>Right</literal> for the latter, see
1437 e.g. <literal>Control.Monad.Error</literal>.</para>
1441 <para>A module corresponding to a class
1442 (e.g. <literal>Bits</literal>) contains the class
1443 definition, perhaps some auxiliary functions, and all
1444 sensible instances for Prelude types, but nothing
1445 more. Other modules containing types for which an instance
1446 for the class in question makes sense contain the code for
1447 the instance itself.</para>
1451 <para>Record-like C bit fields or structs have a
1452 record-like interface, i.e. pure getting and setting of
1453 fields. (<emphasis>TODO</emphasis>: Clarify a little
1454 bit. Add examples.)</para>
1458 <para>Although the possibility of partial application
1461 <literal><replaceable>attr</replaceable> -> <replaceable>object</replaceable> -> <replaceable>object</replaceable></literal>
1463 for functions setting an attribute or value, infix notation
1464 with backquotes implies
1466 <literal><replaceable>object</replaceable> -> <replaceable>attr</replaceable> -> <replaceable>object</replaceable></literal>.
1468 (<emphasis>TODO</emphasis>: Add Examples.)</para>
1472 <para>Conditional interfaces: a library interface should
1473 vary between versions of the library only, not between
1474 platforms or Haskell implementations. Such differences may
1475 be visible at the module level only, so for example module
1476 <literal>System.Win32</literal> would be available on Win32
1477 systems only, and <literal>GHC.Exts</literal> would only be
1478 available when compiling with GHC.</para>
1486 <title>Changes to standard Haskell 98 libraries</title>
1488 <para>Some changes have been made to the standard Haskell 98
1489 libraries in the new library scheme, both in the names of the
1490 modules themselves and in their exported interfaces. Below is a
1491 summary of those changes - at this time, the new libraries are
1492 marked as provisional and are maintained by
1493 <email>libraries@haskell.org</email>, so changes in the interfaces
1494 are all up for discussion.</para>
1497 modules with interface changes
1498 ------------------------------
1501 added instance Typeable (Array ix a)
1504 no interface changes (should have instance Typeable?)
1506 Complex -> Data.Complex
1507 added instance Typeable (Complex a)
1511 hPutBuf :: Handle -> Ptr a -> Int -> IO ()
1512 hGetBuf :: Handle -> Ptr a -> Int -> IO Int
1513 fixIO :: (a -> IO a) -> IO a
1514 hSetEcho :: Handle -> Bool -> IO ()
1515 hGetEcho :: Handle -> IO Bool
1516 hIsTerminalDevice :: Handle -> IO Bool
1521 System -> System.Exit, System.Environment, System.Cmd
1522 split into three modules
1524 just renamed, no interface changes:
1525 -----------------------------------
1527 CPUTTime -> System.CPUTime
1528 Directory -> System.IO.Directory
1530 Locale -> System.Locale
1534 Random -> System.Random