3.6. GHCi commands
Prev | Chapter 3. Using GHCi | Next

## 3.6. GHCi commands

GHCi commands all begin with ‘`:`’ and consist of a single command name followed by zero or more parameters. The command name may be abbreviated, with ambiguities being resolved in favour of the more commonly used commands.

`:add` `module` ...

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

`:browse` [`*`]`module` ...

  Displays the identifiers defined by the module `module`, which must be either loaded into GHCi or be a member of a package. If the `*` symbol is placed before the module name, then all the identifiers defined 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.

`:cd` `dir`

  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.

`:def` `name` `expr`

  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.

`:edit [`file`]`

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

`:help` , `:?`

  Displays a list of the available commands.

`:info` `name` ...

  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.

`:load` `module` ...

  Recursively loads the specified `module`s, 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:

  - `module`, if it was loaded successfully, or

  - the most recently successfully loaded module, if any other modules were loaded as a result of the current `:load`, or

  - `Prelude` otherwise.

`:main `arg1` ... `argn``

  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 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"]

`:module [+|-] [*]`mod1` ... [*]`modn``

  Sets or modifies the current context for statements typed at the prompt. See Section 3.4.3, “What's really in scope at the prompt?” for more details.

`:quit`

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

`:reload`

  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.

`:set` [`option`...]

  Sets various options. See Section 3.7, “The `:set` command” for a list of available options. The `:set` command by itself shows which options are currently set.

`:set` `args` `arg` ...

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

`:set` `editor` `cmd`

  Sets the command used by `:edit` to `cmd`.

`:set` `prog` `prog`

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

`:set` `prompt` `prompt`

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

`:show bindings`

  Show the bindings made at the prompt and their types.

`:show modules`

  Show the list of modules currently load.

`:ctags` [`filename`] `:etags` [`filename`]

  Generates a “tags” file for Vi-style editors (`:ctags`) or Emacs-style editors (`etags`). If no filename is specified, the defaulit `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 10.1, “Ctags and Etags for Haskell: hasktags”.

`:type` `expression`

  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.

`:kind` `type`

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

`:undef` `name`

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

`:unset` `option`...

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

`:!` `command`...

  Executes the shell command `command`.

Prev | Up | Next
3.5. Invoking GHCi | Home | 3.7. The `:set` command