The Hugs 98 User Manual
top | back | next

4  Starting Hugs

On Unix machines, the Hugs interpreter is usually started with a command line of the form:
  hugs [option | file] ...
On Windows 95/NT, Hugs may be started by selecting it from the start menu or by double clicking on a file with the .hs or .lhs extension. (This manual assumes that Hugs has already been successfully installed on your system.)

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:

The environment variables and command line options used by Hugs are described in the following sections.

4.1  Environment options

Before options on the command line are processed, initial option values are set from the environment. On Windows 95/NT, these settings are added to the registry during setup. On other systems, the initial settings are determined by the HUGSFLAGS environment variable. The syntax used in this case is the same as on the command line: options are single letters, preceeded by + or -, and sometimes followed by a value. Option settings are separated by spaces; option values containing spaces are encoded using Haskell string syntax. The environment should be set up before the interpreter is used so that the search path is correctly defined to include the prelude. The built-in defaults, however, may allow Hugs to be run without any help from the environment on some systems.

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:

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

4.2  Options

The behaviour of the interpreter, particularly the read-eval-print loop, can be customized using options. For example, you might use:
 hugs -i +g +h30K
to start the interpreter with the i option (import chasing) disabled, the g option (garbage collector messages) enabled, and with a heap of thirty thousand cells. As this example suggests, many of the options are toggles, meaning that they can either be switched on (by preceding the option with a + character) or off (by using a - character). Options may also be grouped together. For example, hugs +stf -le is equivalent to hugs +s +t +f -l -e.

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:

One reasonable use of the statistics produced by +s would be to observe general trends in the behaviour of a single algorithm with variations in its 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:

Hugs will report on errors of this kind whenever the -e option is enabled (the default setting).

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:

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.


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