in-other-words-0.1.0.0: A higher-order effect system where the sky's the limit
Safe HaskellNone
LanguageHaskell2010

Control.Effect.Optional

Synopsis

Effects

data Optional s m a where Source #

A helper primitive effect for manipulating a region, with the option to execute it in full or in part. s is expected to be a functor.

Helper primitive effects are effects that allow you to avoid interpreting one of your own effects as a primitive if the power needed from direct access to the underlying monad can instead be provided by the relevant helper primitive effect. The reason why you'd want to do this is that helper primitive effects already have ThreadsEff instances defined for them, so you don't have to define any for your own effect.

The helper primitive effects offered in this library are -- in order of ascending power -- Regional, Optional, BaseControl and Unlift.

The typical use-case of Optional is to lift a natural transformation of a base monad equipped with the power to recover from an exception. HoistOption and accompanying interpreters is provided as a specialization of Optional for this purpose.

Optional in its most general form lacks a pre-defined interpreter: when not using HoistOption, you're expected to define your own interpreter for Optional (treating it as a primitive effect).

Optional is typically used as a primitive effect. If you define a Carrier that relies on a novel non-trivial monad transformer t, then you need to make a Functor s => ThreadsEff t (Optional s) instance (if possible). threadOptionalViaBaseControl can help you with that.

The following threading constraints accept Optional:

Constructors

Optionally :: s a -> m a -> Optional s m a 

Instances

Instances details
Carrier m => PrimHandler HoistOptionH (HoistOption m) m Source # 
Instance details

Defined in Control.Effect.Internal.Optional

Functor s => ThreadsEff ListT (Optional s) Source # 
Instance details

Defined in Control.Monad.Trans.List.Church

Methods

threadEff :: Monad m => (forall x. Optional s m x -> m x) -> Optional s (ListT m) a -> ListT m a Source #

Functor s => ThreadsEff (ExceptT e) (Optional s) Source # 
Instance details

Defined in Control.Effect.Type.Optional

Methods

threadEff :: Monad m => (forall x. Optional s m x -> m x) -> Optional s (ExceptT e m) a -> ExceptT e m a Source #

(Functor s, Monoid w) => ThreadsEff (WriterT w) (Optional s) Source # 
Instance details

Defined in Control.Effect.Type.Optional

Methods

threadEff :: Monad m => (forall x. Optional s m x -> m x) -> Optional s (WriterT w m) a -> WriterT w m a Source #

Functor s => ThreadsEff (StateT s') (Optional s) Source # 
Instance details

Defined in Control.Effect.Type.Optional

Methods

threadEff :: Monad m => (forall x. Optional s m x -> m x) -> Optional s (StateT s' m) a -> StateT s' m a Source #

ThreadsEff (ReaderT i) (Optional s) Source # 
Instance details

Defined in Control.Effect.Type.Optional

Methods

threadEff :: Monad m => (forall x. Optional s m x -> m x) -> Optional s (ReaderT i m) a -> ReaderT i m a Source #

Functor s => ThreadsEff (StateT s') (Optional s) Source # 
Instance details

Defined in Control.Effect.Type.Optional

Methods

threadEff :: Monad m => (forall x. Optional s m x -> m x) -> Optional s (StateT s' m) a -> StateT s' m a Source #

(Functor s, Monoid w) => ThreadsEff (WriterT w) (Optional s) Source # 
Instance details

Defined in Control.Effect.Type.Optional

Methods

threadEff :: Monad m => (forall x. Optional s m x -> m x) -> Optional s (WriterT w m) a -> WriterT w m a Source #

(Functor s, Monoid w) => ThreadsEff (WriterT w) (Optional s) Source # 
Instance details

Defined in Control.Effect.Type.Optional

Methods

threadEff :: Monad m => (forall x. Optional s m x -> m x) -> Optional s (WriterT w m) a -> WriterT w m a Source #

Functor s => ThreadsEff (FreeT f) (Optional s) Source # 
Instance details

Defined in Control.Monad.Trans.Free.Church.Alternate

Methods

threadEff :: Monad m => (forall x. Optional s m x -> m x) -> Optional s (FreeT f m) a -> FreeT f m a Source #

type HoistOption (b :: * -> *) = Optional (HoistOptionCall b) Source #

A useful specialization of Optional where the functor is HoistOptionCall b. From this, you can derive hoistOption.

newtype HoistOptionCall b a Source #

Constructors

HoistOptionCall (forall x. (a -> x) -> b x -> b x) 

Instances

Instances details
Carrier m => PrimHandler HoistOptionH (HoistOption m) m Source # 
Instance details

Defined in Control.Effect.Internal.Optional

Functor (HoistOptionCall b) Source # 
Instance details

Defined in Control.Effect.Internal.Optional

Methods

fmap :: (a -> b0) -> HoistOptionCall b a -> HoistOptionCall b b0 #

(<$) :: a -> HoistOptionCall b b0 -> HoistOptionCall b a #

Actions

optionally :: Eff (Optional s) m => s a -> m a -> m a Source #

Execute the provided computation, providing the interpretation of Optional s the option to execute it in full or in part.

hoistOption :: Eff (HoistOption b) m => (forall x. (a -> x) -> b x -> b x) -> m a -> m a Source #

Hoist a natural transformation of the base monad into the current monad, equipped with the option to execute the provided computation in full or in part.

Interpretations

runHoistOption :: Carrier m => HoistOptionC m a -> m a Source #

Runs a HoistOption m effect, where the base monad m is the current monad.

Derivs (HoistOptionC m) = HoistOption m ': Derivs m
Prims  (HoistOptionC m) = HoistOption m ': Prims m

hoistOptionToFinal :: (MonadBaseControl b m, Carrier m) => HoistOptionToFinalC b m a -> m a Source #

Runs a HoistOption b effect, where the base monad b is the final base monad.

Derivs (HoistOptionToFinalC b m) = HoistOption b ': Derivs m
Prims  (HoistOptionToFinalC b m) = HoistOption b ': Prims m

Threading utilities

threadOptionalViaBaseControl :: forall s t m a. (Functor s, Monad m, Monad (t m), ThreadsEff t (BaseControl m)) => (forall x. Optional s m x -> m x) -> Optional s (t m) a -> t m a Source #

A valid definition of threadEff for a ThreadsEff t (Optional s) instance, given that t threads BaseControl b for any b.

Combinators for Algebras

powerAlgHoistOption :: forall m p a. Algebra' p m a -> Algebra' (HoistOption m ': p) m a Source #

Strengthen an Algebra p m by adding a HoistOption m handler

powerAlgHoistOptionFinal :: forall b m p a. MonadBaseControl b m => Algebra' p m a -> Algebra' (HoistOption b ': p) m a Source #

Strengthen an Algebra p m by adding a HoistOption b handler, where b is the final base monad.

Carriers

data HoistOptionC m a Source #

Instances

Instances details
MonadTrans (HoistOptionC :: (Type -> Type) -> Type -> Type) Source # 
Instance details

Defined in Control.Effect.Internal.Optional

Methods

lift :: Monad m => m a -> HoistOptionC m a #

MonadTransControl (HoistOptionC :: (Type -> Type) -> Type -> Type) Source # 
Instance details

Defined in Control.Effect.Internal.Optional

Associated Types

type StT HoistOptionC a #

Methods

liftWith :: Monad m => (Run HoistOptionC -> m a) -> HoistOptionC m a #

restoreT :: Monad m => m (StT HoistOptionC a) -> HoistOptionC m a #

Monad m => Monad (HoistOptionC m) Source # 
Instance details

Defined in Control.Effect.Internal.Optional

Methods

(>>=) :: HoistOptionC m a -> (a -> HoistOptionC m b) -> HoistOptionC m b #

(>>) :: HoistOptionC m a -> HoistOptionC m b -> HoistOptionC m b #

return :: a -> HoistOptionC m a #

Functor m => Functor (HoistOptionC m) Source # 
Instance details

Defined in Control.Effect.Internal.Optional

Methods

fmap :: (a -> b) -> HoistOptionC m a -> HoistOptionC m b #

(<$) :: a -> HoistOptionC m b -> HoistOptionC m a #

MonadFix m => MonadFix (HoistOptionC m) Source # 
Instance details

Defined in Control.Effect.Internal.Optional

Methods

mfix :: (a -> HoistOptionC m a) -> HoistOptionC m a #

MonadFail m => MonadFail (HoistOptionC m) Source # 
Instance details

Defined in Control.Effect.Internal.Optional

Methods

fail :: String -> HoistOptionC m a #

Applicative m => Applicative (HoistOptionC m) Source # 
Instance details

Defined in Control.Effect.Internal.Optional

Methods

pure :: a -> HoistOptionC m a #

(<*>) :: HoistOptionC m (a -> b) -> HoistOptionC m a -> HoistOptionC m b #

liftA2 :: (a -> b -> c) -> HoistOptionC m a -> HoistOptionC m b -> HoistOptionC m c #

(*>) :: HoistOptionC m a -> HoistOptionC m b -> HoistOptionC m b #

(<*) :: HoistOptionC m a -> HoistOptionC m b -> HoistOptionC m a #

MonadIO m => MonadIO (HoistOptionC m) Source # 
Instance details

Defined in Control.Effect.Internal.Optional

Methods

liftIO :: IO a -> HoistOptionC m a #

Alternative m => Alternative (HoistOptionC m) Source # 
Instance details

Defined in Control.Effect.Internal.Optional

Methods

empty :: HoistOptionC m a #

(<|>) :: HoistOptionC m a -> HoistOptionC m a -> HoistOptionC m a #

some :: HoistOptionC m a -> HoistOptionC m [a] #

many :: HoistOptionC m a -> HoistOptionC m [a] #

MonadPlus m => MonadPlus (HoistOptionC m) Source # 
Instance details

Defined in Control.Effect.Internal.Optional

Methods

mzero :: HoistOptionC m a #

mplus :: HoistOptionC m a -> HoistOptionC m a -> HoistOptionC m a #

MonadThrow m => MonadThrow (HoistOptionC m) Source # 
Instance details

Defined in Control.Effect.Internal.Optional

Methods

throwM :: Exception e => e -> HoistOptionC m a #

MonadCatch m => MonadCatch (HoistOptionC m) Source # 
Instance details

Defined in Control.Effect.Internal.Optional

Methods

catch :: Exception e => HoistOptionC m a -> (e -> HoistOptionC m a) -> HoistOptionC m a #

MonadMask m => MonadMask (HoistOptionC m) Source # 
Instance details

Defined in Control.Effect.Internal.Optional

Methods

mask :: ((forall a. HoistOptionC m a -> HoistOptionC m a) -> HoistOptionC m b) -> HoistOptionC m b #

uninterruptibleMask :: ((forall a. HoistOptionC m a -> HoistOptionC m a) -> HoistOptionC m b) -> HoistOptionC m b #

generalBracket :: HoistOptionC m a -> (a -> ExitCase b -> HoistOptionC m c) -> (a -> HoistOptionC m b) -> HoistOptionC m (b, c) #

Carrier m => Carrier (HoistOptionC m) Source # 
Instance details

Defined in Control.Effect.Internal.Optional

Associated Types

type Derivs (HoistOptionC m) :: [Effect] Source #

type Prims (HoistOptionC m) :: [Effect] Source #

type StT (HoistOptionC :: (Type -> Type) -> Type -> Type) a Source # 
Instance details

Defined in Control.Effect.Internal.Optional

type StT (HoistOptionC :: (Type -> Type) -> Type -> Type) a = StT (IdentityT :: (Type -> Type) -> Type -> Type) a
type Derivs (HoistOptionC m) Source # 
Instance details

Defined in Control.Effect.Internal.Optional

type Prims (HoistOptionC m) Source # 
Instance details

Defined in Control.Effect.Internal.Optional

type HoistOptionToFinalC b = InterpretPrimC HoistOptionToFinalH (HoistOption b) Source #