-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/
-- | Convenient monadic HTTP request modifiers
--
@package http-client-request-modifiers
@version 0.1
-- | 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 => m Request
-- 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 => m Request
-- 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 Monads.
--
--
-- 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 strict ByteString as a parameter.
-- - LBS - Use a lazy ByteString as a parameter.
--
module Network.HTTP.Client.Request.Modifiers
-- | Request modifier, abbreviated
--
-- Since 0.1
type ReqMod m = Request -> m Request
-- | Validate and set the request URI.
--
-- Since 0.1
setUri :: MonadThrow m => URI -> ReqMod m
-- | Extend the request URI with a relative URI.
--
-- Since 0.1
setUriRelative :: MonadThrow m => URI -> ReqMod m
-- | Set the query string with a strict ByteString.
--
-- Since 0.1
setQueryBS :: Monad m => ByteString -> ReqMod m
-- | Set the query string with a rendered Query.
--
-- Since 0.1
setQuery :: (Monad m, QueryLike q) => q -> ReqMod m
-- | Add a rendered Query to the end of the query string.
--
-- Since 0.1
addQuery :: (Monad m, QueryLike q) => q -> ReqMod m
-- | Add a single query key/value pair to the end of the query string.
--
-- Since 0.1
addQueryPair :: (Monad m, QueryKeyLike k, QueryValueLike v) => k -> v -> ReqMod m
-- | Set the method with a strict ByteString.
--
-- See Network.HTTP.Types.Method for the methods, e.g.
-- methodGet or methodPost.
--
-- Since 0.1
setMethodBS :: Monad m => Method -> ReqMod m
-- | Set the method with a standard method, e.g. GET or POST.
--
-- Since 0.1
setMethod :: Monad m => StdMethod -> ReqMod m
-- | Set the request headers.
--
-- Since 0.1
setHeaders :: Monad m => RequestHeaders -> ReqMod m
-- | Set the request header by name, removing any other headers with the
-- same name.
--
-- Since 0.1
setHeader :: Monad m => HeaderName -> ByteString -> ReqMod m
-- | Add headers to the request.
--
-- Since 0.1
addHeaders :: Monad m => RequestHeaders -> ReqMod m
-- | Add a single header.
--
-- Since 0.1
addHeader :: Monad m => HeaderName -> ByteString -> ReqMod m
-- | Set the Content-Type header with a MediaType.
--
-- Since 0.1
setContentTypeHeader :: Monad m => MediaType -> ReqMod m
-- | Set the Accept header with a MediaType.
--
-- Since 0.1
setAcceptHeader :: Monad m => MediaType -> ReqMod m
-- | Set the request body.
--
-- Since 0.1
setBody :: Monad m => RequestBody -> Request -> m Request
-- | Set the request body with a strict ByteString.
--
-- Since 0.1
setBodyBS :: Monad m => ByteString -> Request -> m Request
-- | Set the request body with a lazy ByteString.
--
-- Since 0.1
setBodyLBS :: Monad m => ByteString -> Request -> m Request
-- | Set the request body with URL-encoded key/value pairs.
--
-- Since 0.1
setUrlEncodedBody :: Monad m => [(ByteString, ByteString)] -> ReqMod m
-- | Set the method, Content-Type, and strict ByteString
-- body.
--
-- Since 0.1
setSimpleRequestBS :: Monad m => StdMethod -> MediaType -> ByteString -> ReqMod m
-- | Set the method, Content-Type, and lazy ByteString
-- body.
--
-- Since 0.1
setSimpleRequestLBS :: Monad m => StdMethod -> MediaType -> ByteString -> ReqMod m