Docs and examples #341 (#358)

* add docs and examples

* make examples copypastable

* links

* stack exec example

* examples links

* haddock

---------

Co-authored-by: Marco Zocca <[email protected]>

README.md

@@ -19,15 +19,44 @@ Scotty is the cheap and cheerful way to write RESTful, declarative web applicati
 * Conforms to the [web application interface (WAI)](https://github.com/yesodweb/wai/).
 * Uses the very fast Warp webserver by default.
 
-See examples/basic.hs to see Scotty in action. (basic.hs needs the wai-extra package)
+As for the name: Sinatra + Warp = Scotty.
+
+## Examples
+
+Run /basic.hs to see Scotty in action:
 
 ```bash
-> runghc examples/basic.hs
-Setting phasers to stun... (port 3000) (ctrl-c to quit)
-(visit localhost:3000/somepath)
+runghc examples/basic.hs
 ```
+`Setting phasers to stun... (port 3000) (ctrl-c to quit)`
 
-As for the name: Sinatra + Warp = Scotty.
+Or equivalently with [`stack`](https://docs.haskellstack.org/en/stable/):
+
+```bash
+stack exec -- scotty-basic
+```
+
+Once the server is running you can interact with it with curl or a browser:
+
+```bash
+curl localhost:3000
+```
+`foobar`
+
+```bash
+curl localhost:3000/foo_query?p=42
+```
+`<h1>42</h1>`
+
+
+Additionally, the `examples` directory shows a number of concrete use cases, e.g. 
+
+* [exception handling](./examples/exceptions.hs)
+* [global state](./examples/globalstate.hs)
+* [configuration](./examples/reader.hs)
+* [cookies](./examples/cookies.hs)
+* [file upload](./examples/upload.hs)
+* and more
 
 ## More Information
 

Web/Scotty.hs

@@ -5,9 +5,16 @@
 -- Scotty is set up by default for development mode. For production servers,
 -- you will likely want to modify 'Trans.settings' and the 'defaultHandler'. See
 -- the comments on each of these functions for more information.
+--
+-- Please refer to the @examples@ directory and the @spec@ test suite for concrete use cases, e.g. constructing responses, exception handling and useful implementation details.
 module Web.Scotty
-    ( -- * scotty-to-WAI
-      scotty, scottyApp, scottyOpts, scottySocket, Options(..), defaultOptions
+    ( -- * Running 'scotty' servers
+      scotty
+    , scottyOpts
+    , scottySocket
+    , Options(..), defaultOptions
+      -- ** scotty-to-WAI
+    , scottyApp
       -- * Defining Middleware and Routes
       --
       -- | 'Middleware' and routes are run in the order in which they
@@ -40,7 +47,7 @@ module Web.Scotty
       -- * Parsing Parameters
     , Param, Trans.Parsable(..), Trans.readEither
       -- * Types
-    , ScottyM, ActionM, RoutePattern, File, Content(..), Kilobytes, Handler(..)
+    , ScottyM, ActionM, RoutePattern, File, Content(..), Kilobytes, ErrorHandler, Handler(..)
     , ScottyState, defaultScottyState
     ) where
 

Web/Scotty/Trans.hs

@@ -4,15 +4,22 @@
 -- OverloadedStrings language pragma.
 --
 -- The functions in this module allow an arbitrary monad to be embedded
--- in Scotty's monad transformer stack in order that Scotty be combined
--- with other DSLs.
+-- in Scotty's monad transformer stack, e.g. for complex endpoint configuration,
+-- interacting with databases etc.
 --
 -- Scotty is set up by default for development mode. For production servers,
 -- you will likely want to modify 'settings' and the 'defaultHandler'. See
 -- the comments on each of these functions for more information.
+--
+-- Please refer to the @examples@ directory and the @spec@ test suite for concrete use cases, e.g. constructing responses, exception handling and useful implementation details.
 module Web.Scotty.Trans
-    ( -- * scotty-to-WAI
-      scottyT, scottyAppT, scottyOptsT, scottySocketT, Options(..), defaultOptions
+    ( -- * Running 'scotty' servers
+      scottyT
+    , scottyOptsT
+    , scottySocketT
+    , Options(..), defaultOptions
+      -- ** scotty-to-WAI
+    , scottyAppT
       -- * Defining Middleware and Routes
       --
       -- | 'Middleware' and routes are run in the order in which they

examples/basic.hs

@@ -35,10 +35,20 @@ main = scotty 3000 $ do
     get "/" $ text "foobar"
     get "/" $ text "barfoo"
 
-    -- Using a parameter in the query string. Since it has
-    -- not been given, a 500 page is generated.
-    get "/foo" $ do
-        v <- pathParam "fooparam"
+    -- Looking for a parameter in the path. Since the path pattern does not
+    -- contain the parameter name 'p', the server responds with 500 Server Error.
+    get "/foo_fail" $ do
+        v <- pathParam "p"
+        html $ mconcat ["<h1>", v, "</h1>"]
+
+    -- Looking for a parameter 'p' in the path.
+    get "/foo_path/:p" $ do
+        v <- pathParam "p"
+        html $ mconcat ["<h1>", v, "</h1>"]
+
+    -- Looking for a parameter 'p' in the query string.
+    get "/foo_query" $ do
+        v <- queryParam "p"
         html $ mconcat ["<h1>", v, "</h1>"]
 
     -- An uncaught error becomes a 500 page.

examples/exceptions.hs

@@ -5,6 +5,7 @@ module Main (main) where
 
 import Control.Exception (Exception(..))
 import Control.Monad.IO.Class
+import Control.Monad.IO.Unlift (MonadUnliftIO(..))
 
 import Data.String (fromString)
 import Data.Typeable
@@ -34,8 +35,12 @@ handleEx = Handler $ \case
     html $ fromString $ "<h1>" ++ s ++ "</h1>"
 
 main :: IO ()
-main = scottyT 3000 id $ do -- note, we aren't using any additional transformer layers
-                            -- so we can just use 'id' for the runner.
+main = do
+  scottyT 3000 id server -- note: we use 'id' since we don't have to run any effects at each action
+
+-- Any custom monad stack will need to implement 'MonadUnliftIO'
+server :: MonadUnliftIO m => ScottyT m ()
+server = do
     middleware logStdoutDev
 
     defaultHandler handleEx    -- define what to do with uncaught exceptions

examples/scotty-examples.cabal

@@ -66,6 +66,7 @@ executable scotty-exceptions
                        random,
                        scotty,
                        transformers,
+                       unliftio-core,
                        wai-extra
   GHC-options:         -Wall -threaded