# Ticket #1169: ContDoc.patch

File ContDoc.patch, 10.5 KB (added by , 10 years ago) |
---|

Line | |
---|---|

1 | |

2 | New 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/. |

5 | Andriy Palamarchuk <apa3a@yahoo.com>**20070604133602] { |

6 | hunk ./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 : libraries@haskell.org |

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 : libraries@haskell.org |

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 | +-} |

69 | hunk ./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 | + -} |

88 | hunk ./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 : libraries@haskell.org |

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 : libraries@haskell.org |

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 | +-} |

151 | hunk ./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 |

160 | hunk ./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 { |

173 | hunk ./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 | +} |

185 | hunk ./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 | +-} |

193 | hunk ./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 | |

282 | Context: |

283 | |

284 | [Remove Makefile and package.conf.in (used in the old GHC build system) |

285 | Ian Lynagh <igloo@earth.li>**20070524145902] |

286 | [TAG GHC 6.6.1 release |

287 | Ian Lynagh <igloo@earth.li>**20070428195851] |

288 | Patch bundle hash: |

289 | 6253a0a0c1691c96e489aee42430472f9c9599e7 |