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{hGetContents stdin}.
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 LibSystem} 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.
381 %************************************************************************
383 \subsection[nonio-1-3]{Non-I/O things from the 1.3-DRAFT proposal}
385 %************************************************************************
387 Besides the I/O stuff, you also get these things when you use the
388 \tr{-fhaskell-1.3}\index{-fhaskell-1.3 option} flag.
390 Once again: ANY of thing might CHANGE COMPLETELY before we have ``1.3
394 data Either a b = Left a | Right b deriving (Text, Eq, Ord)
396 data Maybe a = Nothing | Just a deriving (Eq, Ord, Text)
398 thenMaybe :: Maybe a -> (a -> Maybe b) -> Maybe b
399 thenMaybe Nothing _ = Nothing
400 thenMaybe (Just x) f = f x
402 curry :: ((a,b) -> c) -> a -> b -> c
403 curry f x y = f (x,y)
405 uncurry :: (a -> b -> c) -> (a,b) -> c
406 uncurry f (x,y) = f x y
408 \index{Maybe type (Haskell 1.3)}
409 \index{Either type (Haskell 1.3)}
410 \index{curry function (Haskell 1.3)}
411 \index{uncurry function (Haskell 1.3)}
413 %************************************************************************
415 \subsection[io-1-3]{Vs~1.3 monadic I/O}
416 \index{GHC vs the DRAFT 1.3 I/O proposal}
417 \index{DRAFT 1.3 I/O proposal vs GHC}
419 %************************************************************************
421 The most notable improvement in Haskell~1.3 is its I/O, with a shift to
422 ``monadic-style'' I/O.
424 We still offer direct access to the so-called \tr{PrimIO} monad, via
425 the \tr{PreludeGlaST} interface. This is NON-STANDARD, an extension.
426 This interface is described in \Sectionref{io-1-3-prim-interface}.
428 The old \tr{PreludePrimIO} interface is DEAD.
430 The even-older \tr{PreludeGlaIO} interface is DEADER.
432 %************************************************************************
434 \subsubsection[io-1-3-shortcomings]{Known shortcomings in monadic I/O}
436 %************************************************************************
438 Before you begin with ``1.3-style'' monadic I/O, you might as well
439 know the known shortcomings of our implementation, as at 0.26.
441 The error type is called \tr{IOError13}, rather than \tr{IOError}
442 \index{IOError13 vs IOError}
443 (which is still the 1.2 type). (Prelude types cannot be renamed,
444 so...) You probably shouldn't be messing with \tr{IOError} much,
447 Some of the 1.3 I/O code, notably the Extremely Cool \tr{LibPosix}
448 stuff, is relatively untested. Go for it, but be wary...
449 \index{LibPosix bugs}
450 \index{bugs, LibPosix}
452 %************************************************************************
454 \subsubsection[io-1-3-main-interface]{1.3-style monadic I/O}
456 %************************************************************************
458 To use our 1.3 I/O, you should compile {\em and link} using a
459 \tr{-fhaskell-1.3}\index{-fhaskell-1.3 option} flag.
461 You should consult the PROPOSED 1.3-I/O standard. GHC~0.26 implements
462 the ``December 1994'' draft, which we distribute in
463 \tr{ghc/docs/io-1.3/}.
465 Alternatively, you could grab the ``June 1995'' draft, from
466 \tr{pub/haskell/report/}, on \tr{ftp.dcs.glasgow.ac.uk}. The main
467 December--June change that you need to know about is: many of the I/O
468 functions have been removed from \tr{Prelude*} interfaces (no import
469 required) and put into \tr{Lib*} interfaces (import required).
471 GHC~0.26 still provides the I/O functions via \tr{Prelude.hi} (no
472 import required). Ignore the ``June draft'' pleadings for
473 \tr{import LibIO}, and you'll be fine.
475 {\em There is no guarantee that the final 1.3 proposal will look
476 anything like the current DRAFT.} It ain't a standard until the fat
479 For interaction with our non-standard \tr{PrimIO}, including
480 \tr{_ccall_}s. we also provide:
482 -- impedance matching stuff
483 ioToPrimIO :: IO a -> PrimIO a
486 %************************************************************************
488 \subsubsection[io-1-3-prim-interface]{Access to the \tr{PrimIO} monad}
489 \index{PrimIO monad (Glasgow extension)}
490 \index{I/O, primitive (Glasgow extension)}
492 %************************************************************************
494 In what we have implemented, \tr{PrimIO} is the
495 handle-the-errors-yourself monad (NB: used for C-calls and such);
496 whereas \tr{IO} is the 1.3-ish we-handle-errors-for-you monad.
498 Should you may need to play with the \tr{PrimIO} monad directly, you
499 can import \tr{PreludeGlaST}.
501 NB: You used to get this stuff from the \tr{PreludePrimIO} interface,
502 which is now deceased. As of 0.26, you get all things
503 state-transforming from the \tr{PreludeGlaST} interface.
505 The usual monadic stuff for \tr{PrimIO}:
507 returnPrimIO :: a -> PrimIO a
508 thenPrimIO :: PrimIO a -> (a -> PrimIO b) -> PrimIO b
509 seqPrimIO :: PrimIO a -> PrimIO b -> PrimIO b
510 fixPrimIO :: (a -> PrimIO a) -> PrimIO a
511 foldrPrimIO :: (a -> b -> PrimIO b) -> PrimIO b -> [a] -> PrimIO b
512 listPrimIO :: [PrimIO a] -> PrimIO [a]
513 mapPrimIO :: (a -> PrimIO b) -> [a] -> PrimIO [b]
514 mapAndUnzipPrimIO :: (a -> PrimIO (b,c)) -> [a] -> PrimIO ([b],[c])
515 forkPrimIO :: PrimIO a -> PrimIO a
517 unsafePerformPrimIO :: PrimIO a -> a
518 unsafeInterleavePrimIO :: PrimIO a -> PrimIO a
519 -- and they are not called "unsafe" for nothing!
522 And some other stuff:
524 data _FILE -- corresponds to a "FILE *" in C
525 -- in classes Eq, _CCallable, and _CReturnable
527 fclose :: _FILE -> PrimIO Int
528 fdopen :: Int -> String -> PrimIO _FILE
529 fflush :: _FILE -> PrimIO Int
530 fopen :: String -> String -> PrimIO _FILE
531 fread :: Int -> Int -> _FILE -> PrimIO (Int, _ByteArray Int)
532 freopen :: String -> String -> _FILE -> PrimIO _FILE
533 fwrite :: _ByteArray Int -> Int -> Int -> _FILE -> PrimIO Int
535 -- please AVOID using these (They will probably die)
536 appendChanPrimIO :: String -> String -> PrimIO ()
537 appendFilePrimIO :: String -> String -> PrimIO ()
538 getArgsPrimIO :: PrimIO [String]
539 readChanPrimIO :: String -> PrimIO String
542 %************************************************************************
544 \subsubsection[own-mainPrimIO]{Using your own @mainPrimIO@}
545 \index{mainPrimIO, rolling your own}
547 %************************************************************************
549 Normally, the GHC runtime system begins things by called an internal
550 function @mainPrimIO :: PrimIO ()@ which, in turn, fires up
551 @dialogueToIO :: Dialogue -> IO ()@, linking in {\em your} @Main.main@
552 to provide the @Dialogue@.
554 (If you give a \tr{-fhaskell-1.3} flag, then a {\em different}
555 @mainPrimIO@ will be linked in---that's why it is important to link
556 with \tr{-fhaskell-1.3}...)
558 To subvert the above process, you need only provide
559 a @mainPrimIO :: PrimIO ()@ of your own
560 (in a module named \tr{Main}). Do {\em not} use a \tr{-fhaskell-1.3} flag!
562 Here's a little example, stolen from Alastair Reid:
564 module Main ( mainPrimIO ) where
568 mainPrimIO :: PrimIO ()
571 _ccall_ printf "%d\n" (14::Int)
573 sleep :: Int -> PrimIO ()
574 sleep t = _ccall_ sleep t