Safe Haskell | None |
---|---|
Language | Haskell2010 |
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
.
- 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
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
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.
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.
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
.
Tool to generate Serialise
instances for types generated by
datatypesTool
. This depends on enumTool
.
jsonTestsTool :: Name -> APITool Source #
cborTestsTool :: Name -> APITool Source #
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.
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)), ... ]