-
-%************************************************************************
-%* *
-%\subsection[infelicities-Glasgow-exts]{In Glasgow extensions}
-%* *
-%************************************************************************
-
-%\begin{description}
-%-------------------------------------------------------------------
-%\item[Glasgow extensions not well ``packaged'':]
-%We would rather give you tidy interfaces to the primitive extensions
-%that GHC provides. For example, instead of your having to muck around
-%with...
-%\begin{verbatim}
-% ... _ccall_ fflush ``stderr'' `thenIO_Int_#` ...
-%\end{verbatim}
-%... (all very grimy); you should be able to import a \tr{LibC.hi}, and
-%pretend that @fflush@ is really a Haskell function!
-
-%This problem will be fixed when Haskell~1.3 comes into existence, and
-%we implement it.
-
-%-------------------------------------------------------------------
-%\item[@ArrRef@s of @Int#@s, @Float#@s, @Double#@s:]
-%Are not in yet, but will be. (Easy to add if you're desperate.)
-%\end{description}
-
-%************************************************************************
-%* *
-\section[vs-Haskell-1.3]{Haskell~1.3 DRAFT vs.~Glasgow Haskell~0.26}
-\index{GHC vs the DRAFT Haskell 1.3 language}
-\index{Haskell 1.3 language DRAFT vs GHC}
-%* *
-%************************************************************************
-
-There is work afoot on ``Haskell~1.3,'' a substantial revision of
-the Haskell~1.2 language.
-
-Haskell 1.3 is NOT a standard; it is NOT even a DRAFT standard. As of
-June 1995, there exists a 1.3 PROPOSAL, which will CERTAINLY change.
-Therefore, the ``1.3 things'' we ``support'' may change ARBITRARILY
-much, and we won't even be mildly apologetic about breaking programs
-that use ``1.3'' facilities.
-
-That said, there are two categories of ``1.3'' things that we commend
-to you.
-\begin{itemize}
-\item
-Things virtually certain to end up in any 1.3~standard. An example is
-the \tr{Maybe} type.
-\item
-Wobblier things which are so much better than their 1.2 equivalents
-that you will want to use them. We mean: monadic I/O.
-
-The basic I/O functions are ``unlikely'' to change and so are
-reasonably safe to adopt. (But see WARNING above...)
-\end{itemize}
-
-To use our 1.3 code, you should compile {\em and link} using a
-\tr{-fhaskell-1.3}\index{-fhaskell-1.3 option} flag.
-
-%************************************************************************
-%* *
-\subsection[duffer-1-3]{Duffer's guide for converting 1.2 I/O to 1.3 I/O}
-\index{I/O---converting 1.2 to 1.3}
-\index{Dialogue I/O--converting to 1.3}
-\index{1.2 I/O---converting to 1.3}
-%* *
-%************************************************************************
-
-Here is our ``crib sheet'' for converting 1.2 I/O to 1.3. In most cases,
-it's really easy.
-\begin{enumerate}
-\item
-Change \tr{readChan stdin} to \tr{getContents}.
-\item
-Change \tr{appendChan stdout} to \tr{putStr}, which is equivalent to
-\tr{hPutStr stdout}.
-Change \tr{appendChan stderr} to \tr{hPutStr stderr}.
-\item
-You need to \tr{import System} if you used @getArgs@, @getEnv@,
-or @getProgName@.
-\item
-Assuming continuation-style @Dialogue@ code, change \tr{... exit done $}
-to \tr{... >>}. Change \tr{... exit $ \ foo ->} to \tr{... >>= \ foo ->}.
-\item
-If you had any functions named \tr{(>>)}, \tr{(>>=)}, or \tr{return},
-change them to something else.
-\end{enumerate}
-
-Also:
-1.3 I/O all the way.
-\tr{Dialogue} usually turns into \tr{IO ()}.
-Use of \tr{StatusFile} request: rewrite (no equivalent exists).
-Add \tr{import Ratio} if you use \tr{Rationals} at all.
-Ditto: \tr{import Complex} if you use complex numbers.
-Ditto: \tr{import Array} if you use arrays. Also: note that
-Arrays now use ordinary pairs, rather than a separate \tr{Assoc} type.
-May be easier to do:
-infix 1 =:
-(=:) a b = (a,b)
-and switch := to =:
-This can happen: \tr{LiteralInt.leStringToInt}; add spaces.
-For \tr{minInt}/\tr{maxInt}, \tr{minChar}/\tr{maxChar} (???)
-use the \tr{Bounded} class methods, \tr{minBound} and \tr{maxBound}.
-Replace class \tr{Text} with \tr{Show}; on rare occasions,
-you may need to do something for \tr{Read}, too.
-The functions \tr{ord} and \tr{chr} have been replaced by
-the class methods \tr{fromEnum} and \tr{toEnum}, respectively.
-The changes, however, can lead to ambiguous overloading.
-Need \tr{import IO} for anything interesting.
-What was called \tr{handle} is now called \tr{catch}.
-New keyword: \tr{do}.
-Other clashes: e.g., \tr{seq}, \tr{fail}.
-\tr{readDec} no longer exists; use ???.
-Type of \tr{fail} changed?
-\tr{(a `op` b) c = ...} is bogus.
-`failWith x' now `fail x'
-`fail x' now `fail (userError x)'
-
-%************************************************************************
-%* *
-\subsection[nonio-1-3]{Non-I/O things from the 1.3-DRAFT proposal}
-%* *
-%************************************************************************
-
-Besides the I/O stuff, you also get these things when you use the
-\tr{-fhaskell-1.3}\index{-fhaskell-1.3 option} flag.
-
-Once again: ANY of thing might CHANGE COMPLETELY before we have ``1.3
-for real.''
-
-\begin{verbatim}
-data Either a b = Left a | Right b deriving (Text, Eq, Ord)
-
-data Maybe a = Nothing | Just a deriving (Eq, Ord, Text)
-
-thenMaybe :: Maybe a -> (a -> Maybe b) -> Maybe b
-thenMaybe Nothing _ = Nothing
-thenMaybe (Just x) f = f x
-
-curry :: ((a,b) -> c) -> a -> b -> c
-curry f x y = f (x,y)
-
-uncurry :: (a -> b -> c) -> (a,b) -> c
-uncurry f (x,y) = f x y
-\end{verbatim}
-\index{Maybe type (Haskell 1.3)}
-\index{Either type (Haskell 1.3)}
-\index{curry function (Haskell 1.3)}
-\index{uncurry function (Haskell 1.3)}
-
-%************************************************************************
-%* *
-\subsection[io-1-3]{Vs~1.3 monadic I/O}
-\index{GHC vs the DRAFT 1.3 I/O proposal}
-\index{DRAFT 1.3 I/O proposal vs GHC}
-%* *
-%************************************************************************
-
-The most notable improvement in Haskell~1.3 is its I/O, with a shift to
-``monadic-style'' I/O.
-
-We still offer direct access to the so-called \tr{PrimIO} monad, via
-the \tr{PreludeGlaST} interface. This is NON-STANDARD, an extension.
-This interface is described in \Sectionref{io-1-3-prim-interface}.
-
-The old \tr{PreludePrimIO} interface is DEAD.
-
-The even-older \tr{PreludeGlaIO} interface is DEADER.
-
-%************************************************************************
-%* *
-\subsubsection[io-1-3-shortcomings]{Known shortcomings in monadic I/O}
-%* *
-%************************************************************************
-
-Before you begin with ``1.3-style'' monadic I/O, you might as well
-know the known shortcomings of our implementation, as at 0.26.
-
-The error type is called \tr{IOError13}, rather than \tr{IOError}
-\index{IOError13 vs IOError}
-(which is still the 1.2 type). (Prelude types cannot be renamed,
-so...) You probably shouldn't be messing with \tr{IOError} much,
-anyway.
-
-Some of the 1.3 I/O code, notably the Extremely Cool \tr{Posix}
-stuff, is relatively untested. Go for it, but be wary...
-\index{Posix library bugs}
-\index{bugs, Posix library}
-
-%************************************************************************
-%* *
-\subsubsection[io-1-3-main-interface]{1.3-style monadic I/O}
-%* *
-%************************************************************************
-
-To use our 1.3 I/O, you should compile {\em and link} using a
-\tr{-fhaskell-1.3}\index{-fhaskell-1.3 option} flag.
-
-You should consult the PROPOSED 1.3-I/O standard. GHC~0.26 implements
-the ``December 1994'' draft, which we distribute in
-\tr{ghc/docs/io-1.3/}.
-
-Alternatively, you could grab the ``June 1995'' draft, from
-\tr{pub/haskell/report/}, on \tr{ftp.dcs.glasgow.ac.uk}. The main
-December--June change that you need to know about is: many of the I/O
-functions have been removed from \tr{Prelude*} interfaces (no import
-required) and put into \tr{Lib*} interfaces (import required).
-
-GHC~0.26 still provides the I/O functions via \tr{Prelude.hi} (no
-import required). Ignore the ``June draft'' pleadings for
-\tr{import IO}, and you'll be fine.
-
-{\em There is no guarantee that the final 1.3 proposal will look
-anything like the current DRAFT.} It ain't a standard until the fat
-committee sings.
-
-For interaction with our non-standard \tr{PrimIO}, including
-\tr{_ccall_}s. we also provide:
-\begin{verbatim}
--- impedance matching stuff
-ioToPrimIO :: IO a -> PrimIO a
-\end{verbatim}
-
-%************************************************************************
-%* *
-\subsubsection[io-1-3-prim-interface]{Access to the \tr{PrimIO} monad}
-\index{PrimIO monad (Glasgow extension)}
-\index{I/O, primitive (Glasgow extension)}
-%* *
-%************************************************************************
-
-In what we have implemented, \tr{PrimIO} is the
-handle-the-errors-yourself monad (NB: used for C-calls and such);
-whereas \tr{IO} is the 1.3-ish we-handle-errors-for-you monad.
-
-Should you may need to play with the \tr{PrimIO} monad directly, you
-can import \tr{PreludeGlaST}.
-
-NB: You used to get this stuff from the \tr{PreludePrimIO} interface,
-which is now deceased. As of 0.26, you get all things
-state-transforming from the \tr{PreludeGlaST} interface.
-
-The usual monadic stuff for \tr{PrimIO}:
-\begin{verbatim}
-returnPrimIO :: a -> PrimIO a
-thenPrimIO :: PrimIO a -> (a -> PrimIO b) -> PrimIO b
-seqPrimIO :: PrimIO a -> PrimIO b -> PrimIO b
-fixPrimIO :: (a -> PrimIO a) -> PrimIO a
-foldrPrimIO :: (a -> b -> PrimIO b) -> PrimIO b -> [a] -> PrimIO b
-listPrimIO :: [PrimIO a] -> PrimIO [a]
-mapPrimIO :: (a -> PrimIO b) -> [a] -> PrimIO [b]
-mapAndUnzipPrimIO :: (a -> PrimIO (b,c)) -> [a] -> PrimIO ([b],[c])
-forkPrimIO :: PrimIO a -> PrimIO a
-
-unsafePerformPrimIO :: PrimIO a -> a
-unsafeInterleavePrimIO :: PrimIO a -> PrimIO a
- -- and they are not called "unsafe" for nothing!
-\end{verbatim}
-
-And some other stuff:
-\begin{verbatim}
-data _FILE -- corresponds to a "FILE *" in C
- -- in classes Eq, _CCallable, and _CReturnable
-
-fclose :: _FILE -> PrimIO Int
-fdopen :: Int -> String -> PrimIO _FILE
-fflush :: _FILE -> PrimIO Int
-fopen :: String -> String -> PrimIO _FILE
-fread :: Int -> Int -> _FILE -> PrimIO (Int, _ByteArray Int)
-freopen :: String -> String -> _FILE -> PrimIO _FILE
-fwrite :: _ByteArray Int -> Int -> Int -> _FILE -> PrimIO Int
-
--- please AVOID using these (They will probably die)
-appendChanPrimIO :: String -> String -> PrimIO ()
-appendFilePrimIO :: String -> String -> PrimIO ()
-getArgsPrimIO :: PrimIO [String]
-readChanPrimIO :: String -> PrimIO String
-\end{verbatim}
-
-%************************************************************************
-%* *
-\subsubsection[own-mainPrimIO]{Using your own @mainPrimIO@}
-\index{mainPrimIO, rolling your own}
-%* *
-%************************************************************************
-
-Normally, the GHC runtime system begins things by called an internal
-function @mainPrimIO :: PrimIO ()@ which, in turn, fires up
-@dialogueToIO :: Dialogue -> IO ()@, linking in {\em your} @Main.main@
-to provide the @Dialogue@.
-
-(If you give a \tr{-fhaskell-1.3} flag, then a {\em different}
-@mainPrimIO@ will be linked in---that's why it is important to link
-with \tr{-fhaskell-1.3}...)
-
-To subvert the above process, you need only provide
-a @mainPrimIO :: PrimIO ()@ of your own
-(in a module named \tr{GHCmain}). Do {\em not} use a \tr{-fhaskell-1.3} flag!
-
-Here's a little example, stolen from Alastair Reid:
-\begin{verbatim}
-module GHCmain ( mainPrimIO ) where
-
-import PreludeGlaST
-
-mainPrimIO :: PrimIO ()
-mainPrimIO =
- sleep 5 `seqPrimIO`
- _ccall_ printf "%d\n" (14::Int)
-
-sleep :: Int -> PrimIO ()
-sleep t = _ccall_ sleep t
-\end{verbatim}