</footnote>
is GHC's interactive environment, in which Haskell expressions can
be interactively evaluated and programs can be interpreted. If
- you're famililar with Hugs<indexterm><primary>Hugs</primary>
+ you're famililar with <ulink url="http://www.haskell.org/hugs/">Hugs</ulink><indexterm><primary>Hugs</primary>
</indexterm>, then you'll be right at home with GHCi. However, GHCi
also has support for interactively loading compiled code, as well as
- supporting all<footnote><para>except the FFI, at the moment</para>
- </footnote>the language extensions that GHC provides.</para>
+ supporting all<footnote><para>except <literal>foreign export</literal>, at the moment</para>
+ </footnote> the language extensions that GHC provides.</para>
<indexterm><primary>FFI</primary><secondary>GHCi support</secondary></indexterm>
<indexterm><primary>Foreign Function Interface</primary><secondary>GHCi support</secondary></indexterm>
$ ghci
___ ___ _
/ _ \ /\ /\/ __(_)
- / /_\// /_/ / / | | GHC Interactive, version 5.00, For Haskell 98.
+ / /_\// /_/ / / | | GHC Interactive, version 5.04, for Haskell 98.
/ /_\\/ __ / /___| | http://www.haskell.org/ghc/
\____/\/ /_/\____/|_| Type :? for help.
-Loading package std ... linking ... done.
+Loading package base ... linking ... done.
+Loading package haskell98 ... linking ... done.
Prelude>
</screen>
<screen>
Commands available from the prompt:
- <stmt> evaluate/run <stmt>
- :cd <dir> change directory to <dir>
- :def <cmd> <expr> define a macro :<cmd>
- :help, :? display this list of commands
- :load <filename> load a module (and it dependents)
- :module <mod> set the context for expression evaluation to <mod>
- :reload reload the current module set
- :set <option> ... set options
- :type <expr> show the type of <expr>
- :unset <option> ... unset options
- :quit exit GHCi
- :!<command> run the shell command <command>
+
+ <stmt> evaluate/run <stmt>
+ :add <filename> ... add module(s) to the current target set
+ :browse [*]<module> display the names defined by <module>
+ :cd <dir> change directory to <dir>
+ :def <cmd> <expr> define a command :<cmd>
+ :help, :? display this list of commands
+ :info [<name> ...] display information about the given names
+ :load <filename> ... load module(s) and their dependents
+ :module [+/-] [*]<mod> ... set the context for expression evaluation
+ :reload reload the current module set
+
+ :set <option> ... set options
+ :set args <arg> ... set the arguments returned by System.getArgs
+ :set prog <progname> set the value returned by System.getProgName
+
+ :show modules show the currently loaded modules
+ :show bindings show the current bindings made at the prompt
+
+ :type <expr> show the type of <expr>
+ :undef <cmd> undefine user-defined command :<cmd>
+ :unset <option> ... unset options
+ :quit exit GHCi
+ :!<command> run the shell command <command>
+
Options for `:set' and `:unset':
+
+r revert top-level expressions after each evaluation
+s print timing/memory stats after each evaluation
+t print type after evaluation
- -<flag> most GHC command line flags can also be set here
+ -<flags> most GHC command line flags can also be set here
(eg. -v2, -fglasgow-exts, etc.)
</screen>
<title>Loading source files</title>
<para>Suppose we have the following Haskell source code, which we
- place in a file <filename>Main.hs</filename> in the current
- directory:</para>
+ place in a file <filename>Main.hs</filename>:</para>
<programlisting>
main = print (fac 20)
fac n = n * fac (n-1)
</programlisting>
+ <para>You can save <filename>Main.hs</filename> anywhere you like,
+ but if you save it somewhere other than the current
+ directory<footnote><para>If you started up GHCi from the command
+ line then GHCi's current directory is the same as the current
+ directory of the shell from which it was started. If you started
+ GHCi from the “Start” menu in Windows, then the
+ current directory is probably something like
+ <filename>C:\Documents and Settings\<replaceable>user
+ name</replaceable></filename>.</para> </footnote> then we will
+ need to change to the right directory in GHCi:</para>
+
+<screen>
+Prelude> :cd <replaceable>dir</replaceable>
+</screen>
+
+ <para>where <replaceable>dir</replaceable> is the directory (or
+ folder) in which you saved <filename>Main.hs</filename>.</para>
+
<para>To load a Haskell source file into GHCi, use the
<literal>:load</literal> command:</para>
<indexterm><primary><literal>:load</literal></primary></indexterm>
Prelude> :load Main
Compiling Main ( Main.hs, interpreted )
Ok, modules loaded: Main.
-Main>
+*Main>
</screen>
<para>GHCi has loaded the <literal>Main</literal> module, and the
- prompt has changed to “<literal>Main></literal>” to
+ prompt has changed to “<literal>*Main></literal>” to
indicate that the current context for expressions typed at the
- prompt is the <literal>Main</literal> module we just
- loaded. So we can now type expressions involving the functions
- from <filename>Main.hs</filename>:</para>
+ prompt is the <literal>Main</literal> module we just loaded (we'll
+ explain what the <literal>*</literal> means later in <xref
+ linkend="ghci-scope">). So we can now type expressions involving
+ the functions from <filename>Main.hs</filename>:</para>
<screen>
-Main> fac 17
+*Main> fac 17
355687428096000
</screen>
indirectly, by the topmost module, and load them all in dependency
order.</para>
- <sect2>
+ <sect2 id="ghci-modules-filenames">
<title>Modules vs. filenames</title>
<indexterm><primary>modules</primary><secondary>and filenames</secondary></indexterm>
<indexterm><primary>filenames</primary><secondary>of modules</secondary></indexterm>
in the same directory and you can't call them all
<filename>Main.hs</filename>.</para>
- <para>One final note: if you load a module called Main, it must
- contain a <literal>main</literal> function, just like in
- GHC.</para>
+ <para>The search path for finding source files is specified with
+ the <option>-i</option> option on the GHCi command line, like
+ so:</para>
+<screen>ghci -i<replaceable>dir<subscript>1</subscript></replaceable>:...:<replaceable>dir<subscript>n</subscript></replaceable></screen>
+
+ <para>or it can be set using the <literal>:set</literal> command
+ from within GHCi (see <xref
+ linkend="ghci-cmd-line-options">)<footnote><para>Note that in
+ GHCi, and <option>––make</option> mode, the <option>-i</option>
+ option is used to specify the search path for
+ <emphasis>source</emphasis> files, whereas in standard
+ batch-compilation mode the <option>-i</option> option is used to
+ specify the search path for interface files, see <xref
+ linkend="search-path">.</para> </footnote></para>
+
+ <para>One consequence of the way that GHCi follows dependencies
+ to find modules to load is that every module must have a source
+ file. The only exception to the rule is modules that come from
+ a package, including the <literal>Prelude</literal> and standard
+ libraries such as <literal>IO</literal> and
+ <literal>Complex</literal>. If you attempt to load a module for
+ which GHCi can't find a source file, even if there are object
+ and interface files for the module, you'll get an error
+ message.</para>
</sect2>
<sect2>
normally converted to byte-code and run using the interpreter.
However, interpreted code can also run alongside compiled code in
GHCi; indeed, normally when GHCi starts, it loads up a compiled
- copy of package <literal>std</literal>, which contains the Prelude
- and standard libraries.</para>
+ copy of the <literal>base</literal> package, which contains the
+ <literal>Prelude</literal>.</para>
<para>Why should we want to run compiled code? Well, compiled
code is roughly 10x faster than interpreted code, but takes about
Compiling B ( B.hs, interpreted )
Compiling A ( A.hs, interpreted )
Ok, modules loaded: A, B, C, D.
-Main>
+*Main>
</screen>
<para>In the messages from the compiler, we see that it skipped D,
isn't necessary, because the source and everything it depends on
is unchanged since the last compilation.</para>
+ <para>At any time you can use the command
+ <literal>:show modules</literal>
+ to get a list of the modules currently loaded
+ into GHCi:</para>
+
+<screen>
+*Main> :show modules
+D ( D.hs, D.o )
+C ( C.hs, interpreted )
+B ( B.hs, interpreted )
+A ( A.hs, interpreted )
+*Main></screen>
+
<para>If we now modify the source of D (or pretend to: using Unix
command <literal>touch</literal> on the source file is handy for
this), the compiler will no longer be able to use the object file,
because it might be out of date:</para>
<screen>
-Main> :! touch D.hs
-Main> :reload
+*Main> :! touch D.hs
+*Main> :reload
Compiling D ( D.hs, interpreted )
Skipping C ( C.hs, interpreted )
Skipping B ( B.hs, interpreted )
Skipping A ( A.hs, interpreted )
Ok, modules loaded: A, B, C, D.
-Main>
+*Main>
</screen>
<para>Note that module D was compiled, but in this instance
<para>So let's try compiling one of the other modules:</para>
<screen>
-Main> :! ghc -c C.hs
-Main> :load A
+*Main> :! ghc -c C.hs
+*Main> :load A
Compiling D ( D.hs, interpreted )
Compiling C ( C.hs, interpreted )
Compiling B ( B.hs, interpreted )
also compile D:</para>
<screen>
-Main> :! ghc -c D.hs
-Main> :reload
+*Main> :! ghc -c D.hs
+*Main> :reload
Ok, modules loaded: A, B, C, D.
</screen>
<literal>:load</literal>:</para>
<screen>
-Main> :load A
+*Main> :load A
Skipping D ( D.hs, D.o )
Skipping C ( C.hs, C.o )
Compiling B ( B.hs, interpreted )
<para>HINT: since GHCi will only use a compiled object file if it
can sure that the compiled version is up-to-date, a good technique
when working on a large program is to occasionally run
- <literal>ghc --make</literal> to compile the whole project (say
+ <literal>ghc ––make</literal> to compile the whole project (say
before you go for lunch :-), then continue working in the
interpreter. As you modify code, the new modules will be
interpreted, but the rest of the project will remain
<sect2 id="ghci-scope">
<title>What's really in scope at the prompt?</title>
- <para>When you type an expression at the prompt, what
- identifiers and types are in scope? GHCi has a concept of a
- <firstterm>context</firstterm> module, which can be set using
- the <literal>:module</literal> command.</para>
+ <para>When you type an expression at the prompt, what
+ identifiers and types are in scope? GHCi provides a flexible
+ way to control exactly how the context for an expression is
+ constructed. Let's start with the simple cases; when you start
+ GHCi the prompt looks like this:</para>
- <para>The context module is shown in the prompt: for example,
- the prompt <literal>Prelude></literal> indicates that the
- current context for evaluating expressions is the Haskell
- <literal>Prelude</literal> module. The Prelude is the default
- context when you start up GHCi.</para>
- <indexterm><primary><literal>Prelude</literal></primary></indexterm>
+<screen>Prelude></screen>
- <para>Exactly which entities are in scope in a given context
- depends on whether the context module is compiled or
- interpreted:</para>
+ <para>Which indicates that everything from the module
+ <literal>Prelude</literal> is currently in scope. If we now
+ load a file into GHCi, the prompt will change:</para>
- <itemizedlist>
- <listitem>
- <para>If the context module is interpreted, then everything
- that was in scope during compilation of that module is also
- in scope at the prompt, i.e. all the imports and any
- top-level functions, types and classes defined in that
- module.</para>
- </listitem>
+<screen>
+Prelude> :load Main.hs
+Compiling Main ( Main.hs, interpreted )
+*Main>
+</screen>
- <listitem>
- <para>If the context module comes from a package, or is
- otherwise compiled, then only the exports of that module are
- in scope at the prompt. So for example, when the current
- context module is <literal>Prelude</literal>, everything the
- <literal>Prelude</literal> exports is in scope, but if we
- switch context to eg. <literal>Time</literal>, then
- everything from the <literal>Prelude</literal> is now
- invisible.</para>
- </listitem>
- </itemizedlist>
+ <para>The new prompt is <literal>*Main</literal>, which
+ indicates that we are typing expressions in the context of the
+ top-level of the <literal>Main</literal> module. Everything
+ that is in scope at the top-level in the module
+ <literal>Main</literal> we just loaded is also in scope at the
+ prompt (probably including <literal>Prelude</literal>, as long
+ as <literal>Main</literal> doesn't explicitly hide it).</para>
+
+ <para>The syntax
+ <literal>*<replaceable>module</replaceable></literal> indicates
+ that it is the full top-level scope of
+ <replaceable>module</replaceable> that is contributing to the
+ scope for expressions typed at the prompt. Without the
+ <literal>*</literal>, just the exports of the module are
+ visible.</para>
+
+ <para>We're not limited to a single module: GHCi can combine
+ scopes from multiple modules, in any mixture of
+ <literal>*</literal> and non-<literal>*</literal> forms. GHCi
+ combines the scopes from all of these modules to form the scope
+ that is in effect at the prompt. For technical reasons, GHCi
+ can only support the <literal>*</literal>-form for modules which
+ are interpreted, so compiled modules and package modules can
+ only contribute their exports to the current scope.</para>
+
+ <para>The scope is manipulated using the
+ <literal>:module</literal> command. For example, if the current
+ scope is <literal>Prelude</literal>, then we can bring into
+ scope the exports from the module <literal>IO</literal> like
+ so:</para>
+
+<screen>
+Prelude> :module +IO
+Prelude,IO> hPutStrLn stdout "hello\n"
+hello
+Prelude,IO>
+</screen>
+
+ <para>(Note: <literal>:module</literal> can be shortened to
+ <literal>:m</literal>). The full syntax of the
+ <literal>:module</literal> command is:</para>
+
+<screen>
+:module <optional>+|-</optional> <optional>*</optional><replaceable>mod<subscript>1</subscript></replaceable> ... <optional>*</optional><replaceable>mod<subscript>n</subscript></replaceable>
+</screen>
- <para>The reason for this unfortunate distinction is boring: for
- a compiled module when the source isn't available, the compiler
- has no way of knowing what was in scope when the module was
- compiled (and we don't store this information in the interface
- file). However, in practice it shouldn't be a problem: if you
- want both <literal>Time</literal> and <literal>Prelude</literal>
- in scope at the same time, just create a file containing the
- line <literal>import Time</literal> and load it into
- GHCi.</para>
-
- <para>To make life slightly easier, the GHCi prompt also behaves
- as if there is an implicit <literal>import qualified</literal>
- declaration for every module in every package, and every module
- currently loaded into GHCi. So in the above example where the
- <literal>Prelude</literal> was invisible, we can always get at
- <literal>Prelude</literal> identifiers by qualifying them, eg.
- <literal>Prelude.map</literal>.</para>
+ <para>Using the <literal>+</literal> form of the
+ <literal>module</literal> commands adds modules to the current
+ scope, and <literal>-</literal> removes them. Without either
+ <literal>+</literal> or <literal>-</literal>, the current scope
+ is replaced by the set of modules specified. Note that if you
+ use this form and leave out <literal>Prelude</literal>, GHCi
+ will assume that you really wanted the
+ <literal>Prelude</literal> and add it in for you (if you don't
+ want the <literal>Prelude</literal>, then ask to remove it with
+ <literal>:m -Prelude</literal>).</para>
+
+ <para>The scope is automatically set after a
+ <literal>:load</literal> command, to the most recently loaded
+ "target" module, in a <literal>*</literal>-form if possible.
+ For example, if you say <literal>:load foo.hs bar.hs</literal>
+ and <filename>bar.hs</filename> contains module
+ <literal>Bar</literal>, then the scope will be set to
+ <literal>*Bar</literal> if <literal>Bar</literal> is
+ interpreted, or if <literal>Bar</literal> is compiled it will be
+ set to <literal>Prelude,Bar</literal> (GHCi automatically adds
+ <literal>Prelude</literal> if it isn't present and there aren't
+ any <literal>*</literal>-form modules).</para>
+
+ <para>With multiple modules in scope, especially multiple
+ <literal>*</literal>-form modules, it is likely that name
+ clashes will occur. Haskell specifies that name clashes are
+ only reported when an ambiguous identifier is used, and GHCi
+ behaves in the same way for expressions typed at the
+ prompt.</para>
+
+ <sect3>
+ <title>Qualified names</title>
+
+ <para>To make life slightly easier, the GHCi prompt also
+ behaves as if there is an implicit <literal>import
+ qualified</literal> declaration for every module in every
+ package, and every module currently loaded into GHCi.</para>
+ </sect3>
</sect2>
<sect2>
</screen>
<para>Any exceptions raised during the evaluation or execution
of the statement are caught and printed by the GHCi command line
- interface (see <xref linkend="sec-Exception"> for more
- information on GHC's Exception support).</para>
+ interface (for more information on exceptions, see the module
+ <literal>Control.Exception</literal> in the libraries
+ documentation).</para>
<para>Every new binding shadows any existing bindings of the
same name, including entities that are in scope in the current
<literal>:module</literal>: the temporary bindings just move to
the new location.</para>
+ <para>HINT: To get a list of the bindings currently in scope, use the
+ <literal>:show bindings</literal> command:</para>
+
+<screen>
+Prelude> :show bindings
+x :: Int
+Prelude></screen>
+
<para>HINT: if you turn on the <literal>+t</literal> option,
GHCi will show the type of each variable bound by a statement.
For example:</para>
of <literal>it</literal> is lost.</para>
</sect2>
+
+ <sect2>
+ <title>Type defaulting in GHCi</title>
+ <indexterm><primary>Type default</primary></indexterm>
+ <indexterm><primary><literal>Show</literal> class</primary></indexterm>
+ <para>
+ Consider this GHCi session:
+<programlisting>
+ ghci> reverse []
+</programlisting>
+ What should GHCi do? Strictly speaking, the program is ambiguous. <literal>show (reverse [])</literal>
+ (which is what GHCi computes here) has type <literal>Show a => a</literal> and how that displays depends
+ on the type <literal>a</literal>. For example:
+<programlisting>
+ ghci> (reverse []) :: String
+ ""
+ ghci> (reverse []) :: [Int]
+ []
+</programlisting>
+ However, it is tiresome for the user to have to specify the type, so GHCi extends Haskell's type-defaulting
+ rules (Section 4.3.4 of the Haskell 98 Report (Revised)) as follows. If the expression yields a set of
+ type constraints that are all from standard classes (<literal>Num</literal>, <literal>Eq</literal> etc.),
+ and at least one is either a numeric class <emphasis>or the <literal>Show</literal>,
+ <literal>Eq</literal>, or <literal>Ord</literal> class</emphasis>,
+ GHCi will try to use one of the <literal>default</literal> types, just as described in the Report.
+ </para>
+ </sect2>
</sect1>
- <sect1>
+ <sect1 id="ghci-invokation">
<title>Invoking GHCi</title>
<indexterm><primary>invoking</primary><secondary>GHCi</secondary></indexterm>
- <indexterm><primary><option>--interactive</option></primary></indexterm>
+ <indexterm><primary><option>––interactive</option></primary></indexterm>
<para>GHCi is invoked with the command <literal>ghci</literal> or
- <literal>ghc --interactive</literal>. A module or filename can
- also be specified on the command line; this instructs GHCi to load
- the that module or filename (and all the modules it depends on),
- just as if you had said <literal>:load
- <replaceable>module</replaceable></literal> at the GHCi prompt
- (see <xref linkend="ghci-commands">). For example, to start GHCi
- and load the program whose topmost module is in the file
- <literal>Main.hs</literal>, we could say:</para>
+ <literal>ghc ––interactive</literal>. One or more modules or
+ filenames can also be specified on the command line; this
+ instructs GHCi to load the specified modules or filenames (and all
+ the modules they depend on), just as if you had said
+ <literal>:load <replaceable>modules</replaceable></literal> at the
+ GHCi prompt (see <xref linkend="ghci-commands">). For example, to
+ start GHCi and load the program whose topmost module is in the
+ file <literal>Main.hs</literal>, we could say:</para>
<screen>
$ ghci Main.hs
</screen>
- <para>Note: only <emphasis>one</emphasis> module name or filename
- may be given on the command line.</para>
-
<para>Most of the command-line options accepted by GHC (see <xref
linkend="using-ghc">) also make sense in interactive mode. The ones
that don't make sense are mostly obvious; for example, GHCi
<title>Packages</title>
<indexterm><primary>packages</primary><secondary>with GHCi</secondary></indexterm>
- <para>GHCi can make use of all the packages that come with GHC,
- For example, to start up GHCi with the <literal>text</literal>
- package loaded:</para>
+ <para>Most packages (see <xref linkend="using-packages">) are
+ available without needing to specify any extra flags at all:
+ they will be automatically loaded the first time they are
+ needed.</para>
+
+ <para>For non-auto packages, however, you need to request the
+ package be loaded by using the <literal>-package</literal> flag:</para>
<screen>
-$ ghci -package text
+$ ghci -package data
___ ___ _
/ _ \ /\ /\/ __(_)
- / /_\// /_/ / / | | GHC Interactive, version 5.00, For Haskell 98.
+ / /_\// /_/ / / | | GHC Interactive, version 5.05, for Haskell 98.
/ /_\\/ __ / /___| | http://www.haskell.org/ghc/
\____/\/ /_/\____/|_| Type :? for help.
-Loading package std ... linking ... done.
+Loading package base ... linking ... done.
+Loading package haskell98 ... linking ... done.
Loading package lang ... linking ... done.
-Loading package text ... linking ... done.
+Loading package concurrent ... linking ... done.
+Loading package readline ... linking ... done.
+Loading package unix ... linking ... done.
+Loading package posix ... linking ... done.
+Loading package util ... linking ... done.
+Loading package data ... linking ... done.
Prelude>
-</screen>
-
- <para>Note that GHCi also loaded the <literal>lang</literal>
- package even though we didn't ask for it: that's because the
- <literal>text</literal> package makes use of one or more of the
- modules in <literal>lang</literal>, and therefore has a
- dependency on it.</para>
+</screen>
<para>The following command works to load new packages into a
running GHCi:</para>
<para>But note that doing this will cause all currently loaded
modules to be unloaded, and you'll be dumped back into the
- Prelude.</para>
+ <literal>Prelude</literal>.</para>
</sect2>
<sect2>
<para>Extra libraries may be specified on the command line using
the normal <literal>-l<replaceable>lib</replaceable></literal>
- option. For example, to load the “m” library:</para>
+ option. (The term <emphasis>library</emphasis> here refers to
+ libraries of foreign object code; for using libraries of Haskell
+ source code, see <xref linkend="ghci-modules-filenames">.) For
+ example, to load the “m” library:</para>
<screen>
$ ghci -lm
<para>On systems with <literal>.so</literal>-style shared
libraries, the actual library loaded will the
- <filename>lib<replaceable>lib</replaceable>.so</filename>. If
- no such library exists on the standard library search path,
- including paths given using
- <literal>-L<replaceable>path</replaceable></literal>, then
- <literal>ghci</literal> will signal an error.</para>
+ <filename>lib<replaceable>lib</replaceable>.so</filename>. GHCi
+ searches the following places for libraries, in this order:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>Paths specified using the
+ <literal>-L<replaceable>path</replaceable></literal>
+ command-line option,</para>
+ </listitem>
+ <listitem>
+ <para>the standard library search path for your system,
+ which on some systems may be overriden by setting the
+ <literal>LD_LIBRARY_PATH</literal> environment
+ variable.</para>
+ </listitem>
+ </itemizedlist>
<para>On systems with <literal>.dll</literal>-style shared
libraries, the actual library loaded will be
<filename><replaceable>lib</replaceable>.dll</filename>. Again,
GHCi will signal an error if it can't find the library.</para>
+
+ <para>GHCi can also load plain object files
+ (<literal>.o</literal> or <literal>.obj</literal> depending on
+ your platform) from the command-line. Just add the name the
+ object file to the command line.</para>
</sect2>
</sect1>
<variablelist>
<varlistentry>
+ <term><literal>:add</literal>
+ <replaceable>module</replaceable> ...</term>
+ <indexterm><primary><literal>:add</literal></primary></indexterm>
+ <listitem>
+ <para>Add <replaceable>module</replaceable>(s) to the
+ current <firstterm>target set</firstterm>, and perform a
+ reload.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>:browse</literal>
+ <optional><literal>*</literal></optional><replaceable>module</replaceable>
+ ...</term>
+ <indexterm><primary><literal>:browse</literal></primary>
+ </indexterm>
+ <listitem>
+ <para>Displays the identifiers defined by the module
+ <replaceable>module</replaceable>, which must be either
+ loaded into GHCi or be a member of a package. If the
+ <literal>*</literal> symbol is placed before the module
+ name, then <emphasis>all</emphasis> the identifiers defined
+ in <replaceable>module</replaceable> are shown; otherwise
+ the list is limited to the exports of
+ <replaceable>module</replaceable>. The
+ <literal>*</literal>-form is only available for modules
+ which are interpreted; for compiled modules (including
+ modules from packages) only the non-<literal>*</literal>
+ form of <literal>:browse</literal> is available.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
<term><literal>:cd</literal> <replaceable>dir</replaceable></term>
<indexterm><primary><literal>:cd</literal></primary></indexterm>
<listitem>
beginning of <replaceable>dir</replaceable> will be replaced
by the contents of the environment variable
<literal>HOME</literal>.</para>
+
+ <para>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.</para>
</listitem>
</varlistentry>
</screen>
<para>Or I could define a simple way to invoke
- “<literal>ghc --make Main</literal>” in the
+ “<literal>ghc ––make Main</literal>” in the
current directory:</para>
<screen>
-Prelude> :def make (\_ -> return ":! ghc --make Main")
+Prelude> :def make (\_ -> return ":! ghc ––make Main")
</screen>
</listitem>
</varlistentry>
<varlistentry>
- <term><literal>:load</literal> <replaceable>module</replaceable></term>
+ <term><literal>:info</literal> <replaceable>name</replaceable>
+ ...</term>
+ <indexterm><primary><literal>:info</literal></primary>
+ </indexterm>
+ <listitem>
+ <para>Displays information about the given name(s). For
+ example, if <replaceable>name</replaceable> is a class, then
+ the class methods and their types will be printed; if
+ <replaceable>name</replaceable> is a type constructor, then
+ its definition will be printed; if
+ <replaceable>name</replaceable> is a function, then its type
+ will be printed. If <replaceable>name</replaceable> has
+ been loaded from a source file, then GHCi will also display
+ the location of its definition in the source.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>:load</literal>
+ <replaceable>module</replaceable> ...</term>
<indexterm><primary><literal>:load</literal></primary></indexterm>
<listitem>
- <para>Recursively loads <replaceable>module</replaceable>
- (which may be a module name or filename), and all the
- modules it depends on. All previously loaded modules are
- forgotten. The module <replaceable>module</replaceable> is
- known as the <firstterm>target</firstterm>.</para>
+ <para>Recursively loads the specified
+ <replaceable>module</replaceable>s, and all the modules they
+ depend on. Here, each <replaceable>module</replaceable>
+ must be a module name or filename, but may not be the name
+ of a module in a package.</para>
+
+ <para>All previously loaded modules, except package modules,
+ are forgotten. The new set of modules is known as the
+ <firstterm>target set</firstterm>. Note that
+ <literal>:load</literal> can be used without any arguments
+ to unload all the currently loaded modules and
+ bindings.</para>
+
+ <para>After a <literal>:load</literal> command, the current
+ context is set to:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para><replaceable>module</replaceable>, if it was loaded
+ successfully, or</para>
+ </listitem>
+ <listitem>
+ <para>the most recently successfully loaded module, if
+ any other modules were loaded as a result of the current
+ <literal>:load</literal>, or</para>
+ </listitem>
+ <listitem>
+ <para><literal>Prelude</literal> otherwise.</para>
+ </listitem>
+ </itemizedlist>
</listitem>
</varlistentry>
<varlistentry>
- <term><literal>:module</literal> <replaceable>module</replaceable></term>
+ <term><literal>:module <optional>+|-</optional> <optional>*</optional><replaceable>mod<subscript>1</subscript></replaceable> ... <optional>*</optional><replaceable>mod<subscript>n</subscript></replaceable></literal></term>
<indexterm><primary><literal>:module</literal></primary></indexterm>
<listitem>
- <para>Sets the current context for statements typed at the
- prompt to <replaceable>module</replaceable>, which must be a
- module name which is already loaded or in a package. See
- <xref linkend="ghci-scope"> for more information on what
- effect the context has on what entities are in scope at the
- prompt.</para>
+ <para>Sets or modifies the current context for statements
+ typed at the prompt. See <xref linkend="ghci-scope"> for
+ more details.</para>
</listitem>
</varlistentry>
<term><literal>:reload</literal></term>
<indexterm><primary><literal>:reload</literal></primary></indexterm>
<listitem>
- <para>Attempts to reload the current target (see
- <literal>:load</literal>) if it, or any module it depends
- on, has changed. Note that this may entail loading new
- modules, or even dropping modules which are no longer
- indirectly required by the target.</para>
+ <para>Attempts to reload the current target set (see
+ <literal>:load</literal>) 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.</para>
</listitem>
</varlistentry>
</varlistentry>
<varlistentry>
+ <term><literal>:set</literal> <literal>args</literal>
+ <replaceable>arg</replaceable> ...</term>
+ <indexterm><primary><literal>:set</literal></primary></indexterm>
+ <listitem>
+ <para>Sets the list of arguments which are returned when the
+ program calls <literal>System.getArgs</literal><indexterm><primary>getArgs</primary>
+ </indexterm>.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>:set</literal> <literal>prog</literal>
+ <replaceable>prog</replaceable></term>
+ <indexterm><primary><literal>:set</literal></primary></indexterm>
+ <listitem>
+ <para>Sets the string to be returned when the program calls
+ <literal>System.getProgName</literal><indexterm><primary>getProgName</primary>
+ </indexterm>.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>:show bindings</literal></term>
+ <indexterm><primary><literal>:show bindings</literal></primary></indexterm>
+ <listitem>
+ <para>Show the bindings made at the prompt and their
+ types.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>:show modules</literal></term>
+ <indexterm><primary><literal>:show modules</literal></primary></indexterm>
+ <listitem>
+ <para>Show the list of modules currently load.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
<term><literal>:type</literal> <replaceable>expression</replaceable></term>
<indexterm><primary><literal>:type</literal></primary></indexterm>
<listitem>
‘<literal>+</literal>” and “command-line”
options, which begin with ‘-’. </para>
+ <para>NOTE: at the moment, the <literal>:set</literal> command
+ doesn't support any kind of quoting in its arguments: quotes will
+ not be removed and cannot be used to group words together. For
+ example, <literal>:set -DFOO='BAR BAZ'</literal> will not do what
+ you expect.</para>
+
<sect2>
<title>GHCi options</title>
<indexterm><primary>options</primary><secondary>GHCi</secondary>
</variablelist>
</sect2>
- <sect2>
+ <sect2 id="ghci-cmd-line-options">
<title>Setting GHC command-line options in GHCi</title>
<para>Normal GHC command-line options may also be set using
</sect2>
</sect1>
- <sect1>
+ <sect1 id="ghci-dot-files">
<title>The <filename>.ghci</filename> file</title>
<indexterm><primary><filename>.ghci</filename></primary><secondary>file</secondary>
</indexterm>
a static one, but in fact it works to set it using
<literal>:set</literal> like this. The changes won't take effect
until the next <literal>:load</literal>, though.)</para>
- </sect1>
- <sect1>
- <title>FAQ and Things To Watch Out For</title>
-
+ <para>Two command-line options control whether the
+ <filename>.ghci</filename> files are read:</para>
+
<variablelist>
<varlistentry>
- <term>GHCi complains about <function>main</function> not being
- in scope when I load a module.</term>
- <indexterm><primary><function>main</function></primary><secondary>with GHCi</secondary>
+ <term><option>-ignore-dot-ghci</option></term>
+ <indexterm><primary><option>-ignore-dot-ghci</option></primary>
</indexterm>
<listitem>
- <para>You probably omitted the <literal>module</literal>
- declaration at the top of the module, which causes the
- module name to default to <literal>Main</literal>. In
- Haskell, the <literal>Main</literal> module must define a
- function called <function>main</function>. Admittedly this
- doesn't make a great deal of sense for an interpreter, but
- the rule was kept for compatibility with GHC.</para>
+ <para>Don't read either <filename>./.ghci</filename> or
+ <filename>$HOME/.ghci</filename> when starting up.</para>
</listitem>
</varlistentry>
-
<varlistentry>
- <term><literal>System.exit</literal> causes GHCi to exit!</term>
- <indexterm><primary><literal>System.exit</literal></primary><secondary>in
- GHCi</secondary></indexterm>
+ <term><option>-read-dot-ghci</option></term>
+ <indexterm><primary><option>-read-dot-ghci</option></primary>
+ </indexterm>
<listitem>
- <para>Yes, it does.</para>
+ <para>Read <filename>.ghci</filename> and
+ <filename>$HOME/.ghci</filename>. This is normally the
+ default, but the <option>-read-dot-ghci</option> option may
+ be used to override a previous
+ <option>-ignore-dot-ghci</option> option.</para>
</listitem>
</varlistentry>
+ </variablelist>
- <varlistentry>
- <term><literal>System.getArgs</literal> returns GHCi's command
- line arguments!</term>
- <listitem>
- <para>Yes, it does.</para>
- </listitem>
- </varlistentry>
+ </sect1>
+ <sect1>
+ <title>FAQ and Things To Watch Out For</title>
+
+ <variablelist>
<varlistentry>
- <term>The interpreter can't load modules with FFI
+ <term>The interpreter can't load modules with foreign export
declarations!</term>
<listitem>
<para>Unfortunately not. We haven't implemented it yet.
</varlistentry>
<varlistentry>
- <term>Hugs has a <literal>:add</literal> command for adding
- modules without throwing away any that are already loaded.
- Why doesn't this work in GHCi?</term>
- <listitem>
- <para>We haven't implemented it yet. Sorry about that.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
<term><literal>-O</literal> doesn't work with GHCi!</term>
<indexterm><primary><option>-O</option></primary>
</indexterm>
properly with GHC's concurrency model.</para>
</listitem>
</varlistentry>
- </variablelist>
+ <varlistentry>
+ <term>After using <literal>getContents</literal>, I can't use
+ <literal>stdin</literal> again until I do
+ <literal>:load</literal> or <literal>:reload</literal>.</term>
+
+ <listitem>
+ <para>This is the defined behaviour of
+ <literal>getContents</literal>: it puts the stdin Handle in
+ a state known as <firstterm>semi-closed</firstterm>, wherein
+ any further I/O operations on it are forbidden. Because I/O
+ state is retained between computations, the semi-closed
+ state persists until the next <literal>:load</literal> or
+ <literal>:reload</literal> command.</para>
+
+ <para>You can make <literal>stdin</literal> reset itself
+ after every evaluation by giving GHCi the command
+ <literal>:set +r</literal>. This works because
+ <literal>stdin</literal> is just a top-level expression that
+ can be reverted to its unevaluated state in the same way as
+ any other top-level expression (CAF).</para>
+ </listitem>
+ </varlistentry>
+
+ </variablelist>
</sect1>
</chapter>