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:

- If expr has type `IO t`, for some type `t`, then it will be treated as a program using the I/O facilities provided by the Haskell `IO` monad. Any final result produced by the computation will be discarded. `
  Prelude> putStr "Hello, world"
  Hello, world
  Prelude>
  `
- In any other case, the value produced by the expression is converted to a string by applying the `show` function from the standard prelude, and the interpreter uses this to print the result. `
  Prelude> "Hello" ++ ", " ++ "world"
  "Hello, world"
  Prelude>
  ` Unlike some previous versions of Hugs, there is no special treatment for values of type `String`; to display a string without the enclosing quotes and special escapes, you should turn it into a program using the `putStr` function, as shown above.

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"
Prelude>
` 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
Test>
` 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
A
Test> take 5 (cycle [A,B])
[A, B, A, B, A]
Test>

`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)
Prelude>
` 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)
Prelude>

`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:

- On a Unix machine, the `SHELL` environment variable is used to determine which shell to use; the default is `/bin/sh`.
- On an DOS machine, the `COMSPEC` environment variable is used to determine which shell to use; this is usually `COMMAND.COM`.

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
Prelude>

`

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
Prelude>

`

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: `
:load
: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: `
:edit
` 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:

- If there is a type constructor with the specified name, then the cursor will be positioned at the first line in the definition of that type constructor.
- If the name is defined by a function or variable binding, then the cursor will be positioned at the first line in the definition of the function or variable (ignoring any type declaration, if present).
- If the name is a constructor function or a selector function associated with a particular datatype, then the cursor will be positioned at the first line in the definition of the corresponding datatype definition.
- If the name represents an internal Hugs function, then the cursor will be positioned at the beginning of the standard prelude file.

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)
Prelude>
` 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)
Prelude>
`

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
Prelude>
` 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
Prelude>
` 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:
/Hugs/lib/Prelude.hs
Demo.hs
Prelude>
` 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:

- Datatypes: The system displays the name of the datatype, the names and types of any constructors or selectors, and a summary of related instance declarations: `
  Prelude> :info Either
  -- type constructor
  data Either a b
  -- constructors:
  Left :: a -> Either a b
  Right :: b -> Either a b
  -- instances:
  instance (Eq b, Eq a) => Eq (Either a b)
  instance (Ord b, Ord a) => Ord (Either a b)
  instance (Read b, Read a) => Read (Either a b)
  instance (Show b, Show a) => Show (Either a b)
  instance Eval (Either a b)
  Prelude>
  ` Newtypes are dealt with in exactly the same way. For a simple example of a datatype with selectors, the output produced for a `Time` datatype: `
  data Time = MkTime { hours, mins, secs :: Int }
  ` is as follows: `
  Time> :info Time
  -- type constructor
  data Time
  -- constructors:
  MkTime :: Int -> Int -> Int -> Time
  -- selectors:
  hours :: Time -> Int
  mins :: Time -> Int
  secs :: Time -> Int
  -- instances:
  instance Eval Time
  Time>
  `
- Type synonyms: The system displays the name and expansion: `
  Prelude> :info String
  -- type constructor
  type String = [Char]
  Prelude>
  ` The expansion is not included in the output if the synonym is restricted.
- Type classes: The system lists the name, superclasses, members, and instance declarations for the specified class: `
  Prelude> :info Num
  -- type class
  class (Eq a, Show a, Eval a) => Num a where
  (+) :: a -> a -> a
  (-) :: a -> a -> a
  (*) :: a -> a -> a
  negate :: a -> a
  abs :: a -> a
  signum :: a -> a
  fromInteger :: Integer -> a
  fromInt :: Int -> a
  -- instances:
  instance Num Int
  instance Num Integer
  instance Num Float
  instance Num Double
  instance Integral a => Num (Ratio a)
  Prelude>
  `
- Other values: For example, named functions and individual constructor, selector, and member functions are displayed with their name and type: `
  Time> :info . : hours min
  (.) :: (a -> b) -> (c -> a) -> c -> b
  (:) :: a -> [a] -> [a] -- data constructor
  hours :: Time -> Int -- selector function
  min :: Ord a => a -> a -> a -- class member
  Time>
  `

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 `(:)'
Prelude>
` 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
List>
` 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
Prelude>
` This is the same information that is displayed in the Hugs startup banner.

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