This module contains the types and functions that power the Generic functions for Waargonaut. Code that writes the code so you don't have to.

Although creating your Decoders and Encoders explicitly is the preferred way of utilising Waargonaut. The Generic mechanism within Haskell provides immense opportunity to reduce or eliminate the need to write code. Given the mechanical nature of JSON this a benefit that cannot be ignored.

There are two typeclasses provided, JsonEncode and JsonDecode. Each with a single function that will generate a Encoder or Decoder for that type. Normally, typeclasses such as these are only parameterised over the type that is to be encoded/decoded. Which is acceptable if there is only ever a single possible way to encode or decode a value of that type. However this is rarely the case, even with respect to strings or numbers.

To account for this, the JsonEncode and JsonDecode typeclasses require an additional type parameter t . This parameter allows you to differentiate between the alternative ways of encoding or decoding a single type a . This parameter is attached to the Encoder or Decoder using the Tagged newtype. Allowing the type system to help you keep track of them.

A quick example on how to use the Waargonaut Generic functionality. We will use the following type and let GHC and Generic write our Encoder and Decoder for us.

data Image = Image
  { _imageWidth    :: Int
  , _imageHeight   :: Int
  , _imageTitle    :: Text
  , _imageAnimated :: Bool
  , _imageIDs      :: [Int]
  }
  deriving (Eq, Show)

Ensure we have the required imports and language options:

{-# LANGUAGE DeriveGeneric #-}
import qualified GHC.Generic as GHC
import Waargonaut.Generic (Generic, HasDatatypeInfo, JsonEncode, JsonDecode, GWaarg)

Update our data type 'deriving' to have GHC to do the heavy lifting:

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

Because Waargonaut uses the 'generics-sop' package to make the Generic functions easier to write and maintain. We need two more instances, note that we don't have to write these either. We can leave these empty and the default implementations, courtesy of Generic, will handle it for us.

instance HasDatatypeInfo Image
instance Generic Image

Now we can define our JsonEncode and JsonDecode instances. We need to provide the t parameter. Assume we have no special requirements, so we can use the GWaarg tag.

instance JsonEncode GWaarg Image
instance JsonDecode GWaarg Image

That's it! We can now use mkEncoder and mkDecoder to write the code for our Image type. These will be tagged with our GWaarg phantom type parameter:

mkEncoder :: Applicative f => Tagged GWaarg (Encoder f Image)
mkDecoder :: Monad f       => Tagged GWaarg (Decoder f Image)

The encoding and decoding "runner" functions will require that you remove the tag. You can use the untag function for this. The next section will discuss the Tagged type.

There is Template Haskell available that can write all of the Generic deriving for you, see the 'Generics.SOP.TH' module in the 'generics-sop' package for more. Given how little boilerplate code is required and that the Template Haskell extension enforces a strict ordering of code within the file. It is not the recommended solution. But I'm not your supervisor, I'm just a library.

The Tagged type comes from the 'tagged' package. It is a 'newtype' that provides a phantom type parameter. As well as having a several useful typeclass instances and helpful functions already written for us.

When dealing with the Tagged Encoders and Decoders there are two functions that are particularly useful; untag, and proxy.

The untag function removes the tag from the inner type:

untag :: -- forall k (s :: k) b. Tagged s b -> b

When used with one of the Tagged Generic functions:

let e = mkEncoder :: Applicative f => Tagged GWaarg (Encoder f Image)

untag e :: Applicative f => Encoder f Image

The other function proxy, allows you to use mkEncoder or mkDecoder with the desired t parameter and then immediately remove the tag. This function requires the use of some proxy that carries the same t of your instance:

proxy :: Tagged s a -> proxy s -> a

One way to utilise this function is in combination with Proxy from base:

(proxy mkDecoder (Proxy :: Proxy GWaarg)) :: Monad f => Decoder f Image

This lets you skip the untag step but without losing the safety of the Tagged phantom type.

All of the techniques described above are explicit and will work in all versions of GHC that Waargonaut supports. Should you be running a GHC that is version 8.0.1 or later, then you have access to a language extension called TypeApplications.

This extension allows you to avoid much of the explicit type annotations described in Tagged section of Waargonaut.Generic. For example the proxy function may be utilised like so:

(proxy mkDecoder (Proxy :: Proxy GWaarg)) :: Monad f => Decoder f Image

Becomes:

(proxy mkDecoder @GWaarg) :: Monad f => Decoder f Image

You can also use the TypeApplications directly on the mkEncoder or mkDecoder function:

mkEncoder GWaarg :: Applicative f => Tagged GWaarg (Encoder f Image)
mkDecoder GWaarg :: Monad f       => Tagged GWaarg (Decoder f Image)