forked from mirrors/org-mode
1026 lines
39 KiB
Plaintext
1026 lines
39 KiB
Plaintext
@chapter Working With Source Code or Embedded Source Code
|
|
|
|
Source code can be included in Org-mode documents using a @samp{src} block:
|
|
|
|
FIXME: This example is also in the Literal Examples section.
|
|
@example
|
|
#+BEGIN_SRC emacs-lisp
|
|
(defun org-xor (a b)
|
|
"Exclusive or."
|
|
(if a (not b) b))
|
|
#+END_SRC
|
|
@end example
|
|
|
|
Org supports the following ways of working with such code blocks:
|
|
|
|
@itemize @bullet
|
|
@item
|
|
Editing in the appropriate Emacs major-mode (@kbd{C-c '})
|
|
@item
|
|
Export with appropriate markup
|
|
@item
|
|
Extraction (``tangling'') into pure code files.
|
|
@item
|
|
Execution, with results captured in the Org buffer
|
|
@item
|
|
Using code blocks in table formulas
|
|
@end itemize
|
|
|
|
|
|
@section Syntax
|
|
:PROPERTIES:
|
|
:CUSTOM_ID: syntax
|
|
:END:
|
|
|
|
@subsection Source Code Block
|
|
The basic syntax of source code blocks in Org-babel is as follows:
|
|
|
|
@example
|
|
#+begin_src language header-arguments
|
|
body
|
|
#+end_src
|
|
@end example
|
|
- 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
|
|
evaluation and output of source code blocks. See the [[header-arguments][Header
|
|
Arguments]] section for a complete review of available header
|
|
arguments.
|
|
- body :: The source code to be evaluated. An important key-binding
|
|
is C-c '. This calls =org-edit-src-code=, a function that brings
|
|
up an edit buffer containing the code using the Emacs major mode
|
|
appropriate to the language. You can edit your source code block
|
|
as you regularly would in Emacs.
|
|
|
|
This syntax can be expanded by naming the source code block.
|
|
|
|
@example
|
|
#+sourcename
|
|
#+begin_src language header-arguments
|
|
body
|
|
#+end_src
|
|
@end example
|
|
|
|
- name :: This name is associated with the source code block. This is
|
|
similar to the =#+tblname= lines that can be used to name tables
|
|
in Org-mode files. Referencing the name of a source code
|
|
block makes it possible to evaluate the block from other places in
|
|
the file, other files, or inside Org-mode tables. It
|
|
is also possible to pass arguments to a source code block through
|
|
this =#+source:= line (see [[alternate-argument-syntax][Alternate argument syntax]]).
|
|
|
|
@subsection Library of Babel
|
|
[[file:library-of-babel.org][Library of Babel]] functions can be called using the following syntax.
|
|
|
|
@example
|
|
#+lob: R-plot(data=R-plot-example-data)
|
|
@end example
|
|
|
|
@subsection Aliases
|
|
Keyword aliases are intended to make Org-babel feel natural to
|
|
programmers fluent in a variety of languages. For example,
|
|
@example
|
|
#+srcname: alias-example
|
|
#+begin_src emacs-lisp
|
|
'((call lob)
|
|
(source function srcname)
|
|
(results resname))
|
|
#+end_src
|
|
|
|
#+results: alias-example
|
|
| call | lob | |
|
|
| source | function | srcname |
|
|
| results | resname | |
|
|
@end example
|
|
- =#+srcname:= can be replaced with either of two aliases, =#+source:= or =#+function:=.
|
|
- =#+results:= can be replaced with its alias, =#+resname:=.
|
|
|
|
When calling Library of Babel functions, as in the following
|
|
example, there are two acceptable keywords. The =#+lob= call in
|
|
the example could be replaced with its alias, =#+call=.
|
|
@example
|
|
#+lob: R-plot(data=R-plot-example-data)
|
|
@end example
|
|
|
|
@section Languages
|
|
:PROPERTIES:
|
|
:CUSTOM_ID: languages
|
|
:END:
|
|
|
|
Org-babel has support for the following languages.
|
|
|
|
| Language | Documentation | Identifier | Requirements |
|
|
|----------------+-----------------------------+------------+---------------------------------------------|
|
|
| Asymptote | org-babel-doc-asymptote | asymptote | [[http://asymptote.sourceforge.net/][asymptote]], [[http://asymptote.sourceforge.net/doc/Editing-modes.html][asy-mode]] |
|
|
| C | [[file:languages/org-babel-doc-C.org][org-babel-doc-C]] | C | none |
|
|
| Clojure | [[file:languages/org-babel-doc-clojure.org][org-babel-doc-clojure]] | clojure | [[http://clojure.org/][clojure]], [[http://www.emacswiki.org/emacs/clojure-mode.el][clojure-mode]], [[http://common-lisp.net/project/slime/][slime]], [[http://clojure.codestuffs.com/][swank-clojure]] |
|
|
| css | org-babel-doc-css | css | none |
|
|
| ditaa | org-babel-doc-ditaa | ditaa | [[http://ditaa.org/ditaa/][ditaa]] (bundled with Org-mode) |
|
|
| Graphviz | org-babel-doc-dot | dot | [[http://www.graphviz.org/][dot]] |
|
|
| Emacs Lisp | org-babel-doc-emacs-lisp | emacs-lisp | none |
|
|
| gnuplot | org-babel-doc-gnuplot | gnuplot | [[http://www.gnuplot.info/][gnuplot]], [[http://cars9.uchicago.edu/~ravel/software/gnuplot-mode.html][gnuplot-mode]] |
|
|
| Haskell | org-babel-doc-haskell | haskell | [[http://www.haskell.org/][haskell]], [[http://projects.haskell.org/haskellmode-emacs/][haskell-mode]], [[http://www.haskell.org/haskellwiki/Haskell_mode_for_Emacs#inf-haskell.el:_the_best_thing_since_the_breadknife][inf-haskell]], [[http://people.cs.uu.nl/andres/lhs2tex/][lhs2tex]] |
|
|
| Matlab | [[file:languages/org-babel-doc-octave-matlab.org][org-babel-doc-octave-matlab]] | matlab | matlab, [[http://sourceforge.net/projects/matlab-emacs/][matlab.el]] |
|
|
| LaTeX | [[file:languages/org-babel-doc-LaTeX.org][org-babel-doc-latex]] | latex | [[http://www.latex-project.org/][latex]], [[http://www.gnu.org/software/auctex/][auctex]], [[http://www.gnu.org/software/auctex/reftex.html][reftex]] |
|
|
| Objective Caml | org-babel-doc-ocaml | ocaml | [[http://caml.inria.fr/][ocaml]], [[http://www-rocq.inria.fr/~acohen/tuareg/][tuareg-mode]] |
|
|
| Octave | [[file:languages/org-babel-doc-octave-matlab.org][org-babel-doc-octave-matlab]] | octave | octave |
|
|
| OZ | [[file:languages/org-babel-doc-oz.org][org-babel-doc-oz]] | oz | [[http://www.mozart-oz.org/][Mozart]] which includes a major mode |
|
|
| Perl | org-babel-doc-perl | perl | [[http://www.perl.org/][perl]], [[http://www.emacswiki.org/emacs/CPerlMode][cperl-mode]] (optional) |
|
|
| Python | org-babel-doc-python | python | [[http://www.python.org/][python]], [[https://launchpad.net/python-mode][python-mode]] (optional) |
|
|
| R | [[file:languages/org-babel-doc-R.org][org-babel-doc-R]] | R | [[http://www.r-project.org/][R]], [[http://ess.r-project.org/][ess-mode]] |
|
|
| Ruby | org-babel-doc-ruby | ruby | [[http://www.ruby-lang.org/][ruby]], [[http://www.ruby-lang.org/][irb]], [[http://github.com/eschulte/rinari/raw/master/util/ruby-mode.el][ruby-mode]], [[http://github.com/eschulte/rinari/raw/master/util/inf-ruby.el][inf-ruby mode]] |
|
|
| Sass | org-babel-doc-sass | sass | [[http://sass-lang.com/][sass]], [[http://github.com/nex3/haml/blob/master/extra/sass-mode.el][sass-mode]] |
|
|
| GNU Screen | [[file:languages/org-babel-doc-screen.org][org-babel-doc-screen]] | screen | [[http://www.gnu.org/software/screen/][screen]], a terminal |
|
|
| shell | org-babel-doc-sh | sh[fn:1] | a shell |
|
|
| SQL | org-babel-doc-sql | sql | none |
|
|
|
|
To add support for a particular language to your Org-babel
|
|
installation first make sure that the requirements of the language
|
|
are met, then add a line like the following to your Emacs
|
|
configuration, (replace "identifier" with one of the
|
|
entries in the Identifier column of the table).
|
|
@example
|
|
(require 'org-babel-identifier)
|
|
@end example
|
|
|
|
@section Header Arguments
|
|
:PROPERTIES:
|
|
:CUSTOM_ID: header-arguments
|
|
:END:
|
|
|
|
Definitions of all Org-babel header arguments are given [[header-argument-specific-documentation][below]]. In
|
|
addition, some languages may add their own header arguments. Please
|
|
see the language-specific documentation for information on
|
|
language-specific header arguments.
|
|
|
|
@subsection Using Header Arguments
|
|
|
|
The values of header arguments can be set in three different ways,
|
|
each more specific than the last.
|
|
|
|
@subsubsection System-wide
|
|
:PROPERTIES:
|
|
:CUSTOM_ID: system-wide-header-argument
|
|
:END:
|
|
|
|
System-wide values of header arguments can be specified by
|
|
customizing the =org-babel-default-header-args= variable:
|
|
@example
|
|
org-babel-default-header-args is a variable defined in `org-babel.el'.
|
|
Its value is
|
|
((:session . "none")
|
|
(:results . "replace")
|
|
(:exports . "code")
|
|
(:cache . "no")
|
|
(:noweb . "no"))
|
|
|
|
|
|
Documentation:
|
|
Default arguments to use when evaluating a source block.
|
|
@end example
|
|
[[#default-noweb]]
|
|
For example, the following example could be used to set the default value
|
|
of =:noweb= header arguments to =yes=. This would have the effect of
|
|
expanding =:noweb= references by default when evaluating source code blocks.
|
|
@example
|
|
(setq org-babel-default-header-args
|
|
(cons '(:noweb . "yes")
|
|
(assq-delete-all :noweb org-babel-default-header-args)))
|
|
@end example
|
|
|
|
@subsubsection Org-mode Properties
|
|
|
|
Header arguments are also read from [[http://orgmode.org/manual/Properties-and-Columns.html#Properties-and-Columns][Org-mode properties]], which
|
|
means they can be set on the outline header level. For example, the
|
|
value of the =:cache= header argument will default to true in all
|
|
source code blocks under the following example of an Org-mode outline header:
|
|
@example
|
|
* outline header
|
|
:PROPERTIES:
|
|
:cache: yes
|
|
:CUSTOM_ID: property-set-header-arguments
|
|
:END:
|
|
@end example
|
|
Properties defined in this way override the properties set in
|
|
=org-babel-default-header-args=. It is convenient to use the
|
|
=org-set-property= function bound to =C-c C-x p= to set properties
|
|
in Org-mode documents.
|
|
|
|
@subsubsection Source Code Block
|
|
:PROPERTIES:
|
|
:CUSTOM_ID: single-block-header-arguments
|
|
:END:
|
|
The most common way to assign values to header arguments is at the
|
|
source code block level. This can be done by listing a sequence of
|
|
header arguments and their values as part of the =#+begin_src=
|
|
line. Properties set in this way override both the values of
|
|
=org-babel-default-header-args= and header argument specified as
|
|
properties. In the following example, the
|
|
=:results= header argument is set to =silent=, meaning the results
|
|
of execution will not be inserted in the buffer, and the =:exports=
|
|
header argument is set to =code=, meaning only the body of the
|
|
source code block
|
|
will be preserved on export to HTML or LaTeX.
|
|
@example
|
|
#+source: factorial
|
|
#+begin_src haskell :results silent :exports code
|
|
fac 0 = 1
|
|
fac n = n * fac (n-1)
|
|
#+end_src
|
|
@end example
|
|
|
|
@subsection Specific Header Arguments
|
|
:PROPERTIES:
|
|
:CUSTOM_ID: header-argument-specific-documentation
|
|
:END:
|
|
|
|
@subsubsection =:var=
|
|
:PROPERTIES:
|
|
:CUSTOM_ID: header-argument-var
|
|
:END:
|
|
|
|
The =:var= header argument is used to pass arguments to
|
|
source code blocks. The specifics of how arguments are included
|
|
in a source code block are language specific and are
|
|
addressed in the language-specific documentation. However, the
|
|
syntax used to specify arguments is the same across all
|
|
languages. The values passed to arguments can be or
|
|
- literal values
|
|
- values from org-mode tables
|
|
- the results of other source code blocks
|
|
|
|
These values can be indexed in a manner similar to arrays -- see
|
|
[[var-argument-indexing][argument indexing]].
|
|
|
|
The following syntax is used to pass arguments to source code
|
|
blocks using the =:var= header argument.
|
|
|
|
@example
|
|
:var name=assign
|
|
@end example
|
|
|
|
where =assign= can take one of the following forms
|
|
|
|
- literal value :: either a string ="string"= or a number =9=.
|
|
- reference :: a table name:
|
|
|
|
@example
|
|
#+tblname: example-table
|
|
| 1 |
|
|
| 2 |
|
|
| 3 |
|
|
| 4 |
|
|
|
|
#+source: table-length
|
|
#+begin_src emacs-lisp :var table=example-table
|
|
(length table)
|
|
#+end_src
|
|
|
|
#+results: table-length
|
|
: 4
|
|
@end example
|
|
|
|
a source code block name, as assigned by =#+srcname:=,
|
|
followed by parentheses:
|
|
|
|
@example
|
|
#+begin_src emacs-lisp :var length=table-length()
|
|
(* 2 length)
|
|
#+end_src
|
|
|
|
#+results:
|
|
: 8
|
|
@end example
|
|
|
|
In addition, an argument can be passed to the source code
|
|
block referenced by =:var=. The argument is passed within
|
|
the parentheses following the source code block name:
|
|
|
|
@example
|
|
#+source: double
|
|
#+begin_src emacs-lisp :var input=8
|
|
(* 2 input)
|
|
#+end_src
|
|
|
|
#+results: double
|
|
: 16
|
|
|
|
#+source: squared
|
|
#+begin_src emacs-lisp :var input=double(input=1)
|
|
(* input input)
|
|
#+end_src
|
|
|
|
#+results: squared
|
|
: 4
|
|
@end example
|
|
|
|
@subsubheading alternate argument syntax
|
|
:PROPERTIES:
|
|
:CUSTOM_ID: alternate-argument-syntax
|
|
:END:
|
|
|
|
It is also possible to specify arguments in a potentially more
|
|
natural way using the =#+source:= line of a source code block.
|
|
As in the following example arguments can be packed inside of
|
|
parenthesis following the source name.
|
|
@example
|
|
#+source: double(input=0)
|
|
#+begin_src emacs-lisp
|
|
(* 2 input)
|
|
#+end_src
|
|
@end example
|
|
|
|
**** indexable variable values
|
|
:PROPERTIES:
|
|
:CUSTOM_ID: var-argument-indexing
|
|
:END:
|
|
|
|
It is possible to assign a portion of a value to a
|
|
variable in a source block. The following example
|
|
assigns the second and third rows of the table
|
|
=example-table= to the variable =data=:
|
|
|
|
@example
|
|
:var data=example-table[1:2]
|
|
@end example
|
|
|
|
*Note:* ranges are indexed using the =:= operator.
|
|
|
|
*Note:* indices are 0 based.
|
|
|
|
The following example assigns the second column of the
|
|
first row of =example-table= to =data=:
|
|
|
|
@example
|
|
:var data=example-table[0,1]
|
|
@end example
|
|
|
|
It is possible to index into the results of source code blocks
|
|
as well as tables. Any number of dimensions can be indexed.
|
|
Dimensions are separated from one another by commas.
|
|
|
|
For more information on indexing behavior see the documentation
|
|
for the =org-babel-ref-index-list= function -- provided below.
|
|
|
|
@example
|
|
org-babel-ref-index-list is a Lisp function in `org-babel-ref.el'.
|
|
|
|
(org-babel-ref-index-list INDEX LIS)
|
|
|
|
Return the subset of LIS indexed by INDEX. If INDEX is
|
|
separated by ,s then each PORTION is assumed to index into the
|
|
next deepest nesting or dimension. A valid PORTION can consist
|
|
of either an integer index, or two integers separated by a : in
|
|
which case the entire range is returned.
|
|
@end example
|
|
|
|
*Note:* In Emacs, the documentation for any function or variable
|
|
can be read using the =describe-function= (M-x describe
|
|
function) and =describe-variable= (M-x describe variable)
|
|
functions, respectively.
|
|
|
|
@subsubsection =:results=
|
|
:PROPERTIES:
|
|
:CUSTOM_ID: header-argument-results
|
|
:END:
|
|
|
|
There are three types of results header argument:
|
|
- *collection* header arguments specify how the results should be collected from
|
|
the source code block;
|
|
- *type* header arguments specify what type of result the source code block
|
|
will return -- which has implications for how they will be
|
|
inserted into the Org-mode buffer; and
|
|
- *handling* header arguments specify how the results of
|
|
evaluating the source code block should be handled.
|
|
|
|
*Note:* only one option from each type may be supplied per source code
|
|
block.
|
|
|
|
@subsubheading collection
|
|
:PROPERTIES:
|
|
:CUSTOM_ID: header-argument-results-collection
|
|
:END:
|
|
The following options are mutually exclusive, and specify how the
|
|
results should be collected from the source code block.
|
|
|
|
- value :: This is the default. The result is the value
|
|
of the last statement in the source code block.
|
|
This header argument places Org-babel in functional
|
|
mode. Note that in some languages, e.g., python,
|
|
use of this result type requires that a =return=
|
|
statement be included in the body of the source code
|
|
block. E.g., =:results value=.
|
|
- output :: The result is the collection of everything printed
|
|
to stdout during the execution of the source code
|
|
block. This header argument places Org-babel in scripting
|
|
mode. E.g., =:results output=.
|
|
|
|
@subsubheading type
|
|
The following options are mutually exclusive and specify what
|
|
type of results the code block will return. By default, results
|
|
are inserted as either a *table* or *scalar* depending on their
|
|
value.
|
|
|
|
- table, vector :: The results should be interpreted as an Org-mode table.
|
|
If a single value is returned, Org-babel will convert it
|
|
into a table with one row and one column. E.g., =:results
|
|
value table=.
|
|
- scalar, verbatim :: The results should be interpreted
|
|
literally -- meaning they will not be converted into a table.
|
|
The results will be inserted into the Org-mode buffer as
|
|
quoted text. E.g., =:results value verbatim=.
|
|
- file :: The results will be interpreted as the path to a file,
|
|
and will be inserted into the Org-mode buffer as a file
|
|
link. E.g., =:results value file=.
|
|
- raw, org :: The results are interpreted as raw Org-mode code and
|
|
are inserted directly into the buffer. If the results look
|
|
like a table they will be aligned as such by Org-mode.
|
|
E.g., =:results value raw=.
|
|
- html :: Results are assumed to be HTML and will be enclosed in
|
|
a =begin_html= block. E.g., =:results value html=.
|
|
- latex :: Results assumed to be LaTeX and are enclosed in a
|
|
=begin_latex= block. E.g., =:results value latex=.
|
|
- code :: Result are assumed to be parseable code and are
|
|
enclosed in a code block. E.g., =:results value code=.
|
|
- pp :: The result is converted to pretty-printed code and is
|
|
enclosed in a code block. This option currently supports
|
|
Emacs Lisp, python, and ruby. E.g., =:results value pp=.
|
|
|
|
@subsubheading handling
|
|
The following results options indicate what Org-babel should do
|
|
with the results once they are collected.
|
|
|
|
- silent :: The results will be echoed in the minibuffer but
|
|
will not be inserted into the Org-mode buffer. E.g.,
|
|
=:results output silent=.
|
|
- replace :: The default value. The results will be inserted
|
|
into the Org-mode buffer. E.g., =:results output
|
|
replace=.
|
|
|
|
@subsubsection =:file=
|
|
:PROPERTIES:
|
|
:CUSTOM_ID: header-argument-file
|
|
:END:
|
|
|
|
=:file= is used to specify a path for file output in which case an
|
|
[[http://orgmode.org/manual/Link-format.html#Link-format][org style]] =file:= link is inserted into the buffer as the
|
|
result. Common examples are graphical output from [[file:languages/org-babel-doc-R.org][R]], gnuplot,
|
|
ditaa and [[file:languages/org-babel-doc-LaTeX.org][latex]] blocks.
|
|
|
|
See the [[#header-argument-dir][=:dir= and remote execution]] section for examples.
|
|
|
|
Note that for some languages, including [[file:languages/org-babel-doc-R.org][R]], gnuplot, [[file:languages/org-babel-doc-LaTeX.org][latex]] and
|
|
ditaa, graphical output is sent to the specified file without the
|
|
file being referenced explicitly in the code block. See the
|
|
documentation for the individual languages for details. In
|
|
contrast, general purpose languages such as python and ruby
|
|
require that the code explicitly create output corresponding to
|
|
the path indicated by =:file=.
|
|
|
|
While the =:file= header argument can be used to specify the path
|
|
to the output file,
|
|
|
|
@subsubsection =:dir= and remote execution
|
|
:PROPERTIES:
|
|
:CUSTOM_ID: header-argument-dir
|
|
:END:
|
|
=:dir= specifies the /default directory/ during code block
|
|
execution. If it is absent, then the directory associated with the
|
|
current buffer is used. In other words, supplying =:dir path=
|
|
temporarily has the same effect as changing the current directory
|
|
with =M-x cd path=, and then not supplying =:dir=. Under the
|
|
surface, =:dir= simply sets the value of the emacs variable
|
|
=default-directory=.
|
|
|
|
When using =:dir=, you should supply a relative path for [[#header-argument-file][file
|
|
output]] (e.g. =:file myfile.jpg= or =:file results/myfile.jpg=) in
|
|
which case that path will be interpreted relative to the default
|
|
directory.
|
|
|
|
In other words, if you want your plot to go into a folder called
|
|
Work in your home directory, you could use
|
|
|
|
@example
|
|
#+begin_src R :file myplot.png :dir ~/Work
|
|
matplot(matrix(rnorm(100), 10), type="l")
|
|
#+end_src
|
|
@end example
|
|
|
|
@subsubheading Remote execution
|
|
A directory on a remote machine can be specified using [[http://www.gnu.org/software/tramp/#Filename-Syntax][tramp
|
|
filename syntax]], in which case the code will be executed on the
|
|
remote machine[fn:2]. An example is
|
|
|
|
@example
|
|
#+begin_src R :file plot.png :dir /dand@@yakuba.princeton.edu:
|
|
plot(1:10, main=system("hostname", intern=TRUE))
|
|
#+end_src
|
|
@end example
|
|
|
|
Text results will be returned to the local org buffer as normal, and
|
|
file output will be created on the remote machine with relative paths
|
|
interpreted relative to the remote directory. An org link to the
|
|
remote file will be created.
|
|
|
|
So in the above example a plot will be created on the remote machine,
|
|
and a link of the following form will be inserted in the org buffer:
|
|
|
|
@example
|
|
[[file:/scp:dand@@yakuba.princeton.edu:/home/dand/plot.png][plot.png]]
|
|
@end example
|
|
|
|
Most of this functionality follows immediately from the fact that
|
|
=:dir= sets the value of the emacs variable =default-directory=,
|
|
thanks to [[http://www.gnu.org/software/tramp/][tramp]]. Those using XEmacs, or GNU Emacs prior to
|
|
version 23 may need to install tramp separately in order for the
|
|
above features to work correctly.
|
|
|
|
@subsubheading Further points
|
|
- If =:dir= is used in conjunction with =:session=, although it
|
|
will determine the starting directory for a new session as
|
|
expected, no attempt is currently made to alter the directory
|
|
associated with an existing session.
|
|
- =:dir= should typically not be used to create files during
|
|
export with =:exports results= or =:exports both=. The reason
|
|
is that, in order to retain portability of exported material
|
|
between machines, during export, links inserted into the buffer
|
|
will *not* be expanded against default directory. Therefore, if
|
|
default-directory is altered using =:dir=, it it probable that
|
|
the file will be created in a location to which the link does
|
|
not point.
|
|
@subsubsection =:exports=
|
|
:PROPERTIES:
|
|
:CUSTOM_ID: header-argument-exports
|
|
:END:
|
|
|
|
Specify what should be included in HTML or LaTeX exports of the
|
|
Org-mode file.
|
|
|
|
- code :: the default. The body of code is included
|
|
into the exported file. E.g., =:exports code=.
|
|
- results :: the result of evaluating the code is included in the
|
|
exported file. E.g., =:exports results=.
|
|
- both :: both the code and results are included in the exported
|
|
file. E.g., =:exports both=.
|
|
- none :: nothing is included in the exported file. E.g.,
|
|
=:exports none=.
|
|
|
|
@subsubsection =:tangle=
|
|
:PROPERTIES:
|
|
:CUSTOM_ID: tangle-header-arguments
|
|
:END:
|
|
|
|
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. E.g., =:tangle yes=.
|
|
- no :: the default. The source code block is not
|
|
exported to a source code file. E.g., =:tangle no=.
|
|
- other :: Any other string passed to the =:tangle= header argument
|
|
is interpreted as a file basename to which the block will
|
|
be exported. E.g., =:tangle basename=.
|
|
|
|
@subsubsection =:session=
|
|
:PROPERTIES:
|
|
:CUSTOM_ID: header-argument-session
|
|
:END:
|
|
|
|
Start a session for an interpreted language where state is
|
|
preserved. This applies particularly to the supported languages
|
|
python, R and ruby.
|
|
|
|
By default, a session is not started.
|
|
|
|
A string passed to the =:session= header argument will give the
|
|
session a name. This makes it possible to run concurrent
|
|
sessions for each interpreted language.
|
|
|
|
@subsubsection =:noweb=
|
|
:PROPERTIES:
|
|
:CUSTOM_ID: header-argument-noweb
|
|
:END:
|
|
|
|
Controls the expansion of [[noweb-reference-syntax][noweb syntax]] references in a
|
|
source code block. This header argument can have one of two
|
|
values: =yes= or =no=.
|
|
- =no= :: the default. No [[noweb-reference-syntax][noweb syntax]] specific action is taken
|
|
on evaluating source code blocks/ However, noweb references
|
|
will still be expanded during tangling.
|
|
- =yes= :: all [[noweb-reference-syntax][noweb syntax]] references in the body of the source
|
|
code block will be expanded before the block is evaluated.
|
|
|
|
@subsubheading Noweb Prefix Lines
|
|
|
|
Noweb insertions are now placed behind the line prefix of the
|
|
=<<reference>>=.
|
|
|
|
This behavior is illustrated in the following example. Because
|
|
the =<<example>>= noweb reference appears behind the SQL
|
|
comment syntax, each line of the expanded noweb reference will
|
|
be commented.
|
|
|
|
This source code block:
|
|
|
|
@example
|
|
-- <<example>>
|
|
@end example
|
|
|
|
|
|
expands to:
|
|
|
|
@example
|
|
-- this is the
|
|
-- multi-line body of example
|
|
@end example
|
|
|
|
Note that noweb replacement text that does *not* contain any
|
|
newlines will not be affected by this change, so it is still
|
|
possible to use inline noweb references.
|
|
|
|
Thanks to Sébastien Vauban for this idea.
|
|
|
|
@subsubsection =:cache=
|
|
:PROPERTIES:
|
|
:CUSTOM_ID: header-argument-cache
|
|
:END:
|
|
|
|
Controls the use of in-buffer caching of source code block
|
|
results to avoid re-running unchanged source code blocks. This
|
|
header argument can have one of two values: =yes= or =no=.
|
|
- =no= :: The default. No caching takes place and the source
|
|
code block will be run every time it is executed.
|
|
- =yes= :: every time the source code block is run a sha1 hash of
|
|
the code and arguments passed to the block will be
|
|
generated. This hash is packed into the =#+results:= line
|
|
of the results and will be checked on subsequent executions
|
|
of the source code block. If the source code block has not
|
|
changed since the last time it was evaluated, it will not be
|
|
re-evaluated.
|
|
|
|
@section Results
|
|
:PROPERTIES:
|
|
:CUSTOM_ID: results-specification
|
|
:END:
|
|
|
|
The way in which results are handled depends on whether a [[header-argument-session][session]]
|
|
is invoked, as well as on whether
|
|
[[header-argument-results-collection][=:results value=] or
|
|
[[header-argument-results-collection][=:results output=]] is used. The following table shows the
|
|
possibilities:
|
|
|
|
| | non-session (default) | =:session= |
|
|
|-------------------+--------------------------+-------------------------------------|
|
|
| =:results value= | value of last expression | value of last expression |
|
|
| =:results output= | contents of stdout | concatenation of interpreter output |
|
|
|
|
*Note:* With =:results value=, the result in both =:session= and
|
|
non-session is returned to Org-mode as a table (a one- or
|
|
two-dimensional vector of strings or numbers) when appropriate.
|
|
|
|
@subsection Non-session
|
|
@subsubsection =:results value=
|
|
This is the default. Internally, the value is obtained by
|
|
wrapping the code in a function definition in the external
|
|
language, and evaluating that function. Therefore, code should be
|
|
written as if it were the body of such a function. In particular,
|
|
note that python does not automatically return a value from a
|
|
function unless a =return= statement is present, and so a
|
|
'return' statement will usually be required in python.
|
|
|
|
This is the only one of the four evaluation contexts in which the
|
|
code is automatically wrapped in a function definition.
|
|
|
|
@subsubsection =:results output=
|
|
The code is passed to the interpreter as an external process, and
|
|
the contents of the standard output stream are returned as
|
|
text. (In certain languages this also contains the error output
|
|
stream; this is an area for future work.)
|
|
|
|
@subsection =:session=
|
|
@subsubsection =:results value=
|
|
The code is passed to the interpreter running as an interactive
|
|
Emacs inferior process. The result returned is the result of the
|
|
last evaluation performed by the interpreter. (This is obtained in
|
|
a language-specific manner: the value of the variable =_= in
|
|
python and ruby, and the value of =.Last.value= in R).
|
|
|
|
@subsubsection =:results output=
|
|
The code is passed to the interpreter running as an interactive
|
|
Emacs inferior process. The result returned is the concatenation
|
|
of the sequence of (text) output from the interactive
|
|
interpreter. Notice that this is not necessarily the same as what
|
|
would be sent to stdout if the same code were passed to a
|
|
non-interactive interpreter running as an external process. For
|
|
example, compare the following two blocks:
|
|
|
|
|
|
@example
|
|
#+begin_src python :results output
|
|
print "hello"
|
|
2
|
|
print "bye"
|
|
#+end_src
|
|
|
|
#+resname:
|
|
: hello
|
|
: bye
|
|
@end example
|
|
|
|
In non-session mode, the '2' is not printed and does not appear.
|
|
@example
|
|
#+begin_src python :results output :session
|
|
print "hello"
|
|
2
|
|
print "bye"
|
|
#+end_src
|
|
|
|
#+resname:
|
|
: hello
|
|
: 2
|
|
: bye
|
|
@end example
|
|
|
|
But in =:session= mode, the interactive interpreter receives input '2'
|
|
and prints out its value, '2'. (Indeed, the other print statements are
|
|
unnecessary here).
|
|
|
|
@section Noweb Reference Syntax
|
|
:PROPERTIES:
|
|
:CUSTOM_ID: noweb-reference-syntax
|
|
:END:
|
|
|
|
The [[http://www.cs.tufts.edu/~nr/noweb/][Noweb]] Literate Programming system allows named blocks of code to
|
|
be referenced by using the familiar Noweb syntax:
|
|
: <<code-block-name>>
|
|
|
|
Noweb references are handled differently during evaluation and
|
|
tangling.
|
|
|
|
When a document is tangled, Noweb references are replaced with the
|
|
named source code block.
|
|
|
|
When a source code block is evaluated, the action depends upon the
|
|
value of the =:noweb= header argument. If =:noweb yes=, then a
|
|
Noweb reference is expanded before evaluation. If =:noweb no=,
|
|
the default, then the reference is not expanded before
|
|
evaluation.
|
|
|
|
*Note:* the default value, =:noweb no=, was chosen to ensure that
|
|
Org-babel does not break correct code in a language, such as Ruby,
|
|
where =<<arg>>= is a syntactically valid construct. If =<<arg>>= is
|
|
not syntactically valid in languages that you use, then please
|
|
consider [[*System%20wide][setting the default value]].
|
|
|
|
An example that uses the Noweb reference syntax is provided in the
|
|
[[literate programming example]].
|
|
|
|
@section Key Bindings & Useful Functions
|
|
|
|
Org-babel re-binds many common Org-mode key sequences depending on
|
|
the context. Within a source-code block the following sequences
|
|
are rebound:
|
|
| =C-c C-c= | [[function-org-babel-execute][org-babel-execute-src-block]] |
|
|
| =C-c C-o= | [[function-org-babel-open-src-block-result][org-babel-open-src-block-result]] |
|
|
| =C-up= | [[function-org-babel-load-in-session][org-babel-load-in-session]] |
|
|
| =M-down= | [[function-org-babel-pop-to-session][org-babel-pop-to-session]] |
|
|
|
|
Org-babel also exposes a number of functions behind the common
|
|
=org-babel-key-prefix= of =C-c M-b=:
|
|
@example
|
|
#+begin_src emacs-lisp :exports none
|
|
(lambda (binding
|
|
(list (format "\\C-c \\M-b %s"
|
|
(car binding))
|
|
(format "[[function-%s][%s]]"
|
|
(cdr binding) (cdr binding))))
|
|
org-babel-key-bindings)
|
|
#+end_src
|
|
@end example
|
|
|
|
| =C-c M-b t= | [[function-org-babel-tangle][org-babel-tangle]] |
|
|
| =C-c M-b T= | [[function-org-babel-tangle-file][org-babel-tangle-file]] |
|
|
| =C-c M-b e= | [[function-org-babel-execute-src-block][org-babel-execute-src-block]] |
|
|
| =C-c M-b s= | [[function-org-babel-execute-subtree][org-babel-execute-subtree]] |
|
|
| =C-c M-b b= | [[function-org-babel-execute-buffer][org-babel-execute-buffer]] |
|
|
| =C-c M-b h= | [[function-org-babel-sha1-hash][org-babel-sha1-hash]] |
|
|
| =C-c M-b g= | [[function-org-babel-goto-named-source-block][org-babel-goto-named-source-block]] |
|
|
| =C-c M-b l= | [[function-org-babel-lob-ingest][org-babel-lob-ingest]] |
|
|
|
|
@subsection Functions
|
|
@subsubsection org-babel-execute-src-block
|
|
:PROPERTIES:
|
|
:CUSTOM_ID: function-org-babel-execute-src-block
|
|
:END:
|
|
|
|
@example
|
|
org-babel-execute-src-block is an interactive Lisp function in
|
|
`org-babel.el'.
|
|
|
|
(org-babel-execute-src-block &optional ARG INFO PARAMS)
|
|
|
|
Execute the current source code block, and insert the results
|
|
into the buffer. Source code execution and the collection and
|
|
formatting of results can be controlled through a variety of
|
|
header arguments.
|
|
|
|
Optionally supply a value for INFO in the form returned by
|
|
`org-babel-get-src-block-info'.
|
|
|
|
Optionally supply a value for PARAMS which will be merged with
|
|
the header arguments specified at the front of the source code
|
|
block.
|
|
@end example
|
|
|
|
@subsubsection org-babel-open-src-block-result
|
|
:PROPERTIES:
|
|
:CUSTOM_ID: function-org-babel-open-src-block-result
|
|
:END:
|
|
|
|
@example
|
|
org-babel-open-src-block-result is an interactive Lisp function in
|
|
`org-babel.el'.
|
|
|
|
(org-babel-open-src-block-result &optional RE-RUN)
|
|
|
|
If `point' is on a src block then open the results of the
|
|
source code block, otherwise return nil. With optional prefix
|
|
argument RE-RUN the source-code block is evaluated even if
|
|
results already exist.
|
|
@end example
|
|
|
|
@subsubsection org-babel-load-in-session
|
|
:PROPERTIES:
|
|
:CUSTOM_ID: function-org-babel-load-in-session
|
|
:END:
|
|
|
|
@example
|
|
org-babel-load-in-session is an interactive Lisp function in
|
|
`org-babel.el'.
|
|
|
|
(org-babel-load-in-session &optional ARG INFO)
|
|
|
|
Load the body of the current source-code block. Evaluate the
|
|
header arguments for the source block before entering the
|
|
session. After loading the body this pops open the session.
|
|
|
|
[back]
|
|
@end example
|
|
|
|
@subsubsection org-babel-pop-to-session
|
|
:PROPERTIES:
|
|
:CUSTOM_ID: function-org-babel-pop-to-session
|
|
:END:
|
|
|
|
@example
|
|
org-babel-pop-to-session is an interactive Lisp function in
|
|
`org-babel.el'.
|
|
|
|
(org-babel-pop-to-session &optional ARG INFO)
|
|
|
|
Pop to the session of the current source-code block. If
|
|
called with a prefix argument then evaluate the header arguments
|
|
for the source block before entering the session. Copy the body
|
|
of the source block to the kill ring.
|
|
|
|
[back]
|
|
@end example
|
|
|
|
@subsubsection org-babel-tangle
|
|
:PROPERTIES:
|
|
:CUSTOM_ID: function-org-babel-tangle
|
|
:END:
|
|
|
|
@example
|
|
org-babel-tangle is an interactive Lisp function in
|
|
`org-babel-tangle.el'.
|
|
|
|
It is bound to C-c M-b t.
|
|
|
|
(org-babel-tangle &optional TARGET-FILE LANG)
|
|
|
|
Extract the bodies of all source code blocks from the current
|
|
file into their own source-specific files. Optional argument
|
|
TARGET-FILE can be used to specify a default export file for all
|
|
source blocks. Optional argument LANG can be used to limit the
|
|
exported source code blocks by language.
|
|
@end example
|
|
|
|
@subsubsection org-babel-execute-subtree
|
|
:PROPERTIES:
|
|
:CUSTOM_ID: function-org-babel-execute-subtree
|
|
:END:
|
|
|
|
@example
|
|
org-babel-execute-subtree is an interactive Lisp function in
|
|
`org-babel.el'.
|
|
|
|
It is bound to C-c M-b s.
|
|
|
|
(org-babel-execute-subtree &optional ARG)
|
|
|
|
Replace EVAL snippets in the entire subtree.
|
|
@end example
|
|
|
|
@subsubsection org-babel-execute-buffer
|
|
:PROPERTIES:
|
|
:CUSTOM_ID: function-org-babel-execute-buffer
|
|
:END:
|
|
|
|
@example
|
|
org-babel-execute-buffer is an interactive Lisp function in
|
|
`org-babel.el'.
|
|
|
|
It is bound to C-c M-b b.
|
|
|
|
(org-babel-execute-buffer &optional ARG)
|
|
|
|
Replace EVAL snippets in the entire buffer.
|
|
@end example
|
|
|
|
@subsubsection org-babel-sha1-hash
|
|
:PROPERTIES:
|
|
:CUSTOM_ID: function-org-babel-sha1-hash
|
|
:END:
|
|
|
|
@example
|
|
org-babel-sha1-hash is an interactive Lisp function in `org-babel.el'.
|
|
|
|
It is bound to C-c M-b h.
|
|
|
|
(org-babel-sha1-hash &optional INFO)
|
|
|
|
Not documented.
|
|
@end example
|
|
|
|
@subsubsection org-babel-goto-named-source-block
|
|
:PROPERTIES:
|
|
:CUSTOM_ID: function-org-babel-goto-named-source-block
|
|
:END:
|
|
|
|
@example
|
|
org-babel-goto-named-source-block is an interactive Lisp function in
|
|
`org-babel.el'.
|
|
|
|
It is bound to C-c M-b g.
|
|
|
|
(org-babel-goto-named-source-block &optional NAME)
|
|
|
|
Go to a named source-code block.
|
|
@end example
|
|
|
|
@subsubsection org-babel-lob-ingest
|
|
:PROPERTIES:
|
|
:CUSTOM_ID: function-org-babel-lob-ingest
|
|
:END:
|
|
|
|
@example
|
|
org-babel-lob-ingest is an interactive Lisp function in
|
|
`org-babel-lob.el'.
|
|
|
|
It is bound to C-c M-b l.
|
|
|
|
(org-babel-lob-ingest &optional FILE)
|
|
|
|
Add all source-blocks defined in FILE to `org-babel-library-of-babel'.
|
|
@end example
|
|
|
|
@section Batch Execution
|
|
It is possible to call Org-babel functions from the command line.
|
|
This shell script calls [[function-org-babel-tangle][org-babel-tangle]] on every one of its
|
|
arguments.
|
|
|
|
Be sure to adjust the paths to fit your system.
|
|
@example
|
|
#!/bin/sh
|
|
# -*- mode: shell-script -*-
|
|
#
|
|
# tangle a file with org-babel
|
|
#
|
|
DIR=`pwd`
|
|
FILES=""
|
|
|
|
# wrap each argument in the code required to call tangle on it
|
|
for i in $@@; do
|
|
FILES="$FILES \"$i\""
|
|
done
|
|
|
|
emacsclient \
|
|
--eval "(progn
|
|
(add-to-list 'load-path (expand-file-name \"~/src/org/lisp/\"))
|
|
(add-to-list 'load-path (expand-file-name \"~/src/org/contrib/lisp/\"))
|
|
(require 'org)(require 'org-exp)(require 'org-babel)
|
|
(mapc (lambda (file)
|
|
(find-file (expand-file-name file \"$DIR\"))
|
|
(org-babel-tangle)
|
|
(kill-buffer)) '($FILES)))"
|
|
@end example
|
|
|
|
@section Footnotes
|
|
|
|
[fn:1] The former use of the =shell= identifier is now deprecated.
|
|
|
|
[fn:2] As long as the interpreter executable is found on the remote
|
|
machine: see the variable =tramp-remote-path=
|