[RFC] Let Org Mode's completion support all Babel header arguments

[RFC] Let Org Mode's completion support all Babel header arguments

[stardiviner]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA256


I found Org Mode's completion (from ~completion-at-point-functions~ which is
provided by ~pcomplete-completions-at-point~) can complete in bellowing places
(the "|" represent cursor point):

#+begin_src pyt|
#+end_src

#+begin_src python :ses|
#+end_src

#+begin_src C :resu|
#+end_src

#+begin_src R :fil|
#+end_src

#+begin_src sh :eva| :expo| :cac| :sheb| :tang| :comm| :no-ex|
#+end_src

But don't support completing some header arguments, like bellowing examples:

#+begin_src sh :wra| :pos :prolo| :epilo| :padli| :mkd| :sep| :file-|
#+end_src

We can see, all bellowing list of header arguments are standard header arguments of Babel.

- - var :: Pass arguments to code blocks.
- - results :: Specify the type of results and how they will be collected and handled.
- - file :: Specify a path for file output.
- - file-desc :: Specify a description for file results.
- - file-ext :: Specify an extension for file output.
- - output-dir :: Specify a directory to write file output to.
- - dir :: Specify the default (possibly remote) directory for code block execution.
- - exports :: Export code and/or results.
- - tangle :: Toggle tangling and specify file name.
- - mkdirp :: Toggle creation of parent directories of target files during tangling.
- - comments :: Toggle insertion of comments in tangled code files.
- - padline :: Control insertion of padding lines in tangled code files.
- - no-expand :: Turn off variable assignment and noweb expansion during tangling.
- - session :: Preserve the state of code evaluation.
- - noweb :: Toggle expansion of noweb references.
- - noweb-ref :: Specify block's noweb reference resolution target.
- - noweb-sep :: String used to separate noweb references.
- - cache :: Avoid re-evaluating unchanged code blocks by a src block content hash.
- - sep :: Delimiter for writing tabular results outside Org.
- - hlines :: Handle horizontal lines in tables.
- - colnames :: Handle column names in tables.
- - rownames :: Handle row names in tables.
- - shebang :: Make tangled files executable.
- - tangle-mode :: Set permission of tangled files.
- - eval :: Limit evaluation of specific code blocks.
- - wrap :: Mark source block evaluation results.
- - post :: Post processing of code block results.
- - prologue :: Text to prepend to code block body.
- - epilogue :: Text to append to code block body.

There are some header arguments are special to Babel language. Like

#+begin_src emacs-lisp :lexical
#+end_src

#+begin_src sh :stdin :cmdline :separator
#+end_src

#+begin_src clojure :show-process :alias
#+end_src

#+begin_src scheme :scheme
#+end_src

#+begin_src python :prefix
#+end_src

#+begin_src R :colnames
#+end_src

#+begin_src sqlite :db
#+end_src

#+begin_src sql :engine :dbconnection :dbhost :dbuser :dbbase :columes :cmdline
#+end_src

#+begin_src C :libs :includes :defines :flags :cmdline
#+end_src

#+begin_src C++ :namespaces
#+end_src

#+begin_src java :classname :cmdargs :cmdline
#+end_src

And there some extra Org Babel extensions might use some new header arguments keywords.

*Conclusion*

So I think Org Mode need an union API to manage those keywords. WDYT?

- -- 
[ stardiviner ]
       I try to make every word tell the meaning that I want to express.

       Blog: https://stardiviner.github.io/
       IRC(freenode): stardiviner, Matrix: stardiviner
       GPG: F09F650D7D674819892591401B5DF1C95AE89AC3
      
-----BEGIN PGP SIGNATURE-----

iQFIBAEBCAAyFiEE8J9lDX1nSBmJJZFAG13xyVromsMFAl62XNUUHG51bWJjaGls
ZEBnbWFpbC5jb20ACgkQG13xyVromsOxLAgAoAgXwRDspbE788Vt5FeZ/0INywZA
FH2RWlwxeENoBMkS9CmZ3/vEXq/C6SXs+OK7Hb9DxR00p+0wJJeDlbso+sL0/cPq
kgQCRgO4rIpBXHgP/vso6Ky8b/lpNRJmHtsdzG3Ymp5tTr2FXBrPYMHIbC7QgL/9
IOEs74bl3n8KIpo+Yy3uTq2ONg7x89uP4V7EodPvC4aRLfX5k/qytA9l2/C/0cgL
mIbeSwrjPFMBeH5eeCgIlP11ZT54U/kaBdegXojgsfA9KFNbcmY6YnZf7LYO4CnN
wZkCLJxs88BoQIC5rDSLg6fxXLKda1eFYOwHYqeqsVIWAJF4hvj69CrtOg==
=IwCf
-----END PGP SIGNATURE-----

Re: [RFC] Let Org Mode's completion support all Babel header arguments

[Nicolas Goaziou]

Hello,

stardiviner <numbchild@gmail.com> writes:

> I found Org Mode's completion (from ~completion-at-point-functions~ which is
> provided by ~pcomplete-completions-at-point~) can complete in bellowing places
> (the "|" represent cursor point):

[...]

> So I think Org Mode need an union API to manage those keywords. WDYT?

pcomplete certainly needs some love.

There is already `org-babel-common-header-args-w-values' and
`org-babel-header-args:LANG'. You may want to look into
`org-lint-wrong-header-value' to check how they are used.

Regards,

-- 
Nicolas Goaziou

Re: [RFC] Let Org Mode's completion support all Babel header arguments

[stardiviner]

[-- Attachment #1.1: Type: text/plain, Size: 1206 bytes --]


Nicolas Goaziou <mail@nicolasgoaziou.fr> writes:

> Hello,
>
> stardiviner <numbchild@gmail.com> writes:
>
>> I found Org Mode's completion (from ~completion-at-point-functions~ which is
>> provided by ~pcomplete-completions-at-point~) can complete in bellowing places
>> (the "|" represent cursor point):
>
> [...]
>
>> So I think Org Mode need an union API to manage those keywords. WDYT?
>
> pcomplete certainly needs some love.
>
> There is already `org-babel-common-header-args-w-values' and
> `org-babel-header-args:LANG'. You may want to look into
> `org-lint-wrong-header-value' to check how they are used.
>
> Regards,

I found library "org-pcomplete.el" and check it out, I combined the header
arguments retrieve mechanism from command ~org-babel-insert-header-arg~. Put it
into ~pcomplete/org-mode/block-option/src~. Not org-pcomplete.el on Babel header
arguments works perfect.

I attached the patch.

-- 
[ stardiviner ]
       I try to make every word tell the meaning that I want to express.

       Blog: https://stardiviner.github.io/
       IRC(freenode): stardiviner, Matrix: stardiviner
       GPG: F09F650D7D674819892591401B5DF1C95AE89AC3
      

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #1.2: 0001-org-pcomplete.el-improve-header-arguments-completion.patch --]
[-- Type: text/x-patch, Size: 1607 bytes --]

From 540f79db180aca95b0e202230c85e592b4fc579c Mon Sep 17 00:00:00 2001
From: stardiviner <numbchild@gmail.com>
Date: Tue, 12 May 2020 21:44:04 +0800
Subject: [PATCH] org-pcomplete.el: improve header arguments completion

* lisp/org-pcomplete.el (pcomplete/org-mode/block-option/src): Make it
complete real all available header arguments like command
`org-babel-insert-header-arg'.
---
 lisp/org-pcomplete.el | 15 ++++++++++-----
 1 file changed, 10 insertions(+), 5 deletions(-)

diff --git a/lisp/org-pcomplete.el b/lisp/org-pcomplete.el
index 28b40fadd..d9c301bd0 100644
--- a/lisp/org-pcomplete.el
+++ b/lisp/org-pcomplete.el
@@ -418,11 +418,16 @@ (defun pcomplete/org-mode/block-option/src ()
 				    (symbol-plist
 				     'org-babel-load-languages)
 				    'custom-type)))))))
-  (while (pcomplete-here
-	  '("-n" "-r" "-l"
-	    ":cache" ":colnames" ":comments" ":dir" ":eval" ":exports"
-	    ":file" ":hlines" ":no-expand" ":noweb" ":results" ":rownames"
-	    ":session" ":shebang" ":tangle" ":tangle-mode" ":var"))))
+  (let* ((info (org-babel-get-src-block-info 'light))
+	 (lang (car info))
+	 (lang-headers (intern (concat "org-babel-header-args:" lang)))
+	 (headers (org-babel-combine-header-arg-lists
+		   org-babel-common-header-args-w-values
+		   (when (boundp lang-headers) (eval lang-headers t)))))
+    (while (pcomplete-here
+	    (mapcar
+             (lambda (arg) (concat ":" (symbol-name (car arg))))
+	     headers)))))
 
 (defun pcomplete/org-mode/block-option/clocktable ()
   "Complete keywords in a clocktable line."
-- 
2.26.2


[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 515 bytes --]

Re: [RFC] Let Org Mode's completion support all Babel header arguments

[Nicolas Goaziou]

Hello,

stardiviner <numbchild@gmail.com> writes:

> Subject: [PATCH] org-pcomplete.el: improve header arguments completion

Thank you. Some comments follow.

> -  (while (pcomplete-here
> -	  '("-n" "-r" "-l"
> -	    ":cache" ":colnames" ":comments" ":dir" ":eval" ":exports"
> -	    ":file" ":hlines" ":no-expand" ":noweb" ":results" ":rownames"
> -	    ":session" ":shebang" ":tangle" ":tangle-mode" ":var"))))
> +  (let* ((info (org-babel-get-src-block-info 'light))
> +	 (lang (car info))
> +	 (lang-headers (intern (concat "org-babel-header-args:" lang)))
> +	 (headers (org-babel-combine-header-arg-lists
> +		   org-babel-common-header-args-w-values
> +		   (when (boundp lang-headers) (eval lang-headers t)))))

(when ...)  -> (and (bounp lang-headers)) (symbol-value lang-headers)

> +    (while (pcomplete-here
> +	    (mapcar
> +             (lambda (arg) (concat ":" (symbol-name (car arg))))

(concat ...) -> (format ":%s" (car arg))

> +	     headers)))))

It looks like you dropped the switches "-n", "-r", "-l".

Also, could you add a few tests in "test-org-pcomplete.el"?

Regards,

-- 
Nicolas Goaziou

Re: [RFC] Let Org Mode's completion support all Babel header arguments

[stardiviner]

[-- Attachment #1.1: Type: text/plain, Size: 1667 bytes --]


Nicolas Goaziou <mail@nicolasgoaziou.fr> writes:

> Hello,
>
> stardiviner <numbchild@gmail.com> writes:
>
>> Subject: [PATCH] org-pcomplete.el: improve header arguments completion
>
> Thank you. Some comments follow.
>
>> -  (while (pcomplete-here
>> -	  '("-n" "-r" "-l"
>> -	    ":cache" ":colnames" ":comments" ":dir" ":eval" ":exports"
>> -	    ":file" ":hlines" ":no-expand" ":noweb" ":results" ":rownames"
>> -	    ":session" ":shebang" ":tangle" ":tangle-mode" ":var"))))
>> +  (let* ((info (org-babel-get-src-block-info 'light))
>> +	 (lang (car info))
>> +	 (lang-headers (intern (concat "org-babel-header-args:" lang)))
>> +	 (headers (org-babel-combine-header-arg-lists
>> +		   org-babel-common-header-args-w-values
>> +		   (when (boundp lang-headers) (eval lang-headers t)))))
>
> (when ...)  -> (and (bounp lang-headers)) (symbol-value lang-headers)

Done.

>
>> +    (while (pcomplete-here
>> +	    (mapcar
>> +             (lambda (arg) (concat ":" (symbol-name (car arg))))
>
> (concat ...) -> (format ":%s" (car arg))

Fixed

>
>> +	     headers)))))
>
> It looks like you dropped the switches "-n", "-r", "-l".
>
> Also, could you add a few tests in "test-org-pcomplete.el"?

Add a test for Babel src block languages and header arguments.

I'm wandering how to complete header argument values? Do you have any hints?

>
> Regards,


-- 
[ stardiviner ]
       I try to make every word tell the meaning that I want to express.

       Blog: https://stardiviner.github.io/
       IRC(freenode): stardiviner, Matrix: stardiviner
       GPG: F09F650D7D674819892591401B5DF1C95AE89AC3
      

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #1.2: 0001-org-pcomplete.el-improve-header-arguments-completion.patch --]
[-- Type: text/x-patch, Size: 2583 bytes --]

From 70232e4b1798725d81edab1dfd7984d41d120e0e Mon Sep 17 00:00:00 2001
From: stardiviner <numbchild@gmail.com>
Date: Tue, 12 May 2020 21:44:04 +0800
Subject: [PATCH] org-pcomplete.el: improve header arguments completion

* lisp/org-pcomplete.el (pcomplete/org-mode/block-option/src): Make it
complete real all available header arguments like command
`org-babel-insert-header-arg'.
---
 lisp/org-pcomplete.el              | 16 +++++++++++-----
 testing/lisp/test-org-pcomplete.el | 17 +++++++++++++++++
 2 files changed, 28 insertions(+), 5 deletions(-)

diff --git a/lisp/org-pcomplete.el b/lisp/org-pcomplete.el
index 28b40fadd..65651512a 100644
--- a/lisp/org-pcomplete.el
+++ b/lisp/org-pcomplete.el
@@ -418,11 +418,17 @@ (defun pcomplete/org-mode/block-option/src ()
 				    (symbol-plist
 				     'org-babel-load-languages)
 				    'custom-type)))))))
-  (while (pcomplete-here
-	  '("-n" "-r" "-l"
-	    ":cache" ":colnames" ":comments" ":dir" ":eval" ":exports"
-	    ":file" ":hlines" ":no-expand" ":noweb" ":results" ":rownames"
-	    ":session" ":shebang" ":tangle" ":tangle-mode" ":var"))))
+  (let* ((info (org-babel-get-src-block-info 'light))
+	 (lang (car info))
+	 (lang-headers (intern (concat "org-babel-header-args:" lang)))
+	 (headers (org-babel-combine-header-arg-lists
+		   org-babel-common-header-args-w-values
+		   (and (boundp lang-headers) (eval lang-headers t)))))
+    (while (pcomplete-here
+	    (append (mapcar
+		     (lambda (arg) (format ":%s" (symbol-name (car arg))))
+		     headers)
+		    '("-n" "-r" "-l"))))))
 
 (defun pcomplete/org-mode/block-option/clocktable ()
   "Complete keywords in a clocktable line."
diff --git a/testing/lisp/test-org-pcomplete.el b/testing/lisp/test-org-pcomplete.el
index e6b0e8a7e..4a7184100 100644
--- a/testing/lisp/test-org-pcomplete.el
+++ b/testing/lisp/test-org-pcomplete.el
@@ -75,6 +75,23 @@ (ert-deftest test-org-pcomplete/keyword ()
       (buffer-string))
     t)))
 
+(ert-deftest test-org-pcomplete/src-block ()
+  "Test Babel src block header arguments completion."
+  (should
+   (string-prefix-p
+    "#+begin_src emacs-lisp"
+    (org-test-with-temp-text "#+begin_src emac<point>"
+      (pcomplete)
+      (buffer-string))
+    t))
+  (should
+   (string-prefix-p
+    "#+begin_src emacs-lisp :session"
+    (org-test-with-temp-text "#+begin_src emacs-lisp :sess<point>"
+      (pcomplete)
+      (buffer-string))
+    t)))
+
 (ert-deftest test-org-pcomplete/link ()
   "Test link completion"
   (should
-- 
2.26.2


[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 515 bytes --]

Re: [RFC] Let Org Mode's completion support all Babel header arguments

[Nicolas Goaziou]

Hello,

stardiviner <numbchild@gmail.com> writes:

> Add a test for Babel src block languages and header arguments.

Thank you.

> I'm wandering how to complete header argument values? Do you have any
> hints?

You can use, again, `org-babel-common-header-args-w-values' for some
parameters. However, most of them specify `:any', which means the value
can be anything, and, therefore, cannot be completed.

You may want to have a look at `org-lint-wrong-header-value' for an
example on how to treat

> +(ert-deftest test-org-pcomplete/src-block ()
> +  "Test Babel src block header arguments completion."

"source block" instead of "src block".

> +  (should
> +   (string-prefix-p
> +    "#+begin_src emacs-lisp"
> +    (org-test-with-temp-text "#+begin_src emac<point>"
> +      (pcomplete)
> +      (buffer-string))
> +    t))

You can remove the t

> +  (should
> +   (string-prefix-p
> +    "#+begin_src emacs-lisp :session"
> +    (org-test-with-temp-text "#+begin_src emacs-lisp :sess<point>"
> +      (pcomplete)
> +      (buffer-string))
> +    t)))

Ditto.

Regards,

-- 
Nicolas Goaziou

Re: [RFC] Let Org Mode's completion support all Babel header arguments

[stardiviner]

[-- Attachment #1.1: Type: text/plain, Size: 1630 bytes --]


Nicolas Goaziou <mail@nicolasgoaziou.fr> writes:

> Hello,
>
> stardiviner <numbchild@gmail.com> writes:
>
>> Add a test for Babel src block languages and header arguments.
>
> Thank you.

Glad this test is simple to write and passed.

>
>> I'm wandering how to complete header argument values? Do you have any
>> hints?
>
> You can use, again, `org-babel-common-header-args-w-values' for some
> parameters. However, most of them specify `:any', which means the value
> can be anything, and, therefore, cannot be completed.

I see. Thanks.

>
> You may want to have a look at `org-lint-wrong-header-value' for an
> example on how to treat
>
>> +(ert-deftest test-org-pcomplete/src-block ()
>> +  "Test Babel src block header arguments completion."
>
> "source block" instead of "src block".

Fixed

>
>> +  (should
>> +   (string-prefix-p
>> +    "#+begin_src emacs-lisp"
>> +    (org-test-with-temp-text "#+begin_src emac<point>"
>> +      (pcomplete)
>> +      (buffer-string))
>> +    t))
>
> You can remove the t

Done.

>
>> +  (should
>> +   (string-prefix-p
>> +    "#+begin_src emacs-lisp :session"
>> +    (org-test-with-temp-text "#+begin_src emacs-lisp :sess<point>"
>> +      (pcomplete)
>> +      (buffer-string))
>> +    t)))
>
> Ditto.

Ditto.

I attached the new patch.

>
> Regards,


-- 
[ stardiviner ]
       I try to make every word tell the meaning that I want to express.

       Blog: https://stardiviner.github.io/
       IRC(freenode): stardiviner, Matrix: stardiviner
       GPG: F09F650D7D674819892591401B5DF1C95AE89AC3
      

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #1.2: 0001-org-pcomplete.el-improve-header-arguments-completion.patch --]
[-- Type: text/x-patch, Size: 2707 bytes --]

From 5b0e7bb971d1459bc1247ce14bec49d897aa2fa5 Mon Sep 17 00:00:00 2001
From: stardiviner <numbchild@gmail.com>
Date: Tue, 12 May 2020 21:44:04 +0800
Subject: [PATCH] org-pcomplete.el: improve header arguments completion

* lisp/org-pcomplete.el (pcomplete/org-mode/block-option/src): Make it
complete real all available header arguments like command
`org-babel-insert-header-arg'.

* testing/lisp/test-org-pcomplete.el (test-org-pcomplete/src-block):
Test Babel source block language and header arguments completing.
---
 lisp/org-pcomplete.el              | 16 +++++++++++-----
 testing/lisp/test-org-pcomplete.el | 15 +++++++++++++++
 2 files changed, 26 insertions(+), 5 deletions(-)

diff --git a/lisp/org-pcomplete.el b/lisp/org-pcomplete.el
index 28b40fadd..65651512a 100644
--- a/lisp/org-pcomplete.el
+++ b/lisp/org-pcomplete.el
@@ -418,11 +418,17 @@ (defun pcomplete/org-mode/block-option/src ()
 				    (symbol-plist
 				     'org-babel-load-languages)
 				    'custom-type)))))))
-  (while (pcomplete-here
-	  '("-n" "-r" "-l"
-	    ":cache" ":colnames" ":comments" ":dir" ":eval" ":exports"
-	    ":file" ":hlines" ":no-expand" ":noweb" ":results" ":rownames"
-	    ":session" ":shebang" ":tangle" ":tangle-mode" ":var"))))
+  (let* ((info (org-babel-get-src-block-info 'light))
+	 (lang (car info))
+	 (lang-headers (intern (concat "org-babel-header-args:" lang)))
+	 (headers (org-babel-combine-header-arg-lists
+		   org-babel-common-header-args-w-values
+		   (and (boundp lang-headers) (eval lang-headers t)))))
+    (while (pcomplete-here
+	    (append (mapcar
+		     (lambda (arg) (format ":%s" (symbol-name (car arg))))
+		     headers)
+		    '("-n" "-r" "-l"))))))
 
 (defun pcomplete/org-mode/block-option/clocktable ()
   "Complete keywords in a clocktable line."
diff --git a/testing/lisp/test-org-pcomplete.el b/testing/lisp/test-org-pcomplete.el
index e6b0e8a7e..2de4f4934 100644
--- a/testing/lisp/test-org-pcomplete.el
+++ b/testing/lisp/test-org-pcomplete.el
@@ -75,6 +75,21 @@ (ert-deftest test-org-pcomplete/keyword ()
       (buffer-string))
     t)))
 
+(ert-deftest test-org-pcomplete/src-block ()
+  "Test Babel source block header arguments completion."
+  (should
+   (string-prefix-p
+    "#+begin_src emacs-lisp"
+    (org-test-with-temp-text "#+begin_src emac<point>"
+      (pcomplete)
+      (buffer-string))))
+  (should
+   (string-prefix-p
+    "#+begin_src emacs-lisp :session"
+    (org-test-with-temp-text "#+begin_src emacs-lisp :sess<point>"
+      (pcomplete)
+      (buffer-string)))))
+
 (ert-deftest test-org-pcomplete/link ()
   "Test link completion"
   (should
-- 
2.26.2


[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 515 bytes --]

Re: [RFC] Let Org Mode's completion support all Babel header arguments

[Nicolas Goaziou]

Hello,

stardiviner <numbchild@gmail.com> writes:

> I attached the new patch.

Applied. Thank you.

Regards,

-- 
Nicolas Goaziou