X-Git-Url: http://git.megacz.com/?a=blobdiff_plain;f=docs%2Fusers_guide%2Fghci.xml;h=7c3fed2e8b5b0902db94349d6141dd5d7340e7ca;hb=eccb2d89eb4b34f31e8ea337d5f8673605f71665;hp=bac55ed4312bdc72b594bf507d34779af4ad5e79;hpb=6a65049a2b80e42ec44ebd775be98a70101ac495;p=ghc-hetmet.git diff --git a/docs/users_guide/ghci.xml b/docs/users_guide/ghci.xml index bac55ed..7c3fed2 100644 --- a/docs/users_guide/ghci.xml +++ b/docs/users_guide/ghci.xml @@ -28,8 +28,11 @@ $ 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. +Loading package ffi-1.0 ... linking ... done. Prelude> @@ -55,8 +58,52 @@ 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> + @@ -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 / \ @@ -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. - @@ -537,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 @@ -555,10 +633,12 @@ hello Prelude IO> - (Note: you can use import M as an - alternative to :module +M, and + (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 + :m. The full syntax of the :module command is: @@ -602,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 @@ -636,6 +752,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"] + + @@ -716,16 +863,16 @@ 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 @@ -814,10 +961,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: @@ -852,9 +1001,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 @@ -1391,7 +1543,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 @@ -1437,7 +1589,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 @@ -1676,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. @@ -1740,6 +1895,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. + @@ -1806,8 +1987,7 @@ $ ghci -lm 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 . - + @@ -1965,6 +2145,17 @@ Prelude> :. cmds.ghci + + : + : + + + Repeat the previous command. + + + + + :history [num] :history @@ -2016,7 +2207,7 @@ Prelude> :. cmds.ghci - :load module ... + :load *module ... :load @@ -2033,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: @@ -2082,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"] + + @@ -2152,6 +2379,29 @@ 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 @@ -2207,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. @@ -2432,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 @@ -2523,18 +2787,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: @@ -2547,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: @@ -2557,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. @@ -2567,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. @@ -2695,6 +2991,13 @@ 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 + start your program thus: + + main = do { hSetBuffering stdout LineBuffering; ... } + + @@ -2704,7 +3007,6 @@ Prelude> :set -fno-glasgow-exts