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

Safe HaskellNone
LanguageHaskell98

Text.Blaze.Internal

Contents

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

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

data StaticString #

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

Constructors

StaticString 

Fields

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

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 # 
(~) * a () => IsString (MarkupM a) # 

Methods

fromString :: String -> MarkupM a #

Monoid a => Semigroup (MarkupM a) # 

Methods

(<>) :: MarkupM a -> MarkupM a -> MarkupM a #

sconcat :: NonEmpty (MarkupM a) -> MarkupM a #

stimes :: Integral b => b -> MarkupM a -> 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] # 
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

data Attribute #

Type for an attribute.

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 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:

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