Spaces:
Running
Running
| <title>CodeMirror: Haskell-literate mode</title> | |
| <meta charset="utf-8"/> | |
| <link rel=stylesheet href="../../doc/docs.css"> | |
| <link rel="stylesheet" href="../../lib/codemirror.css"> | |
| <script src="../../lib/codemirror.js"></script> | |
| <script src="haskell-literate.js"></script> | |
| <script src="../haskell/haskell.js"></script> | |
| <style>.CodeMirror { | |
| border-top : 1px solid #DDDDDD; | |
| border-bottom : 1px solid #DDDDDD; | |
| }</style> | |
| <div id=nav> | |
| <a href="http://codemirror.net"><h1>CodeMirror</h1><img id=logo | |
| src="../../doc/logo.png"></a> | |
| <ul> | |
| <li><a href="../../index.html">Home</a> | |
| <li><a href="../../doc/manual.html">Manual</a> | |
| <li><a href="https://github.com/codemirror/codemirror">Code</a> | |
| </ul> | |
| <ul> | |
| <li><a href="../index.html">Language modes</a> | |
| <li><a class=active href="#">Haskell-literate</a> | |
| </ul> | |
| </div> | |
| <article> | |
| <h2>Haskell literate mode</h2> | |
| <form> | |
| <textarea id="code" name="code"> | |
| > {-# 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;" | |
| > "}" | |
| </textarea> | |
| </form> | |
| <p><strong>MIME types | |
| defined:</strong> <code>text/x-literate-haskell</code>.</p> | |
| <p>Parser configuration parameters recognized: <code>base</code> to | |
| set the base mode (defaults to <code>"haskell"</code>).</p> | |
| <script> | |
| var editor = CodeMirror.fromTextArea(document.getElementById("code"), {mode: "haskell-literate"}); | |
| </script> | |
| </article> | |