Text.XML.Expat.Internal.IO

hexpat-0.19.10: XML parser/formatter based on expat

Safe Haskell | None

Text.XML.Expat.Internal.IO

Contents

- Parser Setup
- Parsing
- Parser Callbacks
- Lower-level interface
- Helpers

Description

Low-level interface to Expat. Unless speed is paramount, this should normally be avoided in favour of the interfaces provided by `SAX` and `Tree`, etc. 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`.

Synopsis

- data Parser
- newParser :: Maybe Encoding -> IO Parser
- parse :: Parser -> ByteString -> IO (Maybe XMLParseError)
- parse' :: Parser -> ByteString -> IO (Maybe XMLParseError)
- withParser :: Parser -> (ParserPtr -> IO a) -> IO a
- type ParserPtr = Ptr Parser_struct
- data Parser_struct
- parseChunk :: ParserPtr -> ByteString -> Bool -> IO (Maybe XMLParseError)
- data Encoding
  - = ASCII
  - | UTF8
  - | UTF16
  - | ISO88591
- data XMLParseError = XMLParseError String XMLParseLocation
- getParseLocation :: ParserPtr -> IO XMLParseLocation
- data XMLParseLocation = XMLParseLocation {
  - xmlLineNumber :: Int64
  - xmlColumnNumber :: Int64
  - xmlByteIndex :: Int64
  - xmlByteCount :: Int64
  }
- type XMLDeclarationHandler = ParserPtr -> CString -> CString -> CInt -> IO Bool
- type StartElementHandler = ParserPtr -> CString -> [(CString, CString)] -> IO Bool
- type EndElementHandler = ParserPtr -> CString -> IO Bool
- type CharacterDataHandler = ParserPtr -> CStringLen -> IO Bool
- type ExternalEntityRefHandler = Parser -> CString -> CString -> CString -> CString -> IO Bool
- type SkippedEntityHandler = ParserPtr -> CString -> Int -> IO Bool
- type StartCDataHandler = ParserPtr -> IO Bool
- type EndCDataHandler = ParserPtr -> IO Bool
- type CommentHandler = ParserPtr -> CString -> IO Bool
- type ProcessingInstructionHandler = ParserPtr -> CString -> CString -> IO Bool
- setXMLDeclarationHandler :: Parser -> XMLDeclarationHandler -> IO ()
- setStartElementHandler :: Parser -> StartElementHandler -> IO ()
- setEndElementHandler :: Parser -> EndElementHandler -> IO ()
- setCharacterDataHandler :: Parser -> CharacterDataHandler -> IO ()
- setStartCDataHandler :: Parser -> StartCDataHandler -> IO ()
- setEndCDataHandler :: Parser -> EndCDataHandler -> IO ()
- setProcessingInstructionHandler :: Parser -> ProcessingInstructionHandler -> IO ()
- setCommentHandler :: Parser -> CommentHandler -> IO ()
- setExternalEntityRefHandler :: Parser -> ExternalEntityRefHandler -> IO ()
- setSkippedEntityHandler :: Parser -> SkippedEntityHandler -> IO ()
- setUseForeignDTD :: Parser -> Bool -> IO ()
- parseExternalEntityReference :: Parser -> CString -> Maybe Encoding -> CStringLen -> IO Bool
- data ExpatHandlers
- encodingToString :: Encoding -> String

## 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 XMLDeclarationHandler = ParserPtr -> CString -> CString -> CInt -> IO Bool

The type of the "XML declaration" callback. Parameters are version, encoding (which can be nullPtr), and standalone declaration, where -1 = no declaration, 0 = no and 1 = yes. Return True to continue parsing as normal, or False to terminate the parse.

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.

type StartCDataHandler = ParserPtr -> IO Bool

The type of the "start cdata" callback. Return True to continue parsing as normal, or False to terminate the parse.

type EndCDataHandler = ParserPtr -> IO Bool

The type of the "end cdata" callback. Return True to continue parsing as normal, or False to terminate the parse.

type CommentHandler = ParserPtr -> CString -> IO Bool

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

type ProcessingInstructionHandler = ParserPtr -> CString -> CString -> IO Bool

The type of the "processing instruction" callback. The first parameter is the first word in the processing instruction. The second parameter is the rest of the characters in the processing instruction after skipping all whitespace after the initial word. Return True to continue parsing as normal, or False to terminate the parse.

setXMLDeclarationHandler :: Parser -> XMLDeclarationHandler -> IO ()

Attach a XMLDeclarationHandler to a Parser.

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.

setStartCDataHandler :: Parser -> StartCDataHandler -> IO ()

Attach a StartCDataHandler to a Parser.

setEndCDataHandler :: Parser -> EndCDataHandler -> IO ()

Attach a EndCDataHandler to a Parser.

setProcessingInstructionHandler :: Parser -> ProcessingInstructionHandler -> IO ()

Attach a ProcessingInstructionHandler to a Parser.

setCommentHandler :: Parser -> CommentHandler -> IO ()

Attach a CommentHandler 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