[happstack-server: 6.3.1
jeremy@n-heptane.com**20111114161051
 Ignore-this: 2905b7921339c2da55d69bbc8b565086
] hunk ./happstack-lite/Examples.lhs 3
-development. Unfortunately, a rich and flexible API can also be
+development. Unfortunately a rich and flexible API can also be
hunk ./happstack-lite/Examples.lhs 5
-realize, is that inside Happstack lives a very simple and easy to use
+realize is that inside Happstack lives a very simple and easy to use
hunk ./happstack-lite/Examples.lhs 8
-happstack-lite gives you that simple, easy to use version of
-Happstack, with out forcing you to give up any of the power and
-flexible.
+happstack-lite brings that simple, easy to use version of Happstack to
+light, with out forcing you to give up any of the power and flexible.
hunk ./happstack-lite/Examples.lhs 13
- 1. gathered all the essential types and functions you need to develop
+ 1. Gathered all the essential types and functions you need to develop
hunk ./happstack-lite/Examples.lhs 17
- 2. Given the functions much simpler type signatures. We've eliminated
-monad transformers, gotten rid of most of the type classes, etc.
+ 2. Given the functions much simpler type signatures by eliminating
+monad transformers, getting rid of most of the type classes, etc.
hunk ./happstack-lite/Examples.lhs 20
- 3. Created this tutorial which demonstrates all the essential things
-you need to know to write a web application in less than 2000 words.
+ 3. Created this tutorial which demonstrates, in less than 2000 words,
+all the essential things you need to know to get started writing a web
+application.
hunk ./happstack-lite/Examples.lhs 27
-the module and use it!
+the corresponding module and use it! To switch from happstack-lite to
+regular happstack simply change your import from `Happstack.Lite` to
+`Happstack.Server` and change `serve` to `simpleHTTP`. That's it!
hunk ./happstack-lite/Examples.lhs 35
-Now onto the tutorial. First we need some LANGUAGE pragmas:
+This document is a literate Haskell file. That means save this file
+and run it with runhaskell!
+
+The latest copy of this tutorial is located at:
+
+The latest HTML-ized version is located at:
+
+
+Now onto the tutorial. 
+
+<ul>
+ <li><a href="#starting">Starting the Server</a></li>
+ <li><a href="#static">Static Routing</a></li>
+ <li><a href="#templates">Templates</a></li>
+ <li><a href="#path">Dynamic Path Segments</a></li>
+ <li><a href="#query">Query String Parameters</a></li>
+ <li><a href="#forms">Form Data</a></li>
+ <li><a href="#cookies">Cookies</a></li>
+ <li><a href="#fileserving">File Serving</a></li>
+ <li><a href="#uploads">File Uploads</a></li>
+</ul>
+
+First we need some LANGUAGE pragmas:
hunk ./happstack-lite/Examples.lhs 69
-> import Text.Blaze
-> import Text.Blaze.Html5           
+> import Text.Blaze.Html5 (Html, (!), a, form, input, p, toHtml, label)
hunk ./happstack-lite/Examples.lhs 74
-To start the app we just call the 'serve' function. The first argument
+<h3><a name="starting">Starting the Server</a></h3>
+
+To start the app we call the `serve` function. The first argument
hunk ./happstack-lite/Examples.lhs 83
-A web application has the type 'ServerPart Response'. 'ServerPart' is a web serving monad. Happstack provides a bunch of functions which run in the 'ServerPart' monad. You can think of it as the web equivalent of the 'IO' monad. Here is our web application:
+A web application has the type `ServerPart Response`. You can think of
+`ServerPart` as the web equivalent of the `IO` monad. 
+
+<h3><a name="static">Static Routing</a></h3
+
+Here is our web application:
hunk ./happstack-lite/Examples.lhs 101
-This web application has two routes. 
+The top-level of our application is just a bunch of routes mappings to handlers.
+
+`dir` is guard used to match on static path components. For example, `dir "echo"`, will match on http://localhost:8000/echo. To match on `"/foo/bar"` you would write, `dir "foo" $ dir "bar" $ handler`.
+
+Each of the routes is tried until one successfully returns a value. In this case, a `Response`.
+
+We convert the list of handlers in a single handler using `msum`. 
+
+The last handler, `homePage` is not guarded by anything, so it will always be called if none of the other handlers were successful.
+
+<h3><a name="templates">HTML Templates</a></h3>
hunk ./happstack-lite/Examples.lhs 146
-The 'dir' function only matches on static path segments. If we have a dynamic path segment, we can use the 'path' function to capture the value and optionally convert it to another type such as Integer. In this example we just echo the captured path segment in the html. Trying visiting:
+<h3><a name="path">Dynamic Path Segments</a></h3>
+
+The 'dir' function only matches on static path segments. If we have a dynamic path segment, we can use the 'path' function to capture the value and optionally convert it to another type such as Integer. In this example we just echo the captured path segment in the html. For example, trying visiting:
hunk ./happstack-lite/Examples.lhs 159
+<h3><a name="query">Query String Parameters</a></h3>
+
hunk ./happstack-lite/Examples.lhs 173
-'lookText' will normally fail (by calling 'mzero') if the parameter is not found. In this example we used 'optional' from Control.Applicative so that it will return a 'Maybe' value instead.
+`lookText` will normally fail (by calling `mzero`) if the parameter is not found. In this example we used `optional` from `Control.Applicative` so that it will return a `Maybe` value instead.
+
+<h3><a name="forms">Form Data</a></h3>
hunk ./happstack-lite/Examples.lhs 177
-We can use 'lookText' (and friends) to extract values from forms as well.
+We can use `lookText` (and friends) to extract values from forms as well.
hunk ./happstack-lite/Examples.lhs 200
-We can use the same 'lookText' function to look up values in in form data.
+We use the same `lookText` function from the previous section to look up values in in form data.
hunk ./happstack-lite/Examples.lhs 202
-You will also note that we use the 'method' function to select between a 'GET' request and a 'POST' request. 
+You will also note that we use the `method` function to select between a `GET` request and a `POST` request. 
hunk ./happstack-lite/Examples.lhs 205
-using the 'GET' method. In the form tag, we see that the form will
+using the `GET` method. In the form tag, we see that the form will
hunk ./happstack-lite/Examples.lhs 208
-'POST'.
+`POST`.
+
+<h3><a name="cookies">Cookies</a></h3>
+
+This example extends the form example to save the message in a cookie. That means you can navigate away from the page and when you come back later it will remember the message you saved.
hunk ./happstack-lite/Examples.lhs 237
-This example extends the form example to save the message in a cookie. That means you can navigate away from the page and when you come back later it will remember the message you saved.
hunk ./happstack-lite/Examples.lhs 240
- 1. lookCookieValue works just like lookText, except it looks up cookies instead of request paramaters or form data.
+ 1. `lookCookieValue` works just like `lookText`, except it looks for the value in the cookies instead of request paramaters or form data.
hunk ./happstack-lite/Examples.lhs 242
- 2. addCookies sends cookies to the browser. addCookies has the type:
+ 2. `addCookies` sends cookies to the browser. addCookies has the type:
hunk ./happstack-lite/Examples.lhs 244
-     addCookies :: [(CookieLife, Cookie)] -> ServerPart ()
+     `addCookies :: [(CookieLife, Cookie)] -> ServerPart ()`
hunk ./happstack-lite/Examples.lhs 246
- 3. 'CookieLife' specifies how long the cookie is valid. 'Session' means it is only valid until the browser window is closed.
+ 3. `CookieLife` specifies how long the cookie is valid. `Session` means it is only valid until the browser window is closed.
hunk ./happstack-lite/Examples.lhs 248
- 4. 'mkCookie' takes the cookie name and the cookie value and makes a Cookie.
+ 4. `mkCookie` takes the cookie name and the cookie value and makes a `Cookie`.
hunk ./happstack-lite/Examples.lhs 250
- 5. 'seeOther' does a 303 redirect tells the browser to do a new GET request on "/fortune".
+ 5. `seeOther` (aka, 303 redirect) tells the browser to do a new GET request on "/fortune".
+
+<h3><a name="fileserving">File Serving</a></h3>
hunk ./happstack-lite/Examples.lhs 255
-disk such as images, stylesheets, external javascript, etc. We can do
-that using the serveDirectory function.
+disk such as images, stylesheets, javascript, etc. We can do
+that using the `serveDirectory` function.
hunk ./happstack-lite/Examples.lhs 262
-The first argument specifies whether serveDirectory should create directory listings or not.
+The first argument specifies whether `serveDirectory` should create directory listings or not.
hunk ./happstack-lite/Examples.lhs 268
-On support platforms (Linux, OS X, Windows), the 'serveDirectory' function will automatically use sendfile() to serve the files. sendfile() uses low-level kernel operations to transfer files directly from the disk to the network with minimal CPU usage and maximal bandwidth usage.
+On support platforms (Linux, OS X, Windows), the `serveDirectory` function will automatically use sendfile() to serve the files. sendfile() uses low-level kernel operations to transfer files directly from the disk to the network with minimal CPU usage and maximal bandwidth usage.
+
+<h3><a name="uploads">File Uploads</a></h3>
hunk ./happstack-lite/Examples.lhs 272
-Handling file uploads is very straight forward. We create a form, just as before. Except instead of 'lookText' we use 'lookFile'.
+Handling file uploads is very straight forward. We create a form, just as before. Except instead of `lookText` we use `lookFile`.
hunk ./happstack-lite/Examples.lhs 297
-temporary file will automatically be deleted after your request
-handler finishes. That ensures that unused files don't clutter up the
-disk. 
+temporary file will automatically be deleted after the server has sent
+the response. That ensures that unused files don't clutter up the
+disk.
hunk ./happstack-lite/Examples.lhs 302
-deleted. Normally the upload handler would use 'moveFile' or
-'copyFile' to move (or copy) the temporary file to a permanent location.
+deleted. Normally the upload handler would use `moveFile` or
+`copyFile` to move (or copy) the temporary file to a permanent location.
hunk ./happstack-lite/Happstack/Lite.hs 138
-method = S.methodOnly 
+method = S.method
hunk ./happstack-lite/happstack-lite.cabal 4
+Description:         This packages provides a subset of Happstack that is easier to learn but still very useful. It as 100% compatible with the full version of Happstack.
hunk ./happstack-lite/happstack-lite.cabal 13
-Cabal-version:       >=1.2
+Cabal-version:       >=1.6
hunk ./happstack-lite/happstack-lite.cabal 19
-  Build-depends: base < 4.4,
+  Build-depends: base < 5,
hunk ./happstack-lite/happstack-lite.cabal 21
-                 happstack-server == 6.2.*,
+                 happstack-server == 6.3.*,
hunk ./happstack-server/happstack-server.cabal 2
-Version:             6.2.5
+Version:             6.3.1