Text.Blaze.Internal

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

Safe Haskell | None
Language | Haskell2010

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 Text.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 a)
  - | CustomParent ChoiceString (MarkupM a)
  - | Leaf StaticString StaticString StaticString a
  - | CustomLeaf ChoiceString Bool a
  - | Content ChoiceString a
  - | Comment ChoiceString a
  - | Append (MarkupM b) (MarkupM a)
  - | AddAttribute StaticString StaticString ChoiceString (MarkupM a)
  - | AddCustomAttribute ChoiceString ChoiceString (MarkupM a)
  - | Empty a
- 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
- (!) :: Attributable h => h -> Attribute -> h
- (!?) :: Attributable h => h -> (Bool, Attribute) -> h
- contents :: MarkupM a -> MarkupM a
- 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

Instances details

Monoid ChoiceString # |
Instance details Defined in Text.Blaze.Internal Methods mempty :: ChoiceString # mappend :: ChoiceString -> ChoiceString -> ChoiceString # mconcat :: [ChoiceString] -> ChoiceString #
Semigroup ChoiceString # |
Instance details Defined in Text.Blaze.Internal Methods (<>) :: ChoiceString -> ChoiceString -> ChoiceString # sconcat :: NonEmpty ChoiceString -> ChoiceString # stimes :: Integral b => b -> ChoiceString -> ChoiceString #
IsString ChoiceString # |
Instance details Defined in Text.Blaze.Internal Methods fromString :: String -> 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

Instances details

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

data MarkupM a #

The core Markup datatype.

Constructors

Parent StaticString StaticString StaticString (MarkupM a) | Tag, open tag, end tag, content
CustomParent ChoiceString (MarkupM a) | Custom parent
Leaf StaticString StaticString StaticString a | Tag, open tag, end tag
CustomLeaf ChoiceString Bool a | Custom leaf
Content ChoiceString a | HTML content
Comment ChoiceString a | HTML comment. Note: you should wrap the `ChoiceString` in a `PreEscaped`.
Append (MarkupM b) (MarkupM a) | 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 a | Empty HTML.

#### Instances

Instances details

ToMarkup Markup # |
Instance details Defined in Text.Blaze Methods toMarkup :: Markup -> Markup # preEscapedToMarkup :: Markup -> Markup #
Applicative MarkupM # |
Instance details Defined in Text.Blaze.Internal Methods pure :: a -> MarkupM a # (<*>) :: MarkupM (a -> b) -> MarkupM a -> MarkupM b # liftA2 :: (a -> b -> c) -> MarkupM a -> MarkupM b -> MarkupM c # (*>) :: MarkupM a -> MarkupM b -> MarkupM b # (<*) :: MarkupM a -> MarkupM b -> MarkupM a #
Functor MarkupM # |
Instance details Defined in Text.Blaze.Internal Methods fmap :: (a -> b) -> MarkupM a -> MarkupM b # (<$) :: a -> MarkupM b -> MarkupM a #
Monad MarkupM # |
Instance details Defined in Text.Blaze.Internal Methods (>>=) :: MarkupM a -> (a -> MarkupM b) -> MarkupM b # (>>) :: MarkupM a -> MarkupM b -> MarkupM b # return :: a -> MarkupM a #
ToMarkup [Markup] # |
Instance details Defined in Text.Blaze Methods toMarkup :: [Markup] -> Markup # preEscapedToMarkup :: [Markup] -> Markup #
Attributable (MarkupM a) # |
Instance details Defined in Text.Blaze.Internal Methods (!) :: MarkupM a -> Attribute -> MarkupM a #
Monoid a => Monoid (MarkupM a) # |
Instance details Defined in Text.Blaze.Internal Methods mempty :: MarkupM a # mappend :: MarkupM a -> MarkupM a -> MarkupM a # mconcat :: [MarkupM a] -> MarkupM a #
Monoid a => Semigroup (MarkupM a) # |
Instance details Defined in Text.Blaze.Internal Methods (<>) :: MarkupM a -> MarkupM a -> MarkupM a # sconcat :: NonEmpty (MarkupM a) -> MarkupM a # stimes :: Integral b => b -> MarkupM a -> MarkupM a #
a ~ () => IsString (MarkupM a) # |
Instance details Defined in Text.Blaze.Internal Methods fromString :: String -> MarkupM a #
Attributable (MarkupM a -> MarkupM b) # |
Instance details Defined in Text.Blaze.Internal 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

Instances details

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

data Attribute #

Type for an attribute.

#### Instances

Instances details

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

data AttributeValue #

The type for the value part of an attribute.

#### Instances

Instances details

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

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

Minimal complete definition

(!)

#### Instances

Instances details

Attributable (MarkupM a) # |
Instance details Defined in Text.Blaze.Internal Methods (!) :: MarkupM a -> Attribute -> MarkupM a #
Attributable (MarkupM a -> MarkupM b) # |
Instance details Defined in Text.Blaze.Internal 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 a #

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