Control.Monad.Trans.Free

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 :: (Functor m, Functor f) => (m ~> n) -> FreeT f m ~> FreeT f n

The very definition of a free monad transformer is that given a natural transformation you get a monad transformer homomorphism.

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

Pull out and join m layers of FreeT f m a.

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.

partialIterT n phi m interprets first n layers of m using phi. This is sort of the opposite for cutoff.

Some examples (n ≥ 0):

partialIterT 0 _ m              ≡ m
partialIterT (n+1) phi . return ≡ return
partialIterT (n+1) phi . lift   ≡ lift
partialIterT (n+1) phi . wrap   ≡ join . lift . phi

intersperseT f m inserts a layer f between every two layers in m.

intersperseT f . return ≡ return
intersperseT f . lift   ≡ lift
intersperseT f . wrap   ≡ wrap . fmap (iterTM (wrap . (<$ f) . wrap))

intercalateT f m inserts a layer f between every two layers in m and then retracts the result.

intercalateT f ≡ retractT . intersperseT f

Tear down a free monad transformer using Monad instance for t m.

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.