1 <Sect1 id="GHC-library">
2 <Title>Miscellaneous libraries
6 <IndexTerm><Primary>libraries, miscellaneous</Primary></IndexTerm>
7 <IndexTerm><Primary>misc, syslib</Primary></IndexTerm>
11 This section describes a collection of Haskell libraries we've
12 collected over the years. Access to any of these modules is provided
13 by giving the <Literal>-syslib misc</Literal><IndexTerm><Primary>-syslib misc option</Primary></IndexTerm>.
17 <Title>The <Literal>Bag</Literal> type
21 <IndexTerm><Primary>Bag module (misc syslib)</Primary></IndexTerm>
25 A <Emphasis>bag</Emphasis> is an unordered collection of elements which may contain
26 duplicates. To use, <Literal>import Bag</Literal>.
32 data Bag elt -- abstract
35 unitBag :: elt -> Bag elt
37 consBag :: elt -> Bag elt -> Bag elt
38 snocBag :: Bag elt -> elt -> Bag elt
40 unionBags :: Bag elt -> Bag elt -> Bag elt
41 unionManyBags :: [Bag elt] -> Bag elt
43 isEmptyBag :: Bag elt -> Bool
44 elemBag :: Eq elt => elt -> Bag elt -> Bool
46 filterBag :: (elt -> Bool) -> Bag elt -> Bag elt
47 partitionBag :: (elt -> Bool) -> Bag elt-> (Bag elt, Bag elt)
48 -- returns the elements that do/don't satisfy the predicate
50 concatBag :: Bag (Bag a) -> Bag a
51 foldBag :: (r -> r -> r) -> (a -> r) -> r -> Bag a -> r
52 mapBag :: (a -> b) -> Bag a -> Bag b
54 listToBag :: [elt] -> Bag elt
55 bagToList :: Bag elt -> [elt]
62 <Sect2 id="FiniteMap">
63 <Title>The <Literal>FiniteMap</Literal> type
67 <IndexTerm><Primary>FiniteMap module (misc syslib)</Primary></IndexTerm>
71 What functional programmers call a <Emphasis>finite map</Emphasis>, everyone else
72 calls a <Emphasis>lookup table</Emphasis>.
76 Out code is derived from that in this paper:
79 "Efficient sets: a balancing act"
80 Journal of functional programming 3(4) Oct 1993, pages 553-562</QUOTE
82 Guess what? The implementation uses balanced trees.
88 data FiniteMap key elt -- abstract
91 emptyFM :: FiniteMap key elt
92 unitFM :: key -> elt -> FiniteMap key elt
93 listToFM :: Ord key => [(key,elt)] -> FiniteMap key elt
94 -- In the case of duplicates, the last is taken
96 -- ADDING AND DELETING
97 -- Throws away any previous binding
98 -- In the list case, the items are added starting with the
99 -- first one in the list
100 addToFM :: Ord key => FiniteMap key elt -> key -> elt -> FiniteMap key elt
101 addListToFM :: Ord key => FiniteMap key elt -> [(key,elt)] -> FiniteMap key elt
103 -- Combines with previous binding
104 -- In the combining function, the first argument is
105 -- the "old" element, while the second is the "new" one.
106 addToFM_C :: Ord key => (elt -> elt -> elt)
107 -> FiniteMap key elt -> key -> elt
108 -> FiniteMap key elt
109 addListToFM_C :: Ord key => (elt -> elt -> elt)
110 -> FiniteMap key elt -> [(key,elt)]
111 -> FiniteMap key elt
113 -- Deletion doesn't complain if you try to delete something
115 delFromFM :: Ord key => FiniteMap key elt -> key -> FiniteMap key elt
116 delListFromFM :: Ord key => FiniteMap key elt -> [key] -> FiniteMap key elt
119 -- Bindings in right argument shadow those in the left
120 plusFM :: Ord key => FiniteMap key elt -> FiniteMap key elt
121 -> FiniteMap key elt
123 -- Combines bindings for the same thing with the given function
124 plusFM_C :: Ord key => (elt -> elt -> elt)
125 -> FiniteMap key elt -> FiniteMap key elt -> FiniteMap key elt
127 minusFM :: Ord key => FiniteMap key elt -> FiniteMap key elt -> FiniteMap key elt
128 -- (minusFM a1 a2) deletes from a1 any bindings which are bound in a2
130 intersectFM :: Ord key => FiniteMap key elt -> FiniteMap key elt -> FiniteMap key elt
131 intersectFM_C :: Ord key => (elt -> elt -> elt)
132 -> FiniteMap key elt -> FiniteMap key elt -> FiniteMap key elt
134 -- MAPPING, FOLDING, FILTERING
135 foldFM :: (key -> elt -> a -> a) -> a -> FiniteMap key elt -> a
136 mapFM :: (key -> elt1 -> elt2) -> FiniteMap key elt1 -> FiniteMap key elt2
137 filterFM :: Ord key => (key -> elt -> Bool)
138 -> FiniteMap key elt -> FiniteMap key elt
141 sizeFM :: FiniteMap key elt -> Int
142 isEmptyFM :: FiniteMap key elt -> Bool
144 elemFM :: Ord key => key -> FiniteMap key elt -> Bool
145 lookupFM :: Ord key => FiniteMap key elt -> key -> Maybe elt
147 :: Ord key => FiniteMap key elt -> elt -> key -> elt
148 -- lookupWithDefaultFM supplies a "default" elt
149 -- to return for an unmapped key
152 fmToList :: FiniteMap key elt -> [(key,elt)]
153 keysFM :: FiniteMap key elt -> [key]
154 eltsFM :: FiniteMap key elt -> [elt]
161 <Sect2 id="ListSetOps">
162 <Title>The <Literal>ListSetOps</Literal> type
166 <IndexTerm><Primary>ListSetOps module (misc syslib)</Primary></IndexTerm>
170 Just a few set-sounding operations on lists. If you want sets, use
171 the <Literal>Set</Literal> module.
177 unionLists :: Eq a => [a] -> [a] -> [a]
178 intersectLists :: Eq a => [a] -> [a] -> [a]
179 minusList :: Eq a => [a] -> [a] -> [a]
180 disjointLists :: Eq a => [a] -> [a] -> Bool
181 intersectingLists :: Eq a => [a] -> [a] -> Bool
189 <Title>The <Literal>Maybes</Literal> type
193 <IndexTerm><Primary>Maybes module (misc syslib)</Primary></IndexTerm>
197 The <Literal>Maybe</Literal> type is in the Haskell 1.4 prelude. Moreover, the
198 required <Literal>Maybe</Literal> library provides many useful functions on
199 <Literal>Maybe</Literal>s. This (pre-1.3) module provides some more:
203 An <Literal>Either</Literal>-like type called <Literal>MaybeErr</Literal>:
206 data MaybeErr val err = Succeeded val | Failed err
212 Some operations to do with <Literal>Maybe</Literal> (some commentary follows):
215 maybeToBool :: Maybe a -> Bool -- Nothing => False; Just => True
216 allMaybes :: [Maybe a] -> Maybe [a]
217 firstJust :: [Maybe a] -> Maybe a
218 findJust :: (a -> Maybe b) -> [a] -> Maybe b
220 assocMaybe :: Eq a => [(a,b)] -> a -> Maybe b
221 mkLookupFun :: (key -> key -> Bool) -- Equality predicate
222 -> [(key,val)] -- The assoc list
223 -> (key -> Maybe val) -- A lookup fun to use
224 mkLookupFunDef :: (key -> key -> Bool) -- Equality predicate
225 -> [(key,val)] -- The assoc list
226 -> val -- Value to return on failure
227 -> key -- The key
228 -> val -- The corresponding value
231 thenMaybe :: Maybe a -> (a -> Maybe b) -> Maybe b
232 returnMaybe :: a -> Maybe a
234 mapMaybe :: (a -> Maybe b) -> [a] -> Maybe [b]
240 NB: <Literal>catMaybes</Literal> which used to be here, is now available via the
241 standard <Literal>Maybe</Literal> interface (<Literal>Maybe</Literal> is an instance of <Literal>MonadPlus</Literal>).
245 <Literal>allMaybes</Literal> collects a list of <Literal>Justs</Literal> into a single <Literal>Just</Literal>, returning
246 <Literal>Nothing</Literal> if there are any <Literal>Nothings</Literal>.
250 <Literal>firstJust</Literal> takes a list of <Literal>Maybes</Literal> and returns the
251 first <Literal>Just</Literal> if there is one, or <Literal>Nothing</Literal> otherwise.
255 <Literal>assocMaybe</Literal> looks up in an association list, returning
256 <Literal>Nothing</Literal> if it fails.
260 Now, some operations to do with <Literal>MaybeErr</Literal> (comments follow):
263 -- a monad thing (surprise, surprise)
264 thenMaB :: MaybeErr a err -> (a -> MaybeErr b err) -> MaybeErr b err
265 returnMaB :: val -> MaybeErr val err
266 failMaB :: err -> MaybeErr val err
268 listMaybeErrs :: [MaybeErr val err] -> MaybeErr [val] [err]
269 foldlMaybeErrs :: (acc -> input -> MaybeErr acc err)
272 -> MaybeErr acc [err]
278 <Literal>listMaybeErrs</Literal> takes a list of <Literal>MaybeErrs</Literal> and, if they all succeed,
279 returns a <Literal>Succeeded</Literal> of a list of their values. If any fail, it
280 returns a <Literal>Failed</Literal> of the list of all the errors in the list.
284 <Literal>foldlMaybeErrs</Literal> works along a list, carrying an accumulator; it
285 applies the given function to the accumulator and the next list item,
286 accumulating any errors that occur.
291 <Sect2 id="memo-library">
292 <Title>The <Literal>Memo</Literal> library
296 <IndexTerm><Primary>Memo (misc syslib)</Primary></IndexTerm>
300 The <Literal>Memo</Literal> library provides fast polymorphic memo functions using hash
301 tables. The interface is:
307 memo :: (a -> b) -> a -> b
313 So, for example, <Literal>memo f</Literal> is a version of <Literal>f</Literal> that caches the results
318 The searching is very fast, being based on pointer equality. One
319 consequence of this is that the caching will only be effective if
320 <Emphasis>exactly the same argument is passed again to the memoised
321 function</Emphasis>. This means not just a copy of a previous argument, but the
322 same instance. It's not useful to memoise integer functions using
323 this interface, because integers are generally copied a lot and two
324 instances of '27' are unlikely to refer to the same object.
328 This memoisation library works well when the keys are large (or even
333 The memo table implementation uses weak pointers and stable names (see
334 the GHC/Hugs library document) to avoid space leaks and allow hashing
335 for arbitrary Haskell objects. NOTE: while individual memo table
336 entries will be garbage collected if the associated key becomes
337 garbage, the memo table itself will not be collected if the function
338 becomes garbage. We plan to fix this in a future version.
342 There's another version of <Literal>memo</Literal> if you want to explicitly give a
343 size for the hash table (the default size is 1001 buckets):
349 memo_sized :: Int -> (a -> b) -> a -> b
356 <Sect2 id="PackedString">
357 <Title>The <Literal>PackedString</Literal> type
361 <IndexTerm><Primary>PackedString module (misc syslib)</Primary></IndexTerm>
365 You need to <Literal>import PackedString</Literal> and heave in your
366 <Literal>-syslib ghc</Literal> to use <Literal>PackedString</Literal>s.
370 The basic type and functions available are:
373 data PackedString -- abstract
375 packString :: [Char] -> PackedString
376 packStringST :: [Char] -> ST s PackedString
377 packCBytesST :: Int -> Addr -> ST s PackedString
378 packBytesForCST :: [Char] -> ST s (ByteArray Int)
379 byteArrayToPS :: ByteArray Int -> PackedString
380 unsafeByteArrayToPS :: ByteArray a -> Int -> PackedString
381 psToByteArray :: PackedString -> ByteArray Int
382 psToByteArrayST :: PackedString -> ST s (ByteArray Int)
384 unpackPS :: PackedString -> [Char]
390 We also provide a wad of list-manipulation-like functions:
393 nilPS :: PackedString
394 consPS :: Char -> PackedString -> PackedString
396 headPS :: PackedString -> Char
397 tailPS :: PackedString -> PackedString
398 nullPS :: PackedString -> Bool
399 appendPS :: PackedString -> PackedString -> PackedString
400 lengthPS :: PackedString -> Int
401 indexPS :: PackedString -> Int -> Char
402 -- 0-origin indexing into the string
403 mapPS :: (Char -> Char) -> PackedString -> PackedString
404 filterPS :: (Char -> Bool) -> PackedString -> PackedString
405 foldlPS :: (a -> Char -> a) -> a -> PackedString -> a
406 foldrPS :: (Char -> a -> a) -> a -> PackedString -> a
407 takePS :: Int -> PackedString -> PackedString
408 dropPS :: Int -> PackedString -> PackedString
409 splitAtPS :: Int -> PackedString -> (PackedString, PackedString)
410 takeWhilePS :: (Char -> Bool) -> PackedString -> PackedString
411 dropWhilePS :: (Char -> Bool) -> PackedString -> PackedString
412 spanPS :: (Char -> Bool) -> PackedString -> (PackedString, PackedString)
413 breakPS :: (Char -> Bool) -> PackedString -> (PackedString, PackedString)
414 linesPS :: PackedString -> [PackedString]
415 wordsPS :: PackedString -> [PackedString]
416 reversePS :: PackedString -> PackedString
417 concatPS :: [PackedString] -> PackedString
418 elemPS :: Char -> PackedString -> Bool
419 -- Perl-style split&join
420 splitPS :: Char -> PackedString -> [PackedString]
421 splitWithPS :: (Char -> Bool) -> PackedString -> [PackedString]
422 joinPS :: PackedString -> [PackedString] -> PackedString
424 substrPS :: PackedString -> Int -> Int -> PackedString
425 -- pluck out a piece of a PackedString
426 -- start and end chars you want; both 0-origin-specified
434 <Title>The <Literal>Set</Literal> type
438 <IndexTerm><Primary>Set module (misc syslib)</Primary></IndexTerm>
442 Our implementation of <Emphasis>sets</Emphasis> (key property: no duplicates) is just
443 a variant of the <Literal>FiniteMap</Literal> module.
453 mkSet :: Ord a => [a] -> Set a
454 setToList :: Set a -> [a]
455 unitSet :: a -> Set a
456 singletonSet :: a -> Set a -- deprecated, use unitSet.
458 union :: Ord a => Set a -> Set a -> Set a
459 unionManySets :: Ord a => [Set a] -> Set a
460 minusSet :: Ord a => Set a -> Set a -> Set a
461 mapSet :: Ord a => (b -> a) -> Set b -> Set a
462 intersect :: Ord a => Set a -> Set a -> Set a
464 elementOf :: Ord a => a -> Set a -> Bool
465 isEmptySet :: Set a -> Bool
467 cardinality :: Set a -> Int
475 <Title>The <Literal>BitSet</Literal> interface
479 <IndexTerm><Primary>Bitset interface (misc syslib)</Primary></IndexTerm>
483 Bit sets are a fast implementation of sets of integers ranging from 0
484 to one less than the number of bits in a machine word (typically 31).
485 If any element exceeds the maximum value for a particular machine
486 architecture, the results of these operations are undefined. You have
493 data BitSet -- abstract
497 mkBS :: [Int] -> BitSet
498 unitBS :: Int -> BitSet
499 unionBS :: BitSet -> BitSet -> BitSet
500 minusBS :: BitSet -> BitSet -> BitSet
501 isEmptyBS :: BitSet -> Bool
502 intersectBS :: BitSet -> BitSet -> BitSet
503 elementBS :: Int -> BitSet -> Bool
504 listBS :: BitSet -> [Int]
512 <Title>The <Literal>Util</Literal> type
516 <IndexTerm><Primary>Util module (misc syslib)</Primary></IndexTerm>
520 Stuff that has been generally useful to use in writing the compiler.
521 Don't be too surprised if this stuff moves/gets-renamed/etc.
527 -- general list processing
528 forall :: (a -> Bool) -> [a] -> Bool
529 exists :: (a -> Bool) -> [a] -> Bool
531 nOfThem :: Int -> a -> [a]
532 lengthExceeds :: [a] -> Int -> Bool
533 isSingleton :: [a] -> Bool
535 --paranoid zip'ing (equal length lists)
536 zipEqual :: [a] -> [b] -> [(a,b)]
537 zipWithEqual :: String -> (a->b->c) -> [a]->[b]->[c]
538 zipWith3Equal :: String -> (a->b->c->d) -> [a]->[b]->[c]->[d]
539 zipWith4Equal :: String -> (a->b->c->d->e) -> [a]->[b]->[c]->[d]->[e]
540 -- lazy in second argument
541 zipLazy :: [a] -> [b] -> [(a,b)]
543 mapAndUnzip :: (a -> (b, c)) -> [a] -> ([b], [c])
544 mapAndUnzip3 :: (a -> (b, c, d)) -> [a] -> ([b], [c], [d])
546 -- prefix and suffix matching on lists of characters.
547 startsWith :: {-prefix-}String -> String -> Maybe String
548 endsWith :: {-suffix-}String -> String -> Maybe String
551 assoc :: Eq a => String -> [(a, b)] -> a -> b
553 -- duplicate handling
554 hasNoDups :: Eq a => [a] -> Bool
555 equivClasses :: (a -> a -> Ordering) -> [a] -> [[a]]
556 runs :: (a -> a -> Bool) -> [a] -> [[a]]
557 removeDups :: (a -> a -> Ordering) -> [a] -> ([a], [[a]])
559 -- sorting (don't complain of no choice...)
560 quicksort :: (a -> a -> Bool) -> [a] -> [a]
561 sortLt :: (a -> a -> Bool) -> [a] -> [a]
562 stableSortLt :: (a -> a -> Bool) -> [a] -> [a]
563 mergesort :: (a -> a -> _CMP_TAG) -> [a] -> [a]
564 mergeSort :: Ord a => [a] -> [a]
565 naturalMergeSort :: Ord a => [a] -> [a]
566 mergeSortLe :: Ord a => [a] -> [a]
567 naturalMergeSortLe :: Ord a => [a] -> [a]
569 -- transitive closures
570 transitiveClosure :: (a -> [a]) -- Successor function
571 -> (a -> a -> Bool) -- Equality predicate
573 -> [a] -- The transitive closure
575 -- accumulating (Left, Right, Bi-directional)
576 mapAccumL :: (acc -> x -> (acc, y))
577 -- Function of elt of input list and
578 -- accumulator, returning new accumulator and
579 -- elt of result list
580 -> acc -- Initial accumulator
581 -> [x] -- Input list
582 -> (acc, [y]) -- Final accumulator and result list
584 mapAccumR :: (acc -> x -> (acc, y)) -> acc -> [x] -> (acc, [y])
586 mapAccumB :: (accl -> accr -> x -> (accl, accr,y))
587 -> accl -> accr -> [x]
588 -> (accl, accr, [y])
590 --list comparison with explicit element comparer.
591 cmpList :: (a -> a -> Ordering) -> [a] -> [a] -> Ordering
594 applyToPair :: ((a -> c), (b -> d)) -> (a, b) -> (c, d)
595 applyToFst :: (a -> c) -> (a, b) -> (c, b)
596 applyToSnd :: (b -> d) -> (a, b) -> (a, d)
597 foldPair :: (a->a->a, b->b->b) -> (a, b) -> [(a, b)] -> (a, b)
598 unzipWith :: (a -> b -> c) -> [(a, b)] -> [c]
607 <Sect1 id="C-interfaces">
608 <Title>Interfaces to C libraries
612 <IndexTerm><Primary>C library interfaces</Primary></IndexTerm>
613 <IndexTerm><Primary>interfaces, C library</Primary></IndexTerm>
617 The GHC system library (<Literal>-syslib misc</Literal>) also provides interfaces to
618 several useful C libraries, mostly from the GNU project.
621 <Sect2 id="Readline">
622 <Title>The <Literal>Readline</Literal> interface
626 <IndexTerm><Primary>Readline library (misc syslib)</Primary></IndexTerm>
627 <IndexTerm><Primary>command-line editing library</Primary></IndexTerm>
631 (Darren Moffat supplied the <Literal>Readline</Literal> interface.)
635 The <Literal>Readline</Literal> module is a straightforward interface to the GNU
636 Readline library. As such, you will need to look at the GNU
637 documentation (and have a <Literal>libreadline.a</Literal> file around somewhere…)
641 You'll need to link any Readlining program with <Literal>-lreadline -ltermcap</Literal>,
642 besides the usual <Literal>-syslib ghc</Literal> (and <Literal>-fhaskell-1.3</Literal>).
646 The main function you'll use is:
649 readline :: String{-the prompt-} -> IO String
655 If you want to mess around with Full Readline G(l)ory, we also
659 rlInitialize, addHistory,
661 rlBindKey, rlAddDefun, RlCallbackFunction(..),
663 rlGetLineBuffer, rlSetLineBuffer, rlGetPoint, rlSetPoint, rlGetEnd,
664 rlSetEnd, rlGetMark, rlSetMark, rlSetDone, rlPendingInput,
666 rlPrompt, rlTerminalName, rlSetReadlineName, rlGetReadlineName
669 (All those names are just Haskellised versions of what you
670 will see in the GNU readline documentation.)
676 <Title>The <Literal>Regex</Literal> and <Literal>MatchPS</Literal> interfaces
680 <IndexTerm><Primary>Regex library (misc syslib)</Primary></IndexTerm>
681 <IndexTerm><Primary>MatchPS library (misc syslib)</Primary></IndexTerm>
682 <IndexTerm><Primary>regular-expressions library</Primary></IndexTerm>
686 (Sigbjorn Finne supplied the regular-expressions interface.)
690 The <Literal>Regex</Literal> library provides quite direct interface to the GNU
691 regular-expression library, for doing manipulation on <Literal>PackedString</Literal>s.
692 You probably need to see the GNU documentation if you are operating at
693 this level. Alternatively, you can use the simpler and higher-level
694 <Literal>RegexString</Literal> interface.
698 The datatypes and functions that <Literal>Regex</Literal> provides are:
701 data PatBuffer # just a bunch of bytes (mutable)
704 = REmatch (Array Int GroupBounds) -- for $1, ... $n
705 GroupBounds -- for $` (everything before match)
706 GroupBounds -- for $& (entire matched string)
707 GroupBounds -- for $' (everything after)
708 GroupBounds -- for $+ (matched by last bracket)
710 -- GroupBounds hold the interval where a group
711 -- matched inside a string, e.g.
713 -- matching "reg(exp)" "a regexp" returns the pair (5,7) for the
714 -- (exp) group. (PackedString indices start from 0)
716 type GroupBounds = (Int, Int)
719 :: PackedString -- pattern to compile
720 -> Bool -- True <=> assume single-line mode
721 -> Bool -- True <=> case-insensitive
722 -> PrimIO PatBuffer
724 re_match :: PatBuffer -- compiled regexp
725 -> PackedString -- string to match
726 -> Int -- start position
727 -> Bool -- True <=> record results in registers
728 -> PrimIO (Maybe REmatch)
730 -- Matching on 2 strings is useful when you're dealing with multiple
731 -- buffers, which is something that could prove useful for
732 -- PackedStrings, as we don't want to stuff the contents of a file
733 -- into one massive heap chunk, but load (smaller chunks) on demand.
735 re_match2 :: PatBuffer -- 2-string version
741 -> PrimIO (Maybe REmatch)
743 re_search :: PatBuffer -- compiled regexp
744 -> PackedString -- string to search
745 -> Int -- start index
746 -> Int -- stop index
747 -> Bool -- True <=> record results in registers
748 -> PrimIO (Maybe REmatch)
750 re_search2 :: PatBuffer -- Double buffer search
753 -> Int -- start index
754 -> Int -- range (?)
755 -> Int -- stop index
756 -> Bool -- True <=> results in registers
757 -> PrimIO (Maybe REmatch)
763 The <Literal>MatchPS</Literal> module provides Perl-like ``higher-level'' facilities
764 to operate on <Literal>PackedStrings</Literal>. The regular expressions in
765 question are in Perl syntax. The ``flags'' on various functions can
766 include: <Literal>i</Literal> for case-insensitive, <Literal>s</Literal> for single-line mode, and
767 <Literal>g</Literal> for global. (It's probably worth your time to peruse the
774 matchPS :: PackedString -- regexp
775 -> PackedString -- string to match
776 -> [Char] -- flags
777 -> Maybe REmatch -- info about what matched and where
779 searchPS :: PackedString -- regexp
780 -> PackedString -- string to match
781 -> [Char] -- flags
784 -- Perl-like match-and-substitute:
785 substPS :: PackedString -- regexp
786 -> PackedString -- replacement
787 -> [Char] -- flags
788 -> PackedString -- string
791 -- same as substPS, but no prefix and suffix:
792 replacePS :: PackedString -- regexp
793 -> PackedString -- replacement
794 -> [Char] -- flags
795 -> PackedString -- string
798 match2PS :: PackedString -- regexp
799 -> PackedString -- string1 to match
800 -> PackedString -- string2 to match
801 -> [Char] -- flags
804 search2PS :: PackedString -- regexp
805 -> PackedString -- string to match
806 -> PackedString -- string to match
807 -> [Char] -- flags
810 -- functions to pull the matched pieces out of an REmatch:
812 getMatchesNo :: REmatch -> Int
813 getMatchedGroup :: REmatch -> Int -> PackedString -> PackedString
814 getWholeMatch :: REmatch -> PackedString -> PackedString
815 getLastMatch :: REmatch -> PackedString -> PackedString
816 getAfterMatch :: REmatch -> PackedString -> PackedString
818 -- (reverse) brute-force string matching;
819 -- Perl equivalent is index/rindex:
820 findPS, rfindPS :: PackedString -> PackedString -> Maybe Int
822 -- Equivalent to Perl "chop" (off the last character, if any):
823 chopPS :: PackedString -> PackedString
825 -- matchPrefixPS: tries to match as much as possible of strA starting
826 -- from the beginning of strB (handy when matching fancy literals in
828 matchPrefixPS :: PackedString -> PackedString -> Int
835 <Sect2 id="RegexString">
836 <Title>The <Literal>RegexString</Literal> interface
840 <IndexTerm><Primary>RegexString library (misc syslib)</Primary></IndexTerm>
841 <IndexTerm><Primary>regular-expressions library</Primary></IndexTerm>
845 (Simon Marlow supplied the String Regex wrapper.)
849 For simple regular expression operations, the <Literal>Regex</Literal> library is a
850 little heavyweight. <Literal>RegexString</Literal> permits regex matching on ordinary
851 Haskell <Literal>String</Literal>s.
855 The datatypes and functions that <Literal>RegexString</Literal> provides are:
858 data Regex -- a compiled regular expression
861 :: String -- regexp to compile
862 -> Regex -- compiled regexp
865 :: Regex -- compiled regexp
866 -> String -- string to match
867 -> Maybe [String] -- text of $1, $2, ... (if matched)
875 <Title>Network-interface toolkit—<Literal>Socket</Literal> and <Literal>SocketPrim</Literal>
879 <IndexTerm><Primary>SocketPrim interface (misc syslib)</Primary></IndexTerm>
880 <IndexTerm><Primary>Socket interface (misc syslib)</Primary></IndexTerm>
881 <IndexTerm><Primary>network-interface library</Primary></IndexTerm>
882 <IndexTerm><Primary>sockets library</Primary></IndexTerm>
883 <IndexTerm><Primary>BSD sockets library</Primary></IndexTerm>
884 (Darren Moffat supplied the initial version of this library.)
888 Your best bet for documentation is to look at the code—really!—
890 <Literal>fptools/ghc/lib/misc/{BSD,Socket,SocketPrim</Literal>.lhs}.
894 The <Literal>BSD</Literal> module provides functions to get at
895 system-database info; pretty straightforward if you're into this sort of
899 getHostName :: IO String
901 getServiceByName :: ServiceName -> IO ServiceEntry
902 getServicePortNumber:: ServiceName -> IO PortNumber
903 getServiceEntry :: IO ServiceEntry
904 setServiceEntry :: Bool -> IO ()
905 endServiceEntry :: IO ()
907 getProtocolByName :: ProtocolName -> IO ProtocolEntry
908 getProtocolByNumber :: ProtocolNumber -> IO ProtcolEntry
909 getProtocolNumber :: ProtocolName -> ProtocolNumber
910 getProtocolEntry :: IO ProtocolEntry
911 setProtocolEntry :: Bool -> IO ()
912 endProtocolEntry :: IO ()
914 getHostByName :: HostName -> IO HostEntry
915 getHostByAddr :: Family -> HostAddress -> IO HostEntry
916 getHostEntry :: IO HostEntry
917 setHostEntry :: Bool -> IO ()
918 endHostEntry :: IO ()
923 The <Literal>SocketPrim</Literal> interface provides quite direct access to
924 the socket facilities in a BSD Unix system, including all the
925 complications. We hope you don't need to use it! See the source if
930 The <Literal>Socket</Literal> interface is a ``higher-level'' interface to
931 sockets, and it is what we recommend. Please tell us if the facilities it
932 offers are inadequate to your task!
936 The interface is relatively modest:
939 connectTo :: Hostname -> PortID -> IO Handle
940 listenOn :: PortID -> IO Socket
942 accept :: Socket -> IO (Handle, HostName)
943 sendTo :: Hostname -> PortID -> String -> IO ()
945 recvFrom :: Hostname -> PortID -> IO String
946 socketPort :: Socket -> IO PortID
948 data PortID -- PortID is a non-abstract type
949 = Service String -- Service Name eg "ftp"
950 | PortNumber PortNumber -- User defined Port Number
951 | UnixSocket String -- Unix family socket in file system
953 type Hostname = String
955 -- 16-bit value (stored in network byte order).
957 -- instance of: Eq, Num, Show.
959 mkPortNumber :: Int -> PortNumber
964 Various examples of networking Haskell code are provided in
970 <Title>The <Literal>Select</Literal> interface
974 <IndexTerm><Primary>Select interface (misc syslib)</Primary></IndexTerm>
978 The <Literal>Select</Literal> interface provides a Haskell wrapper for the <Literal>select()</Literal>
979 OS call supplied by many modern UNIX variants. <Literal>Select</Literal> exports the
986 type TimeOut = Maybe Int
987 -- Nothing => wait indefinitely.
988 -- Just x | x >= 0 => block waiting for 'x' micro seconds.
989 -- | otherwise => block waiting for '-x' micro seconds.
995 -> IO SelectResult
998 = ( [Handle] -- input handles ready
999 , [Handle] -- output handles ready
1000 , [Handle] -- exc. handles ready
1007 Here's an example of how it could be used:
1013 module Main(main) where
1020 hSetBuffering stdin NoBuffering
1021 putStrLn "waiting for input to appear"
1022 hSelect [stdin] [] [] Nothing
1023 putStrLn "input ready, let's try reading"
1031 where the call to <Literal>hSelect</Literal> makes the process go to sleep
1032 until there's input available on <Literal>stdin</Literal>.
1036 Notice that this particular use of <Literal>hSelect</Literal> is now really a no-op
1037 with GHC compiled code, as its implementation of IO will take care to
1038 avoid blocking the process (i.e., all running Haskell threads), and
1039 call <Literal>select()</Literal> for you, if needs be. However, <Literal>hSelect</Literal> exposes
1040 functionality that is useful in other contexts (e.g., you want to
1041 wait for input on two <Literal>Handles</Literal> for 3 seconds, but no longer.)
projects / ghc-hetmet.git / blob