diff options
Diffstat (limited to 'docs/users_guide/ghci.rst')
| -rw-r--r-- | docs/users_guide/ghci.rst | 173 |
1 files changed, 141 insertions, 32 deletions
diff --git a/docs/users_guide/ghci.rst b/docs/users_guide/ghci.rst index fe481ae799..49a96caa0b 100644 --- a/docs/users_guide/ghci.rst +++ b/docs/users_guide/ghci.rst @@ -37,7 +37,7 @@ command ``ghci``: .. code-block:: none $ ghci - GHCi, version 8.0.1: http://www.haskell.org/ghc/ :? for help + GHCi, version 8.y.z: http://www.haskell.org/ghc/ :? for help Prelude> There may be a short pause while GHCi loads the prelude and standard @@ -69,6 +69,15 @@ 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. +Since GHC 8.0.1, you can bind values and functions to names without ``let`` statement: + +.. code-block:: none + + Prelude> x = 42 + Prelude> x + 42 + Prelude> + .. _loading-source-files: Loading source files @@ -129,6 +138,19 @@ them all in dependency order. Windows, then the current directory is probably something like ``C:\Documents and Settings\user name``. +.. ghc-flag:: -fshow-loaded-modules + :shortdesc: Show the names of modules that GHCi loaded after a + :ghci-cmd:`:load` command. + :type: dynamic + + :default: off + :since: 8.2.2 + + Typically GHCi will show only the number of modules that it loaded after a + :ghci-cmd:`:load` command. With this flag, GHC will also list the loaded + modules' names. This was the default behavior prior to GHC 8.2.1 and can be + useful for some tooling users. + .. _ghci-modules-filenames: @@ -425,6 +447,10 @@ The statement ``x <- return 42`` means “execute ``return 42`` in the future statements, for example to print it as we did above. .. ghc-flag:: -fprint-bind-result + :shortdesc: :ref:`Turn on printing of binding results in GHCi <ghci-stmts>` + :type: dynamic + :reverse: -fno-print-bind-result + :category: If :ghc-flag:`-fprint-bind-result` is set then GHCi will print the result of a statement if and only if: @@ -987,10 +1013,10 @@ of type ``a``. eg.: .. code-block:: none - Prelude> Time.getClockTime - Wed Mar 14 12:23:13 GMT 2001 + Prelude> Data.Time.getZonedTime + 2017-04-10 12:34:56.93213581 UTC Prelude> print it - Wed Mar 14 12:23:13 GMT 2001 + 2017-04-10 12:34:56.93213581 UTC The corresponding translation for an IO-typed ``e`` is @@ -1001,6 +1027,20 @@ The corresponding translation for an IO-typed ``e`` is Note that ``it`` is shadowed by the new value each time you evaluate a new expression, and the old value of ``it`` is lost. +In order to stop the value ``it`` being bound on each command, the flag +:ghc-flag:`-fno-it` can be set. The ``it`` variable can be the source +of space leaks due to how shadowed declarations are handled by +GHCi (see :ref:`ghci-decls`). + +.. ghc-flag:: -fno-it + :shortdesc: No longer set the special variable ``it``. + :type: dynamic + :reverse: -fno-no-it + :category: + + When this flag is set, the variable ``it`` will no longer be set + to the result of the previously evaluated expression. + .. _extended-default-rules: Type defaulting in GHCi @@ -1010,7 +1050,10 @@ Type defaulting in GHCi single: Type defaulting; in GHCi single: Show class -.. ghc-flag:: -XExtendedDefaultRules +.. extension:: ExtendedDefaultRules + :shortdesc: Use GHCi's extended default rules in a normal module. + + :since: 6.8.1 Allow defaulting to take place for more than just numeric classes. @@ -1044,7 +1087,7 @@ and defaults the type variable if 3. At least one of the classes ``Ci`` is numeric. -At the GHCi prompt, or with GHC if the :ghc-flag:`-XExtendedDefaultRules` flag +At the GHCi prompt, or with GHC if the :extension:`ExtendedDefaultRules` flag is given, the types are instead resolved with the following method: Find all the unsolved constraints. Then: @@ -1097,7 +1140,7 @@ Interactive classes .. index:: single: Interactive classes -The interactive classes (only relevant when :ghc-flag:`-XExtendedDefaultRules` +The interactive classes (only relevant when :extension:`ExtendedDefaultRules` is in effect) are: any numeric class, ``Show``, ``Eq``, ``Ord``, ``Foldable`` or ``Traversable``. @@ -1111,7 +1154,7 @@ Extended rules around ``default`` declarations single: default declarations Since the rules for defaulting are relaxed under -:ghc-flag:`-XExtendedDefaultRules`, the rules for ``default`` declarations +:extension:`ExtendedDefaultRules`, the rules for ``default`` declarations are also relaxed. According to Section 4.3.4 of the Haskell 2010 Report, a ``default`` declaration looks like ``default (t1, ..., tn)`` where, for each ``ti``, ``Num ti`` must hold. This is relaxed to say that for each @@ -1146,6 +1189,10 @@ it survive a :ghci-cmd:`:cd`, :ghci-cmd:`:add`, :ghci-cmd:`:load`, :ghci-cmd:`:reload` or, :ghci-cmd:`:set`. .. ghc-flag:: -interactive-print ⟨expr⟩ + :shortdesc: :ref:`Select the function to use for printing evaluated + expressions in GHCi <ghci-interactive-print>` + :type: dynamic + :category: Set the function used by GHCi to print evaluation results. Expression must be of type ``C a => a -> IO ()``. @@ -1162,7 +1209,7 @@ printed value. Running GHCi with the command: .. code-block:: none - ghci -interactive-print=SpecPrinter.sprinter SpecPrinter + ghci -interactive-print=SpecPrinter.sprint SpecPrinter will start an interactive session where values with be printed using ``sprint``: @@ -1735,6 +1782,10 @@ is we found that logging each breakpoint in the history cuts performance by a factor of 2 or more. .. ghc-flag:: -fghci-hist-size=⟨n⟩ + :shortdesc: Set the number of entries GHCi keeps for ``:history``. + See :ref:`ghci-debugger`. + :type: dynamic + :category: :default: 50 @@ -1799,12 +1850,26 @@ program was doing when it was in an infinite loop. Just hit Control-C, and examine the history to find out what was going on. .. ghc-flag:: -fbreak-on-exception - -fbreak-on-error + :shortdesc: :ref:`Break on any exception thrown <ghci-debugger-exceptions>` + :type: dynamic + :reverse: -fno-break-on-exception + :category: Causes GHCi to halt evaluation and return to the interactive prompt - in the event of an exception. While :ghc-flag:`-fbreak-on-exception` breaks - on all exceptions, :ghc-flag:`-fbreak-on-error` breaks on only those which - would otherwise be uncaught. + in the event of an exception. :ghc-flag:`-fbreak-on-exception` breaks + on all exceptions. + +.. ghc-flag:: -fbreak-on-error + :shortdesc: :ref:`Break on uncaught exceptions and errors + <ghci-debugger-exceptions>` + :type: dynamic + :reverse: -fno-break-on-error + :category: + + Causes GHCi to halt evaluation and return to the interactive prompt in the + event of an exception. :ghc-flag:`-fbreak-on-error` breaks on only those + exceptions which would otherwise be uncaught. + Example: inspecting functions ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -1945,15 +2010,31 @@ also make sense in interactive mode. The ones that don't make sense are mostly obvious. .. ghc-flag:: -flocal-ghci-history + :shortdesc: Use current directory for the GHCi command history + file ``.ghci-history``. + :type: dynamic + :reverse: -fno-local-ghci-history + :category: + + By default, GHCi keeps global history in ``~/.ghc/ghci_history`` or + ``%APPDATA%/<app>/ghci_history``, but you can use current directory, e.g.: - By default, GHCi keeps global history in ``~/.ghc/ghci_history`` or - ``%APPDATA%/<app>/ghci_history``, but you can use current directory, e.g.: + .. code-block:: none + + $ ghci -flocal-ghci-history - .. code-block:: none + It will create ``.ghci-history`` in current folder where GHCi is launched. - $ ghci -flocal-ghci-history +.. ghc-flag:: -fghci-leak-check + :shortdesc: (Debugging only) check for space leaks when loading + new modules in GHCi. + :type: dynamic + :reverse: -fno-ghci-leak-check + :category: - It will create ``.ghci-history`` in current folder where GHCi is launched. + (Debugging only) When loading new modules with ``:load``, check + that any previously loaded modules have been correctly garbage + collected. Emits messages if a leak is detected. Packages ~~~~~~~~ @@ -1971,7 +2052,7 @@ by using the :ghc-flag:`-package ⟨pkg⟩` flag: .. code-block:: none $ ghci -package readline - GHCi, version 6.8.1: http://www.haskell.org/ghc/ :? for help + GHCi, version 8.y.z: http://www.haskell.org/ghc/ :? for help Loading package base ... linking ... done. Loading package readline-1.0 ... linking ... done. Prelude> @@ -2006,17 +2087,28 @@ libraries, in this order: - Paths specified using the :ghc-flag:`-L ⟨dir⟩` command-line option, -- the standard library search path for your system, which on some +- The standard library search path for your system loader, which on some systems may be overridden by setting the :envvar:`LD_LIBRARY_PATH` environment variable. +- The linker standard library search can also be overriden on some systems using + the :envvar:`LIBRARY_PATH` environment variable. Because of some + implementation detail on Windows, setting ``LIBRARY_PATH`` will also extend + the system loader path for any library it finds. So often setting + :envvar:`LIBRARY_PATH` is enough. + On systems with ``.dll``-style shared libraries, the actual library -loaded will be ``lib.dll``. Again, GHCi will signal an error if it can't -find the library. +loaded will be ``lib.dll``, ``liblib.dll``. GHCi also has full support for +import libraries, either Microsoft style ``.lib``, or GNU GCC style ``.a`` and +``.dll.a`` libraries. If you have an import library it is advisable to always +specify the import libary instead of the ``.dll``. e.g. use ``-lgcc` instead of +``-llibgcc_s_seh-1``. Again, GHCi will signal an error if it can't find the +library. GHCi can also load plain object files (``.o`` or ``.obj`` depending on -your platform) from the command-line. Just add the name the object file -to the command line. +your platform) or static archives (``.a``) from the command-line. Just add the +name the object file or library to the command line. +On Windows GHCi also supports the ``big-obj`` format. Ordering of ``-l`` options matters: a library should be mentioned *before* the libraries it depends on (see :ref:`options-linker`). @@ -2238,17 +2330,17 @@ commonly used commands. .. code-block:: none - Prelude> let date _ = Time.getClockTime >>= print >> return "" + Prelude> let date _ = Data.Time.getZonedTime >>= print >> return "" Prelude> :def date date Prelude> :date - Fri Mar 23 15:16:40 GMT 2001 + 2017-04-10 12:34:56.93213581 UTC Here's an example of a command that takes an argument. It's a re-implementation of :ghci-cmd:`:cd`: .. code-block:: none - Prelude> let mycd d = Directory.setCurrentDirectory d >> return "" + Prelude> let mycd d = System.Directory.setCurrentDirectory d >> return "" Prelude> :def mycd mycd Prelude> :mycd .. @@ -2282,6 +2374,14 @@ commonly used commands. see the number of each breakpoint). The ``*`` form deletes all the breakpoints. +.. ghci-cmd:: :doc; ⟨name⟩ + + (Experimental: This command will likely change significantly in GHC 8.8.) + + Displays the documentation for the given name. Currently the command is + restricted to displaying the documentation directly on the declaration + in question, ignoring documentation for arguments, constructors etc. + .. ghci-cmd:: :edit; ⟨file⟩ Opens an editor to edit the file ⟨file⟩, or the most recently loaded @@ -2733,7 +2833,7 @@ commonly used commands. Infers and prints the type of ⟨expression⟩, but without fiddling with type variables or class constraints. This is useful when you - are using :ghc-flag:`-XTypeApplications` and care about the distinction + are using :extension:`TypeApplications` and care about the distinction between specified type variables (available for type application) and inferred type variables (not available). This mode sometimes prints constraints (such as ``Show Int``) that could readily be solved, but @@ -2745,13 +2845,13 @@ commonly used commands. *X> :type +v length length :: forall (t :: * -> *). Foldable t => forall a. t a -> Int -.. ghci-cmd:: :type +d ⟨expression⟩ +.. ghci-cmd:: :type +d; ⟨expression⟩ Infers and prints the type of ⟨expression⟩, defaulting type variables if possible. In this mode, if the inferred type is constrained by any interactive class (``Num``, ``Show``, ``Eq``, ``Ord``, ``Foldable``, or ``Traversable``), the constrained type variable(s) are defaulted - according to the rules described under :ghc-flag:`-XExtendedDefaultRules`. + according to the rules described under :extension:`ExtendedDefaultRules`. This mode is quite useful when the inferred type is quite general (such as for ``foldr``) and it may be helpful to see a more concrete instantiation. @@ -2946,7 +3046,7 @@ that option apply to loaded modules too. For example :seti -XMonoLocalBinds -It would be undesirable if :ghc-flag:`-XMonoLocalBinds` were to apply to loaded +It would be undesirable if :extension:`MonoLocalBinds` were to apply to loaded modules too: that might cause a compilation error, but more commonly it will cause extra recompilation, because GHC will think that it needs to recompile the module because the flags have changed. @@ -3054,11 +3154,17 @@ Two command-line options control whether the startup files files are read: .. ghc-flag:: -ignore-dot-ghci + :shortdesc: Disable reading of ``.ghci`` files + :type: dynamic + :category: Don't read either :file:`./.ghci` or the other startup files when starting up. .. ghc-flag:: -ghci-script + :shortdesc: Read additional ``.ghci`` files + :type: dynamic + :category: Read a specific file after the usual startup files. Maybe be specified repeatedly for multiple inputs. @@ -3109,7 +3215,7 @@ The ``.haskeline`` file GHCi uses `Haskeline <https://hackage.haskell.org/package/haskeline>`__ under the hood. You can configure it to, among other things, prune duplicates from GHCi history. See: -`Haskeline user preferences <http://trac.haskell.org/haskeline/wiki/UserPrefs>`__. +`Haskeline user preferences <https://github.com/judah/haskeline/wiki/UserPreferences>`__. .. _ghci-obj: @@ -3147,6 +3253,9 @@ separate process for running interpreted code, and communicate with it using messages over a pipe. .. ghc-flag:: -fexternal-interpreter + :shortdesc: Run interpreted code in a separate process + :type: dynamic + :category: misc :since: 8.0.1 |