X-Git-Url: http://git.megacz.com/?a=blobdiff_plain;f=docs%2Fusers_guide%2Fghci.xml;h=28e9972b24afadfc2cfba5d085f41eff34bec30c;hb=806ab6331b967d6176b8790a0b1b551ec0e8e2b6;hp=d8d0a897414c0dac106faf08b0c23fad098caea6;hpb=01d016a48232ca5932efd7fd19fa4ccdb9623576;p=ghc-hetmet.git diff --git a/docs/users_guide/ghci.xml b/docs/users_guide/ghci.xml index d8d0a89..28e9972 100644 --- a/docs/users_guide/ghci.xml +++ b/docs/users_guide/ghci.xml @@ -18,7 +18,7 @@ FFIGHCi support Foreign Function InterfaceGHCi support. - GHCi also includes an interactive debugger (see ).. + GHCi also includes an interactive debugger (see ). Introduction to GHCi @@ -28,64 +28,15 @@ $ ghci - ___ ___ _ - / _ \ /\ /\/ __(_) - / /_\// /_/ / / | | 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. Prelude> There may be a short pause while GHCi loads the prelude and - standard libraries, after which the prompt is shown. If we follow - the instructions and type :? for help, we - get: - - - Commands available from the prompt: - - <stmt> evaluate/run <stmt> - :add <filename> ... add module(s) to the current target set - :browse [*]<module> display the names defined by <module> - :cd <dir> change directory to <dir> - :def <cmd> <expr> define a command :<cmd> - :edit <file> edit file - :edit edit last module - :help, :? display this list of commands - :info [<name> ...] display information about the given names - :load <filename> ... load module(s) and their dependents - :module [+/-] [*]<mod> ... set the context for expression evaluation - :main [<arguments> ...] run the main function with the given arguments - :reload reload the current module set - - :set <option> ... set options - :set args <arg> ... set the arguments returned by System.getArgs - :set prog <progname> set the value returned by System.getProgName - :set prompt <prompt> set the prompt used in GHCi - :set editor <cmd> set the command used for :edit - - :show modules show the currently loaded modules - :show bindings show the current bindings made at the prompt - - :ctags [<file>] create tags file for Vi (default: "tags") - :etags [<file>] create tags file for Emacs (default: "TAGS") - :type <expr> show the type of <expr> - :kind <type> show the kind of <type> - :undef <cmd> undefine user-defined command :<cmd> - :unset <option> ... unset options - :quit exit GHCi - :!<command> run the shell command <command> - - Options for ':set' and ':unset': - - +r revert top-level expressions after each evaluation - +s print timing/memory stats after each evaluation - +t print type after evaluation - -<flags> most GHC command line flags can also be set here - (eg. -v2, -fglasgow-exts, etc.) - + standard libraries, after which the prompt is shown. As the banner + says, you can type :? 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. For Hugs users: many things work the same as in Hugs, so you should be @@ -268,19 +219,17 @@ Ok, modules loaded: Main. Prelude> :! ghc -c D.hs Prelude> :load A -Skipping D ( D.hs, D.o ) -Compiling C ( C.hs, interpreted ) Compiling B ( B.hs, interpreted ) +Compiling C ( C.hs, interpreted ) Compiling A ( A.hs, interpreted ) Ok, modules loaded: A, B, C, D. *Main> - In the messages from the compiler, we see that it skipped D, - and used the object file D.o. The message - Skipping module - indicates that compilation for module - isn't necessary, because the source and everything it depends on + In the messages from the compiler, we see that there is no line + for D. This is because + it isn't necessary to compile D, + because the source and everything it depends on is unchanged since the last compilation. At any time you can use the command @@ -296,7 +245,7 @@ B ( B.hs, interpreted ) A ( A.hs, interpreted ) *Main> - If we now modify the source of D (or pretend to: using Unix + If we now modify the source of D (or pretend to: using the Unix command touch 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: @@ -305,9 +254,6 @@ A ( A.hs, interpreted ) *Main> :! touch D.hs *Main> :reload Compiling D ( D.hs, interpreted ) -Skipping C ( C.hs, interpreted ) -Skipping B ( B.hs, interpreted ) -Skipping A ( A.hs, interpreted ) Ok, modules loaded: A, B, C, D. *Main> @@ -323,8 +269,8 @@ Ok, modules loaded: A, B, C, D. *Main> :! ghc -c C.hs *Main> :load A Compiling D ( D.hs, interpreted ) -Compiling C ( C.hs, interpreted ) Compiling B ( B.hs, interpreted ) +Compiling C ( C.hs, interpreted ) Compiling A ( A.hs, interpreted ) Ok, modules loaded: A, B, C, D. @@ -347,8 +293,6 @@ Ok, modules loaded: A, B, C, D. *Main> :load A -Skipping D ( D.hs, D.o ) -Skipping C ( C.hs, C.o ) Compiling B ( B.hs, interpreted ) Compiling A ( A.hs, interpreted ) Ok, modules loaded: A, B, C, D. @@ -359,7 +303,7 @@ Ok, modules loaded: A, B, C, D. when working on a large program is to occasionally run ghc ––make to compile the whole project (say before you go for lunch :-), then continue working in the - interpreter. As you modify code, the new modules will be + interpreter. As you modify code, the changed modules will be interpreted, but the rest of the project will remain compiled. @@ -449,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 @@ -480,6 +424,45 @@ Prelude> Note that let bindings do not automatically print the value bound, unlike monadic bindings. + Hint: you can also use let-statements + to define functions at the prompt: + +Prelude> let add a b = a + b +Prelude> add 1 2 +3 +Prelude> + + 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 braces and semicolons instead of layout: + +Prelude> let { f op n [] = n ; f op n (h:t) = h `op` f op n t } +Prelude> f (+) 0 [1..3] +6 +Prelude> + + To alleviate this issue, GHCi commands can be split over + multiple lines, by wrapping them in :{ and + :} (each on a single line of its own): + +Prelude> :{ +Prelude| let { g op n [] = n +Prelude| ; g op n (h:t) = h `op` g op n t +Prelude| } +Prelude| :} +Prelude> g (*) 1 [1..3] +6 + + Such multiline commands can be used with any GHCi command, + and the lines between :{ and + :} are simply merged into a single line for + interpretation. That implies that each such group must form a single + valid command when merged, and that no layout rule is used. + The main purpose of multiline commands is not to replace module + loading but to make definitions in .ghci-files (see ) more readable and maintainable. + 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 @@ -577,7 +560,9 @@ hello Prelude IO> - (Note: :module can be shortened to + (Note: you can use import M as an + alternative to :module +M, and + :module can also be shortened to :m). The full syntax of the :module command is: @@ -618,7 +603,7 @@ Prelude IO> Hint: GHCi will tab-complete names that are in scope; for example, if you run GHCi and type J<tab> - then GHCi will expand it to Just . + then GHCi will expand it to “Just ”. @@ -769,7 +754,7 @@ it <- e At the GHCi prompt, or with GHC if the - -fextended-default-rules flag is given, + -XExtendedDefaultRules flag is given, the following additional differences apply: @@ -818,8 +803,8 @@ def = toEnum 0 instance that returns IO a. However, it is only able to return undefined - (the reason for the instance having this type is to not require - extensions to the class system), so if the type defaults to + (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 Integer then ghci gives an error when running a printf. @@ -842,7 +827,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 @@ -983,6 +968,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]) @@ -1002,6 +988,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 @@ -1071,7 +1064,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 @@ -1134,7 +1128,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 @@ -1160,10 +1154,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 @@ -1172,10 +1170,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: @@ -1373,7 +1372,9 @@ a :: a have no context information attached to them. Finding which particular call to head in your program resulted in the error can be a painstaking process, usually involving - Debug.Trace.trace. + Debug.Trace.trace, or compiling with + profiling and using +RTS -xc (see ). The GHCi debugger offers a way to hopefully shed some light on these errors quickly and without modifying or recompiling the source @@ -1382,9 +1383,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: @@ -1540,7 +1545,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. @@ -1568,9 +1573,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 @@ -1586,12 +1589,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> @@ -1721,22 +1719,32 @@ $ 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 modules from packages) only the non-* - form of :browse is available. + form of :browse is available. + If the ! symbol is appended to the + command, data constructors and class methods will be + listed individually, otherwise, they will only be listed + in the context of their data type or class declaration. + The !-form also annotates the listing + with comments giving possible imports for each group of + entries. @@ -1763,16 +1771,6 @@ $ ghci -lm - :continue - :continue - - Continue the current evaluation, when stopped at a - breakpoint. - - - - - :cmd expr :cmd @@ -1787,6 +1785,16 @@ $ ghci -lm + :continue + :continue + + Continue the current evaluation, when stopped at a + breakpoint. + + + + + :ctags filename :etags filename :etags @@ -1796,8 +1804,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 @@ -1904,6 +1913,15 @@ Prelude> :. cmds.ghci + :etags + + + See :ctags. + + + + + :force identifier ... :force @@ -1972,6 +1990,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. @@ -2040,7 +2064,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. @@ -2064,9 +2088,15 @@ Prelude> :main foo bar :module +|- *mod1 ... *modn :module + + import mod + Sets or modifies the current context for statements - typed at the prompt. See for + typed at the prompt. The form import + mod is equivalent to + :module +mod. + See for more details. @@ -2079,7 +2109,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 @@ -2099,7 +2129,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. @@ -2124,10 +2154,11 @@ Prelude> :main foo bar :set - Sets various options. See - for a list of available options. The - :set command by itself shows which - options are currently set. + Sets various options. See for a list of + available options and for a + list of GHCi-specific flags. The :set command by + itself shows which options are currently set. It also lists the current + dynamic flag settings, with GHCi-specific flags listed separately. @@ -2244,10 +2275,32 @@ Prelude> :main foo bar :show modules - Show the list of modules currently load. + Show the list of modules currently loaded. + + + + + + :show packages + :show packages + + + Show the currently active package flags, as well as the list of + packages currently loaded. + + + + + + :show languages + :show languages + + + Show the currently active language flags. + :show [args|prog|prompt|editor|stop] @@ -2355,7 +2408,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 @@ -2467,9 +2520,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 @@ -2478,7 +2532,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: @@ -2626,7 +2680,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. +