Module documentation for 0.3.2.0
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.
Generics.SOP is the main module of this library and contains
more detailed documentation.
Examples of using this library are provided by the following packages:
pretty-sopgeneric pretty printing,
lens-sopgenerically computed lenses,
json-sopgeneric 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.
deriveGenericFunctionswork properly with parameterized types (note that the more widely used
deriveGenericwas already working correctly).
deriveGenericwork properly with empty types.
ccompare_SOPto better support comparison of sum structures.
hctraverse'as well as their unconstrained variants and a number of derived functions, to support effectful traversals.
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 use
fromto turn the generically derived
Is into an
Maybes (and back).
IsNewtypeconstraint synonyms capturing specific classes of datypes.
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.Metadatamodule. The two modules
Generics.SOP.Type.Metadataexport nearly the same names, so for backwards compatibility, we keep exporting
Generics.SOP.Type.Metadatais 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.
GHC 8.2 compatibility.
:.:an instance of
apInjs'_POP. These are variants of
apInjs'_POPthat return their result as an n-ary product, rather than collapsing it into a list.
expand_SOP). These functions expand sums into products, given a default value to fill the other slots.
Add utility functions such as
mapIKthat lift functions into different combinations of identity and constant functors.
NFData(and lifted variants) instances for basic functors, products and sums.
hapInjsas a generalization of
Make basic functors instances of lifted classes (such as
Add various metadata getters
Add catamorphisms and anamorphisms for
TH compatibility changes for GHC 8.1 (master).
unZto destruct a unary sum.
@sinceannotations for various functions.
Now includes a CHANGELOG.
Should now work with ghc-8.0.1-rc1 and -rc2 (thanks to Oleg Grenrus).
tlto project out of a product, and
projectionsas duals of
Now tested with ghc-7.10
hcliftA2, respectively. Similarly for the specialized versions of these functions.
The constraint transformers
All2are now defined as type classes, not type families. As a consequence, the partial applications
All2 care now possible.
Because of the redefinition of
All2, some special cases are no longer necessary. For example,
cpure_POPcan now be implemented as a nested application of
Because of the redefinition of
All2, the functions
hcliftA'and variants (with prime!) are now deprecated. One can easily use the normal versions instead. For example, the definition of
hcliftA'is now simply
hcliftA' p = hcliftA (allP p) where allP :: proxy c -> Proxy (All c) allP _ = Proxy
All2are 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.
Singdatatypes are now deprecated. The replacements are called
singmethod is now called
sList. 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 => ...
SListI xs => ...
For two-dimensional type-level lists, replace
SingI xss => ...
All SListI xss => ...
Because All itself implies
SListI xss(see above), this constraint is equivalent to the old
The old names are provided for (limited) backward compatibility. They map to the new constructs. This will work in some, but not all scenarios.
lengthSinghas also been renamed to
lengthSListfor consistency, and the old name is deprecated.
Proxy carguments have been replaced by
proxy cflexible 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 as
All c (Map f xs)
should now be replaced with
All (c `Compose` f) xs
There is a new module called
Generics.SOP.Dictthat 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 using
All2. Some such theorems are provided.
There is a new TH function
deriveGenericFunctionsthat 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
deriveMetadataValuethat derives a
DatatypeInfovalue for a datatype, but does not create an instance of
HasDatatypeInfo. (Contributed by Oleg Grenrus.)
There is a very simple example file. (Contributed by Oleg Grenrus.)
NSnow results in an
arather than an
I a, matching the specialized version
collapse_NS. (Suggested by Roman Cheplyaka.)
- Updated version bounds for ghc-prim (for ghc-7.10).
Preparations for ghc-7.10.
Documentation fix. (Contributed by Roman Cheplyaka.)
Add superclass constraint (TODO).
Now derive tuple instance for tuples up to 30 components. (Contributed by Michael Orlitzky.)