Text.XML.Expat.Internal.IO

Low-level interface to Expat. Unless speed is paramount, this should normally be avoided in favour of the interfaces provided by Text.XML.Expat.SAX and Text.XML.Expat.Tree. Basic usage is:

1. Make a new parser: newParser.
2. Set up callbacks on the parser: setStartElementHandler, etc.
3. Feed data into the parser: parse, parse' or parseChunk. Some of these functions must be wrapped in withParser.

Parser Setup

data Parser

Instances

Show Parser

newParser :: Maybe Encoding -> IO Parser

Create a Parser.

Parsing

parse :: Parser -> ByteString -> IO (Maybe XMLParseError)

parse data feeds lazy ByteString data into a Parser. It returns Nothing on success, or Just the parse error.

parse' :: Parser -> ByteString -> IO (Maybe XMLParseError)

parse data feeds strict ByteString data into a Parser. It returns Nothing on success, or Just the parse error.

withParser

Arguments

:: Parser

-> (ParserPtr -> IO a)

Computation where parseChunk and other low-level functions may be used

-> IO a

Most of the low-level functions take a ParserPtr so are required to be called inside withParser.

type ParserPtr = Ptr Parser_struct

data Parser_struct

Opaque parser type.

parseChunk :: ParserPtr -> ByteString -> Bool -> IO (Maybe XMLParseError)

parseChunk data False feeds strict ByteString data into a Parser. The end of the data is indicated by passing True for the final parameter. It returns Nothing on success, or Just the parse error.

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

getParseLocation :: ParserPtr -> IO XMLParseLocation

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

Parser Callbacks

type StartElementHandler = ParserPtr -> CString -> [(CString, CString)] -> IO Bool

The type of the "element started" callback. The first parameter is the element name; the second are the (attribute, value) pairs. Return True to continue parsing as normal, or False to terminate the parse.

type EndElementHandler = ParserPtr -> CString -> IO Bool

The type of the "element ended" callback. The parameter is the element name. Return True to continue parsing as normal, or False to terminate the parse.

type CharacterDataHandler = ParserPtr -> CStringLen -> IO Bool

The type of the "character data" callback. The parameter is the character data processed. This callback may be called more than once while processing a single conceptual block of text. Return True to continue parsing as normal, or False to terminate the parse.

type ExternalEntityRefHandler = Parser -> CString -> CString -> CString -> CString -> IO Bool

The type of the "external entity reference" callback. See the expat documentation.

type SkippedEntityHandler = ParserPtr -> CString -> Int -> IO Bool

Set a skipped entity handler. This is called in two situations:

1. An entity reference is encountered for which no declaration has been read and this is not an error.
2. An internal entity reference is read, but not expanded, because XML_SetDefaultHandler has been called.

setStartElementHandler :: Parser -> StartElementHandler -> IO ()

Attach a StartElementHandler to a Parser.

setEndElementHandler :: Parser -> EndElementHandler -> IO ()

Attach an EndElementHandler to a Parser.

setCharacterDataHandler :: Parser -> CharacterDataHandler -> IO ()

Attach an CharacterDataHandler to a Parser.

setExternalEntityRefHandler :: Parser -> ExternalEntityRefHandler -> IO ()

setSkippedEntityHandler :: Parser -> SkippedEntityHandler -> IO ()

setUseForeignDTD :: Parser -> Bool -> IO ()

Lower-level interface

parseExternalEntityReference

Arguments

:: Parser

-> CString

context

-> Maybe Encoding

encoding

-> CStringLen

text

-> IO Bool

data ExpatHandlers

Helpers

encodingToString :: Encoding -> String