Data.Generics

The Data class comprehends a fundamental primitive gfoldl for folding over constructor applications, say terms. This primitive can be instantiated in several ways to map over the immediate subterms of a term; see the gmap combinators later in this class. Indeed, a generic programmer does not necessarily need to use the ingenious gfoldl primitive but rather the intuitive gmap combinators. The gfoldl primitive is completed by means to query top-level constructors, to turn constructor representations into proper terms, and to list all possible datatype constructors. This completion allows us to serve generic programming scenarios like read, show, equality, term generation.

The combinators gmapT, gmapQ, gmapM, etc are all provided with default definitions in terms of gfoldl, leaving open the opportunity to provide datatype-specific definitions. (The inclusion of the gmap combinators as members of class Data allows the programmer or the compiler to derive specialised, and maybe more efficient code per datatype. Note: gfoldl is more higher-order than the gmap combinators. This is subject to ongoing benchmarking experiments. It might turn out that the gmap combinators will be moved out of the class Data.)

Conceptually, the definition of the gmap combinators in terms of the primitive gfoldl requires the identification of the gfoldl function arguments. Technically, we also need to identify the type constructor c for the construction of the result type from the folded term type.

In the definition of gmapQx combinators, we use phantom type constructors for the c in the type of gfoldl because the result type of a query does not involve the (polymorphic) type of the term argument. In the definition of gmapQl we simply use the plain constant type constructor because gfoldl is left-associative anyway and so it is readily suited to fold a left-associative binary operation over the immediate subterms. In the definition of gmapQr, extra effort is needed. We use a higher-order accumulation trick to mediate between left-associative constructor application vs. right-associative binary operation (e.g., (:)). When the query is meant to compute a value of type r, then the result type within generic folding is r -> r. So the result of folding is a function to which we finally pass the right unit.

With the -XDeriveDataTypeable option, GHC can generate instances of the Data class automatically. For example, given the declaration

data T a b = C1 a b | C2 deriving (Typeable, Data)

GHC will generate an instance that is equivalent to

instance (Data a, Data b) => Data (T a b) where
    gfoldl k z (C1 a b) = z C1 `k` a `k` b
    gfoldl k z C2       = z C2

    gunfold k z c = case constrIndex c of
                        1 -> k (k (z C1))
                        2 -> z C2

    toConstr (C1 _ _) = con_C1
    toConstr C2       = con_C2

    dataTypeOf _ = ty_T

con_C1 = mkConstr ty_T "C1" [] Prefix
con_C2 = mkConstr ty_T "C2" [] Prefix
ty_T   = mkDataType "Module.T" [con_C1, con_C2]

This is suitable for datatypes that are exported transparently.

Representation of datatypes. A package of constructor representations with names of type and module.

Constructs a non-representation for a non-representable type

Public representation of datatypes

The class Typeable allows a concrete representation of a type to be calculated.

The type-safe cast operation

A flexible variation parameterised in a type constructor

Cast over k1 -> k2 -> k3

Gets the field labels of a constructor. The list of labels is returned in the same order as they were given in the original constructor declaration.

Gets the fixity of a constructor

Gets the index of a constructor (algebraic datatypes only)

Gets the public presentation of constructors

Gets the datatype of a constructor

Gets the constructors of an algebraic datatype

Gets the type constructor including the module

Gets the public presentation of a datatype

Build a term skeleton

Build a term and use a generic function for subterms

Monadic variation on fromConstrB

Gets the constructor for an index (algebraic datatypes only)

Test for an algebraic type

Test for a non-representable type

Gets the maximum constructor index of an algebraic datatype

Makes a constructor for Char.

Constructs the Char type

Constructs a constructor

Constructs a constructor

Constructs an algebraic datatype

Constructs the Float type

Constructs the Int type

Lookup a constructor via a string

Look up a constructor by its representation

Gets the string for a constructor

Gets the module of a type constructor: take *.*.*... before name

Gets the unqualified type constructor: drop *.*.*... before name

Decide an equality of two types

Extract a witness of equality of two types

Applies a type to a function type. Returns: Just u if the first argument represents a function of type t -> u and the second argument represents a function of type t. Otherwise, returns Nothing.

Cast over k1 -> k2

Decide heterogeneous equality of two types.

Extract a witness of heterogeneous equality of two types

Build a function type.

Force a TypeRep to normal form.

Show a type representation

Splits a type constructor application. Note that if the type constructor is polymorphic, this will not return the kinds that were used.

Observe a type representation for the type of a value.

Takes a value of type a and returns a concrete representation of that type.

Observe the argument types of a type representation

Takes a value of type a and returns a concrete representation of that type.

Observe the type constructor of a quantified type representation.

Unique index for datatype constructors, counting from 1 in the order they are given in the program text.

Representation of constructors. Note that equality on constructors with different types may not work -- i.e. the constructors for False and Nothing may compare equal.

Public representation of constructors

Fixity of constructors

Proxy is a type that holds no data, but has a phantom parameter of arbitrary type (or even kind). Its use is to provide type information, even though there is no value available of that type (or it may be too costly to create one).

Historically, Proxy :: Proxy a is a safer alternative to the undefined :: a idiom.

>>> Proxy :: Proxy (Void, Int -> Int)Proxy

Proxy can even hold types of higher kinds,

>>> Proxy :: Proxy EitherProxy

>>> Proxy :: Proxy FunctorProxy

>>> Proxy :: Proxy complicatedStructureProxy

Propositional equality. If a :~: b is inhabited by some terminating value, then the type a is the same as the type b. To use this equality in practice, pattern-match on the a :~: b to get out the Refl constructor; in the body of the pattern-match, the compiler knows that a ~ b.

Kind heterogeneous propositional equality. Like :~:, a :~~: b is inhabited by a terminating value if and only if a is the same type as b.

A quantified type representation.