core: add reference handler as per jump handler

CHANGELOG.develop

@@ -589,6 +589,7 @@ Other:
   - New emacs banner: "100-banner.txt" (thanks to Robert Zaremba)
   - Add Dogemacs inverted banner for dark themes: "997-banner.txt"
     (thanks to Vitor Finotti and Robby O'Connor)
+  - Added reference handler as per jump handler (thanks to Fangrui Song)
 *** Distribution changes
 - Refactored =spacemacs-bootstrap=, =spacemacs-ui=, and =spacemacs-ui-visual=
   layers:

core/core-jump.el

@@ -39,6 +39,29 @@ sets `spacemacs-jump-handlers' in buffers of that mode."
            "gg" 'spacemacs/jump-to-definition
            "gG" 'spacemacs/jump-to-definition-other-window)))))
 
+(defmacro spacemacs|define-reference-handlers (mode &rest handlers)
+  "Defines reference handlers for the given MODE.
+This defines a variable `spacemacs-reference-handlers-MODE' to which
+handlers can be added, and a function added to MODE-hook which
+sets `spacemacs-reference-handlers' in buffers of that mode."
+  (let ((mode-hook (intern (format "%S-hook" mode)))
+        (func (intern (format "spacemacs//init-reference-handlers-%S" mode)))
+        (handlers-list (intern (format "spacemacs-reference-handlers-%S" mode))))
+    `(progn
+       (defvar ,handlers-list ',handlers
+         ,(format (concat "List of mode-specific reference handlers for %S. "
+                          "These take priority over those in "
+                          "`spacemacs-default-reference-handlers'.")
+                  mode))
+       (defun ,func ()
+         (setq spacemacs-reference-handlers
+               (append ,handlers-list
+                       spacemacs-default-reference-handlers)))
+       (add-hook ',mode-hook ',func)
+       (with-eval-after-load 'bind-map
+         (spacemacs/set-leader-keys-for-major-mode ',mode
+           "gr" 'spacemacs/jump-to-reference)))))
+
 (defun spacemacs/jump-to-definition ()
   "Jump to definition around point using the best tool for this action."
   (interactive)
@@ -68,12 +91,43 @@ sets `spacemacs-jump-handlers' in buffers of that mode."
     (goto-char pos)
     (spacemacs/jump-to-definition)))
 
+(defun spacemacs/jump-to-reference ()
+  "Jump to reference around point using the best tool for this action."
+  (interactive)
+  (catch 'done
+    (let ((old-window (selected-window))
+          (old-buffer (current-buffer))
+          (old-point (point)))
+      (dolist (-handler spacemacs-reference-handlers)
+        (let ((handler (if (listp -handler) (car -handler) -handler))
+              (async (when (listp -handler)
+                       (plist-get (cdr -handler) :async))))
+          (ignore-errors
+            (call-interactively handler))
+          (when (or (eq async t)
+                    (and (fboundp async) (funcall async))
+                    (not (eq old-point (point)))
+                    (not (equal old-buffer (window-buffer old-window))))
+            (throw 'done t)))))
+    (message "No reference handler was able to find this symbol.")))
+
+(defun spacemacs/jump-to-reference-other-window ()
+  "Jump to reference around point in other window."
+  (interactive)
+  (let ((pos (point)))
+    ;; since `spacemacs/jump-to-reference' can be asynchronous we cannot use
+    ;; `save-excursion' here, so we have to bear with the jumpy behavior.
+    (switch-to-buffer-other-window (current-buffer))
+    (goto-char pos)
+    (spacemacs/jump-to-reference)))
+
 ;; Set the `:jump' property manually instead of just using `evil-define-motion'
 ;; in an `eval-after-load' macro invocation because doing that prevents
 ;; `describe-function' from correctly finding the source.
 ;;
 ;; See discussion on https://github.com/syl20bnr/spacemacs/pull/6771
 (with-eval-after-load 'evil
-  (evil-set-command-property 'spacemacs/jump-to-definition :jump t))
+  (evil-set-command-property 'spacemacs/jump-to-definition :jump t)
+  (evil-set-command-property 'spacemacs/jump-to-reference :jump t))
 
 (provide 'core-jump)