4  Starting Hugs

Hugs uses options to set system parameters. These options are distinguished by a leading + or - and are used to customize the behaviour of the interpreter. When Hugs starts, the interpreter performs the following tasks:

• Options in the environment are processed. The variable HUGSFLAGS holds these options. On Windows 95/NT, the registry is also queried for Hugs option settings.
• Command line options are processed.
• Internal data structures are initialized. In particular, the heap is initialized, and its size is fixed at this point; if you want to run the interpreter with a heap size other than the default, then this must be specified using options on the command line, in the environment or in the registry.
• The prelude file is loaded. The interpreter will look for the prelude file on the path specified by the -P option. If the prelude, located in the file Prelude.hs, cannot be found in one of the path directories or in the current directory, then Hugs will terminate; Hugs will not run without the prelude file.
• Program files specified on the command line are loaded. The effect of a command hugs f1 ... fn is the same as starting up Hugs with the hugs command and then typing :load f1 ... fn. In particular, the interpreter will not terminate if a problem occurs while it is trying to load one of the specified files, but it will abort the attempted load command.

4.1  Environment options

It is usually more convenient to save preferred option settings in the environment rather than specifying them on the command line; they will then be used automatically each time the interpreter is started. The method for setting these options depends on the machine and operating system that you are using, and on the way that the Hugs system was installed. The following examples show some typical settings for Unix machines and PCs:

• The method for setting HUGSFLAGS on a Unix machine depends on the choice of shell. For example, a C-shell user might add something like the following to their .cshrc file:
   set HUGSFLAGS -P/usr/Hugs/lib:/usr/Hugs/libhugs -E"vi +%d %s"
  The P option is used to set the search path and the E is used to set the editor. The string quotes are necessary for the value of the E option becauses it contains spaces. The setting for the path assumes that the system has been installed in /usr/local/Hugs and will need to be modified accordingly if a different directory was chosen. The editor specified here is vi, which allows the user to specify a startup line number by preceding it with a + character. The settings are easily changed to accommodate other editors.

  If you are installing Hugs for the benefit of several different users, then you should probably use a script file that sets appropriate values for the environment variables, and then invokes the interpreter:
   #!/bin/sh
   HUGSFLAGS=/usr/Hugs/lib:/usr/Hugs/libhugs -E"vi +%d %s" +s
   export HUGSFLAGS
   exec /usr/local/bin/hugs $*
  One advantage of this approach is that individual users do not have to worry about setting the environment variables themselves. In addition to the E and P options, other options---such as +s in this example---can be set. It is easy for more advanced users to copy and customize a script like this to suit their own needs.

• Users of DOS or Windows 3.1 might add the following line to autoexec.bat:
   set HUGSFLAGS=-P\hugs\lib;\hugs\libhugs -E"vi +%%d %%s"
  The setting for the path assumes that the system has been installed in a top-level hugs directory, and will need to be modified accordingly if a different directory was chosen. In a similar way, the setting for the editor will only work if you have installed the editor program, in this case vi, that it refers to.
• On Windows 95/NT, the setup program initializes the environment, and this can be changed subsequently (on these systems only) by using either the :set command or a registry editor. The InstallShield script that performs the installation initializes the path using the installation directory; other directories can be added using -P. Installed options are stored under the HKEY_LOCAL_MACHINE key; changes to these options using :set are placed under HKEY_CURRENT_USER so that different users do not alter each other's options.

For completeness, we should also mention the other environment variables that are used by Hugs:

• The SHELL variable on a Unix machine, or the COMSPEC variable on a DOS machine, determines which shell is used by the :! command.
• The EDITOR variable is used to try and locate an editor if no editor option has been set. Note, however, that this variable does not normally provide the extra information that is needed to be able to start the editor at a specific line in the input file.

4.2  Options

Option settings can be specified in a number of different ways---the HUGSFLAGS environment variable, the Windows registry, the command line, and the :set command---but the same syntax is used in each case. To avoid any confusion with filenames entered on the command line, option settings must always begin with a leading + or - character. However, in some cases---the h, p, r, P, and E options---the choice is not significant. With the exception of the heap size option, h, all options can be changed while the interpreter is running using the :set command. The same command can be used (without any arguments) to display a summary of the available options and to inspect their current settings.

The complete set of Hugs options is described in the sections below. The only omission here is the -98 and +98 options that are used to set the Haskell 98 compatability mode. These are discussed in Section 7.

Set search path -Ppath

The -Ppath option changes the Hugs search path to the specified path. The search path is usually initialized in the environment and should always include the directory containing the Hugs prelude and the standard libraries. When an unknown module is imported, Hugs searches for a file with the same name as the module along this path. The current directory is always searched before the path is used. Directory names should be separated by colons or, on Windows/DOS machines, by semicolons. Empty components in the path refer to the prior value of the path. For example, setting the path to dir: (dir; on Windows/DOS) would add dir to the front of the current path. Within the path, {Hugs} refers to the directory containing the Hugs libraries so one might use a path such as {Hugs}/lib:{Hugs}/lib/hugs.

Set editor -Ecmd

A -Ecmd option can be used to change the editor string to the specified cmd while the interpreter is running. The editor string is usually initialized from the environment when the interpreter starts running.

Any occurrences of %d and %s in the editor option are replaced by the start line number and the name of the file to be edited, respectively, when the editor is invoked. If specified, the line number parameter is used to let the interpreter start the editor at the line where an error was detected, or, in the case of the :find command, where a specified variable was defined.

Other editors can be selected. For example, you can use the following value to configure Hugs to use emacs:
 -E"emacs +%d %s"
More commonly, emacsclient or gnuclient is used to avoid starting a new emacs with every edit.

On Windows/DOS, you can use -Eedit for the standard DOS editor, or -Enotepad for the Windows notepad editor. However, neither edit or notepad allow you to specify a start line number, so you may prefer to install a different editor.

Print statistics +s,-s

Normally, Hugs just shows the result of evaluating each expression:
 Prelude> map (\x -> x*x) [1..10]
 [1, 4, 9, 16, 25, 36, 49, 64, 81, 100]
 Prelude> [1..]
 [1, 2, 3, 4, {Interrupted!}
 Prelude>
With the +s option, the interpreter will also display statistics about the total number of reductions and cells; the former gives a measure of the work done, while the latter gives an indication of the amount of memory used. For example:
 Prelude> :set +s
 Prelude> map (\x -> x*x) [1..10]
 [1, 4, 9, 16, 25, 36, 49, 64, 81, 100]
 (248 reductions, 429 cells)
 Prelude> [1..]
 [1, 2, 3, 4, {Interrupted!}
 (18 reductions, 54 cells)
 Prelude>
Note that the statistics produced by +s are an extremely crude measure of the behaviour of a program, and can easily be misinterpreted. For example:

• The fact that one expression requires more reductions than another does not necessarily mean that the first is slower; some reductions require much more work than others, and it may be that the average cost of reductions in the first expression is much lower than the average for the second.
• The cell count does not give any information about residency, which is the number of cells that are being used at any given time. For example, it does not distinguish between computations that run in constant space and computations with residency proportional to the size of the input.

Print type after evaluation +t,-t

With the +t option, the interpreter will display both the result and type of each expression entered at the Hugs prompt:
 Prelude> :set +t
 Prelude> map (\x -> x*x) [1..10]
 [1, 4, 9, 16, 25, 36, 49, 64, 81, 100] :: [Int]
 Prelude> not True
 False :: Bool
 Prelude> \x -> x
 <<function>> :: a -> a
 Prelude>
Note that the interpreter will not display the type of an expression if its evaluation is interrupted or fails with a run-time error. In addition, the interpreter will not print the type, IO (), of a program in the IO monad; the interpreter treats these as a special case, giving the programmer more control over the output that is produced.

Terminate on error +f,-f

In normal use, the evaluation of an expression is abandoned completely if a run-time error occurs, such as a failed pattern match or an attempt to divide by zero. For example:
 Prelude> [1 `div` 0]
 [
 Program error: {primDivInt 1 0}

 Prelude> [1 `div` 0, 2]
 [
 Program error: {primDivInt 1 0}

 Prelude>
This is often useful during program development because it means that errors are detected as soon as they occur. However, technically speaking, the two expressions above have different meanings; the first is a singleton list, while the second has two elements. Unfortunately, the output produced by Hugs does not allow us to distinguish between the values.

The -f option can be used to make the Hugs printing option a little more accurate; this should normally be combined with -u because the built-in printer is better than the user-defined show functions at recovering from evaluation errors. With these settings, if the interpreter encounters an irreducible subexpression, then it prints the expression between a matching pair of braces and attempts to continue with the evaluation of other parts of the original expression. For the examples above, we get:
 Prelude> :set -u -f
 Prelude> [1 `div` 0]       -- value is [bottom]
 [{primDivInt 1 0}]
 Prelude> [1 `div` 0, 2]
 [{primDivInt 1 0}, 2]      -- value is [bottom, 2]
 Prelude>
Reading an expression in braces as bottom, the output produced here shows the correct values, according to the semantics of Haskell. Of course, it is not possible to detect all occurrences of bottom like this, such as those produced by a nonterminating computation:
 Prelude> last [1..]
 ^C{Interrupted!}      -- nothing printed until interrupted

 Prelude>
Note that the basic method of evaluation is the same with both the +f and -f options; all that changes is the way that the printing mechanism deals with certain kinds of runtime error.

Garbage collector notification +g,-g

It is sometimes useful to monitor uses of the garbage collector, and to determine how many cells are recovered with each collection. If the +g option is set, then the interpreter will print a message of the form {{Gc:num}} each time that the garbage collector is invoked. The number after the colon indicates the total number of cells that are recovered.

As a simple application, we can use garbage collector messages to observe that an attempt to sum an infinite list, although non-terminating, will at least run in constant space:
 Prelude> :set +g
 Prelude> sum [1..]
 {{Gc:95763}}{{Gc:95760}}{{Gc:95760}}{{Gc:95760}}{Interrupted!}

 Prelude>
Garbage collector messages may be printed at almost any stage in a computation (or indeed while loading, type checking or compiling a file of definitions). For this reason, it is often best to turn garbage collector messages off (using :set -g, for example) if they are not required.

Literate modules +l,-l,+e,-e

Like most programming languages, Hugs usually treats source file input as a sequence of lines in which program text is the norm, and comments play a secondary role. In Hugs, as in Haskell, comments are introduced by the character sequences -- and {- ... -}.

An alternative approach, using an idea described by Knuth as "literate programming," gives more emphasis to comments and documentation, with additional characters needed to distinguish program text from comments. Hugs supports a form of literate programming based on an idea due to Richard Bird and originally implemented as part of the functional programming language Orwell.

In a Hugs literate module, program lines are marked by a > character in the first column; any other line is treated as a program comment. This makes it particularly easy to write a document which is both an executable Hugs module and, at the same time, without need for any preprocessing, suitable for use with document preparation software such as LaTeX.

Hugs will treat any input file with a name ending in .hs as a normal module and any input file with a name ending in .lhs as a literate module. If the -l option is selected, then any other file loaded into Hugs will be treated as a normal module. Conversely, if +l is selected, then these files will be treated as literate modules. The effect of using literate modules can be thought of as applying a preprocessor to each input file that is loaded into Hugs. This has a particularly simple definition in Hugs:
 illiterate   :: String -> String
 illiterate cs = unlines [ " " ++ xs | ('>':xs) <- lines cs ]
The system of literate modules that was used in Orwell is a little more complicated than this and requires the programmer to adopt two further conventions in an attempt to catch simple errors in literate modules:

• Every input file must contain at least one line whose first character is >. This prevents modules with no definitions (because the programmer has forgotten to use the > character to mark definitions) from being accepted.
• Lines containing definitions must be separated from comment lines by one or more blank lines (i.e., lines containing only space and tab characters). This is useful for catching programs where the leading > character has been omitted from one or more lines in the definition of a function. For example:  
  > map f []     = []
    map f (x:xs) = f x : map f xs
  would be treated as an error.

The Haskell Report defines a second style of literate programming in which code is surrounded by \begin{code} and \end{code}. See Appendix C of the Haskell Report for more information about literate programming in Haskell.

Display dots while loading +.,-.

As Hugs loads each file into the interpreter, it prints a short sequence of messages to indicate progress through the various stages of parsing the module, dependency analysis, type checking, and compilation. With the default setting, -., the interpreter prints the name of each stage, backspacing over it to erase it from the screen when the stage is complete. If you are fortunate enough to be using a fast machine, you may not always see the individual words as they flash past. After loading a file, your screen will typically look something like this:
 Prelude> :l Array
 Reading file "/Hugs/lib/Array.hs":

 Hugs session for:
 /Hugs/lib/Prelude.hs
 /Hugs/lib/Array.hs
 Prelude>
On some systems, the use of backspace characters to erase a line may not work properly---for example, if you try to run Hugs from within emacs. In this case, you may prefer to use the +. setting which prints a separate line for each stage, with a row of dots to indicate progress:
 Prelude> :load Array
 Reading file "/Hugs/lib/Array.hs":
 Parsing....................................................
 Dependency analysis........................................
 Type checking..............................................
 Compiling..................................................

 Hugs session for:
 /Hugs/lib/Prelude.hs
 /Hugs/lib/Array.hs
 Prelude>
This setting can also be useful on very slow machines where the growing line of dots provides confirmation that the interpreter is making progress through the various stages involved in loading a file. You should note, however, that the mechanisms used to display the rows of dots can add a substantial overhead to the time that it takes to load files; in one experiment, a particular program took nearly five times longer to load when the +. option was used. In this case, users might prefer to use the -q option described below.

Display nothing while loading +q,-q

The +q (quiet) option supresses the messages used to indicate progress while Hugs is loading files. If this option is turned off using the -q, then the format of output messages is determined by the current +. or -. setting.

List files loaded +w,-w

By default, Hugs prints a complete list of all the files that have been loaded into the system after every successful load or reload command. The -w option can be used to turn this feature off. Note that the :info command, without any arguments, can also be used to list the names of currently loaded files.

Detailed kind errors +k,-k

Haskell uses a system of kinds to ensure that type expressions are well-formed: for example, to make sure that each type constructor is applied to the appropriate number of arguments. For example, the following program:
 module Main where
 data Tree a  = Leaf a | Tree a :^: Tree a
 type Example = Tree Int Bool
will cause an error:
 ERROR "Main.hs" (line 3): Illegal type "Tree Int Bool" in
                           constructor application
The problem here is that Tree is a unary constructor of kind * -> *, but the definition of Example uses it as a binary constructor with at least two arguments, and hence expecting a kind of the form (* -> * -> k), for some kind k.

By default, Hugs reports problems like this with a simple message like the one shown above. However, if the +k option is selected, then the interpreter will print a more detailed version of the error message, including details about the kinds of the type expressions that are involved:
 ERROR "Main.hs" (line 3): Kind error in constructor application
 *** expression     : Tree Int Bool
 *** constructor    : Tree
 *** kind           : * -> *
 *** does not match : * -> a -> b

In addition, if the +k option is used, then Hugs will also include information about kinds in the information produced by the :info command:
 Prelude> :info Tree
 -- type constructor with kind * -> *
 data Tree a

 -- constructors:
 Leaf :: a -> Tree a
 (:^:) :: Tree a -> Tree a -> Tree a

 -- instances:
 instance Eval (Tree a)

 Prelude>

Use "show" to display results +u,-u

In normal use, Hugs displays the value of each expression entered into the interpreter by applying the standard prelude function:
 show :: Show a => a -> String
to it and displaying the resulting string of characters. This approach works well for any value whose type is an instance of the standard Show class; for example, the prelude defines instances of Show for all of the built-in datatypes. It is also easy for users to extend the class with new datatypes, either by providing a handwritten instance declaration, or by requesting an automatically derived instance as part of the datatype definition, as in:
 data Rainbow = Red | Orange | Yellow | Green | Blue | Indigo | Violet
                deriving Show
The advantage of using show is that it allows programmers to display the results of evaluations in whatever form is most convenient for users---which is not always the same as the way in which the values are represented.

This is probably all that most users will ever need. However, there are some circumstances where it is not convenient, for example, for certain kinds of debugging or for work with datatypes that are not instances of Show. In these situations, the -u option can be used to prevent the use of show. In its place, Hugs will use a built-in printing mechanism that works for all datatypes, and uses the representation of a value to determine what gets printed. At any point, the default printing mechanism can be restored by setting +u.

Import chasing +i,-i

Import chasing is a simple, but flexible mechanism for dealing with programs that involve multiple modules. It works in a natural way, using the information in import statements at the beginning of modules, and is particularly useful for large programs, or for programs that use standard Hugs libraries.

For example, consider a module Demo.hs that requires the facilities provided by the STArray library. This dependency might be reflected by including the following import statement at the beginning of Demo.hs:
 import STArray
Now, if we try to load this module into Hugs, then the system will automatically search for the STArray library and load it into Hugs, before Demo.hs is loaded. In fact, the STArray library module also begins with some import statements:
 import ST
 import Array
So, Hugs will actually load the ST and Array libraries first, then the STArray library, and only then will it try to read the rest of Demo.hs:
 Prelude> :load Demo
 Reading file "Demo.hs":
 Reading file "/hugs/libhugs/STArray.hs":
 Reading file "/hugs/libhugs/ST.hs":
 Reading file "/hugs/lib/Array.hs":
 Reading file "/hugs/libhugs/STArray.hs":
 Reading file "Demo.hs":
 Demo>
Initially, the interpreter reads only the first part of any module loaded into the system, upto and including any import statements. Only one module is allowed in each file; files with no module declaration are assumed to declare the Main module. If there are no imports, or if the modules specified as imports have already been loaded, then the system carries on and loads the module as normal. On the other hand, if the module includes import statements for modules that have not already been loaded, then the interpreter postpones the task of reading the current module until all of the specified imports have been successfully loaded. This explains why Demo.hs and STArray.hs are read twice in the example above; first to determine which imports are required, and then to read in the rest of the file once the necessary imports have been loaded.

The list of directories and filenames that Hugs tries in an attempt to locate the source for a module Mod named in an import statement can be specified by:
 [ (dir,"Mod"++suf) | dir <- [d] ++ path ++ [""],
                      suf <- ["", ".hs", ".lhs"]]
The search starts in the directory d where the file containing the import statement was found, then tries each of the directories in the current path (as defined by the -P option), represented here by path, and ends with "", which gives a search relative to the current directory. The fact that the search starts in d is particularly important because it means that you can load a multi-file program into Hugs without having to change to the directory where its source code is located. For example, suppose that /tmp contains the files, A.hs, B.hs, and C.hs, that B imports A, and that C imports B. Now, regardless of the current working directory, you can load the whole program with the command :load /tmp/C; the import in C will be taken as a reference to /tmp/B.hs, while the import in that file will be taken as a reference to /tmp/A.hs.

Import chasing is often very useful, but you should also be aware of its limitations:

• Mutually recursive modules are not supported; if A imports B, then B must not import A, either directly or indirectly through another one of its imports.
• Import chasing assumes a direct mapping from module names to the names of the files that they are stored in. If A imports B, then the code for B must be in a file called either B, B.hs, or B.lhs, and must be located in one of the directories specified above.

  On rare occasions, it is useful to specify a particular pathname as the target for an import statement; Hugs allows string literals to be used as module identifiers for this purpose:
   import "../TypeChecker/Types.hs"
  Note, however, that this is a nonstandard feature of Hugs, and that it is not valid Haskell syntax. You should also be aware that Hugs uses the names of files in deciding whether a particular import has already been loaded, so you should avoid situations where a single file is referred to by more than one name. For example, you should not assume that Hugs will be able to determine whether Demo.hs and ./Demo.hs are references to the same file.

Import chasing is usually enabled by default (setting +i), but it can also be disabled using the -i option.

Set heap size -hsize

A -hsize option can be used to request a particular heap size for the interpreter---the total number of cells that are available at any one time---when Hugs is first loaded. The request will only be honoured if it falls within a certain range, which depends on the machine, and the version of Hugs that is used. The size parameter may include a K or k suffix, which acts as a multiplier by 1,000. For example, either of the following commands:
 hugs -h25000
 hugs -h25K
will usually start the Hugs interpreter with a heap of 25,000 cells. Cells are generally 8 bytes wide (except on the 16 bit Hugs running on DOS) and Hugs allocates a single heap. Note that the heap is used to hold an intermediate (parsed) form of each module while it is being read, type checked and compiled. It follows that, the larger the module, the larger the heap required to enable that module to be loaded into Hugs. In practice, most large programs are written (and loaded) as a number of separate modules which means that this does not usually cause problems.

Unlike all of the other options described here, the heap size setting cannot be changed from within the interpreter using a :set command. However, on Window 95/NT, changing the heap size with :set will affect the next running of Hugs since it saves all options in the registry.

Set prompt -pstring

A -pstr option can be used to change the prompt to the specified string, str:
 Prelude> :set -p"Hugs> "
 Hugs> :set -p"? "
 ?
Note that you will need to use quotes around the prompt string if you want to include spaces or special characters. Any %s in the prompt will be replaced by the current module name. The default prompt is "%s> ".

Set repeat string -rstring

Hugs allows the user to recall the last expression entered into the interpreter by typing the characters $$ as part of the next expression:
 Prelude> map (1+) [1..10]
 [2, 3, 4, 5, 6, 7, 8, 9, 10, 11]
 Prelude> filter even $$
 [2, 4, 6, 8, 10]
 Prelude>
A -rstr option can be used to change the repeat string---the symbol used to recall the last expression---to str. For example, users of Standard ML might be more comfortable using:
 Prelude> :set -rit
 Prelude> 6 * 7
 42
 Prelude> it + it
 84
 Prelude> 
Another reason to change the repeat string is to avoid clashes with uses of the same symbol in a particular program; for example, if $$ is defined as an operator in a program.

Note that the repeat string must be a valid Haskell identifier or symbol, although it will always be parsed as an identifier. If the repeat string is set to a value that is neither an identifier or symbol (for example, -r0), then the repeat last expression facility will be disabled.

Set preprocessor string -Fcmd

Although it is not needed very often, there are sometimes applications where it useful to arrange for input files to be preprocessed before they are passed to the Hugs interpreter. This might be used, for example, to make use of filters to support conditional compilation, language extensions, literate programming systems, or format conversion. The -F option can be used to set a particular command string cmd as the name for a preprocessor. If set, then for any source file, say file.hs, that the user tries to load into Hugs, the interpreter will use the output from the command cmd file.hs instead of the contents of the file file.hs itself.

Note that the -F option is system dependent, and is not supported on all platforms.

Set constraint cutoff limit -cnum

The -c parameter controls the complexity of constraint satisfaction searches in the Hugs type checker. This is a technical mechanism to ensure that type checking terminates, and can safely be ignored by most users. However, in programs that make significant use of complex type class hierarchies, it may sometimes be necessary to increase the setting for the -c option to enable the Hugs type checker to explore a larger search space.

The usual default for this setting is 40, which corresponds to the command line option -c40, and we have not yet seen any examples of valid Hugs programs that are rejected with this setting. (It is possible to construct artificial programs that do require higher values, but such examples are pathological and they do not seem to appear in practice.) There is no practical benefit in choosing a lower value for this parameter. Note that, if the value used is too low, then Hugs will not be able to load some standard files and libraries, including the prelude.