generics-sop
Generic Programming using True Sums of Products
Version on this page: | 0.5.1.3 |
LTS Haskell 22.33: | 0.5.1.3 |
Stackage Nightly 2024-09-07: | 0.5.1.4@rev:1 |
Latest on Hackage: | 0.5.1.4@rev:1 |
generics-sop-0.5.1.3@sha256:3e4ba98d8107d061262b6a59999a7d49879a58ad6ef8257006c104e8591b7842,5703
Module documentation for 0.5.1.3
- Generics
A library to support the definition of generic functions. Datatypes are viewed in a uniform, structured way: the choice between constructors is represented using an n-ary sum, and the arguments of each constructor are represented using an n-ary product.
The module Generics.SOP
is the main module of this library and contains
more detailed documentation.
Since version 0.4.0.0, this package is now based on
sop-core
. The core package
contains all the functionality of n-ary sums and products, whereas this
package provides the datatype-generic programming support on top.
Examples of using this library are provided by the following packages:
basic-sop
basic examples,pretty-sop
generic pretty printing,lens-sop
generically computed lenses,json-sop
generic JSON conversions.
A detailed description of the ideas behind this library is provided by the paper:
Edsko de Vries and Andres Löh. True Sums of Products. Workshop on Generic Programming (WGP) 2014.
Changes
0.5.1.3 (2023-04-23)
- Compatibility with GHC-9.6 / th-abstraction-0.5 (thanks to Ryan Scott).
0.5.1.2 (2022-01-02)
- Compatibility with GHC-9.2.
0.5.1.1 (2021-02-23)
- Compatibility with GHC-9.0.
0.5.1.0 (2020-03-29)
-
Compatibility with GHC-8.10 (thanks to Ryan Scott).
-
Improve TH generation support and extend it to type families (thanks to Ryan Scott).
0.5.0.0 (2019-05-09)
-
Add strictness info to the metadata. This means that code directly using the
ADT
constructor has to be modified because it now has a new fourth argument. (See #76 and #87.) -
Depend on
sop-core-0.5.0.*
which changes the definition ofSameShapeAs
to improve compiler performance and adds “ejections”.
0.4.0.1 (2018-10-23)
- Remove
GHC.Event
import inGenerics.SOP.Instances
to fix build on Windows.
0.4.0.0 (2018-10-20)
-
Split into
sop-core
andgenerics-sop
packages. -
Drop support for GHC < 8.0.2, bump
base
dependency to>= 4.9
and remove dependency ontransformers
. -
Simplify
All2 c
toAll (All c)
and simplifySListI xs
toAll Top xs
, and some implied refactoring. -
Add
Semigroup
andMonoid
instances for various datatypes. -
Add specialised conversion functions for product types, enumeration, and wrapped types.
-
Add benchmark suite.
-
Fix deriving
Generic
for empty datatypes. -
Generic
is now a superclass ofHasDatatypeInfo
. -
More
Generic
instances for datatypes from recent versions ofbase
.
0.3.2.0 (2018-01-08)
-
Make TH
deriveGenericFunctions
work properly with parameterized types (note that the more widely usedderiveGeneric
was already working correctly). -
Make TH
deriveGeneric
work properly with empty types. -
Add
compare_NS
,ccompare_NS
,compare_SOP
, andccompare_SOP
to better support comparison of sum structures. -
Add
hctraverse_
andhctraverse'
as well as their unconstrained variants and a number of derived functions, to support effectful traversals.
0.3.1.0 (2017-06-11)
-
Add
AllZip
,htrans
,hcoerce
,hfromI
,htoI
. These functions are for converting between related structures that do not have common signatures.The most common application of these functions seems to be the scenario where a datatype has components that are all wrapped in a common type constructor application, e.g. a datatype where every component is a
Maybe
. Then we can usehfromI
afterfrom
to turn the generically derivedSOP
ofI
s into anSOP
ofMaybe
s (and back). -
Add
IsProductType
,IsEnumType
,IsWrappedType
andIsNewtype
constraint synonyms capturing specific classes of datypes.
0.3.0.0 (2017-04-29)
-
No longer compatible with GHC 7.6, due to the lack of support for type-level literals.
-
Support type-level metadata. This is provided by the
Generics.SOP.Type.Metadata
module. The two modulesGenerics.SOP.Metadata
andGenerics.SOP.Type.Metadata
export nearly the same names, so for backwards compatibility, we keep exportingGenerics.SOP.Metadata
directly fromGenerics.SOP
, whereasGenerics.SOP.Type.Metadata
is supposed to be imported explicitly (and qualified).Term-level metadata is still available, but is now usually computed automatically from the type-level metadata which contains the same information, using the function
demoteDatatypeInfo
. Term-level metadata is unchanged from generics-sop-0.2, so in most cases, even if your code makes use of metadata, you should not need to change anything.If you use TH deriving, then both type-level metadata and term-level metadata is generated for you automatically, for all supported GHC versions.
If you use GGP deriving, then type-level metadata is available if you use GHC 8.0 or newer. If you use GHC 7.x, then GHC.Generics supports only term-level metadata, so we cannot translate that into type-level metadata. In this combination, you cannot use code that relies on type-level metadata, so you should either upgrade GHC or switch to TH-based deriving.
0.2.5.0 (2017-04-21)
-
GHC 8.2 compatibility.
-
Make
:.:
an instance ofApplicative
,Foldable
andTraversable
. -
Add functions
apInjs'_NP
andapInjs'_POP
. These are variants ofapInjs_NP
andapInjs'_POP
that return their result as an n-ary product, rather than collapsing it into a list. -
Add
hexpand
(andexpand_NS
andexpand_SOP
). These functions expand sums into products, given a default value to fill the other slots. -
Add utility functions such as
mapII
ormapIK
that lift functions into different combinations of identity and constant functors. -
Add
NFData
(and lifted variants) instances for basic functors, products and sums.
0.2.4.0 (2017-02-02)
-
Add
hindex
(andindex_NS
andindex_SOP
). -
Add
hapInjs
as a generalization ofapInjs_NP
andapInjs_POP
. -
Make basic functors instances of lifted classes (such as
Eq1
etc).
0.2.3.0 (2016-12-04)
-
Add various metadata getters
-
Add
hdicts
. -
Add catamorphisms and anamorphisms for
NP
andNS
. -
TH compatibility changes for GHC 8.1 (master).
0.2.2.0 (2016-07-10)
-
Introduced
unZ
to destruct a unary sum. -
Add Haddock
@since
annotations for various functions.
0.2.1.0 (2016-02-08)
-
Now includes a CHANGELOG.
-
Should now work with ghc-8.0.1-rc1 and -rc2 (thanks to Oleg Grenrus).
-
Introduced
hd
andtl
to project out of a product, andProjection
andprojections
as duals ofInjection
andinjections
.
0.2.0.0 (2015-10-23)
-
Now tested with ghc-7.10
-
Introduced names
hmap
,hcmap
,hzipWith
,hczipWith
forhliftA
,hcliftA
,hliftA2
,hcliftA2
, respectively. Similarly for the specialized versions of these functions. -
The constraint transformers
All
andAll2
are now defined as type classes, not type families. As a consequence, the partial applicationsAll c
andAll2 c
are now possible. -
Because of the redefinition of
All
andAll2
, some special cases are no longer necessary. For example,cpure_POP
can now be implemented as a nested application ofpure_NP
. -
Because of the redefinition of
All
andAll2
, the functionshcliftA'
and variants (with prime!) are now deprecated. One can easily use the normal versions instead. For example, the definition ofhcliftA'
is now simplyhcliftA' p = hcliftA (allP p) where allP :: proxy c -> Proxy (All c) allP _ = Proxy
-
Because
All
andAll2
are now type classes, they now have superclass constraints implying that the type-level lists they are ranging over must have singletons.class (SListI xs, ...) => All c xs class (SListI xss, ...) => All2 c xss
Some type signatures can be simplified due to this.
-
The
SingI
typeclass andSing
datatypes are now deprecated. The replacements are calledSListI
andSList
. Thesing
method is now calledsList
. The difference is that the new versions reveal only the spine of the list, and contain no singleton representation for the elements anymore.For one-dimensional type-level lists, replace
SingI xs => ...
by
SListI xs => ...
For two-dimensional type-level lists, replace
SingI xss => ...
by
All SListI xss => ...
Because All itself implies
SListI xss
(see above), this constraint is equivalent to the oldSing xss
.The old names are provided for (limited) backward compatibility. They map to the new constructs. This will work in some, but not all scenarios.
The function
lengthSing
has also been renamed tolengthSList
for consistency, and the old name is deprecated. -
All
Proxy c
arguments have been replaced byproxy c
flexible arguments, so that other type constructors can be used as proxies. -
Class-level composition (
Compose
), pairing (And
), and a trivial constraint (Top
) have been added. Type-level map (Map
) has been removed. Occurrences such asAll c (Map f xs)
should now be replaced with
All (c `Compose` f) xs
-
There is a new module called
Generics.SOP.Dict
that contains functions for manipulating dictionaries explicitly. These can be used to prove theorems about non-trivial class constraints such as the ones that get built usingAll
andAll2
. Some such theorems are provided. -
There is a new TH function
deriveGenericFunctions
that derives the code of a datatype and conversion functions, but does not create a class instance. (Contributed by Oleg Grenrus.) -
There is a new TH function
deriveMetadataValue
that derives aDatatypeInfo
value for a datatype, but does not create an instance ofHasDatatypeInfo
. (Contributed by Oleg Grenrus.) -
There is a very simple example file. (Contributed by Oleg Grenrus.)
-
The function
hcollapse
forNS
now results in ana
rather than anI a
, matching the specialized versioncollapse_NS
. (Suggested by Roman Cheplyaka.)
0.1.1.2 (2015-03-27)
- Updated version bounds for ghc-prim (for ghc-7.10).
0.1.1.1 (2015-03-20)
-
Preparations for ghc-7.10.
-
Documentation fix. (Contributed by Roman Cheplyaka.)
0.1.1 (2015-01-06)
-
Documentation fixes.
-
Add superclass constraint (TODO).
-
Now derive tuple instance for tuples up to 30 components. (Contributed by Michael Orlitzky.)