<screen>
$ ghci
-GHCi, version 6.8.1: http://www.haskell.org/ghc/ :? for help
+GHCi, version 6.12.1: http://www.haskell.org/ghc/ :? for help
+Loading package ghc-prim ... linking ... done.
+Loading package integer-gmp ... linking ... done.
Loading package base ... linking ... done.
+Loading package ffi-1.0 ... linking ... done.
Prelude>
</screen>
</screen>
<para>GHCi interprets the whole line as an expression to evaluate.
- The expression may not span several lines - as soon as you press
- enter, GHCi will attempt to evaluate it.</para>
+ The expression may not span several lines - as soon as you press enter,
+ GHCi will attempt to evaluate it.</para>
+
+ <para>GHCi also has a multiline mode,
+ <indexterm><primary><literal>:set +m</literal></primary></indexterm>,
+ which is terminated by an empty line:</para>
+
+<screen>
+Prelude> :set +m
+Prelude> let x = 42 in x / 9
+Prelude|
+4.666666666666667
+Prelude>
+</screen>
+
+ <para>In Haskell, a <literal>let</literal> expression is followed
+ by <literal>in</literal>. However, in GHCi, since the expression
+ can also be interpreted in the <literal>IO</literal> monad,
+ a <literal>let</literal> binding with no accompanying
+ <literal>in</literal> statement can be signalled by an empty line,
+ as in the above example.</para>
+
+ <para>Multiline mode is useful when entering monadic
+ <literal>do</literal> statements:</para>
+
+<screen>
+Control.Monad.State> flip evalStateT 0 $ do
+Control.Monad.State| i <- get
+Control.Monad.State| lift $ do
+Control.Monad.State| putStrLn "Hello World!"
+Control.Monad.State| print i
+Control.Monad.State|
+"Hello World!"
+0
+Control.Monad.State>
+</screen>
+
+ <para>During a multiline interaction, the user can interrupt and
+ return to the top-level prompt.</para>
+
+<screen>
+Prelude> do
+Prelude| putStrLn "Hello, World!"
+Prelude| ^C
+Prelude>
+</screen>
</sect1>
<sect1 id="loading-source-files">
very often, and use the interpreter for the code being actively
developed.</para>
- <para>When loading up source files with <literal>:load</literal>,
- GHCi looks for any corresponding compiled object files, and will
- use one in preference to interpreting the source if possible. For
- example, suppose we have a 4-module program consisting of modules
- A, B, C, and D. Modules B and C both import D only,
- and A imports both B & C:</para>
+ <para>When loading up source modules with <literal>:load</literal>,
+ GHCi normally looks for any corresponding compiled object files,
+ and will use one in preference to interpreting the source if
+ possible. For example, suppose we have a 4-module program
+ consisting of modules A, B, C, and D. Modules B and C both import
+ D only, and A imports both B & C:</para>
<screen>
A
/ \
Ok, modules loaded: A, B, C, D.
</screen>
+ <para>The automatic loading of object files can sometimes lead to
+ confusion, because non-exported top-level definitions of a module
+ are only available for use in expressions at the prompt when the
+ module is interpreted (see <xref linkend="ghci-scope" />). For
+ this reason, you might sometimes want to force GHCi to load a
+ module using the interpreter. This can be done by prefixing
+ a <literal>*</literal> to the module name or filename when
+ using <literal>:load</literal>, for example</para>
+
+<screen>
+Prelude> :load *A
+Compiling A ( A.hs, interpreted )
+*A>
+</screen>
+
+<para>When the <literal>*</literal> is used, GHCi ignores any
+ pre-compiled object code and interprets the module. If you have
+ already loaded a number of modules as object code and decide that
+ you wanted to interpret one of them, instead of re-loading the whole
+ set you can use <literal>:add *M</literal> to specify that you want
+ <literal>M</literal> to be interpreted (note that this might cause
+ other modules to be interpreted too, because compiled modules cannot
+ depend on interpreted ones).</para>
+
+<para>To always compile everything to object code and never use the
+ interpreter, use the <literal>-fobject-code</literal> option (see
+ <xref linkend="ghci-obj" />).</para>
+
<para>HINT: since GHCi will only use a compiled object file if it
can be sure that the compiled version is up-to-date, a good technique
when working on a large program is to occasionally run
interpreter. As you modify code, the changed modules will be
interpreted, but the rest of the project will remain
compiled.</para>
-
</sect1>
<sect1 id="interactive-evaluation">
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>
+ that is in effect at the prompt.</para>
+
+ <para>NOTE: for technical reasons, GHCi can only support the
+ <literal>*</literal>-form for modules that are interpreted.
+ Compiled modules and package modules can only contribute their
+ exports to the current scope. To ensure that GHCi loads the
+ interpreted version of a module, add the <literal>*</literal>
+ when loading the module, e.g. <literal>:load *M</literal>.</para>
<para>The scope is manipulated using the
<literal>:module</literal> command. For example, if the current
Prelude IO>
</screen>
- <para>(Note: you can use <literal>import M</literal> as an
- alternative to <literal>:module +M</literal>, and
+ <para>(Note: you can use conventional
+ haskell <literal>import</literal> syntax as
+ well, but this does not support
+ <literal>*</literal> forms).
<literal>:module</literal> can also be shortened to
- <literal>:m</literal>). The full syntax of the
+ <literal>:m</literal>. The full syntax of the
<literal>:module</literal> command is:</para>
<screen>
</para>
<sect3>
+ <title><literal>:module</literal> and
+ <literal>:load</literal></title>
+
+ <para>It might seem that <literal>:module</literal> and
+ <literal>:load</literal> do similar things: you can use both
+ to bring a module into scope. However, there is a clear
+ difference. GHCi is concerned with two sets of modules:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>The set of modules that are
+ currently <emphasis>loaded</emphasis>. This set is
+ modified
+ by <literal>:load</literal>, <literal>:add</literal>
+ and <literal>:reload</literal>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>The set of modules that are currently <emphasis>in
+ scope</emphasis> at the prompt. This set is modified
+ by <literal>:module</literal>, and it is also set
+ automatically
+ after <literal>:load</literal>, <literal>:add</literal>,
+ and <literal>:reload</literal>.</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>You cannot add a module to the scope if it is not
+ loaded. This is why trying to
+ use <literal>:module</literal> to load a new module results
+ in the message “<literal>module M is not
+ loaded</literal>”.</para>
+ </sect3>
+
+ <sect3 id="ghci-import-qualified">
<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>
+ package, and every module currently loaded into GHCi. This
+ behaviour can be disabled with the flag <option>-fno-implicit-import-qualified</option><indexterm><primary><option>-fno-implicit-import-qualified</option></primary></indexterm>.</para>
</sect3>
<sect3>
- <title>The <literal>:main</literal> command</title>
+ <title>The <literal>:main</literal> and <literal>:run</literal> commands</title>
<para>
When a program is compiled and executed, it can use the
["foo","bar"]
</screen>
+ <para>
+ We can also quote arguments which contains characters like
+ spaces, and they are treated like Haskell strings, or we can
+ just use Haskell list syntax:
+ </para>
+
+<screen>
+Prelude> :main foo "bar baz"
+["foo","bar baz"]
+Prelude> :main ["foo", "bar baz"]
+["foo","bar baz"]
+</screen>
+
+ <para>
+ Finally, other functions can be called, either with the
+ <literal>-main-is</literal> flag or the <literal>:run</literal>
+ command:
+ </para>
+
+<screen>
+Prelude> let foo = putStrLn "foo" >> System.Environment.getArgs >>= print
+Prelude> let bar = putStrLn "bar" >> System.Environment.getArgs >>= print
+Prelude> :set -main-is foo
+Prelude> :main foo "bar baz"
+foo
+["foo","bar baz"]
+Prelude> :run bar ["foo", "bar baz"]
+bar
+["foo","bar baz"]
+</screen>
+
</sect3>
</sect2>
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
+ (which is what GHCi computes here) has type <literal>Show a => String</literal> and how that displays depends
on the type <literal>a</literal>. For example:
<programlisting>
- ghci> (reverse []) :: String
+ ghci> reverse ([] :: String)
""
- ghci> (reverse []) :: [Int]
+ 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. The
+ rules (Section 4.3.4 of the Haskell 2010 Report) as follows. The
standard rules take each group of constraints <literal>(C1 a, C2 a, ..., Cn
a)</literal> for each type variable <literal>a</literal>, and defaults the
type variable if
<para>GHCi contains a simple imperative-style debugger in which you can
stop a running computation in order to examine the values of
variables. The debugger is integrated into GHCi, and is turned on by
- default: no flags are required to enable the debugging facilities. There
- is one major restriction: breakpoints and single-stepping are only
- available in <emphasis>interpreted</emphasis> modules; compiled code is
- invisible to the debugger.</para>
+ default: no flags are required to enable the debugging
+ facilities. There is one major restriction: breakpoints and
+ single-stepping are only available in interpreted modules;
+ compiled code is invisible to the debugger<footnote><para>Note that packages
+ only contain compiled code, so debugging a package requires
+ finding its source and loading that directly.</para></footnote>.</para>
<para>The debugger provides the following:
<itemizedlist>
</para>
<para>There is currently no support for obtaining a “stack
- trace”, but the tracing and history features provide a useful
- second-best, which will often be enough to establish the context of an
- error.</para>
+ trace”, but the tracing and history features provide a
+ useful second-best, which will often be enough to establish the
+ context of an error. For instance, it is possible to break
+ automatically when an exception is thrown, even if it is thrown
+ from within compiled code (see <xref
+ linkend="ghci-debugger-exceptions" />).</para>
<sect2 id="breakpoints">
<title>Breakpoints and inspecting variables</title>
<screen>
*Main> :set -fbreak-on-exception
*Main> :trace qsort ("abc" ++ undefined)
-"Stopped at <exception thrown>
+“Stopped at <exception thrown>
_exception :: e
[<exception thrown>] *Main> :hist
-1 : qsort.hs:3:24-38
<varlistentry>
<term>
- <literal>:add</literal> <replaceable>module</replaceable> ...
+ <literal>:add</literal> <optional><literal>*</literal></optional><replaceable>module</replaceable> ...
<indexterm><primary><literal>:add</literal></primary></indexterm>
</term>
<listitem>
<para>Add <replaceable>module</replaceable>(s) to the
current <firstterm>target set</firstterm>, and perform a
- reload.</para>
+ reload. Normally pre-compiled code for the module will be
+ loaded if available, or otherwise the module will be
+ compiled to byte-code. Using the <literal>*</literal>
+ prefix forces the module to be loaded as byte-code.</para>
</listitem>
</varlistentry>
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.</para>
- <para>See also <xref linkend="hasktags" />.</para>
- </listitem>
+ </listitem>
</varlistentry>
<varlistentry>
</varlistentry>
<varlistentry>
+ <term>
+ <literal>:</literal>
+ <indexterm><primary><literal>:</literal></primary></indexterm>
+ </term>
+ <listitem>
+ <para>Repeat the previous command.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+
<term>
<literal>:history [<replaceable>num</replaceable>]</literal>
<indexterm><primary><literal>:history</literal></primary></indexterm>
<varlistentry>
<term>
- <literal>:load</literal> <replaceable>module</replaceable> ...
+ <literal>:load</literal> <optional><literal>*</literal></optional><replaceable>module</replaceable> ...
<indexterm><primary><literal>:load</literal></primary></indexterm>
</term>
<listitem>
to unload all the currently loaded modules and
bindings.</para>
+ <para>Normally pre-compiled code for a module will be loaded
+ if available, or otherwise the module will be compiled to
+ byte-code. Using the <literal>*</literal> prefix forces a
+ module to be loaded as byte-code.</para>
+
<para>After a <literal>:load</literal> command, the current
context is set to:</para>
["foo","bar"]
</screen>
+ <para>
+ We can also quote arguments which contains characters like
+ spaces, and they are treated like Haskell strings, or we can
+ just use Haskell list syntax:
+ </para>
+
+<screen>
+Prelude> :main foo "bar baz"
+["foo","bar baz"]
+Prelude> :main ["foo", "bar baz"]
+["foo","bar baz"]
+</screen>
+
+ <para>
+ Finally, other functions can be called, either with the
+ <literal>-main-is</literal> flag or the <literal>:run</literal>
+ command:
+ </para>
+
+<screen>
+Prelude> let foo = putStrLn "foo" >> System.Environment.getArgs >>= print
+Prelude> let bar = putStrLn "bar" >> System.Environment.getArgs >>= print
+Prelude> :set -main-is foo
+Prelude> :main foo "bar baz"
+foo
+["foo","bar baz"]
+Prelude> :run bar ["foo", "bar baz"]
+bar
+["foo","bar baz"]
+</screen>
+
</listitem>
</varlistentry>
<varlistentry>
<term>
+ <literal>:run</literal>
+ <indexterm><primary><literal>:run</literal></primary></indexterm>
+ </term>
+ <listitem>
+ <para>See <literal>:main</literal>.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ <literal>:script</literal> <optional><replaceable>n</replaceable></optional>
+ <literal>filename</literal>
+ <indexterm><primary><literal>:script</literal></primary></indexterm>
+ </term>
+ <listitem>
+ <para>Executes the lines of a file as a series of GHCi commands. This command
+ is compatible with multiline statements as set by <literal>:set +m</literal>
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
<literal>:set</literal> <optional><replaceable>option</replaceable>...</optional>
<indexterm><primary><literal>:set</literal></primary></indexterm>
</term>
Inside <replaceable>prompt</replaceable>, the sequence
<literal>%s</literal> is replaced by the names of the
modules currently in scope, and <literal>%%</literal> is
- replaced by <literal>%</literal>.</para>
+ replaced by <literal>%</literal>. If <replaceable>prompt</replaceable>
+ starts with " then it is parsed as a Haskell String;
+ otherwise it is treated as a literal string.</para>
</listitem>
</varlistentry>
<variablelist>
<varlistentry>
<term>
+ <literal>+m</literal>
+ <indexterm><primary><literal>+m</literal></primary></indexterm>
+ </term>
+ <listitem>
+ <para>Enable parsing of multiline commands. A multiline command
+ is prompted for when the current input line contains open layout
+ contexts.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
<literal>+r</literal>
<indexterm><primary><literal>+r</literal></primary></indexterm>
<indexterm><primary>CAFs</primary><secondary>in GHCi</secondary></indexterm>
</indexterm>
<para>When it starts, unless the <literal>-ignore-dot-ghci</literal>
- flag is given, GHCi reads and executes commands from
- <filename>./.ghci</filename>, followed by
- <filename>$HOME/.ghci</filename>.</para>
-
- <para>The <filename>.ghci</filename> in your home directory is
- most useful for turning on favourite options (eg. <literal>:set
- +s</literal>), and defining useful macros. Placing a
- <filename>.ghci</filename> file in a directory with a Haskell
- project is a useful way to set certain project-wide options so you
- don't have to type them everytime you start GHCi: eg. if your
- project uses GHC extensions and CPP, and has source files in three
- subdirectories A, B and C, you might put the following lines in
+ flag is given, GHCi reads and executes commands from the following
+ files, in this order, if they exist:</para>
+
+ <orderedlist>
+ <listitem>
+ <para><filename>./.ghci</filename></para>
+ </listitem>
+ <listitem>
+ <para><literal><replaceable>appdata</replaceable>/ghc/ghci.conf</literal>,
+ where <replaceable>appdata</replaceable> depends on your system,
+ but is usually something like <literal>C:/Documents and Settings/<replaceable>user</replaceable>/Application Data</literal></para>
+ </listitem>
+ <listitem>
+ <para>On Unix: <literal>$HOME/.ghc/ghci.conf</literal></para>
+ </listitem>
+ <listitem>
+ <para><literal>$HOME/.ghci</literal></para>
+ </listitem>
+ </orderedlist>
+
+ <para>The <filename>ghci.conf</filename> file is most useful for
+ turning on favourite options (eg. <literal>:set +s</literal>), and
+ defining useful macros. Placing a <filename>.ghci</filename> file
+ in a directory with a Haskell project is a useful way to set
+ certain project-wide options so you don't have to type them
+ everytime you start GHCi: eg. if your project uses GHC extensions
+ and CPP, and has source files in three subdirectories A, B and C,
+ you might put the following lines in
<filename>.ghci</filename>:</para>
<screen>
<literal>:set</literal> like this. The changes won't take effect
until the next <literal>:load</literal>, though.)</para>
+ <para>Once you have a library of GHCi macros, you may want
+ to source them from separate files, or you may want to source
+ your <filename>.ghci</filename> file into your running GHCi
+ session while debugging it</para>
+
+<screen>
+:def source readFile
+</screen>
+
+ <para>With this macro defined in your <filename>.ghci</filename>
+ file, you can use <literal>:source file</literal> to read GHCi
+ commands from <literal>file</literal>. You can find (and contribute!-)
+ other suggestions for <filename>.ghci</filename> files on this Haskell
+ wiki page: <ulink
+ url="http://haskell.org/haskellwiki/GHC/GHCi">GHC/GHCi</ulink></para>
+
<para>Two command-line options control whether the
- <filename>.ghci</filename> files are read:</para>
+ startup files files are read:</para>
<variablelist>
<varlistentry>
<indexterm><primary><option>-ignore-dot-ghci</option></primary></indexterm>
</term>
<listitem>
- <para>Don't read either <filename>./.ghci</filename> or
- <filename>$HOME/.ghci</filename> when starting up.</para>
+ <para>Don't read either <filename>./.ghci</filename> or the
+ other startup files when starting up.</para>
</listitem>
</varlistentry>
<varlistentry>
<indexterm><primary><option>-read-dot-ghci</option></primary></indexterm>
</term>
<listitem>
- <para>Read <filename>.ghci</filename> and
- <filename>$HOME/.ghci</filename>. This is normally the
+ <para>Read <filename>./.ghci</filename> and the other
+ startup files (see above). 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>
because this is normally what you want in an interpreter:
output appears as it is generated.
</para>
+ <para>
+ If you want line-buffered behaviour, as in GHC, you can
+ start your program thus:
+ <programlisting>
+ main = do { hSetBuffering stdout LineBuffering; ... }
+ </programlisting>
+ </para>
</listitem>
</varlistentry>
</variablelist>
<!-- Emacs stuff:
;;; Local Variables: ***
- ;;; mode: xml ***
;;; sgml-parent-document: ("users_guide.xml" "book" "chapter") ***
;;; End: ***
-->