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.
A source code block conforms to this structure:
#+NAME: <name> #+BEGIN_SRC <language> <switches> <header arguments> <body> #+END_SRC
Use C-c ' to edit the current code block. It opens a new major mode edit buffer containing the body of the source code block, ready for any edits. Use C-c ' again to close the buffer and return to the Org buffer.
A header argument is specified with an initial colon followed by the argument’s name in lowercase.
Header arguments can be set in several ways; Org prioritizes them in case of overlaps or conflicts by giving local settings a higher priority.
Those are specified by customizing
variable, or, for a specific language LANG
You can set them using ‘header-args’ property (see Properties)—or ‘header-args:LANG’ for language LANG. Header arguments set through properties drawers apply at the sub-tree level on down.
Header arguments are most commonly set at the source code block level, on the ‘BEGIN_SRC’ line:
#+NAME: factorial #+BEGIN_SRC haskell :results silent :exports code :var n=0 fac 0 = 1 fac n = n * fac (n-1) #+END_SRC
Code block header arguments can span multiple lines using ‘HEADER’ keyword on each line.
Use C-c C-c to evaluate the current code block and insert its results in the Org document. 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
The following syntax is used to pass arguments to code blocks using the ‘var’ header argument.
NAME is the name of the variable bound in the code block body. ASSIGN is a literal value, such as a string, a number, a reference to a table, a list, a literal example, another code block—with or without arguments—or the results of evaluating a code block.
How Org handles results of a code block execution depends on many header arguments working together. The primary determinant, however, is the ‘results’ header argument. It controls the collection, type, format, and handling of code block results.
How the results should be collected from the code block. You may choose either ‘output’ or ‘value’ (the default).
What result types to expect from the execution of the code block. You may choose among ‘table’, ‘list’, ‘scalar’, and ‘file’. Org tries to guess it if you do not provide it.
How Org processes results. Some possible values are ‘code’, ‘drawer’, ‘html’, ‘latex’, ‘link’, and ‘raw’.
How to insert the results once properly formatted. Allowed values are ‘silent’, ‘replace’ (the default), ‘append’, or ‘prepend’.
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 buffer.
It is possible to export the code of code blocks, the results of code block evaluation, both the code and the results of code block evaluation, or none. Org defaults to exporting code for most languages.
The ‘exports’ header argument is to specify if that part of the Org file is exported to, say, HTML or LaTeX formats. It can be set to either ‘code’, ‘results’, ‘both’ or ‘none’.
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