blaze-markup-0.8.3.0: A blazingly fast markup combinator library for Haskell

Safe Haskell | None
Language | Haskell2010

Text.Blaze

Contents

- Important types.
- Creating attributes.
- Converting values to Markup.
- Comments
- Creating tags.
- Converting values to attribute values.
- Setting attributes
- Modifying Markup trees

Description

BlazeMarkup is a markup combinator library. It provides a way to embed markup languages like HTML and SVG in Haskell in an efficient and convenient way, with a light-weight syntax.

To use the library, one needs to import a set of combinators. For example, you can use HTML 4 Strict from BlazeHtml package.

    {-# LANGUAGE OverloadedStrings #-}
    import Prelude hiding (head, id, div)
    import Text.Blaze.Html4.Strict hiding (map)
    import Text.Blaze.Html4.Strict.Attributes hiding (title)

To render the page later on, you need a so called Renderer. The recommended renderer is an UTF-8 renderer which produces a lazy bytestring.

    import Text.Blaze.Renderer.Utf8 (renderMarkup)

Now, you can describe pages using the imported combinators.

    page1 :: Markup
    page1 = html $ do
        head $ do
            title "Introduction page."
            link ! rel "stylesheet" ! type_ "text/css" ! href "screen.css"
        body $ do
            div ! id "header" $ "Syntax"
            p "This is an example of BlazeMarkup syntax."
            ul $ mapM_ (li . toMarkup . show) [1, 2, 3]

The resulting HTML can now be extracted using:

    renderMarkup page1

Synopsis

- type Markup = MarkupM ()
- data Tag
- data Attribute
- data AttributeValue
- dataAttribute :: Tag -> AttributeValue -> Attribute
- customAttribute :: Tag -> AttributeValue -> Attribute
- class ToMarkup a where
  - toMarkup :: a -> Markup
  - preEscapedToMarkup :: a -> Markup
- text :: Text -> Markup
- preEscapedText :: Text -> Markup
- lazyText :: Text -> Markup
- preEscapedLazyText :: Text -> Markup
- string :: String -> Markup
- preEscapedString :: String -> Markup
- unsafeByteString :: ByteString -> Markup
- unsafeLazyByteString :: ByteString -> Markup
- textComment :: Text -> Markup
- lazyTextComment :: Text -> Markup
- stringComment :: String -> Markup
- unsafeByteStringComment :: ByteString -> Markup
- unsafeLazyByteStringComment :: ByteString -> Markup
- textTag :: Text -> Tag
- stringTag :: String -> Tag
- class ToValue a where
  - toValue :: a -> AttributeValue
  - preEscapedToValue :: a -> AttributeValue
- textValue :: Text -> AttributeValue
- preEscapedTextValue :: Text -> AttributeValue
- lazyTextValue :: Text -> AttributeValue
- preEscapedLazyTextValue :: Text -> AttributeValue
- stringValue :: String -> AttributeValue
- preEscapedStringValue :: String -> AttributeValue
- unsafeByteStringValue :: ByteString -> AttributeValue
- unsafeLazyByteStringValue :: ByteString -> AttributeValue
- (!) :: Attributable h => h -> Attribute -> h
- (!?) :: Attributable h => h -> (Bool, Attribute) -> h
- contents :: MarkupM a -> MarkupM a

# Important types.

type Markup = MarkupM () Source #

Simplification of the `MarkupM` datatype.

data Tag Source #

Type for an HTML tag. This can be seen as an internal string type used by BlazeMarkup.

#### Instances

Instances details

IsString Tag Source # |
Instance details Defined in Text.Blaze.Internal Methods fromString :: String -> Tag Source #

data Attribute Source #

Type for an attribute.

#### Instances

Instances details

Monoid Attribute Source # |
Instance details Defined in Text.Blaze.Internal Methods mempty :: Attribute Source # mappend :: Attribute -> Attribute -> Attribute Source # mconcat :: [Attribute] -> Attribute Source #
Semigroup Attribute Source # |
Instance details Defined in Text.Blaze.Internal Methods (<>) :: Attribute -> Attribute -> Attribute Source # sconcat :: NonEmpty Attribute -> Attribute Source # stimes :: Integral b => b -> Attribute -> Attribute Source #

data AttributeValue Source #

The type for the value part of an attribute.

#### Instances

Instances details

ToValue AttributeValue Source # |
Instance details Defined in Text.Blaze Methods toValue :: AttributeValue -> AttributeValue Source # preEscapedToValue :: AttributeValue -> AttributeValue Source #
Monoid AttributeValue Source # |
Instance details Defined in Text.Blaze.Internal Methods mempty :: AttributeValue Source # mappend :: AttributeValue -> AttributeValue -> AttributeValue Source # mconcat :: [AttributeValue] -> AttributeValue Source #
Semigroup AttributeValue Source # |
Instance details Defined in Text.Blaze.Internal Methods (<>) :: AttributeValue -> AttributeValue -> AttributeValue Source # sconcat :: NonEmpty AttributeValue -> AttributeValue Source # stimes :: Integral b => b -> AttributeValue -> AttributeValue Source #
IsString AttributeValue Source # |
Instance details Defined in Text.Blaze.Internal Methods fromString :: String -> AttributeValue Source #

# Creating attributes.

dataAttribute Source #

Arguments

:: Tag | Name of the attribute.
-> AttributeValue | Value for the attribute.
-> Attribute | Resulting HTML attribute.

From HTML 5 onwards, the user is able to specify custom data attributes.

An example:

    <p data-foo="bar">Hello.</p>

We support this in BlazeMarkup using this function. The above fragment could be described using BlazeMarkup with:

    p ! dataAttribute "foo" "bar" $ "Hello."

customAttribute Source #

Arguments

:: Tag | Name of the attribute
-> AttributeValue | Value for the attribute
-> Attribute | Resulting HTML attribtue

Create a custom attribute. This is not specified in the HTML spec, but some JavaScript libraries rely on it.

An example:

    <select dojoType="select">foo</select>

Can be produced using:

    select ! customAttribute "dojoType" "select" $ "foo"

# Converting values to Markup.

class ToMarkup a where Source #

Class allowing us to use a single function for Markup values

Minimal complete definition

toMarkup

Methods

toMarkup :: a -> Markup Source #

Convert a value to Markup.

preEscapedToMarkup :: a -> Markup Source #

Convert a value to Markup without escaping

#### Instances

Instances details

ToMarkup Markup Source # |
Instance details Defined in Text.Blaze Methods toMarkup :: Markup -> Markup Source # preEscapedToMarkup :: Markup -> Markup Source #
ToMarkup Int32 Source # |
Instance details Defined in Text.Blaze Methods toMarkup :: Int32 -> Markup Source # preEscapedToMarkup :: Int32 -> Markup Source #
ToMarkup Int64 Source # |
Instance details Defined in Text.Blaze Methods toMarkup :: Int64 -> Markup Source # preEscapedToMarkup :: Int64 -> Markup Source #
ToMarkup Word32 Source # |
Instance details Defined in Text.Blaze Methods toMarkup :: Word32 -> Markup Source # preEscapedToMarkup :: Word32 -> Markup Source #
ToMarkup Word64 Source # |
Instance details Defined in Text.Blaze Methods toMarkup :: Word64 -> Markup Source # preEscapedToMarkup :: Word64 -> Markup Source #
ToMarkup Text Source # |
Instance details Defined in Text.Blaze Methods toMarkup :: Text -> Markup Source # preEscapedToMarkup :: Text -> Markup Source #
ToMarkup Builder Source # |
Instance details Defined in Text.Blaze Methods toMarkup :: Builder -> Markup Source # preEscapedToMarkup :: Builder -> Markup Source #
ToMarkup Text Source # |
Instance details Defined in Text.Blaze Methods toMarkup :: Text -> Markup Source # preEscapedToMarkup :: Text -> Markup Source #
ToMarkup Integer Source # |
Instance details Defined in Text.Blaze Methods toMarkup :: Integer -> Markup Source # preEscapedToMarkup :: Integer -> Markup Source #
ToMarkup Natural Source # |
Instance details Defined in Text.Blaze Methods toMarkup :: Natural -> Markup Source # preEscapedToMarkup :: Natural -> Markup Source #
ToMarkup String Source # |
Instance details Defined in Text.Blaze Methods toMarkup :: String -> Markup Source # preEscapedToMarkup :: String -> Markup Source #
ToMarkup Bool Source # |
Instance details Defined in Text.Blaze Methods toMarkup :: Bool -> Markup Source # preEscapedToMarkup :: Bool -> Markup Source #
ToMarkup Char Source # |
Instance details Defined in Text.Blaze Methods toMarkup :: Char -> Markup Source # preEscapedToMarkup :: Char -> Markup Source #
ToMarkup Double Source # |
Instance details Defined in Text.Blaze Methods toMarkup :: Double -> Markup Source # preEscapedToMarkup :: Double -> Markup Source #
ToMarkup Float Source # |
Instance details Defined in Text.Blaze Methods toMarkup :: Float -> Markup Source # preEscapedToMarkup :: Float -> Markup Source #
ToMarkup Int Source # |
Instance details Defined in Text.Blaze Methods toMarkup :: Int -> Markup Source # preEscapedToMarkup :: Int -> Markup Source #
ToMarkup Word Source # |
Instance details Defined in Text.Blaze Methods toMarkup :: Word -> Markup Source # preEscapedToMarkup :: Word -> Markup Source #
ToMarkup (NonEmpty Char) Source # |
Instance details Defined in Text.Blaze Methods toMarkup :: NonEmpty Char -> Markup Source # preEscapedToMarkup :: NonEmpty Char -> Markup Source #
ToMarkup [Markup] Source # |
Instance details Defined in Text.Blaze Methods toMarkup :: [Markup] -> Markup Source # preEscapedToMarkup :: [Markup] -> Markup Source #

text Source #

Arguments

:: Text | Text to render.
-> Markup | Resulting HTML fragment.

Render text. Functions like these can be used to supply content in HTML.

preEscapedText Source #

Arguments

:: Text | Text to insert
-> Markup | Resulting HTML fragment

Render text without escaping.

lazyText Source #

Arguments

:: Text | Text to insert
-> Markup | Resulting HTML fragment

A variant of `text` for lazy `Text`.

preEscapedLazyText Source #

Arguments

:: Text | Text to insert
-> Markup | Resulting HTML fragment

A variant of `preEscapedText` for lazy `Text`

string Source #

Arguments

:: String | String to insert.
-> Markup | Resulting HTML fragment.

Create an HTML snippet from a `String`.

preEscapedString Source #

Arguments

:: String | String to insert.
-> Markup | Resulting HTML fragment.

Create an HTML snippet from a `String` without escaping

unsafeByteString Source #

Arguments

:: ByteString | Value to insert.
-> Markup | Resulting HTML fragment.

Insert a `ByteString`. This is an unsafe operation:

- The `ByteString` could have the wrong encoding.
- The `ByteString` might contain illegal HTML characters (no escaping is done).

unsafeLazyByteString Source #

Arguments

:: ByteString | Value to insert
-> Markup | Resulting HTML fragment

Insert a lazy `ByteString`. See `unsafeByteString` for reasons why this is an unsafe operation.

# Comments

textComment :: Text -> Markup Source #

Create a comment from a `Text` value. The text should not contain `"--"`. This is not checked by the library.

lazyTextComment :: Text -> Markup Source #

Create a comment from a `Text` value. The text should not contain `"--"`. This is not checked by the library.

stringComment :: String -> Markup Source #

Create a comment from a `String` value. The text should not contain `"--"`. This is not checked by the library.

unsafeByteStringComment :: ByteString -> Markup Source #

Create a comment from a `ByteString` value. The text should not contain `"--"`. This is not checked by the library.

unsafeLazyByteStringComment :: ByteString -> Markup Source #

Create a comment from a `ByteString` value. The text should not contain `"--"`. This is not checked by the library.

# Creating tags.

textTag Source #

Arguments

:: Text | Text to create a tag from
-> Tag | Resulting tag

Create a `Tag` from some `Text`.

stringTag Source #

Arguments

:: String | String to create a tag from
-> Tag | Resulting tag

Create a `Tag` from a `String`.

# Converting values to attribute values.

class ToValue a where Source #

Class allowing us to use a single function for attribute values

Minimal complete definition

toValue

Methods

toValue :: a -> AttributeValue Source #

Convert a value to an attribute value

preEscapedToValue :: a -> AttributeValue Source #

Convert a value to an attribute value without escaping

#### Instances

Instances details

ToValue AttributeValue Source # |
Instance details Defined in Text.Blaze Methods toValue :: AttributeValue -> AttributeValue Source # preEscapedToValue :: AttributeValue -> AttributeValue Source #
ToValue Int32 Source # |
Instance details Defined in Text.Blaze Methods toValue :: Int32 -> AttributeValue Source # preEscapedToValue :: Int32 -> AttributeValue Source #
ToValue Int64 Source # |
Instance details Defined in Text.Blaze Methods toValue :: Int64 -> AttributeValue Source # preEscapedToValue :: Int64 -> AttributeValue Source #
ToValue Word32 Source # |
Instance details Defined in Text.Blaze Methods toValue :: Word32 -> AttributeValue Source # preEscapedToValue :: Word32 -> AttributeValue Source #
ToValue Word64 Source # |
Instance details Defined in Text.Blaze Methods toValue :: Word64 -> AttributeValue Source # preEscapedToValue :: Word64 -> AttributeValue Source #
ToValue Text Source # |
Instance details Defined in Text.Blaze Methods toValue :: Text -> AttributeValue Source # preEscapedToValue :: Text -> AttributeValue Source #
ToValue Builder Source # |
Instance details Defined in Text.Blaze Methods toValue :: Builder -> AttributeValue Source # preEscapedToValue :: Builder -> AttributeValue Source #
ToValue Text Source # |
Instance details Defined in Text.Blaze Methods toValue :: Text -> AttributeValue Source # preEscapedToValue :: Text -> AttributeValue Source #
ToValue Integer Source # |
Instance details Defined in Text.Blaze Methods toValue :: Integer -> AttributeValue Source # preEscapedToValue :: Integer -> AttributeValue Source #
ToValue String Source # |
Instance details Defined in Text.Blaze Methods toValue :: String -> AttributeValue Source # preEscapedToValue :: String -> AttributeValue Source #
ToValue Bool Source # |
Instance details Defined in Text.Blaze Methods toValue :: Bool -> AttributeValue Source # preEscapedToValue :: Bool -> AttributeValue Source #
ToValue Char Source # |
Instance details Defined in Text.Blaze Methods toValue :: Char -> AttributeValue Source # preEscapedToValue :: Char -> AttributeValue Source #
ToValue Double Source # |
Instance details Defined in Text.Blaze Methods toValue :: Double -> AttributeValue Source # preEscapedToValue :: Double -> AttributeValue Source #
ToValue Float Source # |
Instance details Defined in Text.Blaze Methods toValue :: Float -> AttributeValue Source # preEscapedToValue :: Float -> AttributeValue Source #
ToValue Int Source # |
Instance details Defined in Text.Blaze Methods toValue :: Int -> AttributeValue Source # preEscapedToValue :: Int -> AttributeValue Source #
ToValue Word Source # |
Instance details Defined in Text.Blaze Methods toValue :: Word -> AttributeValue Source # preEscapedToValue :: Word -> AttributeValue Source #
ToValue (NonEmpty Char) Source # |
Instance details Defined in Text.Blaze Methods toValue :: NonEmpty Char -> AttributeValue Source # preEscapedToValue :: NonEmpty Char -> AttributeValue Source #

textValue Source #

Arguments

:: Text | The actual value.
-> AttributeValue | Resulting attribute value.

Render an attribute value from `Text`.

preEscapedTextValue Source #

Arguments

:: Text | The actual value
-> AttributeValue | Resulting attribute value

Render an attribute value from `Text` without escaping.

lazyTextValue Source #

Arguments

:: Text | The actual value
-> AttributeValue | Resulting attribute value

A variant of `textValue` for lazy `Text`

preEscapedLazyTextValue Source #

Arguments

:: Text | The actual value
-> AttributeValue | Resulting attribute value

A variant of `preEscapedTextValue` for lazy `Text`

stringValue :: String -> AttributeValue Source #

Create an attribute value from a `String`.

preEscapedStringValue :: String -> AttributeValue Source #

Create an attribute value from a `String` without escaping.

unsafeByteStringValue Source #

Arguments

:: ByteString | ByteString value
-> AttributeValue | Resulting attribute value

Create an attribute value from a `ByteString`. See `unsafeByteString` for reasons why this might not be a good idea.

unsafeLazyByteStringValue Source #

Arguments

:: ByteString | ByteString value
-> AttributeValue | Resulting attribute value

Create an attribute value from a lazy `ByteString`. See `unsafeByteString` for reasons why this might not be a good idea.

# Setting attributes

(!) :: Attributable h => h -> Attribute -> h Source #

Apply an attribute to an element.

Example:

    img ! src "foo.png"

Result:

    <img src="foo.png" />

This can be used on nested elements as well.

Example:

    p ! style "float: right" $ "Hello!"

Result:

    <p style="float: right">Hello!</p>

(!?) :: Attributable h => h -> (Bool, Attribute) -> h Source #

Shorthand for setting an attribute depending on a conditional.

Example:

    p !? (isBig, A.class "big") $ "Hello"

Gives the same result as:

    (if isBig then p ! A.class "big" else p) "Hello"

# Modifying Markup trees

contents :: MarkupM a -> MarkupM a Source #

Take only the text content of an HTML tree.

    contents $ do
        p ! $ "Hello "
        p ! $ "Word!"

Result:

    Hello World!