--- /dev/null
+%************************************************************************
+%* *
+<sect1>Miscellaneous libraries
+<label id="GHC-library">
+<p>
+<nidx>libraries, miscellaneous</nidx>
+<nidx>misc, syslib</nidx>
+%* *
+%************************************************************************
+
+This section describes a collection of Haskell libraries we've
+collected over the years. Access to any of these modules is provided
+by giving the @-syslib misc@<nidx>-syslib misc option</nidx>.
+
+%************************************************************************
+%* *
+<sect2>The @Bag@ type
+<label id="Bag">
+<p>
+<nidx>Bag module (GHC syslib)</nidx>
+%* *
+%************************************************************************
+
+A <em>bag</em> is an unordered collection of elements which may contain
+duplicates. To use, @import Bag@.
+
+<tscreen><verb>
+data Bag elt -- abstract
+
+emptyBag :: Bag elt
+unitBag :: elt -> Bag elt
+
+consBag :: elt -> Bag elt -> Bag elt
+snocBag :: Bag elt -> elt -> Bag elt
+
+unionBags :: Bag elt -> Bag elt -> Bag elt
+unionManyBags :: [Bag elt] -> Bag elt
+
+isEmptyBag :: Bag elt -> Bool
+elemBag :: Eq elt => elt -> Bag elt -> Bool
+
+filterBag :: (elt -> Bool) -> Bag elt -> Bag elt
+partitionBag :: (elt -> Bool) -> Bag elt-> (Bag elt, Bag elt)
+ -- returns the elements that do/don't satisfy the predicate
+
+concatBag :: Bag (Bag a) -> Bag a
+foldBag :: (r -> r -> r) -> (a -> r) -> r -> Bag a -> r
+mapBag :: (a -> b) -> Bag a -> Bag b
+
+listToBag :: [elt] -> Bag elt
+bagToList :: Bag elt -> [elt]
+</verb></tscreen>
+
+%************************************************************************
+%* *
+<sect2>The @FiniteMap@ type
+<label id="FiniteMap">
+<p>
+<nidx>FiniteMap module (GHC syslib)</nidx>
+%* *
+%************************************************************************
+
+What functional programmers call a <em>finite map</em>, everyone else
+calls a <em>lookup table</em>.
+
+Out code is derived from that in this paper:
+<quote>
+S Adams
+"Efficient sets: a balancing act"
+Journal of functional programming 3(4) Oct 1993, pages 553-562
+</quote>
+Guess what? The implementation uses balanced trees.
+
+<tscreen><verb>
+data FiniteMap key elt -- abstract
+
+-- BUILDING
+emptyFM :: FiniteMap key elt
+unitFM :: key -> elt -> FiniteMap key elt
+listToFM :: Ord key => [(key,elt)] -> FiniteMap key elt
+ -- In the case of duplicates, the last is taken
+
+-- ADDING AND DELETING
+ -- Throws away any previous binding
+ -- In the list case, the items are added starting with the
+ -- first one in the list
+addToFM :: Ord key => FiniteMap key elt -> key -> elt -> FiniteMap key elt
+addListToFM :: Ord key => FiniteMap key elt -> [(key,elt)] -> FiniteMap key elt
+
+ -- Combines with previous binding
+ -- In the combining function, the first argument is
+ -- the "old" element, while the second is the "new" one.
+addToFM_C :: Ord key => (elt -> elt -> elt)
+ -> FiniteMap key elt -> key -> elt
+ -> FiniteMap key elt
+addListToFM_C :: Ord key => (elt -> elt -> elt)
+ -> FiniteMap key elt -> [(key,elt)]
+ -> FiniteMap key elt
+
+ -- Deletion doesn't complain if you try to delete something
+ -- which isn't there
+delFromFM :: Ord key => FiniteMap key elt -> key -> FiniteMap key elt
+delListFromFM :: Ord key => FiniteMap key elt -> [key] -> FiniteMap key elt
+
+-- COMBINING
+ -- Bindings in right argument shadow those in the left
+plusFM :: Ord key => FiniteMap key elt -> FiniteMap key elt
+ -> FiniteMap key elt
+
+ -- Combines bindings for the same thing with the given function
+plusFM_C :: Ord key => (elt -> elt -> elt)
+ -> FiniteMap key elt -> FiniteMap key elt -> FiniteMap key elt
+
+minusFM :: Ord key => FiniteMap key elt -> FiniteMap key elt -> FiniteMap key elt
+ -- (minusFM a1 a2) deletes from a1 any bindings which are bound in a2
+
+intersectFM :: Ord key => FiniteMap key elt -> FiniteMap key elt -> FiniteMap key elt
+intersectFM_C :: Ord key => (elt -> elt -> elt)
+ -> FiniteMap key elt -> FiniteMap key elt -> FiniteMap key elt
+
+-- MAPPING, FOLDING, FILTERING
+foldFM :: (key -> elt -> a -> a) -> a -> FiniteMap key elt -> a
+mapFM :: (key -> elt1 -> elt2) -> FiniteMap key elt1 -> FiniteMap key elt2
+filterFM :: Ord key => (key -> elt -> Bool)
+ -> FiniteMap key elt -> FiniteMap key elt
+
+-- INTERROGATING
+sizeFM :: FiniteMap key elt -> Int
+isEmptyFM :: FiniteMap key elt -> Bool
+
+elemFM :: Ord key => key -> FiniteMap key elt -> Bool
+lookupFM :: Ord key => FiniteMap key elt -> key -> Maybe elt
+lookupWithDefaultFM
+ :: Ord key => FiniteMap key elt -> elt -> key -> elt
+ -- lookupWithDefaultFM supplies a "default" elt
+ -- to return for an unmapped key
+
+-- LISTIFYING
+fmToList :: FiniteMap key elt -> [(key,elt)]
+keysFM :: FiniteMap key elt -> [key]
+eltsFM :: FiniteMap key elt -> [elt]
+</verb></tscreen>
+
+%************************************************************************
+%* *
+<sect2>The @ListSetOps@ type
+<label id="ListSetOps">
+<p>
+<nidx>ListSetOps module (GHC syslib)</nidx>
+%* *
+%************************************************************************
+
+Just a few set-sounding operations on lists. If you want sets, use
+the @Set@ module.
+
+<tscreen><verb>
+unionLists :: Eq a => [a] -> [a] -> [a]
+intersectLists :: Eq a => [a] -> [a] -> [a]
+minusList :: Eq a => [a] -> [a] -> [a]
+disjointLists :: Eq a => [a] -> [a] -> Bool
+intersectingLists :: Eq a => [a] -> [a] -> Bool
+</verb></tscreen>
+
+%************************************************************************
+%* *
+<sect2>The @Maybes@ type
+<label id="Maybes">
+<p>
+<nidx>Maybes module (GHC syslib)</nidx>
+%* *
+%************************************************************************
+
+The @Maybe@ type is in the Haskell 1.4 prelude. Moreover, the
+required @Maybe@ library provides many useful functions on
+@Maybe@s. This (pre-1.3) module provides some more:
+
+An @Either@-like type called @MaybeErr@:
+<tscreen><verb>
+data MaybeErr val err = Succeeded val | Failed err
+</verb></tscreen>
+
+Some operations to do with @Maybe@ (some commentary follows):
+<tscreen><verb>
+maybeToBool :: Maybe a -> Bool -- Nothing => False; Just => True
+allMaybes :: [Maybe a] -> Maybe [a]
+firstJust :: [Maybe a] -> Maybe a
+findJust :: (a -> Maybe b) -> [a] -> Maybe b
+
+assocMaybe :: Eq a => [(a,b)] -> a -> Maybe b
+mkLookupFun :: (key -> key -> Bool) -- Equality predicate
+ -> [(key,val)] -- The assoc list
+ -> (key -> Maybe val) -- A lookup fun to use
+mkLookupFunDef :: (key -> key -> Bool) -- Equality predicate
+ -> [(key,val)] -- The assoc list
+ -> val -- Value to return on failure
+ -> key -- The key
+ -> val -- The corresponding value
+
+ -- a monad thing
+thenMaybe :: Maybe a -> (a -> Maybe b) -> Maybe b
+returnMaybe :: a -> Maybe a
+failMaybe :: Maybe a
+mapMaybe :: (a -> Maybe b) -> [a] -> Maybe [b]
+</verb></tscreen>
+
+NB: @catMaybes@ which used to be here, is now available via the
+standard @Maybe@ interface (@Maybe@ is an instance of @MonadPlus@).
+
+@allMaybes@ collects a list of @Justs@ into a single @Just@, returning
+@Nothing@ if there are any @Nothings@.
+
+@firstJust@ takes a list of @Maybes@ and returns the
+first @Just@ if there is one, or @Nothing@ otherwise.
+
+@assocMaybe@ looks up in an association list, returning
+@Nothing@ if it fails.
+
+Now, some operations to do with @MaybeErr@ (comments follow):
+<tscreen><verb>
+ -- a monad thing (surprise, surprise)
+thenMaB :: MaybeErr a err -> (a -> MaybeErr b err) -> MaybeErr b err
+returnMaB :: val -> MaybeErr val err
+failMaB :: err -> MaybeErr val err
+
+listMaybeErrs :: [MaybeErr val err] -> MaybeErr [val] [err]
+foldlMaybeErrs :: (acc -> input -> MaybeErr acc err)
+ -> acc
+ -> [input]
+ -> MaybeErr acc [err]
+</verb></tscreen>
+
+@listMaybeErrs@ takes a list of @MaybeErrs@ and, if they all succeed,
+returns a @Succeeded@ of a list of their values. If any fail, it
+returns a @Failed@ of the list of all the errors in the list.
+
+@foldlMaybeErrs@ works along a list, carrying an accumulator; it
+applies the given function to the accumulator and the next list item,
+accumulating any errors that occur.
+
+%************************************************************************
+%* *
+<sect2>The @PackedString@ type
+<label id="PackedString">
+<p>
+<nidx>PackedString module (GHC syslib)</nidx>
+%* *
+%************************************************************************
+
+You need to @import PackedString@ and heave in your
+@-syslib ghc@ to use @PackedString@s.
+
+The basic type and functions available are:
+<tscreen><verb>
+data PackedString -- abstract
+
+packString :: [Char] -> PackedString
+packStringST :: [Char] -> ST s PackedString
+packCBytesST :: Int -> Addr -> ST s PackedString
+packBytesForCST :: [Char] -> ST s (ByteArray Int)
+byteArrayToPS :: ByteArray Int -> PackedString
+unsafeByteArrayToPS :: ByteArray a -> Int -> PackedString
+psToByteArray :: PackedString -> ByteArray Int
+psToByteArrayST :: PackedString -> ST s (ByteArray Int)
+
+unpackPS :: PackedString -> [Char]
+</verb></tscreen>
+
+We also provide a wad of list-manipulation-like functions:
+<tscreen><verb>
+nilPS :: PackedString
+consPS :: Char -> PackedString -> PackedString
+
+headPS :: PackedString -> Char
+tailPS :: PackedString -> PackedString
+nullPS :: PackedString -> Bool
+appendPS :: PackedString -> PackedString -> PackedString
+lengthPS :: PackedString -> Int
+indexPS :: PackedString -> Int -> Char
+ -- 0-origin indexing into the string
+mapPS :: (Char -> Char) -> PackedString -> PackedString
+filterPS :: (Char -> Bool) -> PackedString -> PackedString
+foldlPS :: (a -> Char -> a) -> a -> PackedString -> a
+foldrPS :: (Char -> a -> a) -> a -> PackedString -> a
+takePS :: Int -> PackedString -> PackedString
+dropPS :: Int -> PackedString -> PackedString
+splitAtPS :: Int -> PackedString -> (PackedString, PackedString)
+takeWhilePS :: (Char -> Bool) -> PackedString -> PackedString
+dropWhilePS :: (Char -> Bool) -> PackedString -> PackedString
+spanPS :: (Char -> Bool) -> PackedString -> (PackedString, PackedString)
+breakPS :: (Char -> Bool) -> PackedString -> (PackedString, PackedString)
+linesPS :: PackedString -> [PackedString]
+wordsPS :: PackedString -> [PackedString]
+reversePS :: PackedString -> PackedString
+concatPS :: [PackedString] -> PackedString
+elemPS :: Char -> PackedString -> Bool
+ -- Perl-style split&join
+splitPS :: Char -> PackedString -> [PackedString]
+splitWithPS :: (Char -> Bool) -> PackedString -> [PackedString]
+joinPS :: PackedString -> [PackedString] -> PackedString
+
+substrPS :: PackedString -> Int -> Int -> PackedString
+ -- pluck out a piece of a PackedString
+ -- start and end chars you want; both 0-origin-specified
+</verb></tscreen>
+
+%************************************************************************
+%* *
+<sect2>The @Pretty@ type
+<label id="Pretty">
+<p>
+<nidx>Pretty module (GHC syslib)</nidx>
+%* *
+%************************************************************************
+
+This is the pretty-printer that is currently used in GHC:
+
+<tscreen><verb>
+type Pretty
+
+ppShow :: Int{-width-} -> Pretty -> [Char]
+
+pp'SP :: Pretty -- "comma space"
+ppComma :: Pretty -- ,
+ppEquals :: Pretty -- =
+ppLbrack :: Pretty -- [
+ppLparen :: Pretty -- (
+ppNil :: Pretty -- nothing
+ppRparen :: Pretty -- )
+ppRbrack :: Pretty -- ]
+ppSP :: Pretty -- space
+ppSemi :: Pretty -- ;
+
+ppChar :: Char -> Pretty
+ppDouble :: Double -> Pretty
+ppFloat :: Float -> Pretty
+ppInt :: Int -> Pretty
+ppInteger :: Integer -> Pretty
+ppRational :: Rational -> Pretty
+ppStr :: [Char] -> Pretty
+
+ppAbove :: Pretty -> Pretty -> Pretty
+ppAboves :: [Pretty] -> Pretty
+ppBeside :: Pretty -> Pretty -> Pretty
+ppBesides :: [Pretty] -> Pretty
+ppCat :: [Pretty] -> Pretty
+ppHang :: Pretty -> Int -> Pretty -> Pretty
+ppInterleave :: Pretty -> [Pretty] -> Pretty -- spacing between
+ppIntersperse :: Pretty -> [Pretty] -> Pretty -- no spacing between
+ppNest :: Int -> Pretty -> Pretty
+ppSep :: [Pretty] -> Pretty
+</verb></tscreen>
+
+%************************************************************************
+%* *
+<sect2>The @Set@ type
+<label id="Set">
+<p>
+<nidx>Set module (GHC syslib)</nidx>
+%* *
+%************************************************************************
+
+Our implementation of <em>sets</em> (key property: no duplicates) is just
+a variant of the @FiniteMap@ module.
+
+<tscreen><verb>
+data Set -- abstract
+ -- instance of: Eq
+
+emptySet :: Set a
+mkSet :: Ord a => [a] -> Set a
+setToList :: Set a -> [a]
+unitSet :: a -> Set a
+singletonSet :: a -> Set a -- deprecated, use unitSet.
+
+union :: Ord a => Set a -> Set a -> Set a
+unionManySets :: Ord a => [Set a] -> Set a
+minusSet :: Ord a => Set a -> Set a -> Set a
+mapSet :: Ord a => (b -> a) -> Set b -> Set a
+intersect :: Ord a => Set a -> Set a -> Set a
+
+elementOf :: Ord a => a -> Set a -> Bool
+isEmptySet :: Set a -> Bool
+
+cardinality :: Set a -> Int
+
+</verb></tscreen>
+
+%************************************************************************
+%* *
+<sect2>The @BitSet@ interface
+<label id="BitSet">
+<p>
+<nidx>Bitset interface (GHC syslib)</nidx>
+%* *
+%************************************************************************
+
+Bit sets are a fast implementation of sets of integers ranging from 0
+to one less than the number of bits in a machine word (typically 31).
+If any element exceeds the maximum value for a particular machine
+architecture, the results of these operations are undefined. You have
+been warned.
+
+<tscreen><verb>
+data BitSet -- abstract
+ -- instance of:
+
+emptyBS :: BitSet
+mkBS :: [Int] -> BitSet
+unitBS :: Int -> BitSet
+unionBS :: BitSet -> BitSet -> BitSet
+minusBS :: BitSet -> BitSet -> BitSet
+isEmptyBS :: BitSet -> Bool
+intersectBS :: BitSet -> BitSet -> BitSet
+elementBS :: Int -> BitSet -> Bool
+listBS :: BitSet -> [Int]
+</verb></tscreen>
+
+%************************************************************************
+%* *
+<sect2>The @Util@ type
+<label id="Util">
+<p>
+<nidx>Util module (GHC syslib)</nidx>
+%* *
+%************************************************************************
+
+Stuff that has been generally useful to use in writing the compiler.
+Don't be too surprised if this stuff moves/gets-renamed/etc.
+
+<tscreen><verb>
+-- general list processing
+forall :: (a -> Bool) -> [a] -> Bool
+exists :: (a -> Bool) -> [a] -> Bool
+
+nOfThem :: Int -> a -> [a]
+lengthExceeds :: [a] -> Int -> Bool
+isSingleton :: [a] -> Bool
+
+--paranoid zip'ing (equal length lists)
+zipEqual :: [a] -> [b] -> [(a,b)]
+zipWithEqual :: String -> (a->b->c) -> [a]->[b]->[c]
+zipWith3Equal :: String -> (a->b->c->d) -> [a]->[b]->[c]->[d]
+zipWith4Equal :: String -> (a->b->c->d->e) -> [a]->[b]->[c]->[d]->[e]
+-- lazy in second argument
+zipLazy :: [a] -> [b] -> [(a,b)]
+
+mapAndUnzip :: (a -> (b, c)) -> [a] -> ([b], [c])
+mapAndUnzip3 :: (a -> (b, c, d)) -> [a] -> ([b], [c], [d])
+
+-- prefix and suffix matching on lists of characters.
+startsWith :: {-prefix-}String -> String -> Maybe String
+endsWith :: {-suffix-}String -> String -> Maybe String
+
+-- association lists
+assoc :: Eq a => String -> [(a, b)] -> a -> b
+
+-- duplicate handling
+hasNoDups :: Eq a => [a] -> Bool
+equivClasses :: (a -> a -> Ordering) -> [a] -> [[a]]
+runs :: (a -> a -> Bool) -> [a] -> [[a]]
+removeDups :: (a -> a -> Ordering) -> [a] -> ([a], [[a]])
+
+-- sorting (don't complain of no choice...)
+quicksort :: (a -> a -> Bool) -> [a] -> [a]
+sortLt :: (a -> a -> Bool) -> [a] -> [a]
+stableSortLt :: (a -> a -> Bool) -> [a] -> [a]
+mergesort :: (a -> a -> _CMP_TAG) -> [a] -> [a]
+mergeSort :: Ord a => [a] -> [a]
+naturalMergeSort :: Ord a => [a] -> [a]
+mergeSortLe :: Ord a => [a] -> [a]
+naturalMergeSortLe :: Ord a => [a] -> [a]
+
+-- transitive closures
+transitiveClosure :: (a -> [a]) -- Successor function
+ -> (a -> a -> Bool) -- Equality predicate
+ -> [a]
+ -> [a] -- The transitive closure
+
+-- accumulating (Left, Right, Bi-directional)
+mapAccumL :: (acc -> x -> (acc, y))
+ -- Function of elt of input list and
+ -- accumulator, returning new accumulator and
+ -- elt of result list
+ -> acc -- Initial accumulator
+ -> [x] -- Input list
+ -> (acc, [y]) -- Final accumulator and result list
+
+mapAccumR :: (acc -> x -> (acc, y)) -> acc -> [x] -> (acc, [y])
+
+mapAccumB :: (accl -> accr -> x -> (accl, accr,y))
+ -> accl -> accr -> [x]
+ -> (accl, accr, [y])
+
+--list comparison with explicit element comparer.
+cmpList :: (a -> a -> Ordering) -> [a] -> [a] -> Ordering
+
+-- pairs
+applyToPair :: ((a -> c), (b -> d)) -> (a, b) -> (c, d)
+applyToFst :: (a -> c) -> (a, b) -> (c, b)
+applyToSnd :: (b -> d) -> (a, b) -> (a, d)
+foldPair :: (a->a->a, b->b->b) -> (a, b) -> [(a, b)] -> (a, b)
+unzipWith :: (a -> b -> c) -> [(a, b)] -> [c]
+</verb></tscreen>
+
+%************************************************************************
+%* *
+<sect1>Interfaces to C libraries
+<label id="C-interfaces">
+<p>
+<nidx>C library interfaces</nidx>
+<nidx>interfaces, C library</nidx>
+%* *
+%************************************************************************
+
+The GHC system library (@-syslib ghc@) also provides interfaces to
+several useful C libraries, mostly from the GNU project.
+
+%************************************************************************
+%* *
+<sect2>The @Readline@ interface
+<label id="Readline">
+<p>
+<nidx>Readline library (GHC syslib)</nidx>
+<nidx>command-line editing library</nidx>
+%* *
+%************************************************************************
+
+(Darren Moffat supplied the @Readline@ interface.)
+
+The @Readline@ module is a straightforward interface to the GNU
+Readline library. As such, you will need to look at the GNU
+documentation (and have a @libreadline.a@ file around somewhere...)
+
+You'll need to link any Readlining program with @-lreadline -ltermcap@,
+besides the usual @-syslib ghc@ (and @-fhaskell-1.3@).
+
+The main function you'll use is:
+<tscreen><verb>
+readline :: String{-the prompt-} -> IO String
+</verb></tscreen>
+
+If you want to mess around with Full Readline G(l)ory, we also
+provide:
+<tscreen><verb>
+rlInitialize, addHistory,
+
+rlBindKey, rlAddDefun, RlCallbackFunction(..),
+
+rlGetLineBuffer, rlSetLineBuffer, rlGetPoint, rlSetPoint, rlGetEnd,
+rlSetEnd, rlGetMark, rlSetMark, rlSetDone, rlPendingInput,
+
+rlPrompt, rlTerminalName, rlSetReadlineName, rlGetReadlineName
+</verb></tscreen>
+(All those names are just Haskellised versions of what you
+will see in the GNU readline documentation.)
+
+%************************************************************************
+%* *
+<sect2>The @Regexp@ and @MatchPS@ interfaces
+<label id="Regexp">
+<p>
+<nidx>Regex library (GHC syslib)</nidx>
+<nidx>MatchPS library (GHC syslib)</nidx>
+<nidx>regular-expressions library</nidx>
+%* *
+%************************************************************************
+
+(Sigbjorn Finne supplied the regular-expressions interface.)
+
+The @Regex@ library provides quite direct interface to the GNU
+regular-expression library, for doing manipulation on
+@PackedString@s. You probably need to see the GNU documentation
+if you are operating at this level.
+
+The datatypes and functions that @Regex@ provides are:
+<tscreen><verb>
+data PatBuffer # just a bunch of bytes (mutable)
+
+data REmatch
+ = REmatch (Array Int GroupBounds) -- for $1, ... $n
+ GroupBounds -- for $` (everything before match)
+ GroupBounds -- for $& (entire matched string)
+ GroupBounds -- for $' (everything after)
+ GroupBounds -- for $+ (matched by last bracket)
+
+-- GroupBounds hold the interval where a group
+-- matched inside a string, e.g.
+--
+-- matching "reg(exp)" "a regexp" returns the pair (5,7) for the
+-- (exp) group. (PackedString indices start from 0)
+
+type GroupBounds = (Int, Int)
+
+re_compile_pattern
+ :: PackedString -- pattern to compile
+ -> Bool -- True <=> assume single-line mode
+ -> Bool -- True <=> case-insensitive
+ -> PrimIO PatBuffer
+
+re_match :: PatBuffer -- compiled regexp
+ -> PackedString -- string to match
+ -> Int -- start position
+ -> Bool -- True <=> record results in registers
+ -> PrimIO (Maybe REmatch)
+
+-- Matching on 2 strings is useful when you're dealing with multiple
+-- buffers, which is something that could prove useful for
+-- PackedStrings, as we don't want to stuff the contents of a file
+-- into one massive heap chunk, but load (smaller chunks) on demand.
+
+re_match2 :: PatBuffer -- 2-string version
+ -> PackedString
+ -> PackedString
+ -> Int
+ -> Int
+ -> Bool
+ -> PrimIO (Maybe REmatch)
+
+re_search :: PatBuffer -- compiled regexp
+ -> PackedString -- string to search
+ -> Int -- start index
+ -> Int -- stop index
+ -> Bool -- True <=> record results in registers
+ -> PrimIO (Maybe REmatch)
+
+re_search2 :: PatBuffer -- Double buffer search
+ -> PackedString
+ -> PackedString
+ -> Int -- start index
+ -> Int -- range (?)
+ -> Int -- stop index
+ -> Bool -- True <=> results in registers
+ -> PrimIO (Maybe REmatch)
+</verb></tscreen>
+
+The @MatchPS@ module provides Perl-like ``higher-level'' facilities
+to operate on @PackedStrings@. The regular expressions in
+question are in Perl syntax. The ``flags'' on various functions can
+include: @i@ for case-insensitive, @s@ for single-line mode, and
+@g@ for global. (It's probably worth your time to peruse the
+source code...)
+
+<tscreen><verb>
+matchPS :: PackedString -- regexp
+ -> PackedString -- string to match
+ -> [Char] -- flags
+ -> Maybe REmatch -- info about what matched and where
+
+searchPS :: PackedString -- regexp
+ -> PackedString -- string to match
+ -> [Char] -- flags
+ -> Maybe REmatch
+
+-- Perl-like match-and-substitute:
+substPS :: PackedString -- regexp
+ -> PackedString -- replacement
+ -> [Char] -- flags
+ -> PackedString -- string
+ -> PackedString
+
+-- same as substPS, but no prefix and suffix:
+replacePS :: PackedString -- regexp
+ -> PackedString -- replacement
+ -> [Char] -- flags
+ -> PackedString -- string
+ -> PackedString
+
+match2PS :: PackedString -- regexp
+ -> PackedString -- string1 to match
+ -> PackedString -- string2 to match
+ -> [Char] -- flags
+ -> Maybe REmatch
+
+search2PS :: PackedString -- regexp
+ -> PackedString -- string to match
+ -> PackedString -- string to match
+ -> [Char] -- flags
+ -> Maybe REmatch
+
+-- functions to pull the matched pieces out of an REmatch:
+
+getMatchesNo :: REmatch -> Int
+getMatchedGroup :: REmatch -> Int -> PackedString -> PackedString
+getWholeMatch :: REmatch -> PackedString -> PackedString
+getLastMatch :: REmatch -> PackedString -> PackedString
+getAfterMatch :: REmatch -> PackedString -> PackedString
+
+-- (reverse) brute-force string matching;
+-- Perl equivalent is index/rindex:
+findPS, rfindPS :: PackedString -> PackedString -> Maybe Int
+
+-- Equivalent to Perl "chop" (off the last character, if any):
+chopPS :: PackedString -> PackedString
+
+-- matchPrefixPS: tries to match as much as possible of strA starting
+-- from the beginning of strB (handy when matching fancy literals in
+-- parsers):
+matchPrefixPS :: PackedString -> PackedString -> Int
+</verb></tscreen>
+
+%************************************************************************
+%* *
+<sect2>Network-interface toolkit---@Socket@ and @SocketPrim@
+<label id="Socket">
+<p>
+<nidx>SocketPrim interface (GHC syslib)</nidx>
+<nidx>Socket interface (GHC syslib)</nidx>
+<nidx>network-interface library</nidx>
+<nidx>sockets library</nidx>
+<nidx>BSD sockets library</nidx>
+%* *
+%************************************************************************
+
+(Darren Moffat supplied the network-interface toolkit.)
+
+Your best bet for documentation is to look at the code---really!---
+normally in @fptools/ghc/lib/misc/{BSD,Socket,SocketPrim@.lhs}.
+
+The @BSD@ module provides functions to get at system-database info;
+pretty straightforward if you're into this sort of thing:
+<tscreen><verb>
+getHostName :: IO String
+
+getServiceByName :: ServiceName -> IO ServiceEntry
+getServicePortNumber:: ServiceName -> IO PortNumber
+getServiceEntry :: IO ServiceEntry
+setServiceEntry :: Bool -> IO ()
+endServiceEntry :: IO ()
+
+getProtocolByName :: ProtocolName -> IO ProtocolEntry
+getProtocolByNumber :: ProtocolNumber -> IO ProtcolEntry
+getProtocolNumber :: ProtocolName -> ProtocolNumber
+getProtocolEntry :: IO ProtocolEntry
+setProtocolEntry :: Bool -> IO ()
+endProtocolEntry :: IO ()
+
+getHostByName :: HostName -> IO HostEntry
+getHostByAddr :: Family -> HostAddress -> IO HostEntry
+getHostEntry :: IO HostEntry
+setHostEntry :: Bool -> IO ()
+endHostEntry :: IO ()
+</verb></tscreen>
+
+The @SocketPrim@ interface provides quite direct access to the
+socket facilities in a BSD Unix system, including all the
+complications. We hope you don't need to use it! See the source if
+needed...
+
+The @Socket@ interface is a ``higher-level'' interface to sockets,
+and it is what we recommend. Please tell us if the facilities it
+offers are inadequate to your task!
+
+The interface is relatively modest:
+<tscreen><verb>
+connectTo :: Hostname -> PortID -> IO Handle
+listenOn :: PortID -> IO Socket
+
+accept :: Socket -> IO (Handle, HostName)
+sendTo :: Hostname -> PortID -> String -> IO ()
+
+recvFrom :: Hostname -> PortID -> IO String
+socketPort :: Socket -> IO PortID
+
+data PortID -- PortID is a non-abstract type
+ = Service String -- Service Name eg "ftp"
+ | PortNumber Int -- User defined Port Number
+ | UnixSocket String -- Unix family socket in file system
+
+type Hostname = String
+</verb></tscreen>
+
+Various examples of networking Haskell code are provided in
+%@ghc/misc/examples/@, notably the @net???/Main.hs@ programs.
projects / ghc-hetmet.git / blobdiff