Portability | non-portable (rank-2 polymorphism, MTPCs) |
---|---|

Stability | provisional |

Maintainer | Edward Kmett <ekmett@gmail.com> |

Safe Haskell | None |

Church-encoded free monad transformer.

- newtype FT f m a = FT {
- runFT :: forall r. (a -> m r) -> (f (m r) -> m r) -> m r

- type F f = FT f Identity
- free :: Functor f => (forall r. (a -> r) -> (f r -> r) -> r) -> F f a
- runF :: Functor f => F f a -> forall r. (a -> r) -> (f r -> r) -> r
- toFT :: (Monad m, Functor f) => FreeT f m a -> FT f m a
- fromFT :: (Monad m, Functor f) => FT f m a -> FreeT f m a
- iterT :: (Functor f, Monad m) => (f (m a) -> m a) -> FT f m a -> m a
- iterTM :: (Functor f, Monad m, MonadTrans t, Monad (t m)) => (f (t m a) -> t m a) -> FT f m a -> t m a
- hoistFT :: (Monad m, Monad n, Functor f) => (forall a. m a -> n a) -> FT f m b -> FT f n b
- transFT :: (Monad m, Functor g) => (forall a. f a -> g a) -> FT f m b -> FT g m b
- cutoff :: (Functor f, Monad m) => Integer -> FT f m a -> FT f m (Maybe a)
- improve :: Functor f => (forall m. MonadFree f m => m a) -> Free f a
- fromF :: (Functor f, MonadFree f m) => F f a -> m a
- toF :: Functor f => Free f a -> F f a
- retract :: (Functor f, Monad f) => F f a -> f a
- iter :: Functor f => (f a -> a) -> F f a -> a
- iterM :: (Functor f, Monad m) => (f (m a) -> m a) -> F f a -> m a
- class Monad m => MonadFree f m | m -> f where
- wrap :: f (m a) -> m a

# The free monad transformer

The "free monad transformer" for a functor `f`

(Functor f, MonadError e m) => MonadError e (FT f m) | |

(Functor f, MonadReader r m) => MonadReader r (FT f m) | |

(Functor f, MonadState s m) => MonadState s (FT f m) | |

(Functor f, MonadWriter w m) => MonadWriter w (FT f m) | |

Functor f => MonadFree f (FT f m) | |

MonadTrans (FT f) | |

Monad (FT f m) | |

Functor (FT f m) | |

MonadPlus m => MonadPlus (FT f m) | |

Applicative (FT f m) | |

(Foldable f, Foldable m, Monad m) => Foldable (FT f m) | |

(Monad m, Traversable m, Traversable f) => Traversable (FT f m) | |

Alternative m => Alternative (FT f m) | |

MonadIO m => MonadIO (FT f m) | |

MonadCont m => MonadCont (FT f m) | |

Apply (FT f m) | |

Bind (FT f m) | |

(Functor f, Monad m, Eq (FreeT f m a)) => Eq (FT f m a) | |

(Functor f, Monad m, Ord (FreeT f m a)) => Ord (FT f m a) |

# The free monad

free :: Functor f => (forall r. (a -> r) -> (f r -> r) -> r) -> F f aSource

Wrap a Church-encoding of a "free monad" as the free monad for a functor.

runF :: Functor f => F f a -> forall r. (a -> r) -> (f r -> r) -> rSource

Unwrap the `Free`

monad to obtain it's Church-encoded representation.

# Operations

toFT :: (Monad m, Functor f) => FreeT f m a -> FT f m aSource

Generate a Church-encoded free monad transformer from a `FreeT`

monad
transformer.

fromFT :: (Monad m, Functor f) => FT f m a -> FreeT f m aSource

Convert to a `FreeT`

free monad representation.

iterT :: (Functor f, Monad m) => (f (m a) -> m a) -> FT f m a -> m aSource

Tear down a free monad transformer using iteration.

iterTM :: (Functor f, Monad m, MonadTrans t, Monad (t m)) => (f (t m a) -> t m a) -> FT f m a -> t m aSource

Tear down a free monad transformer using iteration over a transformer.

cutoff :: (Functor f, Monad m) => Integer -> FT f m a -> FT f m (Maybe a)Source

Cuts off a tree of computations at a given depth. If the depth is 0 or less, no computation nor monadic effects will take place.

Some examples (n ≥ 0):

cutoff 0 _ == return Nothing

cutoff (n+1) . return == return . Just

cutoff (n+1) . lift == lift . liftM Just

cutoff (n+1) . wrap == wrap . fmap (cutoff n)

Calling 'retract . cutoff n' is always terminating, provided each of the steps in the iteration is terminating.

# Operations of free monad

improve :: Functor f => (forall m. MonadFree f m => m a) -> Free f aSource

Improve the asymptotic performance of code that builds a free monad with only binds and returns by using `F`

behind the scenes.

This is based on the "Free Monads for Less" series of articles by Edward Kmett:

http://comonad.com/reader/2011/free-monads-for-less/ http://comonad.com/reader/2011/free-monads-for-less-2/

and "Asymptotic Improvement of Computations over Free Monads" by Janis Voightländer:

fromF :: (Functor f, MonadFree f m) => F f a -> m aSource

Convert to another free monad representation.

iterM :: (Functor f, Monad m) => (f (m a) -> m a) -> F f a -> m aSource

Like `iter`

for monadic values.

# Free Monads With Class

class Monad m => MonadFree f m | m -> f whereSource

Monads provide substitution (`fmap`

) and renormalization (`join`

):

m`>>=`

f =`join`

(`fmap`

f m)

A free `Monad`

is one that does no work during the normalization step beyond simply grafting the two monadic values together.

`[]`

is not a free `Monad`

(in this sense) because

smashes the lists flat.
`join`

[[a]]

On the other hand, consider:

data Tree a = Bin (Tree a) (Tree a) | Tip a

instance`Monad`

Tree where`return`

= Tip Tip a`>>=`

f = f a Bin l r`>>=`

f = Bin (l`>>=`

f) (r`>>=`

f)

This `Monad`

is the free `Monad`

of Pair:

data Pair a = Pair a a

And we could make an instance of `MonadFree`

for it directly:

instance`MonadFree`

Pair Tree where`wrap`

(Pair l r) = Bin l r

Or we could choose to program with

instead of `Free`

Pair`Tree`

and thereby avoid having to define our own `Monad`

instance.

Moreover, Control.Monad.Free.Church provides a `MonadFree`

instance that can improve the *asymptotic* complexity of code that
constructs free monads by effectively reassociating the use of
(`>>=`

). You may also want to take a look at the `kan-extensions`

package (http://hackage.haskell.org/package/kan-extensions).

See `Free`

for a more formal definition of the free `Monad`

for a `Functor`

.

(Functor f, MonadFree f m) => MonadFree f (ListT m) | |

(Functor f, MonadFree f m) => MonadFree f (IdentityT m) | |

(Functor f, MonadFree f m) => MonadFree f (MaybeT m) | |

Functor f => MonadFree f (Free f) | |

Functor f => MonadFree f (F f) | |

Monad m => MonadFree Identity (IterT m) | |

(Functor f, MonadFree f m, Error e) => MonadFree f (ErrorT e m) | |

(Functor f, MonadFree f m, Monoid w) => MonadFree f (WriterT w m) | |

(Functor f, MonadFree f m, Monoid w) => MonadFree f (WriterT w m) | |

(Functor f, MonadFree f m) => MonadFree f (ContT r m) | |

(Functor f, MonadFree f m) => MonadFree f (StateT s m) | |

(Functor f, MonadFree f m) => MonadFree f (StateT s m) | |

(Functor f, MonadFree f m) => MonadFree f (ReaderT e m) | |

(Functor f, Monad m) => MonadFree f (FreeT f m) | |

Functor f => MonadFree f (FT f m) | |

(Functor f, MonadFree f m, Monoid w) => MonadFree f (RWST r w s m) | |

(Functor f, MonadFree f m, Monoid w) => MonadFree f (RWST r w s m) |