Browse Source

lisp/ob-core.el: Allow passing empty vector to :file-desc to omit description

* doc/ (Type): Document empty vector argument for
* etc/ORG-NEWS (New argument for ~file-desc~ babel header): Add entry
to NEWS.
* lisp/ob-core.el (org-babel--file-desc): Add new function to evaluate
file description value.
(org-babel-execute-src-block): Correctly evaluate file description
when executing src block.
(org-babel-insert-result): Correctly evaluate file description value
when inserting the result of src block execution into the buffer.
* testing/lisp/test-ob.el (test-ob/file-desc-header-argument): Add
test case for new behavior.
Matt Huszagh 3 months ago
4 changed files with 46 additions and 9 deletions
  1. 5 3
  2. 11 0
  3. 11 5
  4. 19 1

+ 5 - 3

@@ -17482,10 +17482,12 @@ default behavior is to automatically determine the result type.
   #+cindex: @samp{file-desc}, header argument
-  The =file-desc= header argument defines the description (see
-  [[*Link Format]]) for the link.  If =file-desc= is present but has no value,
+  The =file-desc= header argument defines the description (see [[*Link
+  Format]]) for the link.  If =file-desc= is present but has no value,
   the =file= value is used as the link description.  When this
-  argument is not present, the description is omitted.
+  argument is not present, the description is omitted.  If you want to
+  provide the =file-desc= argument but omit the description, you can
+  provide it with an empty vector (i.e., :file-desc []).
   #+cindex: @samp{sep}, header argument
   By default, Org assumes that a table written to a file has

+ 11 - 0

@@ -24,6 +24,17 @@ Earlier, IDs generated using =ts= method had a hard-coded format (i.e. =20200923
 The new option allows user to customise the format.
 Defaults are unchanged.
+*** New argument for ~file-desc~ babel header
+It is now possible to provide the =file-desc= header argument for a
+babel source block but omit the description by passing an empty vector
+as an argument (i.e., :file-desc []).  This can be useful because
+providing =file-desc= without an argument results in the result of
+=file= being used in the description.  Previously, the only way to
+omit a file description was to omit the header argument entirely,
+which made it difficult/impossible to provide a default value for
 ** New features
 *** =ob-python= improvements to =:return= header argument 

+ 11 - 5

@@ -646,6 +646,14 @@ a list with the following pattern:
        (org-src-coderef-regexp coderef) "" expand nil nil 1))))
+(defun org-babel--file-desc (params result)
+  "Retrieve file description."
+  (pcase (assq :file-desc params)
+    (`nil nil)
+    (`(:file-desc) result)
+    (`(:file-desc . ,(and (pred stringp) val)) val)
+    (`(:file-desc . []) nil)))
 (defun org-babel-execute-src-block (&optional arg info params)
   "Execute the current source code block.
@@ -749,8 +757,7 @@ block."
 		    (let ((*this* (if (not file) result
-				     (let ((desc (assq :file-desc params)))
-				       (and desc (or (cdr desc) result)))))))
+				     (org-babel--file-desc params result)))))
 		      (setq result (org-babel-ref-resolve post))
 		      (when file
 			(setq result-params (remove "file" result-params))))))
@@ -2257,9 +2264,8 @@ INFO may provide the values of these header arguments (in the
 	 (setq result (org-no-properties result))
 	 (when (member "file" result-params)
 	   (setq result (org-babel-result-to-file
-			 result (when (assq :file-desc (nth 2 info))
-				  (or (cdr (assq :file-desc (nth 2 info)))
-				      result))))))
+			 result
+			 (org-babel--file-desc (nth 2 info) result)))))
 	((listp result))
 	(t (setq result (format "%S" result))))
   (if (and result-params (member "silent" result-params))

+ 19 - 1

@@ -1084,7 +1084,25 @@ trying to find the :END: marker."
     (goto-char (point-min))
     (should (search-forward "[[file:foo][bar]]" nil t))
-    (should (search-forward "[[file:foo][foo]]" nil t))))
+    (should (search-forward "[[file:foo][foo]]" nil t)))
+  (should (string-match-p
+           (regexp-quote "[[file:foo]]")
+           (org-test-with-temp-text "
+#+begin_src emacs-lisp :results file :file-desc []
+  \"foo\"
+             (org-babel-next-src-block)
+             (org-babel-execute-src-block)
+             (buffer-substring-no-properties (point-min) (point-max)))))
+  (should (string-match-p
+           (regexp-quote "[[file:foo][foo]]")
+           (org-test-with-temp-text "
+#+begin_src emacs-lisp :results file :file-desc
+  \"foo\"
+             (org-babel-next-src-block)
+             (org-babel-execute-src-block)
+             (buffer-substring-no-properties (point-min) (point-max))))))
 (ert-deftest test-ob/result-file-link-type-header-argument ()
   "Ensure that the result is a link to a file.