Lucid.Base

Base types and combinators.

Rendering

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.

renderToFile :: FilePath -> Html a -> IO ()

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.

Running

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.

Commute inner m to the front.

This is useful when you have impure HTML generation, e.g. using StateT. Recall, there is `MonadState s HtmlT` instance.

exampleHtml :: MonadState Int m => HtmlT m ()
exampleHtml = ul_ $ replicateM_ 5 $ do
  x <- get
  put (x + 1)
  li_ $ toHtml $ show x

exampleHtml' :: Monad m => HtmlT m ()
exampleHtml' = evalState (commuteHtmlT exampleHtml) 1

commuteHtmlT :: (Functor m, Monad n) => HtmlT m a -- ^ unpurely generated HTML -> m (HtmlT n a) -- ^ Commuted monads. Note: n can be Identity commuteHtmlT (HtmlT xs) = fmap (HtmlT . return) xs

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!"))
()

Since: 2.9.9

runHtmlT :: Monad m => HtmlT m a -> m (Builder, a)

Run the HtmlT transformer.

relaxHtmlT

Arguments

:: Monad m

=> HtmlT Identity a

The HTML generated purely.

-> HtmlT m a

Same HTML accessible in a polymorphic context.

Generalize the underlying monad.

Some builders are happy to deliver results in a pure underlying monad, here Identity, but have trouble maintaining the polymorphic type. This utility generalizes from Identity.

Since: 2.9.6

Combinators

makeElement

Arguments

:: Monad m

=> Text

Name.

-> [Attributes]

-> HtmlT m a

Children HTML.

-> HtmlT m a

A parent element.

Make an HTML builder.

makeElementNoEnd

Arguments

:: Monad m

=> Text

Name.

-> [Attributes]

-> HtmlT m ()

A parent element.

Make an HTML builder for elements which have no ending tag.

makeAttributes

Arguments

:: Text

Attribute name.

-> Text

Attribute value.

-> Attributes

Make a set of attributes.

makeAttributesRaw

Arguments

:: Text

Attribute name.

-> Text

Attribute value.

-> Attributes

Make a set of unescaped attributes.

data Attributes

A list of attributes.

Instances

Semigroup Attributes

Defined in Lucid.Base

Methods

(<>) :: Attributes -> Attributes -> Attributes

sconcat :: NonEmpty Attributes -> Attributes

stimes :: Integral b => b -> Attributes -> Attributes

Monoid Attributes

Defined in Lucid.Base

Methods

mempty :: Attributes

mappend :: Attributes -> Attributes -> Attributes

mconcat :: [Attributes] -> Attributes

TermRaw Text Attributes

Some termRaws (like style_, title_) can be used for attributes as well as elements.

Defined in Lucid.Base

Methods

termRaw :: Text -> Text -> Attributes

Term Text Attributes

Some terms (like style_, title_) can be used for attributes as well as elements.

Defined in Lucid.Base

Methods

term :: Text -> Text -> Attributes

(Monad m, ToHtml f, a ~ ()) => TermRaw [Attributes] (f -> HtmlT m a)

Given attributes, expect more child input.

Defined in Lucid.Base

Methods

termRaw :: Text -> [Attributes] -> f -> HtmlT m a

(Monad m, f ~ HtmlT m a) => Term [Attributes] (f -> HtmlT m a)

Given attributes, expect more child input.

Defined in Lucid.Base

Methods

term :: Text -> [Attributes] -> f -> HtmlT m a

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.

data HtmlT m a

A monad transformer that generates HTML. Use the simpler Html type if you don't want to transform over some other monad.

Instances

MonadTrans HtmlT

Defined in Lucid.Base

Methods

lift :: Monad m => m a -> HtmlT m a

MonadState s m => MonadState s (HtmlT m)

Since: 2.9.7

Defined in Lucid.Base

Methods

get :: HtmlT m s

put :: s -> HtmlT m ()

state :: (s -> (a, s)) -> HtmlT m a

MonadReader r m => MonadReader r (HtmlT m)

Since: 2.9.7

Defined in Lucid.Base

Methods

ask :: HtmlT m r

local :: (r -> r) -> HtmlT m a -> HtmlT m a

reader :: (r -> a) -> HtmlT m a

(Monad m, a ~ ()) => TermRaw Text (HtmlT m a)

Given children immediately, just use that and expect no attributes.

Defined in Lucid.Base

Methods

termRaw :: Text -> Text -> HtmlT m a

Monad m => Monad (HtmlT m)

Defined in Lucid.Base

Methods

(>>=) :: HtmlT m a -> (a -> HtmlT m b) -> HtmlT m b

(>>) :: HtmlT m a -> HtmlT m b -> HtmlT m b

return :: a -> HtmlT m a

Functor m => Functor (HtmlT m)

Defined in Lucid.Base

Methods

fmap :: (a -> b) -> HtmlT m a -> HtmlT m b

(<$) :: a -> HtmlT m b -> HtmlT m a

MonadFix m => MonadFix (HtmlT m)

Defined in Lucid.Base

Methods

mfix :: (a -> HtmlT m a) -> HtmlT m a

Monad m => Applicative (HtmlT m)

Defined in Lucid.Base

Methods

pure :: a -> HtmlT m a

(<*>) :: HtmlT m (a -> b) -> HtmlT m a -> HtmlT m b

liftA2 :: (a -> b -> c) -> HtmlT m a -> HtmlT m b -> HtmlT m c

(*>) :: HtmlT m a -> HtmlT m b -> HtmlT m b

(<*) :: HtmlT m a -> HtmlT m b -> HtmlT m a

MonadIO m => MonadIO (HtmlT m)

If you want to use IO in your HTML generation.

Defined in Lucid.Base

Methods

liftIO :: IO a -> HtmlT m a

(Monad m, ToHtml f, a ~ ()) => TermRaw [Attributes] (f -> HtmlT m a)

Given attributes, expect more child input.

Defined in Lucid.Base

Methods

termRaw :: Text -> [Attributes] -> f -> HtmlT m a

(Monad m, f ~ HtmlT m a) => Term [Attributes] (f -> HtmlT m a)

Given attributes, expect more child input.

Defined in Lucid.Base

Methods

term :: Text -> [Attributes] -> f -> HtmlT m a

m ~ Identity => Show (HtmlT m a)

Just calls renderText.

Defined in Lucid.Base

Methods

showsPrec :: Int -> HtmlT m a -> ShowS

show :: HtmlT m a -> String

showList :: [HtmlT m a] -> ShowS

(Monad m, a ~ ()) => IsString (HtmlT m a)

We pack it via string. Could possibly encode straight into a builder. That might be faster.

Defined in Lucid.Base

Methods

fromString :: String -> HtmlT m a

(a ~ (), Monad m) => Semigroup (HtmlT m a)

Since: 2.9.7

Defined in Lucid.Base

Methods

(<>) :: HtmlT m a -> HtmlT m a -> HtmlT m a

sconcat :: NonEmpty (HtmlT m a) -> HtmlT m a

stimes :: Integral b => b -> HtmlT m a -> HtmlT m a

(a ~ (), Monad m) => Monoid (HtmlT m a)

Monoid is right-associative, a la the Builder in it.

Defined in Lucid.Base

Methods

mempty :: HtmlT m a

mappend :: HtmlT m a -> HtmlT m a -> HtmlT m a

mconcat :: [HtmlT m a] -> HtmlT m a

(a ~ (), m ~ Identity) => ToHtml (HtmlT m a)

Since: 2.9.8

Defined in Lucid.Base

Methods

toHtml :: forall (m0 :: Type -> Type). Monad m0 => HtmlT m a -> HtmlT m0 ()

toHtmlRaw :: forall (m0 :: Type -> Type). Monad m0 => HtmlT m a -> HtmlT m0 ()

Monad m => Term (HtmlT m a) (HtmlT m a)

Given children immediately, just use that and expect no attributes.

Defined in Lucid.Base

Methods

term :: Text -> HtmlT m a -> HtmlT m a

Classes

class Term arg result | result -> arg where

Used to construct HTML terms.

Simplest use: p_ = term "p" yields p_.

Very overloaded for three cases:

• The first case is the basic arg of [(Text,Text)] which will return a function that wants children.
• The second is an arg which is HtmlT m (), in which case the term accepts no attributes and just the children are used for the element.
• Finally, this is also used for overloaded attributes, like style_ or title_. If a return type of (Text,Text) is inferred then an attribute will be made.

The instances look intimidating but actually the constraints make it very general so that type inference works well even in the presence of things like OverloadedLists and such.

Methods

term

Arguments

:: Text

Name of the element or attribute.

-> arg

Either an attribute list or children.

-> result

Result: either an element or an attribute.

Used for constructing elements e.g. term "p" yields p_.

Instances

Term Text Attributes

Some terms (like style_, title_) can be used for attributes as well as elements.

Defined in Lucid.Base

Methods

term :: Text -> Text -> Attributes

(Monad m, f ~ HtmlT m a) => Term [Attributes] (f -> HtmlT m a)

Given attributes, expect more child input.

Defined in Lucid.Base

Methods

term :: Text -> [Attributes] -> f -> HtmlT m a

Monad m => Term (HtmlT m a) (HtmlT m a)

Given children immediately, just use that and expect no attributes.

Defined in Lucid.Base

Methods

term :: Text -> HtmlT m a -> HtmlT m a

class TermRaw arg result | result -> arg where

Same as the Term class, but will not HTML escape its children. Useful for elements like style_ or script_.

Methods

termRaw

Arguments

:: Text

Name of the element or attribute.

-> arg

Either an attribute list or children.

-> result

Result: either an element or an attribute.

Used for constructing elements e.g. termRaw "p" yields p_.

Instances

TermRaw Text Attributes

Some termRaws (like style_, title_) can be used for attributes as well as elements.

Defined in Lucid.Base

Methods

termRaw :: Text -> Text -> Attributes

(Monad m, a ~ ()) => TermRaw Text (HtmlT m a)

Given children immediately, just use that and expect no attributes.

Defined in Lucid.Base

Methods

termRaw :: Text -> Text -> HtmlT m a

(Monad m, ToHtml f, a ~ ()) => TermRaw [Attributes] (f -> HtmlT m a)

Given attributes, expect more child input.

Defined in Lucid.Base

Methods

termRaw :: Text -> [Attributes] -> f -> HtmlT m a

class ToHtml a where

Can be converted to HTML.

Methods

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

Convert to HTML, doing HTML escaping.

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

Convert to HTML without any escaping.

Instances

ToHtml String

Defined in Lucid.Base

Methods

toHtml :: forall (m :: Type -> Type). Monad m => String -> HtmlT m ()

toHtmlRaw :: forall (m :: Type -> Type). Monad m => String -> HtmlT m ()

ToHtml ByteString

This instance requires the ByteString to contain UTF-8 encoded text, for the toHtml method. The toHtmlRaw method doesn't care, but the overall HTML rendering methods in this module assume UTF-8.

Since: 2.9.5

Defined in Lucid.Base

Methods

toHtml :: forall (m :: Type -> Type). Monad m => ByteString -> HtmlT m ()

toHtmlRaw :: forall (m :: Type -> Type). Monad m => ByteString -> HtmlT m ()

ToHtml ByteString

This instance requires the ByteString to contain UTF-8 encoded text, for the toHtml method. The toHtmlRaw method doesn't care, but the overall HTML rendering methods in this module assume UTF-8.

Since: 2.9.5

Defined in Lucid.Base

Methods

toHtml :: forall (m :: Type -> Type). Monad m => ByteString -> HtmlT m ()

toHtmlRaw :: forall (m :: Type -> Type). Monad m => ByteString -> HtmlT m ()

ToHtml Text

Defined in Lucid.Base

Methods

toHtml :: forall (m :: Type -> Type). Monad m => Text -> HtmlT m ()

toHtmlRaw :: forall (m :: Type -> Type). Monad m => Text -> HtmlT m ()

ToHtml Text

Defined in Lucid.Base

Methods

toHtml :: forall (m :: Type -> Type). Monad m => Text -> HtmlT m ()

toHtmlRaw :: forall (m :: Type -> Type). Monad m => Text -> HtmlT m ()

(a ~ (), m ~ Identity) => ToHtml (HtmlT m a)

Since: 2.9.8

Defined in Lucid.Base

Methods

toHtml :: forall (m0 :: Type -> Type). Monad m0 => HtmlT m a -> HtmlT m0 ()

toHtmlRaw :: forall (m0 :: Type -> Type). Monad m0 => HtmlT m a -> HtmlT m0 ()