Module documentation for 1.14.5
generic-deriving: Generic programming library for generalised deriving
This package provides functionality for generalising the deriving mechanism in Haskell to arbitrary classes. It was first described in the paper:
- A generic deriving mechanism for Haskell. Jose Pedro Magalhaes, Atze Dijkstra, Johan Jeuring, and Andres Loeh. Haskell’10.
The current implementation integrates with the new GHC Generics. See http://www.haskell.org/haskellwiki/GHC.Generics for more information. Template Haskell code is provided for supporting older GHCs.
This library is organized as follows:
Generics.Deriving.Basedefines the core functionality for GHC generics, including the
Generic(1)classes and representation data types. On modern versions of GHC, this simply re-exports
base. On older versions of GHC, this module backports parts of
GHC.Genericsthat were not included at the time, including
Generics.Deriving.THimplements Template Haskell functionality for deriving instances of
Educational code: in order to provide examples of how to define and use
GHC.Generics-based defaults, this library offers a number of modules which define examples of type classes along with default implementations for the classes’ methods. Currently, the following modules are provided:
It is worth emphasizing that these modules are primarly intended for educational purposes. Many of the classes in these modules resemble other commonly used classes—for example,
base—but in general, the classes that
generic-derivingdefines are not drop-in replacements. Moreover, the generic defaults that
generic-derivingprovide often make simplifying assumptions that may violate expectations of how these classes might work elsewhere. For example, the generic default for
GShowdoes not behave exactly like
If you are seeking
GHC.Generics-based defaults for type classes in
base, consider using the
Generics.Deriving.Defaultprovides newtypes that allow leveraging the generic defaults in this library using the
DerivingViaGHC language extension.
Generics.Deriving.Default, and a selection of educational modules.
- Support building with
- The Template Haskell machinery now uses
TemplateHaskellQuoteswhen building with GHC 8.0+ instead of manually constructing each Template Haskell
Name. A consequence of this is that
generic-derivingwill now build with GHC 9.8, as
TemplateHaskellQuotesabstracts over some internal Template Haskell changes introduced in 9.8.
- Allow building with GHC backends where
HTYPE_SIG_ATOMIC_Tis not defined, such as the WASM backend.
INLINE pragmas on
toimplementations when types don’t have too many constructors or fields, following the heuristics that GHC 9.2+ uses for
- Fix a bug in which
deriveAll1could generate ill kinded code when using
kindSigOptions=False, or when using GHC 8.0 or earlier.
- Fix a bug in which
deriveAll1would reject data types whose last type variable has a kind besides
kon GHC 8.2 or later.
- Backport the
Generic(1)instances introduced for tuples (8 through 15) in
- Make the test suite compile on GHC 9.2 or later.
- Always import
Data.Listqualified to fix the build with recent GHCs.
- Remove instances for
Data.Semigroup.Option, which is deprecated as of
- Allow building with
- Fix a bug in which
deriveAll1would needlessly reject data types whose last type parameter appears as an oversaturated argument to a type family.
- Backport the
GSemigroupa superclass of
GMonoid. Similarly, make
GSemigroup'a superclass of
- In the instance
GMonoid (Maybe a), relax the constraint on
- Add a
GShow, which lets us avoid the need for
Generics.Deriving.TH. As a consequence, the
GShow Stringinstance has been removed, as it is now fully subsumed by the
GShow [a]instance (with which it previously overlapped).
- Functions in
Generics.Deriving.THnow balance groups of
(:+:)as much as possible (
deriving Genericwas already performing this optimization, and now
- Add a
Generics.Deriving.Defaultmodule demonstrating and explaining how and why to use
DerivingVia. There is also a test suite with further examples.
- Backport the
Data.Ord.Down, introduced in
- Refactor internals using
- Adapt to
GHC.Maybein GHC 8.6.
- Remove a test that won’t work on GHC 8.4.
- Adapt to the
EmptyDataDerivingproposal (introduced in GHC 8.4):
from(1)implementations for empty data types that are strict in the argument.
- Introduce an
Generics.Deriving.TH, which controls whether generated
to(1)implementations for empty data types should use the
EmptyCaseextension or not (as is the case in GHC 8.4).
Generics.Deriving.TH, which take
- The backported instances for
V1are now maximally lazy, as per
EmptyDataDeriving. (Previously, some instances would unnecessarily force their argument, such as the
- Add instances for
- Remove the bitrotting
GIxinstances for the new data types in
CTimer) introduced in
- Fix Template Haskell regression involving data families
- Convert examples to test suite
- Backport missing
The behavior of functions in
Generics.Deriving.THhave changed with respect to when type synonyms are generated for
Rep(1)definitions. In particular:
- By default,
deriveRepresentable(1)will no longer define its
Rep(1)type family instance in terms of the type synonym that has to be generated with
deriveAll0And1will no longer generate a type synonym. Instead, they will generate
Generic(1)instances that directly define the
Rep(1)instance inline. If you wish to revert to the old behavior, you will need to use the variants of those functions suffixed with
- New functions
makeRep1Inlinehave been added which, for most purposes, should replace uses of
makeRep1FromType(but see the next bullet point for a caveat).
- The use of
makeRep1FromTypeare now discouraged, but those functions are still available. The reason is that on GHC 7.0/7.2/7.4, it is impossible to use
makeRep1Inlinedue to a GHC bug. Therefore, you must use
deriveRep(1)on GHC 7.0/7.2/7.4 out of necessity.
These changes make dealing with
Genericinstances that involve
- By default,
All functions suffixed in
Generics.Deriving.THhave been removed in favor of a more sensible
-Optionssuffixing scheme. The ability to toggle whether explicit kind signatures are used on type variable binders has been folded into
KindSigOptions, which is an explicit argument to
deriveRep1Optionsand also a field in the more general ‘Options’ data type.
Furthermore, the behavior of derived instances’ kind signatures has changed. By default, the TH code will now always use explicit kind signatures whenever possible, regardless of whether you’re working with plain data types or data family instances. This makes working with
TypeInTypeless surprising, but at the cost of making it slightly more awkward to work with derived
Generic1instances that constrain kinds to
*by means of
Generic1is polykinded on GHC 8.2 and later, the functions in
Generics.Deriving.THwill no longer unify the kind of the last type parameter to be
Fix a bug in which
makeRep(and similarly named functions) would not check whether the argument type can actually have a well kinded
- Renamed internal modules to avoid using apostrophes (averting this bug: https://github.com/haskell/cabal/issues/3631)
- A new
base-4-9Cabal flag was added to more easily facilitate installing
generic-derivingwith manually installed versions of
- Apply an optimization to generated
from(1)instances that factors out common occurrences of
M1. See http://git.haskell.org/ghc.git/commit/9649fc0ae45e006c2ed54cc5ea2414158949fadb
- Export internal typeclass names
- Fix Haddock issues with GHC 7.8
- Fix Haddock parsing issue on GHC 8.0
U1, and made the
U1lazier to correspond with
Datainstances (introduced in
base-4.9) for datatypes in the
- Fix TH regression on GHC 7.0
- Fixed a bug in the
GEnuminstances for unsigned
- Made instances polykinded where possible
- On GHC 8.0 and up,
Generics.Deriving.THuses the new type literal-based machinery
- Rewrote the Template Haskell code to be robust. Among other things, this fixes
a bug with deriving Generic1 instances on GHC 7.8, and makes it easier to
derive Generic1 instances for datatypes that utilize GHC 8.0’s
makeRep0for symmetry with
makeRep1FromTypeto make it easier to pass in the type instance (instead of having to pass each individual type variable, which can be error-prone)
- Added functions with the suffix
-WithKindSigsto allow generating type synonyms with explicit kind signatures in the presence of kind-polymorphic type variables. This is necessary for some datatypes that use
-XTypeInTypeto have derived
Generic(1)instances, but is not turned on by default since the TH kind inference is not perfect and would cause otherwise valid code to be rejected. Use only if you know what you are doing.
- Fixed bug where a datatype with a single, nullary constructor would generate
- More sensible
GEnuminstances for fixed-size integral types
GTraversableinstances for datatypes introduced in GHC 8.0
Generic(1)instances added in GHC 8.0. Specifically,
base-4.4and later) and
base-4.7and later). Added
GTraversableinstances for these datatypes where appropriate.
- Allow deriving of Generic1 using Template Haskell
- Allow deriving of Generic(1) for data families
- Allow deriving of Generic(1) for constructor-less plain datatypes (but not data families, due to technical restrictions)
- Support for unboxed representation types on GHC 7.11+
- The field accessors for the
Generics.Deriving.Basehave been removed to be consistent with
- Ensure that TH generates definitions for isNewtype and packageName, if a recent-enough version of GHC is used
- Ensure that TH-generated names are unique for a given data type’s module and package (similar in spirit to Trac #10487)
- Allow building on stage-1 compilers