[project @ 2003-07-21 15:24:42 by simonmar]

[ghc-hetmet.git] / ghc / docs / users_guide / ghci.sgml

diff --git a/ghc/docs/users_guide/ghci.sgml b/ghc/docs/users_guide/ghci.sgml
index f8f5bbd..d87c1db 100644 (file)
--- a/ghc/docs/users_guide/ghci.sgml
+++ b/ghc/docs/users_guide/ghci.sgml
@@ -9,11 +9,11 @@
     </footnote>
   is GHC's interactive environment, in which Haskell expressions can
   be interactively evaluated and programs can be interpreted.  If
     </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>
   </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>
 
   <indexterm><primary>FFI</primary><secondary>GHCi support</secondary></indexterm>
   <indexterm><primary>Foreign Function Interface</primary><secondary>GHCi support</secondary></indexterm>
 

@@ -27,11 +27,12 @@
 $ ghci
    ___         ___ _
   / _ \ /\  /\/ __(_)
 $ 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.
 
 / /_\\/ __  / /___| |      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>
 
 Prelude> 
 </screen>
 

@@ -42,23 +43,37 @@ Prelude>
 
 <screen>
  Commands available from the prompt:
 
 <screen>
  Commands available from the prompt:

-   &lt;stmt&gt;              evaluate/run &lt;stmt&gt;
-   :cd &lt;dir&gt;           change directory to &lt;dir&gt;
-   :def &lt;cmd&gt; &lt;expr&gt;   define a macro :&lt;cmd&gt;
-   :help, :?           display this list of commands
-   :load &lt;filename&gt;    load a module (and it dependents)
-   :module &lt;mod&gt;       set the context for expression evaluation to &lt;mod&gt;
-   :reload             reload the current module set
-   :set &lt;option&gt; ...   set options
-   :type &lt;expr&gt;        show the type of &lt;expr&gt;
-   :unset &lt;option&gt; ... unset options
-   :quit               exit GHCi
-   :!&lt;command&gt;         run the shell command &lt;command&gt;
+
+   &lt;stmt&gt;                     evaluate/run &lt;stmt&gt;
+   :add &lt;filename&gt; ...        add module(s) to the current target set
+   :browse [*]&lt;module&gt;        display the names defined by &lt;module&gt;
+   :cd &lt;dir&gt;                  change directory to &lt;dir&gt;
+   :def &lt;cmd&gt; &lt;expr&gt;          define a command :&lt;cmd&gt;
+   :help, :?                  display this list of commands
+   :info [&lt;name&gt; ...]         display information about the given names
+   :load &lt;filename&gt; ...       load module(s) and their dependents
+   :module [+/-] [*]&lt;mod&gt; ... set the context for expression evaluation
+   :reload                    reload the current module set
+
+   :set &lt;option&gt; ...          set options
+   :set args &lt;arg&gt; ...        set the arguments returned by System.getArgs
+   :set prog &lt;progname&gt;       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 &lt;expr&gt;               show the type of &lt;expr&gt;
+   :undef &lt;cmd&gt;               undefine user-defined command :&lt;cmd&gt;
+   :unset &lt;option&gt; ...        unset options
+   :quit                      exit GHCi
+   :!&lt;command&gt;                run the shell command &lt;command&gt;
+

  Options for `:set' and `:unset':
  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
     +r                 revert top-level expressions after each evaluation
     +s                 print timing/memory stats after each evaluation
     +t                 print type after evaluation

-    -&lt;flag&gt;            most GHC command line flags can also be set here
+    -&lt;flags&gt;           most GHC command line flags can also be set here

                          (eg. -v2, -fglasgow-exts, etc.)
 </screen>
 
                          (eg. -v2, -fglasgow-exts, etc.)
 </screen>
 

@@ -87,8 +102,7 @@ Prelude>
     <title>Loading source files</title>
 
     <para>Suppose we have the following Haskell source code, which we
     <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)
 
 <programlisting>
 main = print (fac 20)

@@ -97,6 +111,24 @@ fac 0 = 1
 fac n = n * fac (n-1)
 </programlisting>
 
 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 &ldquo;Start&rdquo; 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>
     <para>To load a Haskell source file into GHCi, use the
     <literal>:load</literal> command:</para>
     <indexterm><primary><literal>:load</literal></primary></indexterm>

@@ -105,18 +137,19 @@ fac n = n * fac (n-1)
 Prelude> :load Main
 Compiling Main             ( Main.hs, interpreted )
 Ok, modules loaded: Main.
 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
 </screen>
 
     <para>GHCi has loaded the <literal>Main</literal> module, and the

-    prompt has changed to &ldquo;<literal>Main></literal>&rdquo; to
+    prompt has changed to &ldquo;<literal>*Main></literal>&rdquo; to

     indicate that the current context for expressions typed at the
     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>
 
 <screen>

-Main> fac 17
+*Main> fac 17

 355687428096000
 </screen>
 
 355687428096000
 </screen>
 

@@ -129,7 +162,7 @@ Main> fac 17
     indirectly, by the topmost module, and load them all in dependency
     order.</para>
 
     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>
       <title>Modules vs. filenames</title>
       <indexterm><primary>modules</primary><secondary>and filenames</secondary></indexterm>
       <indexterm><primary>filenames</primary><secondary>of modules</secondary></indexterm>

@@ -158,12 +191,12 @@ Main> fac 17
       <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
       <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>
+      GHCi, and <option>&ndash;&ndash;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
       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
 
       <para>One consequence of the way that GHCi follows dependencies
       to find modules to load is that every module must have a source

@@ -174,10 +207,6 @@ Main> fac 17
       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>
       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>
     </sect2>
 
     <sect2>

@@ -202,8 +231,8 @@ Main> fac 17
     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
     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
 
     <para>Why should we want to run compiled code?  Well, compiled
     code is roughly 10x faster than interpreted code, but takes about

@@ -234,7 +263,7 @@ Compiling C                ( C.hs, interpreted )
 Compiling B                ( B.hs, interpreted )
 Compiling A                ( A.hs, interpreted )
 Ok, modules loaded: A, B, C, D.
 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,
 </screen>
 
     <para>In the messages from the compiler, we see that it skipped D,

@@ -244,20 +273,33 @@ Main>
     isn't necessary, because the source and everything it depends on
     is unchanged since the last compilation.</para>
 
     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>
     <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.
 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
 </screen>
 
     <para>Note that module D was compiled, but in this instance

@@ -268,8 +310,8 @@ Main>
     <para>So let's try compiling one of the other modules:</para>
 
 <screen>
     <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 )
 Compiling D                ( D.hs, interpreted )
 Compiling C                ( C.hs, interpreted )
 Compiling B                ( B.hs, interpreted )

@@ -284,8 +326,8 @@ Ok, modules loaded: A, B, C, D.
     also compile D:</para>
 
 <screen>
     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>
 
 Ok, modules loaded: A, B, C, D.
 </screen>
 

@@ -294,7 +336,7 @@ Ok, modules loaded: A, B, C, D.
     <literal>:load</literal>:</para>
 
 <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 )
 Skipping  D                ( D.hs, D.o )
 Skipping  C                ( C.hs, C.o )
 Compiling B                ( B.hs, interpreted )

@@ -305,7 +347,7 @@ Ok, modules loaded: A, B, C, D.
     <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
     <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 &ndash;&ndash;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
     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

@@ -357,60 +399,108 @@ in a `do' expression pattern binding: print it
     <sect2 id="ghci-scope">
       <title>What's really in scope at the prompt?</title> 
 
     <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>

 
 

-      <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>
+<screen>
+:module <optional>+|-</optional> <optional>*</optional><replaceable>mod<subscript>1</subscript></replaceable> ... <optional>*</optional><replaceable>mod<subscript>n</subscript></replaceable>
+</screen>
+
+      <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>
     </sect2>
   
     <sect2>

@@ -464,8 +554,9 @@ Prelude>
 </screen>
       <para>Any exceptions raised during the evaluation or execution
       of the statement are caught and printed by the GHCi command line
 </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>Every new binding shadows any existing bindings of the
       same name, including entities that are in scope in the current

@@ -478,6 +569,14 @@ Prelude>
       <literal>:module</literal>: the temporary bindings just move to
       the new location.</para>
 
       <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>
       <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>

@@ -538,15 +637,42 @@ Wed Mar 14 12:23:13 GMT 2001
       of <literal>it</literal> is lost.</para>
 
     </sect2>
       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">
     <title>Invoking GHCi</title>
     <indexterm><primary>invoking</primary><secondary>GHCi</secondary></indexterm>
   </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>&ndash;&ndash;interactive</option></primary></indexterm>

 
     <para>GHCi is invoked with the command <literal>ghci</literal> or
 
     <para>GHCi is invoked with the command <literal>ghci</literal> or

-    <literal>ghc --interactive</literal>.  One or more modules or
+    <literal>ghc &ndash;&ndash;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
     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

@@ -569,29 +695,33 @@ $ ghci Main.hs
       <title>Packages</title>
       <indexterm><primary>packages</primary><secondary>with GHCi</secondary></indexterm>
 
       <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>
 
 <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.
 
 / /_\\/ __  / /___| |      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 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> 
 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>The following command works to load new packages into a
       running GHCi:</para>

@@ -602,7 +732,7 @@ Prelude> :set -package <replaceable>name</replaceable>
 
       <para>But note that doing this will cause all currently loaded
       modules to be unloaded, and you'll be dumped back into the
 
       <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>
     </sect2>
 
     <sect2>

@@ -611,7 +741,10 @@ Prelude> :set -package <replaceable>name</replaceable>
       
       <para>Extra libraries may be specified on the command line using
       the normal <literal>-l<replaceable>lib</replaceable></literal>
       
       <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 &ldquo;m&rdquo; 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 &ldquo;m&rdquo; library:</para>

 
 <screen>
 $ ghci -lm
 
 <screen>
 $ ghci -lm

@@ -673,6 +806,28 @@ $ ghci -lm
       </varlistentry>
 
       <varlistentry>
       </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>
        <term><literal>:cd</literal> <replaceable>dir</replaceable></term>
        <indexterm><primary><literal>:cd</literal></primary></indexterm>
        <listitem>

@@ -682,6 +837,12 @@ $ ghci -lm
          beginning of <replaceable>dir</replaceable> will be replaced
          by the contents of the environment variable
          <literal>HOME</literal>.</para>
          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>
 
        </listitem>
       </varlistentry>
 

@@ -728,11 +889,11 @@ Prelude> :mycd ..
 </screen>
 
          <para>Or I could define a simple way to invoke
 </screen>
 
          <para>Or I could define a simple way to invoke

-         &ldquo;<literal>ghc --make Main</literal>&rdquo; in the
+         &ldquo;<literal>ghc &ndash;&ndash;make Main</literal>&rdquo; in the

          current directory:</para>
 
 <screen>
          current directory:</para>
 
 <screen>

-Prelude> :def make (\_ -> return ":! ghc --make Main")
+Prelude> :def make (\_ -> return ":! ghc &ndash;&ndash;make Main")

 </screen>
 
        </listitem>
 </screen>
 
        </listitem>

@@ -779,7 +940,10 @@ Prelude> :def make (\_ -> return ":! ghc --make Main")
 
          <para>All previously loaded modules, except package modules,
          are forgotten.  The new set of modules is known as the
 
          <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>
 
          <para>After a <literal>:load</literal> command, the current
          context is set to:</para>

@@ -802,15 +966,12 @@ Prelude> :def make (\_ -> return ":! ghc --make Main")
       </varlistentry>
 
       <varlistentry>
       </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>
        <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>
 
        </listitem>
       </varlistentry>
 

@@ -847,6 +1008,45 @@ Prelude> :def make (\_ -> return ":! ghc --make Main")
       </varlistentry>
 
       <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>
        <term><literal>:type</literal> <replaceable>expression</replaceable></term>
        <indexterm><primary><literal>:type</literal></primary></indexterm>
        <listitem>

@@ -899,6 +1099,12 @@ Prelude> :def make (\_ -> return ":! ghc --make Main")
     &lsquo;<literal>+</literal>&rdquo; and &ldquo;command-line&rdquo;
     options, which begin with &lsquo;-&rsquo;.  </para>
 
     &lsquo;<literal>+</literal>&rdquo; and &ldquo;command-line&rdquo;
     options, which begin with &lsquo;-&rsquo;.  </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>
     <sect2>
       <title>GHCi options</title>
       <indexterm><primary>options</primary><secondary>GHCi</secondary>

@@ -1055,30 +1261,6 @@ Prelude> :set -fno-glasgow-exts
     
     <variablelist>
       <varlistentry>
     
     <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.getArgs</literal> returns GHCi's command
-       line arguments!</term>
-       <listitem>
-         <para>Yes, it does.</para>
-       </listitem>
-      </varlistentry>
-
-      <varlistentry>

        <term>The interpreter can't load modules with foreign export
        declarations!</term>
        <listitem>
        <term>The interpreter can't load modules with foreign export
        declarations!</term>
        <listitem>