X-Git-Url: http://git.megacz.com/?a=blobdiff_plain;f=docs%2Fusers_guide%2Fghci.xml;h=5daa29c9a12eb6faf5d9c6db5834e449bd9c5baa;hb=878ce92d0559e10a083b6983f2d23380086026d8;hp=3ba2012eee34a086f7cd4ac1cb7fa227c7f6c1a5;hpb=5263c9ab4408e3b62dbf7505ab40a81946d4e49b;p=ghc-hetmet.git diff --git a/docs/users_guide/ghci.xml b/docs/users_guide/ghci.xml index 3ba2012..5daa29c 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 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: @@ -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"] + + @@ -1403,7 +1468,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 @@ -1680,7 +1745,7 @@ $ ghci -lm - :browse *module ... + :browse! *module ... :browse @@ -1698,7 +1763,40 @@ $ ghci -lm *-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. + @@ -1771,26 +1869,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 @@ -1834,6 +1933,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. @@ -1917,6 +2022,17 @@ Prelude> :. cmds.ghci + + : + : + + + Repeat the previous command. + + + + + :history [num] :history @@ -2034,6 +2150,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"] + + @@ -2108,10 +2255,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. @@ -2234,6 +2382,28 @@ Prelude> :main foo bar + :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 @@ -2452,18 +2622,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: @@ -2477,7 +2663,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: @@ -2486,8 +2672,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. @@ -2496,8 +2682,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.