Capability.Source

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.

Relational capability

class Monad m => HasSource (tag :: k) (a :: Type) (m :: Type -> Type) | tag m -> a where

Sourcing capability.

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

Methods

await_ :: Proxy# tag -> m a

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)

Defined in Capability.Source.Internal.Strategies

Methods

await_ :: Proxy# tag -> ReaderRef m s

MonadState s m => HasSource (tag :: k) s (MonadState m)

Defined in Capability.Source.Internal.Strategies

Methods

await_ :: Proxy# tag -> MonadState m s

(HasSource tag r m, MonadTrans t, Monad (t m)) => HasSource (tag :: k) r (Lift (t m))

Defined in Capability.Source.Internal.Strategies

Methods

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

MonadReader r m => HasSource (tag :: k) r (MonadReader m)

Defined in Capability.Source.Internal.Strategies

Methods

await_ :: Proxy# tag -> MonadReader m r

HasState tag r m => HasSource (tag :: k) r (ReadStatePure m)

Defined in Capability.Source.Internal.Strategies

Methods

await_ :: Proxy# tag -> ReadStatePure m r

(HasState tag r m, MonadMask m) => HasSource (tag :: k) r (ReadState m)

Defined in Capability.Source.Internal.Strategies

Methods

await_ :: Proxy# tag -> ReadState m r

(HasSource tag (IORef s) m, MonadIO m) => HasSource (tag :: k) s (ReaderIORef m)

Defined in Capability.Source.Internal.Strategies

Methods

await_ :: Proxy# tag -> ReaderIORef m s

(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)

Defined in Capability.Source.Internal.Strategies

Methods

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

(Monad m, Reifies s (Reified tag (HasSource tag a) m)) => HasSource (tag :: k) a (Reflected s (HasSource tag a) m)

Defined in Capability.Source.Internal.Class

Methods

await_ :: Proxy# tag -> Reflected s (HasSource tag a) m a

(Monad m, Reifies s (Reified tag (HasReader tag r) m)) => HasSource (tag :: k) r (Reflected s (HasReader tag r) m)

Defined in Capability.Reader.Internal.Class

Methods

await_ :: Proxy# tag -> Reflected s (HasReader tag r) m r

(Monad m, Reifies s' (Reified tag (HasState tag s) m)) => HasSource (tag :: k) s (Reflected s' (HasState tag s) m)

Defined in Capability.State.Internal.Class

Methods

await_ :: Proxy# tag -> Reflected s' (HasState tag s) m s

HasSource oldtag r m => HasSource (newtag :: k2) r (Rename oldtag m)

Rename the tag.

Defined in Capability.Source.Internal.Strategies

Methods

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

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

Defined in Capability.Source.Internal.Strategies

Methods

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

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

Defined in Capability.Source.Internal.Strategies

Methods

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

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

Defined in Capability.Source.Internal.Strategies

Methods

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

data Reified (tag :: k) (HasSource tag a) m

Defined in Capability.Source.Internal.Class

data Reified (tag :: k) (HasSource tag a) m = ReifiedSource {

• _await :: m a

}

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

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

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

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)

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) :: Type

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 Type 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 Type Foo = Int
    type instance TypeOf Type Bar = String

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

Strategies

newtype MonadReader (m :: Type -> Type) (a :: Type)

Derive HasSource from m's MonadReader instance.

Constructors

MonadReader (m a)

Instances

MonadReader r m => HasSource (tag :: k) r (MonadReader m)

Defined in Capability.Source.Internal.Strategies

Methods

await_ :: Proxy# tag -> MonadReader m r

MonadReader r m => HasReader (tag :: k) r (MonadReader m)

Defined in Capability.Reader.Internal.Strategies

Methods

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

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

Monad m => Monad (MonadReader m)

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

Functor m => Functor (MonadReader m)

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)

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)

Defined in Capability.Source.Internal.Strategies

Methods

liftIO :: IO a -> MonadReader m a

PrimMonad m => PrimMonad (MonadReader m)

Defined in Capability.Source.Internal.Strategies

Associated Types

type PrimState (MonadReader m)

Methods

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

type PrimState (MonadReader m)

Defined in Capability.Source.Internal.Strategies

type PrimState (MonadReader m) = PrimState m

newtype ReadStatePure (m :: Type -> Type) (a :: Type)

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)

Defined in Capability.Source.Internal.Strategies

Methods

await_ :: Proxy# tag -> ReadStatePure m r

HasState tag r m => HasReader (tag :: k) r (ReadStatePure m)

Defined in Capability.Reader.Internal.Strategies

Methods

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

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

Monad m => Monad (ReadStatePure m)

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

Functor m => Functor (ReadStatePure m)

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)

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 :: Type -> Type) (a :: Type)

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)

Defined in Capability.Source.Internal.Strategies

Methods

await_ :: Proxy# tag -> ReadState m r

(HasState tag r m, MonadMask m) => HasReader (tag :: k) r (ReadState m)

Defined in Capability.Reader.Internal.Strategies

Methods

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

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

Monad m => Monad (ReadState m)

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

Functor m => Functor (ReadState m)

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)

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)

Defined in Capability.Source.Internal.Strategies

Methods

liftIO :: IO a -> ReadState m a

PrimMonad m => PrimMonad (ReadState m)

Defined in Capability.Source.Internal.Strategies

Associated Types

type PrimState (ReadState m)

Methods

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

type PrimState (ReadState m)

Defined in Capability.Source.Internal.Strategies

type PrimState (ReadState m) = PrimState m

newtype MonadState (m :: Type -> Type) (a :: Type)

Derive HasState from m's MonadState instance.

Constructors

MonadState (m a)

Instances

MonadState s m => HasSink (tag :: k) s (MonadState m)

Defined in Capability.Sink.Internal.Strategies

Methods

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

MonadState s m => HasSource (tag :: k) s (MonadState m)

Defined in Capability.Source.Internal.Strategies

Methods

await_ :: Proxy# tag -> MonadState m s

MonadState s m => HasState (tag :: k) s (MonadState m)

Defined in Capability.State.Internal.Strategies

Methods

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

Monad m => Monad (MonadState m)

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

Functor m => Functor (MonadState m)

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)

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)

Defined in Capability.State.Internal.Strategies.Common

Methods

liftIO :: IO a -> MonadState m a

PrimMonad m => PrimMonad (MonadState m)

Defined in Capability.State.Internal.Strategies.Common

Associated Types

type PrimState (MonadState m)

Methods

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

type PrimState (MonadState m)

Defined in Capability.State.Internal.Strategies.Common

type PrimState (MonadState m) = PrimState m

newtype ReaderIORef m a

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)

Defined in Capability.Sink.Internal.Strategies

Methods

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

(HasSource tag (IORef s) m, MonadIO m) => HasSource (tag :: k) s (ReaderIORef m)

Defined in Capability.Source.Internal.Strategies

Methods

await_ :: Proxy# tag -> ReaderIORef m s

(HasReader tag (IORef s) m, MonadIO m) => HasState (tag :: k) s (ReaderIORef m)

Defined in Capability.State.Internal.Strategies

Methods

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

Monad m => Monad (ReaderIORef m)

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

Functor m => Functor (ReaderIORef m)

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)

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 :: Type)

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)

Defined in Capability.Sink.Internal.Strategies

Methods

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

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

Defined in Capability.Source.Internal.Strategies

Methods

await_ :: Proxy# tag -> ReaderRef m s

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

Defined in Capability.State.Internal.Strategies

Methods

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

Monad m => Monad (ReaderRef m)

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

Functor m => Functor (ReaderRef m)

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)

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)

Defined in Capability.State.Internal.Strategies.Common

Methods

liftIO :: IO a -> ReaderRef m a

PrimMonad m => PrimMonad (ReaderRef m)

Defined in Capability.State.Internal.Strategies.Common

Associated Types

type PrimState (ReaderRef m)

Methods

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

type PrimState (ReaderRef m)

Defined in Capability.State.Internal.Strategies.Common

type PrimState (ReaderRef m) = PrimState m

Modifiers

module Capability.Accessors