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 part of a proposal for an
14 extension to the <ulink
15 url="http://www.haskell.org/onlinereport/">Haskell 98</ulink>
16 language. The full proposal has several parts: </para>
20 <para>A modest language extension to Haskell 98 that adds the
21 character <quote>.</quote> to the lexical syntax for a module
22 name, allowing a hierarchical module namespace where a module
23 name is a sequence of components separated by periods.</para>
26 <para>An allocation of the new module namespace to existing
27 and non-existent libraries, people, organisations, and local
31 <para>A policy and procedure for allocating new parts of the
35 <para>A set of libraries which are under the control of the
36 community, have reference implementations kept in a standard
37 place, and conform to a set of guidelines and policies set out
38 in this document. We shall call this set of libraries the
39 <firstterm>core libraries</firstterm>.</para>
43 <para>In addition, this document also describes:</para>
47 <para>Guidelines and conventions for organising the
51 <para>Our policy with respect to the design and evolution of
52 library APIs, versioning of library APIs, and maintenance of
53 the reference implementation.</para>
56 <para>A set of conventions for coding style and portability
57 within the core libraries.</para>
62 <sect1 id="contributing">
63 <title>How to contribute</title>
65 <para>This project is driven by the Haskell community, so
66 contributions of all kinds are welcome. The first step is to join
68 url="http://www.haskell.org/mailman/listinfo/libraries">Haskell
69 libraries mailing list</ulink>, and maybe <ulink
70 url="http://www.haskell.org/pipermail/libraries/">browse the list
71 archives</ulink>. Some of the ways you can contribute are:</para>
75 <para>By donating code: for libraries in the core set which
76 don't yet have a reference implementation, or for new
77 contributions to the core set, code is always welcome. Code
78 that conforms to the style guidelines (which aren't very
79 strict, see <xref linkend="conventions">) and comes with
80 documentation (<xref linkend="documentation">) and a test
81 suite (<xref linkend="testing">) is better, but these aren't
82 essential. As a library progresses through the stability
83 scale (<xref linkend="stability">) these things become more
84 important, but for an experimental library we're not going to
85 worry too much about this stuff.</para>
88 <para>By porting code for an existing library to a new
89 compiler or architecture. A library is classed as portable if
90 it should be available regardless of which compiler/platform
91 combination you're using; however, many libraries are
92 non-portable for one reason or another (see <xref
93 linkend="portability">, and broadening the scope of these
94 libraries is always welcome.</para>
97 <para>Become a library maintainer: if you have a particular
98 interest in and/or knowledge about a certain library, and have
99 the time to spare, and the library in question doesn't already
100 have a maintainer, then you may be a suitable maintainer for
101 the library. The responsibilities of library maintainers are
102 given in <xref linkend="maintainership">. </para>
105 <para>Participating in the design process for new libraries,
106 and suggesting improvements to existing libraries. Everyone
108 url="http://www.haskell.org/mailman/listinfo/libraries">Haskell
109 libraries mailing list</ulink> is invited to
110 participate in the design process, so get involved!</para>
116 <title>The hierarchy layout</title>
118 <para>We first classify each node in the hierarchy according to
119 one of the following terms:</para>
123 <term>Allocated</term>
125 <para>Nodes in the hierarchy can be allocated to a library
126 (whether the library actually exists or not). The currently
127 allocated nodes are specified in <xref
128 linkend="hierarchy">.</para>
135 <para>The <literal>User</literal> hierarchy is reserved for
136 users: a user may always use the portion of the hierarchy
137 which is formed from his/her email address as follows:
138 replace the <literal>@</literal> by a <literal>.</literal>,
139 reverse the order of the components, capitalise the first
140 letter of each component, and prepend
141 <literal>User.</literal>. For example,
142 <literal>simonmar@microsoft.com</literal> becomes
143 <literal>User.Com.Microsoft.Simonmar</literal>.</para>
148 <term>Organisation</term>
150 <para>The <literal>Org</literal> hierarchy is reserved for
151 organisations. Any organisation with a DNS domain name owns
152 a unique space in the hierarchy formed by reversing the
153 components of the domain, capitalising the first character
154 of each component, and prepending
155 <literal>Org.</literal>. <emphasis>ToDo: I don't like this
156 very much, any better ideas?</emphasis></para>
163 <para>The <literal>Local</literal> hierarchy is reserved for
164 libraries which are local to the current site. Libraries
165 which are to be distributed outside the current site should
166 not be placed in the <literal>Local</literal>
172 <term>Top-level</term>
174 <para>All top-level names (i.e. module names that don't
175 contain a <quote><literal>.</literal></quote>) that are
176 otherwise unallocated, are available for use by the program.
177 Note that for compabibility with Haskell 98, some modules in
178 this namespace are reserved
179 (eg. <literal>Directory</literal>, <literal>IO</literal>,
180 <literal>Time</literal> etc.).</para>
185 <term>Unallocated</term>
187 <para>Any node which doesn't belong to any of the above
188 categories is currently unallocated, and is not available
194 <para>A node in the hierarchy may be both a specific library and a
195 parent node for a number of child nodes. For example,
196 <literal>Foreign</literal> is a library, and so is
197 <literal>Foreign.Ptr</literal>.</para>
199 <sect2 id="hierarchy-design-guidelines">
200 <title>Hierarchy design guidelines</title>
204 <sect2 id="module-naming-convention">
205 <title>Module Naming Conventions</title>
209 <sect2 id="hierarchy">
210 <title>The hierarchy</title>
212 <para>The currently allocated top-level names are:</para>
216 <term><literal>Prelude</literal></term>
218 <para>Haskell98 Prelude (mostly just re-exports other
219 parts of the tree).</para>
224 <term><literal>Control</literal></term>
226 <para> Libraries which provide functions, types or classes
227 whose purpose is primarily to express control
233 <term><literal>Data</literal></term>
235 <para>Libraries which provide data types, operations over
236 data types, or type classes, except for libraries for
237 which one of the other more specific categories is
243 <term><literal>Database</literal></term>
245 <para>Libraries for providing access to or operations for
246 building databases.</para>
251 <term><literal>Debug</literal></term>
253 <para>Support for debugging Haskell programs.</para>
258 <term><literal>Edison</literal></term>
260 <para>The Edison data structure library.</para>
265 <term><literal>FileFormat</literal></term>
267 <para>Support for reading and/or writing various file
268 formats (except: programming language source code which
269 lives in <literal>Language</literal>, database formats
270 which live in <literal>Database</literal>, and textual
271 file formats which are catered for in
272 <literal>Text</literal>).</para>
277 <term><literal>Foreign</literal></term>
279 <para>Interaction with code written in a foreign
280 programming language.</para>
285 <term><literal>Graphics</literal></term>
287 <para>Libraries for producing graphics or providing
288 graphical user interfaces.</para>
293 <term><literal>Language</literal></term>
295 <para>Libraries for operating on or generating source code
296 in various programming languages, including parsers,
297 pretty printers, abstract syntax definitions etc.</para>
302 <term><literal>Local</literal></term>
304 <para>Available for site-local use.</para>
309 <term><literal>Numeric</literal></term>
311 <para>Functions and classes which provide operations over
317 <term><literal>Network</literal></term>
319 <para>Libraries for communicating over a network,
320 including implementations of network protocols.</para>
325 <term><literal>Org</literal></term>
327 <para>Allocated to organisations on a domain-name
328 basis (see <xref linkend="layout">).</para>
333 <term><literal>System</literal></term>
335 <para>Libraries for communication with the system on which
336 the Haskell program is running (including the runtime
342 <term><literal>Text</literal></term>
344 <para>Libraries for parsing and generating data in a
345 textual format (including structured textual formats such
346 as XML, HTML, but not including programming language
347 source, which lives in Language).</para>
352 <term><literal>GHC</literal></term>
354 <para>Libraries specific to the GHC/GHCi system.</para>
359 <term><literal>NHC</literal></term>
361 <para>Libraries specific to the NHC compiler.</para>
366 <term><literal>Hugs</literal></term>
368 <para>Libraries specific to the Hugs system.</para>
373 <term><literal>User</literal></term>
375 <para>Allocated to individual users, using email
376 addresses (see <xref linkend="layout">).</para>
383 <sect1 id="licensing">
384 <title>Licensing</title>
386 <para>Following some discussion on the mailing list related to how
387 we should license the libraries, the viewpoint that was least
388 offensive to all involved seems to be the following:</para>
390 <para>We wish to accomodate source code from different
391 contributors, and with different licenses. However, a library of
392 modules where each module is released under a different license,
393 and where the dependencies between modules aren't clear, isn't
394 workable (it's too hard for a user of the library to tell whether
395 they're violating the terms of the each license or not).</para>
397 <para>So the solution is as follows: code under different licenses
398 will be clearly separate in the repository (i.e. in separate
399 subdirectories), and compilers are expected to present packages of
400 modules where all modules in a package fall under the same
401 license, and where the dependencies between packages are
404 <para>It was decided that certain essential functionality should
405 be available under a BSD style license. Hence, the BSD part of
406 the repository will contain implementations of at least the
407 following modules: <literal>Prelude</literal>,
408 <literal>Foreign</literal>, <emphasis>ToDo: what
409 else?</emphasis>.</para>
411 <para><emphasis>ToDo: include a prototype BSD license
412 here</emphasis>.</para>
415 <sect1 id="versioning">
416 <title>Versioning</title>
420 <sect1 id="stability">
421 <title>Library Stability</title>
423 <para>The stability of a library relates primarily to its API.
424 Stability provides an indication of how often the API is likely to
425 change (or whether it may even go away entirely).</para>
427 <para>The stability scale is also a measure of how strictly the
428 conventions in this document are applied to the library: an
429 experimental library isn't subject to any restrictions regarding
430 coding style and documentation, but a stable library is expected
431 to adhere to the guidelines, and come with full documentation and
434 <para>To help with the stability issue, library maintainers are
435 allowed to mark functions, types or classes as
436 <firstterm>deprecated</firstterm><footnote><para>Compilers may have
437 extra support for warning about the use of a deprecated feature, for
438 example GHC's <literal>DEPRECATED</literal> pragma.</para>
439 </footnote>, which means simply that the
440 feature will be removed at a later date. Just how long it will
441 stick around for depends on the stability category of the library
442 (see below). A feature is marked as deprecated in the
443 documentation for the library, and optionally in an
444 implementation-dependent way which enables the system to warn
445 about the use of deprecated features.</para>
447 <para>The current stability categories are:</para>
451 <term><firstterm>experimental</firstterm></term>
453 <para>An experimental library is unrestricted in terms of
454 API changes: the API may change between minor revisions and
455 there is no requirement to retain old interfaces for
456 compatibility. Documentation and tests aren't required for
457 an experimental library.</para>
461 <term><firstterm>provisional</firstterm></term>
463 <para>A provisional library is moving towards stability, and
464 the rate of change of the API is slower. API changes
465 between minor revisions must be accompanied by deprecated
466 versions of the old features where possible. API changes
467 between major versions are unrestricted. The library should
468 come with at least rudimentary documentation.</para>
472 <term><firstterm>stable</firstterm></term>
474 <para>A stable library has an essentially fixed API.
475 Additions to the API may be made for a minor release,
476 deprecated features must be retained for at least one major
477 revision, and small changes only may be made to the existing
478 API semantics for a major revision. A stable library is
479 expected to include full documentation and tests.</para>
486 <sect1 id="portability">
487 <title>Portability Considerations</title>
489 <para>The portability status of a library affects under which
490 platforms and compilers the library will be available on. Haskell
491 implementations are expected to provide all of the portable core
492 libraries, and those non-portable core libraries which are
493 appropriate for that particular platform/compiler
494 implementation.</para>
496 <para>The precise meaning of the terms portable and non-portable
497 for our purposes are given below:</para>
501 <term><firstterm>Portable</firstterm></term>
503 <para>A portable library may use only Haskell 98 features
504 plus approved extensions (see <xref linkend="portability">),
505 and may not use any platform-specific features. It may make
506 use of other portable libraries only.</para>
510 <term><firstterm>Non-portable</firstterm></term>
512 <para>A non-portable library may be non-portable for one or
513 more of the following reasons:</para>
516 <term><firstterm>Requires extensions</firstterm></term>
518 <para>A library which uses non-approved language
523 <term><firstterm>Requires nonportable libraries</firstterm></term>
525 <para>A library which depends (directly or indirectly)
526 on other non-portable libraries.</para>
530 <term><firstterm>OS-specific</firstterm></term>
531 <term><firstterm>Platform-specific</firstterm></term>
533 <para>A library which depends on features or APIs
534 particular to a certain OS or platform is non-portable
535 for that reason.</para>
545 <sect1 id="maintainership">
546 <title>Library Maintainers</title>
548 <para>This is a collaborative project, so we like to devolve
549 control of the design and implementation of libraries to those
550 with an interest or appropriate expertise (or maybe just the
551 time!). A maintainer isn't necessarily a single person - for
552 example, the listed maintainer for most of the core libraries is
553 <email>libraries@haskell.org</email>, indicating that the library
554 is under the control of the community as a whole. The maintainer
555 for the <literal>Foreign</literal> hierarchy is
556 <email>ffi@haskell.org</email>, the mailing list for discussion of
557 the Haskell FFI standard.</para>
559 <para>The responsibilities of a library maintainer include:</para>
563 <para>Most importantly: act as a single point of contact for
564 issues relating to the library API and its
565 implementation.</para>
568 <para>Manage any discussion related to the library (which can
569 take place on <email>libraries.haskell.org</email> if
570 necessary), and summarise the results. Make final decisions,
571 and implement them.</para>
574 <para>Maintain the implementation, including: fixing bugs,
575 updating to keep up with changes in other libraries, porting
576 to new compilers/platforms, and integrating code from other
577 contributors. The maintainer is expected to be the only
578 person/group to make functional changes to the source code
579 (non-functional or trivial changes don't count).</para>
582 <para>Maintain/write the documentation and tests.</para>
585 <para>If you can't maintain the library any more for whatever
586 reason, tell <email>libraries@haskell.org</email> and we'll
587 revert the maintainer status of the library to the
592 <sect2 id="core-team">
593 <title>The Core Team</title>
595 <para>The core team is responsible for making final decisions
596 about the project as a whole and resolving disputes where
597 necessary. We expect that needing to invoke the core team will
598 be a rare occurrence.</para>
600 <para>The core team is also responsible for approving
601 maintainership requests.</para>
603 <para>Currently, the core team consists of one person from each
604 of the compiler camps, and these are also the people that will
605 primarily be maintaining the library framework for their
606 respective compiler projects:</para>
611 <email>simonmar@microsoft.com</email> (GHC representative)</para>
614 <para>Malcolm Wallace
615 <email>Malcolm.Wallace@cs.york.ac.uk</email> (NHC representative)</para>
619 <email>andy@galconn.com</email> (Hugs representative)</para>
626 <sect1 id="documentation">
627 <title>Documentation</title>
632 <title>Testing</title>
636 <sect1 id="Migration-path">
637 <title>Migration path</title>
639 <para>How compatible will a compiler using the new libraries be
640 with code written for Haskell 98 or older library systems (such as
641 the <literal>hslibs</literal> suite and GHC's package system), and
642 for how long will compatibility be maintained?</para>
644 <para>Our current plan for GHC is as follows: by default, with the
645 <option>-fglasgow-exts</option> flag, you'll get access to the
646 core libraries. Compatibility with Haskell 98 code will be
647 maintained using a separate package of wrappers presenting
648 interfaces for the Haskell 98 libraries (<literal>IO</literal>,
649 <literal>Ratio</literal>, <literal>Directory</literal>, etc.).
650 The Haskell 98 compatibility package will be enabled by default,
651 but we plan to add an option to disable it if necessary. For code
652 that uses <literal>-package lang</literal>, we could also provide
653 a compatibility wrapper package (so <literal>-package
654 lang</literal> will continue to work as before and present the
655 same library interfaces), but this may prove too much work to
656 maintain - we haven't decided whether to do this or not. It is
657 unlikely that compatibility wrappers for any of the other
658 <literal>hslibs</literal> packages will be provided.</para>
661 <sect1 id="conventions">
662 <title>Programming Conventions</title>
664 <sect2 id="module-header">
665 <title>Standard Module Header</title> <para>The following module
666 header will be used for all core libraries, and we recommend
667 using it for library source code in general:</para>
670 -----------------------------------------------------------------------------
672 -- Module : <replaceable>module</replaceable>
673 -- Copyright : (c) <replaceable>author</replaceable> <replaceable>year</replaceable>
674 -- License : <replaceable>license</replaceable>
676 -- Maintainer : libraries@haskell.org | <replaceable>email-address</replaceable>
677 -- Stability : experimental | provisional | stable
678 -- Portability : portable | non-portable (<replaceable>reason(s)</replaceable>)
680 -- $Id: libraries.sgml,v 1.1 2001/06/28 14:15:04 simonmar Exp $
682 -- <replaceable>Description</replaceable>
683 -----------------------------------------------------------------------------
690 <term><literal>$Id: libraries.sgml,v 1.1 2001/06/28 14:15:04 simonmar Exp $</literal></term>
692 <para>is optional, but usually included if the module is
693 under CVS or RCS control.</para>
698 <term><replaceable>module</replaceable></term>
700 <para>is the fully qualified module name of the
706 <term><replaceable>author</replaceable>/<replaceable>year</replaceable></term>
708 <para>Is the primary author and copyright holder of the
709 module, and the year in which copyright is claimed.</para>
714 <term><replaceable>license</replaceable></term>
716 <para>Specifies the license on the file (see <xref
717 linkend="licensing">).</para>
722 <term><replaceable>email-address</replaceable></term>
724 <para>The email address of the maintainer, or maintainers,
725 of the library (see <xref linkend="maintainership">).</para>
730 <term><replaceable>reason(s)</replaceable></term>
732 <para>The reasons for non-portability must be listed (see
733 <xref linkend="portability">).</para>
738 <term><replaceable>description</replaceable></term>
740 <para>A short description of the module.</para>
747 <sect2 id="naming-conventions">
748 <title>Naming Conventions</title>
750 <para>These naming conventions are pulled straight from the
751 <literal>hslibs</literal> documentation. They were formed after
752 lengthy discussions and are heavily based on an initial
753 suggestion from Marcin Kowalczyk
754 <email>qrczak@knm.org.pl</email>.</para>
756 <para>Note that the conventions are not mutually exclusive,
757 e.g. should the function creating a set from a list of elements
758 have the name <Literal>set</Literal> or
759 <Literal>listToSet</Literal>? (Alas, it currently has neither
762 <para> The following nomenclature is used: Pure,
763 i.e. non-monadic functions are simply called, well,
764 <emphasis>functions</emphasis>. Monadic functions,
765 i.e. functions having a type <Literal>... -> m a</Literal>
766 for some Monad <Literal>m</Literal> are called
767 <emphasis>actions</emphasis>.</para>
769 <sect3 id="sec-library-module-names">
770 <title>Module names</title>
773 <para>A module defining a data type or type class
774 <replaceable>X</replaceable> has the itself the name
775 <replaceable>X</replaceable>, e.g.
776 <literal>StablePtr</literal>.</para>
780 <para>A module which re-exports the modules in a subtree
781 of the hierarchy has the same name as the root of that
782 subtree, eg. <literal>Foreign</literal> re-exports
783 <literal>Foreign.Ptr</literal>,
784 <literal>Foreign.MarshalUtils</literal> etc.</para>
788 <para>If a subtree of the hierarchy contains several
789 modules which provide similar functionality (eg. there are
790 several pretty-printing libraries under
791 <literal>Text.PrettyPrinter</literal>), then the module at
792 the root of the subtree generally re-exports just
793 <emphasis>one</emphasis> of the modules in the subtree
794 (possibly the most popular or commonly-used
799 <para>In Haskell you sometimes publish
800 <emphasis>two</emphasis> interfaces to your libraries; one
801 for users, and one for library writers or advanced users
802 who might want to extend things. Typically the advanced
803 users need to be able to see past certain
806 <para>The current proposal is for a module named
807 <literal>M</literal>, the <quote>advanced</quote> version
808 would be named <literal>M.Internals</literal>. eg.</para>
811 import Text.Html -- The library
812 import Text.Html.Internals -- The non-abstract library (for building other libs)
819 <sect3 id="sec-library-constructor-names">
820 <title>Constructor names</title>
821 <indexterm><primary>Constructor names</primary></indexterm>
825 <para>Empty values of type <replaceable>X</replaceable>
826 have the name <Literal>empty<replaceable>X</replaceable></Literal>,
827 e.g. <literal>emptySet</literal>.</para>
831 <para>Actions creating a new empty value of type
832 <replaceable>X</replaceable> have the name
833 <literal>newEmpty<replaceable>X</replaceable></literal>,
834 e.g. <literal>newEmptyMVar</literal>.</para>
838 <para>Functions creating an arbitrary value of type
839 <replaceable>X</replaceable> have the name
840 <replaceable>X</replaceable> itself (with the first letter
842 e.g. <literal>array</literal>. (<emphasis>TODO</emphasis>:
843 This often collides with <literal>xToY</literal>
844 convention, how should this be resolved?)
849 <para>Actions creating new values arbitrary values of type
850 <replaceable>X</replaceable> have the name
851 <literal>new<replaceable>X</replaceable></literal>,
852 e.g. <literal>newIORef</literal>.
858 <sect3 id="sec-library-accessor-names">
859 <title>Accessor names</title>
860 <indexterm><primary>Accessor names</primary></indexterm>
864 <para>Functions getting an attribute of a value or a part
865 of it have the name of the attribute itself,
866 e.g. <literal>length</literal>, <literal>bounds</literal>.
871 <para> Actions accessing some kind of reference or state
873 <literal>get<replaceable>X</replaceable></literal>, where
874 <replaceable>X</replaceable> is the type of the contents
875 or the name of the part being accessed,
876 e.g. <literal>getChar</literal>,
877 <literal>getEnv</literal>. An alternative naming scheme is
878 <literal>read<replaceable>Y</replaceable></literal>,
879 where <replaceable>Y</replaceable> is the type of the
880 reference or container, e.g. <literal>readIORef</literal>.
885 <para>Functions or actions getting a value via a
886 pointer-like type <replaceable>X</replaceable> should be
888 <literal>deRef<replaceable>X</replaceable></literal>,
889 e.g. <literal>deRefStablePtr</literal>,
890 <literal>deRefWeak</literal>.</para>
895 <sect3 id="sec-library-modifier-names">
896 <title>Modifier names</title>
897 <indexterm><primary>Modifier names</primary></indexterm>
901 <para>Functions returning a value with attribute
902 <replaceable>X</replaceable> set to a new value should be
904 <literal>set<replaceable>X</replaceable></literal>. (<emphasis>TODO</emphasis>:
905 Add Examples.)</para>
909 <para> Actions setting some kind of reference or state
911 <literal>put<replaceable>X</replaceable></literal>, where
912 <replaceable>X</replaceable> is the type of the contents
913 or the name of the part being accessed,
914 e.g. <literal>putChar</literal>. An alternative naming
916 <literal>write<replaceable>Y</replaceable></literal>,
917 where <replaceable>X</replaceable> is the type of the
918 reference or container,
919 e.g. <literal>writeIORef</literal>. </para></listitem>
922 <para> Actions in the <literal>IO</literal> monad setting
923 some global state <replaceable>X</replaceable> are
924 traditionally named <literal>setX</literal>, too, although
925 <literal>put<replaceable>X</replaceable></literal> would
927 e.g. <literal>setReadlineName</literal>.</para>
931 <para> Actions modifying a container
932 <replaceable>X</replaceable> by a function of type
933 <literal>a -> a</literal> have the name
934 <literal>modify<replaceable>X</replaceable></literal>,
935 e.g. <literal>modifySTRef</literal>.</para>
940 <sect3 id="sec-library-predicate-names">
941 <title>Predicate names</title>
942 <indexterm><primary>Predicate names</primary></indexterm>
946 <para>Predicates, both non-monadic and monadic, testing a
947 property <replaceable>X</replaceable> have the name
948 <literal>is<replaceable>X</replaceable></literal>.
954 <sect3 id="sec-library-naming-conversions">
955 <title>Names for conversions</title>
956 <indexterm><primary>Names for conversions</primary></indexterm>
960 <para>Functions converting a value of type
961 <replaceable>X</replaceable> to a value of type
962 <replaceable>Y</replaceable> have the name
963 <literal><replaceable>X</replaceable>To<replaceable>Y</replaceable></literal>
964 with all leading uppercase characters of
965 <replaceable>X</replaceable> converted to lower case,
966 e.g. <literal>stToIO</literal>.</para>
970 <para>Overloaded conversion functions of type
971 <literal>C a => a -> <replaceable>X</replaceable></literal>
973 <literal>to<replaceable>X</replaceable></literal>,
974 e.g. <literal>toInteger</literal>.</para>
978 <para> Overloaded conversion functions of type
979 <literal>C a => <replaceable>X</replaceable> -> a</literal>
980 have the name <literal>from<replaceable>X</replaceable></literal>,
981 e.g. <literal>fromInteger</literal>.</para>
986 <sect3 id="sec-library-misc-names">
987 <title>Miscellaneous naming conventions</title>
988 <indexterm><primary>Miscellaneous naming
989 convetions</primary></indexterm>
993 <para> An action that is identical to another one called
994 <replaceable>X</replaceable>, but discards the return
996 <literal><replaceable>X</replaceable>_</literal>,
997 e.g. <literal>mapM</literal> and <literal>mapM_</literal>.
1002 <para>Functions and actions which are potentially
1003 dangerous to use and leave some kind of proof obligation
1004 to the programmer have the name
1005 <literal>unsafe<replaceable>X</replaceable></literal>,
1006 e.g. <literal>unsafePerformIO</literal>.
1011 <para>There are two conventions for binary and N-ary
1012 variants of an associative operation: One convention uses
1013 an operator or a short name for the binary operation and a
1014 long name for the N-ary variant,
1015 e.g. <literal>(+)</literal> and <literal>sum</literal>,
1016 <literal>max</literal> and <literal>maximum</literal>. The
1017 other convention suffixes the N-ary variant with
1018 <literal>Many</literal>. (<emphasis>TODO</emphasis>: Add
1023 <para>If possible, names are chosen such that either plain
1024 application or <literal>arg1 `operation` arg2</literal> is
1025 correct English, e.g. <literal>isPrefixOf</literal> is
1026 good for use in backquotes.</para>
1032 <sect2 id="sec-library-misc-conventions">
1033 <title>Library design conventions</title>
1037 <para>Actions setting and modifying a kind of reference or
1038 state return <literal>()</literal>, getting the value is
1039 separate, e.g. <literal>writeIORef</literal> and
1040 <literal>modifyIORef</literal> both return
1041 <literal>()</literal>, only <literal>readIORef</literal>
1042 returns the value in an <literal>IORef</literal>
1047 <para>A function or action taking a some kind of state and
1048 returning a pair consisting of a result and a new state, the
1049 result is the first element of the pair and the new state is
1050 the second, see e.g. <literal>Random</literal>.</para>
1054 <para>When the type <literal>Either</literal> is used to
1055 encode an error condition and a normal result,
1056 <literal>Left</literal> is used for the former and
1057 <literal>Right</literal> for the latter, see
1058 e.g. <literal>MonadEither</literal>.</para>
1062 <para> A module corresponding to a class
1063 (e.g. <literal>Bits</literal>) contains the class
1064 definition, perhaps some auxiliary functions, and all
1065 sensible instances for Prelude types, but nothing
1066 more. Other modules containing types for which an instance
1067 for the class in question makes sense contain the code for
1068 the instance itself.</para>
1072 <para> Record-like C bit fields or structs have a
1073 record-like interface, i.e. pure getting and setting of
1074 fields. (<emphasis>TODO</emphasis>: Clarify a little
1075 bit. Add examples.)</para>
1079 <para> Although the possibility of partial application
1082 <literal><replaceable>attr</replaceable> -> <replaceable>object</replaceable> -> <replaceable>object</replaceable></literal>
1084 for functions setting an attribute or value, infix notation
1085 with backquotes implies
1087 <literal><replaceable>object</replaceable> -> <replaceable>attr</replaceable> -> <replaceable>object</replaceable></literal>.
1089 (<emphasis>TODO</emphasis>: Add Examples.)</para>
1094 <sect2 id="coding-style">
1095 <title>Coding style conventions</title>
1102 <title>Changes to standard Haskell 98 libraries</title>
1104 <para>Some changes have been made to the standard Haskell 98
1105 libraries in the new library scheme, both in the names of the
1106 modules themselves and in their exported interfaces. Below is a
1107 summary of those changes - at this time, the new libraries are
1108 marked as provisional and are maintained by
1109 <email>libraries@haskell.org</email>, so changes in the interfaces
1110 are all up for discussion.</para>
1113 modules with interface changes
1114 ------------------------------
1117 added instance Typeable (Array ix a)
1120 no interface changes (should have instance Typeable?)
1122 Complex -> Data.Complex
1123 added instance Typeable (Complex a)
1127 hPutBuf :: Handle -> Ptr a -> Int -> IO ()
1128 hGetBuf :: Handle -> Ptr a -> Int -> IO Int
1129 fixIO :: (a -> IO a) -> IO a
1135 not placed in hierarchy yet
1137 System -> System.Exit, System.Environment, System.Cmd
1138 split into three modules
1140 just renamed, no interface changes:
1141 -----------------------------------
1143 CPUTTime -> System.CPUTime
1144 Directory -> System.IO.Directory
1146 Locale -> System.Locale
1148 Random -> System.Radom