<sect2>The @Bag@ type
<label id="Bag">
<p>
-<nidx>Bag module (GHC syslib)</nidx>
+<nidx>Bag module (misc syslib)</nidx>
%* *
%************************************************************************
<sect2>The @FiniteMap@ type
<label id="FiniteMap">
<p>
-<nidx>FiniteMap module (GHC syslib)</nidx>
+<nidx>FiniteMap module (misc syslib)</nidx>
%* *
%************************************************************************
<sect2>The @ListSetOps@ type
<label id="ListSetOps">
<p>
-<nidx>ListSetOps module (GHC syslib)</nidx>
+<nidx>ListSetOps module (misc syslib)</nidx>
%* *
%************************************************************************
<sect2>The @Maybes@ type
<label id="Maybes">
<p>
-<nidx>Maybes module (GHC syslib)</nidx>
+<nidx>Maybes module (misc syslib)</nidx>
%* *
%************************************************************************
%************************************************************************
%* *
+<sect2>The @Memo@ library
+<label id="memo-library">
+<p>
+<nidx>Memo (misc syslib)</nidx>
+%* *
+%************************************************************************
+
+The @Memo@ library provides fast polymorphic memo functions using hash
+tables. The interface is:
+
+<tscreen><verb>
+memo :: (a -> b) -> a -> b
+</verb></tscreen>
+
+So, for example, @memo f@ is a version of @f@ that caches the results
+of previous calls.
+
+The searching is very fast, being based on pointer equality. One
+consequence of this is that the caching will only be effective if
+<em/exactly the same argument is passed again to the memoised
+function/. This means not just a copy of a previous argument, but the
+same instance. It's not useful to memoise integer functions using
+this interface, because integers are generally copied a lot and two
+instances of '27' are unlikely to refer to the same object.
+
+This memoisation library works well when the keys are large (or even
+infinite).
+
+The memo table implementation uses weak pointers and stable names (see
+the GHC/Hugs library document) to avoid space leaks and allow hashing
+for arbitrary Haskell objects. NOTE: while individual memo table
+entries will be garbage collected if the associated key becomes
+garbage, the memo table itself will not be collected if the function
+becomes garbage. We plan to fix this in a future version.
+
+There's another version of @memo@ if you want to explicitly give a
+size for the hash table (the default size is 1001 buckets):
+
+<tscreen><verb>
+memo_sized :: Int -> (a -> b) -> a -> b
+</verb></tscreen>
+
+%************************************************************************
+%* *
<sect2>The @PackedString@ type
<label id="PackedString">
<p>
-<nidx>PackedString module (GHC syslib)</nidx>
+<nidx>PackedString module (misc syslib)</nidx>
%* *
%************************************************************************
%************************************************************************
%* *
-<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>
+<nidx>Set module (misc syslib)</nidx>
%* *
%************************************************************************
<sect2>The @BitSet@ interface
<label id="BitSet">
<p>
-<nidx>Bitset interface (GHC syslib)</nidx>
+<nidx>Bitset interface (misc syslib)</nidx>
%* *
%************************************************************************
<sect2>The @Util@ type
<label id="Util">
<p>
-<nidx>Util module (GHC syslib)</nidx>
+<nidx>Util module (misc syslib)</nidx>
%* *
%************************************************************************
%* *
%************************************************************************
-The GHC system library (@-syslib ghc@) also provides interfaces to
+The GHC system library (@-syslib misc@) 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>Readline library (misc syslib)</nidx>
<nidx>command-line editing library</nidx>
%* *
%************************************************************************
%************************************************************************
%* *
-<sect2>The @Regexp@ and @MatchPS@ interfaces
-<label id="Regexp">
+<sect2>The @Regex@ and @MatchPS@ interfaces
+<label id="Regex">
<p>
-<nidx>Regex library (GHC syslib)</nidx>
-<nidx>MatchPS library (GHC syslib)</nidx>
+<nidx>Regex library (misc syslib)</nidx>
+<nidx>MatchPS library (misc 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.
+regular-expression library, for doing manipulation on @PackedString@s.
+You probably need to see the GNU documentation if you are operating at
+this level. Alternatively, you can use the simpler and higher-level
+@RegexString@ interface.
The datatypes and functions that @Regex@ provides are:
<tscreen><verb>
%************************************************************************
%* *
+<sect2>The @RegexString@ interface
+<label id="RegexString">
+<p>
+<nidx>RegexString library (misc syslib)</nidx>
+<nidx>regular-expressions library</nidx>
+%* *
+%************************************************************************
+
+(Simon Marlow supplied the String Regex wrapper.)
+
+For simple regular expression operations, the @Regex@ library is a
+little heavyweight. @RegexString@ permits regex matching on ordinary
+Haskell @String@s.
+
+The datatypes and functions that @RegexString@ provides are:
+<tscreen><verb>
+data Regex -- a compiled regular expression
+
+mkRegex
+ :: String -- regexp to compile
+ -> Regex -- compiled regexp
+
+matchRegex
+ :: Regex -- compiled regexp
+ -> String -- string to match
+ -> Maybe [String] -- text of $1, $2, ... (if matched)
+</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>SocketPrim interface (misc syslib)</nidx>
+<nidx>Socket interface (misc syslib)</nidx>
<nidx>network-interface library</nidx>
<nidx>sockets library</nidx>
<nidx>BSD sockets library</nidx>
%* *
%************************************************************************
-(Darren Moffat supplied the network-interface toolkit.)
+(Darren Moffat supplied the initial version of this library.)
Your best bet for documentation is to look at the code---really!---
normally in @fptools/ghc/lib/misc/{BSD,Socket,SocketPrim@.lhs}.
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
+ = Service String -- Service Name eg "ftp"
+ | PortNumber PortNumber -- User defined Port Number
+ | UnixSocket String -- Unix family socket in file system
type Hostname = String
+
+ -- 16-bit value (stored in network byte order).
+data PortNumber
+ -- instance of: Eq, Num, Show.
+
+mkPortNumber :: Int -> PortNumber
</verb></tscreen>
Various examples of networking Haskell code are provided in
%@ghc/misc/examples/@, notably the @net???/Main.hs@ programs.
+
+%************************************************************************
+%* *
+<sect2>The @Select@ interface
+<label id="Select">
+<p>
+<nidx>Select interface (misc syslib)</nidx>
+%* *
+%************************************************************************
+
+The <tt/Select/ interface provides a Haskell wrapper for the <tt/select()/
+OS call supplied by many modern UNIX variants. <tt/Select/ exports the
+following:
+
+<tscreen><verb>
+type TimeOut = Maybe Int
+ -- Nothing => wait indefinitely.
+ -- Just x | x >= 0 => block waiting for 'x' micro seconds.
+ -- | otherwise => block waiting for '-x' micro seconds.
+
+hSelect :: [Handle]
+ -> [Handle]
+ -> [Handle]
+ -> TimeOut
+ -> IO SelectResult
+
+type SelectResult
+ = ( [Handle] -- input handles ready
+ , [Handle] -- output handles ready
+ , [Handle] -- exc. handles ready
+ )
+
+</verb></tscreen>
+
+Here's an example of how it could be used:
+
+<tscreen><verb>
+module Main(main) where
+
+import Select
+import IO
+
+main :: IO ()
+main = do
+ hSetBuffering stdin NoBuffering
+ putStrLn "waiting for input to appear"
+ hSelect [stdin] [] [] Nothing
+ putStrLn "input ready, let's try reading"
+ x <- getChar
+ print x
+
+</verb></tscreen>
+
+where the call to <tt/hSelect/ makes the process go to sleep
+until there's input available on <tt/stdin/.
+
+Notice that this particular use of <tt/hSelect/ is now really a no-op
+with GHC compiled code, as its implementation of IO will take care to
+avoid blocking the process (i.e., all running Haskell threads), and
+call <tt/select()/ for you, if needs be. However, <tt/hSelect/ exposes
+functionality that is useful in other contexts (e.g., you want to
+wait for input on two <tt/Handles/ for 3 seconds, but no longer.)
+
projects / ghc-hetmet.git / blobdiff