The base functor for a free monad.

The "free monad transformer" for a functor f

The "free monad" for a functor f.

Pushes a layer into a free monad value.

Evaluates the first layer out of a free monad value.

A version of lift that can be used with just a Functor for f.

Tear down a free monad transformer using iteration.

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

Lift a monad homomorphism from m to n into a monad homomorphism from FreeT f m to FreeT f n

hoistFreeT :: (Monad m, Functor f) => (m ~> n) -> FreeT f m ~> FreeT f n

Lift a natural transformation from f to g into a monad homomorphism from FreeT f m to FreeT g n

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.

retract is the left inverse of liftF

 retract . liftF = id

Tear down a Free Monad using iteration.

Like iter for monadic values.

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 join [[a]] smashes the lists flat.

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 Free Pair instead of 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.