From bce5ed6fee217bd4cdfaa432283126446f08b66c Mon Sep 17 00:00:00 2001
From: Rick Lupton <mail@ricklupton.name>
Date: Tue, 12 Mar 2024 22:56:28 +0000
Subject: [PATCH] lisp/org-id.el: add hook `org-id-find-functions'

* lisp/org-id.el (org-id-find-functions): New hook for functions to find
location of org-ids.
(org-id-find): Try to use `org-id-find-functions' first when looking for
an org-id.
* testing/lisp/test-ol.el: Add test for `org-id-find-functions`.

This accommodates tools such as org-roam which otherwise overwrite the
org-id link opening function in order to use their own cached database
of org id locations.
---
 etc/ORG-NEWS            |  6 ++++++
 lisp/org-id.el          | 34 ++++++++++++++++++++++++----------
 testing/lisp/test-ol.el |  8 ++++++++
 3 files changed, 38 insertions(+), 10 deletions(-)

diff --git a/etc/ORG-NEWS b/etc/ORG-NEWS
index abe62daaf..2223fb332 100644
--- a/etc/ORG-NEWS
+++ b/etc/ORG-NEWS
@@ -1308,6 +1308,12 @@ It does no longer use regexps.
 
 It is also faster. Large tables can be read quickly.
 
+*** New hook ~org-id-find-functions~
+
+Functions added to this hook are tried first when locating an org-id.
+Libraries can use this to provide additional methods to efficiently
+locate ids beyond the built-in caching.
+
 * Version 9.6
 
 ** Important announcements and breaking changes
diff --git a/lisp/org-id.el b/lisp/org-id.el
index 58d51deca..a7db53a59 100644
--- a/lisp/org-id.el
+++ b/lisp/org-id.el
@@ -295,6 +295,18 @@ This variable is only relevant when `org-id-track-globally' is set."
   :group 'org-id
   :type 'boolean)
 
+(defvar org-id-find-functions nil
+  "Hook for functions finding an ID location.
+These functions must take two arguments, ID and MARKERP.
+
+`org-id-find' will first try to call these functions, and the
+first non-nil return value will be returned from `org-id-find'.
+See `org-id-find' for the expected return type and meaning of ID
+and MARKERP.  ID will be passed as a string.
+
+If all functions return nil, `org-id-find' will proceed to look
+for the ID using the built-in id location cache.")
+
 ;;; The API functions
 
 ;;;###autoload
@@ -396,16 +408,18 @@ With optional argument MARKERP, return the position as a new marker."
   (cond
    ((symbolp id) (setq id (symbol-name id)))
    ((numberp id) (setq id (number-to-string id))))
-  (let ((file (org-id-find-id-file id))
-	org-agenda-new-buffers where)
-    (when file
-      (setq where (org-id-find-id-in-file id file markerp)))
-    (unless where
-      (org-id-update-id-locations nil t)
-      (setq file (org-id-find-id-file id))
-      (when file
-	(setq where (org-id-find-id-in-file id file markerp))))
-    where))
+  (or
+   (run-hook-with-args-until-success 'org-id-find-functions id markerp)
+   (let ((file (org-id-find-id-file id))
+         org-agenda-new-buffers where)
+     (when file
+       (setq where (org-id-find-id-in-file id file markerp)))
+     (unless where
+       (org-id-update-id-locations nil t)
+       (setq file (org-id-find-id-file id))
+       (when file
+         (setq where (org-id-find-id-in-file id file markerp))))
+     where)))
 
 ;;; Internal functions
 
diff --git a/testing/lisp/test-ol.el b/testing/lisp/test-ol.el
index 3150b4e2f..04ac3395d 100644
--- a/testing/lisp/test-ol.el
+++ b/testing/lisp/test-ol.el
@@ -503,6 +503,14 @@ See https://github.com/yantar92/org/issues/4."
             (test-ol-stored-link-with-text "* H1\n:PROPERTIES:\n:ID: abc\n:END:\n* H2\n** <point>Target\n"
               (org-id-store-link-maybe t))))))
 
+(ert-deftest test-org-link/org-id-find ()
+  "Test `org-id-find' specifications."
+  (should
+   (equal '("id.org" . 12)
+          (org-test-with-temp-text ""
+            (add-hook 'org-id-find-functions (lambda (id _markerp) (cons (concat id ".org") 12)) nil t)
+            (org-id-find "id")))))
+
 
 ;;; Radio Targets
 
-- 
2.37.1 (Apple Git-137.1)