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


-- | A simple environment to control access to data
--   
--   This is a small capability-based interface to check legitimacy of
--   accesses in different parts of the program depending on the context in
--   which the data is accessed. See the README.md in the repository for a
--   longer explanation and an example.
@package safe-access
@version 0.3.2.0

module Control.SafeAccess

-- | Allow things to be accessed. See <a>ensureAccess</a>.
--   
--   <tt>d</tt> is the type describing an access.
newtype Capability m d
MkCapability :: (d -> m AccessDecision) -> Capability m d
[runCapability] :: Capability m d -> d -> m AccessDecision
type Capabilities m d = [Capability m d]

-- | Control the decision process.
--   
--   The constructors are ordered by prevalence. For instance, if two
--   capabilities respectively return <a>AccessGranted</a> and
--   <a>AccessDenied</a>, the final decision will be <a>AccessDenied</a>.
data AccessDecision

-- | No but another <a>Capability</a> can still decide to grant
AccessDeniedSoft :: AccessDecision

-- | Final yes (see explanation)
AccessGranted :: AccessDecision

-- | Final no
AccessDenied :: AccessDecision

-- | A simple monad transformer to ensure that data are accessed
--   legitimately.
--   
--   The return value is either the description of an access having been
--   denied (left) or the result of the normal computation (right).
newtype SafeAccessT d m a
SafeAccessT :: (Capabilities m d -> m (Either d a)) -> SafeAccessT d m a
[runSafeAccessT] :: SafeAccessT d m a -> Capabilities m d -> m (Either d a)
class (Monad m, Monad s) => MonadSafeAccess d m s | m -> s, m -> d
getCapabilities :: MonadSafeAccess d m s => m (Capabilities s d)
liftSub :: MonadSafeAccess d m s => s a -> m a
denyAccess :: MonadSafeAccess d m s => d -> m ()

-- | Check that the access is legal or make the monad "fail".
ensureAccess :: MonadSafeAccess d m s => d -> m ()

-- | Allow certain accesses regardless of the capabilities. (unsecure!)
unsecureAllow :: (Monad m, Eq d) => [d] -> SafeAccessT d m a -> SafeAccessT d m a

-- | Create a capability which only allows a given access
singleCapability :: (Applicative f, Eq d) => d -> Capability f d

-- | Create a capability which only allows given accesses
someCapabilities :: (Applicative f, Eq d) => [d] -> Capability f d

-- | A special capability which allows every access. Be careful with this!
passthroughCapability :: Applicative f => Capability f d

-- | Lift an action from <tt>ErrorT</tt> to <a>SafeAccessT</a>.
liftExceptT :: ExceptT d m a -> SafeAccessT d m a
liftCapability :: (Monad m, MonadTrans t) => Capability m d -> Capability (t m) d
instance GHC.Classes.Eq Control.SafeAccess.AccessDecision
instance GHC.Show.Show Control.SafeAccess.AccessDecision
instance GHC.Base.Applicative m => GHC.Base.Monoid (Control.SafeAccess.Capability m d)
instance GHC.Base.Monoid Control.SafeAccess.AccessDecision
instance GHC.Base.Functor f => GHC.Base.Functor (Control.SafeAccess.SafeAccessT d f)
instance GHC.Base.Applicative f => GHC.Base.Applicative (Control.SafeAccess.SafeAccessT d f)
instance GHC.Base.Monad m => GHC.Base.Monad (Control.SafeAccess.SafeAccessT d m)
instance Control.Monad.Trans.Class.MonadTrans (Control.SafeAccess.SafeAccessT d)
instance Control.Monad.IO.Class.MonadIO m => Control.Monad.IO.Class.MonadIO (Control.SafeAccess.SafeAccessT d m)
instance GHC.Base.Monad m => Control.SafeAccess.MonadSafeAccess d (Control.SafeAccess.SafeAccessT d m) m
instance Control.Monad.Error.Class.MonadError e m => Control.Monad.Error.Class.MonadError e (Control.SafeAccess.SafeAccessT d m)
instance Control.Monad.Reader.Class.MonadReader r m => Control.Monad.Reader.Class.MonadReader r (Control.SafeAccess.SafeAccessT d m)
instance Control.Monad.State.Class.MonadState s m => Control.Monad.State.Class.MonadState s (Control.SafeAccess.SafeAccessT d m)
instance Control.Monad.Writer.Class.MonadWriter w m => Control.Monad.Writer.Class.MonadWriter w (Control.SafeAccess.SafeAccessT d m)
instance Control.SafeAccess.MonadSafeAccess d m s => Control.SafeAccess.MonadSafeAccess d (Control.Monad.Trans.Cont.ContT e m) s
instance Control.SafeAccess.MonadSafeAccess d m s => Control.SafeAccess.MonadSafeAccess d (Control.Monad.Trans.Except.ExceptT e m) s
instance Control.SafeAccess.MonadSafeAccess d m s => Control.SafeAccess.MonadSafeAccess d (Control.Monad.Trans.Identity.IdentityT m) s
instance Control.SafeAccess.MonadSafeAccess d m s => Control.SafeAccess.MonadSafeAccess d (Control.Monad.Trans.List.ListT m) s
instance Control.SafeAccess.MonadSafeAccess d m s => Control.SafeAccess.MonadSafeAccess d (Control.Monad.Trans.Maybe.MaybeT m) s
instance Control.SafeAccess.MonadSafeAccess d m s => Control.SafeAccess.MonadSafeAccess d (Control.Monad.Trans.Reader.ReaderT r m) s
instance (Control.SafeAccess.MonadSafeAccess d m s, GHC.Base.Monoid w) => Control.SafeAccess.MonadSafeAccess d (Control.Monad.Trans.RWS.Lazy.RWST r w st m) s
instance (Control.SafeAccess.MonadSafeAccess d m s, GHC.Base.Monoid w) => Control.SafeAccess.MonadSafeAccess d (Control.Monad.Trans.Writer.Lazy.WriterT w m) s