Table of Contents

Next: , Previous: Publishing, Up: Top


14 Working with source code

Org-mode provides a number of features for working with source code, including editing of code blocks in their native major-mode, evaluation of code blocks, tangling of code blocks, and exporting code blocks and their results in several formats.

Structure of Code Blocks

The structure of code blocks is as follows:

     #+NAME: <name>
     #+BEGIN_SRC <language> <switches> <header arguments>
       <body>
     #+END_SRC

Where <name> is a string used to name the code block, <language> specifies the language of the code block (e.g. emacs-lisp, shell, R, python, etc...), <switches> can be used to control export of the code block, <header arguments> can be used to control many aspects of code block behavior as demonstrated below, and <body> contains the actual source code.

Editing source code

Use C-c ' to edit the current code block. This brings up a language major-mode edit buffer containing the body of the code block. Saving this buffer will write the new contents back to the Org buffer. Use C-c ' again to exit the edit buffer.

Evaluating code blocks

Use C-c C-c to evaluate the current code block and insert its results in the Org-mode buffer. By default, evaluation is only turned on for emacs-lisp code blocks, however support exists for evaluating blocks in many languages. For a complete list of supported languages see the manual. The following shows a code block and its results.

     #+BEGIN_SRC emacs-lisp
       (+ 1 2 3 4)
     #+END_SRC
     
     #+RESULTS:
     : 10

Extracting source code

Use C-c C-v t to create pure source code files by extracting code from source blocks in the current buffer. This is referred to as “tangling”—a term adopted from the literate programming community. During “tangling” of code blocks their bodies are expanded using org-babel-expand-src-block which can expand both variable and “noweb” style references. In order to tangle a code block it must have a :tangle header argument, see the manual for details.

Library of Babel

Use C-c C-v l to load the code blocks from an Org-mode files into the “Library of Babel”, these blocks can then be evaluated from any Org-mode buffer. A collection of generally useful code blocks is distributed with Org-mode in contrib/library-of-babel.org.

Header Arguments

Many aspects of the evaluation and export of code blocks are controlled through header arguments. These can be specified globally, at the file level, at the outline subtree level, and at the individual code block level. The following describes some of the header arguments.

:var
The :var header argument is used to pass arguments to code blocks. The values passed to arguments can be literal values, values from org-mode tables and literal example blocks, or the results of other named code blocks.
:results
The :results header argument controls the collection, type, and handling of code block results. Values of output or value (the default) specify how results are collected from a code block's evaluation. Values of vector, scalar file raw html latex and code specify the type of the results of the code block which dictates how they will be incorporated into the Org-mode buffer. Values of silent, replace, prepend, and append specify handling of code block results, specifically if and how the results should be inserted into the Org-mode buffer.
:session
A header argument of :session will cause the code block to be evaluated in a persistent interactive inferior process in Emacs. This allows for persisting state between code block evaluations, and for manual inspection of the results of evaluation.
:exports
Any combination of the code or the results of a block can be retained on export, this is specified by setting the :results header argument to code results none or both.
:tangle
A header argument of :tangle yes will cause a code block's contents to be tangled to a file named after the filename of the Org-mode buffer. An alternate file name can be specified with :tangle filename.
:cache
A header argument of :cache yes will cause associate a hash of the expanded code block with the results, ensuring that code blocks are only re-run when their inputs have changed.
:noweb
A header argument of :noweb yes will expand “noweb” style references on evaluation and tangling.
:file
Code blocks which output results to files (e.g. graphs, diagrams and figures) can accept a :file filename header argument in which case the results are saved to the named file, and a link to the file is inserted into the Org-mode buffer.

Further reading
Chapter 11.3 of the manual
The Babel site on Worg