New patches: [Added Haddock documentation. Converted the existing module documentation to Haddock format. Created examples. Per Jeff Newberns permission included parts his tutorial "All About Monads" http://haskell.org/all_about_monads/. Andriy Palamarchuk **20070604133602] { hunk ./Control/Monad/Cont/Class.hs 4 ------------------------------------------------------------------------------ --- | --- Module : Control.Monad.Cont.Class --- Copyright : (c) The University of Glasgow 2001 --- License : BSD-style (see the file libraries/base/LICENSE) --- --- Maintainer : libraries@haskell.org --- Stability : experimental --- Portability : non-portable (multi-parameter type classes) --- --- Continuation monad class --- ------------------------------------------------------------------------------ +{- | +Module : Control.Monad.Cont.Class +Copyright : (c) The University of Glasgow 2001, + (c) Jeff Newbern 2003-2007, + (c) Andriy Palamarchuk 2007 +License : BSD-style (see the file libraries/base/LICENSE) + +Maintainer : libraries@haskell.org +Stability : experimental +Portability : non-portable (multi-parameter type classes) + +[Computation type:] Computations which can be interrupted and resumed. + +[Binding strategy:] Binding a function to a monadic value creates +a new continuation which uses the function as the continuation of the monadic +computation. + +[Useful for:] Complex control structures, error handling, +and creating co-routines. + +[Zero and plus:] None. + +[Example type:] @'Cont' r a@ + +The Continuation monad represents computations in continuation-passing style +(CPS). +In continuation-passing style function result is not returned, +but instead is passed to another function, +received as a parameter (continuation). +Computations are built up from sequences +of nested continuations, terminated by a final continuation (often @id@) +which produces the final result. +Since continuations are functions which represent the future of a computation, +manipulation of the continuation functions can achieve complex manipulations +of the future of the computation, +such as interrupting a computation in the middle, aborting a portion +of a computation, restarting a computation, and interleaving execution of +computations. +The Continuation monad adapts CPS to the structure of a monad. + +Before using the Continuation monad, be sure that you have +a firm understanding of continuation-passing style +and that continuations represent the best solution to your particular +design problem. +Many algorithms which require continuations in other languages do not require +them in Haskell, due to Haskell's lazy semantics. +Abuse of the Continuation monad can produce code that is impossible +to understand and maintain. +-} hunk ./Control/Monad/Cont/Class.hs 59 + {- | @callCC@ (call-with-current-continuation) + calls a function with the current continuation as its argument. + Provides an escape continuation mechanism for use with Continuation monads. + Escape continuations allow to abort the current computation and return + a value immediately. + They achieve a similar effect to 'Control.Monad.Error.throwError' + and 'Control.Monad.Error.catchError' + within an 'Control.Monad.Error.Error' monad. + Advantage of this function over calling @return@ is that it makes + the continuation explicit, + allowing more flexibility and better control + (see examples in "Control.Monad.Cont"). + + The standard idiom used with @callCC@ is to provide a lambda-expression + to name the continuation. Then calling the named continuation anywhere + within its scope will escape from the computation, + even if it is many layers deep within nested computations. + -} hunk ./Control/Monad/Cont.hs 4 ------------------------------------------------------------------------------ --- | --- Module : Control.Monad.Cont --- Copyright : (c) The University of Glasgow 2001 --- License : BSD-style (see the file libraries/base/LICENSE) --- --- Maintainer : libraries@haskell.org --- Stability : experimental --- Portability : non-portable (multi-parameter type classes) --- --- Continuation monads. --- ------------------------------------------------------------------------------ +{- | +Module : Control.Monad.Cont +Copyright : (c) The University of Glasgow 2001, + (c) Jeff Newbern 2003-2007, + (c) Andriy Palamarchuk 2007 +License : BSD-style (see the file libraries/base/LICENSE) + +Maintainer : libraries@haskell.org +Stability : experimental +Portability : non-portable (multi-parameter type classes) + +[Computation type:] Computations which can be interrupted and resumed. + +[Binding strategy:] Binding a function to a monadic value creates +a new continuation which uses the function as the continuation of the monadic +computation. + +[Useful for:] Complex control structures, error handling, +and creating co-routines. + +[Zero and plus:] None. + +[Example type:] @'Cont' r a@ + +The Continuation monad represents computations in continuation-passing style +(CPS). +In continuation-passing style function result is not returned, +but instead is passed to another function, +received as a parameter (continuation). +Computations are built up from sequences +of nested continuations, terminated by a final continuation (often @id@) +which produces the final result. +Since continuations are functions which represent the future of a computation, +manipulation of the continuation functions can achieve complex manipulations +of the future of the computation, +such as interrupting a computation in the middle, aborting a portion +of a computation, restarting a computation, and interleaving execution of +computations. +The Continuation monad adapts CPS to the structure of a monad. + +Before using the Continuation monad, be sure that you have +a firm understanding of continuation-passing style +and that continuations represent the best solution to your particular +design problem. +Many algorithms which require continuations in other languages do not require +them in Haskell, due to Haskell's lazy semantics. +Abuse of the Continuation monad can produce code that is impossible +to understand and maintain. +-} hunk ./Control/Monad/Cont.hs 64 + -- * Example 1: Simple Continuation Usage + -- $simpleContExample + + -- * Example 2: Using @callCC@ + -- $callCCExample + + -- * Example 3: Using @ContT@ Monad Transformer + -- $ContTExample hunk ./Control/Monad/Cont.hs 80 --- --------------------------------------------------------------------------- --- Our parameterizable continuation monad +{- | +Continuation monad. +@Cont r a@ is a CPS computation that produces an intermediate result +of type @a@ within a CPS computation whose final result type is @r@. + +The @return@ function simply creates a continuation which passes the value on. + +The @>>=@ operator adds the bound function into the continuation chain. +-} +newtype Cont r a = Cont { hunk ./Control/Monad/Cont.hs 91 -newtype Cont r a = Cont { runCont :: (a -> r) -> r } + {- | Runs a CPS computation, returns its result after applying + the final continuation to it. + Parameters: + + * a continuation computation (@Cont@). + + * the final continuation, which produces the final result (often @id@). + -} + runCont :: (a -> r) -> r +} hunk ./Control/Monad/Cont.hs 118 --- --------------------------------------------------------------------------- --- Our parameterizable continuation monad, with an inner monad - +{- | +The continuation monad transformer. +Can be used to add continuation handling to other monads. +-} hunk ./Control/Monad/Cont.hs 161 +{- $simpleContExample +Calculating length of a list continuation-style: + +>calculateLength :: [a] -> Cont r Int +>calculateLength l = return (length l) + +Here we use @calculateLength@ by making it to pass its result to @print@: + +>main = do +> runCont (calculateLength "123") print +> -- result: 3 + +It is possible to chain 'Cont' blocks with @>>=@. + +>double :: Int -> Cont r Int +>double n = return (n * 2) +> +>main = do +> runCont (calculateLength "123" >>= double) print +> -- result: 6 +-} + +{- $callCCExample +This example gives a taste of how escape continuations work, shows a typical +pattern for their usage. + +>-- Returns a string depending on the length of the name parameter. +>-- If the provided string is empty, returns an error. +>-- Otherwise, returns a welcome message. +>whatsYourName :: String -> String +>whatsYourName name = +> (`runCont` id) $ do -- 1 +> response <- callCC $ \exit -> do -- 2 +> validateName name exit -- 3 +> return $ "Welcome, " ++ name ++ "!" -- 4 +> return response -- 5 +> +>validateName name exit = do +> when (null name) (exit "You forgot to tell me your name!") + +Here is what this example does: + +(1) Runs an anonymous 'Cont' block and extracts value from it with +@(\`runCont\` id)@. Here @id@ is the continuation, passed to the @Cont@ block. + +(1) Binds @response@ to the result of the following 'callCC' block, +binds @exit@ to the continuation. + +(1) Validates @name@. +This approach illustrates advantage of using 'callCC' over @return@. +We pass the continuation to @validateName@, +and interrupt execution of the @Cont@ block from /inside/ of @validateName@. + +(1) Returns the welcome message from the @callCC@ block. +This line is not executed if @validateName@ fails. + +(1) Returns from the @Cont@ block. +-} + +{-$ContTExample +'ContT' can be used to add continuation handling to other monads. +Here is an example how to combine it with @IO@ monad: + +>import Control.Monad.Cont +>import System.IO +> +>main = do +> hSetBuffering stdout NoBuffering +> runContT (callCC askString) reportResult +> +>askString :: (String -> ContT () IO String) -> ContT () IO String +>askString next = do +> liftIO $ putStrLn "Please enter a string" +> s <- liftIO $ getLine +> next s +> +>reportResult :: String -> IO () +>reportResult s = do +> putStrLn ("You entered: " ++ s) + +Action @askString@ requests user to enter a string, +and passes it to the continuation. +@askString@ takes as a parameter a continuation taking a string parameter, +and returning @IO ()@. +Compare its signature to 'runContT' definition. +-} } Context: [Remove Makefile and package.conf.in (used in the old GHC build system) Ian Lynagh **20070524145902] [TAG GHC 6.6.1 release Ian Lynagh **20070428195851] Patch bundle hash: 6253a0a0c1691c96e489aee42430472f9c9599e7