ghc/docs/libraries/libs.sgml

   1 <!doctype linuxdoc system>
   2
   3 <!-- ToDo:
   4   o Add indexing support (to linuxdoc)
   5   o Fix citations in html
   6   -->
   7
   8 <article>
   9
  10 <title>The Hugs-GHC Extension Libraries
  11 <author>Alastair Reid <tt/reid-alastair@cs.yale.edu/
  12         Simon Marlow <tt/simonm@dcs.gla.ac.uk/
  13 <date>v0.8, 14 December 1997
  14 <abstract>
  15 Hugs and GHC provide a common set of libraries to aid portability.
  16 This document specifies the interfaces to these libraries and documents
  17 known differences.  We hope that these modules will be adopted for inclusion
  18 as Standard Haskell Libraries sometime soon.
  19 </abstract>
  20
  21 <toc>
  22
  23 <sect> <idx/ST/
  24 <label id="sec:ST">
  25 <p>
  26
  27 This library provides support for <em/strict/ state threads, as
  28 described in the PLDI '94 paper by John Launchbury and Simon Peyton
  29 Jones <cite id="LazyStateThreads">.  In addition to the monad <tt/ST/,
  30 it also provides mutable variables <tt/STRef/ and mutable arrays
  31 <tt/STArray/.
  32
  33 <tscreen><verb>
  34 module ST( module ST, module Monad ) where
  35 import Monad
  36
  37 data ST s a        -- abstract type
  38 runST              :: forall a. (forall s. ST s a) -> a
  39 fixST              :: (a -> ST s a) -> ST s a
  40 unsafeInterleaveST :: ST s a -> ST s a
  41 instance Functor (ST s)
  42 instance Monad   (ST s)
  43
  44 data STRef s a     -- mutable variables in state thread s
  45                    -- containing values of type a.
  46 newSTRef           :: a -> ST s (STRef s a)
  47 readSTRef          :: STRef s a -> ST s a
  48 writeSTRef         :: STRef s a -> a -> ST s ()
  49 instance Eq (STRef s a)
  50
  51 data STArray s ix elt -- mutable arrays in state thread s
  52                       -- indexed by values of type ix
  53                       -- containing values of type a.
  54 newSTArray          :: Ix ix => (ix,ix) -> elt -> ST s (STArray s ix elt)
  55 boundsSTArray       :: Ix ix => STArray s ix elt -> (ix, ix)
  56 readSTArray         :: Ix ix => STArray s ix elt -> ix -> ST s elt
  57 writeSTArray        :: Ix ix => STArray s ix elt -> ix -> elt -> ST s ()
  58 thawSTArray         :: Ix ix => Array ix elt -> ST s (STArray s ix elt)
  59 freezeSTArray       :: Ix ix => STArray s ix elt -> ST s (Array ix elt)
  60 unsafeFreezeSTArray :: Ix ix => STArray s ix elt -> ST s (Array ix elt)
  61 instance Eq (STArray s ix elt)
  62 </verb></tscreen>
  63
  64 Notes:
  65 <itemize>
  66
  67 <item>
  68 GHC also supports ByteArrays --- these aren't supported by Hugs yet.
  69
  70 <item>
  71 The operations <tt/freezeSTArray/ and <tt/thawSTArray/ convert mutable
  72 arrays to and from immutable arrays.  Semantically, they are identical
  73 to copying the array and they are usually implemented that way.  The
  74 operation <tt/unsafeFreezeSTArray/ is a faster version of
  75 <tt/freezeSTArray/ which omits the copying step.  It's a safe substitute for
  76 <tt/freezeSTArray/ if you don't modify the mutable array after freezing it.
  77
  78 <item>
  79 In the current version of Hugs, the <tt/<idx/runST// operation,
  80 used to specify encapsulation, is implemented as a language construct,
  81 and <tt/runST/ is treated as a keyword.  We plan to change this to match
  82 GHC soon.
  83
  84 <!--
  85   <item>
  86      Note that it is possible to install Hugs 1.4 without support for lazy
  87      state threads, and hence the primitives described here may not be
  88      available in all implementations.  Also, in contrast with the
  89      implementation of lazy state threads in previous releases of Hugs and
  90      Gofer, there is no direct relationship between the
  91      <tt/<idx/ST monad// and the <tt/<idx/IO monad//.
  92   -->
  93
  94 <item>
  95 Hugs provides <tt/thenLazyST/ and <tt/thenStrictST/ so that you can
  96 import <tt/LazyST/ (say) and still use the strict instance in those
  97 places where it matters.  GHC implements LazyST and ST using different
  98 types, so this isn't possible.
  99 </item>
 100
 101 </itemize>
 102
 103 <sect> <idx/LazyST/
 104 <label id="sec:LazyST">
 105 <p>
 106
 107 This library is identical to <tt/ST/ except that the <tt/ST/ monad
 108 instance is <em/lazy/.  The lazy ST monad tends to be more prone to
 109 space leaks than the strict version, so most programmers will use the
 110 former unless laziness is explicitly required.  <tt/LazyST/ provides
 111 two additional operations:
 112
 113 <tscreen> <verb>
 114 lazyToStrictST :: LazyST.ST s a -> ST.ST s a
 115 strictToLazyST :: ST.ST s a -> LazyST.ST s a
 116 </verb> </tscreen>
 117
 118 These are used to convert between lazy and strict state threads.  The
 119 semantics with respect to laziness are as you would expect: the strict
 120 state thread passed to <tt/strictToLazyST/ is not performed until the
 121 result of the lazy state thread it returns is demanded.
 122
 123 <sect> <idx/IOExts/
 124 <label id="sec:IOExts">
 125 <p>
 126
 127 This library provides the following extensions to the IO monad:
 128 <itemize>
 129 <item>
 130 The operations <tt/fixIO/, <tt/unsafePerformIO/ and <tt/unsafeInterleaveIO/
 131 described in <cite id="ImperativeFP">
 132
 133 <item>
 134 References (aka mutable variables) and mutable arrays (but no form of
 135 mutable byte arrays)
 136
 137 <item>
 138 <tt/performGC/ triggers an immediate garbage collection
 139
 140 <item>
 141 When called, <tt/trace/ prints the string in its first argument, and then
 142 returns the second argument as its result.  The <tt/trace/ function is not
 143 referentially transparent, and should only be used for debugging, or for
 144 monitoring execution.
 145
 146 <!--
 147   You should also be warned that, unless you understand some of the
 148   details about the way that Haskell programs are executed, results
 149   obtained using <tt/trace/ can be rather confusing.  For example, the
 150   messages may not appear in the order that you expect.  Even ignoring the
 151   output that they produce, adding calls to <tt/trace/ can change the
 152   semantics of your program.  Consider this a warning!
 153   -->
 154
 155 <item>
 156 <tt/unsafePtrEq/ compares two values for pointer equality without
 157 evaluating them.  The results are not referentially transparent and
 158 may vary significantly from one compiler to another or in the face of
 159 semantics-preserving program changes.  However, pointer equality is useful
 160 in creating a number of referentially transparent constructs such as this
 161 simplified memoisation function:
 162
 163 <tscreen><verb>
 164 > cache :: (a -> b) -> (a -> b)
 165 > cache f = \x -> unsafePerformIO (check x)
 166 >  where
 167 >   ref = unsafePerformIO (newIORef (error "cache", error "cache"))
 168 >   check x = readIORef ref >>= \ (x',a) ->
 169 >              if x `unsafePtrEq` x' then
 170 >                return a
 171 >              else
 172 >                let a = f x in
 173 >                writeIORef ref (x, a) >>
 174 >                return a
 175 </verb></tscreen>
 176
 177
 178 </itemize>
 179
 180 <tscreen><verb>
 181 module IOExts where
 182
 183 fixIO               :: (a -> IO a) -> IO a
 184 unsafePerformIO     :: IO a -> a
 185 unsafeInterleaveIO  :: IO a -> IO a
 186
 187 data IORef a        -- mutable variables containing values of type a
 188 newIORef            :: a -> IO (IORef a)
 189 readIORef           :: IORef a -> IO a
 190 writeIORef          :: IORef a -> a -> IO ()
 191 instance Eq (IORef a)
 192
 193 data IOArray ix elt -- mutable arrays indexed by values of type ix
 194                     -- containing values of type a.
 195 newIOArray          :: Ix ix => (ix,ix) -> elt -> IO (IOArray ix elt)
 196 boundsIOArray       :: Ix ix => IOArray ix elt -> (ix, ix)
 197 readIOArray         :: Ix ix => IOArray ix elt -> ix -> IO elt
 198 writeIOArray        :: Ix ix => IOArray ix elt -> ix -> elt -> IO ()
 199 freezeIOArray       :: Ix ix => IOArray ix elt -> IO (Array ix elt)
 200 instance Eq (IOArray ix elt)
 201
 202 performGC           :: IO ()
 203 trace               :: String -> a -> a
 204 unsafePtrEq         :: a -> a -> Bool
 205 </verb></tscreen>
 206
 207 <!--
 208   <sect> <idx/GlaExts/ <p>
 209
 210   This library provides a convenient bundle of most of the extensions
 211   available in GHC and Hugs.  This module is generally more stable than
 212   the other modules of non-standard extensions so you might choose to
 213   import them from here rather than going straight to the horses mouth.
 214
 215   <tscreen><verb>
 216   module GlaExts( module GlaExts, module IOExts, module ST, module Addr ) where
 217   import IOExts
 218   import ST
 219   import Addr
 220   trace              :: String -> a -> a
 221   performGC          :: IO ()
 222   </verb></tscreen>
 223
 224   The GHC version also provides the types <tt/PrimIO/, <tt/RealWorld/,
 225   <tt/ByteArray/, <tt/Lift/ and operations on these types. It also
 226   provides the unboxed views of the types
 227   <tt/Int/,
 228   <tt/Addr/,
 229   <tt/Word/,
 230   <tt/Float/,
 231   <tt/Double/,
 232   <tt/Integer/ and
 233   <tt/Char/
 234   and a number of ``primitive operations'' (<tt/+&num/,
 235   <tt/plusFloat&num/, etc.).
 236
 237   -->
 238
 239 <sect> <idx/Bits/
 240 <label id="sec:Bits">
 241 <p>
 242
 243 This library defines bitwise operations for signed and unsigned ints.
 244
 245 <tscreen><verb>
 246 module Bits where
 247 infixl 8 `shift`, `rotate`
 248 infixl 7 .&.
 249 infixl 6 `xor`
 250 infixl 5 .|.
 251
 252 class Bits a where
 253   (.&.), (.|.), xor :: a -> a -> a
 254   complement        :: a -> a
 255   shift             :: a -> Int -> a
 256   rotate            :: a -> Int -> a
 257   bit               :: Int -> a
 258   setBit            :: a -> Int -> a
 259   clearBit          :: a -> Int -> a
 260   complementBit     :: a -> Int -> a
 261   testBit           :: a -> Int -> Bool
 262   bitSize           :: a -> Int
 263   isSigned          :: a -> Bool
 264
 265 shiftL, shiftR   :: Bits a => a -> Int -> a
 266 rotateL, rotateR :: Bits a => a -> Int -> a
 267 shiftL  a i = shift  a i
 268 shiftR  a i = shift  a (-i)
 269 rotateL a i = rotate a i
 270 rotateR a i = rotate a (-i)
 271 </verb></tscreen>
 272
 273 Notes:
 274 <itemize>
 275 <item>
 276   <tt/bitSize/ and <tt/isSigned/ are like <tt/floatRadix/ and <tt/floatDigits/
 277   -- they return parameters of the <em/type/ of their argument rather than
 278   of the particular argument they are applied to.  <tt/bitSize/ returns
 279   the number of bits in the type (or <tt/Nothing/ for unbounded types); and
 280   <tt/isSigned/ returns whether the type is signed or not.
 281 <item>
 282   <tt/shift/ performs sign extension.
 283   That is, right shifts fill the top bits with 1 if the  number is negative
 284   and with 0 otherwise.
 285   (Since unsigned types are always positive, the top bit is always filled with
 286   0.)
 287 <item>
 288   Bits are numbered from 0 with bit 0 being the least significant bit.
 289 <item>
 290   <tt/shift x i/ and <tt/rotate x i/ shift to the left if <tt/i/ is
 291   positive and to the right otherwise.
 292 <!--
 293   <item>
 294     <tt/rotate/ is well defined only if bitSize returns a number.
 295     (Maybe we should impose a Bounded constraint on it?)
 296   -->
 297 <item>
 298   <tt/bit i/ is the value with the i'th bit set.
 299 </itemize>
 300
 301 <sect> <idx/Word/
 302 <label id="sec:Word">
 303 <p>
 304
 305 This library provides unsigned integers of various sizes.
 306 The types supported are as follows:
 307
 308 <tabular ca="ll">
 309 type    | number of bits @
 310 <hline>
 311 Word8    | 8  @
 312 Word16   | 16 @
 313 Word32   | 32 @
 314 Word64   | 64 @
 315 <hline>
 316 </tabular>
 317
 318 For each type <it/W/ above, we provide the following functions and
 319 instances.  The type <it/I/ refers to the signed integer type of the
 320 same size.
 321
 322 <tscreen><verb>
 323 data W            -- Unsigned Ints
 324 instance Eq       W
 325 instance Ord      W
 326 instance Show     W
 327 instance Read     W
 328 instance Bounded  W
 329 instance Num      W
 330 instance Real     W
 331 instance Integral W
 332 instance Enum     W
 333 instance Ix       W
 334 instance Bits     W
 335 </verb></tscreen>
 336 Plus
 337 <tscreen><verb>
 338 word8ToWord32  :: Word8  -> Word32
 339 word32ToWord8  :: Word32 -> Word8
 340 word16ToWord32 :: Word16 -> Word32
 341 word32ToWord16 :: Word32 -> Word16
 342
 343 word8ToInt     :: Word8  -> Int
 344 intToWord8     :: Int    -> Word8
 345 word16ToInt    :: Word16 -> Int
 346 intToWord16    :: Int    -> Word16
 347 word32ToInt    :: Word32 -> Int
 348 intToWord32    :: Int    -> Word32
 349 </verb></tscreen>
 350
 351 Notes:
 352 <itemize>
 353 <item>
 354   All arithmetic is performed modulo 2^n
 355
 356   One non-obvious consequequence of this is that <tt/negate/
 357   should <em/not/ raise an error on negative arguments.
 358
 359 <item>
 360 The coercion <tt/wToI/ converts an unsigned n-bit value to the
 361 signed n-bit value with the same representation.  For example,
 362 <tt/word8ToInt8 0xff = -1/.
 363 Likewise, <tt/iToW/ converts signed n-bit values to the
 364 corresponding unsigned n-bit value.
 365
 366 <item>
 367 ToDo: complete the set of coercion functions.
 368
 369 <item>
 370 Use <tt/Prelude.fromIntegral :: (Integral a, Num b) => a -> b/ to
 371 coerce between different sizes or to preserve sign when converting
 372 between values of the same size.
 373
 374 <item>
 375 It would be very natural to add a type a type <tt/Natural/ providing
 376 an unbounded size unsigned integer --- just as <tt/Integer/ provides
 377 unbounded size signed integers.  We do not do that yet since there is
 378 no demand for it.  Doing so would require <tt/Bits.bitSize/ to return
 379 <tt/Maybe Int/.
 380
 381 <item>
 382 The <tt/Enum/ instances stop when they reach their upper or lower
 383 bound --- they don't overflow the way the <tt/Int/ and <tt/Float/
 384 instances do.
 385
 386 <item>
 387 It would be useful to provide a function (or a family of functions?)
 388 which coerced between any two Word types (without going through
 389 Integer).
 390
 391 </itemize>
 392
 393 Hugs only provides <tt/Eq/, <tt/Ord/, <tt/Read/ and <tt/Show/
 394 instances for <tt/Word64/ at the moment.
 395
 396 <sect> <idx/Int/
 397 <label id="sec:Int">
 398 <p>
 399
 400 This library provides signed integers of various sizes.  The types
 401 supported are as follows:
 402
 403 <tabular ca="ll">
 404 type    | number of bits @
 405 <hline>
 406 Int8    | 8  @
 407 Int16   | 16 @
 408 Int32   | 32 @
 409 Int64   | 64 @
 410 <hline>
 411 </tabular>
 412
 413 For each type <it/I/ above, we provide the following instances.
 414
 415 <tscreen><verb>
 416 data I            -- Signed Ints
 417 iToInt            :: I -> Int  -- not provided for Int64
 418 intToi            :: Int -> I  -- not provided for Int64
 419 instance Eq       I
 420 instance Ord      I
 421 instance Show     I
 422 instance Read     I
 423 instance Bounded  I
 424 instance Num      I
 425 instance Real     I
 426 instance Integral I
 427 instance Enum     I
 428 instance Ix       I
 429 instance Bits     I
 430 </verb></tscreen>
 431 Plus
 432 <tscreen><verb>
 433 int8ToInt  :: Int8  -> Int
 434 intToInt8  :: Int   -> Int8
 435 int16ToInt :: Int16 -> Int
 436 intToInt16 :: Int   -> Int16
 437 int32ToInt :: Int32 -> Int
 438 intToInt32 :: Int   -> Int32
 439 </verb></tscreen>
 440
 441 <itemize>
 442 <item>
 443 Hugs does not provide <tt/Int64/ at the moment.
 444
 445 <item>
 446 ToDo: complete the set of coercion functions.
 447
 448 </itemize>
 449
 450 <sect> <idx/Addr/
 451 <label id="sec:Addr">
 452 <p>
 453
 454 This library provides machine addresses and is primarily intended for
 455 use in creating foreign function interfaces using GreenCard.
 456
 457 <tscreen><verb>
 458 module Addr where
 459 data Addr  -- Address type
 460 instance Eq Addr
 461
 462 nullAddr           :: Addr
 463 plusAddr           :: Addr -> Int -> Addr
 464
 465 -- read value out of _immutable_ memory
 466 indexCharOffAddr   :: Addr -> Int -> Char
 467 indexIntOffAddr    :: Addr -> Int -> Int     -- should we drop this?
 468 indexAddrOffAddr   :: Addr -> Int -> Addr
 469 indexFloatOffAddr  :: Addr -> Int -> Float
 470 indexDoubleOffAddr :: Addr -> Int -> Double
 471 indexWord8OffAddr  :: Addr -> Int -> Word8
 472 indexWord16OffAddr :: Addr -> Int -> Word16
 473 indexWord32OffAddr :: Addr -> Int -> Word32
 474 indexWord64OffAddr :: Addr -> Int -> Word64
 475 indexInt8OffAddr   :: Addr -> Int -> Int8
 476 indexInt16OffAddr  :: Addr -> Int -> Int16
 477 indexInt32OffAddr  :: Addr -> Int -> Int32
 478 indexInt64OffAddr  :: Addr -> Int -> Int64
 479
 480 -- read value out of mutable memory
 481 readCharOffAddr    :: Addr -> Int -> IO Char
 482 readIntOffAddr     :: Addr -> Int -> IO Int  -- should we drop this?
 483 readAddrOffAddr    :: Addr -> Int -> IO Addr
 484 readFloatOffAddr   :: Addr -> Int -> IO Float
 485 readDoubleOffAddr  :: Addr -> Int -> IO Double
 486 readWord8OffAddr   :: Addr -> Int -> IO Word8
 487 readWord16OffAddr  :: Addr -> Int -> IO Word16
 488 readWord32OffAddr  :: Addr -> Int -> IO Word32
 489 readWord64OffAddr  :: Addr -> Int -> IO Word64
 490 readInt8OffAddr    :: Addr -> Int -> IO Int8
 491 readInt16OffAddr   :: Addr -> Int -> IO Int16
 492 readInt32OffAddr   :: Addr -> Int -> IO Int32
 493 readInt64OffAddr   :: Addr -> Int -> IO Int64
 494
 495 -- write value into mutable memory
 496 writeCharOffAddr   :: Addr -> Int -> Char   -> IO ()
 497 writeIntOffAddr    :: Addr -> Int -> Int    -> IO ()  -- should we drop this?
 498 writeAddrOffAddr   :: Addr -> Int -> Addr   -> IO ()
 499 writeFloatOffAddr  :: Addr -> Int -> Float  -> IO ()
 500 writeDoubleOffAddr :: Addr -> Int -> Double -> IO ()
 501 writeWord8OffAddr  :: Addr -> Int -> Word8  -> IO ()
 502 writeWord16OffAddr :: Addr -> Int -> Word16 -> IO ()
 503 writeWord32OffAddr :: Addr -> Int -> Word32 -> IO ()
 504 writeWord64OffAddr :: Addr -> Int -> Word64 -> IO ()
 505 writeInt8OffAddr   :: Addr -> Int -> Int8   -> IO ()
 506 writeInt16OffAddr  :: Addr -> Int -> Int16  -> IO ()
 507 writeInt32OffAddr  :: Addr -> Int -> Int32  -> IO ()
 508 writeInt64OffAddr  :: Addr -> Int -> Int64  -> IO ()
 509 </verb></tscreen>
 510
 511 Hugs provides <tt/Addr/ and <tt/nullAddr/ but does not provide any of
 512 the index, read or write functions.  They can be implemented using
 513 GreenCard if required.
 514
 515 <sect> <idx/ForeignObj/
 516 <label id="sec:ForeignObj">
 517 <p>
 518
 519 This module is provided by GHC but not by Hugs.
 520 GreenCard for Hugs provides the <tt/ForeignObj/ type.
 521
 522 <sect> <idx/Concurrent/
 523 <label id="sec:Concurrent">
 524 <p>
 525
 526 This library provides the Concurrent Haskell extensions
 527 <cite id="concurrentHaskell:popl96">.
 528
 529 We are grateful to the Glasgow Haskell Project for allowing us to
 530 redistribute their implementation of this module.
 531
 532 <tscreen><verb>
 533 module Concurrent where
 534
 535 data ThreadId    -- thread identifiers
 536 instance Eq  ThreadId
 537 instance Ord ThreadId
 538
 539 forkIO           :: IO () -> IO ThreadId
 540 killThread       :: ThreadId -> IO ()
 541
 542 data MVar a      -- Synchronisation variables
 543 newEmptyMVar     :: IO (MVar a)
 544 newMVar          :: a -> IO (MVar a)
 545 takeMVar         :: MVar a -> IO a
 546 putMVar          :: MVar a -> a -> IO ()
 547 swapMVar         :: MVar a -> a -> IO a
 548 readMVar         :: MVar a -> IO a
 549 instance Eq (MVar a)
 550
 551 data Chan a      -- channels
 552 newChan          :: IO (Chan a)
 553 writeChan        :: Chan a -> a -> IO ()
 554 readChan         :: Chan a -> IO a
 555 dupChan          :: Chan a -> IO (Chan a)
 556 unReadChan       :: Chan a -> a -> IO ()
 557 getChanContents  :: Chan a -> IO [a]
 558 writeList2Chan   :: Chan a -> [a] -> IO ()
 559
 560 data CVar a       -- one element channels
 561 newCVar          :: IO (CVar a)
 562 putCVar          :: CVar a -> a -> IO ()
 563 getCVar          :: CVar a -> IO a
 564
 565 data QSem        -- General/quantity semaphores
 566 newQSem          :: Int  -> IO QSem
 567 waitQSem         :: QSem -> IO ()
 568 signalQSem       :: QSem -> IO ()
 569
 570 data QSemN       -- General/quantity semaphores
 571 newQSemN         :: Int   -> IO QSemN
 572 waitQSemN        :: QSemN -> Int -> IO ()
 573 signalQSemN      :: QSemN -> Int -> IO ()
 574
 575 type SampleVar a -- Sample variables
 576 newEmptySampleVar:: IO (SampleVar a)
 577 newSampleVar     :: a -> IO (SampleVar a)
 578 emptySampleVar   :: SampleVar a -> IO ()
 579 readSampleVar    :: SampleVar a -> IO a
 580 writeSampleVar   :: SampleVar a -> a -> IO ()
 581 </verb></tscreen>
 582
 583 Notes:
 584 <itemize>
 585
 586 <item>
 587   GHC uses preemptive multitasking:
 588   Context switches can occur at any time, except if you call a C
 589   function (like \verb"getchar") that blocks waiting for input.
 590
 591   Hugs uses cooperative multitasking:
 592   Context switches only occur when you use one of the primitives
 593   defined in this module.  This means that programs such as:
 594
 595 <tscreen><verb>
 596 main = forkIO (write 'a') >> write 'b'
 597  where write c = putChar c >> write c
 598 </verb></tscreen>
 599
 600   will print either <tt/aaaaaaaaaaaaaa.../ or <tt/bbbbbbbbbbbb.../,
 601   instead of some random interleaving of <tt/a/s and <tt/b/s.
 602
 603   In practice, cooperative multitasking is sufficient for writing
 604   simple graphical user interfaces.
 605
 606 <item>
 607 Hugs does not provide the functions <tt/mergeIO/ or <tt/nmergeIO/ since these
 608 require preemptive multitasking.
 609
 610 <item>
 611 Thread identities and <tt/killThread/ has not been implemented yet on
 612 either system. The plan is that <tt/killThread/ will raise an IO
 613 exception in the killed thread which it can catch --- perhaps allowing -->
 614 --it to kill its children before exiting.
 615
 616 <item>
 617 The <tt/Ord/ instance for <tt/ThreadId/s provides an arbitrary total ordering
 618 which might be used to build an ordered binary tree, say.
 619
 620 </itemize>
 621
 622 <sect> <idx/Pretty/
 623 <label id="sec:Pretty">
 624 <p>
 625
 626 This library contains Simon Peyton Jones' implementation of John
 627 Hughes's pretty printer combinators.
 628
 629 <tscreen><verb>
 630 module Pretty where
 631 infixl 6 <>
 632 infixl 6 <+>
 633 infixl 5 $$, $+$
 634 data Doc  -- the Document datatype
 635
 636 -- The primitive Doc values
 637 empty                     :: Doc
 638 text                      :: String   -> Doc
 639 char                      :: Char     -> Doc
 640 int                       :: Int      -> Doc
 641 integer                   :: Integer  -> Doc
 642 float                     :: Float    -> Doc
 643 double                    :: Double   -> Doc
 644 rational                  :: Rational -> Doc
 645 semi, comma, colon, space, equals              :: Doc
 646 lparen, rparen, lbrack, rbrack, lbrace, rbrace :: Doc
 647 parens, brackets, braces  :: Doc -> Doc
 648 quotes, doubleQuotes      :: Doc -> Doc
 649
 650 -- Combining Doc values
 651 (<>)   :: Doc -> Doc -> Doc     -- Beside
 652 hcat   :: [Doc] -> Doc          -- List version of <>
 653 (<+>)  :: Doc -> Doc -> Doc     -- Beside, separated by space
 654 hsep   :: [Doc] -> Doc          -- List version of <+>
 655 ($$)   :: Doc -> Doc -> Doc     -- Above; if there is no
 656                                   -- overlap it "dovetails" the two
 657 vcat   :: [Doc] -> Doc          -- List version of $$
 658 cat    :: [Doc] -> Doc          -- Either hcat or vcat
 659 sep    :: [Doc] -> Doc          -- Either hsep or vcat
 660 fcat   :: [Doc] -> Doc          -- ``Paragraph fill'' version of cat
 661 fsep   :: [Doc] -> Doc          -- ``Paragraph fill'' version of sep
 662 nest   :: Int -> Doc -> Doc     -- Nested
 663 hang   :: Doc -> Int -> Doc -> Doc
 664 punctuate :: Doc -> [Doc] -> [Doc]
 665 -- punctuate p [d1, ... dn] = [d1 <> p, d2 <> p, ... dn-1 <> p, dn]
 666
 667 -- Displaying Doc values
 668 instance Show Doc
 669 render     :: Doc -> String             -- Uses default style
 670 renderStyle  :: Style -> Doc -> String
 671 data Style = Style { lineLength     :: Int,   -- In chars
 672                        ribbonsPerLine :: Float, -- Ratio of ribbon length
 673                                                 -- to line length
 674                        mode :: Mode
 675                }
 676 data Mode = PageMode            -- Normal
 677             | ZigZagMode          -- With zig-zag cuts
 678             | LeftMode            -- No indentation, infinitely long lines
 679             | OneLineMode         -- All on one line
 680 </verb></tscreen>
 681
 682 <biblio files="refs" style="abbrv">
 683
 684
 685 </article>
 686