State capability

An instance should fulfill the following laws. At this point these laws are not definitive, see https://github.com/haskell/mtl/issues/5.

get @t >>= \s1 -> get @t >>= \s2 -> pure (s1, s2) = get @t >>= \s -> pure (s, s)

get @t >>= \_ -> put @t s = put @t s

put @t s1 >> put @t s2 = put @t s2

put @t s >> get @t = put @t s >> pure s

state @t f = get @t >>= \s -> let (a, s') = f s in put @t s' >> pure a

get @tag retrieve the current state of the state capability tag.

put @tag s replace the current state of the state capability tag with s.

state @tag f lifts a pure state computation f to a monadic action in an arbitrary monad m with capability HasState.

Given the current state s of the state capability tag and (a, s') = f s, update the state to s' and return a.

modify @tag f given the current state s of the state capability tag and s' = f s, updates the state of the capability tag to s'.

Same as modify but strict in the new state.

gets @tag f retrieves the image, by f of the current state of the state capability tag.

gets @tag f = f <$> get @tag

Execute the given state action on a sub-component of the current state as defined by the given transformer t. The set of retained capabilities must be passed as @cs. If no capabilities are required, None can be used.

Examples:

foo :: HasState "foo" Int m => m ()
zoom @"foo" @(Field "foo" "foobar") @None foo
  :: (HasField' "foobar" record Int, HasState "foobar" record m) => m ()

zoom @"foo" @(Field "foo" "foobar") @('[MonadIO]) bar
  :: ( HasField' "foobar" record Int, HasState "foobar" record m
     , MonadIO m) => m ()

foo :: HasState "foo" Int m => m ()
bar :: (MonadIO m, HasState "foo" Int m) => m ()

Note: the HasField' constraint comes from the generic-lens package.

This function is experimental and subject to change. See https://github.com/tweag/capability/issues/46.

Reified tag capability m

Defines the dictionary type for the methods of capability under tag in the monad m. Refer to interpret_ for an example use-case.

For example, the HasSink capability has the method yield :: a -> m (). The corresponding dictionary type is defined as follows.

>>> :{
  data instance Reified tag (HasSink tag a) m =
    ReifiedSink { _yield :: forall a. a -> m () }
  :}

Superclass dictionaries are represented as nested records. For example, the HasState capability has the superclasses HasSource and HasSink and the method state :: (s -> (a, s)) -> m a. The corresponding dictionary type is defined as follows.

>>> :{
  data instance Reified tag (HasState tag s) m =
    ReifiedState
      { _stateSource :: Reified tag (HasSource tag s) m,
        _stateSink :: Reified tag (HasSink tag s) m,
        _state :: forall a. (s -> (a, s)) -> m a
      }
  :}

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

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 = …

Derive HasState from m's MonadState instance.

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.

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.