|
|
|
|
|
Description |
This module provides functions to parse an XML document to a tree structure,
either strictly or lazily, as well as a lazy SAX-style interface.
The GenericXMLString type class allows you to use any string type. Three
string types are provided for here: String, ByteString and Text.
Here is a complete example to get you started:
-- | A "hello world" example of hexpat that lazily parses a document, printing
-- it to standard out.
import Text.XML.Expat.Tree
import Text.XML.Expat.Format
import System.Environment
import System.Exit
import System.IO
import qualified Data.ByteString.Lazy as L
main = do
args <- getArgs
case args of
[filename] -> process filename
otherwise -> do
hPutStrLn stderr "Usage: helloworld <file.xml>"
exitWith $ ExitFailure 1
process :: String -> IO ()
process filename = do
inputText <- L.readFile filename
-- Note: Because we're not using the tree, Haskell can't infer the type of
-- strings we're using so we need to tell it explicitly with a type signature.
let (xml, mErr) = parseTree Nothing inputText :: (UNode String, Maybe XMLParseError)
-- Process document before handling error, so we get lazy processing.
L.hPutStr stdout $ formatTree xml
putStrLn ""
case mErr of
Nothing -> return ()
Just err -> do
hPutStrLn stderr $ "XML parse failed: "++show err
exitWith $ ExitFailure 2
Error handling in strict parses is very straight forward - just check the
Either return value. Lazy parses are not so simple. Here are two working
examples that illustrate the ways to handle errors. Here they are:
Way no. 1 - Using a Maybe value
import Text.XML.Expat.Tree
import qualified Data.ByteString.Lazy as L
import Data.ByteString.Internal (c2w)
-- This is the recommended way to handle errors in lazy parses
main = do
let (tree, mError) = parseTree Nothing (L.pack $ map c2w $ "<top><banana></apple></top>")
print (tree :: UNode String)
-- Note: We check the error _after_ we have finished our processing on the tree.
case mError of
Just err -> putStrLn $ "It failed : "++show err
Nothing -> putStrLn "Success!"
Way no. 2 - Using exceptions
Unless exceptions fit in with the design of your program, this way is less preferred.
...
import Control.Exception.Extensible as E
-- This is not the recommended way to handle errors.
main = do
do
let tree = parseTreeThrowing Nothing (L.pack $ map c2w $ "<top><banana></apple></top>")
print (tree :: UNode String)
-- Because of lazy evaluation, you should not process the tree outside the 'do' block,
-- or exceptions could be thrown that won't get caught.
`E.catch` (\exc ->
case E.fromException exc of
Just (XMLParseException err) -> putStrLn $ "It failed : "++show err
Nothing -> E.throwIO exc)
|
|
Synopsis |
|
| | type Nodes tag text = [Node tag text] | | type Attributes tag text = [(tag, text)] | | type UNode text = Node text text | | type UNodes text = Nodes text text | | type UAttributes text = Attributes text text | | extractText :: Monoid text => Node tag text -> text | | parseTree :: (GenericXMLString tag, GenericXMLString text) => Maybe Encoding -> ByteString -> (Node tag text, Maybe XMLParseError) | | parseTree' :: (GenericXMLString tag, GenericXMLString text) => Maybe Encoding -> ByteString -> Either XMLParseError (Node tag text) | | | | data XMLParseError = XMLParseError String XMLParseLocation | | data XMLParseLocation = XMLParseLocation {} | | parseSAX :: (GenericXMLString tag, GenericXMLString text) => Maybe Encoding -> ByteString -> [SAXEvent tag text] | | | | saxToTree :: GenericXMLString tag => [SAXEvent tag text] -> (Node tag text, Maybe XMLParseError) | | parseSAXLocations :: (GenericXMLString tag, GenericXMLString text) => Maybe Encoding -> ByteString -> [(SAXEvent tag text, XMLParseLocation)] | | data XMLParseException = XMLParseException XMLParseError | | parseSAXThrowing :: (GenericXMLString tag, GenericXMLString text) => Maybe Encoding -> ByteString -> [SAXEvent tag text] | | parseTreeThrowing :: (GenericXMLString tag, GenericXMLString text) => Maybe Encoding -> ByteString -> Node tag text | | class (Monoid s, Eq s) => GenericXMLString s where | |
|
|
|
Tree structure
|
|
|
The tree representation of the XML document.
| Constructors | Element | | eName :: !tag | | eAttrs :: ![(tag, text)] | | eChildren :: [Node tag text] | |
| Text !text | |
| Instances | |
|
|
|
Type shortcut for nodes
|
|
type Attributes tag text = [(tag, text)] | Source |
|
Type shortcut for attributes
|
|
|
Type shortcut for a single node with unqualified tag names where tag and
text are the same string type.
|
|
|
Type shortcut for nodes with unqualified tag names where tag and
text are the same string type.
|
|
|
Type shortcut for attributes with unqualified names where tag and
text are the same string type.
|
|
|
Extract all text content from inside a tag into a single string, including
any text contained in children.
|
|
Parse to tree
|
|
|
|
|
|
|
|
|
Encoding types available for the document encoding.
| Constructors | |
|
|
|
Parse error, consisting of message text and error location
| Constructors | | Instances | |
|
|
|
Specifies a location of an event within the input text
| Constructors | XMLParseLocation | | 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 | |
|
|
SAX-style parse
|
|
|
|
|
|
Constructors | StartElement tag [(tag, text)] | | EndElement tag | | CharacterData text | | FailDocument XMLParseError | |
| Instances | |
|
|
|
A lower level function that lazily converts a SAX stream into a tree structure.
|
|
|
|
|
Variants that throw exceptions
|
|
|
An exception indicating an XML parse error, used by the ..Throwing variants.
| Constructors | | Instances | |
|
|
|
|
|
|
|
|
Abstraction of string types
|
|
|
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 | | | Instances | |
|
|
Produced by Haddock version 2.4.2 |