</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 <literal>foreign export</literal>, at the moment</para>
- </footnote>the language extensions that GHC provides.</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>
+ :kind <type> show the kind of <type>
+ :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>
indicate that the current context for expressions typed at the
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
+ linkend="ghci-scope"/>). So we can now type expressions involving
the functions from <filename>Main.hs</filename>:</para>
<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>
<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
+ 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="options-finding-imports">.</para> </footnote></para>
+ 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
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>
-
- <para>One final note: if you load a module called Main, it must
- contain a <literal>main</literal> function, just like in
- GHC.</para>
</sect2>
<sect2>
doing its best to avoid actually recompiling modules if their
external dependencies haven't changed. This is the same
mechanism we use to avoid re-compiling modules in the batch
- compilation setting (see <xref linkend="recomp">).</para>
+ compilation setting (see <xref linkend="recomp"/>).</para>
</sect2>
</sect1>
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
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>
+ and A imports both B & C:</para>
<screen>
A
/ \
<para>Here's an example:</para>
<screen>
-Prelude> x <- return 42
+Prelude> x <- return 42
Prelude> print x
42
Prelude>
</screen>
- <para>The statement <literal>x <- return 42</literal> means
+ <para>The statement <literal>x <- return 42</literal> means
“execute <literal>return 42</literal> in the
<literal>IO</literal> monad, and bind the result to
<literal>x</literal>”. We can then use
Prelude>
</screen>
<para>An important difference between the two types of binding
- is that the monadic bind (<literal>p <- e</literal>) is
+ is that the monadic bind (<literal>p <- e</literal>) is
<emphasis>strict</emphasis> (it evaluates <literal>e</literal>),
whereas with the <literal>let</literal> form, the expression
isn't evaluated immediately:</para>
</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
<para>The corresponding translation for an IO-typed
<replaceable>e</replaceable> is
<screen>
- it <- <replaceable>e</replaceable>
+ it <- <replaceable>e</replaceable>
</screen>
</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 id="ghci-invokation">
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
+ 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>
<para>Most of the command-line options accepted by GHC (see <xref
- linkend="using-ghc">) also make sense in interactive mode. The ones
+ linkend="using-ghc"/>) also make sense in interactive mode. The ones
that don't make sense are mostly obvious; for example, GHCi
doesn't generate interface files, so options related to interface
file generation won't have any effect.</para>
<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
(<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>
+
+ <para>Ordering of <option>-l</option> options matters: a library
+ should be mentioned <emphasis>before</emphasis> the libraries it
+ depends on (see <xref linkend="options-linker"/>).</para>
</sect2>
</sect1>
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>
<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>
+ outputs the current date & time:</para>
<screen>
Prelude> let date _ = Time.getClockTime >>= print >> return ""
<para>All previously loaded modules, except package modules,
are forgotten. The new set of modules is known as the
- <firstterm>target set</firstterm>.</para>
+ <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>
<indexterm><primary><literal>:module</literal></primary></indexterm>
<listitem>
<para>Sets or modifies the current context for statements
- typed at the prompt. See <xref linkend="ghci-scope"> for
+ typed at the prompt. See <xref linkend="ghci-scope"/> for
more details.</para>
</listitem>
</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">
+ <para>Sets various options. See <xref linkend="ghci-set"/>
for a list of available options. The
<literal>:set</literal> command by itself shows which
options are currently set.</para>
</varlistentry>
<varlistentry>
+ <term><literal>:kind</literal> <replaceable>type</replaceable></term>
+ <indexterm><primary><literal>:kind</literal></primary></indexterm>
+ <listitem>
+ <para>Infers and prints the kind of
+ <replaceable>type</replaceable>. The latter can be an arbitrary
+ type expression, including a partial application of a type constructor,
+ such as <literal>Either Int</literal>.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
<term><literal>:undef</literal> <replaceable>name</replaceable></term>
<indexterm><primary><literal>:undef</literal></primary></indexterm>
<listitem>
<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">
+ <para>Unsets certain options. See <xref linkend="ghci-set"/>
for a list of available options.</para>
</listitem>
</varlistentry>
<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
+ 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>
Prelude> :set -fno-glasgow-exts
</screen>
- <para><xref linkend="flag-reference"> lists the reverse for each
+ <para><xref linkend="flag-reference"/> lists the reverse for each
option where applicable.</para>
<para>Certain static options (<option>-package</option>,
<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>The interpreter can't load modules with foreign export
declarations!</term>
<listitem>
projects / ghc-hetmet.git / blobdiff