Portable Libraries

Portable Libraries

These libraries are not part of the Haskell standard but can be ported to most Haskell systems.

Number This library defines a numeric datatype of fixed width integers (whatever Int supplies). However, unlike the built-in Int type, overflows are detected and cause a run-time error. To ensure that all integer arithmetic in a given module includes overflow protection you must include a default declaration for Number.

  module Number where
  data Number              -- fixed width integers
  instance Eq       Number -- class instances
  instance Ord      Number
  instance Show     Number
  instance Enum     Number
  instance Num      Number
  instance Bounded  Number
  instance Real     Number
  instance Ix       Number
  instance Integral Number

Random This library provides a random number generator. We expect that this will be moved into an official Library module soon.

IOExtensions This module provides non-standard extensions to the IO monad. Some of these are unsafe (they may break referential transparency) and must be used carefully.

  module IOExtensions where

  readBinaryFile     :: FilePath -> IO String
  writeBinaryFile    :: FilePath -> String -> IO ()
  appendBinaryFile   :: FilePath -> String -> IO ()
  openBinaryFile     :: FilePath -> IOMode -> IO Handle

  getCh              :: IO Char
  fixIO              :: (a -> IO a) -> IO a
  argv               :: [String]
  garbageCollect     :: IO ()

  unsafePerformIO    :: IO a -> a
  unsafeInterleaveIO :: IO a -> IO a

ListUtils This module includes list functions that were removed from the Prelude in the move from Haskell 1.2 to Haskell 1.3.

  module ListUtils where

  deleteFirstsBy   :: (a -> a -> Bool) -> [a] -> [a] -> [a]
  sums, products   :: Num a => [a] -> [a]

  subsequences     :: [a] -> [[a]]
  permutations     :: [a] -> [[a]]

ParseLib This module provides a library of parser combinators, as described in the paper on Monadic Parser Combinators by Graham Hutton and Erik Meijer [3].
Trace: This library provides a single function, that can sometimes be useful for debugging:
```
  module Trace where
  trace :: String -> a -> a
```
When called, trace prints the string in its first argument, and then returns the second argument as its result. The 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 Hugs programs are executed, results obtained using 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 trace can change the semantics of your program. Consider this a warning!

Interact: This library provides facilities for writing simple interactive programs.

  module Interact where

  type Interact = String -> String

  end                :: Interact
  readChar, peekChar :: Interact -> (Char -> Interact) -> Interact
  pressAnyKey        :: Interact -> Interact
  unreadChar         :: Char -> Interact -> Interact
  writeChar          :: Char -> Interact -> Interact
  writeStr           :: String -> Interact -> Interact
  ringBell           :: Interact -> Interact
  readLine           :: String -> (String -> Interact) -> Interact

An expression e of type Interact can be executed as a program by evaluating run e.

AnsiScreen This library defines some basic ANSI escape seqences for terminal control.

  module AnsiScreen where

  type Pos  = (Int,Int)

  at        :: Pos -> String -> String
  highlight :: String -> String
  goto      :: Int -> Int -> String
  home      :: String
  cls       :: String

The definitions in this module will need to be adapted to work with terminals that do not support ANSI escape sequences.

AnsiInteract This library includes both Interact and AnsiScreen, and also contains further support for screen oriented interactive I/O.

  module AnsiInteract(module AnsiInteract,
                      module Interact,
                      module AnsiScreen) where
  import AnsiScreen
  import Interact

  clearScreen       :: Interact -> Interact
  writeAt           :: Pos -> String -> Interact -> Interact
  moveTo            :: Pos -> Interact -> Interact
  readAt            :: Pos                  -> -- start coords
                       Int                  -> -- max input length
                       (String -> Interact) -> -- continuation
                       Interact
  defReadAt         :: Pos                  -> -- start coords
                       Int                  -> -- max input length
                       String               -> -- default value
                       (String -> Interact) -> -- continuation
                       Interact
  promptReadAt      :: Pos                  -> -- start coords
                       Int                  -> -- max input length     
                       String               -> -- prompt
                       (String -> Interact) -> -- continuation
                       Interact
  defPromptReadAt   :: Pos                  -> -- start coords
                       Int                  -> -- max input length     
                       String               -> -- prompt
                       String               -> -- default value
                       (String -> Interact) -> -- continuation
                       Interact

IORef: This library extends the Hugs IO monad with a datatype representing mutable reference cells, together with a small collection of related operators in the style of Peyton Jones and Wadler [4]:

 module IORef where

 data Ref a  -- Mutable reference cells, holding values of type a.

 newRef      :: a -> IO (Ref a)
 getRef      :: Ref a -> IO a
 setRef      :: Ref a -> a -> IO ()
 eqRef       :: Ref a -> Ref a -> Bool

 instance Eq (Ref a)

ST: This library provides support for lazy state threads and for the ST monad, as described by John Launchbury and Simon Peyton Jones [5].
```
 module ST where

 data MutVar s a   -- mutable variables containing values
                   -- of type a in state thread s.

 newVar       :: a -> ST s (MutVar s a)
 readVar      :: MutVar s a -> ST s a
 writeVar     :: MutVar s a -> a -> ST s ()
 interleaveST :: ST s a -> ST s a

 instance Eq (MutVar s a)
 instance Monad (ST s)
```
The runST operation, used to specify encapsulation, is currently implemented as a language construct, and runST is treated as a keyword.
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 ST and the IO monads.

STArray: This library extends both the ST and Array libraries with support for mutable arrays in the form described by John Launchbury and Simon Peyton Jones [5].

 module STArray where

 data MutArr s a b -- Mutable arrays, indexed by type a, with
                   -- results of type b in state thread s.

 newArr    :: Ix a => (a,a) -> b -> ST s (MutArr s a b)
 readArr   :: Ix a => MutArr s a b -> a -> ST s b
 writeArr  :: Ix a => MutArr s a b -> a -> b -> ST s ()
 freezeArr :: Ix a => MutArr s a b -> ST s (Array a b)

MVar This library provides an implementation of synchronisation objects (MVars), exactly as described in the paper by Simon Peyton Jones, Andrew Gordon and Sigbjorn Finne [6].
There is one significant difference between the implementation of these features in GHC and in Hugs:
- GHC uses preemptive multitasking: Context switches can occur at any time, except if you call a C function (like 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:
```
    main = forkIO (write 'a') >> write 'b'
     where write c = putChar c >> write c
```
  will print either aaaaaaaaaaaaaa... or bbbbbbbbbbbb..., instead of some random interleaving of as and bs.
Cooperative multitasking is sufficient for writing coroutines.
```
  module MVar where

  data MVar a               -- datatype of MVars

  forkIO   :: IO a -> IO () -- Spawn a thread

  newMVar  :: IO (MVar a)
  takeMVar :: MVar a -> IO a
  putMVar  :: MVar a -> a -> IO ()

  instance Eq (MVar a) 
```

Channel This library provides an implementation of buffered channels, exactly as described in the paper by Simon Peyton Jones, Andrew Gordon and Sigbjorn Finne [6].

  module Channel where
  data Channel a  -- datatype of buffered channels
  newChan         :: IO (Channel a)
  putChan         :: Channel a -> a -> IO ()
  getChan         :: Channel a -> IO a
  dupChan         :: Channel a -> IO (Channel a)

CVar This library provides an implementation of channel variables, exactly as described in the paper by Simon Peyton Jones, Andrew Gordon and Sigbjorn Finne [6].

  module CVar where

  import MVar

  type CVar a = (MVar a,  -- Producer -> consumer
                 MVar ()) -- Consumer -> producer

  newCVar    :: IO (CVar a)
  putCVar    :: CVar a -> a -> IO ()
  getCVar    :: CVar a -> IO a