Next: Miscellaneous, Previous: Publishing, Up: Top
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
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.
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 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.
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.
: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 and section 5 of the manual
The Babel site on Worg
Next: Miscellaneous, Previous: Publishing, Up: Top