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


-- | Perhaps, a monad
--   
--   Perhaps, a monad.
@package perhaps
@version 0


module Control.Monad.Perhaps

-- | This monad occupies the middle ground between <a>Maybe</a> and
--   <a>Either</a> in that you can get out an informative error but aren't
--   able to care about its contents, except via bottoms.
--   
--   Since bottoms are indistinguishable in pure code, one can view this as
--   morally the same as <a>Maybe</a>, except when things go wrong, you can
--   pass along a complaint, rather than take what you'd get from
--   <a>fromJust</a>.
--   
--   <pre>
--   &gt;&gt;&gt; import Control.Exception
--   
--   &gt;&gt;&gt; let x = excuse Overflow :: Perhaps ()
--   </pre>
--   
--   Attempting to <a>Show</a> a <a>Perhaps</a> value is hazardous, as it
--   will contain an embedded exception.
--   
--   <pre>
--   &gt;&gt;&gt; x
--   Can't *** Exception: arithmetic overflow
--   </pre>
--   
--   Recovery is possible as <a>Can't</a> isn't strict in its argument.
--   
--   <pre>
--   &gt;&gt;&gt; x &lt;|&gt; Can ()
--   Can ()
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; x `seq` ()
--   ()
--   </pre>
data Perhaps a
Can :: a -> Perhaps a
Can't :: Void -> Perhaps a

-- | This partial function can be used like <tt>fromJust</tt>, but throws
--   the user error.
believe :: Perhaps a -> a
mayhap :: Perhaps a -> Maybe a
newtype PerhapsT m a
PerhapsT :: m (Perhaps a) -> PerhapsT m a
[runPerhapsT] :: PerhapsT m a -> m (Perhaps a)
class MonadPlus m => MonadPerhaps m

-- | This is a monad homomorphism
perhaps :: MonadPerhaps m => Perhaps a -> m a

-- | This is a monad homomorphism
perhaps :: (MonadPerhaps m, m ~ t n, MonadTrans t, MonadPerhaps n) => Perhaps a -> m a

-- | Fail with an exception as an excuse instead of just a string.
excuse :: (MonadPerhaps m, Exception e) => e -> m a

-- | Transform the computation inside a <tt>PerhapsT</tt>.
--   
--   <ul>
--   <li><pre><a>runPerhapsT</a> (<a>mapPerhapsT</a> f m) = f
--   (<a>runPerhapsT</a> m)</pre></li>
--   </ul>
mapPerhapsT :: (m (Perhaps a) -> n (Perhaps b)) -> PerhapsT m a -> PerhapsT n b

-- | Lift a <tt>callCC</tt> operation to the new monad.
liftCallCC :: CallCC m (Perhaps a) (Perhaps b) -> CallCC (PerhapsT m) a b

-- | Lift a <tt>catchE</tt> operation to the new monad.
liftCatch :: Catch e m (Perhaps a) -> Catch e (PerhapsT m) a

-- | Lift a <tt>listen</tt> operation to the new monad.
liftListen :: Monad m => Listen w m (Perhaps a) -> Listen w (PerhapsT m) a

-- | Lift a <tt>pass</tt> operation to the new monad.
liftPass :: Monad m => Pass w m (Perhaps a) -> Pass w (PerhapsT m) a
instance Data.Traversable.Traversable m => Data.Traversable.Traversable (Control.Monad.Perhaps.PerhapsT m)
instance Data.Foldable.Foldable m => Data.Foldable.Foldable (Control.Monad.Perhaps.PerhapsT m)
instance GHC.Base.Functor m => GHC.Base.Functor (Control.Monad.Perhaps.PerhapsT m)
instance GHC.Base.Functor m => GHC.Generics.Generic1 (Control.Monad.Perhaps.PerhapsT m)
instance GHC.Generics.Generic (Control.Monad.Perhaps.PerhapsT m a)
instance Data.Traversable.Traversable Control.Monad.Perhaps.Perhaps
instance Data.Foldable.Foldable Control.Monad.Perhaps.Perhaps
instance GHC.Base.Functor Control.Monad.Perhaps.Perhaps
instance GHC.Show.Show a => GHC.Show.Show (Control.Monad.Perhaps.Perhaps a)
instance GHC.Read.Read a => GHC.Read.Read (Control.Monad.Perhaps.Perhaps a)
instance GHC.Classes.Ord a => GHC.Classes.Ord (Control.Monad.Perhaps.Perhaps a)
instance GHC.Classes.Eq a => GHC.Classes.Eq (Control.Monad.Perhaps.Perhaps a)
instance Data.Data.Data a => Data.Data.Data (Control.Monad.Perhaps.Perhaps a)
instance GHC.Generics.Generic1 Control.Monad.Perhaps.Perhaps
instance GHC.Generics.Generic (Control.Monad.Perhaps.Perhaps a)
instance GHC.Classes.Eq (m (Control.Monad.Perhaps.Perhaps a)) => GHC.Classes.Eq (Control.Monad.Perhaps.PerhapsT m a)
instance GHC.Classes.Ord (m (Control.Monad.Perhaps.Perhaps a)) => GHC.Classes.Ord (Control.Monad.Perhaps.PerhapsT m a)
instance GHC.Show.Show (m (Control.Monad.Perhaps.Perhaps a)) => GHC.Show.Show (Control.Monad.Perhaps.PerhapsT m a)
instance GHC.Read.Read (m (Control.Monad.Perhaps.Perhaps a)) => GHC.Read.Read (Control.Monad.Perhaps.PerhapsT m a)
instance (Data.Data.Data (m (Control.Monad.Perhaps.Perhaps a)), Data.Typeable.Internal.Typeable m, Data.Typeable.Internal.Typeable a) => Data.Data.Data (Control.Monad.Perhaps.PerhapsT m a)
instance Control.Monad.Perhaps.MonadPerhaps Control.Monad.Perhaps.Perhaps
instance GHC.Base.Monad m => Control.Monad.Perhaps.MonadPerhaps (Control.Monad.Perhaps.PerhapsT m)
instance Control.Monad.Perhaps.MonadPerhaps m => Control.Monad.Perhaps.MonadPerhaps (Control.Monad.Trans.State.Lazy.StateT s m)
instance Control.Monad.Perhaps.MonadPerhaps m => Control.Monad.Perhaps.MonadPerhaps (Control.Monad.Trans.State.Strict.StateT s m)
instance (Control.Monad.Perhaps.MonadPerhaps m, GHC.Base.Monoid w) => Control.Monad.Perhaps.MonadPerhaps (Control.Monad.Trans.Writer.Lazy.WriterT w m)
instance (Control.Monad.Perhaps.MonadPerhaps m, GHC.Base.Monoid w) => Control.Monad.Perhaps.MonadPerhaps (Control.Monad.Trans.Writer.Strict.WriterT w m)
instance (Control.Monad.Perhaps.MonadPerhaps m, GHC.Base.Monoid w) => Control.Monad.Perhaps.MonadPerhaps (Control.Monad.Trans.RWS.Lazy.RWST r w s m)
instance (Control.Monad.Perhaps.MonadPerhaps m, GHC.Base.Monoid w) => Control.Monad.Perhaps.MonadPerhaps (Control.Monad.Trans.RWS.Strict.RWST r w s m)
instance Control.Monad.Perhaps.MonadPerhaps m => Control.Monad.Perhaps.MonadPerhaps (Control.Monad.Trans.Reader.ReaderT r m)
instance Control.Monad.Perhaps.MonadPerhaps m => Control.Monad.Perhaps.MonadPerhaps (Control.Monad.Trans.Identity.IdentityT m)
instance GHC.Base.Monad m => GHC.Base.Applicative (Control.Monad.Perhaps.PerhapsT m)
instance GHC.Base.Monad m => GHC.Base.Alternative (Control.Monad.Perhaps.PerhapsT m)
instance GHC.Base.Monad m => GHC.Base.Monad (Control.Monad.Perhaps.PerhapsT m)
instance GHC.Base.Monad m => Control.Monad.Fail.MonadFail (Control.Monad.Perhaps.PerhapsT m)
instance GHC.Base.Monad m => GHC.Base.MonadPlus (Control.Monad.Perhaps.PerhapsT m)
instance Control.Monad.Zip.MonadZip m => Control.Monad.Zip.MonadZip (Control.Monad.Perhaps.PerhapsT m)
instance Control.Monad.Fix.MonadFix m => Control.Monad.Fix.MonadFix (Control.Monad.Perhaps.PerhapsT m)
instance Control.Monad.Trans.Class.MonadTrans Control.Monad.Perhaps.PerhapsT
instance Control.Monad.IO.Class.MonadIO m => Control.Monad.IO.Class.MonadIO (Control.Monad.Perhaps.PerhapsT m)
instance Control.Monad.State.Class.MonadState s m => Control.Monad.State.Class.MonadState s (Control.Monad.Perhaps.PerhapsT m)
instance Control.Monad.Writer.Class.MonadWriter w m => Control.Monad.Writer.Class.MonadWriter w (Control.Monad.Perhaps.PerhapsT m)
instance Control.Monad.Cont.Class.MonadCont m => Control.Monad.Cont.Class.MonadCont (Control.Monad.Perhaps.PerhapsT m)
instance Control.Monad.Reader.Class.MonadReader r m => Control.Monad.Reader.Class.MonadReader r (Control.Monad.Perhaps.PerhapsT m)
instance GHC.Base.Semigroup a => GHC.Base.Semigroup (Control.Monad.Perhaps.Perhaps a)
instance GHC.Base.Semigroup a => GHC.Base.Monoid (Control.Monad.Perhaps.Perhaps a)
instance GHC.Base.Applicative Control.Monad.Perhaps.Perhaps
instance GHC.Base.Alternative Control.Monad.Perhaps.Perhaps
instance GHC.Base.Monad Control.Monad.Perhaps.Perhaps
instance Control.Monad.Fail.MonadFail Control.Monad.Perhaps.Perhaps
instance GHC.Base.MonadPlus Control.Monad.Perhaps.Perhaps
instance Control.Monad.Fix.MonadFix Control.Monad.Perhaps.Perhaps
instance Control.Monad.Zip.MonadZip Control.Monad.Perhaps.Perhaps


module Data.Perhaps

-- | This monad occupies the middle ground between <a>Maybe</a> and
--   <a>Either</a> in that you can get out an informative error but aren't
--   able to care about its contents, except via bottoms.
--   
--   Since bottoms are indistinguishable in pure code, one can view this as
--   morally the same as <a>Maybe</a>, except when things go wrong, you can
--   pass along a complaint, rather than take what you'd get from
--   <a>fromJust</a>.
--   
--   <pre>
--   &gt;&gt;&gt; import Control.Exception
--   
--   &gt;&gt;&gt; let x = excuse Overflow :: Perhaps ()
--   </pre>
--   
--   Attempting to <a>Show</a> a <a>Perhaps</a> value is hazardous, as it
--   will contain an embedded exception.
--   
--   <pre>
--   &gt;&gt;&gt; x
--   Can't *** Exception: arithmetic overflow
--   </pre>
--   
--   Recovery is possible as <a>Can't</a> isn't strict in its argument.
--   
--   <pre>
--   &gt;&gt;&gt; x &lt;|&gt; Can ()
--   Can ()
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; x `seq` ()
--   ()
--   </pre>
data Perhaps a
Can :: a -> Perhaps a
Can't :: Void -> Perhaps a

-- | This partial function can be used like <tt>fromJust</tt>, but throws
--   the user error.
believe :: Perhaps a -> a
mayhap :: Perhaps a -> Maybe a

-- | Fail with an exception as an excuse instead of just a string.
excuse :: (MonadPerhaps m, Exception e) => e -> m a