Safe Haskell	None
Language	Haskell2010

Data.API.Tools

Contents

Tool settings
Individual tools

Description

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.

Synopsis

generate :: API -> Q [Dec]
generateAPITools :: API -> [APITool] -> Q [Dec]
generateWith :: ToolSettings -> API -> Q [Dec]
generateAPIToolsWith :: ToolSettings -> API -> [APITool] -> Q [Dec]
data ToolSettings
defaultToolSettings :: ToolSettings
warnOnOmittedInstance :: ToolSettings -> Bool
newtypeSmartConstructors :: ToolSettings -> Bool
enumTool :: APITool
exampleTool :: APITool
deepSeqTool :: APITool
jsonTool :: APITool
jsonTool' :: APITool
cborTool :: APITool
jsonTestsTool :: Name -> APITool
cborTestsTool :: Name -> APITool
cborToJSONTestsTool :: Name -> Name -> APITool
jsonToCBORTestsTool :: Name -> Name -> APITool
jsonGenericValueTestsTool :: Name -> Name -> APITool
cborGenericValueTestsTool :: Name -> Name -> APITool
lensTool :: APITool
quickCheckTool :: APITool
safeCopyTool :: APITool
samplesTool :: Name -> APITool

Documentation

generate :: API -> Q [Dec] Source #

Generate the datatypes corresponding to an API.

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

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

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

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

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

data ToolSettings Source #

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

Default settings designed to be overridden.

warnOnOmittedInstance :: ToolSettings -> Bool Source #

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

newtypeSmartConstructors :: ToolSettings -> Bool Source #

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

Individual tools

enumTool :: APITool Source #

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

exampleTool :: APITool Source #

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

deepSeqTool :: APITool Source #

Tool to generate NFData instances for generated types.

jsonTool :: APITool Source #

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

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

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

jsonTestsTool :: Name -> APITool Source #

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

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

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

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

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

cborGenericValueTestsTool :: Name -> Name -> APITool Source #

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

lensTool :: APITool Source #

Tool to make lenses for fields in generated types.

quickCheckTool :: APITool Source #

Tool to generate Arbitrary instances for generated types.

safeCopyTool :: APITool Source #

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

samplesTool :: Name -> APITool Source #

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)), ... ]