monad-levels-0.1.0.0: Specific levels of monad transformers

Copyright (c) Ivan Lazar Miljenovic 3-Clause BSD-style Ivan.Miljenovic@gmail.com Trustworthy Haskell2010

Control.Monad.Levels.Constraints

Description

Synopsis

# Constraints in the monad stack

liftSat :: forall c m a. SatisfyConstraint c m => Proxy c -> SatMonad c m a -> m a Source

Lift a value of the satisfying monad to the top of the tower.

lowerSat :: forall c m a f. SatisfyConstraintF c m a f => Proxy c -> Proxy f -> Proxy m -> Proxy a -> SatFunction c f m a -> VarFunction f m a Source

Lower a function from the top of the monad tower down to the satisfying monad in which it can be applied.

lowerSat' :: forall c m a f. (SatisfyConstraint c m, VariadicFunction f) => Proxy c -> Proxy f -> Proxy m -> Proxy a -> (() :- CanLower f m a) -> SatFunction c f m a -> VarFunction f m a Source

A variant of `lowerSat` for when `CanLower f m a ~ ()`.

lowerFunction :: forall c m a. SatisfyConstraint c m => Proxy c -> (SatMonadValue c m a -> SatMonadValue c m a) -> m a -> m a Source

A specialised instance of `lowerSat` where a simple function of type `m a -> m a` is lowered to the satisfying monad.

type SatisfyConstraint c m = (SatisfyConstraint_ (SatDepth c m) c m, c (SatMonad c m), BaseMonad (SatMonad c m) ~ BaseMonad m) Source

For a specified constraint `c` and `MonadTower` `m`, `SatisfyConstraint c m` specifies that it is possible to reach a monad in the tower that specifies the constraint.

type SatisfyConstraintF c m a f = (SatisfyConstraint c m, VariadicFunction f, CanLowerFunc f c m a) Source

An extension of `SatisfyConstraint` that also ensures that any additional constraints needed to satisfy a `VariadicFunction` `f` to achieve an end result based upon the type `m a` are met.

type SatMonad c m = SatMonad_ (SatDepth c m) c m Source

The Monad in the tower that satisfies the provided constraint.

type SatMonadValue c m a = SatMonad_ (SatDepth c m) c m (SatValue_ (SatDepth c m) c m a) Source

Converts `m a` into what the value in the monadic stack is where the monad satisfies the provided constraint.

type CanLowerFunc f c m a = CanLowerFunc_ f (SatDepth c m) c m a Source

Any additional constraints that may be needed for a specified `VariadicFunction` to be valid as it is lowered to the satisfying monad.

This typically matters only if `ValueOnly` or `MonadicOther` are used.

type SatFunction c f m a = VarFunctionSat f (SatDepth c m) c m a Source

The type of the `VariadicFunction` `f` when the provided constraint is satisfied.

class ValidConstraint c Source

When considering whether a particular monad within a `MonadTower` stack satisfies a constraint, we need to be able to determine this at the type level.

This is achieved with the `ConstraintSatisfied` associated type: it should be equated to a closed type family with the result being `True` for all monads for which the constraint is satisfied and `False` for all others.

(This is defined as a type class rather than just a type family so that we can explicitly state that this needs to be defined.)

Associated Types

type ConstraintSatisfied c m :: Bool Source

Instances

 ValidConstraint IsBaseMonad ValidConstraint IsCont ValidConstraint (IsTransformer t) ValidConstraint (IsError e) ValidConstraint (IsReader r) ValidConstraint (IsState s) Monoid w => ValidConstraint (IsWriter w) Monoid w => ValidConstraint (IsRWS r w s)

class (ValidConstraint c, MonadLevel m) => ConstraintPassThrough c m b Source

Indicates whether a specified constraint is allowed to pass through a particular level.

(It may not be recognisable in Haddock documentation, but the `b` parameter is of kind `Bool` using the `DataKinds` extension).

By default, for all monad levels this is set to the value of `DefaultAllowConstraints` for all constraints, with the exception of `IsBaseMonad` for which it is set to `True`.

Instances of this class can - and should when appropriate - be overlapped/overriden.

Instances

 (ValidConstraint c, MonadLevel m, (~) Bool (DefaultAllowConstraints m) b) => ConstraintPassThrough c m b MonadLevel m => ConstraintPassThrough IsBaseMonad m True MonadTower m => ConstraintPassThrough IsCont (ListT m) True MonadLevel m => ConstraintPassThrough (IsTransformer (ExceptT e)) (ListT m) True MonadLevel m => ConstraintPassThrough (IsTransformer (StateT s)) (ListT m) True MonadLevel m => ConstraintPassThrough (IsTransformer (StateT s)) (ListT m) True MonadLevel m => ConstraintPassThrough (IsTransformer (ReaderT r)) (ListT m) True MonadLevel m => ConstraintPassThrough (IsTransformer (ContT r)) (ListT m) True MonadTower m => ConstraintPassThrough (IsError e) (ListT m) True MonadTower m => ConstraintPassThrough (IsReader r) (ListT m) True MonadTower m => ConstraintPassThrough (IsState s) (ListT m) True MonadLevel m => ConstraintPassThrough (IsTransformer (StateT s)) (ContT r m) True MonadLevel m => ConstraintPassThrough (IsTransformer (StateT s)) (ContT r m) True MonadLevel m => ConstraintPassThrough (IsTransformer (ReaderT r)) (ContT c m) True MonadTower m => ConstraintPassThrough (IsReader r) (ContT c m) True MonadTower m => ConstraintPassThrough (IsState s) (ContT r m) True

## Internal types and classes

class (ValidConstraint c, MonadTower m) => SatisfyConstraint_ n c m Source

Inductively find the "floor" in the `MonadTower` where the specified constraint is satisfied.

This class is only exported for documentation purposes: no other instances are possible, and most of the internals are not safe to use outside of this module.

You should use `SatisfyConstraint` instead of this in your constraints.

Associated Types

type SatMonad_ n c m :: * -> * Source

The monad in the stack that satisfies the constraint.

type SatValue_ n c m a Source

The value in the stack within the monad that satisfies the constraint.

type CanLowerFunc_ f n c m a :: Constraint Source

The extra constraints needed to be able to lower the provided `VariadicFunction` `f` to the satisfying monad.

type SatDepth c m = FindTrue (TrySatisfy c m) Source

Calculate how many levels down is the satisfying monad.

proofInst :: MonadLevel m => Proxy m -> Proxy a -> MonadLevel m :- CanUnwrap m a a Source

Whilst `MonadLevel` requires `CanUnwrap m a a` for all `a`, the type system can't always determine this. This is a helper function to do so.

# Variadic functions

class VariadicLower f => VariadicFunction f Source

A function composed of variadic arguments that produces a value based upon the type `m a`.

Minimal complete definition

validLowerFunc, validSatFunc0, validSatFunc, applyVFn

Associated Types

type VarFunction f m a Source

The function (that produces a value based upon the type `m a`) that this instance corresponds to.

Instances

 WrappableVArg va => VariadicFunction (MkVarFnFrom va) (LowerableVArg va, VariadicFunction vf) => VariadicFunction (Func va vf)

class VariadicLower v Source

Base class for dealing with variadic functions/arguments.

Associated Types

type LowerV v m :: * Source

The type when lowered to the `LowerMonad`. In most cases this will be the same value.

type SatV v n c m :: * Source

The type when applied to the satisfying monad.

type CanLower v m a :: Constraint Source

Any additional constraints needed when lowering `v`.

Instances

 VariadicLower ValueOnly VariadicLower MonadicValue VariadicLower va => VariadicLower (MkVarFnFrom va) VariadicLower (MonadicTuple b) VariadicLower (MonadicOther b) VariadicLower (Const b) (VariadicLower a, VariadicLower b) => VariadicLower (Func a b)

type VarFunctionSat f n c m a = VarFunction (SatV f n c m) (SatMonad_ n c m) (SatValue_ n c m a) Source

The function represented by the `VariadicFunction` when lowered to the satisfying monad.

type MkVarFn v = Func v (MkVarFnFrom MonadicValue) Source

The fundamental way of creating a `VariadicFunction`. ```MkVarFn v``` corresponds to a function of type ```VariadicType v m a -> m a``` for some specified `m a`.

If more than one argument is needed for a function, they can be prepended on using `Func`.

data MkVarFnFrom va Source

The result of a `VariadicFunction`. This can't be used on its own, and needs to have at least one `Func` attached to it.

Instances

 WrappableVArg va => VariadicFunction (MkVarFnFrom va) VariadicLower va => VariadicLower (MkVarFnFrom va) type LowerV (MkVarFnFrom va) m = MkVarFnFrom (LowerV va m) type VarFunction (MkVarFnFrom va) m a = VariadicType va m a type CanLower (MkVarFnFrom va) m a = CanLower va m a type SatV (MkVarFnFrom va) n c m = MkVarFnFrom (SatV va n c m)

data Func v1 v2 Source

Represents the function `v1 -> v2`.

Instances

 (LowerableVArg va, VariadicFunction vf) => VariadicFunction (Func va vf) (LowerableVArg va, LiftableVArg vb) => LiftableVArg (Func va vb) (LiftableVArg va, LowerableVArg vb) => LowerableVArg (Func va vb) (VariadicArg va, VariadicArg vb) => VariadicArg (Func va vb) (VariadicLower a, VariadicLower b) => VariadicLower (Func a b) type LowerV (Func va vb) m = Func (LowerV va m) (LowerV vb m) type VarFunction (Func va vf) m a = VariadicType va m a -> VarFunction vf m a type VariadicType (Func va vb) m a = VariadicType va m a -> VariadicType vb m a type CanLower (Func va vb) m a = (CanLower va m a, CanLower vb m a) type SatV (Func va vb) n c m = Func (SatV va n c m) (SatV vb n c m)

## Variadic arguments

class VariadicLower v => VariadicArg v Source

Class representing arguments/parameters for lower-able variadic functions.

When considering a function with an end result based upon `m a`, the following argument types are available:

`ValueOnly`
corresponds to `a`.
`Const b`
corresponds to some other type `b`.
`MonadicValue`
corresponds to `m a`.
`MonadicOther b`
corresponds to `m b`.
`MonadicTuple b`
corresponds to `m (a,b)`.
`Func v1 v2`
corresponds to `v1 -> v2`.

Associated Types

type VariadicType v m a Source

The type that the variadic guard corresponds to within the monad `(m a)`.

Instances

 VariadicArg ValueOnly VariadicArg MonadicValue VariadicArg (MonadicTuple b) VariadicArg (MonadicOther b) VariadicArg (Const b) (VariadicArg va, VariadicArg vb) => VariadicArg (Func va vb)

class VariadicArg v => LowerableVArg v Source

Variadic arguments that can be lowered. All `VariadicArg` values are instances of this class.

This actually defines how a variadic argument is lowered down to the `LowerMonad`.

Minimal complete definition

lowerVArg

Instances

 LowerableVArg ValueOnly LowerableVArg MonadicValue Monoid b => LowerableVArg (MonadicTuple b) LowerableVArg (MonadicOther b) LowerableVArg (Const b) (LiftableVArg va, LowerableVArg vb) => LowerableVArg (Func va vb)

class VariadicArg v => LiftableVArg v Source

In contrast to `LowerableVArg`, this class is for `VariadicArg` values that can be lifted from the `LowerMonad`.

This is important for `Func v1 v2` arguments, as to lower a function we need to lift `v1` before applying the function, and then subsequently lower the result.

All instances of `VariadicArg` are instances of this with the exception of `ValueOnly` (as it's not always possible to convert an arbitrary `InnerValue m a` back into an `a`).

Minimal complete definition

liftVArg

Instances

 LiftableVArg MonadicValue LiftableVArg (MonadicTuple b) LiftableVArg (MonadicOther b) LiftableVArg (Const b) (LowerableVArg va, LiftableVArg vb) => LiftableVArg (Func va vb)

class LiftableVArg v => WrappableVArg v Source

Variadic arguments that can be lifted via a call to `wrap`. Only those that have a `VariadicType` that is a monadic value can thus be instances of this class.

Minimal complete definition

wrapVArg

Instances

 WrappableVArg MonadicValue WrappableVArg (MonadicTuple b) WrappableVArg (MonadicOther b)

data ValueOnly Source

This corresponds to `a` when the final result is based upon ```m a```. This requires the extra constraint of `CanAddInternal m`.

Instances

 LowerableVArg ValueOnly VariadicArg ValueOnly VariadicLower ValueOnly type LowerV ValueOnly m = ValueOnly type VariadicType ValueOnly m a = a type CanLower ValueOnly m a = CanAddInternal m type SatV ValueOnly n c m = ValueOnly

data Const b Source

A constant type that does not depend upon the current monadic context. That is, `Const b` corresponds to just `b`. It is kept as-is when lowering through the different levels.

Instances

 LiftableVArg (Const b) LowerableVArg (Const b) VariadicArg (Const b) VariadicLower (Const b) type LowerV (Const b) m = Const b type VariadicType (Const b) m a = b type CanLower (Const b) m a = () type SatV (Const b) n c m = Const b

Corresponds to `m a`.

Instances

 WrappableVArg MonadicValue LiftableVArg MonadicValue LowerableVArg MonadicValue VariadicArg MonadicValue VariadicLower MonadicValue type LowerV MonadicValue m = MonadicValue type VariadicType MonadicValue m a = m a type CanLower MonadicValue m a = () type SatV MonadicValue n c m = MonadicValue

data MonadicOther b Source

Corresponds to `m b`, where the final result is based upon `m a`. This requires the extra constraint of `CanUnwrap m a b`.

Instances

 WrappableVArg (MonadicOther b) LiftableVArg (MonadicOther b) LowerableVArg (MonadicOther b) VariadicArg (MonadicOther b) VariadicLower (MonadicOther b) type LowerV (MonadicOther b) m = MonadicOther (InnerValue m b) type VariadicType (MonadicOther b) m a = m b type CanLower (MonadicOther b) m a = CanUnwrap m a b type SatV (MonadicOther b) n c m = MonadicOther (SatValue_ n c m b)

data MonadicTuple b Source

Corresponds to `m (a,b)`. This requires the extra constraints of `CanAddInternal m` and `AllowOtherValues m ~ True` (This is used instead of `CanUnwrap` as a simplification).

Instances

 WrappableVArg (MonadicTuple b) LiftableVArg (MonadicTuple b) Monoid b => LowerableVArg (MonadicTuple b) VariadicArg (MonadicTuple b) VariadicLower (MonadicTuple b) type LowerV (MonadicTuple b) m = MonadicTuple b type VariadicType (MonadicTuple b) m a = m (a, b) type CanLower (MonadicTuple b) m a = (CanGetInternal m, (~) Bool (AllowOtherValues m) True) type SatV (MonadicTuple b) n c m = MonadicTuple b

# Re-exported for convenience

data Proxy t :: k -> *

A concrete, poly-kinded proxy type

Constructors

 Proxy

Instances

 Monad (Proxy *) Functor (Proxy *) Applicative (Proxy *) Bounded (Proxy k s) Enum (Proxy k s) Eq (Proxy k s) Ord (Proxy k s) Read (Proxy k s) Show (Proxy k s) Ix (Proxy k s) Generic (Proxy * t) Monoid (Proxy * s) type Rep (Proxy k t) = D1 D1Proxy (C1 C1_0Proxy U1)