ndwarshuis
/
org-mode
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

babel-doc: working on Header Arguments -- not quite compiling

This commit is contained in:
Eric Schulte 2010-06-09 16:17:58 -07:00
parent d7b2397184
commit 2760c8e798
1 changed files with 283 additions and 295 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

392
doc/org.texi
View File

@ -10883,6 +10883,7 @@ Using code blocks in table formulas
* Library of Babel:: * Library of Babel::
* Languages:: * Languages::
* Header Arguments:: * Header Arguments::
* Results::
* Noweb Reference Syntax:: * Noweb Reference Syntax::
* Key Bindings & Useful Functions:: * Key Bindings & Useful Functions::
@end menu @end menu
@ -11150,7 +11151,7 @@ The original table from reference.org is below; I'm just using the first column
| 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]] | | 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]] | | 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]] | | 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]] | | Objective Caml | org-babel-doc-ocaml | ocaml | [[http://caml.inria.fr/][ocaml]], [[http://www-rock.inria.fr/~acohen/tuareg/][tuareg-mode]] |
| Octave | [[file:languages/org-babel-doc-octave-matlab.org][org-babel-doc-octave-matlab]] | octave | octave | | 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 | | 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) | | Perl | org-babel-doc-perl | perl | [[http://www.perl.org/][perl]], [[http://www.emacswiki.org/emacs/CPerlMode][cperl-mode]] (optional) |
@ -11175,30 +11176,36 @@ of the language names from the above table).
@end example @end example
@node Header Arguments, Noweb Reference Syntax, Languages, Working With Source Code @node Header Arguments, Results, Languages, Working With Source Code
@section Header Arguments @section Header Arguments
:PROPERTIES:
:CUSTOM_ID: header-arguments
:END:
Definitions of all Org-babel header arguments are given Definitions of all Org-babel header arguments are given (see @ref{Specific
[[header-argument-specific-documentation][below]]. In addition, some Header Arguments}). In addition, some languages may add their own header
languages may add their own header arguments. Please see the arguments. Please see the language-specific documentation (available at
language-specific documentation for information on language-specific header @uref{http://orgmode.org/worg/org-contrib/babel/reference.php#languages}.)
arguments. for information on language-specific header arguments.
@menu
* Using Header Arguments::
* System-wide Header Arguments::
* Language Specific Header Arguments::
* Header Arguments in Org-mode Properties::
* Header Arguments in Source Code Blocks::
* Specific Header Arguments::
* Using Header Arguments::
@end menu
@node Using Header Arguments, System-wide Header Arguments, , Header Arguments
@subsection Using Header Arguments @subsection Using Header Arguments
The values of header arguments can be set in four different ways, each The values of header arguments can be set in four different ways, each more
more specific (and having higher priority) than the last. specific (and having higher priority) than the last.
@subsubsection System-wide @node System-wide Header Arguments, Language Specific Header Arguments, Using Header Arguments, Header Arguments
:PROPERTIES: @subsubsection System-wide Header Arguments
:CUSTOM_ID: system-wide-header-argument System-wide values of header arguments can be specified by customizing the
:END: @code{org-babel-default-header-args} variable:
System-wide values of header arguments can be specified by
customizing the =org-babel-default-header-args= variable:
@example @example
org-babel-default-header-args is a variable defined in `org-babel.el'. org-babel-default-header-args is a variable defined in `org-babel.el'.
Its value is Its value is
@ -11212,26 +11219,33 @@ more specific (and having higher priority) than the last.
Documentation: Documentation:
Default arguments to use when evaluating a source block. Default arguments to use when evaluating a source block.
@end example @end example
[[#default-noweb]]
For example, the following example could be used to set the default value For example, the following example could be used to set the default value of
of =:noweb= header arguments to =yes=. This would have the effect of @code{:noweb} header arguments to =yes=. This would have the effect of
expanding =:noweb= references by default when evaluating source code blocks. expanding @code{:noweb} references by default when evaluating source code
blocks.
@example @example
(setq org-babel-default-header-args (setq org-babel-default-header-args
(cons '(:noweb . "yes") (cons '(:noweb . "yes")
(assq-delete-all :noweb org-babel-default-header-args))) (assq-delete-all :noweb org-babel-default-header-args)))
@end example @end example
@subsubsection Org-mode Properties
Header arguments are also read from @node Language Specific Header Arguments, Header Arguments in Org-mode Properties, System-wide Header Arguments, Header Arguments
[[http://orgmode.org/manual/Properties-and-Columns.html#Properties-and-Columns][Org-mode @subsubsection Header Arguments in Org-mode Properties
properties]], which can be set on a buffer-wide or per-heading basis. An Each language can define it's own set of default header arguments.
example of setting a header argument for all code blocks in a buffer is
#+begin_example @node Header Arguments in Org-mode Properties, Header Arguments in Source Code Blocks, Language Specific Header Arguments, Header Arguments
@subsubsection Header Arguments in Org-mode Properties
Header arguments are also read from Org-mode properties (see @ref{Property
syntax}), which can be set on a buffer-wide or per-heading basis. An example
of setting a header argument for all code blocks in a buffer is
@example
#+property: tangle yes #+property: tangle yes
#+end_example @end example
When properties are used to set default header arguments, they are looked up When properties are used to set default header arguments, they are looked up
with inheritance, so the value of the =:cache= header argument will default with inheritance, so the value of the =:cache= header argument will default
@ -11245,26 +11259,27 @@ heading:
:CUSTOM_ID: property-set-header-arguments :CUSTOM_ID: property-set-header-arguments
:END: :END:
@end example @end example
Properties defined in this way override the properties set in Properties defined in this way override the properties set in
=org-babel-default-header-args=. It is convenient to use the @code{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 @code{org-set-property} function bound to @key{C-c C-x p} to set properties
in Org-mode documents. in Org-mode documents.
@subsubsection Source Code Block
:PROPERTIES: @node Header Arguments in Source Code Blocks, Specific Header Arguments, Header Arguments in Org-mode Properties, Header Arguments
:CUSTOM_ID: single-block-header-arguments @subsubsection Header Arguments in Source Code Block
:END:
The most common way to assign values to header arguments is at the The most common way to assign values to header arguments is at the source
source code block level. This can be done by listing a sequence of code block level. This can be done by listing a sequence of header
header arguments and their values as part of the =#+begin_src= arguments and their values as part of the @code{#+begin_src} line.
line. Properties set in this way override both the values of Properties set in this way override both the values of
=org-babel-default-header-args= and header argument specified as @code{org-babel-default-header-args} and header argument specified as
properties. In the following example, the properties. In the following example, the @code{:results} header argument
=:results= header argument is set to =silent=, meaning the results is set to @code{silent}, meaning the results of execution will not be
of execution will not be inserted in the buffer, and the =:exports= inserted in the buffer, and the @code{:exports} header argument is set to
header argument is set to =code=, meaning only the body of the @code{code}, meaning only the body of the source code block will be
source code block preserved on export to HTML or LaTeX.
will be preserved on export to HTML or LaTeX.
@example @example
#+source: factorial #+source: factorial
#+begin_src haskell :results silent :exports code #+begin_src haskell :results silent :exports code
@ -11273,17 +11288,27 @@ heading:
#+end_src #+end_src
@end example @end example
@node Specific Header Arguments, , Header Arguments in Source Code Blocks, Header Arguments
@subsection Specific Header Arguments @subsection Specific Header Arguments
:PROPERTIES: Description of every standard (non language-specific) Org-babel header
:CUSTOM_ID: header-argument-specific-documentation argument.
:END:
@subsubsection =:var= @menu
:PROPERTIES: * @code{var}::
:CUSTOM_ID: header-argument-var * @code{results}::
:END: * @code{file}::
* @code{dir} and remote execution::
* @code{exports}::
* @code{tangle}::
* @code{session}::
* @code{noweb}::
* @code{cache}::
@end menu
The =:var= header argument is used to pass arguments to @node @code{var}, @code{results}, , Specific Header Arguments
@subsubsection @code{var}
The @code{:var} header argument is used to pass arguments to
source code blocks. The specifics of how arguments are included source code blocks. The specifics of how arguments are included
in a source code block are language specific and are in a source code block are language specific and are
addressed in the language-specific documentation. However, the addressed in the language-specific documentation. However, the
@ -11293,19 +11318,19 @@ heading:
- values from org-mode tables - values from org-mode tables
- the results of other source code blocks - the results of other source code blocks
These values can be indexed in a manner similar to arrays -- see These values can be indexed in a manner similar to arrays -- see argument
[[var-argument-indexing][argument indexing]]. indexing FIXME/need section on argument indexing.
The following syntax is used to pass arguments to source code The following syntax is used to pass arguments to source code
blocks using the =:var= header argument. blocks using the @code{:var} header argument.
@example @example
:var name=assign :var name=assign
@end example @end example
where =assign= can take one of the following forms where @code{assign} can take one of the following forms
- literal value :: either a string ="string"= or a number =9=. - literal value :: either a string @code{"string"} or a number @code{9}.
- reference :: a table name: - reference :: a table name:
@example @example
@ -11359,14 +11384,11 @@ heading:
@end example @end example
@subsubheading alternate argument syntax @subsubheading alternate argument syntax
:PROPERTIES:
:CUSTOM_ID: alternate-argument-syntax
:END:
It is also possible to specify arguments in a potentially more It is also possible to specify arguments in a potentially more
natural way using the =#+source:= line of a source code block. natural way using the =#+source:= line of a source code block.
As in the following example arguments can be packed inside of As in the following example arguments can be packed inside of
parenthesis following the source name. parenthesis following the source name.
@example @example
#+source: double(input=0) #+source: double(input=0)
#+begin_src emacs-lisp #+begin_src emacs-lisp
@ -11375,9 +11397,6 @@ heading:
@end example @end example
**** indexable variable values **** indexable variable values
:PROPERTIES:
:CUSTOM_ID: var-argument-indexing
:END:
It is possible to assign a portion of a value to a It is possible to assign a portion of a value to a
variable in a source block. The following example variable in a source block. The following example
@ -11423,10 +11442,8 @@ heading:
function) and =describe-variable= (M-x describe variable) function) and =describe-variable= (M-x describe variable)
functions, respectively. functions, respectively.
@subsubsection =:results= @node @code{results}, @code{file}, @code{var}, Specific Header Arguments
:PROPERTIES: @subsubsection @code{results}
:CUSTOM_ID: header-argument-results
:END:
There are three types of results header argument: There are three types of results header argument:
- *collection* header arguments specify how the results should be collected from - *collection* header arguments specify how the results should be collected from
@ -11451,13 +11468,13 @@ heading:
of the last statement in the source code block. of the last statement in the source code block.
This header argument places Org-babel in functional This header argument places Org-babel in functional
mode. Note that in some languages, e.g., python, mode. Note that in some languages, e.g., python,
use of this result type requires that a =return= use of this result type requires that a @code{return}
statement be included in the body of the source code statement be included in the body of the source code
block. E.g., =:results value=. block. E.g., @code{:results value}.
- output :: The result is the collection of everything printed - output :: The result is the collection of everything printed
to stdout during the execution of the source code to stdout during the execution of the source code
block. This header argument places Org-babel in scripting block. This header argument places Org-babel in scripting
mode. E.g., =:results output=. mode. E.g., @code{:results output}.
@subsubheading type @subsubheading type
The following options are mutually exclusive and specify what The following options are mutually exclusive and specify what
@ -11467,28 +11484,28 @@ heading:
- table, vector :: The results should be interpreted as an Org-mode table. - table, vector :: The results should be interpreted as an Org-mode table.
If a single value is returned, Org-babel will convert it If a single value is returned, Org-babel will convert it
into a table with one row and one column. E.g., =:results into a table with one row and one column. E.g., @code{:results
value table=. value table}.
- scalar, verbatim :: The results should be interpreted - scalar, verbatim :: The results should be interpreted
literally -- meaning they will not be converted into a table. literally -- meaning they will not be converted into a table.
The results will be inserted into the Org-mode buffer as The results will be inserted into the Org-mode buffer as
quoted text. E.g., =:results value verbatim=. quoted text. E.g., @code{:results value verbatim}.
- file :: The results will be interpreted as the path to a file, - file :: The results will be interpreted as the path to a file,
and will be inserted into the Org-mode buffer as a file and will be inserted into the Org-mode buffer as a file
link. E.g., =:results value file=. link. E.g., @code{:results value file}.
- raw, org :: The results are interpreted as raw Org-mode code and - raw, org :: The results are interpreted as raw Org-mode code and
are inserted directly into the buffer. If the results look are inserted directly into the buffer. If the results look
like a table they will be aligned as such by Org-mode. like a table they will be aligned as such by Org-mode.
E.g., =:results value raw=. E.g., @code{:results value raw}.
- html :: Results are assumed to be HTML and will be enclosed in - html :: Results are assumed to be HTML and will be enclosed in
a =begin_html= block. E.g., =:results value html=. a @code{begin_html} block. E.g., @code{:results value html}.
- latex :: Results assumed to be LaTeX and are enclosed in a - latex :: Results assumed to be LaTeX and are enclosed in a
=begin_latex= block. E.g., =:results value latex=. @code{begin_latex} block. E.g., @code{:results value latex}.
- code :: Result are assumed to be parseable code and are - code :: Result are assumed to be parseable code and are
enclosed in a code block. E.g., =:results value code=. enclosed in a code block. E.g., @code{:results value code}.
- pp :: The result is converted to pretty-printed code and is - pp :: The result is converted to pretty-printed code and is
enclosed in a code block. This option currently supports enclosed in a code block. This option currently supports
Emacs Lisp, python, and ruby. E.g., =:results value pp=. Emacs Lisp, python, and ruby. E.g., @code{:results value pp}.
@subsubheading handling @subsubheading handling
The following results options indicate what Org-babel should do The following results options indicate what Org-babel should do
@ -11496,48 +11513,40 @@ heading:
- silent :: The results will be echoed in the minibuffer but - silent :: The results will be echoed in the minibuffer but
will not be inserted into the Org-mode buffer. E.g., will not be inserted into the Org-mode buffer. E.g.,
=:results output silent=. @code{:results output silent}.
- replace :: The default value. The results will be inserted - replace :: The default value. The results will be inserted
into the Org-mode buffer. E.g., =:results output into the Org-mode buffer. E.g., @code{:results output
replace=. replace}.
@subsubsection =:file= @node @code{file}, @code{dir} and remote execution, @code{results}, Specific Header Arguments
:PROPERTIES: @subsubsection @code{file}
:CUSTOM_ID: header-argument-file @code{:file} is used to specify a path for file output in which case an
:END: Org-mode style link (see @ref{Link format}) @code{file:} link is inserted
into the buffer as the result. Common examples are graphical output from
R, gnuplot, ditaa and LaTeX blocks.
=:file= is used to specify a path for file output in which case an Note that for some languages, including R, gnuplot, LaTeX and ditaa,
[[http://orgmode.org/manual/Link-format.html#Link-format][org style]] =file:= link is inserted into the buffer as the graphical output is sent to the specified file without the file being
result. Common examples are graphical output from [[file:languages/org-babel-doc-R.org][R]], gnuplot, referenced explicitly in the code block. See the documentation for the
ditaa and [[file:languages/org-babel-doc-LaTeX.org][latex]] blocks. 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 @code{:file}.
See the [[#header-argument-dir][=:dir= and remote execution]] section for examples. While the @code{:file} header argument can be used to specify the path to
the output file,
Note that for some languages, including [[file:languages/org-babel-doc-R.org][R]], gnuplot, [[file:languages/org-babel-doc-LaTeX.org][latex]] and @node @code{dir} and remote execution, @code{exports}, @code{file}, Specific Header Arguments
ditaa, graphical output is sent to the specified file without the @subsubsection @code{dir} and remote execution
file being referenced explicitly in the code block. See the @code{:dir} specifies the /default directory/ during code block
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 execution. If it is absent, then the directory associated with the
current buffer is used. In other words, supplying =:dir path= current buffer is used. In other words, supplying @code{:dir path}
temporarily has the same effect as changing the current directory temporarily has the same effect as changing the current directory with
with =M-x cd path=, and then not supplying =:dir=. Under the @key{M-x cd path}, and then not supplying @code{:dir}. Under the surface,
surface, =:dir= simply sets the value of the emacs variable @code{:dir} simply sets the value of the emacs variable
=default-directory=. @code{default-directory}.
When using =:dir=, you should supply a relative path for [[#header-argument-file][file When using @code{:dir}, you should supply a relative path for file output
output]] (e.g. =:file myfile.jpg= or =:file results/myfile.jpg=) in (e.g. @code{:file myfile.jpg} or @code{:file results/myfile.jpg}) in
which case that path will be interpreted relative to the default which case that path will be interpreted relative to the default
directory. directory.
@ -11551,9 +11560,9 @@ heading:
@end example @end example
@subsubheading Remote execution @subsubheading Remote execution
A directory on a remote machine can be specified using [[http://www.gnu.org/software/tramp/#Filename-Syntax][tramp A directory on a remote machine can be specified using tramp file
filename syntax]], in which case the code will be evaluated on the syntax, in which case the code will be evaluated on the remote
remote machine[fn:2]. An example is machine. An example is
@example @example
#+begin_src R :file plot.png :dir /dand@@yakuba.princeton.edu: #+begin_src R :file plot.png :dir /dand@@yakuba.princeton.edu:
@ -11573,95 +11582,82 @@ 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]] [[file:/scp:dand@@yakuba.princeton.edu:/home/dand/plot.png][plot.png]]
@end example @end example
Most of this functionality follows immediately from the fact that Most of this functionality follows immediately from the fact that @code{:dir}
=:dir= sets the value of the emacs variable =default-directory=, sets the value of the emacs variable @code{default-directory}, thanks to
thanks to [[http://www.gnu.org/software/tramp/][tramp]]. Those using XEmacs, or GNU Emacs prior to tramp. Those using XEmacs, or GNU Emacs prior to version 23 may need to
version 23 may need to install tramp separately in order for the install tramp separately in order for the above features to work correctly.
above features to work correctly.
@subsubheading Further points @subsubheading Further points
- If =:dir= is used in conjunction with =:session=, although it - If @code{:dir} is used in conjunction with @code{:session}, although it
will determine the starting directory for a new session as will determine the starting directory for a new session as
expected, no attempt is currently made to alter the directory expected, no attempt is currently made to alter the directory
associated with an existing session. associated with an existing session.
- =:dir= should typically not be used to create files during - @code{:dir} should typically not be used to create files during
export with =:exports results= or =:exports both=. The reason export with @code{:exports results} or @code{:exports both}. The reason
is that, in order to retain portability of exported material is that, in order to retain portability of exported material
between machines, during export, links inserted into the buffer between machines, during export, links inserted into the buffer
will *not* be expanded against default directory. Therefore, if will *not* be expanded against default directory. Therefore, if
default-directory is altered using =:dir=, it it probable that default-directory is altered using @code{:dir}, it it probable that
the file will be created in a location to which the link does the file will be created in a location to which the link does
not point. not point.
@subsubsection =:exports=
:PROPERTIES:
:CUSTOM_ID: header-argument-exports
:END:
@node @code{exports}, @code{tangle}, @code{dir} and remote execution, Specific Header Arguments
@subsubsection @code{exports}
Specify what should be included in HTML or LaTeX exports of the Specify what should be included in HTML or LaTeX exports of the
Org-mode file. Org-mode file.
- code :: the default. The body of code is included - code :: the default. The body of code is included
into the exported file. E.g., =:exports code=. into the exported file. E.g., @code{:exports code}.
- results :: the result of evaluating the code is included in the - results :: the result of evaluating the code is included in the
exported file. E.g., =:exports results=. exported file. E.g., @code{:exports results}.
- both :: both the code and results are included in the exported - both :: both the code and results are included in the exported
file. E.g., =:exports both=. file. E.g., @code{:exports both}.
- none :: nothing is included in the exported file. E.g., - none :: nothing is included in the exported file. E.g.,
=:exports none=. @code{:exports none}.
@subsubsection =:tangle=
:PROPERTIES:
:CUSTOM_ID: tangle-header-arguments
:END:
@node @code{tangle}, @code{session}, @code{exports}, Specific Header Arguments
@subsubsection @code{tangle}
Specify whether or not the source code block should be included Specify whether or not the source code block should be included
in tangled extraction of source code files. in tangled extraction of source code files.
- yes :: the source code block is exported to a source code file - yes :: the source code block is exported to a source code file
named after the basename (name w/o extension) of the named after the basename (name w/o extension) of the
Org-mode file. E.g., =:tangle yes=. Org-mode file. E.g., @code{:tangle yes}.
- no :: the default. The source code block is not - no :: the default. The source code block is not
exported to a source code file. E.g., =:tangle no=. exported to a source code file. E.g., @code{:tangle no}.
- other :: Any other string passed to the =:tangle= header argument - other :: Any other string passed to the @code{:tangle} header argument
is interpreted as a file basename to which the block will is interpreted as a file basename to which the block will
be exported. E.g., =:tangle basename=. be exported. E.g., @code{:tangle basename}.
@subsubsection =:session=
:PROPERTIES:
:CUSTOM_ID: header-argument-session
:END:
@node @code{session}, @code{noweb}, @code{tangle}, Specific Header Arguments
@subsubsection @code{session}
Start a session for an interpreted language where state is Start a session for an interpreted language where state is
preserved. This applies particularly to the supported languages preserved. This applies particularly to the supported languages
python, R and ruby. python, R and ruby.
By default, a session is not started. By default, a session is not started.
A string passed to the =:session= header argument will give the A string passed to the @code{:session} header argument will give the
session a name. This makes it possible to run concurrent session a name. This makes it possible to run concurrent
sessions for each interpreted language. sessions for each interpreted language.
@subsubsection =:noweb= @node @code{noweb}, @code{cache}, @code{session}, Specific Header Arguments
:PROPERTIES: @subsubsection @code{noweb}
:CUSTOM_ID: header-argument-noweb
:END:
Controls the expansion of [[noweb-reference-syntax][noweb syntax]] references in a Controls the expansion of [[noweb-reference-syntax][noweb syntax]] references in a
source code block. This header argument can have one of two source code block. This header argument can have one of two
values: =yes= or =no=. values: @code{yes} or @code{no}.
- =no= :: the default. No [[noweb-reference-syntax][noweb syntax]] specific action is taken - @code{no} :: the default. No [[noweb-reference-syntax][noweb syntax]] specific action is taken
on evaluating source code blocks/ However, noweb references on evaluating source code blocks/ However, noweb references
will still be expanded during tangling. will still be expanded during tangling.
- =yes= :: all [[noweb-reference-syntax][noweb syntax]] references in the body of the source - @code{yes} :: all [[noweb-reference-syntax][noweb syntax]] references in the body of the source
code block will be expanded before the block is evaluated. code block will be expanded before the block is evaluated.
@subsubheading Noweb Prefix Lines @subsubheading Noweb Prefix Lines
Noweb insertions are now placed behind the line prefix of the Noweb insertions are now placed behind the line prefix of the
=<<reference>>=. @code{<<reference>>}.
This behavior is illustrated in the following example. Because This behavior is illustrated in the following example. Because
the =<<example>>= noweb reference appears behind the SQL the @code{<<example>>} noweb reference appears behind the SQL
comment syntax, each line of the expanded noweb reference will comment syntax, each line of the expanded noweb reference will
be commented. be commented.
@ -11685,80 +11681,72 @@ above features to work correctly.
Thanks to Sébastien Vauban for this idea. Thanks to Sébastien Vauban for this idea.
@subsubsection =:cache= @node @code{cache}, , @code{noweb}, Specific Header Arguments
:PROPERTIES: @subsubsection @code{cache}
:CUSTOM_ID: header-argument-cache
:END:
Controls the use of in-buffer caching of source code block Controls the use of in-buffer caching of source code block
results to avoid re-running unchanged source code blocks. This results to avoid re-running unchanged source code blocks. This
header argument can have one of two values: =yes= or =no=. header argument can have one of two values: @code{yes} or @code{no}.
- =no= :: The default. No caching takes place and the source - @code{no} :: The default. No caching takes place and the source
code block will be run every time it is evaluated. code block will be run every time it is evaluated.
- =yes= :: every time the source code block is run a sha1 hash of - @code{yes} :: every time the source code block is run a sha1 hash of
the code and arguments passed to the block will be the code and arguments passed to the block will be
generated. This hash is packed into the =#+results:= line generated. This hash is packed into the @code{#+results:} line
of the results and will be checked on subsequent executions of the results and will be checked on subsequent executions
of the source code block. If the source code block has not of the source code block. If the source code block has not
changed since the last time it was evaluated, it will not be changed since the last time it was evaluated, it will not be
re-evaluated. re-evaluated.
@node Results, Noweb Reference Syntax, Header Arguments, Working With Source Code
@section Results @section Results
:PROPERTIES: The way in which results are handled depends on whether a
:CUSTOM_ID: results-specification [[header-argument-session][session]] is invoked, as well as on whether
:END: @code{:results value} or @code{:results output} is used. The following
table shows the possibilities:
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= | | | non-session (default) | =:session= |
|-------------------+--------------------------+-------------------------------------| |-------------------+--------------------------+-------------------------------------|
| =:results value= | value of last expression | value of last expression | | =:results value= | value of last expression | value of last expression |
| =:results output= | contents of stdout | concatenation of interpreter output | | =:results output= | contents of stdout | concatenation of interpreter output |
*Note:* With =:results value=, the result in both =:session= and *Note:* With @code{:results value}, the result in both @code{:session} and
non-session is returned to Org-mode as a table (a one- or non-session is returned to Org-mode as a table (a one- or
two-dimensional vector of strings or numbers) when appropriate. two-dimensional vector of strings or numbers) when appropriate.
@subsection Non-session @subsection Non-session
@subsubsection =:results value= @subsubsection @code{:results value}
This is the default. Internally, the value is obtained by This is the default. Internally, the value is obtained by
wrapping the code in a function definition in the external wrapping the code in a function definition in the external
language, and evaluating that function. Therefore, code should be language, and evaluating that function. Therefore, code should be
written as if it were the body of such a function. In particular, written as if it were the body of such a function. In particular,
note that python does not automatically return a value from a note that python does not automatically return a value from a
function unless a =return= statement is present, and so a function unless a @code{return} statement is present, and so a
'return' statement will usually be required in python. 'return' statement will usually be required in python.
This is the only one of the four evaluation contexts in which the This is the only one of the four evaluation contexts in which the
code is automatically wrapped in a function definition. code is automatically wrapped in a function definition.
@subsubsection =:results output= @subsubsection @code{:results output}
The code is passed to the interpreter as an external process, and The code is passed to the interpreter as an external process, and
the contents of the standard output stream are returned as the contents of the standard output stream are returned as
text. (In certain languages this also contains the error output text. (In certain languages this also contains the error output
stream; this is an area for future work.) stream; this is an area for future work.)
@subsection =:session= @subsection @code{:session}
@subsubsection =:results value= @subsubsection @code{:results value}
The code is passed to the interpreter running as an interactive The code is passed to the interpreter running as an interactive Emacs
Emacs inferior process. The result returned is the result of the inferior process. The result returned is the result of the last
last evaluation performed by the interpreter. (This is obtained in evaluation performed by the interpreter. (This is obtained in a
a language-specific manner: the value of the variable =_= in language-specific manner: the value of the variable @code{_} in python
python and ruby, and the value of =.Last.value= in R). and ruby, and the value of @code{.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:
@subsubsection @code{: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
@code{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 @example
#+begin_src python :results output #+begin_src python :results output
@ -11791,7 +11779,7 @@ above features to work correctly.
unnecessary here). unnecessary here).
@node Noweb Reference Syntax, Key Bindings & Useful Functions, Header Arguments, Working With Source Code @node Noweb Reference Syntax, Key Bindings & Useful Functions, Results, Working With Source Code
@section Noweb Reference Syntax @section Noweb Reference Syntax
The [[http://www.cs.tufts.edu/~nr/noweb/][Noweb]] Literate Programming system allows named blocks of code to 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: be referenced by using the familiar Noweb syntax: