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


-- | A typeclass for structures which can be catMaybed, filtered, and partitioned.
--   
--   This provides polymorphic implimentations for filter, compact
--   (catMaybes), and separate. It allows for higher performance
--   implimentations to be used in place of defaults for all data
--   structures, and endeavors to centerally document those
--   implimentations. Compactable aims to be as general and unconstrained
--   as possible, providing instances for non-Functors like Set, as well as
--   some Contravariants (though not published here). Compactable fully
--   subsumes Data.Witherable, offers more laws, and is more general.
@package compactable
@version 0.1.1.1

module Control.Compactable

-- | Class <a>Compactable</a> provides two methods which can be writen in
--   terms of each other, compact and separate.
--   
--   is generalization of catMaybes as a new function. Compact has
--   relations with Functor, Applicative, Monad, Alternative, and
--   Traversable. In that we can use these class to provide the ability to
--   operate on a data type by throwing away intermediate Nothings. This is
--   useful for representing stripping out values or failure.
--   
--   To be compactable alone, no laws must be satisfied other than the type
--   signature.
--   
--   If the data type is also a Functor the following should hold:
--   
--   <ul>
--   <li><i><i>Kleisli composition</i></i> <pre>fmapMaybe (l &lt;=&lt; r) =
--   fmapMaybe l . fmapMaybe r</pre></li>
--   <li><i><i>Functor identity 1</i></i> <pre>compact . fmap Just =
--   id</pre></li>
--   <li><i><i>Functor identity 2</i></i> <pre>fmapMaybe Just =
--   id</pre></li>
--   <li><i><i>Functor relation</i></i> <pre>compact = fmapMaybe
--   id</pre></li>
--   </ul>
--   
--   According to Kmett, (Compactable f, Functor f) is a functor from the
--   kleisli category of Maybe to the category of haskell data types.
--   <tt>Kleisli Maybe -&gt; Hask</tt>.
--   
--   If the data type is also Applicative the following should hold:
--   
--   <ul>
--   <li><i><i>Applicative left identity</i></i> <pre>compact . (pure Just
--   &lt;*&gt;) = id</pre></li>
--   <li><i><i>Applicative right identity</i></i> <pre>applyMaybe (pure
--   Just) = id</pre></li>
--   <li><i><i>Applicative relation</i></i> <pre>compact = applyMaybe (pure
--   id)</pre></li>
--   </ul>
--   
--   If the data type is also a Monad the following should hold:
--   
--   <ul>
--   <li><i><i>Monad left identity</i></i> <pre>flip bindMaybe (return .
--   Just) = id</pre></li>
--   <li><i><i>Monad right identity</i></i> <pre>compact . (return . Just
--   =&lt;&lt;) = id</pre></li>
--   <li><i><i>Monad relation</i></i> <pre>compact = flip bindMaybe
--   return</pre></li>
--   </ul>
--   
--   If the data type is also Alternative the following should hold:
--   
--   <ul>
--   <li><i><i>Alternative identity</i></i> <pre>compact empty =
--   empty</pre></li>
--   <li><i><i>Alternative annihilation</i></i> <pre>compact (const Nothing
--   &lt;$&gt; xs) = empty</pre></li>
--   </ul>
--   
--   If the data type is also Traversable the following should hold:
--   
--   <ul>
--   <li><i><i>Traversable Applicative relation</i></i> <pre>traverseMaybe
--   (pure . Just) = pure</pre></li>
--   <li><i><i>Traversable composition</i></i> <pre>Compose . fmap
--   (traverseMaybe f) . traverseMaybe g = traverseMaybe (Compose . fmap
--   (traverseMaybe f) . g)</pre></li>
--   <li><i><i>Traversable Functor relation</i></i> <pre>traverse f =
--   traverseMaybe (fmap Just . f)</pre></li>
--   <li><i><i>Traversable naturality</i></i> <pre>t . traverseMaybe f =
--   traverseMaybe (t . f)</pre></li>
--   </ul>
--   
--   <h1>Separate and filter</h1>
--   
--   have recently elevated roles in this typeclass, and is not as well
--   explored as compact. Here are the laws known today:
--   
--   <ul>
--   <li><i><i>Functor identity 3</i></i> <pre>fst . separate . fmap Right
--   = id</pre></li>
--   <li><i><i>Functor identity 4</i></i> <pre>snd . separate . fmap Left =
--   id</pre></li>
--   <li><i><i>Applicative left identity 2</i></i> <pre>snd . separate .
--   (pure Right &lt;*&gt;) = id</pre></li>
--   <li><i><i>Applicative right identity 2</i></i> <pre>fst . separate .
--   (pure Left &lt;*&gt;) = id</pre></li>
--   <li><i><i>Alternative annihilation left</i></i> <pre>snd . separate .
--   fmap (const Left) = empty</pre></li>
--   <li><i><i>Alternative annihilation right</i></i> <pre>fst , separate .
--   fmap (const Right) = empty</pre></li>
--   </ul>
--   
--   Docs for relationships between these functions and, a cleanup of laws
--   will happen at some point.
--   
--   If you know of more useful laws, or have better names for the ones
--   above (especially those marked "name me"). Please let me know.
class Compactable (f :: * -> *)
compact :: Compactable f => f (Maybe a) -> f a
compact :: (Compactable f, Functor f) => f (Maybe a) -> f a
separate :: Compactable f => f (Either l r) -> (f l, f r)
separate :: (Compactable f, Functor f) => f (Either l r) -> (f l, f r)
filter :: Compactable f => (a -> Bool) -> f a -> f a
filter :: (Compactable f, Functor f) => (a -> Bool) -> f a -> f a
fmapMaybe :: (Compactable f, Functor f) => (a -> Maybe b) -> f a -> f b
fmapEither :: (Compactable f, Functor f) => (a -> Either l r) -> f a -> (f l, f r)
applyMaybe :: (Compactable f, Applicative f) => f (a -> Maybe b) -> f a -> f b
applyEither :: (Compactable f, Applicative f) => f (a -> Either l r) -> f a -> (f l, f r)
bindMaybe :: (Compactable f, Monad f) => f a -> (a -> f (Maybe b)) -> f b
bindEither :: (Compactable f, Monad f) => f a -> (a -> f (Either l r)) -> (f l, f r)
traverseMaybe :: (Compactable f, Applicative g, Traversable f) => (a -> g (Maybe b)) -> f a -> g (f b)
traverseEither :: (Compactable f, Applicative g, Traversable f) => (a -> g (Either l r)) -> f a -> g (f l, f r)

-- | class <a>CompactFold</a> provides the same methods as
--   <a>Compactable</a> but generalized to work on any <a>Foldable</a>.
--   
--   When a type has MonadPlus (or similar) properties, we can extract the
--   Maybe and the Either, and generalize to Foldable and Bifoldable.
--   
--   Compactable can always be described in terms of CompactFold, because
--   
--   <pre>
--   compact = compactFold
--   </pre>
--   
--   and
--   
--   <pre>
--   separate = separateFold
--   </pre>
--   
--   as it's just a specialization. More exploration is needed on the
--   relationship here.
class Compactable f => CompactFold (f :: * -> *)
compactFold :: (CompactFold f, Foldable g) => f (g a) -> f a
compactFold :: (CompactFold f, MonadPlus f, Foldable g) => f (g a) -> f a
separateFold :: (CompactFold f, Bifoldable g) => f (g a b) -> (f a, f b)
separateFold :: (CompactFold f, MonadPlus f, Bifoldable g) => f (g a b) -> (f a, f b)
fmapFold :: (CompactFold f, Functor f, Foldable g) => (a -> g b) -> f a -> f b
fmapBifold :: (CompactFold f, Functor f, Bifoldable g) => (a -> g l r) -> f a -> (f l, f r)
applyFold :: (CompactFold f, Applicative f, Foldable g) => f (a -> g b) -> f a -> f b
applyBifold :: (CompactFold f, Applicative f, Bifoldable g) => f (a -> g l r) -> f a -> (f l, f r)
bindFold :: (CompactFold f, Monad f, Foldable g) => f a -> (a -> f (g b)) -> f b
bindBifold :: (CompactFold f, Monad f, Bifoldable g) => f a -> (a -> f (g l r)) -> (f l, f r)
traverseFold :: (CompactFold f, Applicative h, Foldable g, Traversable f) => (a -> h (g b)) -> f a -> h (f b)
traverseBifold :: (CompactFold f, Applicative h, Bifoldable g, Traversable f) => (a -> h (g l r)) -> f a -> h (f l, f r)
fforMaybe :: (Compactable f, Functor f) => f a -> (a -> Maybe b) -> f b
fforFold :: (CompactFold f, Functor f, Foldable g) => f a -> (a -> g b) -> f b
fforEither :: (Compactable f, Functor f) => f a -> (a -> Either l r) -> (f l, f r)
fforBifold :: (CompactFold f, Functor f, Bifoldable g) => f a -> (a -> g l r) -> (f l, f r)
mfold' :: (Foldable f, MonadPlus m) => f a -> m a
mlefts :: (Bifoldable f, MonadPlus m) => f a b -> m a
mrights :: (Bifoldable f, MonadPlus m) => f a b -> m b
fmapMaybeM :: (Compactable f, Monad f) => (a -> MaybeT f b) -> f a -> f b
fmapEitherM :: (Compactable f, Monad f) => (a -> ExceptT l f r) -> f a -> (f l, f r)
fforMaybeM :: (Compactable f, Monad f) => f a -> (a -> MaybeT f b) -> f b
fforEitherM :: (Compactable f, Monad f) => f a -> (a -> ExceptT l f r) -> (f l, f r)
applyMaybeM :: (Compactable f, Monad f) => f (a -> MaybeT f b) -> f a -> f b
bindMaybeM :: (Compactable f, Monad f) => f a -> (a -> f (MaybeT f b)) -> f b
traverseMaybeM :: (Monad m, Compactable t, Traversable t) => (a -> MaybeT m b) -> t a -> m (t b)

-- | While more constrained, when available, this default is going to be
--   faster than the one provided in the typeclass
altDefaultCompact :: (Alternative f, Monad f) => f (Maybe a) -> f a

-- | While more constrained, when available, this default is going to be
--   faster than the one provided in the typeclass
altDefaultSeparate :: (Alternative f, Foldable f) => f (Either l r) -> (f l, f r)
instance GHC.Base.MonadPlus f => GHC.Base.MonadPlus (Control.Compactable.MonadSum f)
instance GHC.Base.Monad f => GHC.Base.Monad (Control.Compactable.MonadSum f)
instance GHC.Base.Alternative f => GHC.Base.Alternative (Control.Compactable.MonadSum f)
instance GHC.Base.Applicative f => GHC.Base.Applicative (Control.Compactable.MonadSum f)
instance GHC.Base.Functor f => GHC.Base.Functor (Control.Compactable.MonadSum f)
instance (Control.Arrow.ArrowApply a, Control.Arrow.ArrowPlus a) => Control.Compactable.Compactable (Control.Arrow.ArrowMonad a)
instance Control.Compactable.CompactFold []
instance Control.Compactable.CompactFold GHC.Base.Maybe
instance Control.Compactable.CompactFold Text.ParserCombinators.ReadP.ReadP
instance Control.Compactable.CompactFold Text.ParserCombinators.ReadPrec.ReadPrec
instance Control.Compactable.CompactFold GHC.Conc.Sync.STM
instance (Control.Arrow.ArrowApply a, Control.Arrow.ArrowPlus a) => Control.Compactable.CompactFold (Control.Arrow.ArrowMonad a)
instance GHC.Base.MonadPlus f => GHC.Base.Monoid (Control.Compactable.MonadSum f a)
instance Control.Compactable.Compactable GHC.Base.Maybe
instance GHC.Base.Monoid m => Control.Compactable.Compactable (Data.Either.Either m)
instance Control.Compactable.Compactable []
instance Control.Compactable.Compactable GHC.Types.IO
instance Control.Compactable.Compactable GHC.Conc.Sync.STM
instance Control.Compactable.Compactable Data.Proxy.Proxy
instance Control.Compactable.Compactable Data.Semigroup.Option
instance Control.Compactable.Compactable Text.ParserCombinators.ReadP.ReadP
instance Control.Compactable.Compactable Text.ParserCombinators.ReadPrec.ReadPrec
instance (GHC.Base.Functor f, GHC.Base.Functor g, Control.Compactable.Compactable f, Control.Compactable.Compactable g) => Control.Compactable.Compactable (Data.Functor.Product.Product f g)
instance (GHC.Base.Functor f, GHC.Base.Functor g, Control.Compactable.Compactable g) => Control.Compactable.Compactable (Data.Functor.Compose.Compose f g)
instance Control.Compactable.Compactable Data.IntMap.Internal.IntMap
instance Control.Compactable.Compactable (Data.Map.Internal.Map k)
instance Control.Compactable.Compactable Data.Sequence.Internal.Seq
instance Control.Compactable.Compactable Data.Vector.Vector
instance Control.Compactable.Compactable (Data.Functor.Const.Const r)
instance Control.Compactable.Compactable Data.Set.Internal.Set