Control/Monad/Fix.hs

   1 -----------------------------------------------------------------------------
   2 -- |
   3 -- Module      :  Control.Monad.Fix
   4 -- Copyright   :  (c) Andy Gill 2001,
   5 --                (c) Oregon Graduate Institute of Science and Technology, 2002
   6 -- License     :  BSD-style (see the file libraries/base/LICENSE)
   7 -- Maintainer  :  libraries@haskell.org
   8 -- Stability   :  experimental
   9 -- Portability :  portable
  10 --
  11 -- Monadic fixpoints.
  12 --
  13 -- For a detailed discussion, see Levent Erkok's thesis,
  14 -- /Value Recursion in Monadic Computations/, Oregon Graduate Institute, 2002.
  15 --
  16 -----------------------------------------------------------------------------
  17
  18 module Control.Monad.Fix (
  19         MonadFix(
  20            mfix -- :: (a -> m a) -> m a
  21          ),
  22         fix     -- :: (a -> a) -> a
  23   ) where
  24
  25 import Prelude
  26 import System.IO
  27
  28 -- | @'fix' f@ is the least fixed point of the function @f@,
  29 -- i.e. the least defined @x@ such that @f x = x@.
  30 fix :: (a -> a) -> a
  31 fix f = let x = f x in x
  32
  33 -- | Monads having fixed points with a \'knot-tying\' semantics.
  34 -- Instances of 'MonadFix' should satisfy the following laws:
  35 --
  36 -- [/purity/]
  37 --      @'mfix' ('return' . h)  =  'return' ('fix' h)@
  38 --
  39 -- [/left shrinking/ (or /tightening/)]
  40 --      @'mfix' (\\x -> a >>= \\y -> f x y)  =  \\y -> 'mfix' (\\x -> f x y)@
  41 --
  42 -- [/sliding/]
  43 --      @'mfix' ('Control.Monad.liftM' h . f)  =  'Control.Monad.liftM' h ('mfix' (f . h))@,
  44 --      for strict @h@.
  45 --
  46 -- [/nesting/]
  47 --      @'mfix' (\\x -> 'mfix' (\\y -> f x y))  =  'mfix' (\\x -> f x x)@
  48 --
  49 -- This class is used in the translation of the recursive @do@ notation
  50 -- supported by GHC and Hugs.
  51 class (Monad m) => MonadFix m where
  52         -- | The fixed point of a monadic computation.
  53         -- @'mfix' f@ executes the action @f@ only once, with the eventual
  54         -- output fed back as the input.  Hence @f@ should not be strict,
  55         -- for then @'mfix' f@ would diverge.
  56         mfix :: (a -> m a) -> m a
  57
  58 -- Instances of MonadFix for Prelude monads
  59
  60 -- Maybe:
  61 instance MonadFix Maybe where
  62     mfix f = let a = f (unJust a) in a
  63              where unJust (Just x) = x
  64
  65 -- List:
  66 instance MonadFix [] where
  67     mfix f = case fix (f . head) of
  68                []    -> []
  69                (x:_) -> x : mfix (tail . f)
  70
  71 -- IO:
  72 instance MonadFix IO where
  73     mfix = fixIO