1 <!DOCTYPE ARTICLE PUBLIC "-//OASIS//DTD DocBook V3.1//EN">
3 <article id="libraries">
5 <title>Haskell Libraries</title>
6 <orgname>The Haskell Libraries Mailing List</orgname>
7 <address><email>libraries@haskell.org</email></address>
10 <sect1 id="introduction">
11 <title>Introduction</title>
13 <para>This document consistutes a proposal for an extension to the
14 <ulink url="http://www.haskell.org/onlinereport/">Haskell
15 98</ulink> language. The proposal has several parts: </para>
19 <para>A modest language extension to Haskell 98 that adds the
20 character <quote>.</quote> to the lexical syntax for a module
21 name, allowing a hierarchical module namespace where a module
22 name is a sequence of components separated by periods. The
23 extension is described in <xref
24 linkend="language-extension">.</para>
27 <para>An allocation of the new module namespace to existing
28 and non-existent libraries, people, organisations, and local
32 <para>A policy and procedure for allocating new parts of the
36 <para>A set of libraries which are under the control of the
37 community, have reference implementations kept in a standard
38 place, and conform to a set of guidelines and policies set out
39 in this document. We shall call this set of libraries the
40 <firstterm>core libraries</firstterm>.</para>
44 <para>In addition, this document also describes:</para>
48 <para>Guidelines and conventions for organising the
52 <para>Our policy with respect to the design and evolution of
53 library APIs, versioning of library APIs, and maintenance of
54 the reference implementation.</para>
57 <para>A set of conventions for coding style and portability
58 within the core libraries.</para>
63 <sect1 id="contributing">
64 <title>How to contribute</title>
66 <para>This project is driven by the Haskell community, so
67 contributions of all kinds are welcome. The first step is to join
69 url="http://www.haskell.org/mailman/listinfo/libraries">Haskell
70 libraries mailing list</ulink>, and maybe <ulink
71 url="http://www.haskell.org/pipermail/libraries/">browse the list
72 archives</ulink>. Some of the ways you can contribute are:</para>
76 <para>By donating code: for libraries in the core set which
77 don't yet have a reference implementation, or for new
78 contributions to the core set, code is always welcome. Code
79 that conforms to the style guidelines (which aren't very
80 strict, see <xref linkend="conventions">) and comes with
81 documentation (<xref linkend="documentation">) and a test
82 suite (<xref linkend="testing">) is better, but these aren't
83 essential. As a library progresses through the stability
84 scale (<xref linkend="stability">) these things become more
85 important, but for an experimental library we're not going to
86 worry too much about this stuff.</para>
89 <para>By porting code for an existing library to a new
90 compiler or architecture. A library is classed as portable if
91 it should be available regardless of which compiler/platform
92 combination you're using; however, many libraries are
93 non-portable for one reason or another (see <xref
94 linkend="portability">, and broadening the scope of these
95 libraries is always welcome.</para>
98 <para>Become a library maintainer: if you have a particular
99 interest in and/or knowledge about a certain library, and have
100 the time to spare, and the library in question doesn't already
101 have a maintainer, then you may be a suitable maintainer for
102 the library. The responsibilities of library maintainers are
103 given in <xref linkend="maintainership">. </para>
106 <para>Participating in the design process for new libraries,
107 and suggesting improvements to existing libraries. Everyone
109 url="http://www.haskell.org/mailman/listinfo/libraries">Haskell
110 libraries mailing list</ulink> is invited to
111 participate in the design process, so get involved!</para>
116 <sect1 id="language-extension">
117 <title>The language extension</title>
119 <para>The key concept here is to map the module namespace into a
120 hierarchical directory-like structure. We propose using the dot as
121 a separator, analogous to Java's usage for namespaces.</para>
123 <para>For most compilers and interpreters, this extended module
124 namespace maps directly to a directory/file structure in which the
125 modules are stored. Storing unrelated modules in separate
126 directories (and related modules in the same directory) is a
127 useful and common practice when engineering large systems.</para>
129 <para>(But note that, just as Haskell'98 does not insist that
130 modules live in files of the same name, this proposal does not
131 insist on it either. However, we expect most tools to use the
132 close correspondance to their advantage.)</para>
134 <para>There are several issues arising from this proposal
135 proposal here. </para>
137 <para>This is a surface change to the module naming convention. It
138 does not introduce nested definition of modules. The syntax we
139 propose (a dot separator) is familiar from other languages such as
140 Java, but could in principle be something else, for instance a
141 prime <literal>'</literal>, underscore <literal>_</literal> or
142 centred dot <literal>ċ</literal> or something different
143 again. Of the choices of separator, dot requires a change to the
144 Haskell'98 lexical syntax, allowing</para>
148 qconid -> [modid .] conid
151 <para>where currently the syntax is</para>
155 qconid -> [modid .] conid
158 <para>Note that the new syntax is recursive, a
159 <literal>modid</literal> may contain multiple components separated
160 by dots, where the final component is a <literal>conid</literal>.</para>
162 <para>A consequence of using the dot as the module namespace
163 separator is that it steals one extremely rare construction from
170 <para>in Haskell'98 means the composition of constructor D from
171 module C, with constructor B from module A:</para>
177 <para>No-one so far thinks this is any great loss, and if you
178 really want to say the latter, you still can by simply inserting
186 <title>A possible extension</title>
188 <para>The use of qualified imports has become more verbose: for
192 import qualified XmlParse
193 ... XmlParse.element f ...
199 import qualified Text.Xml.Parse
200 ... Text.Xml.Parse.element f ...
203 <para>It is usually more convenient to make use of Haskell's
204 <literal>as</literal> keyword to shorten qualified identifiers:</para>
207 import qualified Text.Xml.Parse as Parse
208 ... Parse.element f ...
211 <para>A possible extension to the proposal is to make this use
212 of <literal>as</literal> implicit, unless overridden by the
213 programmer with her own <literal>as</literal> clause. The
214 implicit <literal>as</literal> clause always uses the final
215 subdivision of the module name. So for instance, either the
216 fully-qualified or abbreviated-qualified names</para>
219 Text.Xml.Parse.element
223 <para>would be accepted and have the same referent, but a
224 partial qualification like</para>
230 <para>would not be accepted.</para>
234 <title>Renaming subtrees</title>
236 <para>Various proposals have been made to allow you to rename a
237 whole subtree. This may occasionally be convenient: for example
238 suppose there are several libraries under
239 <literal>Org.Com.Microsoft</literal> that I need to import, it
240 would be easier to rename this subtree to just
241 <literal>Microsoft</literal> for use in future import
242 declarations. For example:</para>
245 import Org.Com.Microsoft.* as Microsoft.*
251 <para>The exact syntax of the renaming declaration is up for
252 debate (as is whether we need it at all), please send
253 suggestions to <email>libraries@haskell.org</email>.</para>
259 <title>The hierarchy layout</title>
261 <para>We first classify each node in the hierarchy according to
262 one of the following terms:</para>
266 <term>Allocated</term>
268 <para>Nodes in the hierarchy can be allocated to a library
269 (whether the library actually exists or not). The currently
270 allocated nodes are specified in <xref
271 linkend="hierarchy">.</para>
278 <para>The <literal>User</literal> hierarchy is reserved for
279 users: a user may always use the portion of the hierarchy
280 which is formed from his/her email address as follows:
281 replace the <literal>@</literal> by a <literal>.</literal>,
282 reverse the order of the components, capitalise the first
283 letter of each component, and prepend
284 <literal>User.</literal>. For example,
285 <literal>simonmar@microsoft.com</literal> becomes
286 <literal>User.Com.Microsoft.Simonmar</literal>.</para>
291 <term>Organisation</term>
293 <para>The <literal>Org</literal> hierarchy is reserved for
294 organisations. Any organisation with a DNS domain name owns
295 a unique space in the hierarchy formed by reversing the
296 components of the domain, capitalising the first character
297 of each component, and prepending <literal>Org.</literal>.
298 <emphasis>ToDo: the Org name isn't great, especially when
299 the domain name also ends with Org (eg. Org.Org.Haskell?).
300 Contrib has also been suggested.</emphasis></para>
307 <para>The <literal>Local</literal> hierarchy is reserved for
308 libraries which are local to the current site. Libraries
309 which are to be distributed outside the current site should
310 not be placed in the <literal>Local</literal>
316 <term>Top-level</term>
318 <para>All top-level names (i.e. module names that don't
319 contain a <quote><literal>.</literal></quote>) that are
320 otherwise unallocated, are available for use by the program.
321 Note that for compabibility with Haskell 98, some modules in
322 this namespace are reserved
323 (eg. <literal>Directory</literal>, <literal>IO</literal>,
324 <literal>Time</literal> etc.).</para>
329 <term>Unallocated</term>
331 <para>Any node which doesn't belong to any of the above
332 categories is currently unallocated, and is not available
338 <para>A node in the hierarchy may be both a specific library and a
339 parent node for a number of child nodes. For example,
340 <literal>Foreign</literal> is a library, and so is
341 <literal>Foreign.Ptr</literal>.</para>
343 <sect2 id="hierarchy-design-guidelines">
344 <title>Hierarchy design guidelines</title>
345 <para>Apart from the User, Local and Organisation top-level
346 categories, the rest of the hierarchy is organised with a single
347 principle in mind:</para>
350 <para>Modules are grouped by
351 <emphasis>functionality</emphasis>, since this is the single
352 property that is most helpful for a user of the library - we
353 want users to be able to find out where to obtain
354 functionality easily, and to easily find all the modules that
355 provide relevant functionality.</para>
357 <para>So, if two modules provide similar functionality, or
358 alternative interfaces to the same functionality, then they
359 should be children of the same node in the hierarchy. Modules
360 are never grouped by standards compliance, portability,
361 stability, or any other property.</para>
365 <sect2 id="module-naming-convention">
366 <title>Module Naming Conventions</title>
370 <para>A module defining a data type or type class
371 <replaceable>X</replaceable> has itself the name
372 <replaceable>X</replaceable>, e.g.
373 <literal>StablePtr</literal>.</para>
377 <para>A module which re-exports the modules in a subtree of
378 the hierarchy has the same name as the root of that subtree,
379 eg. <literal>Foreign</literal> re-exports
380 <literal>Foreign.Ptr</literal>,
381 <literal>Foreign.Marshal.Utils</literal> etc.</para>
385 <para>If a subtree of the hierarchy contains several modules
386 which provide similar functionality (eg. there are several
387 pretty-printing libraries under
388 <literal>Text.PrettyPrinter</literal>), then the module at
389 the root of the subtree generally re-exports just
390 <emphasis>one</emphasis> of the modules in the subtree
391 (possibly the most popular or commonly-used
396 <para>In Haskell you sometimes publish
397 <emphasis>two</emphasis> interfaces to your libraries; one
398 for users, and one for library writers or advanced users who
399 might want to extend things. Typically the advanced users
400 need to be able to see past certain abstractions.</para>
402 <para>The current proposal is for a module named
403 <literal>M</literal>, the <quote>advanced</quote> version
404 would be named <literal>M.Internals</literal>. eg.</para>
407 import Text.HTML -- The library
408 import Text.HTML.Internals -- The non-abstract library
413 <para>Acronyms are fully capitalised in a module name.
414 eg. <literal>HTML</literal>, <literal>URI</literal>,
415 <literal>CGI</literal>, etc. Exceptions may be made for
416 acronyms which have an existing well-established alternative
417 capitalisation, or acronyms which are also valid words, and
418 are more often used as such.</para>
422 <para>A module name should be made plural only if the module
423 actually defines multiple entities of a particular kind:
424 eg. <literal>Foreign.C.Types</literal>. Most module names
425 which define a type or class will follow the name of the
426 type or class, so whether to pluralize is not an
432 <sect2 id="hierarchy">
433 <title>The hierarchy</title>
435 <para>The currently allocated top-level names are:</para>
439 <term><literal>Prelude</literal></term>
441 <para>Haskell98 Prelude (mostly just re-exports other
442 parts of the tree).</para>
447 <term><literal>Control</literal></term>
449 <para> Libraries which provide functions, types or classes
450 whose purpose is primarily to express control
456 <term><literal>Data</literal></term>
458 <para>Libraries which provide data types, operations over
459 data types, or type classes, except for libraries for
460 which one of the other more specific categories is
466 <term><literal>Database</literal></term>
468 <para>Libraries for providing access to or operations for
469 building databases.</para>
474 <term><literal>Debug</literal></term>
476 <para>Support for debugging Haskell programs.</para>
481 <term><literal>Edison</literal></term>
483 <para>The Edison data structure library.</para>
488 <term><literal>FileFormat</literal></term>
490 <para>Support for reading and/or writing various file
491 formats (except: programming language source code which
492 lives in <literal>Language</literal>, database formats
493 which live in <literal>Database</literal>, and textual
494 file formats which are catered for in
495 <literal>Text</literal>).</para>
500 <term><literal>Foreign</literal></term>
502 <para>Interaction with code written in a foreign
503 programming language.</para>
508 <term><literal>Graphics</literal></term>
510 <para>Libraries for producing graphics or providing
511 graphical user interfaces.</para>
516 <term><literal>Language</literal></term>
518 <para>Libraries for operating on or generating source code
519 in various programming languages, including parsers,
520 pretty printers, abstract syntax definitions etc.</para>
525 <term><literal>Local</literal></term>
527 <para>Available for site-local use.</para>
532 <term><literal>Numeric</literal></term>
534 <para>Functions and classes which provide operations over
540 <term><literal>Network</literal></term>
542 <para>Libraries for communicating over a network,
543 including implementations of network protocols.</para>
548 <term><literal>Org</literal></term>
550 <para>Allocated to organisations on a domain-name
551 basis (see <xref linkend="layout">).</para>
556 <term><literal>System</literal></term>
558 <para>Libraries for communication with the system on which
559 the Haskell program is running (including the runtime
565 <term><literal>Text</literal></term>
567 <para>Libraries for parsing and generating data in a
568 textual format (including structured textual formats such
569 as XML, HTML, but not including programming language
570 source, which lives in Language).</para>
575 <term><literal>GHC</literal></term>
577 <para>Libraries specific to the GHC/GHCi system.</para>
582 <term><literal>Nhc</literal></term>
584 <para>Libraries specific to the Nhc compiler.</para>
589 <term><literal>Hugs</literal></term>
591 <para>Libraries specific to the Hugs system.</para>
596 <term><literal>User</literal></term>
598 <para>Allocated to individual users, using email
599 addresses (see <xref linkend="layout">).</para>
606 <sect1 id="licensing">
607 <title>Licensing</title>
609 <para>Following some discussion on the mailing list related to how
610 we should license the libraries, the viewpoint that was least
611 offensive to all involved seems to be the following:</para>
613 <para>We wish to accomodate source code from different
614 contributors, and with different licenses. However, a library of
615 modules where each module is released under a different license,
616 and where the dependencies between modules aren't clear, isn't
617 workable (it's too hard for a user of the library to tell whether
618 they're violating the terms of the each license or not).</para>
620 <para>So the solution is as follows: code under different licenses
621 will be clearly separate in the repository (i.e. in separate
622 subdirectories), and compilers are expected to present packages of
623 modules where all modules in a package fall under the same
624 license, and where the dependencies between packages are
627 <para>It was decided that certain essential functionality should
628 be available under a BSD style license. Hence, the BSD part of
629 the repository will contain implementations of at least the
630 following modules: <literal>Prelude</literal>,
631 <literal>Foreign</literal>, <emphasis>ToDo: what
632 else?</emphasis>.</para>
634 <para><emphasis>ToDo: include a prototype BSD license
635 here</emphasis>.</para>
638 <sect1 id="versioning">
639 <title>Versioning</title>
643 <sect1 id="stability">
644 <title>Library Stability</title>
646 <para>The stability of a library relates primarily to its API.
647 Stability provides an indication of how often the API is likely to
648 change (or whether it may even go away entirely).</para>
650 <para>The stability scale is also a measure of how strictly the
651 conventions in this document are applied to the library: an
652 experimental library isn't subject to any restrictions regarding
653 coding style and documentation, but a stable library is expected
654 to adhere to the guidelines, and come with full documentation and
657 <para>To help with the stability issue, library maintainers are
658 allowed to mark functions, types or classes as
659 <firstterm>deprecated</firstterm><footnote><para>Compilers may have
660 extra support for warning about the use of a deprecated feature, for
661 example GHC's <literal>DEPRECATED</literal> pragma.</para>
662 </footnote>, which means simply that the
663 feature will be removed at a later date. Just how long it will
664 stick around for depends on the stability category of the library
665 (see below). A feature is marked as deprecated in the
666 documentation for the library, and optionally in an
667 implementation-dependent way which enables the system to warn
668 about the use of deprecated features.</para>
670 <para>The current stability categories are:</para>
674 <term><firstterm>experimental</firstterm></term>
676 <para>An experimental library is unrestricted in terms of
677 API changes: the API may change between minor revisions and
678 there is no requirement to retain old interfaces for
679 compatibility. Documentation and tests aren't required for
680 an experimental library.</para>
684 <term><firstterm>provisional</firstterm></term>
686 <para>A provisional library is moving towards stability, and
687 the rate of change of the API is slower. API changes
688 between minor revisions must be accompanied by deprecated
689 versions of the old features where possible. API changes
690 between major versions are unrestricted. The library should
691 come with at least rudimentary documentation.</para>
695 <term><firstterm>stable</firstterm></term>
697 <para>A stable library has an essentially fixed API.
698 Additions to the API may be made for a minor release,
699 deprecated features must be retained for at least one major
700 revision, and small changes only may be made to the existing
701 API semantics for a major revision. A stable library is
702 expected to include full documentation and tests.</para>
709 <sect1 id="portability">
710 <title>Portability Considerations</title>
712 <para>The portability status of a library affects under which
713 platforms and compilers the library will be available on. Haskell
714 implementations are expected to provide all of the portable core
715 libraries, and those non-portable core libraries which are
716 appropriate for that particular platform/compiler
717 implementation.</para>
719 <para>The precise meaning of the terms portable and non-portable
720 for our purposes are given below:</para>
724 <term><firstterm>Portable</firstterm></term>
726 <para>A portable library may use only Haskell 98 features
727 plus approved extensions, and may not use any
728 platform-specific features. It may make use of other
729 portable libraries only.</para>
733 <term><firstterm>Non-portable</firstterm></term>
735 <para>A non-portable library may be non-portable for one or
736 more of the following reasons:</para>
739 <term><firstterm>Requires extensions</firstterm></term>
741 <para>A library which uses non-approved language
746 <term><firstterm>Requires nonportable libraries</firstterm></term>
748 <para>A library which depends (directly or indirectly)
749 on other non-portable libraries.</para>
753 <term><firstterm>OS-specific</firstterm></term>
754 <term><firstterm>Platform-specific</firstterm></term>
756 <para>A library which depends on features or APIs
757 particular to a certain OS or platform is non-portable
758 for that reason.</para>
767 <title>Approved Extensions</title>
769 <para>Very few of the core libraries can be implemented using
770 pure Haskell 98. For this reason, we decided to raise the
771 baseline for portable libraries to include a few common
772 extensions; the following langauge extensions can be
773 <emphasis>assumed</emphasis> to be present when writing
779 url="http://haskell.org/ghc/docs/latest/set/ffi.html">Foreign
780 Function Interface</ulink>.</para>
783 <para>Mutable variables
784 (<literal>Data.IORef</literal>).</para>
787 <para>Unsafe IO monad operations
788 (<literal>System.IO.Unsafe</literal>).</para>
792 (<literal>Data.PackedString</literal>).</para>
796 <para>Extensions which we'd like to be standard, but aren't
797 currently implemented by one or more of the target
802 <para>Bit operations (<literal>Data.Bits</literal>).</para>
805 <para>Exceptions (synchronous only), defined by the
806 <literal>Control.Exception</literal> interface.</para>
809 <para>The ST monad, defined by
810 <literal>Control.Monad.ST</literal>, and the associated
811 <literal>Data.Array.ST</literal> and
812 <literal>Data.STRef</literal> libraries. ST requires a
813 small typechecker extension for the <literal>runST</literal>
817 <para>Concurrent Haskell (pre-emptive multitasking
818 optional). GHC and Hugs implement this, but Nhc currently
823 <para>The following extensions are not likely to become part of
824 the baseline, but are nevertheless used by one or more libraries
825 in the core set (which are thus designated non-portable):</para>
829 <para>Multi-parameter type classes.</para>
832 <para>Local unversal and existential quantification.</para>
835 <para>Concurrent Haskell with pre-emptive multitasking.</para>
838 <para>Asynchronous exceptions.</para>
841 <para>Stable Names.</para>
844 <para>Weak Pointers.</para>
848 <para>Other extensions are supported by a single compiler only,
849 and can be accessed by libraries under the top level hierarchy
851 eg. <literal>GHC.UnboxedTypes</literal>.</para>
855 <sect1 id="maintainership">
856 <title>Library Maintainers</title>
858 <para>This is a collaborative project, so we like to devolve
859 control of the design and implementation of libraries to those
860 with an interest or appropriate expertise (or maybe just the
861 time!). A maintainer isn't necessarily a single person - for
862 example, the listed maintainer for most of the core libraries is
863 <email>libraries@haskell.org</email>, indicating that the library
864 is under the control of the community as a whole. The maintainer
865 for the <literal>Foreign</literal> hierarchy is
866 <email>ffi@haskell.org</email>, the mailing list for discussion of
867 the Haskell FFI standard.</para>
869 <para>The responsibilities of a library maintainer include:</para>
873 <para>Most importantly: act as a single point of contact for
874 issues relating to the library API and its
875 implementation.</para>
878 <para>Manage any discussion related to the library (which can
879 take place on <email>libraries.haskell.org</email> if
880 necessary), and summarise the results. Make final decisions,
881 and implement them.</para>
884 <para>Maintain the implementation, including: fixing bugs,
885 updating to keep up with changes in other libraries, porting
886 to new compilers/platforms, and integrating code from other
887 contributors. The maintainer is expected to be the only
888 person/group to make functional changes to the source code
889 (non-functional or trivial changes don't count).</para>
892 <para>Maintain/write the documentation and tests.</para>
895 <para>If you can't maintain the library any more for whatever
896 reason, tell <email>libraries@haskell.org</email> and we'll
897 revert the maintainer status of the library to the
902 <sect2 id="core-team">
903 <title>The Core Team</title>
905 <para>The core team is responsible for making final decisions
906 about the project as a whole and resolving disputes where
907 necessary. We expect that needing to invoke the core team will
908 be a rare occurrence.</para>
910 <para>The core team is also responsible for approving
911 maintainership requests.</para>
913 <para>Currently, the core team consists of one person from each
914 of the compiler camps, and these are also the people that will
915 primarily be maintaining the library framework for their
916 respective compiler projects:</para>
921 <email>simonmar@microsoft.com</email> (GHC representative)</para>
924 <para>Malcolm Wallace
925 <email>Malcolm.Wallace@cs.york.ac.uk</email> (Nhc representative)</para>
929 <email>andy@galconn.com</email> (Hugs representative)</para>
936 <sect1 id="documentation">
937 <title>Documentation</title>
942 <title>Testing</title>
946 <sect1 id="Migration-path">
947 <title>Migration path</title>
949 <para>How compatible will a compiler using the new libraries be
950 with code written for Haskell 98 or older library systems (such as
951 the <literal>hslibs</literal> suite and GHC's package system), and
952 for how long will compatibility be maintained?</para>
954 <para>Our current plan for GHC is as follows: by default, with the
955 <option>-fglasgow-exts</option> flag, you'll get access to the
956 core libraries. Compatibility with Haskell 98 code will be
957 maintained using a separate package of wrappers presenting
958 interfaces for the Haskell 98 libraries (<literal>IO</literal>,
959 <literal>Ratio</literal>, <literal>Directory</literal>, etc.).
960 The Haskell 98 compatibility package will be enabled by default,
961 but we plan to add an option to disable it if necessary. For code
962 that uses <literal>-package lang</literal>, we could also provide
963 a compatibility wrapper package (so <literal>-package
964 lang</literal> will continue to work as before and present the
965 same library interfaces), but this may prove too much work to
966 maintain - we haven't decided whether to do this or not. It is
967 unlikely that compatibility wrappers for any of the other
968 <literal>hslibs</literal> packages will be provided.</para>
971 <sect1 id="conventions">
972 <title>Programming Conventions</title>
974 <sect2 id="module-header">
975 <title>Standard Module Header</title> <para>The following module
976 header will be used for all core libraries, and we recommend
977 using it for library source code in general:</para>
980 -----------------------------------------------------------------------------
982 -- Module : <replaceable>module</replaceable>
983 -- Copyright : (c) <replaceable>author</replaceable> <replaceable>year</replaceable>
984 -- License : <replaceable>license</replaceable>
986 -- Maintainer : libraries@haskell.org | <replaceable>email-address</replaceable>
987 -- Stability : experimental | provisional | stable
988 -- Portability : portable | non-portable (<replaceable>reason(s)</replaceable>)
990 -- $Id: libraries.sgml,v 1.5 2001/08/30 13:36:00 simonmar Exp $
992 -- <replaceable>Description</replaceable>
993 -----------------------------------------------------------------------------
1000 <term><literal>$Id: libraries.sgml,v 1.5 2001/08/30 13:36:00 simonmar Exp $</literal></term>
1002 <para>is optional, but usually included if the module is
1003 under CVS or RCS control.</para>
1008 <term><replaceable>module</replaceable></term>
1010 <para>is the fully qualified module name of the
1016 <term><replaceable>author</replaceable>/<replaceable>year</replaceable></term>
1018 <para>Is the primary author and copyright holder of the
1019 module, and the year in which copyright is claimed.</para>
1024 <term><replaceable>license</replaceable></term>
1026 <para>Specifies the license on the file (see <xref
1027 linkend="licensing">).</para>
1032 <term><replaceable>email-address</replaceable></term>
1034 <para>The email address of the maintainer, or maintainers,
1035 of the library (see <xref linkend="maintainership">).</para>
1040 <term><replaceable>reason(s)</replaceable></term>
1042 <para>The reasons for non-portability must be listed (see
1043 <xref linkend="portability">).</para>
1048 <term><replaceable>description</replaceable></term>
1050 <para>A short description of the module.</para>
1057 <sect2 id="naming-conventions">
1058 <title>Naming Conventions</title>
1060 <para>These naming conventions are pulled straight from the
1061 <literal>hslibs</literal> documentation. They were formed after
1062 lengthy discussions and are heavily based on an initial
1063 suggestion from Marcin Kowalczyk
1064 <email>qrczak@knm.org.pl</email>.</para>
1066 <para>Note that the conventions are not mutually exclusive,
1067 e.g. should the function creating a set from a list of elements
1068 have the name <Literal>set</Literal> or
1069 <Literal>listToSet</Literal>? (Alas, it currently has neither
1072 <para> The following nomenclature is used: Pure,
1073 i.e. non-monadic functions are simply called, well,
1074 <emphasis>functions</emphasis>. Monadic functions,
1075 i.e. functions having a type <Literal>... -> m a</Literal>
1076 for some Monad <Literal>m</Literal> are called
1077 <emphasis>actions</emphasis>.</para>
1079 <sect3 id="sec-library-constructor-names">
1080 <title>Constructor names</title>
1081 <indexterm><primary>Constructor names</primary></indexterm>
1085 <para>Empty values of type <replaceable>X</replaceable>
1086 have the name <Literal>empty<replaceable>X</replaceable></Literal>,
1087 e.g. <literal>emptySet</literal>.</para>
1091 <para>Actions creating a new empty value of type
1092 <replaceable>X</replaceable> have the name
1093 <literal>newEmpty<replaceable>X</replaceable></literal>,
1094 e.g. <literal>newEmptyMVar</literal>.</para>
1098 <para>Functions creating an arbitrary value of type
1099 <replaceable>X</replaceable> have the name
1100 <replaceable>X</replaceable> itself (with the first letter
1102 e.g. <literal>array</literal>. (<emphasis>TODO</emphasis>:
1103 This often collides with <literal>xToY</literal>
1104 convention, how should this be resolved?)
1109 <para>Actions creating new values arbitrary values of type
1110 <replaceable>X</replaceable> have the name
1111 <literal>new<replaceable>X</replaceable></literal>,
1112 e.g. <literal>newIORef</literal>.
1118 <sect3 id="sec-library-accessor-names">
1119 <title>Accessor names</title>
1120 <indexterm><primary>Accessor names</primary></indexterm>
1124 <para>Functions getting an attribute of a value or a part
1125 of it have the name of the attribute itself,
1126 e.g. <literal>length</literal>, <literal>bounds</literal>.
1131 <para> Actions accessing some kind of reference or state
1133 <literal>get<replaceable>X</replaceable></literal>, where
1134 <replaceable>X</replaceable> is the type of the contents
1135 or the name of the part being accessed,
1136 e.g. <literal>getChar</literal>,
1137 <literal>getEnv</literal>. An alternative naming scheme is
1138 <literal>read<replaceable>Y</replaceable></literal>,
1139 where <replaceable>Y</replaceable> is the type of the
1140 reference or container, e.g. <literal>readIORef</literal>.
1145 <para>Functions or actions getting a value via a
1146 pointer-like type <replaceable>X</replaceable> should be
1148 <literal>deRef<replaceable>X</replaceable></literal>,
1149 e.g. <literal>deRefStablePtr</literal>,
1150 <literal>deRefWeak</literal>.</para>
1155 <sect3 id="sec-library-modifier-names">
1156 <title>Modifier names</title>
1157 <indexterm><primary>Modifier names</primary></indexterm>
1161 <para>Functions returning a value with attribute
1162 <replaceable>X</replaceable> set to a new value should be
1164 <literal>set<replaceable>X</replaceable></literal>. (<emphasis>TODO</emphasis>:
1165 Add Examples.)</para>
1169 <para> Actions setting some kind of reference or state
1171 <literal>put<replaceable>X</replaceable></literal>, where
1172 <replaceable>X</replaceable> is the type of the contents
1173 or the name of the part being accessed,
1174 e.g. <literal>putChar</literal>. An alternative naming
1176 <literal>write<replaceable>Y</replaceable></literal>,
1177 where <replaceable>X</replaceable> is the type of the
1178 reference or container,
1179 e.g. <literal>writeIORef</literal>. </para></listitem>
1182 <para> Actions in the <literal>IO</literal> monad setting
1183 some global state <replaceable>X</replaceable> are
1184 traditionally named <literal>setX</literal>, too, although
1185 <literal>put<replaceable>X</replaceable></literal> would
1186 be more appropriate,
1187 e.g. <literal>setReadlineName</literal>.</para>
1191 <para> Actions modifying a container
1192 <replaceable>X</replaceable> by a function of type
1193 <literal>a -> a</literal> have the name
1194 <literal>modify<replaceable>X</replaceable></literal>,
1195 e.g. <literal>modifySTRef</literal>.</para>
1200 <sect3 id="sec-library-predicate-names">
1201 <title>Predicate names</title>
1202 <indexterm><primary>Predicate names</primary></indexterm>
1206 <para>Predicates, both non-monadic and monadic, testing a
1207 property <replaceable>X</replaceable> have the name
1208 <literal>is<replaceable>X</replaceable></literal>.
1214 <sect3 id="sec-library-naming-conversions">
1215 <title>Names for conversions</title>
1216 <indexterm><primary>Names for conversions</primary></indexterm>
1220 <para>Functions converting a value of type
1221 <replaceable>X</replaceable> to a value of type
1222 <replaceable>Y</replaceable> have the name
1223 <literal><replaceable>X</replaceable>To<replaceable>Y</replaceable></literal>
1224 with all leading uppercase characters of
1225 <replaceable>X</replaceable> converted to lower case,
1226 e.g. <literal>stToIO</literal>.</para>
1230 <para>Overloaded conversion functions of type
1231 <literal>C a => a -> <replaceable>X</replaceable></literal>
1233 <literal>to<replaceable>X</replaceable></literal>,
1234 e.g. <literal>toInteger</literal>.</para>
1238 <para> Overloaded conversion functions of type
1239 <literal>C a => <replaceable>X</replaceable> -> a</literal>
1240 have the name <literal>from<replaceable>X</replaceable></literal>,
1241 e.g. <literal>fromInteger</literal>.</para>
1246 <sect3 id="sec-library-misc-names">
1247 <title>Miscellaneous naming conventions</title>
1248 <indexterm><primary>Miscellaneous naming
1249 convetions</primary></indexterm>
1253 <para> An action that is identical to another one called
1254 <replaceable>X</replaceable>, but discards the return
1256 <literal><replaceable>X</replaceable>_</literal>,
1257 e.g. <literal>mapM</literal> and <literal>mapM_</literal>.
1262 <para>Functions and actions which are potentially
1263 dangerous to use and leave some kind of proof obligation
1264 to the programmer have the name
1265 <literal>unsafe<replaceable>X</replaceable></literal>,
1266 e.g. <literal>unsafePerformIO</literal>.
1271 <para>There are two conventions for binary and N-ary
1272 variants of an associative operation: One convention uses
1273 an operator or a short name for the binary operation and a
1274 long name for the N-ary variant,
1275 e.g. <literal>(+)</literal> and <literal>sum</literal>,
1276 <literal>max</literal> and <literal>maximum</literal>. The
1277 other convention suffixes the N-ary variant with
1278 <literal>Many</literal>. (<emphasis>TODO</emphasis>: Add
1283 <para>If possible, names are chosen such that either plain
1284 application or <literal>arg1 `operation` arg2</literal> is
1285 correct English, e.g. <literal>isPrefixOf</literal> is
1286 good for use in backquotes.</para>
1292 <sect2 id="sec-library-misc-conventions">
1293 <title>Library design conventions</title>
1297 <para>Actions setting and modifying a kind of reference or
1298 state return <literal>()</literal>, getting the value is
1299 separate, e.g. <literal>writeIORef</literal> and
1300 <literal>modifyIORef</literal> both return
1301 <literal>()</literal>, only <literal>readIORef</literal>
1302 returns the value in an <literal>IORef</literal>
1307 <para>A function or action taking a some kind of state and
1308 returning a pair consisting of a result and a new state, the
1309 result is the first element of the pair and the new state is
1310 the second, see e.g. <literal>Random</literal>.</para>
1314 <para>When the type <literal>Either</literal> is used to
1315 encode an error condition and a normal result,
1316 <literal>Left</literal> is used for the former and
1317 <literal>Right</literal> for the latter, see
1318 e.g. <literal>Control.Monad.Error</literal>.</para>
1322 <para>A module corresponding to a class
1323 (e.g. <literal>Bits</literal>) contains the class
1324 definition, perhaps some auxiliary functions, and all
1325 sensible instances for Prelude types, but nothing
1326 more. Other modules containing types for which an instance
1327 for the class in question makes sense contain the code for
1328 the instance itself.</para>
1332 <para>Record-like C bit fields or structs have a
1333 record-like interface, i.e. pure getting and setting of
1334 fields. (<emphasis>TODO</emphasis>: Clarify a little
1335 bit. Add examples.)</para>
1339 <para>Although the possibility of partial application
1342 <literal><replaceable>attr</replaceable> -> <replaceable>object</replaceable> -> <replaceable>object</replaceable></literal>
1344 for functions setting an attribute or value, infix notation
1345 with backquotes implies
1347 <literal><replaceable>object</replaceable> -> <replaceable>attr</replaceable> -> <replaceable>object</replaceable></literal>.
1349 (<emphasis>TODO</emphasis>: Add Examples.)</para>
1354 <sect2 id="coding-style">
1355 <title>Coding style conventions</title>
1362 <title>Changes to standard Haskell 98 libraries</title>
1364 <para>Some changes have been made to the standard Haskell 98
1365 libraries in the new library scheme, both in the names of the
1366 modules themselves and in their exported interfaces. Below is a
1367 summary of those changes - at this time, the new libraries are
1368 marked as provisional and are maintained by
1369 <email>libraries@haskell.org</email>, so changes in the interfaces
1370 are all up for discussion.</para>
1373 modules with interface changes
1374 ------------------------------
1377 added instance Typeable (Array ix a)
1380 no interface changes (should have instance Typeable?)
1382 Complex -> Data.Complex
1383 added instance Typeable (Complex a)
1387 hPutBuf :: Handle -> Ptr a -> Int -> IO ()
1388 hGetBuf :: Handle -> Ptr a -> Int -> IO Int
1389 fixIO :: (a -> IO a) -> IO a
1395 added showHex, showOct, showBin & showIntAtBase from NumExts,
1396 but left out floatToDouble & doubleToFloat (realToFrac is more general).
1398 System -> System.Exit, System.Environment, System.Cmd
1399 split into three modules
1401 just renamed, no interface changes:
1402 -----------------------------------
1404 CPUTTime -> System.CPUTime
1405 Directory -> System.IO.Directory
1407 Locale -> System.Locale
1409 Random -> System.Random