Text.XmlHtml

Parsers and renderers for XML and HTML 5. Although the formats are treated differently, the data types used by each are the same, which makes it easy to write code that works with the element structure of either XML or HTML 5 documents.

Limitations:

• The XML parser does not parse internal DOCTYPE subsets. They are just stored as blocks of text, with minimal scanning done to match quotes and brackets to determine the end.
• Since DTDs are not parsed, the XML parser fails on entity references, except for those defined internally. You cannot use this library for parsing XML documents with entity references outside the predefined set.
• The HTML 5 parser is not a compliant HTML parser. Instead, it is a parser for valid HTML 5 content. It should only be used on content that you have reason to believe is probably correct, since the compatibility features of HTML 5 are missing. This is the wrong library on which to build a web spider.
• Both parsers accept fragments of documents, by which is meant that they do not enforce the top-level structure of the document. Files may contain more than one root element, for example.

Types

data Document

Represents a document fragment, including the format, encoding, and document type declaration as well as its content.

Constructors

XmlDocument

Fields

• docEncoding :: !Encoding
• docType :: !(Maybe DocType)
• docContent :: ![Node]

HtmlDocument

Fields

• docEncoding :: !Encoding
• docType :: !(Maybe DocType)
• docContent :: ![Node]

Instances

Eq Document

Methods

(==) :: Document -> Document -> Bool

(/=) :: Document -> Document -> Bool

Show Document

Methods

showsPrec :: Int -> Document -> ShowS

show :: Document -> String

showList :: [Document] -> ShowS

data Node

A node of a document structure. A node can be text, a comment, or an element. XML processing instructions are intentionally omitted as a simplification, and CDATA and plain text are both text nodes, since they ought to be semantically interchangeable.

Constructors

TextNode !Text

Comment !Text

Element

Fields

• elementTag :: !Text
• elementAttrs :: ![(Text, Text)]
• elementChildren :: ![Node]

Instances

Eq Node

Methods

(==) :: Node -> Node -> Bool

(/=) :: Node -> Node -> Bool

Show Node

Methods

showsPrec :: Int -> Node -> ShowS

show :: Node -> String

showList :: [Node] -> ShowS

data DocType

A document type declaration. Note that DTD internal subsets are currently unimplemented.

Constructors

DocType !Text !ExternalID !InternalSubset

Instances

Eq DocType

Methods

(==) :: DocType -> DocType -> Bool

(/=) :: DocType -> DocType -> Bool

Show DocType

Methods

showsPrec :: Int -> DocType -> ShowS

show :: DocType -> String

showList :: [DocType] -> ShowS

data ExternalID

An external ID, as in a document type declaration. This can be a SYSTEM identifier, or a PUBLIC identifier, or can be omitted.

Constructors

Public !Text !Text

System !Text

NoExternalID

Instances

Eq ExternalID

Methods

(==) :: ExternalID -> ExternalID -> Bool

(/=) :: ExternalID -> ExternalID -> Bool

Show ExternalID

Methods

showsPrec :: Int -> ExternalID -> ShowS

show :: ExternalID -> String

showList :: [ExternalID] -> ShowS

data InternalSubset

The internal subset is unparsed, but preserved in case it's actually wanted.

Constructors

InternalText !Text

NoInternalSubset

Instances

Eq InternalSubset

Methods

(==) :: InternalSubset -> InternalSubset -> Bool

(/=) :: InternalSubset -> InternalSubset -> Bool

Show InternalSubset

Methods

showsPrec :: Int -> InternalSubset -> ShowS

show :: InternalSubset -> String

showList :: [InternalSubset] -> ShowS

data Encoding

The character encoding of a document. Currently only the required character encodings are implemented.

Constructors

UTF8

UTF16BE

UTF16LE

ISO_8859_1

Instances

Eq Encoding

Methods

(==) :: Encoding -> Encoding -> Bool

(/=) :: Encoding -> Encoding -> Bool

Show Encoding

Methods

showsPrec :: Int -> Encoding -> ShowS

show :: Encoding -> String

showList :: [Encoding] -> ShowS

data RenderOptions

Rendering options

Constructors

RenderOptions

Fields

• roAttributeSurround :: AttrSurround

  Single or double-quotes used around attribute values

• roAttributeResolveInternal :: AttrResolveInternalQuotes

  Quotes inside attribute values that conflict with the surround are escaped, or the outer quotes are changed to avoid conflicting with the internal ones

• roExplicitEmptyAttrs :: Maybe (HashMap Text (HashSet Text))

  Attributes in the whitelist with empty values are rendered as example="" Nothing applies this rule to all attributes with empty values

Instances

Eq RenderOptions

Methods

(==) :: RenderOptions -> RenderOptions -> Bool

(/=) :: RenderOptions -> RenderOptions -> Bool

Show RenderOptions

Methods

showsPrec :: Int -> RenderOptions -> ShowS

show :: RenderOptions -> String

showList :: [RenderOptions] -> ShowS

data AttrSurround

Constructors

SurroundDoubleQuote

SurroundSingleQuote

Instances

Eq AttrSurround

Methods

(==) :: AttrSurround -> AttrSurround -> Bool

(/=) :: AttrSurround -> AttrSurround -> Bool

Ord AttrSurround

Methods

compare :: AttrSurround -> AttrSurround -> Ordering

(<) :: AttrSurround -> AttrSurround -> Bool

(<=) :: AttrSurround -> AttrSurround -> Bool

(>) :: AttrSurround -> AttrSurround -> Bool

(>=) :: AttrSurround -> AttrSurround -> Bool

max :: AttrSurround -> AttrSurround -> AttrSurround

min :: AttrSurround -> AttrSurround -> AttrSurround

Show AttrSurround

Methods

showsPrec :: Int -> AttrSurround -> ShowS

show :: AttrSurround -> String

showList :: [AttrSurround] -> ShowS

data AttrResolveInternalQuotes

Constructors

AttrResolveByEscape

AttrResolveAvoidEscape

Instances

Eq AttrResolveInternalQuotes

Methods

(==) :: AttrResolveInternalQuotes -> AttrResolveInternalQuotes -> Bool

(/=) :: AttrResolveInternalQuotes -> AttrResolveInternalQuotes -> Bool

Ord AttrResolveInternalQuotes

Methods

compare :: AttrResolveInternalQuotes -> AttrResolveInternalQuotes -> Ordering

(<) :: AttrResolveInternalQuotes -> AttrResolveInternalQuotes -> Bool

(<=) :: AttrResolveInternalQuotes -> AttrResolveInternalQuotes -> Bool

(>) :: AttrResolveInternalQuotes -> AttrResolveInternalQuotes -> Bool

(>=) :: AttrResolveInternalQuotes -> AttrResolveInternalQuotes -> Bool

max :: AttrResolveInternalQuotes -> AttrResolveInternalQuotes -> AttrResolveInternalQuotes

min :: AttrResolveInternalQuotes -> AttrResolveInternalQuotes -> AttrResolveInternalQuotes

Show AttrResolveInternalQuotes

Methods

showsPrec :: Int -> AttrResolveInternalQuotes -> ShowS

show :: AttrResolveInternalQuotes -> String

showList :: [AttrResolveInternalQuotes] -> ShowS

Manipulating documents

isTextNode :: Node -> Bool

Determines whether the node is text or not.

isComment :: Node -> Bool

Determines whether the node is a comment or not.

isElement :: Node -> Bool

Determines whether the node is an element or not.

tagName :: Node -> Maybe Text

Gives the tag name of an element, or Nothing if the node isn't an element.

getAttribute :: Text -> Node -> Maybe Text

Retrieves the attribute with the given name. If the Node is not an element, the result is always Nothing

hasAttribute :: Text -> Node -> Bool

Checks if a given attribute exists in a Node.

setAttribute :: Text -> Text -> Node -> Node

Sets the attribute name to the given value. If the Node is not an element, this is the identity.

nodeText :: Node -> Text

Gives the entire text content of a node, ignoring markup.

childNodes :: Node -> [Node]

Gives the child nodes of the given node. Only elements have child nodes.

childElements :: Node -> [Node]

Gives the child elements of the given node.

childElementsTag :: Text -> Node -> [Node]

Gives all of the child elements of the node with the given tag name.

childElementTag :: Text -> Node -> Maybe Node

Gives the first child element of the node with the given tag name, or Nothing if there is no such child element.

descendantNodes :: Node -> [Node]

Gives the descendants of the given node in the order that they begin in the document.

descendantElements :: Node -> [Node]

Gives the descendant elements of the given node, in the order that their start tags appear in the document.

descendantElementsTag :: Text -> Node -> [Node]

Gives the descendant elements with a given tag name.

descendantElementTag :: Text -> Node -> Maybe Node

Gives the first descendant element of the node with the given tag name, or Nothing if there is no such element.

Parsing

parseXML

Arguments

:: String

Name of document source (perhaps a filename) for error messages

-> ByteString

Document contents

-> Either String Document

The document or an error message

Parses the given XML fragment.

parseHTML

Arguments

:: String

Name of document source (perhaps a filename) for error messages

-> ByteString

Document contents

-> Either String Document

The document or an error message

Parses the given HTML fragment. This enables HTML quirks mode, which changes the parsing algorithm to parse valid HTML 5 documents correctly.

Rendering

render :: Document -> Builder

renderWithOptions :: RenderOptions -> Document -> Builder

Renders a Document.

defaultRenderOptions :: RenderOptions

renderXmlFragment :: Encoding -> [Node] -> Builder

renderXmlFragmentWithOptions :: RenderOptions -> Encoding -> [Node] -> Builder

Function for rendering XML nodes without the overhead of creating a Document structure.

renderHtmlFragment :: Encoding -> [Node] -> Builder

Function for rendering HTML nodes without the overhead of creating a Document structure, using default rendering options

renderHtmlFragmentWithOptions :: RenderOptions -> Encoding -> [Node] -> Builder

Function for rendering HTML nodes without the overhead of creating a Document structure.

renderDocType :: Encoding -> Maybe DocType -> Builder