@@ -0,0 +1,613 @@
1+-- Hoogle documentation, generated by Haddock
2+-- See Hoogle, http://www.haskell.org/hoogle/
3+
4+
5+-- | A family of combinators for defining webservices APIs and serving them
6+--
7+@package servant
8+@version 0.2
9+
10+module Servant.Common.Text
11+
12+-- | For getting values from url captures and query string parameters
13+class FromText a
14+fromText :: FromText a => Text -> Maybe a
15+
16+-- | For putting values in paths and query string parameters
17+class ToText a
18+toText :: ToText a => a -> Text
19+instance ToText Float
20+instance FromText Float
21+instance ToText Double
22+instance FromText Double
23+instance ToText Integer
24+instance FromText Integer
25+instance ToText Word64
26+instance FromText Word64
27+instance ToText Word32
28+instance FromText Word32
29+instance ToText Word16
30+instance FromText Word16
31+instance ToText Word8
32+instance FromText Word8
33+instance ToText Word
34+instance FromText Word
35+instance ToText Int64
36+instance FromText Int64
37+instance ToText Int32
38+instance FromText Int32
39+instance ToText Int16
40+instance FromText Int16
41+instance ToText Int8
42+instance FromText Int8
43+instance ToText Int
44+instance FromText Int
45+instance ToText Bool
46+instance FromText Bool
47+instance ToText String
48+instance FromText String
49+instance ToText Text
50+instance FromText Text
51+
52+
53+-- | This module lets you implement <a>Server</a>s for defined APIs. You'll
54+-- most likely just need <a>serve</a>.
55+module Servant.Server
56+
57+-- | <a>serve</a> allows you to implement an API and produce a wai
58+-- <a>Application</a>.
59+--
60+-- Example:
61+--
62+-- <pre>
63+-- type MyApi = "books" :> Get [Book] -- GET /books
64+-- :<|> "books" :> ReqBody Book :> Post Book -- POST /books
65+--
66+-- server :: Server MyApi
67+-- server = listAllBooks :<|> postBook
68+-- where listAllBooks = ...
69+-- postBook book = ...
70+--
71+-- app :: Application
72+-- app = serve myApi server
73+--
74+-- main :: IO ()
75+-- main = Network.Wai.Handler.Warp.run 8080 app
76+-- </pre>
77+serve :: HasServer layout => Proxy layout -> Server layout -> Application
78+toApplication :: RoutingApplication -> Application
79+data RouteMismatch
80+
81+-- | the usual "not found" error
82+NotFound :: RouteMismatch
83+
84+-- | a more informative "you just got the HTTP method wrong" error
85+WrongMethod :: RouteMismatch
86+
87+-- | an even more informative "your json request body wasn't valid" error
88+InvalidBody :: RouteMismatch
89+
90+-- | <pre>
91+-- > mempty = NotFound
92+-- >
93+-- > NotFound <a>mappend</a> x = x
94+-- > WrongMethod <a>mappend</a> InvalidBody = InvalidBody
95+-- > WrongMethod <a>mappend</a> _ = WrongMethod
96+-- > InvalidBody <a>mappend</a> _ = InvalidBody
97+-- </pre>
98+
99+-- | A wrapper around <tt><a>Either</a> <a>RouteMismatch</a> a</tt>.
100+newtype RouteResult a
101+RR :: Either RouteMismatch a -> RouteResult a
102+routeResult :: RouteResult a -> Either RouteMismatch a
103+failWith :: RouteMismatch -> RouteResult a
104+succeedWith :: a -> RouteResult a
105+isMismatch :: RouteResult a -> Bool
106+
107+-- | If we get a <a>Right</a>, it has precedence over everything else.
108+--
109+-- This in particular means that if we could get several <a>Right</a>s,
110+-- only the first we encounter would be taken into account.
111+type RoutingApplication = Request -> (RouteResult Response -> IO ResponseReceived) -> IO ResponseReceived
112+class HasServer layout where type family Server layout :: *
113+route :: HasServer layout => Proxy layout -> Server layout -> RoutingApplication
114+instance Eq RouteMismatch
115+instance Show RouteMismatch
116+instance Eq a => Eq (RouteResult a)
117+instance Show a => Show (RouteResult a)
118+instance Monoid (RouteResult a)
119+instance Monoid RouteMismatch
120+
121+module Servant.API.Sub
122+
123+-- | The contained API (second argument) can be found under <tt>("/" ++
124+-- path)</tt> (path being the first argument).
125+--
126+-- Example:
127+--
128+-- <pre>
129+-- -- GET /hello/world
130+-- -- returning a JSON encoded World value
131+-- type MyApi = "hello" :> "world" :> Get World
132+-- </pre>
133+data (:>) (path :: k) a
134+(:>) :: Proxy path -> a -> (:>) a
135+
136+-- | Make sure the incoming request starts with <tt>"/path"</tt>, strip it
137+-- and pass the rest of the request path to <tt>sublayout</tt>.
138+instance (KnownSymbol path, HasServer sublayout) => HasServer (path :> sublayout)
139+
140+module Servant.API.Alternative
141+
142+-- | Union of two APIs, first takes precedence in case of overlap.
143+--
144+-- Example:
145+--
146+-- <pre>
147+-- type MyApi = "books" :> Get [Book] -- GET /books
148+-- :<|> "books" :> ReqBody Book :> Post Book -- POST /books
149+-- </pre>
150+data (:<|>) a b
151+(:<|>) :: a -> b -> (:<|>) a b
152+
153+-- | A server for <tt>a <a>:<|></a> b</tt> first tries to match the
154+-- request again the route represented by <tt>a</tt> and if it fails
155+-- tries <tt>b</tt>. You must provide a request handler for each route.
156+--
157+-- <pre>
158+-- type MyApi = "books" :> Get [Book] -- GET /books
159+-- :<|> "books" :> ReqBody Book :> Post Book -- POST /books
160+--
161+-- server :: Server MyApi
162+-- server = listAllBooks :<|> postBook
163+-- where listAllBooks = ...
164+-- postBook book = ...
165+-- </pre>
166+instance (HasServer a, HasServer b) => HasServer (a :<|> b)
167+
168+module Servant.API.Capture
169+
170+-- | Capture a value from the request path under a certain type <tt>a</tt>.
171+--
172+-- Example:
173+--
174+-- <pre>
175+-- -- GET /books/:isbn
176+-- type MyApi = "books" :> Capture "isbn" Text :> Get Book
177+-- </pre>
178+data Capture sym a
179+instance (KnownSymbol capture, FromText a, HasServer sublayout) => HasServer (Capture capture a :> sublayout)
180+
181+module Servant.API.QueryParam
182+
183+-- | Lookup the value associated to the <tt>sym</tt> query string parameter
184+-- and try to extract it as a value of type <tt>a</tt>.
185+--
186+-- Example:
187+--
188+-- <pre>
189+-- -- /books?author=<author name>
190+-- type MyApi = "books" :> QueryParam "author" Text :> Get [Book]
191+-- </pre>
192+data QueryParam sym a
193+
194+-- | If you use <tt><a>QueryParam</a> "author" Text</tt> in one of the
195+-- endpoints for your API, this automatically requires your server-side
196+-- handler to be a function that takes an argument of type
197+-- <tt><a>Maybe</a> <tt>Text</tt></tt>.
198+--
199+-- This lets servant worry about looking it up in the query string and
200+-- turning it into a value of the type you specify, enclosed in
201+-- <a>Maybe</a>, because it may not be there and servant would then hand
202+-- you <a>Nothing</a>.
203+--
204+-- You can control how it'll be converted from <tt>Text</tt> to your type
205+-- by simply providing an instance of <a>FromText</a> for your type.
206+--
207+-- Example:
208+--
209+-- <pre>
210+-- type MyApi = "books" :> QueryParam "author" Text :> Get [Book]
211+--
212+-- server :: Server MyApi
213+-- server = getBooksBy
214+-- where getBooksBy :: Maybe Text -> EitherT (Int, String) IO [Book]
215+-- getBooksBy Nothing = ...return all books...
216+-- getBooksBy (Just author) = ...return books by the given author...
217+-- </pre>
218+
219+-- | Lookup the values associated to the <tt>sym</tt> query string
220+-- parameter and try to extract it as a value of type <tt>[a]</tt>. This
221+-- is typically meant to support query string parameters of the form
222+-- <tt>param[]=val1&param[]=val2</tt> and so on. Note that servant
223+-- doesn't actually require the <tt>[]</tt>s and will fetch the values
224+-- just fine with <tt>param=val1&param=val2</tt>, too.
225+--
226+-- Example:
227+--
228+-- <pre>
229+-- -- /books?authors[]=<author1>&authors[]=<author2>&...
230+-- type MyApi = "books" :> QueryParams "authors" Text :> Get [Book]
231+-- </pre>
232+data QueryParams sym a
233+
234+-- | If you use <tt><a>QueryParams</a> "authors" Text</tt> in one of the
235+-- endpoints for your API, this automatically requires your server-side
236+-- handler to be a function that takes an argument of type
237+-- <tt>[<tt>Text</tt>]</tt>.
238+--
239+-- This lets servant worry about looking up 0 or more values in the query
240+-- string associated to <tt>authors</tt> and turning each of them into a
241+-- value of the type you specify.
242+--
243+-- You can control how the individual values are converted from
244+-- <tt>Text</tt> to your type by simply providing an instance of
245+-- <a>FromText</a> for your type.
246+--
247+-- Example:
248+--
249+-- <pre>
250+-- type MyApi = "books" :> QueryParams "authors" Text :> Get [Book]
251+--
252+-- server :: Server MyApi
253+-- server = getBooksBy
254+-- where getBooksBy :: [Text] -> EitherT (Int, String) IO [Book]
255+-- getBooksBy authors = ...return all books by these authors...
256+-- </pre>
257+
258+-- | Lookup a potentially value-less query string parameter with boolean
259+-- semantics. If the param <tt>sym</tt> is there without any value, or if
260+-- it's there with value "true" or "1", it's interpreted as <a>True</a>.
261+-- Otherwise, it's interpreted as <a>False</a>.
262+--
263+-- Example:
264+--
265+-- <pre>
266+-- -- /books?published
267+-- type MyApi = "books" :> QueryFlag "published" :> Get [Book]
268+-- </pre>
269+data QueryFlag sym
270+
271+-- | If you use <tt><a>QueryFlag</a> "published"</tt> in one of the
272+-- endpoints for your API, this automatically requires your server-side
273+-- handler to be a function that takes an argument of type <a>Bool</a>.
274+--
275+-- Example:
276+--
277+-- <pre>
278+-- type MyApi = "books" :> QueryFlag "published" :> Get [Book]
279+--
280+-- server :: Server MyApi
281+-- server = getBooks
282+-- where getBooks :: Bool -> EitherT (Int, String) IO [Book]
283+-- getBooks onlyPublished = ...return all books, or only the ones that are already published, depending on the argument...
284+-- </pre>
285+instance (KnownSymbol sym, HasServer sublayout) => HasServer (QueryFlag sym :> sublayout)
286+instance (KnownSymbol sym, FromText a, HasServer sublayout) => HasServer (QueryParams sym a :> sublayout)
287+instance (KnownSymbol sym, FromText a, HasServer sublayout) => HasServer (QueryParam sym a :> sublayout)
288+
289+module Servant.API.ReqBody
290+
291+-- | Extract the request body as a value of type <tt>a</tt>.
292+--
293+-- Example:
294+--
295+-- <pre>
296+-- -- POST /books
297+-- type MyApi = "books" :> ReqBody Book :> Post Book
298+-- </pre>
299+data ReqBody a
300+
301+-- | If you use <a>ReqBody</a> in one of the endpoints for your API, this
302+-- automatically requires your server-side handler to be a function that
303+-- takes an argument of the type specified by <a>ReqBody</a>. This lets
304+-- servant worry about extracting it from the request and turning it into
305+-- a value of the type you specify.
306+--
307+-- All it asks is for a <a>FromJSON</a> instance.
308+--
309+-- Example:
310+--
311+-- <pre>
312+-- type MyApi = "books" :> ReqBody Book :> Post Book
313+--
314+-- server :: Server MyApi
315+-- server = postBook
316+-- where postBook :: Book -> EitherT (Int, String) IO Book
317+-- postBook book = ...insert into your db...
318+-- </pre>
319+instance (FromJSON a, HasServer sublayout) => HasServer (ReqBody a :> sublayout)
320+
321+module Servant.API.Get
322+
323+-- | Endpoint for simple GET requests. Serves the result as JSON.
324+--
325+-- Example:
326+--
327+-- <pre>
328+-- type MyApi = "books" :> Get [Book]
329+-- </pre>
330+data Get a
331+
332+-- | When implementing the handler for a <a>Get</a> endpoint, just like for
333+-- <a>Delete</a>, <a>Post</a> and <a>Put</a>, the handler code runs in
334+-- the <tt>EitherT (Int, String) IO</tt> monad, where the <a>Int</a>
335+-- represents the status code and the <a>String</a> a message, returned
336+-- in case of failure. You can quite handily use <a>left</a> to quickly
337+-- fail if some conditions are not met.
338+--
339+-- If successfully returning a value, we just require that its type has a
340+-- <a>ToJSON</a> instance and servant takes care of encoding it for you,
341+-- yielding status code 200 along the way.
342+instance Typeable Get
343+instance ToJSON result => HasServer (Get result)
344+
345+module Servant.API.Post
346+
347+-- | Endpoint for POST requests. The type variable represents the type of
348+-- the response body (not the request body, use <a>RQBody</a> for that).
349+--
350+-- Example:
351+--
352+-- <pre>
353+-- -- POST /books
354+-- -- with a JSON encoded Book as the request body
355+-- -- returning the just-created Book
356+-- type MyApi = "books" :> ReqBody Book :> Post Book
357+-- </pre>
358+data Post a
359+
360+-- | When implementing the handler for a <a>Post</a> endpoint, just like
361+-- for <a>Delete</a>, <a>Get</a> and <a>Put</a>, the handler code runs in
362+-- the <tt>EitherT (Int, String) IO</tt> monad, where the <a>Int</a>
363+-- represents the status code and the <a>String</a> a message, returned
364+-- in case of failure. You can quite handily use <a>left</a> to quickly
365+-- fail if some conditions are not met.
366+--
367+-- If successfully returning a value, we just require that its type has a
368+-- <a>ToJSON</a> instance and servant takes care of encoding it for you,
369+-- yielding status code 201 along the way.
370+instance Typeable Post
371+instance ToJSON a => HasServer (Post a)
372+
373+module Servant.API.Delete
374+
375+-- | Combinator for DELETE requests.
376+--
377+-- Example:
378+--
379+-- <pre>
380+-- -- DELETE /books/:isbn
381+-- type MyApi = "books" :> Capture "isbn" Text :> Delete
382+-- </pre>
383+data Delete
384+
385+-- | If you have a <a>Delete</a> endpoint in your API, the handler for this
386+-- endpoint is meant to delete a resource.
387+--
388+-- The code of the handler will, just like for <a>Get</a>, <a>Post</a>
389+-- and <a>Put</a>, run in <tt>EitherT (Int, String) IO ()</tt>. The
390+-- <a>Int</a> represents the status code and the <a>String</a> a message
391+-- to be returned. You can use <a>left</a> to painlessly error out if the
392+-- conditions for a successful deletion are not met.
393+instance Typeable Delete
394+instance HasServer Delete
395+
396+module Servant.API.Put
397+
398+-- | Endpoint for PUT requests, usually used to update a ressource. The
399+-- type <tt>a</tt> is the type of the response body that's returned.
400+--
401+-- Example:
402+--
403+-- <pre>
404+-- -- PUT /books/:isbn
405+-- -- with a Book as request body, returning the updated Book
406+-- type MyApi = "books" :> Capture "isbn" Text :> ReqBody Book :> Put Book
407+-- </pre>
408+data Put a
409+
410+-- | When implementing the handler for a <a>Put</a> endpoint, just like for
411+-- <a>Delete</a>, <a>Get</a> and <a>Post</a>, the handler code runs in
412+-- the <tt>EitherT (Int, String) IO</tt> monad, where the <a>Int</a>
413+-- represents the status code and the <a>String</a> a message, returned
414+-- in case of failure. You can quite handily use <a>left</a> to quickly
415+-- fail if some conditions are not met.
416+--
417+-- If successfully returning a value, we just require that its type has a
418+-- <a>ToJSON</a> instance and servant takes care of encoding it for you,
419+-- yielding status code 200 along the way.
420+instance Typeable Put
421+instance ToJSON a => HasServer (Put a)
422+
423+
424+-- | QuasiQuoting utilities for API types.
425+--
426+-- <a>sitemap</a> allows you to write your type in a very natural way:
427+--
428+-- <pre>
429+-- [sitemap|
430+-- PUT hello String -> ()
431+-- POST hello/p:Int String -> ()
432+-- GET hello/?name:String Int
433+-- |]
434+-- </pre>
435+--
436+-- Will generate:
437+--
438+-- <pre>
439+-- "hello" :> ReqBody String :> Put ()
440+-- :<|> "hello" :> Capture "p" Int :> ReqBody String :> Post ()
441+-- :<|> "hello" :> QueryParam "name" String :> Get Int
442+-- </pre>
443+--
444+-- Note the <tt>/</tt> before a <tt>QueryParam</tt>!
445+module Servant.QQ
446+
447+-- | Finally-tagless encoding for our DSL. Keeping <tt>repr'</tt> and
448+-- <tt>repr</tt> distinct when writing functions with an <tt>ExpSYM</tt>
449+-- context ensures certain invariants (for instance, that there is only
450+-- one of <a>get</a>, <a>post</a>, <a>put</a>, and <a>delete</a> in a
451+-- value), but sometimes requires a little more work.
452+class ExpSYM repr' repr | repr -> repr', repr' -> repr
453+lit :: ExpSYM repr' repr => String -> repr' -> repr
454+capture :: ExpSYM repr' repr => String -> String -> repr -> repr
455+reqBody :: ExpSYM repr' repr => String -> repr -> repr
456+queryParam :: ExpSYM repr' repr => String -> String -> repr -> repr
457+conj :: ExpSYM repr' repr => repr' -> repr -> repr
458+get :: ExpSYM repr' repr => String -> repr
459+post :: ExpSYM repr' repr => String -> repr
460+put :: ExpSYM repr' repr => String -> repr
461+delete :: ExpSYM repr' repr => String -> repr
462+(>:) :: Type -> Type -> Type
463+parseMethod :: ExpSYM repr' repr => Parser (String -> repr)
464+parseUrlSegment :: ExpSYM repr repr => Parser (repr -> repr)
465+parseUrl :: ExpSYM repr repr => Parser (repr -> repr)
466+data Typ
467+Val :: String -> Typ
468+ReqArgVal :: String -> String -> Typ
469+parseTyp :: Parser Typ
470+parseEntry :: ExpSYM repr repr => Parser repr
471+blockComment :: Parser ()
472+inlineComment :: Parser ()
473+eol :: Parser String
474+eols :: Parser ()
475+parseAll :: Parser Type
476+
477+-- | The sitemap QuasiQuoter.
478+--
479+-- <ul>
480+-- <li><tt>...<i><a>var</a>:<a>type</a></i>...</tt> becomes a
481+-- capture</li>
482+-- <li><tt>.../?<a>var</a>:<a>type</a></tt> becomes a query
483+-- parameter</li>
484+-- <li><tt><a>method</a> ... <a>typ</a></tt> becomes a method returning
485+-- <tt><a>typ</a></tt></li>
486+-- <li><tt><a>method</a> ... <a>typ1</a> -> <a>typ2</a></tt> becomes a
487+-- method with request body of <tt><a>typ1</a></tt> and returning
488+-- <tt><a>typ2</a></tt></li>
489+-- </ul>
490+--
491+-- Comments are allowed, and have the standard Haskell format
492+--
493+-- <ul>
494+-- <li><tt>--</tt> for inline</li>
495+-- <li><tt>{- ... -}</tt> for block</li>
496+-- </ul>
497+sitemap :: QuasiQuoter
498+instance ExpSYM Type Type
499+
500+
501+-- | Type safe internal links.
502+--
503+-- Provides the function <a>mkLink</a>:
504+--
505+-- <pre>
506+-- type API = Proxy ("hello" :> Get Int
507+-- :<a>|</a> "bye" :> QueryParam "name" String :> Post Bool)
508+--
509+-- api :: API
510+-- api = proxy
511+--
512+-- link1 :: Proxy ("hello" :> Get Int)
513+-- link1 = proxy
514+--
515+-- link2 :: Proxy ("hello" :> Delete)
516+-- link2 = proxy
517+--
518+-- mkLink link1 API -- typechecks, returns 'Link "/hello"'
519+--
520+-- mkLink link2 API -- doesn't typecheck
521+-- </pre>
522+--
523+-- That is, <a>mkLink</a> takes two arguments, a link proxy and a
524+-- sitemap, and returns a <a>Link</a>, but only typechecks if the link
525+-- proxy is a valid link, and part of the sitemap.
526+--
527+-- <b>N.B.:</b> <a>mkLink</a> assumes a capture matches any string
528+-- (without slashes).
529+module Servant.Utils.Links
530+
531+-- | The 'ValidLinkIn f s' constraint holds when <tt>s</tt> is an API that
532+-- contains <tt>f</tt>, and <tt>f</tt> is a link.
533+class ValidLinkIn f s
534+mkLink :: ValidLinkIn f s => f -> s -> Link
535+data Link
536+Link :: String -> Link
537+class VLinkHelper f
538+vlh :: VLinkHelper f => proxy f -> String
539+instance Show Link
540+instance VLinkHelper (Post x)
541+instance VLinkHelper (Get x)
542+instance (KnownSymbol s, VLinkHelper e) => VLinkHelper (s :> e)
543+instance (IsElem f s ~ 'True, IsLink f ~ 'True, VLinkHelper f) => ValidLinkIn f s
544+
545+module Servant.API.Raw
546+
547+-- | Endpoint for plugging in your own Wai <a>Application</a>s.
548+--
549+-- The given <a>Application</a> will get the request as received by the
550+-- server, potentially with a modified (stripped) <a>pathInfo</a> if the
551+-- <a>Application</a> is being routed with <a>:></a>.
552+--
553+-- In addition to just letting you plug in your existing WAI
554+-- <a>Application</a>s, this can also be used with <a>serveDirectory</a>
555+-- to serve static files stored in a particular directory on your
556+-- filesystem, or to serve your API's documentation with
557+-- <a>serveDocumentation</a>.
558+data Raw
559+
560+-- | Just pass the request to the underlying application and serve its
561+-- response.
562+--
563+-- Example:
564+--
565+-- <pre>
566+-- type MyApi = "images" :> Raw
567+--
568+-- server :: Server MyApi
569+-- server = serveDirectory "/var/www/images"
570+-- </pre>
571+instance HasServer Raw
572+
573+
574+-- | This module defines a sever-side handler that lets you serve static
575+-- files.
576+--
577+-- <ul>
578+-- <li><a>serveDirectory</a> lets you serve anything that lives under a
579+-- particular directory on your filesystem.</li>
580+-- </ul>
581+module Servant.Utils.StaticFiles
582+
583+-- | Serve anything under the specified directory as a <a>Raw</a> endpoint.
584+--
585+-- <pre>
586+-- type MyApi = "static" :> Raw
587+--
588+-- server :: Server MyApi
589+-- server = serveDirectory "/var/www"
590+-- </pre>
591+--
592+-- would capture any request to <tt>/static/<something></tt> and
593+-- look for <tt><something></tt> under <tt>/var/www</tt>.
594+--
595+-- It will do its best to guess the MIME type for that file, based on the
596+-- extension, and send an appropriate <i>Content-Type</i> header if
597+-- possible.
598+--
599+-- If your goal is to serve HTML, CSS and Javascript files that use the
600+-- rest of the API as a webapp backend, you will most likely not want the
601+-- static files to be hidden behind a <i>/static/</i> prefix. In that
602+-- case, remember to put the <a>serveDirectory</a> handler in the last
603+-- position, because <i>servant</i> will try to match the handlers in
604+-- order.
605+serveDirectory :: FilePath -> Server Raw
606+
607+module Servant.API
608+
609+module Servant
610+
611+-- | A concrete, poly-kinded proxy type
612+data Proxy (t :: k) :: k -> *
613+Proxy :: Proxy