skeleton transient-cycles.el

1 files changed, 80 insertions, 0 deletions

diff --git a/.emacs.d/site-lisp/transient-cycles.el b/.emacs.d/site-lisp/transient-cycles.el
new file mode 100644
index 00000000..709c5af0
--- /dev/null
+++ b/.emacs.d/site-lisp/transient-cycles.el
@@ -0,0 +1,80 @@
+;;; transient-cycles.el --- Define command variants with transient cycling  -*- lexical-binding: t -*-
+
+;; Copyright (C) 2020-2022 Sean Whitton
+;; (If extracting this functionality from my init.el works out, then I hope to
+;; submit it to GNU ELPA, so the copyright notice will change.)
+
+;; Author: Sean Whitton <spwhitton@spwhitton.name>
+;; Keywords: window, minor-mode, convenience
+
+;; This file is NOT part of GNU Emacs.
+
+;; This file is free software: you can redistribute it and/or modify
+;; it under the terms of the GNU General Public License as published by
+;; the Free Software Foundation, either version 3 of the License, or
+;; (at your option) any later version.
+
+;; This file is distributed in the hope that it will be useful,
+;; but WITHOUT ANY WARRANTY; without even the implied warranty of
+;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+;; GNU General Public License for more details.
+
+;; You should have received a copy of the GNU General Public License
+;; along with this file.  If not, see <https://www.gnu.org/licenses/>.
+
+;;; Commentary:
+
+;; Many commands can be conceptualised as selecting an item from an ordered
+;; list or ring.  Sometimes after running such a command, you find that the
+;; item selected is not the one you would have preferred, but the preferred
+;; item is nearby in the list.  If the command has been augmented with
+;; transient cycling, then it finishes by setting a transient map with keys to
+;; move backwards and forwards in the list of items, so you can select a
+;; nearby item instead of the one the command selected.  From the point of
+;; view of commands subsequent to the deactivation of the transient map, it is
+;; as though the first command actually selected the nearby item, not the one
+;; it really selected.
+;;
+;; For example, suppose that you often use C-u M-x eshell to create multiple
+;; Eshell buffers, such that you end up with *eshell*, *eshell*<2>,
+;; *eshell*<3> and so on.  When you use C-x b to switch to one of these
+;; buffers, you will typically end up in the most recently used Eshell.  But
+;; sometimes what you wanted was an older Eshell -- but which one?  It would
+;; be convenient to cycle through the other Eshell buffers when you discover
+;; that C-x b took you to the wrong one.  In this case, we can think of C-x b
+;; as selecting from the list of buffers in `eshell-mode'.  If we augment the
+;; command with transient cycling, then you can use the next and previous keys
+;; in the transient map to cycle through the `eshell-mode' buffers to get to
+;; the right one.  Afterwards, it is as though C-x b had taken you directly
+;; there: the buffer list is undisturbed except for the target Eshell buffer
+;; having been moved to the top, and only the target Eshell buffer is pushed
+;; to the window's previous buffers (see `window-prev-buffers').
+;;
+;; This library provides macros to define variants of commands which have
+;; transient cycling, and also some minor modes which replace some standard
+;; Emacs commands with transient cycling variants the author has found useful.
+;; `transient-cycles-buffer-siblings-mode' implements a more complex version
+;; of the transient cycling described in the preceding example.
+
+;;; Code:
+
+(require 'cl-lib)
+
+(defgroup transient-cycles nil
+  "Defaults when defining variants of commands with transient cycling.")
+
+(defcustom transient-cycles-default-cycle-backwards-key [up]
+  "Default key for cycling backwards in the transient maps set by
+commands augmented with transient cycling."
+  :type 'key-sequence
+  :group 'transient-cycles)
+
+(defcustom transient-cycles-default-cycle-forwards-key [down]
+  "Default key for cycling forwards in the transient maps set by
+commands augmented with transient cycling."
+  :type 'key-sequence
+  :group 'transient-cycles)
+
+(provide 'transient-cycles)
+
+;;; transient-cycles.el ends here