The Hugs 98 User Manual
top | back | next

5  Hugs commands

Hugs provides a number of commands that can be used to evaluate expressions, to load files, and to inspect or modify the behaviour of the system while the interpreter is running. Almost all of the commands in Hugs begin with the : character, followed by a short command word. For convenience, all but the first letter of a command may be omitted. For example, :l, :s and :q can be used as abbreviations for the :load, :set and :quit commands, respectively.

Most Hugs commands take arguments, separated from the command itself, and from one another, by spaces. The Haskell syntax for string constants can be used to enter parts of arguments that contain spaces, newlines, or other special characters. For example, the command:
 :load My File
will be treated as a command to load two files, My and File. Any of the following commands can be used to load a single file, My File, whose name includes an embedded space:
 :load "My File"
 :load "My\SPFile"
 :load "My\  \ File"
 :load My" "File
You may wish to study the lexical syntax of Haskell strings to understand some of these examples. In practice, filenames do not usually include spaces or special characters and can be entered without surrounding quotes, as in:
 :load fact.hs
The full set of Hugs commands is described in the following sections.

5.1  Basic commands

Evaluate expression expr
To evaluate an expression, the user simply enters it at the Hugs prompt. This is treated as a special case, without the leading colon that is required for other commands. The expression must fit on a single line; there is no way to continue an expression onto the next line of input to the interpreter. The actual behaviour of the evaluator depends on the type of expr:

The interpreter will not evaluate an expression that contains a syntax error, a type error, or a reference to an undefined variable:
 Prelude> sum [1..)
 ERROR: Syntax error in expression (unexpected `)')
 Prelude> sum 'a'
 ERROR: Type error in application
 *** expression     : sum 'a'
 *** term           : 'a'
 *** type           : Char
 *** does not match : [a]
 Prelude> sum [1..n]
 ERROR: Undefined variable "n"
Another common problem occurs if there is no show function for the expression entered---that is, if its type is not an instance of the Show class. For example, suppose that a module defines a type T without a Show instance:
 module Test where
 data T = A | B
With just these definitions, any attempt to evaluate an expression of type T will cause an error:
 Test> A
 ERROR: Cannot find "show" function for:
 *** expression : A
 *** of type    : T
To avoid problems like this, you will need to add an instance of the Show class to your program. One of the simplest ways to do that is to request a derived instance of Show as part of the datatype definition, as in:
 module Test where
 data T = A | B  deriving Show
Once this has been loaded, Hugs will evaluate and display values of type T:
 Test> A
 Test> take 5 (cycle [A,B])
 [A, B, A, B, A]

You should also note that the behaviour of the evaluator can be changed while the interpreter is running by using the :set command to modify option settings.

View or change settings :set [options]
Without any arguments, the :set command displays a list of the options and their current settings. The following output shows the settings on a typical machine:
Prelude> :set
 TOGGLES: groups begin with +/- to turn options on/off resp.
 s    Print no. reductions/cells after eval
 t    Print type after evaluation
 f    Terminate evaluation on first error
 g    Print no. cells recovered after gc
 l    Literate modules as default
 e    Warn about errors in literate modules
 .    Print dots to show progress
 q    Print nothing to show progress
 w    Always show which modules are loaded
 k    Show kind errors in full
 u    Use "show" to display results
 i    Chase imports while loading modules

 OTHER OPTIONS: (leading + or - makes no difference)
 hnum Set heap size (cannot be changed within Hugs)
 pstr Set prompt string to str
 rstr Set repeat last expression string to str
 Pstr Set search path for modules to str
 Estr Use editor setting given by str
 cnum Set constraint cutoff limit
 Fstr Set preprocessor filter to str
 Current settings: +fewkui -stgl.q -h250000 -p"%s> " -r$$ -c40
 Search path     : -P{Hugs}\lib;{Hugs}\lib\hugs;{Hugs}\lib\exts
 Editor setting  : -E"vi +%d %s"
 Preprocessor    : -F
 Compatibility   : Haskell 98 (+98)
The :set command can also be used to change options by supplying the required settings as arguments. For example:
 Prelude> :set +st
 Prelude> 1 + 3
 4 :: Int
 (4 reductions, 4 cells)

On Windows 95/NT, all option settings are written out to the registry when a :set command is executed, and will be used by subsequent executions of Hugs.

Shell escape :![command]
A :!cmd command can be used to execute the system command cmd without leaving the Hugs interpreter. For example, :!ls (or :!dir on DOS machines) can be used to list the contents of the current directory. For convenience, the :! command can be abbreviated to a single ! character.

The :! command, without any arguments, starts a new shell:

Most shells provide an exit command to terminate the shell and return to Hugs.

List commands :?
The :? command displays the following summary of all Hugs commands:
 Prelude> :?
 LIST OF COMMANDS:  Any command may be abbreviated to :c where
 c is the first character in the full name.

 :load <filenames>   load modules from specified files
 :load               clear all files except prelude
 :also <filenames>   read additional modules
 :reload             repeat last load command
 :project <filename> use project file
 :edit <filename>    edit file
 :edit               edit last module
 :module <module>    set module for evaluating expressions
 <expr>              evaluate expression
 :type <expr>        print type of expression
 :?                  display this list of commands
 :set <options>      set command line options
 :set                help on command line options
 :names [pat]        list names currently in scope
 :info <names>       describe named objects
 :browse <modules>   browse names defined in <modules>
 :find <name>        edit module containing definition of name
 :!command           shell escape
 :cd dir             change directory
 :gc                 force garbage collection
 :version            print Hugs version
 :quit               exit Hugs interpreter

Change module :module module
A :module module command changes the current module to one given by module. This is the module in which evaluation takes place and in which objects named in commands are resolved. The specified module must be part of the current program. If no module is specified, then the last module to be loaded is assumed. (Note that the name of the current module is usually displayed as part of the Hugs prompt.)

Change directory :cd directory
A :cd dir command changes the current working directory to the path given by dir. If no path is specified, then the command is ignored.

Force a garbage collection :gc
A :gc command can be used to force a garbage collection of the interpreter heap, and to print the number of unused cells obtained as a result:
 Prelude> :gc
 Garbage collection recovered 95766 cells

Exit the interpreter :quit
The :quit command terminates the current Hugs session.

5.2  Loading and editing modules and projects

Load definitions from module :load [filename ...]
The :load command removes any previously loaded modules, and then attempts to load the definitions from each of the listed files, one after the other. If one of these files contains an error, then the load process is suspended and a suitable error message will be displayed. Once the problem has been corrected, the load process can be restarted using a :reload command. On some systems, the load process will be restarted automatically after a :edit command. (The exception occurs on Windows 95/NT because of the way that the interpreter and editor are executed as independent processes.)

If no file names are specified, the :load command just removes any previously loaded definitions, leaving just the definitions provided by the prelude.

The :load command uses the list of directories specified by the current path to search for module files. We can specify the list of directory and filename pairs, in the order that they are searched, using a Haskell list comprehension:
 [ (dir,file++suf) | dir <- [""] ++ path, suf <- ["", ".hs", ".lhs"]]
The file mentioned here is the name of the module file that was entered by the user, while path is the current Hugs search path. The search starts with the directory "", which usually represents a search relative to the current working directory. So, the very first filename that the system tries to load is exactly the same filename entered by the user. However, if the named file cannot be accessed, then the system will try adding a .hs suffix, and then a .lhs suffix, and then it will repeat the process for each directory in the path, until either a suitable file has been located, or, otherwise, until all of the possible choices have been tried. For example, this means that you do not have to type the .hs suffix to load a file Demo.hs from the current directory, provided that you do not already have a Demo file in the same directory. In the same way, it is not usually necesary to include the full pathname for one of the standard Hugs libraries. For example, provided that you do not have an Array, Array.hs, or Array.lhs file in the current working directory, you can load the standard Array library by typing just :load Array.

Load additional files :also [filename ...]
The :also command can be used to load module files, without removing any that have previously been loaded. (However, if any of the previously modules have been modified since they were last read, then they will be reloaded automatically before the additional files are read.)

If successful, a command of the form :load f1 .. fn is equivalent to the sequence of commands:
 :also f1
 :also fn
In particular, :also uses the same mechanisms as :load to search for modules.

Repeat last load command :reload
The :reload command can be used to repeat the last load command. If none of the previously loaded files has been modified since the last time that it was loaded, then :reload will not have any effect. However, if one of the modules has been modified, then it will be reloaded. Note that modules are loaded in a specific order, with the possibility that later modules may import earlier ones. To allow for this, if one module has been reloaded, then all subsequent modules will also be reloaded.

This feature is particularly useful in a windowing environment. If the interpreter is running in one window, then :reload can be used to force the interpreter to take account of changes made by editing modules in other windows.

Load project :project [project file]
Project files were originally introduced to ease the task of working with programs whose source code was spread over several files, all of which had to be loaded at the same time. The facilities for import chasing usually provide a much better way to deal with multiple file projects, but the current release of Hugs does still support the use of project files.

The :project command takes a single argument; the name of a text file containing a list of file names, separated from one another by whitespace (which may include spaces, newlines, or Haskell-style comments). For example, the following is a valid project file:
 {- A simple project file, Demo.prj -}
 Types   -- datatype definitions
 Basics  -- basic operations
 Main    -- the main program
If we load this into Hugs with a command :project Demo.prj, then the interpreter will read the project file and then try to load each of the named files. In this particular case, the overall effect is, essentially, the same as that of:
 :load Types Basics Main
Once a project file has been selected, the :project command (without any arguments) can be used to force Hugs to reread both the project file and the module files that it lists. This might be useful if, for example, the project file itself has been modified since it was first read.

Project file names may also be specified on the command line when the interpreter is invoked by preceding the project file name with a single + character. Note that there must be at least one space on each side of the +. Standard command line options can also be used at the same time, but additional filename arguments will be ignored. Starting Hugs with a command of the form hugs + Demo.prj is equivalent to starting Hugs without any arguments and then giving the command :p Demo.prj.

The :project command uses the same mechanisms as :load to locate the files mentioned in a project file, but it will not use the current path to locate the project file itself; you must specify a full pathname.

As has already been said, import chasing usually provides a much better way to deal with multiple file programs than the old project file system. The big advantage of import chasing is that dependencies between modules are documented within individual modules, leaving the system free to determine the order in which the files should be loaded. For example, if the Main module in the example above actually needs the definitions in Types and Basics, then this will be documented by import statements, and the whole program could be loaded with a single :load Main command.

Edit file :edit [file]
The :edit command starts an editor program to modify or view a module file. On Windows 95/NT, the editor and interpreter are executed as independent processes. On other systems, the current Hugs session will be suspended while the editor is running. Then, when the editor terminates, the Hugs session will be resumed and any files that have been changed will be reloaded automatically. The -E option should be used to configure Hugs to your preferred choice of editor.

If no filename is specified, then Hugs uses the name of the last file that it tried to load. This allows the :edit command to integrate smoothly with the facilities for loading files.

For example, suppose that you want to load four files, f1.hs, f2.hs, f3.hs and f4.hs into the interpreter, but the file f3.hs contains an error of some kind. If you give the command:
 :load f1 f2 f3 f4
then Hugs will successfully load f1.hs and f2.hs, but will abort the load command when it encounters the error in f3.hs, printing an error message to describe the problem that occured. Now, if you use the command:
then Hugs will start up the editor with the cursor positioned at the relevant line of f3.hs (whenever this is possible) so that the error can be corrected and the changes saved in f3.hs. When you close down the editor and return to Hugs, the interpreter will automatically attempt to reload f3.hs and then, if successful, go on to load the next file, f4.hs. So, after just two commands in Hugs, the error in f3.hs has been corrected and all four of the files listed on the original command line have been loaded into the interpreter, ready for use.

Find definition :find name
The :find name command starts up the editor at the definition of a type constructor or function, specified by the argument name, in one of the files currently loaded into Hugs. Note that Hugs must be configured with an appropriate editor for this to work properly. There are four possibilities:

Note that names of infix operators should be given without any enclosing them in parentheses. Thus :f !! starts an editor on the standard prelude at the first line in the definition of (!!). If a given name could be interpreted both as a type constructor and as a value constructor, then the former is assumed.

5.3  Finding information about the system

List names :names [pattern ...]
The :names command can be used to list the names of variables and functions whose definitions are currently loaded into the interpreter. Without any arguments, :names produces a list of all names known to the system; the names are listed in alphabetical order.

The :names command can also accept one or more pattern strings, limiting the list of names that will be printed to those matching one or more of the given pattern strings:
 Prelude> :n fold*
 foldl foldl' foldl1 foldr foldr1
 (5 names listed)
Each pattern string consists of a string of characters and may use standard wildcard syntax: * (matches anything), ? (matches any single character), \c (matches exactly the character c) and ranges of characters of the form [a-zA-Z], etc. For example:
 Prelude> :n *map* *[Ff]ile ?
 $ % * + - . / : < > appendFile map mapM mapM_ readFile writeFile ^
 (17 names listed)

Print type of expression :type expr
The :type command can be used to print the type of an expression without evaluating it. For example:
 Prelude> :t "hello, world"
 "hello, world" :: String
 Prelude> :t putStr "hello, world"
 putStr "hello, world" :: IO ()
 Prelude> :t sum [1..10]
 sum (enumFromTo 1 10) :: (Num a, Enum a) => a
Note that Hugs displays the most general type that can be inferred for each expression. For example, compare the type inferred for sum [1..10] above with the type printed by the evaluator (using :set +t):
 Prelude> :set +t
 Prelude> sum [1..10]
 55 :: Int
The difference is explained by the fact that the evaluator uses the Haskell default mechanism to instantiate the type variable a in the most general type to the type Int, avoiding an error with unresolved overloading.

Display information about names :info [name ...]
The :info command is useful for obtaining information about the files, classes, types and values that are currently loaded.

If there are no arguments, then :info prints a list of all the files that are currently loaded into the interpreter.
 Prelude> :info
 Hugs session for:
If there are arguments, then Hugs treats each one as a name, and displays information about any corresponding type constructor, class, or function. The following examples show the the kind of output that you can expect:

As the last example shows, the :info command can take several arguments and prints out information about each in turn. A warning message is displayed if there are no known references to an argument:
 Prelude> :info (:)
 Unknown reference `(:)'
This illustrates that the arguments are treated as textual names for operators, not syntactic expressions (for example, identifiers). The type of the (:) operator can be obtained using the command :info : as above. There is no provision for including wildcard characters of any form in the arguments of :info commands.

If a particular argument can be interpreted as, for example, both a constructor function, and a type constructor, depending on context, then the output for both possibilities will be displayed.

Display names defined in modules :browse [module ...]
The :browse command can be used to display the list of functions that are exported from the named modules:
 List> :browse Maybe
 module Maybe where
 mapMaybe :: (a -> Maybe b) -> [a] -> [b]
 catMaybes :: [Maybe a] -> [a]
 listToMaybe :: [a] -> Maybe a
 maybeToList :: Maybe a -> [a]
 fromMaybe :: a -> Maybe a -> a
 fromJust :: Maybe a -> a
 isNothing :: Maybe a -> Bool
 isJust :: Maybe a -> Bool
Only the names of currently loaded modules will be recognized.

Display Hugs version :version
The :version command is used to display the version of the Hugs interpreter:
 Prelude> :version
 -- Hugs Version September 1999
This is the same information that is displayed in the Hugs startup banner.

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