diff --git a/api-tools.cabal b/api-tools.cabal --- a/api-tools.cabal +++ b/api-tools.cabal @@ -1,5 +1,5 @@ Name: api-tools -Version: 0.5 +Version: 0.5.1 Synopsis: DSL for generating API boilerplate and docs Description: api-tools provides a compact DSL for describing an API. It uses Template Haskell to generate the @@ -25,7 +25,7 @@ Source-Repository this Type: git Location: git://github.com/iconnect/api-tools.git - Tag: 0.5 + Tag: 0.5.1 Library Hs-Source-Dirs: src @@ -41,9 +41,11 @@ Data.API.NormalForm Data.API.Parse Data.API.PP + Data.API.TH Data.API.Tools Data.API.Tools.Combinators Data.API.Tools.Datatypes + Data.API.Tools.DeepSeq Data.API.Tools.Enum Data.API.Tools.Example Data.API.Tools.JSON @@ -62,7 +64,6 @@ Data.API.Doc.Dir Data.API.Doc.Types Data.API.Scan - Data.API.TH Build-depends: Cabal >= 1.4 && < 2 , @@ -76,6 +77,7 @@ bytestring >= 0.9 && < 0.11 , case-insensitive >= 1.0 && < 1.3 , containers >= 0.5 && < 0.6 , + deepseq >= 1.1 && < 1.4 , lens >= 3.8.7 && < 4.4 , old-locale >= 1.0.0.4 && < 1.1 , regex-compat-tdfa >= 0.95.1 && < 0.96 , diff --git a/changelog b/changelog --- a/changelog +++ b/changelog @@ -1,5 +1,10 @@ -*-change-log-*- +0.5.1 Adam Gundry November 2014 + * Tool to generate NFData instances (added dependency on deepseq) + * Expose internal module with TH utility functions + * Documentation tweaks + 0.5 Adam Gundry October 2014 * Tool to generate Aeson FromJSON instances, as well as FromJSONWithErrs * Add more TypeKind alternatives for custom migrations diff --git a/src/Data/API/TH.hs b/src/Data/API/TH.hs --- a/src/Data/API/TH.hs +++ b/src/Data/API/TH.hs @@ -1,5 +1,8 @@ {-# LANGUAGE TemplateHaskell #-} +-- | This module defines some utilities for working with Template +-- Haskell, which may be useful for defining 'Tool's, but should be +-- considered internal implementation details of this package. module Data.API.TH ( applicativeE , optionalInstanceD @@ -17,8 +20,9 @@ -- | Construct an idiomatic expression (an expression in an -- Applicative context), i.e. --- app ke [] => ke --- app ke [e1,e2,...,en] => ke <$> e1 <*> e2 ... <*> en +-- +-- > app ke [] = ke +-- > app ke [e1,e2,...,en] = ke <$> e1 <*> e2 ... <*> en applicativeE :: ExpQ -> [ExpQ] -> ExpQ applicativeE ke es0 = case es0 of diff --git a/src/Data/API/Tools.hs b/src/Data/API/Tools.hs --- a/src/Data/API/Tools.hs +++ b/src/Data/API/Tools.hs @@ -24,6 +24,7 @@ -- * Individual tools , enumTool , exampleTool + , deepSeqTool , jsonTool , jsonTool' , jsonTestsTool @@ -35,6 +36,7 @@ import Data.API.Tools.Combinators import Data.API.Tools.Datatypes +import Data.API.Tools.DeepSeq import Data.API.Tools.Enum import Data.API.Tools.Example import Data.API.Tools.JSON diff --git a/src/Data/API/Tools/DeepSeq.hs b/src/Data/API/Tools/DeepSeq.hs new file mode 100644 --- /dev/null +++ b/src/Data/API/Tools/DeepSeq.hs @@ -0,0 +1,49 @@ +{-# LANGUAGE QuasiQuotes #-} +{-# LANGUAGE TemplateHaskell #-} +module Data.API.Tools.DeepSeq + ( deepSeqTool + ) where + +import Data.API.TH +import Data.API.Tools.Combinators +import Data.API.Tools.Datatypes +import Data.API.Types + +import Control.DeepSeq +import Data.Monoid +import Language.Haskell.TH + + +-- | Tool to generate 'NFData' instances for generated types. +deepSeqTool :: APITool +deepSeqTool = apiNodeTool $ apiSpecTool gen_sn gen_sr gen_su gen_se mempty + + +gen_sn :: Tool (APINode, SpecNewtype) +gen_sn = mkTool $ \ ts (an, _) -> optionalInstanceD ts ''NFData [nodeRepT an] + [simpleD 'rnf (bdy an)] + where + bdy an = [e| \ x -> rnf ($(newtypeProjectionE an) x) |] + +gen_sr :: Tool (APINode, SpecRecord) +gen_sr = mkTool $ \ ts (an, sr) -> do + x <- newName "x" + optionalInstanceD ts ''NFData [nodeRepT an] [simpleD 'rnf (bdy an sr x)] + where + bdy an sr x = lamE [varP x] $ foldr f [e|()|] (srFields sr) + where + f (fn,_) r = [e| $(nodeFieldE an fn) $(varE x) `seq` $r |] + +gen_su :: Tool (APINode, SpecUnion) +gen_su = mkTool $ \ ts (an, su) -> do + x <- newName "x" + y <- newName "y" + optionalInstanceD ts ''NFData [nodeRepT an] [simpleD 'rnf (bdy an su x y)] + where + bdy an su x y = lamE [varP x] $ caseE (varE x) cs + where + cs = map f (suFields su) + f (fn,_) = match (nodeAltConP an fn [varP y]) (normalB [e|rnf $(varE y)|]) [] + +gen_se :: Tool (APINode, SpecEnum) +gen_se = mkTool $ \ ts (an, _) -> optionalInstanceD ts ''NFData [nodeRepT an] [] diff --git a/src/Data/API/Tutorial.hs b/src/Data/API/Tutorial.hs --- a/src/Data/API/Tutorial.hs +++ b/src/Data/API/Tutorial.hs @@ -124,7 +124,7 @@ > type MyFlag = Bool The Template Haskell staging restriction means that @example@ must be -defined in one module and imported into another to call @generate@. +defined in one module and imported into another to call 'generate'. -} @@ -138,11 +138,27 @@ will define: -* @_text_MyEnum :: MyEnum -> 'Text'@ and @_map_MyEnum :: Map 'Text' MyEnum@, - for converting between enumerations and text representations +* @_text_MyEnum :: MyEnum -> 'Text'@ for converting an enumeration to + its textual representation; +* @_map_MyEnum :: Map 'Text' MyEnum@ for converting a textual + representation back to an enumeration; and + * 'ToJSON', 'FromJSONWithErrs' and 'Arbitrary' instances for all the - generated types + generated types. + +Note that 'generate' must be used to create the datatypes first, +otherwise 'generateAPITools' will result in scope errors. Moreover, +certain tools have dependencies, as described in the documentation for +each tool in "Data.API.Tools". Dependent tools must be generated in +the same call to 'generateAPITools' or a previous call; if they are +missing unpleasant compilation errors will occur. For example, +omitting 'enumTool' in the above to give + +> $(generateAPITools [jsonTool, quickCheckTool] example) + +will lead to errors about undefined symbols @_text_MyEnum@ and +@_map_MyEnum@ in the generated code. -}