Lucid

Clear to write, read and edit DSL for writing HTML

Intro

HTML terms in Lucid are written with a postfix ‘_’ to indicate data rather than code. Some examples:

p_, class_, table_, style_

See Lucid.Html5 for a complete list of Html5 combinators.

Plain text is written using the OverloadedStrings and ExtendedDefaultRules extensions, and is automatically escaped:

>>> "123 < 456" :: Html ()
123 &lt; 456

Elements nest by function application:

>>> table_ (tr_ (td_ (p_ "Hello, World!")))
<table><tr><td><p>Hello, World!</p></td></tr></table>

Elements are juxtaposed via monoidal append:

>>> p_ "hello" <> p_ "sup"
<p>hello</p><p>sup</p>

Or monadic sequencing:

>>> div_ (do p_ "hello"; p_ "sup")
<div><p>hello</p><p>sup</p></div>

Attributes are set using the with combinator:

>>> with p_ [class_ "brand"] "Lucid Inc"
<p class="brand">Lucid Inc</p>

Here is a fuller example of Lucid:

with table_ [rows_ "2"]
     (tr_ (do with td_ [class_ "top",colspan_ "2"]
                   (p_ "Hello, attributes!")
              td_ "yay!"))

For proper rendering you can easily run some HTML immediately with:

>>> renderText (p_ "Hello!")
> "<p>Hello!</p>"

>>> renderBS (with p_ [style_ "color:red"] "Hello!")
"<p style=\"color:red\">Hello!</p>"

For ease of use in GHCi, there is a Show instance, as demonstrated above.

renderText :: Html a -> Text

Render the HTML to a lazy Text.

This is a convenience function defined in terms of execHtmlT, runIdentity and toLazyByteString, and decodeUtf8. Check the source if you're interested in the lower-level behaviour.

renderBS :: Html a -> ByteString

Render the HTML to a lazy ByteString.

This is a convenience function defined in terms of execHtmlT, runIdentity and toLazyByteString. Check the source if you're interested in the lower-level behaviour.

renderTextT :: Monad m => HtmlT m a -> m Text

Render the HTML to a lazy Text, but in a monad.

This is a convenience function defined in terms of execHtmlT and toLazyByteString, and decodeUtf8. Check the source if you're interested in the lower-level behaviour.

renderBST :: Monad m => HtmlT m a -> m ByteString

Render the HTML to a lazy ByteString, but in a monad.

This is a convenience function defined in terms of execHtmlT and toLazyByteString. Check the source if you're interested in the lower-level behaviour.

Running

If the above rendering functions aren't suited for your purpose, you can run the monad directly and use the more low-level blaze Builder, which has a plethora of output modes in Blaze.ByteString.Builder.

execHtmlT

Arguments

:: Monad m

=> HtmlT m a

The HTML to generate.

-> m Builder

The a is discarded.

Build the HTML. Analogous to execState.

You might want to use this is if you want to do something with the raw Builder. Otherwise for simple cases you can just use renderText or renderBS.

evalHtmlT

Arguments

:: Monad m

=> HtmlT m a

HTML monad to evaluate.

-> m a

Ignore the HTML output and just return the value.

Evaluate the HTML to its return value. Analogous to evalState.

Use this if you want to ignore the HTML output of an action completely and just get the result.

For using with the Html type, you'll need runIdentity e.g.

>>> runIdentity (evalHtmlT (p_ "Hello!"))
()

runHtmlT :: HtmlT m a -> m (HashMap Text Text -> Builder -> Builder, a)

This is the low-level way to run the HTML transformer, finally returning an element builder and a value. You can pass mempty for both arguments for a top-level call. See evalHtmlT and execHtmlT for easier to use functions.

Combinators

Types

type Html = HtmlT Identity

Simple HTML builder type. Defined in terms of HtmlT. Check out that type for instance information.

Simple use-cases will just use this type. But if you want to transformer over Reader or something, you can go and use HtmlT.

Classes

class ToText a where

Used for attributes.

Methods

toText :: a -> Text

Instances

ToText String

ToText Text

class ToHtml a where

Can be converted to HTML.

Methods

toHtml :: Monad m => a -> HtmlT m ()

toHtmlRaw :: Monad m => a -> HtmlT m ()

Instances

ToHtml String

ToHtml Text

class Mixed a r where

Used for names that are mixed, e.g. style_.

Methods

mixed :: Text -> a -> r

Instances

(Monad m, (~) * a (HtmlT m r), (~) * r ()) => Mixed a (HtmlT m r)

HTML elements can be a mixed thing e.g. style_.

ToText a => Mixed a (Text, Text)

Attributes can be a mixed thing e.g. style_.

class With a where

With an element use these attributes.

Methods

with

Arguments

:: a

Some element, either Html () or Html () -> Html ().

-> [(Text, Text)]

-> a

With the given element(s), use the given attributes.

Instances

(Monad m, (~) * a ()) => With (HtmlT m a -> HtmlT m a)

For the contentful elements: div_

(Monad m, (~) * a ()) => With (HtmlT m a)

For the contentless elements: br_

Re-exports

module Lucid.Html5