Org mode basically just runs the code every time you export the document. But,
if you’ve changed some code and want a refresh, you can press C-c C-v C-b
and
it will run it for sure then.
Embedding code blocks
A code block is some sort of subprogram which does the desired job.
Defining a code block
You can define and call it at the same time: the code block definition itself acts as an implicit call.
Syntax
The code block is a block element which can be anonymous (without a label) or named (with a label).
#+name: <LABEL>
#+begin_src <LANGUAGE> <HEADER-ARGS>
<BODY>
#+end_src
Anonymous code blocks will be immediately followed by the results block upon evaluation.
printf "I'm anonymous"
I'm anonymous
Named source code blocks will refresh the corresponding named results blocks anywhere in the file.
printf "As I'm named, my results may live anywhere in the file."
It doesn’t matter whether the code block and the results block are “disconnected”, such as here, as the results is a named data which Babel can locate.
As I'm named, my results may live anywhere in the file.
The name can be 20 characters long, and contain…XXX
Language
The following language strings are currently recognized:
Awk, C, R, Asymptote, Calc, Clojure, CSS, Ditaa, Dot, Emacs Lisp, Forth, Fortran, Gnuplot, Haskell, IO, J, Java, Javascript, LaTeX, Ledger, Lilypond, Lisp, Makefile, Maxima, Matlab, Mscgen, Ocaml, Octave, Org, Perl, Pico Lisp, PlantUML, Python, Ruby, Sass, Scala, Scheme, Screen, Shell Script, Shen, Sql, Sqlite, ebnf2ps.
You can also add support for new languages:
(add-to-list 'org-src-lang-modes '("<LANGUAGE>" . "<MAJOR-MODE>"))
so that font lock and editing source do work.
XXX Currently, a bash
code block will be run with bash
, and a shell
code block will
be run with sh
. Both will use shell-script-mode
. XXX
Code block arguments
You can create a code block with optional parameters by specifying a default value for optional parameters. When the code block is executed, the default value is used if no other value has been specified in the call.
The way to define arguments is to declare them on the #+begin_src
line.
(* 2 x)
Specifying default values is necessary because each variable must be initialized when the code block is executed.
If the variable semantics vary by language (as they do), just say so (e.g. when defining a SQL function, vars are substituted into the body by prefixing the names with $, but in python they are local vars in non-session mode and global vars in session mode and so on. Maybe this doc section shouldn’t try to enumerate all those languages, but just redirect to the proper Worg Babel language page for details on arg handling.
Pass by value.
-
Keyword arguments
-
Default arguments
Scope of Variables
-
Global variables
-
Local variables
Remarks
(setq org-babel-min-lines-for-block-output 10)
(print 1)
(setq org-babel-min-lines-for-block-output 0)
(print 1)
Examples
-
Using :headers
Code can (possibly) be easier to read/write when splitting header arguments among multiple lines, by writing the options above the code block.
#+header: :file test.png :fit yes #+header: :imagemagick yes :iminoptions -density 600 :imoutoptions -geometry 400 #+header: :results (if (and (boundp 'backend) (eq backend 'latex)) "latex" "file") #+begin_src latex :exports results :noweb yes :headers '("\\usepackage{tikz}") \begin{tikzpicture} \node[red!50!black] (a) {A}; \node (b) [right of=a] {B}; \draw[->] (a) -- (b); \end{tikzpicture} #+end_src
-
Do stuff conditional to the export backend
Maybe you could do something like the following…
(message "do stuff")
-
Backend-conditional results
You can replace
(:results . "html")
with
(:results . (or (and org-export-current-backend "html") "none"))
in the
defvar
to get the desired result. -
Cross-referencing a results block
+results are never used for cross-references. This is a Babel internal
keyword used to refer to the source that generated this element.
Cross-references only react to #+name keyword.
Sorry, this is confusing. Is it then the case that we are naming the source block to ensure that captions stick to the corresponding results block?
Source block captions apply to the source block, not to the results. You have to define a separate caption for the results.
Source block name will be used both as a label for cross referencing and as a Babel internal code for results correspondence.
And then, we need to separately name the results block, and use a different name for it, so that the cross-references pick it up correctly?
Yes, the name given to the results block doesn’t depend on the results keyword. You can give it any name, as long as it is unique.
Here is an example:
(+ 1 2)
-
Other explanation
You need to apply
caption
andname
keywords on the results, not the source code.
Calling a code block
You can define a code block somewhere and then call it explicitly elsewhere
— provided the code block has a #+name:
meta data to label it.
Syntax
#+call:
is for standalone lines: it lives on a block by itself.
A #+call:
line can be named, in order for its results (for the arguments used)
to be referenced.
It has the following syntax, where each header argument portion is optional.
#+name: <CALL-LINE-NAME>
#+call: <NAME>[<HEADER-ARGS-FOR-BLOCK>](<ARGUMENTS>) <HEADER-ARGS-FOR-CALL-LINE>
-
NAME: Name of the code block to be evaluated.
-
ARGUMENTS: XXX Describe how to pass args.
-
HEADER-ARGS-FOR-BLOCK (“inside header argument”): Header arguments applied to the evaluation of the code block. They affect how the code block is evaluated: they change the inputs.
For example,
:session *org-R*
or:results output
. -
HEADER-ARGS-FOR-CALL-LINE (“end header argument”): Header arguments applied to the evaluation of the #+call: line. They do not affect evaluation of the named code block; instead, they affect how the results are incorporated into the Org mode buffer.
For example,
:exports results
or:results html
.
Remarks
#+call:
lines recently got #+names
, hopefully soon they will get #+header
arguments as well.
Press C-c C-v C-e
on the call line to execute the block.
When evaluating a call line, it is converted into an ephemeral Emacs Lisp code block equivalent to the call line (and created at the point of the call line):
#+begin_src emacs-lisp :var result=<NAME>(<ARGUMENTS>) <HEADER-ARGS-FOR-BLOCK>
, result
#+end_src
which is evaluated in place.
The result of the called function is passed into this ephemeral block, and the output of the block is inserted into the buffer.
This is why call lines have two possible sets of header arguments:
- one to pass header arguments to the original code block being called, and
-
one for local effect in the ephemeral block.
Advice (from Rick Frankel): As to the “call” lines, think of the output of the “called” block as being input to an anonymous block (the #+call), so the hlines are stripped.
Code blocks are sometimes located in a separate file (called “library of Babel”) which can be included in other Org files that wish to use the code blocks.
The result of named code blocks evaluated with a #+call:
line is wrapped
according to the value of org-babel-inline-result-wrap
, which by default is
"=%s="
for markup that produces verbatim text.
Examples
-
Relying on the default value of the arguments
-
Providing explicit values to the arguments
#+call: foo(bar=1)
is equivalent to
#+begin_src emacs-lisp :var results=foo(bar=1) , results #+end_src
-
Recursive
(+ x 1) 5 7 11
-
Other
It is possible to pass the
:dir
header argument through a call line.pwd
Call the above from somewhere else.
/
-
Call by name
Let’s assume, the original code block takes an argument.
echo "input=$input"
If I want to “get rid of” that argument (to avoid typing), I can to name the result of calling that code block with a specific argument.
input=new
As
#+call:
lines can be named, it is possible to reference that result.echo "this=$input"
See how to name the results of a function call and reuse them.
-
Raw results
+call: org-figure-to-slide:exports none :results raw
Does the following call line do what you want?
+call: org-figure-to-slide() :results raw
No square bracket for the “end header arguments”!Thanks for your quick answer. Nevertheless, adding :results raw at the end changes the formatting output but embeds everything within paren. Given your advice, I am pretty closed to what I want to do by adding another :results raw command either as an inside header arguments or directly when declaring the
org-figure-to-slide
code like# ...
Calling a code block from other elements
Using the org-sbe
(for “source block evaluate”) macro, you may call arbitrary
code blocks
- in a table formula,
- in file local variables,
- inside of an elisp link, or
- in any header argument.
Syntax
Return the results of calling NAME
with VARIABLES
.
(org-sbe <NAME> <VARIABLES>)
Don’t quote the NAME
(or, optionally, double quote it).
Each element of VARIABLES
should be a two element list, whose
- first element is the name of the variable and
- second element is a string of its value.
By default, string variable names are interpreted as references to source-code
blocks. To force interpretation of a cell’s value as a string, prefix the
identifier with a $
(e.g., $$2
instead of $2
or $@2$2
instead of
@2$2
).
In order to differentiate between strings and reference names, we surround all strings in double quotes…
From Re: {Orgmode} {babel} passing strings in - msg#00651 - emacs-orgmode-gnu
… or double the $ sign: $$1
(-
;; length w/o .el
(- 13 (length ".el"))
;; length of prefix
(length prefix))
prefix | remaining characters |
---|---|
ob- | nil |
org-b- | nil |
orgb- | nil |
org-bbl- | nil |
bbl- | nil |
babel- | nil |
Remarks
(org-sbe NAME (n $2) (m 3))
The preceding call to org-sbe
is equivalent to the following source code block.
#+begin_src emacs-lisp :var results=NAME(n=val_at_col_2, m=3) :results silent
results
#+end_src
There is no way to map a code block over the rows of a table. You could
use the org-sbe
macro and a spreadsheet formula to call a code block on
multiple table cells, but the results would be inserted back into the table.
A | nil |
B | nil |
eric | nil |
schulte | nil |
(format "-->%s<--" in)
Also remember you can use ELisp in formulas:
Date 1 | Date 2 | Duration |
---|---|---|
86400.0 |
Note the quotes around “$2” and “$1”, they are necessary so that the date is not literally inserted in the formulas when Org is computing it.
-
Tangle the results of a code blocks
To tangle #+RESULTS: block, name the block:
(+ 1 2)
and use:
nil
Examples
-
Calling a code block in a table formula, relying on the default value of the arguments
-
Calling a code block in a table formula, providing explicit values to the arguments
(let ((num (car l)) (nums (cdr l))) (/ (float (+ num (apply #'+ nums))) (1+ (length nums))))
x y z mean 2 3 5 0.00 -
Passing header arguments
It is also possible to pass header arguments to the code block. In this case, a table cell should hold the string value of the header argument which can then be passed before all variables.
(+ x y)
1 2 :file nothing.png nil -
Using
org-sbe
in a local variables lineYou can run some preparatory code (in any language) when the file is opened for the first time by using
(org-sbe NAME)
(whereNAME
is a double-quoted string) in Local Variables lines, at the end of the Org file.#+name: init #+begin_src R :session *R* # initialize some stuff #+end_src # Local variables: # eval: (org-sbe "init") # End:
Emacs will evaluate the set-up block(s), after asking for confirmation.
-
Using
org-sbe
inside of an elisp linkfor i in $(seq 1 $to); do printf $i; done
Clicking on the following hyperlink will execute the code block.
[[elisp:(org-sbe counter (to "3"))][count to 3]]
-
Using
org-sbe
to assign header argumentsYou can use arbitrary Lisp forms to assign header arguments. For example, to dynamically compute the file name.
The following generates a file which is conditional to the export target:
- a
.pdf
image for LaTeX export and -
a
.png
image for HTML export.(if (and (boundp 'latexp) latexp) "Rplots.pdf" "Rplots.png")
x <- seq(-pi, pi, by=0.05) plot(x, sin(x))
rev-3.14
x <- seq(-pi, pi, by=0.05) plot(x, sin(x))
The following works great. (note the tick in the
(boundp 'backend)
).And you could wrap up the extra-long Emacs Lisp in a function or macro in your init to avoid the overlength header argument.
- a
Embedding inline code
You can also evaluate code inline as follows.
Inline code blocks
An inline code block (a.k.a. inline source block) is a code block which is placed inline within textual elements such as paragraphs of text or lists.
Its sole purpose is to include results inline in textual elements.
Syntax
The basic syntax structure for inline code blocks is:
src_<LANGUAGE>{<BODY>}
without header arguments, and:
src_<LANGUAGE>[<HEADER-ARGS>]{<BODY>}
with header arguments.
Remarks
-
Inline code blocks don't associate themselves with their results, they are only expected to be evaluated during export. They are not intended to be executed in the buffer during normal use.
-
Inline code blocks are treated just like code blocks, however they have different default header arguments: see
org-babel-default-inline-header-args
. -
If you set the following
(setq org-babel-inline-result-wrap "$%s$")
then inline code snippets will be wrapped into the formatting string.
-
Currently, inline code blocks are not fontified even when
org-src-fontify-natively
is non-nil. -
Inline code block results are replaceable (i.e., removable) – since commit
85ff663
, on – if they is wrapped in a{{{results(.*)}}}
macro call.Insert current value in
results
macro possibly wrapping RESULT in an export snippet or inline code block first.
Examples
This file was exported on .
The answer to 2 + 3 is .
One plus one equals .
Two plus two equals .
A definition returns “”.
The following code and its result src_emacs-lisp[:exports both]{(message “foo!”)} should be inline.
The following eval `cat ~/.emacs`;
should also be
inline.
Ibid for (let ((x 10)) (< (* x 3) 2))
and
(message "foo!\nbar!")
(as expected?).
Inline Babel calls
Syntax
The syntax for inline evaluation of named code blocks is the following, where each header argument portion is optional (so are the square brackets).
... call_<NAME>(<ARGUMENTS>) ...
... call_<NAME>[<HEADER-ARGS-FOR-BLOCK>](<ARGUMENTS>)[<HEADER-ARGS-FOR-CALL-LINE>] ...
Remarks
-
The result of named code blocks evaluated inline within a block of text is wrapped according to the value of
org-babel-inline-result-wrap
, which by default is"=%s="
for markup that produces verbatim text.
-
When using
:results raw
, you can use properties so that thecall_foo()
part stays a reasonable length:* Description of the Hawaiian Stone Axes Here is a call_square(x=4), stuck in the middle of some prose.
-
Babel call results are also replaceable.
Examples
Simple examples for inline call:
(* x x)
I should be able to put the output inline using .
Here is a , stuck in the middle of some prose.
The following exports as a normal call line:
Now here is an inline call stuck in the middle of some prose.
This one should not be exported call_square(x=2)
because it is quoted.
Finally this next one should export, even though it starts a line because sometimes inline blocks fold with a paragraph.
And, a call with raw results should not have quoted results.
)
Final alternative: here is a , from an inline source block.
-
Similar code in three languages
(+ 1 1) expr 1 + 1 1 + 1
Will lisp-2 export with a newline?
Will shell-2 export with a newline?
Will r-2 export with a newline?