X-Git-Url: http://git.megacz.com/?a=blobdiff_plain;f=docs%2Fusers_guide%2Fghci.xml;h=72481eb24f2094da8ec7cfd6acf6b8338738401b;hb=75f9f3559b9959f067c893ae3f7c89da7fd18813;hp=7fd49e7e57a2a151708d2b00250ec246ed12e0dd;hpb=7494b4052881cf795cc828c8f84b89183a9a17e7;p=ghc-hetmet.git diff --git a/docs/users_guide/ghci.xml b/docs/users_guide/ghci.xml index 7fd49e7..72481eb 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” @@ -28,9 +28,12 @@ $ ghci -GHCi, version 6.8.1: http://www.haskell.org/ghc/ :? for help +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. -Prelude> +Loading package ffi-1.0 ... linking ... done. +Prelude> There may be a short pause while GHCi loads the prelude and @@ -51,12 +54,56 @@ 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, GHCi will attempt to evaluate it. + 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, + :set +m, + which is terminated by an empty line: + + +Prelude> :set +m +Prelude> let x = 42 in x / 9 +Prelude| +4.666666666666667 +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, + as in the above example. + + Multiline mode is useful when entering monadic + do statements: + + +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> + + + During a multiline interaction, the user can interrupt and + return to the top-level prompt. + + +Prelude> do +Prelude| putStrLn "Hello, World!" +Prelude| ^C +Prelude> + @@ -127,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 @@ -202,12 +249,12 @@ Ok, modules loaded: Main. very often, and use the interpreter for the code being actively developed. - When loading up source files with :load, - GHCi 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: + When loading up source modules with :load, + 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: A / \ @@ -232,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: @@ -255,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 @@ -298,6 +345,34 @@ Compiling A ( A.hs, interpreted ) Ok, modules loaded: A, B, C, D. + 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 ). For + this reason, you might sometimes want to force GHCi to load a + module using the interpreter. This can be done by prefixing + a * to the module name or filename when + using :load, for example + + +Prelude> :load *A +Compiling A ( A.hs, interpreted ) +*A> + + +When the * 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 :add *M to specify that you want + M to be interpreted (note that this might cause + other modules to be interpreted too, because compiled modules cannot + depend on interpreted ones). + +To always compile everything to object code and never use the + interpreter, use the -fobject-code option (see + ). + 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 @@ -306,7 +381,6 @@ Ok, modules loaded: A, B, C, D. interpreter. As you modify code, the changed modules will be interpreted, but the rest of the project will remain compiled. - @@ -355,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 @@ -368,7 +442,6 @@ hello IO monad. Prelude> x <- return 42 -42 Prelude> print x 42 Prelude> @@ -380,10 +453,11 @@ Prelude> x in future statements, for example to print it as we did above. - GHCi will print the result of a statement if and only if: + If is set then + 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. @@ -393,13 +467,8 @@ 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: @@ -424,6 +493,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 @@ -463,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 @@ -503,10 +611,14 @@ Compiling Main ( Main.hs, interpreted ) scopes from multiple modules, in any mixture of * and non-* forms. GHCi combines the scopes from all of these modules to form the scope - that is in effect at the prompt. For technical reasons, GHCi - can only support the *-form for modules which - are interpreted, so compiled modules and package modules can - only contribute their exports to the current scope. + that is in effect at the prompt. + + NOTE: for technical reasons, GHCi can only support the + *-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 * + when loading the module, e.g. :load *M. The scope is manipulated using the :module command. For example, if the current @@ -521,10 +633,12 @@ hello Prelude IO> - (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 + (Note: you can use conventional + haskell import syntax as + well, but this does not support + * forms). + :module can also be shortened to + :m. The full syntax of the :module command is: @@ -568,16 +682,52 @@ Prelude IO> + <literal>:module</literal> and + <literal>:load</literal> + + It might seem that :module and + :load do similar things: you can use both + to bring a module into scope. However, there is a clear + difference. GHCi is concerned with two sets of modules: + + + + The set of modules that are + currently loaded. This set is + modified + by :load, :add + and :reload. + + + + The set of modules that are currently in + scope at the prompt. This set is modified + by :module, and it is also set + automatically + after :load, :add, + and :reload. + + + + You cannot add a module to the scope if it is not + loaded. This is why trying to + use :module to load a new module results + in the message “module M is not + loaded”. + + + Qualified names To make life slightly easier, the GHCi prompt also behaves as if there is an implicit import qualified declaration for every module in every - package, and every module currently loaded into GHCi. + package, and every module currently loaded into GHCi. This + behaviour can be disabled with the flag . - The <literal>:main</literal> command + The <literal>:main</literal> and <literal>:run</literal> commands When a program is compiled and executed, it can use the @@ -602,15 +752,46 @@ Prelude> :main foo bar ["foo","bar"] + + 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: + + + +Prelude> :main foo "bar baz" +["foo","bar baz"] +Prelude> :main ["foo", "bar baz"] +["foo","bar baz"] + + + + Finally, other functions can be called, either with the + -main-is flag or the :run + command: + + + +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"] + + - + 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: @@ -623,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 @@ -682,19 +863,19 @@ it <- e ghci> reverse [] What should GHCi do? Strictly speaking, the program is ambiguous. show (reverse []) - (which is what GHCi computes here) has type Show a => a and how that displays depends + (which is what GHCi computes here) has type Show a => String and how that displays depends on the type a. For example: - ghci> (reverse []) :: String + ghci> reverse ([] :: String) "" - ghci> (reverse []) :: [Int] + ghci> reverse ([] :: [Int]) [] 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 98 Report (Revised)) as follows. The + 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 @@ -780,17 +961,19 @@ def = toEnum 0 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. + 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 debuggerNote that packages + only contain compiled code, so debugging a package requires + finding its source and loading that directly.. The debugger provides the following: 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. @@ -816,19 +999,22 @@ 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 context of an - error. - + 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 ). + 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) @@ -842,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: @@ -852,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: @@ -878,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) @@ -929,6 +1115,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 +1135,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 @@ -980,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. @@ -1011,12 +1205,13 @@ _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 now stopped at the breakpoint for a second time. + Setting breakpoints @@ -1040,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 @@ -1060,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. @@ -1094,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 *. @@ -1106,10 +1301,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,19 +1317,20 @@ _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: [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> @@ -1143,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> @@ -1239,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 @@ -1290,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 @@ -1330,16 +1530,20 @@ 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: *Main> :set -fbreak-on-exception *Main> :trace qsort ("abc" ++ undefined) -"Stopped at <exception thrown> +“Stopped at <exception thrown> _exception :: e [<exception thrown>] *Main> :hist -1 : qsort.hs:3:24-38 @@ -1371,21 +1575,21 @@ 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: import Prelude hiding (map) -map :: (a->b) -> a -> b +map :: (a->b) -> [a] -> [b] map f [] = [] map f (x:xs) = f x : map f xs @@ -1403,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. @@ -1413,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 @@ -1427,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 @@ -1437,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 @@ -1463,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. @@ -1487,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. @@ -1535,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 @@ -1553,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 @@ -1624,13 +1828,16 @@ $ ghci -lm - :add module ... + :add *module ... :add Add module(s) to the current target set, and perform a - reload. + 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 * + prefix forces the module to be loaded as byte-code. @@ -1662,22 +1869,58 @@ $ 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. + +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 + + + This output shows that, in the context of the current session, in the scope + of Prelude, the first group of items from + Data.Maybe have not been imported (but are available in + fully qualified form in the GHCi session - see ), whereas the second group of items have been + imported via Prelude and are therefore available either + unqualified, or with a Prelude. qualifier. + @@ -1718,7 +1961,7 @@ $ ghci -lm - :continue + :continue :continue Continue the current evaluation, when stopped at a @@ -1737,38 +1980,39 @@ $ 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 be interpreted for these commands to work. - See also . - + - :def name expr + :def! name expr :def - The command :def - name - expr defines a new GHCi command - :name, - implemented by the Haskell expression - expr, which must have type - String -> IO String. When - :name - args is typed at the - prompt, GHCi will run the expression - (name - args), take the - resulting String, and feed it back into - GHCi as a new sequence of commands. Separate commands in - the result must be separated by - ‘\n’. + :def is used to define new + commands, or macros, in GHCi. The command + :def name + expr defines a new GHCi command + :name, + implemented by the Haskell expression + expr, which must have type + String -> IO String. When + :name + args is typed at the + prompt, GHCi will run the expression + (name + args), take the + resulting String, and feed it back into + GHCi as a new sequence of commands. Separate commands in + the result must be separated by + ‘\n’. That's all a little confusing, so here's a few examples. To start with, here's a new GHCi command which @@ -1812,12 +2056,18 @@ Prelude> :. cmds.ghci :., by analogy with the ‘.’ Unix shell command that does the same thing. + + Typing :def on its own lists the + currently-defined macros. Attempting to redefine an + existing command name results in an error unless the + :def! form is used, in which case the old + command with that name is silently overwritten. - :delete * | num ... + :delete * | num ... :delete @@ -1845,6 +2095,15 @@ Prelude> :. cmds.ghci + :etags + + + See :ctags. + + + + + :force identifier ... :force @@ -1886,6 +2145,17 @@ Prelude> :. cmds.ghci + + : + : + + + Repeat the previous command. + + + + + :history [num] :history @@ -1913,6 +2183,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. @@ -1931,7 +2207,7 @@ Prelude> :. cmds.ghci - :load module ... + :load *module ... :load @@ -1948,6 +2224,11 @@ Prelude> :. cmds.ghci to unload all the currently loaded modules and bindings. + Normally pre-compiled code for a module will be loaded + if available, or otherwise the module will be compiled to + byte-code. Using the * prefix forces a + module to be loaded as byte-code. + After a :load command, the current context is set to: @@ -1981,7 +2262,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. @@ -1997,6 +2278,37 @@ Prelude> :main foo bar ["foo","bar"] + + 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: + + + +Prelude> :main foo "bar baz" +["foo","bar baz"] +Prelude> :main ["foo", "bar baz"] +["foo","bar baz"] + + + + Finally, other functions can be called, either with the + -main-is flag or the :run + command: + + + +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"] + + @@ -2026,7 +2338,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 @@ -2046,7 +2358,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. @@ -2067,14 +2379,38 @@ Prelude> :main foo bar + :run + :run + + + See :main. + + + + + + :script n + filename + :script + + + Executes the lines of a file as a series of GHCi commands. This command + is compatible with multiline statements as set by :set +m + + + + + + :set option... :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. @@ -2121,7 +2457,9 @@ Prelude> :main foo bar Inside prompt, the sequence %s is replaced by the names of the modules currently in scope, and %% is - replaced by %. + replaced by %. If prompt + starts with " then it is parsed as a Haskell String; + otherwise it is treated as a literal string. @@ -2191,12 +2529,34 @@ 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] :show @@ -2221,7 +2581,7 @@ Prelude> :main foo bar - :step [expr] + :step [expr] :step @@ -2302,7 +2662,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 @@ -2324,6 +2684,18 @@ Prelude> :main foo bar + +m + +m + + + Enable parsing of multiline commands. A multiline command + is prompted for when the current input line contains open layout + contexts. + + + + + +r +r CAFsin GHCi @@ -2337,7 +2709,7 @@ Prelude> :main foo 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. @@ -2385,7 +2757,7 @@ Prelude> :main foo bar Prelude> :set -fglasgow-exts - + Any GHC command-line option that is designated as dynamic (see the table in ), may be set using @@ -2414,18 +2786,35 @@ Prelude> :set -fno-glasgow-exts startupfiles, GHCi - When it starts, GHCi always reads and executes commands from - $HOME/.ghci, followed by - ./.ghci. - - The .ghci in your home directory is - most useful for turning on favourite options (eg. :set - +s), and defining useful macros. Placing a - .ghci 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 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 + When it starts, unless the -ignore-dot-ghci + flag is given, GHCi reads and executes commands from the following + files, in this order, if they exist: + + + + ./.ghci + + + appdata/ghc/ghci.conf, + where appdata depends on your system, + but is usually something like C:/Documents and Settings/user/Application Data + + + On Unix: $HOME/.ghc/ghci.conf + + + $HOME/.ghci + + + + The ghci.conf file is most useful for + turning on favourite options (eg. :set +s), and + defining useful macros. Placing a .ghci 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 GHC extensions + and CPP, and has source files in three subdirectories A, B and C, + you might put the following lines in .ghci: @@ -2438,8 +2827,24 @@ Prelude> :set -fno-glasgow-exts :set like this. The changes won't take effect until the next :load, though.) + Once you have a library of GHCi macros, you may want + to source them from separate files, or you may want to source + your .ghci file into your running GHCi + session while debugging it + + +:def source readFile + + + 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 + wiki page: GHC/GHCi + Two command-line options control whether the - .ghci files are read: + startup files files are read: @@ -2448,8 +2853,8 @@ Prelude> :set -fno-glasgow-exts - Don't read either ./.ghci or - $HOME/.ghci when starting up. + Don't read either ./.ghci or the + other startup files when starting up. @@ -2458,8 +2863,8 @@ Prelude> :set -fno-glasgow-exts - Read .ghci and - $HOME/.ghci. This is normally the + Read ./.ghci and the other + startup files (see above). This is normally the default, but the option may be used to override a previous option. @@ -2497,7 +2902,7 @@ Prelude> :set -fno-glasgow-exts FAQ and Things To Watch Out For - + The interpreter can't load modules with foreign export @@ -2573,7 +2978,26 @@ 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. + + + If you want line-buffered behaviour, as in GHC, you can + start your program thus: + + main = do { hSetBuffering stdout LineBuffering; ... } + + @@ -2583,7 +3007,6 @@ Prelude> :set -fno-glasgow-exts