generic-deriving
Generic programming library for generalised deriving.
https://github.com/dreixel/generic-deriving
LTS Haskell 22.33: | 1.14.5@rev:3 |
Stackage Nightly 2024-09-07: | 1.14.5@rev:3 |
Latest on Hackage: | 1.14.5@rev:3 |
generic-deriving-1.14.5@sha256:645e75f3cb7b930381ea67003ac2af08a9299463278a862f21f5bfc93febebb1,7222
Module documentation for 1.14.5
- Generics
- Generics.Deriving
- Generics.Deriving.Base
- Generics.Deriving.ConNames
- Generics.Deriving.Copoint
- Generics.Deriving.Default
- Generics.Deriving.Enum
- Generics.Deriving.Eq
- Generics.Deriving.Foldable
- Generics.Deriving.Functor
- Generics.Deriving.Instances
- Generics.Deriving.Monoid
- Generics.Deriving.Semigroup
- Generics.Deriving.Show
- Generics.Deriving.TH
- Generics.Deriving.Traversable
- Generics.Deriving.Uniplate
- Generics.Deriving
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.Base
defines the core functionality for GHC generics, including theGeneric(1)
classes and representation data types. On modern versions of GHC, this simply re-exportsGHC.Generics
frombase
. On older versions of GHC, this module backports parts ofGHC.Generics
that were not included at the time, includingGeneric(1)
instances. -
Generics.Deriving.TH
implements Template Haskell functionality for deriving instances ofGeneric(1)
. -
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:-
Generics.Deriving.Copoint
-
Generics.Deriving.ConNames
-
Generics.Deriving.Enum
-
Generics.Deriving.Eq
-
Generics.Deriving.Foldable
-
Generics.Deriving.Functor
-
Generics.Deriving.Monoid
-
Generics.Deriving.Semigroup
-
Generics.Deriving.Show
-
Generics.Deriving.Traversable
-
Generics.Deriving.Uniplate
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,
GShow
fromGenerics.Deriving.Show
resemblesShow
frombase
—but in general, the classes thatgeneric-deriving
defines are not drop-in replacements. Moreover, the generic defaults thatgeneric-deriving
provide often make simplifying assumptions that may violate expectations of how these classes might work elsewhere. For example, the generic default forGShow
does not behave exactly likederiving Show
would.If you are seeking
GHC.Generics
-based defaults for type classes inbase
, consider using thegeneric-data
library. -
-
Generics.Deriving.Default
provides newtypes that allow leveraging the generic defaults in this library using theDerivingVia
GHC language extension. -
Generics.Deriving
re-exportsGenerics.Deriving.Base
,Generics.Deriving.Default
, and a selection of educational modules.
Changes
1.14.5 [2023.08.06]
- Support building with
template-haskell-2.21.*
(GHC 9.8). - The Template Haskell machinery now uses
TemplateHaskellQuotes
when building with GHC 8.0+ instead of manually constructing each Template HaskellName
. A consequence of this is thatgeneric-deriving
will now build with GHC 9.8, asTemplateHaskellQuotes
abstracts over some internal Template Haskell changes introduced in 9.8.
1.14.4 [2023.04.30]
- Allow building with GHC backends where
HTYPE_SIG_ATOMIC_T
is not defined, such as the WASM backend. - Place
INLINE [1]
pragmas onfrom
andto
implementations when types don’t have too many constructors or fields, following the heuristics that GHC 9.2+ uses forGeneric
deriving.
1.14.3 [2023.02.27]
- Support
th-abstraction-0.5.*
.
1.14.2 [2022.07.23]
- Fix a bug in which
deriveAll1
could generate ill kinded code when usingkindSigOptions=False
, or when using GHC 8.0 or earlier. - Fix a bug in which
deriveAll1
would reject data types whose last type variable has a kind besidesType
ork
on GHC 8.2 or later.
1.14.1 [2021.08.30]
- Backport the
Generic(1)
instances introduced for tuples (8 through 15) inbase-4.16
. - Make the test suite compile on GHC 9.2 or later.
- Always import
Data.List
qualified to fix the build with recent GHCs.
1.14 [2020.09.30]
- Remove instances for
Data.Semigroup.Option
, which is deprecated as ofbase-4.15.0.0
. - Allow building with
template-haskell-2.17.0.0
(GHC 9.0). - Fix a bug in which
deriveAll1
would needlessly reject data types whose last type parameter appears as an oversaturated argument to a type family.
1.13.1 [2019.11.26]
- Backport the
Generic(1)
instances forKleisli
introduced inbase-4.14
.
1.13 [2019.08.27]
- Make
GSemigroup
a superclass ofGMonoid
. Similarly, makeGSemigroup'
a superclass ofGMonoid'
. - In the instance
GMonoid (Maybe a)
, relax the constraint ona
fromGMonoid
toGSemigroup
.
1.12.4 [2019.04.26]
- Support
th-abstraction-0.3.0.0
or later.
1.12.3 [2019.02.09]
- Support
template-haskell-2.15
. - Add a
gshowList
method toGShow
, which lets us avoid the need forOverlappingInstances
inGenerics.Deriving.TH
. As a consequence, theGShow String
instance has been removed, as it is now fully subsumed by theGShow [a]
instance (with which it previously overlapped). - Functions in
Generics.Deriving.TH
now balance groups of(:*:)
and(:+:)
as much as possible (deriving Generic
was already performing this optimization, and nowgeneric-deriving
does too). - Add a
Generics.Deriving.Default
module demonstrating and explaining how and why to useDerivingVia
. There is also a test suite with further examples.
1.12.2 [2018.06.28]
- Backport the
Generic(1)
instances forData.Ord.Down
, introduced inbase-4.12
. AddGEq
,GShow
,GSemigroup
,GMonoid
,GFunctor
,GFoldable
,GTraversable
, andGCopoint
instances forDown
. - Refactor internals using
th-abstraction
. - Adapt to
Maybe
moving toGHC.Maybe
in GHC 8.6.
1.12.1 [2018.01.11]
- Remove a test that won’t work on GHC 8.4.
1.12 [2017.12.07]
- Adapt to the
EmptyDataDeriving
proposal (introduced in GHC 8.4):Generics.Deriving.TH
now derivesto(1)
andfrom(1)
implementations for empty data types that are strict in the argument.- Introduce an
EmptyCaseOptions
field toOptions
inGenerics.Deriving.TH
, which controls whether generatedfrom(1)
/to(1)
implementations for empty data types should use theEmptyCase
extension or not (as is the case in GHC 8.4). - Add
mkFrom0Options
,mkFrom1Options
,mkTo0Options
, andmkTo1Options
functions toGenerics.Deriving.TH
, which takeEmptyCaseOptions
as arguments. - The backported instances for
V1
are now maximally lazy, as perEmptyDataDeriving
. (Previously, some instances would unnecessarily force their argument, such as theEq
andOrd
instances.) - Add instances for
V1
inGenerics.Deriving.Copoint
,.Eq
,.Foldable
,.Functor
,.Show
, and.Traversable
.
- Remove the bitrotting
simplInstance
function fromGenerics.Deriving.TH
.
1.11.2 [2017.04.10]
- Add
GEq
,GShow
,GEnum
, andGIx
instances for the new data types inForeign.C.Types
(CBool
) andSystem.Posix.Types
(CBlkSize
,CBlkCnt
,CClockId
,CFsBlkCnt
,CFsFilCnt
,CId
,CKey
, andCTimer
) introduced inbase-4.10.0.0
1.11.1 [2016.09.10]
- Fix Template Haskell regression involving data families
- Convert examples to test suite
- Backport missing
Data
andTypeable
instances forRec1
,M1
,(:*:)
,(:+:)
, and(:.:)
1.11
-
The behavior of functions in
Generics.Deriving.TH
have changed with respect to when type synonyms are generated forRep(1)
definitions. In particular:- By default,
deriveRepresentable(1)
will no longer define itsRep(1)
type family instance in terms of the type synonym that has to be generated withderiveRep(1)
. Similarly,deriveAll(1)
andderiveAll0And1
will no longer generate a type synonym. Instead, they will generateGeneric(1)
instances that directly define theRep(1)
instance inline. If you wish to revert to the old behavior, you will need to use the variants of those functions suffixed with-Options
. - New functions
makeRep0Inline
andmakeRep1Inline
have been added which, for most purposes, should replace uses ofmakeRep0
/makeRep0FromType
andmakeRep1
/makeRep1FromType
(but see the next bullet point for a caveat). - The use of
deriveRep(1)
,makeRep0
/makeRep0FromType
, andmakeRep1
/makeRep1FromType
are now discouraged, but those functions are still available. The reason is that on GHC 7.0/7.2/7.4, it is impossible to usemakeRep0Inline
/makeRep1Inline
due to a GHC bug. Therefore, you must usemakeRep0
/makeRep1
andderiveRep(1)
on GHC 7.0/7.2/7.4 out of necessity.
These changes make dealing with
Generic
instances that involvePolyKinds
andTypeInType
much easier. - By default,
-
All functions suffixed in
-WithKindSigs
inGenerics.Deriving.TH
have been removed in favor of a more sensible-Options
suffixing scheme. The ability to toggle whether explicit kind signatures are used on type variable binders has been folded intoKindSigOptions
, which is an explicit argument toderiveRep0Options
/deriveRep1Options
and 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
TypeInType
less surprising, but at the cost of making it slightly more awkward to work with derivedGeneric1
instances that constrain kinds to*
by means of(:.:)
. -
Since
Generic1
is polykinded on GHC 8.2 and later, the functions inGenerics.Deriving.TH
will 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 kindedGeneric(1)
instance. -
Backport missing
Foldable
andTraversable
instances forRec1
1.10.7
- Renamed internal modules to avoid using apostrophes (averting this bug: https://github.com/haskell/cabal/issues/3631)
1.10.6
- A new
base-4-9
Cabal flag was added to more easily facilitate installinggeneric-deriving
with manually installed versions oftemplate-haskell
.
1.10.5
- Apply an optimization to generated
to(1)
/from(1)
instances that factors out common occurrences ofM1
. See http://git.haskell.org/ghc.git/commit/9649fc0ae45e006c2ed54cc5ea2414158949fadb - Export internal typeclass names
- Fix Haddock issues with GHC 7.8
1.10.4.1
- Fix Haddock parsing issue on GHC 8.0
1.10.4
- Backported
MonadPlus
andMonadZip
instances forU1
, and made theFunctor
,Foldable
,Traversable
,Alternative
, andMonad
instances forU1
lazier to correspond withbase-4.9
1.10.3
- Backported
Enum
,Bounded
,Ix
,Functor
,Applicative
,Monad
,MonadFix
,MonadPlus
,MonadZip
,Foldable
,Traversable
, andData
instances (introduced inbase-4.9
) for datatypes in theGenerics.Deriving.Base
module
1.10.2
- Fix TH regression on GHC 7.0
1.10.1
- Added
Generics.Deriving.Semigroup
- Added
GMonoid
instance forData.Monoid.Alt
- Fixed a bug in the
GEnum
instances for unsignedIntegral
types - Added
Safe
/Trustworthy
pragmas - Made instances polykinded where possible
1.10.0
- On GHC 8.0 and up,
Generics.Deriving.TH
uses 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
-XTypeInType
extension. - Added
deriveAll0
andmakeRep0
for symmetry withderiveAll1
andmakeRep1
- Added
makeRep0FromType
andmakeRep1FromType
to 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
-WithKindSigs
to allow generating type synonyms with explicit kind signatures in the presence of kind-polymorphic type variables. This is necessary for some datatypes that use-XTypeInType
to have derivedGeneric(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
incorrect
Generic
instances - More sensible
GEnum
instances for fixed-size integral types - Added
GCopoint
,GEnum
,GEq
,GFoldable
,GFunctor
,GMonoid
,GShow
, andGTraversable
instances for datatypes introduced in GHC 8.0 - Backported
Generic(1)
instances added in GHC 8.0. Specifically,Generic
instances forComplex
(base-4.4
and later)ExitCode
, andVersion
; andGeneric1
instances forComplex
(base-4.4
and later) andProxy
(base-4.7
and later). AddedGEnum
,GEq
,GFoldable
,GFunctor
,GIx
,GShow
, andGTraversable
instances for these datatypes where appropriate.
1.9.0
- 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+
- More
GCopoint
,GEnum
,GEq
,GFoldable
,GFunctor
,GIx
,GMonoid
,GShow
, andGTraversable
instances - The field accessors for the
(:+:)
type inGenerics.Deriving.Base
have been removed to be consistent withGHC.Generics
- 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