Commit 01386d38 authored by pcapriotti's avatar pcapriotti

Add documentation for -interactive-print (#5461)

Based on a patch by Vitaly Bragilevsky <bravit111@gmail.com>
parent b5bc12bd
......@@ -535,6 +535,13 @@
<entry>dynamic</entry>
<entry>-</entry>
</row>
<row>
<entry><option>-interactive-print</option></entry>
<entry><link linkend="ghci-interactive-print">Select the function
to use for printing evaluated expressions in GHCi</link></entry>
<entry>dynamic</entry>
<entry>-</entry>
</row>
</tbody>
</tgroup>
......
......@@ -1090,6 +1090,61 @@ def = toEnum 0
printf.
</para>
</sect2>
<sect2 id="ghci-interactive-print">
<title>Using a custom interactive printing function</title>
<para>[<emphasis role="bold">New in version 7.6.1</emphasis>]
By default, GHCi prints the result of expressions typed at the prompt
using the function <literal>System.IO.print</literal>. Its type
signature is <literal>Show a => a -> IO ()</literal>, and it works by
converting the value to <literal>String</literal> using
<literal>show</literal>.
</para>
<para>
This is not ideal in certain cases, like when the output is long, or
contains strings with non-ascii characters.
</para>
<para>
The <literal>-interactive-print</literal> flag allows to specify any
function of type <literal>C a => a -> IO ()</literal>, for some
constraint <literal>C</literal>, as the function for printing evaluated
expressions. The function can reside in any loaded module or any
registered package.
</para>
<para>
As an example, suppose we have following special printing module:
<programlisting>
module SpecPrinter where
import System.IO
sprint a = putStrLn $ show a ++ "!"
</programlisting>
The <literal>sprint</literal> function adds an exclamation mark at the
end of any printed value. Running GHCi with the command:
<programlisting>
ghci -interactive-print=SpecPrinter.sprinter SpecPrinter
</programlisting>
will start an interactive session where values with be printed using
<literal>sprint</literal>:
<programlisting>
*SpecPrinter> [1,2,3]
[1,2,3]!
*SpecPrinter> 42
42!
</programlisting>
</para>
<para>
A custom pretty printing function can be used, for example, to format
tree-like and nested structures in a more readable way.
</para>
<para>
The <literal>-interactive-print</literal> flag can also be used when
running GHC in <literal>-e mode</literal>:
<programlisting>
% ghc -e "[1,2,3]" -interactive-print=SpecPrinter.sprint SpecPrinter
[1,2,3]!
</programlisting>
</para>
</sect2>
</sect1>
<sect1 id="ghci-debugger">
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment