From dcc1599f74d8115b3bd1bd87648866d89070a7e9 Mon Sep 17 00:00:00 2001 From: Krzysztof Gogolewski Date: Sun, 29 Aug 2021 23:07:43 +0200 Subject: Minor doc fixes - Fix markup in 9.4 release notes - Document -ddump-cs-trace - Mention that ImpredicativeTypes is really supported only since 9.2 - Remove "There are some restrictions on the use of unboxed tuples". This used to be a list, but all those restrictions were removed. - Mark -fimplicit-import-qualified as documented - Remove "The :main and :run command" - duplicated verbatim in options - Avoid calling "main" a function (cf. #7816) - Update System.getArgs: the old location was before hierarchical modules - Note that multiplicity multiplication is not supported (#20319) --- docs/users_guide/9.4.1-notes.rst | 18 +++--- docs/users_guide/debugging.rst | 6 ++ docs/users_guide/expected-undocumented-flags.txt | 2 - docs/users_guide/exts/impredicative_types.rst | 9 ++- docs/users_guide/exts/linear_types.rst | 1 + docs/users_guide/exts/primitives.rst | 38 ++++++------- docs/users_guide/ghci.rst | 72 ++++++------------------ ghc/GHCi/UI.hs | 4 +- 8 files changed, 58 insertions(+), 92 deletions(-) diff --git a/docs/users_guide/9.4.1-notes.rst b/docs/users_guide/9.4.1-notes.rst index 31c0fc3c46..2f3d822f45 100644 --- a/docs/users_guide/9.4.1-notes.rst +++ b/docs/users_guide/9.4.1-notes.rst @@ -42,17 +42,17 @@ Version 9.4.1 raise# :: forall (a :: Type) {r :: RuntimeRep} (b :: TYPE r). a -> b - ``GHC.Exts.reallyUnsafePtrEquality#`` has been made more general, as it is now - both levity-polymorphic and heterogeneous: :: + both levity-polymorphic and heterogeneous: :: reallyUnsafePtrEquality# :: forall {l :: Levity} (a :: TYPE (BoxedRep l)) {k :: Levity} (b :: TYPE (BoxedRep k)) . a -> b -> Int# - This means that ``GHC.Exts.reallyUnsafePtrEquality#`` can be used - on primitive arrays such as ``GHC.Exts.Array#`` and ``GHC.Exts.ByteArray#``. - It can also be used on values of different types, without needing to call - ``GHC.Exts.unsafeCoerce#``. + This means that ``GHC.Exts.reallyUnsafePtrEquality#`` can be used + on primitive arrays such as ``GHC.Exts.Array#`` and ``GHC.Exts.ByteArray#``. + It can also be used on values of different types, without needing to call + ``GHC.Exts.unsafeCoerce#``. - Added ``GHC.Exts.reallyUnsafePtrEquality`` which recovers the previous behaviour of ``GHC.Exts.reallyUnsafePtrEquality#``: :: @@ -74,8 +74,8 @@ Version 9.4.1 for computing the ``Type`` of an ``HsExpr GhcTc`` in a pure fashion. The ``hsLitType`` and ``hsPatType`` functions that previously lived in ``GHC.Tc.Utils.Zonk`` have been moved to this module. -- A `Typeable` constraint has been added to `fromStaticPtr` in the - class `GHC.StaticPtr.IsStatic`. GHC automatically wraps each use of - the `static` keyword with `fromStaticPtr`. Because `static` requires - its argument to be an instance of `Typeable`, `fromStaticPtr` can +- A ``Typeable`` constraint has been added to ``fromStaticPtr`` in the + class ``GHC.StaticPtr.IsStatic``. GHC automatically wraps each use of + the ``static`` keyword with ``fromStaticPtr``. Because ``static`` requires + its argument to be an instance of ``Typeable``, ``fromStaticPtr`` can safely carry this constraint as well. diff --git a/docs/users_guide/debugging.rst b/docs/users_guide/debugging.rst index 9e6664c152..f9e6946b20 100644 --- a/docs/users_guide/debugging.rst +++ b/docs/users_guide/debugging.rst @@ -151,6 +151,12 @@ These flags dump various information from GHC's typechecker and renamer. Make the pattern match exhaustiveness checker be *real* chatty about what it is up to. +.. ghc-flag:: -ddump-cs-trace + :shortdesc: Trace constraint solver + :type: dynamic + + Make the constraint solver be *real* chatty about what it is up to. + .. ghc-flag:: -ddump-rn-stats :shortdesc: Renamer stats :type: dynamic diff --git a/docs/users_guide/expected-undocumented-flags.txt b/docs/users_guide/expected-undocumented-flags.txt index 493a713e25..ed332eee5f 100644 --- a/docs/users_guide/expected-undocumented-flags.txt +++ b/docs/users_guide/expected-undocumented-flags.txt @@ -24,7 +24,6 @@ -dannot-lint -ddump-asm-conflicts -ddump-call-arity --ddump-cs-trace -ddump-debug -ddump-exitify -ddump-simpl-trace @@ -61,7 +60,6 @@ -fghci-history -fghci-sandbox -fhistory-size --fimplicit-import-qualified -fimplicit-params -fimplicit-prelude -firrefutable-tuples diff --git a/docs/users_guide/exts/impredicative_types.rst b/docs/users_guide/exts/impredicative_types.rst index 01d6476923..63017b8a2e 100644 --- a/docs/users_guide/exts/impredicative_types.rst +++ b/docs/users_guide/exts/impredicative_types.rst @@ -8,7 +8,7 @@ Impredicative polymorphism Implies :extension:`RankNTypes`. :implies: :extension:`RankNTypes` - :since: 6.10.1 + :since: 9.2.1 (unreliable in 6.10 - 9.0) Allow impredicative polymorphic types. @@ -34,13 +34,13 @@ inference algorithm. It is described in the paper Switching on :extension:`ImpredicativeTypes` -- Switches on :extension: `RankNTypes` +- Switches on :extension:`RankNTypes` - Allows user-written types to have foralls under type constructors, not just under arrows. For example ``f :: Maybe (forall a. [a] -> [a])`` is a legal type signature. - Allows polymorphic types in Visible Type Application - (when :extension: `TypeApplications` is enabled). For example, you + (when :extension:`TypeApplications` is enabled). For example, you can write ``reverse @(forall b. b->b) xs``. Using VTA with a polymorphic type argument is useful in cases when Quick Look cannot infer the correct instantiation. @@ -54,3 +54,6 @@ For many years GHC has a special case for the function ``($)``, that allows it to typecheck an application like ``runST $ (do { ... })``, even though that instantiation may be impredicative. This special case remains: even without :extension:`ImpredicativeTypes` GHC switches on Quick Look for applications of ``($)``. + +This flag was available in earlier versions of GHC (6.10.1 - 9.0), +but the behavior was unpredictable and not officially supported. diff --git a/docs/users_guide/exts/linear_types.rst b/docs/users_guide/exts/linear_types.rst index 5ed710d1c5..9985310d49 100644 --- a/docs/users_guide/exts/linear_types.rst +++ b/docs/users_guide/exts/linear_types.rst @@ -152,6 +152,7 @@ missing pieces. - Multiplicity polymorphism is incomplete and experimental. You may have success using it, or you may not. Expect it to be really unreliable. + (Multiplicity multiplication is not supported yet.) - There is currently no support for multiplicity annotations such as ``x :: a %p``, ``\(x :: a %p) -> ...``. - A ``case`` expression may consume its scrutinee ``One`` time, diff --git a/docs/users_guide/exts/primitives.rst b/docs/users_guide/exts/primitives.rst index 4f61f75f93..578ca1c4f7 100644 --- a/docs/users_guide/exts/primitives.rst +++ b/docs/users_guide/exts/primitives.rst @@ -172,35 +172,33 @@ primitive operations listed in ``primops.txt.pp`` return unboxed tuples. In particular, the ``IO`` and ``ST`` monads use unboxed tuples to avoid unnecessary allocation during sequences of operations. -There are some restrictions on the use of unboxed tuples: +The typical use of unboxed tuples is simply to return multiple +values, binding those multiple results with a ``case`` expression, +thus: -- The typical use of unboxed tuples is simply to return multiple - values, binding those multiple results with a ``case`` expression, - thus: +:: - :: - - f x y = (# x+1, y-1 #) - g x = case f x x of { (# a, b #) -> a + b } + f x y = (# x+1, y-1 #) + g x = case f x x of { (# a, b #) -> a + b } - You can have an unboxed tuple in a pattern binding, thus +You can have an unboxed tuple in a pattern binding, thus - :: +:: - f x = let (# p,q #) = h x in ..body.. + f x = let (# p,q #) = h x in ..body.. - If the types of ``p`` and ``q`` are not unboxed, the resulting - binding is lazy like any other Haskell pattern binding. The above - example desugars like this: +If the types of ``p`` and ``q`` are not unboxed, the resulting +binding is lazy like any other Haskell pattern binding. The above +example desugars like this: - :: +:: - f x = let t = case h x of { (# p,q #) -> (p,q) } - p = fst t - q = snd t - in ..body.. + f x = let t = case h x of { (# p,q #) -> (p,q) } + p = fst t + q = snd t + in ..body.. - Indeed, the bindings can even be recursive. +Indeed, the bindings can even be recursive. .. _unboxed-sums: diff --git a/docs/users_guide/ghci.rst b/docs/users_guide/ghci.rst index ebafc7fda5..f9d0a60df6 100644 --- a/docs/users_guide/ghci.rst +++ b/docs/users_guide/ghci.rst @@ -873,14 +873,19 @@ done with ordinary ``import`` declarations: Qualified names ^^^^^^^^^^^^^^^ +.. ghc-flag:: -fimplicit-import-qualified + :shortdesc: Put in scope qualified identifiers for every loaded module + :type: dynamic + :reverse: -fno-implicit-import-qualified + :category: + + :default: on + 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. This behaviour can be disabled with the ``-fno-implicit-import-qualified`` flag. -.. index:: - single: -fno-implicit-import-qualified - ``:module`` and ``:load`` ^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -905,50 +910,6 @@ GHCi knows about. Using :ghci-cmd:`:module` or ``import`` to try bring into scope a non-loaded module may result in the message ``module M is not loaded``. -The ``:main`` and ``:run`` commands -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -When a program is compiled and executed, it can use the ``getArgs`` -function to access the command-line arguments. However, we cannot simply -pass the arguments to the ``main`` function while we are testing in -ghci, as the ``main`` function doesn't take its directly. - -Instead, we can use the :ghci-cmd:`:main` command. This runs whatever ``main`` -is in scope, with any arguments being treated the same as command-line -arguments, e.g.: - -.. code-block:: none - - ghci> main = System.Environment.getArgs >>= print - ghci> :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: - -.. code-block:: none - - ghci> :main foo "bar baz" - ["foo","bar baz"] - ghci> :main ["foo", "bar baz"] - ["foo","bar baz"] - -Finally, other functions can be called, either with the ``-main-is`` -flag or the :ghci-cmd:`:run` command: - -.. code-block:: none - - ghci> foo = putStrLn "foo" >> System.Environment.getArgs >>= print - ghci> bar = putStrLn "bar" >> System.Environment.getArgs >>= print - ghci> :set -main-is foo - ghci> :main foo "bar baz" - foo - ["foo","bar baz"] - ghci> :run bar ["foo", "bar baz"] - bar - ["foo","bar baz"] - The ``it`` variable ~~~~~~~~~~~~~~~~~~~ @@ -2650,7 +2611,7 @@ commonly used commands. Adding the optional "``!``" turns type errors into warnings while loading. This allows to use the portions of the module that are correct, even if there are type errors in some definitions. - Effectively, the "-fdefer-type-errors" flag is set before loading + Effectively, the :ghc-flag:`-fdefer-type-errors` flag is set before loading and unset after loading if the flag has not already been set before. See :ref:`defer-type-errors` for further motivation and details. @@ -2681,10 +2642,9 @@ commonly used commands. .. ghci-cmd:: :main; ⟨arg1⟩ ... ⟨argn⟩ When a program is compiled and executed, it can use the ``getArgs`` - function to access the command-line arguments. However, we cannot - simply pass the arguments to the ``main`` function while we are - testing in ghci, as the ``main`` function doesn't take its arguments - directly. + IO action to access the command-line arguments. However, we cannot + simply pass the arguments to ``main`` while we are testing in ghci, + as ``main`` doesn't take its arguments directly. Instead, we can use the :ghci-cmd:`:main` command. This runs whatever ``main`` is in scope, with any arguments being treated the same as @@ -2707,7 +2667,7 @@ commonly used commands. ghci> :main ["foo", "bar baz"] ["foo","bar baz"] - Finally, other functions can be called, either with the ``-main-is`` + Finally, other IO actions can be called, either with the ``-main-is`` flag or the :ghci-cmd:`:run` command: .. code-block:: none @@ -2757,7 +2717,7 @@ commonly used commands. Adding the optional "``!``" turns type errors into warnings while loading. This allows to use the portions of the module that are correct, even if there are type errors in some definitions. - Effectively, the "-fdefer-type-errors" flag is set before loading + Effectively, the :ghc-flag:`-fdefer-type-errors` flag is set before loading and unset after loading if the flag has not already been set before. See :ref:`defer-type-errors` for further motivation and details. @@ -2787,7 +2747,7 @@ commonly used commands. single: getArgs, behavior in GHCi Sets the list of arguments which are returned when the program calls - ``System.getArgs``. + ``System.Environment.getArgs``. .. ghci-cmd:: :set editor; ⟨cmd⟩ @@ -2810,7 +2770,7 @@ commonly used commands. single: getProgName, behavior in GHCi Sets the string to be returned when the program calls - ``System.getProgName``. + ``System.Environment.getProgName``. .. ghci-cmd:: :set prompt; ⟨prompt⟩ diff --git a/ghc/GHCi/UI.hs b/ghc/GHCi/UI.hs index 3bd7f0820c..369002b8bc 100644 --- a/ghc/GHCi/UI.hs +++ b/ghc/GHCi/UI.hs @@ -390,8 +390,8 @@ defFullHelpText = " :set local-config { source | ignore }\n" ++ " set whether to source .ghci in current dir\n" ++ " (loading untrusted config is a security issue)\n" ++ - " :set args ... set the arguments returned by System.getArgs\n" ++ - " :set prog set the value returned by System.getProgName\n" ++ + " :set args ... set the arguments returned by System.Environment.getArgs\n" ++ + " :set prog set the value returned by System.Environment.getProgName\n" ++ " :set prompt set the prompt used in GHCi\n" ++ " :set prompt-cont set the continuation prompt used in GHCi\n" ++ " :set prompt-function set the function to handle the prompt\n" ++ -- cgit v1.2.1