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


-- | Parser combinators for xml-enumerator and compatible XML parsers.
--   
--   Parser combinators for xml-enumerator and compatible XML parsers. The
--   aim is to provide advanced parser combinators to eliminate tiresome
--   repetition of boilerplate in streaming XML parsers.
@package xml-enumerator-combinators
@version 0.1

module Text.XML.Enumerator.Combinators.Tags

-- | Statefully and efficiently parse a list of tags.
--   
--   The first parameter is a function that, given state and an element
--   name, returns either <a>Nothing</a>, to indicate that the element is
--   invalid, or a pair of attribute and element content parsers in
--   <a>Just</a>.
--   
--   The second parameter is a function that, given the current state,
--   returns a <a>fallback</a> parser to be executed when no valid element
--   has been found.
--   
--   The third parameter is the initial state.
--   
--   This function updates the state as it goes along, but it also
--   accumulates a list of elements as they occur.
tags :: Monad m => (a -> Name -> Maybe (AttrParser b, b -> Iteratee Event m (Maybe (a, Maybe c)))) -> (a -> Iteratee Event m (Maybe (a, Maybe c))) -> a -> Iteratee Event m (a, [c])

-- | Parse a permutation of tags.
--   
--   The first parameter is a function to preprocess Names for equality
--   testing, because sometimes XML documents contain inconsistent naming.
--   This allows the user to deal with it.
--   
--   The second parameter is a map of tags to attribute and element content
--   parsers.
--   
--   The third parameter is a fallback parser. The outer Maybe indicates
--   whether it succeeds, and the inner Maybe whether an element should be
--   added to the output list.
--   
--   This function accumulates a list of elements for each step that
--   produces one.
tagsPermute :: (Monad m, Ord k) => (Name -> k) -> Map k (AttrParser a, a -> Iteratee Event m (Maybe b)) -> Iteratee Event m (Maybe (Maybe b)) -> Iteratee Event m (Maybe [b])

-- | Specifies how often an element may repeat.
data Repetition
Repeat :: Bool -> Bool -> Repetition -> Repetition
repetitionNeedsMore :: Repetition -> Bool
repetitionAllowsMore :: Repetition -> Bool
repetitionConsume :: Repetition -> Repetition

-- | Element may never occur.
repeatNever :: Repetition

-- | Element may occur exactly once.
repeatOnce :: Repetition

-- | Element may occur up to once.
repeatOptional :: Repetition

-- | Element may occur any number of times.
repeatMany :: Repetition

-- | Element may occur at least once.
repeatSome :: Repetition

-- | Parse a permutation of tags, with some repeating elements.
--   
--   The first parameter is a function to preprocess Names for equality
--   testing, because sometimes XML documents contain inconsistent naming.
--   This allows the user to deal with it.
--   
--   The second parameter is a map of tags to attribute and element content
--   parsers. It also specifies how often elements may repeat.
--   
--   The third parameter is a fallback parser. The outer Maybe indicates
--   whether it succeeds, and the inner Maybe whether an element should be
--   added to the output list.
--   
--   This function accumulates a list of elements for each step that
--   produces one.
tagsPermuteRepetition :: (Monad m, Ord k) => (Name -> k) -> Map k (Repetition, AttrParser b, b -> Iteratee Event m (Maybe t)) -> Iteratee Event m (Maybe (Maybe (k, t))) -> Iteratee Event m (Maybe [(k, t)])

module Text.XML.Enumerator.Combinators.General

-- | Like <tt>choose</tt>, but also returns the list of elements that were
--   <i>not</i> chosen.
chooseSplit :: Monad m => (a -> m (Maybe b)) -> [a] -> m (Maybe (b, [a]))

-- | Permute all parsers until none return <a>Just</a>.
permute :: Monad m => (a -> m (Maybe b)) -> [a] -> m (Maybe [b])

-- | Permute all parsers until none return <a>Just</a>, but always test
--   some fallback parsers.
permuteFallback :: Monad m => m (Maybe [b]) -> (a -> m (Maybe b)) -> [a] -> m (Maybe [b])