1 %************************************************************************
3 \section[vs-Haskell-defn]{Haskell~1.2 vs.~Glasgow Haskell~0.26: language non-compliance}
4 \index{GHC vs the Haskell 1.2 language}
5 \index{Haskell 1.2 language vs GHC}
7 %************************************************************************
9 This section lists Glasgow Haskell infelicities in its implementation
10 of Haskell~1.2. See also the ``when things go wrong'' section
11 (\sectionref{wrong}) for information about crashes, space leaks, and
12 other undesirable phenomena.
14 The limitations here are listed in Haskell-Report order (roughly).
15 %Limitations related to Glasgow extensions (unboxed numbers, etc.) are
16 %given thereafter (\sectionref{infelicities-Glasgow-exts}).
18 %************************************************************************
20 \subsection[infelicities-exprs-pats]{Expressions and patterns}
22 %************************************************************************
25 %-------------------------------------------------------------------
26 \item[Some valid irrefutable patterns are rejected:]
27 As syntax errors; just put parentheses around them.
29 %-------------------------------------------------------------------
30 \item[Very long @String@ constants:]
31 May not go through. If you add a ``string gap'' every
32 few thousand characters, then the strings can be as long
35 Bear in mind that string gaps and the \tr{-cpp}\index{-cpp option}
36 option don't mix. The C-preprocessor may munch the backslashes.
38 %-------------------------------------------------------------------
39 \item[Very long literal lists:]
40 These may tickle a ``yacc stack overflow'' error in the parser.
41 (It depends on the Yacc used to build your parser.)
44 %************************************************************************
46 \subsection[infelicities-decls]{Declarations and bindings}
48 %************************************************************************
51 %-------------------------------------------------------------------
52 \item[Contexts on @data@ declarations are ignored:]
53 Not that they do much, anyway... This won't wreck your life.
54 (We still [vaguely] plan to add them, however.)
56 %-------------------------------------------------------------------
57 \item[Location of instance declarations is unchecked:]
58 We don't check that instance declarations occur either in the module
59 where the class is declared or the module where the data type is
60 declared. This shouldn't hurt you.
62 For better or worse, we {\em do} check if you try to declare a Prelude
63 instance (Prelude class, Prelude type; e.g., \tr{instance Num Bool})
64 in one of your own modules. For some reason, people like to do this!
65 (But it is not legal Haskell.)
67 %-------------------------------------------------------------------
68 \item[Derived instances of @Text@ for infix constructors:]
69 All the carry-on about derived @readsPrec@ and @showsPrec@ for infix
70 constructors---we don't do it (yet). We treat them the same way as
71 all other constructors.
73 %-------------------------------------------------------------------
74 \item[Derived instances of @Binary@:]
75 We don't. (We don't do anything @Binary@ish.)
78 %************************************************************************
80 \subsection[infelicities-Modules]{Module system and interface files}
82 %************************************************************************
85 %-------------------------------------------------------------------
86 \item[Duplicates in a `renaming' list:]
89 %-------------------------------------------------------------------
90 \item[Duplicates in an `import' declaration:]
91 These are reported as errors, which some might argue they shouldn't
92 be. We reckon it's a feature, not a bug.
94 %-------------------------------------------------------------------
95 \item[Export of `renamed' class methods:]
96 Willnae work. That is: you import a class, renaming one or more
97 methods; then export that class---the renaming of the methods {\em
100 (Otherwise, `renaming'---disgusting though it may be---should work.)
102 %-------------------------------------------------------------------
103 \item[Fixities/precedences following `renamed' entities that are exported:]
106 %-------------------------------------------------------------------
107 \item[\tr{import Foo ()} vs \tr{import Foo}:]
108 GHC cannot tell the difference (!).
110 Given that the only module on which you might want to do the former is
111 \tr{import Prelude ()}, there are probably much bigger gremlins that
112 would jump out and bite you if the import {\em did} work. Besides
113 which, you can achieve the same result with
114 \tr{-fno-implicit-prelude}.\index{-fno-implicit-prelude option}
116 %-------------------------------------------------------------------
117 \item[Some selective import/export checking not done:]
118 On selective import and export of type-constructors/classes in
119 which the data-constructors/methods are named explicitly:
120 it'll work; it's just that every conceivable paranoia
123 %-------------------------------------------------------------------
124 \item[Some Prelude entities cannot be hidden:]
125 For example, this doesn't work:
127 import Prelude hiding (readParen)
129 That's because there are a few should-be-hideable Prelude entities
130 which need to appear by magic for derived instances. They are
131 \tr{(&&)}, \tr{(.)}, \tr{lex}, \tr{map}, \tr{not}, \tr{readParen},
132 \tr{showParen}, and \tr{showString}. SIGH.
134 %-------------------------------------------------------------------
135 \item[\tr{M..} exports vs multiply-imported entities:]
136 If an entity \tr{foo} is imported from several interfaces, as in...
138 import A1 (foo); import A2 (foo); import A3 (foo)
140 ... and you then do a ``dot dot'' export of \tr{A1} (for example), it
141 will be {\em pure luck} if \tr{foo} gets exported. This is very sad.
143 Workaround: export \tr{foo} explicitly.
145 %-------------------------------------------------------------------
146 \item[\tr{M..} with Prelude interfaces:]
147 Doing \tr{Prelude<something>..} in an export list; don't even think
150 %-------------------------------------------------------------------
151 \item[Export of Prelude types/classes must be explicit:]
153 If you want to export a data type, type synonym or class from a
154 Prelude module (its name starts with `Prelude'), then it must be
155 listed explicitly in the export list. If you say:
158 module PreludeMeGently ( PreludeMeGently.. , other_stuff ) where ..
161 then the classes/types in \tr{PreludeMeGently} will {\em not} be
162 exported; just add them to the export list. (This shortcoming is only
163 likely to affect people writing their own Prelude modules.)
165 %-------------------------------------------------------------------
166 \item[Can't export primitives types (e.g., \tr{Int#}):]
170 %-------------------------------------------------------------------
171 \item[Naming errors with \tr{-O} but not without:]
173 Documentation by example---Consider a module with these imports:
176 ... various imports ...
177 import Prettyterm -- desired import
179 import Pretty -- sadly-needed import
182 The \tr{import Pretty} is required because it defines a type
183 \tr{Pretty.Doc} which is mentioned in \tr{import Prettyterm}.
184 (Extremely sad, but them's the rules.)
186 But without \tr{-O}, GHC uses its \tr{-fuse-get-mentioned-vars} hack
187 (for speed), trying to avoid looking at parts of interfaces that have
188 no relevance to this module. As it happens, the thing in
189 \tr{Prettyterm} that mentions \tr{Pretty.Doc} is not used here, so
190 this module will go through without \tr{import Pretty}. Nice, but
194 %************************************************************************
196 \subsection[infelicities-numbers]{Numbers, basic types, and built-in classes}
198 %************************************************************************
201 %-------------------------------------------------------------------
202 % now in glasgow_exts
203 %\item[@fromInt@ method in class @Num@:]
204 % (Non-standard.) We support it, as does HBC.
206 %-------------------------------------------------------------------
207 \item[Very large/small fractional constants:]
208 (i.e., with a decimal point somewhere) GHC does not check that these
209 are out of range (e.g., for a @Float@), and bad things will inevitably
210 follow. To be corrected.
212 This problem does {\em not} exist for integral constants.
214 For very large/small fractional constants near the limits of your
215 floating-point precision, things may go wrong. (It's better than it
216 used to be.) Please report any such bugs.
218 %-------------------------------------------------------------------
219 \item[Unchecked arithmetic:]
220 Arguably {\em not} an infelicity, but... Bear in mind that operations
221 on \tr{Int}, \tr{Float}, and \tr{Double} numbers are {\em unchecked}
222 for overflow, underflow, and other sad occurrences.
224 Use \tr{Integer}, \tr{Rational}, etc., numeric types if this stuff keeps you
227 %-------------------------------------------------------------------
228 \item[Multiply-defined array elements---not checked:]
229 This code fragment {\em should} elicit a fatal error, but it does not:
231 main = print (array (1,1) [ 1:=2, 1:=3 ])
234 %-------------------------------------------------------------------
235 \item[Support for @Binary@ whatnot:]
239 %************************************************************************
241 \subsection[infelicities-IO]{Dialogue I/O}
243 %************************************************************************
245 Dialogue-style I/O---still the default for GHC---is on its way out
246 (see the stuff about ``monadic I/O for Haskell~1.3''), so we probably
247 won't fix these shortcomings.
250 %-------------------------------------------------------------------
251 \item[Support for @Dialogue@ I/O:]
252 We do not yet support all @Requests@, notably:
260 @SetEnv@. Also, we do not support the optional I/O @Requests@.
262 \item[@AppendChan@ and @ReadChan@ requests:]
263 The former only works for \tr{stdout} and \tr{stderr}; the
264 latter only for \tr{stdin}.
266 \item[@Echo@ request:]
267 We don't do anything at all.
270 %************************************************************************
272 \subsection[infelicities-Prelude]{In Prelude support}
274 %************************************************************************
277 %-------------------------------------------------------------------
278 \item[Arbitrary-sized tuples:]
279 Plain old tuples of arbitrary size {\em do} work.
281 of overloading can give rise to large tuples ``under the hood'' of
284 HOWEVER: standard instances for tuples (@Eq@, @Ord@, @Ix@, and
285 @Binary@) are available {\em only} up to 5-tuples; except @Binary@,
286 which we don't do at all.
288 These limitations are easily subvertible, so please ask if you get
292 %************************************************************************
294 %\subsection[infelicities-Glasgow-exts]{In Glasgow extensions}
296 %************************************************************************
299 %-------------------------------------------------------------------
300 %\item[Glasgow extensions not well ``packaged'':]
301 %We would rather give you tidy interfaces to the primitive extensions
302 %that GHC provides. For example, instead of your having to muck around
305 % ... _ccall_ fflush ``stderr'' `thenIO_Int_#` ...
307 %... (all very grimy); you should be able to import a \tr{LibC.hi}, and
308 %pretend that @fflush@ is really a Haskell function!
310 %This problem will be fixed when Haskell~1.3 comes into existence, and
313 %-------------------------------------------------------------------
314 %\item[@ArrRef@s of @Int#@s, @Float#@s, @Double#@s:]
315 %Are not in yet, but will be. (Easy to add if you're desperate.)
318 %************************************************************************
320 \section[vs-Haskell-1.3]{Haskell~1.3 DRAFT vs.~Glasgow Haskell~0.26}
321 \index{GHC vs the DRAFT Haskell 1.3 language}
322 \index{Haskell 1.3 language DRAFT vs GHC}
324 %************************************************************************
326 There is work afoot on ``Haskell~1.3,'' a substantial revision of
327 the Haskell~1.2 language.
329 Haskell 1.3 is NOT a standard; it is NOT even a DRAFT standard. As of
330 June 1995, there exists a 1.3 PROPOSAL, which will CERTAINLY change.
331 Therefore, the ``1.3 things'' we ``support'' may change ARBITRARILY
332 much, and we won't even be mildly apologetic about breaking programs
333 that use ``1.3'' facilities.
335 That said, there are two categories of ``1.3'' things that we commend
339 Things virtually certain to end up in any 1.3~standard. An example is
342 Wobblier things which are so much better than their 1.2 equivalents
343 that you will want to use them. We mean: monadic I/O.
345 The basic I/O functions are ``unlikely'' to change and so are
346 reasonably safe to adopt. (But see WARNING above...)
349 To use our 1.3 code, you should compile {\em and link} using a
350 \tr{-fhaskell-1.3}\index{-fhaskell-1.3 option} flag.
352 %************************************************************************
354 \subsection[duffer-1-3]{Duffer's guide for converting 1.2 I/O to 1.3 I/O}
355 \index{I/O---converting 1.2 to 1.3}
356 \index{Dialogue I/O--converting to 1.3}
357 \index{1.2 I/O---converting to 1.3}
359 %************************************************************************
361 Here is our ``crib sheet'' for converting 1.2 I/O to 1.3. In most cases,
365 Change \tr{readChan stdin} to \tr{getContents}.
367 Change \tr{appendChan stdout} to \tr{putStr}, which is equivalent to
369 Change \tr{appendChan stderr} to \tr{hPutStr stderr}.
371 You need to \tr{import System} if you used @getArgs@, @getEnv@,
374 Assuming continuation-style @Dialogue@ code, change \tr{... exit done $}
375 to \tr{... >>}. Change \tr{... exit $ \ foo ->} to \tr{... >>= \ foo ->}.
377 If you had any functions named \tr{(>>)}, \tr{(>>=)}, or \tr{return},
378 change them to something else.
383 \tr{Dialogue} usually turns into \tr{IO ()}.
384 Use of \tr{StatusFile} request: rewrite (no equivalent exists).
385 Add \tr{import Ratio} if you use \tr{Rationals} at all.
386 Ditto: \tr{import Complex} if you use complex numbers.
387 Ditto: \tr{import Array} if you use arrays. Also: note that
388 Arrays now use ordinary pairs, rather than a separate \tr{Assoc} type.
393 This can happen: \tr{LiteralInt.leStringToInt}; add spaces.
394 For \tr{minInt}/\tr{maxInt}, \tr{minChar}/\tr{maxChar} (???)
395 use the \tr{Bounded} class methods, \tr{minBound} and \tr{maxBound}.
396 Replace class \tr{Text} with \tr{Show}; on rare occasions,
397 you may need to do something for \tr{Read}, too.
398 The functions \tr{ord} and \tr{chr} have been replaced by
399 the class methods \tr{fromEnum} and \tr{toEnum}, respectively.
400 The changes, however, can lead to ambiguous overloading.
401 Need \tr{import IO} for anything interesting.
402 What was called \tr{handle} is now called \tr{catch}.
403 New keyword: \tr{do}.
404 Other clashes: e.g., \tr{seq}, \tr{fail}.
405 \tr{readDec} no longer exists; use ???.
406 Type of \tr{fail} changed?
407 \tr{(a `op` b) c = ...} is bogus.
408 `failWith x' now `fail x'
409 `fail x' now `fail (userError x)'
411 %************************************************************************
413 \subsection[nonio-1-3]{Non-I/O things from the 1.3-DRAFT proposal}
415 %************************************************************************
417 Besides the I/O stuff, you also get these things when you use the
418 \tr{-fhaskell-1.3}\index{-fhaskell-1.3 option} flag.
420 Once again: ANY of thing might CHANGE COMPLETELY before we have ``1.3
424 data Either a b = Left a | Right b deriving (Text, Eq, Ord)
426 data Maybe a = Nothing | Just a deriving (Eq, Ord, Text)
428 thenMaybe :: Maybe a -> (a -> Maybe b) -> Maybe b
429 thenMaybe Nothing _ = Nothing
430 thenMaybe (Just x) f = f x
432 curry :: ((a,b) -> c) -> a -> b -> c
433 curry f x y = f (x,y)
435 uncurry :: (a -> b -> c) -> (a,b) -> c
436 uncurry f (x,y) = f x y
438 \index{Maybe type (Haskell 1.3)}
439 \index{Either type (Haskell 1.3)}
440 \index{curry function (Haskell 1.3)}
441 \index{uncurry function (Haskell 1.3)}
443 %************************************************************************
445 \subsection[io-1-3]{Vs~1.3 monadic I/O}
446 \index{GHC vs the DRAFT 1.3 I/O proposal}
447 \index{DRAFT 1.3 I/O proposal vs GHC}
449 %************************************************************************
451 The most notable improvement in Haskell~1.3 is its I/O, with a shift to
452 ``monadic-style'' I/O.
454 We still offer direct access to the so-called \tr{PrimIO} monad, via
455 the \tr{PreludeGlaST} interface. This is NON-STANDARD, an extension.
456 This interface is described in \Sectionref{io-1-3-prim-interface}.
458 The old \tr{PreludePrimIO} interface is DEAD.
460 The even-older \tr{PreludeGlaIO} interface is DEADER.
462 %************************************************************************
464 \subsubsection[io-1-3-shortcomings]{Known shortcomings in monadic I/O}
466 %************************************************************************
468 Before you begin with ``1.3-style'' monadic I/O, you might as well
469 know the known shortcomings of our implementation, as at 0.26.
471 The error type is called \tr{IOError13}, rather than \tr{IOError}
472 \index{IOError13 vs IOError}
473 (which is still the 1.2 type). (Prelude types cannot be renamed,
474 so...) You probably shouldn't be messing with \tr{IOError} much,
477 Some of the 1.3 I/O code, notably the Extremely Cool \tr{Posix}
478 stuff, is relatively untested. Go for it, but be wary...
479 \index{Posix library bugs}
480 \index{bugs, Posix library}
482 %************************************************************************
484 \subsubsection[io-1-3-main-interface]{1.3-style monadic I/O}
486 %************************************************************************
488 To use our 1.3 I/O, you should compile {\em and link} using a
489 \tr{-fhaskell-1.3}\index{-fhaskell-1.3 option} flag.
491 You should consult the PROPOSED 1.3-I/O standard. GHC~0.26 implements
492 the ``December 1994'' draft, which we distribute in
493 \tr{ghc/docs/io-1.3/}.
495 Alternatively, you could grab the ``June 1995'' draft, from
496 \tr{pub/haskell/report/}, on \tr{ftp.dcs.glasgow.ac.uk}. The main
497 December--June change that you need to know about is: many of the I/O
498 functions have been removed from \tr{Prelude*} interfaces (no import
499 required) and put into \tr{Lib*} interfaces (import required).
501 GHC~0.26 still provides the I/O functions via \tr{Prelude.hi} (no
502 import required). Ignore the ``June draft'' pleadings for
503 \tr{import IO}, and you'll be fine.
505 {\em There is no guarantee that the final 1.3 proposal will look
506 anything like the current DRAFT.} It ain't a standard until the fat
509 For interaction with our non-standard \tr{PrimIO}, including
510 \tr{_ccall_}s. we also provide:
512 -- impedance matching stuff
513 ioToPrimIO :: IO a -> PrimIO a
516 %************************************************************************
518 \subsubsection[io-1-3-prim-interface]{Access to the \tr{PrimIO} monad}
519 \index{PrimIO monad (Glasgow extension)}
520 \index{I/O, primitive (Glasgow extension)}
522 %************************************************************************
524 In what we have implemented, \tr{PrimIO} is the
525 handle-the-errors-yourself monad (NB: used for C-calls and such);
526 whereas \tr{IO} is the 1.3-ish we-handle-errors-for-you monad.
528 Should you may need to play with the \tr{PrimIO} monad directly, you
529 can import \tr{PreludeGlaST}.
531 NB: You used to get this stuff from the \tr{PreludePrimIO} interface,
532 which is now deceased. As of 0.26, you get all things
533 state-transforming from the \tr{PreludeGlaST} interface.
535 The usual monadic stuff for \tr{PrimIO}:
537 returnPrimIO :: a -> PrimIO a
538 thenPrimIO :: PrimIO a -> (a -> PrimIO b) -> PrimIO b
539 seqPrimIO :: PrimIO a -> PrimIO b -> PrimIO b
540 fixPrimIO :: (a -> PrimIO a) -> PrimIO a
541 foldrPrimIO :: (a -> b -> PrimIO b) -> PrimIO b -> [a] -> PrimIO b
542 listPrimIO :: [PrimIO a] -> PrimIO [a]
543 mapPrimIO :: (a -> PrimIO b) -> [a] -> PrimIO [b]
544 mapAndUnzipPrimIO :: (a -> PrimIO (b,c)) -> [a] -> PrimIO ([b],[c])
545 forkPrimIO :: PrimIO a -> PrimIO a
547 unsafePerformPrimIO :: PrimIO a -> a
548 unsafeInterleavePrimIO :: PrimIO a -> PrimIO a
549 -- and they are not called "unsafe" for nothing!
552 And some other stuff:
554 data _FILE -- corresponds to a "FILE *" in C
555 -- in classes Eq, _CCallable, and _CReturnable
557 fclose :: _FILE -> PrimIO Int
558 fdopen :: Int -> String -> PrimIO _FILE
559 fflush :: _FILE -> PrimIO Int
560 fopen :: String -> String -> PrimIO _FILE
561 fread :: Int -> Int -> _FILE -> PrimIO (Int, _ByteArray Int)
562 freopen :: String -> String -> _FILE -> PrimIO _FILE
563 fwrite :: _ByteArray Int -> Int -> Int -> _FILE -> PrimIO Int
565 -- please AVOID using these (They will probably die)
566 appendChanPrimIO :: String -> String -> PrimIO ()
567 appendFilePrimIO :: String -> String -> PrimIO ()
568 getArgsPrimIO :: PrimIO [String]
569 readChanPrimIO :: String -> PrimIO String
572 %************************************************************************
574 \subsubsection[own-mainPrimIO]{Using your own @mainPrimIO@}
575 \index{mainPrimIO, rolling your own}
577 %************************************************************************
579 Normally, the GHC runtime system begins things by called an internal
580 function @mainPrimIO :: PrimIO ()@ which, in turn, fires up
581 @dialogueToIO :: Dialogue -> IO ()@, linking in {\em your} @Main.main@
582 to provide the @Dialogue@.
584 (If you give a \tr{-fhaskell-1.3} flag, then a {\em different}
585 @mainPrimIO@ will be linked in---that's why it is important to link
586 with \tr{-fhaskell-1.3}...)
588 To subvert the above process, you need only provide
589 a @mainPrimIO :: PrimIO ()@ of your own
590 (in a module named \tr{GHCmain}). Do {\em not} use a \tr{-fhaskell-1.3} flag!
592 Here's a little example, stolen from Alastair Reid:
594 module GHCmain ( mainPrimIO ) where
598 mainPrimIO :: PrimIO ()
601 _ccall_ printf "%d\n" (14::Int)
603 sleep :: Int -> PrimIO ()
604 sleep t = _ccall_ sleep t