Abandons the current evaluation (only available when stopped at a breakpoint).

Add module(s) to the current target set, and perform a reload.

Travel back one step in the history. See Section 3.5.5, “Tracing and history”. See also: :trace, :history, :forward.

Set a breakpoint on the specified function or line and column. See Section 3.5.1.1, “Setting breakpoints”.

Displays the identifiers defined by the module module, which must be either loaded into GHCi or be a member of a package. If module is omitted, the most recently-loaded module is used.

If the * symbol is placed before the module name, then all the identifiers in scope in module are shown; otherwise the list is limited to the exports of module. The *-form is only available for modules which are interpreted; for compiled modules (including modules from packages) only the non-* form of :browse is available. If the ! symbol is appended to the command, data constructors and class methods will be listed individually, otherwise, they will only be listed in the context of their data type or class declaration. The !-form also annotates the listing with comments giving possible imports for each group of entries.

Prelude> :browse! Data.Maybe
-- not currently imported
Data.Maybe.catMaybes :: [Maybe a] -> [a]
Data.Maybe.fromJust :: Maybe a -> a
Data.Maybe.fromMaybe :: a -> Maybe a -> a
Data.Maybe.isJust :: Maybe a -> Bool
Data.Maybe.isNothing :: Maybe a -> Bool
Data.Maybe.listToMaybe :: [a] -> Maybe a
Data.Maybe.mapMaybe :: (a -> Maybe b) -> [a] -> [b]
Data.Maybe.maybeToList :: Maybe a -> [a]
-- imported via Prelude
Just :: a -> Maybe a
data Maybe a = Nothing | Just a
Nothing :: Maybe a
maybe :: b -> (a -> b) -> Maybe a -> b

This output shows that, in the context of the current session, in the scope of Prelude, the first group of items from Data.Maybe have not been imported (but are available in fully qualified form in the GHCi session - see Section 3.4.3, “What's really in scope at the prompt?”), whereas the second group of items have been imported via Prelude and are therefore available either unqualified, or with a Prelude. qualifier.

Changes the current working directory to dir. A ‘˜’ symbol at the beginning of dir will be replaced by the contents of the environment variable HOME.

NOTE: changing directories causes all currently loaded modules to be unloaded. This is because the search path is usually expressed using relative directories, and changing the search path in the middle of a session is not supported.

Executes expr as a computation of type IO String, and then executes the resulting string as a list of GHCi commands. Multiple commands are separated by newlines. The :cmd command is useful with :def and :set stop.

Continue the current evaluation, when stopped at a breakpoint.

Generates a “tags” file for Vi-style editors (:ctags) or Emacs-style editors (:etags). If no filename is specified, the default tags or TAGS is used, respectively. Tags for all the functions, constructors and types in the currently loaded modules are created. All modules must be interpreted for these commands to work.

See also Section 11.1, “Ctags and Etags for Haskell: hasktags”.

:def is used to define new commands, or macros, in GHCi. The command :def name expr defines a new GHCi command :name, implemented by the Haskell expression expr, which must have type String -> IO String. When :name args is typed at the prompt, GHCi will run the expression (name args), take the resulting String, and feed it back into GHCi as a new sequence of commands. Separate commands in the result must be separated by ‘\n’.

That's all a little confusing, so here's a few examples. To start with, here's a new GHCi command which doesn't take any arguments or produce any results, it just outputs the current date & time:

Prelude> let date _ = Time.getClockTime >>= print >> return ""
Prelude> :def date date
Prelude> :date
Fri Mar 23 15:16:40 GMT 2001

Here's an example of a command that takes an argument. It's a re-implementation of :cd:

Prelude> let mycd d = Directory.setCurrentDirectory d >> return ""
Prelude> :def mycd mycd
Prelude> :mycd ..

Or I could define a simple way to invoke “ghc ––make Main” in the current directory:

Prelude> :def make (\_ -> return ":! ghc ––make Main")

We can define a command that reads GHCi input from a file. This might be useful for creating a set of bindings that we want to repeatedly load into the GHCi session:

Prelude> :def . readFile
Prelude> :. cmds.ghci

Notice that we named the command :., by analogy with the ‘.’ Unix shell command that does the same thing.

Typing :def on its own lists the currently-defined macros. Attempting to redefine an existing command name results in an error unless the :def! form is used, in which case the old command with that name is silently overwritten.

Delete one or more breakpoints by number (use :show breaks to see the number of each breakpoint). The * form deletes all the breakpoints.

Opens an editor to edit the file file, or the most recently loaded module if file is omitted. The editor to invoke is taken from the EDITOR environment variable, or a default editor on your system if EDITOR is not set. You can change the editor using :set editor.

See :ctags.

Prints the value of identifier in the same way as :print. Unlike :print, :force evaluates each thunk that it encounters while traversing the value. This may cause exceptions or infinite loops, or further breakpoints (which are ignored, but displayed).

Move forward in the history. See Section 3.5.5, “Tracing and history”. See also: :trace, :history, :back.

Displays a list of the available commands.

Repeat the previous command.

Display the history of evaluation steps. With a number, displays that many steps (default: 20). For use with :trace; see Section 3.5.5, “Tracing and history”.

Displays information about the given name(s). For example, if name is a class, then the class methods and their types will be printed; if name is a type constructor, then its definition will be printed; if name is a function, then its type will be printed. If name has been loaded from a source file, then GHCi will also display the location of its definition in the source.

For types and classes, GHCi also summarises instances that mention them. To avoid showing irrelevant information, an instance is shown only if (a) its head mentions name, and (b) all the other things mentioned in the instance are in scope (either qualified or otherwise) as a result of a :load or :module commands.

Infers and prints the kind of type. The latter can be an arbitrary type expression, including a partial application of a type constructor, such as Either Int.

Recursively loads the specified modules, and all the modules they depend on. Here, each module must be a module name or filename, but may not be the name of a module in a package.

All previously loaded modules, except package modules, are forgotten. The new set of modules is known as the target set. Note that :load can be used without any arguments to unload all the currently loaded modules and bindings.

After a :load command, the current context is set to:

When a program is compiled and executed, it can use the getArgs function to access the command-line arguments. However, we cannot simply pass the arguments to the main function while we are testing in ghci, as the main function doesn't take its arguments directly.

Instead, we can use the :main command. This runs whatever main is in scope, with any arguments being treated the same as command-line arguments, e.g.:

Prelude> let main = System.Environment.getArgs >>= print
Prelude> :main foo bar
["foo","bar"]

Sets or modifies the current context for statements typed at the prompt. The form import mod is equivalent to :module +mod. See Section 3.4.3, “What's really in scope at the prompt?” for more details.

Prints a value without forcing its evaluation. :print may be used on values whose types are unknown or partially known, which might be the case for local variables with polymorphic types at a breakpoint. While inspecting the runtime value, :print attempts to reconstruct the type of the value, and will elaborate the type in GHCi's environment if possible. If any unevaluated components (thunks) are encountered, then :print binds a fresh variable with a name beginning with _t to each thunk. See Section 3.5.1, “Breakpoints and inspecting variables” for more information. See also the :sprint command, which works like :print but does not bind new variables.

Quits GHCi. You can also quit by typing control-D at the prompt.

Attempts to reload the current target set (see :load) if any of the modules in the set, or any dependent module, has changed. Note that this may entail loading new modules, or dropping modules which are no longer indirectly required by the target.

Sets various options. See Section 3.8, “The :set command” for a list of available options and Section 5.17.10, “Interactive-mode options” for a list of GHCi-specific flags. The :set command by itself shows which options are currently set. It also lists the current dynamic flag settings, with GHCi-specific flags listed separately.

Sets the list of arguments which are returned when the program calls System.getArgs.

Sets the command used by :edit to cmd.

Sets the string to be returned when the program calls System.getProgName.

Sets the string to be used as the prompt in GHCi. Inside prompt, the sequence %s is replaced by the names of the modules currently in scope, and %% is replaced by %.

Set a command to be executed when a breakpoint is hit, or a new item in the history is selected. The most common use of :set stop is to display the source code at the current location, e.g. :set stop :list.

If a number is given before the command, then the commands are run when the specified breakpoint (only) is hit. This can be quite useful: for example, :set stop 1 :continue effectively disables breakpoint 1, by running :continue whenever it is hit (although GHCi will still emit a message to say the breakpoint was hit). What's more, with cunning use of :def and :cmd you can use :set stop to implement conditional breakpoints:

*Main> :def cond \expr -> return (":cmd if (" ++ expr ++ ") then return \"\" else return \":continue\"")
*Main> :set stop 0 :cond (x < 3)

Ignoring breakpoints for a specified number of iterations is also possible using similar techniques.

Show the bindings made at the prompt and their types.

List the active breakpoints.

List the active evaluations that are stopped at breakpoints.

Show the list of modules currently loaded.

Show the currently active package flags, as well as the list of packages currently loaded.

Show the currently active language flags.

Displays the specified setting (see :set).

Prints a value without forcing its evaluation. :sprint is similar to :print, with the difference that unevaluated subterms are not bound to new variables, they are simply denoted by ‘_’.

Single-step from the last breakpoint. With an expression argument, begins evaluation of the expression with a single-step.

Evaluates the given expression (or from the last breakpoint if no expression is given), and additionally logs the evaluation steps for later inspection using :history. See Section 3.5.5, “Tracing and history”.

Infers and prints the type of expression, including explicit forall quantifiers for polymorphic types. The monomorphism restriction is not applied to the expression during type inference.

Undefines the user-defined command name (see :def above).

Unsets certain options. See Section 3.8, “The :set command” for a list of available options.

Executes the shell command command.