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