Ticket #1169: ContDoc.patch

File ContDoc.patch, 10.5 KB (added by guest, 8 years ago)

The patch. Version 4 of the module source. Accomodated latest Cont changes.

Line 
1
2New patches:
3
4[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/.
5Andriy Palamarchuk <[email protected]>**20070604133602] {
6hunk ./Control/Monad/Cont/Class.hs 4
7------------------------------------------------------------------------------
8--- |
9--- Module      :  Control.Monad.Cont.Class
10--- Copyright   :  (c) The University of Glasgow 2001
11--- License     :  BSD-style (see the file libraries/base/LICENSE)
12---
13--- Maintainer  :  [email protected]
14--- Stability   :  experimental
15--- Portability :  non-portable (multi-parameter type classes)
16---
17--- Continuation monad class
18---
19------------------------------------------------------------------------------
20+{- |
21+Module      :  Control.Monad.Cont.Class
22+Copyright   :  (c) The University of Glasgow 2001,
23+               (c) Jeff Newbern 2003-2007,
24+               (c) Andriy Palamarchuk 2007
25+License     :  BSD-style (see the file libraries/base/LICENSE)
26+
27+Maintainer  :  [email protected]
28+Stability   :  experimental
29+Portability :  non-portable (multi-parameter type classes)
30+
31+[Computation type:] Computations which can be interrupted and resumed.
32+
33+[Binding strategy:] Binding a function to a monadic value creates
34+a new continuation which uses the function as the continuation of the monadic
35+computation.
36+
37+[Useful for:] Complex control structures, error handling,
38+and creating co-routines.
39+
40+[Zero and plus:] None.
41+
42+[Example type:] @'Cont' r a@
43+
44+The Continuation monad represents computations in continuation-passing style
45+(CPS).
46+In continuation-passing style function result is not returned,
47+but instead is passed to another function,
48+received as a parameter (continuation).
49+Computations are built up from sequences
50+of nested continuations, terminated by a final continuation (often @id@)
51+which produces the final result.
52+Since continuations are functions which represent the future of a computation,
53+manipulation of the continuation functions can achieve complex manipulations
54+of the future of the computation,
55+such as interrupting a computation in the middle, aborting a portion
56+of a computation, restarting a computation, and interleaving execution of
57+computations.
58+The Continuation monad adapts CPS to the structure of a monad.
59+
60+Before using the Continuation monad, be sure that you have
61+a firm understanding of continuation-passing style
62+and that continuations represent the best solution to your particular
63+design problem.
64+Many algorithms which require continuations in other languages do not require
65+them in Haskell, due to Haskell's lazy semantics.
66+Abuse of the Continuation monad can produce code that is impossible
67+to understand and maintain.
68+-}
69hunk ./Control/Monad/Cont/Class.hs 59
70+    {- | @callCC@ (call-with-current-continuation)
71+    calls a function with the current continuation as its argument.
72+    Provides an escape continuation mechanism for use with Continuation monads.
73+    Escape continuations allow to abort the current computation and return
74+    a value immediately.
75+    They achieve a similar effect to 'Control.Monad.Error.throwError'
76+    and 'Control.Monad.Error.catchError'
77+    within an 'Control.Monad.Error.Error' monad.
78+    Advantage of this function over calling @return@ is that it makes
79+    the continuation explicit,
80+    allowing more flexibility and better control
81+    (see examples in "Control.Monad.Cont").
82+
83+    The standard idiom used with @callCC@ is to provide a lambda-expression
84+    to name the continuation. Then calling the named continuation anywhere
85+    within its scope will escape from the computation,
86+    even if it is many layers deep within nested computations.
87+    -}
88hunk ./Control/Monad/Cont.hs 4
89------------------------------------------------------------------------------
90--- |
91--- Module      :  Control.Monad.Cont
92--- Copyright   :  (c) The University of Glasgow 2001
93--- License     :  BSD-style (see the file libraries/base/LICENSE)
94---
95--- Maintainer  :  [email protected]
96--- Stability   :  experimental
97--- Portability :  non-portable (multi-parameter type classes)
98---
99--- Continuation monads.
100---
101------------------------------------------------------------------------------
102+{- |
103+Module      :  Control.Monad.Cont
104+Copyright   :  (c) The University of Glasgow 2001,
105+               (c) Jeff Newbern 2003-2007,
106+               (c) Andriy Palamarchuk 2007
107+License     :  BSD-style (see the file libraries/base/LICENSE)
108+
109+Maintainer  :  [email protected]
110+Stability   :  experimental
111+Portability :  non-portable (multi-parameter type classes)
112+
113+[Computation type:] Computations which can be interrupted and resumed.
114+
115+[Binding strategy:] Binding a function to a monadic value creates
116+a new continuation which uses the function as the continuation of the monadic
117+computation.
118+
119+[Useful for:] Complex control structures, error handling,
120+and creating co-routines.
121+
122+[Zero and plus:] None.
123+
124+[Example type:] @'Cont' r a@
125+
126+The Continuation monad represents computations in continuation-passing style
127+(CPS).
128+In continuation-passing style function result is not returned,
129+but instead is passed to another function,
130+received as a parameter (continuation).
131+Computations are built up from sequences
132+of nested continuations, terminated by a final continuation (often @id@)
133+which produces the final result.
134+Since continuations are functions which represent the future of a computation,
135+manipulation of the continuation functions can achieve complex manipulations
136+of the future of the computation,
137+such as interrupting a computation in the middle, aborting a portion
138+of a computation, restarting a computation, and interleaving execution of
139+computations.
140+The Continuation monad adapts CPS to the structure of a monad.
141+
142+Before using the Continuation monad, be sure that you have
143+a firm understanding of continuation-passing style
144+and that continuations represent the best solution to your particular
145+design problem.
146+Many algorithms which require continuations in other languages do not require
147+them in Haskell, due to Haskell's lazy semantics.
148+Abuse of the Continuation monad can produce code that is impossible
149+to understand and maintain.
150+-}
151hunk ./Control/Monad/Cont.hs 64
152+    -- * Example 1: Simple Continuation Usage
153+    -- $simpleContExample
154+
155+    -- * Example 2: Using @callCC@
156+    -- $callCCExample
157+   
158+    -- * Example 3: Using @ContT@ Monad Transformer
159+    -- $ContTExample
160hunk ./Control/Monad/Cont.hs 80
161--- ---------------------------------------------------------------------------
162--- Our parameterizable continuation monad
163+{- |
164+Continuation monad.
165+@Cont r a@ is a CPS computation that produces an intermediate result
166+of type @a@ within a CPS computation whose final result type is @r@.
167+
168+The @return@ function simply creates a continuation which passes the value on.
169+
170+The @>>=@ operator adds the bound function into the continuation chain.
171+-}
172+newtype Cont r a = Cont {
173hunk ./Control/Monad/Cont.hs 91
174-newtype Cont r a = Cont { runCont :: (a -> r) -> r }
175+    {- | Runs a CPS computation, returns its result after applying
176+    the final continuation to it.
177+    Parameters:
178+
179+    * a continuation computation (@Cont@).
180+
181+    * the final continuation, which produces the final result (often @id@).
182+    -}
183+    runCont :: (a -> r) -> r
184+}
185hunk ./Control/Monad/Cont.hs 118
186--- ---------------------------------------------------------------------------
187--- Our parameterizable continuation monad, with an inner monad
188-
189+{- |
190+The continuation monad transformer.
191+Can be used to add continuation handling to other monads.
192+-}
193hunk ./Control/Monad/Cont.hs 161
194+{- $simpleContExample
195+Calculating length of a list continuation-style:
196+
197+>calculateLength :: [a] -> Cont r Int
198+>calculateLength l = return (length l)
199+
200+Here we use @calculateLength@ by making it to pass its result to @print@:
201+
202+>main = do
203+>  runCont (calculateLength "123") print
204+>  -- result: 3
205+
206+It is possible to chain 'Cont' blocks with @>>=@.
207+
208+>double :: Int -> Cont r Int
209+>double n = return (n * 2)
210+>
211+>main = do
212+>  runCont (calculateLength "123" >>= double) print
213+>  -- result: 6
214+-}
215+
216+{- $callCCExample
217+This example gives a taste of how escape continuations work, shows a typical
218+pattern for their usage.
219+
220+>-- Returns a string depending on the length of the name parameter.
221+>-- If the provided string is empty, returns an error.
222+>-- Otherwise, returns a welcome message.
223+>whatsYourName :: String -> String
224+>whatsYourName name =
225+>  (`runCont` id) $ do                      -- 1
226+>    response <- callCC $ \exit -> do       -- 2
227+>      validateName name exit               -- 3
228+>      return $ "Welcome, " ++ name ++ "!"  -- 4
229+>    return response                        -- 5
230+>
231+>validateName name exit = do
232+>  when (null name) (exit "You forgot to tell me your name!")
233+
234+Here is what this example does:
235+
236+(1) Runs an anonymous 'Cont' block and extracts value from it with
237+@(\`runCont\` id)@. Here @id@ is the continuation, passed to the @Cont@ block.
238+
239+(1) Binds @response@ to the result of the following 'callCC' block,
240+binds @exit@ to the continuation.
241+
242+(1) Validates @name@.
243+This approach illustrates advantage of using 'callCC' over @return@.
244+We pass the continuation to @validateName@,
245+and interrupt execution of the @Cont@ block from /inside/ of @validateName@.
246+
247+(1) Returns the welcome message from the @callCC@ block.
248+This line is not executed if @validateName@ fails.
249+
250+(1) Returns from the @Cont@ block.
251+-}
252+
253+{-$ContTExample
254+'ContT' can be used to add continuation handling to other monads.
255+Here is an example how to combine it with @IO@ monad:
256+
257+>import Control.Monad.Cont
258+>import System.IO
259+>
260+>main = do
261+>  hSetBuffering stdout NoBuffering
262+>  runContT (callCC askString) reportResult
263+>
264+>askString :: (String -> ContT () IO String) -> ContT () IO String
265+>askString next = do
266+>  liftIO $ putStrLn "Please enter a string"
267+>  s <- liftIO $ getLine
268+>  next s
269+>
270+>reportResult :: String -> IO ()
271+>reportResult s = do
272+>  putStrLn ("You entered: " ++ s)
273+
274+Action @askString@ requests user to enter a string,
275+and passes it to the continuation.
276+@askString@ takes as a parameter a continuation taking a string parameter,
277+and returning @IO ()@.
278+Compare its signature to 'runContT' definition.
279+-}
280}
281
282Context:
283
284[Remove Makefile and package.conf.in (used in the old GHC build system)
285Ian Lynagh <[email protected]>**20070524145902]
286[TAG GHC 6.6.1 release
287Ian Lynagh <[email protected]>**20070428195851]
288Patch bundle hash:
2896253a0a0c1691c96e489aee42430472f9c9599e7