The Haskell 98 Report
top | back | next | contents | function index

D  Specification of Derived Instances

If T is an algebraic datatype declared by:

data cx => T u1 ... uk	=	K1 t11 ... t1k1 | ...| Kn tn1 ... tnkn
		deriving (C1, ..., Cm)

(where m>=0 and the parentheses may be omitted if m=1) then a derived instance declaration is possible for a class C if these conditions hold:

1. C is one of Eq, Ord, Enum, Bounded, Show, or Read.

2. There is a context cx' such that cx' =>C t_ij holds for each of the constituent types t_ij.

3. If C is Bounded, the type must be either an enumeration (all constructors must by nullary) or have only one constructor.

4. If C is Enum, the type must be an enumeration.

5. There must be no explicit instance declaration elsewhere in the program that makes T u₁ ... u_k an instance of C.

If the deriving form is present, an instance declaration is automatically generated for T u₁ ... u_k over each class C_i. If the derived instance declaration is impossible for any of the C_i then a static error results. If no derived instances are required, the deriving form may be omitted or the form deriving () may be used.

Each derived instance declaration will have the form:

instance (cx, C'₁ u'₁, ..., C'_j u'_j ) => C_i (T u₁ ... u_k) where { d }

where d is derived automatically depending on C_i and the data type declaration for T (as will be described in the remainder of this section), and u'₁ through u'_j form a subset of u₁ through u_k. When inferring the context for the derived instances, type synonyms must be expanded out first. Free names in the declarations d are all defined in the Prelude; the qualifier `Prelude.' is implicit here. The remaining details of the derived instances for each of the derivable Prelude classes are now given.

D.1  Derived instances of Eq and Ord.

Derived comparisons always traverse constructors from left to right. These examples illustrate this property:

(1,undefined) == (2,undefined) =>    False
(undefined,1) == (undefined,2) =>    _|_

D.2  Derived instances of Enum

The nullary constructors are assumed to be numbered left-to-right with the indices 0 through n-1. The succ and pred operators give the successor and predecessor respectively of a value, under this numbering scheme. It is an error to apply succ to the maximum element, or pred to the minimum element.

The toEnum and fromEnum operators map enumerated values to and from the Int type.

enumFrom n returns a list corresponding to the complete enumeration of n's type starting at the value n. Similarly, enumFromThen n n' is the enumeration starting at n, but with second element n', and with subsequent elements generated at a spacing equal to the difference between n and n'. enumFromTo and enumFromThenTo are as defined by the default class methods for Enum (see Figure 5, page ). For example, given the datatype:

data  Color = Red | Orange | Yellow | Green  deriving (Enum)

we would have:

[Orange ..]         ==  [Orange, Yellow, Green]
fromEnum Yellow     ==  2

D.3  Derived instances of Bounded.

D.4  Derived instances of Read and Show.

The function showsPrec d x r accepts a precedence level d (a number from 0 to 10), a value x, and a string r. It returns a string representing x concatenated to r. showsPrec satisfies the law:

showsPrec d x r ++ s  ==  showsPrec d x (r ++ s)

The representation will be enclosed in parentheses if the precedence of the top-level constructor operator in x is less than d. Thus, if d is 0 then the result is never surrounded in parentheses; if d is 10 it is always surrounded in parentheses, unless it is an atomic expression. The extra parameter r is essential if tree-like structures are to be printed in linear time rather than time quadratic in the size of the tree.

The function readsPrec d s accepts a precedence level d (a number from 0 to 10) and a string s, and attempts to parse a value from the front of the string, returning a list of (parsed value, remaining string) pairs. If there is no successful parse, the returned list is empty. It should be the case that

  fst (head (readsPrec d (showsPrec d x r))) == x

That is, readsPrec should be able to parse the string produced by showsPrec, and should deliver the value that showsPrec started with.

showList and readList allow lists of objects to be represented using non-standard denotations. This is especially useful for strings (lists of Char).

readsPrec will parse any valid representation of the standard types apart from lists, for which only the bracketed form [...] is accepted. See Appendix A for full details.

A precise definition of the derived Read and Show instances for general types is beyond the scope of this report. However, the derived Read and Show instances have the following properties:

• The result of show is a syntactically correct Haskell expression containing only constants given the fixity declarations in force at the point where the type is declared.
• The result of show is readable by read if all component types are readable. (This is true for all instances defined in the Prelude but may not be true for user-defined instances.)
• The instance generated by Read allows arbitrary whitespace between tokens on the input string. Extra parentheses are also allowed.
• The result of show contains only the constructor names defined in the data type, parentheses, and spaces. When labelled constructor fields are used, braces, commas, field names, and equal signs are also used. Spaces and parentheses are only added where needed. No line breaks are added.
• If a constructor is defined using labelled field syntax then the derived show for that constructor will use this same syntax; the fields will be in the order declared in the data declaration. The derived Read instance will use this same syntax: all fields must be present and the declared order must be maintained.
• If a constructor is defined in the infix style, the derived Show instance will also use infix style. The derived Read instance will require that the constructor be infix.

The derived Read and Show instances may be unsuitable for some uses. Some problems include:

• Circular structures cannot be printed or read by these instances.
• The printer loses shared substructure; the printed representation of an object may be much larger than necessary.
• The parsing techniques used by the reader are very inefficient; reading a large structure may be quite slow.
• There is no user control over the printing of types defined in the Prelude. For example, there is no way to change the formatting of floating point numbers.

D.5  An Example

As a complete example, consider a tree datatype:

data Tree a = Leaf a | Tree a :^: Tree a
     deriving (Eq, Ord, Read, Show)

Automatic derivation of instance declarations for Bounded and Enum are not possible, as Tree is not an enumeration or single-constructor datatype. The complete instance declarations for Tree are shown in Figure 8, Note the implicit use of default class method definitions---for example, only <= is defined for Ord, with the other class methods (<, >, >=, max, and min) being defined by the defaults given in the class declaration shown in Figure 5 (page ).

infix 4 :^: data Tree a =  Leaf a  |  Tree a :^: Tree a instance (Eq a) => Eq (Tree a) where Leaf m == Leaf n  =  m==n u:^:v  == x:^:y   =  u==x && v==y              _ == _       =  False instance (Ord a) => Ord (Tree a) where Leaf m <= Leaf n  =  m<=n Leaf m <= x:^:y   =  True u:^:v  <= Leaf n  =  False u:^:v  <= x:^:y   =  u<x || u==x && v<=y instance (Show a) => Show (Tree a) where         showsPrec d (Leaf m) = showParen (d >= 10) showStr        where              showStr = showString "Leaf " . showsPrec 10 m         showsPrec d (u :^: v) = showParen (d > 4) showStr        where              showStr = showsPrec 5 u .                         showString " :^: " .                        showsPrec 5 v instance (Read a) => Read (Tree a) where readsPrec d r =  readParen (d > 4)  (\r -> [(u:^:v,w) |  (u,s) <- readsPrec 5 r,  (":^:",t) <- lex s,  (v,w) <- readsPrec 5 t]) r       ++ readParen (d > 9)  (\r -> [(Leaf m,t) |  ("Leaf",s) <- lex r,  (m,t) <- readsPrec 10 s]) r Figure 8 Example of Derived Instances