mirror of
https://git.savannah.gnu.org/git/emacs/org-mode.git
synced 2024-09-12 08:39:56 +00:00
176 lines
6.8 KiB
Org Mode
176 lines
6.8 KiB
Org Mode
#+OPTIONS: H:3 num:nil toc:2 \n:nil @:t ::t |:t ^:t -:t f:t *:t TeX:t LaTeX:t skip:nil d:(HIDE) tags:not-in-toc
|
|
#+STARTUP: align fold nodlcheck hidestars oddeven lognotestate
|
|
#+SEQ_TODO: TODO(t) INPROGRESS(i) WAITING(w@) | DONE(d) CANCELED(c@)
|
|
#+TAGS: Write(w) Update(u) Fix(f) Check(c)
|
|
#+TITLE: Org-babel
|
|
#+AUTHOR: Dan Davison, Eric Schulte
|
|
#+EMAIL: davison at stats dot ox dot ac dot uk
|
|
#+LANGUAGE: en
|
|
#+CATEGORY: worg
|
|
|
|
#+begin_html
|
|
<div id="subtitle">
|
|
<p>executable source code blocks in org-mode</p>
|
|
</div>
|
|
<div id="logo">
|
|
<p>
|
|
<img src="images/tower-of-babel.png" alt="images/tower-of-babel.png" />
|
|
<div id="attr">from <a href="http://www.flickr.com/photos/23379658@N05/" title=""><b>Martijn Streefkerk</b></a></div>
|
|
</p>
|
|
</div>
|
|
#+end_html
|
|
|
|
* Introduction
|
|
Org-babel provides the following modifications to [[http://orgmode.org/manual/Literal-examples.html][the existing
|
|
support]] for blocks of source code examples in the org-mode core.
|
|
1. source code execution
|
|
2. arguments to source code blocks
|
|
|
|
* Basic org-babel functionality
|
|
*** Source code execution
|
|
For interpreted languages such as shell, python, R, etc, org-babel
|
|
allows source blocks to be executed: the code is passed to the
|
|
interpreter and you have control over what is done with the
|
|
results of excecution. E.g. place point anywhere in the following
|
|
block and use C-c C-c to run the code:
|
|
|
|
#+begin_src python :results output
|
|
import time
|
|
x = 4
|
|
print("hello\n")
|
|
#print time.ctime()
|
|
print [5, 10]
|
|
#+end_src
|
|
|
|
#+resname:
|
|
: hello
|
|
: 510
|
|
|
|
#+begin_src R :results value
|
|
x = 4
|
|
date()
|
|
c(5, 10)
|
|
#+end_src
|
|
|
|
#+resname:
|
|
| 5 |
|
|
| 10 |
|
|
|
|
*** What happens to the results?
|
|
Org-babel provides two fundamentally different modes for capturing
|
|
the results of code evaluation, specified by the :results header
|
|
argument:
|
|
**** :results value
|
|
This means that the 'result' of code evaluation is defined to be
|
|
the *value* of the last statement in the block. Thus with this
|
|
setting, one can view the code block as a function with a return
|
|
value. And not only can one view it that way, but you can
|
|
actually use the return value of one source block as input for
|
|
another (see later). This setting is the default.
|
|
**** :results output
|
|
With this setting, org-babel captures all the text output of the
|
|
code block and places it in the org buffer. One can think of this
|
|
as a 'scripting' mode: the code block contains a series of
|
|
commands, and you get the output of all the commands. Unlike in
|
|
the 'functional' mode specified by =:results value=, the code
|
|
block has no return value. (This mode will be familiar to Sweave
|
|
users).
|
|
**** Additional :results settings
|
|
|
|
*** Arguments to source code blocks
|
|
In addition to evaluation of code blocks, org-babel allows them to
|
|
be parameterised (i.e. have arguments). Thus source code blocks
|
|
now have the status of *functions*.
|
|
|
|
* A meta-programming language for org-mode
|
|
* Spreadsheet plugins for org-mode in any language
|
|
* Library of Babel
|
|
Org-babel support saving of source-code blocks in a library from which
|
|
they can be call in any org-mode file. This library is called the
|
|
[[file:library-of-babel.org][Library of Babel]]. It is possible to add source-code blocks from any
|
|
org-mode file to the library by calling
|
|
|
|
#+srcname: add-file-to-lob
|
|
#+begin_src emacs-lisp
|
|
(org-babel-lob-ingest "path/to/file.org")
|
|
#+end_src
|
|
|
|
* Reproducible research
|
|
- output vs. value mode
|
|
- file & graphical output
|
|
- controlling export
|
|
* Literate programming
|
|
- org-babel-tangle
|
|
- org-babel-load-file
|
|
* Reference / Documentation
|
|
|
|
*** Source Code block syntax
|
|
|
|
The basic syntax of source-code blocks is as follows:
|
|
|
|
: #+srcname: name
|
|
: #+begin_src language header-arguments
|
|
: body
|
|
: #+end_src
|
|
|
|
- name :: This name is associated with the source-code block. This is
|
|
similar to the =#+TBLNAME= lines which can be used to name tables
|
|
in org-mode files. By referencing the srcname of a source-code
|
|
block it is possible to evaluate the block for other places,
|
|
files, or from inside tables.
|
|
- language :: The language of the code in the source-code block, valid
|
|
values must be members of `org-babel-interpreters'.
|
|
- header-arguments :: Header arguments control many facets of the
|
|
input to, evaluation of, and output of source-code blocks. See
|
|
the [[* Header Arguments][Header Arguments]] section for a complete review of available
|
|
header arguments.
|
|
- body :: The actual source code which will be evaluated. This can be
|
|
edited with `org-edit-special'.
|
|
|
|
**** Header Arguments
|
|
|
|
- results :: results arguments specify what should be done with the
|
|
output of source-code blocks
|
|
- The following options are mutually exclusive, and specify how the
|
|
results should be collected from the source-code block
|
|
- value ::
|
|
- output ::
|
|
- The following options are mutually exclusive and specify what type
|
|
of results the code block will return
|
|
- vector :: specifies that the results should be interpreted as a
|
|
multidimensional vector (even if the vector is
|
|
trivial), and will be inserted into the org-mode file
|
|
as a table
|
|
- scalar :: specifies that the results should be interpreted as a
|
|
scalar value, and will be inserted into the org-mode
|
|
file as quoted text
|
|
- file :: specifies that the results should be interpreted as the
|
|
path to a file, and will be inserted into the org-mode
|
|
file as a link
|
|
- The following options specify how the results should be inserted
|
|
into the org-mode file
|
|
- replace :: the current results replace any previously inserted
|
|
results from the code block
|
|
- silent :: rather than being inserted into the org-mode file the
|
|
results are echoed into the message bar
|
|
- exports :: exports arguments specify what should be included in html
|
|
or latex exports of the org-mode file
|
|
- code :: the body of code is included into the exported file
|
|
- results :: the results of evaluating the code is included in the
|
|
exported file
|
|
- both :: both the code and results are included in the exported
|
|
file
|
|
- none :: nothing is included in the exported file
|
|
- tangle :: tangle arguments specify whether or not the source-code
|
|
block should be included in tangled extraction of
|
|
source-code files
|
|
- yes :: the source-code block is exported to a source-code file
|
|
named after the basename (name w/o extension) of the
|
|
org-mode file
|
|
- no :: (default) the source-code block is not exported to a
|
|
source-code file
|
|
- other :: any other string passed to the =tangle= header argument
|
|
is interpreted as a file basename to which the block will
|
|
be exported
|
|
|