Revert some changes and change the example

README.lhs

@@ -1 +0,0 @@
-README.md

README.md

@@ -6,45 +6,6 @@
 
 Hasql is a highly efficient PostgreSQL driver and a mapping API. It targets both the users, who need a low level of abstraction, and the users, who face the typical tasks of DB-powered applications, providing them with higher-level APIs.
 
-## Getting started
-
-```haskell
-{-# LANGUAGE OverloadedStrings #-}
-import Data.Text                  (Text)
-import Data.Functor.Contravariant (contramap)
-import Hasql.Connection           (acquire)
-import Hasql.Session              (run, statement)
-import Hasql.Statement            (Statement(..))
-import qualified Hasql.Decoders as HD
-import qualified Hasql.Encoders as HE
-
-data User = User
-  { uId :: Integer
-  , uName :: Text
-  } deriving (Show)
-
-getUser :: Statement Integer User
-getUser = Statement sql encoder (HD.singleRow decoder) True
-  where
-    sql = "SELECT id, name FROM users"
-
-    encoder =
-      contramap fromIntegral (HE.param HE.int8)
-
-    decoder = User
-      <$> fmap fromIntegral (HD.column HD.int8)
-      <*> HD.column HD.text
-
-go :: IO ()
-go = do
-  Right conn <- acquire "postgresql:///mydb"
-  result <- Hasql.Session.run (statement 42 getUser) conn
-  print result
-
-
-main = return ()
-```
-
 
 ## Ecosystem
 
@@ -78,8 +39,78 @@ Hasql is not just a single library, it is a granular ecosystem of composable lib
 
 * **Horizontal scalability of the ecosystem.** Instead of posting feature- or pull-requests, the users are encouraged to release their own small extension-libraries, with themselves becoming the copyright owners and taking on the maintenance responsibilities. Compare this model to the classical one, where some core-team is responsible for everything. One is scalable, the other is not.
 
----
 
-# NOTICE
+# Example
 
-With the recent releases and more to come still, the Hasql ecosystem has undergone a major revision. It is now expected that the users will need a thorough introduction. Hence this notice is to inform you that the documentation with tutorials targeted at both the newcomers and the users who need to migrate from the older versions of the ecosystem are coming soon.
+Following is a complete application, which performs some arithmetic in Postgres using Hasql.
+
+```haskell
+{-# LANGUAGE OverloadedStrings #-}
+import Prelude
+import Data.Int
+import Data.Functor.Contravariant
+import Hasql.Session (Session)
+import Hasql.Statement (Statement(..))
+import qualified Hasql.Session as Session
+import qualified Hasql.Decoders as Decoders
+import qualified Hasql.Encoders as Encoders
+import qualified Hasql.Connection as Connection
+
+
+main :: IO ()
+main = do
+  Right connection <- Connection.acquire connectionSettings
+  result <- Session.run (sumAndDivModSession 3 8 3) connection
+  print result
+  where
+    connectionSettings = Connection.settings "localhost" 5432 "postgres" "" "postgres"
+
+
+-- * Sessions
+-- 
+-- Session is an abstraction over the database connection and all possible errors.
+-- It is used to execute statements.
+-- It is composable and has a Monad instance.
+-- 
+-- It's recommended to define sessions in a dedicated 'Sessions'
+-- submodule of your project.
+-------------------------
+
+sumAndDivModSession :: Int64 -> Int64 -> Int64 -> Session (Int64, Int64)
+sumAndDivModSession a b c = do
+  -- Get the sum of a and b
+  sumOfAAndB <- Session.statement (a, b) sumStatement
+  -- Divide the sum by c and get the modulo as well
+  Session.statement (sumOfAAndB, c) divModStatement
+
+
+-- * Statements
+-- 
+-- Statement is a definition of an individual SQL-statement,
+-- accompanied by a specification of how to encode its parameters and
+-- decode its result.
+-- 
+-- It's recommended to define statements in a dedicated 'Statements'
+-- submodule of your project.
+-------------------------
+
+sumStatement :: Statement (Int64, Int64) Int64
+sumStatement = Statement sql encoder decoder True where
+  sql = "select $1 + $2"
+  encoder =
+    (fst >$< Encoders.param Encoders.int8) <>
+    (snd >$< Encoders.param Encoders.int8)
+  decoder = Decoders.singleRow (Decoders.column Decoders.int8)
+
+divModStatement :: Statement (Int64, Int64) (Int64, Int64)
+divModStatement = Statement sql encoder decoder True where
+  sql = "select $1 / $2, $1 % $2"
+  encoder =
+    (fst >$< Encoders.param Encoders.int8) <>
+    (snd >$< Encoders.param Encoders.int8)
+  decoder = Decoders.singleRow row where
+    row =
+      (,) <$>
+      Decoders.column Decoders.int8 <*>
+      Decoders.column Decoders.int8
+```

hasql.cabal

@@ -85,7 +85,7 @@ library
     vector >= 0.10 && < 0.13,
     hashtables >= 1.1 && < 2,
     text >= 1 && < 2,
-    text-builder >= 0.5.1.1 && < 0.7,
+    text-builder >= 0.6.1.2 && < 0.7,
     bytestring >= 0.10 && < 0.11,
     hashable >= 1.2 && < 1.3,
     -- control:
@@ -203,10 +203,3 @@ test-suite profiling
     hasql,
     bug == 1.*,
     rerebase == 1.*
-
-test-suite readme
-  type:           exitcode-stdio-1.0
-  main-is:        README.lhs
-  build-depends:  base, hasql, text, contravariant, markdown-unlit
-  ghc-options:    -pgmL markdown-unlit
-  build-tool-depends: markdown-unlit:markdown-unlit