:force is not unsupported anymore

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

diff --git a/docs/users_guide/ghci.xml b/docs/users_guide/ghci.xml
index 5f38b37..aaa9c46 100644 (file)
--- a/docs/users_guide/ghci.xml
+++ b/docs/users_guide/ghci.xml
@@ -18,7 +18,7 @@
   <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>
 

-  <sect1>
+  <sect1 id="ghci-introduction">

     <title>Introduction to GHCi</title>
 
     <para>Let's start with an example GHCi session.  You can fire up
     <title>Introduction to GHCi</title>
 
     <para>Let's start with an example GHCi session.  You can fire up

@@ -106,7 +106,7 @@ Prelude>
     enter, GHCi will attempt to evaluate it.</para>
   </sect1>
 
     enter, GHCi will attempt to evaluate it.</para>
   </sect1>
 

-  <sect1>
+  <sect1 id="loading-source-files">

     <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

@@ -363,7 +363,7 @@ Ok, modules loaded: A, B, C, D.
 
   </sect1>
 
 
   </sect1>
 

-  <sect1>
+  <sect1 id="interactive-evaluation">

     <title>Interactive evaluation at the prompt</title>
 
     <para>When you type an expression at the prompt, GHCi immediately
     <title>Interactive evaluation at the prompt</title>
 
     <para>When you type an expression at the prompt, GHCi immediately

@@ -747,24 +747,79 @@ it &lt;- <replaceable>e</replaceable>
     standard rules take each group of constraints <literal>(C1 a, C2 a, ..., Cn
     a)</literal> for each type variable <literal>a</literal>, and defaults the
     type variable if 
     standard rules take each group of constraints <literal>(C1 a, C2 a, ..., Cn
     a)</literal> for each type variable <literal>a</literal>, and defaults the
     type variable if 

-       <itemizedlist>
-           <listitem><para> The type variable <literal>a</literal>
-       appears in no other constraints </para></listitem>
-           <listitem><para> All the classes <literal>Ci</literal> are standard.</para></listitem>
-           <listitem><para> At least one of the classes <literal>Ci</literal> is
-           numeric.</para></listitem>
-      </itemizedlist>
-   At the GHCi prompt, the second and third rules are relaxed as follows
-   (differences italicised):
-       <itemizedlist>
-           <listitem><para> <emphasis>All</emphasis> of the classes
-           <literal>Ci</literal> are single-parameter type classes.</para></listitem>
-           <listitem><para> At least one of the classes <literal>Ci</literal> is
-           numeric, <emphasis>or is <literal>Show</literal>, 
-               <literal>Eq</literal>, or <literal>Ord</literal></emphasis>.</para></listitem>
-      </itemizedlist>
-   The same type-default behaviour can be enabled in an ordinary Haskell
-   module, using the flag <literal>-fextended-default-rules</literal>. 
+    <orderedlist>
+        <listitem>
+            <para>
+                The type variable <literal>a</literal> appears in no
+                other constraints
+            </para>
+        </listitem>
+        <listitem>
+            <para>
+                All the classes <literal>Ci</literal> are standard.
+            </para>
+        </listitem>
+        <listitem>
+            <para>
+                At least one of the classes <literal>Ci</literal> is
+                numeric.
+            </para>
+        </listitem>
+    </orderedlist>
+    At the GHCi prompt, or with GHC if the
+    <literal>-fextended-default-rules</literal> flag is given,
+    the following additional differences apply:
+    <itemizedlist>
+        <listitem>
+            <para>
+                Rule 2 above is relaxed thus:
+                <emphasis>All</emphasis> of the classes
+                <literal>Ci</literal> are single-parameter type classes.
+            </para>
+        </listitem>
+        <listitem>
+            <para>
+                Rule 3 above is relaxed this:
+                At least one of the classes <literal>Ci</literal> is
+                numeric, <emphasis>or is <literal>Show</literal>,
+                <literal>Eq</literal>, or
+                <literal>Ord</literal></emphasis>.
+            </para>
+        </listitem>
+        <listitem>
+            <para>
+                The unit type <literal>()</literal> is added to the
+                start of the standard list of types which are tried when
+                doing type defaulting.
+            </para>
+        </listitem>
+    </itemizedlist>
+    The last point means that, for example, this program:
+<programlisting>
+main :: IO ()
+main = print def
+
+instance Num ()
+
+def :: (Num a, Enum a) => a
+def = toEnum 0
+</programlisting>
+    prints <literal>()</literal> rather than <literal>0</literal> as the
+    type is defaulted to <literal>()</literal> rather than
+    <literal>Integer</literal>.
+   </para>
+   <para>
+    The motivation for the change is that it means <literal>IO a</literal>
+    actions default to <literal>IO ()</literal>, which in turn means that
+    ghci won't try to print a result when running them. This is
+    particularly important for <literal>printf</literal>, which has an
+    instance that returns <literal>IO a</literal>.
+    However, it is only able to return
+    <literal>undefined</literal>
+    (the reason for the instance having this type is to not require
+    extensions to the class system), so if the type defaults to
+    <literal>Integer</literal> then ghci gives an error when running a
+    printf.

    </para>
     </sect2>
   </sect1>
    </para>
     </sect2>
   </sect1>

@@ -966,7 +1021,7 @@ $ ghci -lm
           <literal>:continue</literal> 
           <indexterm><primary><literal>:continue</literal></primary></indexterm>
         </term>
           <literal>:continue</literal> 
           <indexterm><primary><literal>:continue</literal></primary></indexterm>
         </term>

-       <listitem> Shortcut to <literal>:breakpoint continue </literal>
+       <listitem><para>Shortcut to <literal>:breakpoint continue</literal></para>

        </listitem>
       </varlistentry>
 
        </listitem>
       </varlistentry>
 

@@ -1189,9 +1244,9 @@ li - (_t1::[Maybe Integer])
 Prelude> head li
 Just 1
 Prelude> :sp li
 Prelude> head li
 Just 1
 Prelude> :sp li

-li - [Just 1 | _]
+li - Just 1 : _

 Prelude> :p li
 Prelude> :p li

-li - [Just 1 | (_t2::[Maybe Integer])]
+li - Just 1 : (_t2::[Maybe Integer])

 Prelude> last li
 Just 5
 Prelude> :sp li
 Prelude> last li
 Just 5
 Prelude> :sp li

@@ -1207,8 +1262,6 @@ li - [Just 1,(_t6::Maybe Integer),Just 3,(_t7::Maybe Integer),Just 4]
         to help us observe how the <literal>li</literal> variable is evaluated progressively as we operate
          with it. Note for instance how <quote>last</quote> traverses all the elements of
         the list to compute its result, but without evaluating the individual elements.</para>
         to help us observe how the <literal>li</literal> variable is evaluated progressively as we operate
          with it. Note for instance how <quote>last</quote> traverses all the elements of
         the list to compute its result, but without evaluating the individual elements.</para>

-           <para>Finally note that the Prolog convention of [head | tail] is used by 
-        <literal>:sprint</literal> to display unevaluated lists.

          </para>
        </listitem>
       </varlistentry>
          </para>
        </listitem>
       </varlistentry>

@@ -1334,7 +1387,7 @@ li - _
 Prelude> head li
 Just 1
 Prelude> :sp li
 Prelude> head li
 Just 1
 Prelude> :sp li

-li - [Just 1 | _]
+li - Just 1 : _

 Prelude> last li
 Just 5
 Prelude> :sp li
 Prelude> last li
 Just 5
 Prelude> :sp li

@@ -1343,8 +1396,6 @@ li - [Just 1,_,_,_,Just 5]
          The example uses <literal>:sprint</literal> to help us observe how the <literal>li</literal> variable is evaluated progressively as we operate
          with it. Note for instance how <quote>last</quote> traverses all the elements of
         the list to compute its result, but without evaluating the individual elements.</para>
          The example uses <literal>:sprint</literal> to help us observe how the <literal>li</literal> variable is evaluated progressively as we operate
          with it. Note for instance how <quote>last</quote> traverses all the elements of
         the list to compute its result, but without evaluating the individual elements.</para>

-           <para>Finally note that the Prolog convention of [head | tail] is used by 
-        <literal>:sprint</literal> to display unevaluated lists.

          </para>
        </listitem>
       </varlistentry>
          </para>
        </listitem>
       </varlistentry>

@@ -1623,7 +1674,7 @@ Local bindings in scope:
 qsort2.hs:2:15-46>   
 </programlisting>
       What is happening here is that GHCi has interrupted the evaluation of 
 qsort2.hs:2:15-46>   
 </programlisting>
       What is happening here is that GHCi has interrupted the evaluation of 

-      <code>qsort</code> at the breakpoint set in line 2, as the prompt indicates.
+      <literal>qsort</literal> at the breakpoint set in line 2, as the prompt indicates.

       At this point you can freely explore the contents of the bindings in scope,
       but with two catches. </para><para>
       First, take into account that due to the lazy nature of Haskell, some of
       At this point you can freely explore the contents of the bindings in scope,
       but with two catches. </para><para>
       First, take into account that due to the lazy nature of Haskell, some of

@@ -1631,9 +1682,9 @@ qsort2.hs:2:15-46>
       trigger a computation. </para><para>
       Second: look at the types of the things in scope.
       GHCi has left its types parameterised by a variable!
       trigger a computation. </para><para>
       Second: look at the types of the things in scope.
       GHCi has left its types parameterised by a variable!

-      Look at the type of <code>qsort</code>, which is 
+      Look at the type of <literal>qsort</literal>, which is 

       polymorphic on the type of its argument. It does not 
       polymorphic on the type of its argument. It does not 

-      tell us really what the types of <code>x</code> and <code>xs</code> can be. 
+      tell us really what the types of <literal>x</literal> and <literal>xs</literal> can be. 

       In general, polymorphic programs deal with polymorphic values,
       and this means that some of the bindings available in a breakpoint site
       will be parametrically typed.
       In general, polymorphic programs deal with polymorphic values,
       and this means that some of the bindings available in a breakpoint site
       will be parametrically typed.

@@ -1644,11 +1695,11 @@ qsort2.hs:2:15-46>
       This is useful because you cannot just type <literal>x</literal> in the 
       prompt and expect GHCi to return you its value. Perhaps you know for 
       sure that 
       This is useful because you cannot just type <literal>x</literal> in the 
       prompt and expect GHCi to return you its value. Perhaps you know for 
       sure that 

-      <literal>x</literal> is of type <code>Int</code>, which is an instance of 
-      <code>Show</code>, but GHCi does not have this information. 
-      <code>:print</code> however is fine, because it does not need to know the 
+      <literal>x</literal> is of type <literal>Int</literal>, which is an instance of 
+      <literal>Show</literal>, but GHCi does not have this information. 
+      <literal>:print</literal> however is fine, because it does not need to know the 

       type to do its work. </para>
       type to do its work. </para>

-      <para> Let's go on with the debugging session of the <code>qsort</code>
+      <para> Let's go on with the debugging session of the <literal>qsort</literal>

       example:
 <example id="debuggingEx"><title>A short debugging session</title>
 <programlisting>
       example:
 <example id="debuggingEx"><title>A short debugging session</title>
 <programlisting>

@@ -1674,22 +1725,22 @@ x :: Int
          <para>GHCi reminds us that this value is untyped, and instructs us to force its evaluation </para>
        </callout>
        <callout arearefs="seq2">
          <para>GHCi reminds us that this value is untyped, and instructs us to force its evaluation </para>
        </callout>
        <callout arearefs="seq2">

-         <para>This line forces the evaluation of <code>x</code> </para>
+         <para>This line forces the evaluation of <literal>x</literal> </para>

        </callout>
        <callout arearefs="seq3">
          <para>Even though x has been evaluated, we cannot simply use its name to see its value! 
          This is a bit counterintuitive, but currently in GHCi the type of a binding
        </callout>
        <callout arearefs="seq3">
          <para>Even though x has been evaluated, we cannot simply use its name to see its value! 
          This is a bit counterintuitive, but currently in GHCi the type of a binding

-         cannot be a type variable <code>a</code>. 
-         Thus, the binding <code>x</code> gets assigned the concrete type Unknown.</para>
+         cannot be a type variable <literal>a</literal>. 
+         Thus, the binding <literal>x</literal> gets assigned the concrete type Unknown.</para>

        </callout>
        <callout arearefs="seq4">
        </callout>
        <callout arearefs="seq4">

-         <para>We can explore <code>x</code> using the <literal>:print</literal> 
-         command, which does find out that <code>x</code> is of type Int and prints
+         <para>We can explore <literal>x</literal> using the <literal>:print</literal> 
+         command, which does find out that <literal>x</literal> is of type Int and prints

          its value accordingly.</para>
        </callout>
        <callout arearefs="seq5">
          its value accordingly.</para>
        </callout>
        <callout arearefs="seq5">

-          <literal>:print</literal> also updates the type of <code>x</code> with
-          the most concrete type information available.
+          <para><literal>:print</literal> also updates the type of <literal>x</literal> with
+          the most concrete type information available.</para>

        </callout>
       </calloutlist>
       The example shows the standard way to proceeed with polymorphic values in a breakpoint. 
        </callout>
       </calloutlist>
       The example shows the standard way to proceeed with polymorphic values in a breakpoint. 

@@ -1784,7 +1835,7 @@ x :: Int
      <para>
       <itemizedlist>
        <listitem><para>
      <para>
       <itemizedlist>
        <listitem><para>

-         <xref linkend="implicit-parameters" xrefstyle="select: title"/> are only available 
+         Implicit parameters (see <xref linkend="implicit-parameters"/>) are only available 

          at the scope of a breakpoint if there is a explicit type signature.
        </para></listitem>
       </itemizedlist>
          at the scope of a breakpoint if there is a explicit type signature.
        </para></listitem>
       </itemizedlist>

@@ -1804,13 +1855,13 @@ x :: Int
            <programlisting>{-# OPTIONS_GHC -fdebugging #-}</programlisting>
          </listitem>
        </varlistentry>
            <programlisting>{-# OPTIONS_GHC -fdebugging #-}</programlisting>
          </listitem>
        </varlistentry>

-       <varlistentry> <term>* Repeated use of <code>seq</code> and 
+       <varlistentry> <term>* Repeated use of <literal>seq</literal> and 

            <literal>:print</literal> may be necessary to observe unevaluated
            untyped bindings</term> 
          <listitem><para>see <xref linkend="debuggingEx"/> 
          </para></listitem>
        </varlistentry>
            <literal>:print</literal> may be necessary to observe unevaluated
            untyped bindings</term> 
          <listitem><para>see <xref linkend="debuggingEx"/> 
          </para></listitem>
        </varlistentry>

-       <varlistentry> <term> * <code>GHC.Exts.unsafeCoerce</code> can help if you are positive about the type of a binding</term> 
+       <varlistentry> <term> * <literal>GHC.Exts.unsafeCoerce</literal> can help if you are positive about the type of a binding</term> 

          <listitem><para><programlisting>
 type MyLongType a = [Maybe [Maybe a]]
 
          <listitem><para><programlisting>
 type MyLongType a = [Maybe [Maybe a]]
 

@@ -1825,11 +1876,11 @@ Main.hs:15> x'
           Note that a wrong coercion will likely result in your debugging session being interrupted by a segmentation fault 
          </para></listitem>
        </varlistentry>
           Note that a wrong coercion will likely result in your debugging session being interrupted by a segmentation fault 
          </para></listitem>
        </varlistentry>

-       <varlistentry> <term> * The undocumented (and unsupported) &colon;force command </term>
+       <varlistentry> <term> * The <literal>:force</literal> command </term>

          <listitem><para> 
              equivalent to <literal> :print</literal> with automatic 
          <listitem><para> 
              equivalent to <literal> :print</literal> with automatic 

-             <code>seq</code> forcing, 
-             may prove useful to replace sequences of <code>seq</code> and 
+             <literal>seq</literal> forcing, 
+             may prove useful to replace sequences of <literal>seq</literal> and 

              <literal>&colon;print</literal> in some situations. 
          </para></listitem>
        </varlistentry> 
              <literal>&colon;print</literal> in some situations. 
          </para></listitem>
        </varlistentry> 

@@ -1897,6 +1948,32 @@ Main.hs:15> x'
 
   </sect1>
 
 
   </sect1>
 

+  <sect1 id="ghci-obj">
+    <title>Compiling to object code inside GHCi</title>
+
+    <para>By default, GHCi compiles Haskell source code into byte-code
+    that is interpreted by the runtime system.  GHCi can also compile
+    Haskell code to object code: to turn on this feature, use the
+    <option>-fobject-code</option> flag either on the command line or
+    with <literal>:set</literal> (the option
+    <option>-fbyte-code</option> restores byte-code compilation
+    again).  Compiling to object code takes longer, but typically the
+    code will execute 10-20 times faster than byte-code.</para>
+
+    <para>Compiling to object code inside GHCi is particularly useful
+    if you are developing a compiled application, because the
+    <literal>:reload</literal> command typically runs much faster than
+    restarting GHC with <option>--make</option> from the command-line,
+    because all the interface files are already cached in
+    memory.</para>
+
+    <para>There are disadvantages to compiling to object-code: you
+    can't set breakpoints in object-code modules, for example.  Only
+    the exports of an object-code module will be visible in GHCi,
+    rather than all top-level bindings as in interpreted
+    modules.</para>
+  </sect1>
+

   <sect1 id="ghci-faq">
     <title>FAQ and Things To Watch Out For</title>
     
   <sect1 id="ghci-faq">
     <title>FAQ and Things To Watch Out For</title>
     

@@ -1975,7 +2052,7 @@ Main.hs:15> x'
        <term>I can't use Control-C to interrupt computations in
           GHCi on Windows.</term>
         <listitem>
        <term>I can't use Control-C to interrupt computations in
           GHCi on Windows.</term>
         <listitem>

-          <para>See <xref linkend="ghci-windows">.</xref></para>
+          <para>See <xref linkend="ghci-windows"/></para>

         </listitem>
       </varlistentry>
     </variablelist>
         </listitem>
       </varlistentry>
     </variablelist>