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


-- | Providing an interleaving combinator for use with applicative/alternative style implementations.
--   
--   This module contains parser library independent code which can be used
--   to describe inlerleaved execution of applicative style structures. It
--   is amongst other used in the uu-options package, which provides
--   facilities for parsing command-line options or files containing
--   preferences. It generalises the permuting parsers and the list merging
--   parsers as e.g. found in the uulib library. For a more complete
--   description see the Technical Report describing its implementation and
--   use see
--   <a>http://www.cs.uu.nl/research/techreps/UU-CS-2013-005.html</a>
@package uu-interleaved
@version 0.2.0.0


-- | This module contains the additional data types, instance definitions
--   and functions to run parsers in an interleaved way. If all the
--   interleaved parsers recognise a single connected piece of the input
--   text this incorporates the permutation parsers. For some examples see
--   the module <a>Text.ParserCombinators.UU.Demo.MergeAndPermute</a>.
module Control.Applicative.Interleaved
class Splittable f
getNonPure :: Splittable f => f a -> Maybe (f a)
getPure :: Splittable f => f a -> Maybe a

-- | Since we want to get access to the individual parsers which recognise
--   a consecutive piece of the input text we define a new data type, which
--   lifts the underlying parsers to the grammatical level, so they can be
--   transformed, manipulated, and run in a piecewise way. <a>Gram</a> is
--   defined in such a way that we can always access the first parsers to
--   be ran from such a structure. We require that all the <a>Alt</a>s do
--   not recognise the empty string. These should be covered by the
--   <a>Maybe</a> in the <a>Gram</a> constructor.
data Gram f a
Gram :: [Alt f a] -> (Maybe a) -> Gram f a
data Alt f a
Seq :: (f (b -> a)) -> (Gram f b) -> Alt f a
Bind :: (f b) -> (b -> Gram f a) -> Alt f a

-- | The function <tt>mkGram</tt> splits a simple parser into the possibly
--   empty part and the non-empty part. The non-empty part recognises a
--   consecutive part of the input. Here we use the functions
--   <tt>getOneP</tt> and <tt>getZeroP</tt> which are provided in the
--   uu-parsinglib package, but they could easily be provided by other
--   packages too.
mkG :: (Splittable f, Functor f) => f a -> Gram f a

-- | <tt>mkParser</tt> converts a <a>Gram</a>mar back into a parser, which
--   can subsequenly be run.
mkP :: (Monad f, Applicative f, Alternative f) => Gram f a -> f a

-- | The function <a>&lt;&lt;||&gt;</a> is a special version of
--   <a>&lt;||&gt;</a>, which only starts a new instance of its right
--   operand when the left operand cannot proceed. This is used in the
--   function <tt>pmMany</tt>, where we want to merge as many instances of
--   its argument, but no more than that.
(<<||>) :: Functor f => Gram f (b -> a) -> Gram f b -> Gram f a
infixl 4 <<||>

-- | The function <a>&lt;||&gt;</a> is the merging equivalent of
--   <a>&lt;*&gt;</a>. Instead of running its two arguments consecutively,
--   the input is split into parts which serve as input for the left
--   operand and parts which are served to the right operand.
(<||>) :: Functor f => Gram f (a1 -> a2) -> Gram f a1 -> Gram f a2
infixl 4 <||>

-- | <a>sepBy</a> is like <a>mkP</a>, with the additional feature that we
--   require separators between the components. Probably only useful in the
--   permuting case.
sepBy :: (Monad f, Applicative f, Alternative f) => Gram f a -> f b -> f a

-- | Run a sufficient number of <tt>p</tt>'s in a merged fashion, but no
--   more than necessary!!
gmList :: Functor f => Gram f a -> Gram f [a]
instance GHC.Base.Functor f => GHC.Base.Monoid (Control.Applicative.Interleaved.Gram f (r -> r))
instance GHC.Show.Show a => GHC.Show.Show (Control.Applicative.Interleaved.Gram f a)
instance GHC.Base.Functor f => GHC.Base.Functor (Control.Applicative.Interleaved.Gram f)
instance GHC.Base.Functor f => GHC.Base.Functor (Control.Applicative.Interleaved.Alt f)
instance GHC.Base.Functor f => GHC.Base.Applicative (Control.Applicative.Interleaved.Gram f)
instance GHC.Base.Functor f => GHC.Base.Alternative (Control.Applicative.Interleaved.Gram f)
instance GHC.Base.Functor f => GHC.Base.Monad (Control.Applicative.Interleaved.Gram f)
