capability-0.3.0.0: Extensional capabilities and deriving combinators

Safe HaskellNone
LanguageHaskell2010

Capability.Source

Contents

Description

Defines a capability for computations that consume a stream of values as part of their execution.

Programs comsuming streams of data are common. Examples: rolling up input events. Sources are similar to Python generators.

This can be thought of as a reader capability where there's no guarantee that one reads the same value each time.

The HasSource capability enables separating the logic responsible for emitting events from that responsible for collecting or handling them. The name is because a source is needed to produce the locally consumed stream.

Synopsis

Relational capability

class Monad m => HasSource (tag :: k) (a :: *) (m :: * -> *) | tag m -> a where Source #

Sourcing capability.

An instance does not need to fulfill any additional laws besides the monad laws.

Methods

await_ :: Proxy# tag -> m a Source #

For technical reasons, this method needs an extra proxy argument. You only need it if you are defining new instances of HasSource. Otherwise, you will want to use await. See await for more documentation.

Instances
(MutableRef ref, RefElement ref ~ s, HasSource tag ref m, PrimMonad m, PrimState m ~ MCState ref) => HasSource (tag :: k) s (ReaderRef m) Source # 
Instance details

Defined in Capability.Source.Internal.Strategies

Methods

await_ :: Proxy# tag -> ReaderRef m s Source #

MonadState s m => HasSource (tag :: k) s (MonadState m) Source # 
Instance details

Defined in Capability.Source.Internal.Strategies

Methods

await_ :: Proxy# tag -> MonadState m s Source #

(HasSource tag r m, MonadTrans t, Monad (t m)) => HasSource (tag :: k) r (Lift (t m)) Source # 
Instance details

Defined in Capability.Source.Internal.Strategies

Methods

await_ :: Proxy# tag -> Lift (t m) r Source #

MonadReader r m => HasSource (tag :: k) r (MonadReader m) Source # 
Instance details

Defined in Capability.Source.Internal.Strategies

Methods

await_ :: Proxy# tag -> MonadReader m r Source #

HasState tag r m => HasSource (tag :: k) r (ReadStatePure m) Source # 
Instance details

Defined in Capability.Source.Internal.Strategies

Methods

await_ :: Proxy# tag -> ReadStatePure m r Source #

(HasState tag r m, MonadMask m) => HasSource (tag :: k) r (ReadState m) Source # 
Instance details

Defined in Capability.Source.Internal.Strategies

Methods

await_ :: Proxy# tag -> ReadState m r Source #

(HasSource tag (IORef s) m, MonadIO m) => HasSource (tag :: k) s (ReaderIORef m) Source # 
Instance details

Defined in Capability.Source.Internal.Strategies

Methods

await_ :: Proxy# tag -> ReaderIORef m s Source #

(Coercible from to, HasSource tag from m, forall x y. Coercible x y => Coercible (m x) (m y)) => HasSource (tag :: k) to (Coerce to m) Source # 
Instance details

Defined in Capability.Source.Internal.Strategies

Methods

await_ :: Proxy# tag -> Coerce to m to Source #

HasSource oldtag r m => HasSource (newtag :: k1) r (Rename oldtag m) Source #

Rename the tag.

Instance details

Defined in Capability.Source.Internal.Strategies

Methods

await_ :: Proxy# newtag -> Rename oldtag m r Source #

(forall x. Coercible (m x) (t2 (t1 m) x), Monad m, HasSource tag r (t2 (t1 m))) => HasSource (tag :: k) r ((t2 :.: t1) m) Source # 
Instance details

Defined in Capability.Source.Internal.Strategies

Methods

await_ :: Proxy# tag -> (t2 :.: t1) m r Source #

(tag ~ pos, HasPosition' pos struct v, HasSource oldtag struct m) => HasSource (tag :: Nat) v (Pos pos oldtag m) Source # 
Instance details

Defined in Capability.Source.Internal.Strategies

Methods

await_ :: Proxy# tag -> Pos pos oldtag m v Source #

(tag ~ field, HasField' field record v, HasSource oldtag record m) => HasSource (tag :: Symbol) v (Field field oldtag m) Source # 
Instance details

Defined in Capability.Source.Internal.Strategies

Methods

await_ :: Proxy# tag -> Field field oldtag m v Source #

await :: forall tag a m. HasSource tag a m => m a Source #

await @tag a takes a from the source capability tag.

awaits :: forall tag r m a. HasSource tag r m => (r -> a) -> m a Source #

awaits @tag retrieves the image by f of the environment of the reader capability tag.

awaits @tag f = f <$> await @tag

Functional capability

type HasSource' (tag :: k) = HasSource tag (TypeOf k tag) Source #

Type synonym using the TypeOf type family to specify HasSource constraints without having to specify the type associated to a tag.

type family TypeOf k (s :: k) :: * Source #

Type family associating a tag to the corresponding type. It is intended to simplify constraint declarations, by removing the need to redundantly specify the type associated to a tag.

It is poly-kinded, which allows users to define their own kind of tags. Standard haskell types can also be used as tags by specifying the * kind when defining the type family instance.

Defining TypeOf instances for Symbols (typelevel string literals) is discouraged. Since symbols all belong to the same global namespace, such instances could conflict with others defined in external libraries. More generally, as for typeclasses, TypeOf instances should always be defined in the same module as the tag type to prevent issues due to orphan instances.

Example:

    import Capability.Reader

    data Foo
    data Bar
    type instance TypeOf * Foo = Int
    type instance TypeOf * Bar = String

    -- Same as: foo :: HasReader Foo Int M => …
    foo :: HasReader' Foo m => …
    foo = …

Strategies

newtype MonadReader (m :: * -> *) (a :: *) Source #

Derive HasSource from m's MonadReader instance.

Constructors

MonadReader (m a) 
Instances
MonadReader r m => HasSource (tag :: k) r (MonadReader m) Source # 
Instance details

Defined in Capability.Source.Internal.Strategies

Methods

await_ :: Proxy# tag -> MonadReader m r Source #

MonadReader r m => HasReader (tag :: k) r (MonadReader m) Source # 
Instance details

Defined in Capability.Reader.Internal.Strategies

Methods

local_ :: Proxy# tag -> (r -> r) -> MonadReader m a -> MonadReader m a Source #

reader_ :: Proxy# tag -> (r -> a) -> MonadReader m a Source #

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

Defined in Capability.Source.Internal.Strategies

Methods

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

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

return :: a -> MonadReader m a #

fail :: String -> MonadReader m a #

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

Defined in Capability.Source.Internal.Strategies

Methods

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

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

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

Defined in Capability.Source.Internal.Strategies

Methods

pure :: a -> MonadReader m a #

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

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

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

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

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

Defined in Capability.Source.Internal.Strategies

Methods

liftIO :: IO a -> MonadReader m a #

PrimMonad m => PrimMonad (MonadReader m) Source # 
Instance details

Defined in Capability.Source.Internal.Strategies

Associated Types

type PrimState (MonadReader m) :: Type #

Methods

primitive :: (State# (PrimState (MonadReader m)) -> (#State# (PrimState (MonadReader m)), a#)) -> MonadReader m a #

type PrimState (MonadReader m) Source # 
Instance details

Defined in Capability.Source.Internal.Strategies

newtype ReadStatePure (m :: * -> *) (a :: *) Source #

Convert a pure state monad into a reader monad.

Pure meaning that the monad stack does not allow catching exceptions. Otherwise, an exception occurring in the action passed to local could cause the context to remain modified outside of the call to local. E.g.

local @tag (const r') (throw MyException)
`catch` \MyException -> ask @tag

returns r' instead of the previous value.

Note, that no MonadIO instance is provided, as this would allow catching exceptions.

See ReadState.

Constructors

ReadStatePure (m a) 
Instances
HasState tag r m => HasSource (tag :: k) r (ReadStatePure m) Source # 
Instance details

Defined in Capability.Source.Internal.Strategies

Methods

await_ :: Proxy# tag -> ReadStatePure m r Source #

HasState tag r m => HasReader (tag :: k) r (ReadStatePure m) Source # 
Instance details

Defined in Capability.Reader.Internal.Strategies

Methods

local_ :: Proxy# tag -> (r -> r) -> ReadStatePure m a -> ReadStatePure m a Source #

reader_ :: Proxy# tag -> (r -> a) -> ReadStatePure m a Source #

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

Defined in Capability.Source.Internal.Strategies

Methods

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

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

return :: a -> ReadStatePure m a #

fail :: String -> ReadStatePure m a #

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

Defined in Capability.Source.Internal.Strategies

Methods

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

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

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

Defined in Capability.Source.Internal.Strategies

Methods

pure :: a -> ReadStatePure m a #

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

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

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

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

newtype ReadState (m :: * -> *) (a :: *) Source #

Convert a state monad into a reader monad.

Use this if the monad stack allows catching exceptions.

See ReadStatePure.

Constructors

ReadState (m a) 
Instances
(HasState tag r m, MonadMask m) => HasSource (tag :: k) r (ReadState m) Source # 
Instance details

Defined in Capability.Source.Internal.Strategies

Methods

await_ :: Proxy# tag -> ReadState m r Source #

(HasState tag r m, MonadMask m) => HasReader (tag :: k) r (ReadState m) Source # 
Instance details

Defined in Capability.Reader.Internal.Strategies

Methods

local_ :: Proxy# tag -> (r -> r) -> ReadState m a -> ReadState m a Source #

reader_ :: Proxy# tag -> (r -> a) -> ReadState m a Source #

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

Defined in Capability.Source.Internal.Strategies

Methods

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

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

return :: a -> ReadState m a #

fail :: String -> ReadState m a #

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

Defined in Capability.Source.Internal.Strategies

Methods

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

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

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

Defined in Capability.Source.Internal.Strategies

Methods

pure :: a -> ReadState m a #

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

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

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

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

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

Defined in Capability.Source.Internal.Strategies

Methods

liftIO :: IO a -> ReadState m a #

PrimMonad m => PrimMonad (ReadState m) Source # 
Instance details

Defined in Capability.Source.Internal.Strategies

Associated Types

type PrimState (ReadState m) :: Type #

Methods

primitive :: (State# (PrimState (ReadState m)) -> (#State# (PrimState (ReadState m)), a#)) -> ReadState m a #

type PrimState (ReadState m) Source # 
Instance details

Defined in Capability.Source.Internal.Strategies

newtype MonadState (m :: * -> *) (a :: *) Source #

Derive HasState from m's MonadState instance.

Constructors

MonadState (m a) 
Instances
MonadState s m => HasSink (tag :: k) s (MonadState m) Source # 
Instance details

Defined in Capability.Sink.Internal.Strategies

Methods

yield_ :: Proxy# tag -> s -> MonadState m () Source #

MonadState s m => HasSource (tag :: k) s (MonadState m) Source # 
Instance details

Defined in Capability.Source.Internal.Strategies

Methods

await_ :: Proxy# tag -> MonadState m s Source #

MonadState s m => HasState (tag :: k) s (MonadState m) Source # 
Instance details

Defined in Capability.State.Internal.Strategies

Methods

state_ :: Proxy# tag -> (s -> (a, s)) -> MonadState m a Source #

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

Defined in Capability.State.Internal.Strategies.Common

Methods

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

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

return :: a -> MonadState m a #

fail :: String -> MonadState m a #

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

Defined in Capability.State.Internal.Strategies.Common

Methods

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

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

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

Defined in Capability.State.Internal.Strategies.Common

Methods

pure :: a -> MonadState m a #

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

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

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

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

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

Defined in Capability.State.Internal.Strategies.Common

Methods

liftIO :: IO a -> MonadState m a #

PrimMonad m => PrimMonad (MonadState m) Source # 
Instance details

Defined in Capability.State.Internal.Strategies.Common

Associated Types

type PrimState (MonadState m) :: Type #

Methods

primitive :: (State# (PrimState (MonadState m)) -> (#State# (PrimState (MonadState m)), a#)) -> MonadState m a #

type PrimState (MonadState m) Source # 
Instance details

Defined in Capability.State.Internal.Strategies.Common

newtype ReaderIORef m a Source #

Derive a state monad from a reader over an IORef.

Example:

newtype MyState m a = MyState (ReaderT (IORef Int) m a)
  deriving (Functor, Applicative, Monad)
  deriving HasState "foo" Int via
    ReaderIORef (MonadReader (ReaderT (IORef Int) m))

See ReaderRef for a more generic strategy.

Constructors

ReaderIORef (m a) 
Instances
(HasSource tag (IORef s) m, MonadIO m) => HasSink (tag :: k) s (ReaderIORef m) Source # 
Instance details

Defined in Capability.Sink.Internal.Strategies

Methods

yield_ :: Proxy# tag -> s -> ReaderIORef m () Source #

(HasSource tag (IORef s) m, MonadIO m) => HasSource (tag :: k) s (ReaderIORef m) Source # 
Instance details

Defined in Capability.Source.Internal.Strategies

Methods

await_ :: Proxy# tag -> ReaderIORef m s Source #

(HasReader tag (IORef s) m, MonadIO m) => HasState (tag :: k) s (ReaderIORef m) Source # 
Instance details

Defined in Capability.State.Internal.Strategies

Methods

state_ :: Proxy# tag -> (s -> (a, s)) -> ReaderIORef m a Source #

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

Defined in Capability.State.Internal.Strategies.Common

Methods

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

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

return :: a -> ReaderIORef m a #

fail :: String -> ReaderIORef m a #

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

Defined in Capability.State.Internal.Strategies.Common

Methods

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

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

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

Defined in Capability.State.Internal.Strategies.Common

Methods

pure :: a -> ReaderIORef m a #

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

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

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

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

newtype ReaderRef m (a :: *) Source #

Derive a state monad from a reader over a mutable reference.

Mutable references are available in a PrimMonad. The corresponding PrimState has to match the MCState of the reference. This constraint makes a stand-alone deriving clause necessary.

Example:

newtype MyState m a = MyState (ReaderT (IORef Int) m a)
  deriving (Functor, Applicative, Monad)
deriving via ReaderRef (MonadReader (ReaderT (IORef Int) m))
  instance (PrimMonad m, PrimState m ~ PrimState IO)
  => HasState "foo" Int (MyState m)

See ReaderIORef for a specialized version over IORef.

Constructors

ReaderRef (m a) 
Instances
(MutableRef ref, RefElement ref ~ s, HasSource tag ref m, PrimMonad m, PrimState m ~ MCState ref) => HasSink (tag :: k) s (ReaderRef m) Source # 
Instance details

Defined in Capability.Sink.Internal.Strategies

Methods

yield_ :: Proxy# tag -> s -> ReaderRef m () Source #

(MutableRef ref, RefElement ref ~ s, HasSource tag ref m, PrimMonad m, PrimState m ~ MCState ref) => HasSource (tag :: k) s (ReaderRef m) Source # 
Instance details

Defined in Capability.Source.Internal.Strategies

Methods

await_ :: Proxy# tag -> ReaderRef m s Source #

(MutableRef ref, RefElement ref ~ s, HasReader tag ref m, PrimMonad m, PrimState m ~ MCState ref) => HasState (tag :: k) s (ReaderRef m) Source # 
Instance details

Defined in Capability.State.Internal.Strategies

Methods

state_ :: Proxy# tag -> (s -> (a, s)) -> ReaderRef m a Source #

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

Defined in Capability.State.Internal.Strategies.Common

Methods

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

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

return :: a -> ReaderRef m a #

fail :: String -> ReaderRef m a #

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

Defined in Capability.State.Internal.Strategies.Common

Methods

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

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

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

Defined in Capability.State.Internal.Strategies.Common

Methods

pure :: a -> ReaderRef m a #

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

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

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

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

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

Defined in Capability.State.Internal.Strategies.Common

Methods

liftIO :: IO a -> ReaderRef m a #

PrimMonad m => PrimMonad (ReaderRef m) Source # 
Instance details

Defined in Capability.State.Internal.Strategies.Common

Associated Types

type PrimState (ReaderRef m) :: Type #

Methods

primitive :: (State# (PrimState (ReaderRef m)) -> (#State# (PrimState (ReaderRef m)), a#)) -> ReaderRef m a #

type PrimState (ReaderRef m) Source # 
Instance details

Defined in Capability.State.Internal.Strategies.Common

Modifiers