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:

• Generics.EMGM.Common - Common infrastructure for supporting datatypes and defining functions.
• Generics.EMGM.Functions - Generic functions included with EMGM.
• Generics.EMGM.Derive - Generating the EMGM representation for a datatype.

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.

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.

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.

Function that collects values of one type from values of a possibly different type.

For more details, see Generics.EMGM.Functions.Collect.

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 with 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.

Functions that compare two values to determine an ordering.

For more details, see Generics.EMGM.Functions.Compare.

Functions that crush a polymorphic functor container into an iteration over its elements.

For more details, see Generics.EMGM.Functions.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.

Functions that enumerate the values of a datatype.

For more details, see Generics.EMGM.Functions.Enum.

Functions that apply a transformation at every location of one type in a value of a possibly different type.

For more details, see Generics.EMGM.Functions.Everywhere.

Apply a transformation a -> a to values of type a within the argument of type b in a bottom-up manner. Values that do not have type a are passed through id.

everywhere works by searching the datatype b for values that are the same type as the function argument type a. Here are some examples using the datatype declared in the documentation for Everywhere.

   ghci> let f t = case t of { Val i -> Val (i+(1::Int)); other -> other }
   ghci> everywhere f (Val (1::Int))
   Val 2
   ghci> everywhere f (Rec (Rec (Val (1::Int))))
   Rec (Rec (Val 2))

   ghci> let x = [Left 1, Right 'a', Left 2] :: [Either Int Char]
   ghci> everywhere (*(3::Int)) x
   [Left 3,Right 'a',Left 6]
   ghci> everywhere (\x -> x :: Float) x == x
   True

Note the type annotations. Since numerical constants have the type Num a => a, you may need to give explicit types. Also, the function \x -> x has type a -> a, but we need to give it some non-polymorphic type here. By design, there is no connection that can be inferred between the value type and the function type.

everywhere only works if there is an instance for the return type as described in the newtype Everywhere.

Apply a transformation a -> a to values of type a within the argument of type b in a top-down manner. Values that do not have type a are passed through id.

everywhere' is the same as everywhere with the exception of recursive datatypes. For example, compare the example used in the documentation for everywhere with the following.

   ghci> let f t = case t of { Val i -> Val (i+(1::Int)); other -> other }
   ghci> everywhere' f (Val (1::Int))
   Val 2
   ghci> everywhere' f (Rec (Rec (Val (1::Int))))
   Rec (Rec (Val 1))

everywhere' only works if there is an instance for the return type as described in the newtype Everywhere'.

Functions that translate values of one type to values of another. This includes map-like functions that apply non-generic functions to every element in a polymorphic (functor or bifunctor) container. It also includes cast, a configurable, type-safe casting function.

For more details, see Generics.EMGM.Functions.Map.

Cast a value of one type into a value of another. This is a configurable function that allows you to define your own type-safe conversions for a variety of types.

cast works with instances of Rep (Map i) o in which you choose the input type i and the output type o and implement the function of type i -> o.

Here are some examples of instances (and flags you will need or want):

   {-# LANGUAGE MultiParamTypeClasses  #-}
   {-# LANGUAGE FlexibleContexts       #-}
   {-# LANGUAGE FlexibleInstances      #-}
   {-# OPTIONS_GHC -fno-warn-orphans   #-}

   instance Rep (Map Int) Char where
     rep = Map chr

   instance Rep (Map Float) Double where
     rep = Map realToFrac

   instance Rep (Map Integer) Integer where
     rep = Map (+42)

There are no pre-defined instances, and a call to cast will not compile if no instances for the input and output type pair is found, so you must define instances in order to use cast.

Functions similar to deriving Read that parse a string and return a value of a datatype.

For more details, see Generics.EMGM.Functions.Read.

Functions similar to deriving Show that return a string representation of a value of a datatype.

For more details, see Generics.EMGM.Functions.Show.

Functions that split a polymorphic functor values into two structurally equilvalent values.

For more details, see Generics.EMGM.Functions.UnzipWith.

Functions that combine two structurally equilvalent, polymorphic functor values into one.

For more details, see Generics.EMGM.Functions.ZipWith.