[elpa] externals/detached 1ac5d3a25b: Add annoation property to a session

[ELPA Syncer]

branch: externals/detached
commit 1ac5d3a25b96e544e108c94d3f485c4d36b8bc4b
Author: Niklas Eklund <niklas.eklund@posteo.net>
Commit: Niklas Eklund <niklas.eklund@posteo.net>

    Add annoation property to a session
    
    This patch makes it possible to record an annotation to a
    session. This can be seen as a small note for future self about what a
    session might be about. This could aid when comparing different
    sessions that otherwise could look similar.
---
 CHANGELOG.org    |  3 ++-
 detached-list.el | 37 +++++++++++++++++++++++++++++++++++--
 detached.el      | 11 ++++++++++-
 3 files changed, 47 insertions(+), 4 deletions(-)

diff --git a/CHANGELOG.org b/CHANGELOG.org
index 85709be751..af92f54fee 100644
--- a/CHANGELOG.org
+++ b/CHANGELOG.org
@@ -10,7 +10,8 @@
 - Narrow criteria are persistent and applied when resuming detached list 
sessions.
 - Add narrow criterion which searches through the output of all sessions in 
detached list which matches a regexp.
 - Add database hook in order for detached list to update automatically when a 
session is updated.
-
+- Add annotation property to session. This allows users to add a custom 
annotation to a session, see it as a possibility to document a session for the 
future.
+  
 * Version 0.9.1 (2022-09-22)
 
 - Fix bug with detaching in =shell=
diff --git a/detached-list.el b/detached-list.el
index d1fe0047f4..c7f39bbe89 100644
--- a/detached-list.el
+++ b/detached-list.el
@@ -84,10 +84,24 @@ detached list implements."
   "A member of `eldoc-documentation-functions', for signatures."
   (let ((session (tabulated-list-get-id)))
     (when (detached-session-p session)
-      (detached--session-command session))))
+      (let ((strs `(,(detached--session-command session)
+                    ,(when-let  ((annotation (detached--session-annotation 
session)))
+                       (propertize annotation 'face 
'detached-annotation-face)))))
+        (string-join (seq-remove #'null strs) "\n")))))
 
 ;;;; Commands
 
+(defun detached-list-edit-annotation (session)
+  "Edit SESSION's annotation."
+  (interactive
+   (list (tabulated-list-get-id)))
+  (when-let* ((initial-value (or
+                     (detached--session-annotation session)
+                     ""))
+              (annotation (read-string "Annotation: " initial-value)))
+    (setf (detached--session-annotation session) annotation)
+    (detached--db-update-entry session)))
+
 (defun detached-list-quit ()
   "Quit command."
   (interactive)
@@ -266,6 +280,21 @@ Optionally SUPPRESS-OUTPUT."
                        sessions)))
        ,@detached-list--filters))))
 
+(defun detached-list-narrow-annotation-regexp (regexp)
+  "Narrow to sessions which annotation match REGEXP."
+  (interactive
+   (list (read-regexp
+          "Filter session annotations containing (regexp): ")))
+  (when regexp
+    (detached-list-narrow-sessions
+     `((,(concat "Annotation: " regexp) .
+        ,(lambda (sessions)
+           (seq-filter (lambda (it)
+                         (when-let ((annotation (detached--session-annotation 
it)))
+                           (string-match regexp annotation)))
+                       sessions)))
+       ,@detached-list--filters))))
+
 (defun detached-list-narrow-local ()
   "Narrow to local sessions."
   (interactive)
@@ -615,6 +644,7 @@ If prefix-argument is provided unmark instead of mark."
 
 (defvar detached-list-mode-map
   (let ((map (make-sparse-keymap)))
+    (define-key map (kbd "a") #'detached-list-edit-annotation)
     (define-key map (kbd "d") #'detached-list-delete-session)
     (define-key map (kbd "f") #'detached-list-select-filter)
     (define-key map (kbd "g") #'detached-list-revert)
@@ -630,7 +660,8 @@ If prefix-argument is provided unmark instead of mark."
     (define-key map (kbd "n r") #'detached-list-narrow-remote)
     (define-key map (kbd "n s") #'detached-list-narrow-success)
     (define-key map (kbd "n /") #'detached-list-narrow-output-regexp)
-    (define-key map (kbd "n %") #'detached-list-narrow-regexp)
+    (define-key map (kbd "n % a") #'detached-list-narrow-annotation-regexp)
+    (define-key map (kbd "n % c") #'detached-list-narrow-regexp)
     (define-key map (kbd "q") #'detached-list-quit)
     (define-key map (kbd "r") #'detached-list-rerun-session)
     (define-key map (kbd "t") #'detached-list-toggle-mark-session)
@@ -655,6 +686,8 @@ If prefix-argument is provided unmark instead of mark."
   (setq tabulated-list-padding 2)
   (setq tabulated-list-sort-key nil)
   (setq imenu-create-index-function #'detached-list-imenu-index)
+  (setq-local eldoc-echo-area-use-multiline-p t)
+  (setq-local eldoc-idle-delay 0)
   (add-hook 'eldoc-documentation-functions #'detached-list-eldoc nil t)
   (add-hook 'tabulated-list-revert-hook #'detached-list--revert-sessions nil t)
   (tabulated-list-init-header))
diff --git a/detached.el b/detached.el
index 447a528996..14b3663f10 100644
--- a/detached.el
+++ b/detached.el
@@ -220,7 +220,10 @@ Valid values are: create, new and attach")
 (defvar detached-metadata-annotators-alist nil
   "An alist of annotators for metadata.")
 
-(defconst detached-session-version "0.9.1.0"
+(defvar detached-session-annotation nil
+  "An annotation string.")
+
+(defconst detached-session-version "0.9.1.1"
   "The version of `detached-session'.
 This version is encoded as [package-version].[revision].")
 
@@ -271,6 +274,10 @@ This version is encoded as [package-version].[revision].")
   '((t :inherit detached-state-face))
   "Face used to highlight marked session in `detached-list-mode'.")
 
+(defface detached-annotation-face
+  '((t :inherit font-lock-comment-face))
+  "Face used to highlight the annotation of a session in `eldoc-mode'.")
+
 ;;;;; Private
 
 (defvar detached--sessions-initialized nil
@@ -336,6 +343,7 @@ This version is encoded as [package-version].[revision].")
   (degraded nil :read-only t)
   (env nil :read-only t)
   (action nil :read-only t)
+  (annotation)
   (time nil)
   (status nil)
   (size nil)
@@ -634,6 +642,7 @@ active session.  For sessions created with 
`detached-compile' or
                                     :initial-mode detached-session-mode
                                     :time `(:start ,(time-to-seconds 
(current-time)) :end 0.0 :duration 0.0 :offset 0.0)
                                     :status '(unknown . 0)
+                                    :annotation detached-session-annotation
                                     :size 0
                                     :directory 
(detached--get-session-directory)
                                     :env (detached--env command)