Simple operations on generic representations: modify Generic instances to tweak the behavior of generic implementations as if you had declared a slightly different type.

This module provides the following microsurgeries:

• RenameFields: rename the fields of a record type.
• RenameConstrs: rename the constructors.
• OnFields: apply a type constructor f :: Type -> Type to every field.
• CopyRep: use the generic representation of another type of the same shape.
• Typeage: treat a newtype as a data type.
• Derecordify: treat a type as if it weren't a record.

More complex surgeries can be found in generic-data-surgery but also, perhaps surprisingly, in generic-lens (read more about this just below) and one-liner.

Surgeries can be used:

• to derive type class instances with the DerivingVia extension, using the Surgery or ProductSurgery type synonyms (for classes with instances for Generically or GenericProduct);
• with the Data "synthetic type" for more involved transformations, for example using lenses in the next section.

One common and simple situation is to modify the type of some fields, for example wrapping them in a newtype.

We can leverage the generic-lens library, with the two functions below.

-- Lens to a field named fd in a Generic record.
field_ :: HasField_ fd s t a b => Lens s t a b  -- from generic-lens

-- Update a value through a lens (ASetter is a specialization of Lens).
over :: ASetter s t a b -> (a -> b) -> s -> t   -- from lens or microlens

For example, here is a record type:

data R = R { myField :: Int } deriving Generic

The function over (field_ @"myField") Opaque applies the newtype constructor Opaque to the field "myField", but this actually doesn't typecheck as-is. With a bit of help from this module, we can wrap that function as follows:

onData (over (field_ @"myField") Opaque) . toData
  :: R -> Data _ _   -- type arguments hidden

The result has a type Data _ _, that from the point of view of GHC.Generics looks just like R but with the field "myField" wrapped in Opaque, as if we had defined:

data R = R { myField :: Opaque Int } deriving Generic

Example usage

We derive an instance of Show that hides the "myField" field, whatever its type.

instance Show R where
  showsPrec n = gshowsPrec n
    . onData (over (field_ @"myField") Opaque)
    . toData

show (R 3) = "R {myField = _}"

Each microsurgery consists of a type family F to modify metadata in GHC Generic representations, and two mappings (that are just coerce):

  f :: Data (Rep a) p -> Data (F (Rep a)) p
unf :: Data (F (Rep a)) p -> Data (Rep a) p

Use f with toData for generic functions that consume generic values, and unf with fromData for generic functions that produce generic values. Abstract example:

genericSerialize . f . toData
fromData . unf . genericDeserialize

These surgeries require DataKinds and TypeApplications.

Examples

{-# LANGUAGE
    DataKinds,
    TypeApplications #-}

-- Rename all fields to "foo"
renameFields @(SConst "foo")

-- Rename constructor "Bar" to "Baz", and leave all others the same
renameConstrs @(SRename '[ '("Bar", "Baz") ] SId)

Give every field a type f FieldType (where f is a parameter), to obtain a family of types with a shared structure. This "higher-kindification" technique is presented in the following blogposts:

• https://www.benjamin.pizza/posts/2017-12-15-functor-functors.html
• https://reasonablypolymorphic.com/blog/higher-kinded-data/

See also the file test/one-liner-surgery.hs in this package for an example of using one-liner and generic-lens with a synthetic type constructed with DOnFields.

Example

Derive Semigroup and Monoid for a product of Num types:

{-# LANGUAGE DeriveGeneric, DerivingVia #-}
import Data.Monoid (Sum(..))  -- Constructors must be in scope
import GHC.Generics (Generic)
import Generic.Data.Microsurgery
  ( ProductSurgery
  , OnFields
  , GenericProduct(..)  -- Constructors must be in scope
  , Surgery'(..)        --
  )

data TwoCounters = MkTwoCounters { c1 :: Int, c2 :: Int }
  deriving Generic
  deriving (Semigroup, Monoid)
    via (ProductSurgery (OnFields Sum) TwoCounters)  -- Surgery here

Example

Derive Semigroup and Monoid for a product of Num types, but using Sum for one field and Product for the other. In other words, we use the fact that Polar a below is isomorphic to the monoid (Product a, Sum a).

{-# LANGUAGE DeriveGeneric, DerivingVia #-}
import Data.Monoid (Sum(..), Product(..))  -- Constructors must be in scope
import GHC.Generics (Generic)
import Generic.Data.Microsurgery
  ( ProductSurgery
  , CopyRep
  , GenericProduct(..)  -- Constructors must be in scope
  , Surgery'(..)        --
  )

data Polar a = Exp { modulus :: a, argument :: a }
  deriving Generic
  deriving (Semigroup, Monoid)
    via (ProductSurgery (CopyRep (Product a, Sum a)) (Polar a))  -- Surgery here

That is the polar representation of a complex number:

z = modulus * exp(i * argument)

The product of complex numbers defines a monoid isomorphic to the monoid product (Product Double, Sum Double) (multiply the moduli, add the arguments).

z1 <> z2
 = z1 * z2
 = Exp (modulus z1 * modulus z2) (argument z1 + argument z2)

mempty = 1 = Exp 1 0