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


-- | Online XML parsing with polyparse and tagsoup
--   
@package polysoup
@version 0.6


-- | A generic extracting predicate.
module Text.XML.PolySoup.Predicate

-- | A predicate checks if the given element satisfies some properties and
--   extracts its attribute values. You can compose predicates using
--   Functor, Applicative and Alternative operators: <a>*&gt;</a>,
--   <a>&lt;*</a>, <a>&lt;|&gt;</a> etc. Note, that it doesn't really have
--   sense to use function like <a>many</a> or <a>some</a>, since the
--   extracting predicate doesn't consume any input.
newtype Q a b
Q :: (a -> Maybe b) -> Q a b
runQ :: Q a b -> (a -> Maybe b)

-- | Predicate which is always satisfied.
true :: Q a a

-- | Check if the given predicate is satisfied.
satisfy :: (a -> Bool) -> Q a a
instance Alternative (Q a)
instance Applicative (Q a)
instance Functor (Q a)


-- | The module defines a generic parser which can be used, in particular,
--   to parse XML forests. The main characteristic of the parser is that it
--   can be used in a sequential (sub-trees are processed in order) and a
--   selective (subtrees are process regardless of their position) way.
module Text.XML.PolySoup.Parser

-- | An XML forest parser.
newtype P a b
P :: ([a] -> Maybe (b, [a])) -> P a b
runP :: P a b -> [a] -> Maybe (b, [a])

-- | Evaluate parser on the given XML forest.
evalP :: P a b -> [a] -> Maybe b

-- | Find the first tree satisfying the given predicate.
first :: Q a b -> P a b

-- | Select every tree satisfying the given predicate.
every :: Q a b -> P a [b]

-- | A lazy version of <a>every</a> which "forgets" non-matching subtrees
--   along the way.
every' :: Q a b -> P a [b]

-- | Check, if the first tree satisfies the given predicate.
pop :: Q a b -> P a b

-- | Like <a>pop</a>, but doesn't consume the tree.
peek :: Q a b -> P a b

-- | Like <a>first</a>, but doesn't consume the tree.
spy :: Q a b -> P a b

-- | Many combinator which ignores parsing results.
many_ :: Alternative f => f a -> f ()
instance Monad (P a)
instance Alternative (P a)
instance Applicative (P a)
instance Functor (P a)


-- | The module provides tag-level predicates.
module Text.XML.PolySoup.Tag

-- | Get name of the tag.
getName :: Tag s -> Maybe s

-- | Get contents of the text node. A synonym for <a>maybeTagText</a>.
getText :: Tag s -> Maybe s

-- | Get value of the attribute.
getAttr :: Eq s => s -> Tag s -> Maybe s

-- | Get the list of the attributes.
getAtts :: Tag s -> Maybe [(s, s)]

-- | Extract the tag name.
name :: Q (Tag s) s

-- | Extract textual contents of the text node.
text :: Q (Tag s) s

-- | Extract the attribute value.
attr :: Eq s => s -> Q (Tag s) s

-- | Extract the attribute value.
atts :: Q (Tag s) [(s, s)]

-- | Internal node (i.e., an opening tag).
innerTag :: Q (Tag s) (Tag s)

-- | Leaf node (everything but an opening tag).
leafTag :: Q (Tag s) (Tag s)

-- | A text node.
textTag :: Q (Tag s) (Tag s)

-- | A comment node.
commentTag :: Q (Tag s) (Tag s)

-- | A warning node.
warningTag :: Q (Tag s) (Tag s)

-- | A position node.
positionTag :: Q (Tag s) (Tag s)

-- | Does it have a given name?
named :: Eq s => s -> Q (Tag s) (Tag s)

-- | Does it have a given attribute?
hasAttr :: Eq s => s -> Q (Tag s) (Tag s)

-- | Does it have a given attribute with a given value?
hasAttrVal :: Eq s => s -> s -> Q (Tag s) (Tag s)


-- | XML as a tree of XML tags.
--   
--   The module provides an <a>XmlTree</a> data type, which can be used to
--   represent a parsed XML file. The <a>XmlTree</a> structure can be
--   generated lazily by using the <a>parseTree</a> (or <a>parseForest</a>)
--   function on any string-like input supported by the tagsoup library.
--   
--   Note, that the parsing functions do not validate correctness of the
--   input XML data.
module Text.XML.PolySoup.XmlTree

-- | A parsed XML tree. Closing tags are not preserved.
type XmlTree s = Tree (Tag s)

-- | A parsed XML forest. Closing tags are not preserved.
type XmlForest s = [XmlTree s]

-- | Parse XML tree from a list of tags.
parseTree :: (NFData s, StringLike s) => [Tag s] -> XmlTree s

-- | Parse XML forest from a list of tags. Note, that if the XML file has
--   additional headers, the <a>parseForest</a> function has to be used to
--   parse it correctly.
parseForest :: (NFData s, StringLike s) => [Tag s] -> XmlForest s

-- | Render XML tree tags.
renderTree :: XmlTree s -> [Tag s]

-- | Render XML forest tags.
renderForest :: XmlForest s -> [Tag s]


-- | The module provides some common XML tree parsing combinators. There
--   are two main groups of combinators: XPath-like combinators and
--   tag/forest combinators. Use combinators from the first group if
--   possible, since they are generally easier too use and generate results
--   in a lazy manner.
--   
--   The second class contains more powerful combinators which can be used
--   to parse the contents of an XML node in a generic way. Note, that
--   combinators from the two groups can be interleaved -- you can use a
--   forest parser to construct a tree predicate, but you can also use a
--   tree predicate as an elementary forest parser (see the
--   <a>Text.XML.PolySoup.Parser</a> module).
module Text.XML.PolySoup.Combine

-- | Make a tree-level predicate from a tag-level predicate.
node :: Q (Tag s) a -> Q (XmlTree s) a

-- | Combine a tag predicate with an XML predicate. The XML predicate can
--   depend on the value of tag parser and will be called multiple times
--   for tag children elements.
(>/>) :: Q (Tag s) a -> (a -> Q (XmlTree s) b) -> Q (XmlTree s) [b]

-- | Combine the tag parser with the XML parser. The XML parser will be
--   called multiple times for tag children elements.
(</>) :: Q (Tag s) a -> Q (XmlTree s) b -> Q (XmlTree s) (a, [b])

-- | Combine the tag parser with the XML parser. The XML parser will be
--   called multiple times for tag children elements.
(/>) :: Q (Tag s) a -> Q (XmlTree s) b -> Q (XmlTree s) [b]

-- | Similar to <a>/&gt;</a> combinator but runs the XML parser for all
--   descendant XML elements, not only for its children.
(//>) :: Q (Tag s) a -> Q (XmlTree s) b -> Q (XmlTree s) [b]

-- | Combine the tag predicate with the forest parser which will be used to
--   parse contents of the tag element.
join :: Q (Tag s) a -> (a -> P (XmlTree s) b) -> Q (XmlTree s) b

-- | Combine the tag predicate with the forest parser which will be used to
--   parse contents of the tag element.
joinP :: Q (Tag s) a -> P (XmlTree s) b -> Q (XmlTree s) (a, b)

-- | Combine the tag predicate with the orest parser which will be used to
--   parse contents of the tag element. Only results of the tag predicate
--   will be returned (the contents have to be successfully parsed,
--   though).
joinL :: Q (Tag s) a -> P (XmlTree s) b -> Q (XmlTree s) a

-- | Combine the tag predicate with the orest parser which will be used to
--   parse contents of the tag element. Only results of the forest parser
--   will be returned.
joinR :: Q (Tag s) a -> P (XmlTree s) b -> Q (XmlTree s) b

-- | Infix version of the join combinators.
(>^>) :: Q (Tag s) a -> (a -> P (XmlTree s) b) -> Q (XmlTree s) b

-- | Infix version of the joinP combinators.
(<^>) :: Q (Tag s) a -> P (XmlTree s) b -> Q (XmlTree s) (a, b)

-- | Infix version of the joinR combinators.
(^>) :: Q (Tag s) a -> P (XmlTree s) b -> Q (XmlTree s) b

-- | Infix version of the joinL combinators.
(<^) :: Q (Tag s) a -> P (XmlTree s) b -> Q (XmlTree s) a


-- | The module re-exports individual submodules of the library.
module Text.XML.PolySoup