[elpa] externals/denote 3ad974396d 02/12: Make 'denote-link' more abstract to also call it from Lisp

[ELPA Syncer]

branch: externals/denote
commit 3ad974396d01d4e76a01ef0ca024303f547a2fb2
Author: Protesilaos Stavrou <info@protesilaos.com>
Commit: Protesilaos Stavrou <info@protesilaos.com>

    Make 'denote-link' more abstract to also call it from Lisp
---
 denote.el | 111 ++++++++++++++++++++++++++++++++++++++------------------------
 1 file changed, 68 insertions(+), 43 deletions(-)

diff --git a/denote.el b/denote.el
index fd754b33bf..61a92d956b 100644
--- a/denote.el
+++ b/denote.el
@@ -2939,13 +2939,15 @@ Fall back to `denote-org-link-format'."
    ;; Plain text also uses [[denote:ID][TITLE]]
    (t denote-org-link-format)))
 
-(defun denote-link--format-link (file format &optional description)
-  "Prepare link to FILE using FORMAT.
-If DESCRIPTION is non-nil, use it as link description instead of
-FILE's title.
-
-FORMAT is the symbol of a variable that specifies a string.  See
-the `:link' property of `denote-file-types'."
+(defun denote-format-link (file format description)
+  "Prepare link to FILE using FORMAT and DESCRIPTION text.
+FILE is the path to a file name.  FORMAT is the symbol of a
+variable that specifies a string.  See the `:link' property of
+`denote-file-types'.
+
+DESCRIPTION is the text of the link.  If nil, DESCRIPTION is
+retrieved from the FILE, unless the FORMAT is
+`denote-id-only-link-format'."
   (let* ((file-id (denote-retrieve-filename-identifier file))
          (fm (if (symbolp format) (symbol-value format) format))
          (file-type (denote-filetype-heuristics file))
@@ -2953,36 +2955,57 @@ the `:link' property of `denote-file-types'."
                        (or description (denote--retrieve-title-or-filename 
file file-type)))))
     (format fm file-id file-title)))
 
+(make-obsolete 'denote-link--format-link 'denote-format-link "2.1.0")
+
+(defun denote--link-get-description (file file-type)
+  "Return description for `denote-link'.
+If the region is active, make the description the text within the
+region's boundaries.  Else retrieve the title from FILE, given
+FILE-TYPE."
+  (if-let (((region-active-p))
+           (beg (region-beginning))
+           (end (region-end))
+           (selected-text (string-trim (buffer-substring-no-properties beg 
end))))
+      (progn
+        (delete-region beg end)
+        selected-text)
+    (denote--retrieve-title-or-filename file file-type)))
+
 ;;;###autoload
-(defun denote-link (target &optional id-only)
-  "Create link to TARGET note in variable `denote-directory'.
-With optional ID-ONLY, such as a universal prefix
-argument (\\[universal-argument]), insert links with just the
-identifier and no further description.  In this case, the link
-format is always [[denote:IDENTIFIER]].
-
-Use TARGET's title for the link's description.  The title comes
-either from the front matter or the file name.
-
-If region is active, use its text as the link's description
-instead of TARGET's title.  If active region is empty (i.e
-whitespace-only), insert an ID-ONLY link."
-  (interactive (list (denote-file-prompt) current-prefix-arg))
+(defun denote-link (file file-type description &optional id-only)
+  "Create link to FILE note in variable `denote-directory' with DESCRIPTION.
+
+When called interactively, prompt for FILE using completion.  In
+this case, derive FILE-TYPE from the selected FILE, as well as
+the DESCRIPTION from the title of FILE.  The title comes either
+from the front matter or the file name.  With an action region,
+the DESCRIPTION is the text of the region, despite the
+aforementioned.  If active region is empty (i.e whitespace-only),
+insert an ID-ONLY link.
+
+With optional ID-ONLY as a non-nil argument, such as with a
+universal prefix (\\[universal-argument]), insert links with just
+the identifier and no further description.  In this case, the
+link format is always [[denote:IDENTIFIER]].
+
+When called from Lisp, FILE is a string representing a full file
+system path.  FILE-TYPE is a symbol as described in
+`denote-file-type'.  DESCRIPTION is a string.  Whether the called
+treats the active region specially, is up to it."
+  (interactive
+   (let ((file (denote-file-prompt))
+         (type (denote-filetype-heuristics (buffer-file-name))))
+     (list
+      file
+      type
+      (denote--link-get-description file type)
+      current-prefix-arg)))
   (let* ((beg (point))
-         (description (when-let* (((region-active-p))
-                                  (beg (region-beginning))
-                                  (end (region-end))
-                                  (selected-text
-                                   (string-trim
-                                    (buffer-substring-no-properties beg end))))
-                        (delete-region beg end)
-                        selected-text))
-         (identifier-only (or id-only (string-empty-p description)))
-         (file-type (denote-filetype-heuristics (buffer-file-name))))
-    (when target
+         (identifier-only (or id-only (string-empty-p description))))
+    (when file
       (insert
-       (denote-link--format-link
-        target
+       (denote-format-link
+        file
         (denote-link--file-type-format file-type identifier-only)
         description))
       (unless (derived-mode-p 'org-mode)
@@ -3383,18 +3406,20 @@ default, it will show up below the current window."
 (defvar denote-link-add-links-sort nil
   "When t, add REVERSE to `sort-lines' of `denote-link-add-links'.")
 
-(defun denote-link--prepare-links (files current-file id-only)
-  "Prepare links to FILES from CURRENT-FILE.
+(defun denote-link--prepare-links (files current-file-type id-only)
+  "Prepare links to FILES from CURRENT-FILE-TYPE.
 When ID-ONLY is non-nil, use a generic link format.  See
 `denote-link--file-type-format'."
   (with-temp-buffer
-    (mapc (lambda (file)
-            (insert
-             (format
-              denote-link--prepare-links-format
-              (denote-link--format-link
-               file
-               (denote-link--file-type-format current-file id-only)))))
+    (mapc
+     (lambda (file)
+       (insert
+        (format
+         denote-link--prepare-links-format
+         (denote-format-link
+          file
+          (denote-link--file-type-format current-file-type id-only)
+          (denote--link-get-description file (denote-filetype-heuristics 
file))))))
           files)
     (sort-lines denote-link-add-links-sort (point-min) (point-max))
     (buffer-string)))