|
Generics.EMGM | Portability | non-portable | Stability | experimental | Maintainer | generics@haskell.org |
|
|
|
|
|
Description |
EMGM is "Extensible and Modular Generics for the Masses," a library for
datatype-generic programming in Haskell.
This module exports the most commonly used types, classes, and functions. The
documentation is organized by topic for convenient access.
For more in-depth documentation, refer to one of the modules in these
hierarchies:
|
|
Synopsis |
|
data Unit = Unit | | | | data a :*: b = a :*: b | | data EP d r = EP {} | | data ConDescr = ConDescr {} | | | | | | prec :: Fixity -> Prec | | minPrec | | maxPrec :: Prec | | appPrec :: Prec | | recPrec :: Prec | | class Rep g a where | | | class FRep g f where | | | class FRep2 g f where | frep2 :: g a b -> g (f a) (f b) |
| | class FRep3 g f where | frep3 :: g a b c -> g (f a) (f b) (f c) |
| | class BiFRep2 g f where | bifrep2 :: g a1 b1 -> g a2 b2 -> g (f a1 a2) (f b1 b2) |
| | class Generic g where | | | class Generic2 g where | | | class Generic3 g where | | | derive :: Name -> Q [Dec] | | deriveWith :: Modifiers -> Name -> Q [Dec] | | | | type Modifiers = [(String, Modifier)] | | newtype Collect b a = Collect {} | | collect :: Rep (Collect b) a => a -> [b] | | newtype Compare a = Compare {} | | compare :: Rep Compare a => a -> a -> Ordering | | eq :: Rep Compare a => a -> a -> Bool | | neq :: Rep Compare a => a -> a -> Bool | | lt :: Rep Compare a => a -> a -> Bool | | lteq :: Rep Compare a => a -> a -> Bool | | gt :: Rep Compare a => a -> a -> Bool | | gteq :: Rep Compare a => a -> a -> Bool | | min :: Rep Compare a => a -> a -> a | | max :: Rep Compare a => a -> a -> a | | newtype Crush b a = Crush {} | | | | crush :: FRep (Crush b) f => Assoc -> (a -> b -> b) -> b -> f a -> b | | crushl :: FRep (Crush b) f => (a -> b -> b) -> b -> f a -> b | | crushr :: FRep (Crush b) f => (a -> b -> b) -> b -> f a -> b | | flatten :: FRep (Crush [a]) f => Assoc -> f a -> [a] | | flattenl :: FRep (Crush [a]) f => f a -> [a] | | flattenr :: FRep (Crush [a]) f => f a -> [a] | | first :: FRep (Crush [a]) f => Assoc -> f a -> Maybe a | | firstl :: FRep (Crush [a]) f => f a -> Maybe a | | firstr :: FRep (Crush [a]) f => f a -> Maybe a | | and :: FRep (Crush Bool) f => f Bool -> Bool | | or :: FRep (Crush Bool) f => f Bool -> Bool | | any :: FRep (Crush Bool) f => (a -> Bool) -> f a -> Bool | | all :: FRep (Crush Bool) f => (a -> Bool) -> f a -> Bool | | sum :: (Num a, FRep (Crush a) f) => f a -> a | | product :: (Num a, FRep (Crush a) f) => f a -> a | | minimum :: (Rep Compare a, FRep (Crush (Maybe a)) f) => f a -> Maybe a | | maximum :: (Rep Compare a, FRep (Crush (Maybe a)) f) => f a -> Maybe a | | elem :: (Rep Compare a, FRep (Crush Bool) f) => a -> f a -> Bool | | notElem :: (Rep Compare a, FRep (Crush Bool) f) => a -> f a -> Bool | | newtype Enum a = Enum {} | | enum :: Rep Enum a => [a] | | enumN :: (Integral n, Rep Enum a) => n -> [a] | | empty :: Rep Enum a => a | | newtype Map a b = Map {} | | map :: FRep2 Map f => (a -> b) -> f a -> f b | | replace :: FRep2 Map f => f a -> b -> f b | | bimap :: BiFRep2 Map f => (a -> c) -> (b -> d) -> f a b -> f c d | | newtype Read a = Read {} | | readPrec :: Rep Read a => ReadPrec a | | readP :: Rep Read a => Int -> ReadP a | | readsPrec :: Rep Read a => Int -> ReadS a | | reads :: Rep Read a => ReadS a | | read :: Rep Read a => String -> Maybe a | | newtype Show a = Show {} | | showsPrec :: Rep Show a => Int -> a -> ShowS | | shows :: Rep Show a => a -> ShowS | | show :: Rep Show a => a -> String | | newtype UnzipWith a b c = UnzipWith {} | | unzip :: FRep3 UnzipWith f => f (a, b) -> (f a, f b) | | unzipWith :: FRep3 UnzipWith f => (a -> (b, c)) -> f a -> (f b, f c) | | newtype ZipWith a b c = ZipWith {} | | zip :: FRep3 ZipWith f => f a -> f b -> Maybe (f (a, b)) | | zipWith :: FRep3 ZipWith f => (a -> b -> c) -> f a -> f b -> Maybe (f c) |
|
|
|
Common Infrastructure
|
|
This is the collection of types, classes, and functions used to define
generic functions and to build representations for datatypes.
|
|
Datatype Representation
|
|
These are the types and functions required to represent a datatype for
use by generic functions.
|
|
Structure Representation Types
|
|
The unit, sum, and product types form the sum-of-products view for a
Haskell datatype.
|
|
|
The "unit" encodes a constructor with no arguments. An analogous standard
Haskell type is ().
| Constructors | Unit | The only value of type Unit (ignoring _|_).
|
| Instances | |
|
|
|
The "sum" encodes 2 constructor alternatives. An analogous standard
Haskell type is Either a b.
| Constructors | L a | Left alternative
| R b | Right alternative
|
| Instances | |
|
|
|
The "product" encodes 2 constructor arguments. An analogous standard
Haskell type is (a, b).
| Constructors | a :*: b | A pair of arguments
|
| Instances | |
|
|
Embedding-Projection Pair
|
|
A pair of a function and its inverse form the isomorphism between a
datatype and its structure representation.
|
|
|
The embedding-projection pair contains two functions for converting between
the datatype and its representation. An EP value preserves an isomorphism
(ignoring _|_s) between a datatype and its structure representation.
| Constructors | EP | | from :: d -> r | Embed a datatype into its representation.
| to :: r -> d | Project datatype from its representation.
|
|
|
|
|
Constructor Description
|
|
A description of the syntax of each constructor provides useful auxiliary
information for some generic functions.
|
|
|
A constructor description containing useful meta-information about the
syntax used in the data declaration. This is particularly useful in Read
and Show but may also be helpful in other generic functions.
NOTE: It is important that the ConDescr value accurately describe the
syntax in a constructor declaration. An incorrect description may lead to
faulty Read or Show operation.
| Constructors | ConDescr | | conName :: String | Name of the constructor. If it is infix,
don't provide parentheses.
| conArity :: Int | Arity or number of arguments.
| conLabels :: [String] | A list of labels used in record syntax.
They must be declared in the same order as
the data declaration. The list should be
empty if the constructor is not a record.
| conFixity :: Fixity | Infix or not, associativity, precedence.
|
|
| Instances | |
|
|
|
The constructor type used in Read and Show to determine how to parse or
print the constructor.
| Constructors | ConStd | Standard (function-type, nonfix)
| ConRec [String] | Record-style (nonfix or infix)
| ConIfx String | Infix (no record syntax)
|
| Instances | |
|
|
|
An identifier's fixity, associativity, and precedence. If not infix
(Nonfix), the associativity and precedence of the identifier is the same as
function application. If infix, the associativity is indicated by the
constructor and the precedence is an argument to it.
| Constructors | Nonfix | Not infix. Associativity and precedence are the same as function application.
| Infix Prec | Non-associative infix with precedence.
| Infixl Prec | Left-associative infix with precedence.
| Infixr Prec | Right-associative Infix with precedence.
|
| Instances | |
|
|
|
Get the precedence of a fixity value.
|
|
minPrec |
|
|
Maximum precedence: 11
|
|
|
Precedence for function application: 10
|
|
|
Precedence for record construction: 11
|
|
Representation Dispatchers
|
|
Type classes simplify the application of generic functions by providing
(a.k.a. "dispatching") the appropriate structure representation. These
classes are divided into the kinds they support (monomorphic, functor, and
bifunctor).
Note that the numerical suffix represents the number of generic type
variables used in the generic function. No suffix represents 1 generic type
variable.
|
|
Monomorphic
|
|
All types of kind * should have an instance here. This includes types
applied to type variables: [a], Maybe a, Either a b, etc.
|
|
|
The Generic representation dispatcher for monomorphic types (kind *).
Every structure type and supported datatype should have an instance of
Rep. (No default implementation.)
| | Methods | | | Instances | Generic g => Rep g Unit | Generic g => Rep g Char | Generic g => Rep g Double | Generic g => Rep g Float | Generic g => Rep g Integer | Generic g => Rep g Int | Generic g => Rep g Bool | Generic g => Rep g () | Rep Read String | Rep Read String | Rep Read () | Rep Read () | Rep Show String | Rep Show String | Rep Show () | Rep Show () | (Generic g, Rep g a) => Rep g ([] a) | (Generic g, Rep g a) => Rep g (Maybe a) | Rep Read a => Rep Read ([] a) | Rep Read a => Rep Read ([] a) | Rep Show a => Rep Show ([] a) | Rep Show a => Rep Show ([] a) | (Generic g, Rep g a, Rep g b) => Rep g (a :*: b) | (Generic g, Rep g a, Rep g b) => Rep g (a :+: b) | (Generic g, Rep g a, Rep g b) => Rep g (Either a b) | (Generic g, Rep g a, Rep g b) => Rep g ((,) a b) | (Rep Read a, Rep Read b) => Rep Read ((,) a b) | (Rep Read a, Rep Read b) => Rep Read ((,) a b) | (Rep Show a, Rep Show b) => Rep Show ((,) a b) | (Rep Show a, Rep Show b) => Rep Show ((,) a b) | (Generic g, Rep g a, Rep g b, Rep g c) => Rep g ((,,) a b c) | (Rep Read a, Rep Read b, Rep Read c) => Rep Read ((,,) a b c) | (Rep Read a, Rep Read b, Rep Read c) => Rep Read ((,,) a b c) | (Rep Show a, Rep Show b, Rep Show c) => Rep Show ((,,) a b c) | (Rep Show a, Rep Show b, Rep Show c) => Rep Show ((,,) a b c) | (Generic g, Rep g a, Rep g b, Rep g c, Rep g d) => Rep g ((,,,) a b c d) | (Rep Read a, Rep Read b, Rep Read c, Rep Read d) => Rep Read ((,,,) a b c d) | (Rep Read a, Rep Read b, Rep Read c, Rep Read d) => Rep Read ((,,,) a b c d) | (Rep Show a, Rep Show b, Rep Show c, Rep Show d) => Rep Show ((,,,) a b c d) | (Rep Show a, Rep Show b, Rep Show c, Rep Show d) => Rep Show ((,,,) a b c d) | (Generic g, Rep g a, Rep g b, Rep g c, Rep g d, Rep g e) => Rep g ((,,,,) a b c d e) | (Rep Read a, Rep Read b, Rep Read c, Rep Read d, Rep Read e) => Rep Read ((,,,,) a b c d e) | (Rep Read a, Rep Read b, Rep Read c, Rep Read d, Rep Read e) => Rep Read ((,,,,) a b c d e) | (Rep Show a, Rep Show b, Rep Show c, Rep Show d, Rep Show e) => Rep Show ((,,,,) a b c d e) | (Rep Show a, Rep Show b, Rep Show c, Rep Show d, Rep Show e) => Rep Show ((,,,,) a b c d e) | (Generic g, Rep g a, Rep g b, Rep g c, Rep g d, Rep g e, Rep g f) => Rep g ((,,,,,) a b c d e f) | (Rep Read a, Rep Read b, Rep Read c, Rep Read d, Rep Read e, Rep Read f) => Rep Read ((,,,,,) a b c d e f) | (Rep Read a, Rep Read b, Rep Read c, Rep Read d, Rep Read e, Rep Read f) => Rep Read ((,,,,,) a b c d e f) | (Rep Show a, Rep Show b, Rep Show c, Rep Show d, Rep Show e, Rep Show f) => Rep Show ((,,,,,) a b c d e f) | (Rep Show a, Rep Show b, Rep Show c, Rep Show d, Rep Show e, Rep Show f) => Rep Show ((,,,,,) a b c d e f) | (Generic g, Rep g a, Rep g b, Rep g c, Rep g d, Rep g e, Rep g f, Rep g h) => Rep g ((,,,,,,) a b c d e f h) | (Rep Read a, Rep Read b, Rep Read c, Rep Read d, Rep Read e, Rep Read f, Rep Read h) => Rep Read ((,,,,,,) a b c d e f h) | (Rep Read a, Rep Read b, Rep Read c, Rep Read d, Rep Read e, Rep Read f, Rep Read h) => Rep Read ((,,,,,,) a b c d e f h) | (Rep Show a, Rep Show b, Rep Show c, Rep Show d, Rep Show e, Rep Show f, Rep Show h) => Rep Show ((,,,,,,) a b c d e f h) | (Rep Show a, Rep Show b, Rep Show c, Rep Show d, Rep Show e, Rep Show f, Rep Show h) => Rep Show ((,,,,,,) a b c d e f h) | Rep (Collect Bool) Bool | Rep (Collect Bool) Bool | Rep (Collect Char) Char | Rep (Collect Char) Char | Rep (Collect Double) Double | Rep (Collect Double) Double | Rep (Collect Float) Float | Rep (Collect Float) Float | Rep (Collect Int) Int | Rep (Collect Int) Int | Rep (Collect Integer) Integer | Rep (Collect Integer) Integer | Rep (Collect ()) () | Rep (Collect ()) () | Rep (Collect ([] a)) ([] a) | Rep (Collect ([] a)) ([] a) | Rep (Collect (Maybe a)) (Maybe a) | Rep (Collect (Maybe a)) (Maybe a) | Rep (Collect (Either a b)) (Either a b) | Rep (Collect (Either a b)) (Either a b) | Rep (Collect ((,) a b)) ((,) a b) | Rep (Collect ((,) a b)) ((,) a b) | Rep (Collect ((,,) a b c)) ((,,) a b c) | Rep (Collect ((,,) a b c)) ((,,) a b c) | Rep (Collect ((,,,) a b c d)) ((,,,) a b c d) | Rep (Collect ((,,,) a b c d)) ((,,,) a b c d) | Rep (Collect ((,,,,) a b c d e)) ((,,,,) a b c d e) | Rep (Collect ((,,,,) a b c d e)) ((,,,,) a b c d e) | Rep (Collect ((,,,,,) a b c d e f)) ((,,,,,) a b c d e f) | Rep (Collect ((,,,,,) a b c d e f)) ((,,,,,) a b c d e f) | Rep (Collect ((,,,,,,) a b c d e f h)) ((,,,,,,) a b c d e f h) | Rep (Collect ((,,,,,,) a b c d e f h)) ((,,,,,,) a b c d e f h) |
|
|
|
Functor
|
|
Types of kind * -> * should have an instance here. This includes [],
Maybe, etc.
|
|
|
The Generic representation dispatcher for functor types (kind * -> *),
sometimes called container types. (No default implementation.)
| | Methods | | | Instances | |
|
|
|
The Generic2 representation dispatcher for functor types (kind * -> *),
sometimes called container types. (No default implementation.)
| | Methods | frep2 :: g a b -> g (f a) (f b) | Source |
|
| | Instances | |
|
|
|
The Generic3 representation dispatcher for functor types (kind * -> *),
sometimes called container types. (No default implementation.)
| | Methods | frep3 :: g a b c -> g (f a) (f b) (f c) | Source |
|
| | Instances | |
|
|
Bifunctor
|
|
Types of kind * -> * -> * should have an instance here. This includes
(,), Either, etc.
|
|
|
The Generic2 representation dispatcher for bifunctor types (kind
* -> * -> *). (No default implementation.)
| | Methods | bifrep2 :: g a1 b1 -> g a2 b2 -> g (f a1 a2) (f b1 b2) | Source |
|
| | Instances | |
|
|
Generic Function Definition
|
|
Generic functions are instances of these classes. The value-level
structure representation of datatypes is implemented using the members of
these classes. Thus, a generic function is simply a case statement on the
value-level structure.
Note that the numerical suffix represents the number of generic type
variables used in the generic function. No suffix represents 1 generic type
variable.
|
|
|
This class forms the foundation for defining generic functions with a
single generic argument. Each method represents a type case. The class
includes cases for primitive types, cases for the structural representation,
and the rtype case for adding support for new datatypes.
| | Methods | | Many functions perform the same operation on the non-structural cases (as
well as Unit). The cases for constant datatypes (Int, Integer,
Float, Double, Char, and Unit) have a default implementation of
rconstant, thus a generic function may only override rconstant if
desired. Note that there is no default implementation for rconstant
itself.
The class context represents the intersection set of supported type
classes.
| | | Case for the primitive type Int. (Default implementation:
rconstant.)
| | | Case for the primitive type Integer. (Default implementation:
rconstant.)
| | | Case for the primitive type Float. (Default implementation:
rconstant.)
| | | Case for the primitive type Double. (Default implementation:
rconstant.)
| | | Case for the primitive type Char. (Default implementation:
rconstant.)
| | | Case for the structural representation type Unit. It is used to
represent a constructor with no arguments. (Default implementation:
rconstant.)
| | | Case for the structural representation type :+: (sum). It
is used to represent alternative choices between constructors. (No
default implementation.)
| | | Case for the structural representation type :*: (product).
It is used to represent multiple arguments to a constructor. (No
default implementation.)
| | | Case for constructors. While not necessary for every generic function,
this method is required for Read and Show. It is used to hold the
meta-information about a constructor (ConDescr), e.g. name, arity,
fixity, etc. (Since most generic functions do not use rcon and simply pass
the value through, the default implementation is const id.)
| | | Case for datatypes. This method is used to define the structural
representation of an arbitrary Haskell datatype. The first argument is the
embedding-projection pair, necessary for establishing the isomorphism
between datatype and representation. The second argument is the
run-time representation using the methods of Generic. (No default
implementation.)
|
| | Instances | |
|
|
|
This class forms the foundation for defining generic functions with two
generic arguments. Each method represents a type case. The class includes
cases for primitive types, cases for the structural representation, and the
rtype case for adding support for new datatypes.
| | Methods | | Many functions perform the same operation on the non-structural cases (as
well as Unit). The cases for constant datatypes (Int, Integer,
Float, Double, Char, and Unit) have a default implementation of
rconstant2, thus a generic function may only override rconstant2 if
desired. Note that there is no default implementation for rconstant2
itself.
The class context represents the intersection set of supported type
classes.
| | | Case for the primitive type Int. (Default implementation:
rconstant2.)
| | | Case for the primitive type Integer. (Default implementation:
rconstant2.)
| | | Case for the primitive type Float. (Default implementation:
rconstant2.)
| | | Case for the primitive type Double. (Default implementation:
rconstant2.)
| | | Case for the primitive type Char. (Default implementation:
rconstant2.)
| | | Case for the structural representation type Unit. It is used to
represent a constructor with no arguments. (Default implementation:
rconstant2.)
| | rsum2 :: g a1 a2 -> g b1 b2 -> g (a1 :+: b1) (a2 :+: b2) | Source |
| Case for the structural representation type :+: (sum). It
is used to represent alternative choices between constructors. (No
default implementation.)
| | rprod2 :: g a1 a2 -> g b1 b2 -> g (a1 :*: b1) (a2 :*: b2) | Source |
| Case for the structural representation type :*: (product).
It is used to represent multiple arguments to a constructor. (No
default implementation.)
| | | Case for constructors. It is used to hold the meta-information about a
constructor (ConDescr), e.g. name, arity, fixity, etc. (Since most
generic functions do not use rcon and simply pass the value through, the
default implementation is const id.)
| | rtype2 :: EP a2 a1 -> EP b2 b1 -> g a1 b1 -> g a2 b2 | Source |
| Case for datatypes. This method is used to define the structural
representation of an arbitrary Haskell datatype. The first two arguments
are the embedding-projection pairs, necessary for establishing the
isomorphisms between datatype and representation of the two generic types.
The third argument is the run-time representation using the methods of
Generic2. (No default implementation.)
|
| | Instances | |
|
|
|
This class forms the foundation for defining generic functions with three
generic arguments. Each method represents a type case. The class includes
cases for primitive types, cases for the structural representation, and the
rtype case for adding support for new datatypes.
| | Methods | | Many functions perform the same operation on the non-structural cases (as
well as Unit). The cases for constant datatypes (Int, Integer,
Float, Double, Char, and Unit) have a default implementation of
rconstant3, thus a generic function may only override rconstant3 if
desired. Note that there is no default implementation for rconstant3
itself.
The class context represents the intersection set of supported type
classes.
| | | Case for the primitive type Int. (Default implementation:
rconstant3.)
| | | Case for the primitive type Integer. (Default implementation:
rconstant3.)
| | | Case for the primitive type Float. (Default implementation:
rconstant3.)
| | | Case for the primitive type Double. (Default implementation:
rconstant3.)
| | | Case for the primitive type Char. (Default implementation:
rconstant3.)
| | | Case for the structural representation type Unit. It is used to
represent a constructor with no arguments. (Default implementation:
rconstant3.)
| | rsum3 :: g a1 a2 a3 -> g b1 b2 b3 -> g (a1 :+: b1) (a2 :+: b2) (a3 :+: b3) | Source |
| Case for the structural representation type :+: (sum). It
is used to represent alternative choices between constructors. (No
default implementation.)
| | rprod3 :: g a1 a2 a3 -> g b1 b2 b3 -> g (a1 :*: b1) (a2 :*: b2) (a3 :*: b3) | Source |
| Case for the structural representation type :*: (product).
It is used to represent multiple arguments to a constructor. (No
default implementation.)
| | | Case for constructors. It is used to hold the meta-information about a
constructor (ConDescr), e.g. name, arity, fixity, etc. (Since most
generic functions do not use rcon and simply pass the value through, the
default implementation is const id.)
| | rtype3 :: EP a2 a1 -> EP b2 b1 -> EP c2 c1 -> g a1 b1 c1 -> g a2 b2 c2 | Source |
| Case for datatypes. This method is used to define the structural
representation of an arbitrary Haskell datatype. The first three arguments
are the embedding-projection pairs, necessary for establishing the
isomorphisms between datatype and representation of the four generic types.
The fourth argument is the run-time representation using the methods of
Generic3. (No default implementation.)
|
| | Instances | |
|
|
Deriving Representation
|
|
The simplest way to get a representation for a datatype is using the
following functions in a Template Haskell declaration, e.g. $(derive
''MyType). This generates all of the appropriate instances, e.g. Rep,
FRep, etc., for the type MyType.
For more details or more flexibility in what is derived, see
Generics.EMGM.Common.Derive.
|
|
|
Derive all appropriate instances for using EMGM with a datatype.
Here is an example module that shows how to use derive:
{-# LANGUAGE TemplateHaskell #-}
{-# LANGUAGE MultiParamTypeClasses #-}
{-# LANGUAGE FlexibleContexts #-}
{-# LANGUAGE FlexibleInstances #-}
{-# LANGUAGE OverlappingInstances #-}
{-# LANGUAGE UndecidableInstances #-}
module Example where
import Generics.EMGM
data T a = C a Int
$(derive ''T)
The Template Haskell derive declaration in the above example generates the
following (annotated) code:
-- (1) Constructor description declarations (1 per constructor)
conC :: ConDescr
conC = ConDescr "C" 2 [] Nonfix
-- (2) Embedding-projection pair declarations (1 per type)
epT :: EP (T a) (a :*: Int)
epT = EP fromT toT
where fromT (C v1 v2) = v1 :*: v2
toT (v1 :*: v2) = C v1 v2
-- (3) Rep instance (1 per type)
instance (Generic g, Rep g a, Rep g Int) => Rep g (T a) where
rep = rtype epT (rcon conC (rprod rep rep))
-- (4) Higher arity instances if applicable (either FRep, FRep2, and
-- FRep3 together, or BiFRep2)
instance (Generic g) => FRep g T where
frep ra = rtype epT (rcon conC (rprod ra rint))
-- In this case, similar instances would be generated for FRep2 and FRep3.
-- (5) Function-specific instances (1 per type)
instance Rep (Collect Char) Char where
rep = Collect (:[])
Note that the constructor description conC and embedding-project pair epT
are top-level values. This allows them to be shared between multiple
instances. If these names conflict with your own, you may want to put the
$(derive ...) declaration in its own module and restrict the export list.
|
|
|
Same as derive except that you can pass a list of name modifications to
the deriving mechanism.
Use deriveWith if:
- You want to use the generated constructor descriptions or
embedding-projection pairs and one of your constructors or types is an
infix symbol. In other words, if you have a constructor :*, you cannot
refer to the (invalid) generated name for its description, con:*. It
appears that GHC has no problem with that name internally, so this is only
if you want access to it.
- You want to define your own constructor description. This allows you to
give a precise implementation different from the one generated for you.
For option 1, use ChangeTo as in this example:
data U = Int :* Char
$(deriveWith [(":*", ChangeTo "Star")] ''U)
x = ... conStar ...
For option 2, use DefinedAs as in this example:
data V = (:=) { i :: Int, j :: Char }
$(deriveWith [(":=", DefinedAs "Equals")] ''V)
conEquals = ConDescr ":=" 2 [] (Infix 4)
Using the example for option 2 with Generics.EMGM.Functions.Show will print
values of V as infix instead of the default record syntax.
Note that only the first pair with its first field matching the type or
constructor name in the Modifiers list will be used. Any other matches will
be ignored.
|
|
|
Modify the action taken for a given name.
| Constructors | ChangeTo String | Change the syntactic name (of a type or
constructor) to the argument in the generated EP
or ConDescr value. This results in a value named
epX or conX if the argument is "X".
| DefinedAs String | Use this for the name of a user-defined constructor
description instead of a generated one. The
generated code assumes the existance of conX ::
ConDescr (in scope) if the argument is "X".
|
| Instances | |
|
|
|
List of pairs mapping a (type or constructor) name to a modifier action.
|
|
Generic Functions
|
|
The following collection of functions use the common EMGM infrastructure
to work on all datatypes that have instances for a certain representation
dispatcher. These functions are categorized by the core generic
functionality. For example, flattenr is a type of "crush" function,
because it is defined by the Generic instance of the newtype Crush.
More information for each of these is available in its respective module.
|
|
Collect Functions
|
|
Functions that collect values of one type from values of a possibly
different type.
For more details, see Generics.EMGM.Functions.Collect.
|
|
|
The type of a generic function that takes a value of one type and returns a
list of values of another type.
For datatypes to work with Collect, a special instance must be given. This
instance is trivial to write. Given a type D, the Rep instance looks like
this:
{-# LANGUAGE OverlappingInstances #-}
data D = ...
instance Rep (Collect D) D where
rep = Collect (:[])
(Note the requirement of overlapping instances.) This instance triggers when
the result type (the first D) matches some value type (the second D)
contained within the argument to collect. See the source of this module for
more examples.
| Constructors | | Instances | Generic (Collect b) | Rep (Collect Bool) Bool | Rep (Collect Char) Char | Rep (Collect Double) Double | Rep (Collect Float) Float | Rep (Collect Int) Int | Rep (Collect Integer) Integer | Rep (Collect ()) () | Rep (Collect ([] a)) ([] a) | Rep (Collect (Maybe a)) (Maybe a) | Rep (Collect (Either a b)) (Either a b) | Rep (Collect ((,) a b)) ((,) a b) | Rep (Collect ((,,) a b c)) ((,,) a b c) | Rep (Collect ((,,,) a b c d)) ((,,,) a b c d) | Rep (Collect ((,,,,) a b c d e)) ((,,,,) a b c d e) | Rep (Collect ((,,,,,) a b c d e f)) ((,,,,,) a b c d e f) | Rep (Collect ((,,,,,,) a b c d e f h)) ((,,,,,,) a b c d e f h) |
|
|
|
|
Collect values of type b from some value of type a. An empty list means
no values were collected. If you expected otherwise, be sure that you have an
instance such as Rep (Collect B) B for the type B that you are
collecting.
collect works by searching a datatype for values that are the same type as
the return type specified. Here are some examples using the same value but
different return types:
ghci> let x = [Left 1, Right a, Left 2] :: [Either Int Char]
ghci> collect x :: [Int]
[1,2]
ghci> collect x :: [Char]
"a"
ghci> collect x == x
True
Note that the numerical constants have been declared Int using the type
annotation. Since these natively have the type Num a => a, you may need to
give explicit types. By design, there is no connection that can be inferred
between the return type and the argument type.
collect only works if there is an instance for the return type as described
in the newtype Collect.
|
|
Compare Functions
|
|
Functions that compare two values to determine an ordering.
For more details, see Generics.EMGM.Functions.Compare.
|
|
|
The type of a generic function that takes two values of the same type and
returns an Ordering.
| Constructors | | Instances | |
|
|
|
Compare two values and return an Ordering (i.e. LT, GT, or EQ).
This is implemented exactly as if the datatype was deriving Ord.
|
|
|
Equal to. Returns x == y.
|
|
|
Not equal to. Returns x /= y.
|
|
|
Less than. Returns x < y.
|
|
|
Less than or equal to. Returns x <= y.
|
|
|
Greater than. Returns x > y.
|
|
|
Greater than or equal to. Returns x >= y.
|
|
|
The minimum of two values.
|
|
|
The maximum of two values.
|
|
Crush Functions
|
|
Functions that crush a polymorphic functor container into an iteration
over its elements.
For more details, see Generics.EMGM.Functions.Crush.
|
|
|
The type of a generic function that takes an associativity and two
arguments of different types and returns a value of the type of the second.
| Constructors | Crush | | selCrush :: Assoc -> a -> b -> b | |
|
| Instances | |
|
|
|
Associativity of the binary operator used for crush
| Constructors | AssocLeft | Left-associative
| AssocRight | Right-associative
|
|
|
|
|
:: FRep (Crush b) f | | => Assoc | Associativity of the binary operator (left or right).
| -> a -> b -> b | Binary operator on a-elements with an accumulator.
| -> b | The initial b-value for the binary operator.
| -> f a | Container of a-values.
| -> b | The result after applying the above operator on all
a-values.
| Apply a function (a -> b -> b) to each element (a) of a container (f
a) and an accumulator value (b) to produce an accumulated result (b).
This is the most general form in which you must specify the associativity.
You may prefer to use crushr or crushl.
|
|
|
|
A left-associative variant of crush.
|
|
|
A right-associative variant of crush.
|
|
|
Flatten the elements of a container into a list.
This is the most general form in which you must specify the associativity.
You may prefer to use flattenr or flattenl.
|
|
|
A left-associative variant of flatten.
Note that, for a list ls :: [a], flattenl ls == reverse ls.
|
|
|
A right-associative variant of flatten.
Note that, for a list ls :: [a], flattenr ls == ls.
|
|
|
Extract the first element of a container. If the container is empty, return
Nothing.
This is the most general form in which you must specify the associativity.
You may prefer to use firstr or firstl.
|
|
|
A left-associative variant of first.
Note that, for a list ls :: [a], fromJust (firstl ls) == last ls.
|
|
|
A right-associative variant of first.
Note that, for a list ls :: [a], fromJust (firstr ls) == head ls.
|
|
|
Compute the conjunction of all elements in a container. This is a
generalization of the Prelude function of the same name.
|
|
|
Compute the disjunction of all elements in a container. This is a
generalization of the Prelude function of the same name.
|
|
|
Determine if any element in a container satisfies the predicate p. This
is a generalization of the Prelude function of the same name.
|
|
|
Determine if all elements in a container satisfy the predicate p. This
is a generalization the Prelude function of the same name.
|
|
|
Compute the sum of all elements in a container. This is a generalization of
the Prelude function of the same name.
|
|
|
Compute the product of all elements in a container. This is a
generalization of the Prelude function of the same name.
|
|
|
Determine the minimum element of a container. If the container is empty,
return Nothing. This is a generalization of the Prelude function of the
same name.
|
|
|
Determine the maximum element of a container. If the container is empty,
return Nothing. This is a generalization of the Prelude function of the
same name.
|
|
|
Determine if an element is a member of a container. This is a
generalization of the Prelude function of the same name.
|
|
|
Determine if an element is not a member of a container. This is a
generalization of the Prelude function of the same name.
|
|
Enum Functions
|
|
Functions that enumerate the values of a datatype.
For more details, see Generics.EMGM.Functions.Enum.
|
|
|
The type of a generic function that takes no arguments and returns a list
of some type.
| Constructors | | Instances | |
|
|
|
Enumerate the values of a datatype. If the number of values is infinite,
the result will be an infinite list. The remaining functions are derived from
enum.
|
|
|
Enumerate the first n values of a datatype. This is a shortcut for
genericTake n (enum).
|
|
|
Returns the first element of the enumeration from enum. This is
often called the neutral or empty value.
|
|
Map Functions
|
|
Functions that apply non-generic functions to every element in a
polymorphic (functor or bifunctor) container.
For more details, see Generics.EMGM.Functions.Map.
|
|
|
The type of a generic function that takes a value of one type and returns a
value of a different type.
| Constructors | | Instances | |
|
|
|
Apply a function to all elements of a container datatype (kind * -> *).
|
|
|
Replace all a-values in as with b.
|
|
|
Given a datatype F a b, bimap f g applies the function f :: a -> c to
every a-element and the function g :: b -> d to every b-element. The
result is a value with transformed elements: F c d.
|
|
Read Functions
|
|
Functions similar to deriving Read that parse a string and return a
value of a datatype.
For more details, see Generics.EMGM.Functions.Read.
|
|
|
The type of a generic function that takes a constructor-type argument and
returns a parser combinator for some type.
| Constructors | | Instances | Generic Read | Rep Read String | Rep Read () | Rep Read a => Rep Read ([] a) | (Rep Read a, Rep Read b) => Rep Read ((,) a b) | (Rep Read a, Rep Read b, Rep Read c) => Rep Read ((,,) a b c) | (Rep Read a, Rep Read b, Rep Read c, Rep Read d) => Rep Read ((,,,) a b c d) | (Rep Read a, Rep Read b, Rep Read c, Rep Read d, Rep Read e) => Rep Read ((,,,,) a b c d e) | (Rep Read a, Rep Read b, Rep Read c, Rep Read d, Rep Read e, Rep Read f) => Rep Read ((,,,,,) a b c d e f) | (Rep Read a, Rep Read b, Rep Read c, Rep Read d, Rep Read e, Rep Read f, Rep Read h) => Rep Read ((,,,,,,) a b c d e f h) |
|
|
|
|
Generate a ReadPrec parser combinator for the datatype a that handles
operator precedence. This uses the library in
Text.ParserCombinators.ReadPrec and should be similar to a derived
implementation of Text.Read.readPrec.
|
|
|
:: Rep Read a | | => Int | Operator precedence of the enclosing context (a number from 0 to 11).
| -> ReadP a | | Generate a ReadP parser combinator for the datatype a. This can be used
with Text.ParserCombinators.ReadP.
|
|
|
|
:: Rep Read a | | => Int | Operator precedence of the enclosing context (a number from 0 to 11).
| -> ReadS a | Equivalent to String -> [(a,String)].
| Attempt to parse a value from the front of the string using the given
precedence. readsPrec returns a list of (parsed value, remaining string)
pairs. If parsing fails, readsPrec returns an empty list.
|
|
|
|
A variant of readsPrec with the minimum precedence (0).
|
|
|
A variant of reads that returns Just value on a successful parse.
Otherwise, read returns Nothing. Note that a successful parse requires
the input to be completely consumed.
|
|
Show Functions
|
|
Functions similar to deriving Show that return a string
representation of a value of a datatype.
For more details, see Generics.EMGM.Functions.Show.
|
|
|
The type of a generic function that takes a constructor-type argument, a
number (precedence), and a value and returns a ShowS function.
| Constructors | | Instances | Generic Show | Rep Show String | Rep Show () | Rep Show a => Rep Show ([] a) | (Rep Show a, Rep Show b) => Rep Show ((,) a b) | (Rep Show a, Rep Show b, Rep Show c) => Rep Show ((,,) a b c) | (Rep Show a, Rep Show b, Rep Show c, Rep Show d) => Rep Show ((,,,) a b c d) | (Rep Show a, Rep Show b, Rep Show c, Rep Show d, Rep Show e) => Rep Show ((,,,,) a b c d e) | (Rep Show a, Rep Show b, Rep Show c, Rep Show d, Rep Show e, Rep Show f) => Rep Show ((,,,,,) a b c d e f) | (Rep Show a, Rep Show b, Rep Show c, Rep Show d, Rep Show e, Rep Show f, Rep Show h) => Rep Show ((,,,,,,) a b c d e f h) |
|
|
|
|
:: Rep Show a | | => Int | Operator precedence of the enclosing context (a number from 0 to 11).
| -> a | The value to be converted to a String.
| -> ShowS | | Convert a value to a readable string starting with the operator precedence
of the enclosing context.
|
|
|
|
A variant of showsPrec with the minimum precedence (0).
|
|
|
A variant of shows that returns a String instead of ShowS.
|
|
UnzipWith Functions
|
|
Functions that split a polymorphic functor values into two structurally
equilvalent values.
For more details, see Generics.EMGM.Functions.UnzipWith.
|
|
newtype UnzipWith a b c | Source |
|
The type of a generic function that takes an argument of one type and
returns a pair of values with two different types.
| Constructors | UnzipWith | | selUnzipWith :: a -> (b, c) | |
|
| Instances | |
|
|
|
Transforms a container of pairs into a container of first components and a
container of second components. This is a generic version of the Prelude
function of the same name.
|
|
|
:: FRep3 UnzipWith f | | => a -> (b, c) | Splitting function.
| -> f a | Container of a-values.
| -> (f b, f c) | Pair of containers.
| Splits a container into two structurally equivalent containers by applying
a function to every element, which splits it into two corresponding elements.
|
|
|
ZipWith Functions
|
|
Functions that combine two structurally equilvalent, polymorphic functor
values into one.
For more details, see Generics.EMGM.Functions.ZipWith.
|
|
|
The type of a generic function that takes two arguments of two different
types and optionally returns a value of a third type.
| Constructors | ZipWith | | selZipWith :: a -> b -> Maybe c | |
|
| Instances | |
|
|
|
Combine two containers into a single container with pairs of the original
elements. See zipWith for restrictions. This is a generic version of the
Prelude function of the same name.
|
|
|
:: FRep3 ZipWith f | | => a -> b -> c | Binary operator on elements of containers.
| -> f a | Container of a-values.
| -> f b | Container of b-values.
| -> Maybe (f c) | Container of c-values if successful or Nothing
if failed.
| Combine two structurally equivalent containers into one by applying a
function to every corresponding pair of elements. Returns Nothing if f a
and f b have different shapes.
|
|
|
Produced by Haddock version 2.4.2 |