Generalize notes

Refactor the notes API to enable more general functionality (see #518),
and tighter integration with note-taking packages like org-roam (see #602).

- Add citar-keys-with-notes-functions defcustom.
- Rename citar-open-notes-function to citar-open-notes-functions; make a list.
- Refactor citar-open-notes to make use of the above
- Add some convenience functions for working with these data.

Close #601

Author: bdarcus

README.org

@@ -267,15 +267,21 @@ For additional configuration options on this, see [[https://github.com/bdarcus/c
 
 ** Notes
 
-Citar provides a ~citar-format-note-function~ variable, and a default function for org, which also works well with org-roam (v2 now supports org-cite).
+Citar provides a ~citar-create-note-function~ variable, and a default function for org, which also works well with org-roam (v2 now supports org-cite).
 You can configure the title display using the "note" template.
 
-You can also use the ~citar-open-note-function~ variable to replace the default with another; for example from org-roam-bibtex:
+You can also use the ~citar-open-note-functions~ variable to replace or augment the default with another; for example from org-roam-bibtex:
 
 #+BEGIN_SRC emacs-lisp
-(setq citar-open-note-function 'orb-citar-edit-note)
+(setq citar-open-note-functions '(orb-citar-edit-note))
 #+END_SRC
 
+Since ~citar-open-note-functions~ is a list, you can also include multiple functions, to handle different note scenarios.
+
+Citar also includes a ~citar-keys-with-notes-functions~ variable, which specifies a list of functions, each of which returns a list of keys that have associated notes.
+This function allows Citar to correctly format the completion UI candidates.
+The default function only supports one-file-per-key notes.
+
 ** Files, file association and file-field parsing
 
 If you have ~citar-library-paths~ set, the relevant open commands will look in those directories for file names of =CITEKEY.EXTENSION=.

citar-file.el

@@ -27,6 +27,7 @@
   (require 'cl-lib)
   (require 'subr-x))
 (require 'seq)
+(make-obsolete 'citar-format-note-function 'citar-create-note-function "1.0")
 
 ;;; pre-1.0 API cleanup
 
@@ -93,6 +94,9 @@ separator that does not otherwise occur in citation keys."
                  (regexp :tag "Filename separator")))
 
 (defvar citar-notes-paths)
+(defvar citar-create-note-function)
+(defvar citar-library-paths)
+(defvar citar-library-file-extensions)
 
 ;;;; Convenience functions for files and paths
 
@@ -229,6 +233,26 @@ need to scan the contents of DIRS in this case."
                  (puthash key (nreverse filelist) files))
                files))))
 
+(defun citar-file--has-file-notes-hash ()
+  "Return a hash of keys and file paths for notes."
+  (citar-file--directory-files
+   citar-notes-paths nil citar-file-note-extensions
+   citar-file-additional-files-separator))
+
+(defun citar-file--has-library-files-hash ()
+  "Return a hash of keys and file paths for library files."
+  (citar-file--directory-files
+   citar-library-paths nil citar-library-file-extensions
+   citar-file-additional-files-separator))
+
+(defun citar-file--keys-with-file-notes ()
+  "Return a list of keys with file notes."
+  (hash-table-keys (citar-file--has-file-notes-hash)))
+
+(defun citar-file--keys-with-library-files ()
+  "Return a list of keys with file notes."
+  (hash-table-keys (citar-file--has-library-files-hash)))
+
 (defun citar-file--has-file (dirs extensions &optional entry-field)
   "Return predicate testing whether a key and entry have associated files.
 
@@ -322,6 +346,19 @@ of files found in two ways:
                   nil 0 nil
                   file)))
 
+(defun citar-file--open-note (key entry)
+  "Open a note file from KEY and ENTRY."
+  (if-let* ((file (citar-file--get-note-filename key
+                                                 citar-notes-paths
+                                                 citar-file-note-extensions))
+            (file-exists (file-exists-p file)))
+      (find-file file)
+    (if (and (null citar-notes-paths)
+             (equal citar-create-note-function
+                    'citar-org-format-note-default))
+      (error "You must set 'citar-notes-paths'")
+      (funcall citar-create-note-function key entry file))))
+
 (defun citar-file--get-note-filename (key dirs extensions)
   "Return existing or new filename for KEY in DIRS with extension in EXTENSIONS.
 

citar.el

@@ -62,8 +62,10 @@
 
 ;; also rename
 (make-obsolete 'citar-has-a-value 'citar--field-with-value "1.0")
+(make-obsolete 'citar--open-note 'citar-file--open-note "1.0")
 
-
+(make-obsolete-variable
+ 'citar-format-note-function 'citar-create-note-function "1.0")
 
 ;;; Declare variables and functions for byte compiler
 
@@ -222,6 +224,20 @@ If nil, single resources will open without prompting."
   :group 'citar
   :type '(boolean))
 
+;;; Note-handling setup
+
+(defcustom citar-open-note-functions
+  '(citar-file--open-note)
+  "List of functions to open a note."
+  :group 'citar
+  :type '(function))
+
+(defcustom citar-keys-with-notes-functions
+  '(citar-file--keys-with-file-notes)
+  "Functions, without argument, to return a list of keys with notes."
+  :group 'citar
+  :type '(function))
+
 (defcustom citar-open-note-function
   'citar--open-note
   "Function to open a new or existing note.
@@ -233,9 +249,9 @@ ENTRY: an alist with the structured data (title, author, etc.)"
   :group 'citar
   :type 'function)
 
-(defcustom citar-format-note-function
+(defcustom citar-create-note-function
   'citar-org-format-note-default
-  "Function to format a new note.
+  "Function to create a new note.
 
 A note function must take three arguments:
 
@@ -475,6 +491,14 @@ REBUILD-CACHE and FILTER."
              (category . multi-category))
          (complete-with-action action (delete-dups resources) string predicate))))))
 
+(defun citar--keys-with-notes ()
+  "Return a list of keys with associated notes."
+  (seq-uniq
+   (seq-mapcat
+    (lambda (fn)
+      (funcall fn))
+    citar-keys-with-notes-functions)))
+
 (defun citar--select-group-related-resources (resource transform)
   "Group RESOURCE by type or TRANSFORM."
     (let ((extension (file-name-extension resource)))
@@ -605,6 +629,7 @@ repeatedly."
   (citar-file--has-file citar-notes-paths
                         citar-file-note-extensions))
 
+
 (defun citar--format-candidates (bib-files &optional context)
   "Format candidates from BIB-FILES, with optional hidden CONTEXT metadata.
 This both propertizes the candidates for display, and grabs the
@@ -613,15 +638,15 @@ key associated with each one."
          (raw-candidates
           (parsebib-parse bib-files :fields (citar--fields-to-parse)))
          (hasfilep (citar-has-file))
-         (hasnotep (citar-has-note))
+         (hasnote (citar--keys-with-notes))
          (main-width (citar--format-width (citar--get-template 'main)))
          (suffix-width (citar--format-width (citar--get-template 'suffix)))
          (symbols-width (string-width (citar--symbols-string t t t)))
          (star-width (- (frame-width) (+ 2 symbols-width main-width suffix-width))))
     (maphash
      (lambda (citekey entry)
        (let* ((files (when (funcall hasfilep citekey entry) " has:files"))
-              (notes (when (funcall hasnotep citekey entry) " has:notes"))
+              (notes (when (member citekey hasnote) " has:notes"))
               (link (when (citar--field-with-value '("doi" "url") entry) "has:link"))
               (candidate-main
                (citar--format-entry
@@ -1041,21 +1066,19 @@ With prefix, rebuild the cache before offering candidates."
 With prefix, rebuild the cache before offering candidates."
   (interactive (list (citar-select-ref
                       :rebuild-cache current-prefix-arg)))
-  (let ((embark-default-action-overrides '((file . find-file))))
-    (when (and (null citar-notes-paths)
-               (equal citar-format-note-function
-                      'citar-org-format-note-default))
-      (error "You must set 'citar-notes-paths' to open notes with default notes function"))
-    (funcall citar-open-note-function (car key-entry) (cdr key-entry))))
-
-(defun citar--open-note (key entry)
-  "Open a note file from KEY and ENTRY."
-  (if-let* ((file (citar-file--get-note-filename key
-                                                 citar-notes-paths
-                                                 citar-file-note-extensions))
-            (file-exists (file-exists-p file)))
-      (find-file file)
-    (funcall citar-format-note-function key entry file)))
+  (let* ((embark-default-action-overrides '((file . find-file)))
+         (key (car key-entry))
+         (entry (cdr key-entry)))
+    (if (listp citar-open-note-functions)
+        (citar--open-notes key entry)
+      (error "Please change the value of 'citar-open-note-functions' to a list"))))
+
+(defun citar--open-notes (key entry)
+  "Open note(s) associated with KEY and ENTRY."
+  (or (seq-some
+       (lambda (opener)
+         (funcall opener key entry)) citar-open-note-functions)
+      (funcall citar-create-note-function key entry)))
 
 ;;;###autoload
 (defun citar-open-entry (key-entry)