%************************************************************************
%*                                                                      *
\section[backwards]{Backwards compatibility: Converting from GHC 0.xx and Haskell~1.2}
\index{GHC vs the Haskell 1.2 language}
\index{Haskell 1.2 language vs GHC}
%*                                                                      *
%************************************************************************

This part of the guide is to help people upgrading from a
previous version of GHC.  Right now, it is mostly to help people
switching from GHC~0.26 (a Haskell~1.2 compiler, mostly) to GHC~2.01
(a Haskell~1.3 compiler).

%ToDo: index

If you need to maintain Haskell code that will work for multiple
versions of GHC, you can use the \tr{-cpp} flag and the
\tr{__GLASGOW_HASKELL__} pre-processor variable.

For example, in GHC~0.26, \tr{__GLASGOW_HASKELL__} will be 26; for~2.01,
it will be 201.  Thus, you can write:
\begin{verbatim}
#if __HASKELL1__ <= 2
main = appendChan stdout "Hello, world!\n" exit done -- 1.2
#else
# if __GLASGOW_HASKELL__ >= 200
import IO
main = putStr "Hello, world!"	-- real 1.3
# else
main = putStr "Hello, world!\n"	-- pseudo-1.3 in 0.2x
# endif
#endif
\end{verbatim}

%************************************************************************
%*                                                                      *
\subsection{Types}
%*                                                                      *
%************************************************************************

A big new thing in Haskell~1.3 is constructor classes.  Humble old functions
such as @map@ now have an exciting new type:
\begin{verbatim}
map :: Functor f => (a->b) -> f a -> f b
\end{verbatim}
These new overloadings, expecially where it's the type constructor
that's overloaded (as in @map@) can give rise to some puzzling error
messages.  For example:
\begin{code}
  lookupColor :: String -> [(String, (a, b, c))] -> (a, b, c)
  lookupColor colorName colorTable =
	head [(r,g,b) | (c,(r,g,b)) <- colorTable, c == map toLower colorName]
\end{code}
With the type signature this is fine, but if you omit the type signature
you'll get:
\begin{verbatim}
  "Color.hs", line 49: No instance for: Prelude.Eq (a{-a18d-} Prelude.Char)
    "Color.hs", line 49:
	at a use of an overloaded identifier: `Prelude.meth.Prelude.Eq.=='
\end{verbatim}
@map@ no longer says that @colorName@ has to be a list; it could 
be any type of the form (t @Char@).  Unfortunately, lookupColor has to
take equality over these (t @Char@) things, so it gets stuck trying to figure
out how to resolve (@Eq@ (t @Char@)) when it knows nothing about t.  

The solution to such messages is to add type signatures.

%************************************************************************
%*                                                                      *
\subsection{Lexical matters}
%*                                                                      *
%************************************************************************

Old uses of `compose' (\tr{(.)}) can magically turn into qualified
names; e.g., \tr{LiteralInt.leStringToInt}; add spaces.

Leading-underscore names (a Glasgow extension) don't work anymore,
even with \tr{-fglasgow-exts}.

The \tr{Prelude.lex} function doesn't grok Haskell comments any more
(a good simplification, but a change nonetheless).

%************************************************************************
%*                                                                      *
\subsection{Expressions and patterns}
%*                                                                      *
%************************************************************************

You used to be able to define non-binary functions in a pseudo-infix-y
say; e.g., \tr{(a `op` b) c = ...}.  Illegal now.

New keyword: \tr{do}.  Any old variables named \tr{do} will now cause
syntax errors.

%************************************************************************
%*                                                                      *
\subsection{Converting @Dialogue@ I/O}
%*                                                                      *
%************************************************************************

In most cases, it's really easy to convert from Haskell~1.2's I/O to
the monadic I/O of Haskell~1.3.

\begin{enumerate}
\item
The type \tr{Dialogue} usually can become \tr{IO ()}.
\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 IO} to do any interesting I/O; in particular,
anything to do with @Handle@s.
\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
Sometimes, when you change your \tr{main} routine to ``do'' notation,
you'll get an error message like:
\begin{verbatim}
"Main.hs", line 32: No instance for: Prelude.MonadZero IO
    "Main.hs", line 32: in a do statement
\end{verbatim}
This probably means that you need to ``twiddle'' some patterns; e.g.,
I added the twiddle to the \tr{getArgs}-related pattern here:
\begin{verbatim}
main = do
    ~[a1] <- getArgs
    let x = fst (head ((reads::ReadS Int) a1)
    putStr (show (result x))
\end{verbatim}
\item
If you had any functions named \tr{(>>)}, \tr{(>>=)}, or \tr{return},
change them to something else.
\item
If you used the \tr{StatusFile} I/O request, do something else.  No
exact equivalent exists in 1.3.
\end{enumerate}

%************************************************************************
%*                                                                      *
\subsection{Converting from pre-1.3 monadic I/O}
%*                                                                      *
%************************************************************************

GHC~0.26 supported an early DRAFT of the Haskell~1.3 monadic I/O
facilities.  Inevitably, what Really Made It into 1.3 is not quite
what was in the draft.

What was called \tr{handle} in the draft is now called \tr{catch}.

The type of the function \tr{fail} changed between draft and real-thing.
Old: \tr{fail x}; new: \tr{fail (userError x)}.
Also, what used to be \tr{failWith x} is now just \tr{fail x}.

The function \tr{try} didn't make it into 1.3 I/O.  GHC supplies it
(at least for now) as @GHCio.tryIO@.

All the system modules named \tr{LibSomething} dropped the \tr{Lib}.
So: \tr{LibSystem} is now just \tr{System}.

In~0.26, you could mix-n-match @IO@ with @PrimIO@, simply because the
implementation happend to allow it.  Not any more.

The \tr{IOError} type is now abstract; you cannot see it's
constructors.  1.3 provides functions to query errors.

%************************************************************************
%*                                                                      *
\subsection{Use of the standard Prelude}
%*                                                                      *
%************************************************************************

As with any previous Prelude/standard-modules changes, if you have
top-level functions that name-clash with imported entities, you'll get
compiler errors.  So, for example, if your code defines a function
called \tr{seq} (entirely cool in Haskell~1.2), you will now get a
compiler error because there is now a Prelude entity called \tr{seq}.
(You may, of course, \tr{import Prelude hiding (seq)}, if you wish).

Names that frequently clash with new Prelude names:
\tr{fail},
\tr{lookup},
\tr{seq}.

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.  

As suggested above, any \tr{LibXXX} system modules are now just
\tr{XXX}.

Also: note that
Arrays now use ordinary pairs, rather than a separate \tr{Assoc} type.
In some modules, we've found it easier to do:
\begin{verbatim}
infix 1 =:
(=:) a b = (a,b)
\end{verbatim}
and globally replace @:=@ with @=:@.
Works fine for expressions; useless for patterns, however.

For \tr{minInt}/\tr{maxInt} and \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.

The functions \tr{even} and \tr{odd} used to be methods of class
@Integral@.  They are now ordinary, overloaded functions.

The \tr{print} function now appends a newline to its output.  This is
good, but different.

\tr{readDec} no longer exists; use \tr{(reads::ReadS Int)}, or similar.

If you relied on \tr{take}, \tr{drop}, \tr{splitAt}, etc., being
overloaded, you will need to switch to \tr{genericTake},
\tr{genericDrop}, etc., (imported from \tr{List}).

%************************************************************************
%*                                                                      *
\subsection{The module system}
%*                                                                      *
%************************************************************************

GHC~2.01 is fussier than 0.26 about junk in import lists.  This is a
feature.

\tr{Foo..} (in export lists) must be changed to \tr{module Foo}.

Type synonyms may be imported/exported with or without \tr{(..)}---it
was required in Haskell~1.2--but you get a warning if you do it with.

%************************************************************************
%*                                                                      *
\subsection{Use of Glasgow extensions}
%*                                                                      *
%************************************************************************

Leading-underscore names are {\em gone}.  Simon hated them.

To get access to GHC innards, you will need to import system modules
with names of the form \tr{GHCxxx}.  We plan to restrict access to
such interfaces in the future; and, of course, we reserve the right to
make horrible changes to \tr{GHC*} modules....

You can't dig around inside the @ST@/@IO@ monads quite so freely.

If you want to provide your own @mainPrimIO@ routine, it must be
in a module @GHCmain@, not @Main@.

The old \tr{PreludePrimIO} interface is DEAD.

The even-older \tr{PreludeGlaIO} interface is DEADER.

@returnPrimIO@, @thenPrimIO@, and @seqPrimIO@ are deprecated.  You
were warned.

@foldrPrimIO@ has died.

@_FILE@, @fclose@, @fdopen@, @fflush@, @fopen@, @fread@, @freopen@,
and @fwrite@ are dead.

@appendChanPrimIO@, @appendFilePrimIO@, @getArgsPrimIO@, and
@readChanPrimIO@ are dead (as previously warned).

The \tr{LibPosix} stuff didn't make it into 1.3 I/O, so it has become
a ``system library'' (\tr{-syslib posix}).  Other than dropping the
\tr{Lib*} prefix, everything should be the same as in 0.26.