Encoding Typeclass for Waargonaut.

This type class is responsible for creating an Encoder for the type of a , differentiated from the other possible instances of this typeclass for type a by the tag type t .

To create a Tagged Encoder for the purposes of writing an instance your self, you need only data constructor Tagged from Tagged. It has been re-exported from this module.

instance JsonEncode GWaarg Foo where
  mkEncoder = Tagged fooEncoderIWroteEarlier

Decoding Typeclass for Waargonaut

Responsible for creating a Decoder for the type a , differentiated from the other possible instances of this typeclass for type a by the tag type t .

To create a Tagged Decoder for the purposes of writing an instance your self, you need only data constructor Tagged from Tagged. It has been re-exported from this module.

instance JsonDecode GWaarg Foo where
  mkDecoder = Tagged fooDecoderIWroteEarlier

This is a provided tag that may be used for tagging the JsonEncode and JsonDecode instances. You are encouraged to make your own tags for full control of your own instances.

The options we currently have for using the Generic mechanism to handle 'newtype' values:

The configuration options for creating Generic encoder or decoder values.

Default options for Generic functionality:

• Field names are left untouched: (id)
• Newtype values are encoded as raw values: (Unwrap)

Helper function to alter record field names for encoding and decoding. Intended use is to be given the prefix you would like to have removed and then included in the Options for the typeclass you are implementing.

A common use case when encoding Haskell record types is to remove a prefix and then lower-case the first letter:

>>> trimPrefixLowerFirst "_image" "_imageHeight"
"height"

>>> trimPrefixLowerFirst "_image" "Height"
"Height"

>>> trimPrefixLowerFirst "_image" ""
""

>>> trimPrefixLowerFirst "" "_imageHeight"
"_imageHeight"

Create a Tagged Encoder for type a , tagged by t , using the given Options.

Combined with the defaultOpts this is the default implementation of JsonEncode.

Some examples:

instance JsonEncode GWaarg Image where
  mkEncoder = gEncoder defaultOpts

instance JsonEncode GWaarg Image where
  mkEncoder = gEncoder (defaultOpts { _optionsFieldName = trimPrefixLowerFirst "_image" })

Create a Tagged Decoder for type a , tagged by t , using the given Options.

Combined with the defaultOpts this is the default implementation of JsonEncode.

Some examples:

instance JsonEncode GWaarg Image where
  mkDecoder = gDecoder defaultOpts

instance JsonEncode GWaarg Image where
  mkDecoder = gDecoder (defaultOpts { _optionsFieldName = trimPrefixLowerFirst "_image" })

Create a Tagged ObjEncoder for type a , tagged by t .

This isn't compatible with the JsonEncode typeclass because it creates an ObjEncoder and for consistency reasons the JsonEncode typeclass produces Encoders.

However it lets you more easily access the Contravariant functionality that is part of the ObjEncoder type.

data Foo = Foo { fooA :: Text, fooB :: Int } deriving (Eq, Show)
deriveGeneric ''Foo

objEncFoo :: Applicative f => ObjEncoder f Foo
objEncFoo = untag $ gObjEncoder (defaultOps { _optionsFieldName = drop 3 })

NB: This function overrides the newtype options to use the FieldNameAsKey option to be consistent with the behaviour of the record encoding.

The class of representable datatypes.

The SOP approach to generic programming is based on viewing datatypes as a representation (Rep) built from the sum of products of its components. The components of a datatype are specified using the Code type family.

The isomorphism between the original Haskell datatype and its representation is witnessed by the methods of this class, from and to. So for instances of this class, the following laws should (in general) hold:

to . from === id :: a -> a
from . to === id :: Rep a -> Rep a

You typically don't define instances of this class by hand, but rather derive the class instance automatically.

Option 1: Derive via the built-in GHC-generics. For this, you need to use the DeriveGeneric extension to first derive an instance of the Generic class from module GHC.Generics. With this, you can then give an empty instance for Generic, and the default definitions will just work. The pattern looks as follows:

import qualified GHC.Generics as GHC
import Generics.SOP

...

data T = ... deriving (GHC.Generic, ...)

instance Generic T -- empty
instance HasDatatypeInfo T -- empty, if you want/need metadata

Option 2: Derive via Template Haskell. For this, you need to enable the TemplateHaskell extension. You can then use deriveGeneric from module Generics.SOP.TH to have the instance generated for you. The pattern looks as follows:

import Generics.SOP
import Generics.SOP.TH

...

data T = ...

deriveGeneric ''T -- derives HasDatatypeInfo as well

Tradeoffs: Whether to use Option 1 or 2 is mainly a matter of personal taste. The version based on Template Haskell probably has less run-time overhead.

Non-standard instances: It is possible to give Generic instances manually that deviate from the standard scheme, as long as at least

to . from === id :: a -> a

still holds.

A class of datatypes that have associated metadata.

It is possible to use the sum-of-products approach to generic programming without metadata. If you need metadata in a function, an additional constraint on this class is in order.

You typically don't define instances of this class by hand, but rather derive the class instance automatically. See the documentation of Generic for the options.