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


-- | List monad transformer and class
--   
--   A List monad transformer and a List class. With standard list
--   operations for Lists
@package List
@version 0.6.2


-- | The <a>List</a> class and actions for lists
module Data.List.Class

-- | A class for list types. Every list has an underlying monad.
class (MonadPlus l, Monad (ItemM l)) => List l where {
    type ItemM l :: * -> *;
}
runList :: List l => l a -> ItemM l (ListItem l a)

-- | Transform an action returning a list to the returned list
--   
--   <pre>
--   &gt; joinL $ Identity "hello"
--   "hello"
--   </pre>
joinL :: List l => ItemM l (l a) -> l a

-- | cons. Can be derived from MonadPlus but is part of class for
--   performance.
cons :: List l => a -> l a -> l a
infixr 5 `cons`
data ListItem l a
Nil :: ListItem l a
Cons :: a -> l a -> ListItem l a
[headL] :: ListItem l a -> a
[tailL] :: ListItem l a -> l a

-- | Convert a list to a <a>MonadPlus</a>
--   
--   <pre>
--   &gt; fromList [] :: Maybe Int
--   Nothing
--   &gt; fromList [5] :: Maybe Int
--   Just 5
--   </pre>
fromList :: List l => [a] -> l a

-- | filter for any MonadPlus
--   
--   <pre>
--   &gt; filter (&gt; 5) (Just 3)
--   Nothing
--   </pre>
filter :: MonadPlus m => (a -> Bool) -> m a -> m a
repeat :: List l => a -> l a
take :: List l => Int -> l a -> l a
takeWhile :: List l => (a -> Bool) -> l a -> l a
genericTake :: (Integral i, List l) => i -> l a -> l a
scanl :: List l => (a -> b -> a) -> a -> l b -> l a
scanl1 :: List l => (a -> a -> a) -> l a -> l a
transpose :: List l => l (l a) -> l (l a)
zip :: List l => l a -> l b -> l (a, b)
zipWith :: List l => (a -> b -> c) -> l a -> l b -> l c

-- | Generalized <a>concat</a>
--   
--   For <tt>List l =&gt; l (l a) -&gt; l a</tt> use <a>join</a>
concat :: List l => l [a] -> l a

-- | Genereralized <a>concatMap</a>
--   
--   For <tt>List l =&gt; (a -&gt; l b) -&gt; l a -&gt; l b</tt> use
--   <a>=&lt;&lt;</a> (monadic bind)
concatMap :: List l => (a -> [b]) -> l a -> l b
tail :: List l => l a -> l a
enumFrom :: (List l, Enum a) => a -> l a
enumFromTo :: (List l, Enum a) => a -> a -> l a
catMaybes :: List l => l (Maybe a) -> l a
mapMaybe :: List l => (a -> Maybe b) -> l a -> l b

-- | foldr for <a>List</a>s. the result and 'right side' values are monadic
--   actions.
foldrL :: List l => (a -> ItemM l b -> ItemM l b) -> ItemM l b -> l a -> ItemM l b

-- | An action to do foldl for <a>List</a>s
foldlL :: List l => (a -> b -> a) -> a -> l b -> ItemM l a
foldl1L :: List l => (a -> a -> a) -> l a -> ItemM l a

-- | An action to transform a <a>List</a> to a list
--   
--   <pre>
--   &gt; runIdentity $ toList "hello!"
--   "hello!"
--   </pre>
toList :: List l => l a -> ItemM l [a]

-- | Consume a list (execute its actions) and return its length
--   
--   <pre>
--   &gt; runIdentity $ lengthL [1,2,3]
--   3
--   </pre>
lengthL :: (Integral i, List l) => l a -> ItemM l i

-- | Consume all items and return the last one
--   
--   <pre>
--   &gt; runIdentity $ lastL "hello"
--   'o'
--   </pre>
lastL :: List l => l a -> ItemM l a

-- | Merge two lists sorted by a criteria given the criteria
--   
--   <pre>
--   &gt; merge2On id "01568" "239"
--   "01235689"
--   </pre>
merge2On :: (Ord b, List l) => (a -> b) -> l a -> l a -> l a

-- | Merge many lists sorted by a criteria given the criteria
--   
--   <pre>
--   &gt; mergeOn length [["hi", "hey", "hello"], ["cat", "falcon"], ["banana", "cucumber"]]
--   ["hi","cat","hey","hello","banana","falcon","cucumber"]
--   </pre>
mergeOn :: (Ord b, List l) => (a -> b) -> l (l a) -> l a

-- | Execute the monadic actions in a <a>List</a>
execute :: List l => l a -> ItemM l ()

-- | Transform a list of actions to a list of their results
--   
--   <pre>
--   &gt; joinM [Identity 4, Identity 7]
--   [4,7]
--   </pre>
joinM :: List l => l (ItemM l a) -> l a
mapL :: List l => (a -> ItemM l b) -> l a -> l b
filterL :: List l => (a -> ItemM l Bool) -> l a -> l a

-- | Monadic version of iterate. Can be used to produce trees given a
--   children of node function.
--   
--   <pre>
--   import Data.List.Tree (bfsLayers)
--   take 3 $ bfsLayers (iterateM (\i -&gt; [i*2, i*2+1]) [1] :: ListT [] Int)
--   [[1],[2,3],[4,5,6,7]]
--   </pre>
iterateM :: List l => (a -> ItemM l a) -> ItemM l a -> l a
takeWhileM :: List l => (a -> ItemM l Bool) -> l a -> l a
repeatM :: List l => ItemM l a -> l a

-- | Monadic variant of splitAt. Consumes x items from the list and return
--   them with the remaining monadic list.
splitAtM :: List l => Int -> l a -> ItemM l ([a], l a)

-- | Monadic variant of break. Consumes items from the list until a
--   condition holds.
splitWhenM :: List l => (a -> ItemM l Bool) -> l a -> ItemM l ([a], l a)
sortOn :: Ord b => (a -> b) -> [a] -> [a]

-- | Transform the underlying monad of a list given a way to transform the
--   monad
--   
--   <pre>
--   &gt; import Data.List.Tree (bfs)
--   &gt; bfs (transformListMonad (\(Identity x) -&gt; [x, x]) "hey" :: ListT [] Char)
--   "hheeeeyyyyyyyy"
--   </pre>
transformListMonad :: (List l, List k) => (ItemM l (k a) -> ItemM k (k a)) -> l a -> k a

-- | listStateJoin can transform a <tt>ListT (StateT s m) a</tt> to a
--   <tt>StateT s m (ListT m a)</tt>.
--   
--   When iterating a list, a state is already maintained and passed along
--   in the form of the location along the list. This joins the inner
--   <tt>StateT s</tt> into the list. The list will fork the state given to
--   it and won't share its changes.
listStateJoin :: (List l, List k, ItemM l ~ StateT s (ItemM k)) => l a -> ItemM l (k a)
instance (GHC.Show.Show a, GHC.Show.Show (l a)) => GHC.Show.Show (Data.List.Class.ListItem l a)
instance (GHC.Read.Read a, GHC.Read.Read (l a)) => GHC.Read.Read (Data.List.Class.ListItem l a)
instance (GHC.Classes.Ord a, GHC.Classes.Ord (l a)) => GHC.Classes.Ord (Data.List.Class.ListItem l a)
instance (GHC.Classes.Eq a, GHC.Classes.Eq (l a)) => GHC.Classes.Eq (Data.List.Class.ListItem l a)
instance Data.List.Class.List []
instance GHC.Base.Functor m => GHC.Base.Functor (Data.List.Class.ListItem m)


-- | A list monad transformer / a monadic list.
--   
--   Monadic list example: A program which reads numbers from the user and
--   accumulates them.
--   
--   <pre>
--   import Control.Monad.ListT.Funcs (repeatM)
--   import Data.List.Class (execute, scanl, takeWhile, mapL)
--   import Prelude hiding (scanl, takeWhile)
--   
--   main =
--       execute . mapL print .
--       scanl (+) 0 .
--       fmap (fst . head) .
--       takeWhile (not . null) .
--       fmap reads $ repeatM getLine
--   </pre>
--   
--   Note: The <tt>transformers</tt> package also has a <a>ListT</a> type,
--   which oddly enough it is not a list monad transformer. This module was
--   deliberately named differently from <tt>transformers</tt>'s module.
module Control.Monad.ListT
newtype ListT m a
ListT :: m (ListItem (ListT m) a) -> ListT m a
[runListT] :: ListT m a -> m (ListItem (ListT m) a)
instance GHC.Classes.Eq (m (Data.List.Class.ListItem (Control.Monad.ListT.ListT m) a)) => GHC.Classes.Eq (Control.Monad.ListT.ListT m a)
instance GHC.Classes.Ord (m (Data.List.Class.ListItem (Control.Monad.ListT.ListT m) a)) => GHC.Classes.Ord (Control.Monad.ListT.ListT m a)
instance GHC.Read.Read (m (Data.List.Class.ListItem (Control.Monad.ListT.ListT m) a)) => GHC.Read.Read (Control.Monad.ListT.ListT m a)
instance GHC.Show.Show (m (Data.List.Class.ListItem (Control.Monad.ListT.ListT m) a)) => GHC.Show.Show (Control.Monad.ListT.ListT m a)
instance GHC.Base.Monad m => GHC.Base.Semigroup (Control.Monad.ListT.ListT m a)
instance GHC.Base.Monad m => GHC.Base.Monoid (Control.Monad.ListT.ListT m a)
instance GHC.Base.Functor m => GHC.Base.Functor (Control.Monad.ListT.ListT m)
instance GHC.Base.Monad m => GHC.Base.Monad (Control.Monad.ListT.ListT m)
instance GHC.Base.Monad m => GHC.Base.Applicative (Control.Monad.ListT.ListT m)
instance GHC.Base.Monad m => GHC.Base.Alternative (Control.Monad.ListT.ListT m)
instance GHC.Base.Monad m => GHC.Base.MonadPlus (Control.Monad.ListT.ListT m)
instance Control.Monad.Trans.Class.MonadTrans Control.Monad.ListT.ListT
instance GHC.Base.Monad m => Data.List.Class.List (Control.Monad.ListT.ListT m)
instance Control.Monad.IO.Class.MonadIO m => Control.Monad.IO.Class.MonadIO (Control.Monad.ListT.ListT m)


-- | <tt>List</tt> functions with type limited to use <tt>ListT</tt>. This
--   might come useful for type interference.
--   
--   Functions where the <tt>List</tt> is an input type and not only the
--   result type do not need special limited versions.
module Control.Monad.ListT.Funcs
iterateM :: Monad m => (a -> m a) -> m a -> ListT m a
repeatM :: Monad m => m a -> ListT m a
repeat :: Monad m => a -> ListT m a
fromList :: Monad m => [a] -> ListT m a
