In `:break ident` allow out of scope and nested identifiers (Fix #3000)

This patch fixes the bug and implements the feature request of #3000.

1. If `Module` is a real module name and `identifier` a name of a
top-level function in `Module` then `:break Module.identifer` works
also for an `identifier` that is out of scope.

2. Extend the syntax for `:break identifier` to:

    :break [ModQual.]topLevelIdent[.nestedIdent]...[.nestedIdent]

`ModQual` is optional and is either the effective name of a module or
the local alias of a qualified import statement.

`topLevelIdent` is the name of a top level function in the module
referenced by `ModQual`.

`nestedIdent` is optional and the name of a function nested in a let or
where clause inside the previously mentioned function `nestedIdent` or
`topLevelIdent`.

If `ModQual` is a module name, then `topLevelIdent` can be any top level
identifier in this module. If `ModQual` is missing or a local alias of a
qualified import, then `topLevelIdent` must be in scope.

Breakpoints can be set on arbitrarily deeply nested functions, but the
whole chain of nested function names must be specified.

3. To support the new functionality rewrite the code to tab complete `:break`.

2 files changed, 48 insertions, 3 deletions

diff --git a/docs/users_guide/8.12.1-notes.rst b/docs/users_guide/8.12.1-notes.rst
index bc2414489f..1bf9464db4 100644
--- a/docs/users_guide/8.12.1-notes.rst
+++ b/docs/users_guide/8.12.1-notes.rst
@@ -161,6 +161,11 @@ GHCi
   passed as arguments: either by enclosing the file names in double quotes or by
   escaping spaces in file names with a backslash. (:ghc-ticket:`18027`)
 
+- The GHCi debugger syntax ``:break <qualified.name>`` now allows to set
+  breakpoints on all functions. The restrictions ``top-Level`` and ``exported``
+  have been removed. Hence it's now possible to use this syntax to set
+  breakpoints on functions defined in nested ``where`` or ``let`` clauses.
+
 Runtime system
 ~~~~~~~~~~~~~~
 
diff --git a/docs/users_guide/ghci.rst b/docs/users_guide/ghci.rst
index 390719ff80..9f63e0c50b 100644
--- a/docs/users_guide/ghci.rst
+++ b/docs/users_guide/ghci.rst
@@ -1520,12 +1520,52 @@ breakpoint is to name a top-level function:
 
 .. code-block:: none
 
-       :break identifier
+        :break identifier
 
 Where ⟨identifier⟩ names any top-level function in an interpreted module
 currently loaded into GHCi (qualified names may be used). The breakpoint
-will be set on the body of the function, when it is fully applied but
-before any pattern matching has taken place.
+will be set on the body of the function, when it is fully applied.
+If the function has several patterns, then a breakpoint will be set on
+each of them.
+
+By using qualified names, one can set breakpoints on all functions
+(top-level and nested) in every loaded and interpreted module:
+
+.. code-block:: none
+
+    :break [ModQual.]topLevelIdent[.nestedIdent]...[.nestedIdent]
+
+⟨ModQual⟩ is optional and is either the effective name of a module or
+the local alias of a qualified import statement.
+
+⟨topLevelIdent⟩ is the name of a top level function in the module
+referenced by ⟨ModQual⟩.
+
+⟨nestedIdent⟩ is optional and the name of a function nested in a let or
+where clause inside the previously mentioned function ⟨nestedIdent⟩ or
+⟨topLevelIdent⟩.
+
+If ⟨ModQual⟩ is a module name, then ⟨topLevelIdent⟩ can be any top level
+identifier in this module. If ⟨ModQual⟩ is missing or a local alias of a
+qualified import, then ⟨topLevelIdent⟩ must be in scope.
+
+Breakpoints can be set on arbitrarily deeply nested functions, but the
+whole chain of nested function names must be specified.
+
+Consider the function ``foo`` in a module ``Main``:
+
+.. code-block:: none
+
+    foo s = 'a' : add s
+        where add = (++"z")
+
+The breakpoint on the function ``add`` can be set with one of the
+following commands:
+
+.. code-block:: none
+
+       :break Main.foo.add
+       :break foo.add
 
 Breakpoints can also be set by line (and optionally column) number: