From: Daniel Fischer Date: Mon, 30 May 2011 05:54:24 +0000 (+0200) Subject: ghci.xml whitespace only X-Git-Url: http://git.megacz.com/?p=ghc-hetmet.git;a=commitdiff_plain;h=2c4475595ef49267daf2939ef56dc3405dedfb12 ghci.xml whitespace only --- diff --git a/docs/users_guide/ghci.xml b/docs/users_guide/ghci.xml index 7c3fed2..d33ac8e 100644 --- a/docs/users_guide/ghci.xml +++ b/docs/users_guide/ghci.xml @@ -4,7 +4,7 @@ GHCi interpreterGHCi interactiveGHCi - + GHCi The ‘i’ stands for “Interactive” @@ -33,7 +33,7 @@ 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> +Prelude> There may be a short pause while GHCi loads the prelude and @@ -54,33 +54,33 @@ Prelude> 1+2 3 Prelude> let x = 42 in x / 9 4.666666666666667 -Prelude> +Prelude> GHCi interprets the whole line as an expression to evaluate. - The expression may not span several lines - as soon as you press enter, + The expression may not span several lines - as soon as you press enter, GHCi will attempt to evaluate it. - GHCi also has a multiline mode, + GHCi also has a multiline mode, :set +m, which is terminated by an empty line: Prelude> :set +m Prelude> let x = 42 in x / 9 -Prelude| +Prelude| 4.666666666666667 -Prelude> +Prelude> - + In Haskell, a let expression is followed - by in. However, in GHCi, since the expression - can also be interpreted in the IO monad, - a let binding with no accompanying - in statement can be signalled by an empty line, + by in. However, in GHCi, since the expression + can also be interpreted in the IO monad, + a let binding with no accompanying + in statement can be signalled by an empty line, as in the above example. - Multiline mode is useful when entering monadic + Multiline mode is useful when entering monadic do statements: @@ -94,7 +94,7 @@ Control.Monad.State| 0 Control.Monad.State> - + During a multiline interaction, the user can interrupt and return to the top-level prompt. @@ -174,7 +174,7 @@ Ok, modules loaded: Main. Modules vs. filenames modulesand filenames filenamesof modules - + Question: How does GHC find the filename which contains module M? Answer: it looks for the file M.hs, or @@ -279,7 +279,7 @@ Ok, modules loaded: A, B, C, D. because the source and everything it depends on is unchanged since the last compilation. - At any time you can use the command + At any time you can use the command :show modules to get a list of the modules currently loaded into GHCi: @@ -302,7 +302,7 @@ A ( A.hs, interpreted ) *Main> :reload Compiling D ( D.hs, interpreted ) Ok, modules loaded: A, B, C, D. -*Main> +*Main> Note that module D was compiled, but in this instance @@ -429,7 +429,7 @@ hello Using <literal>do-</literal>notation at the prompt do-notationin GHCi statementsin GHCi - + GHCi actually accepts statements rather than just expressions at the prompt. This means you can bind values and functions to names, and use them in future @@ -454,10 +454,10 @@ Prelude> it as we did above. If is set then - GHCi will print the result of a statement if and only if: + GHCi will print the result of a statement if and only if: - The statement is not a binding, or it is a monadic binding + The statement is not a binding, or it is a monadic binding (p <- e) that binds exactly one variable. @@ -501,9 +501,9 @@ Prelude> add 1 2 3 Prelude> - However, this quickly gets tedious when defining functions + 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, + 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 } @@ -525,9 +525,9 @@ Prelude> g (*) 1 [1..3] Such multiline commands can be used with any GHCi command, and the lines between :{ and - :} are simply merged into a single line for + :} 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. + 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. @@ -571,7 +571,7 @@ xs :: [Integer] - What's really in scope at the prompt? + What's really in scope at the prompt? When you type an expression at the prompt, what identifiers and types are in scope? GHCi provides a flexible @@ -637,7 +637,7 @@ Prelude IO> haskell import syntax as well, but this does not support * forms). - :module can also be shortened to + :module can also be shortened to :m. The full syntax of the :module command is: @@ -785,13 +785,13 @@ bar - + The <literal>it</literal> variable it - + Whenever an expression (or a non-binding statement, to be precise) is typed at the prompt, GHCi implicitly binds its value to the variable it. For example: @@ -804,7 +804,7 @@ Prelude> it * 2 What actually happens is that GHCi typechecks the expression, and if it doesn't have an IO type, then it transforms it as follows: an expression - e turns into + e turns into let it = e; print it @@ -875,7 +875,7 @@ it <- e rules (Section 4.3.4 of the Haskell 2010 Report) as follows. The standard rules take each group of constraints (C1 a, C2 a, ..., Cn a) for each type variable a, and defaults the - type variable if + type variable if @@ -973,7 +973,7 @@ def = toEnum 0 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 + 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. @@ -999,7 +999,7 @@ def = toEnum 0 - + 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 @@ -1007,14 +1007,14 @@ def = toEnum 0 automatically when an exception is thrown, even if it is thrown from within compiled code (see ). - + Breakpoints and inspecting variables - + Let's use quicksort as a running example. Here's the code: -qsort [] = [] +qsort [] = [] qsort (a:as) = qsort left ++ [a] ++ qsort right where (left,right) = (filter (<=a) as, filter (>a) as) @@ -1028,7 +1028,7 @@ Prelude> :l qsort.hs [1 of 1] Compiling Main ( qsort.hs, interpreted ) Ok, modules loaded: Main. *Main> - + Now, let's set a breakpoint on the right-hand-side of the second equation of qsort: @@ -1038,12 +1038,12 @@ Ok, modules loaded: Main. Breakpoint 0 activated at qsort.hs:2:15-46 *Main> - + The command :break 2 sets a breakpoint on line 2 of the most recently-loaded module, in this case qsort.hs. Specifically, it picks the leftmost complete subexpression on that line on which to set the - breakpoint, which in this case is the expression + breakpoint, which in this case is the expression (qsort left ++ [a] ++ qsort right). Now, we run the program: @@ -1064,8 +1064,8 @@ right :: [a] location, we can use the :list command: -[qsort.hs:2:15-46] *Main> :list -1 qsort [] = [] +[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) @@ -1138,7 +1138,7 @@ left = (_t1::[a]) 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 + only when the contents of the variable being inspected are completely evaluated. @@ -1174,7 +1174,7 @@ _t1 :: [Integer] [qsort.hs:2:15-46] *Main> a 8 - + You might find it useful to use Haskell's seq function to evaluate individual thunks rather than evaluating the whole expression with :force. @@ -1205,7 +1205,7 @@ _result :: [a] a :: a left :: [a] right :: [a] -[qsort.hs:2:15-46] *Main> +[qsort.hs:2:15-46] *Main> The execution continued at the point it previously stopped, and has @@ -1235,13 +1235,13 @@ right :: [a] :break line :break line column :break module line - :break module line column + :break module line column 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 + 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 @@ -1255,7 +1255,7 @@ right :: [a] and doesn't match others. The best advice is to avoid tab characters in your source code altogether (see in ). + />). If the module is omitted, then the most recently-loaded module is used. @@ -1289,7 +1289,7 @@ right :: [a] *Main> :delete 0 *Main> :show breaks [1] Main qsort.hs:2:15-46 - + To delete all breakpoints at once, use :delete *. @@ -1301,7 +1301,7 @@ 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. GHCi offers two variants of stepping. Use + 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 @@ -1320,7 +1320,7 @@ _result :: IO () expr begins the evaluation of expr in single-stepping mode. If expr is omitted, then it single-steps from - the current breakpoint. :stepover + the current breakpoint. :stepover works similarly. The :list command is particularly useful when @@ -1328,9 +1328,9 @@ _result :: IO () [qsort.hs:5:7-47] *Main> :list -4 +4 5 main = print (qsort [8, 4, 0, 3, 1, 23, 11, 18]) -6 +6 [qsort.hs:5:7-47] *Main> @@ -1343,9 +1343,9 @@ _result :: IO () [qsort.hs:5:7-47] *Main> :step Stopped at qsort.hs:5:14-46 _result :: [Integer] -4 +4 5 main = print (qsort [8, 4, 0, 3, 1, 23, 11, 18]) -6 +6 [qsort.hs:5:14-46] *Main> @@ -1439,13 +1439,13 @@ _result :: [a] *Main> :list qsort -1 qsort [] = [] +1 qsort [] = [] 2 qsort (a:as) = qsort left ++ [a] ++ qsort right 3 where (left,right) = (filter (<=a) as, filter (>a) as) -4 +4 *Main> :b 1 Breakpoint 1 activated at qsort.hs:1:11-12 -*Main> +*Main> and then run a small qsort with @@ -1490,7 +1490,7 @@ Logged breakpoint at qsort.hs:3:24-38 _result :: [a] as :: [a] a :: a -[-1: qsort.hs:3:24-38] *Main> +[-1: qsort.hs:3:24-38] *Main> Note that the local variables at each step in the history have been @@ -1532,10 +1532,10 @@ a :: a we can't set a breakpoint on it directly. For this reason, GHCi 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 + -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 + 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: @@ -1575,15 +1575,15 @@ as = 'b' : 'c' : (_t1::[Char]) Example: inspecting functions - It is possible to use the debugger to examine function values. + 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. + 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. - The process is slightly complicated when the binding is polymorphic. + 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 map function: @@ -1607,9 +1607,9 @@ 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 to any + 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 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 shared with _result. @@ -1617,12 +1617,12 @@ xs :: [a] As we demonstrated earlier (), the - debugger has some intelligence built-in to update the type of - f whenever the types of x or + debugger has some intelligence built-in to update the type of + f whenever the types of x or _result are discovered. 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. + force x a bit, in order to recover both its type + and the argument part of f. *Main> seq x () *Main> :print x @@ -1631,7 +1631,7 @@ x = 1 We can check now that as expected, the type of x - has been reconstructed, and with it the + has been reconstructed, and with it the type of f has been too: *Main> :t x @@ -1641,7 +1641,7 @@ f :: Integer -> b From here, we can apply f to any argument of type Integer and observe - the results. + the results. let b = f 10 *Main> :t b @@ -1667,10 +1667,10 @@ 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 + 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 + in order to recover the result type of f. + But after that, we are free to use f normally. @@ -1691,7 +1691,7 @@ Just 20 CAF at the prompt again. - Implicit parameters (see ) are only available + Implicit parameters (see ) are only available at the scope of a breakpoint if there is an explicit type signature. @@ -1739,7 +1739,7 @@ $ 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> +Prelude> The following command works to load new packages into a @@ -1757,7 +1757,7 @@ Prelude> :set -package name Extra libraries librarieswith GHCi - + Extra libraries may be specified on the command line using the normal -llib option. (The term library here refers to @@ -1889,11 +1889,11 @@ $ ghci -lm modules from packages) only the non-* form of :browse is available. If the ! symbol is appended to the - command, data constructors and class methods will be + 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 + 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. Prelude> :browse! Data.Maybe @@ -1961,7 +1961,7 @@ maybe :: b -> (a -> b) -> Maybe a -> b - :continue + :continue :continue Continue the current evaluation, when stopped at a @@ -2067,7 +2067,7 @@ Prelude> :. cmds.ghci - :delete * | num ... + :delete * | num ... :delete @@ -2095,7 +2095,7 @@ Prelude> :. cmds.ghci - :etags + :etags See :ctags. @@ -2185,9 +2185,9 @@ Prelude> :. cmds.ghci 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, + 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 + are in scope (either qualified or otherwise) as a result of a :load or :module commands. @@ -2389,7 +2389,7 @@ bar - :script n + :script n filename :script @@ -2581,7 +2581,7 @@ bar - :step [expr] + :step [expr] :step @@ -2709,7 +2709,7 @@ bar top-level expressions to be discarded after each evaluation (they are still retained during a single evaluation). - + This option may help if the evaluated top-level expressions are consuming large amounts of space, or if you need repeatable performance measurements. @@ -2757,7 +2757,7 @@ bar Prelude> :set -fglasgow-exts - + Any GHC command-line option that is designated as dynamic (see the table in ), may be set using @@ -2836,7 +2836,7 @@ Prelude> :set -fno-glasgow-exts :def source readFile - With this macro defined in your .ghci + With this macro defined in your .ghci file, you can use :source file to read GHCi commands from file. You can find (and contribute!-) other suggestions for .ghci files on this Haskell @@ -2902,7 +2902,7 @@ Prelude> :set -fno-glasgow-exts FAQ and Things To Watch Out For - + The interpreter can't load modules with foreign export @@ -2991,8 +2991,8 @@ Prelude> :set -fno-glasgow-exts because this is normally what you want in an interpreter: output appears as it is generated. - - If you want line-buffered behaviour, as in GHC, you can + + If you want line-buffered behaviour, as in GHC, you can start your program thus: main = do { hSetBuffering stdout LineBuffering; ... }