diff options
Diffstat (limited to 'docs/users_guide/ghci.xml')
| -rw-r--r-- | docs/users_guide/ghci.xml | 3709 |
1 files changed, 0 insertions, 3709 deletions
diff --git a/docs/users_guide/ghci.xml b/docs/users_guide/ghci.xml deleted file mode 100644 index 399cda90ea..0000000000 --- a/docs/users_guide/ghci.xml +++ /dev/null @@ -1,3709 +0,0 @@ -<?xml version="1.0" encoding="iso-8859-1"?> -<chapter id="ghci"> - <title>Using GHCi</title> - <indexterm><primary>GHCi</primary></indexterm> - <indexterm><primary>interpreter</primary><see>GHCi</see></indexterm> - <indexterm><primary>interactive</primary><see>GHCi</see></indexterm> - - <para>GHCi<footnote> - <para>The ‘i’ stands for “Interactive”</para> - </footnote> - is GHC's interactive environment, in which Haskell expressions can - be interactively evaluated and programs can be interpreted. If - you're familiar with <ulink url="http://www.haskell.org/hugs/">Hugs</ulink><indexterm><primary>Hugs</primary> - </indexterm>, then you'll be right at home with GHCi. However, GHCi - also has support for interactively loading compiled code, as well as - supporting all<footnote><para>except <literal>foreign export</literal>, at the moment</para> - </footnote> the language extensions that GHC provides. - <indexterm><primary>FFI</primary><secondary>GHCi support</secondary></indexterm> - <indexterm><primary>Foreign Function - Interface</primary><secondary>GHCi support</secondary></indexterm> - GHCi also includes an interactive debugger (see <xref linkend="ghci-debugger"/>).</para> - - <sect1 id="ghci-introduction"> - <title>Introduction to GHCi</title> - - <para>Let's start with an example GHCi session. You can fire up - GHCi with the command <literal>ghci</literal>:</para> - -<screen> -$ ghci -GHCi, version 6.12.1: http://www.haskell.org/ghc/ :? for help -Loading package ghc-prim ... linking ... done. -Loading package integer-gmp ... linking ... done. -Loading package base ... linking ... done. -Loading package ffi-1.0 ... linking ... done. -Prelude> -</screen> - - <para>There may be a short pause while GHCi loads the prelude and - standard libraries, after which the prompt is shown. As the banner - says, you can type <literal>:?</literal> to see the list of - commands available, and a half line description of each of them. - We'll explain most of these commands as we go along, and there is - complete documentation for all the commands in - <xref linkend="ghci-commands" />.</para> - - <para>Haskell expressions can be typed at the prompt:</para> - <indexterm><primary>prompt</primary><secondary>GHCi</secondary> - </indexterm> - -<screen> -Prelude> 1+2 -3 -Prelude> let x = 42 in x / 9 -4.666666666666667 -Prelude> -</screen> - - <para>GHCi interprets the whole line as an expression to evaluate. - The expression may not span several lines - as soon as you press enter, - GHCi will attempt to evaluate it.</para> - - <para>In Haskell, a <literal>let</literal> expression is followed - by <literal>in</literal>. However, in GHCi, since the expression - can also be interpreted in the <literal>IO</literal> monad, - a <literal>let</literal> binding with no accompanying - <literal>in</literal> statement can be signalled by an empty line, - as in the above example.</para> - </sect1> - - <sect1 id="loading-source-files"> - <title>Loading source files</title> - - <para>Suppose we have the following Haskell source code, which we - place in a file <filename>Main.hs</filename>:</para> - -<programlisting> -main = print (fac 20) - -fac 0 = 1 -fac n = n * fac (n-1) -</programlisting> - - <para>You can save <filename>Main.hs</filename> anywhere you like, - but if you save it somewhere other than the current - directory<footnote><para>If you started up GHCi from the command - line then GHCi's current directory is the same as the current - directory of the shell from which it was started. If you started - GHCi from the “Start” menu in Windows, then the - current directory is probably something like - <filename>C:\Documents and Settings\<replaceable>user - name</replaceable></filename>.</para> </footnote> then we will - need to change to the right directory in GHCi:</para> - -<screen> -Prelude> :cd <replaceable>dir</replaceable> -</screen> - - <para>where <replaceable>dir</replaceable> is the directory (or - folder) in which you saved <filename>Main.hs</filename>.</para> - - <para>To load a Haskell source file into GHCi, use the - <literal>:load</literal> command:</para> - <indexterm><primary><literal>:load</literal></primary></indexterm> - -<screen> -Prelude> :load Main -Compiling Main ( Main.hs, interpreted ) -Ok, modules loaded: Main. -*Main> -</screen> - - <para>GHCi has loaded the <literal>Main</literal> module, and the - prompt has changed to “<literal>*Main></literal>” to - indicate that the current context for expressions typed at the - prompt is the <literal>Main</literal> module we just loaded (we'll - explain what the <literal>*</literal> means later in <xref - linkend="ghci-scope"/>). So we can now type expressions involving - the functions from <filename>Main.hs</filename>:</para> - -<screen> -*Main> fac 17 -355687428096000 -</screen> - - <para>Loading a multi-module program is just as straightforward; - just give the name of the “topmost” module to the - <literal>:load</literal> command (hint: <literal>:load</literal> - can be abbreviated to <literal>:l</literal>). The topmost module - will normally be <literal>Main</literal>, but it doesn't have to - be. GHCi will discover which modules are required, directly or - indirectly, by the topmost module, and load them all in dependency - order.</para> - - <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> - - <para>Question: How does GHC find the filename which contains - module <replaceable>M</replaceable>? Answer: it looks for the - file <literal><replaceable>M</replaceable>.hs</literal>, or - <literal><replaceable>M</replaceable>.lhs</literal>. This means - that for most modules, the module name must match the filename. - If it doesn't, GHCi won't be able to find it.</para> - - <para>There is one exception to this general rule: when you load - a program with <literal>:load</literal>, or specify it when you - invoke <literal>ghci</literal>, you can give a filename rather - than a module name. This filename is loaded if it exists, and - it may contain any module you like. This is particularly - convenient if you have several <literal>Main</literal> modules - in the same directory and you can't call them all - <filename>Main.hs</filename>.</para> - - <para>The search path for finding source files is specified with - the <option>-i</option> option on the GHCi command line, like - so:</para> -<screen>ghci -i<replaceable>dir<subscript>1</subscript></replaceable>:...:<replaceable>dir<subscript>n</subscript></replaceable></screen> - - <para>or it can be set using the <literal>:set</literal> command - from within GHCi (see <xref - linkend="ghci-cmd-line-options"/>)<footnote><para>Note that in - GHCi, and <option>--make</option> mode, the <option>-i</option> - option is used to specify the search path for - <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="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 - file. The only exception to the rule is modules that come from - a package, including the <literal>Prelude</literal> and standard - libraries such as <literal>IO</literal> and - <literal>Complex</literal>. If you attempt to load a module for - 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> - </sect2> - - <sect2> - <title>Making changes and recompilation</title> - <indexterm><primary><literal>:reload</literal></primary></indexterm> - - <para>If you make some changes to the source code and want GHCi - to recompile the program, give the <literal>:reload</literal> - command. The program will be recompiled as necessary, with GHCi - doing its best to avoid actually recompiling modules if their - external dependencies haven't changed. This is the same - mechanism we use to avoid re-compiling modules in the batch - compilation setting (see <xref linkend="recomp"/>).</para> - </sect2> - </sect1> - - <sect1 id="ghci-compiled"> - <title>Loading compiled code</title> - <indexterm><primary>compiled code</primary><secondary>in GHCi</secondary></indexterm> - - <para>When you load a Haskell source module into GHCi, it is - normally converted to byte-code and run using the interpreter. - However, interpreted code can also run alongside compiled code in - GHCi; indeed, normally when GHCi starts, it loads up a compiled - copy of the <literal>base</literal> package, which contains the - <literal>Prelude</literal>.</para> - - <para>Why should we want to run compiled code? Well, compiled - code is roughly 10x faster than interpreted code, but takes about - 2x longer to produce (perhaps longer if optimisation is on). So - it pays to compile the parts of a program that aren't changing - very often, and use the interpreter for the code being actively - developed.</para> - - <para>When loading up source modules with <literal>:load</literal>, - GHCi normally looks for any corresponding compiled object files, - and will use one in preference to interpreting the source if - possible. For example, suppose we have a 4-module program - consisting of modules A, B, C, and D. Modules B and C both import - D only, and A imports both B & C:</para> -<screen> - A - / \ - B C - \ / - D -</screen> - <para>We can compile D, then load the whole program, like this:</para> -<screen> -Prelude> :! ghc -c -dynamic D.hs -Prelude> :load A -Compiling B ( B.hs, interpreted ) -Compiling C ( C.hs, interpreted ) -Compiling A ( A.hs, interpreted ) -Ok, modules loaded: A, B, C, D. -*Main> -</screen> - - <para>In the messages from the compiler, we see that there is no line - for <literal>D</literal>. This is because - it isn't necessary to compile <literal>D</literal>, - because the source and everything it depends on - is unchanged since the last compilation.</para> - - <para>Note the <literal>-dynamic</literal> flag to GHC: GHCi uses - dynamically-linked object code (if you are on a platform that - supports it), and so in order to use compiled code with GHCi it - must be compiled for dynamic linking.</para> - - <para>At any time you can use the command - <literal>:show modules</literal> - to get a list of the modules currently loaded - into GHCi:</para> - -<screen> -*Main> :show modules -D ( D.hs, D.o ) -C ( C.hs, interpreted ) -B ( B.hs, interpreted ) -A ( A.hs, interpreted ) -*Main></screen> - - <para>If we now modify the source of D (or pretend to: using the Unix - command <literal>touch</literal> on the source file is handy for - this), the compiler will no longer be able to use the object file, - because it might be out of date:</para> - -<screen> -*Main> :! touch D.hs -*Main> :reload -Compiling D ( D.hs, interpreted ) -Ok, modules loaded: A, B, C, D. -*Main> -</screen> - - <para>Note that module D was compiled, but in this instance - because its source hadn't really changed, its interface remained - the same, and the recompilation checker determined that A, B and C - didn't need to be recompiled.</para> - - <para>So let's try compiling one of the other modules:</para> - -<screen> -*Main> :! ghc -c C.hs -*Main> :load A -Compiling D ( D.hs, interpreted ) -Compiling B ( B.hs, interpreted ) -Compiling C ( C.hs, interpreted ) -Compiling A ( A.hs, interpreted ) -Ok, modules loaded: A, B, C, D. -</screen> - - <para>We didn't get the compiled version of C! What happened? - Well, in GHCi a compiled module may only depend on other compiled - modules, and in this case C depends on D, which doesn't have an - object file, so GHCi also rejected C's object file. Ok, so let's - also compile D:</para> - -<screen> -*Main> :! ghc -c D.hs -*Main> :reload -Ok, modules loaded: A, B, C, D. -</screen> - - <para>Nothing happened! Here's another lesson: newly compiled - modules aren't picked up by <literal>:reload</literal>, only - <literal>:load</literal>:</para> - -<screen> -*Main> :load A -Compiling B ( B.hs, interpreted ) -Compiling A ( A.hs, interpreted ) -Ok, modules loaded: A, B, C, D. -</screen> - - <para>The automatic loading of object files can sometimes lead to - confusion, because non-exported top-level definitions of a module - are only available for use in expressions at the prompt when the - module is interpreted (see <xref linkend="ghci-scope" />). For - this reason, you might sometimes want to force GHCi to load a - module using the interpreter. This can be done by prefixing - a <literal>*</literal> to the module name or filename when - using <literal>:load</literal>, for example</para> - -<screen> -Prelude> :load *A -Compiling A ( A.hs, interpreted ) -*A> -</screen> - -<para>When the <literal>*</literal> is used, GHCi ignores any - pre-compiled object code and interprets the module. If you have - already loaded a number of modules as object code and decide that - you wanted to interpret one of them, instead of re-loading the whole - set you can use <literal>:add *M</literal> to specify that you want - <literal>M</literal> to be interpreted (note that this might cause - other modules to be interpreted too, because compiled modules cannot - depend on interpreted ones).</para> - -<para>To always compile everything to object code and never use the - interpreter, use the <literal>-fobject-code</literal> option (see - <xref linkend="ghci-obj" />).</para> - - <para>HINT: since GHCi will only use a compiled object file if it - can be sure that the compiled version is up-to-date, a good technique - when working on a large program is to occasionally run - <literal>ghc --make</literal> to compile the whole project (say - before you go for lunch :-), then continue working in the - interpreter. As you modify code, the changed modules will be - interpreted, but the rest of the project will remain - compiled.</para> - </sect1> - - <sect1 id="interactive-evaluation"> - <title>Interactive evaluation at the prompt</title> - - <para>When you type an expression at the prompt, GHCi immediately - evaluates and prints the result: -<screen> -Prelude> reverse "hello" -"olleh" -Prelude> 5+5 -10 -</screen> -</para> - -<sect2 id="actions-at-prompt"><title>I/O actions at the prompt</title> - -<para>GHCi does more than simple expression evaluation at the prompt. -If you enter an expression of type <literal>IO a</literal> for some - <literal>a</literal>, then GHCi <emphasis>executes</emphasis> it - as an IO-computation. -<screen> -Prelude> "hello" -"hello" -Prelude> putStrLn "hello" -hello -</screen> -This works even if the type of the expression is more general, -provided it can be <emphasis>instantiated</emphasis> to <literal>IO a</literal>. For example -<screen> -Prelude> return True -True -</screen> -Furthermore, GHCi will print the result of the I/O action if (and only -if): -<itemizedlist> - <listitem><para>The result type is an instance of <literal>Show</literal>.</para></listitem> - <listitem><para>The result type is not - <literal>()</literal>.</para></listitem> -</itemizedlist> -For example, remembering that <literal>putStrLn :: String -> IO ()</literal>: -<screen> -Prelude> putStrLn "hello" -hello -Prelude> do { putStrLn "hello"; return "yes" } -hello -"yes" -</screen> -</para></sect2> - - <sect2 id="ghci-stmts"> - <title>Using <literal>do-</literal>notation at the prompt</title> - <indexterm><primary>do-notation</primary><secondary>in GHCi</secondary></indexterm> - <indexterm><primary>statements</primary><secondary>in GHCi</secondary></indexterm> - - <para>GHCi actually accepts <firstterm>statements</firstterm> - rather than just expressions at the prompt. This means you can - bind values and functions to names, and use them in future - expressions or statements.</para> - - <para>The syntax of a statement accepted at the GHCi prompt is - exactly the same as the syntax of a statement in a Haskell - <literal>do</literal> expression. However, there's no monad - overloading here: statements typed at the prompt must be in the - <literal>IO</literal> monad. -<screen> -Prelude> x <- return 42 -Prelude> print x -42 -Prelude> -</screen> - The statement <literal>x <- return 42</literal> means - “execute <literal>return 42</literal> in the - <literal>IO</literal> monad, and bind the result to - <literal>x</literal>”. We can then use - <literal>x</literal> in future statements, for example to print - it as we did above.</para> - - <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 - (<literal>p <- e</literal>) that binds exactly one - variable.</para> - </listitem> - <listitem> - <para>The variable's type is not polymorphic, is not - <literal>()</literal>, and is an instance of - <literal>Show</literal>.</para> - </listitem> - </itemizedlist> - <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> -<screen> -Prelude> let x = 42 -Prelude> x -42 -Prelude> -</screen> - <para>Another important difference between the two types of binding - is that the monadic bind (<literal>p <- e</literal>) is - <emphasis>strict</emphasis> (it evaluates <literal>e</literal>), - whereas with the <literal>let</literal> form, the expression - isn't evaluated immediately:</para> -<screen> -Prelude> let x = error "help!" -Prelude> print x -*** Exception: help! -Prelude> -</screen> - - <para>Note that <literal>let</literal> bindings do not automatically - print the value bound, unlike monadic bindings.</para> - - <para>Hint: you can also use <literal>let</literal>-statements - to define functions at the prompt:</para> -<screen> -Prelude> let add a b = a + b -Prelude> add 1 2 -3 -Prelude> -</screen> - <para>However, this quickly gets tedious when defining functions - with multiple clauses, or groups of mutually recursive functions, - because the complete definition has to be given on a single line, - using explicit semicolons instead of layout:</para> -<screen> -Prelude> let f op n [] = n ; f op n (h:t) = h `op` f op n t -Prelude> f (+) 0 [1..3] -6 -Prelude> -</screen> - <para>To alleviate this issue, GHCi commands can be split over - multiple lines, by wrapping them in <literal>:{</literal> and - <literal>:}</literal> (each on a single line of its own):</para> -<screen> -Prelude> :{ -Prelude| let g op n [] = n -Prelude| g op n (h:t) = h `op` g op n t -Prelude| :} -Prelude> g (*) 1 [1..3] -6 -</screen> - <para>Such multiline commands can be used with any GHCi command, - and note that the layout rule is in effect. - The main purpose of multiline commands is not to replace module - loading but to make definitions in .ghci-files (see <xref - linkend="ghci-dot-files"/>) more readable and maintainable.</para> - - <para>Any exceptions raised during the evaluation or execution - of the statement are caught and printed by the GHCi command line - interface (for more information on exceptions, see the module - <literal>Control.Exception</literal> in the libraries - documentation).</para> - - <para>Every new binding shadows any existing bindings of the - same name, including entities that are in scope in the current - module context.</para> - - <para>WARNING: temporary bindings introduced at the prompt only - last until the next <literal>:load</literal> or - <literal>:reload</literal> command, at which time they will be - simply lost. However, they do survive a change of context with - <literal>:module</literal>: the temporary bindings just move to - the new location.</para> - - <para>HINT: To get a list of the bindings currently in scope, use the - <literal>:show bindings</literal> command:</para> - -<screen> -Prelude> :show bindings -x :: Int -Prelude></screen> - - <para>HINT: if you turn on the <literal>+t</literal> option, - GHCi will show the type of each variable bound by a statement. - For example:</para> - <indexterm><primary><literal>+t</literal></primary></indexterm> -<screen> -Prelude> :set +t -Prelude> let (x:xs) = [1..] -x :: Integer -xs :: [Integer] -</screen> - - </sect2> - - <sect2 id="ghci-multiline"> - <title>Multiline input</title> - - <para>Apart from the <literal>:{ ... :}</literal> syntax for - multi-line input mentioned above, GHCi also has a multiline - mode, enabled by <literal>:set +m</literal>, - <indexterm><primary><literal>:set +m</literal></primary></indexterm> - in which GHCi detects automatically when the current statement - is unfinished and allows further lines to be added. A - multi-line input is terminated with an empty line. For example:</para> - -<screen> -Prelude> :set +m -Prelude> let x = 42 -Prelude| -</screen> - - <para>Further bindings can be added to - this <literal>let</literal> statement, so GHCi indicates that - the next line continues the previous one by changing the - prompt. Note that layout is in effect, so to add more bindings - to this <literal>let</literal> we have to line them up:</para> - -<screen> -Prelude> :set +m -Prelude> let x = 42 -Prelude| y = 3 -Prelude| -Prelude> -</screen> - - <para>Explicit braces and semicolons can be used instead of - layout:</para> - -<screen> -Prelude> do { -Prelude| putStrLn "hello" -Prelude| ;putStrLn "world" -Prelude| } -hello -world -Prelude> -</screen> - - <para>Note that after the closing brace, GHCi knows that the - current statement is finished, so no empty line is required.</para> - - <para>Multiline mode is useful when entering monadic - <literal>do</literal> statements:</para> - -<screen> -Control.Monad.State> flip evalStateT 0 $ do -Control.Monad.State| i <- get -Control.Monad.State| lift $ do -Control.Monad.State| putStrLn "Hello World!" -Control.Monad.State| print i -Control.Monad.State| -"Hello World!" -0 -Control.Monad.State> -</screen> - - <para>During a multiline interaction, the user can interrupt and - return to the top-level prompt.</para> - -<screen> -Prelude> do -Prelude| putStrLn "Hello, World!" -Prelude| ^C -Prelude> -</screen> - </sect2> - - <sect2 id="ghci-decls"> - <title>Type, class and other declarations</title> - - <para>At the GHCi - prompt you can also enter any top-level Haskell declaration, - including <literal>data</literal>, <literal>type</literal>, <literal>newtype</literal>, <literal>class</literal>, <literal>instance</literal>, <literal>deriving</literal>, - and <literal>foreign</literal> declarations. For - example:</para> - -<screen> -Prelude> data T = A | B | C deriving (Eq, Ord, Show, Enum) -Prelude> [A ..] -[A,B,C] -Prelude> :i T -data T = A | B | C -- Defined at <interactive>:2:6 -instance Enum T -- Defined at <interactive>:2:45 -instance Eq T -- Defined at <interactive>:2:30 -instance Ord T -- Defined at <interactive>:2:34 -instance Show T -- Defined at <interactive>:2:39 -</screen> - - <para>As with ordinary variable bindings, later definitions shadow - earlier ones, so you can re-enter a declaration to fix a problem - with it or extend it. But there's a gotcha: when a new type - declaration shadows an older one, there might be other - declarations that refer to the old type. The thing to remember is - that the old type still exists, and these other declarations still - refer to the old type. However, while the old and the new type - have the same name, GHCi will treat them as distinct. For - example:</para> - -<screen> -Prelude> data T = A | B -Prelude> let f A = True; f B = False -Prelude> data T = A | B | C -Prelude> f A - -<interactive>:2:3: - Couldn't match expected type `main::Interactive.T' - with actual type `T' - In the first argument of `f', namely `A' - In the expression: f A - In an equation for `it': it = f A -Prelude> -</screen> - - <para>The old, shadowed, version of <literal>T</literal> is - displayed as <literal>main::Interactive.T</literal> by GHCi in - an attempt to distinguish it from the new <literal>T</literal>, - which is displayed as simply <literal>T</literal>.</para> - - <para>Class and type-family instance declarations are simply added to the list of available instances, - with one exception. Since you might want to re-define one, - a class or type-family instance <emphasis>replaces</emphasis> any earlier instance with - an identical head or left hand side (respectively). - (See <xref linkend="type-families"/>.)</para> - </sect2> - - <sect2 id="ghci-scope"> - <title>What's really in scope at the prompt?</title> - - <para>When you type an expression at the prompt, what - identifiers and types are in scope? - GHCi provides a flexible - way to control exactly how the context for an expression is - constructed: - <itemizedlist> - <listitem><para> - The <literal>:load</literal>, <literal>:add</literal>, - and <literal>:reload</literal> commands (<xref linkend="ghci-load-scope"/>). - </para></listitem> - <listitem><para> - The <literal>import</literal> declaration (<xref linkend="ghci-import-decl"/>). - </para></listitem> - <listitem><para> - The <literal>:module</literal> command (<xref linkend="ghci-module-cmd"/>). - </para></listitem> - </itemizedlist> - </para> - <para>The command <literal>:show imports</literal> will show a summary of which modules - contribute to the top-level scope.</para> - <para> - Hint: GHCi will tab-complete names that are in scope; for - example, if you run GHCi and type <literal>J<tab></literal> - then GHCi will expand it to “<literal>Just </literal>”. - </para> - - <sect3 id="ghci-load-scope"> - <title>The effect of <literal>:load</literal> on what is in scope</title> - <para> - The <literal>:load</literal>, <literal>:add</literal>, and <literal>:reload</literal> - commands (<xref linkend="loading-source-files"/> - and <xref linkend="ghci-compiled"/>) affect the top-level scope. - Let's start with the simple cases; when you start - GHCi the prompt looks like this: - -<screen>Prelude></screen> - - which indicates that everything from the module - <literal>Prelude</literal> is currently in scope; the visible - identifiers are exactly those that would be visible in a Haskell - source file with no <literal>import</literal> - declarations.</para> - - <para>If we now load a file into GHCi, the prompt will change:</para> - -<screen> -Prelude> :load Main.hs -Compiling Main ( Main.hs, interpreted ) -*Main> -</screen> - - <para>The new prompt is <literal>*Main</literal>, which - indicates that we are typing expressions in the context of the - top-level of the <literal>Main</literal> module. Everything - that is in scope at the top-level in the module - <literal>Main</literal> we just loaded is also in scope at the - prompt (probably including <literal>Prelude</literal>, as long - as <literal>Main</literal> doesn't explicitly hide it).</para> - - <para>The syntax in the prompt - <literal>*<replaceable>module</replaceable></literal> indicates - that it is the full top-level scope of - <replaceable>module</replaceable> that is contributing to the - scope for expressions typed at the prompt. Without the - <literal>*</literal>, just the exports of the module are - visible.</para> - - <para>NOTE: for technical reasons, GHCi can only support the - <literal>*</literal>-form for modules that are interpreted. - Compiled modules and package modules can only contribute their - exports to the current scope. To ensure that GHCi loads the - interpreted version of a module, add the <literal>*</literal> - when loading the module, e.g. <literal>:load *M</literal>.</para> - - <para>In general, after a <literal>:load</literal> command, an automatic - import is added to the scope for the most recently loaded - "target" module, in a <literal>*</literal>-form if possible. - For example, if you say <literal>:load foo.hs bar.hs</literal> - and <filename>bar.hs</filename> contains module - <literal>Bar</literal>, then the scope will be set to - <literal>*Bar</literal> if <literal>Bar</literal> is - interpreted, or if <literal>Bar</literal> is compiled it will be - set to <literal>Prelude Bar</literal> (GHCi automatically adds - <literal>Prelude</literal> if it isn't present and there aren't - any <literal>*</literal>-form modules). These - automatically-added imports can be seen with - <literal>:show imports</literal>: - -<screen> -Prelude> :load hello.hs -[1 of 1] Compiling Main ( hello.hs, interpreted ) -Ok, modules loaded: Main. -*Main> :show imports -:module +*Main -- added automatically -*Main> -</screen> - - and the automatically-added import is replaced the next time you - use <literal>:load</literal>, <literal>:add</literal>, or - <literal>:reload</literal>. It can also be removed by - <literal>:module</literal> as with normal imports.</para> - </sect3> - - <sect3 id="ghci-import-decl"> - <title>Controlling what is in scope with <literal>import</literal></title> - - <para>We are not limited to a single module: GHCi can combine - scopes from multiple modules, in any mixture of - <literal>*</literal> and non-<literal>*</literal> forms. GHCi - combines the scopes from all of these modules to form the scope - that is in effect at the prompt.</para> - - <para>To add modules to the scope, use ordinary Haskell - <literal>import</literal> syntax:</para> - -<screen> -Prelude> import System.IO -Prelude System.IO> hPutStrLn stdout "hello\n" -hello -Prelude System.IO> -</screen> - - <para>The full Haskell import syntax is supported, including - <literal>hiding</literal> and <literal>as</literal> clauses. - The prompt shows the modules that are currently imported, but it - omits details about <literal>hiding</literal>, - <literal>as</literal>, and so on. To see the full story, use - <literal>:show imports</literal>:</para> - -<screen> -Prelude> import System.IO -Prelude System.IO> import Data.Map as Map -Prelude System.IO Map> :show imports -import Prelude -- implicit -import System.IO -import Data.Map as Map -Prelude System.IO Map> -</screen> - - <para>Note that the <literal>Prelude</literal> import is marked - as implicit. It can be overridden with an explicit - <literal>Prelude</literal> import, just like in a Haskell - module.</para> - - <para>With multiple modules in scope, especially multiple - <literal>*</literal>-form modules, it is likely that name - clashes will occur. Haskell specifies that name clashes are - only reported when an ambiguous identifier is used, and GHCi - behaves in the same way for expressions typed at the - prompt.</para> - - </sect3> - - <sect3 id="ghci-module-cmd"> - <title>Controlling what is in scope with the <literal>:module</literal> command</title> - - <para>Another way to manipulate the scope is to use the - <literal>:module</literal> command, whose syntax is this: - -<screen> -:module <optional>+|-</optional> <optional>*</optional><replaceable>mod<subscript>1</subscript></replaceable> ... <optional>*</optional><replaceable>mod<subscript>n</subscript></replaceable> -</screen> - - Using the <literal>+</literal> form of the - <literal>module</literal> commands adds modules to the current - scope, and <literal>-</literal> removes them. Without either - <literal>+</literal> or <literal>-</literal>, the current scope - is replaced by the set of modules specified. Note that if you - use this form and leave out <literal>Prelude</literal>, an - implicit <literal>Prelude</literal> import will be added - automatically.</para> - - <para>The <literal>:module</literal> command provides a way to do - two things that cannot be done with ordinary - <literal>import</literal> declarations: - <itemizedlist> - <listitem> - <para><literal>:module</literal> supports the - <literal>*</literal> modifier on modules, which opens the - full top-level scope of a module, rather than just its - exports.</para> - </listitem> - <listitem> - <para>Imports can be <emphasis>removed</emphasis> from the - context, using the syntax <literal>:module -M</literal>. - The <literal>import</literal> syntax is cumulative (as in a - Haskell module), so this is the only way to subtract from - the scope.</para> - </listitem> - </itemizedlist> - </para> - </sect3> - - <sect3 id="ghci-import-qualified"> - <title>Qualified names</title> - - <para>To make life slightly easier, the GHCi prompt also - behaves as if there is an implicit <literal>import - qualified</literal> declaration for every module in every - package, and every module currently loaded into GHCi. This - behaviour can be disabled with the flag <option>-fno-implicit-import-qualified</option><indexterm><primary><option>-fno-implicit-import-qualified</option></primary></indexterm>.</para> - </sect3> - - <sect3> - <title><literal>:module</literal> and - <literal>:load</literal></title> - - <para>It might seem that <literal>:module</literal>/<literal>import</literal> and - <literal>:load</literal>/<literal>:add</literal>/<literal>:reload</literal> - do similar things: you can use both - to bring a module into scope. However, there is a very important - difference. GHCi is concerned with two sets of modules:</para> - - <itemizedlist> - <listitem> - <para>The set of modules that are currently - <emphasis>loaded</emphasis>. This set is modified by - <literal>:load</literal>, <literal>:add</literal> and - <literal>:reload</literal>, and can be shown with - <literal>:show modules</literal>. - </para> - </listitem> - <listitem> - <para>The set of modules that are currently <emphasis>in - scope</emphasis> at the prompt. This set is modified by - <literal>import</literal> and <literal>:module</literal>, and - it is also modified automatically after - <literal>:load</literal>, <literal>:add</literal>, and - <literal>:reload</literal>, as described above. - The set of modules in scope can be shown with - <literal>:show imports</literal>.</para> - </listitem> - </itemizedlist> - - <para>You can add a module to the scope (via <literal>:module</literal> - or <literal>import</literal>) - only if either (a) it is loaded, or - (b) it is a module from a package that GHCi knows about. - Using <literal>:module</literal> or <literal>import</literal> - to try bring into scope a non-loaded module may result - in the message “<literal>module M is not - loaded</literal>”.</para> - </sect3> - - </sect2> - <sect2> - <title>The <literal>:main</literal> and <literal>:run</literal> commands</title> - - <para> - When a program is compiled and executed, it can use the - <literal>getArgs</literal> function to access the - command-line arguments. - However, we cannot simply pass the arguments to the - <literal>main</literal> function while we are testing in ghci, - as the <literal>main</literal> function doesn't take its - directly. - </para> - - <para> - Instead, we can use the <literal>:main</literal> command. - This runs whatever <literal>main</literal> is in scope, with - any arguments being treated the same as command-line arguments, - e.g.: - </para> - -<screen> -Prelude> let main = System.Environment.getArgs >>= print -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> - </sect2> - - - <sect2> - <title>The <literal>it</literal> variable</title> - <indexterm><primary><literal>it</literal></primary> - </indexterm> - - <para>Whenever an expression (or a non-binding statement, to be - precise) is typed at the prompt, GHCi implicitly binds its value - to the variable <literal>it</literal>. For example:</para> -<screen> -Prelude> 1+2 -3 -Prelude> it * 2 -6 -</screen> - <para>What actually happens is that GHCi typechecks the - expression, and if it doesn't have an <literal>IO</literal> type, - then it transforms it as follows: an expression - <replaceable>e</replaceable> turns into -<screen> -let it = <replaceable>e</replaceable>; -print it -</screen> - which is then run as an IO-action.</para> - - <para>Hence, the original expression must have a type which is an - instance of the <literal>Show</literal> class, or GHCi will - complain:</para> - -<screen> -Prelude> id - -<interactive>:1:0: - No instance for (Show (a -> a)) - arising from use of `print' at <interactive>:1:0-1 - Possible fix: add an instance declaration for (Show (a -> a)) - In the expression: print it - In a 'do' expression: print it -</screen> - - <para>The error message contains some clues as to the - transformation happening internally.</para> - - <para>If the expression was instead of type <literal>IO a</literal> for - some <literal>a</literal>, then <literal>it</literal> will be - bound to the result of the <literal>IO</literal> computation, - which is of type <literal>a</literal>. eg.:</para> -<screen> -Prelude> Time.getClockTime -Wed Mar 14 12:23:13 GMT 2001 -Prelude> print it -Wed Mar 14 12:23:13 GMT 2001 -</screen> - - <para>The corresponding translation for an IO-typed - <replaceable>e</replaceable> is -<screen> -it <- <replaceable>e</replaceable> -</screen> - </para> - - <para>Note that <literal>it</literal> is shadowed by the new - value each time you evaluate a new expression, and the old value - of <literal>it</literal> is lost.</para> - - </sect2> - - <sect2 id="extended-default-rules"> - <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 => String</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 2010 Report) as follows. The - 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 - <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>-XExtendedDefaultRules</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 so that printf - doesn't 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> - <para>See also <xref linkend="actions-at-prompt"/> for how the monad of a computational - expression defaults to <literal>IO</literal> if possible. - </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"> - <title>The GHCi Debugger</title> - <indexterm><primary>debugger</primary><secondary>in GHCi</secondary> - </indexterm> - - <para>GHCi contains a simple imperative-style debugger in which you can - stop a running computation in order to examine the values of - variables. The debugger is integrated into GHCi, and is turned on by - default: no flags are required to enable the debugging - facilities. There is one major restriction: breakpoints and - single-stepping are only available in interpreted modules; - compiled code is invisible to the debugger<footnote><para>Note that packages - only contain compiled code, so debugging a package requires - finding its source and loading that directly.</para></footnote>.</para> - - <para>The debugger provides the following: - <itemizedlist> - <listitem> - <para>The ability to set a <firstterm>breakpoint</firstterm> on a - function definition or expression in the program. When the function - is called, or the expression evaluated, GHCi suspends - execution and returns to the prompt, where you can inspect the - values of local variables before continuing with the - execution.</para> - </listitem> - <listitem> - <para>Execution can be <firstterm>single-stepped</firstterm>: the - evaluator will suspend execution approximately after every - reduction, allowing local variables to be inspected. This is - equivalent to setting a breakpoint at every point in the - program.</para> - </listitem> - <listitem> - <para>Execution can take place in <firstterm>tracing - mode</firstterm>, in which the evaluator remembers each - evaluation step as it happens, but doesn't suspend execution until - an actual breakpoint is reached. When this happens, the history of - evaluation steps can be inspected.</para> - </listitem> - <listitem> - <para>Exceptions (e.g. pattern matching failure and - <literal>error</literal>) can be treated as breakpoints, to help - locate the source of an exception in the program.</para> - </listitem> - </itemizedlist> - </para> - - <para>There is currently no support for obtaining a “stack - trace”, but the tracing and history features provide a - useful second-best, which will often be enough to establish the - context of an error. For instance, it is possible to break - automatically when an exception is thrown, even if it is thrown - from within compiled code (see <xref - linkend="ghci-debugger-exceptions" />).</para> - - <sect2 id="breakpoints"> - <title>Breakpoints and inspecting variables</title> - - <para>Let's use quicksort as a running example. Here's the code:</para> - -<programlisting> -qsort [] = [] -qsort (a:as) = qsort left ++ [a] ++ qsort right - where (left,right) = (filter (<=a) as, filter (>a) as) - -main = print (qsort [8, 4, 0, 3, 1, 23, 11, 18]) -</programlisting> - - <para>First, load the module into GHCi:</para> - -<screen> -Prelude> :l qsort.hs -[1 of 1] Compiling Main ( qsort.hs, interpreted ) -Ok, modules loaded: Main. -*Main> - </screen> - - <para>Now, let's set a breakpoint on the right-hand-side of the second - equation of qsort:</para> - -<programlisting> -*Main> :break 2 -Breakpoint 0 activated at qsort.hs:2:15-46 -*Main> -</programlisting> - - <para>The command <literal>:break 2</literal> sets a breakpoint on line - 2 of the most recently-loaded module, in this case - <literal>qsort.hs</literal>. Specifically, it picks the - leftmost complete subexpression on that line on which to set the - breakpoint, which in this case is the expression - <literal>(qsort left ++ [a] ++ qsort right)</literal>.</para> - - <para>Now, we run the program:</para> - -<programlisting> -*Main> main -Stopped at qsort.hs:2:15-46 -_result :: [a] -a :: a -left :: [a] -right :: [a] -[qsort.hs:2:15-46] *Main> -</programlisting> - - <para>Execution has stopped at the breakpoint. The prompt has changed to - indicate that we are currently stopped at a breakpoint, and the location: - <literal>[qsort.hs:2:15-46]</literal>. To further clarify the - location, we can use the <literal>:list</literal> command:</para> - -<programlisting> -[qsort.hs:2:15-46] *Main> :list -1 qsort [] = [] -2 qsort (a:as) = qsort left ++ [a] ++ qsort right -3 where (left,right) = (filter (<=a) as, filter (>a) as) -</programlisting> - - <para>The <literal>:list</literal> command lists the source code around - the current breakpoint. If your output device supports it, then GHCi - will highlight the active subexpression in bold.</para> - - <para>GHCi has provided bindings for the free variables<footnote><para>We - originally provided bindings for all variables in scope, rather - than just - the free variables of the expression, but found that this affected - performance considerably, hence the current restriction to just the - free variables.</para> - </footnote> of the expression - on which the - breakpoint was placed (<literal>a</literal>, <literal>left</literal>, - <literal>right</literal>), and additionally a binding for the result of - the expression (<literal>_result</literal>). These variables are just - like other variables that you might define in GHCi; you - can use them in expressions that you type at the prompt, you can ask - for their types with <literal>:type</literal>, and so on. There is one - important difference though: these variables may only have partial - types. For example, if we try to display the value of - <literal>left</literal>:</para> - -<screen> -[qsort.hs:2:15-46] *Main> left - -<interactive>:1:0: - Ambiguous type variable `a' in the constraint: - `Show a' arising from a use of `print' at <interactive>:1:0-3 - Cannot resolve unknown runtime types: a - Use :print or :force to determine these types -</screen> - - <para>This is because <literal>qsort</literal> is a polymorphic function, - and because GHCi does not carry type information at runtime, it cannot - determine the runtime types of free variables that involve type - variables. Hence, when you ask to display <literal>left</literal> at - the prompt, GHCi can't figure out which instance of - <literal>Show</literal> to use, so it emits the type error above.</para> - - <para>Fortunately, the debugger includes a generic printing command, - <literal>:print</literal>, which can inspect the actual runtime value of a - variable and attempt to reconstruct its type. If we try it on - <literal>left</literal>:</para> - -<screen> -[qsort.hs:2:15-46] *Main> :set -fprint-evld-with-show -[qsort.hs:2:15-46] *Main> :print left -left = (_t1::[a]) -</screen> - - <para>This isn't particularly enlightening. What happened is that - <literal>left</literal> is bound to an unevaluated computation (a - suspension, or <firstterm>thunk</firstterm>), and - <literal>:print</literal> does not force any evaluation. The idea is - that <literal>:print</literal> can be used to inspect values at a - breakpoint without any unfortunate side effects. It won't force any - evaluation, which could cause the program to give a different answer - than it would normally, and hence it won't cause any exceptions to be - raised, infinite loops, or further breakpoints to be triggered (see - <xref linkend="nested-breakpoints" />). - Rather than forcing thunks, <literal>:print</literal> - binds each thunk to a fresh variable beginning with an - underscore, in this case - <literal>_t1</literal>.</para> - - <para>The flag <literal>-fprint-evld-with-show</literal> instructs - <literal>:print</literal> to reuse - available <literal>Show</literal> instances when possible. This happens - only when the contents of the variable being inspected - are completely evaluated.</para> - - - <para>If we aren't concerned about preserving the evaluatedness of a - variable, we can use <literal>:force</literal> instead of - <literal>:print</literal>. The <literal>:force</literal> command - behaves exactly like <literal>:print</literal>, except that it forces - the evaluation of any thunks it encounters:</para> - -<screen> -[qsort.hs:2:15-46] *Main> :force left -left = [4,0,3,1] -</screen> - - <para>Now, since <literal>:force</literal> has inspected the runtime - value of <literal>left</literal>, it has reconstructed its type. We - can see the results of this type reconstruction:</para> - -<screen> -[qsort.hs:2:15-46] *Main> :show bindings -_result :: [Integer] -a :: Integer -left :: [Integer] -right :: [Integer] -_t1 :: [Integer] -</screen> - - <para>Not only do we now know the type of <literal>left</literal>, but - all the other partial types have also been resolved. So we can ask - for the value of <literal>a</literal>, for example:</para> - -<screen> -[qsort.hs:2:15-46] *Main> a -8 -</screen> - - <para>You might find it useful to use Haskell's - <literal>seq</literal> function to evaluate individual thunks rather - than evaluating the whole expression with <literal>:force</literal>. - For example:</para> - -<screen> -[qsort.hs:2:15-46] *Main> :print right -right = (_t1::[Integer]) -[qsort.hs:2:15-46] *Main> seq _t1 () -() -[qsort.hs:2:15-46] *Main> :print right -right = 23 : (_t2::[Integer]) -</screen> - - <para>We evaluated only the <literal>_t1</literal> thunk, revealing the - head of the list, and the tail is another thunk now bound to - <literal>_t2</literal>. The <literal>seq</literal> function is a - little inconvenient to use here, so you might want to use - <literal>:def</literal> to make a nicer interface (left as an exercise - for the reader!).</para> - - <para>Finally, we can continue the current execution:</para> - -<screen> -[qsort.hs:2:15-46] *Main> :continue -Stopped at qsort.hs:2:15-46 -_result :: [a] -a :: a -left :: [a] -right :: [a] -[qsort.hs:2:15-46] *Main> -</screen> - - <para>The execution continued at the point it previously stopped, and has - now stopped at the breakpoint for a second time.</para> - - - <sect3 id="setting-breakpoints"> - <title>Setting breakpoints</title> - - <para>Breakpoints can be set in various ways. Perhaps the easiest way to - set a breakpoint is to name a top-level function:</para> - -<screen> - :break <replaceable>identifier</replaceable> -</screen> - - <para>Where <replaceable>identifier</replaceable> names any top-level - function in an interpreted module currently loaded into GHCi (qualified - names may be used). The breakpoint will be set on the body of the - function, when it is fully applied but before any pattern matching has - taken place.</para> - - <para>Breakpoints can also be set by line (and optionally column) - number:</para> - -<screen> - :break <replaceable>line</replaceable> - :break <replaceable>line</replaceable> <replaceable>column</replaceable> - :break <replaceable>module</replaceable> <replaceable>line</replaceable> - :break <replaceable>module</replaceable> <replaceable>line</replaceable> <replaceable>column</replaceable> -</screen> - - <para>When a breakpoint is set on a particular line, GHCi sets the - breakpoint on the - leftmost subexpression that begins and ends on that line. If two - complete subexpressions start at the same - column, the longest one is picked. If there is no complete - subexpression on the line, then the leftmost expression starting on - the line is picked, and failing that the rightmost expression that - partially or completely covers the line.</para> - - <para>When a breakpoint is set on a particular line and column, GHCi - picks the smallest subexpression that encloses that location on which - to set the breakpoint. Note: GHC considers the TAB character to have a - width of 1, wherever it occurs; in other words it counts - characters, rather than columns. This matches what some editors do, - and doesn't match others. The best advice is to avoid tab - characters in your source code altogether (see - <option>-fwarn-tabs</option> in <xref linkend="options-sanity" - />).</para> - - <para>If the module is omitted, then the most recently-loaded module is - used.</para> - - <para>Not all subexpressions are potential breakpoint locations. Single - variables are typically not considered to be breakpoint locations - (unless the variable is the right-hand-side of a function definition, - lambda, or case alternative). The rule of thumb is that all redexes - are breakpoint locations, together with the bodies of functions, - lambdas, case alternatives and binding statements. There is normally - no breakpoint on a let expression, but there will always be a - breakpoint on its body, because we are usually interested in inspecting - the values of the variables bound by the let.</para> - - </sect3> - <sect3> - <title>Listing and deleting breakpoints</title> - - <para>The list of breakpoints currently enabled can be displayed using - <literal>:show breaks</literal>:</para> -<screen> -*Main> :show breaks -[0] Main qsort.hs:1:11-12 -[1] Main qsort.hs:2:15-46 -</screen> - - <para>To delete a breakpoint, use the <literal>:delete</literal> - command with the number given in the output from <literal>:show breaks</literal>:</para> - -<screen> -*Main> :delete 0 -*Main> :show breaks -[1] Main qsort.hs:2:15-46 -</screen> - - <para>To delete all breakpoints at once, use <literal>:delete *</literal>.</para> - - </sect3> - </sect2> - - <sect2 id="single-stepping"> - <title>Single-stepping</title> - - <para>Single-stepping is a great way to visualise the execution of your - program, and it is also a useful tool for identifying the source of a - bug. GHCi offers two variants of stepping. Use - <literal>:step</literal> to enable all the - breakpoints in the program, and execute until the next breakpoint is - reached. Use <literal>:steplocal</literal> to limit the set - of enabled breakpoints to those in the current top level function. - Similarly, use <literal>:stepmodule</literal> to single step only on - breakpoints contained in the current module. - For example:</para> - -<screen> -*Main> :step main -Stopped at qsort.hs:5:7-47 -_result :: IO () -</screen> - - <para>The command <literal>:step - <replaceable>expr</replaceable></literal> begins the evaluation of - <replaceable>expr</replaceable> in single-stepping mode. If - <replaceable>expr</replaceable> is omitted, then it single-steps from - the current breakpoint. <literal>:steplocal</literal> and - <literal>:stepmodule</literal> work similarly.</para> - - <para>The <literal>:list</literal> command is particularly useful when - single-stepping, to see where you currently are:</para> - -<screen> -[qsort.hs:5:7-47] *Main> :list -4 -5 main = print (qsort [8, 4, 0, 3, 1, 23, 11, 18]) -6 -[qsort.hs:5:7-47] *Main> -</screen> - - <para>In fact, GHCi provides a way to run a command when a breakpoint is - hit, so we can make it automatically do - <literal>:list</literal>:</para> - -<screen> -[qsort.hs:5:7-47] *Main> :set stop :list -[qsort.hs:5:7-47] *Main> :step -Stopped at qsort.hs:5:14-46 -_result :: [Integer] -4 -5 main = print (qsort [8, 4, 0, 3, 1, 23, 11, 18]) -6 -[qsort.hs:5:14-46] *Main> -</screen> - </sect2> - - <sect2 id="nested-breakpoints"> - <title>Nested breakpoints</title> - <para>When GHCi is stopped at a breakpoint, and an expression entered at - the prompt triggers a - second breakpoint, the new breakpoint becomes the “current” - one, and the old one is saved on a stack. An arbitrary number of - breakpoint contexts can be built up in this way. For example:</para> - -<screen> -[qsort.hs:2:15-46] *Main> :st qsort [1,3] -Stopped at qsort.hs:(1,0)-(3,55) -_result :: [a] -... [qsort.hs:(1,0)-(3,55)] *Main> -</screen> - - <para>While stopped at the breakpoint on line 2 that we set earlier, we - started a new evaluation with <literal>:step qsort [1,3]</literal>. - This new evaluation stopped after one step (at the definition of - <literal>qsort</literal>). The prompt has changed, now prefixed with - <literal>...</literal>, to indicate that there are saved breakpoints - beyond the current one. To see the stack of contexts, use - <literal>:show context</literal>:</para> - -<screen> -... [qsort.hs:(1,0)-(3,55)] *Main> :show context ---> main - Stopped at qsort.hs:2:15-46 ---> qsort [1,3] - Stopped at qsort.hs:(1,0)-(3,55) -... [qsort.hs:(1,0)-(3,55)] *Main> -</screen> - - <para>To abandon the current evaluation, use - <literal>:abandon</literal>:</para> - -<screen> -... [qsort.hs:(1,0)-(3,55)] *Main> :abandon -[qsort.hs:2:15-46] *Main> :abandon -*Main> -</screen> - </sect2> - - <sect2 id="ghci-debugger-result"> - <title>The <literal>_result</literal> variable</title> - <para>When stopped at a breakpoint or single-step, GHCi binds the - variable <literal>_result</literal> to the value of the currently - active expression. The value of <literal>_result</literal> is - presumably not available yet, because we stopped its evaluation, but it - can be forced: if the type is known and showable, then just entering - <literal>_result</literal> at the prompt will show it. However, - there's one caveat to doing this: evaluating <literal>_result</literal> - will be likely to trigger further breakpoints, starting with the - breakpoint we are currently stopped at (if we stopped at a real - breakpoint, rather than due to <literal>:step</literal>). So it will - probably be necessary to issue a <literal>:continue</literal> - immediately when evaluating <literal>_result</literal>. Alternatively, - you can use <literal>:force</literal> which ignores breakpoints.</para> - </sect2> - - <sect2 id="tracing"> - <title>Tracing and history</title> - - <para>A question that we often want to ask when debugging a program is - “how did I get here?”. Traditional imperative debuggers - usually provide some kind of stack-tracing feature that lets you see - the stack of active function calls (sometimes called the “lexical - call stack”), describing a path through the code - to the current location. Unfortunately this is hard to provide in - Haskell, because execution proceeds on a demand-driven basis, rather - than a depth-first basis as in strict languages. The - “stack“ in GHC's execution engine bears little - resemblance to the lexical call stack. Ideally GHCi would maintain a - separate lexical call stack in addition to the dynamic call stack, and - in fact this is exactly - what our profiling system does (<xref linkend="profiling" />), and what - some other Haskell debuggers do. For the time being, however, GHCi - doesn't maintain a lexical call stack (there are some technical - challenges to be overcome). Instead, we provide a way to backtrack from a - breakpoint to previous evaluation steps: essentially this is like - single-stepping backwards, and should in many cases provide enough - information to answer the “how did I get here?” - question.</para> - - <para>To use tracing, evaluate an expression with the - <literal>:trace</literal> command. For example, if we set a breakpoint - on the base case of <literal>qsort</literal>:</para> - -<screen> -*Main> :list qsort -1 qsort [] = [] -2 qsort (a:as) = qsort left ++ [a] ++ qsort right -3 where (left,right) = (filter (<=a) as, filter (>a) as) -4 -*Main> :b 1 -Breakpoint 1 activated at qsort.hs:1:11-12 -*Main> -</screen> - - <para>and then run a small <literal>qsort</literal> with - tracing:</para> - -<screen> -*Main> :trace qsort [3,2,1] -Stopped at qsort.hs:1:11-12 -_result :: [a] -[qsort.hs:1:11-12] *Main> -</screen> - - <para>We can now inspect the history of evaluation steps:</para> - -<screen> -[qsort.hs:1:11-12] *Main> :hist --1 : qsort.hs:3:24-38 --2 : qsort.hs:3:23-55 --3 : qsort.hs:(1,0)-(3,55) --4 : qsort.hs:2:15-24 --5 : qsort.hs:2:15-46 --6 : qsort.hs:3:24-38 --7 : qsort.hs:3:23-55 --8 : qsort.hs:(1,0)-(3,55) --9 : qsort.hs:2:15-24 --10 : qsort.hs:2:15-46 --11 : qsort.hs:3:24-38 --12 : qsort.hs:3:23-55 --13 : qsort.hs:(1,0)-(3,55) --14 : qsort.hs:2:15-24 --15 : qsort.hs:2:15-46 --16 : qsort.hs:(1,0)-(3,55) -<end of history> -</screen> - - <para>To examine one of the steps in the history, use - <literal>:back</literal>:</para> - -<screen> -[qsort.hs:1:11-12] *Main> :back -Logged breakpoint at qsort.hs:3:24-38 -_result :: [a] -as :: [a] -a :: a -[-1: qsort.hs:3:24-38] *Main> -</screen> - - <para>Note that the local variables at each step in the history have been - preserved, and can be examined as usual. Also note that the prompt has - changed to indicate that we're currently examining the first step in - the history: <literal>-1</literal>. The command - <literal>:forward</literal> can be used to traverse forward in the - history.</para> - - <para>The <literal>:trace</literal> command can be used with or without - an expression. When used without an expression, tracing begins from - the current breakpoint, just like <literal>:step</literal>.</para> - - <para>The history is only available when - using <literal>:trace</literal>; the reason for this is we found that - logging each breakpoint in the history cuts performance by a factor of - 2 or more. By default, GHCi remembers the last 50 steps in the history, but this can be changed with the <option>-fghci-hist-size=<replaceable>n</replaceable></option><indexterm><primary><option>-fghci-hist-size</option></primary></indexterm> option).</para> - </sect2> - - <sect2 id="ghci-debugger-exceptions"> - <title>Debugging exceptions</title> - <para>Another common question that comes up when debugging is - “where did this exception come from?”. Exceptions such as - those raised by <literal>error</literal> or <literal>head []</literal> - have no context information attached to them. Finding which - particular call to <literal>head</literal> in your program resulted in - the error can be a painstaking process, usually involving - <literal>Debug.Trace.trace</literal>, or compiling with - profiling and using <literal>Debug.Trace.traceStack</literal> - or <literal>+RTS -xc</literal> (see <xref - linkend="prof-time-options" />).</para> - - <para>The GHCi debugger offers a way to hopefully shed some light on - these errors quickly and without modifying or recompiling the source - code. One way would be to set a breakpoint on the location in the - source code that throws the exception, and then use - <literal>:trace</literal> and <literal>:history</literal> to establish - the context. However, <literal>head</literal> is in a library and - we can't set a breakpoint on it directly. For this reason, GHCi - provides the flags <literal>-fbreak-on-exception</literal> which causes - the evaluator to stop when an exception is thrown, and <literal> - -fbreak-on-error</literal>, which works similarly but stops only on - uncaught exceptions. When stopping at an exception, GHCi will act - just as it does when a breakpoint is hit, with the deviation that it - will not show you any source code location. Due to this, these - commands are only really useful in conjunction with - <literal>:trace</literal>, in order to log the steps leading up to the - exception. For example:</para> - -<screen> -*Main> :set -fbreak-on-exception -*Main> :trace qsort ("abc" ++ undefined) -“Stopped at <exception thrown> -_exception :: e -[<exception thrown>] *Main> :hist --1 : qsort.hs:3:24-38 --2 : qsort.hs:3:23-55 --3 : qsort.hs:(1,0)-(3,55) --4 : qsort.hs:2:15-24 --5 : qsort.hs:2:15-46 --6 : qsort.hs:(1,0)-(3,55) -<end of history> -[<exception thrown>] *Main> :back -Logged breakpoint at qsort.hs:3:24-38 -_result :: [a] -as :: [a] -a :: a -[-1: qsort.hs:3:24-38] *Main> :force as -*** Exception: Prelude.undefined -[-1: qsort.hs:3:24-38] *Main> :print as -as = 'b' : 'c' : (_t1::[Char]) -</screen> - - <para>The exception itself is bound to a new variable, - <literal>_exception</literal>.</para> - - <para>Breaking on exceptions is particularly useful for finding out what - your program was doing when it was in an infinite loop. Just hit - Control-C, and examine the history to find out what was going - on.</para> - </sect2> - - <sect2><title>Example: inspecting functions</title> - <para> - It is possible to use the debugger to examine function values. - When we are at a breakpoint and a function is in scope, the debugger - cannot show - you the source code for it; however, it is possible to get some - information by applying it to some arguments and observing the result. - </para> - - <para> - The process is slightly complicated when the binding is polymorphic. - We show the process by means of an example. - To keep things simple, we will use the well known <literal>map</literal> function: -<programlisting> -import Prelude hiding (map) - -map :: (a->b) -> [a] -> [b] -map f [] = [] -map f (x:xs) = f x : map f xs -</programlisting> - </para> - - <para> - We set a breakpoint on <literal>map</literal>, and call it. -<screen> -*Main> :break 5 -Breakpoint 0 activated at map.hs:5:15-28 -*Main> map Just [1..5] -Stopped at map.hs:(4,0)-(5,12) -_result :: [b] -x :: a -f :: a -> b -xs :: [a] -</screen> - GHCi tells us that, among other bindings, <literal>f</literal> is in scope. - However, its type is not fully known yet, - and thus it is not possible to apply it to any - arguments. Nevertheless, observe that the type of its first argument is the - same as the type of <literal>x</literal>, and its result type is shared - with <literal>_result</literal>. - </para> - - <para> - As we demonstrated earlier (<xref linkend="breakpoints" />), the - debugger has some intelligence built-in to update the type of - <literal>f</literal> whenever the types of <literal>x</literal> or - <literal>_result</literal> are discovered. So what we do in this - scenario is - force <literal>x</literal> a bit, in order to recover both its type - and the argument part of <literal>f</literal>. -<screen> -*Main> seq x () -*Main> :print x -x = 1 -</screen> - </para> - <para> - We can check now that as expected, the type of <literal>x</literal> - has been reconstructed, and with it the - type of <literal>f</literal> has been too:</para> -<screen> -*Main> :t x -x :: Integer -*Main> :t f -f :: Integer -> b -</screen> - <para> - From here, we can apply f to any argument of type Integer and observe - the results. -<screen><![CDATA[ -*Main> let b = f 10 -*Main> :t b -b :: b -*Main> b -<interactive>:1:0: - Ambiguous type variable `b' in the constraint: - `Show b' arising from a use of `print' at <interactive>:1:0 -*Main> :p b -b = (_t2::a) -*Main> seq b () -() -*Main> :t b -b :: a -*Main> :p b -b = Just 10 -*Main> :t b -b :: Maybe Integer -*Main> :t f -f :: Integer -> Maybe Integer -*Main> f 20 -Just 20 -*Main> map f [1..5] -[Just 1, Just 2, Just 3, Just 4, Just 5] -]]></screen> - In the first application of <literal>f</literal>, we had to do - some more type reconstruction - in order to recover the result type of <literal>f</literal>. - But after that, we are free to use - <literal>f</literal> normally. - </para> - </sect2> - - <sect2><title>Limitations</title> - <itemizedlist> - <listitem> - <para>When stopped at a breakpoint, if you try to evaluate a variable - that is already under evaluation, the second evaluation will hang. - The reason is - that GHC knows the variable is under evaluation, so the new - evaluation just waits for the result before continuing, but of - course this isn't going to happen because the first evaluation is - stopped at a breakpoint. Control-C can interrupt the hung - evaluation and return to the prompt.</para> - <para>The most common way this can happen is when you're evaluating a - CAF (e.g. main), stop at a breakpoint, and ask for the value of the - CAF at the prompt again.</para> - </listitem> - <listitem><para> - Implicit parameters (see <xref linkend="implicit-parameters"/>) are only available - at the scope of a breakpoint if there is an explicit type signature. - </para> - </listitem> - </itemizedlist> - </sect2> - </sect1> - - <sect1 id="ghci-invocation"> - <title>Invoking GHCi</title> - <indexterm><primary>invoking</primary><secondary>GHCi</secondary></indexterm> - <indexterm><primary><option>--interactive</option></primary></indexterm> - - <para>GHCi is invoked with the command <literal>ghci</literal> or - <literal>ghc --interactive</literal>. One or more modules or - filenames can also be specified on the command line; this - instructs GHCi to load the specified modules or filenames (and all - the modules they depend on), just as if you had said - <literal>:load <replaceable>modules</replaceable></literal> at the - GHCi prompt (see <xref linkend="ghci-commands" />). For example, to - start GHCi and load the program whose topmost module is in the - file <literal>Main.hs</literal>, we could say:</para> - -<screen> -$ ghci Main.hs -</screen> - - <para>Most of the command-line options accepted by GHC (see <xref - linkend="using-ghc"/>) also make sense in interactive mode. The ones - that don't make sense are mostly obvious.</para> - - <sect2> - <title>Packages</title> - <indexterm><primary>packages</primary><secondary>with GHCi</secondary></indexterm> - - <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 hidden packages, however, you need to request the - package be loaded by using the <literal>-package</literal> flag:</para> - -<screen> -$ ghci -package readline -GHCi, version 6.8.1: http://www.haskell.org/ghc/ :? for help -Loading package base ... linking ... done. -Loading package readline-1.0 ... linking ... done. -Prelude> -</screen> - - <para>The following command works to load new packages into a - running GHCi:</para> - -<screen> -Prelude> :set -package <replaceable>name</replaceable> -</screen> - - <para>But note that doing this will cause all currently loaded - modules to be unloaded, and you'll be dumped back into the - <literal>Prelude</literal>.</para> - </sect2> - - <sect2> - <title>Extra libraries</title> - <indexterm><primary>libraries</primary><secondary>with GHCi</secondary></indexterm> - - <para>Extra libraries may be specified on the command line using - the normal <literal>-l<replaceable>lib</replaceable></literal> - 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 “m” library:</para> - -<screen> -$ ghci -lm -</screen> - - <para>On systems with <literal>.so</literal>-style shared - libraries, the actual library loaded will the - <filename>lib<replaceable>lib</replaceable>.so</filename>. GHCi - searches the following places for libraries, in this order:</para> - - <itemizedlist> - <listitem> - <para>Paths specified using the - <literal>-L<replaceable>path</replaceable></literal> - command-line option,</para> - </listitem> - <listitem> - <para>the standard library search path for your system, - which on some systems may be overridden by setting the - <literal>LD_LIBRARY_PATH</literal> environment - variable.</para> - </listitem> - </itemizedlist> - - <para>On systems with <literal>.dll</literal>-style shared - libraries, the actual library loaded will be - <filename><replaceable>lib</replaceable>.dll</filename>. Again, - GHCi will signal an error if it can't find the library.</para> - - <para>GHCi can also load plain object files - (<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> - - <sect1 id="ghci-commands"> - <title>GHCi commands</title> - - <para>GHCi commands all begin with - ‘<literal>:</literal>’ and consist of a single command - name followed by zero or more parameters. The command name may be - abbreviated, with ambiguities being resolved in favour of the more - commonly used commands.</para> - - <variablelist> - <varlistentry> - <term> - <literal>:abandon</literal> - <indexterm><primary><literal>:abandon</literal></primary></indexterm> - </term> - <listitem> - <para>Abandons the current evaluation (only available when stopped at - a breakpoint).</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <literal>:add</literal> <optional><literal>*</literal></optional><replaceable>module</replaceable> ... - <indexterm><primary><literal>:add</literal></primary></indexterm> - </term> - <listitem> - <para>Add <replaceable>module</replaceable>(s) to the - current <firstterm>target set</firstterm>, and perform a - reload. Normally pre-compiled code for the module will be - loaded if available, or otherwise the module will be - compiled to byte-code. Using the <literal>*</literal> - prefix forces the module to be loaded as byte-code.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <literal>:back <optional><replaceable>n</replaceable></optional></literal> - <indexterm><primary><literal>:back</literal></primary></indexterm> - </term> - <listitem> - <para>Travel back <replaceable>n</replaceable> steps in the - history. <replaceable>n</replaceable> is one if omitted. - See <xref linkend="tracing" /> for more about GHCi's debugging - facilities. See also: - <literal>:trace</literal>, <literal>:history</literal>, - <literal>:forward</literal>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <literal>:break [<replaceable>identifier</replaceable> | - [<replaceable>module</replaceable>] <replaceable>line</replaceable> - [<replaceable>column</replaceable>]]</literal> - </term> - <indexterm><primary><literal>:break</literal></primary></indexterm> - <listitem> - <para>Set a breakpoint on the specified function or line and - column. See <xref linkend="setting-breakpoints" />.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <literal>:browse</literal><optional><literal>!</literal></optional> <optional><optional><literal>*</literal></optional><replaceable>module</replaceable></optional> ... - <indexterm><primary><literal>:browse</literal></primary></indexterm> - </term> - <listitem> - <para>Displays the identifiers exported by the module - <replaceable>module</replaceable>, which must be either - loaded into GHCi or be a member of a package. If - <replaceable>module</replaceable> is omitted, the most - recently-loaded module is used.</para> - - <para>Like all other GHCi commands, the output is always - displayed in the current GHCi scope (<xref linkend="ghci-scope"/>).</para> - - <para>There are two variants of the browse command: - <itemizedlist> - <listitem> - <para>If the <literal>*</literal> symbol is placed before - the module name, then <emphasis>all</emphasis> the - identifiers in scope in <replaceable>module</replaceable> - (rather that just its exports) are shown. </para> - - <para>The <literal>*</literal>-form is only available for modules - which are interpreted; for compiled modules (including - modules from packages) only the non-<literal>*</literal> - form of <literal>:browse</literal> is available.</para> - </listitem> - <listitem> - <para>Data constructors and class methods are usually - displayed in the context of their data type or class declaration. - However, if the <literal>!</literal> symbol is appended to the - command, thus <literal>:browse!</literal>, - they are listed individually. - The <literal>!</literal>-form also annotates the listing - with comments giving possible imports for each group of - entries. Here is an example: -<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> - This output shows that, in the context of the current session (ie in the scope - of <literal>Prelude</literal>), the first group of items from - <literal>Data.Maybe</literal> are not in scope (althought they are available in - fully qualified form in the GHCi session - see <xref - linkend="ghci-scope"/>), whereas the second group of items are in scope - (via <literal>Prelude</literal>) and are therefore available either - unqualified, or with a <literal>Prelude.</literal> qualifier. - </para> - </listitem> - </itemizedlist> - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <literal>:cd</literal> <replaceable>dir</replaceable> - <indexterm><primary><literal>:cd</literal></primary></indexterm> - </term> - <listitem> - <para>Changes the current working directory to - <replaceable>dir</replaceable>. A - ‘<literal>˜</literal>’ symbol at the - beginning of <replaceable>dir</replaceable> will be replaced - by the contents of the environment variable - <literal>HOME</literal>. - See also the <literal>:show paths</literal> command for - showing the current working directory.</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> - - <varlistentry> - <term> - <literal>:cmd</literal> <replaceable>expr</replaceable> - <indexterm><primary><literal>:cmd</literal></primary></indexterm> - </term> - <listitem> - <para>Executes <replaceable>expr</replaceable> as a computation of - type <literal>IO String</literal>, and then executes the resulting - string as a list of GHCi commands. Multiple commands are separated - by newlines. The <literal>:cmd</literal> command is useful with - <literal>:def</literal> and <literal>:set stop</literal>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <literal>:complete</literal> <replaceable>type</replaceable> - <optional><replaceable>n</replaceable>-</optional><optional><replaceable>m</replaceable></optional> - <replaceable>string-literal</replaceable> - <indexterm><primary><literal>:complete</literal></primary></indexterm> - </term> - <listitem> - <para>This command allows to request command completions - from GHCi even when interacting over a pipe instead of a - proper terminal and is designed for integrating GHCi's - completion with text editors and IDEs.</para> - - <para>When called, <literal>:complete</literal> prints the - <replaceable>n</replaceable><superscript>th</superscript> to - <replaceable>m</replaceable><superscript>th</superscript> - completion candidates for the partial input - <replaceable>string-literal</replaceable> for the completion - domain denoted by - <replaceable>type</replaceable>. Currently, only the - <literal>repl</literal> domain is supported which denotes - the kind of completion that would be provided interactively - by GHCi at the input prompt.</para> - - <para>If omitted, <replaceable>n</replaceable> and - <replaceable>m</replaceable> default to the first or last - available completion candidate respectively. If there are - less candidates than requested via the range argument, - <replaceable>n</replaceable> and - <replaceable>m</replaceable> are implicitly capped to the - number of available completition candidates.</para> - - <para>The output of <literal>:complete</literal> begins with - a header line containing three space-delimited fields: - - <itemizedlist> - <listitem>An integer denoting the number - <replaceable>l</replaceable> of printed - completions,</listitem> - - <listitem>an integer denoting the total number of - completions available, and finally</listitem> - - <listitem>a string literal denoting a common - prefix to be added to the returned completion - candidates.</listitem> - </itemizedlist> - - The header line is followed by <replaceable>l</replaceable> - lines each containing one completion candidate encoded as - (quoted) string literal. Here are some example invocations - showing the various cases:</para> - -<screen> -Prelude> :complete repl 0 "" -0 470 "" -Prelude> :complete repl 5 "import For" -5 21 "import " -"Foreign" -"Foreign.C" -"Foreign.C.Error" -"Foreign.C.String" -"Foreign.C.Types" -Prelude> :complete repl 5-10 "import For" -6 21 "import " -"Foreign.C.Types" -"Foreign.Concurrent" -"Foreign.ForeignPtr" -"Foreign.ForeignPtr.Safe" -"Foreign.ForeignPtr.Unsafe" -"Foreign.Marshal" -Prelude> :complete repl 20- "import For" -2 21 "import " -"Foreign.StablePtr" -"Foreign.Storable" -Prelude> :complete repl "map" -3 3 "" -"map" -"mapM" -"mapM_" -Prelude> :complete repl 5-10 "map" -0 3 "" -</screen> - - </listitem> - </varlistentry> - - <varlistentry> - <term> - <literal>:continue</literal> - <indexterm><primary><literal>:continue</literal></primary></indexterm> - </term> - <listitem><para>Continue the current evaluation, when stopped at a - breakpoint.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <literal>:ctags</literal> <optional><replaceable>filename</replaceable></optional> - <literal>:etags</literal> <optional><replaceable>filename</replaceable></optional> - <indexterm><primary><literal>:etags</literal></primary> - </indexterm> - <indexterm><primary><literal>:etags</literal></primary> - </indexterm> - </term> - <listitem> - <para>Generates a “tags” file for Vi-style editors - (<literal>:ctags</literal>) or - Emacs-style editors (<literal>:etags</literal>). If - no filename is specified, the default <filename>tags</filename> or - <filename>TAGS</filename> is - used, respectively. Tags for all the functions, constructors and - types in the currently loaded modules are created. All modules must - be interpreted for these commands to work.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <literal>:def<optional>!</optional> <optional><replaceable>name</replaceable> <replaceable>expr</replaceable></optional></literal> - <indexterm><primary><literal>:def</literal></primary></indexterm> - </term> - <listitem> - <para><literal>:def</literal> is used to define new - commands, or macros, in GHCi. The command - <literal>:def</literal> <replaceable>name</replaceable> - <replaceable>expr</replaceable> defines a new GHCi command - <literal>:<replaceable>name</replaceable></literal>, - implemented by the Haskell expression - <replaceable>expr</replaceable>, which must have type - <literal>String -> IO String</literal>. When - <literal>:<replaceable>name</replaceable> - <replaceable>args</replaceable></literal> is typed at the - prompt, GHCi will run the expression - <literal>(<replaceable>name</replaceable> - <replaceable>args</replaceable>)</literal>, take the - resulting <literal>String</literal>, and feed it back into - GHCi as a new sequence of commands. Separate commands in - the result must be separated by - ‘<literal>\n</literal>’.</para> - - <para>That's all a little confusing, so here's a few - examples. To start with, here's a new GHCi command which - doesn't take any arguments or produce any results, it just - outputs the current date & time:</para> - -<screen> -Prelude> let date _ = Time.getClockTime >>= print >> return "" -Prelude> :def date date -Prelude> :date -Fri Mar 23 15:16:40 GMT 2001 -</screen> - - <para>Here's an example of a command that takes an argument. - It's a re-implementation of <literal>:cd</literal>:</para> - -<screen> -Prelude> let mycd d = Directory.setCurrentDirectory d >> return "" -Prelude> :def mycd mycd -Prelude> :mycd .. -</screen> - - <para>Or I could define a simple way to invoke - “<literal>ghc --make Main</literal>” in the - current directory:</para> - -<screen> -Prelude> :def make (\_ -> return ":! ghc --make Main") -</screen> - - <para>We can define a command that reads GHCi input from a - file. This might be useful for creating a set of bindings - that we want to repeatedly load into the GHCi session:</para> - -<screen> -Prelude> :def . readFile -Prelude> :. cmds.ghci -</screen> - - <para>Notice that we named the command - <literal>:.</literal>, by analogy with the - ‘<literal>.</literal>’ Unix shell command that - does the same thing.</para> - - <para>Typing <literal>:def</literal> on its own lists the - currently-defined macros. Attempting to redefine an - existing command name results in an error unless the - <literal>:def!</literal> form is used, in which case the old - command with that name is silently overwritten.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <literal>:delete * | <replaceable>num</replaceable> ...</literal> - <indexterm><primary><literal>:delete</literal></primary></indexterm> - </term> - <listitem> - <para>Delete one or more breakpoints by number (use <literal>:show - breaks</literal> to see the number of each breakpoint). The - <literal>*</literal> form deletes all the breakpoints.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <literal>:edit <optional><replaceable>file</replaceable></optional></literal> - <indexterm><primary><literal>:edit</literal></primary></indexterm> - </term> - <listitem> - <para>Opens an editor to edit the file - <replaceable>file</replaceable>, or the most recently loaded - module if <replaceable>file</replaceable> is omitted. - If there were errors during the last loading, - the cursor will be positioned at the line of the first error. The - editor to invoke is taken from the <literal>EDITOR</literal> - environment variable, or a default editor on your system if - <literal>EDITOR</literal> is not set. You can change the - editor using <literal>:set editor</literal>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <literal>:etags</literal> - </term> - <listitem> - <para>See <literal>:ctags</literal>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <literal>:force <replaceable>identifier</replaceable> ...</literal> - <indexterm><primary><literal>:force</literal></primary></indexterm> - </term> - <listitem> - <para>Prints the value of <replaceable>identifier</replaceable> in - the same way as <literal>:print</literal>. Unlike - <literal>:print</literal>, <literal>:force</literal> evaluates each - thunk that it encounters while traversing the value. This may - cause exceptions or infinite loops, or further breakpoints (which - are ignored, but displayed).</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <literal>:forward <optional><replaceable>n</replaceable></optional></literal> - <indexterm><primary><literal>:forward</literal></primary></indexterm> - </term> - <listitem> - <para>Move forward <replaceable>n</replaceable> steps in the - history. <replaceable>n</replaceable> is one if omitted. - See <xref linkend="tracing" /> for more about GHCi's debugging - facilities. See also: - <literal>:trace</literal>, <literal>:history</literal>, - <literal>:back</literal>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <literal>:help</literal> - <indexterm><primary><literal>:help</literal></primary></indexterm> - </term> - <term> - <literal>:?</literal> - <indexterm><primary><literal>:?</literal></primary></indexterm> - </term> - <listitem> - <para>Displays a list of the available commands.</para> - </listitem> - </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> - </term> - <listitem> - <para>Display the history of evaluation steps. With a - number, displays that many steps (default: 20). For use - with <literal>:trace</literal>; see <xref linkend="tracing" - />. To set the number of history entries stored by GHCi, - use - <option>-fghci-hist-size=<replaceable>n</replaceable></option>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <literal>:info</literal><optional><literal>!</literal></optional><replaceable>name</replaceable> ... - <indexterm><primary><literal>:info</literal></primary></indexterm> - </term> - <listitem> - <para>Displays information about the given name(s). For - example, if <replaceable>name</replaceable> is a class, then - the class methods and their types will be printed; if - <replaceable>name</replaceable> is a type constructor, then - its definition will be printed; if - <replaceable>name</replaceable> is a function, then its type - will be printed. If <replaceable>name</replaceable> has - been loaded from a source file, then GHCi will also display - the location of its definition in the source.</para> - <para>For types and classes, GHCi also summarises instances that - mention them. To avoid showing irrelevant information, an instance - is shown only if (a) its head mentions <replaceable>name</replaceable>, - and (b) all the other things mentioned in the instance - are in scope (either qualified or otherwise) as a result of - a <literal>:load</literal> or <literal>:module</literal> commands. </para> - <para> - The command <literal>:info!</literal> works in a similar fashion - but it removes restriction (b), showing all instances that are in - scope and mention <replaceable>name</replaceable> in their head. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <literal>:issafe</literal><optional><replaceable>module</replaceable></optional> - <indexterm><primary><literal>:issafe</literal></primary></indexterm> - </term> - <listitem> - <para>Displays Safe Haskell information about the given - module (or the current module if omitted). This includes the trust - type of the module and its containing package.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <literal>:kind</literal><optional><literal>!</literal></optional> - <replaceable>type</replaceable> - <indexterm><primary><literal>:kind</literal></primary></indexterm> - </term> - <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>. In fact, <literal>:kind</literal> - even allows you to write a partial application of a type synonym (usually disallowed), - so that this works: -<programlisting> -ghci> type T a b = (a,b,a) -ghci> :k T Int Bool -T Int Bool :: * -ghci> :k T -T :: * -> * -> * -ghci> :k T Int -T Int :: * -> * -</programlisting> - </para> - <para> - If you specify the - optional "<literal>!</literal>", GHC will in addition normalise the type - by expanding out type synonyms and evaluating type-function applications, - and display the normalised result.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <literal>:list</literal> <replaceable>identifier</replaceable> - <indexterm><primary><literal>:list</literal></primary></indexterm> - </term> - <listitem> - <para>Lists the source code around the definition of - <replaceable>identifier</replaceable> or the current - breakpoint if not given. This requires that the identifier be - defined in an interpreted module. If your output device - supports it, then GHCi will highlight the active - subexpression in bold.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <literal>:list</literal> <optional><replaceable>module</replaceable></optional> <replaceable>line</replaceable> - <indexterm><primary><literal>:list</literal></primary></indexterm> - </term> - <listitem> - <para>Lists the source code around the given line number of - <replaceable>module</replaceable>. This requires that the module be - interpreted. If your output device supports it, then GHCi will - highlight the active subexpression in bold.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <literal>:load</literal><optional><literal>!</literal></optional> <optional><literal>*</literal></optional><replaceable>module</replaceable> ... - <indexterm><primary><literal>:load</literal></primary></indexterm> - </term> - <listitem> - <para>Recursively loads the specified - <replaceable>module</replaceable>s, and all the modules they - depend on. Here, each <replaceable>module</replaceable> - must be a module name or filename, but may not be the name - of a module in a package.</para> - - <para>All previously loaded modules, except package modules, - are forgotten. The new set of modules is known as the - <firstterm>target set</firstterm>. Note that - <literal>:load</literal> can be used without any arguments - to unload all the currently loaded modules and - bindings.</para> - - <para>Normally pre-compiled code for a module will be loaded - if available, or otherwise the module will be compiled to - byte-code. Using the <literal>*</literal> prefix forces a - module to be loaded as byte-code.</para> - - <para>Adding the optional "<literal>!</literal>" turns type - errors into warnings while loading. This allows to use the - portions of the module that are correct, even if there are - type errors in some definitions. Effectively, the - "-fdefer-type-errors" flag is set before loading and unset - after loading if the flag has not already been set - before. See <xref linkend="defer-type-errors" /> for further - motivation and details.</para> - - <para>After a <literal>:load</literal> command, the current - context is set to:</para> - - <itemizedlist> - <listitem> - <para><replaceable>module</replaceable>, if it was loaded - successfully, or</para> - </listitem> - <listitem> - <para>the most recently successfully loaded module, if - any other modules were loaded as a result of the current - <literal>:load</literal>, or</para> - </listitem> - <listitem> - <para><literal>Prelude</literal> otherwise.</para> - </listitem> - </itemizedlist> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <literal>:main <replaceable>arg<subscript>1</subscript></replaceable> ... <replaceable>arg<subscript>n</subscript></replaceable></literal> - <indexterm><primary><literal>:main</literal></primary></indexterm> - </term> - <listitem> - <para> - When a program is compiled and executed, it can use the - <literal>getArgs</literal> function to access the - command-line arguments. - However, we cannot simply pass the arguments to the - <literal>main</literal> function while we are testing in ghci, - as the <literal>main</literal> function doesn't take its - arguments directly. - </para> - - <para> - Instead, we can use the <literal>:main</literal> command. - This runs whatever <literal>main</literal> is in scope, with - any arguments being treated the same as command-line arguments, - e.g.: - </para> - -<screen> -Prelude> let main = System.Environment.getArgs >>= print -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> - - <varlistentry> - <term> - <literal>:module <optional>+|-</optional> <optional>*</optional><replaceable>mod<subscript>1</subscript></replaceable> ... <optional>*</optional><replaceable>mod<subscript>n</subscript></replaceable></literal> - <indexterm><primary><literal>:module</literal></primary></indexterm> - </term> - <term> - <literal>import <replaceable>mod</replaceable></literal> - </term> - <listitem> - <para>Sets or modifies the current context for statements - typed at the prompt. The form <literal>import - <replaceable>mod</replaceable></literal> is equivalent to - <literal>:module +<replaceable>mod</replaceable></literal>. - See <xref linkend="ghci-scope"/> for - more details.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <literal>:print </literal> <replaceable>names</replaceable> ... - <indexterm><primary><literal>:print</literal></primary></indexterm> - </term> - <listitem> - <para>Prints a value without forcing its evaluation. - <literal>:print</literal> may be used on values whose types are - unknown or partially known, which might be the case for local - variables with polymorphic types at a breakpoint. While inspecting - the runtime value, <literal>:print</literal> attempts to - reconstruct the type of the value, and will elaborate the type in - GHCi's environment if possible. If any unevaluated components - (thunks) are encountered, then <literal>:print</literal> binds - a fresh variable with a name beginning with <literal>_t</literal> - to each thunk. See <xref linkend="breakpoints" /> for more - information. See also the <literal>:sprint</literal> command, - which works like <literal>:print</literal> but does not bind new - variables.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <literal>:quit</literal> - <indexterm><primary><literal>:quit</literal></primary></indexterm> - </term> - <listitem> - <para>Quits GHCi. You can also quit by typing control-D - at the prompt.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <literal>:reload</literal><optional><literal>!</literal></optional> - <indexterm><primary><literal>:reload</literal></primary></indexterm> - </term> - <listitem> - <para>Attempts to reload the current target set (see - <literal>:load</literal>) if any of the modules in the set, - or any dependent module, has changed. Note that this may - entail loading new modules, or dropping modules which are no - longer indirectly required by the target.</para> - - <para>Adding the optional "<literal>!</literal>" turns type - errors into warnings while loading. This allows to use the - portions of the module that are correct, even if there are - type errors in some definitions. Effectively, the - "-fdefer-type-errors" flag is set before loading and unset - after loading if the flag has not already been set - before. See <xref linkend="defer-type-errors" /> for further - motivation and details.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <literal>:run</literal> - <indexterm><primary><literal>:run</literal></primary></indexterm> - </term> - <listitem> - <para>See <literal>:main</literal>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <literal>:script</literal> <optional><replaceable>n</replaceable></optional> - <literal>filename</literal> - <indexterm><primary><literal>:script</literal></primary></indexterm> - </term> - <listitem> - <para>Executes the lines of a file as a series of GHCi commands. This command - is compatible with multiline statements as set by <literal>:set +m</literal> - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <literal>:set</literal> <optional><replaceable>option</replaceable>...</optional> - <indexterm><primary><literal>:set</literal></primary></indexterm> - </term> - <listitem> - <para>Sets various options. See <xref linkend="ghci-set"/> for a list of - available options and <xref linkend="interactive-mode-options"/> for a - list of GHCi-specific flags. The <literal>:set</literal> command by - itself shows which options are currently set. It also lists the current - dynamic flag settings, with GHCi-specific flags listed separately.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <literal>:set</literal> <literal>args</literal> <replaceable>arg</replaceable> ... - <indexterm><primary><literal>:set args</literal></primary></indexterm> - </term> - <listitem> - <para>Sets the list of arguments which are returned when the - program calls <literal>System.getArgs</literal><indexterm><primary>getArgs</primary> - </indexterm>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <literal>:set</literal> <literal>editor</literal> <replaceable>cmd</replaceable> - </term> - <listitem> - <para>Sets the command used by <literal>:edit</literal> to - <replaceable>cmd</replaceable>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <literal>:set</literal> <literal>prog</literal> <replaceable>prog</replaceable> - <indexterm><primary><literal>:set prog</literal></primary></indexterm> - </term> - <listitem> - <para>Sets the string to be returned when the program calls - <literal>System.getProgName</literal><indexterm><primary>getProgName</primary> - </indexterm>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <literal>:set</literal> <literal>prompt</literal> <replaceable>prompt</replaceable> - </term> - <listitem> - <para>Sets the string to be used as the prompt in GHCi. - Inside <replaceable>prompt</replaceable>, the sequence - <literal>%s</literal> is replaced by the names of the - modules currently in scope, <literal>%l</literal> is replaced - by the line number (as referenced in compiler messages) of the - current prompt, and <literal>%%</literal> is replaced by - <literal>%</literal>. If <replaceable>prompt</replaceable> - starts with " then it is parsed as a Haskell String; - otherwise it is treated as a literal string.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <literal>:set</literal> <literal>prompt2</literal> <replaceable>prompt</replaceable> - </term> - <listitem> - <para>Sets the string to be used as the continuation prompt - (used when using the <literal>:{</literal> command) in GHCi.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <literal>:set</literal> <literal>stop</literal> - [<replaceable>num</replaceable>] <replaceable>cmd</replaceable> - </term> - <listitem> - <para>Set a command to be executed when a breakpoint is hit, or a new - item in the history is selected. The most common use of - <literal>:set stop</literal> is to display the source code at the - current location, e.g. <literal>:set stop :list</literal>.</para> - - <para>If a number is given before the command, then the commands are - run when the specified breakpoint (only) is hit. This can be quite - useful: for example, <literal>:set stop 1 :continue</literal> - effectively disables breakpoint 1, by running - <literal>:continue</literal> whenever it is hit (although GHCi will - still emit a message to say the breakpoint was hit). What's more, - with cunning use of <literal>:def</literal> and - <literal>:cmd</literal> you can use <literal>:set stop</literal> to - implement conditional breakpoints:</para> -<screen> -*Main> :def cond \expr -> return (":cmd if (" ++ expr ++ ") then return \"\" else return \":continue\"") -*Main> :set stop 0 :cond (x < 3) -</screen> - <para>Ignoring breakpoints for a specified number of iterations is - also possible using similar techniques.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <literal>:seti</literal> <optional><replaceable>option</replaceable>...</optional> - <indexterm><primary><literal>:seti</literal></primary></indexterm> - </term> - <listitem> - <para> - Like <literal>:set</literal>, but options set with - <literal>:seti</literal> affect only expressions and - commands typed at the prompt, and not modules loaded with - <literal>:load</literal> (in contrast, options set with - <literal>:set</literal> apply everywhere). See <xref - linkend="ghci-interactive-options" />. - </para> - <para> - Without any arguments, displays the current set of options - that are applied to expressions and commands typed at the - prompt. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <literal>:show bindings</literal> - <indexterm><primary><literal>:show bindings</literal></primary></indexterm> - </term> - <listitem> - <para>Show the bindings made at the prompt and their - types.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <literal>:show breaks</literal> - <indexterm><primary><literal>:show breaks</literal></primary></indexterm> - </term> - <listitem> - <para>List the active breakpoints.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <literal>:show context</literal> - <indexterm><primary><literal>:show context</literal></primary></indexterm> - </term> - <listitem> - <para>List the active evaluations that are stopped at breakpoints.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <literal>:show imports</literal> - <indexterm><primary><literal>:show imports</literal></primary></indexterm> - </term> - <listitem> - <para>Show the imports that are currently in force, as - created by <literal>import</literal> and - <literal>:module</literal> commands.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <literal>:show modules</literal> - <indexterm><primary><literal>:show modules</literal></primary></indexterm> - </term> - <listitem> - <para>Show the list of modules currently loaded.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <literal>:show packages</literal> - <indexterm><primary><literal>:show packages</literal></primary></indexterm> - </term> - <listitem> - <para>Show the currently active package flags, as well as the list of - packages currently loaded.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <literal>:show paths</literal> - <indexterm><primary><literal>:show paths</literal></primary></indexterm> - </term> - <listitem> - <para>Show the current working directory (as set via - <literal>:cd</literal> command), as well as the list of - directories searched for source files (as set by the - <option>-i</option> option).</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <literal>:show language</literal> - <indexterm><primary><literal>:show language</literal></primary></indexterm> - </term> - <listitem> - <para>Show the currently active language flags for source files.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <literal>:showi language</literal> - <indexterm><primary><literal>:showi language</literal></primary></indexterm> - </term> - <listitem> - <para>Show the currently active language flags for - expressions typed at the prompt (see also <literal>:seti</literal>).</para> - </listitem> - </varlistentry> - - - <varlistentry> - <term> - <literal>:show [args|prog|prompt|editor|stop]</literal> - <indexterm><primary><literal>:show</literal></primary></indexterm> - </term> - <listitem> - <para>Displays the specified setting (see - <literal>:set</literal>).</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <literal>:sprint</literal> - <indexterm><primary><literal>:sprint</literal></primary></indexterm> - </term> - <listitem> - <para>Prints a value without forcing its evaluation. - <literal>:sprint</literal> is similar to <literal>:print</literal>, - with the difference that unevaluated subterms are not bound to new - variables, they are simply denoted by ‘_’.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <literal>:step</literal> <optional><replaceable>expr</replaceable></optional> - <indexterm><primary><literal>:step</literal></primary></indexterm> - </term> - <listitem> - <para>Enable all breakpoints and begin evaluating an - expression in single-stepping mode. In this - mode evaluation will be stopped after every reduction, - allowing local variables to be inspected. - - If <replaceable>expr</replaceable> is not given, evaluation will - resume at the last breakpoint. - - See <xref linkend="single-stepping" />.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <literal>:steplocal</literal> - <indexterm><primary><literal>:steplocal</literal></primary></indexterm> - </term> - <listitem> - <para>Enable only breakpoints in the current top-level - binding and resume evaluation at the last breakpoint.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <literal>:stepmodule</literal> - <indexterm><primary><literal>:stepmodule</literal></primary></indexterm> - </term> - <listitem> - <para>Enable only breakpoints in the current module and - resume evaluation at the last breakpoint.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <literal>:trace <optional><replaceable>expr</replaceable></optional></literal> - <indexterm><primary><literal>:trace</literal></primary></indexterm> - </term> - <listitem> - <para>Evaluates the given expression (or from the last breakpoint if - no expression is given), and additionally logs the evaluation - steps for later inspection using <literal>:history</literal>. See - <xref linkend="tracing" />.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <literal>:type</literal> <replaceable>expression</replaceable> - <indexterm><primary><literal>:type</literal></primary></indexterm> - </term> - <listitem> - <para>Infers and prints the type of - <replaceable>expression</replaceable>, including explicit - forall quantifiers for polymorphic types. The monomorphism - restriction is <emphasis>not</emphasis> applied to the - expression during type inference.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <literal>:undef</literal> <replaceable>name</replaceable> - <indexterm><primary><literal>:undef</literal></primary></indexterm> - </term> - <listitem> - <para>Undefines the user-defined command - <replaceable>name</replaceable> (see <literal>:def</literal> - above).</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <literal>:unset</literal> <replaceable>option</replaceable>... - <indexterm><primary><literal>:unset</literal></primary></indexterm> - </term> - <listitem> - <para>Unsets certain options. See <xref linkend="ghci-set"/> - for a list of available options.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <literal>:!</literal> <replaceable>command</replaceable>... - <indexterm><primary><literal>:!</literal></primary></indexterm> - <indexterm><primary>shell commands</primary><secondary>in GHCi</secondary></indexterm> - </term> - <listitem> - <para>Executes the shell command - <replaceable>command</replaceable>.</para> - </listitem> - </varlistentry> - - </variablelist> - </sect1> - - <sect1 id="ghci-set"> - <title>The <literal>:set</literal> and <literal>:seti</literal> commands</title> - <indexterm><primary><literal>:set</literal></primary></indexterm> - <indexterm><primary><literal>:seti</literal></primary></indexterm> - - <para>The <literal>:set</literal> command sets two types of - options: GHCi options, which begin with - ‘<literal>+</literal>’, and “command-line” - options, which begin with ‘-’. </para> - - <para>NOTE: at the moment, the <literal>:set</literal> command - doesn't support any kind of quoting in its arguments: quotes will - not be removed and cannot be used to group words together. For - example, <literal>:set -DFOO='BAR BAZ'</literal> will not do what - you expect.</para> - - <sect2> - <title>GHCi options</title> - <indexterm><primary>options</primary><secondary>GHCi</secondary> - </indexterm> - - <para>GHCi options may be set using <literal>:set</literal> and - unset using <literal>:unset</literal>.</para> - - <para>The available GHCi options are:</para> - - <variablelist> - <varlistentry> - <term> - <literal>+m</literal> - <indexterm><primary><literal>+m</literal></primary></indexterm> - </term> - <listitem> - <para>Enable parsing of multiline commands. A multiline command - is prompted for when the current input line contains open layout - contexts (see <xref linkend="ghci-multiline" />).</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <literal>+r</literal> - <indexterm><primary><literal>+r</literal></primary></indexterm> - <indexterm><primary>CAFs</primary><secondary>in GHCi</secondary></indexterm> - <indexterm><primary>Constant Applicative Form</primary><see>CAFs</see></indexterm> - </term> - <listitem> - <para>Normally, any evaluation of top-level expressions - (otherwise known as CAFs or Constant Applicative Forms) in - loaded modules is retained between evaluations. Turning - on <literal>+r</literal> causes all evaluation of - top-level expressions to be discarded after each - evaluation (they are still retained - <emphasis>during</emphasis> a single evaluation).</para> - - <para>This option may help if the evaluated top-level - expressions are consuming large amounts of space, or if - you need repeatable performance measurements.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <literal>+s</literal> - <indexterm><primary><literal>+s</literal></primary></indexterm> - </term> - <listitem> - <para>Display some stats after evaluating each expression, - including the elapsed time and number of bytes allocated. - NOTE: the allocation figure is only accurate to the size - of the storage manager's allocation area, because it is - calculated at every GC. Hence, you might see values of - zero if no GC has occurred.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <literal>+t</literal> - <indexterm><primary><literal>+t</literal></primary></indexterm> - </term> - <listitem> - <para>Display the type of each variable bound after a - statement is entered at the prompt. If the statement is a - single expression, then the only variable binding will be - for the variable - ‘<literal>it</literal>’.</para> - </listitem> - </varlistentry> - </variablelist> - </sect2> - - <sect2 id="ghci-cmd-line-options"> - <title>Setting GHC command-line options in GHCi</title> - - <para>Normal GHC command-line options may also be set using - <literal>:set</literal>. For example, to turn on - <option>-fwarn-missing-signatures</option>, you would say:</para> - -<screen> -Prelude> :set -fwarn-missing-signatures -</screen> - - <para>Any GHC command-line option that is designated as - <firstterm>dynamic</firstterm> (see the table in <xref - linkend="flag-reference"/>), may be set using - <literal>:set</literal>. To unset an option, you can set the - reverse option:</para> - <indexterm><primary>dynamic</primary><secondary>options</secondary></indexterm> - -<screen> -Prelude> :set -fno-warn-incomplete-patterns -XNoMultiParamTypeClasses -</screen> - - <para><xref linkend="flag-reference"/> lists the reverse for each - option where applicable.</para> - - <para>Certain static options (<option>-package</option>, - <option>-I</option>, <option>-i</option>, and - <option>-l</option> in particular) will also work, but some may - not take effect until the next reload.</para> - <indexterm><primary>static</primary><secondary>options</secondary></indexterm> - </sect2> - - <sect2 id="ghci-interactive-options"> - <title>Setting options for interactive evaluation only</title> - - <para> - GHCi actually maintains <emphasis>two</emphasis> sets of options: -<itemizedlist> -<listitem><para> - The <emphasis>loading options</emphasis> apply when loading modules -</para></listitem> -<listitem><para> - The <emphasis>interactive options</emphasis> apply when evaluating expressions and commands typed at the GHCi prompt. -</para></listitem> -</itemizedlist> -The <literal>:set</literal> command modifies both, but there is - also a <literal>:seti</literal> command (for "set - interactive") that affects only the interactive options set. - </para> - - <para> - It is often useful to change the interactive options, - without having that option apply to loaded modules - too. For example -<screen> -:seti -XMonoLocalBinds -</screen> - It would be undesirable if <option>-XMonoLocalBinds</option> were to - apply to loaded modules too: that might cause a compilation error, but - more commonly it will cause extra recompilation, because GHC will think - that it needs to recompile the module because the flags have changed. - </para> - - <para> - If you are setting language options in your <literal>.ghci</literal> file, it is good practice - to use <literal>:seti</literal> rather than <literal>:set</literal>, - unless you really do want them to apply to all modules you - load in GHCi. - </para> - - <para> - The two sets of options can be inspected using the - <literal>:set</literal> and <literal>:seti</literal> commands - respectively, with no arguments. For example, in a clean GHCi - session we might see something like this: -<screen> -Prelude> :seti -base language is: Haskell2010 -with the following modifiers: - -XNoMonomorphismRestriction - -XNoDatatypeContexts - -XNondecreasingIndentation - -XExtendedDefaultRules -GHCi-specific dynamic flag settings: -other dynamic, non-language, flag settings: - -fimplicit-import-qualified -warning settings: -</screen> - </para> -<para> -The two sets of options are initialised as follows. First, both sets of options -are initialised as described in <xref linkend="ghci-dot-files"/>. -Then the interactive options are modified as follows: -<itemizedlist> -<listitem><para> - The option <option>-XExtendedDefaultRules</option> - is enabled, in order to apply special defaulting rules to - expressions typed at the prompt (see <xref - linkend="extended-default-rules" />). - </para></listitem> - -<listitem> <para> - The Monomorphism Restriction is disabled (see <xref linkend="monomorphism" />). - </para></listitem> -</itemizedlist> -</para> - </sect2> - </sect1> - - <sect1 id="ghci-dot-files"> - <title>The <filename>.ghci</filename> and <filename>.haskeline</filename> files</title> - - <sect2 id="dot-ghci-files"> - <title>The <filename>.ghci</filename> files</title> - - <indexterm><primary><filename>.ghci</filename></primary><secondary>file</secondary> - </indexterm> - <indexterm><primary>startup</primary><secondary>files, GHCi</secondary> - </indexterm> - - <para>When it starts, unless the <literal>-ignore-dot-ghci</literal> - flag is given, GHCi reads and executes commands from the following - files, in this order, if they exist:</para> - - <orderedlist> - <listitem> - <para><filename>./.ghci</filename></para> - </listitem> - <listitem> - <para><literal><replaceable>appdata</replaceable>/ghc/ghci.conf</literal>, - where <replaceable>appdata</replaceable> depends on your system, - but is usually something like <literal>C:/Documents and Settings/<replaceable>user</replaceable>/Application Data</literal></para> - </listitem> - <listitem> - <para>On Unix: <literal>$HOME/.ghc/ghci.conf</literal></para> - </listitem> - <listitem> - <para><literal>$HOME/.ghci</literal></para> - </listitem> - </orderedlist> - - <para>The <filename>ghci.conf</filename> file is most useful for - turning on favourite options (eg. <literal>:set +s</literal>), and - defining useful macros. Note: when setting language options in - this file it is usually desirable to use <literal>:seti</literal> - rather than <literal>:set</literal> (see <xref - linkend="ghci-interactive-options" />). - </para> - - <para> - Placing a <filename>.ghci</filename> file - in a directory with a Haskell project is a useful way to set - certain project-wide options so you don't have to type them - every time you start GHCi: eg. if your project uses multi-parameter - type classes, scoped type variables, - and CPP, and has source files in three subdirectories A, B and C, - you might put the following lines in - <filename>.ghci</filename>:</para> - -<screen> -:set -XMultiParamTypeClasses -XScopedTypeVariables -cpp -:set -iA:B:C -</screen> - - <para>(Note that strictly speaking the <option>-i</option> flag is - a static one, but in fact it works to set it using - <literal>:set</literal> like this. The changes won't take effect - until the next <literal>:load</literal>, though.)</para> - - <para>Once you have a library of GHCi macros, you may want - to source them from separate files, or you may want to source - your <filename>.ghci</filename> file into your running GHCi - session while debugging it</para> - -<screen> -:def source readFile -</screen> - - <para>With this macro defined in your <filename>.ghci</filename> - file, you can use <literal>:source file</literal> to read GHCi - commands from <literal>file</literal>. You can find (and contribute!-) - other suggestions for <filename>.ghci</filename> files on this Haskell - wiki page: <ulink - url="http://haskell.org/haskellwiki/GHC/GHCi">GHC/GHCi</ulink></para> - - <para>Additionally, any files specified with - <literal>-ghci-script</literal> flags will be read after the - standard files, allowing the use of custom .ghci files.</para> - - <para>Two command-line options control whether the - startup files files are read:</para> - - <variablelist> - <varlistentry> - <term> - <option>-ignore-dot-ghci</option> - <indexterm><primary><option>-ignore-dot-ghci</option></primary></indexterm> - </term> - <listitem> - <para>Don't read either <filename>./.ghci</filename> or the - other startup files when starting up.</para> - </listitem> - </varlistentry> - <varlistentry> - <term> - <option>-ghci-script</option> - <indexterm><primary><option>-ghci-script</option></primary></indexterm> - </term> - <listitem> - <para>Read a specific file after the usual startup files. - Maybe be specified repeatedly for multiple inputs.</para> - </listitem> - </varlistentry> - </variablelist> - - <para> - When defining GHCi macros, there is some important behavior you - should be aware of when names may conflict with built-in - commands, especially regarding tab completion. - </para> - <para> - For example, consider if you had a macro named - <literal>:time</literal> and in the shell, typed <literal>:t - 3</literal> - what should happen? The current algorithm we use - for completing commands is: - - <orderedlist> - <listitem> - <para>First, look up an exact match on the name from the defined macros.</para> - </listitem> - <listitem> - <para>Look for the exact match on the name in the built-in command list.</para> - </listitem> - <listitem> - <para>Do a prefix lookup on the list of built-in commands - - if a built-in command matches, but a macro is defined with - the same name as the built-in defined, pick the - macro.</para> - </listitem> - <listitem> - <para>Do a prefix lookup on the list of built-in commands.</para> - </listitem> - <listitem> - <para>Do a prefix lookup on the list of defined macros.</para> - </listitem> - </orderedlist> - </para> - - <para> - Here are some examples: - - <orderedlist> - <listitem> - <para>You have a macro <literal>:time</literal> and enter <literal>:t 3</literal></para> - <para>You get <literal>:type 3</literal></para> - </listitem> - - <listitem> - <para>You have a macro <literal>:type</literal> and enter <literal>:t 3</literal></para> - <para>You get <literal>:type 3</literal> with your defined macro, not the builtin.</para> - </listitem> - - <listitem> - <para>You have a macro <literal>:time</literal> and a macro - <literal>:type</literal>, and enter <literal>:t - 3</literal></para> - <para>You get <literal>:type 3</literal> with your defined macro.</para> - </listitem> - </orderedlist> - </para> - </sect2> - - <sect2 id="dot-haskeline-file"> - <title>The <filename>.haskeline</filename> file</title> - - <indexterm><primary><filename>.haskeline</filename></primary><secondary>file</secondary> - </indexterm> - <indexterm><primary>startup</primary><secondary>files, GHCi</secondary> - </indexterm> - - GHCi uses <ulink url="https://hackage.haskell.org/package/haskeline">Haskeline</ulink> - under the hood. You can configure it to, among other things, prune - duplicates from ghci history. See: - <ulink url="http://trac.haskell.org/haskeline/wiki/UserPrefs">Haskeline user preferences</ulink>. - </sect2> - </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> - - <variablelist> - <varlistentry> - <term>The interpreter can't load modules with foreign export - declarations!</term> - <listitem> - <para>Unfortunately not. We haven't implemented it yet. - Please compile any offending modules by hand before loading - them into GHCi.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <literal>-O</literal> doesn't work with GHCi! - <indexterm><primary><option>-O</option></primary></indexterm> - </term> - <listitem> - <para>For technical reasons, the bytecode compiler doesn't - interact well with one of the optimisation passes, so we - have disabled optimisation when using the interpreter. This - isn't a great loss: you'll get a much bigger win by - compiling the bits of your code that need to go fast, rather - than interpreting them with optimisation turned on.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>Unboxed tuples don't work with GHCi</term> - <listitem> - <para>That's right. You can always compile a module that - uses unboxed tuples and load it into GHCi, however. - (Incidentally the previous point, namely that - <literal>-O</literal> is incompatible with GHCi, is because - the bytecode compiler can't deal with unboxed - tuples).</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>Concurrent threads don't carry on running when GHCi is - waiting for input.</term> - <listitem> - <para>This should work, as long as your GHCi was built with - the <option>-threaded</option> switch, which is the default. - Consult whoever supplied your GHCi installation.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>After using <literal>getContents</literal>, I can't use - <literal>stdin</literal> again until I do - <literal>:load</literal> or <literal>:reload</literal>.</term> - - <listitem> - <para>This is the defined behaviour of - <literal>getContents</literal>: it puts the stdin Handle in - a state known as <firstterm>semi-closed</firstterm>, wherein - any further I/O operations on it are forbidden. Because I/O - state is retained between computations, the semi-closed - state persists until the next <literal>:load</literal> or - <literal>:reload</literal> command.</para> - - <para>You can make <literal>stdin</literal> reset itself - after every evaluation by giving GHCi the command - <literal>:set +r</literal>. This works because - <literal>stdin</literal> is just a top-level expression that - can be reverted to its unevaluated state in the same way as - any other top-level expression (CAF).</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>I can't use Control-C to interrupt computations in - GHCi on Windows.</term> - <listitem> - <para>See <xref linkend="ghci-windows"/>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>The default buffering mode is different in GHCi to GHC.</term> - <listitem> - <para> - In GHC, the stdout handle is line-buffered by default. - However, in GHCi we turn off the buffering on stdout, - because this is normally what you want in an interpreter: - output appears as it is generated. - </para> - <para> - If you want line-buffered behaviour, as in GHC, you can - start your program thus: - <programlisting> - main = do { hSetBuffering stdout LineBuffering; ... } - </programlisting> - </para> - </listitem> - </varlistentry> - </variablelist> - </sect1> - -</chapter> - -<!-- Emacs stuff: - ;;; Local Variables: *** - ;;; sgml-parent-document: ("users_guide.xml" "book" "chapter") *** - ;;; End: *** - --> |