1 <!doctype linuxdoc system>
4 o Add indexing support (to linuxdoc)
5 o Fix citations in html
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, 28 January 1998
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.
23 <sect> <idx/Naming conventions/
24 <label id="sec:Naming conventions">
27 The set of interfaces specified in this document try to adhere to the
28 following naming conventions:
32 Actions that create a new values have the prefix <tt/new/ followed by
33 the name of the type of object they're creating, e.g., <tt/newIORef/,
36 Operations that read a value from a mutable object are prefixed with
37 <tt/read/, and operations that update the contents have the prefix
38 <tt/write/, e.g., <tt/readChan/, <tt/readIOArray/.
43 This differs from the convention used to name the operations for
44 reading and writing to a file <tt/Handle/, where <tt/get/ and <tt/put/
47 Operations provided by various concurrency abstractions, e.g., <tt/MVar/,
48 <tt/CVar/ , also deviate from this naming scheme. This is perhaps
49 defensible, since the read and write operations have additional
50 behaviour, e.g., <tt/takeMVar/ tries to read the current value
51 of an <tt/MVar/, locking it if it succeeds.
54 Conversions operators have the form <tt/AToB/ where <tt/A/ and <tt/B/
55 are the types we're converting between.
57 Operations that lazily read values from a mutable object/handle, have
58 the form <tt/getXContents/, e.g., <tt/Channel.getChanContents/ and
59 <tt/IO.hGetContents/. (OK, so the latter isn't called
60 <tt/getHandleContents/, but you hopefully get the picture.)
63 <sect> <idx/LazyST/ <p>
65 This library provides support for both <em/lazy/ and <em/strict/ state
66 threads, as described in the PLDI '94 paper by John Launchbury and
67 Simon Peyton Jones <cite id="LazyStateThreads">. In addition to the
68 monad <tt/ST/, it also provides mutable variables <tt/STRef/ and
69 mutable arrays <tt/STArray/. As the name suggests, the monad <tt/ST/
70 instance is <em/lazy/.
76 This library provides support for <em/strict/ state threads, as
77 described in the PLDI '94 paper by John Launchbury and Simon Peyton
78 Jones <cite id="LazyStateThreads">. In addition to the monad <tt/ST/,
79 it also provides mutable variables <tt/STRef/ and mutable arrays
83 module ST( module ST, module Monad ) where
86 data ST s a -- abstract type
87 runST :: forall a. (forall s. ST s a) -> a
88 fixST :: (a -> ST s a) -> ST s a
89 unsafeInterleaveST :: ST s a -> ST s a
90 instance Functor (ST s)
93 data STRef s a -- mutable variables in state thread s
94 -- containing values of type a.
95 newSTRef :: a -> ST s (STRef s a)
96 readSTRef :: STRef s a -> ST s a
97 writeSTRef :: STRef s a -> a -> ST s ()
98 instance Eq (STRef s a)
100 data STArray s ix elt -- mutable arrays in state thread s
101 -- indexed by values of type ix
102 -- containing values of type a.
103 newSTArray :: Ix ix => (ix,ix) -> elt -> ST s (STArray s ix elt)
104 boundsSTArray :: Ix ix => STArray s ix elt -> (ix, ix)
105 readSTArray :: Ix ix => STArray s ix elt -> ix -> ST s elt
106 writeSTArray :: Ix ix => STArray s ix elt -> ix -> elt -> ST s ()
107 thawSTArray :: Ix ix => Array ix elt -> ST s (STArray s ix elt)
108 freezeSTArray :: Ix ix => STArray s ix elt -> ST s (Array ix elt)
109 unsafeFreezeSTArray :: Ix ix => STArray s ix elt -> ST s (Array ix elt)
110 instance Eq (STArray s ix elt)
117 GHC also supports ByteArrays --- these aren't supported by Hugs yet.
120 The operations <tt/freezeSTArray/ and <tt/thawSTArray/ convert mutable
121 arrays to and from immutable arrays. Semantically, they are identical
122 to copying the array and they are usually implemented that way. The
123 operation <tt/unsafeFreezeSTArray/ is a faster version of
124 <tt/freezeSTArray/ which omits the copying step. It's a safe substitute for
125 <tt/freezeSTArray/ if you don't modify the mutable array after freezing it.
128 In the current version of Hugs, the <tt/<idx/runST// operation,
129 used to specify encapsulation, is implemented as a language construct,
130 and <tt/runST/ is treated as a keyword. We plan to change this to match
135 Note that it is possible to install Hugs 1.4 without support for lazy
136 state threads, and hence the primitives described here may not be
137 available in all implementations. Also, in contrast with the
138 implementation of lazy state threads in previous releases of Hugs and
139 Gofer, there is no direct relationship between the
140 <tt/<idx/ST monad// and the <tt/<idx/IO monad//.
144 Hugs provides <tt/thenLazyST/ and <tt/thenStrictST/ so that you can
145 import <tt/LazyST/ (say) and still use the strict instance in those
146 places where it matters. GHC implements LazyST and ST using different
147 types, so this isn't possible.
153 <label id="sec:LazyST">
156 This library is identical to <tt/ST/ except that the <tt/ST/ monad
157 instance is <em/lazy/. The lazy ST monad tends to be more prone to
158 space leaks than the strict version, so most programmers will use the
159 former unless laziness is explicitly required. <tt/LazyST/ provides
160 two additional operations:
163 lazyToStrictST :: LazyST.ST s a -> ST.ST s a
164 strictToLazyST :: ST.ST s a -> LazyST.ST s a
167 These are used to convert between lazy and strict state threads. The
168 semantics with respect to laziness are as you would expect: the strict
169 state thread passed to <tt/strictToLazyST/ is not performed until the
170 result of the lazy state thread it returns is demanded.
173 <label id="sec:IOExts">
176 This library provides the following extensions to the IO monad:
179 The operations <tt/fixIO/, <tt/unsafePerformIO/ and <tt/unsafeInterleaveIO/
180 described in <cite id="ImperativeFP">
183 References (aka mutable variables) and mutable arrays (but no form of
187 <tt/performGC/ triggers an immediate garbage collection
190 When called, <tt/trace/ prints the string in its first argument, and then
191 returns the second argument as its result. The <tt/trace/ function is not
192 referentially transparent, and should only be used for debugging, or for
193 monitoring execution.
196 You should also be warned that, unless you understand some of the
197 details about the way that Haskell programs are executed, results
198 obtained using <tt/trace/ can be rather confusing. For example, the
199 messages may not appear in the order that you expect. Even ignoring the
200 output that they produce, adding calls to <tt/trace/ can change the
201 semantics of your program. Consider this a warning!
205 <tt/unsafePtrEq/ compares two values for pointer equality without
206 evaluating them. The results are not referentially transparent and
207 may vary significantly from one compiler to another or in the face of
208 semantics-preserving program changes. However, pointer equality is useful
209 in creating a number of referentially transparent constructs such as this
210 simplified memoisation function:
213 > cache :: (a -> b) -> (a -> b)
214 > cache f = \x -> unsafePerformIO (check x)
216 > ref = unsafePerformIO (newIORef (error "cache", error "cache"))
217 > check x = readIORef ref >>= \ (x',a) ->
218 > if x `unsafePtrEq` x' then
222 > writeIORef ref (x, a) >>
232 fixIO :: (a -> IO a) -> IO a
233 unsafePerformIO :: IO a -> a
234 unsafeInterleaveIO :: IO a -> IO a
236 data IORef a -- mutable variables containing values of type a
237 newIORef :: a -> IO (IORef a)
238 readIORef :: IORef a -> IO a
239 writeIORef :: IORef a -> a -> IO ()
240 instance Eq (IORef a)
242 data IOArray ix elt -- mutable arrays indexed by values of type ix
243 -- containing values of type a.
244 newIOArray :: Ix ix => (ix,ix) -> elt -> IO (IOArray ix elt)
245 boundsIOArray :: Ix ix => IOArray ix elt -> (ix, ix)
246 readIOArray :: Ix ix => IOArray ix elt -> ix -> IO elt
247 writeIOArray :: Ix ix => IOArray ix elt -> ix -> elt -> IO ()
248 freezeIOArray :: Ix ix => IOArray ix elt -> IO (Array ix elt)
249 instance Eq (IOArray ix elt)
252 trace :: String -> a -> a
253 unsafePtrEq :: a -> a -> Bool
257 <sect> <idx/GlaExts/ <p>
259 This library provides a convenient bundle of most of the extensions
260 available in GHC and Hugs. This module is generally more stable than
261 the other modules of non-standard extensions so you might choose to
262 import them from here rather than going straight to the horses mouth.
265 module GlaExts( module GlaExts, module IOExts, module ST, module Addr ) where
269 trace :: String -> a -> a
273 The GHC version also provides the types <tt/PrimIO/, <tt/RealWorld/,
274 <tt/ByteArray/, <tt/Lift/ and operations on these types. It also
275 provides the unboxed views of the types
283 and a number of ``primitive operations'' (<tt/+&num/,
284 <tt/plusFloat&num/, etc.).
289 <label id="sec:Bits">
292 This library defines bitwise operations for signed and unsigned ints.
296 infixl 8 `shift`, `rotate`
302 (.&.), (.|.), xor :: a -> a -> a
304 shift :: a -> Int -> a
305 rotate :: a -> Int -> a
307 setBit :: a -> Int -> a
308 clearBit :: a -> Int -> a
309 complementBit :: a -> Int -> a
310 testBit :: a -> Int -> Bool
312 isSigned :: a -> Bool
314 shiftL, shiftR :: Bits a => a -> Int -> a
315 rotateL, rotateR :: Bits a => a -> Int -> a
316 shiftL a i = shift a i
317 shiftR a i = shift a (-i)
318 rotateL a i = rotate a i
319 rotateR a i = rotate a (-i)
325 <tt/bitSize/ and <tt/isSigned/ are like <tt/floatRadix/ and <tt/floatDigits/
326 -- they return parameters of the <em/type/ of their argument rather than
327 of the particular argument they are applied to. <tt/bitSize/ returns
328 the number of bits in the type (or <tt/Nothing/ for unbounded types); and
329 <tt/isSigned/ returns whether the type is signed or not.
331 <tt/shift/ performs sign extension.
332 That is, right shifts fill the top bits with 1 if the number is negative
333 and with 0 otherwise.
334 (Since unsigned types are always positive, the top bit is always filled with
337 Bits are numbered from 0 with bit 0 being the least significant bit.
339 <tt/shift x i/ and <tt/rotate x i/ shift to the left if <tt/i/ is
340 positive and to the right otherwise.
343 <tt/rotate/ is well defined only if bitSize returns a number.
344 (Maybe we should impose a Bounded constraint on it?)
347 <tt/bit i/ is the value with the i'th bit set.
351 <label id="sec:Word">
354 This library provides unsigned integers of various sizes.
355 The types supported are as follows:
358 type | number of bits @
367 For each type <it/W/ above, we provide the following functions and
368 instances. The type <it/I/ refers to the signed integer type of the
372 data W -- Unsigned Ints
387 word8ToWord32 :: Word8 -> Word32
388 word32ToWord8 :: Word32 -> Word8
389 word16ToWord32 :: Word16 -> Word32
390 word32ToWord16 :: Word32 -> Word16
392 word8ToInt :: Word8 -> Int
393 intToWord8 :: Int -> Word8
394 word16ToInt :: Word16 -> Int
395 intToWord16 :: Int -> Word16
396 word32ToInt :: Word32 -> Int
397 intToWord32 :: Int -> Word32
403 All arithmetic is performed modulo 2^n
405 One non-obvious consequequence of this is that <tt/negate/
406 should <em/not/ raise an error on negative arguments.
409 The coercion <tt/wToI/ converts an unsigned n-bit value to the
410 signed n-bit value with the same representation. For example,
411 <tt/word8ToInt8 0xff = -1/.
412 Likewise, <tt/iToW/ converts signed n-bit values to the
413 corresponding unsigned n-bit value.
416 ToDo: complete the set of coercion functions.
419 Use <tt/Prelude.fromIntegral :: (Integral a, Num b) => a -> b/ to
420 coerce between different sizes or to preserve sign when converting
421 between values of the same size.
424 It would be very natural to add a type a type <tt/Natural/ providing
425 an unbounded size unsigned integer --- just as <tt/Integer/ provides
426 unbounded size signed integers. We do not do that yet since there is
427 no demand for it. Doing so would require <tt/Bits.bitSize/ to return
431 The <tt/Enum/ instances stop when they reach their upper or lower
432 bound --- they don't overflow the way the <tt/Int/ and <tt/Float/
436 It would be useful to provide a function (or a family of functions?)
437 which coerced between any two Word types (without going through
442 Hugs only provides <tt/Eq/, <tt/Ord/, <tt/Read/ and <tt/Show/
443 instances for <tt/Word64/ at the moment.
449 This library provides signed integers of various sizes. The types
450 supported are as follows:
453 type | number of bits @
462 For each type <it/I/ above, we provide the following instances.
465 data I -- Signed Ints
466 iToInt :: I -> Int -- not provided for Int64
467 intToi :: Int -> I -- not provided for Int64
482 int8ToInt :: Int8 -> Int
483 intToInt8 :: Int -> Int8
484 int16ToInt :: Int16 -> Int
485 intToInt16 :: Int -> Int16
486 int32ToInt :: Int32 -> Int
487 intToInt32 :: Int -> Int32
492 Hugs does not provide <tt/Int64/ at the moment.
495 ToDo: complete the set of coercion functions.
500 <label id="sec:Addr">
503 This library provides machine addresses and is primarily intended for
504 use in creating foreign function interfaces using GreenCard.
508 data Addr -- Address type
512 plusAddr :: Addr -> Int -> Addr
514 -- read value out of _immutable_ memory
515 indexCharOffAddr :: Addr -> Int -> Char
516 indexIntOffAddr :: Addr -> Int -> Int -- should we drop this?
517 indexAddrOffAddr :: Addr -> Int -> Addr
518 indexFloatOffAddr :: Addr -> Int -> Float
519 indexDoubleOffAddr :: Addr -> Int -> Double
520 indexWord8OffAddr :: Addr -> Int -> Word8
521 indexWord16OffAddr :: Addr -> Int -> Word16
522 indexWord32OffAddr :: Addr -> Int -> Word32
523 indexWord64OffAddr :: Addr -> Int -> Word64
524 indexInt8OffAddr :: Addr -> Int -> Int8
525 indexInt16OffAddr :: Addr -> Int -> Int16
526 indexInt32OffAddr :: Addr -> Int -> Int32
527 indexInt64OffAddr :: Addr -> Int -> Int64
529 -- read value out of mutable memory
530 readCharOffAddr :: Addr -> Int -> IO Char
531 readIntOffAddr :: Addr -> Int -> IO Int -- should we drop this?
532 readAddrOffAddr :: Addr -> Int -> IO Addr
533 readFloatOffAddr :: Addr -> Int -> IO Float
534 readDoubleOffAddr :: Addr -> Int -> IO Double
535 readWord8OffAddr :: Addr -> Int -> IO Word8
536 readWord16OffAddr :: Addr -> Int -> IO Word16
537 readWord32OffAddr :: Addr -> Int -> IO Word32
538 readWord64OffAddr :: Addr -> Int -> IO Word64
539 readInt8OffAddr :: Addr -> Int -> IO Int8
540 readInt16OffAddr :: Addr -> Int -> IO Int16
541 readInt32OffAddr :: Addr -> Int -> IO Int32
542 readInt64OffAddr :: Addr -> Int -> IO Int64
544 -- write value into mutable memory
545 writeCharOffAddr :: Addr -> Int -> Char -> IO ()
546 writeIntOffAddr :: Addr -> Int -> Int -> IO () -- should we drop this?
547 writeAddrOffAddr :: Addr -> Int -> Addr -> IO ()
548 writeFloatOffAddr :: Addr -> Int -> Float -> IO ()
549 writeDoubleOffAddr :: Addr -> Int -> Double -> IO ()
550 writeWord8OffAddr :: Addr -> Int -> Word8 -> IO ()
551 writeWord16OffAddr :: Addr -> Int -> Word16 -> IO ()
552 writeWord32OffAddr :: Addr -> Int -> Word32 -> IO ()
553 writeWord64OffAddr :: Addr -> Int -> Word64 -> IO ()
554 writeInt8OffAddr :: Addr -> Int -> Int8 -> IO ()
555 writeInt16OffAddr :: Addr -> Int -> Int16 -> IO ()
556 writeInt32OffAddr :: Addr -> Int -> Int32 -> IO ()
557 writeInt64OffAddr :: Addr -> Int -> Int64 -> IO ()
560 Hugs provides <tt/Addr/ and <tt/nullAddr/ but does not provide any of
561 the index, read or write functions. They can be implemented using
562 GreenCard if required.
565 <label id="sec:NumExts">
568 The <tt/NumExts/ interface collect together various numeric
569 operations that have proven to be commonly useful
572 -- Going between Doubles and Floats:
573 doubleToFloat :: Double -> Float
574 floatToDouble :: Float -> Double
576 showHex :: Integral a => a -> ShowS
577 showOct :: Integral a => a -> ShowS
583 If <tt/doubleToFloat/ is applied to a <tt/Double/ that is within
584 the representable range for <tt/Float/, the result may be the next
585 higher or lower representable <tt/Float/ value. If the <tt/Double/
586 is out of range, the result is undefined.
588 No loss of precision occurs in the other direction with
589 <tt/floatToDouble/, the floating value remains unchanged.
591 <tt/showOct/ and <tt/showHex/ will prefix <tt/0o/ and <tt/0x/
592 respectively. Like <tt/Numeric.showInt/, these show functions
593 work on positive numbers only.
597 <label id="sec:Foreign">
600 This module is provided by GHC but not by Hugs.
601 GreenCard for Hugs provides the <tt/ForeignObj/ type.
603 <sect> <idx/Concurrent/
604 <label id="sec:Concurrent">
607 This library provides the Concurrent Haskell extensions
608 <cite id="concurrentHaskell:popl96">.
610 We are grateful to the Glasgow Haskell Project for allowing us to
611 redistribute their implementation of this module.
614 module Concurrent where
616 data ThreadId -- thread identifiers
618 instance Ord ThreadId
620 forkIO :: IO () -> IO ThreadId
621 killThread :: ThreadId -> IO ()
623 data MVar a -- Synchronisation variables
624 newEmptyMVar :: IO (MVar a)
625 newMVar :: a -> IO (MVar a)
626 takeMVar :: MVar a -> IO a
627 putMVar :: MVar a -> a -> IO ()
628 swapMVar :: MVar a -> a -> IO a
629 readMVar :: MVar a -> IO a
632 data Chan a -- channels
633 newChan :: IO (Chan a)
634 writeChan :: Chan a -> a -> IO ()
635 readChan :: Chan a -> IO a
636 dupChan :: Chan a -> IO (Chan a)
637 unReadChan :: Chan a -> a -> IO ()
638 getChanContents :: Chan a -> IO [a]
639 writeList2Chan :: Chan a -> [a] -> IO ()
641 data CVar a -- one element channels
642 newCVar :: IO (CVar a)
643 putCVar :: CVar a -> a -> IO ()
644 getCVar :: CVar a -> IO a
646 data QSem -- General/quantity semaphores
647 newQSem :: Int -> IO QSem
648 waitQSem :: QSem -> IO ()
649 signalQSem :: QSem -> IO ()
651 data QSemN -- General/quantity semaphores
652 newQSemN :: Int -> IO QSemN
653 waitQSemN :: QSemN -> Int -> IO ()
654 signalQSemN :: QSemN -> Int -> IO ()
656 type SampleVar a -- Sample variables
657 newEmptySampleVar:: IO (SampleVar a)
658 newSampleVar :: a -> IO (SampleVar a)
659 emptySampleVar :: SampleVar a -> IO ()
660 readSampleVar :: SampleVar a -> IO a
661 writeSampleVar :: SampleVar a -> a -> IO ()
668 GHC uses preemptive multitasking:
669 Context switches can occur at any time, except if you call a C
670 function (like \verb"getchar") that blocks waiting for input.
672 Hugs uses cooperative multitasking:
673 Context switches only occur when you use one of the primitives
674 defined in this module. This means that programs such as:
677 main = forkIO (write 'a') >> write 'b'
678 where write c = putChar c >> write c
681 will print either <tt/aaaaaaaaaaaaaa.../ or <tt/bbbbbbbbbbbb.../,
682 instead of some random interleaving of <tt/a/s and <tt/b/s.
684 In practice, cooperative multitasking is sufficient for writing
685 simple graphical user interfaces.
688 Hugs does not provide the functions <tt/mergeIO/ or <tt/nmergeIO/ since these
689 require preemptive multitasking.
692 Thread identities and <tt/killThread/ has not been implemented yet on
693 either system. The plan is that <tt/killThread/ will raise an IO
694 exception in the killed thread which it can catch --- perhaps allowing -->
695 --it to kill its children before exiting.
698 The <tt/Ord/ instance for <tt/ThreadId/s provides an arbitrary total ordering
699 which might be used to build an ordered binary tree, say.
704 <label id="sec:Pretty">
707 This library contains Simon Peyton Jones' implementation of John
708 Hughes's pretty printer combinators.
715 data Doc -- the Document datatype
717 -- The primitive Doc values
719 text :: String -> Doc
722 integer :: Integer -> Doc
723 float :: Float -> Doc
724 double :: Double -> Doc
725 rational :: Rational -> Doc
726 semi, comma, colon, space, equals :: Doc
727 lparen, rparen, lbrack, rbrack, lbrace, rbrace :: Doc
728 parens, brackets, braces :: Doc -> Doc
729 quotes, doubleQuotes :: Doc -> Doc
731 -- Combining Doc values
732 (<>) :: Doc -> Doc -> Doc -- Beside
733 hcat :: [Doc] -> Doc -- List version of <>
734 (<+>) :: Doc -> Doc -> Doc -- Beside, separated by space
735 hsep :: [Doc] -> Doc -- List version of <+>
736 ($$) :: Doc -> Doc -> Doc -- Above; if there is no
737 -- overlap it "dovetails" the two
738 vcat :: [Doc] -> Doc -- List version of $$
739 cat :: [Doc] -> Doc -- Either hcat or vcat
740 sep :: [Doc] -> Doc -- Either hsep or vcat
741 fcat :: [Doc] -> Doc -- ``Paragraph fill'' version of cat
742 fsep :: [Doc] -> Doc -- ``Paragraph fill'' version of sep
743 nest :: Int -> Doc -> Doc -- Nested
744 hang :: Doc -> Int -> Doc -> Doc
745 punctuate :: Doc -> [Doc] -> [Doc]
746 -- punctuate p [d1, ... dn] = [d1 <> p, d2 <> p, ... dn-1 <> p, dn]
748 -- Displaying Doc values
750 render :: Doc -> String -- Uses default style
751 renderStyle :: Style -> Doc -> String
752 data Style = Style { lineLength :: Int, -- In chars
753 ribbonsPerLine :: Float, -- Ratio of ribbon length
757 data Mode = PageMode -- Normal
758 | ZigZagMode -- With zig-zag cuts
759 | LeftMode -- No indentation, infinitely long lines
760 | OneLineMode -- All on one line
763 <biblio files="refs" style="abbrv">