Hugs and GHC provide a common set of libraries to aid portability. This document specifies the interfaces to these libraries and documents known differences. It is the hope of the GHC team that these libraries in the long run become part of every Haskell system.
To make both writing new libraries and reading programs using them easier, a few conventions the set of interfaces specified in this document try to adhere to are listed in the following sections. Note that because of compatibility issues and the evolving nature of this library collection, there are still a few exceptions, but hopefully they vanish in the future.
These conventions are not carved into stone for eternity, they are just a collection of thoughts people involved in the development of these libraries had at some point in time. They were formed after quite some discussions and are heavily based on an initial suggestion of Marcin Kowalczyk <qrczak@knm.org.pl>. Feel free to discuss them, the Haskell mailing list <haskell@haskell.org> is probably the right place for this.
This is what people like discussing about most: names. Note that the conventions are not mutually exclusive, e.g. should the function creating a set from a list of elements have the name set or listToSet? (Alas, it currently has neither name.)
The following nomenclature is used: Pure, i.e. non-monadic functions are simply called, well, functions. Monadic functions, i.e. functions having a type ... -> m a for some Monad m are called actions.
Empty values of type X have the name emptyX, e.g. emptySet.
Actions creating a new empty value of type X have the name newEmptyX, e.g. newEmptyMVar.
Functions creating an arbitrary value of type X have the name X itself, e.g. array. (TODO: This often collides with xToY convention, how should this be resolved?)
Actions creating new values arbitrary values of type X have the name newX, e.g. newIORef.
Functions getting an attribute of an value or a part of it have the name of the attribute itself, e.g. length, bounds.
Actions accessing some kind of reference or state have the name getX, where X is the type of the contents or the name of the part being accessed, e.g. getChar, getEnv. An alternative naming scheme is readY, where Y is the type of the reference or container, e.g. readIORef.
Functions or actions getting a value via a pointer-like type X should be named deRefX, e.g. deRefStablePtr, deRefWeak.
Functions returning an value with attribute X set to a new value should be named setX. (TODO: Add Examples.)
Actions setting some kind of reference or state have the name putX, where X is the type of the contents or the name of the part being accessed, e.g. putChar. An alternative naming scheme is writeY, where Y is the type of the reference or container, e.g. writeIORef.
Actions in the IO monad setting some global state X are traditionally named setX, too, although putX would be more appropriate, e.g. y, setReadlineName.
Functions returning a container X modified by a function of type a -> a have the name updateX. (TODO: Add Examples.)
Actions modifying a container X by a function of type a -> a have the name modifyX, e.g. modifySTRef.
Predicates, both non-monadic and monadic, testing a property X have the name isX.
Functions converting a value of type X to a value of type Y have the name xToY with all leading uppercase characters of X converted to lower case, e.g. stToIO.
Overloaded conversion functions of type C a => a -> X have the name toX, e.g. toInteger.
Overloaded conversion functions of type C a => X -> a have the name fromX, e.g. fromInteger.
An action that is identical to another one called X, but discards the return value has the name X_, e.g. mapM and mapM_.
Functions and actions which are potentially dangerous to use and leave some kind of proof obligation to the programmer have the name unsafeX, e.g. unsafePerformIO.
There are two conventions for binary and N-ary variants of an associative operation: One convention uses an operator or a short name for the binary operation and a long name for the N-ary variant, e.g. (+) and sum, max and maximum. The other convention suffixes the N-ary variant with Many. (TODO: Add Examples.)
If possible, names are chosen such that either plain application or arg1 `operation` arg2 is correct English, e.g. isPrefixOf is good for use in backquotes.