Data.Aeson.TH

aeson-1.1.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
    }
  - | UntaggedValue
  - | ObjectWithSingleField
  - | TwoElemArray
- defaultOptions :: Options
- defaultTaggedObject :: SumEncoding
- deriveJSON :: Options -> Name -> Q [Dec]
- deriveJSON1 :: Options -> Name -> Q [Dec]
- deriveJSON2 :: Options -> Name -> Q [Dec]
- deriveToJSON :: Options -> Name -> Q [Dec]
- deriveToJSON1 :: Options -> Name -> Q [Dec]
- deriveToJSON2 :: Options -> Name -> Q [Dec]
- deriveFromJSON :: Options -> Name -> Q [Dec]
- deriveFromJSON1 :: Options -> Name -> Q [Dec]
- deriveFromJSON2 :: Options -> Name -> Q [Dec]
- mkToJSON :: Options -> Name -> Q Exp
- mkLiftToJSON :: Options -> Name -> Q Exp
- mkLiftToJSON2 :: Options -> Name -> Q Exp
- mkToEncoding :: Options -> Name -> Q Exp
- mkLiftToEncoding :: Options -> Name -> Q Exp
- mkLiftToEncoding2 :: Options -> Name -> Q Exp
- mkParseJSON :: Options -> Name -> Q Exp
- mkLiftParseJSON :: Options -> Name -> Q Exp
- mkLiftParseJSON2 :: 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
UntaggedValue | Constructor names won't be encoded. Instead only the contents of the constructor will be encoded as if the type had a single constructor. JSON encodings have to be disjoint for decoding to work properly. When decoding, constructors are tried in the order of definition. If some encodings overlap, the first one defined will succeed. Note: Nullary constructors are encoded as strings (using `constructorTagModifier`). Having a nullary constructor alongside a single field constructor that encodes to a string leads to ambiguity. Note: Only the last error is kept when decoding, so in the case of malformed JSON, only an error for the last constructor will be reported.
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`.

deriveJSON1 #

Arguments

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

Generates both `ToJSON1` and `FromJSON1` instance declarations for the given data type or data family instance constructor.

This is a convienience function which is equivalent to calling both `deriveToJSON1` and `deriveFromJSON1`.

deriveJSON2 #

Arguments

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

Generates both `ToJSON2` and `FromJSON2` instance declarations for the given data type or data family instance constructor.

This is a convienience function which is equivalent to calling both `deriveToJSON2` and `deriveFromJSON2`.

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.

deriveToJSON1 #

Arguments

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

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

deriveToJSON2 #

Arguments

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

Generates a `ToJSON2` 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.

deriveFromJSON1 #

Arguments

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

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

deriveFromJSON2 #

Arguments

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

Generates a `FromJSON2` 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`.

mkLiftToJSON #

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` by using the given encoding function on occurrences of the last type parameter.

mkLiftToJSON2 #

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` by using the given encoding functions on occurrences of the last two type parameters.

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.

mkLiftToEncoding #

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 by using the given encoding function on occurrences of the last type parameter.

mkLiftToEncoding2 #

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 by using the given encoding functions on occurrences of the last two type parameters.

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.

mkLiftParseJSON #

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 by using the given parsing function on occurrences of the last type parameter.

mkLiftParseJSON2 #

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 by using the given parsing functions on occurrences of the last two type parameters.