feat!: add custom display function for indices

README.org

@@ -5,6 +5,7 @@
 * Contents :TOC:noexport:
 - [[#introduction][Introduction]]
 - [[#changelog][Changelog]]
+  - [[#jan-26-2026][Jan. 26 2026]]
   - [[#aug-26-2024][Aug. 26 2024]]
   - [[#sep-11-2019][Sep. 11 2019]]
   - [[#nov-15-2018][Nov. 15 2018]]
@@ -29,6 +30,9 @@ as identifiers, as opposed to strictly increasing numbers. The public
 API is largely the same, however, and simple numbers are still the default.
 
 * Changelog
+** Jan. 26 2026
+- Added support for changing how Lisp indices are displayed via =winum-display-function=.
+- Removed =winum-mode-line-p= predicate.
 ** Aug. 26 2024
 - Added support for arbitrary Lisp objects (non-nil, compared with =equal=) as indices.
 - Added customize variable =winum-auto-assign-function= to control auto-assigning behavior.

winum.el

@@ -139,6 +139,15 @@ increasing integers to each window."
   :group 'winum
   :type 'function)
 
+(defcustom winum-display-function #'prin1-to-string
+  "A function that determines how window indices are displayed to the screen."
+  :group 'winum
+  :type 'function)
+
+(defun winum-display-function (index)
+  "Call the variable value of `winum-display-function' on INDEX."
+  (funcall winum-display-function index))
+
 (defcustom winum-auto-setup-mode-line t
   "When nil, `winum-mode' will not display window numbers in the mode-line.
 You might want this to be nil if you use a package that already manages window
@@ -151,18 +160,22 @@ numbers in the mode-line."
   :group 'winum
   :type  'integer)
 
-(defcustom winum-mode-line-p #'integerp
-  "A predicate that determines when to display a window index on the mode-line.
-By default, only integers are displayed."
-  :group 'winum
-  :type 'function)
-
 (defcustom winum-format " %s "
   "Format string defining how the window number looks like in the mode-line.
 This string is passed to the `format' function along with the index."
   :group 'winum
   :type  'string)
 
+(defcustom winum-format-use-display-function nil
+  "Non-nil means `winum-format' takes the output of `winum-display-function'.
+
+If this is non-nil, the window index display on the mode-line runs the index
+through `winum-display-function' and then `winum-format' before being displayed.
+
+Otherwise, the raw object is formatted with `winum-format'."
+  :group 'winum
+  :type 'boolean)
+
 (defcustom winum-ignored-buffers '(" *which-key*")
   "List of buffers to ignore when assigning indices."
   :group 'winum
@@ -234,8 +247,11 @@ Such a structure allows for per-frame bidirectional fast access.")
 
 (defvar winum--mode-line-segment
   '(:eval (let ((index (winum-get-index)))
-            (when (funcall winum-mode-line-p index)
-              (propertize (format winum-format index) 'face 'winum-face))))
+            (propertize (format winum-format
+                                (if winum-format-use-display-function
+                                    (funcall winum-display-function index)
+                                  index))
+                        'face 'winum-face)))
   "What is pushed into `mode-line-format' when setting it up automatically.")
 
 (defvar winum--last-used-scope winum-scope
@@ -374,7 +390,7 @@ There are several ways to provide the value:
          (w (winum-get-window-by-index i)))
     (if w
         (winum--switch-to-window w)
-      (user-error "No window with index %S" i))))
+      (user-error "No window with index %s" (winum-display-function i)))))
 
 ;;;###autoload
 (defun winum-delete-window-by-index (&optional arg)
@@ -395,7 +411,7 @@ There are several ways to provide the value:
          (w (winum-get-window-by-index i)))
     (if w
         (delete-window w)
-      (user-error "No window with index %S" i))))
+      (user-error "No window with index %s" (winum-display-function i)))))
 
 ;; Public API ------------------------------------------------------------------
 
@@ -424,6 +440,15 @@ PREFIX must be a key sequence, like the ones returned by `kbd'."
   (let ((w (or window (selected-window))))
     (gethash w (winum--get-index-table))))
 
+;;;###autoload
+(defun winum-display-index (&optional window)
+  "Get the current or specified window's current number as a displayable string.
+WINDOW: if specified, the window of which we want to know the number.
+        If not specified, the number of the currently selected window is
+        returned."
+  (let* ((i (winum-get-index window)))
+    (winum-display-function i)))
+
 ;; For backwards compatibility
 ;;;###autoload
 (defun winum-get-number-string (&optional window)
@@ -431,11 +456,7 @@ PREFIX must be a key sequence, like the ones returned by `kbd'."
 WINDOW: if specified, the window of which we want to know the number.
         If not specified, the number of the currently selected window is
         returned."
-  (let* ((n (winum-get-index window))
-         (s (if (funcall winum-mode-line-p n)
-                (format "%s" n)
-              "")))
-    (propertize s 'face 'winum-face)))
+  (propertize (winum-display-index window) 'face 'winum-face))
 
 ;; Internal functions ----------------------------------------------------------
 
@@ -558,7 +579,7 @@ first index anyway."
                   (ind (-> inds (cl-first) (cdr))))
         (when (> (length inds) 1)
           (message "Winum conflict - window %s was assigned an index by multiple custom assign functions: '%s'"
-                   window (--map (format "%s -> %S" (car it) (cdr it)) inds)))
+                   window (--map (format "%s -> %s" (car it) (winum-display-function (cdr it))) inds)))
         (winum--assign window ind)
         (push ind winum--assigned-indices)))))
 
@@ -567,8 +588,9 @@ first index anyway."
 Returns the assigned index, or nil on error."
   (if (gethash index (winum--get-window-table))
       (progn
-        (message "Index %S already assigned to %s, can't assign to %s"
-                 index (gethash index (winum--get-window-table)) window)
+        (message "Index %s already assigned to %s, can't assign to %s"
+                 (winum-display-function index)
+                 (gethash index (winum--get-window-table)) window)
         nil)
     (puthash index window (winum--get-window-table))
     (puthash window index (winum--get-index-table))
@@ -592,7 +614,7 @@ Returns the assigned index, or nil on error."
      (frame-local
       (winum--list-windows-in-frame))
      (t
-      (user-error "Invalid `winum-scope': %S" winum-scope)))))
+      (user-error "Invalid `winum-scope': %s" winum-scope)))))
 
 (defun winum--ignore-window-p (window)
   "Non-nil if WINDOW should be ignored for indexing."