[nongnu] elpa/annotate d52ee5dec0 359/372: Merge pull request #113 from cage2/master

[ELPA Syncer]

branch: elpa/annotate
commit d52ee5dec0bb9bf365e031bdeda4f8692488b1d9
Merge: 4ae1d4f2a6 a45584c53f
Author: cage2 <1257703+cage2@users.noreply.github.com>
Commit: GitHub <noreply@github.com>

    Merge pull request #113 from cage2/master
    
    Added a command to delete an annotation
---
 README.org  | 31 +++++++++++++++++++++++--------
 annotate.el | 58 +++++++++++++++++++++++++++++++++++++++++++++++-----------
 2 files changed, 70 insertions(+), 19 deletions(-)

diff --git a/README.org b/README.org
index eabe5b8ec6..1703fac7c1 100644
--- a/README.org
+++ b/README.org
@@ -22,8 +22,8 @@ is active, ~C-c C-a~ will create, edit, or delete annotations.
 With an  active region, ~C-c  C-a~ creates  a new annotation  for that
 region. With no active region, ~C-c C-a~ will create an annotation for
 the word  under point. If point  is on an annotated  region, ~C-c C-a~
-will edit that annotation instead of  creating a new one. Clearing the
-annotation deletes them.
+will edit that  annotation instead of creating a new  one. Typing ~C-c
+C-d~ or clearing the annotation deletes them.
 
 Use ~C-c ]~ to jump to the next  annotation and ~C-c [~ to jump to the
 previous annotation.
@@ -76,6 +76,10 @@ can take advantage of its packages generated files 
management.
     will edit that annotation instead of  creating a new one. Clearing the
     annotation deletes them.
 
+    If ~annotate-annotation-confirm-deletion~ is  non nil (the default
+    is *nil*) a confirmation action is asked, using ~y-or-n-p~, to the
+    user before actually remove the annotation.
+
     If point  is the newline  character and the  customizable variable
     ~annotate-endline-annotate-whole-line~ is not  nil (default is non
     nil)  the whole  line is  annotated (or  the next  if the  line is
@@ -87,14 +91,25 @@ can take advantage of its packages generated files 
management.
     will signal an error.
 
 **** related customizable variable
-     - ~annotate-endline-annotate-whole-line~
-     - ~annotate-highlight~;
-     - ~annotate-highlight-secondary~;
-     - ~annotate-annotation~;
-     - ~annotate-annotation-secondary~;
      - ~annotate-annotation-column~;
+     - ~annotate-annotation-confirm-deletion~;
      - ~annotate-annotation-max-size-not-place-new-line~;
-     - ~annotate-annotation-position-policy~.
+     - ~annotate-annotation-position-policy~;
+     - ~annotate-annotation-secondary~;
+     - ~annotate-annotation~;
+     - ~annotate-endline-annotate-whole-line~;
+     - ~annotate-highlight-secondary~;
+     - ~annotate-highlight~.
+
+*** ~C-c C-d~
+    Delete an annotation under point, if such annotation exists.
+
+    If ~annotate-annotation-confirm-deletion~ is  non nil (the default
+    is *nil*) a confirmation action is asked, using ~y-or-n-p~, to the
+    user before actually remove the annotation.
+
+**** related customizable variable
+     - ~annotate-annotation-confirm-deletion~.
 
 *** ~C-c ]~ (function annotate-goto-next-annotation)
     Jump to the next  annotation.
diff --git a/annotate.el b/annotate.el
index 3df082c70f..cac2992623 100644
--- a/annotate.el
+++ b/annotate.el
@@ -7,7 +7,7 @@
 ;; Maintainer: Bastian Bechtold
 ;; URL: https://github.com/bastibe/annotate.el
 ;; Created: 2015-06-10
-;; Version: 1.3.2
+;; Version: 1.4.2
 
 ;; This file is NOT part of GNU Emacs.
 
@@ -58,7 +58,7 @@
 ;;;###autoload
 (defgroup annotate nil
   "Annotate files without changing them."
-  :version "1.3.2"
+  :version "1.4.2"
   :group 'text)
 
 ;;;###autoload
@@ -73,6 +73,8 @@ See https://github.com/bastibe/annotate.el/ for 
documentation."
 
 (define-key annotate-mode-map (kbd "C-c C-a") 'annotate-annotate)
 
+(define-key annotate-mode-map (kbd "C-c C-d") 'annotate-delete-annotation)
+
 (define-key annotate-mode-map (kbd "C-c C-s") 
'annotate-show-annotation-summary)
 
 (define-key annotate-mode-map (kbd "C-c ]") 'annotate-goto-next-annotation)
@@ -162,6 +164,12 @@ file will be shown."
   :type 'boolean
   :group 'annotate)
 
+(defcustom annotate-annotation-confirm-deletion nil
+ "If non nil a prompt asking confirmation before deleting an
+annotation file will be shown."
+  :type 'boolean
+  :group 'annotate)
+
 (defcustom annotate-annotation-max-size-not-place-new-line 15
  "The maximum `string-width` allowed for an annotation to be
 placed on the right margin of the window instead of its own line
@@ -281,6 +289,9 @@ annotation as defined in the database."
 (defconst annotate-summary-replace-button-label "[replace]"
   "The label for the button, in summary window, to replace an annotation.")
 
+(defconst annotate-confirm-deleting-annotation-prompt  "Delete this 
annotation? "
+  "The string for the prompt to be shown when asking for annotation deletion 
confirm.")
+
 ;;;; custom errors
 
 (define-error 'annotate-error "Annotation error")
@@ -1995,9 +2006,7 @@ This function is not part of the public API."
    (save-excursion
      (with-current-buffer (current-buffer)
        (let* ((chain         (annotate-find-chain annotation))
-              (filename      (annotate-actual-file-name))
-              (info-format-p (eq (annotate-guess-file-format filename)
-                                 :info)))
+              (filename      (annotate-actual-file-name)))
          (dolist (single-element chain)
            (goto-char (overlay-end single-element))
            (move-end-of-line nil)
@@ -2008,6 +2017,8 @@ This function is not part of the public API."
 (defun annotate--delete-annotation-chain-ring (annotation-ring)
   "Delete overlay of `annotation-ring' from a buffer.
 
+A ring is a single element of an annotation chain.
+
 This function is not part of the public API."
   (annotate-ensure-annotation (annotation-ring)
     (save-excursion
@@ -2018,7 +2029,8 @@ This function is not part of the public API."
       (delete-overlay annotation-ring))))
 
 (defun annotate-delete-chain-element (annotation)
-  "Delete a ring from a chain where `annotation' belong."
+  "Delete a ring (a ring is a single element of an annotation chain.)
+from a chain where `annotation' belong."
   (annotate-ensure-annotation (annotation)
     (let* ((chain                   (annotate-find-chain    annotation))
            (first-of-chain-p        (annotate-chain-first-p annotation))
@@ -2073,15 +2085,37 @@ This function is not part of the public API."
        (t
         (move-overlay last-annotation last-annotation-starting-pos 
new-ending-pos))))))
 
+(defun annotate--delete-annotation-chain-prevent-modification (annotation)
+"Delete an annotation chain backing up and restoring modification
+status of the buffer before deletion occured.
+
+This function is not part of the public API."
+  (annotate-ensure-annotation (annotation)
+    (annotate-with-restore-modified-bit
+     (annotate--delete-annotation-chain annotation))))
+
+(defun annotate--confirm-annotation-delete ()
+  "Prompt user for delete confirmation.
+This function is not part of the public API."
+  (or (not annotate-annotation-confirm-deletion)
+      (y-or-n-p annotate-confirm-deleting-annotation-prompt)))
+
+(cl-defun annotate-delete-annotation (&optional (point (point)))
+  "Command  to  delete  an  annotation,  `point'  is  the  buffer
+position  where  to  look  for  annotation  (default  the  cursor
+point)."
+  (interactive)
+  (when-let ((annotation (annotate-annotation-at point)))
+    (let* ((delete-confirmed-p (annotate--confirm-annotation-delete)))
+      (when delete-confirmed-p
+        (annotate--delete-annotation-chain-prevent-modification annotation)))))
+
 (defun annotate-change-annotation (pos)
   "Change annotation at point. If empty, delete annotation."
   (let* ((highlight       (annotate-annotation-at pos))
          (annotation-text (read-from-minibuffer annotate-annotation-prompt
                                                 (overlay-get highlight 
'annotation))))
-    (cl-labels ((delete (annotation)
-                  (annotate-with-restore-modified-bit
-                    (annotate--delete-annotation-chain annotation)))
-                (change (annotation)
+    (cl-labels ((change (annotation)
                   (let ((chain (annotate-find-chain annotation)))
                     (dolist (single-element chain)
                       (annotate-overlay-maybe-set-help-echo single-element 
annotation-text)
@@ -2092,7 +2126,9 @@ This function is not part of the public API."
          ((null annotation-text))
          ;; annotation was erased:
          ((string= "" annotation-text)
-          (delete highlight))
+          (let* ((delete-confirmed-p (annotate--confirm-annotation-delete)))
+            (when delete-confirmed-p
+              (annotate--delete-annotation-chain-prevent-modification 
highlight))))
          ;; annotation was changed:
          (t
           (change highlight)))))))