-- Stability : experimental
-- Portability : portable
--
--- The Fix monad.
+-- Monadic fixpoints.
--
--- Inspired by the paper
--- /Functional Programming with Overloading and
--- Higher-Order Polymorphism/,
--- Mark P Jones (<http://www.cse.ogi.edu/~mpj/>)
--- Advanced School of Functional Programming, 1995.
+-- For more details, see Levent Erkok's thesis,
+-- /Value Recursion in Monadic Computations/, 2002.
--
-----------------------------------------------------------------------------
import Prelude
import System.IO
+-- | @'fix' f@ is the least fixed point of the function @f@.
fix :: (a -> a) -> a
fix f = let x = f x in x
+-- | Monads having fixed points with a \`knot-tying\' semantics.
+-- Instances of 'MonadFix' should satisfy the laws
+--
+-- [purity]
+-- @'mfix' ('return' . h) = 'return' ('fix' h)@
+--
+-- [left shrinking (or tightening)]
+-- @'mfix' (\x -> a >>= \y -> f x y) = \y -> 'mfix' (\x -> f x y)@
+--
+-- [sliding]
+-- @'mfix' ('Control.Monad.liftM' h . f) = 'Control.Monad.liftM' h ('mfix' (f . h))@,
+-- for strict @h@.
+--
+-- [nesting]
+-- @'mfix' (\x -> 'mfix' (\y -> f x y)) = 'mfix' (\x -> f x x)@
+--
+-- This class is used in the translation of the recursive @do@ notation
+-- supported by GHC and Hugs.
class (Monad m) => MonadFix m where
+ -- | The fixed point of a monadic computation.
+ -- @'mfix' f@ executes the action 'f' only once, with the eventual
+ -- output fed back as the input. Hence @f@ should not be strict,
+ -- for then @'mfix' f@ would diverge.
mfix :: (a -> m a) -> m a
-- Instances of MonadFix for Prelude monads