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


-- | Indexed XML cursors similar to 'Text.XML.Cursor' from xml-conduit
--   
--   Please see <a>README.md</a>.
@package xml-indexed-cursor
@version 0.1.1.0


-- | This module provides indexed <a>Cursor</a>s. It has a very similar API
--   to <a>Text.XML.Cursor</a>.
--   
--   The big difference is in the <a>Cursor</a> type. <a>Cursor</a> wraps
--   around a <a>Node</a>, while this module's <a>Cursor</a> type wraps
--   around an <a>IndexedNode</a>.
--   
--   An <a>IndexedNode</a> is a data type that contains both a <a>Node</a>
--   and a <a>NodeIndex</a>. The <a>NodeIndex</a> gives a way to figure out
--   how two <a>IndexedNode</a>s compare to each other in the
--   <a>Document</a>. It gives the ability to figure out which
--   <a>IndexedNode</a> comes earlier in the <a>Document</a>. This gives
--   the ability to sort lists of <a>IndexedNode</a>s, based on their
--   location in the <a>Document</a>. See <a>NodeIndex</a> for more
--   information.
module Text.XML.Cursor.Indexed

-- | This is similar to <a>Cursor</a> except for <a>IndexedNode</a>.
type IndexedCursor = Cursor IndexedNode

-- | This is similar to <a>Axis</a> except for <a>IndexedNode</a>.
type IndexedAxis = Axis IndexedNode

-- | Index for a <a>Node</a> in a <a>Document</a>.
--   
--   The root element has a value of '[]'. Every child element is given an
--   <a>Int</a> index as the first element of the list, and the grandchild
--   elements are given an <a>Int</a> index as the second element of the
--   list, and so on. If there are multiple root elements, then '[]' acts
--   as a "virtual" root element that contains all actual root elements.
--   
--   <pre>
--   &gt;&gt;&gt; let cursor = indexedCursorFromText_ "&lt;foo&gt;&lt;bar/&gt;&lt;/foo&gt;"
--   
--   &gt;&gt;&gt; unNodeIndex $ indexedCursorNodeIndex cursor
--   fromList []
--   </pre>
--   
--   This function will be used in the following examples.
--   
--   <pre>
--   &gt;&gt;&gt; :{
--   let getNodeIndex :: [IndexedCursor] -&gt; Seq Int
--       getNodeIndex = unNodeIndex . indexedCursorNodeIndex . head
--   :}
--   </pre>
--   
--   The index of the first child of the root be <tt>[0]</tt>
--   
--   <pre>
--   &gt;&gt;&gt; let cursor = indexedCursorFromText_ "&lt;foo&gt;&lt;bar/&gt;&lt;baz/&gt;&lt;/foo&gt;"
--   
--   &gt;&gt;&gt; getNodeIndex $ child cursor
--   fromList [0]
--   </pre>
--   
--   The index of the second child of the root would be <tt>[1]</tt>.
--   
--   <pre>
--   &gt;&gt;&gt; let cursor = indexedCursorFromText_ "&lt;foo&gt;&lt;bar/&gt;&lt;baz/&gt;&lt;/foo&gt;"
--   
--   &gt;&gt;&gt; getNodeIndex $ cursor $| child &gt;=&gt; followingSibling
--   fromList [1]
--   </pre>
--   
--   The index of the third child of the root would be <tt>[2]</tt>.
--   
--   <pre>
--   &gt;&gt;&gt; let cursor = indexedCursorFromText_ "&lt;foo&gt;&lt;bar/&gt;&lt;baz/&gt;&lt;zap/&gt;&lt;/foo&gt;"
--   
--   &gt;&gt;&gt; getNodeIndex $ cursor $| child &gt;=&gt; followingSibling &gt;=&gt; followingSibling
--   fromList [2]
--   </pre>
--   
--   The index of the first child of the first child of the root would be
--   <tt>[0, 0]</tt>.
--   
--   <pre>
--   &gt;&gt;&gt; let cursor = indexedCursorFromText_ "&lt;foo&gt;&lt;bar&gt;&lt;hello/&gt;&lt;/bar&gt;&lt;/foo&gt;"
--   
--   &gt;&gt;&gt; getNodeIndex $ cursor $| child &gt;=&gt; child
--   fromList [0,0]
--   </pre>
--   
--   The index of the second child of the first child of the root would be
--   <tt>[0, 1]</tt> (since the <tt>[Int]</tt> is stored reversed).
--   
--   <pre>
--   &gt;&gt;&gt; let cursor = indexedCursorFromText_ "&lt;foo&gt;&lt;bar&gt;&lt;hello/&gt;&lt;bye/&gt;&lt;/bar&gt;&lt;/foo&gt;"
--   
--   &gt;&gt;&gt; getNodeIndex $ cursor $| child &gt;=&gt; child &gt;=&gt; followingSibling
--   fromList [0,1]
--   </pre>
--   
--   The index of the third child of the fourth child of the root would be
--   <tt>[3, 2]</tt>.
--   
--   <pre>
--   &gt;&gt;&gt; let doc = "&lt;foo&gt;&lt;zero/&gt;&lt;one/&gt;&lt;two/&gt;&lt;three&gt;&lt;sub0/&gt;&lt;sub1/&gt;&lt;sub2/&gt;&lt;/three&gt;&lt;/foo&gt;"
--   
--   &gt;&gt;&gt; let cursor = indexedCursorFromText_ doc
--   
--   &gt;&gt;&gt; :{
--   let xpath =
--         child &gt;=&gt;                 -- focusing on &lt;zero/&gt;
--         followingSibling &gt;=&gt;      -- focusing on &lt;one/&gt;
--         followingSibling &gt;=&gt;      -- focusing on &lt;two/&gt;
--         followingSibling &gt;=&gt;      -- focusing on &lt;three/&gt;
--             child &gt;=&gt;             -- focusing on the &lt;sub0/&gt; element
--             followingSibling &gt;=&gt;  -- focusing on the &lt;sub1/&gt; element
--             followingSibling      -- focusing on the &lt;sub2/&gt; eleemnt
--   in getNodeIndex $ xpath cursor
--   :}
--   fromList [3,2]
--   </pre>
newtype NodeIndex
NodeIndex :: Seq Int -> NodeIndex
[unNodeIndex] :: NodeIndex -> Seq Int
class HasNodeIndex a

-- | This is basically <tt><a>Lens'</a> a <a>NodeIndex</a></tt>.
nodeIndexLens :: (HasNodeIndex a, Functor f) => (NodeIndex -> f NodeIndex) -> a -> f a

-- | Index to use for the root <a>NodeIndex</a>. Should be '[]'.
rootIndex :: NodeIndex

-- | <a>IndexedNode</a> just wraps together a <a>Node</a> and a
--   <a>NodeIndex</a> for that <a>Node</a>.
data IndexedNode
IndexedNode :: NodeIndex -> Node -> IndexedNode
[indexedNodeIndex] :: IndexedNode -> NodeIndex
[indexedNodeNode] :: IndexedNode -> Node

-- | Get the <a>NodeIndex</a> from the <a>IndexedNode</a> pointed to by an
--   <a>IndexedCursor</a>.
indexedCursorNodeIndex :: IndexedCursor -> NodeIndex

-- | Convert a <a>Node</a> to a root <a>IndexedNode</a>.
nodeToRootIndexedNode :: Node -> IndexedNode

-- | Create a <a>NodeIndex</a> for the <a>Int</a> child below the input
--   parent <a>NodeIndex</a>.
toChildIndex :: NodeIndex -> Int -> NodeIndex

-- | Given a <a>NodeIndex</a>, create an <a>IndexedNode</a> for a
--   <a>Node</a>.
nodeToIndexedNode :: NodeIndex -> Node -> IndexedNode

-- | In <tt><a>childNodeToIndexedNode</a> parentIndex childIndexInt
--   childNode</tt>, create an <a>IndexedNode</a> out of
--   <tt>childNode</tt>, creating its <a>NodeIndex</a> using
--   <a>toChildIndex</a>.
childNodeToIndexedNode :: NodeIndex -> Int -> Node -> IndexedNode

-- | In <tt><a>childNodesToIndexedNodes</a> parentIndex childNodes</tt>
--   convert a list of <a>Node</a> <tt>childNodes</tt> to a list of
--   <tt>IndexNode</tt>s using the <a>NodeIndex</a> <tt>parentIndex</tt>.
childNodesToIndexedNodes :: NodeIndex -> [Node] -> [IndexedNode]

-- | Convert a <a>Document</a> to a <a>Cursor</a>. It will point to the
--   document root.
fromDocument :: Document -> IndexedCursor

-- | Convert a <a>Node</a> to a root <a>IndexedCursor</a>.
fromNode :: Node -> IndexedCursor
toCursor :: () => (node -> [node]) -> node -> Cursor node

-- | The current node.
node :: () => Cursor node -> node

-- | The child axis. XPath: <i>the child axis contains the children of the
--   context node</i>.
child :: () => Cursor node -> [Cursor node]

-- | The parent axis. As described in XPath: <i>the parent axis contains
--   the parent of the context node, if there is one</i>.
--   
--   Every node but the root element of the document has a parent. Parent
--   nodes will always be <tt>NodeElement</tt>s.
parent :: () => Axis node

-- | The preceding-sibling axis. XPath: <i>the preceding-sibling axis
--   contains all the preceding siblings of the context node [...]</i>.
precedingSibling :: () => Axis node

-- | The following-sibling axis. XPath: <i>the following-sibling axis
--   contains all the following siblings of the context node [...]</i>.
followingSibling :: () => Axis node

-- | The ancestor axis. XPath: <i>the ancestor axis contains the ancestors
--   of the context node; the ancestors of the context node consist of the
--   parent of context node and the parent's parent and so on; thus, the
--   ancestor axis will always include the root node, unless the context
--   node is the root node</i>.
ancestor :: () => Axis node

-- | The descendant axis. XPath: <i>the descendant axis contains the
--   descendants of the context node; a descendant is a child or a child of
--   a child and so on; thus the descendant axis never contains attribute
--   or namespace nodes</i>.
descendant :: () => Axis node

-- | Modify an axis by adding the context node itself as the first element
--   of the result list.
orSelf :: () => Axis node -> Axis node

-- | The preceding axis. XPath: <i>the preceding axis contains all nodes in
--   the same document as the context node that are before the context node
--   in document order, excluding any ancestors and excluding attribute
--   nodes and namespace nodes</i>.
preceding :: () => Axis node

-- | The following axis. XPath: <i>the following axis contains all nodes in
--   the same document as the context node that are after the context node
--   in document order, excluding any descendants and excluding attribute
--   nodes and namespace nodes</i>.
following :: () => Axis node

-- | Apply a function to the result of an axis.
(&|) :: () => (Cursor node -> [a]) -> (a -> b) -> Cursor node -> [b]
infixr 1 &|

-- | Combine two axes so that the second works on the children of the
--   results of the first.
(&/) :: () => Axis node -> (Cursor node -> [a]) -> Cursor node -> [a]
infixr 1 &/

-- | Combine two axes so that the second works on the descendants of the
--   results of the first.
(&//) :: () => Axis node -> (Cursor node -> [a]) -> Cursor node -> [a]
infixr 1 &//

-- | Combine two axes so that the second works on both the result nodes,
--   and their descendants.
(&.//) :: () => Axis node -> (Cursor node -> [a]) -> Cursor node -> [a]
infixr 1 &.//

-- | Apply an axis to a 'Cursor node'.
($|) :: () => Cursor node -> (Cursor node -> a) -> a
infixr 1 $|

-- | Apply an axis to the children of a 'Cursor node'.
($/) :: () => Cursor node -> (Cursor node -> [a]) -> [a]
infixr 1 $/

-- | Apply an axis to the descendants of a 'Cursor node'.
($//) :: () => Cursor node -> (Cursor node -> [a]) -> [a]
infixr 1 $//

-- | Apply an axis to a 'Cursor node' as well as its descendants.
($.//) :: () => Cursor node -> (Cursor node -> [a]) -> [a]
infixr 1 $.//

-- | Left-to-right Kleisli composition of monads.
(>=>) :: Monad m => (a -> m b) -> (b -> m c) -> a -> m c
infixr 1 >=>

-- | Filter cursors that don't pass a check.
check :: Boolean b => (Cursor a -> b) -> Axis a

-- | Filter nodes that don't pass a check.
checkIndexedNode :: Boolean b => (IndexedNode -> b) -> IndexedAxis

-- | Filter elements that don't pass a check, and remove all non-elements.
checkElement :: Boolean b => (Element -> b) -> IndexedAxis

-- | Filter elements that don't pass a name check, and remove all
--   non-elements.
checkName :: Boolean b => (Name -> b) -> IndexedAxis

-- | Select only those elements with a matching tag name.
--   
--   XPath: /A node test that is a QName is true if and only if the type of
--   the node (see [5 Data Model]) is the principal node type and has an
--   expanded-name equal to the expanded-name specified by the QName./
element :: Name -> IndexedAxis

-- | Select only text nodes, and directly give the <tt>Content</tt> values.
--   
--   XPath: <i>The node test text() is true for any text node.</i>
--   
--   Note that this is not strictly an <a>Axis</a>, but will work with most
--   combinators.
--   
--   <pre>
--   &gt;&gt;&gt; let cursor = indexedCursorFromText_ "&lt;foo&gt;hello&lt;bar/&gt;bye&lt;/foo&gt;"
--   
--   &gt;&gt;&gt; cursor $| child &gt;=&gt; content
--   ["hello","bye"]
--   
--   &gt;&gt;&gt; cursor $| child &gt;=&gt; child &gt;=&gt; content
--   []
--   </pre>
content :: IndexedCursor -> [Text]

-- | Select attributes on the current element (or nothing if it is not an
--   element).
--   
--   XPath: /the attribute axis contains the attributes of the context
--   node; the axis will be empty unless the context node is an element/
--   
--   Note that this is not strictly an <a>Axis</a>, but will work with most
--   combinators.
--   
--   The return list of the generalised axis contains as elements lists of
--   <tt>Content</tt> elements, each full list representing an attribute
--   value.
--   
--   <pre>
--   &gt;&gt;&gt; let cursor = indexedCursorFromText_ "&lt;foo hello='cat' bar='3'&gt;hello world&lt;/foo&gt;"
--   
--   &gt;&gt;&gt; cursor $| attribute "hello"
--   ["cat"]
--   
--   &gt;&gt;&gt; cursor $| attribute "doesntexist"
--   []
--   
--   &gt;&gt;&gt; cursor $| child &gt;=&gt; attribute "attroftext"
--   []
--   </pre>
attribute :: Name -> IndexedCursor -> [Text]

-- | Similar to <a>attribute</a> but return a <a>Maybe</a> instead of a
--   list.
--   
--   <pre>
--   &gt;&gt;&gt; let cursor = indexedCursorFromText_ "&lt;foo hello='cat' bar='3'&gt;hello world&lt;/foo&gt;"
--   
--   &gt;&gt;&gt; cursor $| attributeMay "hello"
--   Just "cat"
--   
--   &gt;&gt;&gt; cursor $| attributeMay "doesntexist"
--   Nothing
--   </pre>
attributeMay :: Name -> IndexedCursor -> Maybe Text

-- | Select attributes on the current element (or nothing if it is not an
--   element). Namespace and case are ignored.
--   
--   XPath: /the attribute axis contains the attributes of the context
--   node; the axis will be empty unless the context node is an element/
--   
--   Note that this is not strictly an <a>Axis</a>, but will work with most
--   combinators.
--   
--   The return list of the generalised axis contains as elements lists of
--   <tt>Content</tt> elements, each full list representing an attribute
--   value.
--   
--   <pre>
--   &gt;&gt;&gt; let cursor = indexedCursorFromText_ "&lt;foo HellO='cat'/&gt;"
--   
--   &gt;&gt;&gt; cursor $| laxAttribute "HellO"
--   ["cat"]
--   
--   &gt;&gt;&gt; cursor $| laxAttribute "Hello"
--   ["cat"]
--   
--   &gt;&gt;&gt; cursor $| laxAttribute "hello"
--   ["cat"]
--   
--   &gt;&gt;&gt; cursor $| laxAttribute "bye"
--   []
--   </pre>
laxAttribute :: Text -> IndexedCursor -> [Text]

-- | Select only those element nodes with the given attribute.
hasAttribute :: Name -> IndexedAxis

-- | Select only those element nodes containing the given attribute
--   key/value pair.
attributeIs :: Name -> Text -> IndexedAxis

-- | For a given <a>Name</a>, find all <a>descendant</a> <a>Element</a>s
--   with that <a>Name</a>.
descendantElementsNamed :: Name -> IndexedAxis

-- | For a given <a>Name</a>, find all <a>ancestor</a> <a>Element</a>s.
--   with that <a>Name</a>.
ancestorElementsNamed :: Name -> IndexedAxis

-- | In <tt><a>descendantElementsNamedWithAttr</a> elemName attrKey
--   attrVal</tt>, find all <a>descendant</a> <a>Element</a>s with
--   <tt>elemName</tt> that have an attribute called <tt>attrKey</tt> with
--   a value of <tt>attrVal</tt>.
descendantElementsNamedWithAttr :: Name -> Name -> Text -> IndexedAxis

-- | Find all <a>content</a> in all <a>descendant</a>s.
--   
--   <pre>
--   &gt;&gt;&gt; let cursor = indexedCursorFromText_ "&lt;foo&gt;hello&lt;bar&gt;lala&lt;/bar&gt;bye&lt;/foo&gt;"
--   
--   &gt;&gt;&gt; descendantContent cursor
--   ["hello","lala","bye"]
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; let cursor = indexedCursorFromText_ "&lt;foo/&gt;"
--   
--   &gt;&gt;&gt; descendantContent cursor
--   []
--   </pre>
descendantContent :: IndexedCursor -> [Text]

-- | Find <a>attribute</a> with <a>Name</a> on the element
--   <a>IndexedCursor</a> is pointing to.
--   
--   <pre>
--   &gt;&gt;&gt; let cursor = indexedCursorFromText_ "&lt;foo hello='3'/&gt;"
--   
--   &gt;&gt;&gt; attrValForElemCursor "hello" cursor
--   Just "3"
--   
--   &gt;&gt;&gt; attrValForElemCursor "bye" cursor
--   Nothing
--   </pre>
attrValForElemCursor :: Name -> IndexedCursor -> Maybe Text

-- | This reads a <a>Document</a> from a <a>ByteString</a> with
--   <a>parseLBS_</a>, and then converts that <a>Document</a> to an
--   <a>IndexedCursor</a>.
indexedCursorFromByteString_ :: ByteString -> IndexedCursor

-- | Similar to <a>indexedCursorFromByteString_</a> but uses
--   <a>parseLBS</a> instead of <a>parseLBS_</a>.
indexedCursorFromByteString :: ByteString -> Either SomeException IndexedCursor

-- | Similar to <a>indexedCursorFromByteString_</a> but uses
--   <a>parseText_</a> instead of <a>parseLBS_</a>.
indexedCursorFromText_ :: Text -> IndexedCursor

-- | Similar to <a>indexedCursorFromByteString_</a> but uses
--   <a>parseText</a> instead of <a>parseLBS_</a>.
indexedCursorFromText :: Text -> Either SomeException IndexedCursor

-- | Similar to <a>indexedCursorFromByteString_</a> but also takes
--   <a>ParseSettings</a>.
indexedCursorFromByteStringWithOpts_ :: ParseSettings -> ByteString -> IndexedCursor

-- | Similar to <a>indexedCursorFromByteString</a> but also takes
--   <a>ParseSettings</a>.
indexedCursorFromByteStringWithOpts :: ParseSettings -> ByteString -> Either SomeException IndexedCursor

-- | Similar to <a>indexedCursorFromText_</a> but also takes
--   <a>ParseSettings</a>.
indexedCursorFromTextWithOpts_ :: ParseSettings -> Text -> IndexedCursor

-- | Similar to <a>indexedCursorFromText</a> but also takes
--   <a>ParseSettings</a>.
indexedCursorFromTextWithOpts :: ParseSettings -> Text -> Either SomeException IndexedCursor
instance GHC.Show.Show Text.XML.Cursor.Indexed.IndexedNode
instance GHC.Classes.Eq Text.XML.Cursor.Indexed.IndexedNode
instance Data.Data.Data Text.XML.Cursor.Indexed.IndexedNode
instance GHC.Show.Show Text.XML.Cursor.Indexed.NodeIndex
instance GHC.Read.Read Text.XML.Cursor.Indexed.NodeIndex
instance GHC.Classes.Ord Text.XML.Cursor.Indexed.NodeIndex
instance GHC.Classes.Eq Text.XML.Cursor.Indexed.NodeIndex
instance Data.Data.Data Text.XML.Cursor.Indexed.NodeIndex
instance Text.XML.Cursor.Indexed.HasNodeIndex Text.XML.Cursor.Indexed.IndexedNode
instance Text.XML.Cursor.Indexed.HasNodeIndex Text.XML.Cursor.Indexed.NodeIndex
