@@ -7,73 +7,77 @@
7-- Stability : experimental
7-- Stability : experimental
8-- Portability : portable
8-- Portability : portable
10−-- The documentation below is structured in such a way that most important
10+-- The documentation below is structured in such a way that the most
11−-- information goes first: you learn how to do HTTP requests, then how to
11+-- important information is presented first: you learn how to do HTTP
12−-- embed them in any monad you have, then it goes on giving you details
12+-- requests, how to embed them in any monad you have, and then it gives you
13−-- about less-common things you may want to know about. The documentation is
13+-- details about less-common things you may want to know about. The
14−-- written with sufficient coverage of details and examples, it's designed
14+-- documentation is written with sufficient coverage of details and
15−-- to be a complete tutorial on its own.
15+-- examples, and it's designed to be a complete tutorial on its own.
17-- /(A modest intro goes here, click on 'req' to start making requests.)/
17-- /(A modest intro goes here, click on 'req' to start making requests.)/
19-- === About the library
19-- === About the library
21−-- This is an easy-to-use, type-safe, expandable, high-level HTTP library
21+-- Req is an easy-to-use, type-safe, expandable, high-level HTTP library
22-- that just works without any fooling around.
22-- that just works without any fooling around.
24−-- What does the “easy-to-use” phrase mean? It means that the library is
24+-- What does the phrase “easy-to-use” mean? It means that the library is
25−-- designed to be beginner-friendly, so it's simple to add it to your monad
25+-- designed to be beginner-friendly so it's simple to add to your monad
26-- stack, intuitive to work with, well-documented, and does not get in your
26-- stack, intuitive to work with, well-documented, and does not get in your
27−-- way. Doing HTTP requests is a common task and Haskell library for this
27+-- way. Doing HTTP requests is a common task and a Haskell library for this
28-- should be very approachable and clear to beginners, thus certain
28-- should be very approachable and clear to beginners, thus certain
29-- compromises were made. For example, one cannot currently modify
29-- compromises were made. For example, one cannot currently modify
30−-- 'L.ManagerSettings' of default manager because the library always uses
30+-- 'L.ManagerSettings' of the default manager because the library always
31−-- the same implicit global manager for simplicity and maximal connection
31+-- uses the same implicit global manager for simplicity and maximal
32−-- sharing. There is a way to use your own manager with different settings,
32+-- connection sharing. There is a way to use your own manager with different
33−-- but it requires a bit more typing.
33+-- settings, but it requires a bit more typing.
35-- “Type-safe” means that the library is protective and eliminates certain
35-- “Type-safe” means that the library is protective and eliminates certain
36−-- class of errors. For example, we have correct-by-construction 'Url's,
36+-- classes of errors. For example, we have correct-by-construction 'Url's,
37−-- it's guaranteed that user does not send request body when using methods
37+-- it's guaranteed that the user does not send the request body when using
38−-- like 'GET' or 'OPTIONS', amount of implicit assumptions is minimized by
38+-- methods like 'GET' or 'OPTIONS', and the amount of implicit assumptions
39−-- making user specify his\/her intentions in explicit form (for example,
39+-- is minimized by making the user specify his\/her intentions in an
40−-- it's not possible to avoid specifying body or method of a request).
40+-- explicit form (for example, it's not possible to avoid specifying the
41−-- Authentication methods that assume TLS force user to use TLS on type
41+-- body or method of a request). Authentication methods that assume TLS
42+-- force the user to use TLS at the type level. The library also carefully
42−-- level. The library carefully hides underlying types from lower-level
43+-- hides underlying types from the lower-level @http-client@ package because
43−-- @http-client@ package because it's not safe enough (for example
44+-- those types are not safe enough (for example 'L.Request' is an instance
44−-- 'L.Request' is an instance of 'Data.String.IsString' and if it's
45+-- of 'Data.String.IsString' and, if it's malformed, it will blow up at
45−-- malformed, it will blow up at run-time).
46+-- run-time).
47-- “Expandable” refers to the ability of the library to be expanded without
48-- “Expandable” refers to the ability of the library to be expanded without
48−-- ugly hacking. For example, it's possible to define your own HTTP methods,
49+-- having to resort to ugly hacking. For example, it's possible to define
50+-- your own HTTP methods, create new ways to construct the body of a
49−-- new ways to construct body of request, new authorization options, new
51+-- request, create new authorization options, perform a request in a
50−-- ways to actually perform request and how to represent\/parse response. As
52+-- different way, and create your own methods to parse and represent a
51−-- user extends the library to satisfy his\/her special needs, the new
53+-- response. As a user extends the library to satisfy his\/her special
52−-- solutions work just like built-ins. That said, all common cases are
54+-- needs, the new solutions will work just like the built-ins. However, all
53−-- covered by the library out-of-the-box.
55+-- of the common cases are also covered by the library out-of-the-box.
55-- “High-level” means that there are less details to worry about. The
57-- “High-level” means that there are less details to worry about. The
56−-- library is a result of my experiences as a Haskell consultant, working
58+-- library is a result of my experiences as a Haskell consultant. Working
57−-- for several clients who have very different projects and so the library
59+-- for several clients, who had very different projects, showed me that the
58−-- adapts easily to any particular style of writing Haskell applications.
60+-- library should adapt easily to any particular style of writing Haskell
59−-- For example, some people prefer throwing exceptions, while others are
61+-- applications. For example, some people prefer throwing exceptions, while
60−-- concerned with purity: just define 'handleHttpException' accordingly when
62+-- others are concerned with purity. Just define 'handleHttpException'
61−-- making your monad instance of 'MonadHttp' and it will play seamlessly.
63+-- accordingly when making your monad instance of 'MonadHttp' and it will
62−-- Finally, the library cuts boilerplate considerably and helps write
64+-- play together seamlessly. Finally, the library cuts boilerplate down
63−-- concise, easy to read and maintain code.
65+-- considerably, and helps you write concise, easy to read, and maintainable
65-- === Using with other libraries
68-- === Using with other libraries
67−-- * You won't need low-level interface of @http-client@ most of the
70+-- * You won't need the low-level interface of @http-client@ most of the
68−-- time, but when you do, it's better import it qualified because it
71+-- time, but when you do, it's better to do a qualified import,
69−-- has naming conflicts with @req@.
72+-- because @http-client@ has naming conflicts with @req@.
70−-- * For streaming of large request bodies see companion package
73+-- * For streaming of large request bodies see the companion package
71-- @req-conduit@: <https://hackage.haskell.org/package/req-conduit>.
74-- @req-conduit@: <https://hackage.haskell.org/package/req-conduit>.
73-- === Lightweight, no risk solution
76-- === Lightweight, no risk solution
75-- The library uses the following mature packages under the hood to
78-- The library uses the following mature packages under the hood to
76−-- guarantee you best experience without bugs or other funny business:
79+-- guarantee you the best experience that doesn't have any bugs or other
78-- * <https://hackage.haskell.org/package/http-client> — low level HTTP
82-- * <https://hackage.haskell.org/package/http-client> — low level HTTP
79-- client used everywhere in Haskell.
83-- client used everywhere in Haskell.
@@ -81,9 +85,9 @@
81-- support for @http-client@.
85-- support for @http-client@.
83-- It's important to note that since we leverage well-known libraries that
87-- It's important to note that since we leverage well-known libraries that
84−-- the whole Haskell ecosystem uses, there is no risk in using @req@, as the
88+-- the whole Haskell ecosystem uses, there is no risk in using @req@. The
85-- machinery for performing requests is the same as with @http-conduit@ and
89-- machinery for performing requests is the same as with @http-conduit@ and
86−-- @wreq@, it's just the API is different.
90+-- @wreq@. The only difference is the API.
88{-# LANGUAGE CPP #-}
92{-# LANGUAGE CPP #-}
89{-# LANGUAGE DataKinds #-}
93{-# LANGUAGE DataKinds #-}