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

Safe Haskell | None
Language | Haskell98

Text.Blaze.Internal

Contents

- Important types.
- Creating custom tags and attributes.
- Converting values to Markup.
- Comments
- Converting values to tags.
- Converting values to attribute values.
- Setting attributes
- Modifying Markup elements
- Querying Markup elements

Description

The BlazeMarkup core, consisting of functions that offer the power to generate custom markup elements. It also offers user-centric functions, which are exposed through `Blaze`.

While this module is exported, usage of it is not recommended, unless you know what you are doing. This module might undergo changes at any time.

Synopsis

- data ChoiceString
  - = Static !StaticString
  - | String String
  - | Text Text
  - | ByteString ByteString
  - | PreEscaped ChoiceString
  - | External ChoiceString
  - | AppendChoiceString ChoiceString ChoiceString
  - | EmptyChoiceString
- data StaticString = StaticString {
  - getString :: String -> String
  - getUtf8ByteString :: ByteString
  - getText :: Text
  }
- data MarkupM a
  - = Parent StaticString StaticString StaticString (MarkupM b)
  - | CustomParent ChoiceString (MarkupM b)
  - | Leaf StaticString StaticString StaticString
  - | CustomLeaf ChoiceString Bool
  - | Content ChoiceString
  - | Comment ChoiceString
  - | Append (MarkupM b) (MarkupM c)
  - | AddAttribute StaticString StaticString ChoiceString (MarkupM a)
  - | AddCustomAttribute ChoiceString ChoiceString (MarkupM a)
  - | Empty
- type Markup = MarkupM ()
- data Tag
- data Attribute
- data AttributeValue
- customParent :: Tag -> Markup -> Markup
- customLeaf :: Tag -> Bool -> Markup
- attribute :: Tag -> Tag -> AttributeValue -> Attribute
- dataAttribute :: Tag -> AttributeValue -> Attribute
- customAttribute :: Tag -> AttributeValue -> Attribute
- text :: Text -> Markup
- preEscapedText :: Text -> Markup
- lazyText :: Text -> Markup
- preEscapedLazyText :: Text -> Markup
- textBuilder :: Builder -> Markup
- preEscapedTextBuilder :: Builder -> 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
- textValue :: Text -> AttributeValue
- preEscapedTextValue :: Text -> AttributeValue
- lazyTextValue :: Text -> AttributeValue
- preEscapedLazyTextValue :: Text -> AttributeValue
- textBuilderValue :: Builder -> AttributeValue
- preEscapedTextBuilderValue :: Builder -> AttributeValue
- stringValue :: String -> AttributeValue
- preEscapedStringValue :: String -> AttributeValue
- unsafeByteStringValue :: ByteString -> AttributeValue
- unsafeLazyByteStringValue :: ByteString -> AttributeValue
- class Attributable h where
- (!) :: Attributable h => h -> Attribute -> h
- (!?) :: Attributable h => h -> (Bool, Attribute) -> h
- contents :: MarkupM a -> MarkupM b
- external :: MarkupM a -> MarkupM a
- null :: MarkupM a -> Bool

# Important types.

data ChoiceString #

A string denoting input from different string representations.

Constructors

Static !StaticString | Static data
String String | A Haskell String
Text Text | A Text value
ByteString ByteString | An encoded bytestring
PreEscaped ChoiceString | A pre-escaped string
External ChoiceString | External data in style/script tags, should be checked for validity
AppendChoiceString ChoiceString ChoiceString | Concatenation
EmptyChoiceString | Empty string

Instances

IsString ChoiceString # |
Methods fromString :: String -> ChoiceString #
Monoid ChoiceString # |
Methods mempty :: ChoiceString # mappend :: ChoiceString -> ChoiceString -> ChoiceString # mconcat :: [ChoiceString] -> ChoiceString #

data StaticString #

A static string that supports efficient output to all possible backends.

Constructors

StaticString |
Fields getString :: String -> String Appending haskell string getUtf8ByteString :: ByteString UTF-8 encoded bytestring getText :: Text Text value

Instances

IsString StaticString # |
Methods fromString :: String -> StaticString #

data MarkupM a #

The core Markup datatype.

Constructors

Parent StaticString StaticString StaticString (MarkupM b) | Tag, open tag, end tag, content
CustomParent ChoiceString (MarkupM b) | Custom parent
Leaf StaticString StaticString StaticString | Tag, open tag, end tag
CustomLeaf ChoiceString Bool | Custom leaf
Content ChoiceString | HTML content
Comment ChoiceString | HTML comment. Note: you should wrap the `ChoiceString` in a `PreEscaped`.
Append (MarkupM b) (MarkupM c) | Concatenation of two HTML pieces
AddAttribute StaticString StaticString ChoiceString (MarkupM a) | Add an attribute to the inner HTML. Raw key, key, value, HTML to receive the attribute.
AddCustomAttribute ChoiceString ChoiceString (MarkupM a) | Add a custom attribute to the inner HTML.
Empty | Empty HTML.

Instances

Monad MarkupM # |
Methods (>>=) :: MarkupM a -> (a -> MarkupM b) -> MarkupM b # (>>) :: MarkupM a -> MarkupM b -> MarkupM b # return :: a -> MarkupM a # fail :: String -> MarkupM a #
Functor MarkupM # |
Methods fmap :: (a -> b) -> MarkupM a -> MarkupM b # (<$) :: a -> MarkupM b -> MarkupM a #
Applicative MarkupM # |
Methods pure :: a -> MarkupM a # (<*>) :: MarkupM (a -> b) -> MarkupM a -> MarkupM b # (*>) :: MarkupM a -> MarkupM b -> MarkupM b # (<*) :: MarkupM a -> MarkupM b -> MarkupM a #
ToMarkup Markup # |
Methods toMarkup :: Markup -> Markup # preEscapedToMarkup :: Markup -> Markup #
IsString (MarkupM a) # |
Methods fromString :: String -> MarkupM a #
Monoid a => Monoid (MarkupM a) # |
Methods mempty :: MarkupM a # mappend :: MarkupM a -> MarkupM a -> MarkupM a # mconcat :: [MarkupM a] -> MarkupM a #
Attributable (MarkupM a) # |
Methods (!) :: MarkupM a -> Attribute -> MarkupM a #
ToMarkup [Markup] # |
Methods toMarkup :: [Markup] -> Markup # preEscapedToMarkup :: [Markup] -> Markup #
Attributable (MarkupM a -> MarkupM b) # |
Methods (!) :: (MarkupM a -> MarkupM b) -> Attribute -> MarkupM a -> MarkupM b #

type Markup = MarkupM () #

Simplification of the `MarkupM` datatype.

data Tag #

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

Instances

IsString Tag # |
Methods fromString :: String -> Tag #

data Attribute #

Type for an attribute.

Instances

Monoid Attribute # |
Methods mempty :: Attribute # mappend :: Attribute -> Attribute -> Attribute # mconcat :: [Attribute] -> Attribute #

data AttributeValue #

The type for the value part of an attribute.

Instances

IsString AttributeValue # |
Methods fromString :: String -> AttributeValue #
Monoid AttributeValue # |
Methods mempty :: AttributeValue # mappend :: AttributeValue -> AttributeValue -> AttributeValue # mconcat :: [AttributeValue] -> AttributeValue #
ToValue AttributeValue # |
Methods toValue :: AttributeValue -> AttributeValue # preEscapedToValue :: AttributeValue -> AttributeValue #

# Creating custom tags and attributes.

customParent #

Arguments

:: Tag | Element tag
-> Markup | Content
-> Markup | Resulting markup

Create a custom parent element

customLeaf #

Arguments

:: Tag | Element tag
-> Bool | Close the leaf?
-> Markup | Resulting markup

Create a custom leaf element

attribute #

Arguments

:: Tag | Raw key
-> Tag | Shared key string for the HTML attribute.
-> AttributeValue | Value for the HTML attribute.
-> Attribute | Resulting HTML attribute.

Create an HTML attribute that can be applied to an HTML element later using the `!` operator.

dataAttribute #

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 #

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.

text #

Arguments

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

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

preEscapedText #

Arguments

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

Render text without escaping.

lazyText #

Arguments

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

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

preEscapedLazyText #

Arguments

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

A variant of `preEscapedText` for lazy `Text`

textBuilder #

Arguments

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

A variant of `text` for text `Builder`.

preEscapedTextBuilder #

Arguments

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

A variant of `preEscapedText` for lazy `Text`

string #

Arguments

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

Create an HTML snippet from a `String`.

preEscapedString #

Arguments

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

Create an HTML snippet from a `String` without escaping

unsafeByteString #

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 #

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 #

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

lazyTextComment :: Text -> Markup #

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

stringComment :: String -> Markup #

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

unsafeByteStringComment :: ByteString -> Markup #

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

unsafeLazyByteStringComment :: ByteString -> Markup #

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

# Converting values to tags.

textTag #

Arguments

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

Create a `Tag` from some `Text`.

stringTag #

Arguments

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

Create a `Tag` from a `String`.

# Converting values to attribute values.

textValue #

Arguments

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

Render an attribute value from `Text`.

preEscapedTextValue #

Arguments

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

Render an attribute value from `Text` without escaping.

lazyTextValue #

Arguments

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

A variant of `textValue` for lazy `Text`

preEscapedLazyTextValue #

Arguments

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

A variant of `preEscapedTextValue` for lazy `Text`

textBuilderValue #

Arguments

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

A variant of `textValue` for text `Builder`

preEscapedTextBuilderValue #

Arguments

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

A variant of `preEscapedTextValue` for text `Builder`

stringValue :: String -> AttributeValue #

Create an attribute value from a `String`.

preEscapedStringValue :: String -> AttributeValue #

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

unsafeByteStringValue #

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 #

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

class Attributable h where #

Used for applying attributes. You should not define your own instances of this class.

Minimal complete definition

(!)

Methods

(!) :: h -> Attribute -> h #

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>

Instances

Attributable (MarkupM a) # |
Methods (!) :: MarkupM a -> Attribute -> MarkupM a #
Attributable (MarkupM a -> MarkupM b) # |
Methods (!) :: (MarkupM a -> MarkupM b) -> Attribute -> MarkupM a -> MarkupM b #

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

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 #

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 elements

contents :: MarkupM a -> MarkupM b #

Take only the text content of an HTML tree.

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

Result:

    Hello World!

external :: MarkupM a -> MarkupM a #

Mark HTML as external data. External data can be:

- CSS data in a `style` tag;
- Script data in a `script` tag.

This function is applied automatically when using the `style` or `script` combinators.

# Querying Markup elements

null :: MarkupM a -> Bool #

Check if a `Markup` value is completely empty (renders to the empty string).