-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | XML subset DOM parser
--   
--   An XML DOM-style parser, that only parses a subset of XML, but is
--   designed to be fast.
@package hexml
@version 0.3.5


-- | A module for fast first-approximation parsing of XML. Note that
--   entities, e.g. <tt>&amp;amp;</tt>, are not expanded.
module Text.XML.Hexml

-- | A node in an XML document, created by <a>parse</a>, then calling
--   functions such as <a>children</a> on that initial <a>Node</a>.
data Node

-- | An XML attribute, comprising of a name and a value. As an example,
--   <tt>hello="world"</tt> would produce <tt>Attribute "hello"
--   "world"</tt>.
data Attribute
Attribute :: ByteString -> ByteString -> Attribute
[attributeName] :: Attribute -> ByteString
[attributeValue] :: Attribute -> ByteString

-- | Parse a ByteString as an XML document, returning a <a>Left</a> error
--   message, or a <a>Right</a> document. Note that the returned node will
--   have a <a>name</a> of <tt>""</tt>, no <a>attributes</a>, and
--   <a>contents</a> as per the document. Often the first child will be the
--   <tt>&lt;?xml ... ?&gt;</tt> element. For documents which comprise an
--   XML node and a single root element, use <tt><a>children</a> n !!
--   1</tt>.
parse :: ByteString -> Either ByteString Node

-- | Given a node, rerender it to something with an equivalent parse tree.
--   Mostly useful for debugging - if you want the real source document use
--   <a>outer</a> instead.
render :: Node -> ByteString

-- | Find the starting location of a node, the <tt>&lt;</tt> character. The
--   first character will be reported as <tt>(line 1,column 1)</tt>,
--   because thats how error messages typically do it.
location :: Node -> (Int, Int)

-- | Get the name of a node, e.g. <tt>&lt;test /&gt;</tt> produces
--   <tt>"test"</tt>.
name :: Node -> ByteString

-- | Get the inner text, from inside the tag, e.g. <tt>&lt;test /&gt;</tt>
--   produces <tt>""</tt> and <tt>&lt;test&gt;hello&lt;/test&gt;</tt>
--   produces <tt>"hello"</tt>. The result will have identical
--   layout/spacing to the source document.
inner :: Node -> ByteString

-- | Get the outer text, including the tag itself, e.g. <tt>&lt;test
--   /&gt;</tt> produces <tt>"&lt;test /&gt;"</tt> and
--   <tt>&lt;test&gt;hello&lt;/test&gt;</tt> produces
--   <tt>"&lt;test&gt;hello&lt;/test&gt;"</tt>. The result will have
--   identical layout/spacing to the source document.
outer :: Node -> ByteString

-- | Get the attributes of this node.
attributes :: Node -> [Attribute]

-- | Get the direct child nodes of this node.
children :: Node -> [Node]

-- | Get the contents of a node, including both the content strings (as
--   <a>Left</a>, never blank) and the direct child nodes (as
--   <a>Right</a>). If you only want the child nodes, use <a>children</a>.
contents :: Node -> [Either ByteString Node]

-- | Get the first attribute of this node which has a specific name, if
--   there is one. A more efficient version of:
--   
--   <pre>
--   attributeBy n s = listToMaybe $ filter (\(Attribute a _) -&gt; a == s $ attributes n
--   </pre>
attributeBy :: Node -> ByteString -> Maybe Attribute

-- | Get the direct children of this node which have a specific name. A
--   more efficient version of:
--   
--   <pre>
--   childrenBy p s = filter (\n -&gt; name n == s) $ children p
--   </pre>
childrenBy :: Node -> ByteString -> [Node]
instance GHC.Classes.Eq Text.XML.Hexml.Attribute
instance GHC.Classes.Ord Text.XML.Hexml.Attribute
instance GHC.Internal.Show.Show Text.XML.Hexml.Attribute
instance GHC.Internal.Show.Show Text.XML.Hexml.Node
instance GHC.Internal.Show.Show Text.XML.Hexml.Str
instance GHC.Internal.Foreign.Storable.Storable Text.XML.Hexml.Str
