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


-- | Online XML parsing with polyparse and tagsoup
--   
--   Please see the README on GitHub at
--   <a>https://github.com/kawu/polysoup#readme</a>
@package polysoup
@version 0.2.1

module Text.XML.PolySoup

-- | XML forest parser with result type a.
type XmlParser s a = Parser (Tag s) a
type TagParser s a = Parser (Tag s) a

-- | A tag predicate checks if the tag (HTML element) satisfies some
--   properties and extracts attribute values. You can compose tag
--   predicates using Applicative and Alternative operators: <a>*&gt;</a>,
--   <a>&lt;*</a>, <a>&lt;|&gt;</a> etc.
data TagPred s a

-- | Make a tag parser from the tag predicate.
satisfyPred :: TagPred s a -> TagParser s a

-- | Predicate which is always satisfied.
true :: TagPred s ()

-- | True predicate which returns the tag itself.
getTag :: TagPred s (Tag s)

-- | Check if the HTML element is an open tag.
isTagOpen :: TagPred s ()

-- | Check if the tag is an open tag and matches the given name.
isTagOpenName :: Eq s => s -> TagPred s ()

-- | Check if the HTML element is a closing tag.
isTagClose :: TagPred s ()

-- | Check if the tag is a closing tag and matches the given name.
isTagCloseName :: Eq s => s -> TagPred s ()

-- | Test if the tag is a text node.
isTagText :: TagPred s ()

-- | Test if the tag is a text node.
isTagComment :: TagPred s ()

-- | Get name of the open tag.
tagOpenName :: TagPred s s

-- | Get text content of the tag.
tagText :: TagPred s s

-- | A shorthand for isTagOpenName.
tag :: Eq s => s -> TagPred s ()

-- | Check if the tag has the given attribute with the given value.
hasAttr :: (Show s, Eq s, StringLike s) => s -> s -> TagPred s ()

-- | Get attribute value from the open tag.
getAttr :: (Show s, Eq s, StringLike s) => s -> TagPred s s

-- | Get attribute value from the open tag or Nothing, if the attribute is
--   not present.
maybeAttr :: (Show s, Eq s, StringLike s) => s -> TagPred s (Maybe s)

-- | Ignore any number of XML elements on the current level.
ignore :: Eq s => XmlParser s ()

-- | Ignore XML tree or text element.
ignoreAny :: Eq s => XmlParser s ()

-- | Ignore text element.
ignoreText :: XmlParser s ()

-- | Ignore XML tree.
ignoreTag :: Eq s => XmlParser s ()

-- | Version of the ignoreAny function with a monoid result type.
ignoreAnyM :: (Eq s, Monoid m) => XmlParser s m

-- | Parse XML element using the given tag predicate and ignore contents of
--   the element.
cut :: Eq s => TagPred s a -> XmlParser s a

-- | Parse a list of XML elements and collect all values retrieved with a
--   given parser.
findAll :: Eq s => XmlParser s a -> XmlParser s [a]

-- | Find first XML element accepted be the given parser and ignore the
--   rest of elements in the collection.
findIgnore :: Eq s => XmlParser s a -> XmlParser s (Maybe a)

-- | Find fist XML element accepted by the given parser. TODO: Change type
--   to XmlParser s (Maybe a)?
findFirst :: Eq s => XmlParser s a -> XmlParser s a

-- | Parse text element and retrieve its content.
text :: Eq s => XmlParser s s

-- | Combine the tag parser with the XML parser which will be used to parse
--   contents of the tag element.
join :: Eq s => TagPred s a -> (a -> XmlParser s b) -> XmlParser s b

-- | Combine the tag parser with the XML parser which will be used to parse
--   contents of the tag element. Parsing results will be returned in a
--   form of a pair.
joinP :: Eq s => TagPred s a -> XmlParser s b -> XmlParser s (a, b)

-- | Combine the tag parser with the XML parser which will be used to parse
--   contents of the tag element. Only results of the XML parser will be
--   returned.
joinR :: Eq s => TagPred s a -> XmlParser s b -> XmlParser s b

-- | Combine the tag parser with the XML parser which will be used to parse
--   contents of the tag element. Only results of the tag parser will be
--   returned.
joinL :: Eq s => TagPred s a -> XmlParser s b -> XmlParser s a

-- | Infix version of the join combinators.
(>^>) :: Eq s => TagPred s a -> (a -> XmlParser s b) -> XmlParser s b
infixr 2 >^>

-- | Infix version of the joinP combinators.
(<^>) :: Eq s => TagPred s a -> XmlParser s b -> XmlParser s (a, b)
infixr 2 <^>

-- | Infix version of the joinR combinators.
(^>) :: Eq s => TagPred s a -> XmlParser s b -> XmlParser s b
infixr 2 ^>

-- | Infix version of the joinL combinators.
(<^) :: Eq s => TagPred s a -> XmlParser s b -> XmlParser s a
infixr 2 <^

-- | Combine the tag parser with the XML parser. The XML parser can depend
--   on the value of tag parser and will be called multiple times for tag
--   children elements.
(>/>) :: Eq s => TagPred s a -> (a -> XmlParser s b) -> XmlParser s [b]
infixr 2 >/>

-- | Combine the tag parser with the XML parser. The XML parser will be
--   called multiple times for tag children elements.
(</>) :: Eq s => TagPred s a -> XmlParser s b -> XmlParser s (a, [b])
infixr 2 </>

-- | Combine the tag parser with the XML parser. The XML parser will be
--   called multiple times for tag children elements. Only results of XML
--   parsing will be returned.
(/>) :: Eq s => TagPred s a -> XmlParser s b -> XmlParser s [b]
infixr 2 />

-- | Combine the tag parser with the XML parser. The XML parser will be
--   called multiple times for tag children elements. Only results of the
--   tag parser will be returned.
(</) :: Eq s => TagPred s a -> XmlParser s b -> XmlParser s a
infixr 2 </

-- | Similar to <a>/&gt;</a> combinator but runs the XML parser for all
--   descendant XML elements, not only for its children.
(//>) :: Eq s => TagPred s a -> TagParser s b -> TagParser s [b]
infixr 2 //>

-- | Combinators with results concatenation.
--   
--   Similar to <a>&lt;/&gt;</a> combinator but additionaly concatenates
--   XML parser results.
(<#>) :: (Eq s, Monoid m) => TagPred s a -> XmlParser s m -> XmlParser s (a, m)
infixr 2 <#>

-- | Similar to <a>/&gt;</a> combinator but additionaly concatenates XML
--   parser results.
(#>) :: (Eq s, Monoid m) => TagPred s a -> XmlParser s m -> XmlParser s m
infixr 2 #>

-- | Similar to <a>//&gt;</a> combinator but additionaly concatenates XML
--   parser results.
(##>) :: (Eq s, Monoid m) => TagPred s a -> TagParser s m -> TagParser s m
infixr 2 ##>

-- | Parser the given string to the list of tags.
parseTags :: StringLike s => s -> [Tag s]

-- | Parser the given tag list with the given XML parser.
tagsParseXml :: StringLike s => XmlParser s b -> [Tag s] -> b

-- | Parser the given string with the given XML parser.
parseXml :: StringLike s => XmlParser s b -> s -> b

-- | Collect all tags of the parsed XML element.
elemTags :: Eq s => XmlParser s [Tag s]

-- | Retrieve tags related to a collection of XML elements.
collTags :: Eq s => XmlParser s [Tag s]

-- | Many combinator which ignores parsing results.
many_ :: Alternative f => f a -> f ()

-- | Escape XML string.
escapeXml :: StringLike str => str -> str
instance GHC.Base.Functor (Text.XML.PolySoup.TagPred s)
instance GHC.Base.Applicative (Text.XML.PolySoup.TagPred s)
instance GHC.Base.Alternative (Text.XML.PolySoup.TagPred s)