From df2252b87ff9c289ae7692b78c71fc8f61b7efb2 Mon Sep 17 00:00:00 2001 From: Dan Davison Date: Sun, 11 Apr 2010 11:48:07 -0400 Subject: [PATCH] Initialise new source code chapter with reference.org from Worg source-code-chapter.texi is just reference.org with level 1 headings replaced with @section, and level 2 headings replaced with @subsection, and with a top level @chapter node. This file is included in org.texi with an @include line for now. --- doc/org.texi | 2 + doc/source-code-chapter.texi | 1006 ++++++++++++++++++++++++++++++++++ 2 files changed, 1008 insertions(+) create mode 100644 doc/source-code-chapter.texi diff --git a/doc/org.texi b/doc/org.texi index 17615e0fa..1b3e078c2 100644 --- a/doc/org.texi +++ b/doc/org.texi @@ -10842,6 +10842,8 @@ 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:}. +@include source-code-chapter.texi + @node Miscellaneous, Hacking, Publishing, Top @chapter Miscellaneous diff --git a/doc/source-code-chapter.texi b/doc/source-code-chapter.texi new file mode 100644 index 000000000..eafe02d7f --- /dev/null +++ b/doc/source-code-chapter.texi @@ -0,0 +1,1006 @@ +@chapter Working with source code or Embedded Source Code + +@section Syntax + :PROPERTIES: + :CUSTOM_ID: syntax + :END: + +@subsection Source Code Block +The basic syntax of source code blocks in Org-babel is as follows: + +: #+begin_src language header-arguments +: body +: #+end_src + +- language :: The language of the code in the source code block. Valid + values must be members of =org-babel-interpreters=. +- header-arguments :: Header arguments control many facets of the + evaluation and output of source code blocks. See the [[header-arguments][Header + Arguments]] section for a complete review of available header + arguments. +- body :: The source code to be evaluated. An important key-binding + is C-c '. This calls =org-edit-src-code=, a function that brings + up an edit buffer containing the code using the Emacs major mode + appropriate to the language. You can edit your source code block + as you regularly would in Emacs. + +This syntax can be expanded by naming the source code block. + +: #+source: name +: #+begin_src language header-arguments +: +: #+end_src + +- 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. + +: #+lob: R-plot(data=R-plot-example-data) + +@subsection Aliases + Keyword aliases are intended to make Org-babel feel natural to + programmers fluent in a variety of languages. For example, + #+begin_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=. + #+begin_example + ,#+lob: R-plot(data=R-plot-example-data) + #+end_example + +@section Languages + :PROPERTIES: + :CUSTOM_ID: languages + :END: + + Org-babel has support for the following languages. + + | 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 | + + 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). + #+begin_src emacs-lisp + (require 'org-babel-identifier) + #+end_src + +@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 three different ways, +each more specific than the last. + +*** 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: + #+begin_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. + #+begin_src emacs-lisp :results silent :exports code + (setq org-babel-default-header-args + (cons '(:noweb . "yes") + (assq-delete-all :noweb org-babel-default-header-args))) + #+end_src + +*** Org-mode Properties + + Header arguments are also read from [[http://orgmode.org/manual/Properties-and-Columns.html#Properties-and-Columns][Org-mode properties]], which + means they can be set on the outline header level. For example, the + value of the =:cache= header argument will default to true in all + source code blocks under the following example of an Org-mode outline header: + #+begin_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. + +*** 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. + #+begin_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: + +*** =: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. + + #+begin_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: + + #+begin_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: + + #+begin_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: + + #+begin_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 + +**** 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. + #+begin_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=: + + #+begin_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=: + + #+begin_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. + + #+begin_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. + +*** =: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. + +**** 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=. + +**** type + The following options are mutually exclusive and specify what + type of results the code block will return. By default, results + are inserted as either a *table* or *scalar* depending on their + value. + + - table, vector :: The results should be interpreted as an Org-mode table. + If a single value is returned, Org-babel will convert it + into a table with one row and one column. E.g., =:results + value table=. + - scalar, verbatim :: The results should be interpreted + literally -- meaning they will not be converted into a table. + The results will be inserted into the Org-mode buffer as + quoted text. E.g., =:results value verbatim=. + - file :: The results will be interpreted as the path to a file, + and will be inserted into the Org-mode buffer as a file + link. E.g., =:results value file=. + - raw, org :: The results are interpreted as raw Org-mode code and + are inserted directly into the buffer. If the results look + like a table they will be aligned as such by Org-mode. + E.g., =:results value raw=. + - html :: Results are assumed to be HTML and will be enclosed in + a =begin_html= block. E.g., =:results value html=. + - latex :: Results assumed to be LaTeX and are enclosed in a + =begin_latex= block. E.g., =:results value latex=. + - code :: Result are assumed to be parseable code and are + enclosed in a code block. E.g., =:results value code=. + - pp :: The result is converted to pretty-printed code and is + enclosed in a code block. This option currently supports + Emacs Lisp, python, and ruby. E.g., =:results value pp=. + +**** handling + The following results options indicate what Org-babel should do + with the results once they are collected. + + - silent :: The results will be echoed in the minibuffer but + will not be inserted into the Org-mode buffer. E.g., + =:results output silent=. + - replace :: The default value. The results will be inserted + into the Org-mode buffer. E.g., =:results output + replace=. + +*** =:file= + :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, + +*** =: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 + +#+begin_example + ,#+begin_src R :file myplot.png :dir ~/Work + matplot(matrix(rnorm(100), 10), type="l") + ,#+end_src +#+end_example + +**** 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 + +#+begin_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: + +#+begin_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. + +**** 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. +*** =: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=. + +*** =: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=. + +*** =: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. + +*** =: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. + +**** Noweb Prefix Lines + + Noweb insertions are now placed behind the line prefix of the + =<>=. + + This behavior is illustrated in the following example. Because + the =<>= noweb reference appears behind the SQL + comment syntax, each line of the expanded noweb reference will + be commented. + + This source code block: + + #+begin_example + -- <> + #+end_example + + + expands to: + + #+begin_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. + +*** =: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. + +**** Non-session +***** =:results value= + This is the default. Internally, the value is obtained by + wrapping the code in a function definition in the external + language, and evaluating that function. Therefore, code should be + written as if it were the body of such a function. In particular, + note that python does not automatically return a value from a + function unless a =return= statement is present, and so a + 'return' statement will usually be required in python. + + This is the only one of the four evaluation contexts in which the + code is automatically wrapped in a function definition. + +***** =:results output= + The code is passed to the interpreter as an external process, and + the contents of the standard output stream are returned as + text. (In certain languages this also contains the error output + stream; this is an area for future work.) + +**** =:session= +***** =:results value= + The code is passed to the interpreter running as an interactive + Emacs inferior process. The result returned is the result of the + last evaluation performed by the interpreter. (This is obtained in + a language-specific manner: the value of the variable =_= in + python and ruby, and the value of =.Last.value= in R). + +***** =:results output= + The code is passed to the interpreter running as an interactive + Emacs inferior process. The result returned is the concatenation + of the sequence of (text) output from the interactive + interpreter. Notice that this is not necessarily the same as what + would be sent to stdout if the same code were passed to a + non-interactive interpreter running as an external process. For + example, compare the following two blocks: + +#+begin_src python :results output + print "hello" + 2 + print "bye" +#+end_src + +#+resname: + : hello + : bye + + In non-session mode, the '2' is not printed and does not appear. + +#+begin_src python :results output :session + print "hello" + 2 + print "bye" +#+end_src + +#+resname: + : hello + : 2 + : bye + + But in =:session= mode, the interactive interpreter receives input '2' + and prints out its value, '2'. (Indeed, the other print statements are + unnecessary here). + +@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: + : <> + + 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 =<>= is a syntactically valid construct. If =<>= 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=: + #+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 + | =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 +*** org-babel-execute-src-block + :PROPERTIES: + :CUSTOM_ID: function-org-babel-execute-src-block + :END: + +#+begin_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 + +*** org-babel-open-src-block-result + :PROPERTIES: + :CUSTOM_ID: function-org-babel-open-src-block-result + :END: + +#+begin_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 + +*** org-babel-load-in-session + :PROPERTIES: + :CUSTOM_ID: function-org-babel-load-in-session + :END: + +#+begin_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 + +*** org-babel-pop-to-session + :PROPERTIES: + :CUSTOM_ID: function-org-babel-pop-to-session + :END: + +#+begin_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 + +*** org-babel-tangle + :PROPERTIES: + :CUSTOM_ID: function-org-babel-tangle + :END: + +#+begin_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 + +*** org-babel-execute-subtree + :PROPERTIES: + :CUSTOM_ID: function-org-babel-execute-subtree + :END: + +#+begin_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 + +*** org-babel-execute-buffer + :PROPERTIES: + :CUSTOM_ID: function-org-babel-execute-buffer + :END: + +#+begin_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 + +*** org-babel-sha1-hash + :PROPERTIES: + :CUSTOM_ID: function-org-babel-sha1-hash + :END: + +#+begin_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 + +*** org-babel-goto-named-source-block + :PROPERTIES: + :CUSTOM_ID: function-org-babel-goto-named-source-block + :END: + +#+begin_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 + +*** org-babel-lob-ingest + :PROPERTIES: + :CUSTOM_ID: function-org-babel-lob-ingest + :END: + +#+begin_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. +#+begin_src sh + #!/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_src + +@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= + + +@section HTML 1 :noexport: + +#+begin_html + +#+end_html + +@subsection Note + - HTML 1 was keeping the babelfish code from exporting. Not sure + why or if the code itself is necessary, but moving it here gets + the fish on the page.