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