Copyright | (c) 2014 Sean Leather |
---|---|
License | BSD3 |
Maintainer | sean.leather@gmail.com |
Stability | experimental |
Safe Haskell | None |
Language | Haskell2010 |
Each of the functions in this module is a monadic request modifier, using the
ReqMod
type. Most of them do not have any side effects; however, the
consistent use of Monad
allows for easy chaining with bind (>>=
) or Kleisli
composition (>=>
).
Example
The example that inspired this package is modifying the Request
from
parseUrl
:
parseUrl
"http://httpbin.org/post" >>=setMethod
POST
>>=setBodyLBS
"hello"
Suppose I want to reuse the URL post request but not the body. I can define a function for just that part:
let httpbinPost ::MonadThrow
m => mRequest
httpbinPost =parseUrl
"http://httpbin.org/post" >>=setMethod
POST
Alternative formulations of the above, without using request modifiers, are:
parseUrl
"http://httpbin.org/post" >>= req -> return $ req {method
=renderStdMethod
POST
,requestBody
=RequestBodyLBS
"hello" }
and
let httpbinPost ::MonadThrow
m => mRequest
httpbinPost = do req <-parseUrl
"http://httpbin.org/post" return $ req {method
=renderStdMethod
POST
}
Benefits
The main benefits of monadic request modifiers are:
- composability,
- conciseness, and
- allowing an arbitrary combination of
Monad
s.
Naming Scheme
The naming scheme used for functions in this module is:
set
- Set a value, overriding any existing value.add
- Append a value to the end of a list and do not override any existing values.BS
- Use a strictByteString
as a parameter.LBS
- Use a lazyByteString
as a parameter.
- type ReqMod m = Request -> m Request
- setUri :: MonadThrow m => URI -> ReqMod m
- setUriRelative :: MonadThrow m => URI -> ReqMod m
- setQueryBS :: Monad m => ByteString -> ReqMod m
- setQuery :: (Monad m, QueryLike q) => q -> ReqMod m
- addQuery :: (Monad m, QueryLike q) => q -> ReqMod m
- addQueryPair :: (Monad m, QueryKeyLike k, QueryValueLike v) => k -> v -> ReqMod m
- setMethodBS :: Monad m => Method -> ReqMod m
- setMethod :: Monad m => StdMethod -> ReqMod m
- setHeaders :: Monad m => RequestHeaders -> ReqMod m
- setHeader :: Monad m => HeaderName -> ByteString -> ReqMod m
- addHeaders :: Monad m => RequestHeaders -> ReqMod m
- addHeader :: Monad m => HeaderName -> ByteString -> ReqMod m
- setContentTypeHeader :: Monad m => MediaType -> ReqMod m
- setAcceptHeader :: Monad m => MediaType -> ReqMod m
- setBody :: Monad m => RequestBody -> Request -> m Request
- setBodyBS :: Monad m => ByteString -> Request -> m Request
- setBodyLBS :: Monad m => ByteString -> Request -> m Request
- setUrlEncodedBody :: Monad m => [(ByteString, ByteString)] -> ReqMod m
- setSimpleRequestBS :: Monad m => StdMethod -> MediaType -> ByteString -> ReqMod m
- setSimpleRequestLBS :: Monad m => StdMethod -> MediaType -> ByteString -> ReqMod m
Request Modifier Type
URI/URL
setUri :: MonadThrow m => URI -> ReqMod m Source
Validate and set the request URI.
Since 0.1
setUriRelative :: MonadThrow m => URI -> ReqMod m Source
Extend the request URI with a relative URI.
Since 0.1
Query String
setQueryBS :: Monad m => ByteString -> ReqMod m Source
Set the query string with a strict ByteString
.
Since 0.1
setQuery :: (Monad m, QueryLike q) => q -> ReqMod m Source
Set the query string with a rendered Query
.
Since 0.1
addQuery :: (Monad m, QueryLike q) => q -> ReqMod m Source
Add a rendered Query
to the end of the query string.
Since 0.1
addQueryPair :: (Monad m, QueryKeyLike k, QueryValueLike v) => k -> v -> ReqMod m Source
Add a single query key/value pair to the end of the query string.
Since 0.1
Method
setMethodBS :: Monad m => Method -> ReqMod m Source
Set the method with a strict ByteString
.
See Network.HTTP.Types.Method for the methods, e.g. methodGet
or
methodPost
.
Since 0.1
Headers
setHeaders :: Monad m => RequestHeaders -> ReqMod m Source
Set the request headers.
Since 0.1
setHeader :: Monad m => HeaderName -> ByteString -> ReqMod m Source
Set the request header by name, removing any other headers with the same name.
Since 0.1
addHeaders :: Monad m => RequestHeaders -> ReqMod m Source
Add headers to the request.
Since 0.1
addHeader :: Monad m => HeaderName -> ByteString -> ReqMod m Source
Add a single header.
Since 0.1
setContentTypeHeader :: Monad m => MediaType -> ReqMod m Source
Set the Content-Type
header with a MediaType
.
Since 0.1
setAcceptHeader :: Monad m => MediaType -> ReqMod m Source
Set the Accept
header with a MediaType
.
Since 0.1
Body
setBodyBS :: Monad m => ByteString -> Request -> m Request Source
Set the request body with a strict ByteString
.
Since 0.1
setBodyLBS :: Monad m => ByteString -> Request -> m Request Source
Set the request body with a lazy ByteString
.
Since 0.1
setUrlEncodedBody :: Monad m => [(ByteString, ByteString)] -> ReqMod m Source
Set the request body with URL-encoded key/value pairs.
Since 0.1
Convenient Combinations
setSimpleRequestBS :: Monad m => StdMethod -> MediaType -> ByteString -> ReqMod m Source
Set the method, Content-Type
, and strict ByteString
body.
Since 0.1
setSimpleRequestLBS :: Monad m => StdMethod -> MediaType -> ByteString -> ReqMod m Source
Set the method, Content-Type
, and lazy ByteString
body.
Since 0.1