14 Working with source code

Source code here refers to any code typed in Org mode documents. Org can manage source code in any Org file once such code is tagged with begin and end markers. Working with source code begins with tagging source code blocks. Tagged ‘src’ code blocks are not restricted to the preamble or the end of an Org document; they can go anywhere—with a few exceptions, such as not inside comments and fixed width areas. Here’s a sample ‘src’ code block in emacs-lisp:

#+BEGIN_SRC emacs-lisp
  (defun org-xor (a b)
     "Exclusive or."
     (if a (not b) b))
#+END_SRC

Org can take the code in the block between the #+BEGIN_SRC and #+END_SRC tags, and format, compile, execute, and show the results. Org can simplify many housekeeping tasks essential to modern code maintenance. That’s why these blocks in Org mode literature are sometimes referred to as ‘live code’ blocks (as compared to the static text and documentation around it). Users can control how ‘live’ they want each block by tweaking the headers for compiling, execution, extraction.

Org’s ‘src’ code block type is one of many block types, such as quote, export, verse, latex, example, and verbatim. This section pertains to src code blocks between #+BEGIN_SRC and #+END_SRC

For editing ‘src’ code blocks, Org provides native Emacs major-modes. That leverages the latest Emacs features for that source code language mode.

For exporting, Org can then extract ‘src’ code blocks into compilable source files (in a conversion process known as tangling in literate programming terminology).

For publishing, Org’s back-ends can handle the ‘src’ code blocks and the text for output to a variety of formats with native syntax highlighting.

For executing the source code in the ‘src’ code blocks, Org provides facilities that glue the tasks of compiling, collecting the results of the execution, and inserting them back to the Org file. Besides text output, results may include links to other data types that Emacs can handle: audio, video, and graphics.

An important feature of Org’s execution of the ‘src’ code blocks is passing variables, functions, and results between ‘src’ blocks. Such interoperability uses a common syntax even if these ‘src’ blocks are in different source code languages. The integration extends to linking the debugger’s error messages to the line in the ‘src’ code block in the Org file. That should partly explain why this functionality by the original contributors, Eric Schulte and Dan Davison, was called ‘Org Babel’.

In literate programming, the main appeal is code and documentation co-existing in one file. Org mode takes this several steps further. First by enabling execution, and then by inserting results of that execution back into the Org file. Along the way, Org provides extensive formatting features, including handling tables. Org handles multiple source code languages in one file, and provides a common syntax for passing variables, functions, and results between ‘src’ code blocks.

Org mode fulfills the promise of easy verification and maintenance of publishing reproducible research by keeping all these in the same file: text, data, code, configuration settings of the execution environment, the results of the execution, and associated narratives, claims, references, and internal and external links.

Details of Org’s facilities for working with source code are shown next.