home *** CD-ROM | disk | FTP | other *** search
/ ARM Club 3 / TheARMClub_PDCD3.iso / hensa / programming / hugs_1 / hugs_txt < prev    next >
Encoding:
Text File  |  1996-08-16  |  81.9 KB  |  2,221 lines

  1. NOTICE: This text version of the Hugs documentation is provided for the
  2. benefit of users with special needs---anyone reading this document with
  3. the aid of a speech synthesizer, for example.  The formatting, use of
  4. fonts, etc. in this version of the document is sub-optimal, and you are
  5. strongly encouraged to use one of the alternative formats whenever you
  6. have an option.
  7.  
  8. -------------------------------------------------------------------------------
  9. Hugs 1.3 
  10.  
  11. The Haskell User's Gofer System 
  12.  
  13. User Manual
  14.  
  15. Mark P. Jones 
  16. Department of Computer Science 
  17. The University of Nottingham 
  18. Nottingham NG7 2RD, England 
  19. August 1996
  20.  
  21. -------------------------------------------------------------------------------
  22.  
  23. Contents
  24.  
  25. 1       A technical summary of Hugs 1.3
  26.  
  27.  
  28. 2       Hugs for beginners
  29.  
  30.         2.1     Expressions
  31.         2.2     Commands
  32.         2.3     Scripts
  33.  
  34. 3       Starting Hugs
  35.  
  36.         3.1     Environment variables
  37.         3.2     Command line options
  38.                 3.2.1   Print statistics   +s,-s
  39.                 3.2.2   Print type after evaluation   +t,-t
  40.                 3.2.3   Terminate on error   +f,-f
  41.                 3.2.4   Garbage collector notification   +g,-g
  42.                 3.2.5   Literate scripts   +l,-l,+e,-e
  43.                 3.2.6   Display dots while loading   +.,-.
  44.                 3.2.7   List files loaded   +w,-w
  45.                 3.2.8   Detailed kind errors   +k,-k
  46.                 3.2.9   Use "show'' to display results   +u,-u
  47.                 3.2.10  Import chasing   +i,-i
  48.                 3.2.11  Set heap size   -h<size>
  49.                 3.2.12  Set prompt   -p<string>
  50.                 3.2.13  Set repeat string   -r<string>
  51.                 3.2.14  Set search path   -P<path>
  52.                 3.2.15  Set editor command line   -E<cmd>
  53.  
  54. 4       Hugs commands
  55.  
  56.         4.1     Basic commands
  57.                 4.1.1   Evaluate expression   <expr>
  58.                 4.1.2   View or change command line settings   :set [<options>]
  59.                 4.1.3   Shell escape   :![<command>]
  60.                 4.1.4   Change directory   :cd <directory>
  61.                 4.1.5   Force a garbage collection   :gc
  62.                 4.1.6   List commands   :?
  63.                 4.1.7   Exit the interpreter   :quit
  64.         4.2     Loading and editing scripts and projects
  65.                 4.2.1   Load definitions from file   :load [<filename> ...]
  66.                 4.2.2   Load additional files   :also [<filename> ...]
  67.                 4.2.3   Repeat last load command   :reload
  68.                 4.2.4   Load project   :project [<project file>]
  69.                 4.2.5   Edit file   :edit [<file>]
  70.                 4.2.6   Find definition   :find <name>
  71.         4.3     Finding information about the system
  72.                 4.3.1   List names   :names [<pattern> ...]
  73.                 4.3.2   Print type of expression   :type <expr>
  74.                 4.3.3   Display information about names   :info [<name> ...]
  75.  
  76. 5       Library overview
  77.  
  78.         5.1     Standard libraries
  79.         5.2     Hugs-specific libraries
  80.  
  81. 6       Pointers to further information
  82.  
  83. References
  84.  
  85.  
  86. Conditions of use, duplication and distribution
  87.  
  88. Hugs 1.3 is copyright (c) Mark P. Jones, University of Nottingham,
  89. 1994--1996.
  90.  
  91. Permission to use, copy, modify, and distribute Hugs for any personal
  92. or educational use without fee is hereby granted, provided that:
  93.  
  94.  (a) This copyright notice is retained in both source code
  95.  and supporting documentation.
  96.  
  97.  (b) Modified versions of this software are redistributed
  98.  only if accompanied by a complete history (date, author,
  99.  description) of modifications made; the intention here is to
  100.  give appropriate credit to those involved, while
  101.  simultaneously ensuring that any recipient can determine the
  102.  origin of the software.
  103.  
  104.  (c) The same conditions are also applied to any software
  105.  system derived either in full or in part from Hugs.
  106.  
  107. No part of Hugs may be distributed as a part or accompaniment of any
  108. commercial package or product without the explicit written permission
  109. of the author and copyright holder.  The distribution of commercial
  110. products which require or make use of Hugs will normally be permitted
  111. if the Hugs distribution is supplied separately to and offered at cost
  112. price to the purchaser of the commercial product.
  113.  
  114. In specifying these conditions, our intention is to permit widespread
  115. use of Hugs while, at the same time, protecting the interests, rights
  116. and efforts of all those involved.  Please contact the author and
  117. copyright holder to arrange alternative terms and conditions if your
  118. intended use of Hugs is not permitted by the terms and conditions in
  119. this notice.
  120.  
  121. While Hugs has much in common with Gofer (from which it was originally
  122. derived), there are also some significant differences between the two
  123. systems.  For example, Hugs conforms closely to the Haskell standard
  124. while Gofer was intended as a more experimental system.  As a result,
  125. any and all rights previously conferred for the use, duplication, and
  126. distribution of Gofer do NOT automatically carry over to Hugs.
  127.  
  128. NOTICE: Hugs is provided "as is" without express or implied warranty.
  129.  
  130.  
  131. 1. A technical summary of Hugs 1.3
  132.  
  133. Hugs 1.3 provides an almost complete implementation of Haskell 1.3 [1],
  134. including:
  135.  
  136.  o Lazy evaluation, higher order functions, and pattern matching.
  137.  
  138.  o A wide range of built-in types, from characters to bignums, and
  139.    lists to functions, with comprehensive facilities for defining new
  140.    datatypes and type synonyms.
  141.  
  142.  o An advanced polymorphic type system with type and constructor class
  143.    overloading.
  144.  
  145.  o All of the features of the Haskell 1.3 expression and pattern syntax
  146.    including lambda, case, conditional and let expressions, list
  147.    comprehensions, do-notation, operator sections, and wildcard,
  148.    irrefutable and 'as' patterns.
  149.  
  150.  o An implementation of the main Haskell 1.3 primitives for monadic
  151.    I/O, with support for simple interactive programs, access to text
  152.    files, handle-based I/O, and exception handling.
  153.  
  154. The only Haskell 1.3 feature that is not supported is the module system.
  155.  
  156. Hugs is implemented as an interpreter that provides:
  157.  
  158.  o A relatively small, portable system that can be used on a range of
  159.    different machines, from home computers, to Unix workstations.
  160.  
  161.  o A read-eval-print loop for displaying the value of each expression
  162.    that is entered into the interpreter.
  163.  
  164.  o Fast loading, type checking, and compilation of script files, with
  165.    facilities for automatic loading of imported modules.
  166.  
  167.  o Integration with an external editor, chosen by the user, to allow
  168.    for rapid development, and for location of errors.
  169.  
  170.  o Modest browsing facilities that can be used to find information
  171.    about the operations and types that are available.
  172.  
  173. Hugs is a successor to Gofer --- an experimental functional programming
  174. system that was first released in September 1991 --- and users of Gofer
  175. will see much that is familiar in Hugs.  However, Hugs offers much
  176. greater compatibility with the Haskell standard; indeed, the name Hugs
  177. was originally chosen as a mnemonic for the "Haskell users' Gofer
  178. system.''  There have been many modifications and enhancements to Hugs
  179. since its first release on Valentines day, February 14, in 1995. Some
  180. of the most obvious improvements include:
  181.  
  182.  o Full support for new Haskell 1.3 features, including the labelled
  183.    field syntax, do- notation, newtype, strictness annotations in
  184.    datatypes, the Eval class, ISO character set, etc.
  185.  
  186.  o User interface enhancements, particularly the HUGSPATH and import
  187.    chasing features, both of which were motivated by a greater emphasis
  188.    on the role of libraries in Haskell 1.3.
  189.  
  190.  o Small improvements in runtime performance, and more reliable space
  191.    usage, thanks to the use of non-conservative garbage collection
  192.    during program execution.
  193.  
  194. There have also been a number of other enhancements, and fixes for bugs
  195. in previous releases, some more serious than others.
  196.  
  197. Already, there are ambitious plans for the future, with collaboration
  198. and joint releases from the functional programming groups at Nottingham
  199. and Yale. For example, in the near future, we expect to release a
  200. system combining the best of Hugs 1.3 and the recent Yale release of
  201. Hugs 1.01.  This will provide full support for modules, Haskell 1.3,
  202. and libraries for both X window and Win32 programming. However, we also
  203. intend to maintain the current release as a relatively small and stable
  204. system that will be suitable for teaching and research, even on fairly
  205. small machines.
  206.  
  207.  
  208. 2. Hugs for beginners
  209.  
  210. This section covers the basics that you need to understand to start
  211. using Hugs.  Most of the points discussed here will already be familiar
  212. to readers with experience of previous versions of Hugs or Gofer.  To
  213. begin with, we need to start the interpreter; the usual way to do this
  214. is by using the command hugs, which produces a startup banner something
  215. like the following:
  216.  
  217.       ___    ___   ___    ___   __________   __________
  218.      /  /   /  /  /  /   /  /  /  _______/  /  _______/  The Haskell User's
  219.     /  /___/  /  /  /   /  /  /  / _____   /  /______       Gofer System
  220.    /  ____   /  /  /   /  /  /  / /_   /  /______   /
  221.   /  /   /  /  /  /___/  /  /  /___/  /  _______/  /         Version 1.3
  222.  /__/   /__/  /_________/  /_________/  /_________/          August 1996
  223.  
  224.    Copyright (c) Mark P Jones, The University of Nottingham, 1994-1996.
  225.  
  226.  Reading script file "/Hugs/lib/Prelude.hs":
  227.  
  228.  Hugs session for:
  229.  /Hugs/lib/Prelude.hs
  230.  
  231. The file /Hugs/lib/Prelude.hs mentioned here contains standard
  232. definitions that are loaded into Hugs each time that the interpreter is
  233. started; the filename will vary from one installation to the next.
  234. You may notice a pause while the interpreter is initialized and the
  235. prelude definitions are loaded into the system.
  236.  
  237. The three main concepts that you need to know about before you can make
  238. proper use of Hugs are expressions, commands, and scripts.
  239.  
  240.  
  241. 2.1. Expressions
  242.  
  243. In essence, using Hugs is just like using a calculator; the interpreter
  244. simply evaluates each expression that is entered, printing the results
  245. as it goes.
  246.  
  247.  ? (2+3)*8
  248.  40
  249.  ? sum [1..10]
  250.  55
  251.  ?
  252.  
  253. The ? character on the first, third and fifth lines here is the Hugs
  254. prompt, indicating that the system is ready to accept input from the
  255. user.  In response to the first prompt, the user entered the expression
  256. (2+3)*8, which was evaluated to produce the result 40.  In response to
  257. the second prompt, the user typed the expression sum [1..10].  The
  258. notation [1..10] represents the list of integers between 1 and 10
  259. inclusive, and sum is a built-in function that calculates the sum of a
  260. list of numbers.  So the result obtained by Hugs is:
  261.  
  262.  1 + 2 + 3 + 4 + 5 + 6 + 7 + 8 + 9 + 10  =  55.
  263.  
  264. In fact, we could have typed this sum directly into Hugs:
  265.  
  266.  ? 1 + 2 + 3 + 4 + 5 + 6 + 7 + 8 + 9 + 10
  267.  55
  268.  ? 
  269.  
  270. Unlike many calculators, however, Hugs is not limited to working with
  271. numbers; expressions can involve many different types of value,
  272. including numbers, booleans, characters, strings, lists, functions, and
  273. user-defined datatypes.  Some of these are illustrated in the following
  274. example:
  275.  
  276.  ? (not True) || False
  277.  False
  278.  ? reverse "Hugs is cool"
  279.  "looc si sguH"
  280.  ? filter even [1..10]     
  281.  [2, 4, 6, 8, 10]
  282.  ? take 10 fibs where fibs = 0:1:zipWith (+) fibs (tail fibs)
  283.  [0, 1, 1, 2, 3, 5, 8, 13, 21, 34]
  284.  ?
  285.  
  286. Hugs even allows whole programs to be used as values in calculations.
  287. For example, putStr "hello, " is a simple program that outputs the
  288. string "hello, ".  Combining this with a similar program to print the
  289. string "world", gives:
  290.  
  291.  ? putStr "hello, " >> putStr "world"
  292.  hello, world
  293.  ?
  294.  
  295. Just as there are standard operations for dealing with numbers, so
  296. there are standard operations for dealing with programs.  For example,
  297. the >> operator used here constructs a new program from the programs
  298. supplied as its operands, running one after the other. Normally, Hugs
  299. just prints the value of each expression entered.  But, as this example
  300. shows, if the expression evaluates to a program, then Hugs will run it
  301. instead.
  302.  
  303.  
  304. 2.2. Commands
  305.  
  306. Each line that you enter in response to the Hugs prompt is treated as a
  307. command to the interpreter.  For example, when you enter an expression
  308. into Hugs, it is treated as a command to evaluate that expression, and
  309. to display the result. There are two commands that are particularly
  310. worth remembering:
  311.  
  312.  o :q exits the interpreter. On most systems, you can also terminate
  313.    Hugs by typing the end-of-file character (control-Z, on a DOS
  314.    machine, usually control-D on a Unix system).
  315.  
  316.  o :? prints a list of all the commands, which can be useful if you
  317.    forget the name of the command that you want to use.
  318.  
  319. Like most other commands in Hugs, these commands both start with a
  320. colon, :.
  321.  
  322. Note that the interrupt key (control-C or control-Break on most
  323. systems) can be used to abandon the process of reading script files, or
  324. evaluating expressions.  When the interrupt is detected, Hugs prints
  325. {Interrupted!} and returns to the prompt so that further commands can
  326. be entered.
  327.  
  328.  
  329. 2.3. Scripts
  330.  
  331. Functions like sum, >> and take, used in the examples above, are all
  332. defined in the Hugs prelude; you can actually do quite a lot using just
  333. the types and operations provided by the prelude. But, in general, you
  334. will also want to define new types and operations, storing them in
  335. script files that can be loaded and used by Hugs. For example, suppose
  336. that you put the following definition:
  337.  
  338.  fact n = product [1..n]
  339.  
  340. into a file called fact.hs.  (By convention, Hugs scripts are stored in
  341. files ending with the characters .hs.) The product function used here
  342. is also defined in the prelude, and can be used to calculate the
  343. product of a list of numbers, just as you might use sum to calculate
  344. the corresponding sum. So the line above defines a function fact that
  345. takes an argument n and calculates its factorial.  In standard
  346. mathematical notation, fact n = n!, which is usually defined by an
  347. equation:
  348.  
  349.  n! = 1 * 2 * ... * (n-1) * n
  350.  
  351. Once you become familiar with the notation, you will see that the Hugs
  352. definition is really very similar to this informal, mathematical
  353. version: the factorial of a number n is the product of the numbers from
  354. 1 to n.
  355.  
  356. Before we can use this definition in a Hugs session, we have to load
  357. fact.hs into the interpreter.  One of the simplest ways to do this uses
  358. the :load command:
  359.  
  360.  ? :load fact.hs 
  361.  Reading script file "fact.hs":
  362.                     
  363.  Hugs session for:
  364.  /Hugs/lib/Prelude.hs
  365.  fact.hs
  366.  ? 
  367.  
  368. Notice the list of filenames displayed after Hugs session for:; this
  369. tells you which files of definitions are currently being used by Hugs,
  370. the first of which is always the standard prelude.  Now that the
  371. fact.hs file has been loaded, we can start to use the fact function
  372. that we have defined:
  373.  
  374.  ? fact 6
  375.  720
  376.  ? fact 6 + fact 7
  377.  5760
  378.  ? fact 7 `div` fact 6
  379.  7
  380.  ?
  381.  
  382. As another example, the standard formula for the number of different
  383. ways of choosing r objects from a collection of n objects is n! `div`
  384. (r! * (n-r)!).  One simple and direct (but otherwise not particularly
  385. good) definition for this function in Hugs is as follows:
  386.  
  387.  comb n r = fact n `div` (fact r * fact (n-r))
  388.  
  389. One way to use this function is to include its definition as part of an
  390. expression entered in directly to Hugs:
  391.  
  392.  ? comb 5 2 where comb n r = fact n `div` (fact r * fact (n-r))
  393.  10
  394.  ? 
  395.  
  396. The definition of comb here is local to this expression.  If we want to
  397. use comb several times, then it would be sensible to add its definition
  398. to the file fact.hs.  Once this has been done, and the fact.hs file has
  399. been reloaded, we can use the comb function like any other built-in
  400. operator:
  401.  
  402.  ? comb 5 2
  403.  10
  404.  ?
  405.  
  406.  
  407. 3. Starting Hugs
  408.  
  409. The Hugs interpreter is usually started with a command line of the
  410. form:
  411.  
  412.   hugs [option | file] ...
  413.  
  414. (This manual assumes that Hugs has already been successfully installed
  415. on your system, and that it can be invoked using the hugs command.)  As
  416. soon as it starts, the interpreter will perform the following tasks:
  417.  
  418.  o Process any command line options. These are distinguished from other
  419.    command line arguments by a leading + or - and are used to customize
  420.    the behaviour of the interpreter.
  421.  
  422.  o Initialize the interpreter's internal data structures.  In
  423.    particular, the heap is initialized, and its size is fixed at this
  424.    point; if you want to run the interpreter with a heap size other
  425.    than the default, then this must be specified using the -h command
  426.    line option when the interpreter is started.
  427.  
  428.  o Load the prelude file.  The interpreter will look for the prelude
  429.    file on the path specified by the HUGSPATH environment variable, or
  430.    by the path supplied with a -P command line option. If the prelude
  431.    cannot be found in one of the path directories, or if the path has
  432.    not been set to an appropriate value, then the interpreter will look
  433.    for Prelude.hs in the current directory.  If the prelude cannot be
  434.    found, or if an error occurs while it is being loaded, then the
  435.    interpreter will terminate; Hugs will not run without the prelude
  436.    file.
  437.  
  438.  o Load any script files specified on the command line.  The effect of
  439.    a command hugs f1 ... fn is the same as starting up Hugs with the
  440.    hugs command and then typing :load f1 ... fn. In particular, the
  441.    interpreter will not terminate if a problem occurs while it is
  442.    trying to load one of the specified files, but it will abort the
  443.    attempted load command.
  444.  
  445. The environment variables and command line options used by Hugs are
  446. described in the following sections.
  447.  
  448. 3.1. Environment variables
  449.  
  450. There are two environment variables that should normally be set before
  451. the interpreter is used:
  452.  
  453.  o HUGSPATH specifies the list of directories that will be searched for
  454.    Hugs script files, including the standard prelude when the
  455.    interpreter is first invoked.  Directory names should be separated
  456.    by colons or, on DOS/Windows machines, by semicolons, or on
  457.    RISCOS machines by a comma.  Empty components in the path will 
  458.    be treated as references to the current working directory.
  459.  
  460.  o HUGSEDIT specifies the command line for an external editor.  Any
  461.    occurrences of %d and %s in the HUGSEDIT command line will be
  462.    replaced by the start line number and the name of the file to be
  463.    edited, respectively, when the editor is invoked.  If specified, the
  464.    line number parameter is used to let the interpreter start the
  465.    editor at the line where an error was detected, or, in the case of
  466.    the :find command, where a specified variable was defined.
  467.  
  468. Values for these variables can be provided when the interpreter is
  469. invoked using the -P and -E command line options, respectively; these
  470. settings can be further inspected and modified while the interpreter is
  471. running using the :set command.
  472.  
  473. However, it is usually more convenient to save preferred settings in
  474. environment variables that will be used automatically each time the
  475. interpreter is started.  The method for setting these variables depends
  476. on the machine and operating system that you are using, and on the way
  477. that the Hugs system was installed.  The following examples show some
  478. typical settings for Unix machines and PCs:
  479.  
  480.  o The method for setting HUGSPATH and HUGSEDIT on a Unix machine
  481.    depends on the choice of shell.  For example, a C-shell user might
  482.    add something like the following to their .cshrc file:
  483.  
  484.     set HUGSPATH /usr/local/Hugs/lib:/usr/local/Hugs/libhugs
  485.     set HUGSEDIT "vi +%d %s"
  486.  
  487.    The editor specified here is vi which allows the user to specify a
  488.    start up line number by preceding it with a + character.  The
  489.    settings are easily changed to accommodate other editors.  For
  490.    example, you can use the following line to configure Hugs to use
  491.    emacs:
  492.  
  493.     set HUGSEDIT "emacs +%d %s"
  494.  
  495.    If you are installing Hugs for the benefit of several different
  496.    users, then you should probably use a script file that sets
  497.    appropriate values for the environment variables, and then invokes
  498.    the interpreter:
  499.  
  500.     #!/bin/sh
  501.     HUGSPATH=/usr/local/Hugs/lib:/usr/local/Hugs/libhugs
  502.     export HUGSPATH
  503.     HUGSEDIT="vi +%d %s"
  504.     export HUGSEDIT
  505.     exec /usr/local/bin/hugs +s $*
  506.  
  507.    One advantage of this approach is that individual users do not have
  508.    to worry about setting the environment variables themselves.  In
  509.    addition, the script can be used to specify startup command line
  510.    options---like the +s in this example---without needing to change
  511.    the default settings that are built in to the interpreter. It is
  512.    easy for more advanced users to copy and customize a script like
  513.    this to suit their own needs.
  514.  
  515.  o Users of DOS or Windows should add the following lines to autoexec.bat:
  516.  
  517.     set HUGSPATH=\hugs\lib;\hugs\libhugs
  518.     set HUGSEDIT=vi +%%d %%s
  519.  
  520.    The setting for HUGSPATH assumes that the system has been installed
  521.    in a top-level hugs directory, and will need to be modified
  522.    accordingly if a different directory was chosen. In a similar way,
  523.    the setting for HUGSEDIT will only work if you have installed the
  524.    editor program, vi, that it refers to.  If you don't want to install
  525.    a new editor, then you can  set HUGSEDIT=edit for the standard DOS
  526.    editor, or set HUGSEDIT=notepad for the Windows 95 notepad editor.
  527.    Note, however, that neither edit or notepad allow the intepreter to
  528.    specify a start line number.
  529.  
  530. For completeness, we should also mention the other environment
  531. variables that are used by Hugs:
  532.  
  533.  o The SHELL variable on a Unix machine, or the COMSPEC variable on a
  534.    DOS machine, determines which shell is used by the :! command.
  535.  
  536.  o The EDITOR variable is used to try and locate an editor if the
  537.    HUGSEDIT variable has not been set.  Note, however, that this
  538.    variable does not normally provide the extra information that is
  539.    needed to be able to start the editor at a specific line in the
  540.    input file.
  541.  
  542. Previous versions of Hugs used a HUGS variable to locate the standard
  543. prelude file, but this variable is not used by Hugs 1.3.
  544.  
  545. 3.2. Command line options
  546.  
  547. The behaviour of the interpreter, particularly the read-eval-print
  548. loop, can be customized using command line options.  For example, you
  549. might use:
  550.  
  551.  hugs -i +g +h30K
  552.  
  553. to start the interpreter with the i option (import chasing) disabled,
  554. the g option (garbage collector messages) enabled, and with a heap of
  555. thirty thousand cells.  As this example suggests, most of the command
  556. line options are toggles, meaning that they can either be switched on
  557. (by preceding the option with a + character) or off (by using a -
  558. character).  Options may also be grouped together. For example, hugs
  559. +stf -le is equivalent to hugs +s +t +f -l -e.
  560.  
  561. To avoid any confusion with filenames entered on the command line,
  562. option settings must always begin with a leading + or - character.
  563. However, in some cases---the h, p, r, P, and E options---the choice is
  564. not significant.  With the exception of the heap size option, h, all
  565. command line options can be changed while the interpreter is running
  566. using the :set command.  The same command can be used (without any
  567. arguments) to display a summary of the available options and to inspect
  568. their current settings.
  569.  
  570. The complete set of Hugs command line options is described in the
  571. sections below.
  572.  
  573.  
  574. 3.2.1. Print statistics   +s,-s
  575.  
  576. Normally, Hugs just shows the result of evaluating each expression:
  577.  
  578.  ? map (\x -> x*x) [1..10]
  579.  [1, 4, 9, 16, 25, 36, 49, 64, 81, 100]
  580.  ? [1..]
  581.  [1, 2, 3, 4, {Interrupted!}
  582.  ?
  583.  
  584. With the +s option, the interpreter will also display statistics about
  585. the total number of reductions and cells; the former gives a measure of
  586. the work done, while the latter gives an indication of the amount of
  587. memory used.  For example:
  588.  
  589.  ? :set +s
  590.  ? map (\x -> x*x) [1..10]
  591.  [1, 4, 9, 16, 25, 36, 49, 64, 81, 100]
  592.  (230 reductions, 408 cells)
  593.  ? [1..]
  594.  [1, 2, 3, 4, {Interrupted!}
  595.  (18 reductions, 54 cells)
  596.  ?
  597.  
  598. Note that the statistics produced by +s are an extremely crude measure
  599. of the behaviour of a program, and can easily be misinterpreted. For
  600. example:
  601.  
  602.  o The fact that one expression requires more reductions than another
  603.    does not necessarily mean that the first is slower; some reductions
  604.    require much more work than others, and it may be that the average
  605.    cost of reductions in the first expression is much lower than the
  606.    average for the second.
  607.  
  608.  o The cell count does not give any information about residency, which
  609.    is the number of cells that are being used at any given time.  For
  610.    example, it does not distinguish between computations that run in
  611.    constant space and computations with residency proportional to the
  612.    size of the input.
  613.  
  614. One reasonable use of the statistics produced by +s would be to observe
  615. general trends in the behaviour of a single algorithm with variations
  616. in its input.
  617.  
  618.  
  619. 3.2.2. Print type after evaluation   +t,-t
  620.  
  621. With the +t option, the interpreter will display both the result and
  622. type of each expression entered at the Hugs prompt:
  623.  
  624.  ? map (\x -> x*x) [1..10]
  625.  [1, 4, 9, 16, 25, 36, 49, 64, 81, 100] :: [Int]
  626.  ? not True
  627.  False :: Bool
  628.  ? \x -> x
  629.  <<function>> :: a -> a
  630.  ?
  631.  
  632. Note that the interpreter will not display the type of an expression if
  633. its evaluation is interrupted or fails with a run-time error. In
  634. addition, the interpreter will not print the type, IO (), of a program
  635. in the IO monad; the interpreter treats these as a special case, giving
  636. the programmer more control over the output that is produced.
  637.  
  638.  
  639. 3.2.3. Terminate on error   +f,-f
  640.  
  641. In normal use, the evaluation of an expression is abandoned completely
  642. if a run-time error occurs, such as a failed pattern match or an
  643. attempt to divide by zero.  For example:
  644.  
  645.  ? [1 `div` 0]
  646.  [
  647.  Program error: {primDivInt 1 0}
  648.  
  649.  ? [1 `div` 0, 2]
  650.  [
  651.  Program error: {primDivInt 1 0}
  652.  
  653.  ?
  654.  
  655. This is often useful during program development because it means that
  656. errors are detected as soon as they occur. However, technically
  657. speaking, the two expressions above have different meanings; the first
  658. is a singleton list, while the second has two elements. Unfortunately,
  659. the output produced by Hugs does not allow us to distinguish between
  660. the values.
  661.  
  662. The -f option can be used to make the Hugs printing option a little
  663. more accurate; this should normally be combined with -u because the
  664. built-in printer is better than the user-defined show functions at
  665. recovering from evaluation errors.  With these settings, if the
  666. interpreter encounters an irreducible subexpression, then it prints the
  667. expression between a matching pair of braces and attempts to continue
  668. with the evaluation of other parts of the original expression.  For the
  669. examples above, we get:
  670.  
  671.  ? :set -u -f
  672.  ? [1 `div` 0]         -- value is [bottom]
  673.  [{primDivInt 1 0}]
  674.  ? [1 `div` 0, 2]
  675.  [{primDivInt 1 0}, 2] -- value is [bottom, 2]
  676.  ?
  677.  
  678. Notice that, reading an expression in braces as bottom, both of the
  679. values printed by Hugs give the correct value.  Of course, it is not
  680. possible to detect all occurrences of bottom like this, such as those
  681. produced by a nonterminating computation:
  682.  
  683.  ? last [1..]
  684.  ^C{Interrupted!}      -- nothing printed until interrupted
  685.  
  686.  ?
  687.  
  688. Note that the basic method of evaluation is the same with both the +f
  689. and -f options; all that changes is the way that the printing mechanism
  690. deals with certain kinds of runtime error.
  691.  
  692.  
  693. 3.2.4. Garbage collector notification   +g,-g
  694.  
  695. It is sometimes useful to monitor uses of the garbage collector, and to
  696. determine how many cells are recovered with each collection. If the +g
  697. option is set, then the interpreter will print a message of the form
  698. {{Gc:num}} each time that the garbage collector is invoked.  The number
  699. after the colon indicates the total number of cells that have been
  700. recovered.
  701.  
  702. As a simple application, we can use garbage collector messages to
  703. observe that an attempt to sum an infinite list, although
  704. non-terminating, will at least run in constant space:
  705.  
  706.  ? :set +g
  707.  ? sum [1..]
  708.  {{Gc:95763}}{{Gc:95760}}{{Gc:95760}}{{Gc:95760}}{Interrupted!}
  709.  
  710.  ?
  711.  
  712. Garbage collector messages may be printed at almost any stage in a
  713. computation (or indeed while loading, type checking or compiling a file
  714. of definitions).  For this reason, it is often best to turn garbage
  715. collector messages off (using :set -g, for example) if they are not
  716. required.
  717.  
  718.  
  719. 3.2.5. Literate scripts   +l,-l,+e,-e
  720.  
  721. Like most programming languages, Hugs usually treats source file input
  722. as a sequence of lines in which program text is the norm, and comments
  723. play a secondary role.  In Hugs, as in Haskell, comments are introduced
  724. by the character sequences -- and {- ... -}.
  725.  
  726. An alternative approach, using an idea described by Knuth as "literate
  727. programming'', gives more emphasis to comments and documentation, with
  728. additional characters needed to distinguish program text from comments.
  729. Hugs supports a form of literate programming based on an idea due to
  730. Richard Bird and originally implemented as part of the functional
  731. programming language Orwell.
  732.  
  733. In a Hugs literate script, program lines are marked by a > character in
  734. the first column; any other line is treated as a program comment. This
  735. makes it particularly easy to write a document which is both an
  736. executable Hugs script and, at the same time, without need for any
  737. preprocessing, suitable for use with document preparation software such
  738. as LaTeX.
  739.  
  740. Hugs will treat any input file with a name ending in .hs as a normal
  741. script and any input file with a name ending in .lhs as a literate
  742. script.  If the -l option is selected, then any other file loaded into
  743. Hugs will be treated as a normal script.  Conversely, if +l is
  744. selected, then these files will be treated as literate scripts.  The
  745. effect of using literate scripts can be thought of as applying a
  746. preprocessor to each input file that is loaded into Hugs.  This has a
  747. particularly simple definition in Hugs:
  748.  
  749.  illiterate   :: String -> String
  750.  illiterate cs = unlines [ " " ++ xs | ('>':xs) <- lines cs ]
  751.  
  752. The system of literate scripts that was used in Orwell is a little more
  753. complicated than this and requires the programmer to adopt two further
  754. conventions in an attempt to catch simple errors in literate scripts:
  755.  
  756.  o Every input file must contain at least one line whose first
  757.    character is >.  This prevents scripts with no definitions (because
  758.    the programmer has forgotten to use the > character to mark
  759.    definitions) from being accepted.
  760.  
  761.  o Lines containing definitions must be separated from comment lines by
  762.    one or more blank lines (i.e., lines containing only space and tab
  763.    characters).  This is useful for catching programs where the leading
  764.    > character has been omitted from one or more lines in the
  765.    definition of a function.  For example:
  766.  
  767.     > map f []     = []
  768.       map f (x:xs) = f x : map f xs
  769.  
  770.    would be treated as an error.
  771.  
  772. Hugs will report on errors of this kind whenever the -e option is
  773. enabled (the default setting).
  774.  
  775.  
  776. 3.2.6. Display dots while loading   +.,-.
  777.  
  778. As Hugs loads each script file into the interpreter, it prints a short
  779. sequence of messages to indicate progress through the various stages of
  780. parsing the script, dependency analysis, type checking, and
  781. compilation. With the default setting, -., the interpreter prints the
  782. name of each stage, backspacing over it to erase it from the screen
  783. when the stage is complete.  If you are fortunate enough to be using a
  784. fast machine, you may not always see the individual words as they flash
  785. past.  After loading a file, your screen will typically look something
  786. like this:
  787.  
  788.  ? :l Array
  789.  Reading script file "/Hugs/lib/Array.hs":
  790.  
  791.  Hugs session for:
  792.  /Hugs/lib/Prelude.hs
  793.  /Hugs/lib/Array.hs
  794.  ?
  795.  
  796. On some systems, the use of backspace characters to erase a line may
  797. not work properly---for example, if you try to run Hugs from within
  798. emacs.  In this case, you may prefer to use the +.  setting which
  799. prints a separate line for each stage, with a row of dots to indicate
  800. progress:
  801.  
  802.  ? :load Array
  803.  Reading script file "/Hugs/lib/Array.hs":
  804.  Parsing....................................................
  805.  Dependency analysis........................................
  806.  Type checking..............................................
  807.  Compiling..................................................
  808.  
  809.  Hugs session for:
  810.  /Hugs/lib/Prelude.hs
  811.  /Hugs/lib/Array.hs
  812.  ?
  813.  
  814. This setting can also be useful on very slow machines where the growing
  815. line of dots provides confirmation that the interpreter is making
  816. progress through the various stages involved in loading a file.  You
  817. should note, however, that the mechanisms used to display the rows of
  818. dots can add a substantial overhead to the time that it takes to load
  819. script files; in one experiment, a particular program took nearly five
  820. times longer to load when the +. option was used.
  821.  
  822.  
  823. 3.2.7. List files loaded   +w,-w
  824.  
  825. By default, Hugs prints a complete list of all the script files that
  826. have been loaded into the system after every successful load or reload
  827. command. The -w option can be used to turn this feature off.  Note that
  828. the :info command, without any arguments, can also be used to list the
  829. names of currently loaded script files.
  830.  
  831.  
  832. 3.2.8. Detailed kind errors   +k,-k
  833.  
  834. Hugs uses a system of kinds to ensure that type expressions are
  835. well-formed: for example, to make sure that each type constructor is
  836. applied to the appropriate number of arguments.  For example, the
  837. following lines:
  838.  
  839.  data Tree a  = Leaf a | Tree a :^: Tree a
  840.  type Example = Tree Int Bool
  841.  
  842. will cause an error:
  843.  
  844.  ERROR "Demo" (line 12): Illegal type "Tree Int Bool" in
  845.                          constructor application
  846.  
  847. The problem here is that Tree is a unary constructor of kind * -> *,
  848. but the definition of Example uses it as a binary constructor with at
  849. least two arguments, and hence expecting a kind of the form (* -> * ->
  850. k), for some kind k.
  851.  
  852. By default, Hugs reports problems like this with a simple message like
  853. the one shown above.  However, if the +k option is selected, then the
  854. interpreter will print a more detailed version of the error message,
  855. including details about the kinds of the type expressions that are
  856. involved:
  857.  
  858.  ERROR "Demo.hs" (line 12): Kind error in constructor application
  859.  *** expression     : Tree Int Bool
  860.  *** constructor    : Tree
  861.  *** kind           : * -> *
  862.  *** does not match : * -> a -> b
  863.  ?
  864.  
  865. In addition, if the +k option is used, then Hugs will also include
  866. information about kinds in the information produced by the :info
  867. command:
  868.  
  869.  ? :info Tree
  870.  -- type constructor with kind * -> *
  871.  data Tree a
  872.  
  873.  -- constructors:
  874.  Leaf :: a -> Tree a
  875.  (:^:) :: Tree a -> Tree a -> Tree a
  876.  
  877.  -- instances:
  878.  instance Eval (Tree a)
  879.  
  880.  ?
  881.  
  882.  
  883. 3.2.9. Use "show'' to display results   +u,-u
  884.  
  885. In normal use, Hugs displays the value of each expression entered into
  886. the interpreter by applying the standard prelude function:
  887.  
  888.  show :: Show a => a -> String
  889.  
  890. to it and displaying the resulting string of characters.  This approach
  891. works well for any value whose type is an instance of the standard Show
  892. class; for example, the prelude defines instances of Show for most of
  893. the built-in datatypes.  It is also easy for users to extend the class
  894. with new datatypes, either by providing a handwritten instance
  895. declaration, or by requesting an automatically derived instance as part
  896. of the datatype definition, as in:
  897.  
  898.  data Rainbow = Red | Orange | Yellow | Green | Blue | Indigo | Violet
  899.                 deriving Show
  900.  
  901. The advantage of using show is that it allows programmers to display
  902. the results of evaluations in whatever form is most convenient for
  903. users---which is not always the same as the way in which the values are
  904. represented.
  905.  
  906. This is probably all that most users will ever need.  However, there
  907. are some circumstances where it is not convenient, for example, for
  908. certain kinds of debugging or for work with datatypes that are not
  909. instances of Show.  In these situations, the -u option can be used to
  910. prevent the use of show.  In its place, Hugs will use a built-in
  911. printing mechanism that works for all datatypes, and uses the
  912. representation of a value to determine what gets printed. At any point,
  913. the default printing mechanism can be restored by setting +u.
  914.  
  915.  
  916. 3.2.10. Import chasing   +i,-i
  917.  
  918. Import chasing is a simple, but flexible mechanism for dealing with
  919. programs that involve multiple script files.  It works in a natural
  920. way, using the information in import statements at the beginning of
  921. script files, and is particularly useful for large programs, or for
  922. programs that use standard Hugs libraries.
  923.  
  924. For example, consider a script file Demo.hs that requires the
  925. facilities provided by the STArray library. This dependency might be
  926. reflected by including the following import statement at the beginning
  927. of Demo.hs:
  928.  
  929.  import STArray
  930.  
  931. Now, if we try to load this script into Hugs, then the system will
  932. automatically search for the STArray library and load it into Hugs,
  933. before Demo.hs is loaded.  In fact, the STArray library also begins
  934. with some import statements:
  935.  
  936.  import ST
  937.  import Array
  938.  
  939. So, Hugs will actually load the ST and Array libraries first, then the
  940. STArray library, and only then will it try to read the rest of
  941. Demo.hs:
  942.  
  943.  ? :load Demo
  944.  Reading script file "Demo.hs":
  945.  Reading script file "/hugs/libhugs/STArray.hs":
  946.  Reading script file "/hugs/libhugs/ST.hs":
  947.  Reading script file "/hugs/lib/Array.hs":
  948.  Reading script file "/hugs/libhugs/STArray.hs":
  949.  Reading script file "Demo.hs":
  950.  ?
  951.  
  952. Initially, the interpreter reads only the first part of any script file
  953. loaded into the system, upto and including any import statements. If
  954. there are no imports, or if the files specified as imports have already
  955. been loaded, then the system carries on and loads the script file as
  956. normal. On the other hand, if the script includes import statements for
  957. files that have not already been loaded, then the interpreter postpones
  958. the task of reading the current script until all of the specified
  959. imports have been successfully loaded.  This explains why the Demo.hs
  960. script and the STArray library are read twice in the example above;
  961. first to determine which imports are required, and then to read in the
  962. rest of the file once the necessary imports have been loaded.
  963.  
  964. The list of directories and filenames that Hugs tries in an attempt to
  965. locate the source for a module Mod named in an import statement can be
  966. specified by:
  967.  
  968.  [ (dir,"Mod"++suf) | dir <- [d] ++ path ++ [""],
  969.                       suf <- ["", ".hs", ".lhs"]]
  970.  
  971. The search starts in the directory d where the file containing the
  972. import statement was found, then tries each of the directories in the
  973. HUGSPATH, represented here by path, and ends with "", which gives a
  974. search relative to the current directory. The fact that the search
  975. starts in d is particularly important because it means that you can
  976. load a multi-file program into Hugs without having to change to the
  977. directory where its source code is located. For example, suppose that
  978. /tmp contains the files, A.hs, B.hs, and C.hs,  that B imports A, and
  979. that C imports B. Now, regardless of the current working directory, you
  980. can load the whole program with the command :load /tmp/C; the import in
  981. C will be taken as a reference to /tmp/B.hs, while the import in that
  982. file will be taken as a reference to /tmp/A.hs.
  983.  
  984. Import chasing is often very useful, but you should also be aware of
  985. its limitations:
  986.  
  987.  o Mutually recursive modules are not supported; if A imports B, then B
  988.    must not import A, either directly or indirectly through another one
  989.    of its imports.
  990.  
  991.  o Import chasing assumes a direct mapping from module names to the
  992.    names of the files that they are stored in.  If A imports B, then
  993.    the code for B must be in a script file called either B, B.hs, or
  994.    B.lhs, and must be located in one of the directories specified
  995.    above.
  996.  
  997.    On rare occasions, it is useful to specify a particular pathname as
  998.    the target for an import statement; Hugs allows string literals to
  999.    be used as module identifiers for this purpose:
  1000.  
  1001.      import "../TypeChecker/Types.hs"
  1002.  
  1003.    Note, however, that this is a nonstandard feature of Hugs, and that
  1004.    it is not valid Haskell syntax.  You should also be aware that Hugs
  1005.    uses the names of script files in deciding whether a particular
  1006.    import has already been loaded, so you should avoid situations where
  1007.    a single file is referred to by more than one name.  For example,
  1008.    you should not assume that Hugs will be able to determine whether
  1009.    Demo.hs and ./Demo.hs are references to the same file.
  1010.  
  1011.  o Hugs allows multiple module definitions within a single script file,
  1012.    but the import chasing mechanisms do not work properly with such
  1013.    files because they only take account of import statements in the
  1014.    first module.
  1015.  
  1016. Import chasing is usually enabled by default (setting +i), but it can
  1017. also be disabled using the -i option.
  1018.  
  1019.  
  1020. 3.2.11. Set heap size   -h<size>
  1021.  
  1022. A -h<size> command line option can be used to request a particular heap
  1023. size for the interpreter---the total number of cells that are available
  1024. at any one time---when Hugs is first loaded.  The request will only be
  1025. honoured if it falls within a certain range, which depends on the
  1026. machine, and the version of Hugs that is used.  The <size> parameter
  1027. may include a K or k suffix, which acts as a multiplier by 1,000. For
  1028. example, either of the following commands:
  1029.  
  1030.  hugs -h25000
  1031.  hugs -h25K
  1032.  
  1033. will usually start the Hugs interpreter with a heap of 25,000 cells.
  1034. Note that the heap is used to hold an intermediate (parsed) form of
  1035. script files while they are being read, type checked and compiled.  It
  1036. follows that, the larger the script file, the larger the heap required
  1037. to enable that file to be loaded into Hugs.  In practice, most large
  1038. programs are written (and loaded) as a number of separate scripts which
  1039. means that this does not usually cause problems.
  1040.  
  1041. Unlike all of the other command line options described here, the heap
  1042. size setting cannot be changed from within the interpreter using a :set
  1043. command.
  1044.  
  1045.  
  1046. 3.2.12. Set prompt   -p<string>
  1047.  
  1048. A -p<str> option can be used to change the prompt to the specified
  1049. string, <str>:
  1050.  
  1051.  ? :set -p"Hugs> "
  1052.  Hugs> :set -p"? "
  1053.  ?
  1054.  
  1055. Note that you will need to use quotes around the prompt string if you
  1056. want to include spaces or special characters.
  1057.  
  1058.  
  1059. 3.2.13. Set repeat string   -r<string>
  1060.  
  1061. Hugs allows the user to recall the last expression entered into the
  1062. interpreter by typing the characters $$ as part of the next
  1063. expression:
  1064.  
  1065.  ? map (1+) [1..10]
  1066.  [2, 3, 4, 5, 6, 7, 8, 9, 10, 11]
  1067.  ? filter even $$
  1068.  [2, 4, 6, 8, 10]
  1069.  ?
  1070.  
  1071. A -r<str> option can be used to change the repeat string---the symbol
  1072. used to recall the last expression---to <str>.  For example, users of
  1073. Standard ML might be more comfortable using:
  1074.  
  1075.  ? :set -rit
  1076.  ? 6 * 7
  1077.  42
  1078.  ? it + it
  1079.  84
  1080.  ? 
  1081.  
  1082. Another reason to change the repeat string is to avoid clashes with
  1083. uses of the same symbol in a particular program; for example, if $$ is
  1084. defined as an operator in a Hugs script.
  1085.  
  1086. Note that the repeat string must be a valid Haskell identifier or
  1087. symbol, although it will always be parsed as an identifier.  If the
  1088. repeat string is set to a value that is neither an identifier or symbol
  1089. (for example, -r0), then the repeat last expression facility will be
  1090. disabled.
  1091.  
  1092.  
  1093. 3.2.14. Set search path   -P<path>
  1094.  
  1095. A -P<path> option can be used to change the Hugs search path to the
  1096. specified <path>. The search path is usually initialized to the value
  1097. of the HUGSPATH environment variable when the interpreter starts
  1098. running.
  1099.  
  1100.  
  1101. 3.2.15. Set editor command line   -E<cmd>
  1102.  
  1103. A -E<cmd> option can be used to change the editor command line string
  1104. to the specified <cmd> while the interpreter is running.  The editor
  1105. command line string is usually initialized to the value of the HUGSEDIT
  1106. environment variable when the interpreter starts running.
  1107.  
  1108.  
  1109. 4. Hugs commands
  1110.  
  1111. Hugs provides a number of commands that can be used to evaluate
  1112. expressions, to load script files, and to inspect or modify the
  1113. behaviour of the system while the interpreter is running.  Almost all
  1114. of the commands in Hugs begin with the : character, followed by a short
  1115. command word.  For convenience, all but the first letter of a command
  1116. may be omitted.  For example, :l, :s and :q can be used as
  1117. abbreviations for the :load, :set and :quit commands, respectively.
  1118.  
  1119. Most Hugs commands take arguments, separated from the command itself,
  1120. and from one another, by spaces.  The Haskell syntax for string
  1121. constants can be used to enter parts of arguments that contain spaces,
  1122. newlines, or other special characters.  For example, the command:
  1123.  
  1124.  :load My File
  1125.  
  1126. will be treated as a command to load two files, My and File.  Any of the
  1127. following commands can be used to load a single My File file whose name
  1128. includes an embedded space:
  1129.  
  1130.  :load "My File"
  1131.  :load "My\SPFile"
  1132.  :load "My\  \ File"
  1133.  :load My" "File
  1134.  
  1135. However, in practice, filenames do not usually include spaces or
  1136. special characters and can be entered without surrounding quotes, as
  1137. in:
  1138.  
  1139.  :load fact.hs
  1140.  
  1141. The full set of Hugs commands is described in the following sections.
  1142.  
  1143.  
  1144. 4.1. Basic commands
  1145.  
  1146. 4.1.1. Evaluate expression   <expr>
  1147.  
  1148. To evaluate an expression, the user simply enters it at the Hugs
  1149. prompt. This is treated as a special case, without the leading colon
  1150. that is  required for other commands.  The actual behaviour of the
  1151. evaluator depends on the type of <expr>:
  1152.  
  1153.    If <expr> has type IO (), then it will be treated as a program using
  1154.    the I/O facilities provided by the Haskell IO monad.
  1155.  
  1156.      ? putStr "hello, world"
  1157.      hello, world
  1158.      ? 
  1159.  
  1160.    In any other case, the value produced by the expression is converted
  1161.    to a string by applying the show function from the standard prelude,
  1162.    and the interpreter uses this to print the result.
  1163.  
  1164.      ? "hello" ++ ", " ++ "world"
  1165.      "hello, world"
  1166.      ? 
  1167.  
  1168.    Unlike previous versions of Hugs and Gofer, there is no special
  1169.    treatment for values of type String; to display a string without the
  1170.    enclosing quotes and special escapes, you should turn it into a
  1171.    program using the putStr function, as shown above.
  1172.  
  1173. The interpreter will not evaluate an expression that contains a syntax
  1174. error, a type error, or a reference to an undefined variable:
  1175.  
  1176.  ? sum [1..)
  1177.  ERROR: Syntax error in expression (unexpected `)')
  1178.  ? sum 'a'
  1179.  ERROR: Type error in application
  1180.  *** expression     : sum 'a'
  1181.  *** term           : 'a'
  1182.  *** type           : Char
  1183.  *** does not match : [a]
  1184.  ? sum [1..n]
  1185.  ERROR: Undefined variable "n"
  1186.  ? 
  1187.  
  1188. Another common problem occurs if there is no show function for the
  1189. expression entered---that is, if its type is not an instance of theShow
  1190. class.  For example, getChar has type IO Char which does not match the
  1191. type IO () for a program and is not an instance of Show:
  1192.  
  1193.  ? getChar
  1194.  ERROR: Cannot find "show" function for:
  1195.  *** expression : getChar
  1196.  *** of type    : IO Char
  1197.  ? 
  1198.  
  1199. In this particular case, the problem occurs because the user has not
  1200. specified what they want to do with the character that is returned
  1201. by getChar.  If you want to run the program and discard its result, then
  1202. you must do this explicitly:
  1203.  
  1204.  ? getChar >> return ()
  1205.  w
  1206.  ?
  1207.  
  1208. If the errors occurs when you try to display the value of a
  1209. user-defined datatype, then you will need to add an instance of the
  1210. Show class to your program.  One of the simplest way to achieve this is
  1211. to request a derived instance of Show as part of the datatype
  1212. definition, as in:
  1213.  
  1214.  data Date = Date { day::Int, month::Month, year::Int }
  1215.              deriving Show
  1216.  
  1217.  data Month = Jan | Feb | Mar | Apr | May | Jun
  1218.             | Jul | Aug | Sep | Oct | Nov | Dec
  1219.               deriving Show
  1220.  
  1221.  xmas = Date { day = 25, month = Dec, year = 1996 }
  1222.  
  1223. For example, once these definitions have been loaded into Hugs, we can
  1224. evaluate and display the date xmas as we would expect:
  1225.  
  1226.  ? xmas
  1227.  Date{day=25,month=Dec,year=1996}
  1228.  ? 
  1229.  
  1230. You should also note that the behaviour of the evaluator can be changed
  1231. while the interpreter is running by using the :set command to modify
  1232. command line settings.
  1233.  
  1234.  
  1235. 4.1.2. View or change command line settings   :set [<options>]
  1236.  
  1237. Without any arguments, the :set command displays a list of the command
  1238. line options and their current settings. The following output shows the
  1239. default settings on a typical machine:
  1240.  
  1241.  ? :set
  1242.  TOGGLES: groups begin with +/- to turn options on/off resp.
  1243.  s    Print no. reductions/cells after eval
  1244.  t    Print type after evaluation
  1245.  f    Terminate evaluation on first error
  1246.  g    Print no. cells recovered after gc
  1247.  l    Literate scripts as default
  1248.  e    Warn about errors in literate scripts
  1249.  .    Print dots to show progress
  1250.  w    Always show which files loaded
  1251.  k    Show kind errors in full
  1252.  u    Use "show" to display results
  1253.  i    Chase imports while loading files
  1254.  
  1255.  OTHER OPTIONS: (leading + or - makes no difference)
  1256.  hnum Set heap size (cannot be changed within Hugs)
  1257.  pstr Set prompt string to str
  1258.  rstr Set repeat last expression string to str
  1259.  Pstr Set search path for script files to str
  1260.  Estr Use editor setting given by str
  1261.  
  1262.  Current settings: +fekui -stgl.w -h100000 -p"? " -r$$
  1263.  Search path     : -P/Hugs/lib:/Hugs/libhugs
  1264.  Editor setting  : -E"vi +%d %s"
  1265.  ? 
  1266.  
  1267. The :set command can also be used to change command line options by
  1268. supplying the required settings as arguments.  For example:
  1269.  
  1270.  ? :set +st
  1271.  ? 1 + 3
  1272.  4 :: Int
  1273.  (4 reductions, 4 cells)
  1274.  ?
  1275.  
  1276.  
  1277. 4.1.3. Shell escape   :![<command>]
  1278.  
  1279. A :!<cmd> command can be used to execute the system command <cmd>
  1280. without leaving the Hugs interpreter.  For example,:!ls (or :!dir on
  1281. DOS machines) can be used to list the contents of the current
  1282. directory.  For convenience, the :! command can be abbreviated to a
  1283. single ! character.
  1284.  
  1285. The :! command, without any arguments, starts a new shell:
  1286.  
  1287.  o On a Unix machine, the SHELL environment variable is used to
  1288.    determine which shell to use; the default is /bin/sh.
  1289.  
  1290.  o On an DOS machine, the COMSPEC environment variable is used to
  1291.    determine which shell to use; this is usually COMMAND.COM.
  1292.  
  1293. Most shells provide an exit command to terminate the shell and return
  1294. to Hugs.
  1295.  
  1296.  
  1297. 4.1.4. Change directory   :cd <directory>
  1298.  
  1299. A :cd dir command changes the current working directory to the path
  1300. given by dir.  If no path is specified, then the command is ignored.
  1301.  
  1302.  
  1303. 4.1.5. Force a garbage collection   :gc
  1304.  
  1305. A :gc command can be used to force a garbage collection of the
  1306. interpreter heap, and to print the number of unused cells obtained as a
  1307. result:
  1308.  
  1309.  ? :gc
  1310.  Garbage collection recovered 95766 cells
  1311.  ? 
  1312.  
  1313.  
  1314. 4.1.6. List commands   :?
  1315.  
  1316. The :? command displays the following summary of all Hugs commands:
  1317.  
  1318.  ? :?
  1319.  LIST OF COMMANDS:  Any command may be abbreviated to :c where
  1320.  c is the first character in the full name.
  1321.  
  1322.  :load <filenames>   load scripts from specified files
  1323.  :load               clear all files except prelude
  1324.  :also <filenames>   read additional script files
  1325.  :reload             repeat last load command
  1326.  :project <filename> use project file
  1327.  :edit <filename>    edit file
  1328.  :edit               edit last file
  1329.  <expr>              evaluate expression
  1330.  :type <expr>        print type of expression
  1331.  :?                  display this list of commands
  1332.  :set <options>      set command line options
  1333.  :set                help on command line options
  1334.  :names [pat]        list names currently in scope
  1335.  :info <names>       describe named objects
  1336.  :find <name>        edit file containing definition of name
  1337.  :!command           shell escape
  1338.  :cd dir             change directory
  1339.  :gc                 force garbage collection
  1340.  :quit               exit Hugs interpreter
  1341.  ?
  1342.  
  1343.  
  1344. 4.1.7. Exit the interpreter   :quit
  1345.  
  1346. The :quit command terminates the current Hugs session.
  1347.  
  1348.  
  1349. 4.2. Loading and editing scripts and projects
  1350.  
  1351. 4.2.1. Load definitions from file   :load [<filename> ...]
  1352.  
  1353. The :load command removes any previously loaded script files, and then
  1354. attempts to load the definitions from each of the listed files, one
  1355. after the other.  If one of these files contains an error, then the
  1356. load process is suspended and a suitable error message will be
  1357. displayed. Once the problem has been corrected, the load process can be
  1358. restarted using a :reload command.  The load process will also be
  1359. restarted automatically after a :edit command.
  1360.  
  1361. If no file names are specified, the :load command just removes any
  1362. previously loaded definitions, leaving just the definitions provided by
  1363. the prelude.
  1364.  
  1365. The :load command uses the list of directories specified by the
  1366. HUGSPATH environment variable to search for script files.  We can
  1367. specify the list of directory and filename pairs, in the order that
  1368. they are searched, using a Haskell list comprehension:
  1369.  
  1370.  [ (dir,file++suf) | dir <- [""] ++ path, suf <- ["", ".hs", ".lhs"]]
  1371.  
  1372. The file mentioned here is the name of the script file that was entered
  1373. by the user, while path is the list of directories in the HUGSPATH.
  1374. The search starts with the directory "", which usually represents a
  1375. search relative to the current working directory.  So, the very first
  1376. filename that the system tries to load is exactly the same filename
  1377. entered by the user.  However, if the named file cannot be accessed,
  1378. then the system will try adding a .hs suffix, and then a .lhs suffix,
  1379. and then it will repeat the process for each directory in the path,
  1380. until either a suitable file has been located, or, otherwise, until all
  1381. of the possible choices have been tried. For example, this means that
  1382. you do not have to type the .hs suffix to load a file Demo.hs from the
  1383. current directory, provided that you do not already have a Demo file in
  1384. the same directory.  In the same way, it is not usually necesary to
  1385. include the full pathname for one of the standard Hugs libraries.  For
  1386. example, provided that you do not have an Array, Array.hs, or Array.lhs
  1387. file in the current working directory, you can load the standard Array
  1388. library by typing just :load Array.
  1389.  
  1390.  
  1391. 4.2.2. Load additional files   :also [<filename> ...]
  1392.  
  1393. The :also command can be used to load script files, without removing
  1394. any previously loaded files.  (However, if any of the previously loaded
  1395. script files have been modified since they were last read, then they
  1396. will be reloaded automatically before the additional files are read.)
  1397.  
  1398. If successful, a command of the form :load f1 .. fn is equivalent to
  1399. the sequence of commands:
  1400.  
  1401.  :load
  1402.  :also f1
  1403.    .
  1404.    .
  1405.  :also fn
  1406.  
  1407. In particular, :also uses the same mechanisms as :load to search for
  1408. script files.
  1409.  
  1410.  
  1411. 4.2.3. Repeat last load command   :reload
  1412.  
  1413. The :reload command can be used to repeat the last load command. If
  1414. none of the previously loaded files has been modified since the last
  1415. time that it was loaded,  then :reload will not have any effect.
  1416. However, if one of the script files has been modified, then it will be
  1417. reloaded.  Note that script files are loaded in a specific order, with
  1418. the possibility that later scripts may depend on the definitions in
  1419. earlier ones.  To allow for this, if one script has been reloaded, then
  1420. all subsequent scripts will also be reloaded.
  1421.  
  1422. This feature is particularly useful in a windowing environment.  If the
  1423. interpreter is running in one window, then :reload can be used to force
  1424. the interpreter to take account of changes made by editing script files
  1425. in other windows.
  1426.  
  1427.  
  1428. 4.2.4. Load project   :project [<project file>]
  1429.  
  1430. Project files were originally introduced to ease the task of working
  1431. with programs whose source code was spread over several script files,
  1432. all of which had to be loaded at the same time. The new facilities for
  1433. import chasing usually provide a much better way to deal with multiple
  1434. file projects, but the current version of Hugs 1.3 does still support
  1435. the use of project files.
  1436.  
  1437. The :project command takes a single argument; the name of a text file
  1438. containing a list of script file names, separated from one another by
  1439. whitespace (which may include spaces, newlines, or Haskell-style
  1440. comments).  For example, the following is a valid project file:
  1441.  
  1442.  {- A simple project file, Demo.prj -}
  1443.  Types   -- datatype definitions
  1444.  Basics  -- basic operations
  1445.  Main    -- the main program
  1446.  
  1447. If we load this into Hugs with a command :project Demo.prj, then the
  1448. interpreter will read the project file and then try to load each of the
  1449. named files.  In this particular case, the overall effect is,
  1450. essentially, the same as that of:
  1451.  
  1452.  :load Types Basics Main
  1453.  
  1454. Once a project file has been selected, the :project command (without
  1455. any arguments) can be used to force Hugs to reread both the project
  1456. file and the script files that it lists.  This might be useful if, for
  1457. example, the project file itself has been modified since it was first
  1458. read.
  1459.  
  1460. Project file names may also be specified on the command line when the
  1461. interpreter is invoked by preceding the project file name with a
  1462. single+ character.  Note that there must be at least one space on each
  1463. side of the +.  Standard command line options can also be used at the
  1464. same time, but additional filename arguments will be ignored.  Starting
  1465. Hugs with a command of the form hugs + Demo.proj is equivalent to
  1466. starting Hugs without the any arguments and then giving the command :p
  1467. Demo.prj.
  1468.  
  1469. The :project command uses the same mechanisms as :load to locate the
  1470. script files mentioned in a project file, but it will not use the
  1471. HUGSPATH setting to locate the project file itself; you must specify a
  1472. full pathname.
  1473.  
  1474. As has already been said, import chasing usually provides a much better
  1475. way to deal with multiple file programs than the old project file
  1476. system. The big advantage of import chasing is that dependencies
  1477. between modules are documented within individual script files, leaving
  1478. the system free to determine the order in which the files should be
  1479. loaded.  For example, if the Main script in the example above actually
  1480. needs the definitions in Types and Basics, then this will be documented
  1481. by import statements, and the whole program could be loaded with a
  1482. single :load Main command.
  1483.  
  1484.  
  1485. 4.2.5. Edit file   :edit [<file>]
  1486.  
  1487. The :edit command suspends the current Hugs session and starts an
  1488. editor program to modify or view a script file.  The Hugs session will
  1489. be resumed when the editor terminates; any script files that have been
  1490. changed will be reloaded automatically. The HUGSEDIT variable, or the
  1491. -E command line option, should be used to configure Hugs to your
  1492. preferred choice of editor.
  1493.  
  1494. If no filename is specified, then Hugs uses the name of the last script
  1495. file that it tried to load.  This allows the :edit command to integrate
  1496. smoothly with the facilities for loading script files.
  1497.  
  1498. For example, suppose that you want to load four files, f1.hs, f2.hs,
  1499. f3.hs and f4.hs into the interpreter, but the file f3.hs contains an
  1500. error of some kind. If you give the command:
  1501.  
  1502.  :load f1 f2 f3 f4
  1503.  
  1504. then Hugs will successfully load f1.hs and f2.hs, but will abort the
  1505. load command when it encounters the error in f3.hs, printing an error
  1506. message to describe the problem that occured.  Now, if you use the
  1507. command:
  1508.  
  1509.  :edit
  1510.  
  1511. then Hugs will start up the editor with the cursor positioned at the
  1512. relevant line of f3.hs (whenever this is possible) so that the error
  1513. can be corrected and the changes saved in f3.hs.  When you close down
  1514. the editor and return to Hugs, the interpreter will automatically
  1515. attempt to reload f3.hs and then, if successful, go on to load the next
  1516. file, f4.hs. So, after just two commands in Hugs, the error in f3.hs
  1517. has been corrected and all four of the files listed on the original
  1518. command line have been loaded into the interpreter, ready for use.
  1519.  
  1520.  
  1521. 4.2.6. Find definition   :find <name>
  1522.  
  1523. The :find name command starts up the editor at the definition of a type
  1524. constructor or function, specified by the argument name, in one of the
  1525. files currently loaded into Hugs.  Note that Hugs must be configured
  1526. with an appropriate value for the HUGSEDIT variable, to allow the
  1527. cursor to be positioned at the correct line in the source file. There
  1528. are four possibilities:
  1529.  
  1530.  o If there is a type constructor with the specified name, then the
  1531.    cursor will be positioned at the first line in the definition of
  1532.    that type constructor.
  1533.  
  1534.  o If the name is defined by a function or variable binding, then the
  1535.    cursor will be positioned at the first line in the definition of the
  1536.    function or variable (ignoring any type declaration, if present).
  1537.  
  1538.  o If the name is a constructor function or a selector function
  1539.    associated with a particular datatype, then the cursor will be
  1540.    positioned at the first line in the definition of the corresponding
  1541.    data definition.
  1542.  
  1543.  o If the name represents an internal Hugs function, then the cursor
  1544.    will be positioned at the beginning of the standard prelude file.
  1545.  
  1546. Note that names of infix operators should be given without any
  1547. enclosing them in parentheses.  Thus :f !! starts an editor on the
  1548. standard prelude at the first line in the definition of (!!). If a
  1549. given name could be interpreted both as a type constructor and as a
  1550. value constructor, then the former is assumed.
  1551.  
  1552.  
  1553. 4.3. Finding information about the system
  1554.  
  1555. 4.3.1. List names   :names [<pattern> ...]
  1556.  
  1557. The :names command can be used to list the names of variables and
  1558. functions whose definitions are currently loaded into the interpreter.
  1559. Without any arguments, :names produces a list of all names known to the
  1560. system; the names are listed in alphabetical order.
  1561.  
  1562. The :names command can also accept one or more pattern strings,
  1563. limiting the list of names that will be printed to those matching one
  1564. or more of the given pattern strings:
  1565.  
  1566.  ? :n fold*
  1567.  foldl foldl' foldl1 foldr foldr1
  1568.  (5 names listed)
  1569.  ?
  1570.  
  1571. Each pattern string consists of a string of characters and may use
  1572. standard wildcard syntax: * (matches anything), ? (matches any single
  1573. character), \c (matches exactly the character c) and ranges of
  1574. characters of the form [a-zA-Z], etc.  For example:
  1575.  
  1576.  ? :n *map* *[Ff]ile ?
  1577.  $ % * + - . / : < > appendFile map mapM mapM_ readFile writeFile ^
  1578.  (17 names listed)
  1579.  ?
  1580.  
  1581.  
  1582. 4.3.2. Print type of expression   :type <expr>
  1583.  
  1584. The :type command can be used to print the type of an expression
  1585. without evaluating it.  For example:
  1586.  
  1587.  ? :t "hello, world"
  1588.  "hello, world" :: String
  1589.  ? :t putStr "hello, world"
  1590.  putStr "hello, world" :: IO ()
  1591.  ? :t sum [1..10]
  1592.  sum (enumFromTo 1 10) :: (Num a, Enum a) => a
  1593.  ?
  1594.  
  1595. Note that Hugs displays the most general type that can be inferred for
  1596. each expression.  For example, compare the type inferred for sum
  1597. [1..10] above with the type printed by the evaluator (using :set +t):
  1598.  
  1599.  ? :set +t
  1600.  ? sum [1..10]
  1601.  55 :: Int
  1602.  ?
  1603.  
  1604. The difference is explained by the fact that the evaluator uses the
  1605. Haskell default mechanism to instantiate the type variable a in the
  1606. most general type to the type Int, avoiding an error with unresolved
  1607. overloading.
  1608.  
  1609.  
  1610. 4.3.3. Display information about names   :info [<name> ...]
  1611.  
  1612. The :info command is useful for obtaining information about the files,
  1613. classes, types and values that are currently loaded.
  1614.  
  1615. If there are no arguments, then :info prints a list of all the script
  1616. files that are currently loaded into the interpreter.
  1617.  
  1618.  ? :info
  1619.  Hugs session for:
  1620.  /Hugs/lib/Prelude.hs
  1621.  Demo.hs
  1622.  ? 
  1623.  
  1624. If there are arguments, then Hugs treats each one as a name, and
  1625. displays information about any corresponding type constructor, class,
  1626. or function. The following examples show the the kind of output that
  1627. you can expect:
  1628.  
  1629. Datatypes:  The system displays the name of the datatype, the names and
  1630. types of any constructors or selectors, and a summary of related
  1631. instance declarations:
  1632.  
  1633.  ? :info Either
  1634.  -- type constructor
  1635.  data Either a b
  1636.  
  1637.  -- constructors:
  1638.  Left :: a -> Either a b
  1639.  Right :: b -> Either a b
  1640.  
  1641.  -- instances:
  1642.  instance (Eq b, Eq a) => Eq (Either a b)
  1643.  instance (Ord b, Ord a) => Ord (Either a b)
  1644.  instance (Read b, Read a) => Read (Either a b)
  1645.  instance (Show b, Show a) => Show (Either a b)
  1646.  instance Eval (Either a b)
  1647.  
  1648.  ?
  1649.  
  1650. Newtypes are dealt with in exactly the same way. For a simple example
  1651. of a datatype with selectors, the output produced for a Time datatype:
  1652.  
  1653.  data Time = MkTime { hours, mins, secs :: Int }
  1654.  
  1655. is as follows:
  1656.  
  1657.  ? :info Time
  1658.  -- type constructor
  1659.  data Time
  1660.  
  1661.  -- constructors:
  1662.  MkTime :: Int -> Int -> Int -> Time
  1663.  
  1664.  -- selectors:
  1665.  hours :: Time -> Int
  1666.  mins :: Time -> Int
  1667.  secs :: Time -> Int
  1668.  
  1669.  -- instances:
  1670.  instance Eval Time
  1671.  
  1672.  ?
  1673.  
  1674. Type synonyms:  The system displays the name and expansion:
  1675.  
  1676.  ? :info String
  1677.  -- type constructor
  1678.  type String = [Char]
  1679.  
  1680.  ?
  1681.  
  1682. The expansion is not included in the output if the synonym is
  1683. restricted.
  1684.  
  1685. Type classes: The system lists the name, superclasses, members, and
  1686. instance declarations for the specified class:
  1687.  
  1688.  ? :info Num
  1689.  -- type class
  1690.  class (Eq a, Show a, Eval a) => Num a where
  1691.    (+) :: a -> a -> a
  1692.    (-) :: a -> a -> a
  1693.    (*) :: a -> a -> a
  1694.    negate :: a -> a
  1695.    abs :: a -> a
  1696.    signum :: a -> a
  1697.    fromInteger :: Integer -> a
  1698.    fromInt :: Int -> a
  1699.  
  1700.  -- instances:
  1701.  instance Num Int
  1702.  instance Num Integer
  1703.  instance Num Float
  1704.  instance Num Double
  1705.  instance Integral a => Num (Ratio a)
  1706.  
  1707.  ?
  1708.  
  1709. Other values: For example, named functions and individual constructor,
  1710. selector, and member functions are displayed with their name and type:
  1711.  
  1712.  ? :info . : hours min
  1713.  (.) :: (a -> b) -> (c -> a) -> c -> b
  1714.  
  1715.  (:) :: a -> [a] -> [a]  -- data constructor
  1716.  
  1717.  hours :: Time -> Int  -- selector function
  1718.  
  1719.  min :: Ord a => a -> a -> a  -- class member
  1720.  
  1721.  ?
  1722.  
  1723. As the last example shows, the :info command can take several arguments
  1724. and prints out information about each in turn.  A warning message is
  1725. displayed if there are no known references to an argument:
  1726.  
  1727.  ? :info (:)
  1728.  Unknown reference `(:)'
  1729.  ?
  1730.  
  1731. This illustrates that the arguments are treated as textual names for
  1732. operators, not syntactic expressions (for example, identifiers). The
  1733. type of the (:) operator can be obtained using the command :info : as
  1734. above.  There is no provision for including wildcard characters of any
  1735. form in the arguments of :info commands.
  1736.  
  1737. If a particular argument can be interpreted as, for example, both a
  1738. constructor function, and a type constructor, depending on context,
  1739. then the output for both possibilities will be displayed.
  1740.  
  1741.  
  1742. 5. Library overview
  1743.  
  1744. Haskell 1.3 places much greater emphasis on the use of libraries than
  1745. previous versions of the language.  Following that lead, the Hugs 1.3
  1746. distribution includes a number of different libraries.  Some of these
  1747. are based on the current proposal for standardized libraries in
  1748. Haskell, while others are Hugs-specific. All of these are described in
  1749. the following sections.  All that you need to do to use libraries is to
  1750. import them at the beginning of a Hugs script. For example:
  1751.  
  1752.  module MandlebrotSet where
  1753.  import Array
  1754.  import Complex
  1755.  ...
  1756.  
  1757. Of course, this assumes that HUGSPATH has been set to point to the
  1758. directories where the libraries are stored, and that import chasing is
  1759. enabled.
  1760.  
  1761.  
  1762. 5.1. Standard libraries
  1763.  
  1764. The following libraries conform closely to current proposals for the
  1765. Haskell 1.3 standard, and should be supported by all Haskell platforms.
  1766. However, at the time of writing, the exact details and specification of
  1767. the Haskell 1.3 libraries has not been finalized, so you can expect to
  1768. see some changes and possible incompatibilities in future releases.
  1769.  
  1770. Array: This library introduces a datatype and operations for using
  1771. Haskell arrays.  Unlike previous versions, support for arrays is not
  1772. included as part of the standard prelude.  The operations provided by
  1773. this library are as follows:
  1774.  
  1775.  module Array where
  1776.  
  1777.  infixl 9  !, //
  1778.  
  1779.  data Array a b -- Arrays indexed by values of type a,
  1780.                 -- with results of type b.
  1781.  
  1782.  array      :: Ix a => (a,a) -> [(a,b)] -> Array a b
  1783.  listArray  :: Ix a => (a,a) -> [b] -> Array a b
  1784.  (!)        :: Ix a => Array a b -> a -> b
  1785.  bounds     :: Ix a => Array a b -> (a,a)
  1786.  indices    :: Ix a => Array a b -> [a]
  1787.  elems      :: Ix a => Array a b -> [b]
  1788.  assocs     :: Ix a => Array a b -> [(a,b)]
  1789.  accumArray :: Ix a => (b -> c -> b) -> b -> (a,a) -> [(a,c)]
  1790.                 -> Array a b
  1791.  (//)       :: Ix a => Array a b -> [(a,b)] -> Array a b
  1792.  accum      :: Ix a => (b -> c -> b) -> Array a b -> [(a,c)]
  1793.                 -> Array a b
  1794.  amap       :: Ix a => (b -> c) -> Array a b -> Array a c
  1795.  ixmap      :: (Ix a, Ix b) => (a,a) -> (a -> b) -> Array b c
  1796.                 -> Array a c
  1797.  
  1798.  instance (Ix a, Eq b) => Eq (Array a b)
  1799.  instance (Ix a, Ord b) => Ord (Array a b)
  1800.  instance (Ix a, Show a, Show b) => Show (Array a b)
  1801.  
  1802. Char: According to the Haskell standard, this library provides support
  1803. for functions on characters, including isAlpha, isUpper, isDigit, and
  1804. toUpper.  However, in the current distribution of Hugs, these functions
  1805. are already defined in the standard prelude, so the Hugs Char library
  1806. is just an empty stub, provided for compatibility.
  1807.  
  1808. Complex: This library introduces a datatype and operations for complex
  1809. numbers.  Unlike previous versions, support for complex numbers is not
  1810. included as part of the standard prelude.  The operations provided by
  1811. this library are as follows:
  1812.  
  1813.  module Complex where
  1814.  
  1815.  infix  6  :+
  1816.  
  1817.  data RealFloat a => Complex a = !a :+ !a
  1818.       deriving (Eq, Read, Show)
  1819.  
  1820.  realPart, imagPart :: RealFloat a => Complex a -> a
  1821.  conjugate          :: RealFloat a => Complex a -> Complex a
  1822.  mkPolar            :: RealFloat a => a -> a -> Complex a
  1823.  cis                :: RealFloat a => a -> Complex a
  1824.  polar              :: RealFloat a => Complex a -> (a, a)
  1825.  magnitude, phase   :: RealFloat a => Complex a -> a
  1826.  
  1827.  instance RealFloat a => Num (Complex a)
  1828.  instance RealFloat a => Fractional (Complex a)
  1829.  instance RealFloat a => Floating (Complex a)
  1830.  
  1831. IO: This library provides a number of advanced features for the IO
  1832. monad, complementing the basic facilities in the standard prelude.
  1833. Note that the names and semantics of functions defined in this library
  1834. are particularly likely to change as the details of the I/O standard
  1835. are clarified.
  1836.  
  1837.  module IO where
  1838.  
  1839.  isUserError    :: IOError -> Maybe String
  1840.  isIllegalError, isAlreadyExists,
  1841.   isAlreadyInUse, isFullError,
  1842.   isPermissionError,
  1843.   isEOFError    :: IOError -> Bool
  1844.  ioeGetHandle   :: IOError -> Maybe Handle
  1845.  ioeGetFileName :: IOError -> Maybe FilePath
  1846.  
  1847.  data Handle    -- built-in datatype of IO handles
  1848.  
  1849.  data IOMode     = ReadMode | WriteMode | AppendMode
  1850.                    deriving (Eq, Ord, Enum, Show, Read)
  1851.  
  1852.  stdin          :: Handle
  1853.  stdout         :: Handle
  1854.  stderr         :: Handle
  1855.  hGetContents   :: Handle -> IO String
  1856.  openFile       :: FilePath -> IOMode -> IO Handle
  1857.  hClose, hFlush :: Handle -> IO ()
  1858.  hIsEOF         :: Handle -> IO Bool
  1859.  hPutChar       :: Handle -> Char -> IO ()
  1860.  hPutStr        :: Handle -> String -> IO ()
  1861.  hGetChar       :: Handle -> IO Char
  1862.  getCh          :: IO Char
  1863.  isEOF          :: IO Bool
  1864.  
  1865. Ix: According to the Haskell standard, this library provides support
  1866. for the Ix type class.  However, in the current distribution of Hugs,
  1867. this class is already defined in the standard prelude, so the Hugs Ix
  1868. library is just an empty stub, provided for compatibility.
  1869.  
  1870. List: This library provides a large collection of list processing
  1871. utilities.  Some of these functions were previously included as part of
  1872. the standard prelude, but there are also many new functions:
  1873.  
  1874.  module List where
  1875.  
  1876.  infix 5 \\
  1877.  
  1878.  delete             :: (Eq a) => a -> [a] -> [a]
  1879.  deleteBy           :: (a -> a -> Bool) -> a -> [a] -> [a]
  1880.  (\\)               :: (Eq a) => [a] -> [a] -> [a]
  1881.  deleteFirsts       :: (Eq a) => [a] -> [a] -> [a]
  1882.  deleteFirstsBy     :: (a -> a -> Bool) -> [a] -> [a] -> [a]
  1883.  
  1884.  elemBy, notElemBy  :: (a -> a -> Bool) -> a -> [a] -> Bool
  1885.  lookupBy           :: (a -> a -> Bool) -> a -> [(a, b)] -> Maybe b
  1886.  
  1887.  partition          :: (a -> Bool) -> [a] -> ([a],[a])
  1888.  
  1889.  nub                :: Eq a => [a] -> [a]
  1890.  nubBy              :: (a -> a -> Bool) -> [a] -> [a]
  1891.  group              :: (Eq a) => [a] -> [[a]]
  1892.  groupBy            :: (a -> a -> Bool) -> [a] -> [[a]]
  1893.  
  1894.  sums, products     :: Num a => [a] -> [a]
  1895.  
  1896.  transpose          :: [[a]] -> [[a]]
  1897.  
  1898.  genericLength      :: (Num i) => [b] -> i
  1899.  genericDrop        :: (Integral i) => i -> [a] -> [a]
  1900.  genericTake        :: (Integral i) => i -> [a] -> [a]
  1901.  genericSplitAt     :: (Integral i) => i -> [b] -> ([b],[b])
  1902.  genericReplicate   :: (Integral i) => i -> a -> [a]
  1903.  
  1904.  elemIndex          :: Eq a => [a] -> a -> Int
  1905.  elemIndexBy        :: (a -> a -> Bool) -> [a] -> a -> Int
  1906.  
  1907.  mapAccumL          :: (a -> b -> (a, c)) -> a -> [b] -> (a, [c])
  1908.  mapAccumR          :: (a -> b -> (a, c)) -> a -> [b] -> (a, [c])
  1909.  
  1910.  intersperse        :: a -> [a] -> [a]
  1911.  inits              :: [a] -> [[a]]
  1912.  tails              :: [a] -> [[a]]
  1913.  subsequences       :: [a] -> [[a]]
  1914.  permutations       :: [a] -> [[a]]
  1915.  union              :: (Eq a) => [a] -> [a] -> [a]
  1916.  intersect          :: (Eq a) => [a] -> [a] -> [a]
  1917.  
  1918.  -- Extending the zip family of functions:
  1919.  
  1920.  zip4               :: [a] -> [b] -> [c] -> [d]
  1921.                         -> [(a,b,c,d)]
  1922.  zip5               :: [a] -> [b] -> [c] -> [d] -> [e]
  1923.                         -> [(a,b,c,d,e)]
  1924.  zip6               :: [a] -> [b] -> [c] -> [d] -> [e] -> [f]
  1925.                         -> [(a,b,c,d,e,f)]
  1926.  zip7               :: [a] -> [b] -> [c] -> [d] -> [e] -> [f] -> [g]
  1927.                         -> [(a,b,c,d,e,f,g)]
  1928.  
  1929.  -- Extending the zipWith family of functions:
  1930.  
  1931.  zipWith4           :: (a->b->c->d->e)
  1932.                         -> [a]->[b]->[c]->[d]->[e]
  1933.  zipWith5           :: (a->b->c->d->e->f)
  1934.                         -> [a]->[b]->[c]->[d]->[e]->[f]
  1935.  zipWith6           :: (a->b->c->d->e->f->g)
  1936.                         -> [a]->[b]->[c]->[d]->[e]->[f]->[g]
  1937.  zipWith7           :: (a->b->c->d->e->f->g->h)
  1938.                         -> [a]->[b]->[c]->[d]->[e]->[f]->[g]->[h]
  1939.  
  1940.  -- Extending the unzip family of functions:
  1941.  
  1942.  unzip4             :: [(a,b,c,d)]
  1943.                         -> ([a],[b],[c],[d])
  1944.  unzip5             :: [(a,b,c,d,e)]
  1945.                         -> ([a],[b],[c],[d],[e])
  1946.  unzip6             :: [(a,b,c,d,e,f)]
  1947.                         -> ([a],[b],[c],[d],[e],[f])
  1948.  unzip7             :: [(a,b,c,d,e,f,g)]
  1949.                         -> ([a],[b],[c],[d],[e],[f],[g])
  1950.  
  1951. Maybe: This library provides utility functions for working with the
  1952. Maybe datatype, as defined in the standard prelude:
  1953.  
  1954.  module Maybe where
  1955.  
  1956.  exists            :: Maybe a -> Bool
  1957.  the               :: Maybe a -> a
  1958.  theExists         :: Maybe a -> (a, Bool)
  1959.  fromMaybe         :: a -> Maybe a -> a
  1960.  maybeToList       :: Maybe a -> [a]
  1961.  listToMaybe       :: [a] -> Maybe a
  1962.  findMaybe         :: (a -> Bool) -> [a] -> Maybe a
  1963.  catMaybes         :: [Maybe a] -> [a]
  1964.  mapMaybe          :: (a -> Maybe b) -> [a] -> [b]
  1965.  
  1966. Monad: This library provides general purpose operations for monadic
  1967. programming using instances of the Monad, MonadZero, and MonadPlus
  1968. classes:
  1969.  
  1970.  module Monad where
  1971.  
  1972.  join         :: Monad m => m (m a) -> m a
  1973.  apply        :: Monad m => (a -> m b) -> (m a -> m b)
  1974.  (@@)         :: Monad m => (a -> m b) -> (c -> m a) -> (c -> m b)
  1975.  mapAndUnzipL :: Monad m => (a -> m (b,c)) -> [a] -> m ([b], [c])
  1976.  mapAndUnzipR :: Monad m => (a -> m (b,c)) -> [a] -> m ([b], [c])
  1977.  accumulateL  :: Monad m => [m a] -> m [a]
  1978.  accumulateR  :: Monad m => [m a] -> m [a]
  1979.  sequenceL    :: Monad m => [m a] -> m ()
  1980.  sequenceR    :: Monad m => [m a] -> m ()
  1981.  zipWithL     :: Monad m => (a -> b -> m c) -> [a] -> [b] -> m [c]
  1982.  zipWithR     :: Monad m => (a -> b -> m c) -> [a] -> [b] -> m [c]
  1983.  mapL         :: Monad m => (a -> m b) -> ([a] -> m [b])
  1984.  mapR         :: Monad m => (a -> m b) -> ([a] -> m [b])
  1985.  foldL        :: Monad m => (a -> b -> m a) -> a -> [b] -> m a
  1986.  foldR        :: Monad m => (a -> b -> m b) -> b -> [a] -> m b
  1987.  concatM      :: MonadPlus m => [m a] -> m a
  1988.  unless       :: Monad m => Bool -> m () -> m ()
  1989.  when         :: Monad m => Bool -> m () -> m ()
  1990.  
  1991. Rational: According to the Haskell standard, this library provides
  1992. support for rational numbers, including the Ratio and Rational type
  1993. constructors. However, in the current distribution of Hugs, these
  1994. functions are already defined in the standard prelude, so the Hugs
  1995. Rational library is just an empty stub, provided for compatibility.
  1996.  
  1997. System: This library extends the Haskell IO monad with facilities for
  1998. writing stand-alone programs that need to deal with things like command
  1999. line arguments, environment variables, and exit codes.  In fact, the
  2000. implementation of these features in Hugs 1.3 is very weak---the
  2001. operations themselves are not well-suited to an interpreter-based
  2002. environment like Hugs---and the library is included mainly for
  2003. compatibility with Haskell.
  2004.  
  2005.  module System where
  2006.  
  2007.  data ExitCode = ExitSuccess | ExitFailure Int
  2008.                  deriving (Eq, Ord, Read, Show)
  2009.  
  2010.  getArgs      :: IO [String]
  2011.  getProgName  :: IO String
  2012.  getEnv       :: String -> IO String
  2013.  system       :: String -> IO ExitCode
  2014.  exitWith     :: ExitCode -> IO a
  2015.  
  2016.  
  2017. 5.2. Hugs-specific libraries
  2018.  
  2019. The distribution for Hugs 1.3 also includes a number of Hugs-specific
  2020. libraries, most of which are described below.  Please note that these
  2021. libraries are not part of the Haskell standard.
  2022.  
  2023. IORef: This library extends the Hugs I/O monad with a datatype
  2024. representing mutable reference cells, together with a small collection
  2025. of related operators in the style of Peyton Jones and Wadler [2]:
  2026.  
  2027.  module IORef where
  2028.  
  2029.  data Ref a  -- Mutable reference cells, holding values of type a.
  2030.  
  2031.  newRef      :: a -> IO (Ref a)
  2032.  getRef      :: Ref a -> IO a
  2033.  setRef      :: Ref a -> a -> IO ()
  2034.  eqRef       :: Ref a -> Ref a -> Bool
  2035.  
  2036.  instance Eq (Ref a)
  2037.  
  2038. ST: This library provides support for lazy state threads and for the ST
  2039. monad, as described by John Launchbury and Simon Peyton Jones [3]. The
  2040. operations provided by the library are as follows:
  2041.  
  2042.  module ST where
  2043.  
  2044.  data MutVar s a   -- mutable variables containing values
  2045.                    -- of type a in state thread s.
  2046.  
  2047.  returnST     :: a -> ST s a
  2048.  thenST       :: ST s a -> (a -> ST s b) -> ST s b
  2049.  newVar       :: a -> ST s (MutVar s a)
  2050.  readVar      :: MutVar s a -> ST s a
  2051.  writeVar     :: MutVar s a -> a -> ST s ()
  2052.  mutvarEq     :: MutVar s a -> MutVar s a -> Bool
  2053.  interleaveST :: ST s a -> ST s a
  2054.  
  2055.  instance Eq (MutVar s a)
  2056.  instance Monad (ST s)
  2057.  
  2058. The runST operation, used to specify encapsulation, is currently
  2059. implemented as a language construct, and runST is treated as a
  2060. keyword.
  2061.  
  2062. Note that it is possible to install Hugs 1.3 without support for lazy
  2063. state threads, and hence the primitives described here may not be
  2064. available in all implementations.  Also, in contrast with the
  2065. implementation of lazy state threads in previous releases of Hugs and
  2066. Gofer, there is no direct relationship between the ST and the IO
  2067. monads.
  2068.  
  2069. STArray: This library extends both the ST and Array libraries with
  2070. support for mutable arrays in the form described by John Launchbury and
  2071. Simon Peyton Jones [3].  The operations provided by the library are as
  2072. follows:
  2073.  
  2074.  module STArray where
  2075.  
  2076.  data MutArr s a b -- Mutable arrays, indexed by type a, with
  2077.                    -- results of type b in state thread s.
  2078.  
  2079.  newArr    :: Ix a => (a,a) -> b -> ST s (MutArr s a b)
  2080.  readArr   :: Ix a => MutArr s a b -> a -> ST s b
  2081.  writeArr  :: Ix a => MutArr s a b -> a -> b -> ST s ()
  2082.  freezeArr :: Ix a => MutArr s a b -> ST s (Array a b)
  2083.  
  2084. Trace: This library provides a single function, that can sometimes be
  2085. useful for debugging:
  2086.  
  2087.  module Trace where
  2088.  trace :: String -> a -> a
  2089.  
  2090. When called, trace prints the string in its first argument, and then
  2091. returns the second argument as its result.  The trace function is not
  2092. referentially transparent, and should only be used for debugging, or
  2093. for monitoring execution.  You should also be warned that, unless you
  2094. understand some of the details about the way that Hugs programs are
  2095. executed, results obtained using trace can be rather confusing.  For
  2096. example, the messages may not appear in the order that you expect.
  2097. Even ignoring the output that they produce, adding calls to trace can
  2098. change the semantics of your program.  Consider this a warning!
  2099.  
  2100. Number: This library defines a numeric datatype, Number, of fixed width
  2101. integers (whatever Int supplies).  Unlike the built-in Int type,
  2102. arithmetic overflows involving Number values will cause a run-time
  2103. error:
  2104.  
  2105.  module Number where
  2106.  
  2107.  default (Number,Int,Float)
  2108.  
  2109.  type Number = <restricted>
  2110.  
  2111.  instance Eq Number
  2112.  instance Ord Number
  2113.  instance Show Number
  2114.  instance Enum Number
  2115.  instance Num Number
  2116.  instance Bounded Number
  2117.  instance Real Number
  2118.  instance Ix Number
  2119.  instance Integral Number
  2120.  
  2121. ParseLib: This file provides a library of parser combinators, as
  2122. described in the paper on Monadic Parser Combinators by Graham Hutton
  2123. and Erik Meijer [4].
  2124.  
  2125.  
  2126. 6. Pointers to further information
  2127.  
  2128. Hugs
  2129.  
  2130. The full distribution for Hugs is available on the World Wide Web from:
  2131.  
  2132.   http://www.cs.nott.ac.uk/Department/Staff/mpj/hugs.html
  2133.  
  2134. or by anonymous ftp from:
  2135.  
  2136.   ftp://ftp.cs.nott.ac.uk/pub/haskell/hugs.
  2137.  
  2138. The distribution includes source code, demo programs, library files,
  2139. user documentation, and precompiled binaries for common platforms.
  2140.  
  2141. There is also a home page for Hugs at Yale:
  2142.  
  2143.   http://haskell.cs.yale.edu/hugs/,
  2144.  
  2145. and there are mailing lists for Hugs users (hugs-users@cs.yale.edu),
  2146. and for bug reports (hugs-bugs@cs.yale.edu). To subscribe, send an
  2147. email message to hugs-users-request@cs.yale.edu, or to
  2148. hugs-bugs-request@cs.yale.edu, respectively.
  2149.  
  2150. Haskell
  2151.  
  2152. An online version of the Haskell 1.3 report is available from:
  2153.  
  2154.   http://haskell.cs.yale.edu/haskell-report/haskell-report.html.
  2155.  
  2156. Archives for Haskell are maintained at various sites around the world:
  2157.  
  2158.   Chalmers, Sweden     ftp://ftp.cs.chalmers.se/pub/haskell
  2159.   Glasgow, Scotland    ftp://ftp.dcs.glasgow.ac.uk/pub/haskell
  2160.   Nottingham, England  ftp://ftp.cs.nott.ac.uk/pub/haskell
  2161.   Yale, USA            ftp://haskell.cs.yale.edu/pub/haskell
  2162.  
  2163. There is a common mailing list for technical discussion of Haskell;
  2164. details are available at the sites listed above.
  2165.  
  2166. Functional programming
  2167.  
  2168. The usenet newsgroup comp.lang.functional provides a forum for general
  2169. discussion about functional programming languages.  A list of
  2170. frequently asked questions (FAQs), and their answers, is available
  2171. from:
  2172.  
  2173.   http://www.cs.nott.ac.uk/Department/Staff/mpj/faq.html.
  2174.  
  2175. The FAQ list contains many pointers to other functional programming
  2176. resources around the world.
  2177.  
  2178. Further reading
  2179.  
  2180. As we said at the very beginning, this manual is not intended as a
  2181. tutorial on either functional programming in general, or Haskell in
  2182. particular. For these things, my first recommendations would be for the
  2183. Introduction to Functional Programming by Bird and Wadler [5], and the
  2184. Gentle Introduction to Haskell by Hudak and Fasel [6], respectively.
  2185. Note, however, that there are several other good textbooks dealing
  2186. either with Haskell or related languages.
  2187.  
  2188. For those with an interest in the implementation of Hugs, the report
  2189. about the implementation of Gofer [7], Hugs' predecessor, should be a
  2190. useful starting point.
  2191.  
  2192.  
  2193. References
  2194.  
  2195. [1] Peterson, J. and Hammond (editors), K. 1996 (May). Report on the
  2196. Programming Language Haskell 1.3, A Non-strict Purely Functional
  2197. Language. Technical report. Yale University. Department of Computer
  2198. Science.
  2199.  
  2200. [2] Peyton Jones, S. and Wadler, P. 1993 (January). Imperative
  2201. Functional Programming, from Proceedings 20th Symposium on Principles
  2202. of Programming Languages.
  2203.  
  2204. [3] Launchbury, J. and Peyton Jones, S.L. 1994 (June). Lazy functional
  2205. state threads, from Conference on Programming Language Design and
  2206. Implementation. Orlando, FL.
  2207.  
  2208. [4] Hutton, G. and Meijer, E. 1996. Monadic parser combinators.
  2209.  
  2210. [5] Bird, R. and Wadler, P. 1988. Introduction to functional
  2211. programming. Prentice Hall.
  2212.  
  2213. [6] Hudak, P. and Fasel, J. 1992 (May). A gentle introduction to
  2214. Haskell. ACM SIGPLAN Notices, 27(5).
  2215.  
  2216. [7] Jones, M.P. 1994 (May). The implementation of the Gofer functional
  2217. programming system.  Technical report. Yale University. New Haven,
  2218. Connecticut, USA.
  2219.  
  2220. -------------------------------------------------------------------------------
  2221.