Tom's documentation updates for the new code block syntax
This commit is contained in:
Eric Schulte
parent
1ed12cac1a
commit
a3f781be12
478
doc/org.texi
478
doc/org.texi
|
|
@ -11651,19 +11651,26 @@ The following sections describe Org-mode's code block handling facilities.
|
|||
@section Structure of code blocks
|
||||
@cindex code block, structure
|
||||
@cindex source code, block structure
|
||||
@cindex #+NAME
|
||||
@ciindex #+BEGIN_SRC
|
||||
|
||||
The structure of code blocks is as follows (empty code blocks may be inserted
|
||||
using Org-mode's @ref{Easy Templates} system):
|
||||
Live code blocks can be specified with a @samp{src} block or
|
||||
inline@footnote{Note that @samp{src} blocks may be inserted using Org-mode's
|
||||
@ref{Easy Templates} system}. The structure of a @samp{src} block is
|
||||
|
||||
@example
|
||||
#+srcname: <name>
|
||||
#+begin_src <language> <switches> <header arguments>
|
||||
#+NAME: <name>
|
||||
#+BEGIN_SRC <language> <switches> <header arguments>
|
||||
<body>
|
||||
#+end_src
|
||||
#+END_SRC
|
||||
@end example
|
||||
|
||||
Switches and header arguments are optional. Code can also be embedded in text
|
||||
inline using
|
||||
The @code{#+NAME:} line is optional, and can be used to name the code
|
||||
block. Live code blocks require that a language be specified on the
|
||||
@code{#+BEGIN_SRC} line. Switches and header arguments are optional.
|
||||
@cindex source code, inline
|
||||
|
||||
Live code blocks can also be specified inline using
|
||||
|
||||
@example
|
||||
src_<language>@{<body>@}
|
||||
|
|
@ -11676,26 +11683,30 @@ src_<language>[<header arguments>]@{<body>@}
|
|||
@end example
|
||||
|
||||
@table @code
|
||||
@item <name>
|
||||
This name is associated with the code block. This is similar to the
|
||||
@samp{#+tblname} lines that can be used to name tables in Org-mode files.
|
||||
Referencing the name of a code block makes it possible to evaluate the
|
||||
block from other places in the file, other files, or from Org-mode table
|
||||
formulas (see @ref{The spreadsheet}). Names are assumed to be unique by
|
||||
evaluation functions and the behavior of multiple blocks of the same name is
|
||||
@item <#+NAME: name>
|
||||
This line associates a name with the code block. This is similar to the
|
||||
@code{#+TBLNAME: NAME} lines that can be used to name tables in Org-mode
|
||||
files. Referencing the name of a code block makes it possible to evaluate
|
||||
the block from other places in the file, from other files, or from Org-mode
|
||||
table formulas (see @ref{The spreadsheet}). Names are assumed to be unique
|
||||
and the behavior of Org-mode when two or more blocks share the same name is
|
||||
undefined.
|
||||
@cindex #+NAME
|
||||
@item <language>
|
||||
The language of the code in the block.
|
||||
The language of the code in the block (see @ref{Languages}).
|
||||
@cindex source code, language
|
||||
@item <switches>
|
||||
Optional switches controlling exportation of the code block (see switches discussion in
|
||||
Optional switches control code block export (see the discussion of switches in
|
||||
@ref{Literal examples})
|
||||
@cindex source code, switches
|
||||
@item <header arguments>
|
||||
Optional header arguments control many aspects of evaluation, export and
|
||||
tangling of code blocks. See the @ref{Header arguments}.
|
||||
tangling of code blocks (see @ref{Header arguments}).
|
||||
Header arguments can also be set on a per-buffer or per-subtree
|
||||
basis using properties.
|
||||
@item source code, header arguments
|
||||
@item <body>
|
||||
The source code.
|
||||
Source code in the specified language.
|
||||
@end table
|
||||
|
||||
@comment node-name, next, previous, up
|
||||
|
|
@ -11744,12 +11755,12 @@ variable @code{org-src-fontify-natively}.
|
|||
@cindex code block, exporting
|
||||
@cindex source code, exporting
|
||||
|
||||
It is possible to export the @emph{contents} of code blocks, the
|
||||
@emph{results} of code block evaluation, @emph{neither}, or @emph{both}. For
|
||||
most languages, the default exports the contents of code blocks. However, for
|
||||
some languages (e.g.@: @code{ditaa}) the default exports the results of code
|
||||
block evaluation. For information on exporting code block bodies, see
|
||||
@ref{Literal examples}.
|
||||
It is possible to export the @emph{code} of code blocks, the @emph{results}
|
||||
of code block evaluation, @emph{both} the code and the results of code block
|
||||
evaluation, or @emph{none}. For most languages, the default exports code.
|
||||
However, for some languages (e.g.@: @code{ditaa}) the default exports the
|
||||
results of code block evaluation. For information on exporting code block
|
||||
bodies, see @ref{Literal examples}.
|
||||
|
||||
The @code{:exports} header argument can be used to specify export
|
||||
behavior:
|
||||
|
|
@ -11827,14 +11838,15 @@ of tangled code files.
|
|||
@cindex source code, evaluating
|
||||
|
||||
Code blocks can be evaluated@footnote{Whenever code is evaluated there is a
|
||||
potential for that code to do harm. Org-mode provides a number of safeguards
|
||||
to ensure that it only evaluates code with explicit confirmation from the
|
||||
user. For information on these safeguards (and on how to disable them) see
|
||||
@ref{Code evaluation security}.} and the results placed in the Org-mode
|
||||
buffer. By default, evaluation is only turned on for @code{emacs-lisp} code
|
||||
blocks, however support exists for evaluating blocks in many languages. See
|
||||
@ref{Languages} for a list of supported languages. See @ref{Structure of
|
||||
code blocks} for information on the syntax used to define a code block.
|
||||
potential for that code to do harm. Org-mode provides safeguards to ensure
|
||||
that code is only evaluated after explicit confirmation from the user. For
|
||||
information on these safeguards (and on how to disable them) see @ref{Code
|
||||
evaluation security}.} and the results of evaluation optionally placed in the
|
||||
Org-mode buffer. By default, the evaluation facility is only enabled for
|
||||
Lisp code blocks specified as @code{emacs-lisp}. However, souce code blocks
|
||||
in many languages can be evaluated within Org-mode (see @ref{Languages} for a
|
||||
list of supported languages and @ref{Structure of code blocks} for
|
||||
information on the syntax used to define a code block).
|
||||
|
||||
@kindex C-c C-c
|
||||
There are a number of ways to evaluate code blocks. The simplest is to press
|
||||
|
|
@ -11843,63 +11855,51 @@ There are a number of ways to evaluate code blocks. The simplest is to press
|
|||
evaluation from the @kbd{C-c C-c} key binding.}. This will call the
|
||||
@code{org-babel-execute-src-block} function to evaluate the block and insert
|
||||
its results into the Org-mode buffer.
|
||||
@cindex #+CALL
|
||||
|
||||
It is also possible to evaluate named code blocks from anywhere in an
|
||||
Org-mode buffer or an Org-mode table. @code{#+call} (or synonymously
|
||||
@code{#+function} or @code{#+lob}) lines can be used to remotely execute code
|
||||
blocks located in the current Org-mode buffer or in the ``Library of Babel''
|
||||
(see @ref{Library of Babel}). These lines use the following syntax to place
|
||||
a call on a line by itself.
|
||||
Org-mode buffer or an Org-mode table. Live code blocks located in the current
|
||||
Org-mode buffer or in the ``Library of Babel'' (see @ref{Library of Babel})
|
||||
can be executed. Named code blocks can be executed with a separate
|
||||
@code{#+CALL:} line or inline within a block of text.
|
||||
|
||||
The syntax of the @code{#+CALL:} line is
|
||||
|
||||
@example
|
||||
#+call: <name>(<arguments>)
|
||||
#+call: <name>[<header args>](<arguments>) <header args>
|
||||
#+CALL: <name>(<arguments>)
|
||||
#+CALL: <name>[<inside header arguments>](<arguments>) <end header arguments>
|
||||
@end example
|
||||
|
||||
The following syntax can be used to place these calls within a block of
|
||||
prose.
|
||||
The syntax for inline evaluation of named code blocks is
|
||||
|
||||
@example
|
||||
...prose... call_<name>(<arguments>) ...prose...
|
||||
...prose... call_<name>[<header args>](<arguments>)[<header args>] ...prose...
|
||||
... call_<name>(<arguments>) ...
|
||||
... call_<name>[<inside header arguments>](<arguments>)[<end header arguments>] ...
|
||||
@end example
|
||||
|
||||
@table @code
|
||||
@item <name>
|
||||
The name of the code block to be evaluated.
|
||||
The name of the code block to be evaluated (see @ref{Structure of code blocks}).
|
||||
@item <arguments>
|
||||
Arguments specified in this section will be passed to the code block. These
|
||||
arguments should relate to @code{:var} header arguments in the called code
|
||||
block expressed using standard function call syntax. For example if the
|
||||
original code block named @code{double} has the header argument @code{:var
|
||||
n=2}, then the call line passing the number four to that block would be
|
||||
written as @code{#+call: double(n=2)}.
|
||||
@item <header args>
|
||||
Header arguments can be placed either inside the call to the code block or at
|
||||
the end of the line as shown below.
|
||||
arguments use standard function call syntax, rather than
|
||||
header argument syntax. For example, a @code{#+CALL:} line that passes the
|
||||
number four to a code block named @code{double}, which declares the header
|
||||
argument @code{:var n=2}, would be written as @code{#+CALL: double(n=4)}.
|
||||
@item <inside header arguments>
|
||||
Inside header arguments are passed through and applied to the named code
|
||||
block. These arguments use header argument syntax rather than standard
|
||||
function call syntax. Inside header arguments affect how the code block is
|
||||
evaluated. For example, @code{[:results output]} will collect the results of
|
||||
everything printed to @code{STDOUT} during execution of the code block.
|
||||
@item <end header arguments>
|
||||
End header arguments are applied to the calling instance and do not affect
|
||||
evaluation of the named code block. They affect how the results are
|
||||
incorporated into the Org-mode buffer and how the call line is exported. For
|
||||
example, @code{:results html} will insert the results of the call line
|
||||
evaluation in the Org buffer, wrapped in a @code{BEGIN_HTML:} block.
|
||||
|
||||
@example
|
||||
#+call: code_bloc_name[XXXX](arguments) YYYY
|
||||
@end example
|
||||
|
||||
Header arguments located in these two locations are treated differently.
|
||||
|
||||
@table @code
|
||||
@item XXXX
|
||||
Those placed in the @code{XXXX} location are passed through and applied to
|
||||
the code block being called. These header arguments affect how the code
|
||||
block is evaluated, for example @code{[:results output]} will collect the
|
||||
results from @code{STDOUT} of the called code block.
|
||||
@item YYYY
|
||||
Those placed in the @code{YYYY} location are applied to the call line and do
|
||||
not affect the code block being called. These header arguments affect how
|
||||
the results are incorporated into the Org-mode buffer when the call line is
|
||||
evaluated, and how the call line is exported. For example @code{:results
|
||||
org} at the end of the call line will insert the results of the call line
|
||||
inside of an Org-mode block.
|
||||
@end table
|
||||
|
||||
For more examples of passing header arguments to @code{#+call:} lines see
|
||||
For more examples of passing header arguments to @code{#+CALL:} lines see
|
||||
@ref{Header arguments in function calls}.
|
||||
@end table
|
||||
|
||||
|
|
@ -11909,15 +11909,19 @@ For more examples of passing header arguments to @code{#+call:} lines see
|
|||
@cindex source code, library
|
||||
@cindex code block, library
|
||||
|
||||
The ``Library of Babel'' is a library of code blocks
|
||||
that can be called from any Org-mode file. The library is housed in an
|
||||
Org-mode file located in the @samp{contrib} directory of Org-mode.
|
||||
Org-mode users can deposit functions they believe to be generally
|
||||
useful in the library.
|
||||
The ``Library of Babel'' consists of code blocks that can be called from any
|
||||
Org-mode file. Code blocks defined in the ``Library of Babel'' can be called
|
||||
remotely as if they were in the current Org-mode buffer (see @ref{Evaluating
|
||||
code blocks} for information on the syntax of remote code block evaluation).
|
||||
|
||||
|
||||
The central repository of code blocks in the ``Library of Babel'' is housed
|
||||
in an Org-mode file located in the @samp{contrib} directory of Org-mode.
|
||||
|
||||
Users can add code blocks they believe to be generally useful to their
|
||||
``Library of Babel.'' The code blocks can be stored in any Org-mode file and
|
||||
then loaded into the library with @code{org-babel-lob-ingest}.
|
||||
|
||||
Code blocks defined in the ``Library of Babel'' can be called remotely as if
|
||||
they were in the current Org-mode buffer (see @ref{Evaluating code blocks}
|
||||
for information on the syntax of remote code block evaluation).
|
||||
|
||||
@kindex C-c C-v i
|
||||
Code blocks located in any Org-mode file can be loaded into the ``Library of
|
||||
|
|
@ -12111,7 +12115,7 @@ in Org-mode documents.
|
|||
|
||||
The most common way to assign values to header arguments is at the
|
||||
code block level. This can be done by listing a sequence of header
|
||||
arguments and their values as part of the @code{#+begin_src} line.
|
||||
arguments and their values as part of the @code{#+BEGIN_SRC} line.
|
||||
Properties set in this way override both the values of
|
||||
@code{org-babel-default-header-args} and header arguments specified as
|
||||
properties. In the following example, the @code{:results} header argument
|
||||
|
|
@ -12121,28 +12125,30 @@ inserted in the buffer, and the @code{:exports} header argument is set to
|
|||
preserved on export to HTML or LaTeX.
|
||||
|
||||
@example
|
||||
#+source: factorial
|
||||
#+begin_src haskell :results silent :exports code :var n=0
|
||||
#+NAME: factorial
|
||||
#+BEGIN_SRC haskell :results silent :exports code :var n=0
|
||||
fac 0 = 1
|
||||
fac n = n * fac (n-1)
|
||||
#+end_src
|
||||
#+END_SRC
|
||||
@end example
|
||||
Similarly, it is possible to set header arguments for inline code blocks:
|
||||
Similarly, it is possible to set header arguments for inline code blocks
|
||||
|
||||
@example
|
||||
src_haskell[:exports both]@{fac 5@}
|
||||
@end example
|
||||
|
||||
Code block header arguments can span multiple lines using =#+header:= or
|
||||
=#+headers:= lines preceding a code block or nested in between the name and
|
||||
body of a named code block.
|
||||
Code block header arguments can span multiple lines using @code{#+HEADER:} or
|
||||
@code{#+HEADERS:} lines preceding a code block or nested between the
|
||||
@code{#+NAME:} line and the @code{#+BEGIN_SRC} line of a named code block.
|
||||
@cindex #+HEADER:
|
||||
@cindex #+HEADERS:
|
||||
|
||||
Multi-line header arguments on an un-named code block:
|
||||
@example
|
||||
#+headers: :var data1=1
|
||||
#+begin_src emacs-lisp :var data2=2
|
||||
#+HEADERS: :var data1=1
|
||||
#+BEGIN_SRC emacs-lisp :var data2=2
|
||||
(message "data1:%S, data2:%S" data1 data2)
|
||||
#+end_src
|
||||
#+END_SRC
|
||||
|
||||
#+results:
|
||||
: data1:1, data2:2
|
||||
|
|
@ -12150,11 +12156,11 @@ Multi-line header arguments on an un-named code block:
|
|||
|
||||
Multi-line header arguments on a named code block:
|
||||
@example
|
||||
#+source: named-block
|
||||
#+header: :var data=2
|
||||
#+begin_src emacs-lisp
|
||||
#+NAME: named-block
|
||||
#+HEADER: :var data=2
|
||||
#+BEGIN_SRC emacs-lisp
|
||||
(message "data:%S" data)
|
||||
#+end_src
|
||||
#+END_SRC
|
||||
|
||||
#+results: named-block
|
||||
: data:2
|
||||
|
|
@ -12165,20 +12171,20 @@ Multi-line header arguments on a named code block:
|
|||
@subsubheading Header arguments in function calls
|
||||
|
||||
At the most specific level, header arguments for ``Library of Babel'' or
|
||||
function call lines can be set as shown in the two examples below. For more
|
||||
information on the structure of @code{#+call:} lines see @ref{Evaluating code
|
||||
@code{#+CALL:} lines can be set as shown in the two examples below. For more
|
||||
information on the structure of @code{#+CALL:} lines see @ref{Evaluating code
|
||||
blocks}.
|
||||
|
||||
The following will apply the @code{:exports results} header argument to the
|
||||
evaluation of the @code{#+call:} line.
|
||||
evaluation of the @code{#+CALL:} line.
|
||||
@example
|
||||
#+call: factorial(n=5) :exports results
|
||||
#+CALL: factorial(n=5) :exports results
|
||||
@end example
|
||||
|
||||
The following will apply the @code{:session special} header argument to the
|
||||
evaluation of the @code{factorial} code block.
|
||||
@example
|
||||
#+call: factorial[:session special](n=5)
|
||||
#+CALL: factorial[:session special](n=5)
|
||||
@end example
|
||||
|
||||
@node Specific header arguments, , Using header arguments, Header arguments
|
||||
|
|
@ -12223,14 +12229,18 @@ Additional header arguments are defined on a language-specific basis, see
|
|||
The @code{:var} header argument is used to pass arguments to code blocks.
|
||||
The specifics of how arguments are included in a code block vary by language;
|
||||
these 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 literal values, values from org-mode tables
|
||||
and literal example blocks, the results of other code blocks, or Emacs Lisp
|
||||
code---see the ``Emacs Lisp evaluation of variables'' heading below. In
|
||||
every case, variables require a default value when they are declared.
|
||||
syntax used to specify arguments is the same across all languages. In every
|
||||
case, variables require a default value when they are declared.
|
||||
|
||||
These values can be indexed in a manner similar to arrays---see the
|
||||
``indexable variable values'' heading below.
|
||||
The values passed to arguments can either be literal values, references, or
|
||||
Emacs Lisp code (see @ref{Emacs Lisp evaluation of variables}). References
|
||||
include anything in the Org-mode file that takes a @code{#+NAME:},
|
||||
@code{#+TBLNAME:}, or @code{#+RESULTS:} line. This includes tables, lists,
|
||||
@code{#+BEGIN_EXAMPLE} blocks, other code blocks, and the results of other
|
||||
code blocks.
|
||||
|
||||
Argument values can be indexed in a manner similar to arrays (see
|
||||
@ref{Indexable variable values}).
|
||||
|
||||
The following syntax is used to pass arguments to code blocks using the
|
||||
@code{:var} header argument.
|
||||
|
|
@ -12241,74 +12251,134 @@ The following syntax is used to pass arguments to code blocks using the
|
|||
|
||||
where @code{assign} can take one of the following forms
|
||||
|
||||
@itemize @bullet
|
||||
@table @asis
|
||||
@item literal value
|
||||
either a string @code{"string"} or a number @code{9}.
|
||||
either a string @samp{"string"} or a number @samp{9}.
|
||||
@item reference
|
||||
a table name:
|
||||
tables, lists, literal examples, other code blocks, and results blocks can
|
||||
all be passed by reference
|
||||
@table @asis
|
||||
@item table
|
||||
|
||||
@example
|
||||
#+tblname: example-table
|
||||
#+TBLNAME: example-table
|
||||
| 1 |
|
||||
| 2 |
|
||||
| 3 |
|
||||
| 4 |
|
||||
|
||||
#+source: table-length
|
||||
#+begin_src emacs-lisp :var table=example-table
|
||||
#+NAME: table-length
|
||||
#+BEGIN_SRC emacs-lisp :var table=example-table
|
||||
(length table)
|
||||
#+end_src
|
||||
#+END_SRC
|
||||
|
||||
#+results: table-length
|
||||
: 4
|
||||
@end example
|
||||
|
||||
a code block name, as assigned by @code{#+srcname:}, followed by
|
||||
@item list
|
||||
a named, simple list. Nesting is not carried through to the source code
|
||||
block.
|
||||
|
||||
@example
|
||||
#+NAME: example-list
|
||||
- simple
|
||||
- not
|
||||
- nested
|
||||
- lists
|
||||
|
||||
#+BEGIN_SRC emacs-lisp :var x=example-list
|
||||
(print x)
|
||||
#+END_SRC
|
||||
|
||||
#+RESULTS:
|
||||
| simple | lists |
|
||||
@end example
|
||||
|
||||
@item code block
|
||||
a code block name, as assigned by @code{#+NAME:}, followed by
|
||||
parentheses:
|
||||
|
||||
@example
|
||||
#+begin_src emacs-lisp :var length=table-length()
|
||||
#+BEGIN_SRC emacs-lisp :var length=table-length()
|
||||
(* 2 length)
|
||||
#+end_src
|
||||
#+END_SRC
|
||||
|
||||
#+results:
|
||||
: 8
|
||||
@end example
|
||||
|
||||
In addition, an argument can be passed to the code block referenced
|
||||
by @code{:var}. The argument is passed within the parentheses following the
|
||||
code block name:
|
||||
In addition, an argument can be passed to the code block referenced by
|
||||
@code{:var}. The argument is passed within the parentheses following the
|
||||
code block name using standard function call syntax:
|
||||
|
||||
@example
|
||||
#+source: double
|
||||
#+begin_src emacs-lisp :var input=8
|
||||
#+NAME: double
|
||||
#+BEGIN_SRC emacs-lisp :var input=8
|
||||
(* 2 input)
|
||||
#+end_src
|
||||
#+END_SRC
|
||||
|
||||
#+results: double
|
||||
: 16
|
||||
|
||||
#+source: squared
|
||||
#+begin_src emacs-lisp :var input=double(input=1)
|
||||
#+NAME: squared
|
||||
#+BEGIN_SRC emacs-lisp :var input=double(input=1)
|
||||
(* input input)
|
||||
#+end_src
|
||||
#+END_SRC
|
||||
|
||||
#+results: squared
|
||||
: 4
|
||||
@end example
|
||||
@end itemize
|
||||
|
||||
@item literal example
|
||||
named literal examples are passed intact
|
||||
|
||||
@example
|
||||
#+NAME: literal-example
|
||||
#+BEGIN_EXAMPLE
|
||||
A literal example
|
||||
on two lines
|
||||
#+END_EXAMPLE
|
||||
|
||||
#+NAME: read-literal-example
|
||||
#+BEGIN_SRC emacs-lisp :var x=literal-example
|
||||
(concatenate 'string x " for you.")
|
||||
#+END_SRC
|
||||
|
||||
#+results: read-literal-example
|
||||
: A literal example
|
||||
: on two lines for you.
|
||||
|
||||
@end example
|
||||
|
||||
@item results block
|
||||
|
||||
named results blocks are passed intact. Referring to the results of the last
|
||||
example
|
||||
|
||||
@example
|
||||
#+BEGIN_SRC emacs-lisp :var x=read-literal-example
|
||||
(concatenate 'string x "\nAgain.")
|
||||
#+END_SRC
|
||||
|
||||
#+results:
|
||||
: A literal example
|
||||
: on two lines for you.
|
||||
: Again.
|
||||
@end example
|
||||
@end table
|
||||
|
||||
@subsubheading Alternate argument syntax
|
||||
It is also possible to specify arguments in a potentially more natural way
|
||||
using the @code{#+source:} line of a code block. As in the following
|
||||
example arguments can be packed inside of parenthesis, separated by commas,
|
||||
using the @code{#+NAME:} line of a code block. As in the following
|
||||
example, arguments can be packed inside of parenthesis, separated by commas,
|
||||
following the source name.
|
||||
|
||||
@example
|
||||
#+source: double(input=0, x=2)
|
||||
#+begin_src emacs-lisp
|
||||
#+NAME: double(input=0, x=2)
|
||||
#+BEGIN_SRC emacs-lisp
|
||||
(* 2 (+ input x))
|
||||
#+end_src
|
||||
#+END_SRC
|
||||
@end example
|
||||
|
||||
@subsubheading Indexable variable values
|
||||
|
|
@ -12322,15 +12392,15 @@ following example assigns the last cell of the first row the table
|
|||
@code{example-table} to the variable @code{data}:
|
||||
|
||||
@example
|
||||
#+results: example-table
|
||||
#+NAME: example-table
|
||||
| 1 | a |
|
||||
| 2 | b |
|
||||
| 3 | c |
|
||||
| 4 | d |
|
||||
|
||||
#+begin_src emacs-lisp :var data=example-table[0,-1]
|
||||
#+BEGIN_SRC emacs-lisp :var data=example-table[0,-1]
|
||||
data
|
||||
#+end_src
|
||||
#+END_SRC
|
||||
|
||||
#+results:
|
||||
: a
|
||||
|
|
@ -12342,16 +12412,16 @@ example the following assigns the middle three rows of @code{example-table}
|
|||
to @code{data}.
|
||||
|
||||
@example
|
||||
#+results: example-table
|
||||
#+NAME: example-table
|
||||
| 1 | a |
|
||||
| 2 | b |
|
||||
| 3 | c |
|
||||
| 4 | d |
|
||||
| 5 | 3 |
|
||||
|
||||
#+begin_src emacs-lisp :var data=example-table[1:3]
|
||||
#+BEGIN_SRC emacs-lisp :var data=example-table[1:3]
|
||||
data
|
||||
#+end_src
|
||||
#+END_SRC
|
||||
|
||||
#+results:
|
||||
| 2 | b |
|
||||
|
|
@ -12365,15 +12435,15 @@ interpreted to mean the entire range and as such are equivalent to
|
|||
column is referenced.
|
||||
|
||||
@example
|
||||
#+results: example-table
|
||||
#+NAME: example-table
|
||||
| 1 | a |
|
||||
| 2 | b |
|
||||
| 3 | c |
|
||||
| 4 | d |
|
||||
|
||||
#+begin_src emacs-lisp :var data=example-table[,0]
|
||||
#+BEGIN_SRC emacs-lisp :var data=example-table[,0]
|
||||
data
|
||||
#+end_src
|
||||
#+END_SRC
|
||||
|
||||
#+results:
|
||||
| 1 | 2 | 3 | 4 |
|
||||
|
|
@ -12384,16 +12454,16 @@ Any number of dimensions can be indexed. Dimensions are separated from one
|
|||
another by commas, as shown in the following example.
|
||||
|
||||
@example
|
||||
#+source: 3D
|
||||
#+begin_src emacs-lisp
|
||||
#+NAME: 3D
|
||||
#+BEGIN_SRC emacs-lisp
|
||||
'(((1 2 3) (4 5 6) (7 8 9))
|
||||
((10 11 12) (13 14 15) (16 17 18))
|
||||
((19 20 21) (22 23 24) (25 26 27)))
|
||||
#+end_src
|
||||
#+END_SRC
|
||||
|
||||
#+begin_src emacs-lisp :var data=3D[1,,1]
|
||||
#+BEGIN_SRC emacs-lisp :var data=3D[1,,1]
|
||||
data
|
||||
#+end_src
|
||||
#+END_SRC
|
||||
|
||||
#+results:
|
||||
| 11 | 14 | 17 |
|
||||
|
|
@ -12402,31 +12472,31 @@ another by commas, as shown in the following example.
|
|||
@subsubheading Emacs Lisp evaluation of variables
|
||||
|
||||
Emacs lisp code can be used to initialize variable values. When a variable
|
||||
value starts with @code{(}, @code{[}, @code{'} or @code{`} it will be evaluated as
|
||||
Emacs Lisp and the result of the evaluation will be assigned as the variable
|
||||
value. The following example demonstrates use of this evaluation to reliably
|
||||
pass the file-name of the org-mode buffer to a code block---note that
|
||||
evaluation of header arguments is guaranteed to take place in the original
|
||||
org-mode file, while there is no such guarantee for evaluation of the code
|
||||
block body.
|
||||
value starts with @code{(}, @code{[}, @code{'} or @code{`} it will be
|
||||
evaluated as Emacs Lisp and the result of the evaluation will be assigned as
|
||||
the variable value. The following example demonstrates use of this
|
||||
evaluation to reliably pass the file-name of the org-mode buffer to a code
|
||||
block---note that evaluation of header arguments is guaranteed to take place
|
||||
in the original Org-mode file, while there is no such guarantee for
|
||||
evaluation of the code block body.
|
||||
|
||||
@example
|
||||
#+begin_src sh :var filename=(buffer-file-name) :exports both
|
||||
#+BEGIN_SRC sh :var filename=(buffer-file-name) :exports both
|
||||
wc -w $filename
|
||||
#+end_src
|
||||
#+END_SRC
|
||||
@end example
|
||||
|
||||
Note that values read from tables and lists will not be evaluated as
|
||||
Emacs Lisp, as shown in the following example.
|
||||
|
||||
@example
|
||||
#+results: table
|
||||
#+NAME: table
|
||||
| (a b c) |
|
||||
|
||||
#+headers: :var data=table[0,0]
|
||||
#+begin_src perl
|
||||
#+HEADERS: :var data=table[0,0]
|
||||
#+BEGIN_SRC perl
|
||||
$data
|
||||
#+end_src
|
||||
#+END_SRC
|
||||
|
||||
#+results:
|
||||
: (a b c)
|
||||
|
|
@ -12569,9 +12639,9 @@ In other words, if you want your plot to go into a folder called @file{Work}
|
|||
in your home directory, you could use
|
||||
|
||||
@example
|
||||
#+begin_src R :file myplot.png :dir ~/Work
|
||||
#+BEGIN_SRC R :file myplot.png :dir ~/Work
|
||||
matplot(matrix(rnorm(100), 10), type="l")
|
||||
#+end_src
|
||||
#+END_SRC
|
||||
@end example
|
||||
|
||||
@subsubheading Remote execution
|
||||
|
|
@ -12579,9 +12649,9 @@ A directory on a remote machine can be specified using tramp file syntax, in
|
|||
which case the code will be evaluated on the remote machine. An example is
|
||||
|
||||
@example
|
||||
#+begin_src R :file plot.png :dir /dand@@yakuba.princeton.edu:
|
||||
#+BEGIN_SRC R :file plot.png :dir /dand@@yakuba.princeton.edu:
|
||||
plot(1:10, main=system("hostname", intern=TRUE))
|
||||
#+end_src
|
||||
#+END_SRC
|
||||
@end example
|
||||
|
||||
Text results will be returned to the local Org-mode buffer as usual, and file
|
||||
|
|
@ -12612,7 +12682,7 @@ currently made to alter the directory associated with an existing session.
|
|||
@code{:dir} should typically not be used to create files during export with
|
||||
@code{:exports results} or @code{: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 @code{default
|
||||
links inserted into the buffer will @emph{not} be expanded against @code{default
|
||||
directory}. Therefore, if @code{default-directory} is altered using
|
||||
@code{:dir}, it is probable that the file will be created in a location to
|
||||
which the link does not point.
|
||||
|
|
@ -12786,33 +12856,33 @@ following Org-mode file, the bodies of code blocks will be concatenated into
|
|||
the resulting pure code file.
|
||||
|
||||
@example
|
||||
#+begin_src sh :tangle yes :noweb yes :shebang #!/bin/sh
|
||||
#+BEGIN_SRC sh :tangle yes :noweb yes :shebang #!/bin/sh
|
||||
<<fullest-disk>>
|
||||
#+end_src
|
||||
#+END_SRC
|
||||
* the mount point of the fullest disk
|
||||
:PROPERTIES:
|
||||
:noweb-ref: fullest-disk
|
||||
:END:
|
||||
|
||||
** query all mounted disks
|
||||
#+begin_src sh
|
||||
#+BEGIN_SRC sh
|
||||
df \
|
||||
#+end_src
|
||||
#+END_SRC
|
||||
|
||||
** strip the header row
|
||||
#+begin_src sh
|
||||
#+BEGIN_SRC sh
|
||||
|sed '1d' \
|
||||
#+end_src
|
||||
#+END_SRC
|
||||
|
||||
** sort by the percent full
|
||||
#+begin_src sh
|
||||
#+BEGIN_SRC sh
|
||||
|awk '@{print $5 " " $6@}'|sort -n |tail -1 \
|
||||
#+end_src
|
||||
#+END_SRC
|
||||
|
||||
** extract the mount point
|
||||
#+begin_src sh
|
||||
#+BEGIN_SRC sh
|
||||
|awk '@{print $2@}'
|
||||
#+end_src
|
||||
#+END_SRC
|
||||
@end example
|
||||
|
||||
@node cache, sep, noweb-ref, Specific header arguments
|
||||
|
|
@ -12842,18 +12912,18 @@ invalidated and the code block is re-run. In the following example,
|
|||
changed since it was last run.
|
||||
|
||||
@example
|
||||
#+srcname: random
|
||||
#+begin_src R :cache yes
|
||||
#+NAME: random
|
||||
#+BEGIN_SRC R :cache yes
|
||||
runif(1)
|
||||
#+end_src
|
||||
#+END_SRC
|
||||
|
||||
#+results[a2a72cd647ad44515fab62e144796432793d68e1]: random
|
||||
0.4659510825295
|
||||
|
||||
#+srcname: caller
|
||||
#+begin_src emacs-lisp :var x=random :cache yes
|
||||
#+NAME: caller
|
||||
#+BEGIN_SRC emacs-lisp :var x=random :cache yes
|
||||
x
|
||||
#+end_src
|
||||
#+END_SRC
|
||||
|
||||
#+results[bec9c8724e397d5df3b696502df3ed7892fc4f5f]: caller
|
||||
0.254227238707244
|
||||
|
|
@ -12887,17 +12957,17 @@ variable and raises an error. Setting @code{:hlines no} or relying on the
|
|||
default value yields the following results.
|
||||
|
||||
@example
|
||||
#+tblname: many-cols
|
||||
#+TBLNAME: many-cols
|
||||
| a | b | c |
|
||||
|---+---+---|
|
||||
| d | e | f |
|
||||
|---+---+---|
|
||||
| g | h | i |
|
||||
|
||||
#+source: echo-table
|
||||
#+begin_src python :var tab=many-cols
|
||||
#+NAME: echo-table
|
||||
#+BEGIN_SRC python :var tab=many-cols
|
||||
return tab
|
||||
#+end_src
|
||||
#+END_SRC
|
||||
|
||||
#+results: echo-table
|
||||
| a | b | c |
|
||||
|
|
@ -12909,17 +12979,17 @@ default value yields the following results.
|
|||
Leaves hlines in the table. Setting @code{:hlines yes} has this effect.
|
||||
|
||||
@example
|
||||
#+tblname: many-cols
|
||||
#+TBLNAME: many-cols
|
||||
| a | b | c |
|
||||
|---+---+---|
|
||||
| d | e | f |
|
||||
|---+---+---|
|
||||
| g | h | i |
|
||||
|
||||
#+source: echo-table
|
||||
#+begin_src python :var tab=many-cols :hlines yes
|
||||
#+NAME: echo-table
|
||||
#+BEGIN_SRC python :var tab=many-cols :hlines yes
|
||||
return tab
|
||||
#+end_src
|
||||
#+END_SRC
|
||||
|
||||
#+results: echo-table
|
||||
| a | b | c |
|
||||
|
|
@ -12944,16 +13014,16 @@ names will be removed from the table before
|
|||
processing, then reapplied to the results.
|
||||
|
||||
@example
|
||||
#+tblname: less-cols
|
||||
#+TBLNAME: less-cols
|
||||
| a |
|
||||
|---|
|
||||
| b |
|
||||
| c |
|
||||
|
||||
#+srcname: echo-table-again
|
||||
#+begin_src python :var tab=less-cols
|
||||
#+NAME: echo-table-again
|
||||
#+BEGIN_SRC python :var tab=less-cols
|
||||
return [[val + '*' for val in row] for row in tab]
|
||||
#+end_src
|
||||
#+END_SRC
|
||||
|
||||
#+results: echo-table-again
|
||||
| a |
|
||||
|
|
@ -12989,14 +13059,14 @@ The first column of the table is removed from the table before processing,
|
|||
and is then reapplied to the results.
|
||||
|
||||
@example
|
||||
#+tblname: with-rownames
|
||||
#+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
|
||||
#+NAME: 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
|
||||
#+END_SRC
|
||||
|
||||
#+results: echo-table-once-again
|
||||
| one | 11 | 12 | 13 | 14 | 15 |
|
||||
|
|
@ -13093,26 +13163,26 @@ 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
|
||||
#+BEGIN_SRC python :results output
|
||||
print "hello"
|
||||
2
|
||||
print "bye"
|
||||
#+end_src
|
||||
#+END_SRC
|
||||
|
||||
#+resname:
|
||||
#+results:
|
||||
: hello
|
||||
: bye
|
||||
@end example
|
||||
|
||||
In non-session mode, the `2' is not printed and does not appear.
|
||||
@example
|
||||
#+begin_src python :results output :session
|
||||
#+BEGIN_SRC python :results output :session
|
||||
print "hello"
|
||||
2
|
||||
print "bye"
|
||||
#+end_src
|
||||
#+END_SRC
|
||||
|
||||
#+resname:
|
||||
#+results:
|
||||
: hello
|
||||
: 2
|
||||
: bye
|
||||
|
|
|
|||
Loading…
Reference in New Issue