[project @ 2003-07-21 15:24:42 by simonmar]
[ghc-hetmet.git] / ghc / docs / users_guide / ghci.sgml
index 0ba4d8d..d87c1db 100644 (file)
@@ -162,7 +162,7 @@ Ok, modules loaded: Main.
     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>
@@ -196,7 +196,7 @@ Ok, modules loaded: Main.
       <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
@@ -207,10 +207,6 @@ Ok, modules loaded: Main.
       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>
@@ -641,6 +637,33 @@ Wed Mar 14 12:23:13 GMT 2001
       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">
@@ -672,26 +695,33 @@ $ ghci Main.hs
       <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>network</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 network
+$ ghci -package data
    ___         ___ _
   / _ \ /\  /\/ __(_)
- / /_\// /_/ / /  | |      GHC Interactive, version 5.04, for Haskell 98.
+ / /_\// /_/ / /  | |      GHC Interactive, version 5.05, for Haskell 98.
 / /_\\/ __  / /___| |      http://www.haskell.org/ghc/
 \____/\/ /_/\____/|_|      Type :? for help.
 
 Loading package base ... linking ... done.
 Loading package haskell98 ... linking ... done.
-Loading package network ... linking ... done.
+Loading package lang ... 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 will also automatically load any packages
-      on which the requested package depends.</para>
+</screen>
 
       <para>The following command works to load new packages into a
       running GHCi:</para>
@@ -702,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
-      Prelude.</para>
+      <literal>Prelude</literal>.</para>
     </sect2>
 
     <sect2>
@@ -711,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>
-      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
@@ -804,6 +837,12 @@ $ ghci -lm
          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>
 
@@ -1222,22 +1261,6 @@ Prelude> :set -fno-glasgow-exts
     
     <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>