bug#69993: Wrap window buffers while cycling

[Juri Linkov]

> The Elisp manual says about 'switch-to-prev-buffer'
>
>      The previous buffer is usually the buffer shown before the buffer
>      currently shown in WINDOW.  However, a buffer that has been buried
>      or killed, or has been already shown by a recent invocation of
>      ‘switch-to-prev-buffer’, does not qualify as previous buffer.

I see that the Elisp manual also says about 'switch-to-prev-buffer':

 -- Command: bury-buffer &optional buffer-or-name
     ...
     (*note Quitting Windows::).  Otherwise, it calls
     ‘switch-to-prev-buffer’ (*note Window History::)
     to show another buffer in that window.

This means that it reuses switch-to-prev-buffer to show any available
buffer, even the buffers that were never shown in that window.

This means that such calls should be wrapped with let-bind
to handle the case when the list of prev/next-buffers becomes empty
to switch to any other buffer not shown in that window before:

@@ -4994,7 +5042,8 @@ bury-buffer
      (t
       ;; Switch to another buffer in window.
       (set-window-dedicated-p nil nil)
-      (switch-to-prev-buffer nil 'bury)))
+      (let ((switch-to-prev-buffer-wrap nil))
+        (switch-to-prev-buffer nil 'bury))))
     ;; Always return nil.
     nil))

Also for:

 -- Command: replace-buffer-in-windows &optional buffer-or-name
    ...
     The replacement buffer in each window is chosen via
     ‘switch-to-prev-buffer’ (*note Window History::).

need the same:

@@ -5145,7 +5194,8 @@ replace-buffer-in-windows
             (when (or dedicated-side (not (window--delete window t t)))
               ;; Switch to another buffer in that window.
               (set-window-dedicated-p window nil)
-              (if (switch-to-prev-buffer window 'kill)
+              (if (let ((switch-to-prev-buffer-wrap nil))
+                    (switch-to-prev-buffer window 'kill))
                   (and dedicated-side (set-window-dedicated-p window 'side))
                 (window--delete window nil 'kill))))
        ;; Unrecord BUFFER in WINDOW.

And for:

 -- Function: quit-restore-window &optional window bury-or-kill
    ...
    As a consequence, if WINDOW is not deleted, invoking
    ‘switch-to-prev-buffer’ will usually show the buffer again.

need the same:

@@ -5292,7 +5340,8 @@ quit-restore-window
       (set-window-dedicated-p window nil)
       ;; Try to switch to a previous buffer.  Delete the window only if
       ;; that is not possible (Bug#48367).
-      (if (switch-to-prev-buffer window bury-or-kill)
+      (if (let ((switch-to-prev-buffer-wrap nil))
+            (switch-to-prev-buffer window bury-or-kill))
           (when (eq dedicated 'side)
             (set-window-dedicated-p window 'side))
         (window--delete window nil (eq bury-or-kill 'kill))

The Elisp manual doesn't mention that delete-windows-on
uses switch-to-prev-buffer, unlike it mentions other functions:

  The ‘switch-to-prev-buffer’ command, in particular, is
  used by ‘replace-buffer-in-windows’, ‘bury-buffer’ and ‘quit-window’ to
  find a replacement buffer for a window.

but delete-windows-on still needs the same:

@@ -5116,7 +5164,8 @@ delete-windows-on
             (t
              ;; In window switch to previous buffer.
              (set-window-dedicated-p window nil)
-             (switch-to-prev-buffer window 'bury)
+             (let ((switch-to-prev-buffer-wrap nil))
+                (switch-to-prev-buffer window 'bury))
               ;; Restore the dedicated 'side' flag.
               (when (eq dedicated 'side)
                 (set-window-dedicated-p window 'side)))))

> Admittedly, "recent" is not very precise.  The idea is, among others,
> that an intervening C-x b will make "recent invocations" appear as if
> they never happened.

'C-x b' is not different from 'C-x <left>' and 'C-x <right>'
when the buffer selected for 'C-x b' was already shown in the window.

> I think the following is problematic:
>
>   (defun tab-line-switch-to-prev-tab (&optional event)
>     "Switch to the previous tab's buffer.
>   Its effect is the same as using the `previous-buffer' command
>   (\\[previous-buffer])."
>
> If the "previous tab" does not show the buffer 'switch-to-prev-buffer'
> would switch to, then the doc is wrong.  I'm not sure whether
> 'tab-line-tabs-window-buffers' can guarantee that this chooses the same
> buffer 'switch-to-prev-buffer' would switch to, though.  If it doesn't,
> then the effect should be that of C-x b switching to a buffer earlier
> shown in that window.  BTW, burying a buffer removes it from the tab
> line but does not prevent 'switch-to-prev-buffer' from switching to it -
> it just makes it very unlikely IIRC.

tab-line-switch-to-prev-tab doesn't choose buffers itself:
for tab-line-tabs-window-buffers it just delegates the task
to switch-to-prev-buffer.