<chapter id="ghci">
<title>Using GHCi</title>
<indexterm><primary>GHCi</primary></indexterm>
- <indexterm><primary>interpreter</primary></indexterm>
+ <indexterm><primary>interpreter</primary><see>GHCi</see></indexterm>
+ <indexterm><primary>interactive</primary><see>GHCi</see></indexterm>
<para>GHCi<footnote>
<para>The ‘i’ stands for “Interactive”</para>
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>
+ <indexterm><primary>FFI</primary><secondary>GHCi support</secondary></indexterm>
+ <indexterm><primary>Foreign Function Interface</primary><secondary>GHCi support</secondary></indexterm>
<sect1>
<title>Introduction to GHCi</title>
$ ghci
___ ___ _
/ _ \ /\ /\/ __(_)
- / /_\// /_/ / / | | GHC Interactive, version 4.11, For Haskell 98.
+ / /_\// /_/ / / | | GHC Interactive, version 5.00, For Haskell 98.
/ /_\\/ __ / /___| | http://www.haskell.org/ghc/
\____/\/ /_/\____/|_| Type :? for help.
<screen>
Prelude> 1+2
3
-PrePrelude> let x = 42 in x / 9
+Prelude> let x = 42 in x / 9
4.666666666666667
Prelude>
</screen>
<para>To load a Haskell source file into GHCi, use the
<literal>:load</literal> command:</para>
+ <indexterm><primary><literal>:load</literal></primary></indexterm>
<screen>
Prelude> :load Main
<sect2>
<title>Modules vs. filenames</title>
+ <indexterm><primary>modules</primary><secondary>and filenames</secondary></indexterm>
+ <indexterm><primary>filenames</primary><secondary>of modules</secondary></indexterm>
<para>Question: How does GHC find the filename which contains
module <replaceable>M</replaceable>? Answer: it looks for the
<sect2>
<title>Making changes and recompilation</title>
+ <indexterm><primary><literal>:reload</literal></primary></indexterm>
<para>If you make some changes to the source code and want GHCi
to recompile the program, give the <literal>:reload</literal>
<sect1 id="ghci-compiled">
<title>Loading compiled code</title>
+ <indexterm><primary>compiled code</primary><secondary>in GHCi</secondary></indexterm>
<para>When you load a Haskell source module into GHCi, it is
normally converted to byte-code and run using the interpreter.
<para>What actually happens is that GHCi typechecks the
expression, and if it doesn't have an <literal>IO</literal> type,
then it transforms it as follows: an expression
- <replaceable>e</replaceable> turns into <literal>let it =
- <replaceable>e</replaceable> in print it</literal>. It then runs
- the new expression as an IO-action.</para>
+ <replaceable>e</replaceable> turns into
+<screen>
+ let it = <replaceable>e</replaceable>;
+ print it
+</screen>
+ which is then run as an IO-action.</para>
- <para>Hence the original expression must have a type which is an
+ <para>Hence, the original expression must have a type which is an
instance of the <literal>Show</literal> class, or GHCi will
complain:</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. This is the default context
- when you start up GHCi.</para>
+ <literal>Prelude</literal> module. The Prelude is the default
+ context when you start up GHCi.</para>
<indexterm><primary><literal>Prelude</literal></primary></indexterm>
<para>Exactly which entities are in scope in a given context
<sect2>
<title>Using <literal>do-</literal>notation at the prompt</title>
+ <indexterm><primary>do-notation</primary><secondary>in GHCi</secondary></indexterm>
+ <indexterm><primary>statements</primary><secondary>in GHCi</secondary></indexterm>
<para>GHCi actually accepts <firstterm>statements</firstterm>
rather than just expressions at the prompt. This means you can
<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>
+ <indexterm><primary><literal>+t</literal></primary></indexterm>
<screen>
Prelude> :set +t
Prelude> let (x:xs) = [1..]
6
</screen>
+ <para>This is a result of the translation mentioned earlier,
+ namely that an expression <replaceable>e</replaceable> is
+ translated to
+<screen>
+ let it = <replaceable>e</replaceable>;
+ print it
+</screen>
+ before execution, resulting in a binding for
+ <literal>it</literal>.</para>
+
<para>If the expression was of type <literal>IO a</literal> for
some <literal>a</literal>, then <literal>it</literal> will be
bound to the result of the <literal>IO</literal> computation,
Wed Mar 14 12:23:13 GMT 2001
</screen>
+ <para>The corresponding translation for an IO-typed
+ <replaceable>e</replaceable> is
+<screen>
+ it <- <replaceable>e</replaceable>
+</screen>
+ </para>
+
<para>Note that <literal>it</literal> is shadowed by the new
value each time you evaluate a new expression, and the old value
of <literal>it</literal> is lost.</para>
<sect1>
<title>Invoking GHCi</title>
+ <indexterm><primary>invoking</primary><secondary>GHCi</secondary></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
+ 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>
<sect2>
<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,
but note: packages <emphasis>must</emphasis> be specified on the
$ ghci -package text
___ ___ _
/ _ \ /\ /\/ __(_)
- / /_\// /_/ / / | | GHC Interactive, version 4.11, For Haskell 98.
+ / /_\// /_/ / / | | GHC Interactive, version 5.00, For Haskell 98.
/ /_\\/ __ / /___| | http://www.haskell.org/ghc/
\____/\/ /_/\____/|_| Type :? for help.
<sect2>
<title>Extra libraries</title>
+ <indexterm><primary>libraries</primary><secondary>with GHCi</secondary></indexterm>
<para>Extra libraries may be specified on the command line using
the normal <literal>-l<replaceable>lib</replaceable></literal>
<variablelist>
<varlistentry>
<term><literal>:cd</literal> <replaceable>dir</replaceable></term>
+ <indexterm><primary><literal>:cd</literal></primary></indexterm>
<listitem>
<para>Changes the current working directory to
<replaceable>dir</replaceable>. A
</varlistentry>
<varlistentry>
- <term><literal>:def</literal></term>
+ <term><literal>:def</literal> <replaceable>name</replaceable> <replaceable>expr</replaceable></term>
+ <indexterm><primary><literal>:def</literal></primary></indexterm>
<listitem>
- <para>ToDo.</para>
+ <para>The command <literal>:def</literal>
+ <replaceable>name</replaceable>
+ <replaceable>expr</replaceable> defines a new GHCi command
+ <literal>:<replaceable>name</replaceable></literal>,
+ implemented by the Haskell expression
+ <replaceable>expr</replaceable>, which must have type
+ <literal>String -> IO String</literal>. When
+ <literal>:<replaceable>name</replaceable>
+ <replaceable>args</replaceable></literal> is typed at the
+ prompt, GHCi will run the expression
+ <literal>(<replaceable>name</replaceable>
+ <replaceable>args</replaceable>)</literal>, take the
+ resulting <literal>String</literal>, and feed it back into
+ GHCi as a new sequence of commands. Separate commands in
+ the result must be separated by
+ ‘<literal>\n</literal>’.</para>
+
+ <para>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:</para>
+
+<screen>
+Prelude> let date _ = Time.getClockTime >>= print >> return ""
+Prelude> :def date date
+Prelude> :date
+Fri Mar 23 15:16:40 GMT 2001
+</screen>
+
+ <para>Here's an example of a command that takes an argument.
+ It's a re-implementation of <literal>:cd</literal>:</para>
+
+<screen>
+Prelude> let mycd d = Directory.setCurrentDirectory d >> return ""
+Prelude> :def mycd mycd
+Prelude> :mycd ..
+</screen>
+
+ <para>Or I could define a simple way to invoke
+ “<literal>ghc --make Main</literal>” in the
+ current directory:</para>
+
+<screen>
+Prelude> :def make (\_ -> return ":! ghc --make Main")
+</screen>
+
</listitem>
</varlistentry>
<varlistentry>
<term><literal>:help</literal></term>
+ <indexterm><primary><literal>:help</literal></primary></indexterm>
<term><literal>:?</literal></term>
+ <indexterm><primary><literal>:?</literal></primary></indexterm>
<listitem>
<para>Displays a list of the available commands.</para>
</listitem>
<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
<varlistentry>
<term><literal>:module</literal> <replaceable>module</replaceable></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
</varlistentry>
<varlistentry>
- <term><literal>:quit</literal> <replaceable>module</replaceable></term>
+ <term><literal>:quit</literal></term>
+ <indexterm><primary><literal>:quit</literal></primary></indexterm>
<listitem>
<para>Quits GHCi. You can also quit by typing a control-D
at the prompt.</para>
<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
<varlistentry>
<term><literal>:set</literal> <optional><replaceable>option</replaceable>...</optional></term>
+ <indexterm><primary><literal>:set</literal></primary></indexterm>
<listitem>
<para>Sets various options. See <xref linkend="ghci-set">
for a list of available options. The
<varlistentry>
<term><literal>:type</literal> <replaceable>expression</replaceable></term>
+ <indexterm><primary><literal>:type</literal></primary></indexterm>
<listitem>
<para>Infers and prints the type of
<replaceable>expression</replaceable>, including explicit
</varlistentry>
<varlistentry>
+ <term><literal>:undef</literal> <replaceable>name</replaceable></term>
+ <indexterm><primary><literal>:undef</literal></primary></indexterm>
+ <listitem>
+ <para>Undefines the user-defined command
+ <replaceable>name</replaceable> (see <literal>:def</literal>
+ above).</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
<term><literal>:unset</literal> <replaceable>option</replaceable>...</term>
+ <indexterm><primary><literal>:unset</literal></primary></indexterm>
<listitem>
<para>Unsets certain options. See <xref linkend="ghci-set">
for a list of available options.</para>
<varlistentry>
<term><literal>:!</literal> <replaceable>command</replaceable>...</term>
+ <indexterm><primary><literal>:!</literal></primary></indexterm>
+ <indexterm><primary>shell commands</primary><secondary>in GHCi</secondary></indexterm>
<listitem>
<para>Executes the shell command
<replaceable>command</replaceable>.</para>
<sect1 id="ghci-set">
<title>The <literal>:set</literal> command</title>
+ <indexterm><primary><literal>:set</literal></primary></indexterm>
<para>The <literal>:set</literal> command sets two types of
options: GHCi options, which begin with
‘<literal>+</literal>” and “command-line”
- options, which begin with ‘-’. Either type of option
- may be set using <literal>:set</literal> and unset using
- <literal>:unset</literal>.</para>
+ options, which begin with ‘-’. </para>
- <para>The available GHCi options are:</para>
+ <sect2>
+ <title>GHCi options</title>
+ <indexterm><primary>options</primary><secondary>GHCi</secondary>
+ </indexterm>
- <variablelist>
- <varlistentry>
- <term><literal>+r</literal></term>
- <listitem>
- <para>Normally, any evaluation of top-level expressions
- (otherwise known as CAFs or Constant Applicative Forms) in
- loaded modules is retained between evaluations. Turning on
- <literal>+r</literal> causes all evaluation of top-level
- expressions to be discarded after each evaluation (they are
- still retained <emphasis>during</emphasis> a single
- evaluation).</para>
+ <para>GHCi options may be set using <literal>:set</literal> and
+ unset using <literal>:unset</literal>.</para>
+
+ <para>The available GHCi options are:</para>
+
+ <variablelist>
+ <varlistentry>
+ <term><literal>+r</literal></term>
+ <indexterm><primary><literal>+r</literal></primary></indexterm>
+ <indexterm><primary>CAFs</primary><secondary>in GHCi</secondary></indexterm>
+ <indexterm><primary>Constant Applicative Form</primary><see>CAFs</see></indexterm>
+ <listitem>
+ <para>Normally, any evaluation of top-level expressions
+ (otherwise known as CAFs or Constant Applicative Forms) in
+ loaded modules is retained between evaluations. Turning
+ on <literal>+r</literal> causes all evaluation of
+ top-level expressions to be discarded after each
+ evaluation (they are still retained
+ <emphasis>during</emphasis> a single evaluation).</para>
- <para>This option may help if the evaluated top-level
- expressions are consuming large amounts of space, or if you
- need repeatable performance measurements.</para>
- </listitem>
- </varlistentry>
+ <para>This option may help if the evaluated top-level
+ expressions are consuming large amounts of space, or if
+ you need repeatable performance measurements.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>+s</literal></term>
+ <indexterm><primary><literal>+s</literal></primary></indexterm>
+ <listitem>
+ <para>Display some stats after evaluating each expression,
+ including the elapsed time and number of bytes allocated.
+ NOTE: the allocation figure is only accurate to the size
+ of the storage manager's allocation area, because it is
+ calculated at every GC. Hence, you might see values of
+ zero if no GC has occurred.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>+t</literal></term>
+ <indexterm><primary><literal>+t</literal></primary></indexterm>
+ <listitem>
+ <para>Display the type of each variable bound after a
+ statement is entered at the prompt. If the statement is a
+ single expression, then the only variable binding will be
+ for the variable
+ ‘<literal>it</literal>’.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </sect2>
- <varlistentry>
- <term><literal>+s</literal></term>
- <listitem>
- <para>Display some stats after evaluating each expression,
- including the elapsed time and number of bytes allocated.
- NOTE: the allocation figure is only accurate to the size of
- the storage manager's allocation area, because it is
- calculated at every GC. Hence, you might see values of zero
- if no GC has occurred.</para>
- </listitem>
- </varlistentry>
+ <sect2>
+ <title>Setting GHC command-line options in GHCi</title>
- <varlistentry>
- <term><literal>+t</literal></term>
- <listitem>
- <para>Display the type of each variable bound after a
- statement is entered at the prompt. If the statement is a
- single expression, then the only variable binding will be
- for the variable ‘<literal>it</literal>’.</para>
- </listitem>
- </varlistentry>
- </variablelist>
+ <para>Normal GHC command-line options may also be set using
+ <literal>:set</literal>. For example, to turn on
+ <option>-fglasgow-exts</option>, you would say:</para>
- <para>In addition, any normal GHC command-line option that is
- designated as <firstterm>dynamic</firstterm> (see the table in
- <xref linkend="flag-reference">), may be set using
- <literal>:set</literal>. Certain static options
- (<option>-I</option>, <option>-i</option>, and <option>-l</option>
- in particular) will also work, but may not take effect until the
- next reload.</para>
+<screen>
+Prelude> :set -fglasgow-exts
+</screen>
+
+ <para>Any GHC command-line option that is designated as
+ <firstterm>dynamic</firstterm> (see the table in <xref
+ linkend="flag-reference">), may be set using
+ <literal>:set</literal>. To unset an option, you can set the
+ reverse option:</para>
+ <indexterm><primary>dynamic</primary><secondary>options</secondary></indexterm>
+
+<screen>
+Prelude> :set -fno-glasgow-exts
+</screen>
+
+ <para><xref linkend="flag-reference"> lists the reverse for each
+ option where applicable.</para>
+
+ <para>Certain static options (<option>-I</option>,
+ <option>-i</option>, and <option>-l</option> in particular) will
+ also work, but may not take effect until the next reload.</para>
+ <indexterm><primary>static</primary><secondary>options</secondary></indexterm>
+ </sect2>
</sect1>
<sect1>
<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>
+ </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>
+ </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>
<listitem>
<para>Yes, it does.</para>
</listitem>
projects / ghc-hetmet.git / blobdiff