Data.API.Tools

This module provides an interface for generating TH declarations from an API. To use it, splice in a call to generate followed by one or more calls to generateAPITools, like so:

$(generate myAPI)
$(generateAPITools [enumTool, jsonTool', quickCheckTool] myAPI)

If you wish to override any of the instances generated by the tools, you can do so by writing instance declarations after the call to generate but before the call to generateAPITools.

Documentation

generate :: API -> Q [Dec]

Generate the datatypes corresponding to an API.

generateAPITools :: API -> [APITool] -> Q [Dec]

Apply a list of tools to an API, generating TH declarations. See the individual tool descriptions for details. Note that generate must be called first, and some tools have dependencies, which must be included in the same or a preceding call to generateAPITools.

Tool settings

generateWith :: ToolSettings -> API -> Q [Dec]

Generate the datatypes corresponding to an API, allowing the ToolSettings to be overriden.

generateAPIToolsWith :: ToolSettings -> API -> [APITool] -> Q [Dec]

Apply a list of tools to an API, generating TH declarations. This form allows the ToolSettings to be overridden.

data ToolSettings

Settings to control the behaviour of API tools. This record may be extended in the future, so you should construct a value by overriding individual fields of defaultToolSettings.

defaultToolSettings :: ToolSettings

Default settings designed to be overridden.

warnOnOmittedInstance :: ToolSettings -> Bool

Generate a warning when an instance declaration is omitted because it already exists

newtypeSmartConstructors :: ToolSettings -> Bool

Rename the constructors of filtered newtypes and generate smart constructors that enforce the invariants

Individual tools

enumTool :: APITool

Tool to generate the maps between enumerations and Text strings named by text_enum_nm and map_enum_nm.

exampleTool :: APITool

Tool to generate Example instances for types generated by datatypesTool. This depends on quickCheckTool.

deepSeqTool :: APITool

Tool to generate NFData instances for generated types.

jsonTool :: APITool

Tool to generate ToJSON and FromJSONWithErrs instances for types generated by datatypesTool. This depends on enumTool. For historical reasons this does not generate FromJSON instances; you probably want to use jsonTool' instead.

jsonTool' :: APITool

Tool to generate ToJSON, FromJSON and FromJSONWithErrs instances for types generated by datatypesTool. This depends on enumTool. Note that generated FromJSON and FromJSONWithErrs instances will always agree on the decoding of a value, but that the FromJSONWithErrs instances for basic types are more liberal than FromJSON.

cborTool :: APITool

Tool to generate Serialise instances for types generated by datatypesTool. This depends on enumTool.

jsonTestsTool :: Name -> APITool

Tool to generate a list of JSON round-trip tests of type [(String, Property)] with the given name. This depends on jsonTool and quickCheckTool.

cborTestsTool :: Name -> APITool

Tool to generate a list of CBOR round-trip tests of type [(String, Property)] with the given name. This depends on cborTool and quickCheckTool.

cborToJSONTestsTool :: Name -> Name -> APITool

Tool to generate a list of CBOR-to-JSON conversion tests of type [(String, Property)]. The first name must be the API being tested, and the second should be the name of the declaration to be produced. This depends on cborTool, jsonTool and quickCheckTool.

jsonToCBORTestsTool :: Name -> Name -> APITool

Tool to generate a list of JSON-to-CBOR conversion tests of type [(String, Property)]. The first name must be the API being tested, and the second should be the name of the declaration to be produced. This depends on cborTool, jsonTool and quickCheckTool.

jsonGenericValueTestsTool :: Name -> Name -> APITool

Tool to generate a list of tests that the Value generic representation agrees with the type-specific JSON representation.

cborGenericValueTestsTool :: Name -> Name -> APITool

Tool to generate a list of tests that the Value generic representation agrees with the type-specific CBOR representation.

lensTool :: APITool

Tool to make lenses for fields in generated types.

quickCheckTool :: APITool

Tool to generate Arbitrary instances for generated types.

safeCopyTool :: APITool

Tool to derive SafeCopy instances for generated types. At present, this derives only base version instances.

samplesTool :: Name -> APITool

Generate a list of (type name, sample generator) pairs corresponding to each type in the API, with samples encoded as JSON. This depends on the Example instances generated by exampleTool. It generates something like this:

samples :: [(String, Gen Value)]
samples = [("Foo", fmap toJSON (example :: Gen Foo)), ... ]