A catHello World!
unit ``` As it stands, there are several problems with this library: * Creating HTML documents is difficult - every new element requires at least one record and one data constructor. * It is possible to represent invalid documents: * The developer might mistype the element name * The developer can associate an attribute with the wrong type of element * The developer can use a closed element when an open element is correct In the remainder of the chapter, we will apply certain techniques to solve these problems and turn our library into a usable domain-specific language for creating HTML documents. ## Smart Constructors The first technique we will apply is simple but can be very effective. Instead of exposing the representation of the data to the module's users, we can use the module exports list to hide the `Element`, `Content` and `Attribute` data constructors, and only export so-called *smart constructors*, which construct data which is known to be correct. Here is an example. First, we provide a convenience function for creating HTML elements: ```haskell element :: String -> Array Attribute -> Maybe (Array Content) -> Element element name attribs content = Element { name: name , attribs: attribs , content: content } ``` Next, we create smart constructors for those HTML elements we want our users to be able to create, by applying the `element` function: ```haskell a :: Array Attribute -> Array Content -> Element a attribs content = element "a" attribs (Just content) p :: Array Attribute -> Array Content -> Element p attribs content = element "p" attribs (Just content) img :: Array Attribute -> Element img attribs = element "img" attribs Nothing ``` Finally, we update the module exports list to only export those functions which are known to construct correct data structures: ```haskell module Data.DOM.Smart ( Element , Attribute(..) , Content(..) , a , p , img , render ) where ``` The module exports list is provided immediately after the module name inside parentheses. Each module export can be one of three types: * A value (or function), indicated by the name of the value, * A type class, indicated by the name of the class, * A type constructor and any associated data constructors, indicated by the name of the type followed by a parenthesized list of exported data constructors. Here, we export the `Element` *type*, but we do not export its data constructors. If we did, the user would be able to construct invalid HTML elements. In the case of the `Attribute` and `Content` types, we still export all of the data constructors (indicated by the symbol `..` in the exports list). We will apply the technique of smart constructors to these types shortly. Notice that we have already made some big improvements to our library: * It is impossible to represent HTML elements with invalid names (of course, we are restricted to the set of element names provided by the library). * Closed elements cannot contain content by construction. We can apply this technique to the `Content` type very easily. We simply remove the data constructors for the `Content` type from the exports list, and provide the following smart constructors: ```haskell text :: String -> Content text = TextContent elem :: Element -> Content elem = ElementContent ``` Let's apply the same technique to the `Attribute` type. First, we provide a general-purpose smart constructor for attributes. Here is a first attempt: ```haskell attribute :: String -> String -> Attribute attribute key value = Attribute { key: key , value: value } infix 4 attribute as := ``` This representation suffers from the same problem as the original `Element` type - it is possible to represent attributes which do not exist or whose names were entered incorrectly. To solve this problem, we can create a newtype which represents attribute names: ```haskell newtype AttributeKey = AttributeKey String ``` With that, we can modify our operator as follows: ```haskell attribute :: AttributeKey -> String -> Attribute attribute (AttributeKey key) value = Attribute { key: key , value: value } ``` If we do not export the `AttributeKey` data constructor, then the user has no way to construct values of type `AttributeKey` other than by using functions we explicitly export. Here are some examples: ```haskell href :: AttributeKey href = AttributeKey "href" _class :: AttributeKey _class = AttributeKey "class" src :: AttributeKey src = AttributeKey "src" width :: AttributeKey width = AttributeKey "width" height :: AttributeKey height = AttributeKey "height" ``` Here is the final exports list for our new module. Note that we no longer export any data constructors directly: ```haskell module Data.DOM.Smart ( Element , Attribute , Content , AttributeKey , a , p , img , href , _class , src , width , height , attribute, (:=) , text , elem , render ) where ``` If we try this new module in PSCi, we can already see massive improvements in the conciseness of the user code: ``` $ spago repl > import Prelude > import Data.DOM.Smart > import Control.Monad.Eff.Console > log $ render $ p [ _class := "main" ] [ text "Hello World!" ]Hello World!
unit ``` Note, however, that no changes had to be made to the `render` function, because the underlying data representation never changed. This is one of the benefits of the smart constructors approach - it allows us to separate the internal data representation for a module from the representation which is perceived by users of its external API. ## Exercises 1. (Easy) Use the `Data.DOM.Smart` module to experiment by creating new HTML documents using `render`. 2. (Medium) Some HTML attributes such as `checked` and `disabled` do not require values, and may be rendered as *empty attributes*: ```markup ``` Modify the representation of an `Attribute` to take empty attributes into account. Write a function which can be used in place of `attribute` or `:=` to add an empty attribute to an element. ## Phantom Types To motivate the next technique, consider the following code: ``` > log $ render $ img [ src := "cat.jpg" , width := "foo" , height := "bar" ]
unit
```
The problem here is that we have provided string values for the `width` and `height` attributes, where we should only be allowed to provide numeric values in units of pixels or percentage points.
To solve this problem, we can introduce a so-called *phantom type* argument to our `AttributeKey` type:
```haskell
newtype AttributeKey a = AttributeKey String
```
The type variable `a` is called a *phantom type* because there are no values of type `a` involved in the right-hand side of the definition. The type `a` only exists to provide more information at compile-time. Any value of type `AttributeKey a` is simply a string at runtime, but at compile-time, the type of the value tells us the desired type of the values associated with this key.
We can modify the type of our `attribute` function to take the new form of `AttributeKey` into account:
```haskell
attribute :: forall a. IsValue a => AttributeKey a -> a -> Attribute
attribute (AttributeKey key) value = Attribute
{ key: key
, value: toValue value
}
```
Here, the phantom type argument `a` is used to ensure that the attribute key and attribute value have compatible types. Since the user cannot create values of type `AttributeKey a` directly (only via the constants we provide in the library), every attribute will be correct by construction.
Note that the `IsValue` constraint ensures that whatever value type we associate to a key, its values can be converted to strings and displayed in the generated HTML. The `IsValue` type class is defined as follows:
```haskell
class IsValue a where
toValue :: a -> String
```
We also provide type class instances for the `String` and `Int` types:
```haskell
instance stringIsValue :: IsValue String where
toValue = id
instance intIsValue :: IsValue Int where
toValue = show
```
We also have to update our `AttributeKey` constants so that their types reflect the new type parameter:
```haskell
href :: AttributeKey String
href = AttributeKey "href"
_class :: AttributeKey String
_class = AttributeKey "class"
src :: AttributeKey String
src = AttributeKey "src"
width :: AttributeKey Int
width = AttributeKey "width"
height :: AttributeKey Int
height = AttributeKey "height"
```
Now we find it is impossible to represent these invalid HTML documents, and we are forced to use numbers to represent the `width` and `height` attributes instead:
```
> import Prelude
> import Data.DOM.Phantom
> import Control.Monad.Eff.Console
> :paste
… log $ render $ img
… [ src := "cat.jpg"
… , width := 100
… , height := 200
… ]
… ^D
unit
```
## Exercises
1. (Easy) Create a data type which represents either pixel or percentage lengths. Write an instance of `IsValue` for your type. Modify the `width` and `height` attributes to use your new type.
2. (Difficult) By defining type-level representatives for the Boolean values `true` and `false`, we can use a phantom type to encode whether an `AttributeKey` represents an *empty attribute* such as `disabled` or `checked`.
```haskell
data True
data False
```
Modify your solution to the previous exercise to use a phantom type to prevent the user from using the `attribute` operator with an empty attribute.
## The Free Monad
In our final set of modifications to our API, we will use a construction called the *free monad* to turn our `Content` type into a monad, enabling do notation. This will allow us to structure our HTML documents in a form in which the nesting of elements becomes clearer - instead of this:
```haskell
p [ _class := "main" ]
[ elem $ img
[ src := "cat.jpg"
, width := 100
, height := 200
]
, text "A cat"
]
```
we will be able to write this:
```haskell
p [ _class := "main" ] $ do
elem $ img
[ src := "cat.jpg"
, width := 100
, height := 200
]
text "A cat"
```
However, do notation is not the only benefit of a free monad. The free monad allows us to separate the *representation* of our monadic actions from their *interpretation*, and even support *multiple interpretations* of the same actions.
The `Free` monad is defined in the `free` library, in the `Control.Monad.Free` module. We can find out some basic information about it using PSCi, as follows:
```
> import Control.Monad.Free
> :kind Free
(Type -> Type) -> Type -> Type
```
The kind of `Free` indicates that it takes a type constructor as an argument, and returns another type constructor. In fact, the `Free` monad can be used to turn any `Functor` into a `Monad`!
We begin by defining the *representation* of our monadic actions. To do this, we need to create a `Functor` with one data constructor for each monadic action we wish to support. In our case, our two monadic actions will be `elem` and `text`. In fact, we can simply modify our `Content` type as follows:
```haskell
data ContentF a
= TextContent String a
| ElementContent Element a
instance functorContentF :: Functor ContentF where
map f (TextContent s x) = TextContent s (f x)
map f (ElementContent e x) = ElementContent e (f x)
```
Here, the `ContentF` type constructor looks just like our old `Content` data type - however, it now takes a type argument `a`, and each data constructor has been modified to take a value of type `a` as an additional argument. The `Functor` instance simply applies the function `f` to the value of type `a` in each data constructor.
With that, we can define our new `Content` monad as a type synonym for the `Free` monad, which we construct by using our `ContentF` type constructor as the first type argument:
```haskell
type Content = Free ContentF
```
Instead of a type synonym, we might use a `newtype` to avoid exposing the internal representation of our library to our users - by hiding the `Content` data constructor, we restrict our users to only using the monadic actions we provide.
Because `ContentF` is a `Functor`, we automatically get a `Monad` instance for `Free ContentF`.
We have to modify our `Element` data type slightly to take account of the new type argument on `Content`. We will simply require that the return type of our monadic computations be `Unit`:
```haskell
newtype Element = Element
{ name :: String
, attribs :: Array Attribute
, content :: Maybe (Content Unit)
}
```
In addition, we have to modify our `elem` and `text` functions, which become our new monadic actions for the `Content` monad. To do this, we can use the `liftF` function, provided by the `Control.Monad.Free` module. Here is its type:
```haskell
liftF :: forall f a. f a -> Free f a
```
`liftF` allows us to construct an action in our free monad from a value of type `f a` for some type `a`. In our case, we can simply use the data constructors of our `ContentF` type constructor directly:
```haskell
text :: String -> Content Unit
text s = liftF $ TextContent s unit
elem :: Element -> Content Unit
elem e = liftF $ ElementContent e unit
```
Some other routine modifications have to be made, but the interesting changes are in the `render` function, where we have to *interpret* our free monad.
## Interpreting the Monad
The `Control.Monad.Free` module provides a number of functions for interpreting a computation in a free monad:
```haskell
runFree
:: forall f a
. Functor f
=> (f (Free f a) -> Free f a)
-> Free f a
-> a
runFreeM
:: forall f m a
. (Functor f, MonadRec m)
=> (f (Free f a) -> m (Free f a))
-> Free f a
-> m a
```
The `runFree` function is used to compute a *pure* result. The `runFreeM` function allows us to use a monad to interpret the actions of our free monad.
*Note*: Technically, we are restricted to using monads `m` which satisfy the stronger `MonadRec` constraint. In practice, this means that we don't need to worry about stack overflow, since `m` supports safe *monadic tail recursion*.
First, we have to choose a monad in which we can interpret our actions. We will use the `Writer String` monad to accumulate a HTML string as our result.
Our new `render` method starts by delegating to a helper function, `renderElement`, and using `execWriter` to run our computation in the `Writer` monad:
```haskell
render :: Element -> String
render = execWriter <<< renderElement
```
`renderElement` is defined in a where block:
```haskell
where
renderElement :: Element -> Writer String Unit
renderElement (Element e) = do
```
The definition of `renderElement` is straightforward, using the `tell` action from the `Writer` monad to accumulate several small strings:
```haskell
tell "<"
tell e.name
for_ e.attribs $ \x -> do
tell " "
renderAttribute x
renderContent e.content
```
Next, we define the `renderAttribute` function, which is equally simple:
```haskell
where
renderAttribute :: Attribute -> Writer String Unit
renderAttribute (Attribute x) = do
tell x.key
tell "=\""
tell x.value
tell "\""
```
The `renderContent` function is more interesting. Here, we use the `runFreeM` function to interpret the computation inside the free monad, delegating to a helper function, `renderContentItem`:
```haskell
renderContent :: Maybe (Content Unit) -> Writer String Unit
renderContent Nothing = tell " />"
renderContent (Just content) = do
tell ">"
runFreeM renderContentItem content
tell ""
```
The type of `renderContentItem` can be deduced from the type signature of `runFreeM`. The functor `f` is our type constructor `ContentF`, and the monad `m` is the monad in which we are interpreting the computation, namely `Writer String`. This gives the following type signature for `renderContentItem`:
```haskell
renderContentItem :: ContentF (Content Unit) -> Writer String (Content Unit)
```
We can implement this function by simply pattern matching on the two data constructors of `ContentF`:
```haskell
renderContentItem (TextContent s rest) = do
tell s
pure rest
renderContentItem (ElementContent e rest) = do
renderElement e
pure rest
```
In each case, the expression `rest` has the type `Content Unit`, and represents the remainder of the interpreted computation. We can complete each case by returning the `rest` action.
That's it! We can test our new monadic API in PSCi, as follows:
```
> import Prelude
> import Data.DOM.Free
> import Control.Monad.Eff.Console
> :paste
… log $ render $ p [] $ do
… elem $ img [ src := "cat.jpg" ]
… text "A cat"
… ^D
A cat