From d1ab0c7cbcda92114cce4d51b36aac5f07d26e4d Mon Sep 17 00:00:00 2001
From: William Carroll <wpcarro@gmail.com>
Date: Fri, 29 Jul 2022 21:12:59 -0700
Subject: feat(wpcarro/emacs): Package cycle.el

This will likely break a few things since I've changed the names of a few
functions to reflect their mutative APIs.

Change-Id: If6279999fba50813b68e66d7713c12afd209eb90
Reviewed-on: https://cl.tvl.fyi/c/depot/+/6004
Reviewed-by: wpcarro <wpcarro@gmail.com>
Autosubmit: wpcarro <wpcarro@gmail.com>
Tested-by: BuildkiteCI
---
 users/wpcarro/emacs/.emacs.d/wpc/buffer.el         |   4 +-
 users/wpcarro/emacs/.emacs.d/wpc/colorscheme.el    |   6 +-
 users/wpcarro/emacs/.emacs.d/wpc/cycle.el          | 224 ---------------------
 users/wpcarro/emacs/.emacs.d/wpc/fonts.el          |   6 +-
 users/wpcarro/emacs/.emacs.d/wpc/irc.el            |   4 +-
 users/wpcarro/emacs/.emacs.d/wpc/vterm-mgt.el      |  14 +-
 users/wpcarro/emacs/.emacs.d/wpc/window-manager.el |  14 +-
 users/wpcarro/emacs/default.nix                    |   1 +
 users/wpcarro/emacs/pkgs/cycle/cycle.el            | 202 +++++++++++++++++++
 users/wpcarro/emacs/pkgs/cycle/default.nix         |  34 ++++
 users/wpcarro/emacs/pkgs/cycle/tests.el            |  80 ++++++++
 11 files changed, 341 insertions(+), 248 deletions(-)
 delete mode 100644 users/wpcarro/emacs/.emacs.d/wpc/cycle.el
 create mode 100644 users/wpcarro/emacs/pkgs/cycle/cycle.el
 create mode 100644 users/wpcarro/emacs/pkgs/cycle/default.nix
 create mode 100644 users/wpcarro/emacs/pkgs/cycle/tests.el

diff --git a/users/wpcarro/emacs/.emacs.d/wpc/buffer.el b/users/wpcarro/emacs/.emacs.d/wpc/buffer.el
index ede3d3e68d05..0f86f7f811e6 100644
--- a/users/wpcarro/emacs/.emacs.d/wpc/buffer.el
+++ b/users/wpcarro/emacs/.emacs.d/wpc/buffer.el
@@ -143,12 +143,12 @@ Return a reference to that buffer."
 (defun buffer-cycle-next ()
   "Cycle forward through the `buffer-source-code-buffers'."
   (interactive)
-  (buffer-cycle #'cycle-next))
+  (buffer-cycle #'cycle-next!))
 
 (defun buffer-cycle-prev ()
   "Cycle backward through the `buffer-source-code-buffers'."
   (interactive)
-  (buffer-cycle #'cycle-prev))
+  (buffer-cycle #'cycle-prev!))
 
 (defun buffer-ivy-source-code ()
   "Use `ivy-read' to choose among all open source code buffers."
diff --git a/users/wpcarro/emacs/.emacs.d/wpc/colorscheme.el b/users/wpcarro/emacs/.emacs.d/wpc/colorscheme.el
index cc2afd6c5770..20d209f895eb 100644
--- a/users/wpcarro/emacs/.emacs.d/wpc/colorscheme.el
+++ b/users/wpcarro/emacs/.emacs.d/wpc/colorscheme.el
@@ -51,7 +51,7 @@ There is no hook that I'm aware of to handle this more elegantly."
 
 (defun colorscheme-whitelist-set (colorscheme)
   "Focus the COLORSCHEME in the `colorscheme-whitelist' cycle."
-  (cycle-focus (lambda (x) (equal x colorscheme)) colorscheme-whitelist)
+  (cycle-focus! (lambda (x) (equal x colorscheme)) colorscheme-whitelist)
   (colorscheme-set (colorscheme-current)))
 
 (defun colorscheme-ivy-select ()
@@ -66,8 +66,8 @@ There is no hook that I'm aware of to handle this more elegantly."
 Cycle prev otherwise."
   (disable-theme (cycle-current colorscheme-whitelist))
   (let ((theme (if forward?
-                   (cycle-next colorscheme-whitelist)
-                 (cycle-prev colorscheme-whitelist))))
+                   (cycle-next! colorscheme-whitelist)
+                 (cycle-prev! colorscheme-whitelist))))
     (colorscheme-set theme)
     (message (s-concat "Active theme: " (symbol-to-string theme)))))
 
diff --git a/users/wpcarro/emacs/.emacs.d/wpc/cycle.el b/users/wpcarro/emacs/.emacs.d/wpc/cycle.el
deleted file mode 100644
index a1853ece1431..000000000000
--- a/users/wpcarro/emacs/.emacs.d/wpc/cycle.el
+++ /dev/null
@@ -1,224 +0,0 @@
-;;; cycle.el --- Simple module for working with cycles -*- lexical-binding: t -*-
-
-;; Author: William Carroll <wpcarro@gmail.com>
-;; Version: 0.0.1
-;; Package-Requires: ((emacs "24.3"))
-
-;;; Commentary:
-;; Something like this may already exist, but I'm having trouble finding it, and
-;; I think writing my own is a nice exercise for learning more Elisp.
-
-;;; Code:
-
-;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
-;; Dependencies
-;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
-
-(require 'prelude)
-(require 'math)
-(require 'maybe)
-(require 'struct)
-(require 'cl-lib)
-
-;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
-;; Wish list
-;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
-
-;; - TODO: Provide immutable variant.
-;; - TODO: Replace mutable consumption with immutable variant.
-;; - TODO: Replace indexing with (math-mod current cycle).
-
-;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
-;; Library
-;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
-
-;; `current-index' tracks the current index
-;; `xs' is the original list
-(cl-defstruct cycle current-index previous-index xs)
-
-(defconst cycle-enable-tests? t
-  "When t, run the tests defined herein.")
-
-(defun cycle-from-list (xs)
-  "Create a cycle from a list of `XS'."
-  (if (= 0 (length xs))
-      (make-cycle :current-index nil
-                  :previous-index nil
-                  :xs xs)
-    (make-cycle :current-index 0
-                :previous-index nil
-                :xs xs)))
-
-(defun cycle-new (&rest xs)
-  "Create a cycle with XS as the values."
-  (cycle-from-list xs))
-
-(defun cycle-to-list (xs)
-  "Return the list representation of a cycle, XS."
-  (cycle-xs xs))
-
-(defun cycle--next-index<- (lo hi x)
-  "Return the next index in a cycle when moving downwards.
-- `LO' is the lower bound.
-- `HI' is the upper bound.
-- `X' is the current index."
-  (if (< (- x 1) lo)
-      (- hi 1)
-    (- x 1)))
-
-(defun cycle--next-index-> (lo hi x)
-  "Return the next index in a cycle when moving upwards.
-- `LO' is the lower bound.
-- `HI' is the upper bound.
-- `X' is the current index."
-  (if (>= (+ 1 x) hi)
-      lo
-    (+ 1 x)))
-
-(defun cycle-previous-focus (cycle)
-  "Return the previously focused entry in CYCLE."
-  (let ((i (cycle-previous-index cycle)))
-    (if (maybe-some? i)
-        (nth i (cycle-xs cycle))
-      nil)))
-
-;; TODO: Consider adding "!" to the function name herein since many of them
-;; mutate the collection, and the APIs are beginning to confuse me.
-(defun cycle-focus-previous! (xs)
-  "Jump to the item in XS that was most recently focused; return the cycle.
-This will error when previous-index is nil.  This function mutates the
-underlying struct."
-  (let ((i (cycle-previous-index xs)))
-    (if (maybe-some? i)
-        (progn
-          (cycle-jump i xs)
-          (cycle-current xs))
-      (error "Cannot focus the previous element since cycle-previous-index is nil"))))
-
-(defun cycle-next (xs)
-  "Return the next value in `XS' and update `current-index'."
-  (let* ((current-index (cycle-current-index xs))
-         (next-index (cycle--next-index-> 0 (cycle-count xs) current-index)))
-    (struct-set! cycle previous-index current-index xs)
-    (struct-set! cycle current-index next-index xs)
-    (nth next-index (cycle-xs xs))))
-
-(defun cycle-prev (xs)
-  "Return the previous value in `XS' and update `current-index'."
-  (let* ((current-index (cycle-current-index xs))
-         (next-index (cycle--next-index<- 0 (cycle-count xs) current-index)))
-    (struct-set! cycle previous-index current-index xs)
-    (struct-set! cycle current-index next-index xs)
-    (nth next-index (cycle-xs xs))))
-
-(defun cycle-current (cycle)
-  "Return the current value in `CYCLE'."
-  (nth (cycle-current-index cycle) (cycle-xs cycle)))
-
-(defun cycle-count (cycle)
-  "Return the length of `xs' in `CYCLE'."
-  (length (cycle-xs cycle)))
-
-(defun cycle-jump (i xs)
-  "Jump to the I index of XS."
-  (let ((current-index (cycle-current-index xs))
-        (next-index (math-mod i (cycle-count xs))))
-    (struct-set! cycle previous-index current-index xs)
-    (struct-set! cycle current-index next-index xs))
-  xs)
-
-(defun cycle-focus (p cycle)
-  "Focus the element in CYCLE for which predicate, P, is t."
-  (let ((i (->> cycle
-                cycle-xs
-                (-find-index p))))
-    (if i
-        (cycle-jump i cycle)
-      (error "No element in cycle matches predicate"))))
-
-(defun cycle-focus-item (x xs)
-  "Focus item, X, in cycle XS.
-ITEM is the first item in XS that t for `equal'."
-  (cycle-focus (lambda (y) (equal x y)) xs))
-
-(defun cycle-contains? (x xs)
-  "Return t if cycle, XS, has member X."
-  (->> xs
-       cycle-xs
-       (list-contains? x)))
-
-(defun cycle-empty? (xs)
-  "Return t if cycle XS has no elements."
-  (= 0 (length (cycle-xs xs))))
-
-(defun cycle-focused? (xs)
-  "Return t if cycle XS has a non-nil value for current-index."
-  (maybe-some? (cycle-current-index xs)))
-
-(defun cycle-append (x xs)
-  "Add X to the left of the focused element in XS.
-If there is no currently focused item, add X to the beginning of XS."
-  (if (cycle-empty? xs)
-      (progn
-        (struct-set! cycle xs (list x) xs)
-        (struct-set! cycle current-index 0 xs)
-        (struct-set! cycle previous-index nil xs))
-    (let ((curr-i (cycle-current-index xs))
-          (prev-i (cycle-previous-index xs)))
-      (if curr-i
-          (progn
-            (struct-set! cycle xs (-insert-at curr-i x (cycle-xs xs)) xs)
-            (when (and prev-i (>= prev-i curr-i))
-              (struct-set! cycle previous-index (1+ prev-i) xs))
-            (when curr-i (struct-set! cycle current-index (1+ curr-i) xs)))
-        (progn
-          (struct-set! cycle xs (cons x (cycle-xs xs)) xs)
-          (when prev-i (struct-set! cycle previous-index (1+ prev-i) xs))))
-      xs)))
-
-(defun cycle-remove (x xs)
-  "Attempt to remove X from XS.
-
-X is found using `equal'.
-
-If X is the currently focused value, after it's deleted, current-index will be
-  nil.  If X is the previously value, after it's deleted, previous-index will be
-  nil."
-  (let ((curr-i (cycle-current-index xs))
-        (prev-i (cycle-previous-index xs))
-        (rm-i (-elem-index x (cycle-xs xs))))
-    (struct-set! cycle xs (-remove-at rm-i (cycle-xs xs)) xs)
-    (when prev-i
-      (when (> prev-i rm-i) (struct-set! cycle previous-index (1- prev-i) xs))
-      (when (= prev-i rm-i) (struct-set! cycle previous-index nil xs)))
-    (when curr-i
-      (when (> curr-i rm-i) (struct-set! cycle current-index (1- curr-i) xs))
-      (when (= curr-i rm-i) (struct-set! cycle current-index nil xs)))
-    xs))
-
-;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
-;; Tests
-;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
-
-(when cycle-enable-tests?
-  (let ((xs (cycle-new 1 2 3)))
-    (prelude-assert (maybe-nil? (cycle-previous-focus xs)))
-    (prelude-assert (= 1 (cycle-current xs)))
-    (prelude-assert (= 2 (cycle-next xs)))
-    (prelude-assert (= 1 (cycle-previous-focus xs)))
-    (prelude-assert (= 1 (->> xs (cycle-jump 0) cycle-current)))
-    (prelude-assert (= 2 (->> xs (cycle-jump 1) cycle-current)))
-    (prelude-assert (= 3 (->> xs (cycle-jump 2) cycle-current)))
-    (prelude-assert (= 2 (cycle-previous-focus xs)))
-    (prelude-assert (= 2 (cycle-focus-previous! xs)))
-    (prelude-assert (equal '(1 4 2 3) (cycle-xs (cycle-append 4 xs))))
-    (prelude-assert (equal '(1 2 3) (cycle-xs (cycle-remove 4 xs))))
-    (progn
-      (cycle-focus-item 3 xs)
-      (cycle-focus-item 2 xs)
-      (cycle-remove 1 xs)
-      (prelude-assert (= 2 (cycle-current xs)))
-      (prelude-assert (= 3 (cycle-previous-focus xs))))))
-
-(provide 'cycle)
-;;; cycle.el ends here
diff --git a/users/wpcarro/emacs/.emacs.d/wpc/fonts.el b/users/wpcarro/emacs/.emacs.d/wpc/fonts.el
index 196b8828626f..9490896ae7cc 100644
--- a/users/wpcarro/emacs/.emacs.d/wpc/fonts.el
+++ b/users/wpcarro/emacs/.emacs.d/wpc/fonts.el
@@ -68,8 +68,8 @@
 (cl-defun fonts-cycle (&key forward?)
   "Cycle forwards when `FORWARD?' non-nil."
   (let ((font (if forward?
-                  (cycle-next fonts-whitelist)
-                (cycle-prev fonts-whitelist))))
+                  (cycle-next! fonts-whitelist)
+                (cycle-prev! fonts-whitelist))))
     (message (s-concat "Active font: " font))
     (fonts-set font)))
 
@@ -93,7 +93,7 @@
   "Focuses the FONT in the `fonts-whitelist' cycle.
 The size of the font is determined by `fonts-size'."
   (prelude-assert (cycle-contains? font fonts-whitelist))
-  (cycle-focus (lambda (x) (equal x font)) fonts-whitelist)
+  (cycle-focus! (lambda (x) (equal x font)) fonts-whitelist)
   (fonts-set (fonts-current) fonts-size))
 
 (defun fonts-ivy-select ()
diff --git a/users/wpcarro/emacs/.emacs.d/wpc/irc.el b/users/wpcarro/emacs/.emacs.d/wpc/irc.el
index 9103bd38fe1a..70d26f7f08c2 100644
--- a/users/wpcarro/emacs/.emacs.d/wpc/irc.el
+++ b/users/wpcarro/emacs/.emacs.d/wpc/irc.el
@@ -135,7 +135,7 @@
   (with-current-buffer (current-buffer)
     (let ((cycle (irc-channel->cycle irc-server->channels (buffer-name))))
       (erc-join-channel
-       (cycle-next cycle))
+       (cycle-next! cycle))
       (irc-message
        (string-format "Current IRC channel: %s" (cycle-current cycle))))))
 
@@ -145,7 +145,7 @@
   (with-current-buffer (current-buffer)
     (let ((cycle (irc-channel->cycle irc-server->channels (buffer-name))))
       (erc-join-channel
-       (cycle-prev cycle))
+       (cycle-prev! cycle))
       (irc-message
        (string-format "Current IRC channel: %s" (cycle-current cycle))))))
 
diff --git a/users/wpcarro/emacs/.emacs.d/wpc/vterm-mgt.el b/users/wpcarro/emacs/.emacs.d/wpc/vterm-mgt.el
index ec9a04d1c846..29c24d89ec9c 100644
--- a/users/wpcarro/emacs/.emacs.d/wpc/vterm-mgt.el
+++ b/users/wpcarro/emacs/.emacs.d/wpc/vterm-mgt.el
@@ -55,8 +55,8 @@ This function should be called from a buffer running vterm."
   (interactive)
   (vterm-mgt--assert-vterm-buffer)
   (vterm-mgt-reconcile-state)
-  (cycle-focus-item (current-buffer) vterm-mgt--instances)
-  (switch-to-buffer (cycle-next vterm-mgt--instances))
+  (cycle-focus-item! (current-buffer) vterm-mgt--instances)
+  (switch-to-buffer (cycle-next! vterm-mgt--instances))
   (when vterm-mgt-scroll-on-focus (end-of-buffer)))
 
 (defun vterm-mgt-prev ()
@@ -65,8 +65,8 @@ This function should be called from a buffer running vterm."
   (interactive)
   (vterm-mgt--assert-vterm-buffer)
   (vterm-mgt-reconcile-state)
-  (cycle-focus-item (current-buffer) vterm-mgt--instances)
-  (switch-to-buffer (cycle-prev vterm-mgt--instances))
+  (cycle-focus-item! (current-buffer) vterm-mgt--instances)
+  (switch-to-buffer (cycle-prev! vterm-mgt--instances))
   (when vterm-mgt-scroll-on-focus (end-of-buffer)))
 
 (defun vterm-mgt-instantiate ()
@@ -81,8 +81,8 @@ If however you must call `vterm', if you'd like to cycle through vterm
   (interactive)
   (vterm-mgt-reconcile-state)
   (let ((buffer (vterm t)))
-    (cycle-append buffer vterm-mgt--instances)
-    (cycle-focus-item buffer vterm-mgt--instances)))
+    (cycle-append! buffer vterm-mgt--instances)
+    (cycle-focus-item! buffer vterm-mgt--instances)))
 
 (defun vterm-mgt-kill ()
   "Kill the current buffer and remove it from `vterm-mgt--instances'.
@@ -106,7 +106,7 @@ instance."
     (if (cycle-focused? vterm-mgt--instances)
         (switch-to-buffer (cycle-current vterm-mgt--instances))
       (progn
-        (cycle-jump 0 vterm-mgt--instances)
+        (cycle-jump! 0 vterm-mgt--instances)
         (switch-to-buffer (cycle-current vterm-mgt--instances))))))
 
 (defun vterm-mgt-rename-buffer (name)
diff --git a/users/wpcarro/emacs/.emacs.d/wpc/window-manager.el b/users/wpcarro/emacs/.emacs.d/wpc/window-manager.el
index 4c61138f948a..94fb99d4271b 100644
--- a/users/wpcarro/emacs/.emacs.d/wpc/window-manager.el
+++ b/users/wpcarro/emacs/.emacs.d/wpc/window-manager.el
@@ -97,12 +97,12 @@
 (defun window-manager-next-workspace ()
   "Cycle forwards to the next workspace."
   (interactive)
-  (window-manager--change-workspace (cycle-next window-manager--workspaces)))
+  (window-manager--change-workspace (cycle-next! window-manager--workspaces)))
 
 (defun window-manager-prev-workspace ()
   "Cycle backwards to the previous workspace."
   (interactive)
-  (window-manager--change-workspace (cycle-prev window-manager--workspaces)))
+  (window-manager--change-workspace (cycle-prev! window-manager--workspaces)))
 
 ;; Here is the code required to toggle EXWM's modes.
 (defun window-manager--line-mode ()
@@ -120,7 +120,7 @@
   (interactive)
   (with-current-buffer (window-buffer)
     (when (eq major-mode 'exwm-mode)
-      (funcall (cycle-next window-manager--modes)))))
+      (funcall (cycle-next! window-manager--modes)))))
 
 (defun window-manager--label->index (label workspaces)
   "Return the index of the workspace in WORKSPACES named LABEL."
@@ -152,10 +152,10 @@ Currently using super- as the prefix for switching workspaces."
 
 (defun window-manager--switch (label)
   "Switch to a named workspaces using LABEL."
-  (cycle-focus (lambda (x)
-                 (equal label
-                        (window-manager-named-workspace-label x)))
-               window-manager--workspaces)
+  (cycle-focus! (lambda (x)
+                  (equal label
+                         (window-manager-named-workspace-label x)))
+                window-manager--workspaces)
   (window-manager--change-workspace (cycle-current window-manager--workspaces)))
 
 (defun window-manager-toggle-previous ()
diff --git a/users/wpcarro/emacs/default.nix b/users/wpcarro/emacs/default.nix
index 78d3b1b371bb..56779f5ac8c0 100644
--- a/users/wpcarro/emacs/default.nix
+++ b/users/wpcarro/emacs/default.nix
@@ -26,6 +26,7 @@ let
   wpcarrosEmacs = emacsWithPackages (epkgs:
     (with wpcarro.emacs.pkgs; [
       al
+      cycle
       list
       maybe
       set
diff --git a/users/wpcarro/emacs/pkgs/cycle/cycle.el b/users/wpcarro/emacs/pkgs/cycle/cycle.el
new file mode 100644
index 000000000000..0d9834f6bf29
--- /dev/null
+++ b/users/wpcarro/emacs/pkgs/cycle/cycle.el
@@ -0,0 +1,202 @@
+;;; cycle.el --- Simple module for working with cycles -*- lexical-binding: t -*-
+
+;; Author: William Carroll <wpcarro@gmail.com>
+;; Version: 0.0.1
+;; Package-Requires: ((emacs "24.3"))
+
+;;; Commentary:
+;; Something like this may already exist, but I'm having trouble finding it, and
+;; I think writing my own is a nice exercise for learning more Elisp.
+
+;;; Code:
+
+;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
+;; Dependencies
+;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
+
+(require 'dash)
+(require 'maybe)
+(require 'list)
+(require 'struct)
+(require 'cl-lib)
+
+;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
+;; Wish list
+;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
+
+;; - TODO: Provide immutable variant.
+;; - TODO: Replace mutable consumption with immutable variant.
+
+;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
+;; Library
+;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
+
+;; `current-index' tracks the current index
+;; `xs' is the original list
+(cl-defstruct cycle current-index previous-index xs)
+
+(defun cycle-from-list (xs)
+  "Create a cycle from a list of `XS'."
+  (if (= 0 (length xs))
+      (make-cycle :current-index nil
+                  :previous-index nil
+                  :xs xs)
+    (make-cycle :current-index 0
+                :previous-index nil
+                :xs xs)))
+
+(defun cycle-new (&rest xs)
+  "Create a cycle with XS as the values."
+  (cycle-from-list xs))
+
+(defun cycle-to-list (xs)
+  "Return the list representation of a cycle, XS."
+  (cycle-xs xs))
+
+(defun cycle-previous-focus (cycle)
+  "Return the previously focused entry in CYCLE."
+  (let ((i (cycle-previous-index cycle)))
+    (if (maybe-some? i)
+        (nth i (cycle-xs cycle))
+      nil)))
+
+(defun cycle-focus-previous! (xs)
+  "Jump to the item in XS that was most recently focused; return the cycle.
+This will error when previous-index is nil.  This function mutates the
+underlying struct."
+  (let ((i (cycle-previous-index xs)))
+    (if (maybe-some? i)
+        (progn
+          (cycle-jump! i xs)
+          (cycle-current xs))
+      (error "Cannot focus the previous element since cycle-previous-index is nil"))))
+
+(defun cycle-next! (xs)
+  "Return the next value in `XS' and update `current-index'."
+  (let* ((current-index (cycle-current-index xs))
+         (next-index (cycle--next-index-> 0 (cycle-count xs) current-index)))
+    (struct-set! cycle previous-index current-index xs)
+    (struct-set! cycle current-index next-index xs)
+    (nth next-index (cycle-xs xs))))
+
+(defun cycle-prev! (xs)
+  "Return the previous value in `XS' and update `current-index'."
+  (let* ((current-index (cycle-current-index xs))
+         (next-index (cycle--next-index<- 0 (cycle-count xs) current-index)))
+    (struct-set! cycle previous-index current-index xs)
+    (struct-set! cycle current-index next-index xs)
+    (nth next-index (cycle-xs xs))))
+
+(defun cycle-current (cycle)
+  "Return the current value in `CYCLE'."
+  (nth (cycle-current-index cycle) (cycle-xs cycle)))
+
+(defun cycle-count (cycle)
+  "Return the length of `xs' in `CYCLE'."
+  (length (cycle-xs cycle)))
+
+(defun cycle-jump! (i xs)
+  "Jump to the I index of XS."
+  (let ((current-index (cycle-current-index xs))
+        (next-index (mod i (cycle-count xs))))
+    (struct-set! cycle previous-index current-index xs)
+    (struct-set! cycle current-index next-index xs))
+  xs)
+
+(defun cycle-focus! (p cycle)
+  "Focus the element in CYCLE for which predicate, P, is t."
+  (let ((i (->> cycle
+                cycle-xs
+                (-find-index p))))
+    (if i
+        (cycle-jump! i cycle)
+      (error "No element in cycle matches predicate"))))
+
+(defun cycle-focus-item! (x xs)
+  "Focus item, X, in cycle XS.
+ITEM is the first item in XS that t for `equal'."
+  (cycle-focus! (lambda (y) (equal x y)) xs))
+
+(defun cycle-append! (x xs)
+  "Add X to the left of the focused element in XS.
+If there is no currently focused item, add X to the beginning of XS."
+  (if (cycle-empty? xs)
+      (progn
+        (struct-set! cycle xs (list x) xs)
+        (struct-set! cycle current-index 0 xs)
+        (struct-set! cycle previous-index nil xs))
+    (let ((curr-i (cycle-current-index xs))
+          (prev-i (cycle-previous-index xs)))
+      (if curr-i
+          (progn
+            (struct-set! cycle xs (-insert-at curr-i x (cycle-xs xs)) xs)
+            (when (and prev-i (>= prev-i curr-i))
+              (struct-set! cycle previous-index (1+ prev-i) xs))
+            (when curr-i (struct-set! cycle current-index (1+ curr-i) xs)))
+        (progn
+          (struct-set! cycle xs (cons x (cycle-xs xs)) xs)
+          (when prev-i (struct-set! cycle previous-index (1+ prev-i) xs))))
+      xs)))
+
+(defun cycle-remove! (x xs)
+  "Attempt to remove X from XS.
+
+X is found using `equal'.
+
+If X is the currently focused value, after it's deleted, current-index will be
+  nil.  If X is the previously value, after it's deleted, previous-index will be
+  nil."
+  (let ((curr-i (cycle-current-index xs))
+        (prev-i (cycle-previous-index xs))
+        (rm-i (-elem-index x (cycle-xs xs))))
+    (struct-set! cycle xs (-remove-at rm-i (cycle-xs xs)) xs)
+    (when prev-i
+      (when (> prev-i rm-i) (struct-set! cycle previous-index (1- prev-i) xs))
+      (when (= prev-i rm-i) (struct-set! cycle previous-index nil xs)))
+    (when curr-i
+      (when (> curr-i rm-i) (struct-set! cycle current-index (1- curr-i) xs))
+      (when (= curr-i rm-i) (struct-set! cycle current-index nil xs)))
+    xs))
+
+;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
+;; Predicates
+;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
+
+(defun cycle-contains? (x xs)
+  "Return t if cycle, XS, has member X."
+  (->> xs
+       cycle-xs
+       (list-contains? x)))
+
+(defun cycle-empty? (xs)
+  "Return t if cycle XS has no elements."
+  (= 0 (length (cycle-xs xs))))
+
+(defun cycle-focused? (xs)
+  "Return t if cycle XS has a non-nil value for current-index."
+  (maybe-some? (cycle-current-index xs)))
+
+;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
+;; Helper Functions
+;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
+
+(defun cycle--next-index<- (lo hi x)
+  "Return the next index in a cycle when moving downwards.
+- `LO' is the lower bound.
+- `HI' is the upper bound.
+- `X' is the current index."
+  (if (< (- x 1) lo)
+      (- hi 1)
+    (- x 1)))
+
+(defun cycle--next-index-> (lo hi x)
+  "Return the next index in a cycle when moving upwards.
+- `LO' is the lower bound.
+- `HI' is the upper bound.
+- `X' is the current index."
+  (if (>= (+ 1 x) hi)
+      lo
+    (+ 1 x)))
+
+(provide 'cycle)
+;;; cycle.el ends here
diff --git a/users/wpcarro/emacs/pkgs/cycle/default.nix b/users/wpcarro/emacs/pkgs/cycle/default.nix
new file mode 100644
index 000000000000..00c4a87dc9d7
--- /dev/null
+++ b/users/wpcarro/emacs/pkgs/cycle/default.nix
@@ -0,0 +1,34 @@
+{ pkgs, depot, ... }:
+
+let
+  cycle = pkgs.callPackage
+    ({ emacsPackages }:
+      emacsPackages.trivialBuild {
+        pname = "cycle";
+        version = "1.0.0";
+        src = ./cycle.el;
+        packageRequires =
+          (with emacsPackages; [
+            dash
+          ]) ++
+          (with depot.users.wpcarro.emacs.pkgs; [
+            list
+            maybe
+            struct
+          ]);
+      })
+    { };
+
+  emacs = (pkgs.emacsPackagesFor pkgs.emacs28).emacsWithPackages (epkgs: [
+    epkgs.dash
+    depot.users.wpcarro.emacs.pkgs.maybe
+    cycle
+  ]);
+in
+cycle.overrideAttrs (_old: {
+  doCheck = true;
+  checkPhase = ''
+    ${emacs}/bin/emacs -batch \
+      -l ert -l ${./tests.el} -f ert-run-tests-batch-and-exit
+  '';
+})
diff --git a/users/wpcarro/emacs/pkgs/cycle/tests.el b/users/wpcarro/emacs/pkgs/cycle/tests.el
new file mode 100644
index 000000000000..e58c97bedbe2
--- /dev/null
+++ b/users/wpcarro/emacs/pkgs/cycle/tests.el
@@ -0,0 +1,80 @@
+;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
+;; Dependencies
+;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
+
+(require 'ert)
+(require 'cycle)
+(require 'dash)
+(require 'maybe)
+
+;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
+;; Tests
+;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
+
+(setq xs (cycle-new 1 2 3))
+
+(ert-deftest cycle-initializes-properly ()
+  (should (= 3 (cycle-count xs)))
+  (should (maybe-nil? (cycle-previous-focus xs)))
+  (should (cycle-contains? 1 xs))
+  (should (cycle-contains? 2 xs))
+  (should (cycle-contains? 3 xs)))
+
+(ert-deftest cycle-contains? ()
+  ;; Returns t or nil
+  (should (eq t (cycle-contains? 1 xs)))
+  (should (eq t (cycle-contains? 2 xs)))
+  (should (eq t (cycle-contains? 3 xs)))
+  (should (eq nil (cycle-contains? 4 xs))))
+
+(ert-deftest cycle-empty? ()
+  (should (eq t (cycle-empty? (cycle-new))))
+  (should (eq nil (cycle-empty? xs))))
+
+(ert-deftest cycle-current ()
+  (should (= 1 (cycle-current xs))))
+
+(ert-deftest cycle-next! ()
+  (let ((xs (cycle-from-list '(1 2 3))))
+    (should (= 2 (cycle-next! xs)))))
+
+(ert-deftest cycle-prev! ()
+  (let ((xs (cycle-from-list '(1 2 3))))
+    (cycle-next! xs)
+    (should (= 1 (cycle-prev! xs)))))
+
+(ert-deftest cycle-previous-focus ()
+  (let ((xs (cycle-from-list '(1 2 3))))
+    (cycle-focus-item! 2 xs)
+    (cycle-next! xs)
+    (should (= 2 (cycle-previous-focus xs)))))
+
+(ert-deftest cycle-jump! ()
+  (let ((xs (cycle-from-list '(1 2 3))))
+    (should (= 1 (->> xs (cycle-jump! 0) cycle-current)))
+    (should (= 2 (->> xs (cycle-jump! 1) cycle-current)))
+    (should (= 3 (->> xs (cycle-jump! 2) cycle-current)))))
+
+(ert-deftest cycle-focus-previous! ()
+  (let ((xs (cycle-from-list '(1 2 3))))
+    (cycle-focus-item! 2 xs)
+    (cycle-next! xs)
+    (should (= 2 (cycle-previous-focus xs)))
+    (should (= 2 (cycle-focus-previous! xs)))))
+
+(ert-deftest cycle-append! ()
+  (let ((xs (cycle-from-list '(1 2 3))))
+    (cycle-focus-item! 2 xs)
+    (cycle-append! 4 xs)
+    (should (equal '(1 4 2 3) (cycle-xs xs)))))
+
+(ert-deftest cycle-remove! ()
+  (let ((xs (cycle-from-list '(1 2 3))))
+    (should (equal '(1 2) (cycle-xs (cycle-remove! 3 xs))))))
+
+(ert-deftest cycle-misc ()
+  (cycle-focus-item! 3 xs)
+  (cycle-focus-item! 2 xs)
+  (cycle-remove! 1 xs)
+  (should (= 2 (cycle-current xs)))
+  (should (= 3 (cycle-previous-focus xs))))
-- 
cgit 1.4.1