[project @ 1996-01-08 20:28:12 by partain]
[ghc-hetmet.git] / ghc / docs / users_guide / vs_haskell.lit
1 %************************************************************************
2 %*                                                                      *
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}
6 %*                                                                      *
7 %************************************************************************
8
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.
13
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}).
17
18 %************************************************************************
19 %*                                                                      *
20 \subsection[infelicities-exprs-pats]{Expressions and patterns}
21 %*                                                                      *
22 %************************************************************************
23
24 \begin{description}
25 %-------------------------------------------------------------------
26 \item[Some valid irrefutable patterns are rejected:]
27 As syntax errors; just put parentheses around them.
28
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
33 as you like.
34
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.
37
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.)
42 \end{description}
43
44 %************************************************************************
45 %*                                                                      *
46 \subsection[infelicities-decls]{Declarations and bindings}
47 %*                                                                      *
48 %************************************************************************
49
50 \begin{description}
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.)
55
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.
61
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.)
66
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.
72
73 %-------------------------------------------------------------------
74 \item[Derived instances of @Binary@:]
75 We don't.  (We don't do anything @Binary@ish.)
76 \end{description}
77
78 %************************************************************************
79 %*                                                                      *
80 \subsection[infelicities-Modules]{Module system and interface files}
81 %*                                                                      *
82 %************************************************************************
83
84 \begin{description}
85 %-------------------------------------------------------------------
86 \item[Duplicates in a `renaming' list:]
87 Are not reported.
88
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.
93
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
98 will not} propagate.
99
100 (Otherwise, `renaming'---disgusting though it may be---should work.)
101
102 %-------------------------------------------------------------------
103 \item[Fixities/precedences following `renamed' entities that are exported:]
104 No chance.
105
106 %-------------------------------------------------------------------
107 \item[\tr{import Foo ()} vs \tr{import Foo}:]
108 GHC cannot tell the difference (!).
109
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}
115
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
121 check won't be done.
122
123 %-------------------------------------------------------------------
124 \item[Some Prelude entities cannot be hidden:]
125 For example, this doesn't work:
126 \begin{verbatim}
127 import Prelude hiding (readParen)
128 \end{verbatim}
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.
133
134 %-------------------------------------------------------------------
135 \item[\tr{M..} exports vs multiply-imported entities:]
136 If an entity \tr{foo} is imported from several interfaces, as in...
137 \begin{verbatim}
138 import A1 (foo); import A2 (foo); import A3 (foo)
139 \end{verbatim}
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.
142
143 Workaround: export \tr{foo} explicitly.
144
145 %-------------------------------------------------------------------
146 \item[\tr{M..} with Prelude interfaces:]
147 Doing \tr{Prelude<something>..} in an export list; don't even think
148 it.
149
150 %-------------------------------------------------------------------
151 \item[Export of Prelude types/classes must be explicit:]
152
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:
156
157 \begin{verbatim}
158 module PreludeMeGently ( PreludeMeGently.. , other_stuff ) where ..
159 \end{verbatim}
160
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.)
164
165 %-------------------------------------------------------------------
166 \item[Can't export primitives types (e.g., \tr{Int#}):]
167
168 Don't even try...
169
170 %-------------------------------------------------------------------
171 \item[Naming errors with \tr{-O} but not without:]
172
173 Documentation by example---Consider a module with these imports:
174
175 \begin{verbatim}
176 ... various imports ...
177 import Prettyterm       -- desired import
178
179 import Pretty           -- sadly-needed import
180 \end{verbatim}
181
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.)
185
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
191 wrong.
192 \end{description}
193
194 %************************************************************************
195 %*                                                                      *
196 \subsection[infelicities-numbers]{Numbers, basic types, and built-in classes}
197 %*                                                                      *
198 %************************************************************************
199
200 \begin{description}
201 %-------------------------------------------------------------------
202 % now in glasgow_exts
203 %\item[@fromInt@ method in class @Num@:]
204 % (Non-standard.) We support it, as does HBC.
205
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.
211
212 This problem does {\em not} exist for integral constants.
213
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.
217
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.
223
224 Use \tr{Integer}, \tr{Rational}, etc., numeric types if this stuff keeps you
225 awake at night.
226
227 %-------------------------------------------------------------------
228 \item[Multiply-defined array elements---not checked:]
229 This code fragment {\em should} elicit a fatal error, but it does not:
230 \begin{verbatim}
231 main = print (array (1,1) [ 1:=2, 1:=3 ])
232 \end{verbatim}
233
234 %-------------------------------------------------------------------
235 \item[Support for @Binary@ whatnot:]
236 We don't.
237 \end{description}
238
239 %************************************************************************
240 %*                                                                      *
241 \subsection[infelicities-IO]{Dialogue I/O}
242 %*                                                                      *
243 %************************************************************************
244
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.
248
249 \begin{description}
250 %-------------------------------------------------------------------
251 \item[Support for @Dialogue@ I/O:]
252 We do not yet support all @Requests@, notably:
253 @ReadBinFile@,
254 @WriteBinFile@,
255 @AppendBinFile@,
256 @StatusFile@,
257 @ReadBinChan@,
258 @AppendBinChan@,
259 @StatusChan@,
260 @SetEnv@.  Also, we do not support the optional I/O @Requests@.
261
262 \item[@AppendChan@ and @ReadChan@ requests:]
263 The former only works for \tr{stdout} and \tr{stderr}; the
264 latter only for \tr{stdin}.
265
266 \item[@Echo@ request:]
267 We don't do anything at all.
268 \end{description}
269
270 %************************************************************************
271 %*                                                                      *
272 \subsection[infelicities-Prelude]{In Prelude support}
273 %*                                                                      *
274 %************************************************************************
275
276 \begin{description}
277 %-------------------------------------------------------------------
278 \item[Arbitrary-sized tuples:]
279 Plain old tuples of arbitrary size {\em do} work.
280 Note that lots
281 of overloading can give rise to large tuples ``under the hood'' of
282 your program.
283
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.
287
288 These limitations are easily subvertible, so please ask if you get
289 stuck on them.
290 \end{description}
291
292 %************************************************************************
293 %*                                                                      *
294 %\subsection[infelicities-Glasgow-exts]{In Glasgow extensions}
295 %*                                                                      *
296 %************************************************************************
297
298 %\begin{description}
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
303 %with...
304 %\begin{verbatim}
305 %    ... _ccall_ fflush ``stderr'' `thenIO_Int_#` ...
306 %\end{verbatim}
307 %... (all very grimy); you should be able to import a \tr{LibC.hi}, and
308 %pretend that @fflush@ is really a Haskell function!
309
310 %This problem will be fixed when Haskell~1.3 comes into existence, and
311 %we implement it.
312
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.)
316 %\end{description}
317
318 %************************************************************************
319 %*                                                                      *
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}
323 %*                                                                      *
324 %************************************************************************
325
326 There is work afoot on ``Haskell~1.3,'' a substantial revision of
327 the Haskell~1.2 language.
328
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.
334
335 That said, there are two categories of ``1.3'' things that we commend
336 to you.
337 \begin{itemize}
338 \item
339 Things virtually certain to end up in any 1.3~standard.  An example is
340 the \tr{Maybe} type.
341 \item
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.
344
345 The basic I/O functions are ``unlikely'' to change and so are
346 reasonably safe to adopt.  (But see WARNING above...)
347 \end{itemize}
348
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.
351
352 %************************************************************************
353 %*                                                                      *
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}
358 %*                                                                      *
359 %************************************************************************
360
361 Here is our ``crib sheet'' for converting 1.2 I/O to 1.3.  In most cases,
362 it's really easy.
363 \begin{enumerate}
364 \item
365 Change \tr{readChan stdin} to \tr{hGetContents stdin}.
366 \item
367 Change \tr{appendChan stdout} to \tr{putStr}, which is equivalent to
368 \tr{hPutStr stdout}.
369 Change \tr{appendChan stderr} to \tr{hPutStr stderr}.
370 \item
371 You need to \tr{import LibSystem} if you used @getArgs@, @getEnv@,
372 or @getProgName@.
373 \item
374 Assuming continuation-style @Dialogue@ code, change \tr{... exit done $}
375 to \tr{... >>}.  Change \tr{... exit $ \ foo ->} to \tr{... >>= \ foo ->}.
376 \item
377 If you had any functions named \tr{(>>)}, \tr{(>>=)}, or \tr{return},
378 change them to something else.
379 \end{enumerate}
380
381 %************************************************************************
382 %*                                                                      *
383 \subsection[nonio-1-3]{Non-I/O things from the 1.3-DRAFT proposal}
384 %*                                                                      *
385 %************************************************************************
386
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.
389
390 Once again: ANY of thing might CHANGE COMPLETELY before we have ``1.3
391 for real.''
392
393 \begin{verbatim}
394 data Either a b = Left a | Right b deriving (Text, Eq, Ord)
395
396 data Maybe a = Nothing | Just a deriving (Eq, Ord, Text)
397
398 thenMaybe :: Maybe a -> (a -> Maybe b) -> Maybe b
399 thenMaybe Nothing _ = Nothing
400 thenMaybe (Just x) f = f x
401
402 curry   :: ((a,b) -> c) -> a -> b -> c
403 curry f x y = f (x,y)
404
405 uncurry :: (a -> b -> c) -> (a,b) -> c
406 uncurry f (x,y) = f x y
407 \end{verbatim}
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)}
412
413 %************************************************************************
414 %*                                                                      *
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}
418 %*                                                                      *
419 %************************************************************************
420
421 The most notable improvement in Haskell~1.3 is its I/O, with a shift to
422 ``monadic-style'' I/O.
423
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}.
427
428 The old \tr{PreludePrimIO} interface is DEAD.
429
430 The even-older \tr{PreludeGlaIO} interface is DEADER.
431
432 %************************************************************************
433 %*                                                                      *
434 \subsubsection[io-1-3-shortcomings]{Known shortcomings in monadic I/O}
435 %*                                                                      *
436 %************************************************************************
437
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.
440
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,
445 anyway.
446
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}
451
452 %************************************************************************
453 %*                                                                      *
454 \subsubsection[io-1-3-main-interface]{1.3-style monadic I/O}
455 %*                                                                      *
456 %************************************************************************
457
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.
460
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/}.
464
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).
470
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.
474
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
477 committee sings.
478
479 For interaction with our non-standard \tr{PrimIO}, including
480 \tr{_ccall_}s.  we also provide:
481 \begin{verbatim}
482 -- impedance matching stuff
483 ioToPrimIO      :: IO a -> PrimIO a
484 \end{verbatim}
485
486 %************************************************************************
487 %*                                                                      *
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)}
491 %*                                                                      *
492 %************************************************************************
493
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.
497
498 Should you may need to play with the \tr{PrimIO} monad directly, you
499 can import \tr{PreludeGlaST}.
500
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.
504
505 The usual monadic stuff for \tr{PrimIO}:
506 \begin{verbatim}
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
516
517 unsafePerformPrimIO     :: PrimIO a -> a
518 unsafeInterleavePrimIO  :: PrimIO a -> PrimIO a
519   -- and they are not called "unsafe" for nothing!
520 \end{verbatim}
521
522 And some other stuff:
523 \begin{verbatim}
524 data _FILE  -- corresponds to a "FILE *" in C
525             -- in classes Eq, _CCallable, and _CReturnable
526
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
534
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
540 \end{verbatim}
541
542 %************************************************************************
543 %*                                                                      *
544 \subsubsection[own-mainPrimIO]{Using your own @mainPrimIO@}
545 \index{mainPrimIO, rolling your own}
546 %*                                                                      *
547 %************************************************************************
548
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@.
553
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}...)
557
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!
561
562 Here's a little example, stolen from Alastair Reid:
563 \begin{verbatim}
564 module Main ( mainPrimIO ) where
565
566 import PreludeGlaST
567
568 mainPrimIO :: PrimIO ()
569 mainPrimIO = 
570          sleep 5                                `seqPrimIO`
571          _ccall_ printf "%d\n" (14::Int)
572
573 sleep :: Int -> PrimIO ()
574 sleep t = _ccall_ sleep t
575 \end{verbatim}