ghc/docs/users_guide/backwards.lit

   1 %************************************************************************
   2 %*                                                                      *
   3 \section[backwards]{Backwards compatibility: Converting from GHC 0.xx and Haskell~1.2}
   4 \index{GHC vs the Haskell 1.2 language}
   5 \index{Haskell 1.2 language vs GHC}
   6 %*                                                                      *
   7 %************************************************************************
   8
   9 This part of the guide is to help people upgrading from a
  10 previous version of GHC.  Right now, it is mostly to help people
  11 switching from GHC~0.29 (a Haskell~1.2 compiler, mostly) to GHC~2.xx
  12 (a Haskell~1.4 compiler).
  13
  14 %ToDo: index
  15
  16 If you need to maintain Haskell code that will work for multiple
  17 versions of GHC, you can use the \tr{-cpp} flag and the
  18 \tr{__GLASGOW_HASKELL__} pre-processor variable.
  19
  20 For example, in GHC~0.29, \tr{__GLASGOW_HASKELL__} will be 29; for~2.04,
  21 it will be 204.  Thus, you can write:
  22 \begin{verbatim}
  23 #if __HASKELL1__ <= 2
  24 main = appendChan stdout "Hello, world!\n" exit done -- 1.2
  25 #else
  26 # if __GLASGOW_HASKELL__ >= 200
  27 import IO
  28 main = putStr "Hello, world!"   -- real 1.3
  29 # else
  30 main = putStr "Hello, world!\n" -- pseudo-1.3 in 0.2x
  31 # endif
  32 #endif
  33 \end{verbatim}
  34
  35 %************************************************************************
  36 %*                                                                      *
  37 \subsection{Types}
  38 %*                                                                      *
  39 %************************************************************************
  40
  41 A big new thing in Haskell~1.3 is constructor classes.  Humble old functions
  42 such as @map@ now have an exciting new type:
  43 \begin{verbatim}
  44 map :: Functor f => (a->b) -> f a -> f b
  45 \end{verbatim}
  46 These new overloadings, expecially where it's the type constructor
  47 that's overloaded (as in @map@) can give rise to some puzzling error
  48 messages.  For example:
  49 \begin{code}
  50   lookupColor :: String -> [(String, (a, b, c))] -> (a, b, c)
  51   lookupColor colorName colorTable =
  52         head [(r,g,b) | (c,(r,g,b)) <- colorTable, c == map toLower colorName]
  53 \end{code}
  54 With the type signature this is fine, but if you omit the type signature
  55 you'll get:
  56 \begin{verbatim}
  57   "Color.hs", line 49: No instance for: Prelude.Eq (a{-a18d-} Prelude.Char)
  58     "Color.hs", line 49:
  59         at a use of an overloaded identifier: `Prelude.meth.Prelude.Eq.=='
  60 \end{verbatim}
  61 @map@ no longer says that @colorName@ has to be a list; it could
  62 be any type of the form (t @Char@).  Unfortunately, lookupColor has to
  63 take equality over these (t @Char@) things, so it gets stuck trying to figure
  64 out how to resolve (@Eq@ (t @Char@)) when it knows nothing about t.
  65
  66 The solution to such messages is to add type signatures.
  67
  68 %************************************************************************
  69 %*                                                                      *
  70 \subsection{Lexical matters}
  71 %*                                                                      *
  72 %************************************************************************
  73
  74 Old uses of `compose' (\tr{(.)}) can magically turn into qualified
  75 names; e.g., \tr{LiteralInt.leStringToInt}; add spaces.
  76
  77 Leading-underscore names (a Glasgow extension) don't work anymore,
  78 even with \tr{-fglasgow-exts}.
  79
  80 The \tr{Prelude.lex} function doesn't grok Haskell comments any more
  81 (a good simplification, but a change nonetheless).
  82
  83 %************************************************************************
  84 %*                                                                      *
  85 \subsection{Expressions and patterns}
  86 %*                                                                      *
  87 %************************************************************************
  88
  89 You used to be able to define non-binary functions in a pseudo-infix-y
  90 say; e.g., \tr{(a `op` b) c = ...}.  Illegal now.
  91
  92 New keyword: \tr{do}.  Any old variables named \tr{do} will now cause
  93 syntax errors.
  94
  95 %************************************************************************
  96 %*                                                                      *
  97 \subsection{Converting @Dialogue@ I/O}
  98 %*                                                                      *
  99 %************************************************************************
 100
 101 In most cases, it's really easy to convert from Haskell~1.2's I/O to
 102 the monadic I/O of Haskell~1.3.
 103
 104 \begin{enumerate}
 105 \item
 106 The type \tr{Dialogue} usually can become \tr{IO ()}.
 107 \item
 108 Change \tr{readChan stdin} to \tr{getContents}.
 109 \item
 110 Change \tr{appendChan stdout} to \tr{putStr}, which is equivalent to
 111 \tr{hPutStr stdout}.
 112 Change \tr{appendChan stderr} to \tr{hPutStr stderr}.
 113 \item
 114 You need to \tr{import IO} to do any interesting I/O; in particular,
 115 anything to do with @Handle@s.
 116 \item
 117 You need to \tr{import System} if you used @getArgs@, @getEnv@,
 118 or @getProgName@.
 119 \item
 120 Assuming continuation-style @Dialogue@ code, change \tr{... exit done $}
 121 to \tr{... >>}.  Change \tr{... exit $ \ foo ->} to \tr{... >>= \ foo ->}.
 122 \item
 123 Sometimes, when you change your \tr{main} routine to ``do'' notation,
 124 you'll get an error message like:
 125 \begin{verbatim}
 126 "Main.hs", line 32: No instance for: Prelude.MonadZero IO
 127     "Main.hs", line 32: in a do statement
 128 \end{verbatim}
 129 This probably means that you need to ``twiddle'' some patterns; e.g.,
 130 I added the twiddle to the \tr{getArgs}-related pattern here:
 131 \begin{verbatim}
 132 main = do
 133     ~[a1] <- getArgs
 134     let x = fst (head ((reads::ReadS Int) a1)
 135     putStr (show (result x))
 136 \end{verbatim}
 137 \item
 138 If you had any functions named \tr{(>>)}, \tr{(>>=)}, or \tr{return},
 139 change them to something else.
 140 \item
 141 If you used the \tr{StatusFile} I/O request, do something else.  No
 142 exact equivalent exists in 1.3.
 143 \end{enumerate}
 144
 145 %************************************************************************
 146 %*                                                                      *
 147 \subsection{Converting from pre-1.3 monadic I/O}
 148 %*                                                                      *
 149 %************************************************************************
 150
 151 GHC~0.29 supported an early DRAFT of the Haskell~1.3 monadic I/O
 152 facilities.  Inevitably, what Really Made It into 1.3 is not quite
 153 what was in the draft.
 154
 155 What was called \tr{handle} in the draft is now called \tr{catch}.
 156
 157 The type of the function \tr{fail} changed between draft and real-thing.
 158 Old: \tr{fail x}; new: \tr{fail (userError x)}.
 159 Also, what used to be \tr{failWith x} is now just \tr{fail x}.
 160
 161 All the system modules named \tr{LibSomething} dropped the \tr{Lib}.
 162 So: \tr{LibSystem} is now just \tr{System}.
 163
 164 As of 2.09, GHC doesn't have @PrimIO@, and all @_ccall_@s now return
 165 type @IO a@, where @a@ is the return type of the @_ccall_@ itself.
 166
 167 The \tr{IOError} type is now abstract; you cannot see it's
 168 constructors.  1.3 provides functions to query errors.
 169
 170 %************************************************************************
 171 %*                                                                      *
 172 \subsection{Use of the standard Prelude}
 173 %*                                                                      *
 174 %************************************************************************
 175
 176 As with any previous Prelude/standard-modules changes, if you have
 177 top-level functions that name-clash with imported entities, you'll get
 178 compiler errors.  So, for example, if your code defines a function
 179 called \tr{seq} (entirely cool in Haskell~1.2), you will now get a
 180 compiler error because there is now a Prelude entity called \tr{seq}.
 181 (You may, of course, \tr{import Prelude hiding (seq)}, if you wish).
 182
 183 Names that frequently clash with new Prelude names:
 184 \tr{fail},
 185 \tr{lookup},
 186 \tr{seq}.
 187
 188 Add \tr{import Ratio} if you use \tr{Rationals} at all.
 189 Ditto: \tr{import Complex} if you use complex numbers.
 190 Ditto: \tr{import Array} if you use arrays.
 191
 192 As suggested above, any \tr{LibXXX} system modules are now just
 193 \tr{XXX}.
 194
 195 Also: note that
 196 Arrays now use ordinary pairs, rather than a separate \tr{Assoc} type.
 197 In some modules, we've found it easier to do:
 198 \begin{verbatim}
 199 infix 1 =:
 200 (=:) a b = (a,b)
 201 \end{verbatim}
 202 and globally replace @:=@ with @=:@.
 203 Works fine for expressions; useless for patterns, however.
 204
 205 For \tr{minInt}/\tr{maxInt} and \tr{minChar}/\tr{maxChar},
 206 use the \tr{Bounded} class methods, \tr{minBound} and \tr{maxBound}.
 207
 208 Replace class \tr{Text} with \tr{Show}; on rare occasions,
 209 you may need to do something for \tr{Read}, too.
 210
 211 The functions \tr{ord} and \tr{chr} have been replaced by
 212 the class methods \tr{fromEnum} and \tr{toEnum}, respectively.
 213 The changes, however, can lead to ambiguous overloading.
 214
 215 The functions \tr{even} and \tr{odd} used to be methods of class
 216 @Integral@.  They are now ordinary, overloaded functions.
 217
 218 The \tr{print} function now appends a newline to its output.  This is
 219 good, but different.
 220
 221 \tr{readDec} no longer exists; use \tr{(reads::ReadS Int)}, or similar.
 222
 223 If you relied on \tr{take}, \tr{drop}, \tr{splitAt}, etc., being
 224 overloaded, you will need to switch to \tr{genericTake},
 225 \tr{genericDrop}, etc., (imported from \tr{List}).
 226
 227 %************************************************************************
 228 %*                                                                      *
 229 \subsection{The module system}
 230 %*                                                                      *
 231 %************************************************************************
 232
 233 GHC~2.04 is fussier than 0.29 about junk in import lists.  This is a
 234 feature.
 235
 236 \tr{Foo..} (in export lists) must be changed to \tr{module Foo}.
 237
 238 Type synonyms may be imported/exported with or without \tr{(..)}---it
 239 was required in Haskell~1.2--but you get a warning if you do it with.
 240
 241 %************************************************************************
 242 %*                                                                      *
 243 \subsection{Use of Glasgow extensions}
 244 %*                                                                      *
 245 %************************************************************************
 246
 247 Leading-underscore names are {\em gone}.  Simon hated them.
 248
 249 To get access to GHC innards, you will need to import system modules
 250 with names of the form \tr{GHCxxx}.  We plan to restrict access to
 251 such interfaces in the future; and, of course, we reserve the right to
 252 make horrible changes to \tr{GHC*} modules....
 253
 254 You can't dig around inside the @ST@/@IO@ monads quite so freely.
 255
 256 The old \tr{PreludePrimIO} interface is DEAD.
 257
 258 The even-older \tr{PreludeGlaIO} interface is DEADER.
 259
 260 @returnPrimIO@, @thenPrimIO@, and @seqPrimIO@ are deprecated.  You
 261 were warned.
 262
 263 @foldrPrimIO@ has died.
 264
 265 @_FILE@, @fclose@, @fdopen@, @fflush@, @fopen@, @fread@, @freopen@,
 266 and @fwrite@ are dead.
 267
 268 @appendChanPrimIO@, @appendFilePrimIO@, @getArgsPrimIO@, and
 269 @readChanPrimIO@ are dead (as previously warned).
 270
 271 The \tr{LibPosix} stuff didn't make it into 1.3 I/O, so it has become
 272 a ``system library'' (\tr{-syslib posix}).  Other than dropping the
 273 \tr{Lib*} prefix, everything should be the same as in 0.29.
 274
 275 As of GHC 2.09, @mainPrimIO@ is now called @mainIO@, to reflect the
 276 fact that @PrimIO@ doesn't exist anymore.  If you want to provide your
 277 own @mainIO@ routine, it must be in a module @GHCmain@, not @Main@.