[elpa] externals/denote 02647460cd 8/9: Merge branch 'new-denote-directory-files'

[ELPA Syncer]

branch: externals/denote
commit 02647460cdf6152a5a241cb35c5571184d635633
Merge: 97f34bdc0c f0711a2bc3
Author: Protesilaos Stavrou <info@protesilaos.com>
Commit: Protesilaos Stavrou <info@protesilaos.com>

    Merge branch 'new-denote-directory-files'
---
 README.org               | 33 +++++++---------
 denote-journal-extras.el |  2 +-
 denote-sort.el           |  2 +-
 denote.el                | 97 ++++++++++++++++++++++++++++++------------------
 4 files changed, 75 insertions(+), 59 deletions(-)

diff --git a/README.org b/README.org
index 8ad7b4f696..e3d2890be0 100644
--- a/README.org
+++ b/README.org
@@ -3797,17 +3797,19 @@ might change them without further notice.
 
 #+findex: denote-directory-files
 + Function ~denote-directory-files~ :: Return list of absolute file
-  paths in variable ~denote-directory~.  Files only need to have an
-  identifier.  The return value may thus include file types that are
-  not implied by ~denote-file-type~. To limit the return value to text
-  files, use the function ~denote-directory-text-only-files~.
-  Remember that the ~denote-directory~ accepts a directory-local value
-  ([[#h:15719799-a5ff-4e9a-9f10-4ca03ef8f6c5][Maintain separate directories 
for notes]]).
-
-#+findex: denote-directory-text-only-files
-+ Function ~denote-directory-text-only-files~ :: Return list of text
-  files in variable ~denote-directory~.  Filter
-  ~denote-directory-files~ using ~denote-file-is-note-p~.
+  paths in variable ~denote-directory~. Files only need to have an
+  identifier. The return value may thus include file types that are
+  not implied by ~denote-file-type~. Remember that the variable
+  ~denote-directory~ accepts a dir-local value, as explained in its
+  doc string ([[#h:15719799-a5ff-4e9a-9f10-4ca03ef8f6c5][Maintain separate 
directories for notes]]). With optional
+  =FILES-MATCHING-REGEXP=, restrict files to those matching the given
+  regular expression. With optional =OMIT-CURRENT= as a non-nil value,
+  do not include the current Denote file in the returned list. With
+  optional =TEXT-ONLY= as a non-nil value, limit the results to text
+  files that satisfy ~denote-file-is-note-p~. [ As part of
+  {{{development-version}}}, the ~denote-directory-files~ subsumes the
+  now-deprecated ~denote-directory-files-matching-regexp~,
+  ~denote-all-files~, ~denote-directory-text-only-files~. ]
 
 #+findex: denote-directory-subdirectories
 + Function ~denote-directory-subdirectories~ :: Return list of
@@ -3817,15 +3819,6 @@ might change them without further notice.
   ~denote-directory~ accepts a directory-local value for what we call
   "silos" ([[#h:15719799-a5ff-4e9a-9f10-4ca03ef8f6c5][Maintain separate 
directories for notes]]).
 
-#+findex: denote-directory-files-matching-regexp
-+ Function ~denote-directory-files-matching-regexp~ :: Return list of
-  files matching =REGEXP= in ~denote-directory-files~.
-
-#+findex: denote-all-files
-+ Function ~denote-all-files~ :: Return the list of Denote files in
-  the variable ~denote-directory~. With optional =OMIT-CURRENT=, do
-  not include the current Denote file in the returned list.
-
 #+findex: denote-file-name-relative-to-denote-directory
 + Function ~denote-file-name-relative-to-denote-directory~ :: Return
   name of =FILE= relative to the variable ~denote-directory~.  =FILE=
diff --git a/denote-journal-extras.el b/denote-journal-extras.el
index 6fac979a9e..abdd8a4369 100644
--- a/denote-journal-extras.el
+++ b/denote-journal-extras.el
@@ -172,7 +172,7 @@ is internally processed by 
`denote-journal-extras--get-date'."
 (defun denote-journal-extras--entry-today (&optional date)
   "Return list of files matching a journal for today or optional DATE.
 DATE has the same format as that returned by 
`denote-journal-extras--get-date'."
-  (denote-directory-files-matching-regexp
+  (denote-directory-files
    (format "%sT[0-9]\\{6\\}.*_%s"
            (format-time-string "%Y%m%d" date)
            denote-journal-extras-keyword)))
diff --git a/denote-sort.el b/denote-sort.el
index b6195373af..8cd6ff9660 100644
--- a/denote-sort.el
+++ b/denote-sort.el
@@ -122,7 +122,7 @@ name component.
 
 With optional REVERSE as a non-nil value, reverse the sort order."
   (denote-sort-files
-   (denote-directory-files-matching-regexp files-matching-regexp)
+   (denote-directory-files files-matching-regexp)
    sort-by-component
    reverse))
 
diff --git a/denote.el b/denote.el
index d2b28bee7d..3fb3faba96 100644
--- a/denote.el
+++ b/denote.el
@@ -314,7 +314,7 @@ When the value is `text', the file type is that of Text 
mode.
 Any other non-nil value is the same as the default.
 
 NOTE: Expert users can change the supported file-types by editing
-the value of `denote-file-types'. That variable, which is not a
+the value of `denote-file-types'.  That variable, which is not a
 user option, controls the behaviour of all file-type-aware
 functions (creating notes, renaming them, inserting front matter,
 formatting a link, etc.). Consult its documentation for the
@@ -797,26 +797,49 @@ Avoids traversing dotfiles (unconditionally) and whatever 
matches
       (t)))
    :follow-symlinks))
 
-(defun denote-directory-files ()
+(defun denote-directory-files (&optional files-matching-regexp omit-current 
text-only)
   "Return list of absolute file paths in variable `denote-directory'.
 
 Files only need to have an identifier.  The return value may thus
 include file types that are not implied by `denote-file-type'.
-To limit the return value to text files, use the function
-`denote-directory-text-only-files'.
 
 Remember that the variable `denote-directory' accepts a dir-local
-value, as explained in its doc string."
-  (mapcar
-   #'expand-file-name
-   (seq-filter
-    #'denote-file-has-identifier-p
-    (denote--directory-all-files-recursively))))
+value, as explained in its doc string.
+
+With optional FILES-MATCHING-REGEXP, restrict files to those
+matching the given regular expression.
+
+With optional OMIT-CURRENT as a non-nil value, do not include the
+current Denote file in the returned list.
+
+With optional TEXT-ONLY as a non-nil value, limit the results to
+text files that satisfy `denote-file-is-note-p'."
+  (let ((files (mapcar
+                #'expand-file-name
+                (seq-filter
+                 #'denote-file-has-identifier-p
+                 (denote--directory-all-files-recursively)))))
+    (when (and omit-current buffer-file-name (denote-file-has-identifier-p 
buffer-file-name))
+      (setq files (delete buffer-file-name files)))
+    (when files-matching-regexp
+      (setq files (seq-filter
+                   (lambda (f)
+                     (string-match-p files-matching-regexp 
(denote-get-file-name-relative-to-denote-directory f)))
+                   files)))
+    (when text-only
+      (setq files (seq-filter #'denote-file-is-note-p 
(denote-directory-files))))
+    files))
+
+;; NOTE 2023-11-30: We are declaring `denote-directory-text-only-files'
+;; obsolete, though we keep it around for the foreseeable future.  It
+;; WILL BE REMOVED ahead of version 3.0.0 of Denote, whenever that
+;; happens.
+(make-obsolete 'denote-directory-text-only-files 'denote-directory-files 
"2.2.0")
 
 (defun denote-directory-text-only-files ()
   "Return list of text files in variable `denote-directory'.
 Filter `denote-directory-files' using `denote-file-is-note-p'."
-  (seq-filter #'denote-file-is-note-p (denote-directory-files)))
+  (denote-directory-files nil nil :text-only))
 
 (defun denote-directory-subdirectories ()
   "Return list of subdirectories in variable `denote-directory'.
@@ -882,8 +905,7 @@ something like .org even if the actual file extension is
   (let ((files
          (seq-filter
           (lambda (file)
-            (and (denote-file-has-identifier-p file)
-                 (string-prefix-p id (file-name-nondirectory file))))
+            (string-prefix-p id (file-name-nondirectory file)))
           (denote-directory-files))))
     (if (length< files 2)
         (car files)
@@ -902,21 +924,26 @@ something like .org even if the actual file extension is
 The path is relative to DIRECTORY (default: ‘default-directory’)."
   (file-relative-name (denote-get-path-by-id id) directory))
 
+;; NOTE 2023-11-30: We are declaring `denote-directory-files-matching-regexp'
+;; obsolete, though we keep it around for the foreseeable future.  It
+;; WILL BE REMOVED ahead of version 3.0.0 of Denote, whenever that
+;; happens.
+(make-obsolete 'denote-directory-files-matching-regexp 'denote-directory-files 
"2.2.0")
+
 (defun denote-directory-files-matching-regexp (regexp)
   "Return list of files matching REGEXP in `denote-directory-files'."
-  (seq-filter
-   (lambda (f)
-     (string-match-p regexp (denote-get-file-name-relative-to-denote-directory 
f)))
-   (denote-directory-files)))
+  (denote-directory-files regexp))
+
+;; NOTE 2023-11-30: We are declaring `denote-all-files' obsolete,
+;; though we keep it around for the foreseeable future.  It WILL BE
+;; REMOVED ahead of version 3.0.0 of Denote, whenever that happens.
+(make-obsolete 'denote-all-files 'denote-directory-files "2.2.0")
 
 (defun denote-all-files (&optional omit-current)
   "Return the list of Denote files in variable `denote-directory'.
 With optional OMIT-CURRENT, do not include the current Denote
 file in the returned list."
-  (let ((files (denote-directory-files)))
-    (if (and omit-current buffer-file-name (denote-file-has-identifier-p 
buffer-file-name))
-        (delete buffer-file-name files)
-      files)))
+  (denote-directory-files nil omit-current nil))
 
 (defvar denote--file-history nil
   "Minibuffer history of `denote-file-prompt'.")
@@ -925,9 +952,7 @@ file in the returned list."
   "Prompt for file with identifier in variable `denote-directory'.
 With optional FILES-MATCHING-REGEXP, filter the candidates per
 the given regular expression."
-  (let ((files (if files-matching-regexp
-                   (denote-directory-files-matching-regexp 
files-matching-regexp)
-                 (denote-all-files :omit-current))))
+  (let ((files (denote-directory-files files-matching-regexp :omit-current)))
     (completing-read "Select note: " files nil nil nil 'denote--file-history)))
 
 ;;;; Keywords
@@ -1475,10 +1500,11 @@ that internally)."
 
 (defun denote--retrieve-location-in-xrefs (identifier)
   "Return list of xrefs for IDENTIFIER with their respective location.
-Limit the search to text files, per `denote-directory-text-only-files'."
+Limit the search to text files, per `denote-directory-files' with
+non-nil `text-only' parameter."
   (mapcar #'xref-match-item-location
           (xref-matches-in-files identifier
-                                 (denote-directory-text-only-files))))
+                                 (denote-directory-files nil nil :text-only))))
 
 (defun denote--retrieve-group-in-xrefs (identifier)
   "Access location of xrefs for IDENTIFIER and group them per file.
@@ -3436,7 +3462,7 @@ ALIST is not used in favour of using
                     (when-let ((buffer-file-name file))
                       (denote-link--prepare-backlinks
                        (apply-partially #'xref-matches-in-files id
-                                        (delete file 
(denote-directory-text-only-files)))
+                                        (denote-directory-files nil 
:omit-current :text-only))
                        nil)))))
     (denote-link--display-buffer buf)))
 
@@ -3467,9 +3493,7 @@ default, it will show up below the current window."
              (project-find-functions #'denote-project-find))
         (xref--show-xrefs
          (apply-partially #'xref-matches-in-files id
-                          ;; remove the current buffer file from the
-                          ;; backlinks
-                          (delete file (denote-directory-text-only-files)))
+                          (denote-directory-files nil :omit-current 
:text-only))
          nil)))))
 
 (define-obsolete-function-alias
@@ -3529,10 +3553,8 @@ inserts links with just the identifier."
    (list
     (read-regexp "Insert links matching REGEX: " nil 
'denote-link--add-links-history)
     current-prefix-arg))
-  (let* ((current-file (buffer-file-name))
-         (file-type (denote-filetype-heuristics current-file)))
-    (if-let ((files (delete current-file
-                            (denote-directory-files-matching-regexp regexp)))
+  (let ((file-type (denote-filetype-heuristics (buffer-file-name))))
+    (if-let ((files (denote-directory-files regexp :omit-current))
              (beg (point)))
         (progn
           (insert (denote-link--prepare-links files file-type id-only))
@@ -4084,7 +4106,8 @@ current denote PROJECT."
 Return all files that have an identifier for the current denote
 PROJECT.  The return value may thus include file types that are
 not implied by `denote-file-type'.  To limit the return value to
-text files, use the function `denote-directory-text-only-files'."
+text files, use the function `denote-directory-files' with a
+non-nil `text-only' parameter."
   (denote-directory-files))
 
 (defun denote-project-find (dir)
@@ -4136,13 +4159,13 @@ and errors and if the word at point is not a Denote 
identifier."
 (cl-defmethod xref-backend-references ((_backend (eql 'denote)) identifier)
   "Return list of xrefs where IDENTIFIER is referenced.
 This include the definition itself."
-  (xref-matches-in-files identifier (denote-directory-text-only-files)))
+  (xref-matches-in-files identifier (denote-directory-files nil nil 
:text-only)))
 
 (cl-defmethod xref-backend-identifier-completion-table ((_backend
                                                          (eql 'denote)))
   "Return list of Denote identifers as completion table."
 
-  (mapcar #'denote-retrieve-filename-identifier (denote-all-files)))
+  (mapcar #'denote-retrieve-filename-identifier (denote-directory-files)))
 
 (provide 'denote)
 ;;; denote.el ends here