git.iko.soy/typeable/servant
on master help sign in
More haddocks for Capture
e9ebb0fAlp Mestanogullari
src/Servant/API/Alternative.hs+1−1
compare with master
unifiedsplit
@@ -58,7 +58,7 @@ instance (HasClient a, HasClient b) => HasClient (a :<|> b) where
58 clientWithRoute (Proxy :: Proxy a) req :<|>
58 clientWithRoute (Proxy :: Proxy a) req :<|>
59 clientWithRoute (Proxy :: Proxy b) req
59 clientWithRoute (Proxy :: Proxy b) req
60
60
61−-- | The generated docs for @a ':<|>' b@ just append the docs
61+-- | The generated docs for @a ':<|>' b@ just appends the docs
62-- for @a@ with the docs for @b@.
62-- for @a@ with the docs for @b@.
63instance (HasDocs layout1, HasDocs layout2)
63instance (HasDocs layout1, HasDocs layout2)
64 => HasDocs (layout1 :<|> layout2) where
64 => HasDocs (layout1 :<|> layout2) where
src/Servant/API/Capture.hs+45−2
@@ -4,7 +4,7 @@
4{-# LANGUAGE FlexibleContexts #-}
4{-# LANGUAGE FlexibleContexts #-}
5{-# LANGUAGE FlexibleInstances #-}
5{-# LANGUAGE FlexibleInstances #-}
6{-# LANGUAGE ScopedTypeVariables #-}
6{-# LANGUAGE ScopedTypeVariables #-}
7−module Servant.API.Capture where
7+module Servant.API.Capture (Capture) where
8
8
9import Data.Proxy
9import Data.Proxy
10import Data.Text
10import Data.Text
@@ -17,12 +17,34 @@ import Servant.Common.Text
17import Servant.Docs
17import Servant.Docs
18import Servant.Server
18import Servant.Server
19
19
20−-- * Captures
20+-- | Capture a value from the request path under a certain type @a@.
21+--
22+-- Example:
23+--
24+-- > -- GET /books/:isbn
25+-- > type MyApi = "books" :> Capture "isbn" Text :> Get Book
21data Capture sym a
26data Capture sym a
22
27
23captured :: FromText a => proxy (Capture sym a) -> Text -> Maybe a
28captured :: FromText a => proxy (Capture sym a) -> Text -> Maybe a
24captured _ = fromText
29captured _ = fromText
25
30
31+-- | If you use 'Capture' in one of the endpoints for your API,
32+-- this automatically requires your server-side handler to be a function
33+-- that takes an argument of the type specified by the 'Capture'.
34+-- This lets servant worry about getting it from the URL and turning
35+-- it into a value of the type you specify.
36+--
37+-- You can control how it'll be converted from 'Text' to your type
38+-- by simply providing an instance of 'FromText' for your type.
39+--
40+-- Example:
41+--
42+-- > type MyApi = "books" ':>' 'Capture' "isbn" 'Text' ':>' 'Get' Book
43+-- >
44+-- > server :: 'Server' MyApi
45+-- > server = getBook
46+-- > where getBook :: Text -> 'EitherT' (Int, String) IO Book
47+-- > getBook isbn = ...
26instance (KnownSymbol capture, FromText a, HasServer sublayout)
48instance (KnownSymbol capture, FromText a, HasServer sublayout)
27 => HasServer (Capture capture a :> sublayout) where
49 => HasServer (Capture capture a :> sublayout) where
28
50
@@ -40,6 +62,25 @@ instance (KnownSymbol capture, FromText a, HasServer sublayout)
40
62
41 where captureProxy = Proxy :: Proxy (Capture capture a)
63 where captureProxy = Proxy :: Proxy (Capture capture a)
42
64
65+-- | If you use a 'Capture' in one of your endpoints in your API,
66+-- the corresponding querying function will automatically take
67+-- an additional argument of the type specified by your 'Capture'.
68+-- That function will take care of inserting a textual representation
69+-- of this value at the right place in the request path.
70+--
71+-- You can control how values for this type are turned into
72+-- text by specifying a 'ToText' instance for your type.
73+--
74+-- Example:
75+--
76+-- > type MyApi = "books" ':>' 'Capture' "isbn" 'Text' ':>' 'Get' Book
77+-- >
78+-- > myApi :: Proxy MyApi
79+-- > myApi = Proxy
80+-- >
81+-- > getBook :: Text -> BaseUrl -> EitherT String IO Book
82+-- > getBook = client myApi
83+-- > -- then you can just use "getBook" to query that endpoint
43instance (KnownSymbol capture, ToText a, HasClient sublayout)
84instance (KnownSymbol capture, ToText a, HasClient sublayout)
44 => HasClient (Capture capture a :> sublayout) where
85 => HasClient (Capture capture a :> sublayout) where
45
86
@@ -52,6 +93,8 @@ instance (KnownSymbol capture, ToText a, HasClient sublayout)
52
93
53 where p = unpack (toText val)
94 where p = unpack (toText val)
54
95
96+-- | @"books" :> 'Capture' "isbn" Text@ will appear as
97+-- @/books/:isbn@ in the docs
55instance (KnownSymbol sym, ToCapture (Capture sym a), HasDocs sublayout)
98instance (KnownSymbol sym, ToCapture (Capture sym a), HasDocs sublayout)
56 => HasDocs (Capture sym a :> sublayout) where
99 => HasDocs (Capture sym a :> sublayout) where
57
100