Org-babel: Reference

System-wide values of header arguments can be specified by customizing the org-babel-default-header-args variable:

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.

#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.

(setq org-babel-default-header-args
      (cons '(:noweb . "yes")
            (assq-delete-all :noweb org-babel-default-header-args)))

Header arguments are also read from Org-mode properties. An example of setting a header argument for all code blocks in a buffer is

#+property: tangle yes

Properties can also be set at the outline heading 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 heading:

* outline heading
  :PROPERTIES:
  :cache:    yes
  :CUSTOM_ID: property-set-header-arguments
  :END:

Properties defined in this way override buffer-wide properties, and 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.

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.

#+source: factorial
#+begin_src haskell :results silent :exports code
  fac 0 = 1
  fac n = n * fac (n-1)
#+end_src

Output header arguments change the content of output in a range of situations.

• :results
  

  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.

  • collection
    The following options are mutually exclusive, and specify how the results should be collected from the code block. The exact behavior depends on whether or not the code block is executed in a session.

    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.

    • Interaction with :session
      

      The specific way in which results are handled depends on whether a session is invoked, as well as on whether :results value or :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.

      • Non-session
        
        • :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.

        • :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.)
      • :session
        
        • :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).
        • :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:

          print "hello"
          2
          print "bye"
          

          hello
          bye
          

          In non-session mode, the '2' is not printed and does not appear.

          print "hello"
          2
          print "bye"
          

          hello
          2
          bye
          

          But in :session mode, the interactive interpreter receives input '2' and prints out its value, '2'. (Indeed, the other print statements are unnecessary here).

  • 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.

  • 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.

• :file
  

  :file is used to specify a path for file output in which case an org style file: link is inserted into the buffer as the result. Common examples are graphical output from R, gnuplot, ditaa and latex blocks.

  See the :dir and remote execution section for examples.

  Note that for some languages, including R, gnuplot, 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.

  The :file header argument can be used to specify the full path to the output file, but it is sometimes more convenient to specify a path relative to the default directory, which can be set with the :dir header argument.

• :exports
  

  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.

• :tangle
  

  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.

Execution header arguments change how a code block executes.

• :dir and remote execution
  :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 and :file, supply a relative path for file output (e.g. :file myfile.jpg or :file results/myfile.jpg). The path passed to :file will be interpreted relative to the path specified by :dir..

  For example, to write myplot.png to a folder called Work in the user's home directory:

  #+begin_src R :file myplot.png :dir ~/Work
  matplot(matrix(rnorm(100), 10), type="l")
  #+end_src
  

  • Remote execution
    A directory on a remote machine can be specified passing an argument in tramp filename syntax to :dir. In this case, the code block will be executed on the remote machine.² For example, the following code block will execute the machine at yakuba.princeton.edu:

    #+begin_src R :file plot.png :dir /dand@yakuba.princeton.edu:
      plot(1:10, main=system("hostname", intern=TRUE))
    #+end_src
    

    Results of the remote execution will be returned to the local org buffer. File output will be created on the remote machine with a path interpreted relative to the remote directory specified by :dir. In addition, a link to the remote file will be created in the Org-mode buffer. Following on the example, a plot will be created on the remote machine, and a link of the following form will be inserted in the org buffer:

    [[file:/scp:dand@yakuba.princeton.edu:/home/dand/plot.png][plot.png]]
    

    Most of this functionality follows immediately from the fact that :dir sets the value of the emacs variable default-directory, thanks to tramp.³

  • Further points
    
    • When :dir is used in conjunction with :session it will determine the starting directory for a new session as expected, but no attempt is 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 is probable that the file will be created in a location to which the link does not point.
• :var
  

  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 argument indexing.

  The following syntax is used to pass arguments to source code blocks using the :var header argument.

  :var name=assign
  

  where assign can take one of the following forms

  literal value

  either a string ="string"= or a number 9.

  reference

  a table name:

  #+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
  

  a source code block name, as assigned by #+srcname:, followed by parentheses:

  #+begin_src emacs-lisp :var length=table-length()
    (* 2 length)
  #+end_src
  
  #+results:
  : 8
  

  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:

  #+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
  

  • alternate argument syntax
    

    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.

    #+source: double(input=0)
    #+begin_src emacs-lisp
      (* 2 input)
    #+end_src
    

  • indexable variable values
    

    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:

    :var data=example-table[1:2]
    

    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:

    :var data=example-table[0,1]
    

    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.

    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.
    

    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.

• :session
  

  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.

• :noweb
  

  Controls the expansion of 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 syntax specific action is taken on evaluating source code blocks/ However, noweb references will still be expanded during tangling.

  yes

  all noweb syntax references in the body of the source code block will be expanded before the block is evaluated.

  • 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>>
    

    expands to:

    -- this is the
    -- multi-line body of 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.

• :cache
  

  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.

• :no-expand
  By default, code blocks are expanded on tangling, so that referenced data is assigned to variables in the tangled code. :no-expand can be used to turn off this behaviour.

Languages supported by Org-babel represent and process tabular data in various ways. Org-babel uses header arguments to manage the process of translating Org-mode tables to and from supported languages.

• :hlines
  Tables are frequently represented with one or more horizontal lines, or hlines. The :hlines argument to an Org-babel code block accepts the values yes or no, with a default value of -no=.

  no

  Strips hlines from the input table. In most languages this is the desired effect because an 'hline symbol is interpreted as an unbound variable and raises an error. Setting :hlines no or relying on the default value yields the following results.

  #+tblname: many-cols
  | a | b | c |
  |---+---+---|
  | d | e | f |
  |---+---+---|
  | g | h | i |
  
  #+source: echo-table
  #+begin_src python :var tab=many-cols
    return tab
  #+end_src
  
  #+results: echo-table
  | a | b | c |
  | d | e | f |
  | g | h | i |
  

  yes

  Leaves hlines in the table. This is the default for emacs-lisp which may want to handle 'hline symbols explicitly.

• :colnames
  The :colnames header argument accepts the values yes, no, or nil for unassigned. The default value is nil.

  nil

  If an input table looks like it has column names (because its second row is an hline), then the column names will be removed from the table by Org-babel before processing, then reapplied to the results.

  #+tblname: less-cols
  | a |
  |---|
  | b |
  | c |
    
  #+srcname: echo-table-again
  #+begin_src python :var tab=less-cols
    return [[val + '*' for val in row] for row in tab]
  #+end_src
  
  #+results: echo-table-again
  | a  |
  |----|
  | b* |
  | c* |
  

  no

  No column name pre-processing takes place

  yes

  Column names are removed and reapplied as with nil even if the table does not look like it has column names (i.e. the second row is not an hline)

• :rownames ⁵
  The :rownames header argument can take on the values yes or no, with a default value of no.

  no

  No row name pre-processing will take place.

  yes

  The first column of the table is removed from the table by Org-babel before processing, and is then reapplied to the results.

  #+tblname: with-rownames
  | one | 1 | 2 | 3 | 4 |  5 |
  | two | 6 | 7 | 8 | 9 | 10 | 
  
  #+srcname: echo-table-once-again
  #+begin_src python :var tab=with-rownames :rownames yes
    return [[val + 10 for val in row] for row in tab]            
  #+end_src
  
  #+results: echo-table-once-again
  | one | 11 | 12 | 13 | 14 | 15 |
  | two | 16 | 17 | 18 | 19 | 20 |
  

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.

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.

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.

org-babel-expand-src-block is an interactive Lisp function in
`org-babel.el'.

It is bound to C-c C-v C-p.

(org-babel-expand-src-block &optional ARG INFO PARAMS)

Expand the current source code block according to it's header
arguments, and pop open the results in a preview buffer.

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.

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]

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'.

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.

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]

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.

    org-babel-switch-to-session is an interactive Lisp function in
`org-babel.el'.

It is bound to C-c C-v C-z.

(org-babel-switch-to-session &optional ARG INFO)

Switch 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.

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.