@@ -1,6 +1,6 @@
11{-# LANGUAGE RecordWildCards #-}
22
3−-- | A module for first-approximation parsing of XML.
3+-- | A module for fast first-approximation parsing of XML.
44-- Note that entities, e.g. @&@, are not expanded.
55module Text.XML.Hexml(
66 Node, Attribute(..),
@@ -58,15 +58,22 @@ foreign import ccall node_attributes :: Ptr CDocument -> Ptr CNode -> Ptr CInt -
5858foreign import ccall node_childBy :: Ptr CDocument -> Ptr CNode -> Ptr CNode -> CString -> CInt -> IO (Ptr CNode)
5959foreign import ccall node_attributeBy :: Ptr CDocument -> Ptr CNode -> CString -> CInt -> IO (Ptr CAttr)
6060
61−-- | An XML document, created by 'documentParse'.
61+-- | A node in an XML document, created by 'documentParse', then calling functions such
62+-- as 'children' on that initial node.
6263data Node = Node BS.ByteString (ForeignPtr CDocument) (Ptr CNode)
6364
65+-- | An XML attribute, comprising of a name and a value. As an example,
66+-- @hello=\"world\"@ would produce @Attribute \"hello\" \"world\"@.
6467data Attribute = Attribute BS.ByteString BS.ByteString deriving (Show, Eq, Ord)
6568
6669instance Show Node where
6770 show d = "Node " ++ show (BS.unpack $ outer d)
6871
6972
73+-- | Parse a ByteString as an XML document, returning a 'Left' error message, or a 'Right' document.
74+-- Note that the returned node will have a 'name' of @\"\"@, no attributes, and content as per the document.
75+-- Often the first child will be the @<?xml ... ?>@ element. For documents which comprise a single
76+-- root element, use @'children' n !! 1@.
7077parse :: BS.ByteString -> Either BS.ByteString Node
7178parse src = unsafePerformIO $ BS.unsafeUseAsCStringLen (src <> BS.singleton '\0') $ \(str, len) -> do
7279 doc <- document_parse str (fromIntegral len - 1)
@@ -80,6 +87,8 @@ parse src = unsafePerformIO $ BS.unsafeUseAsCStringLen (src <> BS.singleton '\0'
8087 doc <- newForeignPtr document_free_funptr doc
8188 return $ Right $ Node src doc node
8289
90+-- | Given a node, rerender it to something with an equivalent parse tree.
91+-- Mostly useful for debugging - if you want the real source document use 'outer' instead.
8392render :: Node -> BS.ByteString
8493render (Node _ doc n) = unsafePerformIO $ withForeignPtr doc $ \d -> do
8594 i <- node_render d n nullPtr 0
@@ -100,15 +109,19 @@ attrPeek src doc a = unsafePerformIO $ withForeignPtr doc $ \_ -> do
100109 val <- applyStr src <$> peekElemOff (castPtr a) 1
101110 return $ Attribute name val
102111
112+-- | Get the name of a node, e.g. @<test />@ produces @\"test\"@.
103113name :: Node -> BS.ByteString
104114name = nodeBS 0
105115
116+-- | Get the inner text.
106117inner :: Node -> BS.ByteString
107118inner = nodeBS 1
108119
120+-- | Get the outer text.
109121outer :: Node -> BS.ByteString
110122outer = nodeBS 2
111123
124+-- | Get the contents of a node, the strings and child nodes.
112125contents :: Node -> [Either BS.ByteString Node]
113126contents n@(Node src _ _) = f (strStart inner) outers
114127 where