Wording updates

Changed the wording of some sections. Added more info to some of the
exercise README files.

Added some more structure to the tests exercise to make it a little
less open. Still undefined sections but there is a bit more guidance
about what things might look like.

Preparation for the name change to 'Applied' instead of 'Advanced'

README.md

@@ -1,4 +1,4 @@
-# Advanced Functional Programming Course
+# Applied Functional Programming Course
 
 <img src="http://i.imgur.com/0h9dFhl.png" height="400" width="640" />
 
@@ -7,7 +7,7 @@
 * Have completed, or are capable of completing, the [Data61 FP Course](https://github.com/data61/fp-course).
 * Have a few months self-study to your name.
 * Want to know how to build larger applications with statically typed FP.
-* Are willing to accept that a web application is a sufficient choice, for now.
+* Are willing to accept that a web application is a sufficient choice.
 
 ### We:
 
@@ -41,16 +41,18 @@ $ cd <levelN>
 $ cabal sandbox init
 $ cabal configure
 $ cabal install --only-dependencies
+$ $EDITOR README.md
 ```
 The normal cabal build commands should then work as expected. We do recommend
 using cabal sandboxes as they provide a contained Haskell environment for a
-given project. Easy to clean up, and package versions won't conflict with any other
-sandboxed project you may be working on. Hence their name.
+given project. Easy to clean up, and package versions won't conflict with any
+other sandboxed project you may be working on. Hence their name.
 
 To use the Nix Shell:
 ```bash
 $ cd <levelN>
 $ nix-shell
+$ $EDITOR README.md
 ```
 Once that completes you will be in a ``nix-shell`` environment with all the
 tools required to build the application for that level. Note that the

level01/README.md

@@ -6,5 +6,8 @@ basic web app. The focus will be on reading the [Hackage] documentation for the
 missing and what we need from the [Wai] package to make our "Hello, World!"
 application run.
 
+Our "application" will respond to ALL incoming requests with a 200 status code
+response and the message "Hello, World!".
+
 [Hackage]: (https://hackage.haskell.org/)
 [Wai]: (https://hackage.haskell.org/package/wai)

level01/src/FirstApp/Main.hs

@@ -38,7 +38,7 @@ app _ cb =
 -- a library. The reasoning behind this is that when you come to do your
 -- testing, you'll be able to import the entire application as a library without
 -- needing to worry about any initialisation code you've buried in your
--- executable Main.sh.
+-- executable Main.hs.
 runApp :: IO ()
-runApp = run 3000 app
+runApp = run undefined undefined
 

level01/src/Main.hs

@@ -2,5 +2,8 @@ module Main where
 
 import qualified FirstApp.Main as Main
 
+-- Our application will be built as a library that will be included in an
+-- executable. So our ``bin/Main.hs`` is a straightforward and unremarkable
+-- affair. We won't be updating this file.
 main :: IO ()
 main = Main.runApp

level02/README.md

@@ -8,7 +8,7 @@ as a pair programmer. It will inform us when we've forgotten to handle a given
 path, tried to use information we don't have access to, or haven't validated our
 inputs sufficiently.
 
-First, to build this application we're going to need some requirements:
+To build this application we're going to need some requirements:
 
 ### Requirements
 We have a WebThing(TM) somewhere and we would like, for some
@@ -36,4 +36,4 @@ GET /<topic>/view
 GET /list
 ```
 
-The starting point for this Level is the ``src/FirstApp/Types.hs``.
+The starting point for this exercise is the ``src/FirstApp/Types.hs``.

level02/src/FirstApp/Types.hs

@@ -41,7 +41,7 @@ data RqType = RqType
 data Error = Error
 
 -- Provide a type to list our response content types so we don't try to
--- do the wrong thing with what we meant to be used as text/JSON etc.
+-- do the wrong thing with what we meant to be used as text or JSON etc.
 data ContentType = ContentType
 
 -- The ContentType description for a header doesn't match our data definition
@@ -76,7 +76,7 @@ newtype CommentText = CommentText Text
 
 -- A benefit of `newtype` is that we can choose to *not* export the constructor
 -- and provide a function of our own. In our case, we're not interested in empty
--- `Text` values so we can eliminate them and immediately report an error.
+-- `Text` values so we will eliminate them and immediately report an error.
 mkTopic
   :: Text
   -> Either Error Topic

level03/src/FirstApp/Conf.hs

@@ -30,11 +30,6 @@ import           Options.Applicative        (Parser, ParserInfo, eitherReader,
 
 import           Text.Read                  (readEither)
 
--- Similar to when we were considering what might go wrong with the RqType,
--- lets think about might go wrong when trying to gather our configuration
--- information.
-data ConfigError
-
 newtype Port = Port
   { getPort :: Int }
   deriving (Eq, Show)
@@ -48,6 +43,11 @@ newtype HelloMsg = HelloMsg
 -- - A changeable message for our users: `HelloMsg`
 data Conf = Conf
 
+-- Similar to when we were considering what might go wrong with the RqType,
+-- lets think about might go wrong when trying to gather our configuration
+-- information.
+data ConfigError
+
 -- Our application will be able to load configuration from both a file and
 -- command line input. We want to be able to use the command line to temporarily
 -- override the configuration from our file. How to would you combine them? This

level03/src/FirstApp/Main.hs

@@ -62,9 +62,8 @@ resp400 =
 app
   :: a
   -> Application
-app cfg rq cb = mkRequest rq
-  >>= fmap handleRespErr . pure . handleRErr
-  >>= cb
+app cfg rq cb =
+  (handleRespErr . handleRErr <$> mkRequest rq) >>= cb
   where
     -- Does this seem clunky to you?
     handleRespErr =
@@ -80,7 +79,7 @@ handleRequest
   -> RqType
   -> Either Error Response
 handleRequest _cfg (AddRq _ _) =
-  Right . resp200 PlainText $ "App says: " <> undefined
+  Right $ resp200 PlainText ("App says: " <> undefined)
 handleRequest _ (ViewRq _) =
   Right $ resp200 PlainText "Susan was here"
 handleRequest _ ListRq =
@@ -110,7 +109,7 @@ mkAddRequest
   -> Either Error RqType
 mkAddRequest ti c = AddRq
   <$> mkTopic ti
-  <*> (mkCommentText . decodeUtf8 $ LBS.toStrict c)
+  <*> (mkCommentText . decodeUtf8 . LBS.toStrict) c
 
 mkViewRequest
   :: Text

level04/README.md

@@ -8,18 +8,18 @@ you to adding tests to your Haskell application. The setup of the Cabal file is
 already completed for you, but will be covered.
 
 As is to be expected, there are multiple testing frameworks and packages
-available but we will only cover one here. Chosen partly due to its possible
-familiarity.
-
-We will use the [HSpec] framework, with the [hspec-wai] package to make our
-lives a bit easier.
+available but we will only cover one here. We will use the [HSpec] framework,
+with the [hspec-wai] package to make our lives a bit easier.
 
 ### Tool Introduction: GHCID
 
 Additionally we'd like to introduce a command line tool that we find quite
 useful for Haskell development; [ghcid]. This is a very lightweight tool that
-works for any project with a functioning cabal setup. In an spare open terminal
-window, navigate to the project root of the Haskell project and run ``$ ghcid``.
+works for any project with a functioning cabal setup.
+
+If you would like to use it, consult its documentation for how to install it,
+and then in an spare open terminal window, navigate to the root of the Haskell
+project and run ``$ ghcid``.
 
 It will then attempt to build your project, if errors are found they will be
 displayed. But more importantly you can go back to editing files in the project

level04/tests/Test.hs

@@ -22,5 +22,8 @@ main = do
       -- failure code to trip up anything that might be watching our run status.
       error "Config failure error handling not implemented"
 
-    Right cfg ->
-      error "tests not implemented"
+    Right cfg -> do
+      let app' = undefined
+      hspec . undefined $ do
+          describe undefined $ do
+            error "test undefined"