lucid-2.9.2: Clear to write, read and edit DSL for HTML

Safe HaskellNone
LanguageHaskell98

Lucid.Base

Contents

Description

Base types and combinators.

Synopsis

Rendering

renderText :: Html a -> Text Source

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 Source

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 Source

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 Source

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 () Source

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 Source

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 Source

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, a) Source

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

Combinators

makeElement Source

Arguments

:: Monad m 
=> Text

Name.

-> HtmlT m a

Children HTML.

-> HtmlT m a

A parent element.

Make an HTML builder.

makeElementNoEnd Source

Arguments

:: Monad m 
=> Text

Name.

-> HtmlT m ()

A parent element.

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

makeXmlElementNoEnd Source

Arguments

:: Monad m 
=> Text

Name.

-> HtmlT m ()

A parent element.

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

makeAttribute Source

Arguments

:: Text

Attribute name.

-> Text

Attribute value.

-> Attribute 

Make an attribute builder.

Types

type Html = HtmlT Identity Source

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 Source

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

Used for lift.

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

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

Monad m => Monad (HtmlT m)

Basically acts like Writer.

Monad m => Functor (HtmlT m)

Just re-uses Monad.

Monad m => Applicative (HtmlT m)

Based on the monad instance.

MonadIO m => MonadIO (HtmlT m)

If you want to use IO in your HTML generation.

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

Given attributes, expect more child input.

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

Given attributes, expect more child input.

(~) (* -> *) m Identity => Show (HtmlT m a)

Just calls renderText.

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

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

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

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

Monad m => With (HtmlT m a -> HtmlT m a)

For the contentful elements: div_

Monad m => With (HtmlT m a)

For the contentless elements: br_

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

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

data Attribute Source

A simple attribute. Don't use the constructor, use makeAttribute.

Constructors

Attribute !Text !Text 

Instances

Eq Attribute 
Show Attribute 
Hashable Attribute 
TermRaw Text Attribute

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

Term Text Attribute

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

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

Given attributes, expect more child input.

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

Given attributes, expect more child input.

Classes

class Term arg result | result -> arg where Source

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.

Minimal complete definition

termWith

Methods

term Source

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_.

termWith Source

Arguments

:: Text

Name.

-> [Attribute]

Attribute transformer.

-> arg

Some argument.

-> result

Result: either an element or an attribute.

Use this if you want to make an element which inserts some pre-prepared attributes into the element.

Instances

Term Text Attribute

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

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

Given attributes, expect more child input.

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

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

class TermRaw arg result | result -> arg where Source

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

Minimal complete definition

termRawWith

Methods

termRaw Source

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_.

termRawWith Source

Arguments

:: Text

Name.

-> [Attribute]

Attribute transformer.

-> arg

Some argument.

-> result

Result: either an element or an attribute.

Use this if you want to make an element which inserts some pre-prepared attributes into the element.

Instances

TermRaw Text Attribute

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

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

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

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

Given attributes, expect more child input.

class ToHtml a where Source

Can be converted to HTML.

Methods

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

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

class With a where Source

With an element use these attributes. An overloaded way of adding attributes either to an element accepting attributes-and-children or one that just accepts attributes. See the two instances.

Methods

with Source

Arguments

:: a

Some element, either Html a or Html a -> Html a.

-> [Attribute] 
-> a 

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

Instances

Monad m => With (HtmlT m a -> HtmlT m a)

For the contentful elements: div_

Monad m => With (HtmlT m a)

For the contentless elements: br_