Data.Aeson.TH

aeson-0.11.2.0: Fast JSON parsing and encoding

Copyright | (c) 2011-2016 Bryan O'Sullivan (c) 2011 MailRank, Inc.
License | BSD3
Stability | experimental
Portability | portable
Safe Haskell | None
Language | Haskell2010

Data.Aeson.TH

Contents

- Encoding configuration
- FromJSON and ToJSON derivation

Description

Functions to mechanically derive `ToJSON` and `FromJSON` instances. Note that you need to enable the `TemplateHaskell` language extension in order to use this module.

An example shows how instances are generated for arbitrary data types. First we define a data type:

    data D a = Nullary
             | Unary Int
             | Product String Char a
             | Record { testOne   :: Double
                      , testTwo   :: Bool
                      , testThree :: D a
                      } deriving Eq

Next we derive the necessary instances. Note that we make use of the feature to change record field names. In this case we drop the first 4 characters of every field name. We also modify constructor names by lower-casing them:

    $(deriveJSON defaultOptions{fieldLabelModifier = drop 4, constructorTagModifier = map toLower} ''D)

Now we can use the newly created instances.

    d :: D Int
    d = Record { testOne = 3.14159
               , testTwo = True
               , testThree = Product "test" 'A' 123
               }

    >>> fromJSON (toJSON d) == Success d
    > True

This also works for data family instances, but instead of passing in the data family name (with double quotes), we pass in a data family instance constructor (with a single quote):

    data family DF a
    data instance DF Int = DF1 Int
                         | DF2 Int Int
                         deriving Eq

    $(deriveJSON defaultOptions 'DF1)
    -- Alternatively, one could pass 'DF2 instead

Please note that you can derive instances for tuples using the following syntax:

    -- FromJSON and ToJSON instances for 4-tuples.
    $(deriveJSON defaultOptions ''(,,,))

Synopsis

- data Options = Options {
  - fieldLabelModifier :: String -> String
  - constructorTagModifier :: String -> String
  - allNullaryToStringTag :: Bool
  - omitNothingFields :: Bool
  - sumEncoding :: SumEncoding
  - unwrapUnaryRecords :: Bool
  }
- data SumEncoding
  - = TaggedObject {
    - tagFieldName :: String
    - contentsFieldName :: String
    }
  - | ObjectWithSingleField
  - | TwoElemArray
- defaultOptions :: Options
- defaultTaggedObject :: SumEncoding
- deriveJSON :: Options -> Name -> Q [Dec]
- deriveToJSON :: Options -> Name -> Q [Dec]
- deriveFromJSON :: Options -> Name -> Q [Dec]
- mkToJSON :: Options -> Name -> Q Exp
- mkToEncoding :: Options -> Name -> Q Exp
- mkParseJSON :: Options -> Name -> Q Exp

# Encoding configuration

data Options #

Options that specify how to encode/decode your datatype to/from JSON.

Constructors

Options |
Fields fieldLabelModifier :: String -> String Function applied to field labels. Handy for removing common record prefixes for example. constructorTagModifier :: String -> String Function applied to constructor tags which could be handy for lower-casing them for example. allNullaryToStringTag :: Bool If `True` the constructors of a datatype, with all nullary constructors, will be encoded to just a string with the constructor tag. If `False` the encoding will always follow the `sumEncoding`. omitNothingFields :: Bool If `True` record fields with a `Nothing` value will be omitted from the resulting object. If `False` the resulting object will include those fields mapping to `null`. sumEncoding :: SumEncoding Specifies how to encode constructors of a sum datatype. unwrapUnaryRecords :: Bool Hide the field name when a record constructor has only one field, like a newtype.

Instances

Show Options # |
Methods showsPrec :: Int -> Options -> ShowS # show :: Options -> String # showList :: [Options] -> ShowS #

data SumEncoding #

Specifies how to encode constructors of a sum datatype.

Constructors

TaggedObject | A constructor will be encoded to an object with a field `tagFieldName` which specifies the constructor tag (modified by the `constructorTagModifier`). If the constructor is a record the encoded record fields will be unpacked into this object. So make sure that your record doesn't have a field with the same label as the `tagFieldName`. Otherwise the tag gets overwritten by the encoded value of that field! If the constructor is not a record the encoded constructor contents will be stored under the `contentsFieldName` field.
Fields tagFieldName :: String contentsFieldName :: String
ObjectWithSingleField | A constructor will be encoded to an object with a single field named after the constructor tag (modified by the `constructorTagModifier`) which maps to the encoded contents of the constructor.
TwoElemArray | A constructor will be encoded to a 2-element array where the first element is the tag of the constructor (modified by the `constructorTagModifier`) and the second element the encoded contents of the constructor.

Instances

Eq SumEncoding # |
Methods (==) :: SumEncoding -> SumEncoding -> Bool # (/=) :: SumEncoding -> SumEncoding -> Bool #
Show SumEncoding # |
Methods showsPrec :: Int -> SumEncoding -> ShowS # show :: SumEncoding -> String # showList :: [SumEncoding] -> ShowS #

defaultOptions :: Options #

Default encoding `Options`:

    Options
    { fieldLabelModifier      = id
    , constructorTagModifier  = id
    , allNullaryToStringTag   = True
    , omitNothingFields       = False
    , sumEncoding             = defaultTaggedObject
    , unwrapUnaryRecords      = False
    }

defaultTaggedObject :: SumEncoding #

Default `TaggedObject` `SumEncoding` options:

    defaultTaggedObject = TaggedObject
                          { tagFieldName      = "tag"
                          , contentsFieldName = "contents"
                          }

# FromJSON and ToJSON derivation

deriveJSON #

Arguments

:: Options | Encoding options.
-> Name | Name of the type for which to generate `ToJSON` and `FromJSON` instances.
-> Q [Dec] |

Generates both `ToJSON` and `FromJSON` instance declarations for the given data type or data family instance constructor.

This is a convienience function which is equivalent to calling both `deriveToJSON` and `deriveFromJSON`.

deriveToJSON #

Arguments

:: Options | Encoding options.
-> Name | Name of the type for which to generate a `ToJSON` instance declaration.
-> Q [Dec] |

Generates a `ToJSON` instance declaration for the given data type or data family instance constructor.

deriveFromJSON #

Arguments

:: Options | Encoding options.
-> Name | Name of the type for which to generate a `FromJSON` instance declaration.
-> Q [Dec] |

Generates a `FromJSON` instance declaration for the given data type or data family instance constructor.

mkToJSON #

Arguments

:: Options | Encoding options.
-> Name | Name of the type to encode.
-> Q Exp |

Generates a lambda expression which encodes the given data type or data family instance constructor as a `Value`.

mkToEncoding #

Arguments

:: Options | Encoding options.
-> Name | Name of the type to encode.
-> Q Exp |

Generates a lambda expression which encodes the given data type or data family instance constructor as a JSON string.

mkParseJSON #

Arguments

:: Options | Encoding options.
-> Name | Name of the encoded type.
-> Q Exp |

Generates a lambda expression which parses the JSON encoding of the given data type or data family instance constructor.