emacs-orgmode@gnu.org archives
 help / color / mirror / code / Atom feed
* [feature request] The :pre header argument
@ 2021-02-18 21:48 Rodrigo Morales
  2021-02-19 13:33 ` Rodrigo Morales
  0 siblings, 1 reply; 4+ messages in thread
From: Rodrigo Morales @ 2021-02-18 21:48 UTC (permalink / raw)
  To: emacs-orgmode


This message contains my thoughts on a feature request which I think
would be useful: The =:pre= header argument, it would be used to
execute a code block before the code block at point is executed. It
would be similar to the behavior of the =:post= header argument.

Here's a simple example that shows how =:pre= could be used

#+NAME: clean-path-experiments
#+begin_src dash
if [ ! -z "$my__experiments" ] && [ -d "$my__experiments" ]; then
  find ~/e -mindepth 1 -maxdepth 1 -exec rm -rf {} +
fi
#+end_src

#+NAME: tree-command
#+begin_src dash
tree -a --noreport
#+end_src

#+NAME: create-dir-for-minimal-reproducible-example
#+HEADER: :pre clean-path-experiments()
#+HEADER: :post tree-command()
#+begin_src python
import os

[os.makedirs(_) for _ in ["a/foo", "a/bar", "b"]]
[os.mknod(_) for _ in ["a/1.txt", "a/2.txt", "a/foo/b.txt", "a/bar/b.txt", "b/b.txt"]]
#+end_src

#+RESULTS: create-dir-for-minimal-reproducible-example
#+begin_example
.
├── a
│   ├── 1.txt
│   ├── 2.txt
│   ├── bar
│   │   └── b.txt
│   └── foo
│       └── b.txt
└── b
    └── b.txt
#+end_example

I think that such header argument would be useful because of two
main reasons:

* It would improve readability of code blocks by explicitly expressing dependency

By having a header argument for the sole purpose of expressing
dependencies between code blocks, the readability of header arguments
would be improved. Recall that it is currently possible to express
such dependency by calling a code block through a =:var <<name>>=
header argument but I think that =:var= header argument must only be
used for defining variables (be it from results obtained from
different code blocks or literals).

The first code block shown below show the differences between using
=:var= and =:pre= for the same scenario. =first-code-block= uses the
=:var= header argument while the =second-code-block= uses the =:pre=
header argument.

#+NAME: first-code-block
#+begin_src org
For our experimentation, let's start with an empty directory and let's
execute the first step.

,#+NAME: first-step
,#+HEADER: :results silent
,#+HEADER: :var e=clean-path-experiments
,#+begin_src dash
touch first-step.txt
,#+end_src

We know execute the second step.

,#+NAME: second-step
,#+HEADER: :results silent
,#+HEADER: :var e=first-step
,#+begin_src dash
touch second-step.txt
,#+end_src

Finally, we execute the third step.

,#+NAME: third-step
,#+HEADER: :results silent
,#+HEADER: :var e=second-step
,#+begin_src dash
touch third-step.txt
,#+end_src
#+end_src

#+NAME: second-code-block
#+begin_src org
For our experimentation, let's start with an empty directory and let's
execute the first step.

,#+NAME: first-step
,#+HEADER: :results silent
,#+HEADER: :pre clean-path-experiments()
,#+begin_src dash
touch first-step.txt
,#+end_src

We know execute the second step.

,#+NAME: second-step
,#+HEADER: :results silent
,#+HEADER: :pre first-step()
,#+begin_src dash
touch second-step.txt
,#+end_src

Finally, we execute the third step.

,#+NAME: third-step
,#+HEADER: :results silent
,#+HEADER: :pre second-step()
,#+begin_src dash
touch third-step.txt
,#+end_src
#+end_src

In my opinion, the second code block looks more readable than the
first one.

* it would add importance to the =:post= header argument

The =:post= header argument can be used in Org Mode 9.3 to execute a
given code block after the code block at point is executed; having a
header argument that does the opposite of the =:post= header argument
would give relevance to the =:post= header argument.

-- 
Greetings,
Rodrigo Morales.

IRC: rdrg109 (freenode)


^ permalink raw reply	[flat|nested] 4+ messages in thread

* Re: [feature request] The :pre header argument
  2021-02-18 21:48 [feature request] The :pre header argument Rodrigo Morales
@ 2021-02-19 13:33 ` Rodrigo Morales
  2021-02-20  1:50   ` Rodrigo Morales
  0 siblings, 1 reply; 4+ messages in thread
From: Rodrigo Morales @ 2021-02-19 13:33 UTC (permalink / raw)
  To: org-mode-email

[-- Attachment #1: Type: text/plain, Size: 4283 bytes --]

You can read this message with proper formatting here (
https://codeberg.org/rdrg109/gists/src/branch/main/the-pre-header-argument.org
).

On Thu, 18 Feb 2021 at 16:52, Rodrigo Morales <moralesrodrigo1100@gmail.com>
wrote:

>
> This message contains my thoughts on a feature request which I think
> would be useful: The =:pre= header argument, it would be used to
> execute a code block before the code block at point is executed. It
> would be similar to the behavior of the =:post= header argument.
>
> Here's a simple example that shows how =:pre= could be used
>
> #+NAME: clean-path-experiments
> #+begin_src dash
> if [ ! -z "$my__experiments" ] && [ -d "$my__experiments" ]; then
>   find ~/e -mindepth 1 -maxdepth 1 -exec rm -rf {} +
> fi
> #+end_src
>
> #+NAME: tree-command
> #+begin_src dash
> tree -a --noreport
> #+end_src
>
> #+NAME: create-dir-for-minimal-reproducible-example
> #+HEADER: :pre clean-path-experiments()
> #+HEADER: :post tree-command()
> #+begin_src python
> import os
>
> [os.makedirs(_) for _ in ["a/foo", "a/bar", "b"]]
> [os.mknod(_) for _ in ["a/1.txt", "a/2.txt", "a/foo/b.txt", "a/bar/b.txt",
> "b/b.txt"]]
> #+end_src
>
> #+RESULTS: create-dir-for-minimal-reproducible-example
> #+begin_example
> .
> ├── a
> │   ├── 1.txt
> │   ├── 2.txt
> │   ├── bar
> │   │   └── b.txt
> │   └── foo
> │       └── b.txt
> └── b
>     └── b.txt
> #+end_example
>
> I think that such header argument would be useful because of two
> main reasons:
>
> * It would improve readability of code blocks by explicitly expressing
> dependency
>
> By having a header argument for the sole purpose of expressing
> dependencies between code blocks, the readability of header arguments
> would be improved. Recall that it is currently possible to express
> such dependency by calling a code block through a =:var <<name>>=
> header argument but I think that =:var= header argument must only be
> used for defining variables (be it from results obtained from
> different code blocks or literals).
>
> The first code block shown below show the differences between using
> =:var= and =:pre= for the same scenario. =first-code-block= uses the
> =:var= header argument while the =second-code-block= uses the =:pre=
> header argument.
>
> #+NAME: first-code-block
> #+begin_src org
> For our experimentation, let's start with an empty directory and let's
> execute the first step.
>
> ,#+NAME: first-step
> ,#+HEADER: :results silent
> ,#+HEADER: :var e=clean-path-experiments
> ,#+begin_src dash
> touch first-step.txt
> ,#+end_src
>
> We know execute the second step.
>
> ,#+NAME: second-step
> ,#+HEADER: :results silent
> ,#+HEADER: :var e=first-step
> ,#+begin_src dash
> touch second-step.txt
> ,#+end_src
>
> Finally, we execute the third step.
>
> ,#+NAME: third-step
> ,#+HEADER: :results silent
> ,#+HEADER: :var e=second-step
> ,#+begin_src dash
> touch third-step.txt
> ,#+end_src
> #+end_src
>
> #+NAME: second-code-block
> #+begin_src org
> For our experimentation, let's start with an empty directory and let's
> execute the first step.
>
> ,#+NAME: first-step
> ,#+HEADER: :results silent
> ,#+HEADER: :pre clean-path-experiments()
> ,#+begin_src dash
> touch first-step.txt
> ,#+end_src
>
> We know execute the second step.
>
> ,#+NAME: second-step
> ,#+HEADER: :results silent
> ,#+HEADER: :pre first-step()
> ,#+begin_src dash
> touch second-step.txt
> ,#+end_src
>
> Finally, we execute the third step.
>
> ,#+NAME: third-step
> ,#+HEADER: :results silent
> ,#+HEADER: :pre second-step()
> ,#+begin_src dash
> touch third-step.txt
> ,#+end_src
> #+end_src
>
> In my opinion, the second code block looks more readable than the
> first one.
>
> * it would add importance to the =:post= header argument
>
> The =:post= header argument can be used in Org Mode 9.3 to execute a
> given code block after the code block at point is executed; having a
> header argument that does the opposite of the =:post= header argument
> would give relevance to the =:post= header argument.
>
> --
> Greetings,
> Rodrigo Morales.
>
> IRC: rdrg109 (freenode)
>

[-- Attachment #2: Type: text/html, Size: 5115 bytes --]

^ permalink raw reply	[flat|nested] 4+ messages in thread

* Re: [feature request] The :pre header argument
  2021-02-19 13:33 ` Rodrigo Morales
@ 2021-02-20  1:50   ` Rodrigo Morales
  2021-04-05  4:49     ` Ihor Radchenko
  0 siblings, 1 reply; 4+ messages in thread
From: Rodrigo Morales @ 2021-02-20  1:50 UTC (permalink / raw)
  To: org-mode-email

[-- Attachment #1: Type: text/plain, Size: 4775 bytes --]

I've provided more relevant information on this feature request [[
https://codeberg.org/rdrg109/gists/src/branch/main/feature-request-pre-header-argument.org][here]].
Please consider reading that instead of the first message on this thread.

On Fri, 19 Feb 2021 at 08:33, Rodrigo Morales <moralesrodrigo1100@gmail.com>
wrote:

> You can read this message with proper formatting here (
> https://codeberg.org/rdrg109/gists/src/branch/main/the-pre-header-argument.org
> ).
>
> On Thu, 18 Feb 2021 at 16:52, Rodrigo Morales <
> moralesrodrigo1100@gmail.com> wrote:
>
>>
>> This message contains my thoughts on a feature request which I think
>> would be useful: The =:pre= header argument, it would be used to
>> execute a code block before the code block at point is executed. It
>> would be similar to the behavior of the =:post= header argument.
>>
>> Here's a simple example that shows how =:pre= could be used
>>
>> #+NAME: clean-path-experiments
>> #+begin_src dash
>> if [ ! -z "$my__experiments" ] && [ -d "$my__experiments" ]; then
>>   find ~/e -mindepth 1 -maxdepth 1 -exec rm -rf {} +
>> fi
>> #+end_src
>>
>> #+NAME: tree-command
>> #+begin_src dash
>> tree -a --noreport
>> #+end_src
>>
>> #+NAME: create-dir-for-minimal-reproducible-example
>> #+HEADER: :pre clean-path-experiments()
>> #+HEADER: :post tree-command()
>> #+begin_src python
>> import os
>>
>> [os.makedirs(_) for _ in ["a/foo", "a/bar", "b"]]
>> [os.mknod(_) for _ in ["a/1.txt", "a/2.txt", "a/foo/b.txt",
>> "a/bar/b.txt", "b/b.txt"]]
>> #+end_src
>>
>> #+RESULTS: create-dir-for-minimal-reproducible-example
>> #+begin_example
>> .
>> ├── a
>> │   ├── 1.txt
>> │   ├── 2.txt
>> │   ├── bar
>> │   │   └── b.txt
>> │   └── foo
>> │       └── b.txt
>> └── b
>>     └── b.txt
>> #+end_example
>>
>> I think that such header argument would be useful because of two
>> main reasons:
>>
>> * It would improve readability of code blocks by explicitly expressing
>> dependency
>>
>> By having a header argument for the sole purpose of expressing
>> dependencies between code blocks, the readability of header arguments
>> would be improved. Recall that it is currently possible to express
>> such dependency by calling a code block through a =:var <<name>>=
>> header argument but I think that =:var= header argument must only be
>> used for defining variables (be it from results obtained from
>> different code blocks or literals).
>>
>> The first code block shown below show the differences between using
>> =:var= and =:pre= for the same scenario. =first-code-block= uses the
>> =:var= header argument while the =second-code-block= uses the =:pre=
>> header argument.
>>
>> #+NAME: first-code-block
>> #+begin_src org
>> For our experimentation, let's start with an empty directory and let's
>> execute the first step.
>>
>> ,#+NAME: first-step
>> ,#+HEADER: :results silent
>> ,#+HEADER: :var e=clean-path-experiments
>> ,#+begin_src dash
>> touch first-step.txt
>> ,#+end_src
>>
>> We know execute the second step.
>>
>> ,#+NAME: second-step
>> ,#+HEADER: :results silent
>> ,#+HEADER: :var e=first-step
>> ,#+begin_src dash
>> touch second-step.txt
>> ,#+end_src
>>
>> Finally, we execute the third step.
>>
>> ,#+NAME: third-step
>> ,#+HEADER: :results silent
>> ,#+HEADER: :var e=second-step
>> ,#+begin_src dash
>> touch third-step.txt
>> ,#+end_src
>> #+end_src
>>
>> #+NAME: second-code-block
>> #+begin_src org
>> For our experimentation, let's start with an empty directory and let's
>> execute the first step.
>>
>> ,#+NAME: first-step
>> ,#+HEADER: :results silent
>> ,#+HEADER: :pre clean-path-experiments()
>> ,#+begin_src dash
>> touch first-step.txt
>> ,#+end_src
>>
>> We know execute the second step.
>>
>> ,#+NAME: second-step
>> ,#+HEADER: :results silent
>> ,#+HEADER: :pre first-step()
>> ,#+begin_src dash
>> touch second-step.txt
>> ,#+end_src
>>
>> Finally, we execute the third step.
>>
>> ,#+NAME: third-step
>> ,#+HEADER: :results silent
>> ,#+HEADER: :pre second-step()
>> ,#+begin_src dash
>> touch third-step.txt
>> ,#+end_src
>> #+end_src
>>
>> In my opinion, the second code block looks more readable than the
>> first one.
>>
>> * it would add importance to the =:post= header argument
>>
>> The =:post= header argument can be used in Org Mode 9.3 to execute a
>> given code block after the code block at point is executed; having a
>> header argument that does the opposite of the =:post= header argument
>> would give relevance to the =:post= header argument.
>>
>> --
>> Greetings,
>> Rodrigo Morales.
>>
>> IRC: rdrg109 (freenode)
>>
>

[-- Attachment #2: Type: text/html, Size: 5881 bytes --]

^ permalink raw reply	[flat|nested] 4+ messages in thread

* Re: [feature request] The :pre header argument
  2021-02-20  1:50   ` Rodrigo Morales
@ 2021-04-05  4:49     ` Ihor Radchenko
  0 siblings, 0 replies; 4+ messages in thread
From: Ihor Radchenko @ 2021-04-05  4:49 UTC (permalink / raw)
  To: Rodrigo Morales, org-mode-email

Hi,

Rodrigo Morales <moralesrodrigo1100@gmail.com> writes:

> I've provided more relevant information on this feature request [[
> https://codeberg.org/rdrg109/gists/src/branch/main/feature-request-pre-header-argument.org][here]].
> Please consider reading that instead of the first message on this thread.

I think the origin intention of the :post header argument is slightly
different from your use-case. It is intended to be used for
post-processing the results:

> The ‘post’ header argument is for post-processing results from block
> evaluation.  When ‘post’ has any value, Org binds the results to
> ‘*this*’ variable for easy passing to ‘var’ header argument
> specifications (see *note Environment of a Code Block::).  That makes
> results available to other code blocks, or even for direct Emacs Lisp
> code execution.

If you want to execute some arbitrary code before/after your code block,
it is probably more canonical to use noweb references. Using your
example:

#+begin_src emacs-lisp
# Cleanup first using experiments/clean-dir(): "<<experiments/clean-dir()>>"
# Create dir structure using
# minimal-reproducible-example/create-dir-structure:
# "<<minimal-reproducible-example/create-dir-structure()>>"
# Finally, execute `tree' using experiments/execute-tree:
(message "<<experiments/execute-tree()>>")
#+end_src

It will not produce spurious variable definitions.

Best,
Ihor





^ permalink raw reply	[flat|nested] 4+ messages in thread

end of thread, other threads:[~2021-04-05  4:45 UTC | newest]

Thread overview: 4+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2021-02-18 21:48 [feature request] The :pre header argument Rodrigo Morales
2021-02-19 13:33 ` Rodrigo Morales
2021-02-20  1:50   ` Rodrigo Morales
2021-04-05  4:49     ` Ihor Radchenko

Code repositories for project(s) associated with this public inbox

	https://git.savannah.gnu.org/cgit/emacs/org-mode.git

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).