[elpa] externals/dtache 31d7ffd5f7 131/158: Rename redirect-only to attachable

[ELPA Syncer]

branch: externals/dtache
commit 31d7ffd5f7857958b9fa004d3069de3d3e980e8f
Author: Niklas Eklund <niklas.eklund@posteo.net>
Commit: Niklas Eklund <niklas.eklund@posteo.net>

    Rename redirect-only to attachable
    
    This patch changes the usage of redirect-only to nonattachable and
    attachable.
---
 README.org          | 26 ++++++++++++++------------
 dtache-compile.el   |  2 +-
 dtache-eshell.el    |  2 +-
 dtache-shell.el     |  8 ++++----
 dtache.el           | 37 ++++++++++++++++++-------------------
 test/dtache-test.el | 23 ++++++++++++-----------
 6 files changed, 50 insertions(+), 48 deletions(-)

diff --git a/README.org b/README.org
index c3e80f2a7d..f9f8dd24ab 100644
--- a/README.org
+++ b/README.org
@@ -233,6 +233,10 @@ By default =dtache= uses the echo area to notify the user 
when a session has fin
 #+end_src
 
 * Customization
+** TODO Customizable variables
+
+Add a table of all customizable variables, with explenations.
+
 ** Completion annotations
 
 The user can customize the appearance of annotations in =dtache-open-session= 
by modifying the =dtache-annotation-format=. The default annotation format is 
the following.
@@ -250,13 +254,9 @@ The user can customize the appearance of annotations in 
=dtache-open-session= by
     "The format of the annotations.")
 #+end_src
 
-If the user wants to remove specific annotations or decrease/increase the 
widths, do that by changing the values for this variable.
-
-** Automatic status labeling
+** Status deduction
 
-The =dtache-env= script, found in this repository, can be used to execute 
shell commands in a controlled environment. This environment makes sure that 
the exit status is present in the session's output. This allows =dtache= to 
parse it and automatically label a session with either =success= or =failure=.
-
-Add the following to the configuration in order to take advantage of this 
feature.
+The users are encouraged to define the =dtache-env= variable. It should point 
to the =dtache-env= script, which is provided in the repository. This script 
allows sessions to communicate the status of a session when it transitions to 
inactive. When configured properly =dtache= will be able to set the status of a 
session to either =success= or =failure=.
 
 #+begin_src elisp :lexical t :results none
   (setq dtache-env "/path/to/repo/dtache-env")
@@ -264,7 +264,7 @@ Add the following to the configuration in order to take 
advantage of this featur
 
 ** Metadata annotators
 
-The user can configure any number of annotators to run upon creation of a 
session. Here is an example of an annotator which captures the branch name if 
the session is started in a git repository.
+The user can configure any number of annotators to run upon creation of a 
session. Here is an example of an annotator which captures the git branch name, 
if the session is started in a git repository.
 
 #+begin_src elisp :lexical t :results none
   (defun my/dtache--session-git-branch ()
@@ -277,25 +277,27 @@ The user can configure any number of annotators to run 
upon creation of a sessio
             (string-trim (buffer-string)))))))
 #+end_src
 
-The user only needs to add this function to the list of annotators.
+Next add the annotation function to the =dtache-metadata-annotators-alist= 
together with a symbol describing the property.
 
 #+begin_src elisp :lexical t :results none
   (setq dtache-metadata-annotators-alist '((branch . 
my/dtache--session-git-branch))
 #+end_src
 
-** Redirect only
+** TODO Redirect only
 
 Some programs doesn't play well with =tee=, which =dtache= relies upon to 
redirect the output both to standard out as well as to file. If you encounter a 
situation where output from a session is only visible once it has become 
inactive, the command you launched should instead be using =redirect only=. To 
list a command to run with redirect only can be done by adding a regexp to 
=dtache-redirect-only-regexps=.
 
 #+begin_src elisp :lexical t :results none
-  (setq dtache-redirect-only-regexps '("^ls"))
+  (setq dtache-nonattachable-commands '("^ls"))
 #+end_src
 
 Here a command beginning with =ls= would from now on be using redirect only.
+
+This should be renamed =not attachable= or similar.
 * Tips & Tricks
 ** Remote support
 
-The =dtache= package supports 
[[https://www.gnu.org/software/emacs/manual/html_node/elisp/Connection-Local-Variables.html][Connection
 Local Variables]] which allows you to change the variables used by =dtache= 
when running on a remote host. This useful when the user needs to alter dtache 
settings when running on a remote host.
+The =dtache= package supports 
[[https://www.gnu.org/software/emacs/manual/html_node/elisp/Connection-Local-Variables.html][Connection
 Local Variables]] which allows the user to customize the variables used by 
=dtache= when running on a remote host. This example shows how the following 
variables are customized for all remote hosts.
 
 #+begin_src elisp :lexical t :results none
   (connection-local-set-profile-variables
@@ -312,7 +314,7 @@ The =dtache= package supports 
[[https://www.gnu.org/software/emacs/manual/html_n
 
 * Versions
 
-Information about larger changes that has been made between versions can be 
found in the [[./CHANGELOG.org]]
+Information about larger changes that has been made between versions can be 
found in the =CHANGELOG.org=
 
 * Contributions
 
diff --git a/dtache-compile.el b/dtache-compile.el
index 8ddea2e6ba..bbdcf77d17 100644
--- a/dtache-compile.el
+++ b/dtache-compile.el
@@ -99,7 +99,7 @@ Optionally EDIT-COMMAND."
       (pcase-let ((`(,command ,mode ,_ ,highlight-regexp) args)
                   (buffer-name "*dtache-compilation*"))
         (if (and (not (eq dtache-session-mode 'attach))
-                 (dtache-redirect-only-p command))
+                 (not (dtache-attachable-command-p command)))
             (dtache-start-session command t)
           (cl-letf* ((name-function (lambda (_) buffer-name))
                      (dtache--current-session (or dtache--current-session
diff --git a/dtache-eshell.el b/dtache-eshell.el
index 0205dac926..5163fadc1d 100644
--- a/dtache-eshell.el
+++ b/dtache-eshell.el
@@ -86,7 +86,7 @@ If prefix-argument directly DETACH from the session."
    (list (dtache-eshell-select-session)))
   (when (dtache-valid-session session)
     (if (and (eq 'active (dtache--determine-session-state session))
-             (not (dtache--session-redirect-only session)))
+             (dtache--session-attachable session))
         (cl-letf* ((dtache-session-mode 'attach)
                    (input
                     (dtache-dtach-command session t))
diff --git a/dtache-shell.el b/dtache-shell.el
index 62d3b4f2d7..010b6387b1 100644
--- a/dtache-shell.el
+++ b/dtache-shell.el
@@ -83,7 +83,7 @@ cluttering the comint-history with dtach commands."
    (list (dtache-shell-select-session)))
   (when (dtache-valid-session session)
     (if (and (eq 'active (dtache--determine-session-state session))
-             (not (dtache--session-redirect-only session)))
+             (dtache--session-attachable session))
         (cl-letf ((dtache--current-session session)
                   (comint-input-sender #'dtache-shell--attach-input-sender)
                   ((symbol-function 'comint-add-to-input-history) (lambda (_) 
t)))
@@ -105,9 +105,9 @@ cluttering the comint-history with dtach commands."
   "Create a dtache session based on STRING and send to PROC."
   (with-connection-local-variables
    (let* ((command (substring-no-properties string))
-          (dtache-session-mode (if (dtache-redirect-only-p command)
-                                   'new
-                                 'create))
+          (dtache-session-mode (if (dtache-attachable-command-p command)
+                                   'create
+                                 'new))
           (dtach-command (dtache-dtach-command command t)))
      (comint-simple-send proc dtach-command))))
 
diff --git a/dtache.el b/dtache.el
index adca3a2cf2..5f93778379 100644
--- a/dtache.el
+++ b/dtache.el
@@ -114,8 +114,8 @@
   :group 'dtache
   :type 'plist)
 
-(defcustom dtache-redirect-only-regexps nil
-  "Regexps for commands that should be run with redirect only."
+(defcustom dtache-nonattachable-commands nil
+  "A list of commands which `dtache' should consider nonattachable."
   :type '(repeat (regexp :format "%v"))
   :group 'dtache)
 
@@ -143,7 +143,7 @@ Valid values are: create, new and attach")
 (defvar dtache-metadata-annotators-alist nil
   "An alist of annotators for metadata.")
 
-(defconst dtache-session-version "0.2.2"
+(defconst dtache-session-version "0.2.3"
   "The version of `dtache-session'.
 This version is encoded as [package-version].[revision].")
 
@@ -239,7 +239,7 @@ This version is encoded as [package-version].[revision].")
   (directory nil :read-only t)
   (metadata nil :read-only t)
   (host nil :read-only t)
-  (redirect-only nil :read-only t)
+  (attachable nil :read-only t)
   (action nil :read-only t)
   (status nil)
   (duration nil)
@@ -488,7 +488,7 @@ compilation or shell-command the command will also kill the 
window."
                                  :origin dtache-session-origin
                                  :action dtache-session-action
                                  :working-directory 
(dtache--get-working-directory)
-                                 :redirect-only (dtache-redirect-only-p 
command)
+                                 :attachable (dtache-attachable-command-p 
command)
                                  :creation-time (time-to-seconds 
(current-time))
                                  :status 'unknown
                                  :log-size 0
@@ -512,7 +512,7 @@ Optionally SUPPRESS-OUTPUT."
     (if-let ((run-in-background
               (and (or suppress-output
                        (eq dtache-session-mode 'new)
-                       (dtache--session-redirect-only 
dtache--current-session))))
+                       (not (dtache--session-attachable 
dtache--current-session)))))
              (dtache-session-mode 'new))
         (progn (setq dtache-enabled nil)
                (apply #'start-file-process-shell-command
@@ -632,7 +632,7 @@ If session is not valid trigger an automatic cleanup on 
SESSION's host."
     (let* ((dtache--current-session session)
            (dtache-session-mode 'attach)
            (inhibit-message t))
-      (if (dtache--session-redirect-only session)
+      (if (dtache--session-attachable session)
           (dtache--attach-session session)
         (cl-letf* (((symbol-function #'set-process-sentinel) #'ignore)
                    (buffer dtache--shell-command-buffer)
@@ -657,7 +657,7 @@ Optionally CONCAT the command return command into a string."
 Optionally CONCAT the command return command into a string."
   (with-connection-local-variables
    (let* ((dtache-session-mode (cond ((eq dtache-session-mode 'attach) 'attach)
-                                    ((dtache--session-redirect-only session) 
'new)
+                                     ((not (dtache--session-attachable 
session)) 'new)
                                     (t dtache-session-mode)))
           (socket (dtache--session-file session 'socket t)))
      (setq dtache--buffer-session session)
@@ -681,15 +681,15 @@ Optionally CONCAT the command return command into a 
string."
            ,dtache-shell-program "-c"
            ,(dtache--magic-command session)))))))
 
-(defun dtache-redirect-only-p (command)
-  "Return t if COMMAND should run in degreaded mode."
-  (if (thread-last dtache-redirect-only-regexps
+(defun dtache-attachable-command-p (command)
+  "Return t if COMMAND is attachable."
+  (if (thread-last dtache-nonattachable-commands
         (seq-filter (lambda (regexp)
                       (string-match-p regexp command)))
         (length)
         (= 0))
-      nil
-    t))
+      t
+    nil))
 
 (defun dtache-metadata ()
   "Return a property list with metadata."
@@ -933,7 +933,7 @@ Optionally make the path LOCAL to host."
 
 (defun dtache--attach-session (session)
   "Attach to SESSION."
-  (if (dtache--session-redirect-only session)
+  (if (not (dtache--session-attachable session))
       (dtache-tail-output session)
     (if-let ((attach-fun (plist-get (dtache--session-action session) :attach)))
         (funcall attach-fun session)
@@ -1052,13 +1052,12 @@ Optionally make the path LOCAL to host."
 (defun dtache--magic-command (session)
   "Return the magic dtache command for SESSION.
 
-If SESSION is redirect-only fallback to a command that doesn't rely on tee.
-Otherwise use tee to log stdout and stderr individually."
+If SESSION is nonattachable fallback to a command that doesn't rely on tee."
   (let* ((log (dtache--session-file session 'log t))
          (redirect
-          (if (dtache--session-redirect-only session)
-              (format "&> %s" log)
-            (format "2>&1 | tee %s" log)))
+          (if (dtache--session-attachable session)
+              (format "2>&1 | tee %s" log)
+             (format "&> %s" log)))
          (env (if dtache-env dtache-env (format "%s -c" dtache-shell-program)))
          (command
           (shell-quote-argument
diff --git a/test/dtache-test.el b/test/dtache-test.el
index 54a2f6c06e..951ee9c7a4 100644
--- a/test/dtache-test.el
+++ b/test/dtache-test.el
@@ -202,34 +202,35 @@
      (should (equal copy (car (dtache--db-get-sessions)))))))
 
 (ert-deftest dtache-test-magic-command ()
-  (let ((normal-session (dtache--session-create :directory "/tmp/dtache/"
+  (let ((attachable-session (dtache--session-create :directory "/tmp/dtache/"
                                                 :working-directory 
"/home/user/"
                                                 :command "ls -la"
+                                                :attachable t
                                                 :id 'foo123))
-        (redirect-session (dtache--session-create :directory "/tmp/dtache/"
+        (nonattachable-session (dtache--session-create :directory 
"/tmp/dtache/"
                                                 :working-directory 
"/home/user/"
                                                 :command "ls -la"
-                                                :redirect-only t
+                                                :attachable nil
                                                 :id 'foo123)))
     ;; With dtache-env
     (let ((dtache-env "dtache-env"))
       (should (string= "{ dtache-env ls\\ -la; } 2>&1 | tee 
/tmp/dtache/foo123.log"
-                       (dtache--magic-command normal-session)))
+                       (dtache--magic-command attachable-session)))
       (should (string= "{ dtache-env ls\\ -la; } &> /tmp/dtache/foo123.log"
-                       (dtache--magic-command redirect-session))))
+                       (dtache--magic-command nonattachable-session))))
 
     ;; Without dtache-env
     (let ((dtache-env nil)
           (dtache-shell-program "bash"))
       (should (string= "{ bash -c ls\\ -la; } 2>&1 | tee 
/tmp/dtache/foo123.log"
-                       (dtache--magic-command normal-session)))
+                       (dtache--magic-command attachable-session)))
       (should (string= "{ bash -c ls\\ -la; } &> /tmp/dtache/foo123.log"
-                       (dtache--magic-command redirect-session))))))
+                       (dtache--magic-command nonattachable-session))))))
 
-(ert-deftest dtache-test-redirect-only-p ()
-  (let ((dtache-redirect-only-regexps '("ls")))
-    (should (not (dtache-redirect-only-p "cd")))
-    (should (dtache-redirect-only-p "ls -la"))))
+(ert-deftest dtache-test-attachable-command-p ()
+  (let ((dtache-nonattachable-commands '("ls")))
+    (should (dtache-attachable-command-p "cd"))
+    (should (not (dtache-attachable-command-p "ls -la")))))
 
 (ert-deftest dtache-test-session-pid ()
   (cl-letf* (((symbol-function #'process-file) (lambda (_program _infile 
_buffer _display &rest _args)