git.iko.soy/typeable/servant
on master help sign in
Documentation
commit6be78e0b387f44277ee9339fd49472e603a2e23e authorJulian K. Arni <jkarni@gmail.com> dateWed 13 Sep 2017, 11:05 (9 years ago) parentffbfa42
5 files changed+58−27
compare with master
unifiedsplit
servant-client-core/src/Servant/Client/Core.hs+29−16 servant-client-core/src/Servant/Client/Core/Internal/Class.hs+1−1 servant-client-core/src/Servant/Client/Core/Internal/Request.hs+2 servant-client/src/Servant/Client.hs+7−4 servant-client/src/Servant/Client/Internal/HttpClient.hs+19−6
servant-client-core/src/Servant/Client/Core.hs+29−16
@@ -1,4 +1,3 @@
1−{-# LANGUAGE AllowAmbiguousTypes #-}
21{-# LANGUAGE CPP #-}
32{-# LANGUAGE DataKinds #-}
43{-# LANGUAGE FlexibleContexts #-}
@@ -17,23 +16,34 @@
1716-- querying functions for each endpoint just from the type representing your
1817-- API.
1918module Servant.Client.Core
20− ( AuthClientData
21− , AuthenticateReq(..)
22− , clientIn
19+ (
20+ -- * Client generation
21+ clientIn
2322 , HasClient(..)
23+
24+ -- * Authentication
2425 , mkAuthenticateReq
26+ , AuthenticateReq(..)
27+ , AuthClientData
28+
29+ -- * Generic Client
30+ , ClientLike(..)
31+ , genericMkClientL
32+ , genericMkClientP
2533 , ServantError(..)
2634 , EmptyClient(..)
27− , RunClient(..)
35+
36+ -- * Request
2837 , Request(..)
2938 , defaultRequest
30− , Response(..)
3139 , RequestBody(..)
40+
41+ -- * Response
42+ , Response(..)
43+ , RunClient(..)
3244 , module Servant.Client.Core.Internal.BaseUrl
33− , ClientLike(..)
34− , genericMkClientL
35− , genericMkClientP
36− -- * Writing instances
45+
46+ -- * Writing HasClient instances
3747 , addHeader
3848 , appendToQueryString
3949 , appendToPath
@@ -84,13 +94,13 @@ import Servant.Client.Core.Internal.BaseUrl (BaseUrl (..),
8494 showBaseUrl)
8595import Servant.Client.Core.Internal.BasicAuth
8696import Servant.Client.Core.Internal.Class
87−import Servant.Client.Core.Internal.Request
8897import Servant.Client.Core.Internal.Generic
98+import Servant.Client.Core.Internal.Request
8999
90100-- * Accessing APIs as a Client
91101
92−-- | 'client' allows you to produce operations to query an API from a client within
93−-- a given monadic context `m`
102+-- | 'clientIn' allows you to produce operations to query an API from a client
103+-- within a 'RunClient' monad.
94104--
95105-- > type MyApi = "books" :> Get '[JSON] [Book] -- GET /books
96106-- > :<|> "books" :> ReqBody '[JSON] Book :> Post '[JSON] Book -- POST /books
@@ -108,9 +118,12 @@ clientIn :: HasClient m api => Proxy api -> Proxy m -> Client m api
108118clientIn p pm = clientWithRoute pm p defaultRequest
109119
110120
111−-- | This class lets us define how each API combinator
112−-- influences the creation of an HTTP request. It's mostly
113−-- an internal class, you can just use 'client'.
121+-- | This class lets us define how each API combinator influences the creation
122+-- of an HTTP request.
123+--
124+-- Unless you are writing a new backend for @servant-client-core@ or new
125+-- combinators that you want to support client-generation, you can ignore this
126+-- class.
114127class RunClient m => HasClient m api where
115128 type Client (m :: * -> *) (api :: *) :: *
116129 clientWithRoute :: Proxy m -> Proxy api -> Request -> Client m api
servant-client-core/src/Servant/Client/Core/Internal/Class.hs+1−1
@@ -3,7 +3,7 @@
33{-# LANGUAGE ScopedTypeVariables #-}
44{-# LANGUAGE TypeFamilies #-}
55{-# LANGUAGE OverloadedStrings #-}
6−{-| Types for possible backends to run client-side `Request` queries -}
6+-- | Types for possible backends to run client-side `Request` queries
77module Servant.Client.Core.Internal.Class where
88
99import Control.Monad (unless)
servant-client-core/src/Servant/Client/Core/Internal/Request.hs+2
@@ -28,6 +28,8 @@ import Web.HttpApiData (ToHttpApiData, toEncodedUrlPiece,
2828 toHeader)
2929
3030-- | A type representing possible errors in a request
31+--
32+-- Note that this type substially change in 0.12
3133data ServantError =
3234 -- | The server returned an error response
3335 FailureResponse Response
servant-client/src/Servant/Client.hs+7−4
@@ -1,10 +1,13 @@
1+-- | This module provides 'client' which can automatically generate
2+-- querying functions for each endpoint just from the type representing your
3+-- API.
14module Servant.Client
2− ( ClientEnv(..)
5+ ( client
36 , ClientM
47 , runClientM
5− , client
6− , module X
8+ , ClientEnv(..)
9+ , module Servant.Client.Core
710 ) where
811
912import Servant.Client.Internal.HttpClient
10−import Servant.Client.Core as X
13+import Servant.Client.Core
servant-client/src/Servant/Client/Internal/HttpClient.hs+19−6
@@ -41,23 +41,36 @@ import Servant.Client.Core
4141
4242import qualified Network.HTTP.Client as Client
4343
44+-- | The environment in which a request is run.
4445data ClientEnv
4546 = ClientEnv
4647 { manager :: Client.Manager
4748 , baseUrl :: BaseUrl
4849 }
4950
51+-- | Generates a set of client functions for an API.
52+--
53+-- Example:
54+--
55+-- > type API = Capture "no" Int :> Get '[JSON] Int
56+-- > :<|> Get '[JSON] [Bool]
57+-- >
58+-- > api :: Proxy API
59+-- > api = Proxy
60+-- >
61+-- > getInt :: Int -> ClientM Int
62+-- > getBools :: ClientM [Bool]
63+-- > getInt :<|> getBools = client api
5064client :: HasClient ClientM api => Proxy api -> Client ClientM api
5165client api = api `clientIn` (Proxy :: Proxy ClientM)
5266
5367-- | @ClientM@ is the monad in which client functions run. Contains the
5468-- 'Manager' and 'BaseUrl' used for requests in the reader environment.
55−newtype ClientM a = ClientM { runClientM' :: ReaderT ClientEnv (ExceptT ServantError IO) a }
56− deriving ( Functor, Applicative, Monad, MonadIO, Generic
57− , MonadReader ClientEnv
58− , MonadError ServantError
59− , MonadThrow, MonadCatch
60− )
69+newtype ClientM a = ClientM
70+ { runClientM' :: ReaderT ClientEnv (ExceptT ServantError IO) a }
71+ deriving ( Functor, Applicative, Monad, MonadIO, Generic
72+ , MonadReader ClientEnv, MonadError ServantError, MonadThrow
73+ , MonadCatch)
6174
6275instance MonadBase IO ClientM where
6376 liftBase = ClientM . liftBase