The Hugs 98 User Manual
top | back | next

## 6`` Library overview

Haskell 98 places much greater emphasis on the use of libraries than early versions of the language. Following that lead, the Hugs 98 distribution includes most of the official libraries defined in the Haskell Library Report [Haskell98libs]. The distribution also includes a number of unofficial libraries, which fall into two categories: portable libraries, which are implemented using standard Haskell or widely implemented Haskell extensions; and Hugs-specific libraries, which use features that are not available in other Haskell implementations.

All that you need to do to use libraries is to import them using an `import` declaration. For example: `
module MandlebrotSet where
import Array
import Complex
...
` Of course, this assumes that `HUGSPATH` has been set to point to the directories where the libraries are stored, and that import chasing is enabled. The default search path includes the directories containing both the standard and unofficial libraries.

### 6.1`` Standard Libraries

The Hugs 98 distribution includes the following standard libraries: `Array`, `Char`, `Complex`, `IO`, `Ix`, `List`, `Locale`, `Maybe`, `Monad`, `Numeric`, `Prelude`, `Random`, `Ratio`, and `System`. The libraries `Directory`, `Time`, and `CPUTime`, are not currently supported. The library report [Haskell98libs] contains full descriptions of all of theses standard libraries. Differences between the library report and the libraries supplied with Hugs are described in Section 9.

### 6.2`` The Hugs-GHC Extension Libraries

Hugs and GHC provide a common set of libraries to aid portability; detailed specifications for these libraries are described elsewhere [HugsGHClibs]. The Hugs-GHC modules included in the current distribution include `Addr`, `Bits`, `Channel`, `ChannelVar`, `Concurrent`, `Dynamic`, `Foreign`, `IOExts`, `Int`, `GetOpt`, `NumExts`, `Pretty`, `ST`, `LazyST`, `Weak`, and `Word`. The `Exception` and `Stable` libraries are not currently supported. Note that the `ST` and `LazyST` libraries cannot be used when the interpreter is running in Haskell 98 mode; the type for `runST` requires support for rank-2 polymorphism, which is only available in Hugs mode. (See Section 7.3.2 for further details.)

The specifications and implementations of all of these libraries are still evolving, and are subject to change.

### 6.3`` Portable Libraries

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

- `ListUtils` This module provides list functions that were removed from the Prelude in the move from Haskell 1.2 to Haskell 1.3. `
  module ListUtils where
  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 [MonParse].
- `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
  `

### 6.4`` Hugs-Specific Libraries

These libraries provide several non-standard facilities for Hugs programmers. Other Haskell implementations may provide similar features, but this is not guaranteed, and there may be significant differences in organization, naming, semantics, or functionality.

- `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
  ` This library cannot be used when Hugs is running in Haskell 98 mode because it requires features that are only supported in full Hugs mode.
- `IOExtensions` This module provides non-standard extensions to the `IO` monad. `
  module IOExtensions where
  readBinaryFile :: FilePath -> IO String
  writeBinaryFile :: FilePath -> String -> IO ()
  appendBinaryFile :: FilePath -> String -> IO ()
  openBinaryFile :: FilePath -> IOMode -> IO Handle
  getCh :: IO Char
  argv :: [String]
  `
- `Trace`: This library provides a single function, that can sometimes be useful for debugging: `
  module Trace where
  trace :: String -> a -> a
  traceShow :: Show a => String -> a -> a
  ` When called, `trace` prints the string in its first argument, and then returns the second argument as its result. The `traceShow` function is a variant of `trace` that generates its output message by concatenating the supplied `String` argument with the result of applying `show` to its value argument. These functions are 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!
- `Trex` This library supports Trex extensible records. These can only be used when Hugs is compiled with Trex support using the `-enable-TREX` configuration option. Trex is described in more details in Section 7.2.
- `HugsInternals` This library provides primitives for accessing Hugs internals; for example, they provide the means with which to implement simple error-recovery and debugging facilities in Haskell. They should be regarded as an experimental feature and may not be supported in future versions of Hugs. They can only be used if hugs was configured with the `--enable-internal-prims` flag.
- `GenericPrint` This library provides a "generic" (or "polymorphic") print function in Haskell, that works in essentially the same way as Hugs' builtin printer when the `-u` option is used. The module `HugsInternals` is required.
- `CVHAssert` This library provides a simple implementation of Cordy Hall's assertions for performance debugging. These primitives are an experimental feature that may be removed in future versions of Hugs. They can only be used if hugs was configured with the `--enable-internal-prims` flag.
- `Win32` This library contains Haskell versions for many of the functions in the Microsoft Win32 library. It is only available on Windows 95/NT. The `--with-plugins` configuration option must be used in conjunction with this and the other Microsoft libraries.

Other libraries included in the standard distribution, but not further documented here are `Sequence`, `Pretty`, `HugsDynamic`, `HugsLibs`, `StdLibs`, and `OldWeak`.

The Hugs 98 User Manual
top | back | next
May 22, 1999