eeva/servant
1
0
Fork 0
Code Issues Pull requests Projects Releases Wiki Activity

Merge pull request #504 from haskell-servant/jkarni/doc-fixes

Browse source 
Doc fixes
This commit is contained in:
Julian Arni 2016-05-12 09:53:35 +02:00
commit ff40b327bc
3 changed files with 58 additions and 64 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

52
doc/tutorial/Server.lhs
View file

@ -809,7 +809,7 @@ type UserAPI3 = -- view the user with given userid, in JSON
Capture "userid" Int :> Get '[JSON] User
:<|> -- delete the user with given userid. empty response
Capture "userid" Int :> Delete '[] ()
Capture "userid" Int :> DeleteNoContent '[JSON] NoContent
```
We can instead factor out the `userid`:
@ -817,7 +817,7 @@ We can instead factor out the `userid`:
``` haskell
type UserAPI4 = Capture "userid" Int :>
( Get '[JSON] User
:<|> Delete '[] ()
:<|> DeleteNoContent '[JSON] NoContent
)
```
@ -826,10 +826,10 @@ corresponding `Server`:
``` haskell ignore
Server UserAPI3 = (Int -> Handler User)
:<|> (Int -> Handler ())
:<|> (Int -> Handler NoContent)
Server UserAPI4 = Int -> ( Handler User
:<|> Handler ()
:<|> Handler NoContent
)
```
@ -844,7 +844,7 @@ server8 = getUser :<|> deleteUser
where getUser :: Int -> Handler User
getUser _userid = error "..."
deleteUser :: Int -> Handler ()
deleteUser :: Int -> Handler NoContent
deleteUser _userid = error "..."
-- notice how getUser and deleteUser
@ -856,7 +856,7 @@ server9 userid = getUser userid :<|> deleteUser userid
where getUser :: Int -> Handler User
getUser = error "..."
deleteUser :: Int -> Handler ()
deleteUser :: Int -> Handler NoContent
deleteUser = error "..."
```
@ -875,13 +875,13 @@ type API1 = "users" :>
-- we factor out the Request Body
type API2 = ReqBody '[JSON] User :>
( Get '[JSON] User -- just display the same user back, don't register it
:<|> Post '[JSON] () -- register the user. empty response
:<|> PostNoContent '[JSON] NoContent -- register the user. empty response
)
-- we factor out a Header
type API3 = Header "Authorization" Token :>
( Get '[JSON] SecretData -- get some secret data, if authorized
:<|> ReqBody '[JSON] SecretData :> Post '[] () -- add some secret data, if authorized
:<|> ReqBody '[JSON] SecretData :> PostNoContent '[JSON] NoContent -- add some secret data, if authorized
)
newtype Token = Token ByteString
@ -894,11 +894,11 @@ API type only at the end.
``` haskell
type UsersAPI =
Get '[JSON] [User] -- list users
:<|> ReqBody '[JSON] User :> Post '[] () -- add a user
:<|> ReqBody '[JSON] User :> PostNoContent '[JSON] NoContent -- add a user
:<|> Capture "userid" Int :>
( Get '[JSON] User -- view a user
:<|> ReqBody '[JSON] User :> Put '[] () -- update a user
:<|> Delete '[] () -- delete a user
:<|> ReqBody '[JSON] User :> PutNoContent '[JSON] NoContent -- update a user
:<|> DeleteNoContent '[JSON] NoContent -- delete a user
)
usersServer :: Server UsersAPI
@ -907,7 +907,7 @@ usersServer = getUsers :<|> newUser :<|> userOperations
where getUsers :: Handler [User]
getUsers = error "..."
newUser :: User -> Handler ()
newUser :: User -> Handler NoContent
newUser = error "..."
userOperations userid =
@ -917,21 +917,21 @@ usersServer = getUsers :<|> newUser :<|> userOperations
viewUser :: Int -> Handler User
viewUser = error "..."
updateUser :: Int -> User -> Handler ()
updateUser :: Int -> User -> Handler NoContent
updateUser = error "..."
deleteUser :: Int -> Handler ()
deleteUser :: Int -> Handler NoContent
deleteUser = error "..."
```
``` haskell
type ProductsAPI =
Get '[JSON] [Product] -- list products
:<|> ReqBody '[JSON] Product :> Post '[] () -- add a product
:<|> ReqBody '[JSON] Product :> PostNoContent '[JSON] NoContent -- add a product
:<|> Capture "productid" Int :>
( Get '[JSON] Product -- view a product
:<|> ReqBody '[JSON] Product :> Put '[] () -- update a product
:<|> Delete '[] () -- delete a product
:<|> ReqBody '[JSON] Product :> PutNoContent '[JSON] NoContent -- update a product
:<|> DeleteNoContent '[JSON] NoContent -- delete a product
)
data Product = Product { productId :: Int }
@ -942,7 +942,7 @@ productsServer = getProducts :<|> newProduct :<|> productOperations
where getProducts :: Handler [Product]
getProducts = error "..."
newProduct :: Product -> Handler ()
newProduct :: Product -> Handler NoContent
newProduct = error "..."
productOperations productid =
@ -952,10 +952,10 @@ productsServer = getProducts :<|> newProduct :<|> productOperations
viewProduct :: Int -> Handler Product
viewProduct = error "..."
updateProduct :: Int -> Product -> Handler ()
updateProduct :: Int -> Product -> Handler NoContent
updateProduct = error "..."
deleteProduct :: Int -> Handler ()
deleteProduct :: Int -> Handler NoContent
deleteProduct = error "..."
```
@ -975,20 +975,20 @@ abstract that away:
-- indexed by values of type 'i'
type APIFor a i =
Get '[JSON] [a] -- list 'a's
:<|> ReqBody '[JSON] a :> Post '[] () -- add an 'a'
:<|> ReqBody '[JSON] a :> PostNoContent '[JSON] NoContent -- add an 'a'
:<|> Capture "id" i :>
( Get '[JSON] a -- view an 'a' given its "identifier" of type 'i'
:<|> ReqBody '[JSON] a :> Put '[] () -- update an 'a'
:<|> Delete '[] () -- delete an 'a'
:<|> ReqBody '[JSON] a :> PutNoContent '[JSON] NoContent -- update an 'a'
:<|> DeleteNoContent '[JSON] NoContent -- delete an 'a'
)
-- Build the appropriate 'Server'
-- given the handlers of the right type.
serverFor :: Handler [a] -- handler for listing of 'a's
-> (a -> Handler ()) -- handler for adding an 'a'
-> (a -> Handler NoContent) -- handler for adding an 'a'
-> (i -> Handler a) -- handler for viewing an 'a' given its identifier of type 'i'
-> (i -> a -> Handler ()) -- updating an 'a' with given id
-> (i -> Handler ()) -- deleting an 'a' given its id
-> (i -> a -> Handler NoContent) -- updating an 'a' with given id
-> (i -> Handler NoContent) -- deleting an 'a' given its id
-> Server (APIFor a i)
serverFor = error "..."
-- implementation left as an exercise. contact us on IRC

10
doc/tutorial/index.rst
View file

@ -3,14 +3,8 @@ Tutorial
This is an introductory tutorial to **servant**.
.. note::
This tutorial is for the latest version of servant. The tutorial for
servant-0.4 can be viewed
`here <https://haskell-servant.github.io/tutorial/>`_.
(Any comments, issues or feedback about the tutorial can be handled
through
`servant's issue tracker <http://github.com/haskell-servant/servant/issues>`_.)
(Any comments, issues or feedback about the tutorial can be submitted
to `servant's issue tracker <http://github.com/haskell-servant/servant/issues>`_.)
.. toctree::

60
servant-server/src/Servant/Server/Internal/ServantErr.hs
View file

@ -31,7 +31,7 @@ responseServantErr ServantErr{..} = responseLBS status errHeaders errBody
-- Example:
--
-- > failingHandler :: Handler ()
-- > failingHandler = throwErr $ err300 { errBody = "I can't choose." }
-- > failingHandler = throwError $ err300 { errBody = "I can't choose." }
--
err300 :: ServantErr
err300 = ServantErr { errHTTPCode = 300
@ -45,7 +45,7 @@ err300 = ServantErr { errHTTPCode = 300
-- Example:
--
-- > failingHandler :: Handler ()
-- > failingHandler = throwErr err301
-- > failingHandler = throwError err301
--
err301 :: ServantErr
err301 = ServantErr { errHTTPCode = 301
@ -59,7 +59,7 @@ err301 = ServantErr { errHTTPCode = 301
-- Example:
--
-- > failingHandler :: Handler ()
-- > failingHandler = throwErr err302
-- > failingHandler = throwError err302
--
err302 :: ServantErr
err302 = ServantErr { errHTTPCode = 302
@ -73,7 +73,7 @@ err302 = ServantErr { errHTTPCode = 302
-- Example:
--
-- > failingHandler :: Handler ()
-- > failingHandler = throwErr err303
-- > failingHandler = throwError err303
--
err303 :: ServantErr
err303 = ServantErr { errHTTPCode = 303
@ -87,7 +87,7 @@ err303 = ServantErr { errHTTPCode = 303
-- Example:
--
-- > failingHandler :: Handler ()
-- > failingHandler = throwErr err304
-- > failingHandler = throwError err304
--
err304 :: ServantErr
err304 = ServantErr { errHTTPCode = 304
@ -101,7 +101,7 @@ err304 = ServantErr { errHTTPCode = 304
-- Example:
--
-- > failingHandler :: Handler ()
-- > failingHandler = throwErr err305
-- > failingHandler = throwError err305
--
err305 :: ServantErr
err305 = ServantErr { errHTTPCode = 305
@ -115,7 +115,7 @@ err305 = ServantErr { errHTTPCode = 305
-- Example:
--
-- > failingHandler :: Handler ()
-- > failingHandler = throwErr err307
-- > failingHandler = throwError err307
--
err307 :: ServantErr
err307 = ServantErr { errHTTPCode = 307
@ -129,7 +129,7 @@ err307 = ServantErr { errHTTPCode = 307
-- Example:
--
-- > failingHandler :: Handler ()
-- > failingHandler = throwErr $ err400 { errBody = "Your request makes no sense to me." }
-- > failingHandler = throwError $ err400 { errBody = "Your request makes no sense to me." }
--
err400 :: ServantErr
err400 = ServantErr { errHTTPCode = 400
@ -143,7 +143,7 @@ err400 = ServantErr { errHTTPCode = 400
-- Example:
--
-- > failingHandler :: Handler ()
-- > failingHandler = throwErr $ err401 { errBody = "Your credentials are invalid." }
-- > failingHandler = throwError $ err401 { errBody = "Your credentials are invalid." }
--
err401 :: ServantErr
err401 = ServantErr { errHTTPCode = 401
@ -157,7 +157,7 @@ err401 = ServantErr { errHTTPCode = 401
-- Example:
--
-- > failingHandler :: Handler ()
-- > failingHandler = throwErr $ err402 { errBody = "You have 0 credits. Please give me $$$." }
-- > failingHandler = throwError $ err402 { errBody = "You have 0 credits. Please give me $$$." }
--
err402 :: ServantErr
err402 = ServantErr { errHTTPCode = 402
@ -171,7 +171,7 @@ err402 = ServantErr { errHTTPCode = 402
-- Example:
--
-- > failingHandler :: Handler ()
-- > failingHandler = throwErr $ err403 { errBody = "Please login first." }
-- > failingHandler = throwError $ err403 { errBody = "Please login first." }
--
err403 :: ServantErr
err403 = ServantErr { errHTTPCode = 403
@ -185,7 +185,7 @@ err403 = ServantErr { errHTTPCode = 403
-- Example:
--
-- > failingHandler :: Handler ()
-- > failingHandler = throwErr $ err404 { errBody = "(╯°□°）╯︵ ┻━┻)." }
-- > failingHandler = throwError $ err404 { errBody = "(╯°□°）╯︵ ┻━┻)." }
--
err404 :: ServantErr
err404 = ServantErr { errHTTPCode = 404
@ -199,7 +199,7 @@ err404 = ServantErr { errHTTPCode = 404
-- Example:
--
-- > failingHandler :: Handler ()
-- > failingHandler = throwErr $ err405 { errBody = "Your account privileges does not allow for this. Please pay $$$." }
-- > failingHandler = throwError $ err405 { errBody = "Your account privileges does not allow for this. Please pay $$$." }
--
err405 :: ServantErr
err405 = ServantErr { errHTTPCode = 405
@ -213,7 +213,7 @@ err405 = ServantErr { errHTTPCode = 405
-- Example:
--
-- > failingHandler :: Handler ()
-- > failingHandler = throwErr err406
-- > failingHandler = throwError err406
--
err406 :: ServantErr
err406 = ServantErr { errHTTPCode = 406
@ -227,7 +227,7 @@ err406 = ServantErr { errHTTPCode = 406
-- Example:
--
-- > failingHandler :: Handler ()
-- > failingHandler = throwErr err407
-- > failingHandler = throwError err407
--
err407 :: ServantErr
err407 = ServantErr { errHTTPCode = 407
@ -241,7 +241,7 @@ err407 = ServantErr { errHTTPCode = 407
-- Example:
--
-- > failingHandler :: Handler ()
-- > failingHandler = throwErr $ err409 { errBody = "Transaction conflicts with 59879cb56c7c159231eeacdd503d755f7e835f74" }
-- > failingHandler = throwError $ err409 { errBody = "Transaction conflicts with 59879cb56c7c159231eeacdd503d755f7e835f74" }
--
err409 :: ServantErr
err409 = ServantErr { errHTTPCode = 409
@ -255,7 +255,7 @@ err409 = ServantErr { errHTTPCode = 409
-- Example:
--
-- > failingHandler :: Handler ()
-- > failingHandler = throwErr $ err410 { errBody = "I know it was here at some point, but.. I blame bad luck." }
-- > failingHandler = throwError $ err410 { errBody = "I know it was here at some point, but.. I blame bad luck." }
--
err410 :: ServantErr
err410 = ServantErr { errHTTPCode = 410
@ -269,7 +269,7 @@ err410 = ServantErr { errHTTPCode = 410
-- Example:
--
-- > failingHandler :: Handler ()
-- > failingHandler = throwErr err411
-- > failingHandler = throwError err411
--
err411 :: ServantErr
err411 = ServantErr { errHTTPCode = 411
@ -283,7 +283,7 @@ err411 = ServantErr { errHTTPCode = 411
-- Example:
--
-- > failingHandler :: Handler ()
-- > failingHandler = throwErr $ err412 { errBody = "Precondition fail: x < 42 && y > 57" }
-- > failingHandler = throwError $ err412 { errBody = "Precondition fail: x < 42 && y > 57" }
--
err412 :: ServantErr
err412 = ServantErr { errHTTPCode = 412
@ -297,7 +297,7 @@ err412 = ServantErr { errHTTPCode = 412
-- Example:
--
-- > failingHandler :: Handler ()
-- > failingHandler = throwErr $ err413 { errBody = "Request exceeded 64k." }
-- > failingHandler = throwError $ err413 { errBody = "Request exceeded 64k." }
--
err413 :: ServantErr
err413 = ServantErr { errHTTPCode = 413
@ -311,7 +311,7 @@ err413 = ServantErr { errHTTPCode = 413
-- Example:
--
-- > failingHandler :: Handler ()
-- > failingHandler = throwErr $ err414 { errBody = "Maximum length is 64." }
-- > failingHandler = throwError $ err414 { errBody = "Maximum length is 64." }
--
err414 :: ServantErr
err414 = ServantErr { errHTTPCode = 414
@ -325,7 +325,7 @@ err414 = ServantErr { errHTTPCode = 414
-- Example:
--
-- > failingHandler :: Handler ()
-- > failingHandler = throwErr $ err415 { errBody = "Supported media types: gif, png" }
-- > failingHandler = throwError $ err415 { errBody = "Supported media types: gif, png" }
--
err415 :: ServantErr
err415 = ServantErr { errHTTPCode = 415
@ -339,7 +339,7 @@ err415 = ServantErr { errHTTPCode = 415
-- Example:
--
-- > failingHandler :: Handler ()
-- > failingHandler = throwErr $ err416 { errBody = "Valid range is [0, 424242]." }
-- > failingHandler = throwError $ err416 { errBody = "Valid range is [0, 424242]." }
--
err416 :: ServantErr
err416 = ServantErr { errHTTPCode = 416
@ -353,7 +353,7 @@ err416 = ServantErr { errHTTPCode = 416
-- Example:
--
-- > failingHandler :: Handler ()
-- > failingHandler = throwErr $ err417 { errBody = "I found a quux in the request. This isn't going to work." }
-- > failingHandler = throwError $ err417 { errBody = "I found a quux in the request. This isn't going to work." }
--
err417 :: ServantErr
err417 = ServantErr { errHTTPCode = 417
@ -367,7 +367,7 @@ err417 = ServantErr { errHTTPCode = 417
-- Example:
--
-- > failingHandler :: Handler ()
-- > failingHandler = throwErr $ err500 { errBody = "Exception in module A.B.C:55. Have a great day!" }
-- > failingHandler = throwError $ err500 { errBody = "Exception in module A.B.C:55. Have a great day!" }
--
err500 :: ServantErr
err500 = ServantErr { errHTTPCode = 500
@ -381,7 +381,7 @@ err500 = ServantErr { errHTTPCode = 500
-- Example:
--
-- > failingHandler :: Handler ()
-- > failingHandler = throwErr $ err501 { errBody = "/v1/foo is not supported with quux in the request." }
-- > failingHandler = throwError $ err501 { errBody = "/v1/foo is not supported with quux in the request." }
--
err501 :: ServantErr
err501 = ServantErr { errHTTPCode = 501
@ -395,7 +395,7 @@ err501 = ServantErr { errHTTPCode = 501
-- Example:
--
-- > failingHandler :: Handler ()
-- > failingHandler = throwErr $ err502 { errBody = "Tried gateway foo, bar, and baz. None responded." }
-- > failingHandler = throwError $ err502 { errBody = "Tried gateway foo, bar, and baz. None responded." }
--
err502 :: ServantErr
err502 = ServantErr { errHTTPCode = 502
@ -409,7 +409,7 @@ err502 = ServantErr { errHTTPCode = 502
-- Example:
--
-- > failingHandler :: Handler ()
-- > failingHandler = throwErr $ err503 { errBody = "We're rewriting in PHP." }
-- > failingHandler = throwError $ err503 { errBody = "We're rewriting in PHP." }
--
err503 :: ServantErr
err503 = ServantErr { errHTTPCode = 503
@ -423,7 +423,7 @@ err503 = ServantErr { errHTTPCode = 503
-- Example:
--
-- > failingHandler :: Handler ()
-- > failingHandler = throwErr $ err504 { errBody = "Backend foobar did not respond in 5 seconds." }
-- > failingHandler = throwError $ err504 { errBody = "Backend foobar did not respond in 5 seconds." }
--
err504 :: ServantErr
err504 = ServantErr { errHTTPCode = 504
@ -437,7 +437,7 @@ err504 = ServantErr { errHTTPCode = 504
-- Example usage:
--
-- > failingHandler :: Handler ()
-- > failingHandler = throwErr $ err505 { errBody = "I support HTTP/4.0 only." }
-- > failingHandler = throwError $ err505 { errBody = "I support HTTP/4.0 only." }
--
err505 :: ServantErr
err505 = ServantErr { errHTTPCode = 505