Shell Code Blocks in Babel

:results {output, value}

• output returns stdout, default
• value returns exit code

Supported types: table, list, and file.

Examples:

Define the following 2D-array:

#+name: make_array
#+begin_src bash
declare -a array

m=4
n=3
for ((i=0; i<m; i++))
do
    for ((j=0; j<n; j++))
    do
        a[${i},${j}]=$RANDOM
    done
done
for ((i=0; i<m; i++))
do
    for ((j=0; j<n; j++))
    do
        echo -ne "${a[${i},${j}]}\t"
    done
    echo
done
#+end_src

When called with :results output table or :results table

#+RESULTS:
| 19323 | 14951 | 2805 |
| 19323 | 14951 | 2805 |
| 19323 | 14951 | 2805 |
| 19323 | 14951 | 2805 |

When called with :results output list or :results list

#+RESULTS:
- (29607 15726 14035)
- (29607 15726 14035)
- (29607 15726 14035)
- (29607 15726 14035)

When called with :results file :file my_output.txt, a file named "my_output.txt" is created which contains the output. The results contains a link to the file.

#+RESULTS:
file:my_output.txt

#+begin_src sh :results output
  cat my_output.txt
#+end_src

#+RESULTS:
: 1526	5064	6484
: 1526	5064	6484
: 1526	5064	6484
: 1526	5064	6484

:dir <path>

Use the :dir header to specify the default directory to use during execution.

TIP Use :dir to execute commands on a remote server. See Choosing a working directory to learn more about :dir.

Example:

Open an SSH connection to a server and create a file if it doesn't already exist.

#+begin_src bash :results output :dir /ssh:user@localhost:/home/user
if [ ! -e  "foo_file" ];
then
    echo "foo" > foo_file
    echo "Created foo_file"
else
    echo "foo_file already exists!"
fi
#+end_src

#+RESULTS:
: Created foo_file

Example (with sessions):

It also works with sessions!

#+begin_src bash :results output :dir /ssh:user@localhost:/home/user :session *remote*
if [ ! -e  "foo_file" ];
then
    echo "foo" > foo_file
    echo "Created foo_file"
else
    echo "foo_file already exists!"
fi
#+end_src

#+RESULTS:
: foo_file already exists!

:session <session-name>

Use the header :session <session-name> to run different code blocks in the same shell instance. If <session-name> is "none", blank, or the :session header arg is left out altogether, then the code block evaluates in a temporary shell instance. Otherwise, a comint (command-line interpreter) buffer with <session-name> is created and reused. The code block is then sent for evaluation and the results inserted into the Org buffer. Blocks are processed synchronously (i.e. they freeze Emacs until done).

Examples:

The following creates a session called "*my-session*" and defines a variable⁹. The next block uses the same shell instance and has access to the variable from the previous block. Finally, a block with another session is given. It uses a different shell instance and, therefore, has no knowledge of the variable from the other session.

#+begin_src sh :results none :session *my-session*
  X=1
#+end_src

#+begin_src sh :results output :session *my-session*
  echo X was set to "$X"
#+end_src

#+RESULTS:
: X was set to 1

#+begin_src sh :results output :session *another-session*
  echo X was set to "$X"
#+end_src

#+RESULTS:
: X was set to

Sessions are useful for isolating processes and for incremental development.

:async <[yes|no]>

Run session blocks asynchronously with the :async header. This means Emacs will not freeze while waiting for the block to execute.

The :async header accepts optional arguments of "yes" and "no". When "yes", blocks are executed in a background process. When "no", the block behaves like :session (Emacs freezes until execution completes). A "yes" argument is assumed unless the argument is "no".

NOTE: :async requires the :session header!

Examples:

A universally unique identifier (UUID) appears while an async block executes:

#+begin_src sh :results output :session test :async yes
echo "Hello, world!"
sleep 3
echo "Good-bye, cruel World..."
#+end_src

#+RESULTS:
: d3aec7bd-c2a0-41f4-bd4d-edad7143cbbc

When the process completes, the UUID is replaced with the results:

#+begin_src sh :results output :session test :async yes
echo "Hello, world!"
sleep 3
echo "Good-bye, cruel World..."
#+end_src

#+RESULTS:
: Hello, world!
: Good-bye, cruel World...

Disable asynchronous execution by passing "no" as an argument:

#+begin_src sh :results output :session test :async no
echo "Changing the :async argument to 'no'"
sleep 3
echo "will run the block synchronously (freezing Emacs"
echo "until the block completes)."
#+end_src

#+RESULTS:
: Changing the :async argument to 'no'
: will run the block synchronously (freezing Emacs
: until the block completes).

:var <name_1>=<value_1> ... [<name_n>=<value_n>]

Use the :var header to define variables in the shell environment.

Variables are defined using the following forms. Separate multiple variables with a space.

* Only works with Bash.

Example (scalar):

#+begin_src dash :var by_two=0  x=2
  if [ "$by_two" = "0" ]; then
    echo $(($x * 2))
  else
    echo $(($x * 3))
  fi
#+end_src

#+RESULTS:
: 4

Example (1D-array):

#+begin_src bash :results output :var arr='("apple" "banana" "cherry")
  echo The first element is...
  echo \"${arr[1]}\"
#+end_src

#+RESULTS:
: The first element is...
: "banana"

The :var header lets results be passed between blocks, which allows blocks to act like functions.

#+name: multiply_by_2
#+begin_src bash :var data="" :results output
  echo $(($data * 2))
#+end_src

#+begin_src bash :post multiply_by_2(data=*this*)
  echo 3
#+end_src

#+results:
: 6

:stdin <element-name>

Use the :stdin header arg to pass named Org elements, such as code block results, to a shell process as standard input.

NOTE When :stdin is used, the block is evaluated in a temporary shell, regardless of whether a :session is declared.

Example:

#+name: my-org-element
This is something referenced as stdin.
The stdin can even be multiple lines!

#+begin_src sh :stdin my-org-element :results output
cat
#+end_src

#+RESULTS:
: This is something referenced as stdin.
: The stdin can even be multiple lines!

Example:

#+name: my-input
3

#+begin_src bash :stdin my-input :results output
read n
echo You entered: "$n"
#+end_src

#+RESULTS:
: You entered: 3

Example:

#+name: my-input-block
#+begin_src bash
  echo "$(uname -o)"
  x=$(ps -p $PPID -o comm=)
  echo "${x:1:5}"
#+end_src

#+RESULTS: my-input-block
| GNU/Linux |
| emacs     |

#+begin_src bash :stdin my-input-block
  echo $(cut -f 1 -d "/") rocks!
#+end_src

#+RESULTS:
: GNU emacs rocks!

:cmdline <arg_1> ... [arg_n]

Use the :cmdline header arg to pass arguments to a shell command. The arguments are passed verbatim as

<system shell> -c <temporary file with src block contents> <arguments>

#+begin_src sh :cmdline arg ; touch /tmp/not-an-arg
...
#+end_src

#+begin_src sh :cmdline arg1 arg2
  echo "$1"
  echo "$2"
#+end_src

#+RESULTS:
| arg1 |
| arg2 |

:shebang [shebang]

Use the :shebang header arg to process a block as a command¹⁰.

Pass an interpreter directive (e.g. #!/bin/bash) to override the declared shell. If no shebang is provided, the block language is used (e.g. #+begin_src bash).

NOTE When the :shebang header arg is used, the block is evaluated in a temporary shell, regardless of whether a :session is declared.

TIP The :shebang header arg is useful for when a script spans several lines. Without the :shebang header arg, block lines are sent to the shell process in sequence which may result in unwanted output characters.

Example (remove unwanted characters):

#+begin_src sh :results output :session unwanted-chars
  X=1
  echo Setting X...
  sleep 3
  echo X was set to "$X"
#+end_src

#+RESULTS:
: Setting X...
: sh-5.1$ X was set to 1

#+begin_src sh :results output :shebang
  X=1
  echo Setting X...
  sleep 3
  echo X was set to "$X"
#+end_src

#+RESULTS:
: Setting X...
: X was set to 1

Example (override):

#+begin_src bash :shebang #!/usr/bin/env dash
  if [ `basename $SHELL` == bash ]; then
    echo bash;
  else
    echo dash;
  fi
#+end_src

#+RESULTS:
: dash