Org mode part 2
This is the second article in a series about Emacs Org mode. It assumes that you read the first one.
Today we’ll talk a bit about literate programming. The idea is to write an Org mode document that includes snippets of code, and possibly the result of their execution as well. It kind of reverses the way you think about documenting code: instead of adding comments inside your program, you add your program’s code inside the documentation file. In the end the result is the same, you still get executable code.
Org mode includes a feature named Babel which allows for embedding code in any programming language you fancy. Let’s get started.
First, we need to make sure that Babel is enabled for a few other languages
than ELisp (the only one by default). Add the following in your emacs
configuration and evaluate it with
M-C-x (or restart Emacs):
First open a new buffer
literate.org, with this content:
#+TITLE directive is just to add a title to the Org file; it is not
really needed. The other directives we use are
which respectively introduce and close a code block for a particular
language. Note that Emacs automatically applies the proper syntax highlighting.
C-c C-c to evaluate the code block under the point. After confirmation,
Babel will insert a new block
#+RESULTS with the result of the evaluation,
What happened here? Emacs forked a process to execute the code using Python, and got back the returned value, and inserted it into the buffer.
By default the result is the returned value i.e. the last expression that was
executed, but you can also use the output of the program as the result with a
#+begin_src python :result output. For example, evaluate the
shell statement below, again using
Calling code blocks
Babel also allows you to refer to code blocks from elsewhere in your document,
by labeling each block with a name, using directive
#+name. Let’s say we have
some Ruby code to revert a string (yes, I know we could use the native
We can now call this block. Note that we get the result of the block evaluation. So if you want to use the result of a function in the block, you also need to add the call to that function (see the last line).
To call the block, add a
#+call directive referring to the block’s name and
binding the input variable
str, and type
C-c C-c with the point onto it:
Here is a more practical example to illustrate the power of Babel, using different languages to get the job done. This is actually similar to an iPython notebook.
Suppose I want to produce a report containing statistics about the words that are used in a collection of files. Assuming all these files are in the same directory (let’s say they are Markdown files), this shell script counts the number of unique words in each file:
The result has multiple lines, one per file. Therefore it is stored into an Org table:
Now let’s compute the standard deviation. We could follow up with another shell script, but it is easier to do this in ELisp. Add this block in the buffer:
#+begin_src directive uses the
:var keyword to bind the Lisp variable
samples to the output of the
words code block (which is the table
above). In Lisp that
samples variable will be set with a list of
lists. Basically each row in the table is a sublist, and since the table has
only one column the sublists only contain a single number, like this:
If you evaluate the block with
C-c C-c, you get the final result:
You can of course re-run the report anytime you want. Once we have our report ready, Org mode is able to export it into plenty of different formats, choosing exactly what should be included and excluded. But that’s a discussion for another day.