CodeMirror: Haskell-literate mode

Haskell literate mode

> {-# LANGUAGE OverloadedStrings #-}
> {-# OPTIONS_GHC -fno-warn-unused-do-bind #-}
> import Control.Applicative ((<$>), (<*>))
> import Data.Maybe (isJust)

> import Data.Text (Text)
> import Text.Blaze ((!))
> import qualified Data.Text as T
> import qualified Happstack.Server as Happstack
> import qualified Text.Blaze.Html5 as H
> import qualified Text.Blaze.Html5.Attributes as A

> import Text.Digestive
> import Text.Digestive.Blaze.Html5
> import Text.Digestive.Happstack
> import Text.Digestive.Util

Simple forms and validation
---------------------------

Let's start by creating a very simple datatype to represent a user:

> data User = User
>     { userName :: Text
>     , userMail :: Text
>     } deriving (Show)

And dive in immediately to create a `Form` for a user. The `Form v m a` type
has three parameters:

- `v`: the type for messages and errors (usually a `String`-like type, `Text` in
  this case);
- `m`: the monad we are operating in, not specified here;
- `a`: the return type of the `Form`, in this case, this is obviously `User`.

> userForm :: Monad m => Form Text m User

We create forms by using the `Applicative` interface. A few form types are
provided in the `Text.Digestive.Form` module, such as `text`, `string`,
`bool`...

In the `digestive-functors` library, the developer is required to label each
field using the `.:` operator. This might look like a bit of a burden, but it
allows you to do some really useful stuff, like separating the `Form` from the
actual HTML layout.

> userForm = User
>     <$> "name" .: text Nothing
>     <*> "mail" .: check "Not a valid email address" checkEmail (text Nothing)

The `check` function enables you to validate the result of a form. For example,
we can validate the email address with a really naive `checkEmail` function.

> checkEmail :: Text -> Bool
> checkEmail = isJust . T.find (== '@')

More validation
---------------

For our example, we also want descriptions of Haskell libraries, and in order to
do that, we need package versions...

> type Version = [Int]

We want to let the user input a version number such as `0.1.0.0`. This means we
need to validate if the input `Text` is of this form, and then we need to parse
it to a `Version` type. Fortunately, we can do this in a single function:
`validate` allows conversion between values, which can optionally fail.

`readMaybe :: Read a => String -> Maybe a` is a utility function imported from
`Text.Digestive.Util`.

> validateVersion :: Text -> Result Text Version
> validateVersion = maybe (Error "Cannot parse version") Success .
>     mapM (readMaybe . T.unpack) . T.split (== '.')

A quick test in GHCi:

ghci> validateVersion (T.pack "0.3.2.1")
    Success [0,3,2,1]
    ghci> validateVersion (T.pack "0.oops")
    Error "Cannot parse version"

It works! This means we can now easily add a `Package` type and a `Form` for it:

> data Category = Web | Text | Math
>     deriving (Bounded, Enum, Eq, Show)

> data Package = Package Text Version Category
>     deriving (Show)

> packageForm :: Monad m => Form Text m Package
> packageForm = Package
>     <$> "name"     .: text Nothing
>     <*> "version"  .: validate validateVersion (text (Just "0.0.0.1"))
>     <*> "category" .: choice categories Nothing
>   where
>     categories = [(x, T.pack (show x)) | x <- [minBound .. maxBound]]

Composing forms
---------------

A release has an author and a package. Let's use this to illustrate the
composability of the digestive-functors library: we can reuse the forms we have
written earlier on.

> data Release = Release User Package
>     deriving (Show)

> releaseForm :: Monad m => Form Text m Release
> releaseForm = Release
>     <$> "author"  .: userForm
>     <*> "package" .: packageForm

Views
-----

As mentioned before, one of the advantages of using digestive-functors is
separation of forms and their actual HTML layout. In order to do this, we have
another type, `View`.

We can get a `View` from a `Form` by supplying input. A `View` contains more
information than a `Form`, it has:

- the original form;
- the input given by the user;
- any errors that have occurred.

It is this view that we convert to HTML. For this tutorial, we use the
[blaze-html] library, and some helpers from the `digestive-functors-blaze`
library.

[blaze-html]: http://jaspervdj.be/blaze/

Let's write a view for the `User` form. As you can see, we here refer to the
different fields in the `userForm`. The `errorList` will generate a list of
errors for the `"mail"` field.

> userView :: View H.Html -> H.Html
> userView view = do
>     label     "name" view "Name: "
>     inputText "name" view
>     H.br
>
>     errorList "mail" view
>     label     "mail" view "Email address: "
>     inputText "mail" view
>     H.br

Like forms, views are also composable: let's illustrate that by adding a view
for the `releaseForm`, in which we reuse `userView`. In order to do this, we
take only the parts relevant to the author from the view by using `subView`. We
can then pass the resulting view to our own `userView`.
We have no special view code for `Package`, so we can just add that to
`releaseView` as well. `childErrorList` will generate a list of errors for each
child of the specified form. In this case, this means a list of errors from
`"package.name"` and `"package.version"`. Note how we use `foo.bar` to refer to
nested forms.

> releaseView :: View H.Html -> H.Html
> releaseView view = do
>     H.h2 "Author"
>     userView $ subView "author" view
>
>     H.h2 "Package"
>     childErrorList "package" view
>
>     label     "package.name" view "Name: "
>     inputText "package.name" view
>     H.br
>
>     label     "package.version" view "Version: "
>     inputText "package.version" view
>     H.br
>
>     label       "package.category" view "Category: "
>     inputSelect "package.category" view
>     H.br

The attentive reader might have wondered what the type parameter for `View` is:
it is the `String`-like type used for e.g. error messages.
But wait! We have
    releaseForm :: Monad m => Form Text m Release
    releaseView :: View H.Html -> H.Html
... doesn't this mean that we need a `View Text` rather than a `View Html`?  The
answer is yes -- but having `View Html` allows us to write these views more
easily with the `digestive-functors-blaze` library. Fortunately, we will be able
to fix this using the `Functor` instance of `View`.
    fmap :: Monad m => (v -> w) -> View v -> View w
A backend
---------
To finish this tutorial, we need to be able to actually run this code. We need
an HTTP server for that, and we use [Happstack] for this tutorial. The
`digestive-functors-happstack` library gives about everything we need for this.
[Happstack]: http://happstack.com/

> site :: Happstack.ServerPart Happstack.Response
> site = do
>     Happstack.decodeBody $ Happstack.defaultBodyPolicy "/tmp" 4096 4096 4096
>     r <- runForm "test" releaseForm
>     case r of
>         (view, Nothing) -> do
>             let view' = fmap H.toHtml view
>             Happstack.ok $ Happstack.toResponse $
>                 template $
>                     form view' "/" $ do
>                         releaseView view'
>                         H.br
>                         inputSubmit "Submit"
>         (_, Just release) -> Happstack.ok $ Happstack.toResponse $
>             template $ do
>                 css
>                 H.h1 "Release received"
>                 H.p $ H.toHtml $ show release
>
> main :: IO ()
> main = Happstack.simpleHTTP Happstack.nullConf site

Utilities
---------

> template :: H.Html -> H.Html
> template body = H.docTypeHtml $ do
>     H.head $ do
>         H.title "digestive-functors tutorial"
>         css
>     H.body body
> css :: H.Html
> css = H.style ! A.type_ "text/css" $ do
>     "label {width: 130px; float: left; clear: both}"
>     "ul.digestive-functors-error-list {"
>     "    color: red;"
>     "    list-style-type: none;"
>     "    padding-left: 0px;"
>     "}"

​x
 
> {-# LANGUAGE OverloadedStrings #-}> {-# OPTIONS_GHC -fno-warn-unused-do-bind #-}> import Control.Applicative ((<$>), (<*>))> import Data.Maybe (isJust)​> import Data.Text (Text)> import Text.Blaze ((!))> import qualified Data.Text as T> import qualified Happstack.Server as Happstack> import qualified Text.Blaze.Html5 as H> import qualified Text.Blaze.Html5.Attributes as A​> import Text.Digestive> import Text.Digestive.Blaze.Html5> import Text.Digestive.Happstack> import Text.Digestive.Util​Simple forms and validation---------------------------​Let's start by creating a very simple datatype to represent a user:​> data User = User>     { userName :: Text>     , userMail :: Text>     } deriving (Show)​And dive in immediately to create a `Form` for a user. The `Form v m a` typehas three parameters:​- `v`: the type for messages and errors (usually a `String`-like type, `Text` in  this case);- `m`: the monad we are operating in, not specified here;- `a`: the return type of the `Form`, in this case, this is obviously `User`.​> userForm :: Monad m => Form Text m User​We create forms by using the `Applicative` interface. A few form types areprovided in the `Text.Digestive.Form` module, such as `text`, `string`,`bool`...​In the `digestive-functors` library, the developer is required to label eachfield using the `.:` operator. This might look like a bit of a burden, but itallows you to do some really useful stuff, like separating the `Form` from theactual HTML layout.​> userForm = User>     <$> "name" .: text Nothing>     <*> "mail" .: check "Not a valid email address" checkEmail (text Nothing)​The `check` function enables you to validate the result of a form. For example,we can validate the email address with a really naive `checkEmail` function.​> checkEmail :: Text -> Bool> checkEmail = isJust . T.find (== '@')​More validation---------------​For our example, we also want descriptions of Haskell libraries, and in order todo that, we need package versions...​> type Version = [Int]​We want to let the user input a version number such as `0.1.0.0`. This means weneed to validate if the input `Text` is of this form, and then we need to parseit to a `Version` type. Fortunately, we can do this in a single function:`validate` allows conversion between values, which can optionally fail.​`readMaybe :: Read a => String -> Maybe a` is a utility function imported from`Text.Digestive.Util`.​> validateVersion :: Text -> Result Text Version> validateVersion = maybe (Error "Cannot parse version") Success .>     mapM (readMaybe . T.unpack) . T.split (== '.')​A quick test in GHCi:​    ghci> validateVersion (T.pack "0.3.2.1")    Success [0,3,2,1]    ghci> validateVersion (T.pack "0.oops")    Error "Cannot parse version"​It works! This means we can now easily add a `Package` type and a `Form` for it:​> data Category = Web | Text | Math>     deriving (Bounded, Enum, Eq, Show)​> data Package = Package Text Version Category>     deriving (Show)​> packageForm :: Monad m => Form Text m Package> packageForm = Package>     <$> "name"     .: text Nothing>     <*> "version"  .: validate validateVersion (text (Just "0.0.0.1"))>     <*> "category" .: choice categories Nothing>   where>     categories = [(x, T.pack (show x)) | x <- [minBound .. maxBound]]​Composing forms---------------​A release has an author and a package. Let's use this to illustrate thecomposability of the digestive-functors library: we can reuse the forms we havewritten earlier on.​> data Release = Release User Package>     deriving (Show)​> releaseForm :: Monad m => Form Text m Release> releaseForm = Release>     <$> "author"  .: userForm>     <*> "package" .: packageForm​Views-----​As mentioned before, one of the advantages of using digestive-functors isseparation of forms and their actual HTML layout. In order to do this, we haveanother type, `View`.​We can get a `View` from a `Form` by supplying input. A `View` contains moreinformation than a `Form`, it has:​- the original form;- the input given by the user;- any errors that have occurred.​It is this view that we convert to HTML. For this tutorial, we use the[blaze-html] library, and some helpers from the `digestive-functors-blaze`library.​[blaze-html]: http://jaspervdj.be/blaze/​Let's write a view for the `User` form. As you can see, we here refer to thedifferent fields in the `userForm`. The `errorList` will generate a list oferrors for the `"mail"` field.​> userView :: View H.Html -> H.Html> userView view = do>     label     "name" view "Name: ">     inputText "name" view>     H.br>>     errorList "mail" view>     label     "mail" view "Email address: ">     inputText "mail" view>     H.br​Like forms, views are also composable: let's illustrate that by adding a viewfor the `releaseForm`, in which we reuse `userView`. In order to do this, wetake only the parts relevant to the author from the view by using `subView`. Wecan then pass the resulting view to our own `userView`.We have no special view code for `Package`, so we can just add that to`releaseView` as well. `childErrorList` will generate a list of errors for eachchild of the specified form. In this case, this means a list of errors from`"package.name"` and `"package.version"`. Note how we use `foo.bar` to refer tonested forms.​> releaseView :: View H.Html -> H.Html> releaseView view = do>     H.h2 "Author">     userView $ subView "author" view>>     H.h2 "Package">     childErrorList "package" view>>     label     "package.name" view "Name: ">     inputText "package.name" view>     H.br>>     label     "package.version" view "Version: ">     inputText "package.version" view>     H.br>>     label       "package.category" view "Category: ">     inputSelect "package.category" view>     H.br​The attentive reader might have wondered what the type parameter for `View` is:it is the `String`-like type used for e.g. error messages.But wait! We have    releaseForm :: Monad m => Form Text m Release    releaseView :: View H.Html -> H.Html... doesn't this mean that we need a `View Text` rather than a `View Html`?  Theanswer is yes -- but having `View Html` allows us to write these views moreeasily with the `digestive-functors-blaze` library. Fortunately, we will be ableto fix this using the `Functor` instance of `View`.    fmap :: Monad m => (v -> w) -> View v -> View wA backend---------To finish this tutorial, we need to be able to actually run this code. We needan HTTP server for that, and we use [Happstack] for this tutorial. The`digestive-functors-happstack` library gives about everything we need for this.[Happstack]: http://happstack.com/​> site :: Happstack.ServerPart Happstack.Response> site = do>     Happstack.decodeBody $ Happstack.defaultBodyPolicy "/tmp" 4096 4096 4096>     r <- runForm "test" releaseForm>     case r of>         (view, Nothing) -> do>             let view' = fmap H.toHtml view>             Happstack.ok $ Happstack.toResponse $>                 template $>                     form view' "/" $ do>                         releaseView view'>                         H.br>                         inputSubmit "Submit">         (_, Just release) -> Happstack.ok $ Happstack.toResponse $>             template $ do>                 css>                 H.h1 "Release received">                 H.p $ H.toHtml $ show release>> main :: IO ()> main = Happstack.simpleHTTP Happstack.nullConf site​Utilities---------​> template :: H.Html -> H.Html> template body = H.docTypeHtml $ do>     H.head $ do>         H.title "digestive-functors tutorial">         css>     H.body body> css :: H.Html> css = H.style ! A.type_ "text/css" $ do>     "label {width: 130px; float: left; clear: both}">     "ul.digestive-functors-error-list {">     "    color: red;">     "    list-style-type: none;">     "    padding-left: 0px;">     "}"    

MIME types defined: text/x-literate-haskell.

Parser configuration parameters recognized: base to set the base mode (defaults to "haskell").