Text.XML.LibXML.SAX

libxml-sax-0.7.5: Bindings for the libXML2 SAX interface

Copyright | 2010 John Millikin
License | MIT
Maintainer | jmillikin@gmail.com
Portability | portable
Safe Haskell | None
Language | Haskell98

Text.XML.LibXML.SAX

Contents

- Parser
  - Parser input
- Callbacks
  - Parse events
  - Warning and error reporting

Description

Bindings for the libXML2 SAX interface

Synopsis

- data Parser m
- newParserIO :: Maybe Text -> IO (Parser IO)
- newParserST :: Maybe Text -> ST s (Parser (ST s))
- parseBytes :: Parser m -> ByteString -> m ()
- parseComplete :: Parser m -> m ()
- data Callback m a
- setCallback :: Parser m -> Callback m a -> a -> m ()
- clearCallback :: Parser m -> Callback m a -> m ()
- parsedBeginDocument :: Callback m (m Bool)
- parsedEndDocument :: Callback m (m Bool)
- parsedBeginElement :: Callback m (Name -> [(Name, [Content])] -> m Bool)
- parsedEndElement :: Callback m (Name -> m Bool)
- parsedCharacters :: Callback m (Text -> m Bool)
- parsedReference :: Callback m (Text -> m Bool)
- parsedComment :: Callback m (Text -> m Bool)
- parsedInstruction :: Callback m (Instruction -> m Bool)
- parsedCDATA :: Callback m (Text -> m Bool)
- parsedWhitespace :: Callback m (Text -> m Bool)
- parsedInternalSubset :: Callback m (Text -> Maybe ExternalID -> m Bool)
- parsedExternalSubset :: Callback m (Text -> Maybe ExternalID -> m Bool)
- reportWarning :: Callback m (Text -> m Bool)
- reportError :: Callback m (Text -> m Bool)

# Parser

data Parser m

A `Parser` tracks the internal state of a LibXML parser context.

As LibXML is a very stateful library, parsers must operate within either the `IO` or `ST` monad. Use `newParserIO` or `newParserST` to create parsers in the appropriate monad.

In general, clients should prefer `newParserST`, because ST values can be safely computed with no side effects.

newParserIO

Arguments

:: Maybe Text | An optional filename or URI
-> IO (Parser IO) |

newParserST

Arguments

:: Maybe Text | An optional filename or URI
-> ST s (Parser (ST s)) |

## Parser input

parseBytes :: Parser m -> ByteString -> m ()

parseComplete :: Parser m -> m ()

Finish parsing any buffered data, and check that the document was closed correctly.

# Callbacks

data Callback m a

setCallback :: Parser m -> Callback m a -> a -> m ()

Set a callback computation to run when a particular parse event occurs. The callback should return `True` to continue parsing, or `False` to abort.

Alternatively, callbacks may throw an `Exception` to abort parsing. The exception will be propagated through to the caller of `parseBytes` or `parseComplete`.

clearCallback :: Parser m -> Callback m a -> m ()

Remove a callback from the parser. This might also change the parser's behavior, such as automatically expanding entity references when no `parsedReference` callback is set.

## Parse events

parsedBeginDocument :: Callback m (m Bool)

parsedEndDocument :: Callback m (m Bool)

parsedBeginElement :: Callback m (Name -> [(Name, [Content])] -> m Bool)

parsedEndElement :: Callback m (Name -> m Bool)

parsedCharacters :: Callback m (Text -> m Bool)

parsedReference :: Callback m (Text -> m Bool)

If `parsedReference` is set, entity references in element and attribute content will reported separately from text, and will not be automatically expanded.

Use this when processing documents in passthrough mode, to preserve existing entity references.

parsedComment :: Callback m (Text -> m Bool)

parsedInstruction :: Callback m (Instruction -> m Bool)

parsedCDATA :: Callback m (Text -> m Bool)

If `parsedCDATA` is set, it receives any text contained in CDATA blocks. By default, all text is received by `parsedCharacters`.

parsedWhitespace :: Callback m (Text -> m Bool)

If `parsedWhitespace` is set, it receives any whitespace marked as ignorable by the document's DTD. By default, all text is received by `parsedCharacters`.

parsedInternalSubset :: Callback m (Text -> Maybe ExternalID -> m Bool)

parsedExternalSubset :: Callback m (Text -> Maybe ExternalID -> m Bool)

## Warning and error reporting

reportWarning :: Callback m (Text -> m Bool)

reportError :: Callback m (Text -> m Bool)