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

Safe Haskell | None
Language | Haskell2010

Lucid.Base

Contents

- Rendering
- Running
- Combinators
- Types
- Classes

Description

Base types and combinators.

Synopsis

- renderText :: Html a -> Text
- renderBS :: Html a -> ByteString
- renderTextT :: Monad m => HtmlT m a -> m Text
- renderBST :: Monad m => HtmlT m a -> m ByteString
- renderToFile :: FilePath -> Html a -> IO ()
- execHtmlT :: Monad m => HtmlT m a -> m Builder
- evalHtmlT :: Monad m => HtmlT m a -> m a
- runHtmlT :: HtmlT m a -> m (Seq Attribute -> Builder, a)
- relaxHtmlT :: forall (m :: Type -> Type) a. Monad m => HtmlT Identity a -> HtmlT m a
- commuteHtmlT :: forall m (n :: Type -> Type) a. (Functor m, Monad n) => HtmlT m a -> m (HtmlT n a)
- makeElement :: forall (m :: Type -> Type) a. Functor m => Text -> HtmlT m a -> HtmlT m a
- makeElementNoEnd :: forall (m :: Type -> Type). Applicative m => Text -> HtmlT m ()
- makeXmlElementNoEnd :: forall (m :: Type -> Type). Applicative m => Text -> HtmlT m ()
- makeAttribute :: Text -> Text -> Attribute
- type Html = HtmlT Identity
- newtype HtmlT (m :: Type -> Type) a = HtmlT (m (Seq Attribute -> Builder, a))
- data Attribute = Attribute !Text !Text
- class Term arg result | result -> arg where
  - term :: Text -> arg -> result
  - termWith :: Text -> [Attribute] -> arg -> result
- class TermRaw arg result | result -> arg where
  - termRaw :: Text -> arg -> result
  - termRawWith :: Text -> [Attribute] -> arg -> result
- class ToHtml a where
  - toHtml :: forall (m :: Type -> Type). Monad m => a -> HtmlT m ()
  - toHtmlRaw :: forall (m :: Type -> Type). Monad m => a -> HtmlT m ()
- class With a where
  - with :: a -> [Attribute] -> a

# 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 (Seq Attribute -> 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.

relaxHtmlT Source #

Arguments

:: forall (m :: Type -> Type) a. 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

commuteHtmlT Source #

Arguments

:: forall m (n :: Type -> Type) a. (Functor m, Monad n) |
=> HtmlT m a | unpurely generated HTML
-> m (HtmlT n a) | Commuted monads. Note: `n` can be `Identity`

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

Since: 2.9.9

# Combinators

makeElement Source #

Arguments

:: forall (m :: Type -> Type) a. Functor m |
=> Text | Name.
-> HtmlT m a | Children HTML.
-> HtmlT m a | A parent element.

Make an HTML builder.

makeElementNoEnd Source #

Arguments

:: forall (m :: Type -> Type). Applicative m |
=> Text | Name.
-> HtmlT m () | A parent element.

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

makeXmlElementNoEnd Source #

Arguments

:: forall (m :: Type -> Type). Applicative 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`.

newtype HtmlT (m :: Type -> Type) a Source #

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

Don't rely on the internal representation of this type. Use the monad and functor classes.

Constructors

HtmlT (m (Seq Attribute -> Builder, a)) |

#### Instances

Instances details

MonadTrans HtmlT Source # | Used for `lift`.
Instance details Defined in Lucid.Base Methods lift :: Monad m => m a -> HtmlT m a Source #
MFunctor HtmlT Source # | Since: 2.9.5
Instance details Defined in Lucid.Base Methods hoist :: Monad m => (forall a. m a -> n a) -> HtmlT m b -> HtmlT n b Source #
MonadError e m => MonadError e (HtmlT m) Source # | Since: 2.9.9
Instance details Defined in Lucid.Base Methods throwError :: e -> HtmlT m a Source # catchError :: HtmlT m a -> (e -> HtmlT m a) -> HtmlT m a Source #
MonadReader r m => MonadReader r (HtmlT m) Source # | Since: 2.9.7
Instance details Defined in Lucid.Base Methods ask :: HtmlT m r Source # local :: (r -> r) -> HtmlT m a -> HtmlT m a Source # reader :: (r -> a) -> HtmlT m a Source #
MonadState s m => MonadState s (HtmlT m) Source # | Since: 2.9.7
Instance details Defined in Lucid.Base Methods get :: HtmlT m s Source # put :: s -> HtmlT m () Source # state :: (s -> (a, s)) -> HtmlT m a Source #
MonadWriter w m => MonadWriter w (HtmlT m) Source # | Since: 2.9.9
Instance details Defined in Lucid.Base Methods writer :: (a, w) -> HtmlT m a Source # tell :: w -> HtmlT m () Source # listen :: HtmlT m a -> HtmlT m (a, w) Source # pass :: HtmlT m (a, w -> w) -> HtmlT m a Source #
(Monad m, a ~ ()) => TermRaw Text (HtmlT m a) Source # | Given children immediately, just use that and expect no attributes.
Instance details Defined in Lucid.Base Methods termRaw :: Text -> Text -> HtmlT m a Source # termRawWith :: Text -> [Attribute] -> Text -> HtmlT m a Source #
MonadIO m => MonadIO (HtmlT m) Source # | If you want to use IO in your HTML generation.
Instance details Defined in Lucid.Base Methods liftIO :: IO a -> HtmlT m a Source #
Applicative m => Applicative (HtmlT m) Source # | Based on the monad instance.
Instance details Defined in Lucid.Base Methods pure :: a -> HtmlT m a Source # (<*>) :: HtmlT m (a -> b) -> HtmlT m a -> HtmlT m b Source # liftA2 :: (a -> b -> c) -> HtmlT m a -> HtmlT m b -> HtmlT m c Source # (*>) :: HtmlT m a -> HtmlT m b -> HtmlT m b Source # (<*) :: HtmlT m a -> HtmlT m b -> HtmlT m a Source #
Functor m => Functor (HtmlT m) Source # | Just re-uses Monad.
Instance details Defined in Lucid.Base Methods fmap :: (a -> b) -> HtmlT m a -> HtmlT m b Source # (<$) :: a -> HtmlT m b -> HtmlT m a Source #
Monad m => Monad (HtmlT m) Source # | Basically acts like Writer.
Instance details Defined in Lucid.Base Methods (>>=) :: HtmlT m a -> (a -> HtmlT m b) -> HtmlT m b Source # (>>) :: HtmlT m a -> HtmlT m b -> HtmlT m b Source # return :: a -> HtmlT m a Source #
MonadFix m => MonadFix (HtmlT m) Source # |
Instance details Defined in Lucid.Base Methods mfix :: (a -> HtmlT m a) -> HtmlT m a Source #
(Applicative m, f ~ HtmlT m a) => Term [Attribute] (f -> HtmlT m a) Source # | Given attributes, expect more child input.
Instance details Defined in Lucid.Base Methods term :: Text -> [Attribute] -> f -> HtmlT m a Source # termWith :: Text -> [Attribute] -> [Attribute] -> f -> HtmlT m a Source #
(Monad m, ToHtml f, a ~ ()) => TermRaw [Attribute] (f -> HtmlT m a) Source # | Given attributes, expect more child input.
Instance details Defined in Lucid.Base Methods termRaw :: Text -> [Attribute] -> f -> HtmlT m a Source # termRawWith :: Text -> [Attribute] -> [Attribute] -> f -> HtmlT m a Source #
(a ~ (), Applicative m) => Monoid (HtmlT m a) Source # | Monoid is right-associative, a la the `Builder` in it.
Instance details Defined in Lucid.Base Methods mempty :: HtmlT m a Source # mappend :: HtmlT m a -> HtmlT m a -> HtmlT m a Source # mconcat :: [HtmlT m a] -> HtmlT m a Source #
(a ~ (), Applicative m) => Semigroup (HtmlT m a) Source # | Since: 2.9.7
Instance details Defined in Lucid.Base Methods (<>) :: HtmlT m a -> HtmlT m a -> HtmlT m a Source # sconcat :: NonEmpty (HtmlT m a) -> HtmlT m a Source # stimes :: Integral b => b -> HtmlT m a -> HtmlT m a Source #
(Monad m, a ~ ()) => IsString (HtmlT m a) Source # | We pack it via string. Could possibly encode straight into a builder. That might be faster.
Instance details Defined in Lucid.Base Methods fromString :: String -> HtmlT m a Source #
m ~ Identity => Show (HtmlT m a) Source # | Just calls `renderText`.
Instance details Defined in Lucid.Base Methods showsPrec :: Int -> HtmlT m a -> ShowS Source # show :: HtmlT m a -> String Source # showList :: [HtmlT m a] -> ShowS Source #
(a ~ (), m ~ Identity) => ToHtml (HtmlT m a) Source # | Since: 2.9.8
Instance details Defined in Lucid.Base Methods toHtml :: forall (m0 :: Type -> Type). Monad m0 => HtmlT m a -> HtmlT m0 () Source # toHtmlRaw :: forall (m0 :: Type -> Type). Monad m0 => HtmlT m a -> HtmlT m0 () Source #
Functor m => With (HtmlT m a) Source # | For the contentless elements: `br_`
Instance details Defined in Lucid.Base Methods with :: HtmlT m a -> [Attribute] -> HtmlT m a Source #
Functor m => With (HtmlT m a -> HtmlT m a) Source # | For the contentful elements: `div_`
Instance details Defined in Lucid.Base Methods with :: (HtmlT m a -> HtmlT m a) -> [Attribute] -> HtmlT m a -> HtmlT m a Source #
Applicative m => Term (HtmlT m a) (HtmlT m a) Source # | Given children immediately, just use that and expect no attributes.
Instance details Defined in Lucid.Base Methods term :: Text -> HtmlT m a -> HtmlT m a Source # termWith :: Text -> [Attribute] -> HtmlT m a -> HtmlT m a Source #

data Attribute Source #

A simple attribute. Don't use the constructor, use `makeAttribute`. Attributes are case sensitive, so if you want attributes to be merged properly, use a single case representation.

Constructors

Attribute !Text !Text |

#### Instances

Instances details

Show Attribute Source # |
Instance details Defined in Lucid.Base Methods showsPrec :: Int -> Attribute -> ShowS Source # show :: Attribute -> String Source # showList :: [Attribute] -> ShowS Source #
Eq Attribute Source # |
Instance details Defined in Lucid.Base Methods (==) :: Attribute -> Attribute -> Bool Source # (/=) :: Attribute -> Attribute -> Bool Source #
Hashable Attribute Source # |
Instance details Defined in Lucid.Base Methods hashWithSalt :: Int -> Attribute -> Int Source # hash :: Attribute -> Int Source #
Term Text Attribute Source # | Some terms (like `style_`, `title_`) can be used for attributes as well as elements.
Instance details Defined in Lucid.Base Methods term :: Text -> Text -> Attribute Source # termWith :: Text -> [Attribute] -> Text -> Attribute Source #
TermRaw Text Attribute Source # | Some termRaws (like `style_`, `title_`) can be used for attributes as well as elements.
Instance details Defined in Lucid.Base Methods termRaw :: Text -> Text -> Attribute Source # termRawWith :: Text -> [Attribute] -> Text -> Attribute Source #
(Applicative m, f ~ HtmlT m a) => Term [Attribute] (f -> HtmlT m a) Source # | Given attributes, expect more child input.
Instance details Defined in Lucid.Base Methods term :: Text -> [Attribute] -> f -> HtmlT m a Source # termWith :: Text -> [Attribute] -> [Attribute] -> f -> HtmlT m a Source #
(Monad m, ToHtml f, a ~ ()) => TermRaw [Attribute] (f -> HtmlT m a) Source # | Given attributes, expect more child input.
Instance details Defined in Lucid.Base Methods termRaw :: Text -> [Attribute] -> f -> HtmlT m a Source # termRawWith :: Text -> [Attribute] -> [Attribute] -> f -> HtmlT m a Source #

# 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

Instances details

Term Text Attribute Source # | Some terms (like `style_`, `title_`) can be used for attributes as well as elements.
Instance details Defined in Lucid.Base Methods term :: Text -> Text -> Attribute Source # termWith :: Text -> [Attribute] -> Text -> Attribute Source #
(Applicative m, f ~ HtmlT m a) => Term [Attribute] (f -> HtmlT m a) Source # | Given attributes, expect more child input.
Instance details Defined in Lucid.Base Methods term :: Text -> [Attribute] -> f -> HtmlT m a Source # termWith :: Text -> [Attribute] -> [Attribute] -> f -> HtmlT m a Source #
Applicative m => Term (HtmlT m a) (HtmlT m a) Source # | Given children immediately, just use that and expect no attributes.
Instance details Defined in Lucid.Base Methods term :: Text -> HtmlT m a -> HtmlT m a Source # termWith :: Text -> [Attribute] -> HtmlT m a -> HtmlT m a Source #

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

Instances details

TermRaw Text Attribute Source # | Some termRaws (like `style_`, `title_`) can be used for attributes as well as elements.
Instance details Defined in Lucid.Base Methods termRaw :: Text -> Text -> Attribute Source # termRawWith :: Text -> [Attribute] -> Text -> Attribute Source #
(Monad m, a ~ ()) => TermRaw Text (HtmlT m a) Source # | Given children immediately, just use that and expect no attributes.
Instance details Defined in Lucid.Base Methods termRaw :: Text -> Text -> HtmlT m a Source # termRawWith :: Text -> [Attribute] -> Text -> HtmlT m a Source #
(Monad m, ToHtml f, a ~ ()) => TermRaw [Attribute] (f -> HtmlT m a) Source # | Given attributes, expect more child input.
Instance details Defined in Lucid.Base Methods termRaw :: Text -> [Attribute] -> f -> HtmlT m a Source # termRawWith :: Text -> [Attribute] -> [Attribute] -> f -> HtmlT m a Source #

class ToHtml a where Source #

Can be converted to HTML.

Methods

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

Convert to HTML, doing HTML escaping.

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

Convert to HTML without any escaping.

#### Instances

Instances details

ToHtml ByteString Source # | 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
Instance details Defined in Lucid.Base Methods toHtml :: forall (m :: Type -> Type). Monad m => ByteString -> HtmlT m () Source # toHtmlRaw :: forall (m :: Type -> Type). Monad m => ByteString -> HtmlT m () Source #
ToHtml ByteString Source # | 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
Instance details Defined in Lucid.Base Methods toHtml :: forall (m :: Type -> Type). Monad m => ByteString -> HtmlT m () Source # toHtmlRaw :: forall (m :: Type -> Type). Monad m => ByteString -> HtmlT m () Source #
ToHtml Text Source # |
Instance details Defined in Lucid.Base Methods toHtml :: forall (m :: Type -> Type). Monad m => Text -> HtmlT m () Source # toHtmlRaw :: forall (m :: Type -> Type). Monad m => Text -> HtmlT m () Source #
ToHtml Text Source # |
Instance details Defined in Lucid.Base Methods toHtml :: forall (m :: Type -> Type). Monad m => Text -> HtmlT m () Source # toHtmlRaw :: forall (m :: Type -> Type). Monad m => Text -> HtmlT m () Source #
ToHtml String Source # |
Instance details Defined in Lucid.Base Methods toHtml :: forall (m :: Type -> Type). Monad m => String -> HtmlT m () Source # toHtmlRaw :: forall (m :: Type -> Type). Monad m => String -> HtmlT m () Source #
(a ~ (), m ~ Identity) => ToHtml (HtmlT m a) Source # | Since: 2.9.8
Instance details Defined in Lucid.Base Methods toHtml :: forall (m0 :: Type -> Type). Monad m0 => HtmlT m a -> HtmlT m0 () Source # toHtmlRaw :: forall (m0 :: Type -> Type). Monad m0 => HtmlT m a -> HtmlT m0 () 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

Instances details

Functor m => With (HtmlT m a) Source # | For the contentless elements: `br_`
Instance details Defined in Lucid.Base Methods with :: HtmlT m a -> [Attribute] -> HtmlT m a Source #
Functor m => With (HtmlT m a -> HtmlT m a) Source # | For the contentful elements: `div_`
Instance details Defined in Lucid.Base Methods with :: (HtmlT m a -> HtmlT m a) -> [Attribute] -> HtmlT m a -> HtmlT m a Source #