aeson-0.10.0.0: Fast JSON parsing and encoding

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

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 Source

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 Source |

data SumEncoding Source

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 Source |
Show SumEncoding Source |

defaultOptions :: Options Source

Default encoding `Options`:

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

defaultTaggedObject :: SumEncoding Source

Default `TaggedObject` `SumEncoding` options:

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

# FromJSON and ToJSON derivation

deriveJSON Source

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 Source

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 Source

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 Source

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 Source

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 Source

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.