Moduleaeson-2.2.3.0Haskell2010

Data.Aeson.TH

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

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 ''(,,,))

If you derive ToJSON for a type that has no constructors, the splice will require enabling EmptyCase to compile.

2 types
29 values

Packageaeson-2.2.3.0
Exports31
LanguageHaskell2010
LicenceBSD-3-Clause
SourceTH.hs

Encoding configuration

13 declarations

datadata Options

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

Options can be set using record syntax on defaultOptions with the fields below.

Instances1Show

Show OptionsDefined in aeson-2.2.3.0 · Data.Aeson.Types.Internal

valuefieldLabelModifier :: Options -> String -> String

Function applied to field labels. Handy for removing common record prefixes for example.

valueconstructorTagModifier :: Options -> String -> String

Function applied to constructor tags which could be handy for lower-casing them for example.

valueallNullaryToStringTag :: Options -> 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.

valueomitNothingFields :: Options -> 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.

In aeson-2.2 this flag is generalised to omit all values with omitField x = True. If False, the resulting object will include those fields encoded as specified.

Note that this does not affect parsing: Maybe fields are optional regardless of the value of omitNothingFields. allowOmittedFieds controls parsing behavior.

valueallowOmittedFields :: Options -> Bool

If True, missing fields of a record will be filled with omittedField values (if they are Just). If False, all fields will required to present in the record object.

valuesumEncoding :: Options -> SumEncoding

Specifies how to encode constructors of a sum datatype.

valueunwrapUnaryRecords :: Options -> Bool

Hide the field name when a record constructor has only one field, like a newtype.

valuetagSingleConstructors :: Options -> Bool

Encode types with a single constructor as sums, so that allNullaryToStringTag and sumEncoding apply.

valuerejectUnknownFields :: Options -> Bool

Applies only to Data.Aeson.FromJSON instances. If a field appears in the parsed object map, but does not appear in the target object, parsing will fail, with an error message indicating which fields were unknown.

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

Instances2Eq, Show

Eq SumEncodingDefined in aeson-2.2.3.0 · Data.Aeson.Types.Internal
Show SumEncodingDefined in aeson-2.2.3.0 · Data.Aeson.Types.Internal

valuedefaultOptions :: Options

Default encoding Options:

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

valuedefaultTaggedObject :: SumEncoding

Default TaggedObject SumEncoding options:

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

FromJSON and ToJSON derivation

18 declarations

valuederiveJSON

:: 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 convenience function which is equivalent to calling both deriveToJSON and deriveFromJSON.

valuederiveJSON1

:: 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 convenience function which is equivalent to calling both deriveToJSON1 and deriveFromJSON1.

valuederiveJSON2

:: 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 convenience function which is equivalent to calling both deriveToJSON2 and deriveFromJSON2.

valuederiveToJSON

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

valuederiveToJSON1

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

valuederiveToJSON2

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

valuederiveFromJSON

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

valuederiveFromJSON1

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

valuederiveFromJSON2

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

valuemkToJSON

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

valuemkLiftToJSON

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

valuemkLiftToJSON2

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

valuemkToEncoding

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

valuemkLiftToEncoding

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

valuemkLiftToEncoding2

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

valuemkParseJSON

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

valuemkLiftParseJSON

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

valuemkLiftParseJSON2

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