Portability	portable
Stability	experimental
Safe Haskell	None

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

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
}
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
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.

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.

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.

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.

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.

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 as JSON.

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.