api-tools-0.4: DSL for generating API boilerplate and docs

Safe HaskellNone




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

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.

defaultToolSettings :: ToolSettingsSource

Default settings designed to be overridden.

warnOnOmittedInstance :: ToolSettings -> BoolSource

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

Individual tools

enumTool :: APIToolSource

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

exampleTool :: APIToolSource

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

jsonTool :: APIToolSource

Tool to generate ToJSON and FromJSONWithErrs instances for types generated by datatypesTool. This depends on enumTool.

jsonTestsTool :: Name -> APIToolSource

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

lensTool :: APIToolSource

Tool to make lenses for fields in generated types.

quickCheckTool :: APIToolSource

Tool to generate Arbitrary instances for generated types.

safeCopyTool :: APIToolSource

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

samplesTool :: Name -> APIToolSource

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