Add a skeleton libraries directory
[ghc.git] / libraries / doc / libraries.xml
1 <?xml version="1.0" encoding="iso-8859-1"?>
2 <!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
3 "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
4 <!ENTITY libtable SYSTEM "libtable.xml">
5 ]>
6
7 <article id="libraries">
8 <articleinfo>
9 <title>Hierarchical Haskell Libraries</title>
10 <orgname>The Haskell Libraries Mailing List</orgname>
11 <address><email>libraries@haskell.org</email></address>
12 </articleinfo>
13
14 <sect1 id="introduction">
15 <title>Introduction</title>
16
17 <para>The <ulink
18 url="http://www.haskell.org/hierarchical-modules/">Hierarchical
19 Module Namespace Extension</ulink> is a modest extension to Haskell 98
20 which replaces the existing flat module namespace with a
21 hierarchy.</para>
22
23 <para>This document constitutes a proposal for how the new
24 hierarchical namespace should be used. It is
25 <emphasis>not</emphasis> an addendum to the Haskell 98 report: the
26 contents of this document are still under discussion on the
27 <ulink
28 url="http://www.haskell.org/mailman/listinfo/libraries"><literal>libraries@haskell.org</literal></ulink>
29 mailing list, and are subject to change.</para>
30
31 <para>The most up to date version of this document can be found in
32 the <ulink
33 url="http://www.haskell.org/ghc/docs/latest/html/building/sec-cvs.html">GHC
34 CVS repository</ulink> in the directory
35 <literal>fptools/libraries/doc</literal>.</para>
36
37 <para>The proposal has several parts: </para>
38
39 <itemizedlist>
40 <listitem>
41 <para>An allocation of the new module namespace to existing
42 and non-existent libraries, people, organisations, and local
43 use.</para>
44 </listitem>
45 <listitem>
46 <para>A policy and procedure for allocating new parts of the
47 namespace.</para>
48 </listitem>
49 <listitem>
50 <para>A set of libraries which are under the control of the
51 community and have reference implementations. These libraries
52 will vary from almost completely stable (eg. the
53 <literal>Prelude</literal>) to experimental libraries with
54 fast-changing APIs. Throughout this document, these libraries
55 shall be referred to as the <firstterm>Reference
56 Libraries</firstterm>. The reference libraries serve to both
57 define the library APIs, and provide implementations; in most
58 cases this will be the primary implementation of that
59 library.</para>
60 </listitem>
61 </itemizedlist>
62
63 <para>In addition, this document also describes:</para>
64
65 <itemizedlist>
66 <listitem>
67 <para>Guidelines and conventions for organising the
68 hierarchy.</para>
69 </listitem>
70 <listitem>
71 <para>Our policy with respect to the design and evolution of
72 library APIs, versioning of library APIs, and maintenance of
73 the reference implementation.</para>
74 </listitem>
75 <listitem>
76 <para>A set of conventions for coding style and portability
77 within the libraries.</para>
78 </listitem>
79 </itemizedlist>
80 </sect1>
81
82 <sect1 id="contributing">
83 <title>How to contribute</title>
84
85 <para>This project is driven by the Haskell community, so
86 contributions of all kinds are welcome. The first step is to join
87 the <ulink
88 url="http://www.haskell.org/mailman/listinfo/libraries">Haskell
89 libraries mailing list</ulink>, and maybe <ulink
90 url="http://www.haskell.org/pipermail/libraries/">browse the list
91 archives</ulink>. Some of the ways you can contribute are:</para>
92
93 <itemizedlist>
94 <listitem>
95 <para>By donating code: for libraries which don't yet have a
96 reference implementation, code is always welcome. Code that
97 conforms to the design guidelines (which aren't very strict,
98 see <xref linkend="library-design"/>) and comes with documentation
99 (<xref linkend="documentation"/>) and a test suite (<xref
100 linkend="testing"/>) is better, but these aren't essential. As
101 a library progresses through the stability scale (<xref
102 linkend="stability"/>) these things become more important, but
103 for an experimental library we're not going to worry too much
104 about this stuff.</para>
105
106 <para>See section <xref
107 linkend="contributing-reference-libraries"/> for details on
108 contributing new library code.</para>
109 </listitem>
110 <listitem>
111 <para>By porting code for an existing library to a new
112 compiler or architecture. A library is classed as portable if
113 it should be available regardless of which compiler/platform
114 combination you're using; however, many libraries are
115 non-portable for one reason or another (see <xref
116 linkend="portability"/>), and broadening the scope of these
117 libraries is always welcome.</para>
118 </listitem>
119 <listitem>
120 <para>Become a library maintainer: if you have a particular
121 interest in and/or knowledge about a certain library, and have
122 the time to spare, and the library in question doesn't already
123 have a maintainer, then you may be a suitable maintainer for
124 the library. The responsibilities of library maintainers are
125 given in <xref linkend="maintainership"/>. </para>
126 </listitem>
127 <listitem>
128 <para>Participating in the design process for new libraries,
129 and suggesting improvements to existing libraries. Everyone
130 on the <ulink
131 url="http://www.haskell.org/mailman/listinfo/libraries">Haskell
132 libraries mailing list</ulink> is invited to
133 participate in the design process, so get involved!</para>
134 </listitem>
135 </itemizedlist>
136
137 </sect1>
138
139 <!--
140 <sect2>
141 <title>A possible extension</title>
142
143 <para>The use of qualified imports has become more verbose: for
144 instance</para>
145
146 <programlisting>
147 import qualified XmlParse
148 ... XmlParse.element f ...
149 </programlisting>
150
151 <para>becomes</para>
152
153 <programlisting>
154 import qualified Text.Xml.Parse
155 ... Text.Xml.Parse.element f ...
156 </programlisting>
157
158 <para>It is usually more convenient to make use of Haskell's
159 <literal>as</literal> keyword to shorten qualified identifiers:</para>
160
161 <programlisting>
162 import qualified Text.Xml.Parse as Parse
163 ... Parse.element f ...
164 </programlisting>
165
166 <para>A possible extension to the proposal is to make this use
167 of <literal>as</literal> implicit, unless overridden by the
168 programmer with her own <literal>as</literal> clause. The
169 implicit <literal>as</literal> clause always uses the final
170 subdivision of the module name. So for instance, either the
171 fully-qualified or abbreviated-qualified names</para>
172
173 <programlisting>
174 Text.Xml.Parse.element
175 Parse.element
176 </programlisting>
177
178 <para>would be accepted and have the same referent, but a
179 partial qualification like</para>
180
181 <programlisting>
182 Xml.Parse.element
183 </programlisting>
184
185 <para>would not be accepted.</para>
186 </sect2>
187
188 <sect2>
189 <title>Renaming subtrees</title>
190
191 <para>Various proposals have been made to allow you to rename a
192 whole subtree. This may occasionally be convenient: for example
193 suppose there are several libraries under
194 <literal>Org.Com.Microsoft</literal> that I need to import, it
195 would be easier to rename this subtree to just
196 <literal>Microsoft</literal> for use in future import
197 declarations. For example:</para>
198
199 <programlisting>
200 import Org.Com.Microsoft.* as Microsoft.*
201 import Microsoft.Foo
202 import Microsoft.Bar
203 ...
204 </programlisting>
205
206 <para>The exact syntax of the renaming declaration is up for
207 debate (as is whether we need it at all), please send
208 suggestions to <email>libraries@haskell.org</email>.</para>
209 </sect2>
210 -->
211
212
213 <sect1 id="layout">
214 <title>The hierarchy</title>
215
216 <para>We first classify each node in the hierarchy according to
217 one of the following terms:</para>
218
219 <variablelist>
220 <varlistentry>
221 <term>Allocated</term>
222 <listitem>
223 <para>Nodes in the hierarchy can be allocated to a library.
224 The currently allocated nodes are specified in <xref
225 linkend="allocated-names"/>.</para>
226 </listitem>
227 </varlistentry>
228
229 <varlistentry>
230 <term>User</term>
231 <listitem>
232 <para>The <literal>User</literal> hierarchy is reserved for
233 users: a user may always use the portion of the hierarchy
234 which is formed from his/her email address as follows:
235 replace any <quote><literal>.</literal></quote>s in the
236 username (before the <literal>@</literal>) with
237 <quote><literal>_</literal></quote>, replace the
238 <quote><literal>@</literal></quote> by a
239 <quote><literal>.</literal></quote>, reverse the order of
240 the components, capitalise the first letter of each
241 component, and prepend
242 <quote><literal>User.</literal></quote>. For example,
243 <literal>simonmar@microsoft.com</literal> becomes
244 <literal>User.Com.Microsoft.Simonmar</literal>.</para>
245 </listitem>
246 </varlistentry>
247
248 <varlistentry>
249 <term>Organisation</term>
250 <listitem>
251 <para>The <literal>Org</literal> hierarchy is reserved for
252 organisations. Any organisation with a DNS domain name owns
253 a unique space in the hierarchy formed by reversing the
254 components of the domain, capitalising the first character
255 of each component, and prepending <literal>Org.</literal>.
256 <emphasis>ToDo: the Org name isn't great, especially when
257 the domain name also ends with Org (eg. Org.Org.Haskell?).
258 Contrib has also been suggested.</emphasis></para>
259 </listitem>
260 </varlistentry>
261
262 <varlistentry>
263 <term>Local</term>
264 <listitem>
265 <para>The <literal>Local</literal> hierarchy is reserved for
266 libraries which are local to the current site. Libraries
267 which are to be distributed outside the current site should
268 not be placed in the <literal>Local</literal>
269 hierarchy.</para>
270 </listitem>
271 </varlistentry>
272
273 <varlistentry>
274 <term>Unallocated</term>
275 <listitem>
276 <para>Any node which doesn't belong to any of the above
277 categories is currently unallocated, and is available for
278 use by Haskell programs.</para>
279 </listitem>
280 </varlistentry>
281 </variablelist>
282
283 <para>A node in the hierarchy may be both a specific library and a
284 parent node for a number of child nodes. For example,
285 <literal>Foreign</literal> is a library, and so is
286 <literal>Foreign.Ptr</literal>.</para>
287
288 <sect2 id="hierarchy-design-guidelines">
289 <title>Hierarchy design guidelines</title>
290
291 <para>Apart from the <literal>User</literal>,
292 <literal>Local</literal> and <literal>Org</literal> top-level
293 categories, the rest of the hierarchy is organised with a single
294 principle in mind:</para>
295
296 <blockquote>
297 <para>Modules are grouped by
298 <emphasis>functionality</emphasis>, since this is the single
299 property that is most helpful for a user of the library - we
300 want users to be able to find out where to obtain
301 functionality easily, and to easily find all the modules that
302 provide relevant functionality.</para>
303
304 <para>So, if two modules provide similar functionality, or
305 alternative interfaces to the same functionality, then they
306 should be children of the same node in the hierarchy. Modules
307 should not be grouped by standards compliance, portability,
308 stability, or any other property.</para>
309 </blockquote>
310
311 <para>It should be noted that this is a guideline rather than a
312 rule: sometimes it just isn't the right thing. For example, the
313 <literal>DotNet</literal> top-level name contains a mirror of
314 the Microsoft .NET base class library; if we had gone purely by
315 functionality then these libraries would have to be scattered
316 around the hierarchy, resulting in a situation where it would
317 probably be <emphasis>harder</emphasis> for a programmer to find
318 the functionality he or she is interested in.</para>
319
320 <para>There are some other considerations when choosing where to
321 place libraries. Where possible, choose a layout that finds a
322 good compromise between depth of nesting and logical grouping of
323 functionality; for example, although the <literal>Text</literal>
324 hierarchy could logically be placed as a child of
325 <literal>FileFormat</literal>, we choose not to because
326 <literal>Text</literal> is ubiquitous and we don't want to have
327 to type the extra component all the time.</para>
328
329 <para>Also consider consistency: if a particular sub-hierarchy
330 provides similar functionality to another sub-hierarchy in the
331 tree, then preferably the structure of the two subtrees should
332 also be similar. For example: under
333 <literal>Language.Haskell</literal> we have children
334 <literal>Syntax</literal>, <literal>Lexer</literal>,
335 <literal>Parser</literal> etc., so under
336 <literal>Language.C</literal> we should have a similar
337 structure.</para>
338 </sect2>
339
340 <sect2 id="module-naming-convention">
341 <title>Module naming conventions</title>
342
343 <itemizedlist>
344 <listitem>
345 <para>A module defining a data type or type class
346 <replaceable>X</replaceable> has itself the name
347 <replaceable>X</replaceable>, e.g.
348 <literal>StablePtr</literal>.</para>
349 </listitem>
350
351 <listitem>
352 <para>A module which re-exports the modules in a subtree of
353 the hierarchy has the same name as the root of that subtree,
354 eg. <literal>Foreign</literal> re-exports
355 <literal>Foreign.Ptr</literal>,
356 <literal>Foreign.Marshal.Utils</literal> etc.</para>
357 </listitem>
358
359 <listitem>
360 <para>If a subtree of the hierarchy contains several modules
361 which provide similar functionality (eg. there are several
362 pretty-printing libraries under
363 <literal>Text.PrettyPrinter</literal>), then the module at
364 the root of the subtree generally re-exports just
365 <emphasis>one</emphasis> of the modules in the subtree
366 (possibly the most popular or commonly-used
367 alternative).</para>
368 </listitem>
369
370 <listitem>
371 <para>In Haskell you sometimes publish
372 <emphasis>two</emphasis> interfaces to your libraries; one
373 for users, and one for library writers or advanced users who
374 might want to extend things. Typically the advanced users
375 need to be able to see past certain abstractions.</para>
376
377 <para>The current proposal is for a module named
378 <literal>M</literal>, the <quote>advanced</quote> version
379 would be named <literal>M.Internals</literal>. eg.</para>
380
381 <programlisting>
382 import Text.HTML -- The library
383 import Text.HTML.Internals -- The non-abstract library
384 </programlisting>
385 </listitem>
386
387 <listitem>
388 <para>Acronyms are fully capitalised in a module name.
389 eg. <literal>HTML</literal>, <literal>URI</literal>,
390 <literal>CGI</literal>, etc. Exceptions may be made for
391 acronyms which have an existing well-established alternative
392 capitalisation, or acronyms which are also valid words, and
393 are more often used as such.</para>
394 </listitem>
395
396 <listitem>
397 <para>A module name should be made plural only if the module
398 actually defines multiple entities of a particular kind:
399 eg. <literal>Foreign.C.Types</literal>. Most module names
400 which define a type or class will follow the name of the
401 type or class, so whether to pluralize is not an
402 issue.</para>
403 </listitem>
404 </itemizedlist>
405 </sect2>
406
407 <sect2 id="top-level-names">
408 <title>The top-level names</title>
409
410 <para>The currently allocated nodes in the hierarchy are listed
411 in the next section (<xref linkend="allocated-names"/>). In
412 addition, for each top-level name we describe its intended
413 purpose below:</para>
414
415 <variablelist>
416 <varlistentry>
417 <term><literal>Control</literal></term>
418 <listitem>
419 <para>Libraries which provide functions, types or classes
420 whose purpose is primarily to express control
421 structure.</para>
422 </listitem>
423 </varlistentry>
424
425 <varlistentry>
426 <term><literal>Data</literal></term>
427 <listitem>
428 <para>Libraries which provide data types, operations over
429 data types, or type classes, except for libraries for
430 which one of the other more specific categories is
431 appropriate.</para>
432 </listitem>
433 </varlistentry>
434
435 <varlistentry>
436 <term><literal>Database</literal></term>
437 <listitem>
438 <para>Libraries for providing access to or operations for
439 building databases.</para>
440 </listitem>
441 </varlistentry>
442
443 <varlistentry>
444 <term><literal>Debug</literal></term>
445 <listitem>
446 <para>Support for debugging Haskell programs.</para>
447 </listitem>
448 </varlistentry>
449
450 <varlistentry>
451 <term><literal>DotNet</literal></term>
452 <listitem>
453 <para>Mirrors the Microsoft .NET base class hierarchy, for
454 systems providing access to the .NET libraries.</para>
455 </listitem>
456 </varlistentry>
457
458 <varlistentry>
459 <term><literal>Edison</literal></term>
460 <listitem>
461 <para>The Edison data structure library.</para>
462 </listitem>
463 </varlistentry>
464
465 <varlistentry>
466 <term><literal>Codec</literal></term>
467 <listitem>
468 <para>Support for (en)coding and decoding data in various
469 formats. <literal>Codec</literal> encompasses compression
470 (both lossy and non-lossy) codings, transport
471 codings, and encryption.</para>
472 </listitem>
473 </varlistentry>
474
475 <varlistentry>
476 <term><literal>Foreign</literal></term>
477 <listitem>
478 <para>Interaction with code written in a foreign
479 programming language.</para>
480 </listitem>
481 </varlistentry>
482
483 <varlistentry>
484 <term><literal>Graphics</literal></term>
485 <listitem>
486 <para>Libraries for producing graphics or providing
487 graphical user interfaces.</para>
488 </listitem>
489 </varlistentry>
490
491 <varlistentry>
492 <term><literal>Language</literal></term>
493 <listitem>
494 <para>Libraries for operating on or generating source code
495 in various programming languages, including parsers,
496 pretty printers, abstract syntax definitions etc.</para>
497 </listitem>
498 </varlistentry>
499
500 <varlistentry>
501 <term><literal>Local</literal></term>
502 <listitem>
503 <para>Available for site-local use.</para>
504 </listitem>
505 </varlistentry>
506
507 <varlistentry>
508 <term><literal>Numeric</literal></term>
509 <listitem>
510 <para>Functions and classes which provide operations over
511 numeric data.</para>
512 </listitem>
513 </varlistentry>
514
515 <varlistentry>
516 <term><literal>Network</literal></term>
517 <listitem>
518 <para>Libraries for communicating over a network,
519 including implementations of network protocols.</para>
520 </listitem>
521 </varlistentry>
522
523 <varlistentry>
524 <term><literal>Org</literal></term>
525 <listitem>
526 <para>Allocated to organisations on a domain-name
527 basis (see <xref linkend="layout"/>).</para>
528 </listitem>
529 </varlistentry>
530
531 <varlistentry>
532 <term><literal>Prelude</literal></term>
533 <listitem>
534 <para>Haskell98 Prelude (mostly just re-exports other
535 parts of the tree).</para>
536 </listitem>
537 </varlistentry>
538
539 <varlistentry>
540 <term><literal>System</literal></term>
541 <listitem>
542 <para>Libraries for communication with the system on which
543 the Haskell program is running (including the runtime
544 system).</para>
545 </listitem>
546 </varlistentry>
547
548 <varlistentry>
549 <term><literal>Text</literal></term>
550 <listitem>
551 <para>Libraries for parsing and generating data in a
552 textual format (including structured textual formats such
553 as XML, HTML, but not including programming language
554 source, which lives in Language).</para>
555 </listitem>
556 </varlistentry>
557
558 <varlistentry>
559 <term><literal>GHC</literal></term>
560 <listitem>
561 <para>Libraries specific to the GHC/GHCi system.</para>
562 </listitem>
563 </varlistentry>
564
565 <varlistentry>
566 <term><literal>Nhc</literal></term>
567 <listitem>
568 <para>Libraries specific to the Nhc compiler.</para>
569 </listitem>
570 </varlistentry>
571
572 <varlistentry>
573 <term><literal>Hugs</literal></term>
574 <listitem>
575 <para>Libraries specific to the Hugs system.</para>
576 </listitem>
577 </varlistentry>
578
579 <varlistentry>
580 <term><literal>User</literal></term>
581 <listitem>
582 <para>Allocated to individual users, using email
583 addresses (see <xref linkend="layout"/>).</para>
584 </listitem>
585 </varlistentry>
586 </variablelist>
587 </sect2>
588
589 <sect2 id="allocated-names">
590 <title>Allocated libraries</title>
591
592 <informaltable>
593 <tgroup cols="3" align="left" colsep="1" rowsep="1">
594 <thead>
595 <row>
596 <entry>Library</entry>
597 <entry>Maintainer</entry>
598 <entry>URL</entry>
599 </row>
600 </thead>
601 <tbody>
602 &libtable;
603 </tbody>
604 </tgroup>
605 </informaltable>
606 </sect2>
607 </sect1>
608
609 <sect1 id="reference-libraries">
610 <title>Reference libraries</title>
611
612 <para>There are reference implementations for many of the
613 libraries allocated in the hierarchy (see <xref
614 linkend="allocated-names"/>). These reference libraries serve to define
615 the API for each library, and also in most cases provide the
616 primary implementation of that library. We don't discount the
617 possibility that multiple implementations of libraries may exist,
618 but there is only ever one reference implementation.</para>
619
620 <para>Many of the reference libraries live in the CVS repository
621 on <literal>cvs.haskell.org</literal> under the directory <ulink
622 url="http://cvs.haskell.org/cgi-bin/cvsweb.cgi/fptools/libraries"><literal>fptools/libraries</literal></ulink>,
623 but others are maintained and distributed separately by members of
624 the Haskell community. <xref linkend="allocated-names"/> lists the
625 maintainer for each reference library, and a location from which
626 the code can be obtained.</para>
627
628 <sect2 id="installing">
629 <title>Installing libraries</title>
630
631 <para>Compilers are normally distributed with a number of
632 libraries, which may or may not be built from the reference
633 implementations.</para>
634
635 <para>Currently, the procedure for installing a library which is
636 not distributed with your compiler is currently dependent on a
637 number of things: platform, compiler, and how much support is
638 provided by the library maintainer. We aim to standardise this
639 procedure to a certain extent by providing a library
640 infrastructure which automates the building, installation and
641 packaging of libraries for all architectures and compilers. The
642 means by which we might achieve this are being actively
643 discussed: see the <ulink
644 url="http://www.haskell.org/pipermail/libraries/">libraries
645 mailing list archives</ulink>.</para>
646 </sect2>
647
648 <sect2 id="contributing-reference-libraries">
649 <title>Contributing new reference libraries</title>
650
651 <para>The process for contributing a new library is as
652 follows:</para>
653
654 <variablelist>
655 <varlistentry>
656 <term>Allocate module names.</term>
657 <listitem>
658 <para>If you want a library in the <literal>User</literal>
659 or <literal>Org</literal> part of the hierarchy, then
660 nothing needs to be done: just go ahead and distribute
661 your library.</para>
662
663 <para>If, however, you are providing a library for any
664 other part of the hierarchy, then the module names in the
665 should be allocated. <xref linkend="allocated-names"/>
666 lists the parts of the hierarchy that are currently
667 allocated.</para>
668
669 <para>There are several reasons for allocating module
670 names centrally in this way:</para>
671
672 <itemizedlist>
673 <listitem>
674 <para>Haskell users have the guarantee that libraries
675 never conflict with each other by using the same
676 module name.</para>
677 </listitem>
678 <listitem>
679 <para>There is always one place to obtain a given
680 library, each library has a single reference
681 implementation, and there is a single point of contact
682 for the implementor(s).</para>
683 </listitem>
684 </itemizedlist>
685
686 <para>Remember that this only applies to libraries: code
687 in a <emphasis>program</emphasis> can use whatever module
688 names it chooses (but it's probably a good idea to avoid
689 conflicting with any libraries that might be installed:
690 avoiding the allocated module names is a good way to
691 ensure that).</para>
692
693 <para>To allocate module names for a new library, send
694 mail to <email>libraries@haskell.org</email> describing
695 your library and which module names you are proposing to
696 allocate. Provided there is no conflict, then the names
697 will normally be allocated and added to the list above. A
698 conflict might arise if for example someone else wants to
699 provide a library with the same name; conflicts will be
700 resolved by consensus on a case-by-case basis.</para>
701 </listitem>
702 </varlistentry>
703
704 <varlistentry>
705 <term>Distribute the library.</term>
706 <listitem>
707 <para>The mechanism by which libraries should be
708 distributed is currently being discussed; we hope in the
709 future to make the process much easier for library
710 writers. Currently you have to do all the work yourself:
711 write a build system (or steal one), installation scripts
712 and support for packaging on each platform that you wish
713 to support.</para>
714 </listitem>
715 </varlistentry>
716 </variablelist>
717 </sect2>
718
719 <sect2 id="licensing">
720 <title>Licensing</title>
721
722 <para>Following some discussion on the mailing list related to
723 how we should license the libraries, the viewpoint that was
724 least offensive to all involved seems to be the
725 following:</para>
726
727 <para>We wish to accommodate source code from different
728 contributors, and with different licenses. However, a library
729 of modules where each module is released under a different
730 license, and where the dependencies between modules aren't
731 clear, isn't workable (it's too hard for a user of the library
732 to tell whether they're violating the terms of the each license
733 or not).</para>
734
735 <para>So the solution is as follows: code under different
736 licenses will be clearly separate in the repository (i.e. in
737 separate subdirectories), and compilers are expected to present
738 packages of modules where all modules in a package fall under
739 the same license, and where the dependencies between packages
740 are clear.</para>
741
742 <para>It was decided that certain essential functionality should
743 be available under a BSD style license. Hence, the BSD part of
744 the repository will contain implementations of at least the
745 following modules: <literal>Prelude</literal>,
746 <literal>Foreign</literal>, <emphasis>ToDo: what
747 else?</emphasis>.</para>
748
749 <para>There is one further requirement: reference libraries must
750 be available under a license approved by the Open Source
751 Initiative. See <ulink url="http://www.opensource.org//">The
752 Open Source Initiative</ulink> for a list of approved
753 licensees.</para>
754 </sect2>
755
756 <sect2 id="versioning">
757 <title>Versioning</title>
758 <para><emphasis>ToDo</emphasis></para>
759 </sect2>
760
761 <sect2 id="stability">
762 <title>Library stability</title>
763
764 <para>The stability of a library relates primarily to its API.
765 Stability provides an indication of how often the API is likely
766 to change (or whether it may even go away entirely).</para>
767
768 <para>The stability scale is also a measure of how strictly the
769 conventions in this document are applied to the library: an
770 experimental library isn't subject to any restrictions regarding
771 coding style and documentation, but a stable library is expected
772 to adhere to the guidelines, and come with full documentation
773 and tests.</para>
774
775 <para>To help with the stability issue, library maintainers are
776 allowed to mark functions, types or classes as
777 <firstterm>deprecated</firstterm><footnote><para>Compilers may
778 have extra support for warning about the use of a deprecated
779 feature, for example GHC's <literal>DEPRECATED</literal>
780 pragma.</para> </footnote>, which means simply that the feature
781 will be removed at a later date. Just how long it will stick
782 around for depends on the stability category of the library (see
783 below). A feature is marked as deprecated in the documentation
784 for the library, and optionally in an implementation-dependent
785 way which enables the system to warn about the use of deprecated
786 features.</para>
787
788 <para>The current stability categories are:</para>
789
790 <variablelist>
791 <varlistentry>
792 <term><firstterm>experimental</firstterm></term>
793 <listitem>
794 <para>An experimental library is unrestricted in terms of
795 API changes: the API may change between minor revisions
796 and there is no requirement to retain old interfaces for
797 compatibility. Documentation and tests aren't required
798 for an experimental library.</para>
799 </listitem>
800 </varlistentry>
801 <varlistentry>
802 <term><firstterm>provisional</firstterm></term>
803 <listitem>
804 <para>A provisional library is moving towards stability,
805 and the rate of change of the API is slower. API changes
806 between minor revisions must be accompanied by deprecated
807 versions of the old features where possible. API changes
808 between major versions are unrestricted. The library
809 should come with at least rudimentary
810 documentation.</para>
811 </listitem>
812 </varlistentry>
813 <varlistentry>
814 <term><firstterm>stable</firstterm></term>
815 <listitem>
816 <para>A stable library has an essentially fixed API.
817 Additions to the API may be made for a minor release,
818 deprecated features must be retained for at least one
819 major revision, and small changes only may be made to the
820 existing API semantics for a major revision. A stable
821 library is expected to include full documentation and
822 tests.</para>
823 </listitem>
824 </varlistentry>
825 </variablelist>
826
827 </sect2>
828
829 <sect2 id="portability">
830 <title>Portability considerations</title>
831
832 <para>The portability status of a library affects which
833 platforms and compilers the library will be available on. The
834 precise meaning of the terms portable and non-portable for our
835 purposes are given below:</para>
836
837 <variablelist>
838 <varlistentry>
839 <term><firstterm>Portable</firstterm></term>
840 <listitem>
841 <para>A library which is available on all platforms and
842 with all Haskell implementations is portable.</para>
843
844 <para>A portable library may make use of non-portable
845 features or import non-portable libraries in its
846 implementation, as long as it does so conditionally and
847 provides the same interface on all platforms and with all
848 Haskell implementations.</para>
849 </listitem>
850 </varlistentry>
851 <varlistentry>
852 <term><firstterm>Non-portable</firstterm></term>
853 <listitem>
854 <para>A non-portable library may be non-portable for one
855 or more of the following reasons:</para>
856 <variablelist>
857 <varlistentry>
858 <term><firstterm>Requires extensions</firstterm></term>
859 <listitem>
860 <para>A library which uses non-approved language
861 extensions in its implementation, and has no
862 portable fallback implementation.</para>
863 </listitem>
864 </varlistentry>
865 <varlistentry>
866 <term><firstterm>Requires nonportable libraries</firstterm></term>
867 <listitem>
868 <para>A library which depends (directly or indirectly)
869 on other non-portable libraries.</para>
870 </listitem>
871 </varlistentry>
872 <varlistentry>
873 <term><firstterm>OS-specific</firstterm></term>
874 <term><firstterm>Platform-specific</firstterm></term>
875 <listitem>
876 <para>A library which depends on features or APIs
877 particular to a certain OS or platform is
878 non-portable for that reason.</para>
879 </listitem>
880 </varlistentry>
881 </variablelist>
882 </listitem>
883 </varlistentry>
884 </variablelist>
885
886 <sect3 id="approved-extensions">
887 <title>Approved extensions</title>
888
889 <para>Very few of the reference libraries can be implemented
890 using pure Haskell 98. For this reason, we decided to raise
891 the baseline for portable libraries to include a few common
892 extensions; the following language extensions can be
893 <emphasis>assumed</emphasis> to be present when writing
894 libraries:</para>
895
896 <itemizedlist>
897 <listitem>
898 <para>The <ulink
899 url="http://haskell.org/ghc/docs/latest/set/ffi.html">Foreign
900 Function Interface</ulink>.</para>
901 </listitem>
902 <listitem>
903 <para>Mutable variables
904 (<literal>Data.IORef</literal>).</para>
905 </listitem>
906 <listitem>
907 <para>Unsafe IO monad operations
908 (<literal>System.IO.Unsafe</literal>).</para>
909 </listitem>
910 <listitem>
911 <para>Packed strings
912 (<literal>Data.PackedString</literal>).</para>
913 </listitem>
914 <listitem>
915 <para>Bit operations (<literal>Data.Bits</literal>).</para>
916 </listitem>
917 </itemizedlist>
918
919 <para>Extensions which we'd like to be standard, but aren't
920 currently implemented by one or more of the target
921 compilers:</para>
922
923 <itemizedlist>
924 <listitem>
925 <para>Exceptions (synchronous only), defined by the
926 <literal>Control.Exception</literal> interface.</para>
927 </listitem>
928 <listitem>
929 <para>The ST monad, defined by
930 <literal>Control.Monad.ST</literal>, and the associated
931 <literal>Data.Array.ST</literal> and
932 <literal>Data.STRef</literal> libraries. ST requires a
933 small typechecker extension for the
934 <literal>runST</literal> function.</para>
935 </listitem>
936 <listitem>
937 <para>Concurrent Haskell (pre-emptive multitasking
938 optional). GHC and Hugs implement this, but Nhc currently
939 does not.</para>
940 </listitem>
941 </itemizedlist>
942
943 <para>The following extensions are not likely to become part
944 of the baseline, but are nevertheless used by one or more
945 libraries in the reference set (which are thus designated
946 non-portable):</para>
947
948 <itemizedlist>
949 <listitem>
950 <para>Multi-parameter type classes.</para>
951 </listitem>
952 <listitem>
953 <para>Local universal and existential quantification.</para>
954 </listitem>
955 <listitem>
956 <para>Concurrent Haskell with pre-emptive multitasking.</para>
957 </listitem>
958 <listitem>
959 <para>Asynchronous exceptions.</para>
960 </listitem>
961 <listitem>
962 <para>Stable Names.</para>
963 </listitem>
964 <listitem>
965 <para>Weak Pointers.</para>
966 </listitem>
967 </itemizedlist>
968
969 <para>Other extensions are supported by a single compiler
970 only, and can be accessed by libraries under the top level
971 hierarchy for that compiler,
972 eg. <literal>GHC.UnboxedTypes</literal>.</para>
973 </sect3>
974 </sect2>
975
976 <sect2 id="maintainership">
977 <title>Library maintainers</title>
978
979 <para>This is a collaborative project, so we like to devolve
980 control of the design and implementation of libraries to those
981 with an interest or appropriate expertise (or maybe just the
982 time!). A maintainer isn't necessarily a single person - for
983 example, the listed maintainer for most of the reference
984 libraries is <email>libraries@haskell.org</email>, indicating
985 that the library is under the control of the community as a
986 whole. The maintainer for the <literal>Foreign</literal>
987 hierarchy is <email>ffi@haskell.org</email>, the mailing list
988 for discussion of the Haskell FFI standard.</para>
989
990 <para>The responsibilities of a library maintainer include:</para>
991
992 <itemizedlist>
993 <listitem>
994 <para>Most importantly: act as a single point of contact for
995 issues relating to the library API and its
996 implementation.</para>
997 </listitem>
998 <listitem>
999 <para>Manage any discussion related to the library (which
1000 can take place on <email>libraries@haskell.org</email> if
1001 necessary), and summarise the results. Make final
1002 decisions, and implement them.</para>
1003 </listitem>
1004 <listitem>
1005 <para>Maintain the implementation, including: fixing bugs,
1006 updating to keep up with changes in other libraries, porting
1007 to new compilers/platforms, and integrating code from other
1008 contributors. The maintainer is expected to be the only
1009 person/group to make functional changes to the source code
1010 (non-functional or trivial changes don't count).</para>
1011 </listitem>
1012 <listitem>
1013 <para>Maintain/write the documentation and tests.</para>
1014 </listitem>
1015 <listitem>
1016 <para>If you can't maintain the library any more for
1017 whatever reason, tell <email>libraries@haskell.org</email>
1018 and we'll revert the maintainer status of the library to the
1019 default.</para>
1020 </listitem>
1021 </itemizedlist>
1022 </sect2>
1023
1024 <sect2 id="documentation">
1025 <title>Documentation</title>
1026
1027 <para>We are using <ulink
1028 url="http://www.haskell.org/haddock/">Haddock</ulink> to
1029 document the libraries. Haddock generates nice hyperlinked HTML
1030 output directly from the Haskell source, and understands
1031 comments written in a particular style as documentation
1032 annotations, which are merged with the generated
1033 documentation.</para>
1034
1035 <para>Before submitting code to the libraries project, please
1036 ensure that it passes through Haddock without complaint. Even
1037 if it contains no actual documentation annotations, we'll get
1038 useful documentation out of the source alone (type signatures,
1039 data types, etc.).</para>
1040 </sect2>
1041
1042 <sect2 id="coding-style">
1043 <title>Coding style</title>
1044
1045 <sect3 id="module-header">
1046 <title>Standard module header</title>
1047
1048 <para>Using a standard module header makes it easy to
1049 automatically extract meta-information from library source
1050 code, such as the stability/portability of individual modules.
1051 We recommend using the following module header for reference
1052 libraries:</para>
1053
1054 <programlisting>
1055 -----------------------------------------------------------------------------
1056 -- |
1057 -- Module : <replaceable>module</replaceable>
1058 -- Copyright : (c) <replaceable>author</replaceable> <replaceable>year</replaceable>
1059 -- License : <replaceable>license</replaceable>
1060 --
1061 -- Maintainer : libraries@haskell.org | <replaceable>email-address</replaceable>
1062 -- Stability : experimental | provisional | stable
1063 -- Portability : portable | non-portable (<replaceable>reason(s)</replaceable>)
1064 --
1065 -- &dollar;Id&dollar;
1066 --
1067 -- <replaceable>Description</replaceable>
1068 -----------------------------------------------------------------------------
1069 </programlisting>
1070
1071 <para>where:</para>
1072
1073 <variablelist>
1074 <varlistentry>
1075 <term><literal>$Id: libraries.xml,v 1.2 2004/08/18 16:42:56 panne Exp $</literal></term>
1076 <listitem>
1077 <para>is optional, but may be included if the module is
1078 under CVS or RCS control (however, current wisdom
1079 suggests that using
1080 <literal>&dollar;Id&dollar;</literal> tags are not such
1081 a great idea).</para>
1082 </listitem>
1083 </varlistentry>
1084
1085 <varlistentry>
1086 <term><replaceable>module</replaceable></term>
1087 <listitem>
1088 <para>is the fully qualified module name of the
1089 module</para>
1090 </listitem>
1091 </varlistentry>
1092
1093 <varlistentry>
1094 <term><replaceable>author</replaceable>/<replaceable>year</replaceable></term>
1095 <listitem>
1096 <para>Is the primary author and copyright holder of the
1097 module, and the year in which copyright is
1098 claimed.</para>
1099 </listitem>
1100 </varlistentry>
1101
1102 <varlistentry>
1103 <term><replaceable>license</replaceable></term>
1104 <listitem>
1105 <para>Specifies the license on the file (see <xref
1106 linkend="licensing"/>).</para>
1107 </listitem>
1108 </varlistentry>
1109
1110 <varlistentry>
1111 <term><replaceable>email-address</replaceable></term>
1112 <listitem>
1113 <para>The email address of the maintainer, or
1114 maintainers, of the library (see <xref
1115 linkend="maintainership"/>).</para>
1116 </listitem>
1117 </varlistentry>
1118
1119 <varlistentry>
1120 <term><replaceable>reason(s)</replaceable></term>
1121 <listitem>
1122 <para>The reasons for non-portability must be listed
1123 (see <xref linkend="portability"/>).</para>
1124 </listitem>
1125 </varlistentry>
1126
1127 <varlistentry>
1128 <term><replaceable>description</replaceable></term>
1129 <listitem>
1130 <para>A short description of the module.</para>
1131 </listitem>
1132 </varlistentry>
1133 </variablelist>
1134 </sect3>
1135 </sect2>
1136
1137 <sect2 id="testing">
1138 <title>Testing</title>
1139 <para><emphasis>ToDo</emphasis></para>
1140 </sect2>
1141 </sect1>
1142
1143 <sect1 id="Migration-path">
1144 <title>Migration path</title>
1145
1146 <para>How compatible will a compiler using the new libraries be
1147 with code written for Haskell 98 or older library systems (such as
1148 the <literal>hslibs</literal> suite and GHC's package system), and
1149 for how long will compatibility be maintained?</para>
1150
1151 <para>Our current plan for GHC is as follows: by default, with the
1152 <option>-fglasgow-exts</option> flag, you'll get access to the
1153 following libraries from the CVS repository: those under
1154 <literal>base</literal>, <literal>network</literal>,
1155 <literal>unix</literal>, <literal>readline</literal>,
1156 <literal>template-haskell</literal>, and
1157 <literal>haskell-src</literal>. Compatibility with Haskell 98
1158 code will be maintained using a separate package of wrappers
1159 presenting interfaces for the Haskell 98 libraries
1160 (<literal>IO</literal>, <literal>Ratio</literal>,
1161 <literal>Directory</literal>, etc.). The Haskell 98 compatibility
1162 package will be enabled by default, but we plan to add an option
1163 to disable it if necessary. For code that uses <literal>-package
1164 lang</literal>, we could also provide a compatibility wrapper
1165 package (so <literal>-package lang</literal> will continue to work
1166 as before and present the same library interfaces), but this may
1167 prove too much work to maintain - we haven't decided whether to do
1168 this or not. It is unlikely that compatibility wrappers for any
1169 of the other <literal>hslibs</literal> packages will be
1170 provided.</para>
1171 </sect1>
1172
1173 <sect1 id="library-design">
1174 <title>Library design</title>
1175
1176 <sect2 id="naming-conventions">
1177 <title>Naming conventions</title>
1178
1179 <para>These naming conventions are pulled straight from the
1180 <literal>hslibs</literal> documentation. They were formed after
1181 lengthy discussions and are heavily based on an initial
1182 suggestion from Marcin Kowalczyk
1183 <email>qrczak@knm.org.pl</email>.</para>
1184
1185 <para>Note that the conventions are not mutually exclusive,
1186 e.g. should the function creating a set from a list of elements
1187 have the name <literal>set</literal> or
1188 <literal>listToSet</literal>? (Alas, it currently has neither
1189 name.)</para>
1190
1191 <para> The following nomenclature is used: Pure,
1192 i.e. non-monadic functions are simply called, well,
1193 <emphasis>functions</emphasis>. Monadic functions,
1194 i.e. functions having a type <literal>... -&#62; m a</literal>
1195 for some Monad <literal>m</literal> are called
1196 <emphasis>actions</emphasis>.</para>
1197
1198 <sect3 id="sec-library-constructor-names">
1199 <title>Constructor names</title>
1200 <indexterm><primary>Constructor names</primary></indexterm>
1201
1202 <itemizedlist>
1203 <listitem>
1204 <para>Empty values of type <replaceable>X</replaceable>
1205 have the name <literal>empty<replaceable>X</replaceable></literal>,
1206 e.g. <literal>emptySet</literal>.</para>
1207 </listitem>
1208
1209 <listitem>
1210 <para>Actions creating a new empty value of type
1211 <replaceable>X</replaceable> have the name
1212 <literal>newEmpty<replaceable>X</replaceable></literal>,
1213 e.g. <literal>newEmptyMVar</literal>.</para>
1214 </listitem>
1215
1216 <listitem>
1217 <para>Functions creating an arbitrary value of type
1218 <replaceable>X</replaceable> have the name
1219 <replaceable>X</replaceable> itself (with the first letter
1220 downcased),
1221 e.g. <literal>array</literal>. (<emphasis>TODO</emphasis>:
1222 This often collides with <literal>xToY</literal>
1223 convention, how should this be resolved?)
1224 </para>
1225 </listitem>
1226
1227 <listitem>
1228 <para>Actions creating new values arbitrary values of type
1229 <replaceable>X</replaceable> have the name
1230 <literal>new<replaceable>X</replaceable></literal>,
1231 e.g. <literal>newIORef</literal>.
1232 </para>
1233 </listitem>
1234 </itemizedlist>
1235 </sect3>
1236
1237 <sect3 id="sec-library-accessor-names">
1238 <title>Accessor names</title>
1239 <indexterm><primary>Accessor names</primary></indexterm>
1240
1241 <itemizedlist>
1242 <listitem>
1243 <para>Functions getting an attribute of a value or a part
1244 of it have the name of the attribute itself,
1245 e.g. <literal>length</literal>, <literal>bounds</literal>.
1246 </para>
1247 </listitem>
1248
1249 <listitem>
1250 <para> Actions accessing some kind of reference or state
1251 have the name
1252 <literal>get<replaceable>X</replaceable></literal>, where
1253 <replaceable>X</replaceable> is the type of the contents
1254 or the name of the part being accessed,
1255 e.g. <literal>getChar</literal>,
1256 <literal>getEnv</literal>. An alternative naming scheme is
1257 <literal>read<replaceable>Y</replaceable></literal>,
1258 where <replaceable>Y</replaceable> is the type of the
1259 reference or container, e.g. <literal>readIORef</literal>.
1260 </para>
1261 </listitem>
1262
1263 <listitem>
1264 <para>Functions or actions getting a value via a
1265 pointer-like type <replaceable>X</replaceable> should be
1266 named
1267 <literal>deRef<replaceable>X</replaceable></literal>,
1268 e.g. <literal>deRefStablePtr</literal>,
1269 <literal>deRefWeak</literal>.</para>
1270 </listitem>
1271 </itemizedlist>
1272 </sect3>
1273
1274 <sect3 id="sec-library-modifier-names">
1275 <title>Modifier names</title>
1276 <indexterm><primary>Modifier names</primary></indexterm>
1277
1278 <itemizedlist>
1279 <listitem>
1280 <para>Functions returning a value with attribute
1281 <replaceable>X</replaceable> set to a new value should be
1282 named
1283 <literal>set<replaceable>X</replaceable></literal>. (<emphasis>TODO</emphasis>:
1284 Add Examples.)</para>
1285 </listitem>
1286
1287 <listitem>
1288 <para> Actions setting some kind of reference or state
1289 have the name
1290 <literal>put<replaceable>X</replaceable></literal>, where
1291 <replaceable>X</replaceable> is the type of the contents
1292 or the name of the part being accessed,
1293 e.g. <literal>putChar</literal>. An alternative naming
1294 scheme is
1295 <literal>write<replaceable>Y</replaceable></literal>,
1296 where <replaceable>X</replaceable> is the type of the
1297 reference or container,
1298 e.g. <literal>writeIORef</literal>. </para></listitem>
1299
1300 <listitem>
1301 <para> Actions in the <literal>IO</literal> monad setting
1302 some global state <replaceable>X</replaceable> are
1303 traditionally named <literal>setX</literal>, too, although
1304 <literal>put<replaceable>X</replaceable></literal> would
1305 be more appropriate,
1306 e.g. <literal>setReadlineName</literal>.</para>
1307 </listitem>
1308
1309 <listitem>
1310 <para> Actions modifying a container
1311 <replaceable>X</replaceable> by a function of type
1312 <literal>a -> a</literal> have the name
1313 <literal>modify<replaceable>X</replaceable></literal>,
1314 e.g. <literal>modifySTRef</literal>.</para>
1315 </listitem>
1316 </itemizedlist>
1317 </sect3>
1318
1319 <sect3 id="sec-library-predicate-names">
1320 <title>Predicate names</title>
1321 <indexterm><primary>Predicate names</primary></indexterm>
1322
1323 <itemizedlist>
1324 <listitem>
1325 <para>Predicates, both non-monadic and monadic, testing a
1326 property <replaceable>X</replaceable> have the name
1327 <literal>is<replaceable>X</replaceable></literal>.
1328 </para>
1329 </listitem>
1330 </itemizedlist>
1331 </sect3>
1332
1333 <sect3 id="sec-library-naming-conversions">
1334 <title>Names for conversions</title>
1335 <indexterm><primary>Names for conversions</primary></indexterm>
1336
1337 <itemizedlist>
1338 <listitem>
1339 <para>Functions converting a value of type
1340 <replaceable>X</replaceable> to a value of type
1341 <replaceable>Y</replaceable> have the name
1342 <literal><replaceable>X</replaceable>To<replaceable>Y</replaceable></literal>
1343 with all leading uppercase characters of
1344 <replaceable>X</replaceable> converted to lower case,
1345 e.g. <literal>stToIO</literal>.</para>
1346 </listitem>
1347
1348 <listitem>
1349 <para>Overloaded conversion functions of type
1350 <literal>C a => a -> <replaceable>X</replaceable></literal>
1351 have the name
1352 <literal>to<replaceable>X</replaceable></literal>,
1353 e.g. <literal>toInteger</literal>.</para>
1354 </listitem>
1355
1356 <listitem>
1357 <para> Overloaded conversion functions of type
1358 <literal>C a => <replaceable>X</replaceable> -> a</literal>
1359 have the name <literal>from<replaceable>X</replaceable></literal>,
1360 e.g. <literal>fromInteger</literal>.</para>
1361 </listitem>
1362 </itemizedlist>
1363 </sect3>
1364
1365 <sect3 id="sec-library-misc-names">
1366 <title>Miscellaneous naming conventions</title>
1367 <indexterm><primary>Miscellaneous naming
1368 conventions</primary></indexterm>
1369
1370 <itemizedlist>
1371 <listitem>
1372 <para> An action that is identical to another one called
1373 <replaceable>X</replaceable>, but discards the return
1374 value has the name
1375 <literal><replaceable>X</replaceable>_</literal>,
1376 e.g. <literal>mapM</literal> and <literal>mapM_</literal>.
1377 </para>
1378 </listitem>
1379
1380 <listitem>
1381 <para>Functions and actions which are potentially
1382 dangerous to use and leave some kind of proof obligation
1383 to the programmer have the name
1384 <literal>unsafe<replaceable>X</replaceable></literal>,
1385 e.g. <literal>unsafePerformIO</literal>.
1386 </para>
1387 </listitem>
1388
1389 <listitem>
1390 <para>There are two conventions for binary and N-ary
1391 variants of an associative operation: One convention uses
1392 an operator or a short name for the binary operation and a
1393 long name for the N-ary variant,
1394 e.g. <literal>(+)</literal> and <literal>sum</literal>,
1395 <literal>max</literal> and <literal>maximum</literal>. The
1396 other convention suffixes the N-ary variant with
1397 <literal>Many</literal>. (<emphasis>TODO</emphasis>: Add
1398 Examples.)</para>
1399 </listitem>
1400
1401 <listitem>
1402 <para>If possible, names are chosen such that either plain
1403 application or <literal>arg1 `operation` arg2</literal> is
1404 correct English, e.g. <literal>isPrefixOf</literal> is
1405 good for use in backquotes.</para>
1406 </listitem>
1407 </itemizedlist>
1408 </sect3>
1409 </sect2>
1410
1411 <sect2 id="sec-library-misc-conventions">
1412 <title>Library design guidelines</title>
1413
1414 <itemizedlist>
1415 <listitem>
1416 <para>Actions setting and modifying a kind of reference or
1417 state return <literal>()</literal>, getting the value is
1418 separate, e.g. <literal>writeIORef</literal> and
1419 <literal>modifyIORef</literal> both return
1420 <literal>()</literal>, only <literal>readIORef</literal>
1421 returns the value in an <literal>IORef</literal>
1422 </para>
1423 </listitem>
1424
1425 <listitem>
1426 <para>A function or action taking a some kind of state and
1427 returning a pair consisting of a result and a new state, the
1428 result is the first element of the pair and the new state is
1429 the second, see e.g. <literal>Random</literal>.</para>
1430 </listitem>
1431
1432 <listitem>
1433 <para>When the type <literal>Either</literal> is used to
1434 encode an error condition and a normal result,
1435 <literal>Left</literal> is used for the former and
1436 <literal>Right</literal> for the latter, see
1437 e.g. <literal>Control.Monad.Error</literal>.</para>
1438 </listitem>
1439
1440 <listitem>
1441 <para>A module corresponding to a class
1442 (e.g. <literal>Bits</literal>) contains the class
1443 definition, perhaps some auxiliary functions, and all
1444 sensible instances for Prelude types, but nothing
1445 more. Other modules containing types for which an instance
1446 for the class in question makes sense contain the code for
1447 the instance itself.</para>
1448 </listitem>
1449
1450 <listitem>
1451 <para>Record-like C bit fields or structs have a
1452 record-like interface, i.e. pure getting and setting of
1453 fields. (<emphasis>TODO</emphasis>: Clarify a little
1454 bit. Add examples.)</para>
1455 </listitem>
1456
1457 <listitem>
1458 <para>Although the possibility of partial application
1459 suggests the type
1460
1461 <literal><replaceable>attr</replaceable> -> <replaceable>object</replaceable> -> <replaceable>object</replaceable></literal>
1462
1463 for functions setting an attribute or value, infix notation
1464 with backquotes implies
1465
1466 <literal><replaceable>object</replaceable> -> <replaceable>attr</replaceable> -> <replaceable>object</replaceable></literal>.
1467
1468 (<emphasis>TODO</emphasis>: Add Examples.)</para>
1469 </listitem>
1470
1471 <listitem>
1472 <para>Conditional interfaces: a library interface should
1473 vary between versions of the library only, not between
1474 platforms or Haskell implementations. Such differences may
1475 be visible at the module level only, so for example module
1476 <literal>System.Win32</literal> would be available on Win32
1477 systems only, and <literal>GHC.Exts</literal> would only be
1478 available when compiling with GHC.</para>
1479 </listitem>
1480 </itemizedlist>
1481 </sect2>
1482
1483 </sect1>
1484
1485 <sect1>
1486 <title>Changes to standard Haskell 98 libraries</title>
1487
1488 <para>Some changes have been made to the standard Haskell 98
1489 libraries in the new library scheme, both in the names of the
1490 modules themselves and in their exported interfaces. Below is a
1491 summary of those changes - at this time, the new libraries are
1492 marked as provisional and are maintained by
1493 <email>libraries@haskell.org</email>, so changes in the interfaces
1494 are all up for discussion.</para>
1495
1496 <screen>
1497 modules with interface changes
1498 ------------------------------
1499
1500 Array -> Data.Array
1501 added instance Typeable (Array ix a)
1502
1503 Char -> Data.Char
1504 no interface changes (should have instance Typeable?)
1505
1506 Complex -> Data.Complex
1507 added instance Typeable (Complex a)
1508
1509 IO -> System.IO
1510 added
1511 hPutBuf :: Handle -> Ptr a -> Int -> IO ()
1512 hGetBuf :: Handle -> Ptr a -> Int -> IO Int
1513 fixIO :: (a -> IO a) -> IO a
1514 hSetEcho :: Handle -> Bool -> IO ()
1515 hGetEcho :: Handle -> IO Bool
1516 hIsTerminalDevice :: Handle -> IO Bool
1517
1518 List -> Data.List
1519 exports [](..)
1520
1521 System -> System.Exit, System.Environment, System.Cmd
1522 split into three modules
1523
1524 just renamed, no interface changes:
1525 -----------------------------------
1526
1527 CPUTTime -> System.CPUTime
1528 Directory -> System.IO.Directory
1529 Ix -> Data.Ix
1530 Locale -> System.Locale
1531 Maybe -> Data.Maybe
1532 Monad -> Data.Monad
1533 Numeric -> Numeric
1534 Random -> System.Random
1535 Ratio -> Data.Ratio
1536 Time -> System.Time
1537 </screen>
1538 </sect1>
1539 <index/>
1540 </article>