hexpat-0.19.10: XML parser/formatter based on expat

Safe Haskell | None

Text.XML.Expat.SAX

Contents

- XML primitives
- SAX-style parse
- Variants that throw exceptions
- Helpers
- Abstraction of string types
- Deprecated parse functions

Description

This module provides functions to parse an XML document to a lazy stream of SAX events.

Synopsis

- data Encoding
  - = ASCII
  - | UTF8
  - | UTF16
  - | ISO88591
- data XMLParseError = XMLParseError String XMLParseLocation
- data XMLParseLocation = XMLParseLocation {
  - xmlLineNumber :: Int64
  - xmlColumnNumber :: Int64
  - xmlByteIndex :: Int64
  - xmlByteCount :: Int64
  }
- data ParseOptions tag text = ParseOptions {
  - overrideEncoding :: Maybe Encoding
  - entityDecoder :: Maybe (tag -> Maybe text)
  }
- data SAXEvent tag text
  - = XMLDeclaration text (Maybe text) (Maybe Bool)
  - | StartElement tag [(tag, text)]
  - | EndElement tag
  - | CharacterData text
  - | StartCData
  - | EndCData
  - | ProcessingInstruction text text
  - | Comment text
  - | FailDocument XMLParseError
- textFromCString :: GenericXMLString text => CString -> IO text
- parse :: (GenericXMLString tag, GenericXMLString text) => ParseOptions tag text -> ByteString -> [SAXEvent tag text]
- parseG :: forall tag text l. (GenericXMLString tag, GenericXMLString text, List l) => ParseOptions tag text -> l ByteString -> l (SAXEvent tag text)
- parseLocations :: (GenericXMLString tag, GenericXMLString text) => ParseOptions tag text -> ByteString -> [(SAXEvent tag text, XMLParseLocation)]
- parseLocationsG :: forall tag text l. (GenericXMLString tag, GenericXMLString text, List l) => ParseOptions tag text -> l ByteString -> l (SAXEvent tag text, XMLParseLocation)
- parseLocationsThrowing :: (GenericXMLString tag, GenericXMLString text) => ParseOptions tag text -> ByteString -> [(SAXEvent tag text, XMLParseLocation)]
- parseThrowing :: (GenericXMLString tag, GenericXMLString text) => ParseOptions tag text -> ByteString -> [SAXEvent tag text]
- defaultParseOptions :: ParseOptions tag text
- data XMLParseException = XMLParseException XMLParseError
- setEntityDecoder :: (GenericXMLString tag, GenericXMLString text) => Parser -> (tag -> Maybe text) -> (ParserPtr -> text -> IO ()) -> IO ()
- 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
- parseSAX :: (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)]
- parseSAXThrowing :: (GenericXMLString tag, GenericXMLString text) => Maybe Encoding -> ByteString -> [SAXEvent tag text]
- type ParserOptions tag text = ParseOptions tag text
- defaultParserOptions :: ParseOptions tag text

# XML primitives

data Encoding

Encoding types available for the document encoding.

Constructors

ASCII |
UTF8 |
UTF16 |
ISO88591 |

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 |

# SAX-style parse

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

data SAXEvent tag text

Constructors

XMLDeclaration text (Maybe text) (Maybe Bool) |
StartElement tag [(tag, text)] |
EndElement tag |
CharacterData text |
StartCData |
EndCData |
ProcessingInstruction text text |
Comment text |
FailDocument XMLParseError |

Instances

(Eq tag, Eq text) => Eq (SAXEvent tag text) |
(Show tag, Show text) => Show (SAXEvent tag text) |
(NFData tag, NFData text) => NFData (SAXEvent tag text) |

textFromCString :: GenericXMLString text => CString -> IO text

Converts a `CString` to a `GenericXMLString` type.

parse

Arguments

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

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

parseG

Arguments

:: forall tag text l . (GenericXMLString tag, GenericXMLString text, List l) |
=> ParseOptions tag text | Parse options
-> l ByteString | Input text (a lazy ByteString)
-> l (SAXEvent tag text) |

Parse a generalized list of ByteStrings containing XML to SAX events. In the event of an error, FailDocument is the last element of the output list.

parseLocations

Arguments

:: (GenericXMLString tag, GenericXMLString text) |
=> ParseOptions tag text | Parse options
-> ByteString | Input text (a lazy ByteString)
-> [(SAXEvent tag text, XMLParseLocation)] |

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

parseLocationsG

Arguments

:: forall tag text l . (GenericXMLString tag, GenericXMLString text, List l) |
=> ParseOptions tag text | Parse options
-> l ByteString | Input text (a lazy ByteString)
-> l (SAXEvent tag text, XMLParseLocation) |

Parse a generalized list of ByteStrings containing XML to SAX events. In the event of an error, FailDocument is the last element of the output list.

parseLocationsThrowing

Arguments

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

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

`parseLocationsThrowing` 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.

parseThrowing

Arguments

:: (GenericXMLString tag, GenericXMLString text) |
=> ParseOptions tag text | Parse options
-> ByteString | input text (a lazy ByteString)
-> [SAXEvent tag text] |

Lazily parse XML to SAX events. 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.

defaultParseOptions :: ParseOptions tag text

# Variants that throw exceptions

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 |

# Helpers

setEntityDecoder

Arguments

:: (GenericXMLString tag, GenericXMLString text) |
=> Parser |
-> (tag -> Maybe text) | Entity decoder
-> (ParserPtr -> text -> IO ()) | Code to insert character data into the document
-> IO () |

A helper for configuring the hexpat parser to use the specified entity decoder.

# 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 parse functions

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`

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

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

type ParserOptions tag text = ParseOptions tag text

Deprecated: renamed to ParseOptions

defaultParserOptions :: ParseOptions tag text

Deprecated: renamed to defaultParseOptions

DEPRECATED. Renamed to defaultParseOptions.