Add :run and tweak :main

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

diff --git a/docs/users_guide/ghci.xml b/docs/users_guide/ghci.xml
index b092953..9fa5d87 100644 (file)
--- a/docs/users_guide/ghci.xml
+++ b/docs/users_guide/ghci.xml
@@ -368,7 +368,6 @@ hello
       <literal>IO</literal> monad.
 <screen>
 Prelude> x &lt;- return 42
-42
 Prelude> print x
 42
 Prelude>
@@ -380,7 +379,8 @@ Prelude>
       <literal>x</literal> in future statements, for example to print
       it as we did above.</para>
 
-      <para>GHCi will print the result of a statement if and only if: 
+      <para>If <option>-fprint-bind-result</option> is set then
+      GHCi will print the result of a statement if and only if: 
        <itemizedlist>
          <listitem>
            <para>The statement is not a binding, or it is a monadic binding 
@@ -393,13 +393,8 @@ Prelude>
              <literal>Show</literal></para>
          </listitem>
        </itemizedlist>
-      The automatic printing of binding results can be suppressed with
-      <option>:set -fno-print-bind-result</option> (this does not
-      suppress printing the result of non-binding statements).
-      <indexterm><primary><option>-fno-print-bind-result</option></primary></indexterm><indexterm><primary><option>-fprint-bind-result</option></primary></indexterm>.
-      You might want to do this to prevent the result of binding
-      statements from being fully evaluated by the act of printing
-      them, for example.</para>
+      <indexterm><primary><option>-fprint-bind-result</option></primary></indexterm><indexterm><primary><option>-fno-print-bind-result</option></primary></indexterm>.
+      </para>
 
       <para>Of course, you can also bind normal non-IO expressions
       using the <literal>let</literal>-statement:</para>
@@ -616,7 +611,7 @@ Prelude IO>
       </sect3>
 
       <sect3>
-        <title>The <literal>:main</literal> command</title>
+        <title>The <literal>:main</literal> and <literal>:run</literal> commands</title>
 
         <para>
           When a program is compiled and executed, it can use the
@@ -641,6 +636,37 @@ Prelude> :main foo bar
 ["foo","bar"]
 </screen>
 
+        <para>
+            We can also quote arguments which contains characters like
+            spaces, and they are treated like Haskell strings, or we can
+            just use Haskell list syntax:
+        </para>
+
+<screen>
+Prelude> :main foo "bar baz"
+["foo","bar baz"]
+Prelude> :main ["foo", "bar baz"]
+["foo","bar baz"]
+</screen>
+
+        <para>
+            Finally, other functions can be called, either with the
+            <literal>-main-is</literal> flag or the <literal>:run</literal>
+            command:
+        </para>
+
+<screen>
+Prelude> let foo = putStrLn "foo" >> System.Environment.getArgs >>= print
+Prelude> let bar = putStrLn "bar" >> System.Environment.getArgs >>= print
+Prelude> :set -main-is foo
+Prelude> :main foo "bar baz"
+foo
+["foo","bar baz"]
+Prelude> :run bar ["foo", "bar baz"]
+bar
+["foo","bar baz"]
+</screen>
+
       </sect3>
     </sect2>
   
@@ -1442,7 +1468,7 @@ as = 'b' : 'c' : (_t1::[Char])
 <programlisting>
 import Prelude hiding (map)
 
-map :: (a->b) -> a -> b
+map :: (a->b) -> [a] -> [b]
 map f [] = []
 map f (x:xs) = f x : map f xs
 </programlisting>
@@ -1745,6 +1771,32 @@ $ ghci -lm
     The <literal>!</literal>-form also annotates the listing 
     with comments giving possible imports for each group of 
     entries.</para>
+<screen>
+Prelude> :browse! Data.Maybe
+-- not currently imported
+Data.Maybe.catMaybes :: [Maybe a] -> [a]
+Data.Maybe.fromJust :: Maybe a -> a
+Data.Maybe.fromMaybe :: a -> Maybe a -> a
+Data.Maybe.isJust :: Maybe a -> Bool
+Data.Maybe.isNothing :: Maybe a -> Bool
+Data.Maybe.listToMaybe :: [a] -> Maybe a
+Data.Maybe.mapMaybe :: (a -> Maybe b) -> [a] -> [b]
+Data.Maybe.maybeToList :: Maybe a -> [a]
+-- imported via Prelude
+Just :: a -> Maybe a
+data Maybe a = Nothing | Just a
+Nothing :: Maybe a
+maybe :: b -> (a -> b) -> Maybe a -> b
+</screen>
+  <para>
+    This output shows that, in the context of the current session, in the scope
+    of <literal>Prelude</literal>, the first group of items from
+    <literal>Data.Maybe</literal> have not been imported (but are available in
+    fully qualified form in the GHCi session - see <xref
+      linkend="ghci-scope"/>), whereas the second group of items have been
+    imported via <literal>Prelude</literal> and are therefore available either
+    unqualified, or with a <literal>Prelude.</literal> qualifier.
+  </para>
        </listitem>
       </varlistentry>
 
@@ -1970,6 +2022,17 @@ Prelude> :. cmds.ghci
       </varlistentry>
 
       <varlistentry>
+       <term>
+          <literal>:</literal>
+          <indexterm><primary><literal>:</literal></primary></indexterm>
+        </term>
+       <listitem>
+         <para>Repeat the previous command.</para>
+       </listitem>
+      </varlistentry>
+
+      <varlistentry>
+
        <term>
           <literal>:history [<replaceable>num</replaceable>]</literal>
           <indexterm><primary><literal>:history</literal></primary></indexterm>
@@ -2087,6 +2150,37 @@ Prelude> :main foo bar
 ["foo","bar"]
 </screen>
 
+        <para>
+            We can also quote arguments which contains characters like
+            spaces, and they are treated like Haskell strings, or we can
+            just use Haskell list syntax:
+        </para>
+
+<screen>
+Prelude> :main foo "bar baz"
+["foo","bar baz"]
+Prelude> :main ["foo", "bar baz"]
+["foo","bar baz"]
+</screen>
+
+        <para>
+            Finally, other functions can be called, either with the
+            <literal>-main-is</literal> flag or the <literal>:run</literal>
+            command:
+        </para>
+
+<screen>
+Prelude> let foo = putStrLn "foo" >> System.Environment.getArgs >>= print
+Prelude> let bar = putStrLn "bar" >> System.Environment.getArgs >>= print
+Prelude> :set -main-is foo
+Prelude> :main foo "bar baz"
+foo
+["foo","bar baz"]
+Prelude> :run bar ["foo", "bar baz"]
+bar
+["foo","bar baz"]
+</screen>
+
         </listitem>
       </varlistentry>