X-Git-Url: http://git.megacz.com/?a=blobdiff_plain;f=ghc%2Fdocs%2Fusers_guide%2Fghci.sgml;h=668886211eeaacb511950212bbc05f605eef3886;hb=8cd11ef105d821cbcc62fbcc0d3eae34c6408f63;hp=412b0a5787bfe3dded911ad79e0d98755b235ab3;hpb=75034ecb9f9bc999548590a9ad23b993136c0dde;p=ghc-hetmet.git diff --git a/ghc/docs/users_guide/ghci.sgml b/ghc/docs/users_guide/ghci.sgml index 412b0a5..6688862 100644 --- a/ghc/docs/users_guide/ghci.sgml +++ b/ghc/docs/users_guide/ghci.sgml @@ -1,7 +1,8 @@ Using GHCi GHCi - interpreter + interpreterGHCi + interactiveGHCi GHCi The ‘i’ stands for “Interactive” @@ -13,6 +14,8 @@ also has support for interactively loading compiled code, as well as supporting allexcept the FFI, at the moment the language extensions that GHC provides. + FFIGHCi support + Foreign Function InterfaceGHCi support Introduction to GHCi @@ -24,7 +27,7 @@ $ ghci ___ ___ _ / _ \ /\ /\/ __(_) - / /_\// /_/ / / | | GHC Interactive, version 4.11, For Haskell 98. + / /_\// /_/ / / | | GHC Interactive, version 5.00, For Haskell 98. / /_\\/ __ / /___| | http://www.haskell.org/ghc/ \____/\/ /_/\____/|_| Type :? for help. @@ -70,7 +73,7 @@ Prelude> Prelude> 1+2 3 -PrePrelude> let x = 42 in x / 9 +Prelude> let x = 42 in x / 9 4.666666666666667 Prelude> @@ -96,6 +99,7 @@ fac n = n * fac (n-1) To load a Haskell source file into GHCi, use the :load command: + :load Prelude> :load Main @@ -127,6 +131,8 @@ Main> fac 17 Modules vs. filenames + modulesand filenames + filenamesof modules Question: How does GHC find the filename which contains module M? Answer: it looks for the @@ -151,6 +157,7 @@ Main> fac 17 Making changes and recompilation + :reload If you make some changes to the source code and want GHCi to recompile the program, give the :reload @@ -164,6 +171,7 @@ Main> fac 17 Loading compiled code + compiled codein GHCi When you load a Haskell source module into GHCi, it is normally converted to byte-code and run using the interpreter. @@ -300,11 +308,14 @@ hello 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 let it = - e in print it. It then runs - the new expression as an IO-action. + e turns into + + let it = e; + print it + + which is then run as an IO-action. - Hence the original expression must have a type which is an + Hence, the original expression must have a type which is an instance of the Show class, or GHCi will complain: @@ -329,8 +340,8 @@ in a `do' expression pattern binding: print it The context module is shown in the prompt: for example, the prompt Prelude> indicates that the current context for evaluating expressions is the Haskell - Prelude module. This is the default context - when you start up GHCi. + Prelude module. The Prelude is the default + context when you start up GHCi. Prelude Exactly which entities are in scope in a given context @@ -379,6 +390,8 @@ in a `do' expression pattern binding: print it 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 @@ -443,6 +456,7 @@ Prelude> HINT: if you turn on the +t option, GHCi will show the type of each variable bound by a statement. For example: + +t Prelude> :set +t Prelude> let (x:xs) = [1..] @@ -467,6 +481,16 @@ Prelude> it * 2 6 + This is a result of the translation mentioned earlier, + namely that an expression e is + translated to + + let it = e; + print it + + before execution, resulting in a binding for + it. + If the expression was of type IO a for some a, then it will be bound to the result of the IO computation, @@ -477,6 +501,13 @@ Prelude> print it Wed Mar 14 12:23:13 GMT 2001 + The corresponding translation for an IO-typed + e is + + it <- e + + + Note that it is shadowed by the new value each time you evaluate a new expression, and the old value of it is lost. @@ -486,13 +517,15 @@ Wed Mar 14 12:23:13 GMT 2001 Invoking GHCi + invokingGHCi + GHCi is invoked with the command ghci or ghc --interactive. A module or filename can also be specified on the command line; this instructs GHCi to load the that module or filename (and all the modules it depends on), - just as if you had said - :load module at the GHCi prompt + just as if you had said :load + module at the GHCi prompt (see ). For example, to start GHCi and load the program whose topmost module is in the file Main.hs, we could say: @@ -512,6 +545,7 @@ $ ghci Main.hs Packages + packageswith GHCi GHCi can make use of all the packages that come with GHC, but note: packages must be specified on the @@ -523,7 +557,7 @@ $ ghci Main.hs $ ghci -package text ___ ___ _ / _ \ /\ /\/ __(_) - / /_\// /_/ / / | | GHC Interactive, version 4.11, For Haskell 98. + / /_\// /_/ / / | | GHC Interactive, version 5.00, For Haskell 98. / /_\\/ __ / /___| | http://www.haskell.org/ghc/ \____/\/ /_/\____/|_| Type :? for help. @@ -542,6 +576,7 @@ Prelude> Extra libraries + librarieswith GHCi Extra libraries may be specified on the command line using the normal -llib @@ -581,6 +616,7 @@ $ ghci -lm :cd dir + :cd Changes the current working directory to dir. A @@ -592,15 +628,63 @@ $ ghci -lm - :def + :def name expr + :def - ToDo. + 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 + doesn't take any arguments or produce any results, it just + outputs the current date & time: + + +Prelude> let date _ = Time.getClockTime >>= print >> return "" +Prelude> :def date date +Prelude> :date +Fri Mar 23 15:16:40 GMT 2001 + + + Here's an example of a command that takes an argument. + It's a re-implementation of :cd: + + +Prelude> let mycd d = Directory.setCurrentDirectory d >> return "" +Prelude> :def mycd mycd +Prelude> :mycd .. + + + Or I could define a simple way to invoke + “ghc --make Main” in the + current directory: + + +Prelude> :def make (\_ -> return ":! ghc --make Main") + + :help + :help :? + :? Displays a list of the available commands. @@ -608,6 +692,7 @@ $ ghci -lm :load module + :load Recursively loads module (which may be a module name or filename), and all the @@ -619,6 +704,7 @@ $ ghci -lm :module module + :module Sets the current context for statements typed at the prompt to module, which must be a @@ -630,7 +716,8 @@ $ ghci -lm - :quit module + :quit + :quit Quits GHCi. You can also quit by typing a control-D at the prompt. @@ -639,6 +726,7 @@ $ ghci -lm :reload + :reload Attempts to reload the current target (see :load) if it, or any module it depends @@ -650,6 +738,7 @@ $ ghci -lm :set option... + :set Sets various options. See for a list of available options. The @@ -660,6 +749,7 @@ $ ghci -lm :type expression + :type Infers and prints the type of expression, including explicit @@ -670,7 +760,18 @@ $ ghci -lm + :undef name + :undef + + Undefines the user-defined command + name (see :def + above). + + + + :unset option... + :unset Unsets certain options. See for a list of available options. @@ -679,6 +780,8 @@ $ ghci -lm :! command... + :! + shell commandsin GHCi Executes the shell command command. @@ -690,64 +793,101 @@ $ ghci -lm The <literal>:set</literal> command + :set The :set command sets two types of options: GHCi options, which begin with ‘+” and “command-line” - options, which begin with ‘-’. Either type of option - may be set using :set and unset using - :unset. + options, which begin with ‘-’. - The available GHCi options are: + + GHCi options + optionsGHCi + - - - +r - - Normally, any evaluation of top-level expressions - (otherwise known as CAFs or Constant Applicative Forms) in - loaded modules is retained between evaluations. Turning on - +r causes all evaluation of top-level - expressions to be discarded after each evaluation (they are - still retained during a single - evaluation). + GHCi options may be set using :set and + unset using :unset. + + The available GHCi options are: + + + + +r + +r + CAFsin GHCi + Constant Applicative FormCAFs + + Normally, any evaluation of top-level expressions + (otherwise known as CAFs or Constant Applicative Forms) in + loaded modules is retained between evaluations. Turning + on +r causes all evaluation of + 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. - - + This option may help if the evaluated top-level + expressions are consuming large amounts of space, or if + you need repeatable performance measurements. + + + + + +s + +s + + Display some stats after evaluating each expression, + including the elapsed time and number of bytes allocated. + NOTE: the allocation figure is only accurate to the size + of the storage manager's allocation area, because it is + calculated at every GC. Hence, you might see values of + zero if no GC has occurred. + + + + + +t + +t + + Display the type of each variable bound after a + statement is entered at the prompt. If the statement is a + single expression, then the only variable binding will be + for the variable + ‘it’. + + + + - - +s - - Display some stats after evaluating each expression, - including the elapsed time and number of bytes allocated. - NOTE: the allocation figure is only accurate to the size of - the storage manager's allocation area, because it is - calculated at every GC. Hence, you might see values of zero - if no GC has occurred. - - + + Setting GHC command-line options in GHCi - - +t - - Display the type of each variable bound after a - statement is entered at the prompt. If the statement is a - single expression, then the only variable binding will be - for the variable ‘it’. - - - + Normal GHC command-line options may also be set using + :set. For example, to turn on + , you would say: - In addition, any normal GHC command-line option that is - designated as dynamic (see the table in - ), may be set using - :set. Certain static options - (, , and - in particular) will also work, but may not take effect until the - next reload. + +Prelude> :set -fglasgow-exts + + + Any GHC command-line option that is designated as + dynamic (see the table in ), may be set using + :set. To unset an option, you can set the + reverse option: + dynamicoptions + + +Prelude> :set -fno-glasgow-exts + + + lists the reverse for each + option where applicable. + + Certain static options (, + , and in particular) will + also work, but may not take effect until the next reload. + staticoptions + @@ -787,7 +927,25 @@ $ ghci -lm + GHCi complains about main not being + in scope when I load a module. + mainwith GHCi + + + You probably omitted the module + declaration at the top of the module, which causes the + module name to default to Main. In + Haskell, the Main module must define a + function called main. Admittedly this + doesn't make a great deal of sense for an interpreter, but + the rule was kept for compatibility with GHC. + + + + System.exit causes GHCi to exit! + System.exitin + GHCi Yes, it does.