X-Git-Url: http://git.megacz.com/?p=ghc-hetmet.git;a=blobdiff_plain;f=docs%2Fusers_guide%2Fghci.xml;h=35aa7cd279e4cf48400447b93c1425946f8f5c92;hp=7d07f9b4c499b12938587858ef607a70c9a826d7;hb=e16acfd0329fbd10a1ff1bf808eb3b795fe1f56c;hpb=9fa5ced11b0955f69773b2bd616441c69c7d1068 diff --git a/docs/users_guide/ghci.xml b/docs/users_guide/ghci.xml index 7d07f9b..35aa7cd 100644 --- a/docs/users_guide/ghci.xml +++ b/docs/users_guide/ghci.xml @@ -368,7 +368,6 @@ hello IO monad. Prelude> x <- return 42 -42 Prelude> print x 42 Prelude> @@ -380,7 +379,8 @@ 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 @@ -393,13 +393,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 +419,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 +611,7 @@ Prelude IO> - 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,6 +636,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"] + + @@ -780,10 +845,12 @@ 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: @@ -818,9 +885,12 @@ 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 @@ -929,6 +999,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 +1019,13 @@ left = (_t1::[a]) underscore, in this case _t1. + The flag -fprint-evld-with-show instructs + :print to reuse + available Show instances when possible. This happens + only when the contents of the variable being inspected + are completely evaluated. + + If we aren't concerned about preserving the evaluatedness of a variable, we can use :force instead of :print. The :force command @@ -1017,7 +1095,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 @@ -1106,10 +1185,14 @@ right :: [a] Single-stepping is a great way to visualise the execution of your program, and it is also a useful tool for identifying the source of a - bug. The concept is simple: single-stepping enables all the - breakpoints in the program and executes until the next breakpoint is - reached, at which point you can single-step again, or continue - normally. For example: + bug. GHCi offers two variants of stepping. Use + :step to enable all the + breakpoints in the program, and execute until the next breakpoint is + reached. Use :steplocal to limit the set + of enabled breakpoints to those in the current top level function. + Similarly, use :stepmodule to single step only on + breakpoints contained in the current module. + For example: *Main> :step main @@ -1118,10 +1201,11 @@ _result :: IO () The command :step - expr begins the evaluation of + expr begins the evaluation of expr in single-stepping mode. If - expr is ommitted, then it single-steps from - the current breakpoint. + expr is omitted, then it single-steps from + the current breakpoint. :stepover + works similarly. The :list command is particularly useful when single-stepping, to see where you currently are: @@ -1330,9 +1414,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: @@ -1385,7 +1473,7 @@ as = 'b' : 'c' : (_t1::[Char]) 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 @@ -1662,22 +1750,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. + @@ -1704,16 +1828,6 @@ $ ghci -lm - :continue - :continue - - Continue the current evaluation, when stopped at a - breakpoint. - - - - - :cmd expr :cmd @@ -1728,6 +1842,16 @@ $ ghci -lm + :continue + :continue + + Continue the current evaluation, when stopped at a + breakpoint. + + + + + :ctags filename :etags filename :etags @@ -1737,8 +1861,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 @@ -1749,26 +1874,27 @@ $ ghci -lm - :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,6 +1938,12 @@ 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. @@ -1845,6 +1977,15 @@ Prelude> :. cmds.ghci + :etags + + + See :ctags. + + + + + :force identifier ... :force @@ -1886,6 +2027,17 @@ Prelude> :. cmds.ghci + + : + : + + + Repeat the previous command. + + + + + :history [num] :history @@ -1913,6 +2065,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. @@ -1981,7 +2139,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 +2155,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 +2215,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 +2235,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. @@ -2071,10 +2260,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. @@ -2191,12 +2381,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 @@ -2302,7 +2514,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 @@ -2414,18 +2626,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 + 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 .ghci: @@ -2439,7 +2668,7 @@ Prelude> :set -fno-glasgow-exts until the next :load, though.) Two command-line options control whether the - .ghci files are read: + startup files files are read: @@ -2448,8 +2677,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 +2687,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. @@ -2573,7 +2802,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. +