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.
The structure of code blocks is as follows:
#+NAME: <name> #+BEGIN_SRC <language> <switches> <header arguments> <body> #+END_SRC
<name> is a string used to name the code block,
<language> specifies the language of the code block
<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
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.
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
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
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.
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 accessible through Org-mode’s community-driven documentation on Worg.
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.
:varheader 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.
:resultsheader argument controls the collection, type, and handling of code block results. Values of
value(the default) specify how results are collected from a code block's evaluation. Values of
codespecify the type of the results of the code block which dictates how they will be incorporated into the Org-mode buffer. Values of
appendspecify handling of code block results, specifically if and how the results should be inserted into the Org-mode buffer.
:sessionwill 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.
:resultsheader argument to
:tangle yeswill 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
:cache yeswill 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 yeswill expand “noweb” style references on evaluation and tangling.
:file filenameheader 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.
Chapter 11.3 of the manual
The Babel site on Worg