-- 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 implementations for filter, compact
--   (catMaybes), and separate. It allows for higher performance
--   implementations to be used in place of defaults for all data
--   structures, and endeavors to centerally document those
--   implementations. 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.2.3

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
partition :: Compactable f => (a -> Bool) -> f a -> (f a, f a)
partition :: (Compactable f, Functor f) => (a -> Bool) -> f a -> (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 Alternative (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, Monad f, Alternative f, Foldable g) => f (g a) -> f a
separateFold :: (CompactFold f, Bifoldable g) => f (g a b) -> (f a, f b)
separateFold :: (CompactFold f, Monad f, Alternative 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, Alternative m) => f a -> m a
mlefts :: (Bifoldable f, Alternative m) => f a b -> m a
mrights :: (Bifoldable f, Alternative 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.Alternative f => GHC.Base.Alternative (Control.Compactable.AltSum f)
instance GHC.Base.Applicative f => GHC.Base.Applicative (Control.Compactable.AltSum f)
instance GHC.Base.Functor f => GHC.Base.Functor (Control.Compactable.AltSum f)
instance Control.Compactable.CompactFold []
instance Control.Compactable.CompactFold GHC.Maybe.Maybe
instance Control.Compactable.CompactFold GHC.Types.IO
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.Compactable.CompactFold Control.Applicative.ZipList
instance Control.Compactable.CompactFold Data.Semigroup.Option
instance Control.Compactable.CompactFold GHC.Generics.U1
instance Control.Compactable.CompactFold Data.Proxy.Proxy
instance (Control.Arrow.ArrowPlus a, Control.Arrow.ArrowApply a) => Control.Compactable.CompactFold (Control.Arrow.ArrowMonad a)
instance GHC.Base.MonadPlus a => Control.Compactable.CompactFold (Control.Applicative.WrappedMonad a)
instance (GHC.Base.Alternative a, GHC.Base.Monad a) => Control.Compactable.CompactFold (GHC.Generics.Rec1 a)
instance (GHC.Base.Alternative a, GHC.Base.Monad a) => Control.Compactable.CompactFold (Data.Semigroup.Internal.Alt a)
instance (GHC.Base.Alternative f, GHC.Base.Monad f, GHC.Base.Alternative g, GHC.Base.Monad g) => Control.Compactable.CompactFold (f GHC.Generics.:*: g)
instance (Control.Compactable.Compactable f, GHC.Base.Alternative f, GHC.Base.Monad f, Control.Compactable.Compactable g, GHC.Base.Alternative g, GHC.Base.Monad g) => Control.Compactable.CompactFold (Data.Functor.Product.Product f g)
instance (GHC.Base.Alternative f, GHC.Base.Monad f) => Control.Compactable.CompactFold (GHC.Generics.M1 i c f)
instance GHC.Base.Alternative f => GHC.Base.Semigroup (Control.Compactable.AltSum f a)
instance GHC.Base.Alternative f => GHC.Base.Monoid (Control.Compactable.AltSum f a)
instance Control.Compactable.Compactable GHC.Maybe.Maybe
instance GHC.Base.Monoid m => Control.Compactable.Compactable (Data.Either.Either m)
instance Control.Compactable.Compactable []
instance Control.Compactable.Compactable Control.Applicative.ZipList
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 GHC.Generics.U1
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
instance (Control.Arrow.ArrowPlus a, Control.Arrow.ArrowApply a) => Control.Compactable.Compactable (Control.Arrow.ArrowMonad a)
instance GHC.Base.Monad a => Control.Compactable.Compactable (Control.Applicative.WrappedMonad a)
instance GHC.Base.Functor a => Control.Compactable.Compactable (GHC.Generics.Rec1 a)
instance GHC.Base.Functor a => Control.Compactable.Compactable (Data.Semigroup.Internal.Alt a)
instance (GHC.Base.Functor a, GHC.Base.Functor b) => Control.Compactable.Compactable (a GHC.Generics.:*: b)
instance GHC.Base.Functor f => Control.Compactable.Compactable (GHC.Generics.M1 i c f)
instance (GHC.Base.Functor f, GHC.Base.Functor g) => Control.Compactable.Compactable (f GHC.Generics.:.: g)