ob-shell.el: New option `org-babel-shell-results-defaults-to-output'

* lisp/ob-shell.el (org-babel-shell-results-defaults-to-output):
New option.

* testing/lisp/test-ob-exp.el (ob-exp/exports-inline): Fix test.

See <https://orgmode.org/list/CA+A2iZaziAfMeGpBqL6qGrzrWEVvLvC0DUw++T4gCF3NGuW-DQ@mail.gmail.com>

3 files changed, 47 insertions, 9 deletions

diff --git a/etc/ORG-NEWS b/etc/ORG-NEWS
index 87c5696..983709c 100644
--- a/etc/ORG-NEWS
+++ b/etc/ORG-NEWS
@@ -359,6 +359,25 @@ You can turn this on/off on a per-file basis with =#+startup: num= or
 This new option allows you to convert a LaTeX fragment directly into
 HTML.
 
+*** New option ~org-babel-shell-results-defaults-to-output~
+
+By default, source code blocks are executed in "functional mode": it
+means that the results of executing them are the value of their last
+statement (see [[https://orgmode.org/manual/Results-of-Evaluation.html][the documentation]].)
+
+The value of a shell script's execution is its exit code.  But most
+users expect the results of executing a shell script to be its output,
+not its exit code.
+
+So we introduced this option, that you can set to =nil= if you want
+to stick using ~:results value~ as the implicit header.
+
+In all Babel libraries, the absence of a ~:results~ header should
+produce the same result than setting ~:results value~, unless there is
+an option to explicitly create an exception.
+
+See [[https://orgmode.org/list/CA+A2iZaziAfMeGpBqL6qGrzrWEVvLvC0DUw++T4gCF3NGuW-DQ@mail.gmail.com/][this thread]] for more context.
+
 *** New hook ~org-agenda-filter-hook~
 
 Functions in this hook are run after ~org-agenda-filter~ is called.
@@ -5669,7 +5688,7 @@ that Calc formulas can operate on them.
 
      Thanks to Nicolas Goaziou for coding these changes.
 
-**** A property value of "nil" now means to unset a property
+**** A property value of =nil= now means to unset a property
 
      This can be useful in particular with property inheritance, if
      some upper level has the property, and some grandchild of it
diff --git a/lisp/ob-shell.el b/lisp/ob-shell.el
index 2f6b4ec..c08ba50 100644
--- a/lisp/ob-shell.el
+++ b/lisp/ob-shell.el
@@ -71,6 +71,19 @@ outside the Customize interface."
 	 (set-default symbol value)
 	 (org-babel-shell-initialize)))
 
+(defcustom org-babel-shell-results-defaults-to-output t
+  "Let shell execution defaults to \":results output\".
+
+When set to t, use \":results output\" when no :results setting
+is set.  This is especially useful for inline source blocks.
+
+When set to nil, stick to the convention of using :results value
+as the default setting when no :results is set, the \"value\" of
+a shell execution being its exit code."
+  :group 'org-babel
+  :type 'boolean
+  :package-version '(Org . "9.4"))
+
 (defun org-babel-execute:shell (body params)
   "Execute a block of Shell commands with Babel.
 This function is called by `org-babel-execute-src-block'."
@@ -80,8 +93,11 @@ This function is called by `org-babel-execute-src-block'."
                   (when stdin (org-babel-sh-var-to-string
                                (org-babel-ref-resolve stdin)))))
 	 (results-params (cdr (assq :result-params params)))
-	 (value-is-exit-status (or (equal '("replace") results-params)
-				   (member "value" results-params)))
+	 (value-is-exit-status
+	  (or (and
+	       (equal '("replace") results-params)
+	       (not org-babel-shell-results-defaults-to-output))
+	      (member "value" results-params)))
 	 (cmdline (cdr (assq :cmdline params)))
          (full-body (concat
 		     (org-babel-expand-body:generic
@@ -215,8 +231,11 @@ of the statements in BODY, if RESULT-TYPE equals `value' then
 return the value of the last statement in BODY."
   (let* ((shebang (cdr (assq :shebang params)))
 	 (results-params (cdr (assq :result-params params)))
-	 (value-is-exit-status (or (equal '("replace") results-params)
-				   (member "value" results-params)))
+	 (value-is-exit-status
+	  (or (and
+	       (equal '("replace") results-params)
+	       (not org-babel-shell-results-defaults-to-output))
+	      (member "value" results-params)))
 	 (results
 	  (cond
 	   ((or stdin cmdline)	       ; external shell script w/STDIN
diff --git a/testing/lisp/test-ob-exp.el b/testing/lisp/test-ob-exp.el
index 32b22b1..f6be51f 100644
--- a/testing/lisp/test-ob-exp.el
+++ b/testing/lisp/test-ob-exp.el
@@ -190,9 +190,9 @@ a table."
 (ert-deftest ob-exp/exports-inline ()
   (should
    (string-match
-    (regexp-quote "Here is one in the middle {{{results(=0=)}}} of a line.
-Here is one at the end of a line. {{{results(=0=)}}}
-{{{results(=0=)}}} Here is one at the beginning of a line.")
+    (regexp-quote "Here is one in the middle {{{results(=1=)}}} of a line.
+Here is one at the end of a line. {{{results(=2=)}}}
+{{{results(=3=)}}} Here is one at the beginning of a line.")
     (org-test-at-id "54cb8dc3-298c-4883-a933-029b3c9d4b18"
       (org-narrow-to-subtree)
       (let ((org-babel-inline-result-wrap "=%s="))
@@ -252,7 +252,7 @@ Here is one at the end of a line. {{{results(=0=)}}}
      (regexp-quote "Here is one in the middle src_sh[]{echo 1} of a line.
 Here is one at the end of a line. src_sh[]{echo 2}
 src_sh[]{echo 3} Here is one at the beginning of a line.
-Here is one that is also evaluated: src_sh[]{echo 4} {{{results(=0=)}}}")
+Here is one that is also evaluated: src_sh[]{echo 4} {{{results(=4=)}}}")
      nil t)
     (org-test-at-id "cd54fc88-1b6b-45b6-8511-4d8fa7fc8076"
       (org-narrow-to-subtree)