[Hiding IO
Bryan O'Sullivan <bos@serpentine.com>**20080409061727] {
move ./examples/ch29/HandleT.hs ./examples/ch16/MonadHandle.hs
adddir ./examples/ch17
addfile ./examples/ch16/HandleIO.hs
addfile ./examples/ch16/handleIO.ghci
addfile ./examples/ch16/monadio.ghci
hunk ./en/ch16-monad-case.xml 823
+  </sect1>
+
+  <sect1>
+    <title>Hiding the IO monad</title>
+
+    <para>The blessing and curse of the <type>IO</type> monad is that
+      it is extremely powerful.  If we believe that careful use of
+      types helps us to avoid programming mistakes, then the
+      <type>IO</type> monad should be a great source of unease.
+      Because the <type>IO</type> monad imposes no restrictions on
+      what we can do, it leaves us vulnerable to all kinds of
+      accidents.</para>
+
+    <para>How can we tame its power?  Let's say that we would like to
+      guarantee to ourselves that a piece of code can read and write
+      files on the local filesystem, but that it will not access the
+      network.  We can't use the plain <type>IO</type> monad, because
+      it won't restrict us.</para>
+
+    <sect2>
+      <title>Using a newtype</title>
+
+      <para>Let's create a module that provides a small set of
+	functionality for reading and writing files.</para>
+
+      &HandleIO.hs:module;
+
+      <para>Our first approach to creating a restricted version of
+	<type>IO</type> is to wrap it with a &newtype;.</para>
+
+      &HandleIO.hs:newtype;
+
+      <para>We do the by-now familiar trick of exporting the type
+	constructor and the <function>runHandleIO</function> execution
+	function from our module, but not the data constructor.  This
+	will prevent code running within the <type>HandleIO</type>
+	monad from getting hold of the <type>IO</type> monad that it
+	wraps.</para>
+
+      <para>All that remains is for us to wrap each of the actions we
+	want our monad to allow.  This is a simple matter of wrapping
+	each <type>IO</type> with a <type>HandleIO</type> data
+	constructor.</para>
+
+      &HandleIO.hs:actions;
+
+      <para>We can now use our restricted <type>HandleIO</type> monad
+	to perform I/O.</para>
+
+      &HandleIO.hs:safeHello;
+
+      <para>To run this action, we use
+	<function>runHandleIO</function>.</para>
+
+      &handleIO.ghci:HandleIO;
+
+      <para>If we try to sequence an action that runs in the
+	<type>HandleIO</type> monad with one that is not permitted,
+	the type system forbids it.</para>
+
+      &handleIO.ghci:bad;
+    </sect2>
+
+    <sect2>
+      <title>Designing for unexpected uses</title>
+
+      <para>There's one small, but significant, problem with our
+	<type>HandleIO</type> monad: it doesn't take into account the
+	possibility that we might occasionally need an escape hatch.
+	If we define a monad like this, it is likely that we will
+	occasionally need to perform an I/O action that isn't allowed
+	for by the design of our monad.</para>
+
+      <para>Our purpose in defining a monad like this is to make it
+	easier for us to write solid code in the common case, not to
+	make corner cases impossible.   Let's thus give ourselves a
+	way out.</para>
+
+      <para>The <code>Control.Monad.Trans</code> module defines a
+	<quote>standard escape hatch</quote>, the <type>MonadIO</type>
+	type class.  This defines a single function,
+	<function>liftIO</function>, which lets us embed an
+	<type>IO</type> action in another monad.</para>
+
+      &monadio.ghci:MonadIO;
+
+      <para>Our implementation of this type class is trivial: we just
+	wrap <type>IO</type> with our data constructor.</para>
+
+      &HandleIO.hs:MonadIO;
+      
+      <para>With judicious use of <function>liftIO</function>, we can
+	escape our shackles and invoke <type>IO</type> actions where
+	necessary.</para>
+
+      &HandleIO.hs:tidyHello;
+
+      <tip>
+	<title>Automatic derivation and MonadIO</title>
+
+	<para>We could have had the compiler automatically derive an
+	  instance of <type>MonadIO</type> for us by adding the type
+	  class to the <code>deriving</code> clause of
+	  <type>HandleIO</type>.  This would be our usual strategy in
+	  production code.  The only reason we didn't do this was to
+	  introduce <type>MonadIO</type> after the initial
+	  concepts.</para>
+      </tip>
+    </sect2>
+
+    <sect2>
+      <title>Using type classes</title>
+
+      <remark>Write me!</remark>
+    </sect2>
hunk ./en/ch17-monad-trans.xml 3
-<chapter id="hs.monadtrans" revision="unpublished">
-  <title>FIXME (Monad Transformers / DONS)</title>
-  <remark>FIXME.</remark>
+<chapter id="monadtrans" revision="unpublished">
+  <title>Monad transformers</title>
+
+  <para>Monads provide a powerful way to build computations with
+    effects.  Each of the standard monads is specialised to do exactly
+    one thing.  Quite often, this does not fit our real world
+    needs.</para>
+
+  <para>Recall the <type>Parse</type> type that we developed in
+      <xref linkend="binary"/>.  When we introduced monads, we
+    mentioned that this type was a state monad in disguise. However,
+    it's a little more complex than the standard <type>State</type>
+    monad, because it uses the <type>Either</type> type to allow the
+    possibility of a parsing failure.  If a parse fails early on, we
+    want to stop parsing, not continue in some broken state.</para>
+
+  <para>Even if we were to recast <type>Parse</type> as an instance of
+    the <type>Monad</type> type class, we can't simply drop it and use
+    <type>State</type> instead.  The <type>State</type> monad uses the
+    default implementation of <function>fail</function>: this calls
+    <function>error</function>, which throws an exception that we
+    can't catch in pure code.  The <type>State</type> monad thus
+    <emphasis>appears</emphasis> to allow for failure, without
+    actually being any use.  Once again, we recommend that you almost
+    always avoid using <function>fail</function>.</para>
+
+  <para>There is no joy in the prospect of having to hand-craft a new
+    monad every time we want behaviour that differs slightly from that
+    provided by some standard monad.  Fortunately, we can
+    <emphasis>combine</emphasis> monads by layering them: for example,
+    we can take the standard <type>State</type> monad, and add the
+    possibility of failure to it.</para>
+
+  <para>We call one of these layering monads a <emphasis>monad
+      transfomer</emphasis>, because it modifies the behaviour of an
+    underlying monad.  This finally gives us an explanation of the
+    name of the standard <code>mtl</code> library, where most of the
+    standard monads are defined: it's the monad transformer library.
+    It defines both normal monads and transformer versions of most of
+    them.</para>
+
hunk ./examples/ch16/HandleIO.hs 1
+{-- snippet module --}
+{-# LANGUAGE GeneralizedNewtypeDeriving #-}
+
+module HandleIO
+    (
+      HandleIO
+    , Handle
+    , IOMode(..)
+    , runHandleIO
+    , openFile
+    , hClose
+    , hPutStrLn
+    ) where
+    
+import System.IO (Handle, IOMode(..))
+import qualified System.IO
+{-- /snippet module --}
+import System.Directory (removeFile)
+
+{-- snippet MonadIO --}
+import Control.Monad.Trans (MonadIO(..))
+
+instance MonadIO HandleIO where
+    liftIO = HandleIO
+{-- /snippet MonadIO --}
+
+{-- snippet newtype --}
+newtype HandleIO a = HandleIO { runHandleIO :: IO a }
+    deriving (Monad)
+{-- /snippet newtype --}
+
+{-- snippet actions --}
+openFile :: FilePath -> IOMode -> HandleIO Handle
+openFile path mode = HandleIO (System.IO.openFile path mode)
+
+hClose :: Handle -> HandleIO ()
+hClose = HandleIO . System.IO.hClose
+
+hPutStrLn :: Handle -> String -> HandleIO ()
+hPutStrLn h s = HandleIO (System.IO.hPutStrLn h s)
+{-- /snippet actions --}
+
+{-- snippet safeHello --}
+safeHello :: FilePath -> HandleIO ()
+safeHello path = do
+  h <- openFile path WriteMode
+  hPutStrLn h "hello world"
+  hClose h
+{-- /snippet safeHello --}
+
+{-- snippet tidyHello --}
+tidyHello :: FilePath -> HandleIO ()
+tidyHello path = do
+  safeHello path
+  liftIO (removeFile path)
+{-- /snippet tidyHello --}
hunk ./examples/ch16/MonadHandle.hs 1
-module HandleT
+{-# LANGUAGE FunctionalDependencies, GeneralizedNewtypeDeriving,
+    MultiParamTypeClasses, TypeSynonymInstances #-}
+
+module MonadHandle
hunk ./examples/ch16/MonadHandle.hs 12
+import Control.Monad.Writer
hunk ./examples/ch16/MonadHandle.hs 14
-import System.IO (Handle, hClose)
+import System.IO (IOMode(..))
+
+class Monad m => MonadHandle h m | m -> h where
+    openFile :: FilePath -> IOMode -> m h
+    hPutStrLn :: h -> String -> m ()
+    hClose :: h -> m ()
+
+instance MonadHandle System.IO.Handle IO where
+    openFile = System.IO.openFile
+    hPutStrLn = System.IO.hPutStrLn
+    hClose = System.IO.hClose
+
+safeHello :: MonadHandle h m => FilePath -> m ()
+safeHello path = do
+  h <- openFile path WriteMode
+  hPutStrLn h "hello world"
+  hClose h
hunk ./examples/ch16/MonadHandle.hs 32
-class MonadIO m => MonadHandle m where
-    hGetContents :: Handle -> m String
-    hGetContents = liftIO . System.IO.hGetContents
+data Event = Open FilePath IOMode
+           | PutStrLn String String
+           | Close String
+             deriving (Show)
hunk ./examples/ch16/MonadHandle.hs 37
-    hPutStr :: Handle -> String -> m ()
-    hPutStr h = liftIO . System.IO.hPutStr h
+newtype WriterIO a = W { runW :: Writer [Event] a }
+    deriving (Monad, MonadWriter [Event])
hunk ./examples/ch16/MonadHandle.hs 40
-    hPutStrLn :: Handle -> String -> m ()
-    hPutStrLn h = liftIO . System.IO.hPutStrLn h
+runWriterIO :: WriterIO a -> (a, [Event])
+runWriterIO = runWriter . runW
hunk ./examples/ch16/MonadHandle.hs 43
-instance MonadHandle IO
+instance MonadHandle FilePath WriterIO where
+    openFile path mode = tell [Open path mode] >> return path
+    hPutStrLn h str = tell [PutStrLn h str]
+    hClose h = tell [Close h]
hunk ./examples/ch16/handleIO.ghci 1
+--# HandleIO
+:load HandleIO
+runHandleIO (safeHello "hello_world_101.txt")
+:m +System.Directory
+removeFile "hello_world_101.txt"
+
+--# bad
+runHandleIO (safeHello "goodbye" >> removeFile "goodbye")
hunk ./examples/ch16/monadio.ghci 1
+--# MonadIO
+:m +Control.Monad.Trans
+:info MonadIO
}