[project @ 2004-05-24 09:13:21 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 f7a6e06..792f68b 100644 (file)
--- a/ghc/docs/users_guide/ghci.sgml
+++ b/ghc/docs/users_guide/ghci.sgml
@@ -63,6 +63,7 @@ Prelude>
    :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
@@ -196,7 +197,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
@@ -637,6 +638,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">
@@ -751,6 +779,10 @@ $ 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>
@@ -810,6 +842,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>
 
@@ -1026,6 +1064,17 @@ Prelude> :def make (\_ -> return ":! ghc &ndash;&ndash;make Main")
       </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>