X-Git-Url: http://git.megacz.com/?a=blobdiff_plain;f=docs%2Fusers_guide%2Fghci.xml;h=54ce6b7c74ea8d558c4abd48c21560fe49e90775;hb=45b04f650e6985c524301112a8381a1aff808fc6;hp=26efdee4f74a06f60ff1a11074670284405b4b67;hpb=8eb677bc6758080886aa8b21340cc3470b249b75;p=ghc-hetmet.git diff --git a/docs/users_guide/ghci.xml b/docs/users_guide/ghci.xml index 26efdee..54ce6b7 100644 --- a/docs/users_guide/ghci.xml +++ b/docs/users_guide/ghci.xml @@ -18,7 +18,7 @@ FFIGHCi support Foreign Function InterfaceGHCi support - + Introduction to GHCi Let's start with an example GHCi session. You can fire up @@ -49,6 +49,8 @@ Prelude> :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 @@ -60,12 +62,13 @@ Prelude> :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 (defauilt: "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> @@ -103,7 +106,7 @@ Prelude> enter, GHCi will attempt to evaluate it. - + Loading source files Suppose we have the following Haskell source code, which we @@ -360,7 +363,7 @@ Ok, modules loaded: A, B, C, D. - + Interactive evaluation at the prompt When you type an expression at the prompt, GHCi immediately @@ -402,7 +405,7 @@ hello - + Using <literal>do-</literal>notation at the prompt do-notationin GHCi statementsin GHCi @@ -444,7 +447,13 @@ Prelude> Show - + The automatic printing of binding results can be supressed with + (this does not + supress 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 + them, for example. Of course, you can also bind normal non-IO expressions using the let-statement: @@ -604,6 +613,12 @@ Prelude IO> behaves in the same way for expressions typed at the prompt. + + 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 . + + Qualified names @@ -732,24 +747,79 @@ it <- e standard rules take each group of constraints (C1 a, C2 a, ..., Cn a) for each type variable a, and defaults the type variable if - - The type variable a - appears in no other constraints - All the classes Ci are standard. - At least one of the classes Ci is - numeric. - - At the GHCi prompt, the second and third rules are relaxed as follows - (differences italicised): - - All of the classes - Ci are single-parameter type classes. - At least one of the classes Ci is - numeric, or is Show, - Eq, or Ord. - - The same type-default behaviour can be enabled in an ordinary Haskell - module, using the flag -fextended-default-rules. + + + + The type variable a appears in no + other constraints + + + + + All the classes Ci are standard. + + + + + At least one of the classes Ci is + numeric. + + + + At the GHCi prompt, or with GHC if the + -fextended-default-rules flag is given, + the following additional differences apply: + + + + Rule 2 above is relaxed thus: + All of the classes + Ci are single-parameter type classes. + + + + + Rule 3 above is relaxed this: + At least one of the classes Ci is + numeric, or is Show, + Eq, or + Ord. + + + + + The unit type () is added to the + start of the standard list of types which are tried when + doing type defaulting. + + + + The last point means that, for example, this program: + +main :: IO () +main = print def + +instance Num () + +def :: (Num a, Enum a) => a +def = toEnum 0 + + prints () rather than 0 as the + type is defaulted to () rather than + Integer. + + + The motivation for the change is that it means IO a + actions default to IO (), which in turn means that + ghci won't try to print a result when running them. This is + particularly important for printf, which has an + 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 + Integer then ghci gives an error when running a + printf. @@ -891,6 +961,21 @@ $ ghci -lm + :breakpoint list|add|continue|del|stop|step ... + :breakpoint + + + Permits to add, delete or list the breakpoints in a debugging session. + In order to make this command available, the + -fdebugging flag must be active. The easiest way is to launch + GHCi with the -fdebugging option. For more + details on how the debugger works, see . + + + + + + :browse *module ... :browse @@ -933,6 +1018,15 @@ $ ghci -lm + :continue + :continue + + Shortcut to :breakpoint continue + + + + + :def name expr :def @@ -1001,6 +1095,22 @@ Prelude> :. cmds.ghci + :edit file + :edit + + + Opens an editor to edit the file + file, or the most recently loaded + module if file is omitted. The + editor to invoke is taken from the EDITOR + environment variable, or a default editor on your system if + EDITOR is not set. You can change the + editor using :set editor. + + + + + :help :help @@ -1072,6 +1182,38 @@ Prelude> :. cmds.ghci + :main arg1 ... argn + :main + + + + When a program is compiled and executed, it can use the + getArgs function to access the + command-line arguments. + 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. + + + + Instead, we can use the :main command. + This runs whatever main is in scope, with + any arguments being treated the same as command-line arguments, + e.g.: + + + +Prelude> let main = System.Environment.getArgs >>= print +Prelude> :main foo bar +["foo","bar"] + + + + + + + :module +|- *mod1 ... *modn :module @@ -1084,6 +1226,48 @@ Prelude> :. cmds.ghci + :print names ... + :print + + + Prints a semievaluated value without forcing its evaluation. + :print works just like :sprint but additionally, + :print binds the unevaluated parts -called + suspensions- + to names which you can play with. For example: + +Prelude> let li = map Just [1..5] +Prelude> :sp li +li - _ +Prelude> :p li +li - (_t1::[Maybe Integer]) +Prelude> head li +Just 1 +Prelude> :sp li +li - Just 1 : _ +Prelude> :p li +li - Just 1 : (_t2::[Maybe Integer]) +Prelude> last li +Just 5 +Prelude> :sp li +li - [Just 1,_,_,_,Just 5] +Prelude> :p li +li - [Just 1,(_t3::Maybe Integer),(_t4::Maybe Integer),(_t5::Maybe Integer),Just 4] +Prelude> _t4 +Just 3 +Prelude> :p li +li - [Just 1,(_t6::Maybe Integer),Just 3,(_t7::Maybe Integer),Just 4] + + The example uses :print and :sprint + to help us observe how the li variable is evaluated progressively as we operate + with it. Note for instance how last traverses all the elements of + the list to compute its result, but without evaluating the individual elements. + + + + + + :quit :quit @@ -1134,6 +1318,16 @@ Prelude> :. cmds.ghci + :set editor cmd + + + Sets the command used by :edit to + cmd. + + + + + :set prog prog :set prog @@ -1177,7 +1371,34 @@ Prelude> :. cmds.ghci Show the list of modules currently load. - + + + :sprint + :sprint + + + Prints a semievaluated value without forcing its evaluation. + :sprint and its sibling :print + are very useful to observe how lazy evaluation works in your code. For example: + +Prelude> let li = map Just [1..5] +Prelude> :sp li +li - _ +Prelude> head li +Just 1 +Prelude> :sp li +li - Just 1 : _ +Prelude> last li +Just 5 +Prelude> :sp li +li - [Just 1,_,_,_,Just 5] + + The example uses :sprint to help us observe how the li variable is evaluated progressively as we operate + with it. Note for instance how last traverses all the elements of + the list to compute its result, but without evaluating the individual elements. + + + :ctags filename @@ -1375,7 +1596,382 @@ Prelude> :set -fno-glasgow-exts staticoptions + + The GHCi debugger + debugger + GHCi embeds an utility debugger with a very basic set of operations. The debugger + is always available in ghci, you do not need to do anything to activate it. + The following conditions must hold before a module can be debugged in GHCi: + + + The module must have been loaded interpreted, i.e. not loaded from an .o file compiled by ghc + + + The module must have been loaded with the -fdebugging flag + + + Using the debugger + The debugger allows the insertion of breakpoints at specific locations in the source code. These locations are governed by event sites, and not by line as in traditional debuggers such as gdb. + Once a breakpointed event is hit, the debugger stops the execution and you can examine the local variables in scope + in the context of the event, as well as evaluate arbitrary Haskell expressions in + a special interactive prompt. + + When you are done you issue the :continue + command to leave the breakpoint and let the execution go on. + Note that not all the GHCi commands are supported in a breakpoint. + + + Events + Events are the places in source code where you can set a breakpoint. + +qsort [] = [] +qsort (x:xs) = + let left = filter (\y -> y < x) xs + right = case filter (\y -> y > x) xs of + right_val -> right_val + in qsort left ++ [x] ++ qsort right +main = do { + arg <- getLine ; + let num = read arg :: [Int] ; + print (qsort num) ; + putStrLn "GoodBye!" } + + The GHCi debugger recognizes the following event types: + + + Function definition and local bindings in let/where + + + Lambda expression entry point + + + Let expression body + + + Case alternative body + + + do notation statements + + + In reality however, ghci eliminates some redundant event sites. + For instance, sites with two co-located breakpoint events are coalesced into a single one, + and sites with no bindings in scope are assumed to be uninteresting and no breakpoint can be set in them. + + + + You don't need to do anything special in order to start the debugging session. + Simply use ghci to evaluate your Haskell expressions and whenever a breakpoint + is hit, the debugger will enter the stage: + +*main:Main> :break add Main 2 +Breakpoint set at (2,15) +*main:Main> qsort [10,9..1] +Local bindings in scope: + x :: a, xs :: [a], left :: [a], right :: [a] + +qsort2.hs:2:15-46> + + What is happening here is that GHCi has interrupted the evaluation of + qsort at the breakpoint set in line 2, as the prompt indicates. + At this point you can freely explore the contents of the bindings in scope, + but with two catches. + First, take into account that due to the lazy nature of Haskell, some of + these bindings may be unevaluated, and that exploring their contents may + trigger a computation. + Second: look at the types of the things in scope. + GHCi has left its types parameterised by a variable! + Look at the type of qsort, which is + polymorphic on the type of its argument. It does not + tell us really what the types of x and xs can be. + In general, polymorphic programs deal with polymorphic values, + and this means that some of the bindings available in a breakpoint site + will be parametrically typed. + + So, what can we do with a value without concrete type? Very few interesting + things. The :print command in ghci allows you to + explore its contents and see if it is evaluated or not. + This is useful because you cannot just type x in the + prompt and expect GHCi to return you its value. Perhaps you know for + sure that + x is of type Int, which is an instance of + Show, but GHCi does not have this information. + :print however is fine, because it does not need to know the + type to do its work. + Let's go on with the debugging session of the qsort + example: +A short debugging session + +qsort2.hs:2:15-46> x +This is an untyped, unevaluated computation. You can use seq to +force its evaluation and then :print to recover its type +qsort2.hs:2:15-46> seq x () +() +qsort2.hs:2:15-46> x +This is an untyped, unevaluated computation. You can use seq to +force its evaluation and then :print to recover its type + +qsort2.hs:2:15-46> :t x +x :: GHC.Base.Unknown +qsort2.hs:2:15-46> :p x +x - 10 +qsort2.hs:2:15-46> :t x +x :: Int + + + + + GHCi reminds us that this value is untyped, and instructs us to force its evaluation + + + This line forces the evaluation of x + + + Even though x has been evaluated, we cannot simply use its name to see its value! + This is a bit counterintuitive, but currently in GHCi the type of a binding + cannot be a type variable a. + Thus, the binding x gets assigned the concrete type Unknown. + + + We can explore x using the :print + command, which does find out that x is of type Int and prints + its value accordingly. + + + :print also updates the type of x with + the most concrete type information available. + + + The example shows the standard way to proceeed with polymorphic values in a breakpoint. + + + Commands + Breakpoints can be set in several ways using the :breakpoint command. Note that you can take advantage of the command abbreviation feature of GHCi and use simply :bre to save quite a few keystrokes. + + + + :breakpoint add module line + + + Adds a breakpoint at the first event found at line line in module, if any. + + + + + :breakpoint add module line column + + + Adds a breakpoint at the first event found after column column + at line line in module, if any. + + + + + + :breakpoint continue + + + When at a breakpoint, continue execution up to the next breakpoint + or end of evaluation. + + + + + + :continue + + + Shortcut for :breakpoint continue + + + + + + :breakpoint list + + + Lists the currently set up breakpoints. + + + + + :breakpoint del num + + + Deletes the breakpoint at position num in the list of + breakpoints shown by :breakpoint list. + + + + + :breakpoint del module line + + + Dels the breakpoint at line line in module, if any. + + + + + :breakpoint del module linecol + + + Deletes the first breakpoint found after column column + at line line in module, if any. + + + + + :breakpoint stop + + + Stop the program being executed. This interrupts a debugging session + and returns to the top level. + + + + + Debugging Higher-Order functions + It is possible to use the debugger to examine lambdas. + When we are at a breakpoint and a lambda is in scope, the debugger cannot show + you the source code that constitutes it; however, it is possible to get some + information by applying it to some arguments and observing the result. + + The process is slightly complicated when the binding is polymorphic. + We will use a example to show the process. + To keep it simple, we will use the well known map function: + +import Prelude hiding (map) + +map :: (a->b) -> a -> b +map f [] = [] +map f (x:xs) = f x : map f xs + + We set a breakpoint on map, and call it. + +*Main> :break map +Breakpoint 0 activated at map.hs:(4,0)-(5,12) +*Main> map Just [1..5] +Stopped at map.hs:(4,0)-(5,12) +_result :: [b] +x :: a +f :: a -> b +xs :: [a] + + GHCi tells us that, among other bindings, f is in scope. + However, its type is not fully known yet, + and thus it is not possible to apply it yet to any + arguments. Nevertheless, observe that the type of its first argument is the + same as the type of x, and its result type is the + same as the type of _result. + The debugger has some intelligence built-in to update the type of + f whenever the types of x or + _result are reconstructed. So what we do in this scenario is + force x a bit, in order to recover both its type + and the argument part of f. + +*Main> seq x () +*Main> :print x +x = 1 + + We can check now that as expected, the type of x + has been reconstructed, and with it the + type of f has been too: + +*Main> :t x +x :: Integer +*Main> :t f +f :: Integer -> b + + From here, we can apply f to any argument of type Integer and observe the + results. + let b = f 10 +*Main> :t b +b :: b +*Main> b +:1:0: + Ambiguous type variable `b' in the constraint: + `Show b' arising from a use of `print' at :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] + ]]> + In the first application of f, we had to do + some more type reconstruction + in order to recover the result type of f. + But after that, we are free to use + f normally. + + Tips + + * Use PRAGMAs to fine tune which modules are loaded under debugging mode + + {-# OPTIONS_GHC -fdebugging #-} + + + * Repeated use of seq and + :print may be necessary to observe unevaluated + untyped bindings + see + + + * GHC.Exts.unsafeCoerce can help if you are positive about the type of a binding + +type MyLongType a = [Maybe [Maybe a]] + +*Main> :m +GHC.Exts +*Main> main +Local bindings in scope: + x :: a +Main.hs:15> let x' = unsafeCoerce x :: MyLongType Bool +Main.hs:15> x' +[Just [Just False, Just True]] + + Note that a wrong coercion will likely result in your debugging session being interrupted by a segmentation fault + + + * The :force command + + equivalent to :print with automatic + seq forcing, + may prove useful to replace sequences of seq and + :print in some situations. + + + + + Limitations + + + + Implicit parameters (see ) are only available + at the scope of a breakpoint if there is a explicit type signature. + + + + + Modules compiled by GHCi under the -fdebugging + flag will perform slower: the debugging mode introduces some overhead. + Modules compiled to object code by ghc are not affected. + + + + + The <filename>.ghci</filename> file .ghcifile @@ -1438,7 +2034,33 @@ Prelude> :set -fno-glasgow-exts - + + Compiling to object code inside GHCi + + 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 + flag either on the command line or + with :set (the 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. + + Compiling to object code inside GHCi is particularly useful + if you are developing a compiled application, because the + :reload command typically runs much faster than + restarting GHC with from the command-line, + because all the interface files are already cached in + memory. + + 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. + + + FAQ and Things To Watch Out For @@ -1483,10 +2105,9 @@ Prelude> :set -fno-glasgow-exts Concurrent threads don't carry on running when GHCi is waiting for input. - No, they don't. This is because the Haskell binding - to the GNU readline library doesn't support reading from the - terminal in a non-blocking way, which is required to work - properly with GHC's concurrency model. + This should work, as long as your GHCi was built with + the switch, which is the default. + Consult whoever supplied your GHCi installation. @@ -1513,6 +2134,13 @@ Prelude> :set -fno-glasgow-exts + + I can't use Control-C to interrupt computations in + GHCi on Windows. + + See + +