hexpat-0.19.10: XML parser/formatter based on expat

Safe Haskell | None

Text.XML.Expat.Annotated

Contents

- Tree structure
- Generic node manipulation
- Annotation-specific
- Qualified nodes
- Namespaced nodes
- Parse to tree
- Variant that throws exceptions
- Convert from SAX
- Abstraction of string types
- Deprecated

Description

A variant of Node in which Element nodes have an annotation of any type, and some concrete functions that annotate with the XML parse location.

The names conflict with those in Tree so you must use qualified import if you want to use both modules.

Synopsis

- type Node a tag text = NodeG a [] tag text
- data NodeG a c tag text
  - = Element {
    - eName :: !tag
    - eAttributes :: ![(tag, text)]
    - eChildren :: c (NodeG a c tag text)
    - eAnn :: a
    }
  - | Text !text
- type UNode a text = Node a text text
- type LNode tag text = Node XMLParseLocation tag text
- type ULNode text = LNode text text
- module Text.XML.Expat.Internal.NodeClass
- modifyAnnotation :: (a -> a) -> Node a tag text -> Node a tag text
- mapAnnotation :: (a -> b) -> Node a tag text -> Node b tag text
- type QNode a text = Node a (QName text) text
- type QLNode text = LNode (QName text) text
- module Text.XML.Expat.Internal.Qualified
- type NNode a text = Node a (NName text) text
- type NLNode text = LNode (NName text) text
- module Text.XML.Expat.Internal.Namespaced
- data ParseOptions tag text = ParseOptions {
  - overrideEncoding :: Maybe Encoding
  - entityDecoder :: Maybe (tag -> Maybe text)
  }
- defaultParseOptions :: ParseOptions tag text
- data Encoding
  - = ASCII
  - | UTF8
  - | UTF16
  - | ISO88591
- parse :: (GenericXMLString tag, GenericXMLString text) => ParseOptions tag text -> ByteString -> (LNode tag text, Maybe XMLParseError)
- parse' :: (GenericXMLString tag, GenericXMLString text) => ParseOptions tag text -> ByteString -> Either XMLParseError (LNode tag text)
- parseG :: (GenericXMLString tag, GenericXMLString text, List l) => ParseOptions tag text -> l ByteString -> ItemM l (NodeG XMLParseLocation l tag text)
- data XMLParseError = XMLParseError String XMLParseLocation
- data XMLParseLocation = XMLParseLocation {
  - xmlLineNumber :: Int64
  - xmlColumnNumber :: Int64
  - xmlByteIndex :: Int64
  - xmlByteCount :: Int64
  }
- parseThrowing :: (GenericXMLString tag, GenericXMLString text) => ParseOptions tag text -> ByteString -> LNode tag text
- data XMLParseException = XMLParseException XMLParseError
- saxToTree :: GenericXMLString tag => [(SAXEvent tag text, a)] -> (Node a tag text, Maybe XMLParseError)
- saxToTreeG :: forall l a tag text. (GenericXMLString tag, List l, Monad (ItemM l)) => l (SAXEvent tag text, a) -> ItemM l (NodeG a l tag text)
- class (Monoid s, Eq s) => GenericXMLString s where
  - gxNullString :: s -> Bool
  - gxToString :: s -> String
  - gxFromString :: String -> s
  - gxFromChar :: Char -> s
  - gxHead :: s -> Char
  - gxTail :: s -> s
  - gxBreakOn :: Char -> s -> (s, s)
  - gxFromCStringLen :: CStringLen -> IO s
  - gxToByteString :: s -> ByteString
- eAttrs :: Node a tag text -> [(tag, text)]
- parseSAX :: (GenericXMLString tag, GenericXMLString text) => Maybe Encoding -> ByteString -> [SAXEvent tag text]
- parseSAXThrowing :: (GenericXMLString tag, GenericXMLString text) => Maybe Encoding -> ByteString -> [SAXEvent tag text]
- parseSAXLocations :: (GenericXMLString tag, GenericXMLString text) => Maybe Encoding -> ByteString -> [(SAXEvent tag text, XMLParseLocation)]
- parseSAXLocationsThrowing :: (GenericXMLString tag, GenericXMLString text) => Maybe Encoding -> ByteString -> [(SAXEvent tag text, XMLParseLocation)]
- parseTree :: (GenericXMLString tag, GenericXMLString text) => Maybe Encoding -> ByteString -> (LNode tag text, Maybe XMLParseError)
- parseTree' :: (GenericXMLString tag, GenericXMLString text) => Maybe Encoding -> ByteString -> Either XMLParseError (LNode tag text)
- parseTreeThrowing :: (GenericXMLString tag, GenericXMLString text) => Maybe Encoding -> ByteString -> LNode tag text
- unannotate :: Functor c => NodeG a c tag text -> NodeG c tag text
- type ParserOptions tag text = ParseOptions tag text
- defaultParserOptions :: ParseOptions tag text

# Tree structure

type Node a tag text = NodeG a [] tag text

A pure tree representation that uses a list as its container type, annotated variant.

In the `hexpat` package, a list of nodes has the type `[Node tag text]`, but note that you can also use the more general type function `ListOf` to give a list of any node type, using that node's associated list type, e.g. `ListOf (UNode Text)`.

data NodeG a c tag text

Annotated variant of the tree representation of the XML document, meaning that it has an extra piece of information of your choice attached to each Element.

`c` is the container type for the element's children, which is [] in the `hexpat` package, and a monadic list type for `hexpat-iteratee`.

`tag` is the tag type, which can either be one of several string types, or a special type from the `Text.XML.Expat.Namespaced` or `Text.XML.Expat.Qualified` modules.

`text` is the string type for text content.

`a` is the type of the annotation. One of the things this can be used for is to store the XML parse location, which is useful for error handling.

Note that some functions in the `Text.XML.Expat.Cursor` module need to create new nodes through the `MkElementClass` type class. Normally this can only be done if `a` is a Maybe type or () (so it can provide the Nothing value for the annotation on newly created nodes). Or, you can write your own `MkElementClass` instance. Apart from that, there is no requirement for `a` to be a Maybe type.

Constructors

Element |

Fields

eName :: !tag
eAttributes :: ![(tag, text)]
eChildren :: c (NodeG a c tag text)
eAnn :: a

Text !text |

Instances

(Functor c, List c) => MkElementClass (NodeG ()) c |
(Functor c, List c) => MkElementClass (NodeG (Maybe a)) c |
(Functor c, List c) => NodeClass (NodeG a) c |
(Eq tag, Eq text, Eq a) => Eq (NodeG a [] tag text) |
(Show tag, Show text, Show a) => Show (NodeG a [] tag text) |
(NFData tag, NFData text, NFData a) => NFData (NodeG a [] tag text) |

type UNode a text = Node a text text

Type alias for an annotated node with unqualified tag names where tag and text are the same string type

type LNode tag text = Node XMLParseLocation tag text

Type alias for an annotated node, annotated with parse location

type ULNode text = LNode text text

Type alias for an annotated node with unqualified tag names where tag and text are the same string type, annotated with parse location

# Generic node manipulation

module Text.XML.Expat.Internal.NodeClass

# Annotation-specific

modifyAnnotation :: (a -> a) -> Node a tag text -> Node a tag text

Modify this node's annotation (non-recursively) if it's an element, otherwise no-op.

mapAnnotation :: (a -> b) -> Node a tag text -> Node b tag text

Modify this node's annotation and all its children recursively if it's an element, otherwise no-op.

# Qualified nodes

type QNode a text = Node a (QName text) text

Type alias for an annotated node where qualified names are used for tags

type QLNode text = LNode (QName text) text

Type alias for an annotated node where qualified names are used for tags, annotated with parse location

module Text.XML.Expat.Internal.Qualified

# Namespaced nodes

type NNode a text = Node a (NName text) text

Type alias for an annotated node where namespaced names are used for tags

type NLNode text = LNode (NName text) text

Type alias for an annotated node where namespaced names are used for tags, annotated with parse location

module Text.XML.Expat.Internal.Namespaced

# Parse to tree

data ParseOptions tag text

Constructors

ParseOptions |

Fields

overrideEncoding :: Maybe Encoding

  The encoding parameter, if provided, overrides the document's encoding declaration.

entityDecoder :: Maybe (tag -> Maybe text)

  If provided, entity references (i.e. `&nbsp;` and friends) will be decoded into text using the supplied lookup function

defaultParseOptions :: ParseOptions tag text

data Encoding

Encoding types available for the document encoding.

Constructors

ASCII |
UTF8 |
UTF16 |
ISO88591 |

parse

Arguments

:: (GenericXMLString tag, GenericXMLString text) |
=> ParseOptions tag text | Parse options
-> ByteString | Input text (a lazy ByteString)
-> (LNode tag text, Maybe XMLParseError) |

Lazily parse XML to tree. Note that forcing the XMLParseError return value will force the entire parse. Therefore, to ensure lazy operation, don't check the error status until you have processed the tree.

parse'

Arguments

:: (GenericXMLString tag, GenericXMLString text) |
=> ParseOptions tag text | Parse options
-> ByteString | Input text (a strict ByteString)
-> Either XMLParseError (LNode tag text) |

Strictly parse XML to tree. Returns error message or valid parsed tree.

parseG

Arguments

:: (GenericXMLString tag, GenericXMLString text, List l) |
=> ParseOptions tag text | Parse options
-> l ByteString | Input text as a generalized list of blocks
-> ItemM l (NodeG XMLParseLocation l tag text) |

Parse a generalized list to a tree, ignoring parse errors. This function allows for a parse from an enumerator/iteratee to a lazy tree structure using the `List-enumerator` package.

data XMLParseError

Parse error, consisting of message text and error location

Constructors

XMLParseError String XMLParseLocation |

Instances

Eq XMLParseError |
Show XMLParseError |
NFData XMLParseError |

data XMLParseLocation

Specifies a location of an event within the input text

Constructors

XMLParseLocation |

Fields

xmlLineNumber :: Int64

  Line number of the event

xmlColumnNumber :: Int64

  Column number of the event

xmlByteIndex :: Int64

  Byte index of event from start of document

xmlByteCount :: Int64

  The number of bytes in the event

Instances

Eq XMLParseLocation |
Show XMLParseLocation |
NFData XMLParseLocation |

# Variant that throws exceptions

parseThrowing

Arguments

:: (GenericXMLString tag, GenericXMLString text) |
=> ParseOptions tag text | Parse options
-> ByteString | Input text (a lazy ByteString)
-> LNode tag text |

Lazily parse XML to tree. In the event of an error, throw `XMLParseException`.

`parseThrowing` can throw an exception from pure code, which is generally a bad way to handle errors, because Haskell's lazy evaluation means it's hard to predict where it will be thrown from. However, it may be acceptable in situations where it's not expected during normal operation, depending on the design of your program.

data XMLParseException

An exception indicating an XML parse error, used by the ..Throwing variants.

Constructors

XMLParseException XMLParseError |

Instances

Eq XMLParseException |
Show XMLParseException |
Typeable XMLParseException |
Exception XMLParseException |

# Convert from SAX

saxToTree :: GenericXMLString tag => [(SAXEvent tag text, a)] -> (Node a tag text, Maybe XMLParseError)

A lower level function that lazily converts a SAX stream into a tree structure. Variant that takes annotations for start tags.

saxToTreeG :: forall l a tag text. (GenericXMLString tag, List l, Monad (ItemM l)) => l (SAXEvent tag text, a) -> ItemM l (NodeG a l tag text)

A lower level function that converts a generalized SAX stream into a tree structure. Ignores parse errors.

# Abstraction of string types

class (Monoid s, Eq s) => GenericXMLString s where

An abstraction for any string type you want to use as xml text (that is, attribute values or element text content). If you want to use a new string type with hexpat, you must make it an instance of `GenericXMLString`.

Methods

gxNullString :: s -> Bool

gxToString :: s -> String

gxFromString :: String -> s

gxFromChar :: Char -> s

gxHead :: s -> Char

gxTail :: s -> s

gxBreakOn :: Char -> s -> (s, s)

gxFromCStringLen :: CStringLen -> IO s

gxToByteString :: s -> ByteString

Instances

GenericXMLString String |
GenericXMLString ByteString |
GenericXMLString Text |

# Deprecated

eAttrs :: Node a tag text -> [(tag, text)]

Deprecated: use eAttributes instead

parseSAX

Arguments

:: (GenericXMLString tag, GenericXMLString text) |
=> Maybe Encoding | Optional encoding override
-> ByteString | Input text (a lazy ByteString)
-> [SAXEvent tag text] |

Deprecated: use Text.XML.Expat.SAX.parse instead

DEPRECATED: Use `parse` instead.

Lazily parse XML to SAX events. In the event of an error, FailDocument is the last element of the output list. Deprecated in favour of new `parse`

parseSAXThrowing

Arguments

:: (GenericXMLString tag, GenericXMLString text) |
=> Maybe Encoding | Optional encoding override
-> ByteString | Input text (a lazy ByteString)
-> [SAXEvent tag text] |

Deprecated: use Text.XML.Expat.SAX.parseThrowing instead

DEPRECATED: Use `parseThrowing` instead.

Lazily parse XML to SAX events. In the event of an error, throw `XMLParseException`.

parseSAXLocations

Arguments

:: (GenericXMLString tag, GenericXMLString text) |
=> Maybe Encoding | Optional encoding override
-> ByteString | Input text (a lazy ByteString)
-> [(SAXEvent tag text, XMLParseLocation)] |

Deprecated: use Text.XML.Expat.SAX.parseLocations instead

DEPRECATED: Use `parseLocations` instead.

A variant of parseSAX that gives a document location with each SAX event.

parseSAXLocationsThrowing

Arguments

:: (GenericXMLString tag, GenericXMLString text) |
=> Maybe Encoding | Optional encoding override
-> ByteString | Input text (a lazy ByteString)
-> [(SAXEvent tag text, XMLParseLocation)] |

Deprecated: use Text.XML.Expat.SAX.parseLocationsThrowing instead

DEPRECATED: Used `parseLocationsThrowing` instead.

A variant of parseSAX that gives a document location with each SAX event. In the event of an error, throw `XMLParseException`.

parseTree

Arguments

:: (GenericXMLString tag, GenericXMLString text) |
=> Maybe Encoding | Optional encoding override
-> ByteString | Input text (a lazy ByteString)
-> (LNode tag text, Maybe XMLParseError) |

Deprecated: use Text.XML.Annotated.parse instead

DEPRECATED: Use `parse` instead.

Lazily parse XML to tree. Note that forcing the XMLParseError return value will force the entire parse. Therefore, to ensure lazy operation, don't check the error status until you have processed the tree.

parseTree'

Arguments

:: (GenericXMLString tag, GenericXMLString text) |
=> Maybe Encoding | Optional encoding override
-> ByteString | Input text (a strict ByteString)
-> Either XMLParseError (LNode tag text) |

Deprecated: use Text.XML.Expat.parse' instead

DEPRECATED: use `parse` instead.

Strictly parse XML to tree. Returns error message or valid parsed tree.

parseTreeThrowing

Arguments

:: (GenericXMLString tag, GenericXMLString text) |
=> Maybe Encoding | Optional encoding override
-> ByteString | Input text (a lazy ByteString)
-> LNode tag text |

Deprecated: use Text.XML.Annotated.parseThrowing instead

DEPRECATED: use `parseThrowing` instead

Lazily parse XML to tree. In the event of an error, throw `XMLParseException`.

unannotate :: Functor c => NodeG a c tag text -> NodeG c tag text

Deprecated: use fromElement instead

Convert an annotated tree (Annotated module) into a non-annotated tree (Tree module). DEPRECATED in favour of `fromElement`.

type ParserOptions tag text = ParseOptions tag text

Deprecated: renamed to ParseOptions

defaultParserOptions :: ParseOptions tag text

Deprecated: renamed to defaultParseOptions

DEPRECATED. Renamed to defaultParseOptions.