org-babel-expand-body:lang function needs to be implemented by every
language, and is used to expand the body of a code block for
execution or tangling
adding a suite of functions to org-babel.el which can be used to
handle hlines, rownames, and columnnames in input tables. These
functions can be called from any org-babel-language.el file.
done in close collaboration with Dan Davison
Prior to this, a terminal hline would leave dangling empty cells:
#+TBLNAME: A
|---+---+---|
| a | b | c |
|---+---+---|
#+begin_src emacs-lisp :var tab=A
tab
#+end_src
#+results:
|---+---+---|
| a | b | c |
|---+---+---|
| | | |
Previously "R" could overshadow "Ruby", and "C" could overshadow
"Clojure", causing blocks of the longer language name to fail to
load. This issue has now been fixed
thanks to Maurizio Vitale for the suggestion. This allows literal
values to be passed to code blocks through `sbe' without forcing the
use of quotes inside the table.
This deals with external process :results value mode for R, ruby,
python, perl and clojure: if the shell process has a non-zero exit
code, a buffer containing stderr is displayed.
Prior to this commit,
OUTPUT-BUFFER nil
REPLACE 'replace
ERROR-BUFFER 'current-buffer
resulted in stdout going with stderr to the current buffer, contra the
docstring. With this change stdout is discarded in this case. The
docstring does stipulate that stdout always should go to *Shell
Command Output*; this change does not make that happen in this case.
At this commit, org-babel-shell-command-on-region is a direct copy of
shell-command-on-region. In addition to switching to use the org-babel
version, we change the argument passed so that they agree with the
docstring of s-c-o-r.
Despite the change in arguments, the same behaviour results because
s-c-o-r does not behave as documented in emacs23. Future commits will
be able to fix these bugs in the org-babel version, as necessary.
This change fixes a bug in the remote execution branch, involving the
way that org-babel-tramp-handle-call-process-region is used
to (conditionally) handle calls to call-process-region. When
org-babel-execute-src-block called itself recursively (e.g. when
resolving a reference to another src block), a circular binding of
symbols and values resulted.
When using ':results value' in certain situations, results are written
to file by the foreign language process and subsequently read from
file by emacs into an elisp table structure. If the foreign language
process is running remotely, then the results are written
remotely. These changes ensure that in that case, an appropriate
remote file name is constructed to read the remote data.
These changes solve two problems: both are discussed in the following thread
http://lists.gnu.org/archive/html/tramp-devel/2010-02/msg00025.html
of which a summary follows.
Firstly, shell-command-on-region does not work with tramp in the same
way that shell-command does. I.e. whereas
(let ((default-directory "/user@remote-host:"))
(shell-command "hostname" t))
gives the remote hostname,
(let ((default-directory "/user@remote-host:"))
(shell-command-on-region (point) (mark) "hostname" t))
does not.
The reason is that shell-command-on-region calls call-process-region,
which does not use a tramp handler for remote files. However, such a
file handler does exist (unused) in the tramp sources:
tramp-handle-call-process-region. There is a slight problem in that
there is a bug in that function definition in current tramp (which has
persisted because the function is not normally used).
Therefore, we define an org-babel version of
tramp-handle-call-process-region which fixes the bug, and we bind
call-process-region to org-babel-tramp-handle-call-process-region for
the duration of org-babel-execute-src-block.
This introduces a new header argument :dir. For the duration of source
block execution, default-directory is set to the value of this header
argument. Consequences include:
- external interpreter processes run in that directory
- new session processes run in that directory (but existing ones are unaffected)
- relative paths for file output are relative to that directory
The name of a directory on a remote machine may be specified with
tramp syntax (/user@host:path), in which case the interpreter
executable will be sought in tramp-remote-path, and if found will
execute on the remote machine in the specified remote directory.
Use shell-command-on-region, bringing R into line with ruby, python,
clojure, shell. In addition to consistency (and perhaps efficiency),
this will also be preferable in the case of a remote R process because
it means that transfer of the input to the remote process is dealt
with automatically by tramp.
Before this change we have
#+begin_src ruby :results value :session
["1", "3"]
#+end_src
#+results:
: 1", "3
After, we have
#+begin_src ruby :results value :session
["1", "3"]
#+end_src
#+results:
| 1 | 3 |
This change provides for better export of named source-code blocks,
with specific support for more attractive html export. The arguments
are included with the source code name, and both the source code name
and code body are wrapped in a div to support styling with css. For
example the following CSS can be used to associate a source-code block
name with it's code body, and to slightly indent the body.
.org-src-container {
border-left: 4px solid gray;
padding: 0.5em 0.5em 0.5em 1em; }
.org-src-container pre {
margin-left: 1em; }
the progress-marker local variable set inside of a let in
org-exp-blocks is used to constrain searches in org-babel-exp to
ensure that a babel block doesn't overwrite non-babel src blocks
When exporting to html the source-code block name will be included
as a <label> immediately preceding the exported code. This <label>
is decorated with the 'org-src-name' css class.
When exporting to LaTeX with the listings package the source-code
block name will be included as a listings \title for the code
block. Currently the name will not be exported when the listings
package is not in use.
So, for example since the following <<example>> noweb reference
appears behind the SQL comment syntax the entire inserted body will
also be SQL commented
-- <<example>>
expands to
-- this is the
-- multi-line body of example
Note that noweb replacement text which 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.
Variable names in gnuplot source code preceded by the '$' character
will be expanded to their value before the code is executed. For
example the following will results in the evaluation of 'plot
sin(x)' by gnuplot.
"sin(x)"
plot $fun
Insertion of new results was failing if the block was followed by
end-of-buffer. Also, if the block was followed by non-empty lines, the
\#+resname was being inserted away from column 0.
pressing tab while on the front of a results line will fold the
results in the same manner as tabbing on the front of a block will
fold the block. To automatically hide all blocks when entering a
new file add the `org-babel-result-hide-all' function to your
`org-mode-hook'
"results" is now an acceptable alias for "resname". Org-babel
will begin inserting results using the "results" option however
either option will remain viable moving forward.
The initial `org-babel-hash-show' characters of the hash will
remain visible. Pressing C-c C-c with the point on one of these
initial characters will copy the hash to the kill ring, should you
need to know it for any particular reason.
This can be overridden with the use of the header argument :cache on
the block, or subtree level. To set the global behavior to caching
add the following to your emacs init
(setq org-babel-default-header-args
(delete '(:nocache) org-babel-default-header-args))
This commit expands the #+resname: line to include a sha1 hash of
the contents of the source-code block (including header arguments).
This hash is saved in raw text in the resname line. When a source
block is evaluated it's hash is recalculated and checked against the
hash in it's results line, if they are equal the current results are
returned with no recalculation.
Optional prefix argument when evaluating a source block will force
re-calculation.
caching behavior can be inhibited through the use of the :nocache
header argument. for global inhibition of caching add :nocache to
the `org-babel-default-header-args' variable.
it is now possible to only assign a portion of a value to a variable
in a source block. So for example the following will only assign
the second and third lines of the table 'example-table' to the
variable 'data'
:var data=example-table[1:2]
and the following will only assign the second column of the first row
:var data=example-table[0,1]
note that all indices are 0 based
it is possible to index into the results of source-code blocks as
well as tables. any number of dimensions can be indexed as long as
they are separated by ','s and ranges can be indexed using the ':'
operator. for more information on indexing behavior see
`org-babel-ref-index-list'
With this change, if :file <filepath> is specified, ruby and python
blindly output a link to <filepath>. Responsibility for creating the
contents in <filepath> lies with the python/ruby code.
Doug Hellmann writes:
> Some calendar systems (Google, Zimbra) handle subscriptions to
> multiple calendars (or to an account) by grouping them under a single
> caldav directory in the calendar tree. org-mac-iCal assumes there is
> only one ics file created per caldav directory, so while it *creates*
> all of the needed merged ics files, it only copies one of them to
> ~/Library/Calendar before importing the contents into the diary.
A "functional-style" source block is one in which the name is followed
immediately by a parenthesised argument. An example is the following
"function", which generates n uniform random numbers:
\#+srcname: rand(n)
\#+begin_src R
runif(n)
\#+end_src
With these changes, such source blocks are passed over to the export
machinery in the following form:
\#+begin_src org-babel-lob
<function-def-keyword> rand(n):
\#+end_src
\#+begin_src R <switches>
<indent>runif(n)
\#+end_src
where <function-def-keyword> is the value of
org-babel-function-def-export-keyword, which defaults to "function",
<switches> are the src block switches that belonged to the original
block, and <indent> is the whitespace indent of the function body, the
width of which is determined by org-babel-function-def-export-indent.
org-babel-lob is a simple major mode responsible for fontification of
the blocks corresponding to the function definition line (as opposed
to the function body).
This adds a new terminal (sixth) element to the list returned from
org-babel-get-src-block-info. It is used when exporting the code of
"functional style" code blocks, i.e. those in which the name of the
block is followed by a parenthesised argument list (or an empty pair
of parentheses).
- org-babel-get-src-block-info returns the name of the block as a new
fifth element.
- org-babel-get-src-block-info incorporates the parenthesised variable
references into the header arg list, with precendence given to
explicit :var references, as before.
- remove function org-babel-get-src-block-name
- remove function org-babel-get-src-block-function-args
org-babel-get-src-block-function-args now returns a list
(lang body params-alist switches srcname)
where, unless a non-nil value for the optional argument is passed,
params-alist contains any :var entries acquired from the parenthesised
argument list following the srcname.
The switches are flags like -n and must *precede* the first colon
after the language (i.e. precede the first header argument). So the
general src block syntax is
\#+begin_src lang <switches> :header1 val1 :header2 val2 ...
...
org-babel-get-src-block-info now returns a list
(lang body params-alist switches)
noweb references which include ()s are now evaluated. It is
possible to pass arguments to the noweb references using the existing
lob argument syntax. So after this commit the following
<<example-block>>
will insert the body of "example-block", and the following
<<example-block()>>
will insert the results of "example-block", and the following
<<example-block(a=9)>>
will insert the results of "example-block" with argument "a" set to
the literal value of 9
This forces the #+lob regexp to match at the beginning of a line (with
optional preceding whitespace), and requires inline code blocks to be
surrounded by some whitespace.
Currently, python fontification is used for export of these lines, due
to some similarity between python function call syntax and #+lob call
syntax. This is implemented as a language type "babel", mapped to
python in org-src-lang-modes.
merging original change by Dan Davison which generalizes the types
of blocks exported by org-babel to include the following types
- inline
- lob
- block
1) source blocks can now reference source-blocks in other files using
the filename:sourcename syntax
2) on export all references are now made to explicitly point to the
original buffer using the filename:sourcename syntax. This ensures
that all references are correctly resolved on export, even when the
referenced source block has already been processed.
org-registry-assoc-all removed matching links from the registry. This meant
subsequent calls with the same parameters would return nothing.
Add another function for finding entries in the register, which used find-if to
get entries satisfying a predicate.
One half of this patch is a revert of c167a4ac32.
These changes are necessary so that :results output works correctly
with #+lob calls. For example the following example did not work:
--------------------------------------------------
3. :results output org -> doesn't work with #+lob:
--------------------------------------------------
\#+srcname: randthree(n,max)
\#+begin_src ruby
number = n
maximum = max
puts "* Random numbers\n" +
"Here are some random numbers: " +
(1..number).collect {|x| (rand * maximum).ceil }.join(", ") +
"."
\#+end_src
\#+lob: randthree(n=3,max=10) :results output org
When evaluating R code in a persistent session, lines of output
typically start with a single prompt character. However, under certain
circumstances, lines start with a concatenation of (primary and
secondary) prompt characters separated by spaces. This seems to be
related to having blank lines in the input. This fix ensures that all
such prompt characters are removed from the output.
And when merging header args, those from enclosing scopes take
precedence. For example, output to file from a source block is
implemented by (a) sending the output to file, and (b) having the
source block return the file name as its result. Before this change,
the file name returned could be set by a referenced source block (a
nested call), regardless of the value of the :file header arg of the
top-level source block.
Prior to this, reference resolution could fail with quoted
strings. E.g. this didn't work:
\#+srcname: py-id(a=1)
\#+begin_src python
a
\#+end_src
\#+lob: py-id(a="1")
This change allows org-file-properties to supply header args, and also
allows property inheritance if it has been enabled. Header-args
aquired from the item (or by inheritance) have precedence over those
aquired from org-file-properties.
If a [:file filename.ext] header arg is provided, then all graphical
output from the source block is captured on disk, and output of the
source block is a link to the resulting file, as with the
graphics-only languages such as gnuplot, ditaa, dot, asymptote. An
attempt is made to find a graphics device corresponding to the file
extension (currently .png, .jpg, .jpeg, .tiff, .bmp, .pdf, .ps,
.postscript are recognised); if that fails, png format output is
created.
Additionally, values for several arguments to the R graphics
device can be passed using header args:
:width :height :bg :units :pointsize
:antialias :quality :compression :res :type
:family :title :fonts :version :paper :encoding
:pagecentre :colormodel :useDingbats :horizontal
Arguments to the R graphics device that are not supported as header
args can be passed as a string in R argument syntax, using the header
arg :R-dev-args
An example block is (although both bg and fg can be passed directly as
header args)
\#+begin_src R :file z.pdf :width 8 :height 8 :R-dev-args bg="olivedrab", fg="hotpink"
plot(matrix(rnorm(100), ncol=2), type="l")
\#+end_src
Eric Schulte
Dan Davison
Julien Barnier
Carsten Dominik
Bernt Hansen
Christian Egli
Joel Boehland
Joel Boehland
Eric Schulte
Benjamin Andresen
James TD Smith