ae160e6 · typeable/req

git.iko.soy/typeable/req

on master help sign in

Misc documentation corrections and minor tweaks

ae160e6mrkkrp9 years ago

CHANGELOG.md+6−6

compare with master

unifiedsplit

@@ -41,12 +41,12 @@

42## Req 0.2.0

44−* Added support for multipart form data in form of `ReqBodyMultipart` body

44+* Added support for multipart form data in the form of `ReqBodyMultipart`

45− option and `reqBodyMultipart` helper function. This also required a change

45+ body option and `reqBodyMultipart` helper function. This also required a

46− in type signature of `getRequestContentType`, which now takes `body`, not

46+ change in the type signature of `getRequestContentType`, which now takes

47− `Proxy body` because we need to extract boundary from `body` and put it

47+ `body`, not `Proxy body` because we need to extract boundary from `body`

48− into `Content-Type` header. This change, however, shouldn't be too

48+ and put it into `Content-Type` header. This change, however, shouldn't be

49− dangerous for end-users.

49+ too dangerous for end-users.

51* Added support for OAuth 1.0 authentication via `oAuth1` option.

Network/HTTP/Req.hs+26−25

@@ -419,8 +419,8 @@ req method url body Proxy options = req' method url body options $ \request mana

419-- that allows to perform a request in arbitrary fashion.

420--

421-- This function /does not/ perform handling\/wrapping exceptions, checking

422−-- response, and retrying. It only prepares 'L.Request' and allows you to

422+-- response (with 'httpConfigCheckResponse'), and retrying. It only prepares

423−-- use it.

423+-- 'L.Request' and allows you to use it.

424--

425-- @since 0.3.0

426

@@ -438,7 +438,6 @@ req'

438 -> m a

439req' method url body options m = do

440 config@HttpConfig {..} <- getHttpConfig

441− manager <- liftIO (readIORef globalManager)

442 let -- NOTE First appearance of any given header wins. This allows to

441 let -- NOTE First appearance of any given header wins. This allows to

443 -- “overwrite” headers when we construct a request by cons-ing.

442 -- “overwrite” headers when we construct a request by cons-ing.

444 nubHeaders = Endo $ \x ->

443 nubHeaders = Endo $ \x ->

@@ -456,7 +455,7 @@ req' method url body options m = do

456 getRequestMod url <>

455 getRequestMod url <>

457 getRequestMod (Womb method :: Womb "method" method)

456 getRequestMod (Womb method :: Womb "method" method)

458 request <- finalizeRequest options request'

457 request <- finalizeRequest options request'

459− m request manager

458+ withReqManager (m request)

460

459

461-- | Global 'L.Manager' that 'req' uses. Here we just go with the default

460-- | Global 'L.Manager' that 'req' uses. Here we just go with the default

462-- settings, so users don't need to deal with this manager stuff at all, but

461-- settings, so users don't need to deal with this manager stuff at all, but

@@ -496,8 +495,8 @@ withReqManager m = liftIO (readIORef globalManager) >>= m

496-- When writing a library, keep your API polymorphic in terms of

495-- When writing a library, keep your API polymorphic in terms of

497-- 'MonadHttp', only define instance of 'MonadHttp' in final application.

496-- 'MonadHttp', only define instance of 'MonadHttp' in final application.

498-- Another option is to use @newtype@ wrapped monad stack and define

497-- Another option is to use @newtype@ wrapped monad stack and define

499−-- 'MonadHttp' for it. As of version /0.4.0/, the 'Req' monad is provided

498+-- 'MonadHttp' for it. As of version /0.4.0/, the 'Req' monad that follows

500−-- for this out-of-the-box.

499+-- this strategy is provided out-of-the-box.

501

500

502-- | A type class for monads that support performing HTTP requests.

501-- | A type class for monads that support performing HTTP requests.

503-- Typically, you only need to define the 'handleHttpException' method

502-- Typically, you only need to define the 'handleHttpException' method

@@ -516,9 +515,9 @@ class MonadIO m => MonadHttp m where

516 -- | Return 'HttpConfig' to be used when performing HTTP requests. Default

515 -- | Return 'HttpConfig' to be used when performing HTTP requests. Default

517 -- implementation returns its 'def' value, which is described in the

516 -- implementation returns its 'def' value, which is described in the

518 -- documentation for the type. Common usage pattern with manually defined

517 -- documentation for the type. Common usage pattern with manually defined

519− -- 'getHttpConfig' is to return some hard-coded value, or value extracted

518+ -- 'getHttpConfig' is to return some hard-coded value, or a value

520− -- from 'Control.Monad.Reader.MonadReader' if a more flexible approach to

519+ -- extracted from 'Control.Monad.Reader.MonadReader' if a more flexible

521− -- configuration is desirable.

520+ -- approach to configuration is desirable.

522

521

523 getHttpConfig :: m HttpConfig

522 getHttpConfig :: m HttpConfig

524 getHttpConfig = return def

523 getHttpConfig = return def

@@ -536,8 +535,8 @@ data HttpConfig = HttpConfig

536 -- value: 10.

535 -- value: 10.

537 , httpConfigAltManager :: Maybe L.Manager

536 , httpConfigAltManager :: Maybe L.Manager

538 -- ^ Alternative 'L.Manager' to use. 'Nothing' (default value) means

537 -- ^ Alternative 'L.Manager' to use. 'Nothing' (default value) means

539− -- that default implicit manager will be used (that's what you want in

538+ -- that the default implicit manager will be used (that's what you want

540− -- 99% of cases).

539+ -- in 99% of cases).

541 , httpConfigCheckResponse :: forall r. HttpResponse r => L.Request -> r -> IO ()

540 , httpConfigCheckResponse :: forall r. HttpResponse r => L.Request -> r -> IO ()

542 -- ^ Function to check the response immediately after receiving the

541 -- ^ Function to check the response immediately after receiving the

543 -- status and headers. This is used for throwing exceptions on

542 -- status and headers. This is used for throwing exceptions on

@@ -713,7 +712,7 @@ instance HttpMethod PATCH where

713 httpMethodName Proxy = Y.methodPatch

712 httpMethodName Proxy = Y.methodPatch

714

713

715-- | A type class for types that can be used as an HTTP method. To define a

714-- | A type class for types that can be used as an HTTP method. To define a

716−-- non-standard method, follow this example that defines COPY:

715+-- non-standard method, follow this example that defines @COPY@:

717--

716--

718-- > data COPY = COPY

717-- > data COPY = COPY

719-- >

718-- >

@@ -954,7 +953,7 @@ instance QueryParam FormUrlEncodedParam where

954-- | Multipart form data. Please consult the

953-- | Multipart form data. Please consult the

955-- "Network.HTTP.Client.MultipartFormData" module for how to construct

954-- "Network.HTTP.Client.MultipartFormData" module for how to construct

956-- parts, then use 'reqBodyMultipart' to create actual request body from the

955-- parts, then use 'reqBodyMultipart' to create actual request body from the

957−-- parts. 'reqBodyMultipart' is the only way to get a value of type

956+-- parts. 'reqBodyMultipart' is the only way to get a value of the type

958-- 'ReqBodyMultipart', as its constructor is not exported on purpose.

957-- 'ReqBodyMultipart', as its constructor is not exported on purpose.

959--

958--

960-- @since 0.2.0

959-- @since 0.2.0

@@ -1063,9 +1062,9 @@ instance HttpBody body => RequestComponent (Womb "body" body) where

1063-- the last argument of 'req' to specify no optional parameters, or combine

1062-- the last argument of 'req' to specify no optional parameters, or combine

1064-- 'Option's using 'mappend' (or @('<>')@) to have several of them at once.

1063-- 'Option's using 'mappend' (or @('<>')@) to have several of them at once.

1065

1064

1066−-- | Opaque 'Option' type is a 'Monoid' you can use to pack collection of

1065+-- | The opaque 'Option' type is a 'Monoid' you can use to pack collection

1067−-- optional parameters like query parameters and headers. See sections below

1066+-- of optional parameters like query parameters and headers. See sections

1068−-- to learn which 'Option' primitives are available.

1067+-- below to learn which 'Option' primitives are available.

1069

1068

1070data Option (scheme :: Scheme) =

1069data Option (scheme :: Scheme) =

1071 Option (Endo (Y.QueryText, L.Request)) (Maybe (L.Request -> IO L.Request))

1070 Option (Endo (Y.QueryText, L.Request)) (Maybe (L.Request -> IO L.Request))

@@ -1096,8 +1095,8 @@ withQueryParams f = Option (Endo (first f)) Nothing

1096withRequest :: (L.Request -> L.Request) -> Option scheme

1095withRequest :: (L.Request -> L.Request) -> Option scheme

1097withRequest f = Option (Endo (second f)) Nothing

1096withRequest f = Option (Endo (second f)) Nothing

1098

1097

1099−-- | A helper to create an 'Option' that adds a finalizer (request

1098+-- | A helper to create an 'Option' that adds a finalizer (an IO-enabled

1100−-- transformation that is applied after all other modifications).

1099+-- request transformation that is applied after all other modifications).

1101

1100

1102asFinalizer :: (L.Request -> IO L.Request) -> Option scheme

1101asFinalizer :: (L.Request -> IO L.Request) -> Option scheme

1103asFinalizer = Option mempty . pure

1102asFinalizer = Option mempty . pure

@@ -1293,7 +1292,7 @@ oAuth2Token token = asFinalizer

1293

1292

1294-- | Specify the port to connect to explicitly. Normally, 'Url' you use

1293-- | Specify the port to connect to explicitly. Normally, 'Url' you use

1295-- determines the default port: @80@ for HTTP and @443@ for HTTPS. This

1294-- determines the default port: @80@ for HTTP and @443@ for HTTPS. This

1296−-- 'Option' allows to choose arbitrary port overwriting the defaults.

1295+-- 'Option' allows to choose an arbitrary port overwriting the defaults.

1297

1296

1298port :: Int -> Option scheme

1297port :: Int -> Option scheme

1299port n = withRequest $ \x ->

1298port n = withRequest $ \x ->

@@ -1482,7 +1481,7 @@ responseCookieJar = L.responseCookieJar . toVanillaResponse

1482-- $new-response-interpretation

1481-- $new-response-interpretation

1483--

1482--

1484-- To create a new response interpretation you just need to make your data

1483-- To create a new response interpretation you just need to make your data

1485−-- type an instance of 'HttpResponse' type class.

1484+-- type an instance of the 'HttpResponse' type class.

1486

1485

1487-- | A type class for response interpretations. It allows to fully control

1486-- | A type class for response interpretations. It allows to fully control

1488-- how request is made and how its body is parsed.

1487-- how request is made and how its body is parsed.

@@ -1504,7 +1503,7 @@ class HttpResponse response where

1504 getHttpResponse :: L.Request -> L.Manager -> IO response

1503 getHttpResponse :: L.Request -> L.Manager -> IO response

1505

1504

1506 -- | Construct a “preview” of response body. It is recommend to limit the

1505 -- | Construct a “preview” of response body. It is recommend to limit the

1507− -- length to 1024 bytes. This is mainly useful for inclusion of response

1506+ -- length to 1024 bytes. This is mainly used for inclusion of response

1508 -- body fragments in exceptions.

1507 -- body fragments in exceptions.

1509 --

1508 --

1510 -- __Note__: in versions 0.3.0–0.4.0 this function returned @'IO'

1509 -- __Note__: in versions 0.3.0–0.4.0 this function returned @'IO'

@@ -1522,14 +1521,16 @@ class HttpResponse response where

1522-- 'RequestComponent' changing\/overwriting something in it. 'Endo' is a

1521-- 'RequestComponent' changing\/overwriting something in it. 'Endo' is a

1523-- monoid of endomorphisms under composition, it's used to chain different

1522-- monoid of endomorphisms under composition, it's used to chain different

1524-- request components easier using @('<>')@.

1523-- request components easier using @('<>')@.

1524+--

1525+-- __Note__: this type class is not a part of the public API.

1525

1526

1526class RequestComponent a where

1527class RequestComponent a where

1527

1528

1528 -- | Get a function that takes a 'L.Request' and changes it somehow

1529 -- | Get a function that takes a 'L.Request' and changes it somehow

1529− -- returning another 'L.Request'. For example HTTP method instance of

1530+ -- returning another 'L.Request'. For example, the 'HttpMethod' instance

1530− -- 'RequestComponent' just overwrites method. The function is wrapped in

1531+ -- of 'RequestComponent' just overwrites method. The function is wrapped

1531− -- 'Endo' so it's easier to chain such “modifying applications” together

1532+ -- in 'Endo' so it's easier to chain such “modifying applications”

1532− -- building bigger and bigger 'RequestComponent's.

1533+ -- together building bigger and bigger 'RequestComponent's.

1533

1534

1534 getRequestMod :: a -> Endo L.Request

1535 getRequestMod :: a -> Endo L.Request

1535

1536