Generic functions that approximate familiar term-level functions. The generics handle the sum of products representation and have "holes" for the base case, which must be filled by the user via a type class. Perhaps you may also think of these as "reusable" or "generic" generics.
Most relevant for simple parsing and printing/serializing/reducing tasks where the only "work" to do for the given data type is mechanical field sequencing. If you require more logic than that (and can't place it in types/newtypes), you will not be able to use this library.
Emphasis is put on type safety and performance. Notably, for sum type generics,
we permit parsing constructor names on the type level (via
symparsec). For cases where you
want to implement your own high-performance sum type handling, we provide
Generic.Data.FOnCstr.
There are a number of competing parsing and serialization Haskell libraries. Most have a type class for enumerating permitted types, and some simple generics which use that type class for the base case. Other than that base case, everyone is writing largely the same generic code.
While writing my own libraries, I realized that if another developer wanted use my serializer, they would probably need to write their own type class for base cases (due to some specific library design). Alas, this would mean they have to copy-paste my generics and swap the type classes. Very silly. But it turned out my generics were otherwise highly general, so I spun them out into this library. Now you can swap the type class just by filling in some holes.
Unless otherwise specified, this is how we disambiguate constructors. How the sum tag is parsed from a constructor is up to the user (and may be done on the type-level if one wishes).
foldMap :: (Foldable t, Monoid m) => (a -> m) -> t a -> mThe user provides the a -> m dictionary via a special type class instance.
Constructor fields are mapped and combined left-to-right. Sum representations
are handled by mappending the constructor via a user-supplied String -> m
first.
Useful for:
- simple binary serializers which just concatenate fields together
- reducing to a numeric value
traverse :: (Traversable t, Applicative f) => (a -> f b) -> t a -> f (t b)The user provides the f a dictionary via a special type class instance.
Constructor field actions are run left-to-right.
Sum representations are handled by running a constructor action first (thus
requiring Monad f).
Useful for:
- simple binary parsers which can parse generic
foldMapoutput
I don't know what this is exactly. It's like contramap?
This library is designed to work with and around existing libraries and type classes. Thus, you will likely be dealing in orphans. Instances, that is. That's life, Jim.
I have made some weird design choices in this library. Here are some rationales.
I don't like silently erroring on badly-configured generics usage, e.g. asking for a function via generics for an empty data type. Originally, I made those type error, and that was that. But it meant I would write the same instance over and over again. And that requirement was hidden in a type class implementation. Really, it'd be nice if I could put such requirements directly in the types of the functions that have them.
I've done that. Now, on certain representation errors, e.g. you tried to use non-sum generics on a sum type, we runtime error instead. However, there's a separate layer for making assertions about generic representation on the type level, the use of which is highly suggested.
Note that if you like to write wrappers over generic functions to fill in certain bits of info, your job just got a lot uglier. Soz. Anything for type safety my sweet.
Provided under the MIT license. See LICENSE for license text.