@@ -58,8 +58,8 @@ 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−-- | A node in an XML document, created by 'documentParse', then calling functions such
62−-- as 'children' on that initial node.
61+-- | A node in an XML document, created by 'parse', then calling functions such
62+-- as 'children' on that initial 'Node'.
6363data Node = Node BS.ByteString (ForeignPtr CDocument) (Ptr CNode)
6464
6565-- | An XML attribute, comprising of a name and a value. As an example,
@@ -72,7 +72,7 @@ instance Show Node where
7272
7373-- | Parse a ByteString as an XML document, returning a 'Left' error message, or a 'Right' document.
7474-- 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
75+-- Often the first child will be the @\<?xml ... ?\>@ element. For documents which comprise a single
7676-- root element, use @'children' n !! 1@.
7777parse :: BS.ByteString -> Either BS.ByteString Node
7878parse src = unsafePerformIO $ BS.unsafeUseAsCStringLen (src <> BS.singleton '\0') $ \(str, len) -> do
@@ -109,19 +109,25 @@ attrPeek src doc a = unsafePerformIO $ withForeignPtr doc $ \_ -> do
109109 val <- applyStr src <$> peekElemOff (castPtr a) 1
110110 return $ Attribute name val
111111
112−-- | Get the name of a node, e.g. @<test />@ produces @\"test\"@.
112+-- | Get the name of a node, e.g. @\<test /\>@ produces @\"test\"@.
113113name :: Node -> BS.ByteString
114114name = nodeBS 0
115115
116−-- | Get the inner text.
116+-- | Get the inner text, from inside the tag, e.g. @\<test /\>@ produces @\"\"@
117+-- and @\<test\>hello\</test\>@ produces @\"hello\"@.
118+-- The result will have identical layout/spacing to the source document.
117119inner :: Node -> BS.ByteString
118120inner = nodeBS 1
119121
120−-- | Get the outer text.
122+-- | Get the outer text, including the tag itself, e.g. @\<test /\>@ produces @\"\<test /\>\"@
123+-- and @\<test\>hello\</test\>@ produces @\"\<test\>hello\</test\>\"@.
124+-- The result will have identical layout/spacing to the source document.
121125outer :: Node -> BS.ByteString
122126outer = nodeBS 2
123127
124−-- | Get the contents of a node, the strings and child nodes.
128+-- | Get the contents of a node, including both the content strings (as 'Left', never blank) and
129+-- the direct child nodes (as 'Right').
130+-- If you only want the child nodes, use 'children'.
125131contents :: Node -> [Either BS.ByteString Node]
126132contents n@(Node src _ _) = f (strStart inner) outers
127133 where
@@ -133,6 +139,7 @@ contents n@(Node src _ _) = f (strStart inner) outers
133139 inner = nodeStr 1 n
134140 outers = map (nodeStr 2 &&& id) $ children n
135141
142+-- | Get the direct child nodes of this node.
136143children :: Node -> [Node]
137144children (Node src doc n) = unsafePerformIO $ withForeignPtr doc $ \d -> do
138145 alloca $ \count -> do
@@ -140,6 +147,7 @@ children (Node src doc n) = unsafePerformIO $ withForeignPtr doc $ \d -> do
140147 count <- fromIntegral <$> peek count
141148 return [Node src doc $ plusPtr res $ i*szNode | i <- [0..count-1]]
142149
150+-- | Get the attributes of this node.
143151attributes :: Node -> [Attribute]
144152attributes (Node src doc n) = unsafePerformIO $ withForeignPtr doc $ \d -> do
145153 alloca $ \count -> do
@@ -147,6 +155,10 @@ attributes (Node src doc n) = unsafePerformIO $ withForeignPtr doc $ \d -> do
147155 count <- fromIntegral <$> peek count
148156 return [attrPeek src doc $ plusPtr res $ i*szAttr | i <- [0..count-1]]
149157
158+-- | Get the direct children of this node which have a specific name.
159+-- A more efficient version of:
160+--
161+-- > childrenBy p s = filter (\n -> name n == s) $ children p
150162childrenBy :: Node -> BS.ByteString -> [Node]
151163childrenBy (Node src doc n) str = go nullPtr
152164 where
@@ -155,6 +167,10 @@ childrenBy (Node src doc n) str = go nullPtr
155167 r <- node_childBy d n old bs $ fromIntegral len
156168 return $ if r == nullPtr then [] else Node src doc r : go r
157169
170+-- | Get the first attribute of this node which has a specific name, if there is one.
171+-- A more efficient version of:
172+--
173+-- > attributeBy n s = listToMaybe $ filter (\(Attribute a _) -> a == s $ attributes n
158174attributeBy :: Node -> BS.ByteString -> Maybe Attribute
159175attributeBy (Node src doc n) str = unsafePerformIO $ withForeignPtr doc $ \d ->
160176 BS.unsafeUseAsCStringLen str $ \(bs, len) -> do