X-Git-Url: http://git.megacz.com/?a=blobdiff_plain;f=docs%2Fusers_guide%2Fghci.xml;h=3ba2012eee34a086f7cd4ac1cb7fa227c7f6c1a5;hb=0093a2827f6b4007c4fcb298a559c9b7dd17aec1;hp=9810dce06444dc8df096c641dc056af9b17d560b;hpb=0cfe6d46b0033b5a26964a73168767e2e97276cc;p=ghc-hetmet.git diff --git a/docs/users_guide/ghci.xml b/docs/users_guide/ghci.xml index 9810dce..3ba2012 100644 --- a/docs/users_guide/ghci.xml +++ b/docs/users_guide/ghci.xml @@ -393,9 +393,9 @@ Prelude> Show - The automatic printing of binding results can be supressed with + The automatic printing of binding results can be suppressed with (this does not - supress printing the result of non-binding statements). + suppress printing the result of non-binding statements). . You might want to do this to prevent the result of binding statements from being fully evaluated by the act of printing @@ -788,7 +788,7 @@ def = toEnum 0 The debugger provides the following: - The abilty to set a breakpoint on a + The ability to set a breakpoint 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 @@ -929,6 +929,7 @@ right :: [a] left: +[qsort.hs:2:15-46] *Main> :set -fprint-evld-with-show [qsort.hs:2:15-46] *Main> :print left left = (_t1::[a]) @@ -948,6 +949,13 @@ left = (_t1::[a]) underscore, in this case _t1. + The flag -fprint-evld-with-show instructs + :print to reuse + available Show instances when possible. This happens + only when the contents of the variable being inspected + are completely evaluated. + + If we aren't concerned about preserving the evaluatedness of a variable, we can use :force instead of :print. The :force command @@ -1017,7 +1025,8 @@ right :: [a] The execution continued at the point it previously stopped, and has now stopped at the breakpoint for a second time. - + + Setting breakpoints Breakpoints can be set in various ways. Perhaps the easiest way to @@ -1080,7 +1089,7 @@ right :: [a] Listing and deleting breakpoints The list of breakpoints currently enabled can be displayed using - :show breaks: + :show breaks: *Main> :show breaks [0] Main qsort.hs:1:11-12 @@ -1106,10 +1115,14 @@ right :: [a] 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. The concept is simple: single-stepping enables all the - breakpoints in the program and executes until the next breakpoint is - reached, at which point you can single-step again, or continue - normally. For example: + bug. GHCi offers two variants of stepping. Use + :step to enable all the + breakpoints in the program, and execute until the next breakpoint is + reached. Use :steplocal to limit the set + of enabled breakpoints to those in the current top level function. + Similarly, use :stepmodule to single step only on + breakpoints contained in the current module. + For example: *Main> :step main @@ -1118,10 +1131,11 @@ _result :: IO () The command :step - expr begins the evaluation of + expr begins the evaluation of expr in single-stepping mode. If - expr is ommitted, then it single-steps from - the current breakpoint. + expr is omitted, then it single-steps from + the current breakpoint. :stepover + works similarly. The :list command is particularly useful when single-stepping, to see where you currently are: @@ -1330,9 +1344,13 @@ a :: a :trace and :history to establish the context. However, head is in a library and we can't set a breakpoint on it directly. For this reason, GHCi - provides the flag -fbreak-on-exception which causes - the evaluator to stop when an exception is thrown, just as it does when - a breakpoint is hit. This is only really useful in conjunction with + provides the flags -fbreak-on-exception which causes + the evaluator to stop when an exception is thrown, and + -fbreak-on-error, 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 :trace, in order to log the steps leading up to the exception. For example: @@ -1488,7 +1506,7 @@ Just 20 Implicit parameters (see ) are only available - at the scope of a breakpoint if there is a explicit type signature. + at the scope of a breakpoint if there is an explicit type signature. @@ -1516,9 +1534,7 @@ $ ghci Main.hs Most of the command-line options accepted by GHC (see ) also make sense in interactive mode. The ones - that don't make sense are mostly obvious; for example, GHCi - doesn't generate interface files, so options related to interface - file generation won't have any effect. + that don't make sense are mostly obvious. Packages @@ -1534,12 +1550,7 @@ $ ghci Main.hs $ ghci -package readline - ___ ___ _ - / _ \ /\ /\/ __(_) - / /_\// /_/ / / | | GHC Interactive, version 6.6, for Haskell 98. -/ /_\\/ __ / /___| | http://www.haskell.org/ghc/ -\____/\/ /_/\____/|_| Type :? for help. - +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> @@ -1669,17 +1680,20 @@ $ ghci -lm - :browse *module ... + :browse *module ... :browse Displays the identifiers defined by the module module, which must be either - loaded into GHCi or be a member of a package. If the - * symbol is placed before the module - name, then all the identifiers defined - in module are shown; otherwise - the list is limited to the exports of + loaded into GHCi or be a member of a package. If + module is omitted, the most + recently-loaded module is used. + + If the * symbol is placed before + the module name, then all the + identifiers in scope in module are + shown; otherwise the list is limited to the exports of module. The *-form is only available for modules which are interpreted; for compiled modules (including @@ -1711,16 +1725,6 @@ $ ghci -lm - :continue - :continue - - Continue the current evaluation, when stopped at a - breakpoint. - - - - - :cmd expr :cmd @@ -1735,6 +1739,16 @@ $ ghci -lm + :continue + :continue + + Continue the current evaluation, when stopped at a + breakpoint. + + + + + :ctags filename :etags filename :etags @@ -1744,8 +1758,9 @@ $ ghci -lm Generates a “tags” file for Vi-style editors - (:ctags) or Emacs-style editors (etags). If - no filename is specified, the defaulit tags or + (:ctags) or + Emacs-style editors (:etags). If + no filename is specified, the default tags or TAGS is used, respectively. Tags for all the functions, constructors and types in the currently loaded modules are created. All modules must @@ -1852,6 +1867,15 @@ Prelude> :. cmds.ghci + :etags + + + See :ctags. + + + + + :force identifier ... :force @@ -1920,6 +1944,12 @@ Prelude> :. cmds.ghci will be printed. If name has been loaded from a source file, then GHCi will also display the location of its definition in the source. + 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 name, + and (b) all the other things mentioned in the instance + are in scope (either qualified or otherwise) as a result of + a :load or :module commands. @@ -1988,7 +2018,7 @@ Prelude> :. cmds.ghci However, we cannot simply pass the arguments to the main function while we are testing in ghci, as the main function doesn't take its - directly. + arguments directly. @@ -2033,7 +2063,7 @@ Prelude> :main foo bar Prints a value without forcing its evaluation. :print may be used on values whose types are - unkonwn or partially known, which might be the case for local + unknown or partially known, which might be the case for local variables with polymorphic types at a breakpoint. While inspecting the runtime value, :print attempts to reconstruct the type of the value, and will elaborate the type in @@ -2053,7 +2083,7 @@ Prelude> :main foo bar :quit - Quits GHCi. You can also quit by typing a control-D + Quits GHCi. You can also quit by typing control-D at the prompt. @@ -2198,7 +2228,7 @@ Prelude> :main foo bar :show modules - Show the list of modules currently load. + Show the list of modules currently loaded. @@ -2309,7 +2339,7 @@ Prelude> :main foo bar The :set command sets two types of options: GHCi options, which begin with - ‘+” and “command-line” + ‘+’, and “command-line” options, which begin with ‘-’. NOTE: at the moment, the :set command @@ -2421,9 +2451,10 @@ Prelude> :set -fno-glasgow-exts startupfiles, GHCi - When it starts, GHCi always reads and executes commands from - $HOME/.ghci, followed by - ./.ghci. + When it starts, unless the -ignore-dot-ghci + flag is given, GHCi reads and executes commands from + ./.ghci, followed by + $HOME/.ghci. The .ghci in your home directory is most useful for turning on favourite options (eg. :set @@ -2432,7 +2463,7 @@ Prelude> :set -fno-glasgow-exts project is a useful way to set certain project-wide options so you don't have to type them everytime you start GHCi: eg. if your project uses GHC extensions and CPP, and has source files in three - subdirectories A B and C, you might put the following lines in + subdirectories A, B and C, you might put the following lines in .ghci: @@ -2580,7 +2611,19 @@ Prelude> :set -fno-glasgow-exts I can't use Control-C to interrupt computations in GHCi on Windows. - See + See . + + + + + The default buffering mode is different in GHCi to GHC. + + + 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. +