Org-mode code block setup and teardown

By Jeff Kreeftmeijer on 2021-08-04

Org-mode helps keep code samples up to date by actually running them during exporting. Instead of copying a command with its output from the terminal to the document, include only the command. Then, capture its actual output by running the command during the conversion to an output format like HTML.

For example, to show the output of the cat command, use a shell code block¹:

#+begin_src shell :exports both :results output
  cat hello.txt
#+end_src

Exporting this example to HTML produces a document with two code blocks in <pre> tags. The first shows the command from the input code block (cat hello.txt), and the second shows the results from running the command:

cat hello.txt

Setup and teardown

Use the :prologue and :epilogue header arguments to prepare for code blocks to be run, without printing the setup and teardown commands to the exported file. For example, if the file to be read doesn’t exist, create it right before executing the code in the code block, and remove it after²:

#+header: :exports both
#+header: :results output
#+header: :prologue "echo 'Hello, new file!' >> new.txt"
#+header: :epilogue "rm new.txt"
#+begin_src shell 
  cat new.txt
#+end_src

Like before, this produces the both the input source block, and the results block with the contents of the file:

cat new.txt

Results with errors

Showing that a command fails by printing its error message is sometimes useful to illustrate a point.

Org’s exporter captures the command’s standard output stream to print to the output block, but it doesn’t capture standard error. For example, if the passed file does not exist, cat returns an error. The exporter will not print the output block for the following example:

#+header: :exports both
#+header: :results output
#+begin_src shell
  cat ghost.txt
#+end_src

Since ghost.txt does not exist, the exporter outputs a warning message while exporting and does not include the results block in the HTML result:

cat ghost.txt

To remedy this, make sure the output sent to standard error is redirected to standard output and that the code sample returns a zero exit code. The former is achieved by calling exec 2>&1 as the prologue to redirect the command’s output to standard output. To satisfy the latter, the command’s exit code is replaced with a zero by calling : as the epilogue (which is a no-op that returns a zero exit code):

#+header: :exports both
#+header: :results output
#+header: :prologue exec 2>&1
#+header: :epilogue ":"
#+begin_src shell
 cat ghost.txt
#+end_src

This example produces both the input and output code block in the HTML export:

cat ghost.txt

The :exports and :results header arguments indicate the exporter should export both the code block and its results, and that it should print output of the code block as text results, respectively.
↩︎
This example uses #+header lines to split the header arguments over multiple lines, and is equivalent to placing all header arguments in the #+begin_src line:
```
#+begin_src shell :exports both :results output :prologue "echo 'Hello, World!' >> hello.txt" :epilogue "rm hello.txt"
  cat hello.txt
#+end_src
```
↩︎