git.iko.soy/typeable/servant
on master help sign in
Merge branch 'jkarni/qq-docs' into new-impl
commit52c24c8b3532507de36b183d76479bc65498982a authorAlp Mestanogullari <alpmestan@gmail.com> dateTue 25 Nov 2014, 17:39 (12 years ago) parent5435dd4ae8cca6
7 files changed+74−8
compare with master
unifiedsplit
servant.cabal+1−1 src/Servant.hs+2−2 src/Servant/API.hs+2−2 src/Servant/Utils/ApiQuasiQuoting.hs → src/Servant/QQ.hs+40−1 src/Servant/Utils/Links.hs+27 test/Servant/Utils/ApiQuasiQuotingSpec.hs → test/Servant/QQSpec.hs+1−1 test/Servant/Utils/LinksSpec.hs+1−1
servant.cabal+1−1
@@ -31,8 +31,8 @@ library
3131 Servant.Common.Req
3232 Servant.Common.Text
3333 Servant.Docs
34+ Servant.QQ
3435 Servant.Server
35− Servant.Utils.ApiQuasiQuoting
3636 Servant.Utils.Links
3737 Servant.Utils.StaticFiles
3838 build-depends:
src/Servant.hs+2−2
@@ -12,7 +12,7 @@ module Servant (
1212 -- | Using your types in request paths and query string parameters
1313 module Servant.Common.Text,
1414 -- | Utilities on top of the servant core
15− module Servant.Utils.ApiQuasiQuoting,
15+ module Servant.QQ,
1616 module Servant.Utils.Links,
1717 module Servant.Utils.StaticFiles,
1818 -- | Useful re-exports
@@ -25,6 +25,6 @@ import Servant.Client
2525import Servant.Common.Text
2626import Servant.Docs
2727import Servant.Server
28−import Servant.Utils.ApiQuasiQuoting
28+import Servant.QQ
2929import Servant.Utils.Links
3030import Servant.Utils.StaticFiles
src/Servant/API.hs+2−2
@@ -31,7 +31,7 @@ module Servant.API (
3131
3232 -- * Utilities
3333 -- | QuasiQuotes for endpoints
34− module Servant.Utils.ApiQuasiQuoting,
34+ module Servant.QQ,
3535 -- | Type-safe internal URLs
3636 module Servant.Utils.Links,
3737 ) where
@@ -46,6 +46,6 @@ import Servant.API.QueryParam
4646import Servant.API.Raw
4747import Servant.API.ReqBody
4848import Servant.API.Sub
49−import Servant.Utils.ApiQuasiQuoting (sitemap)
49+import Servant.QQ (sitemap)
5050import Servant.Utils.Links (mkLink)
5151import Servant.Utils.StaticFiles
src/Servant/Utils/ApiQuasiQuoting.hs → src/Servant/QQ.hsrenamed+40−1
@@ -5,7 +5,28 @@
55{-# LANGUAGE ScopedTypeVariables #-}
66{-# LANGUAGE TemplateHaskell #-}
77{-# OPTIONS_GHC -fno-warn-unused-do-bind #-}
8−module Servant.Utils.ApiQuasiQuoting where
8+-- | QuasiQuoting utilities for API types.
9+--
10+-- 'sitemap' allows you to write your type in a very natural way:
11+--
12+-- @
13+-- [sitemap|
14+-- PUT hello String -> ()
15+-- POST hello/p:Int String -> ()
16+-- GET hello/?name:String Int
17+-- |]
18+-- @
19+--
20+-- Will generate:
21+--
22+-- @
23+-- "hello" :> ReqBody String :> Put ()
24+-- :\<|> "hello" :> Capture "p" Int :> ReqBody String :> Post ()
25+-- :\<|> "hello" :> QueryParam "name" String :> Get Int
26+-- @
27+--
28+-- Note the @/@ before a @QueryParam@!
29+module Servant.QQ where
930
1031import Control.Monad (void)
1132import Control.Applicative hiding (many, (<|>), optional)
@@ -23,6 +44,11 @@ import Servant.API.ReqBody
2344import Servant.API.Sub
2445import Servant.API.Alternative
2546
47+-- | Finally-tagless encoding for our DSL.
48+-- Keeping 'repr'' and 'repr' distinct when writing functions with an
49+-- @ExpSYM@ context ensures certain invariants (for instance, that there is
50+-- only one of 'get', 'post', 'put', and 'delete' in a value), but
51+-- sometimes requires a little more work.
2652class ExpSYM repr' repr | repr -> repr', repr' -> repr where
2753 lit :: String -> repr' -> repr
2854 capture :: String -> String -> repr -> repr
@@ -148,6 +174,19 @@ parseAll = do
148174 where union :: Type -> Type -> Type
149175 union a = AppT (AppT (ConT ''(:<|>)) a)
150176
177+-- | The sitemap QuasiQuoter.
178+--
179+-- * @.../<var>:<type>/...@ becomes a capture
180+-- * @.../?<var>:<type>@ becomes a query parameter
181+-- * @<method> ... <typ>@ becomes a method returning @<typ>@
182+-- * @<method> ... <typ1> -> <typ2>@ becomes a method with request
183+-- body of @<typ1>@ and returning @<typ2>@
184+--
185+-- Comments are allowed, and have the standard Haskell format
186+--
187+-- * @--@ for inline
188+-- * @{- ... -}@ for block
189+--
151190sitemap :: QuasiQuoter
152191sitemap = QuasiQuoter { quoteExp = undefined
153192 , quotePat = undefined
src/Servant/Utils/Links.hs+27
@@ -6,6 +6,33 @@
66{-# LANGUAGE FunctionalDependencies #-}
77{-# LANGUAGE ScopedTypeVariables #-}
88{-# LANGUAGE UndecidableInstances #-}
9+-- | Type safe internal links.
10+--
11+-- Provides the function 'mkLink':
12+--
13+-- @
14+-- type API = Proxy ("hello" :> Get Int
15+-- :<|> "bye" :> QueryParam "name" String :> Post Bool)
16+--
17+-- api :: API
18+-- api = proxy
19+--
20+-- link1 :: Proxy ("hello" :> Get Int)
21+-- link1 = proxy
22+--
23+-- link2 :: Proxy ("hello" :> Delete)
24+-- link2 = proxy
25+--
26+-- mkLink link1 API -- typechecks, returns 'Link "/hello"'
27+--
28+-- mkLink link2 API -- doesn't typecheck
29+-- @
30+--
31+-- That is, 'mkLink' takes two arguments, a link proxy and a sitemap, and
32+-- returns a 'Link', but only typechecks if the link proxy is a valid link,
33+-- and part of the sitemap.
34+--
35+-- __N.B.:__ 'mkLink' assumes a capture matches any string (without slashes).
936module Servant.Utils.Links where
1037
1138import Data.Proxy
test/Servant/Utils/ApiQuasiQuotingSpec.hs → test/Servant/QQSpec.hsrenamed+1−1
@@ -7,7 +7,7 @@
77{-# LANGUAGE TypeFamilies #-}
88{-# LANGUAGE TypeOperators #-}
99{-# LANGUAGE UndecidableInstances #-}
10−module Servant.Utils.ApiQuasiQuotingSpec where
10+module Servant.QQSpec where
1111
1212import Test.Hspec
1313
test/Servant/Utils/LinksSpec.hs+1−1
@@ -6,7 +6,7 @@ module Servant.Utils.LinksSpec where
66import Test.Hspec
77
88import Servant.API
9−import Servant.Utils.ApiQuasiQuotingSpec ( (~>) )
9+import Servant.QQSpec ( (~>) )
1010import Servant.Utils.Links (IsElem, IsLink)
1111
1212type TestApi =