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