-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/
-- | An easy-to-use HTTP client library.
--
-- A web client library that is designed for ease of use.
--
-- Tutorial: http://www.serpentine.com/wreq/tutorial.html
--
-- Features include:
--
--
-- - Simple but powerful lens-based API
-- - A solid test suite, and built on reliable libraries like
-- http-client and lens
-- - Session handling includes connection keep-alive and pooling, and
-- cookie persistence
-- - Automatic response body decompression
-- - Powerful multipart form and file upload handling
-- - Support for JSON requests and responses, including navigation of
-- schema-less responses
-- - Basic and OAuth2 bearer authentication
-- - Early TLS support via the tls package
--
@package wreq
@version 0.1.0.1
-- | HTTP client types.
module Network.Wreq.Types
-- | Options for configuring a client.
data Options
Options :: Either ManagerSettings Manager -> Maybe Proxy -> Maybe Auth -> [Header] -> [(Text, Text)] -> Int -> CookieJar -> Options
-- | Either configuration for a Manager, or an actual
-- Manager.
--
-- If only ManagerSettings are provided, then by default a new
-- Manager will be created for each request.
--
-- Note: when issuing HTTP requests using Options-based
-- functions from the the Network.Wreq.Session module
-- (getWith, putWith, etc.), this field will be ignored.
--
-- An example of using a specific manager:
--
--
-- import Network.HTTP.Client (withManager)
--
-- withManager $ \mgr -> do
-- let opts = defaults { manager = Right mgr }
-- getWith opts "http://httpbin.org/get"
--
--
-- An example of changing settings (this will use a separate
-- Manager for every request, so make sense only if you're issuing
-- a tiny handful of requets):
--
--
-- import Network.HTTP.Client (defaultManagerSettings)
--
-- let settings = defaultManagerSettings { managerConnCount = 5 }
-- opts = defaults { manager = Left settings }
-- getWith opts "http://httpbin.org/get"
--
manager :: Options -> Either ManagerSettings Manager
-- | Host name and port for a proxy to use, if any.
proxy :: Options -> Maybe Proxy
-- | Authentication information.
--
-- Example (note the use of TLS):
--
--
-- let opts = defaults { auth = basicAuth "user" "pass" }
-- getWith opts "https://httpbin.org/basic-auth/user/pass"
--
auth :: Options -> Maybe Auth
-- | Additional headers to send with each request.
--
--
-- let opts = defaults { headers = [("Accept", "*/*")] }
-- getWith opts "http://httpbin.org/get"
--
headers :: Options -> [Header]
-- | Key-value pairs to assemble into a query string to add to the end of a
-- URL.
--
-- For example, given:
--
--
-- let opts = defaults { params = [("sort", "ascending"), ("key", "name")] }
-- getWith opts "http://httpbin.org/get"
--
--
-- This will generate a URL of the form:
--
--
-- http://httpbin.org/get?sort=ascending&key=name
--
params :: Options -> [(Text, Text)]
-- | The maximum number of HTTP redirects to follow before giving up and
-- throwing an exception.
--
-- In this example, a HttpException will be thrown with a
-- TooManyRedirects constructor, because the maximum number of
-- redirects allowed will be exceeded:
--
--
-- let opts = defaults { redirects = 3 }
-- getWith opts "http://httpbin.org/redirect/5"
--
redirects :: Options -> Int
-- | Cookies to set when issuing requests.
--
-- Note: when issuing HTTP requests using Options-based
-- functions from the the Network.Wreq.Session module
-- (getWith, putWith, etc.), this field will be used only
-- for the first HTTP request to be issued during a
-- Session. Any changes changes made for subsequent requests will
-- be ignored.
cookies :: Options -> CookieJar
-- | Supported authentication types.
--
-- Do not use HTTP authentication unless you are using TLS encryption.
-- These authentication tokens can easily be captured and reused by an
-- attacker if transmitted in the clear.
data Auth
-- | Basic authentication. This consists of a plain username and password.
BasicAuth :: ByteString -> ByteString -> Auth
-- | An OAuth2 bearer token. This is treated by many services as the
-- equivalent of a username and password.
OAuth2Bearer :: ByteString -> Auth
-- | A not-quite-standard OAuth2 bearer token (that seems to be used only
-- by GitHub). This is treated by whoever accepts it as the equivalent of
-- a username and password.
OAuth2Token :: ByteString -> Auth
-- | A product type for representing more complex payload types.
data Payload
Raw :: ContentType -> RequestBody -> Payload
-- | A type that can be converted into a POST request payload.
class Postable a
postPayload :: Postable a => a -> Request -> IO Request
-- | A type that can be converted into a PUT request payload.
class Putable a
putPayload :: Putable a => a -> Request -> IO Request
-- | A key/value pair for an application/x-www-form-urlencoded
-- POST request body.
data FormParam
(:=) :: ByteString -> v -> FormParam
-- | A type that can be rendered as the value portion of a key/value pair
-- for use in an application/x-www-form-urlencoded POST body.
-- Intended for use with the FormParam type.
--
-- The instances for String, strict Text, and lazy
-- Text are all encoded using UTF-8 before being URL-encoded.
--
-- The instance for Maybe gives an empty string on Nothing,
-- and otherwise uses the contained type's instance.
class FormValue a
renderFormValue :: FormValue a => a -> ByteString
-- | A MIME content type, e.g. "application/octet-stream".
type ContentType = ByteString
-- | An element of a Link header.
data Link
Link :: ByteString -> [(ByteString, ByteString)] -> Link
linkURL :: Link -> ByteString
linkParams :: Link -> [(ByteString, ByteString)]
-- | The error type used by asJSON and asValue if a failure
-- occurs when parsing a response body as JSON.
data JSONError
JSONError :: String -> JSONError
instance FormValue a => FormValue (Maybe a)
instance FormValue ()
instance FormValue Double
instance FormValue Float
instance FormValue Word64
instance FormValue Word32
instance FormValue Word16
instance FormValue Word8
instance FormValue Word
instance FormValue Integer
instance FormValue Int64
instance FormValue Int32
instance FormValue Int16
instance FormValue Int8
instance FormValue Int
instance FormValue ByteString
instance FormValue ByteString
instance FormValue String
instance FormValue Builder
instance FormValue Text
instance FormValue Text
instance Putable Value
instance Putable ByteString
instance Putable ByteString
instance Putable Payload
instance Postable Value
instance Postable ByteString
instance Postable ByteString
instance Postable Payload
instance Postable FormParam
instance Postable [FormParam]
instance Postable (ByteString, ByteString)
instance Postable [(ByteString, ByteString)]
instance Postable [Part]
instance Postable Part
-- | HTTP client lens machinery.
--
-- When reading the examples in this module, you should assume the
-- following environment:
--
--
-- -- Make it easy to write literal ByteString and Text values.
-- {-# LANGUAGE OverloadedStrings #-}
--
-- -- Our handy module.
-- import Network.Wreq
--
-- -- Operators such as (&) and (.~).
-- import Control.Lens
--
-- -- Conversion of Haskell values to JSON.
-- import Data.Aeson (toJSON)
--
-- -- Easy traversal of JSON data.
-- import Data.Aeson.Lens (key, nth)
--
module Network.Wreq.Lens
-- | Options for configuring a client.
data Options
-- | A lens onto configuration of the connection manager provided by the
-- http-client package.
--
-- In this example, we enable the use of OpenSSL for (hopefully) secure
-- connections:
--
--
-- import OpenSSL.Session (context)
-- import Network.HTTP.Client.OpenSSL
--
-- let opts = defaults & manager .~ Left (opensslManagerSettings context)
-- withOpenSSL $
-- getWith opts "https://httpbin.org/get"
--
manager :: Lens' Options (Either ManagerSettings Manager)
-- | A lens onto proxy configuration.
--
-- Example:
--
--
-- let opts = defaults & proxy .~ httpProxy "localhost" 8000
-- getWith opts "http://httpbin.org/get"
--
proxy :: Lens' Options (Maybe Proxy)
-- | A lens onto request authentication.
--
-- Example (note the use of TLS):
--
--
-- let opts = defaults & auth .~ basicAuth "user" "pass"
-- getWith opts "https://httpbin.org/basic-auth/user/pass"
--
auth :: Lens' Options (Maybe Auth)
-- | A lens onto all headers with the given name (there can legitimately be
-- zero or more).
--
-- Example:
--
--
-- let opts = defaults & header "Accept" .~ ["*/*"]
-- getWith opts "http://httpbin.org/get"
--
header :: HeaderName -> Lens' Options [ByteString]
-- | A lens onto all query parameters with the given name (there can
-- legitimately be zero or more).
--
-- In this example, we construct the query URL
-- "http://httpbin.org/get?foo=bar&foo=quux".
--
--
-- let opts = defaults & param "foo" .~ ["bar", "quux"]
-- getWith opts "http://httpbin.org/get"
--
param :: Text -> Lens' Options [Text]
-- | A lens onto the maximum number of redirects that will be followed
-- before an exception is thrown.
--
-- In this example, a HttpException will be thrown with a
-- TooManyRedirects constructor, because the maximum number of
-- redirects allowed will be exceeded.
--
--
-- let opts = defaults & redirects .~ 3
-- getWith opts "http://httpbin.org/redirect/5"
--
redirects :: Lens' Options Int
-- | A lens onto all headers (there can legitimately be zero or more).
--
-- In this example, we print all the headers sent by default with every
-- request.
--
--
-- print (defaults ^. headers)
--
headers :: Lens' Options [Header]
-- | A lens onto all query parameters.
params :: Lens' Options [(Text, Text)]
-- | A traversal onto the cookie with the given name, if one exists.
cookie :: ByteString -> Traversal' Options Cookie
-- | A lens onto all cookies.
cookies :: Lens' Options CookieJar
-- | Define a HTTP proxy, consisting of a hostname and port number.
data Proxy :: *
-- | A lens onto the hostname portion of a proxy configuration.
proxyHost :: Lens' Proxy ByteString
-- | A lens onto the TCP port number of a proxy configuration.
proxyPort :: Lens' Proxy Int
data Cookie :: *
-- | A lens onto the name of a cookie.
cookieName :: Lens' Cookie ByteString
-- | A lens onto the value of a cookie.
cookieValue :: Lens' Cookie ByteString
-- | A lens onto the expiry time of a cookie.
cookieExpiryTime :: Lens' Cookie UTCTime
-- | A lens onto the domain of a cookie.
cookieDomain :: Lens' Cookie ByteString
-- | A lens onto the path of a cookie.
cookiePath :: Lens' Cookie ByteString
-- | A lens onto the creation time of a cookie.
cookieCreationTime :: Lens' Cookie UTCTime
-- | A lens onto the last access time of a cookie.
cookieLastAccessTime :: Lens' Cookie UTCTime
-- | A lens onto whether a cookie is persistent across sessions (also known
-- as a "tracking cookie").
cookiePersistent :: Lens' Cookie Bool
-- | A lens onto whether a cookie is host-only.
cookieHostOnly :: Lens' Cookie Bool
-- | A lens onto whether a cookie is secure-only, such that it will only be
-- used over TLS.
cookieSecureOnly :: Lens' Cookie Bool
-- | A lens onto whether a cookie is "HTTP-only".
--
-- Such cookies should be used only by browsers when transmitting HTTP
-- requests. They must be unavailable in non-browser environments, such
-- as when executing JavaScript scripts.
cookieHttpOnly :: Lens' Cookie Bool
-- | A simple representation of the HTTP response.
--
-- Since 0.1.0
data Response body :: * -> *
-- | A lens onto the body of a response.
--
--
-- r <- get "http://httpbin.org/get"
-- print (r ^. responseBody)
--
responseBody :: Lens (Response body0) (Response body1) body0 body1
-- | A lens onto all matching named headers in an HTTP response.
--
-- To access exactly one header (the result will be the empty string if
-- there is no match), use the (^.) operator.
--
--
-- r <- get "http://httpbin.org/get"
-- print (r ^. responseHeader "Content-Type")
--
--
-- To access at most one header (the result will be Nothing if
-- there is no match), use the (^?) operator.
--
--
-- r <- get "http://httpbin.org/get"
-- print (r ^? responseHeader "Content-Transfer-Encoding")
--
--
-- To access all (zero or more) matching headers, use the (^..)
-- operator.
--
--
-- r <- get "http://httpbin.org/get"
-- print (r ^.. responseHeader "Set-Cookie")
--
responseHeader :: HeaderName -> Traversal' (Response body) ByteString
-- | A fold over Link headers, matching on both parameter name and
-- value.
--
-- For example, here is a Link header returned by the GitHub
-- search API.
--
--
-- Link:
-- <https://api.github.com/search/code?q=addClass+user%3Amozilla&page=2>; rel="next",
-- <https://api.github.com/search/code?q=addClass+user%3Amozilla&page=34>; rel="last"
--
--
-- And here is an example of how we can retrieve the URL for the
-- next link programatically.
--
--
-- r <- get "https://api.github.com/search/code?q=addClass+user:mozilla"
-- print (r ^? responseLink "rel" "next" . linkURL)
--
responseLink :: ByteString -> ByteString -> Fold (Response body) Link
-- | A fold over any cookies that match the given name.
--
--
-- r <- get "http://www.nytimes.com/"
-- print (r ^? responseCookie "RMID")
--
responseCookie :: ByteString -> Fold (Response body) Cookie
-- | A lens onto all headers in an HTTP response.
responseHeaders :: Lens' (Response body) ResponseHeaders
-- | A lens onto all cookies set in the response.
responseCookieJar :: Lens' (Response body) CookieJar
-- | A lens onto the status of an HTTP response.
responseStatus :: Lens' (Response body) Status
-- | A lens onto the version of an HTTP response.
responseVersion :: Lens' (Response body) HttpVersion
-- | HTTP Status.
--
-- Only the statusCode is used for comparisons.
--
-- Please use mkStatus to create status codes from code and
-- message, or the Enum instance or the status code constants
-- (like ok200). There might be additional record members in the
-- future.
--
-- Note that the Show instance is only for debugging.
data Status :: *
-- | A lens onto the numeric identifier of an HTTP status.
statusCode :: Lens' Status Int
-- | A lens onto the textual description of an HTTP status.
statusMessage :: Lens' Status ByteString
-- | An element of a Link header.
data Link
-- | A lens onto the URL portion of a Link element.
linkURL :: Lens' Link ByteString
-- | A lens onto the parameters of a Link element.
linkParams :: Lens' Link [(ByteString, ByteString)]
-- | A single part of a multipart message.
data Part :: *
-- | A lens onto the name of the input element associated
-- with part of a multipart form upload.
partName :: Lens' Part Text
-- | A lens onto the filename associated with part of a multipart form
-- upload.
partFileName :: Lens' Part (Maybe String)
-- | A lens onto the content-type associated with part of a multipart form
-- upload.
partContentType :: Traversal' Part (Maybe MimeType)
-- | A lens onto the code that fetches the data associated with part of a
-- multipart form upload.
partGetBody :: Lens' Part (IO RequestBody)
-- | Turn an attoparsec Parser into a Fold.
--
-- Both headers and bodies can contain complicated data that we may need
-- to parse.
--
-- Example: when responding to an OPTIONS request, a server may return
-- the list of verbs it supports in any order, up to and including
-- changing the order on every request (which httpbin.org /actually
-- does/!). To deal with this possibility, we parse the list, then sort
-- it.
--
--
-- >>> import Data.Attoparsec.ByteString.Char8 as A
--
-- >>> import Data.List (sort)
--
-- >>>
--
-- >>> let comma = skipSpace >> "," >> skipSpace
--
-- >>> let verbs = A.takeWhile isAlpha_ascii `sepBy` comma
--
-- >>>
--
-- >>> r <- options "http://httpbin.org/get"
--
-- >>> r ^. responseHeader "Allow" . atto verbs . to sort
-- ["GET","HEAD","OPTIONS"]
--
atto :: Parser a -> Fold ByteString a
-- | A library for client-side HTTP requests, focused on ease of use.
--
-- When reading the examples in this module, you should assume the
-- following environment:
--
--
-- -- Make it easy to write literal ByteString and Text values.
-- {-# LANGUAGE OverloadedStrings #-}
--
-- -- Our handy module.
-- import Network.Wreq
--
-- -- Operators such as (&) and (.~).
-- import Control.Lens
--
-- -- Conversion of Haskell values to JSON.
-- import Data.Aeson (toJSON)
--
-- -- Easy traversal of JSON data.
-- import Data.Aeson.Lens (key, nth)
--
--
-- There exist some less frequently used lenses that are not exported
-- from this module; these can be found in Network.Wreq.Lens.
module Network.Wreq
-- | Issue a GET request.
--
-- Example:
--
--
-- get "http://httpbin.org/get"
--
--
--
-- >>> r <- get "http://httpbin.org/get"
--
-- >>> r ^. responseStatus . statusCode
-- 200
--
get :: String -> IO (Response ByteString)
-- | Issue a GET request, using the supplied Options.
--
-- Example:
--
--
-- let opts = defaults & param "foo" .~ ["bar"]
-- getWith opts "http://httpbin.org/get"
--
--
--
-- >>> let opts = defaults & param "foo" .~ ["bar"]
--
-- >>> r <- getWith opts "http://httpbin.org/get"
--
-- >>> r ^? responseBody . key "url"
-- Just (String "http://httpbin.org/get?foo=bar")
--
getWith :: Options -> String -> IO (Response ByteString)
-- | Issue a POST request.
--
-- Example:
--
--
-- post "http://httpbin.org/post" (toJSON [1,2,3])
--
--
--
-- >>> r <- post "http://httpbin.org/post" (toJSON [1,2,3])
--
-- >>> r ^? responseBody . key "json"
-- Just (Array (fromList [Number 1.0,Number 2.0,Number 3.0]))
--
post :: Postable a => String -> a -> IO (Response ByteString)
-- | Issue a POST request, using the supplied Options.
--
-- Example:
--
--
-- let opts = defaults & param "foo" .~ ["bar"]
-- postWith opts "http://httpbin.org/post" (toJSON [1,2,3])
--
--
--
-- >>> let opts = defaults & param "foo" .~ ["bar"]
--
-- >>> r <- postWith opts "http://httpbin.org/post" (toJSON [1,2,3])
--
-- >>> r ^? responseBody . key "url"
-- Just (String "http://httpbin.org/post?foo=bar")
--
postWith :: Postable a => Options -> String -> a -> IO (Response ByteString)
-- | Issue a HEAD request.
--
-- Example:
--
--
-- head_ "http://httpbin.org/get"
--
--
--
-- >>> r <- head_ "http://httpbin.org/get"
--
-- >>> r ^? responseHeader "Content-Type"
-- Just "application/json"
--
head_ :: String -> IO (Response ())
-- | Issue a HEAD request, using the supplied Options.
--
-- Example:
--
--
-- let opts = defaults & param "foo" .~ ["bar"]
-- headWith opts "http://httpbin.org/get"
--
--
--
-- >>> let opts = defaults & param "foo" .~ ["bar"]
--
-- >>> r <- headWith opts "http://httpbin.org/get"
--
-- >>> r ^? responseHeader "Connection"
-- Just "keep-alive"
--
headWith :: Options -> String -> IO (Response ())
-- | Issue an OPTIONS request.
--
-- Example:
--
--
-- options "http://httpbin.org/get"
--
--
-- See atto for a more complex worked example.
options :: String -> IO (Response ())
-- | Issue an OPTIONS request, using the supplied Options.
--
-- Example:
--
--
-- let opts = defaults & param "foo" .~ ["bar"]
-- optionsWith opts "http://httpbin.org/get"
--
optionsWith :: Options -> String -> IO (Response ())
-- | Issue a PUT request.
put :: Putable a => String -> a -> IO (Response ByteString)
-- | Issue a PUT request, using the supplied Options.
putWith :: Putable a => Options -> String -> a -> IO (Response ByteString)
-- | Issue a DELETE request.
--
-- Example:
--
--
-- delete "http://httpbin.org/delete"
--
--
--
-- >>> r <- delete "http://httpbin.org/delete"
--
-- >>> r ^. responseStatus . statusCode
-- 200
--
delete :: String -> IO (Response ())
-- | Issue a DELETE request, using the supplied Options.
--
-- Example:
--
--
-- let opts = defaults & redirects .~ 0
-- deleteWith opts "http://httpbin.org/delete"
--
--
--
-- >>> let opts = defaults & redirects .~ 0
--
-- >>> r <- deleteWith opts "http://httpbin.org/delete"
--
-- >>> r ^. responseStatus . statusCode
-- 200
--
deleteWith :: Options -> String -> IO (Response ())
foldGet :: (a -> ByteString -> IO a) -> a -> String -> IO a
foldGetWith :: Options -> (a -> ByteString -> IO a) -> a -> String -> IO a
-- | Options for configuring a client.
data Options
defaults :: Options
-- | A lens onto configuration of the connection manager provided by the
-- http-client package.
--
-- In this example, we enable the use of OpenSSL for (hopefully) secure
-- connections:
--
--
-- import OpenSSL.Session (context)
-- import Network.HTTP.Client.OpenSSL
--
-- let opts = defaults & manager .~ Left (opensslManagerSettings context)
-- withOpenSSL $
-- getWith opts "https://httpbin.org/get"
--
manager :: Lens' Options (Either ManagerSettings Manager)
-- | A lens onto all headers with the given name (there can legitimately be
-- zero or more).
--
-- Example:
--
--
-- let opts = defaults & header "Accept" .~ ["*/*"]
-- getWith opts "http://httpbin.org/get"
--
header :: HeaderName -> Lens' Options [ByteString]
-- | A lens onto all query parameters with the given name (there can
-- legitimately be zero or more).
--
-- In this example, we construct the query URL
-- "http://httpbin.org/get?foo=bar&foo=quux".
--
--
-- let opts = defaults & param "foo" .~ ["bar", "quux"]
-- getWith opts "http://httpbin.org/get"
--
param :: Text -> Lens' Options [Text]
-- | A lens onto the maximum number of redirects that will be followed
-- before an exception is thrown.
--
-- In this example, a HttpException will be thrown with a
-- TooManyRedirects constructor, because the maximum number of
-- redirects allowed will be exceeded.
--
--
-- let opts = defaults & redirects .~ 3
-- getWith opts "http://httpbin.org/redirect/5"
--
redirects :: Lens' Options Int
-- | A lens onto all headers (there can legitimately be zero or more).
--
-- In this example, we print all the headers sent by default with every
-- request.
--
--
-- print (defaults ^. headers)
--
headers :: Lens' Options [Header]
-- | A lens onto all query parameters.
params :: Lens' Options [(Text, Text)]
-- | A traversal onto the cookie with the given name, if one exists.
cookie :: ByteString -> Traversal' Options Cookie
-- | A lens onto all cookies.
cookies :: Lens' Options CookieJar
-- | Supported authentication types.
--
-- Do not use HTTP authentication unless you are using TLS encryption.
-- These authentication tokens can easily be captured and reused by an
-- attacker if transmitted in the clear.
data Auth
-- | A lens onto request authentication.
--
-- Example (note the use of TLS):
--
--
-- let opts = defaults & auth .~ basicAuth "user" "pass"
-- getWith opts "https://httpbin.org/basic-auth/user/pass"
--
auth :: Lens' Options (Maybe Auth)
-- | Basic authentication. This consists of a plain username and password.
--
-- Example (note the use of TLS):
--
--
-- let opts = defaults & auth .~ basicAuth "user" "pass"
-- getWith opts "https://httpbin.org/basic-auth/user/pass"
--
--
--
-- >>> let opts = defaults & auth .~ basicAuth "user" "pass"
--
-- >>> r <- getWith opts "https://httpbin.org/basic-auth/user/pass"
--
-- >>> r ^? responseBody . key "authenticated"
-- Just (Bool True)
--
basicAuth :: ByteString -> ByteString -> Maybe Auth
-- | An OAuth2 bearer token. This is treated by many services as the
-- equivalent of a username and password.
--
-- Example (note the use of TLS):
--
--
-- let opts = defaults & auth .~ oauth2Bearer "1234abcd"
-- getWith opts "https://public-api.wordpress.com/rest/v1/me/"
--
oauth2Bearer :: ByteString -> Maybe Auth
-- | A not-quite-standard OAuth2 bearer token (that seems to be used only
-- by GitHub). This will be treated by whatever services accept it as the
-- equivalent of a username and password.
--
-- Example (note the use of TLS):
--
--
-- let opts = defaults & auth .~ oauth2Token "abcd1234"
-- getWith opts "https://api.github.com/user"
--
oauth2Token :: ByteString -> Maybe Auth
-- | Define a HTTP proxy, consisting of a hostname and port number.
data Proxy :: *
Proxy :: !ByteString -> !Int -> Proxy
-- | A lens onto proxy configuration.
--
-- Example:
--
--
-- let opts = defaults & proxy .~ httpProxy "localhost" 8000
-- getWith opts "http://httpbin.org/get"
--
proxy :: Lens' Options (Maybe Proxy)
-- | Proxy configuration.
--
-- Example:
--
--
-- let opts = defaults & proxy .~ httpProxy "localhost" 8000
-- getWith opts "http://httpbin.org/get"
--
--
-- (You may wonder why this function returns a 'Maybe Proxy'. This allows
-- it to be easily used on the right hand side of an operation, as above,
-- without its result needing to be wrapped in Just.)
httpProxy :: ByteString -> Int -> Maybe Proxy
withManager :: (Options -> IO a) -> IO a
-- | A product type for representing more complex payload types.
data Payload
Raw :: ContentType -> RequestBody -> Payload
-- | A key/value pair for an application/x-www-form-urlencoded
-- POST request body.
data FormParam
(:=) :: ByteString -> v -> FormParam
-- | A type that can be rendered as the value portion of a key/value pair
-- for use in an application/x-www-form-urlencoded POST body.
-- Intended for use with the FormParam type.
--
-- The instances for String, strict Text, and lazy
-- Text are all encoded using UTF-8 before being URL-encoded.
--
-- The instance for Maybe gives an empty string on Nothing,
-- and otherwise uses the contained type's instance.
class FormValue a
-- | A single part of a multipart message.
data Part :: *
-- | A lens onto the name of the input element associated
-- with part of a multipart form upload.
partName :: Lens' Part Text
-- | A lens onto the filename associated with part of a multipart form
-- upload.
partFileName :: Lens' Part (Maybe String)
-- | A lens onto the content-type associated with part of a multipart form
-- upload.
partContentType :: Traversal' Part (Maybe MimeType)
-- | A lens onto the code that fetches the data associated with part of a
-- multipart form upload.
partGetBody :: Lens' Part (IO RequestBody)
-- | Make a Part whose content is a strict ByteString.
--
-- The Part does not have a file name or content type associated
-- with it.
partBS :: Text -> ByteString -> Part
-- | Make a Part whose content is a lazy ByteString.
--
-- The Part does not have a file name or content type associated
-- with it.
partLBS :: Text -> ByteString -> Part
-- | Make a Part whose content is a strict Text, encoded as
-- UTF-8.
--
-- The Part does not have a file name or content type associated
-- with it.
partText :: Text -> Text -> Part
-- | Make a Part whose content is a String, encoded as
-- UTF-8.
--
-- The Part does not have a file name or content type associated
-- with it.
partString :: Text -> String -> Part
-- | Make a Part from a file.
--
-- The entire file will reside in memory at once. If you want constant
-- memory usage, use partFileSource.
--
-- The FilePath supplied will be used as the file name of the
-- Part. If you do not want to reveal this name to the server, you
-- must remove it prior to uploading.
--
-- The Part does not have a content type associated with it.
partFile :: Text -> FilePath -> Part
-- | Stream a Part from a file.
--
-- The FilePath supplied will be used as the file name of the
-- Part. If you do not want to reveal this name to the server, you
-- must remove it prior to uploading.
--
-- The Part does not have a content type associated with it.
partFileSource :: Text -> FilePath -> Part
-- | A simple representation of the HTTP response.
--
-- Since 0.1.0
data Response body :: * -> *
-- | A lens onto the body of a response.
--
--
-- r <- get "http://httpbin.org/get"
-- print (r ^. responseBody)
--
responseBody :: Lens (Response body0) (Response body1) body0 body1
-- | A lens onto all matching named headers in an HTTP response.
--
-- To access exactly one header (the result will be the empty string if
-- there is no match), use the (^.) operator.
--
--
-- r <- get "http://httpbin.org/get"
-- print (r ^. responseHeader "Content-Type")
--
--
-- To access at most one header (the result will be Nothing if
-- there is no match), use the (^?) operator.
--
--
-- r <- get "http://httpbin.org/get"
-- print (r ^? responseHeader "Content-Transfer-Encoding")
--
--
-- To access all (zero or more) matching headers, use the (^..)
-- operator.
--
--
-- r <- get "http://httpbin.org/get"
-- print (r ^.. responseHeader "Set-Cookie")
--
responseHeader :: HeaderName -> Traversal' (Response body) ByteString
-- | A fold over Link headers, matching on both parameter name and
-- value.
--
-- For example, here is a Link header returned by the GitHub
-- search API.
--
--
-- Link:
-- <https://api.github.com/search/code?q=addClass+user%3Amozilla&page=2>; rel="next",
-- <https://api.github.com/search/code?q=addClass+user%3Amozilla&page=34>; rel="last"
--
--
-- And here is an example of how we can retrieve the URL for the
-- next link programatically.
--
--
-- r <- get "https://api.github.com/search/code?q=addClass+user:mozilla"
-- print (r ^? responseLink "rel" "next" . linkURL)
--
responseLink :: ByteString -> ByteString -> Fold (Response body) Link
-- | A fold over any cookies that match the given name.
--
--
-- r <- get "http://www.nytimes.com/"
-- print (r ^? responseCookie "RMID")
--
responseCookie :: ByteString -> Fold (Response body) Cookie
-- | A lens onto all headers in an HTTP response.
responseHeaders :: Lens' (Response body) ResponseHeaders
-- | A lens onto all cookies set in the response.
responseCookieJar :: Lens' (Response body) CookieJar
-- | A lens onto the status of an HTTP response.
responseStatus :: Lens' (Response body) Status
-- | HTTP Status.
--
-- Only the statusCode is used for comparisons.
--
-- Please use mkStatus to create status codes from code and
-- message, or the Enum instance or the status code constants
-- (like ok200). There might be additional record members in the
-- future.
--
-- Note that the Show instance is only for debugging.
data Status :: *
-- | A lens onto the numeric identifier of an HTTP status.
statusCode :: Lens' Status Int
-- | An element of a Link header.
data Link
-- | A lens onto the URL portion of a Link element.
linkURL :: Lens' Link ByteString
-- | A lens onto the parameters of a Link element.
linkParams :: Lens' Link [(ByteString, ByteString)]
-- | The error type used by asJSON and asValue if a failure
-- occurs when parsing a response body as JSON.
data JSONError
JSONError :: String -> JSONError
-- | Convert the body of an HTTP response from JSON to a suitable Haskell
-- type.
--
-- In this example, we use asJSON in the IO monad, where
-- it will throw a JSONError exception if conversion to the
-- desired type fails.
--
--
-- {-# LANGUAGE DeriveGeneric #-}
-- import GHC.Generics (Generic)
--
-- {- This Haskell type corresponds to the structure of a
-- response body from httpbin.org. -}
--
-- data GetBody = GetBody {
-- headers :: Map Text Text
-- , args :: Map Text Text
-- , origin :: Text
-- , url :: Text
-- } deriving (Show, Generic)
--
-- -- Get GHC to derive a FromJSON instance for us.
-- instance FromJSON GetBody
--
-- {- The fact that we want a GetBody below will be inferred by our
-- use of the "headers" accessor function. -}
--
-- foo = do
-- r <- asJSON =<< get "http://httpbin.org/get"
-- print (headers (r ^. responseBody))
--
--
-- If we use asJSON in the Either monad, it will return
-- Left with a JSONError payload if conversion fails, and
-- Right with a Response whose responseBody is the
-- converted value on success.
asJSON :: (MonadThrow m, FromJSON a) => Response ByteString -> m (Response a)
-- | Convert the body of an HTTP response from JSON to a Value.
--
-- In this example, we use asValue in the IO monad, where
-- it will throw a JSONError exception if the conversion to
-- Value fails.
--
--
-- foo = do
-- r <- asValue =<< get "http://httpbin.org/get"
-- print (r ^? responseBody . key "headers" . key "User-Agent")
--
asValue :: MonadThrow m => Response ByteString -> m (Response Value)
data Cookie :: *
-- | A lens onto the name of a cookie.
cookieName :: Lens' Cookie ByteString
-- | A lens onto the value of a cookie.
cookieValue :: Lens' Cookie ByteString
-- | A lens onto the expiry time of a cookie.
cookieExpiryTime :: Lens' Cookie UTCTime
-- | A lens onto the domain of a cookie.
cookieDomain :: Lens' Cookie ByteString
-- | A lens onto the path of a cookie.
cookiePath :: Lens' Cookie ByteString
-- | Turn an attoparsec Parser into a Fold.
--
-- Both headers and bodies can contain complicated data that we may need
-- to parse.
--
-- Example: when responding to an OPTIONS request, a server may return
-- the list of verbs it supports in any order, up to and including
-- changing the order on every request (which httpbin.org /actually
-- does/!). To deal with this possibility, we parse the list, then sort
-- it.
--
--
-- >>> import Data.Attoparsec.ByteString.Char8 as A
--
-- >>> import Data.List (sort)
--
-- >>>
--
-- >>> let comma = skipSpace >> "," >> skipSpace
--
-- >>> let verbs = A.takeWhile isAlpha_ascii `sepBy` comma
--
-- >>>
--
-- >>> r <- options "http://httpbin.org/get"
--
-- >>> r ^. responseHeader "Allow" . atto verbs . to sort
-- ["GET","HEAD","OPTIONS"]
--
atto :: Parser a -> Fold ByteString a
module Network.Wreq.Session
data Session
withSession :: (Session -> IO a) -> IO a
get :: Session -> String -> IO (Response ByteString)
post :: Postable a => Session -> String -> a -> IO (Response ByteString)
head_ :: Session -> String -> IO (Response ())
options :: Session -> String -> IO (Response ())
put :: Putable a => Session -> String -> a -> IO (Response ByteString)
delete :: Session -> String -> IO (Response ())
getWith :: Options -> Session -> String -> IO (Response ByteString)
postWith :: Postable a => Options -> Session -> String -> a -> IO (Response ByteString)
headWith :: Options -> Session -> String -> IO (Response ())
optionsWith :: Options -> Session -> String -> IO (Response ())
putWith :: Putable a => Options -> Session -> String -> a -> IO (Response ByteString)
deleteWith :: Options -> Session -> String -> IO (Response ())
instance Show Session