xmlhtml-0.2.5.4: XML parser and renderer with HTML 5 quirks mode

Safe Haskell | None
Language | Haskell2010

Text.XmlHtml

Contents

- Types
- Manipulating documents
- Parsing
- Rendering

Description

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.

Synopsis

- data Document
  - = XmlDocument {
    - docEncoding :: !Encoding
    - docType :: !(Maybe DocType)
    - docContent :: ![Node]
    }
  - | HtmlDocument {
    - docEncoding :: !Encoding
    - docType :: !(Maybe DocType)
    - docContent :: ![Node]
    }
- data Node
  - = TextNode !Text
  - | Comment !Text
  - | Element {
    - elementTag :: !Text
    - elementAttrs :: ![(Text, Text)]
    - elementChildren :: ![Node]
    }
- data DocType = DocType !Text !ExternalID !InternalSubset
- data ExternalID
  - = Public !Text !Text
  - | System !Text
  - | NoExternalID
- data InternalSubset
  - = InternalText !Text
  - | NoInternalSubset
- data Encoding
  - = UTF8
  - | UTF16BE
  - | UTF16LE
  - | ISO_8859_1
- data RenderOptions = RenderOptions {
  - roAttributeSurround :: AttrSurround
  - roAttributeResolveInternal :: AttrResolveInternalQuotes
  - roExplicitEmptyAttrs :: Maybe (HashMap Text (HashSet Text))
  }
- data AttrSurround
  - = SurroundDoubleQuote
  - | SurroundSingleQuote
- data AttrResolveInternalQuotes
  - = AttrResolveByEscape
  - | AttrResolveAvoidEscape
- isTextNode :: Node -> Bool
- isComment :: Node -> Bool
- isElement :: Node -> Bool
- tagName :: Node -> Maybe Text
- getAttribute :: Text -> Node -> Maybe Text
- hasAttribute :: Text -> Node -> Bool
- setAttribute :: Text -> Text -> Node -> Node
- nodeText :: Node -> Text
- childNodes :: Node -> [Node]
- childElements :: Node -> [Node]
- childElementsTag :: Text -> Node -> [Node]
- childElementTag :: Text -> Node -> Maybe Node
- descendantNodes :: Node -> [Node]
- descendantElements :: Node -> [Node]
- descendantElementsTag :: Text -> Node -> [Node]
- descendantElementTag :: Text -> Node -> Maybe Node
- parseXML :: String -> ByteString -> Either String Document
- parseHTML :: String -> ByteString -> Either String Document
- render :: Document -> Builder
- renderWithOptions :: RenderOptions -> Document -> Builder
- defaultRenderOptions :: RenderOptions
- renderXmlFragment :: Encoding -> [Node] -> Builder
- renderXmlFragmentWithOptions :: RenderOptions -> Encoding -> [Node] -> Builder
- renderHtmlFragment :: Encoding -> [Node] -> Builder
- renderHtmlFragmentWithOptions :: RenderOptions -> Encoding -> [Node] -> Builder
- renderDocType :: Encoding -> Maybe DocType -> Builder

# Types

data Document Source #

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

Instances details

Show Document Source # |
Instance details Defined in Text.XmlHtml.Common Methods showsPrec :: Int -> Document -> ShowS Source # show :: Document -> String Source # showList :: [Document] -> ShowS Source #
Eq Document Source # |
Instance details Defined in Text.XmlHtml.Common Methods (==) :: Document -> Document -> Bool Source # (/=) :: Document -> Document -> Bool Source #

data Node Source #

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

Instances details

Show Node Source # |
Instance details Defined in Text.XmlHtml.Common Methods showsPrec :: Int -> Node -> ShowS Source # show :: Node -> String Source # showList :: [Node] -> ShowS Source #
Eq Node Source # |
Instance details Defined in Text.XmlHtml.Common Methods (==) :: Node -> Node -> Bool Source # (/=) :: Node -> Node -> Bool Source #

data DocType Source #

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

Constructors

DocType !Text !ExternalID !InternalSubset |

#### Instances

Instances details

Show DocType Source # |
Instance details Defined in Text.XmlHtml.Common Methods showsPrec :: Int -> DocType -> ShowS Source # show :: DocType -> String Source # showList :: [DocType] -> ShowS Source #
Eq DocType Source # |
Instance details Defined in Text.XmlHtml.Common Methods (==) :: DocType -> DocType -> Bool Source # (/=) :: DocType -> DocType -> Bool Source #

data ExternalID Source #

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

Instances details

Show ExternalID Source # |
Instance details Defined in Text.XmlHtml.Common Methods showsPrec :: Int -> ExternalID -> ShowS Source # show :: ExternalID -> String Source # showList :: [ExternalID] -> ShowS Source #
Eq ExternalID Source # |
Instance details Defined in Text.XmlHtml.Common Methods (==) :: ExternalID -> ExternalID -> Bool Source # (/=) :: ExternalID -> ExternalID -> Bool Source #

data InternalSubset Source #

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

Constructors

InternalText !Text |
NoInternalSubset |

#### Instances

Instances details

Show InternalSubset Source # |
Instance details Defined in Text.XmlHtml.Common Methods showsPrec :: Int -> InternalSubset -> ShowS Source # show :: InternalSubset -> String Source # showList :: [InternalSubset] -> ShowS Source #
Eq InternalSubset Source # |
Instance details Defined in Text.XmlHtml.Common Methods (==) :: InternalSubset -> InternalSubset -> Bool Source # (/=) :: InternalSubset -> InternalSubset -> Bool Source #

data Encoding Source #

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

Constructors

UTF8 |
UTF16BE |
UTF16LE |
ISO_8859_1 |

#### Instances

Instances details

Show Encoding Source # |
Instance details Defined in Text.XmlHtml.Common Methods showsPrec :: Int -> Encoding -> ShowS Source # show :: Encoding -> String Source # showList :: [Encoding] -> ShowS Source #
Eq Encoding Source # |
Instance details Defined in Text.XmlHtml.Common Methods (==) :: Encoding -> Encoding -> Bool Source # (/=) :: Encoding -> Encoding -> Bool Source #

data RenderOptions Source #

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

Instances details

Show RenderOptions Source # |
Instance details Defined in Text.XmlHtml.Common Methods showsPrec :: Int -> RenderOptions -> ShowS Source # show :: RenderOptions -> String Source # showList :: [RenderOptions] -> ShowS Source #
Eq RenderOptions Source # |
Instance details Defined in Text.XmlHtml.Common Methods (==) :: RenderOptions -> RenderOptions -> Bool Source # (/=) :: RenderOptions -> RenderOptions -> Bool Source #

data AttrSurround Source #

Constructors

SurroundDoubleQuote |
SurroundSingleQuote |

#### Instances

Instances details

Show AttrSurround Source # |
Instance details Defined in Text.XmlHtml.Common Methods showsPrec :: Int -> AttrSurround -> ShowS Source # show :: AttrSurround -> String Source # showList :: [AttrSurround] -> ShowS Source #
Eq AttrSurround Source # |
Instance details Defined in Text.XmlHtml.Common Methods (==) :: AttrSurround -> AttrSurround -> Bool Source # (/=) :: AttrSurround -> AttrSurround -> Bool Source #
Ord AttrSurround Source # |

Instance details

Defined in Text.XmlHtml.Common

Methods

compare :: AttrSurround -> AttrSurround -> Ordering Source #

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

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

(>) :: AttrSurround -> AttrSurround -> Bool Source #

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

max :: AttrSurround -> AttrSurround -> AttrSurround Source #

min :: AttrSurround -> AttrSurround -> AttrSurround Source #

data AttrResolveInternalQuotes Source #

Constructors

AttrResolveByEscape |
AttrResolveAvoidEscape |

#### Instances

Instances details

Show AttrResolveInternalQuotes Source # |
Instance details Defined in Text.XmlHtml.Common Methods showsPrec :: Int -> AttrResolveInternalQuotes -> ShowS Source # show :: AttrResolveInternalQuotes -> String Source # showList :: [AttrResolveInternalQuotes] -> ShowS Source #
Eq AttrResolveInternalQuotes Source # |
Instance details Defined in Text.XmlHtml.Common Methods (==) :: AttrResolveInternalQuotes -> AttrResolveInternalQuotes -> Bool Source # (/=) :: AttrResolveInternalQuotes -> AttrResolveInternalQuotes -> Bool Source #
Ord AttrResolveInternalQuotes Source # |

Instance details

Defined in Text.XmlHtml.Common

Methods

compare :: AttrResolveInternalQuotes -> AttrResolveInternalQuotes -> Ordering Source #

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

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

(>) :: AttrResolveInternalQuotes -> AttrResolveInternalQuotes -> Bool Source #

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

max :: AttrResolveInternalQuotes -> AttrResolveInternalQuotes -> AttrResolveInternalQuotes Source #

min :: AttrResolveInternalQuotes -> AttrResolveInternalQuotes -> AttrResolveInternalQuotes Source #

# Manipulating documents

isTextNode :: Node -> Bool Source #

Determines whether the node is text or not.

isComment :: Node -> Bool Source #

Determines whether the node is a comment or not.

isElement :: Node -> Bool Source #

Determines whether the node is an element or not.

tagName :: Node -> Maybe Text Source #

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

getAttribute :: Text -> Node -> Maybe Text Source #

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

hasAttribute :: Text -> Node -> Bool Source #

Checks if a given attribute exists in a `Node`.

setAttribute :: Text -> Text -> Node -> Node Source #

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

nodeText :: Node -> Text Source #

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

childNodes :: Node -> [Node] Source #

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

childElements :: Node -> [Node] Source #

Gives the child elements of the given node.

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

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

childElementTag :: Text -> Node -> Maybe Node Source #

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] Source #

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

descendantElements :: Node -> [Node] Source #

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

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

Gives the descendant elements with a given tag name.

descendantElementTag :: Text -> Node -> Maybe Node Source #

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

# Parsing

parseXML Source #

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 Source #

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 Source #

renderWithOptions :: RenderOptions -> Document -> Builder Source #

Renders a `Document`.

defaultRenderOptions :: RenderOptions Source #

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

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

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

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

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

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

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

renderDocType :: Encoding -> Maybe DocType -> Builder Source #