X-Git-Url: http://git.megacz.com/?a=blobdiff_plain;f=docs%2Fusers_guide%2Fghci.xml;h=d9295484c85e2f84ddf5ea1550b7604f6898e7a4;hb=aedb94f5f220b5e442b23ecc445fd38c8d9b6ba0;hp=28e9972b24afadfc2cfba5d085f41eff34bec30c;hpb=806ab6331b967d6176b8790a0b1b551ec0e8e2b6;p=ghc-hetmet.git diff --git a/docs/users_guide/ghci.xml b/docs/users_guide/ghci.xml index 28e9972..d929548 100644 --- a/docs/users_guide/ghci.xml +++ b/docs/users_guide/ghci.xml @@ -202,12 +202,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 / \ @@ -298,6 +298,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 +334,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. - @@ -368,7 +395,6 @@ hello IO monad. Prelude> x <- return 42 -42 Prelude> print x 42 Prelude> @@ -380,7 +406,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 +420,8 @@ Prelude> Show - The automatic printing of binding results can be suppressed with - (this does not - suppress printing the result of non-binding statements). - . - You might want to do this to prevent the result of binding - statements from being fully evaluated by the act of printing - them, for example. + . + Of course, you can also bind normal non-IO expressions using the let-statement: @@ -542,10 +564,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 @@ -607,16 +633,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 @@ -641,6 +703,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"] + + @@ -819,10 +912,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: @@ -857,9 +952,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 @@ -1396,7 +1494,7 @@ a :: a *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 @@ -1442,7 +1540,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 @@ -1681,13 +1779,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. @@ -1745,6 +1846,32 @@ $ ghci -lm 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. + @@ -1817,26 +1944,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 @@ -1880,6 +2008,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. @@ -1963,6 +2097,17 @@ Prelude> :. cmds.ghci + + : + : + + + Repeat the previous command. + + + + + :history [num] :history @@ -2014,7 +2159,7 @@ Prelude> :. cmds.ghci - :load module ... + :load *module ... :load @@ -2031,6 +2176,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: @@ -2080,6 +2230,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"] + + @@ -2205,7 +2386,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. @@ -2521,18 +2704,34 @@ Prelude> :set -fno-glasgow-exts When it starts, unless the -ignore-dot-ghci - flag is given, GHCi reads and executes commands from - ./.ghci, followed by - $HOME/.ghci. - - The .ghci in your home directory is - most useful for turning on favourite options (eg. :set - +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 + 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: @@ -2545,8 +2744,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: @@ -2555,8 +2770,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. @@ -2565,8 +2780,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.