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>
264 ToDo: unpublished interfaces.
268 <term>Allocated</term>
270 <para>Nodes in the hierarchy can be allocated to a library
271 (whether the library actually exists or not). The currently
272 allocated nodes are specified in <xref
273 linkend="hierarchy">.</para>
280 <para>The <literal>User</literal> hierarchy is reserved for
281 users: a user may always use the portion of the hierarchy
282 which is formed from his/her email address as follows:
283 replace any <quote><literal>.</literal></quote>s in the
284 username (before the <literal>@</literal>) with
285 <quote><literal>_</literal></quote>, replace the
286 <quote><literal>@</literal></quote> by a
287 <quote><literal>.</literal></quote>, reverse the order of
288 the components, capitalise the first letter of each
289 component, and prepend
290 <quote><literal>User.</literal></quote>. For example,
291 <literal>simonmar@microsoft.com</literal> becomes
292 <literal>User.Com.Microsoft.Simonmar</literal>.</para>
297 <term>Organisation</term>
299 <para>The <literal>Org</literal> hierarchy is reserved for
300 organisations. Any organisation with a DNS domain name owns
301 a unique space in the hierarchy formed by reversing the
302 components of the domain, capitalising the first character
303 of each component, and prepending <literal>Org.</literal>.
304 <emphasis>ToDo: the Org name isn't great, especially when
305 the domain name also ends with Org (eg. Org.Org.Haskell?).
306 Contrib has also been suggested.</emphasis></para>
313 <para>The <literal>Local</literal> hierarchy is reserved for
314 libraries which are local to the current site. Libraries
315 which are to be distributed outside the current site should
316 not be placed in the <literal>Local</literal>
322 <term>Top-level</term>
324 <para>All top-level names (i.e. module names that don't
325 contain a <quote><literal>.</literal></quote>) that are
326 otherwise unallocated, are available for use by the program.
327 Note that for compabibility with Haskell 98, some modules in
328 this namespace are reserved
329 (eg. <literal>Directory</literal>, <literal>IO</literal>,
330 <literal>Time</literal> etc.).</para>
335 <term>Unallocated</term>
337 <para>Any node which doesn't belong to any of the above
338 categories is currently unallocated, and is not available
344 <para>A node in the hierarchy may be both a specific library and a
345 parent node for a number of child nodes. For example,
346 <literal>Foreign</literal> is a library, and so is
347 <literal>Foreign.Ptr</literal>.</para>
349 <sect2 id="hierarchy-design-guidelines">
350 <title>Hierarchy design guidelines</title>
351 <para>Apart from the User, Local and Organisation top-level
352 categories, the rest of the hierarchy is organised with a single
353 principle in mind:</para>
356 <para>Modules are grouped by
357 <emphasis>functionality</emphasis>, since this is the single
358 property that is most helpful for a user of the library - we
359 want users to be able to find out where to obtain
360 functionality easily, and to easily find all the modules that
361 provide relevant functionality.</para>
363 <para>So, if two modules provide similar functionality, or
364 alternative interfaces to the same functionality, then they
365 should be children of the same node in the hierarchy. Modules
366 are never grouped by standards compliance, portability,
367 stability, or any other property.</para>
370 <para>There are some other considerations when choosing where to
371 place libraries. Where possible, choose a layout that finds a
372 good compromise between depth of nesting and logical grouping of
373 functionality; for example, although the <literal>Text</literal>
374 hierarchy could logically be placed as a child of
375 <literal>FileFormat</literal>, we choose not to because
376 <literal>Text</literal> is ubiquitous and we don't want to have
377 to type the extra component all the time.</para>
379 <para>Also consider consistency: if a particular sub-hierarchy
380 provides similar functionality to another sub-hierarchy in the
381 tree, then preferably the structure of the two subtrees should
382 also be similar. For example: under
383 <literal>Language.Haskell</literal> we have children
384 <literal>Syntax</literal>, <literal>Lexer</literal>,
385 <literal>Parser</literal> etc., so under
386 <literal>Language.C</literal> we should have a similar
390 <sect2 id="module-naming-convention">
391 <title>Module Naming Conventions</title>
395 <para>A module defining a data type or type class
396 <replaceable>X</replaceable> has itself the name
397 <replaceable>X</replaceable>, e.g.
398 <literal>StablePtr</literal>.</para>
402 <para>A module which re-exports the modules in a subtree of
403 the hierarchy has the same name as the root of that subtree,
404 eg. <literal>Foreign</literal> re-exports
405 <literal>Foreign.Ptr</literal>,
406 <literal>Foreign.Marshal.Utils</literal> etc.</para>
410 <para>If a subtree of the hierarchy contains several modules
411 which provide similar functionality (eg. there are several
412 pretty-printing libraries under
413 <literal>Text.PrettyPrinter</literal>), then the module at
414 the root of the subtree generally re-exports just
415 <emphasis>one</emphasis> of the modules in the subtree
416 (possibly the most popular or commonly-used
421 <para>In Haskell you sometimes publish
422 <emphasis>two</emphasis> interfaces to your libraries; one
423 for users, and one for library writers or advanced users who
424 might want to extend things. Typically the advanced users
425 need to be able to see past certain abstractions.</para>
427 <para>The current proposal is for a module named
428 <literal>M</literal>, the <quote>advanced</quote> version
429 would be named <literal>M.Internals</literal>. eg.</para>
432 import Text.HTML -- The library
433 import Text.HTML.Internals -- The non-abstract library
438 <para>Acronyms are fully capitalised in a module name.
439 eg. <literal>HTML</literal>, <literal>URI</literal>,
440 <literal>CGI</literal>, etc. Exceptions may be made for
441 acronyms which have an existing well-established alternative
442 capitalisation, or acronyms which are also valid words, and
443 are more often used as such.</para>
447 <para>A module name should be made plural only if the module
448 actually defines multiple entities of a particular kind:
449 eg. <literal>Foreign.C.Types</literal>. Most module names
450 which define a type or class will follow the name of the
451 type or class, so whether to pluralize is not an
457 <sect2 id="hierarchy">
458 <title>The hierarchy</title>
460 <para>The currently allocated top-level names are:</para>
464 <term><literal>Prelude</literal></term>
466 <para>Haskell98 Prelude (mostly just re-exports other
467 parts of the tree).</para>
472 <term><literal>Control</literal></term>
474 <para> Libraries which provide functions, types or classes
475 whose purpose is primarily to express control
481 <term><literal>Data</literal></term>
483 <para>Libraries which provide data types, operations over
484 data types, or type classes, except for libraries for
485 which one of the other more specific categories is
491 <term><literal>Database</literal></term>
493 <para>Libraries for providing access to or operations for
494 building databases.</para>
499 <term><literal>Debug</literal></term>
501 <para>Support for debugging Haskell programs.</para>
506 <term><literal>Edison</literal></term>
508 <para>The Edison data structure library.</para>
513 <term><literal>FileFormat</literal></term>
515 <para>Support for reading and/or writing various file
516 formats (except: programming language source code which
517 lives in <literal>Language</literal>, database formats
518 which live in <literal>Database</literal>, and textual
519 file formats which are catered for in
520 <literal>Text</literal>).</para>
525 <term><literal>Foreign</literal></term>
527 <para>Interaction with code written in a foreign
528 programming language.</para>
533 <term><literal>Graphics</literal></term>
535 <para>Libraries for producing graphics or providing
536 graphical user interfaces.</para>
541 <term><literal>Language</literal></term>
543 <para>Libraries for operating on or generating source code
544 in various programming languages, including parsers,
545 pretty printers, abstract syntax definitions etc.</para>
550 <term><literal>Local</literal></term>
552 <para>Available for site-local use.</para>
557 <term><literal>Numeric</literal></term>
559 <para>Functions and classes which provide operations over
565 <term><literal>Network</literal></term>
567 <para>Libraries for communicating over a network,
568 including implementations of network protocols.</para>
573 <term><literal>Org</literal></term>
575 <para>Allocated to organisations on a domain-name
576 basis (see <xref linkend="layout">).</para>
581 <term><literal>System</literal></term>
583 <para>Libraries for communication with the system on which
584 the Haskell program is running (including the runtime
590 <term><literal>Text</literal></term>
592 <para>Libraries for parsing and generating data in a
593 textual format (including structured textual formats such
594 as XML, HTML, but not including programming language
595 source, which lives in Language).</para>
600 <term><literal>GHC</literal></term>
602 <para>Libraries specific to the GHC/GHCi system.</para>
607 <term><literal>Nhc</literal></term>
609 <para>Libraries specific to the Nhc compiler.</para>
614 <term><literal>Hugs</literal></term>
616 <para>Libraries specific to the Hugs system.</para>
621 <term><literal>User</literal></term>
623 <para>Allocated to individual users, using email
624 addresses (see <xref linkend="layout">).</para>
631 <sect1 id="licensing">
632 <title>Licensing</title>
634 <para>Following some discussion on the mailing list related to how
635 we should license the libraries, the viewpoint that was least
636 offensive to all involved seems to be the following:</para>
638 <para>We wish to accomodate source code from different
639 contributors, and with different licenses. However, a library of
640 modules where each module is released under a different license,
641 and where the dependencies between modules aren't clear, isn't
642 workable (it's too hard for a user of the library to tell whether
643 they're violating the terms of the each license or not).</para>
645 <para>So the solution is as follows: code under different licenses
646 will be clearly separate in the repository (i.e. in separate
647 subdirectories), and compilers are expected to present packages of
648 modules where all modules in a package fall under the same
649 license, and where the dependencies between packages are
652 <para>It was decided that certain essential functionality should
653 be available under a BSD style license. Hence, the BSD part of
654 the repository will contain implementations of at least the
655 following modules: <literal>Prelude</literal>,
656 <literal>Foreign</literal>, <emphasis>ToDo: what
657 else?</emphasis>.</para>
659 <para>There is one further requirement: only licenses approved by
660 the Open Source Initiative may be used with the core libraries.
661 See <ulink url="http://www.opensource.org//">The Open Source
662 Initiative</ulink> for a list of approved licensees.</para>
664 <para><emphasis>ToDo: include a prototype BSD license
665 here</emphasis>.</para>
668 <sect1 id="versioning">
669 <title>Versioning</title>
673 <sect1 id="stability">
674 <title>Library Stability</title>
676 <para>The stability of a library relates primarily to its API.
677 Stability provides an indication of how often the API is likely to
678 change (or whether it may even go away entirely).</para>
680 <para>The stability scale is also a measure of how strictly the
681 conventions in this document are applied to the library: an
682 experimental library isn't subject to any restrictions regarding
683 coding style and documentation, but a stable library is expected
684 to adhere to the guidelines, and come with full documentation and
687 <para>To help with the stability issue, library maintainers are
688 allowed to mark functions, types or classes as
689 <firstterm>deprecated</firstterm><footnote><para>Compilers may have
690 extra support for warning about the use of a deprecated feature, for
691 example GHC's <literal>DEPRECATED</literal> pragma.</para>
692 </footnote>, which means simply that the
693 feature will be removed at a later date. Just how long it will
694 stick around for depends on the stability category of the library
695 (see below). A feature is marked as deprecated in the
696 documentation for the library, and optionally in an
697 implementation-dependent way which enables the system to warn
698 about the use of deprecated features.</para>
700 <para>The current stability categories are:</para>
704 <term><firstterm>experimental</firstterm></term>
706 <para>An experimental library is unrestricted in terms of
707 API changes: the API may change between minor revisions and
708 there is no requirement to retain old interfaces for
709 compatibility. Documentation and tests aren't required for
710 an experimental library.</para>
714 <term><firstterm>provisional</firstterm></term>
716 <para>A provisional library is moving towards stability, and
717 the rate of change of the API is slower. API changes
718 between minor revisions must be accompanied by deprecated
719 versions of the old features where possible. API changes
720 between major versions are unrestricted. The library should
721 come with at least rudimentary documentation.</para>
725 <term><firstterm>stable</firstterm></term>
727 <para>A stable library has an essentially fixed API.
728 Additions to the API may be made for a minor release,
729 deprecated features must be retained for at least one major
730 revision, and small changes only may be made to the existing
731 API semantics for a major revision. A stable library is
732 expected to include full documentation and tests.</para>
739 <sect1 id="portability">
740 <title>Portability Considerations</title>
742 <para>The portability status of a library affects under which
743 platforms and compilers the library will be available on. Haskell
744 implementations are expected to provide all of the portable core
745 libraries, and those non-portable core libraries which are
746 appropriate for that particular platform/compiler
747 implementation.</para>
749 <para>The precise meaning of the terms portable and non-portable
750 for our purposes are given below:</para>
754 <term><firstterm>Portable</firstterm></term>
756 <para>A portable library may use only Haskell 98 features
757 plus approved extensions, and may not use any
758 platform-specific features. It may make use of other
759 portable libraries only.</para>
763 <term><firstterm>Non-portable</firstterm></term>
765 <para>A non-portable library may be non-portable for one or
766 more of the following reasons:</para>
769 <term><firstterm>Requires extensions</firstterm></term>
771 <para>A library which uses non-approved language
776 <term><firstterm>Requires nonportable libraries</firstterm></term>
778 <para>A library which depends (directly or indirectly)
779 on other non-portable libraries.</para>
783 <term><firstterm>OS-specific</firstterm></term>
784 <term><firstterm>Platform-specific</firstterm></term>
786 <para>A library which depends on features or APIs
787 particular to a certain OS or platform is non-portable
788 for that reason.</para>
797 <title>Approved Extensions</title>
799 <para>Very few of the core libraries can be implemented using
800 pure Haskell 98. For this reason, we decided to raise the
801 baseline for portable libraries to include a few common
802 extensions; the following langauge extensions can be
803 <emphasis>assumed</emphasis> to be present when writing
809 url="http://haskell.org/ghc/docs/latest/set/ffi.html">Foreign
810 Function Interface</ulink>.</para>
813 <para>Mutable variables
814 (<literal>Data.IORef</literal>).</para>
817 <para>Unsafe IO monad operations
818 (<literal>System.IO.Unsafe</literal>).</para>
822 (<literal>Data.PackedString</literal>).</para>
826 <para>Extensions which we'd like to be standard, but aren't
827 currently implemented by one or more of the target
832 <para>Bit operations (<literal>Data.Bits</literal>).</para>
835 <para>Exceptions (synchronous only), defined by the
836 <literal>Control.Exception</literal> interface.</para>
839 <para>The ST monad, defined by
840 <literal>Control.Monad.ST</literal>, and the associated
841 <literal>Data.Array.ST</literal> and
842 <literal>Data.STRef</literal> libraries. ST requires a
843 small typechecker extension for the <literal>runST</literal>
847 <para>Concurrent Haskell (pre-emptive multitasking
848 optional). GHC and Hugs implement this, but Nhc currently
853 <para>The following extensions are not likely to become part of
854 the baseline, but are nevertheless used by one or more libraries
855 in the core set (which are thus designated non-portable):</para>
859 <para>Multi-parameter type classes.</para>
862 <para>Local unversal and existential quantification.</para>
865 <para>Concurrent Haskell with pre-emptive multitasking.</para>
868 <para>Asynchronous exceptions.</para>
871 <para>Stable Names.</para>
874 <para>Weak Pointers.</para>
878 <para>Other extensions are supported by a single compiler only,
879 and can be accessed by libraries under the top level hierarchy
881 eg. <literal>GHC.UnboxedTypes</literal>.</para>
885 <sect1 id="maintainership">
886 <title>Library Maintainers</title>
888 <para>This is a collaborative project, so we like to devolve
889 control of the design and implementation of libraries to those
890 with an interest or appropriate expertise (or maybe just the
891 time!). A maintainer isn't necessarily a single person - for
892 example, the listed maintainer for most of the core libraries is
893 <email>libraries@haskell.org</email>, indicating that the library
894 is under the control of the community as a whole. The maintainer
895 for the <literal>Foreign</literal> hierarchy is
896 <email>ffi@haskell.org</email>, the mailing list for discussion of
897 the Haskell FFI standard.</para>
899 <para>The responsibilities of a library maintainer include:</para>
903 <para>Most importantly: act as a single point of contact for
904 issues relating to the library API and its
905 implementation.</para>
908 <para>Manage any discussion related to the library (which can
909 take place on <email>libraries.haskell.org</email> if
910 necessary), and summarise the results. Make final decisions,
911 and implement them.</para>
914 <para>Maintain the implementation, including: fixing bugs,
915 updating to keep up with changes in other libraries, porting
916 to new compilers/platforms, and integrating code from other
917 contributors. The maintainer is expected to be the only
918 person/group to make functional changes to the source code
919 (non-functional or trivial changes don't count).</para>
922 <para>Maintain/write the documentation and tests.</para>
925 <para>If you can't maintain the library any more for whatever
926 reason, tell <email>libraries@haskell.org</email> and we'll
927 revert the maintainer status of the library to the
932 <sect2 id="core-team">
933 <title>The Core Team</title>
935 <para>The core team is responsible for making final decisions
936 about the project as a whole and resolving disputes where
937 necessary. We expect that needing to invoke the core team will
938 be a rare occurrence.</para>
940 <para>The core team is also responsible for approving
941 maintainership requests.</para>
943 <para>Currently, the core team consists of one person from each
944 of the compiler camps, and these are also the people that will
945 primarily be maintaining the library framework for their
946 respective compiler projects:</para>
951 <email>simonmar@microsoft.com</email> (GHC representative)</para>
954 <para>Malcolm Wallace
955 <email>Malcolm.Wallace@cs.york.ac.uk</email> (Nhc representative)</para>
959 <email>andy@galconn.com</email> (Hugs representative)</para>
966 <sect1 id="documentation">
967 <title>Documentation</title>
972 <title>Testing</title>
976 <sect1 id="Migration-path">
977 <title>Migration path</title>
979 <para>How compatible will a compiler using the new libraries be
980 with code written for Haskell 98 or older library systems (such as
981 the <literal>hslibs</literal> suite and GHC's package system), and
982 for how long will compatibility be maintained?</para>
984 <para>Our current plan for GHC is as follows: by default, with the
985 <option>-fglasgow-exts</option> flag, you'll get access to the
986 core libraries. Compatibility with Haskell 98 code will be
987 maintained using a separate package of wrappers presenting
988 interfaces for the Haskell 98 libraries (<literal>IO</literal>,
989 <literal>Ratio</literal>, <literal>Directory</literal>, etc.).
990 The Haskell 98 compatibility package will be enabled by default,
991 but we plan to add an option to disable it if necessary. For code
992 that uses <literal>-package lang</literal>, we could also provide
993 a compatibility wrapper package (so <literal>-package
994 lang</literal> will continue to work as before and present the
995 same library interfaces), but this may prove too much work to
996 maintain - we haven't decided whether to do this or not. It is
997 unlikely that compatibility wrappers for any of the other
998 <literal>hslibs</literal> packages will be provided.</para>
1001 <sect1 id="conventions">
1002 <title>Programming Conventions</title>
1004 <sect2 id="module-header">
1005 <title>Standard Module Header</title> <para>The following module
1006 header will be used for all core libraries, and we recommend
1007 using it for library source code in general:</para>
1010 -----------------------------------------------------------------------------
1012 -- Module : <replaceable>module</replaceable>
1013 -- Copyright : (c) <replaceable>author</replaceable> <replaceable>year</replaceable>
1014 -- License : <replaceable>license</replaceable>
1016 -- Maintainer : libraries@haskell.org | <replaceable>email-address</replaceable>
1017 -- Stability : experimental | provisional | stable
1018 -- Portability : portable | non-portable (<replaceable>reason(s)</replaceable>)
1020 -- $Id: libraries.sgml,v 1.7 2002/02/12 15:17:34 simonmar Exp $
1022 -- <replaceable>Description</replaceable>
1023 -----------------------------------------------------------------------------
1030 <term><literal>$Id: libraries.sgml,v 1.7 2002/02/12 15:17:34 simonmar Exp $</literal></term>
1032 <para>is optional, but usually included if the module is
1033 under CVS or RCS control.</para>
1038 <term><replaceable>module</replaceable></term>
1040 <para>is the fully qualified module name of the
1046 <term><replaceable>author</replaceable>/<replaceable>year</replaceable></term>
1048 <para>Is the primary author and copyright holder of the
1049 module, and the year in which copyright is claimed.</para>
1054 <term><replaceable>license</replaceable></term>
1056 <para>Specifies the license on the file (see <xref
1057 linkend="licensing">).</para>
1062 <term><replaceable>email-address</replaceable></term>
1064 <para>The email address of the maintainer, or maintainers,
1065 of the library (see <xref linkend="maintainership">).</para>
1070 <term><replaceable>reason(s)</replaceable></term>
1072 <para>The reasons for non-portability must be listed (see
1073 <xref linkend="portability">).</para>
1078 <term><replaceable>description</replaceable></term>
1080 <para>A short description of the module.</para>
1087 <sect2 id="naming-conventions">
1088 <title>Naming Conventions</title>
1090 <para>These naming conventions are pulled straight from the
1091 <literal>hslibs</literal> documentation. They were formed after
1092 lengthy discussions and are heavily based on an initial
1093 suggestion from Marcin Kowalczyk
1094 <email>qrczak@knm.org.pl</email>.</para>
1096 <para>Note that the conventions are not mutually exclusive,
1097 e.g. should the function creating a set from a list of elements
1098 have the name <Literal>set</Literal> or
1099 <Literal>listToSet</Literal>? (Alas, it currently has neither
1102 <para> The following nomenclature is used: Pure,
1103 i.e. non-monadic functions are simply called, well,
1104 <emphasis>functions</emphasis>. Monadic functions,
1105 i.e. functions having a type <Literal>... -> m a</Literal>
1106 for some Monad <Literal>m</Literal> are called
1107 <emphasis>actions</emphasis>.</para>
1109 <sect3 id="sec-library-constructor-names">
1110 <title>Constructor names</title>
1111 <indexterm><primary>Constructor names</primary></indexterm>
1115 <para>Empty values of type <replaceable>X</replaceable>
1116 have the name <Literal>empty<replaceable>X</replaceable></Literal>,
1117 e.g. <literal>emptySet</literal>.</para>
1121 <para>Actions creating a new empty value of type
1122 <replaceable>X</replaceable> have the name
1123 <literal>newEmpty<replaceable>X</replaceable></literal>,
1124 e.g. <literal>newEmptyMVar</literal>.</para>
1128 <para>Functions creating an arbitrary value of type
1129 <replaceable>X</replaceable> have the name
1130 <replaceable>X</replaceable> itself (with the first letter
1132 e.g. <literal>array</literal>. (<emphasis>TODO</emphasis>:
1133 This often collides with <literal>xToY</literal>
1134 convention, how should this be resolved?)
1139 <para>Actions creating new values arbitrary values of type
1140 <replaceable>X</replaceable> have the name
1141 <literal>new<replaceable>X</replaceable></literal>,
1142 e.g. <literal>newIORef</literal>.
1148 <sect3 id="sec-library-accessor-names">
1149 <title>Accessor names</title>
1150 <indexterm><primary>Accessor names</primary></indexterm>
1154 <para>Functions getting an attribute of a value or a part
1155 of it have the name of the attribute itself,
1156 e.g. <literal>length</literal>, <literal>bounds</literal>.
1161 <para> Actions accessing some kind of reference or state
1163 <literal>get<replaceable>X</replaceable></literal>, where
1164 <replaceable>X</replaceable> is the type of the contents
1165 or the name of the part being accessed,
1166 e.g. <literal>getChar</literal>,
1167 <literal>getEnv</literal>. An alternative naming scheme is
1168 <literal>read<replaceable>Y</replaceable></literal>,
1169 where <replaceable>Y</replaceable> is the type of the
1170 reference or container, e.g. <literal>readIORef</literal>.
1175 <para>Functions or actions getting a value via a
1176 pointer-like type <replaceable>X</replaceable> should be
1178 <literal>deRef<replaceable>X</replaceable></literal>,
1179 e.g. <literal>deRefStablePtr</literal>,
1180 <literal>deRefWeak</literal>.</para>
1185 <sect3 id="sec-library-modifier-names">
1186 <title>Modifier names</title>
1187 <indexterm><primary>Modifier names</primary></indexterm>
1191 <para>Functions returning a value with attribute
1192 <replaceable>X</replaceable> set to a new value should be
1194 <literal>set<replaceable>X</replaceable></literal>. (<emphasis>TODO</emphasis>:
1195 Add Examples.)</para>
1199 <para> Actions setting some kind of reference or state
1201 <literal>put<replaceable>X</replaceable></literal>, where
1202 <replaceable>X</replaceable> is the type of the contents
1203 or the name of the part being accessed,
1204 e.g. <literal>putChar</literal>. An alternative naming
1206 <literal>write<replaceable>Y</replaceable></literal>,
1207 where <replaceable>X</replaceable> is the type of the
1208 reference or container,
1209 e.g. <literal>writeIORef</literal>. </para></listitem>
1212 <para> Actions in the <literal>IO</literal> monad setting
1213 some global state <replaceable>X</replaceable> are
1214 traditionally named <literal>setX</literal>, too, although
1215 <literal>put<replaceable>X</replaceable></literal> would
1216 be more appropriate,
1217 e.g. <literal>setReadlineName</literal>.</para>
1221 <para> Actions modifying a container
1222 <replaceable>X</replaceable> by a function of type
1223 <literal>a -> a</literal> have the name
1224 <literal>modify<replaceable>X</replaceable></literal>,
1225 e.g. <literal>modifySTRef</literal>.</para>
1230 <sect3 id="sec-library-predicate-names">
1231 <title>Predicate names</title>
1232 <indexterm><primary>Predicate names</primary></indexterm>
1236 <para>Predicates, both non-monadic and monadic, testing a
1237 property <replaceable>X</replaceable> have the name
1238 <literal>is<replaceable>X</replaceable></literal>.
1244 <sect3 id="sec-library-naming-conversions">
1245 <title>Names for conversions</title>
1246 <indexterm><primary>Names for conversions</primary></indexterm>
1250 <para>Functions converting a value of type
1251 <replaceable>X</replaceable> to a value of type
1252 <replaceable>Y</replaceable> have the name
1253 <literal><replaceable>X</replaceable>To<replaceable>Y</replaceable></literal>
1254 with all leading uppercase characters of
1255 <replaceable>X</replaceable> converted to lower case,
1256 e.g. <literal>stToIO</literal>.</para>
1260 <para>Overloaded conversion functions of type
1261 <literal>C a => a -> <replaceable>X</replaceable></literal>
1263 <literal>to<replaceable>X</replaceable></literal>,
1264 e.g. <literal>toInteger</literal>.</para>
1268 <para> Overloaded conversion functions of type
1269 <literal>C a => <replaceable>X</replaceable> -> a</literal>
1270 have the name <literal>from<replaceable>X</replaceable></literal>,
1271 e.g. <literal>fromInteger</literal>.</para>
1276 <sect3 id="sec-library-misc-names">
1277 <title>Miscellaneous naming conventions</title>
1278 <indexterm><primary>Miscellaneous naming
1279 convetions</primary></indexterm>
1283 <para> An action that is identical to another one called
1284 <replaceable>X</replaceable>, but discards the return
1286 <literal><replaceable>X</replaceable>_</literal>,
1287 e.g. <literal>mapM</literal> and <literal>mapM_</literal>.
1292 <para>Functions and actions which are potentially
1293 dangerous to use and leave some kind of proof obligation
1294 to the programmer have the name
1295 <literal>unsafe<replaceable>X</replaceable></literal>,
1296 e.g. <literal>unsafePerformIO</literal>.
1301 <para>There are two conventions for binary and N-ary
1302 variants of an associative operation: One convention uses
1303 an operator or a short name for the binary operation and a
1304 long name for the N-ary variant,
1305 e.g. <literal>(+)</literal> and <literal>sum</literal>,
1306 <literal>max</literal> and <literal>maximum</literal>. The
1307 other convention suffixes the N-ary variant with
1308 <literal>Many</literal>. (<emphasis>TODO</emphasis>: Add
1313 <para>If possible, names are chosen such that either plain
1314 application or <literal>arg1 `operation` arg2</literal> is
1315 correct English, e.g. <literal>isPrefixOf</literal> is
1316 good for use in backquotes.</para>
1322 <sect2 id="sec-library-misc-conventions">
1323 <title>Library design conventions</title>
1327 <para>Actions setting and modifying a kind of reference or
1328 state return <literal>()</literal>, getting the value is
1329 separate, e.g. <literal>writeIORef</literal> and
1330 <literal>modifyIORef</literal> both return
1331 <literal>()</literal>, only <literal>readIORef</literal>
1332 returns the value in an <literal>IORef</literal>
1337 <para>A function or action taking a some kind of state and
1338 returning a pair consisting of a result and a new state, the
1339 result is the first element of the pair and the new state is
1340 the second, see e.g. <literal>Random</literal>.</para>
1344 <para>When the type <literal>Either</literal> is used to
1345 encode an error condition and a normal result,
1346 <literal>Left</literal> is used for the former and
1347 <literal>Right</literal> for the latter, see
1348 e.g. <literal>Control.Monad.Error</literal>.</para>
1352 <para>A module corresponding to a class
1353 (e.g. <literal>Bits</literal>) contains the class
1354 definition, perhaps some auxiliary functions, and all
1355 sensible instances for Prelude types, but nothing
1356 more. Other modules containing types for which an instance
1357 for the class in question makes sense contain the code for
1358 the instance itself.</para>
1362 <para>Record-like C bit fields or structs have a
1363 record-like interface, i.e. pure getting and setting of
1364 fields. (<emphasis>TODO</emphasis>: Clarify a little
1365 bit. Add examples.)</para>
1369 <para>Although the possibility of partial application
1372 <literal><replaceable>attr</replaceable> -> <replaceable>object</replaceable> -> <replaceable>object</replaceable></literal>
1374 for functions setting an attribute or value, infix notation
1375 with backquotes implies
1377 <literal><replaceable>object</replaceable> -> <replaceable>attr</replaceable> -> <replaceable>object</replaceable></literal>.
1379 (<emphasis>TODO</emphasis>: Add Examples.)</para>
1384 <sect2 id="coding-style">
1385 <title>Coding style conventions</title>
1392 <title>Changes to standard Haskell 98 libraries</title>
1394 <para>Some changes have been made to the standard Haskell 98
1395 libraries in the new library scheme, both in the names of the
1396 modules themselves and in their exported interfaces. Below is a
1397 summary of those changes - at this time, the new libraries are
1398 marked as provisional and are maintained by
1399 <email>libraries@haskell.org</email>, so changes in the interfaces
1400 are all up for discussion.</para>
1403 modules with interface changes
1404 ------------------------------
1407 added instance Typeable (Array ix a)
1410 no interface changes (should have instance Typeable?)
1412 Complex -> Data.Complex
1413 added instance Typeable (Complex a)
1417 hPutBuf :: Handle -> Ptr a -> Int -> IO ()
1418 hGetBuf :: Handle -> Ptr a -> Int -> IO Int
1419 fixIO :: (a -> IO a) -> IO a
1420 hSetEcho :: Handle -> Bool -> IO ()
1421 hGetEcho :: Handle -> IO Bool
1422 hIsTerminalDevice :: Handle -> IO Bool
1427 System -> System.Exit, System.Environment, System.Cmd
1428 split into three modules
1430 just renamed, no interface changes:
1431 -----------------------------------
1433 CPUTTime -> System.CPUTime
1434 Directory -> System.IO.Directory
1436 Locale -> System.Locale
1440 Random -> System.Random