-<!doctype linuxdoc system>
+<!doctype linuxdoc system [
+ <!ENTITY addr SYSTEM "Addr.sgml">
+ <!ENTITY bits SYSTEM "Bits.sgml">
+ <!ENTITY concurrent SYSTEM "Concurrent.sgml">
+ <!ENTITY dynamic SYSTEM "Dynamic.sgml">
+ <!ENTITY exception SYSTEM "Exception.sgml">
+ <!ENTITY glaexts SYSTEM "GlaExts.sgml">
+ <!ENTITY ioexts SYSTEM "IOExts.sgml">
+ <!ENTITY int SYSTEM "Int.sgml">
+ <!ENTITY ndset SYSTEM "NDSet.sgml">
+ <!ENTITY numexts SYSTEM "NumExts.sgml">
+ <!ENTITY pretty SYSTEM "Pretty.sgml">
+ <!ENTITY st SYSTEM "ST.sgml">
+ <!ENTITY weak SYSTEM "Weak.sgml">
+ <!ENTITY word SYSTEM "Word.sgml">
+]>
<!-- ToDo:
o Add indexing support (to linuxdoc)
<article>
<title>The Hugs-GHC Extension Libraries
-<author>The Hugs/GHC Team
-<date>August 1998
+<author>Alastair Reid <tt/reid-alastair@cs.yale.edu/
+ Simon Marlow <tt/simonm@dcs.gla.ac.uk/
+<date>v0.8, 28 January 1998
<abstract>
Hugs and GHC provide a common set of libraries to aid portability.
This document specifies the interfaces to these libraries and documents
-known differences.
+known differences. We hope that these modules will be adopted for inclusion
+as Standard Haskell Libraries sometime soon.
</abstract>
<toc>
the form <tt/getXContents/, e.g., <tt/Channel.getChanContents/ and
<tt/IO.hGetContents/. (OK, so the latter isn't called
<tt/getHandleContents/, but you hopefully get the picture.)
-<item>
-Overloaded operators that convert values to some fixed type are named
-<tt/toX/, where <tt/X/ is the type we're converting into, e.g.,
-<tt/toInt/, <tt/toDyn/.
-<p>
-Similarly for overloaded coercion operations that go the other way,
-from a known type to an overloaded one. These have the prefix
-<tt/from/ followed by the name of the type we're converting from,
-e.g., <tt/fromInteger/, <tt/fromDyn/, <tt/fromDynamic/.
-
</itemize>
-<sect> <idx/ST/
-<label id="sec:ST">
-<p>
-
-This library provides support for <em/strict/ state threads, as
-described in the PLDI '94 paper by John Launchbury and Simon Peyton
-Jones <cite id="LazyStateThreads">. In addition to the monad <tt/ST/,
-it also provides mutable variables <tt/STRef/ and mutable arrays
-<tt/STArray/.
-
-<tscreen><verb>
-module ST( module ST, module Monad ) where
-import Monad
-
-data ST s a -- abstract type
-runST :: forall a. (forall s. ST s a) -> a
-fixST :: (a -> ST s a) -> ST s a
-unsafeInterleaveST :: ST s a -> ST s a
-instance Functor (ST s)
-instance Monad (ST s)
-
-data STRef s a -- mutable variables in state thread s
- -- containing values of type a.
-newSTRef :: a -> ST s (STRef s a)
-readSTRef :: STRef s a -> ST s a
-writeSTRef :: STRef s a -> a -> ST s ()
-instance Eq (STRef s a)
+<!-- ========================= -->
-data STArray s ix elt -- mutable arrays in state thread s
- -- indexed by values of type ix
- -- containing values of type a.
-newSTArray :: Ix ix => (ix,ix) -> elt -> ST s (STArray s ix elt)
-boundsSTArray :: Ix ix => STArray s ix elt -> (ix, ix)
-readSTArray :: Ix ix => STArray s ix elt -> ix -> ST s elt
-writeSTArray :: Ix ix => STArray s ix elt -> ix -> elt -> ST s ()
-thawSTArray :: Ix ix => Array ix elt -> ST s (STArray s ix elt)
-freezeSTArray :: Ix ix => STArray s ix elt -> ST s (Array ix elt)
-unsafeFreezeSTArray :: Ix ix => STArray s ix elt -> ST s (Array ix elt)
-instance Eq (STArray s ix elt)
-</verb></tscreen>
-
-Notes:
-<itemize>
-
-<item>
-GHC also supports ByteArrays --- these aren't supported by Hugs yet.
-
-<item>
-The operations <tt/freezeSTArray/ and <tt/thawSTArray/ convert mutable
-arrays to and from immutable arrays. Semantically, they are identical
-to copying the array and they are usually implemented that way. The
-operation <tt/unsafeFreezeSTArray/ is a faster version of
-<tt/freezeSTArray/ which omits the copying step. It's a safe substitute for
-<tt/freezeSTArray/ if you don't modify the mutable array after freezing it.
-
-<item>
-In the current version of Hugs, the <tt/<idx/runST// operation,
-used to specify encapsulation, is implemented as a language construct,
-and <tt/runST/ is treated as a keyword. We plan to change this to match
-GHC soon.
-
-<!--
- <item>
- Note that it is possible to install Hugs 1.4 without support for lazy
- state threads, and hence the primitives described here may not be
- available in all implementations. Also, in contrast with the
- implementation of lazy state threads in previous releases of Hugs and
- Gofer, there is no direct relationship between the
- <tt/<idx/ST monad// and the <tt/<idx/IO monad//.
- -->
+&addr
+&bits
+&concurrent
+&dynamic
+&exception
-<item>
-Hugs provides <tt/thenLazyST/ and <tt/thenStrictST/ so that you can
-import <tt/LazyST/ (say) and still use the strict instance in those
-places where it matters. GHC implements LazyST and ST using different
-types, so this isn't possible.
-</item>
+<sect> <idx/Foreign/
+<label id="sec:Foreign">
+<p>
+This module is provided by GHC but not by Hugs.
+GreenCard for Hugs provides the <tt/ForeignObj/ type.
-</itemize>
+&glaexts
+&ioexts
+&int
<sect> <idx/LazyST/
<label id="sec:LazyST">
state thread passed to <tt/strictToLazyST/ is not performed until the
result of the lazy state thread it returns is demanded.
-<sect> <idx/IOExts/
-<label id="sec:IOExts">
-<p>
-
-This library provides the following extensions to the IO monad:
-
-<tscreen><verb>
-module IOExts where
-
-fixIO :: (a -> IO a) -> IO a
-unsafePerformIO :: IO a -> a
-unsafeInterleaveIO :: IO a -> IO a
-
-data IORef a -- mutable variables containing values of type a
-newIORef :: a -> IO (IORef a)
-readIORef :: IORef a -> IO a
-writeIORef :: IORef a -> a -> IO ()
-instance Eq (IORef a)
-
-data IOArray ix elt -- mutable arrays indexed by values of type ix
- -- containing values of type a.
-newIOArray :: Ix ix => (ix,ix) -> elt -> IO (IOArray ix elt)
-boundsIOArray :: Ix ix => IOArray ix elt -> (ix, ix)
-readIOArray :: Ix ix => IOArray ix elt -> ix -> IO elt
-writeIOArray :: Ix ix => IOArray ix elt -> ix -> elt -> IO ()
-freezeIOArray :: Ix ix => IOArray ix elt -> IO (Array ix elt)
-instance Eq (IOArray ix elt)
-
-openFileEx :: FilePath -> IOModeEx -> IO Handle
-data IOModeEx = BinaryMode IO.IOMode | TextMode IO.IOMode
-instance Eq IOModeEx
-instance Read IOModeEx
-instance Show IOModeEx
-
-performGC :: IO ()
-trace :: String -> a -> a
-unsafePtrEq :: a -> a -> Bool
-
-unsafeIOToST :: IO a -> ST s a
-</verb></tscreen>
-
-<itemize>
-<item>
-The operations <tt/fixIO/, <tt/unsafePerformIO/ and <tt/unsafeInterleaveIO/
-described in <cite id="ImperativeFP">
-
-<item>
-References (aka mutable variables) and mutable arrays (but no form of
-mutable byte arrays)
-
-<item>
-<tt/openFileEx/ extends the standard <tt/openFile/ action with support
-for opening binary files. On platforms that make no distinction
-between text and binary files, <tt/openFileEx/ is indistinguishable
-from <tt/openFile/.
-
-<item>
-<tt/performGC/ triggers an immediate garbage collection
-
-<item>
-When called, <tt/trace/ prints the string in its first argument, and then
-returns the second argument as its result. The <tt/trace/ function is not
-referentially transparent, and should only be used for debugging, or for
-monitoring execution.
-
-<!--
- You should also be warned that, unless you understand some of the
- details about the way that Haskell programs are executed, results
- obtained using <tt/trace/ can be rather confusing. For example, the
- messages may not appear in the order that you expect. Even ignoring the
- output that they produce, adding calls to <tt/trace/ can change the
- semantics of your program. Consider this a warning!
- -->
-
-<item>
-<tt/unsafePtrEq/ compares two values for pointer equality without
-evaluating them. The results are not referentially transparent and
-may vary significantly from one compiler to another or in the face of
-semantics-preserving program changes. However, pointer equality is useful
-in creating a number of referentially transparent constructs such as this
-simplified memoisation function:
-
-<tscreen><verb>
-> cache :: (a -> b) -> (a -> b)
-> cache f = \x -> unsafePerformIO (check x)
-> where
-> ref = unsafePerformIO (newIORef (error "cache", error "cache"))
-> check x = readIORef ref >>= \ (x',a) ->
-> if x `unsafePtrEq` x' then
-> return a
-> else
-> let a = f x in
-> writeIORef ref (x, a) >>
-> return a
-</verb></tscreen>
-
-<item>
-The <tt/unsafeIOToST/ action provides a loop hole for lifting an
-<tt/IO/ action into the <tt/ST/ monad. This is a potentially unsafe
-thing to do, so the onus is on the programmer to ensure that the
-use of <tt/unsafeIOToST/ does not ruin underlying program properties
-such as referential transparency.
-</itemize>
-
-<!--
- <sect> <idx/GlaExts/ <p>
-
- This library provides a convenient bundle of most of the extensions
- available in GHC and Hugs. This module is generally more stable than
- the other modules of non-standard extensions so you might choose to
- import them from here rather than going straight to the horses mouth.
-
- <tscreen><verb>
- module GlaExts( module GlaExts, module IOExts, module ST, module Addr ) where
- import IOExts
- import ST
- import Addr
- trace :: String -> a -> a
- performGC :: IO ()
- </verb></tscreen>
-
- The GHC version also provides the types <tt/PrimIO/, <tt/RealWorld/,
- <tt/ByteArray/, <tt/Lift/ and operations on these types. It also
- provides the unboxed views of the types
- <tt/Int/,
- <tt/Addr/,
- <tt/Word/,
- <tt/Float/,
- <tt/Double/,
- <tt/Integer/ and
- <tt/Char/
- and a number of ``primitive operations'' (<tt/+&num/,
- <tt/plusFloat&num/, etc.).
-
- -->
-
-<sect> <idx/Bits/
-<label id="sec:Bits">
-<p>
-
-This library defines bitwise operations for signed and unsigned ints.
-
-<tscreen><verb>
-module Bits where
-infixl 8 `shift`, `rotate`
-infixl 7 .&.
-infixl 6 `xor`
-infixl 5 .|.
-
-class Bits a where
- (.&.), (.|.), xor :: a -> a -> a
- complement :: a -> a
- shift :: a -> Int -> a
- rotate :: a -> Int -> a
- bit :: Int -> a
- setBit :: a -> Int -> a
- clearBit :: a -> Int -> a
- complementBit :: a -> Int -> a
- testBit :: a -> Int -> Bool
- bitSize :: a -> Int
- isSigned :: a -> Bool
-
-shiftL, shiftR :: Bits a => a -> Int -> a
-rotateL, rotateR :: Bits a => a -> Int -> a
-shiftL a i = shift a i
-shiftR a i = shift a (-i)
-rotateL a i = rotate a i
-rotateR a i = rotate a (-i)
-</verb></tscreen>
-
-Notes:
-<itemize>
-<item>
- <tt/bitSize/ and <tt/isSigned/ are like <tt/floatRadix/ and <tt/floatDigits/
- -- they return parameters of the <em/type/ of their argument rather than
- of the particular argument they are applied to. <tt/bitSize/ returns
- the number of bits in the type; and <tt/isSigned/ returns whether
- the type is signed or not.
-<item>
- <tt/shift/ performs sign extension on signed number types.
- That is, right shifts fill the top bits with 1 if the number is negative
- and with 0 otherwise.
-<item>
- Bits are numbered from 0 with bit 0 being the least significant bit.
-<item>
- <tt/shift x i/ and <tt/rotate x i/ shift to the left if <tt/i/ is
- positive and to the right otherwise.
-<!--
- <item>
- <tt/rotate/ is well defined only if bitSize returns a number.
- (Maybe we should impose a Bounded constraint on it?)
- -->
-<item>
- <tt/bit i/ is the value with the i'th bit set.
-</itemize>
-
-<sect> <idx/Word/
-<label id="sec:Word">
-<p>
-
-This library provides unsigned integers of various sizes.
-The types supported are as follows:
-
-<tabular ca="ll">
-type | number of bits @
-<!-- <hline> -->
-Word8 | 8 @
-Word16 | 16 @
-Word32 | 32 @
-Word64 | 64 @
-<!-- <hline> -->
-</tabular>
-
-For each type <it/W/ above, we provide the following functions and
-instances. The type <it/I/ refers to the signed integer type of the
-same size.
-
-<tscreen><verb>
-data W -- Unsigned Ints
-instance Eq W
-instance Ord W
-instance Show W
-instance Read W
-instance Bounded W
-instance Num W
-instance Real W
-instance Integral W
-instance Enum W
-instance Ix W
-instance Bits W
-</verb></tscreen>
-Plus
-<tscreen><verb>
-word8ToWord32 :: Word8 -> Word32
-word32ToWord8 :: Word32 -> Word8
-word16ToWord32 :: Word16 -> Word32
-word32ToWord16 :: Word32 -> Word16
-
-word8ToInt :: Word8 -> Int
-intToWord8 :: Int -> Word8
-word16ToInt :: Word16 -> Int
-intToWord16 :: Int -> Word16
-word32ToInt :: Word32 -> Int
-intToWord32 :: Int -> Word32
-</verb></tscreen>
-
-Notes:
-<itemize>
-<item>
- All arithmetic is performed modulo 2^n
-
- One non-obvious consequequence of this is that <tt/negate/
- should <em/not/ raise an error on negative arguments.
-
-<item>
-The coercion <tt/wToI/ converts an unsigned n-bit value to the
-signed n-bit value with the same representation. For example,
-<tt/word8ToInt8 0xff = -1/.
-Likewise, <tt/iToW/ converts signed n-bit values to the
-corresponding unsigned n-bit value.
-
-<item>
-ToDo: complete the set of coercion functions.
-
-<item>
-Use <tt/Prelude.fromIntegral :: (Integral a, Num b) => a -> b/ to
-coerce between different sizes or to preserve sign when converting
-between values of the same size.
-
-<item>
-It would be very natural to add a type a type <tt/Natural/ providing
-an unbounded size unsigned integer --- just as <tt/Integer/ provides
-unbounded size signed integers. We do not do that yet since there is
-no demand for it. Doing so would require <tt/Bits.bitSize/ to return
-<tt/Maybe Int/.
-
-<item>
-The <tt/Enum/ instances stop when they reach their upper or lower
-bound --- they don't overflow the way the <tt/Int/ and <tt/Float/
-instances do.
-
-<item>
-It would be useful to provide a function (or a family of functions?)
-which coerced between any two Word types (without going through
-Integer).
-
-</itemize>
-
-Hugs only provides <tt/Eq/, <tt/Ord/, <tt/Read/ and <tt/Show/
-instances for <tt/Word64/ at the moment.
-
-<sect> <idx/Int/
-<label id="sec:Int">
-<p>
-
-This library provides signed integers of various sizes. The types
-supported are as follows:
-
-<tabular ca="ll">
-type | number of bits @
-<!-- <hline> -->
-Int8 | 8 @
-Int16 | 16 @
-Int32 | 32 @
-Int64 | 64 @
-<!-- <hline> -->
-</tabular>
-
-For each type <it/I/ above, we provide the following instances.
-
-<tscreen><verb>
-data I -- Signed Ints
-iToInt :: I -> Int -- not provided for Int64
-intToi :: Int -> I -- not provided for Int64
-instance Eq I
-instance Ord I
-instance Show I
-instance Read I
-instance Bounded I
-instance Num I
-instance Real I
-instance Integral I
-instance Enum I
-instance Ix I
-instance Bits I
-</verb></tscreen>
-Plus
-<tscreen><verb>
-int8ToInt :: Int8 -> Int
-intToInt8 :: Int -> Int8
-int16ToInt :: Int16 -> Int
-intToInt16 :: Int -> Int16
-int32ToInt :: Int32 -> Int
-intToInt32 :: Int -> Int32
-</verb></tscreen>
-
-<itemize>
-<item>
-Hugs does not provide <tt/Int64/ at the moment.
-
-<item>
-ToDo: complete the set of coercion functions.
-
-</itemize>
-
-<sect> <idx/Addr/
-<label id="sec:Addr">
-<p>
-
-This library provides machine addresses and is primarily intended for
-use in creating foreign function interfaces using GreenCard.
-
-<tscreen><verb>
-module Addr where
-data Addr -- Address type
-instance Eq Addr
-
-nullAddr :: Addr
-plusAddr :: Addr -> Int -> Addr
-
--- read value out of _immutable_ memory
-indexCharOffAddr :: Addr -> Int -> Char
-indexIntOffAddr :: Addr -> Int -> Int -- should we drop this?
-indexAddrOffAddr :: Addr -> Int -> Addr
-indexFloatOffAddr :: Addr -> Int -> Float
-indexDoubleOffAddr :: Addr -> Int -> Double
-indexWord8OffAddr :: Addr -> Int -> Word8
-indexWord16OffAddr :: Addr -> Int -> Word16
-indexWord32OffAddr :: Addr -> Int -> Word32
-indexWord64OffAddr :: Addr -> Int -> Word64
-indexInt8OffAddr :: Addr -> Int -> Int8
-indexInt16OffAddr :: Addr -> Int -> Int16
-indexInt32OffAddr :: Addr -> Int -> Int32
-indexInt64OffAddr :: Addr -> Int -> Int64
-
--- read value out of mutable memory
-readCharOffAddr :: Addr -> Int -> IO Char
-readIntOffAddr :: Addr -> Int -> IO Int -- should we drop this?
-readAddrOffAddr :: Addr -> Int -> IO Addr
-readFloatOffAddr :: Addr -> Int -> IO Float
-readDoubleOffAddr :: Addr -> Int -> IO Double
-readWord8OffAddr :: Addr -> Int -> IO Word8
-readWord16OffAddr :: Addr -> Int -> IO Word16
-readWord32OffAddr :: Addr -> Int -> IO Word32
-readWord64OffAddr :: Addr -> Int -> IO Word64
-readInt8OffAddr :: Addr -> Int -> IO Int8
-readInt16OffAddr :: Addr -> Int -> IO Int16
-readInt32OffAddr :: Addr -> Int -> IO Int32
-readInt64OffAddr :: Addr -> Int -> IO Int64
-
--- write value into mutable memory
-writeCharOffAddr :: Addr -> Int -> Char -> IO ()
-writeIntOffAddr :: Addr -> Int -> Int -> IO () -- should we drop this?
-writeAddrOffAddr :: Addr -> Int -> Addr -> IO ()
-writeFloatOffAddr :: Addr -> Int -> Float -> IO ()
-writeDoubleOffAddr :: Addr -> Int -> Double -> IO ()
-writeWord8OffAddr :: Addr -> Int -> Word8 -> IO ()
-writeWord16OffAddr :: Addr -> Int -> Word16 -> IO ()
-writeWord32OffAddr :: Addr -> Int -> Word32 -> IO ()
-writeWord64OffAddr :: Addr -> Int -> Word64 -> IO ()
-writeInt8OffAddr :: Addr -> Int -> Int8 -> IO ()
-writeInt16OffAddr :: Addr -> Int -> Int16 -> IO ()
-writeInt32OffAddr :: Addr -> Int -> Int32 -> IO ()
-writeInt64OffAddr :: Addr -> Int -> Int64 -> IO ()
-</verb></tscreen>
-
-Hugs provides <tt/Addr/ and <tt/nullAddr/ but does not provide any of
-the index, read or write functions. They can be implemented using
-GreenCard if required.
-
-<sect> <idx/NumExts/
-<label id="sec:NumExts">
-<p>
-
-The <tt/NumExts/ interface collect together various numeric
-operations that have proven to be commonly useful
-
-<tscreen> <verb>
--- Going between Doubles and Floats:
-doubleToFloat :: Double -> Float
-floatToDouble :: Float -> Double
-
-showHex :: Integral a => a -> ShowS
-showOct :: Integral a => a -> ShowS
-</verb> </tscreen>
-
-Notes:
-<itemize>
-<item>
- If <tt/doubleToFloat/ is applied to a <tt/Double/ that is within
- the representable range for <tt/Float/, the result may be the next
- higher or lower representable <tt/Float/ value. If the <tt/Double/
- is out of range, the result is undefined.
-<item>
- No loss of precision occurs in the other direction with
- <tt/floatToDouble/, the floating value remains unchanged.
-<item>
- <tt/showOct/ and <tt/showHex/ will prefix <tt/0o/ and <tt/0x/
- respectively. Like <tt/Numeric.showInt/, these show functions
- work on positive numbers only.
-</itemize>
-
-<sect> <idx/Foreign/
-<label id="sec:Foreign">
-<p>
-
-This module provides two types to better allow the Haskell world to
-share its data with the outside world (and vice versa), <em/foreign
-objects/ and <em/stable pointers/:
-
-<tscreen><verb>
-module Foreign where
-data ForeignObj -- abstract, instance of: Eq
-
-makeForeignObj :: Addr{-object-} -> Addr{-finaliser-} -> IO ForeignObj
-writeForeignObj :: ForeignObj -> Addr{-new value-} -> IO ()
-
-data StablePtr a -- abstract, instance of: Eq.
-makeStablePtr :: a -> IO (StablePtr a)
-deRefStablePtr :: StablePtr a -> IO a
-freeStablePtr :: StablePtr a -> IO ()
-</verb> </tscreen>
-
-<itemize>
-<item>The <tt/ForeignObj/ type provides foreign objects, encapsulated
-references to values outside the Haskell heap. Foreign objects are
-finalised by the garbage collector when they become dead. The
-finaliser to use is given as second argument to <tt/makeForeignOj/,
-and is currently a function pointer to a C function with
-the following signature
-
-<tscreen><verb>
-void finaliseFO(void* obj);
-</verb></tscreen>
-
-The finaliser is passed the reference to the external object (i.e.,
-the first argument to <tt/makeForeignObj/.)
-
-<item>
-The <tt/writeForeignObj/ lets you overwrite the encapsulated foreign
-reference with another.
-
-<item>
-Stable pointers allow you to hand out references to Haskell heap
-objects to the outside world. <bf/ToDo:/ <em/say more./
-</itemize>
-
-In addition to the above, the following operations for indexing via
-a <tt/ForeignObj/ are also, mirrored on the same operations provided
-over <tt/Addr/s:
-
-<tscreen><verb>
-indexCharOffForeignObj :: ForeignObj -> Int -> Char
-indexIntOffForeignObj :: ForeignObj -> Int -> Int
-indexAddrOffForeignObj :: ForeignObj -> Int -> Addr
-indexFloatOffForeignObj :: ForeignObj -> Int -> Float
-indexDoubleOffForeignObj :: ForeignObj -> Int -> Double
-indexWord8OffForeignObj :: ForeignObj -> Int -> Word8
-indexWord16OffForeignObj :: ForeignObj -> Int -> Word16
-indexWord32OffForeignObj :: ForeignObj -> Int -> Word32
-indexWord64OffForeignObj :: ForeignObj -> Int -> Word64
-
-indexInt8OffForeignObj :: ForeignObj -> Int -> Int8
-indexInt16OffForeignObj :: ForeignObj -> Int -> Int16
-indexInt32OffForeignObj :: ForeignObj -> Int -> Int32
-indexInt64OffForeignObj :: ForeignObj -> Int -> Int64
-
--- read value out of mutable memory
-readCharOffForeignObj :: ForeignObj -> Int -> IO Char
-readIntOffForeignObj :: ForeignObj -> Int -> IO Int
-readAddrOffForeignObj :: ForeignObj -> Int -> IO Addr
-readFloatOffForeignObj :: ForeignObj -> Int -> IO Float
-readDoubleOffForeignObj :: ForeignObj -> Int -> IO Double
-readWord8OffForeignObj :: ForeignObj -> Int -> IO Word8
-readWord16OffForeignObj :: ForeignObj -> Int -> IO Word16
-readWord32OffForeignObj :: ForeignObj -> Int -> IO Word32
-readWord64OffForeignObj :: ForeignObj -> Int -> IO Word64
-readInt8OffForeignObj :: ForeignObj -> Int -> IO Int8
-readInt16OffForeignObj :: ForeignObj -> Int -> IO Int16
-readInt32OffForeignObj :: ForeignObj -> Int -> IO Int32
-readInt64OffForeignObj :: ForeignObj -> Int -> IO Int64
-
-writeCharOffForeignObj :: ForeignObj -> Int -> Char -> IO ()
-writeIntOffForeignObj :: ForeignObj -> Int -> Int -> IO ()
-writeAddrOffForeignObj :: ForeignObj -> Int -> Addr -> IO ()
-writeFloatOffForeignObj :: ForeignObj -> Int -> Float -> IO ()
-writeDoubleOffForeignObj :: ForeignObj -> Int -> Double -> IO ()
-writeWord8OffForeignObj :: ForeignObj -> Int -> Word8 -> IO ()
-writeWord16OffForeignObj :: ForeignObj -> Int -> Word16 -> IO ()
-writeWord32OffForeignObj :: ForeignObj -> Int -> Word32 -> IO ()
-writeWord64OffForeignObj :: ForeignObj -> Int -> Word64 -> IO ()
-writeInt8OffForeignObj :: ForeignObj -> Int -> Int8 -> IO ()
-writeInt16OffForeignObj :: ForeignObj -> Int -> Int16 -> IO ()
-writeInt32OffForeignObj :: ForeignObj -> Int -> Int32 -> IO ()
-writeInt64OffForeignObj :: ForeignObj -> Int -> Int64 -> IO ()
-</verb></tscreen>
-
-<sect> <idx/Concurrent/
-<label id="sec:Concurrent">
-<p>
-
-This library provides the Concurrent Haskell extensions
-<cite id="concurrentHaskell:popl96">.
-
-We are grateful to the Glasgow Haskell Project for allowing us to
-redistribute their implementation of this module.
-
-<tscreen><verb>
-module Concurrent where
-
-data ThreadId -- thread identifiers
-instance Eq ThreadId
-instance Ord ThreadId
-
-forkIO :: IO () -> IO ThreadId
-killThread :: ThreadId -> IO ()
-
-data MVar a -- Synchronisation variables
-newEmptyMVar :: IO (MVar a)
-newMVar :: a -> IO (MVar a)
-takeMVar :: MVar a -> IO a
-putMVar :: MVar a -> a -> IO ()
-swapMVar :: MVar a -> a -> IO a
-readMVar :: MVar a -> IO a
-instance Eq (MVar a)
-
-data Chan a -- channels
-newChan :: IO (Chan a)
-writeChan :: Chan a -> a -> IO ()
-readChan :: Chan a -> IO a
-dupChan :: Chan a -> IO (Chan a)
-unReadChan :: Chan a -> a -> IO ()
-getChanContents :: Chan a -> IO [a]
-writeList2Chan :: Chan a -> [a] -> IO ()
-
-data CVar a -- one element channels
-newCVar :: IO (CVar a)
-putCVar :: CVar a -> a -> IO ()
-getCVar :: CVar a -> IO a
-
-data QSem -- General/quantity semaphores
-newQSem :: Int -> IO QSem
-waitQSem :: QSem -> IO ()
-signalQSem :: QSem -> IO ()
-
-data QSemN -- General/quantity semaphores
-newQSemN :: Int -> IO QSemN
-waitQSemN :: QSemN -> Int -> IO ()
-signalQSemN :: QSemN -> Int -> IO ()
-
-type SampleVar a -- Sample variables
-newEmptySampleVar:: IO (SampleVar a)
-newSampleVar :: a -> IO (SampleVar a)
-emptySampleVar :: SampleVar a -> IO ()
-readSampleVar :: SampleVar a -> IO a
-writeSampleVar :: SampleVar a -> a -> IO ()
-</verb></tscreen>
-
-Notes:
-<itemize>
-
-<item>
- GHC uses preemptive multitasking:
- Context switches can occur at any time, except if you call a C
- function (like \verb"getchar") that blocks waiting for input.
-
- Hugs uses cooperative multitasking:
- Context switches only occur when you use one of the primitives
- defined in this module. This means that programs such as:
-
-<tscreen><verb>
-main = forkIO (write 'a') >> write 'b'
- where write c = putChar c >> write c
-</verb></tscreen>
-
- will print either <tt/aaaaaaaaaaaaaa.../ or <tt/bbbbbbbbbbbb.../,
- instead of some random interleaving of <tt/a/s and <tt/b/s.
-
- In practice, cooperative multitasking is sufficient for writing
- simple graphical user interfaces.
-
-<item>
-Hugs does not provide the functions <tt/mergeIO/ or <tt/nmergeIO/ since these
-require preemptive multitasking.
-
-<item>
-Thread identities and <tt/killThread/ has not been implemented yet on
-either system. The plan is that <tt/killThread/ will raise an IO
-exception in the killed thread which it can catch --- perhaps allowing -->
---it to kill its children before exiting.
-
-<item>
-The <tt/Ord/ instance for <tt/ThreadId/s provides an arbitrary total ordering
-which might be used to build an ordered binary tree, say.
-
-</itemize>
-
-<sect> <idx/Dynamic/
-<label id="sec:Dynamic">
-<p>
-
-The <tt/Dynamic/ library provides cheap-and-cheerful dynamic types for
-Haskell. A dynamically typed value is one which carries type
-information with it at run-time, and is represented by the
-abstract type <tt/Dynamic/. Values can be converted into <tt/Dynamic/
-ones, which can then be combined and manipulated by the program using
-the operations provided over the abstract, dynamic type. One of
-these operations allows you to convert a dynamically-typed value back
-into a value with the same (monomorphic) type it had before converting
-it into a dynamically-typed value.
-
-The <tt/Dynamic/ library is capable of dealing with monomorphic types
-only; no support for polymorphic dynamic values, but hopefully that
-can be added at a later stage.
-
-Examples where this library may come in handy (dynamic types, really -
-hopefully the library provided here will suffice) are: persistent
-programming, interpreters, distributed programming etc.
-
-The following operations are provided over the <tt/Dynamic/ type:
-
-<tscreen> <verb>
-data Dynamic -- abstract, instance of: Show --
-
-toDyn :: Typeable a => a -> Dynamic
-fromDyn :: Typeable a => Dynamic -> a -> a
-fromDynamic :: Typeable a => Dynamic -> Maybe a
-</verb></tscreen>
-
-<itemize>
-<item> <tt/toDyn/ converts a value into a dynamic one, provided
-<tt/toDyn/ knows the (concrete) type representation of the value.
-The <tt/Typeable/ type class is used to encode this, overloading a
-function that returns the type representation of a value. More on this
-below.
-<item> There's two ways of going from a dynamic value to one with
-a concrete type: <tt/fromDyn/, tries to convert the dynamic value into
-a value with the same type as its second argument. If this fails, the
-default second argument is just returned. <tt/fromDynamic/ returns a
-<tt/Maybe/ type instead, <tt/Nothing/ coming back if the conversion
-was not possible.
-<item>
-The <tt/Dynamic/ type has got a <tt/Show/ instance which returns
-a pretty printed string of the type of the dynamic value. (Useful when
-debugging).
-</itemize>
-
-<sect1> The <tt/Dynamic/ type
-<nidx/The Dynamic type/
-<label id="sec:Dynamic:TypeRep">
-<p>
-
-Haskell types are represented as terms using the <tt/TypeRep/
-abstract type:
-
-<tscreen> <verb>
-data TypeRep -- abstract, instance of: Eq, Show
-data TyCon -- abstract, instance of: Eq, Show
-
-mkTyCon :: String -> TyCon
-mkAppTy :: TyCon -> [TypeRep] -> TypeRep
-mkFunTy :: TypeRep -> TypeRep -> TypeRep
-applyTy :: TypeRep -> TypeRep -> Maybe TypeRep
-</verb></tscreen>
-
-<itemize>
-<item> <tt/mkAppTy/ applies a type constructor to a sequence of types,
-returning a type.
-<item> <tt/mkFunTy/ is a special case of <tt/mkAppTy/, applying
-the function type constructor to a pair of types.
-<item> <tt/applyTy/ applies a type to a function type. If possible,
-the result type is returned.
-<item> Type constructors are represented by the abstract type,
-<tt/TyCon/.
-<item>
-Most importantly, <tt/TypeRep/s can be compared for equality.
-Type equality is used when converting a <tt/Dynamic/ value into a
-value of some specific type, comparing the type representation that
-the <tt/Dynamic/ value embeds with equality of the type representation
-of the type we're trying to convert the dynamically-typed value into.
-<item>
-To allow comparisons between <tt/TypeRep/s to be implemented
-efficiently, the <em/abstract/ <tt/TyCon/ type is used, with
-the constructor function <tt/mkTyCon/ provided:
-
-<tscreen> <verb>
-mkTyCon :: String -> TyCon
-</verb></tscreen>
-
-An implementation of the <tt/Dynamic/ interface guarantees the
-following,
-
-<tscreen> <verb>
- mkTyCon "a" == mkTyCon "a"
-</verb></tscreen>
-
-A really efficient implementation is possible if we guarantee/demand
-that the strings are unique, and for a particular type constructor,
-the application <tt/mkTyCon/ to the string that represents the type
-constructor is never duplicated. Provided you follow the
-the author of <tt/Typeable/
-
- [<bf/Q:/ <em>Would this constraint be
-unworkable in practice?</em>]
-<item>
-Both <tt/TyCon/ and <tt/TypeRep/ are instances of the <tt/Show/ type
-classes. To have tuple types be shown in infix form, the <tt/Show/
-instance guarantees that type constructors consisting of <tt/n/-commas,
-i.e., (<tt/mkTyCon ",,,,"/), is shown as an <tt/(n+1)/ tuple in infix
-form.
-</itemize>
-
-<sect1> <idx/Representing types/
-<label id="sec:Dynamic:Typeable">
-<p>
-
-To ease the construction of <tt/Dynamic/ values, we
-introduce the following type class to help working with <tt/TypeRep/s:
-
-<tscreen><verb>
-class Typeable a where
- typeOf :: a -> TypeRep
-</verb></tscreen>
-
-<itemize>
-<item> The <tt/typeOf/ function is overloaded to return the type
-representation associated with a type.
-<item> <bf/Important:/ The argument to <tt/typeOf/ is only used to
-carry type information around so that overloading can be resolved.
-<tt/Typeable/ instances should never, ever look at this argument.
-<item> The <tt/Dynamic/ library provide <tt/Typeable/ instances
-for all Prelude and Hugs/GHC extension library types. They are:
-
-<tscreen><verb>
-Prelude types:
- Int, Char, Bool, Float, Double, Integer, (IO a),
- [a], (Either a b), (Maybe a), (a->b),
- (), (,), (,,), (,,,), (,,,,),
- Ordering, Complex, Array, Handle
-Hugs/GHC types:
- Addr, Word8, Word16, Word32, Word64,
- Int8,Int16,Int32,Int64,
- ForeignObj, MVar, (ST s a), (StablePtr a)
-GHC types:
- Word, ByteArray, MutableByteArray
-</verb></tscreen>
-
-</itemize>
-
-<sect1> <idx/Utility functions/
-<label id="sec:Dynamic:util">
-<p>
-
-Operations for applying a dynamic function type to a
-dynamically typed argument are commonly useful, and
-also provided:
-
-<tscreen> <verb>
-dynApply :: Dynamic -> Dynamic -> Dynamic -- unsafe.
-dynApplyMb :: Dynamic -> Dynamic -> Maybe Dynamic
-</verb></tscreen>
-
-
-<sect> <idx/GetOpt/
-<label id="sec:GetOpt">
-<p>
-
-The <tt/GetOpt/ library contains Sven Panne's Haskell implementation
-of <tt/getopt/, providing features nigh-on identical to GNU <tt/getopt/:
-
-<tscreen><verb>
-module GetOpt where
-
--- representing a single option:
-data OptDescr a
- = Option [Char] -- list of short option characters
- [String] -- list of long option strings (without "--")
- (ArgDescr a) -- argument descriptor
- String -- explanation of option for user
-
--- argument option:
-data ArgDescr a
- = NoArg a -- no argument expected
- | ReqArg (String -> a) String -- option requires argument
- | OptArg (Maybe String -> a) String -- optional argument
-
-usageInfo :: String -- header
- -> [OptDescr a] -- options recognised
- -> String -- nicely formatted decription of options
-
-getOpt :: ArgOrder a -- non-option handling
- -> [OptDescr a] -- options recognised
- -> [String] -- the command-line
- -> ( [a] -- options
- , [String] -- non-options
- ,[String] -- error messages
- )
-
-data ArgOrder a
- = RequireOrder
- | Permute
- | ReturnInOrder (String -> a)
-
-</verb></tscreen>
-
-<itemize>
-<item> The command-line options recognised is described by a list of
-<tt/OptDescr/ values. The <tt/OptDescr/ describes the long and short
-strings that recognise the option, together with a help string and
-info on whether the option takes extra arguments, if any.
-<item>
-From a list of option values, <tt/usageInfo/ returns a nicely
-formatted string that enumerates the different options supported
-together with a short message about what
-<item>
-To decode a command-line with respect to a list of options,
-<tt/getOpt/ is used. It processes the command-line, and returns
-the list of values that matched (and those that didn't). The first
-argument to <tt/getOpt/ controls whether the user is to give the
-options in any old order or not.
-</itemize>
-
-To hopefully illuminate the role of the different <tt/GetOpt/ data
-structures, here's the command-line options for a (very simple)
-compiler:
-
-<tscreen><verb>
-module Opts where
-
-import GetOpt
-import Maybe ( fromMaybe )
-
-data Flag
- = Verbose | Version
- | Input String | Output String | LibDir String
- deriving Show
-
-options :: [OptDescr Flag]
-options =
- [ Option ['v'] ["verbose"] (NoArg Verbose) "chatty output on stderr"
- , Option ['V','?'] ["version"] (NoArg Version) "show version number"
- , Option ['o'] ["output"] (OptArg outp "FILE") "output FILE"
- , Option ['c'] [] (OptArg inp "FILE") "input FILE"
- , Option ['L'] ["libdir"] (ReqArg LibDir "DIR") "library directory"
- ]
-
-inp,outp :: Maybe String -> Flag
-outp = Output . fromMaybe "stdout"
-inp = Input . fromMaybe "stdout"
-
-compilerOpts :: [String] -> IO ([Flag], [String])
-compilerOpts argv =
- case (getOpt Permute options argv) of
- (o,n,[] ) -> return (o,n)
- (_,_,errs) -> fail (userError (concat errs ++ usageInfo header options))
- where header = "Usage: ic [OPTION...] files..."
-</verb></tscreen>
-
-
-<sect> <idx/Pretty/
-<label id="sec:Pretty">
-<p>
-
-This library contains Simon Peyton Jones' implementation of John
-Hughes's pretty printer combinators.
-
-<tscreen><verb>
-module Pretty where
-infixl 6 <>
-infixl 6 <+>
-infixl 5 $$, $+$
-data Doc -- the Document datatype
-
--- The primitive Doc values
-empty :: Doc
-text :: String -> Doc
-char :: Char -> Doc
-int :: Int -> Doc
-integer :: Integer -> Doc
-float :: Float -> Doc
-double :: Double -> Doc
-rational :: Rational -> Doc
-semi, comma, colon, space, equals :: Doc
-lparen, rparen, lbrack, rbrack, lbrace, rbrace :: Doc
-parens, brackets, braces :: Doc -> Doc
-quotes, doubleQuotes :: Doc -> Doc
-
--- Combining Doc values
-(<>) :: Doc -> Doc -> Doc -- Beside
-hcat :: [Doc] -> Doc -- List version of <>
-(<+>) :: Doc -> Doc -> Doc -- Beside, separated by space
-hsep :: [Doc] -> Doc -- List version of <+>
-($$) :: Doc -> Doc -> Doc -- Above; if there is no
- -- overlap it "dovetails" the two
-vcat :: [Doc] -> Doc -- List version of $$
-cat :: [Doc] -> Doc -- Either hcat or vcat
-sep :: [Doc] -> Doc -- Either hsep or vcat
-fcat :: [Doc] -> Doc -- ``Paragraph fill'' version of cat
-fsep :: [Doc] -> Doc -- ``Paragraph fill'' version of sep
-nest :: Int -> Doc -> Doc -- Nested
-hang :: Doc -> Int -> Doc -> Doc
-punctuate :: Doc -> [Doc] -> [Doc]
--- punctuate p [d1, ... dn] = [d1 <> p, d2 <> p, ... dn-1 <> p, dn]
+&numexts
+&pretty
+&st
+&weak
+&word
--- Displaying Doc values
-instance Show Doc
-render :: Doc -> String -- Uses default style
-renderStyle :: Style -> Doc -> String
-data Style = Style { lineLength :: Int, -- In chars
- ribbonsPerLine :: Float, -- Ratio of ribbon length
- -- to line length
- mode :: Mode
- }
-data Mode = PageMode -- Normal
- | ZigZagMode -- With zig-zag cuts
- | LeftMode -- No indentation, infinitely long lines
- | OneLineMode -- All on one line
-</verb></tscreen>
+<!-- ========================= -->
<biblio files="refs" style="abbrv">
projects / ghc-hetmet.git / blobdiff