1705 lines
53 KiB
Org Mode
1705 lines
53 KiB
Org Mode
#+OPTIONS: H:3 num:nil toc:t
|
|
#+TITLE: org-babel --- facilitating communication between programming languages and people
|
|
#+SEQ_TODO: TODO PROPOSED | DONE DEFERRED REJECTED
|
|
#+STARTUP: oddeven
|
|
|
|
* Introduction
|
|
|
|
Org-Babel enables *communication* between programming languages and
|
|
between people.
|
|
|
|
Org-Babel provides:
|
|
- communication between programs :: Data passes seamlessly between
|
|
different programming languages, text, and tables.
|
|
- communication between people :: Data and calculations are embedded
|
|
in the same document as notes explanations and reports.
|
|
|
|
** communication between programs
|
|
|
|
Org-Mode supports embedded blocks of source code (in any language)
|
|
inside of Org documents. Org-Babel allows these blocks of code to be
|
|
executed from within Org-Mode with natural handling of their inputs
|
|
and outputs.
|
|
|
|
*** simple execution
|
|
with both scalar, file, and table output
|
|
|
|
|
|
*** reading information from tables
|
|
|
|
|
|
*** reading information from other source blocks (disk usage in your home directory)
|
|
|
|
This will work for Linux and Mac users, not so sure about shell
|
|
commands for windows users.
|
|
|
|
To run place the cursor on the =#+begin_src= line of the source block
|
|
labeled directory-pie and press =\C-c\C-c=.
|
|
|
|
#+srcname: directories
|
|
#+begin_src bash :results replace
|
|
cd ~ && du -sc * |grep -v total
|
|
#+end_src
|
|
|
|
#+resname: directories
|
|
| 64 | "Desktop" |
|
|
| 11882808 | "Documents" |
|
|
| 8210024 | "Downloads" |
|
|
| 879800 | "Library" |
|
|
| 57344 | "Movies" |
|
|
| 7590248 | "Music" |
|
|
| 5307664 | "Pictures" |
|
|
| 0 | "Public" |
|
|
| 152 | "Sites" |
|
|
| 8 | "System" |
|
|
| 56 | "bin" |
|
|
| 3274848 | "mail" |
|
|
| 5282032 | "src" |
|
|
| 1264 | "tools" |
|
|
|
|
#+srcname: directory-pie
|
|
#+begin_src R :var dirs = directories
|
|
pie(dirs[,1], labels = dirs[,2])
|
|
#+end_src
|
|
|
|
|
|
*** operations in/on tables
|
|
|
|
#+tblname: grades-table
|
|
| student | grade | letter |
|
|
|---------+-------+--------|
|
|
| 1 | 48 | F |
|
|
| 2 | 30 | F |
|
|
| 3 | 0 | F |
|
|
| 4 | 1 | F |
|
|
| 5 | 56 | F |
|
|
| 6 | 46 | F |
|
|
#+TBLFM: $2='(sbe random-score-generator)::$3='(sbe assign-grade (score $2))
|
|
|
|
#+srcname: assign-grade
|
|
#+begin_src ruby :var score=99
|
|
case score
|
|
when 0..59: "F"
|
|
when 60..69: "D"
|
|
when 70..79: "C"
|
|
when 80..89: "B"
|
|
when 90..100: "A"
|
|
else "Invalid Score"
|
|
end
|
|
#+end_src
|
|
|
|
#+srcname: random-score-generator
|
|
#+begin_src ruby
|
|
rand(100)
|
|
#+end_src
|
|
|
|
#+srcname: show-distribution
|
|
#+begin_src R :var grades=grades-table
|
|
hist(grades[,2])
|
|
#+end_src
|
|
|
|
|
|
** communication between people
|
|
Quick overview of Org-Mode's exportation abilities, with links to the
|
|
online Org-Mode documentation, a focus on source-code blocks, and the
|
|
exportation options provided by Org-Babel.
|
|
|
|
*** Interactive tutorial
|
|
This would demonstrate applicability to Reproducible Research, and
|
|
Literate Programming.
|
|
|
|
*** Tests embedded in documentation
|
|
org-babels own functional tests are contained in a large org-mode
|
|
table, allowing the test suite to be run be evaluation of the table
|
|
and the results to be collected in the same table.
|
|
|
|
|
|
* Tasks [21/32]
|
|
|
|
** TODO resolve references to other buffers
|
|
This would allow source blocks to call upon tables, source-blocks,
|
|
and results in other buffers.
|
|
|
|
See...
|
|
- [[file:lisp/org-babel-ref.el::TODO%20allow%20searching%20for%20names%20in%20other%20buffers][org-babel-ref.el:searching-in-other-buffers]]
|
|
- [[file:lisp/org-babel.el::defun%20org-babel%20find%20named%20result%20name][org-babel.el#org-babel-find-named-result]]
|
|
|
|
** TODO figure out how to handle graphic output
|
|
This is listed under [[* graphical output][graphical output]] in out objectives.
|
|
|
|
This should take advantage of the =:results file= option, and
|
|
languages which almost always produce graphical output should set
|
|
=:results file= to true by default. That would handle placing these
|
|
results in the buffer. Then if there is a combination of =silent= and
|
|
=file= =:results= headers we could drop the results to a temp buffer
|
|
and pop open that buffer...
|
|
|
|
** TODO share org-babel
|
|
how should we share org-babel?
|
|
|
|
- post to org-mode and ess mailing lists
|
|
- create a org-babel page on worg
|
|
- create a short screencast demonstrating org-babel in action
|
|
|
|
*** examples
|
|
we need to think up some good examples
|
|
|
|
**** interactive tutorials
|
|
This could be a place to use [[* org-babel assertions][org-babel assertions]].
|
|
|
|
for example the first step of a tutorial could assert that the version
|
|
of the software-package (or whatever) is equal to some value, then
|
|
source-code blocks could be used with confidence (and executed
|
|
directly from) the rest of the tutorial.
|
|
|
|
**** answering a text-book question w/code example
|
|
org-babel is an ideal environment enabling both the development and
|
|
demonstrationg of the code snippets required as answers to many
|
|
text-book questions.
|
|
|
|
**** something using tables
|
|
maybe something along the lines of calculations from collected grades
|
|
|
|
**** file sizes
|
|
Maybe something like the following which outputs sizes of directories
|
|
under the home directory, and then instead of the trivial =emacs-lisp=
|
|
block we could use an R block to create a nice pie chart of the
|
|
results.
|
|
|
|
#+srcname: sizes
|
|
#+begin_src bash :results replace
|
|
du -sc ~/*
|
|
#+end_src
|
|
|
|
#+begin_src emacs-lisp :var sizes=sizes :results replace
|
|
(mapcar #'car sizes)
|
|
#+end_src
|
|
|
|
** TODO command line execution
|
|
Allow source code blocks to be called form the command line. This
|
|
will be easy using the =sbe= function in [[file:lisp/org-babel-table.el][org-babel-table.el]].
|
|
|
|
This will rely upon [[* resolve references to other buffers][resolve references to other buffers]].
|
|
|
|
** TODO inline source code blocks [3/5]
|
|
Like the =\R{ code }= blocks
|
|
|
|
not sure what the format should be, maybe just something simple
|
|
like =src_lang[]{}= where lang is the name of the source code
|
|
language to be evaluated, =[]= is optional and contains any header
|
|
arguments and ={}= contains the code.
|
|
|
|
(see [[* (sandbox) inline source blocks][the-sandbox]])
|
|
|
|
*** DONE evaluation with \C-c\C-c
|
|
Putting aside the header argument issue for now we can just run these
|
|
with the following default header arguments
|
|
- =:results= :: silent
|
|
- =:exports= :: results
|
|
|
|
*** DONE inline exportation
|
|
Need to add an interblock hook (or some such) through org-exp-blocks
|
|
*** DONE header arguments
|
|
We should make it possible to use header arguments.
|
|
|
|
*** TODO fontification
|
|
we should color these blocks differently
|
|
|
|
*** TODO refine html exportation
|
|
should use a span class, and should show original source in tool-tip
|
|
|
|
** TODO allow tables with hline to be passed as args into R
|
|
This doesn't seem to work at the moment (example below). It would
|
|
also be nice to have a natural way for the column names of the org
|
|
table to become the column names of the R data frame, and to have
|
|
the option to specify that the first column is to be used as row
|
|
names in R (these must be unique). But this might require a bit of
|
|
thinking about.
|
|
|
|
|
|
#+TBLNAME: egtable
|
|
| col1 | col2 | col3 |
|
|
|------+---------+------|
|
|
| 1 | 2 | 3 |
|
|
| 4 | schulte | 6 |
|
|
|
|
#+begin_src R var tabel=egtable
|
|
tabel
|
|
#+end_src
|
|
|
|
Another example is in the [[*operations%20in%20on%20tables][grades example]].
|
|
|
|
** PROPOSED conversion between org-babel and noweb (e.g. .Rnw) format
|
|
I haven't thought about this properly. Just noting it down. What
|
|
Sweave uses is called "R noweb" (.Rnw).
|
|
|
|
I found a good description of noweb in the following article (see
|
|
the [[http://www.cs.tufts.edu/~nr/pubs/lpsimp.pdf][pdf]]).
|
|
|
|
I think there are two parts to noweb, the construction of
|
|
documentation and the extraction of source-code (with notangle). *documentation*: org-mode handles all of our documentation needs in
|
|
a manner that I believe is superior to noweb. *source extraction* At this point I don't see anyone writing large
|
|
applications with 100% of the source code contained in org-babel
|
|
files, rather I see org-babel files containing things like
|
|
- notes with active code chunks
|
|
- interactive tutorials
|
|
- requirements documents with code running test suites
|
|
- and of course experimental reports with the code to run the
|
|
experiment, and perform analysis
|
|
|
|
Basically I think the scope of the programs written in org-babel
|
|
(at least initially) will be small enough that it wont require the
|
|
addition of a tangle type program to extract all of the source code
|
|
into a running application.
|
|
|
|
On the other hand, since we already have named blocks of source
|
|
code which reference other blocks on which they rely, this
|
|
shouldn't be too hard to implement either on our own, or possibly
|
|
relying on something like noweb/notangle.
|
|
|
|
** PROPOSED Create objects in top level (global) environment in R?
|
|
At the moment, objects created by computations performed in the
|
|
code block are evaluated in the scope of the
|
|
code-block-function-body and therefore disappear when the code
|
|
block is evaluated {unless you employ some extra trickery like
|
|
assign('name', object, env=globalenv()) }. I think it will be
|
|
desirable to also allow for a style wherein objects that are
|
|
created in one code block persist in the R global environment and
|
|
can be re-used in a separate block.
|
|
|
|
This is what Sweave does, and while I'm not saying we have to be
|
|
the same as Sweave, it wouldn't be hard for us to provide the same
|
|
behaviour in this case; if we don't, we risk undeservedly being
|
|
written off as an oddity by some.
|
|
|
|
IOW one aspect of org-babel is that of a sort of functional
|
|
meta-programming language. This is crazy, in a very good
|
|
way. Nevertheless, wrt R I think there's going to be a lot of value
|
|
in providing for a working style in which the objects are stored in
|
|
the R session, rather than elisp/org buffer. This will be a very
|
|
familiar working style to lots of people.
|
|
|
|
There are no doubt a number of different ways of accomplishing
|
|
this, the simplest being a hack like adding
|
|
|
|
#+begin_src R
|
|
for(objname in ls())
|
|
assign(objname, get(objname), envir=globalenv())
|
|
#+end_src
|
|
|
|
to the source code block function body. (Maybe wrap it in an on.exit() call).
|
|
|
|
However this may deserve to be thought about more carefully, perhaps
|
|
with a view to having a uniform approach across languages. E.g. shell
|
|
code blocks have the same semantics at the moment (no persistence of
|
|
variables across code blocks), because the body is evaluated in a new
|
|
bash shell process rather than a running shell. And I guess the same
|
|
is true for python. However, in both these cases, you could imagine
|
|
implementing the alternative in which the body is evaluated in a
|
|
persistent interactive session. It's just that it's particularly
|
|
natural for R, seeing as both ESS and org-babel evaluate commands in a
|
|
single persistent R session.
|
|
|
|
** PROPOSED support for passing paths to files between source blocks
|
|
Maybe this should be it's own result type (in addition to scalars and
|
|
vectors). The reason being that some source-code blocks (for example
|
|
ditaa or anything that results in the creation of a file) may want to
|
|
pass a file path back to org-mode which could then be inserted into
|
|
the org-mode buffer as a link to the file...
|
|
|
|
This would allow for display of images upon export providing
|
|
functionality similar to =org-exp-blocks= only in a more general
|
|
manner.
|
|
|
|
** PROPOSED re-implement helper functions from org-R
|
|
Much of the power of org-R seems to be in it's helper functions for
|
|
the quick graphing of tables. Should we try to re-implement these
|
|
functions on top of org-babel?
|
|
|
|
I'm thinking this may be useful both to add features to org-babel-R and
|
|
also to potentially suggest extensions of the framework. For example
|
|
one that comes to mind is the ability to treat a source-code block
|
|
like a function which accepts arguments and returns results. Actually
|
|
this can be it's own TODO (see [[* source blocks as functions][source blocks as functions]]).
|
|
|
|
** DONE pass multiple reference arguments into R
|
|
Can we do this? I wasn't sure how to supply multiple 'var' header
|
|
args. Just delete this if I'm being dense.
|
|
|
|
This should be working, see the following example...
|
|
|
|
#+srcname: two-arg-example
|
|
#+begin_src R :var n=2 :var m=8
|
|
n + m
|
|
#+end_src
|
|
|
|
#+resname: two-arg-example
|
|
: 10
|
|
|
|
** DEFERRED use textConnection to pass tsv to R?
|
|
When passing args from the org buffer to R, the following route is
|
|
used: arg in buffer -> elisp -> tsv on file -> data frame in R. I
|
|
think it would be possible to avoid having to write to file by
|
|
constructing an R expression in org-babel-R-assign-elisp, something
|
|
like this
|
|
|
|
#+begin_src emacs-lisp
|
|
(org-babel-R-input-command
|
|
(format "%s <- read.table(textConnection(\"%s\"), sep=\"\\t\", as.is=TRUE)"
|
|
name (orgtbl-to-tsv value '(:sep "\t" :fmt org-babel-R-quote-tsv-field))))
|
|
#+end_src
|
|
|
|
I haven't tried to implement this yet as it's basically just
|
|
fiddling with something that works. The only reason for it I can
|
|
think of would be efficiency and I haven't tested that.
|
|
|
|
This Didn't work after an initial test. I still think this is a
|
|
good idea (I also think we should try to do something similar when
|
|
writing out results frmo R to elisp) however as it wouldn't result
|
|
in any functional changes I'm bumping it down to deferred for
|
|
now. [Eric]
|
|
|
|
for quick tests
|
|
|
|
#+tblname: quick-test
|
|
| 1 | 2 | 3 |
|
|
|
|
#+srcname: quick-test-src-blk
|
|
#+begin_src R :var vec=quick-test
|
|
mean(mean(vec))
|
|
#+end_src
|
|
|
|
: 2
|
|
|
|
** DEFERRED re-implement R evaluation using ess-command or ess-execute
|
|
I don't have any complaints with the current R evaluation code or
|
|
behaviour, but I think it would be good to use the ESS functions
|
|
from a political point of view. Plus of course it has the normal
|
|
benefits of an API (insulates us from any underlying changes etc). [DED]
|
|
|
|
I'll look into this. I believe that I looked at and rejected these
|
|
functions initially but now I can't remember why. I agree with
|
|
your overall point about using API's where available. I will take
|
|
a look back at these and either switch to using the ess commands,
|
|
or at least articulate under this TODO the reasons for using our
|
|
custom R-interaction commands. [Eric]
|
|
|
|
ess-execute
|
|
|
|
Lets just replace =org-babel-R-input-command= with =ess-execute=.
|
|
|
|
I tried this, and although it works in some situations, I find that =ess-command= will often just hang indefinitely without returning
|
|
results. Also =ess-execute= will occasionally hang, and pops up
|
|
the buffer containing the results of the command's execution, which
|
|
is undesirable. For now these functions can not be used. Maybe
|
|
someone more familiar with the ESS code can recommend proper usage
|
|
of =ess-command= or some other lower-level function which could be
|
|
used in place of [[file:lisp/org-babel-R.el::defun%20org-babel%20R%20input%20command%20command][org-babel-R-input-command]].
|
|
|
|
*** ess functions
|
|
|
|
#+begin_quote ess-command
|
|
(ess-command COM &optional BUF SLEEP NO-PROMPT-CHECK)
|
|
|
|
Send the ESS process command COM and delete the output
|
|
from the ESS process buffer. If an optional second argument BUF exists
|
|
save the output in that buffer. BUF is erased before use.
|
|
COM should have a terminating newline.
|
|
Guarantees that the value of .Last.value will be preserved.
|
|
When optional third arg SLEEP is non-nil, `(sleep-for (* a SLEEP))'
|
|
will be used in a few places where `a' is proportional to `ess-cmd-delay'.
|
|
#+end_quote
|
|
|
|
#+begin_quote ess-execute
|
|
(ess-execute COMMAND &optional INVERT BUFF MESSAGE)
|
|
|
|
Send a command to the ESS process.
|
|
A newline is automatically added to COMMAND. Prefix arg (or second arg
|
|
INVERT) means invert the meaning of
|
|
`ess-execute-in-process-buffer'. If INVERT is 'buffer, output is
|
|
forced to go to the process buffer. If the output is going to a
|
|
buffer, name it *BUFF*. This buffer is erased before use. Optional
|
|
fourth arg MESSAGE is text to print at the top of the buffer (defaults
|
|
to the command if BUFF is not given.)
|
|
#+end_quote
|
|
|
|
*** out current setup
|
|
|
|
1) The body of the R source code block is wrapped in a function
|
|
2) The function is called inside of a =write.table= function call
|
|
writing the results to a table
|
|
3) The table is read using =org-table-import=
|
|
|
|
** DEFERRED Rework Interaction with Running Processes [0/3]
|
|
*** TODO ability to select which of multiple sessions is being used
|
|
Increasingly it is looking like we're going to want to run all
|
|
source code blocks in comint buffer (sessions). Which will have
|
|
the benefits of
|
|
1) allowing background execution
|
|
2) maintaining state between source-blocks
|
|
- allowing inline blocks w/o header arguments
|
|
|
|
**** R sessions
|
|
(like ess-switch-process in .R buffers)
|
|
|
|
Maybe this could be packaged into a header argument, something
|
|
like =:R_session= which could accept either the name of the
|
|
session to use, or the string =prompt=, in which case we could use
|
|
the =ess-switch-process= command to select a new process.
|
|
|
|
*** TODO evaluation of shell code as background process?
|
|
After C-c C-c on an R code block, the process may appear to
|
|
block, but C-g can be used to reclaim control of the .org buffer,
|
|
without interrupting the R evalution. However I believe this is not
|
|
true of bash/sh evaluation. [Haven't tried other languages] Perhaps
|
|
a solution is just to background the individual shell commands.
|
|
|
|
The other languages (aside from emacs lisp) are run through the
|
|
shell, so if we find a shell solution it should work for them as
|
|
well.
|
|
|
|
Adding an ampersand seems to be a supported way to run commands in
|
|
the background (see [[http://www.emacswiki.org/emacs/ExecuteExternalCommand#toc4][external-commands]]). Although a more extensible
|
|
solution may involve the use of the [[elisp:(progn (describe-function 'call-process-region) nil)][call-process-region]] function.
|
|
|
|
Going to try this out in a new file [[file:lisp/org-babel-proc.el][org-babel-proc.el]]. This should
|
|
contain functions for asynchronously running generic shell commands
|
|
in the background, and then returning their input.
|
|
|
|
**** partial update of org-mode buffer
|
|
The sleekest solution to this may be using a comint buffer, and
|
|
then defining a filter function which would incrementally interpret
|
|
the results as they are returned, including insertion into the
|
|
org-mode buffer. This may actually cause more problems than it is
|
|
worth, what with the complexities of identifying the types of
|
|
incrementally returned results, and the need for maintenance of a
|
|
process marker in the org buffer.
|
|
|
|
**** 'working' spinner
|
|
It may be nice and not too difficult to place a spinner on/near the
|
|
evaluating source code block
|
|
|
|
*** TODO conversion of output from interactive shell, R (and python) sessions to org-babel buffers
|
|
[DED] This would be a nice feature I think. Although a org-babel purist
|
|
would say that it's working the wrong way round... After some
|
|
interactive work in a *R* buffer, you save the buffer, maybe edit
|
|
out some lines, and then convert it to org-babel format for
|
|
posterity. Same for a shell session either in a *shell* buffer, or
|
|
pasted from another terminal emulator. And python of course.
|
|
|
|
** DONE ensure that table ranges work
|
|
when a table range is passed to org-babel as an argument, it should be
|
|
interpreted as a vector.
|
|
|
|
| 1 | 2 | simple |
|
|
| 2 | 3 | Fixnum:1 |
|
|
| 3 | 4 | Array:123456 |
|
|
| 4 | 5 | |
|
|
| 5 | 6 | |
|
|
| 6 | 7 | |
|
|
#+TBLFM: @1$3='(sbe simple-sbe-example (n 4))::@2$3='(sbe task-table-range (n @1$1..@6$1))::@3$3='(sbe task-table-range (n (@1$1..@6$1)))
|
|
|
|
#+srcname: simple-sbe-example
|
|
#+begin_src emacs-lisp
|
|
"simple"
|
|
#+end_src
|
|
|
|
#+srcname: task-table-range
|
|
#+begin_src ruby :var n=simple-sbe-example
|
|
"#{n.class}:#{n}"
|
|
#+end_src
|
|
|
|
#+srcname: simple-results
|
|
#+begin_src emacs-lisp :var n=task-table-range(n=(1 2 3))
|
|
n
|
|
#+end_src
|
|
|
|
#+resname: simple-results
|
|
: Array:123
|
|
|
|
#+srcname: task-arr-referent
|
|
#+begin_src ruby :var ar=(1 2 3)
|
|
ar.size
|
|
#+end_src
|
|
|
|
#+resname: task-arr-referent
|
|
: 3
|
|
|
|
** DONE global variable indicating default to vector output
|
|
how about an alist... =org-babel-default-header-args= this may already
|
|
exist... just execute the following and all source blocks will default
|
|
to vector output
|
|
|
|
#+begin_src emacs-lisp
|
|
(setq org-babel-default-header-args '((:results . "vector")))
|
|
#+end_src
|
|
|
|
** DONE name named results if source block is named
|
|
currently this isn't happening although it should be
|
|
|
|
#+srcname: test-naming-named-source-blocks
|
|
#+begin_src emacs-lisp
|
|
:namer
|
|
#+end_src
|
|
|
|
#+resname: test-naming-named-source-blocks
|
|
: :namer
|
|
** DONE (simple caching) check for named results before source blocks
|
|
see the TODO comment in [[file:lisp/org-babel-ref.el::TODO%20This%20should%20explicitly%20look%20for%20resname%20lines%20before][org-babel-ref.el#org-babel-ref-resolve-reference]]
|
|
** DONE set =:results silent= when eval with prefix argument
|
|
|
|
#+begin_src emacs-lisp
|
|
'silentp
|
|
#+end_src
|
|
** DONE results-type header (vector/file) [3/3]
|
|
In response to a point in Dan's email. We should allow the user to
|
|
force scalar or vector results. This could be done with a header
|
|
argument, and the default behavior could be controlled through a
|
|
configuration variable.
|
|
|
|
#+srcname: task-trivial-vector
|
|
#+begin_src ruby :results replace vector
|
|
:scalar
|
|
#+end_src
|
|
|
|
#+resname:
|
|
| ":scalar" |
|
|
|
|
since it doesn't make sense to turn a vector into a scalar, lets
|
|
just add a two values...
|
|
|
|
- vector :: forces the results to be a vector (potentially 1 dimensional)
|
|
- file :: this throws an error if the result isn't a string, and
|
|
tries to treat it as a path to a file.
|
|
|
|
I'm just going to cram all of these into the =:results= header
|
|
argument. Then if we allow multiple header arguments it should
|
|
work out, for example one possible header argument string could be =:results replace vector file=, which would *replace* any existing
|
|
results forcing the results into an org-mode table, and
|
|
interpreting any strings as file paths.
|
|
|
|
*** DONE multiple =:results= headers
|
|
|
|
#+srcname: multiple-result-headers
|
|
#+begin_src ruby :results replace silent
|
|
:schulte
|
|
#+end_src
|
|
|
|
#+resname:
|
|
|
|
*** DONE file result types
|
|
When inserting into an org-mode buffer create a link with the path
|
|
being the value, and optionally the display being the
|
|
=file-name-nondirectory= if it exists.
|
|
|
|
#+srcname: task-file-result
|
|
#+begin_src python :results replace file
|
|
"something"
|
|
#+end_src
|
|
|
|
#+resname:
|
|
[[something][something]]
|
|
|
|
|
|
This will be useful because blocks like =ditaa= and =dot= can return
|
|
the string path of their files, and can add =file= to their results
|
|
header.
|
|
|
|
*** DONE vector result types
|
|
|
|
#+srcname: task-force-results
|
|
#+begin_src emacs-lisp :results vector
|
|
8
|
|
#+end_src
|
|
|
|
#+resname:
|
|
| 8 |
|
|
|
|
** DONE results name
|
|
In order to do this we will need to start naming our results.
|
|
Since the source blocks are named with =#+srcname:= lines we can
|
|
name results with =#+resname:= lines (if the source block has no
|
|
name then no name is given to the =#+resname:= line on creation,
|
|
otherwise the name of the source block is used).
|
|
|
|
This will have the additional benefit of allowing results and
|
|
source blocks to be located in different places in a buffer (and
|
|
eventually in different buffers entirely).
|
|
|
|
#+srcname: developing-resnames
|
|
#+begin_src emacs-lisp :results silent
|
|
'schulte
|
|
#+end_src
|
|
|
|
Once source blocks are able to find their own =#+resname:= lines
|
|
we then need to...
|
|
|
|
#+srcname: sbe-w-new-results
|
|
#+begin_src emacs-lisp :results replace
|
|
(sbe "developing-resnames")
|
|
#+end_src
|
|
|
|
#+resname:
|
|
: schulte
|
|
|
|
*** TODO change the results insertion functions to use these lines
|
|
|
|
*** TODO teach references to resolve =#+resname= lines.
|
|
|
|
** DONE org-babel tests org-babel [1/1]
|
|
since we are accumulating this nice collection of source-code blocks
|
|
in the sandbox section we should make use of them as unit tests.
|
|
What's more, we should be able to actually use org-babel to run these
|
|
tests.
|
|
|
|
We would just need to cycle over every source code block under the
|
|
sandbox, run it, and assert that the return value is equal to what we
|
|
expect.
|
|
|
|
I have the feeling that this should be possible using only org-babel
|
|
functions with minimal or no additional elisp. It would be very cool
|
|
for org-babel to be able to test itself.
|
|
|
|
This is now done, see [[* Tests]].
|
|
|
|
*** DEFERRED org-babel assertions (may not be necessary)
|
|
These could be used to make assertions about the results of a
|
|
source-code block. If the assertion fails then the point could be
|
|
moved to the block, and error messages and highlighting etc... could
|
|
ensue
|
|
|
|
** DONE make C-c C-c work anywhere within source code block?
|
|
This seems like it would be nice to me, but perhaps it would be
|
|
inefficient or ugly in implementation? I suppose you could search
|
|
forward, and if you find #+end_src before you find #+begin_src,
|
|
then you're inside one. [DED]
|
|
|
|
Agreed, I think inside of the =#+srcname: line= would be useful as
|
|
well.
|
|
|
|
#+srcname: testing-out-cc
|
|
#+begin_src emacs-lisp
|
|
'schulte
|
|
#+end_src
|
|
|
|
** DONE integration with org tables
|
|
We should make it easy to call org-babel source blocks from org-mode
|
|
table formulas. This is practical now that it is possible to pass
|
|
arguments to org-babel source blocks.
|
|
|
|
See the related [[* (sandbox) integration w/org tables][sandbox]] header for tests/examples.
|
|
|
|
*** digging in org-table.el
|
|
In the past [[file:~/src/org/lisp/org-table.el::org%20table%20el%20The%20table%20editor%20for%20Org%20mode][org-table.el]] has proven difficult to work with.
|
|
|
|
Should be a hook in [[file:~/src/org/lisp/org-table.el::defun%20org%20table%20eval%20formula%20optional%20arg%20equation][org-table-eval-formula]].
|
|
|
|
Looks like I need to change this [[file:~/src/org/lisp/org-table.el::if%20lispp][if statement]] (line 2239) into a cond
|
|
expression.
|
|
|
|
** DONE source blocks as functions
|
|
|
|
Allow source code blocks to be called like functions, with arguments
|
|
specified. We are already able to call a source-code block and assign
|
|
it's return result to a variable. This would just add the ability to
|
|
specify the values of the arguments to the source code block assuming
|
|
any exist. For an example see
|
|
|
|
When a variable appears in a header argument, how do we differentiate
|
|
between it's value being a reference or a literal value? I guess this
|
|
could work just like a programming language. If it's escaped or in
|
|
quotes, then we count it as a literal, otherwise we try to look it up
|
|
and evaluate it.
|
|
|
|
** DONE folding of code blocks? [2/2]
|
|
[DED] In similar way to using outline-minor-mode for folding function
|
|
bodies, can we fold code blocks? #+begin whatever statements are
|
|
pretty ugly, and in any case when you're thinking about the overall
|
|
game plan you don't necessarily want to see the code for each Step.
|
|
|
|
*** DONE folding of source code block
|
|
Sounds good, and wasn't too hard to implement. Code blocks should
|
|
now be fold-able in the same manner as headlines (by pressing TAB
|
|
on the first line).
|
|
|
|
*** REJECTED folding of results
|
|
So, lets do a three-stage tab cycle... First fold the src block,
|
|
then fold the results, then unfold.
|
|
|
|
There's no way to tell if the results are a table or not w/o
|
|
actually executing the block which would be too expensive of an
|
|
operation.
|
|
|
|
** DONE selective export of text, code, figures
|
|
[DED] The org-babel buffer contains everything (code, headings and
|
|
notes/prose describing what you're up to, textual/numeric/graphical
|
|
code output, etc). However on export to html / LaTeX one might want
|
|
to include only a subset of that content. For example you might
|
|
want to create a presentation of what you've done which omits the
|
|
code.
|
|
|
|
[EMS] So I think this should be implemented as a property which can
|
|
be set globally or on the outline header level (I need to review
|
|
the mechanics of org-mode properties). And then as a source block
|
|
header argument which will apply only to a specific source code
|
|
block. A header argument of =:export= with values of
|
|
|
|
- =code= :: just show the code in the source code block
|
|
- =none= :: don't show the code or the results of the evaluation
|
|
- =results= :: just show the results of the code evaluation (don't
|
|
show the actual code)
|
|
- =both= :: show both the source code, and the results
|
|
|
|
this will be done in [[* (sandbox) selective export][(sandbox) selective export]].
|
|
|
|
** DONE a header argument specifying silent evaluation (no output)
|
|
This would be useful across all types of source block. Currently
|
|
there is a =:replace t= option to control output, this could be
|
|
generalized to an =:output= option which could take the following
|
|
options (maybe more)
|
|
|
|
- =t= :: this would be the default, and would simply insert the
|
|
results after the source block
|
|
- =replace= :: to replace any results which may already be there
|
|
- =silent= :: this would inhibit any insertion of the results
|
|
|
|
This is now implemented see the example in the [[* silent evaluation][sandbox]]
|
|
|
|
** DONE assign variables from tables in R
|
|
This is now working (see [[* (sandbox table) R][(sandbox-table)-R]]). Although it's not that
|
|
impressive until we are able to print table results from R.
|
|
|
|
** DONE insert 2-D R results as tables
|
|
everything is working but R and shell
|
|
|
|
*** DONE shells
|
|
|
|
*** DONE R
|
|
|
|
This has already been tackled by Dan in [[file:existing_tools/org-R.el::defconst%20org%20R%20write%20org%20table%20def][org-R:check-dimensions]]. The
|
|
functions there should be useful in combination with [[http://cran.r-project.org/doc/manuals/R-data.html#Export-to-text-files][R-export-to-csv]]
|
|
as a means of converting multidimensional R objects to emacs lisp.
|
|
|
|
It may be as simple as first checking if the data is multidimensional,
|
|
and then, if so using =write= to write the data out to a temporary
|
|
file from which emacs can read the data in using =org-table-import=.
|
|
|
|
Looking into this further, is seems that there is no such thing as a
|
|
scalar in R [[http://tolstoy.newcastle.edu.au/R/help/03a/3733.html][R-scalar-vs-vector]]. In that light I am not sure how to
|
|
deal with trivial vectors (scalars) in R. I'm tempted to just treat
|
|
them as vectors, but then that would lead to a proliferation of
|
|
trivial 1-cell tables...
|
|
|
|
** DONE allow variable initialization from source blocks
|
|
Currently it is possible to initialize a variable from an org-mode
|
|
table with a block argument like =table=sandbox= (note that the
|
|
variable doesn't have to named =table=) as in the following example
|
|
|
|
#+TBLNAME: sandbox
|
|
| 1 | 2 | 3 |
|
|
| 4 | schulte | 6 |
|
|
|
|
#+begin_src emacs-lisp :var table=sandbox :results replace
|
|
(message (format "table = %S" table))
|
|
#+end_src
|
|
|
|
: "table = ((1 2 3) (4 \"schulte\" 6))"
|
|
|
|
It would be good to allow initialization of variables from the results
|
|
of other source blocks in the same manner. This would probably
|
|
require the addition of =#+SRCNAME: example= lines for the naming of
|
|
source blocks, also the =table=sandbox= syntax may have to be expanded
|
|
to specify whether the target is a source code block or a table
|
|
(alternately we could just match the first one with the given name
|
|
whether it's a table or a source code block).
|
|
|
|
At least initially I'll try to implement this so that there is no need
|
|
to specify whether the reference is to a table or a source-code block.
|
|
That seems to be simpler both in terms of use and implementation.
|
|
|
|
This is now working for emacs-lisp, ruby and python (and mixtures of
|
|
the three) source blocks. See the examples in the [[* (sandbox) referencing other source blocks][sandbox]].
|
|
|
|
This is currently working only with emacs lisp as in the following
|
|
example in the [[* emacs lisp source reference][emacs lisp source reference]].
|
|
|
|
|
|
** TODO Add languages [0/5]
|
|
I'm sure there are many more that aren't listed here. Please add
|
|
them, and bubble any that you particularly care about up to the top.
|
|
|
|
Any new language should be implemented in a org-babel-lang.el file.
|
|
Follow the pattern set by [[file:lisp/org-babel-script.el][org-babel-script.el]], [[file:lisp/org-babel-shell.el][org-babel-shell.el]] and
|
|
[[file:lisp/org-babel-R.el][org-babel-R.el]].
|
|
|
|
*** TODO perl
|
|
This could probably be added to [[file:lisp/org-babel-script.el][org-babel-script.el]]
|
|
|
|
*** TODO java
|
|
|
|
*** TODO ditaa
|
|
(see [[* file result types][file result types]])
|
|
|
|
*** TODO dot
|
|
(see [[* file result types][file result types]])
|
|
|
|
*** TODO asymptote
|
|
(see [[* file result types][file result types]])
|
|
|
|
|
|
* Bugs [11/14]
|
|
|
|
** TODO non-orgtbl formatted lists
|
|
for example
|
|
|
|
#+srcname: this-doesn't-match-orgtbl
|
|
#+begin_src emacs-lisp :results replace
|
|
'((:results . "replace"))
|
|
#+end_src
|
|
|
|
#+resname: this-doesn't-match-orgtbl
|
|
|
|
** TODO collapsing consecutive newlines in string output
|
|
|
|
#+srcname: multi-line-string-output
|
|
#+begin_src ruby :results replace
|
|
"the first line ends here
|
|
|
|
|
|
and this is the second one
|
|
|
|
even a third"
|
|
#+end_src
|
|
|
|
#+resname:
|
|
: the first line ends here
|
|
: and this is the second one
|
|
: return even a third
|
|
|
|
** TODO cursor movement when evaluating source blocks
|
|
E.g. the pie chart example. Despite the save-window-excursion in
|
|
org-babel-execute:R. (I never learned how to do this properly: org-R
|
|
jumps all over the place...)
|
|
|
|
** DONE R-code broke on "org-babel" rename
|
|
|
|
#+srcname: bug-R-babels
|
|
#+begin_src R
|
|
8 * 2
|
|
#+end_src
|
|
|
|
** DONE error on trivial R results
|
|
|
|
So I know it's generally not a good idea to squash error without
|
|
handling them, but in this case the error almost always means that
|
|
there was no file contents to be read by =org-table-import=, so I
|
|
think it's ok.
|
|
|
|
#+srcname: bug-trivial-r1
|
|
#+begin_src R :results replace
|
|
pie(c(1, 2, 3), labels = c(1, 2, 3))
|
|
#+end_src
|
|
|
|
#+srcname: bug-trivial-r2
|
|
#+begin_src R :results replace
|
|
8
|
|
#+end_src
|
|
|
|
#+resname: bug-trivial-r2
|
|
: 8
|
|
|
|
#+srcname: bug-trivial-r3
|
|
#+begin_src R :results replace
|
|
c(1, 2, 3)
|
|
#+end_src
|
|
|
|
#+resname: bug-trivial-r3
|
|
| 1 |
|
|
| 2 |
|
|
| 3 |
|
|
|
|
** DONE ruby new variable creation (multi-line ruby blocks)
|
|
Actually it looks like we were dropping all but the last line.
|
|
|
|
#+srcname: multi-line-ruby-test
|
|
#+begin_src ruby :var table=bug-numerical-table :results replace
|
|
total = 0
|
|
table.each{|n| total += n}
|
|
total/table.size
|
|
#+end_src
|
|
|
|
#+resname:
|
|
: 2
|
|
|
|
** DONE R code execution seems to choke on certain inputs
|
|
Currently the R code seems to work on vertical (but not landscape)
|
|
tables
|
|
|
|
#+srcname: little-fake
|
|
#+begin_src emacs-lisp
|
|
"schulte"
|
|
#+end_src
|
|
|
|
#+begin_src R :var num=little-fake
|
|
num
|
|
#+end_src
|
|
|
|
#+resname:
|
|
: schulte
|
|
: 11
|
|
: 11
|
|
: 11
|
|
: schulte
|
|
: 9
|
|
: 9
|
|
: 11
|
|
|
|
#+srcname: set-debug-on-error
|
|
#+begin_src emacs-lisp :results silent
|
|
(setq debug-on-error t)
|
|
#+end_src
|
|
|
|
#+srcname: bug-numerical-table
|
|
#+begin_src emacs-lisp :results silent
|
|
'(1 2 3)
|
|
#+end_src
|
|
|
|
#+srcname: bug-R-number-evaluation
|
|
#+begin_src R :var table=bug-numerical-table :results replace
|
|
mean(mean(table))
|
|
#+end_src
|
|
|
|
#+resname:
|
|
: 2
|
|
|
|
#+tblname: bug-vert-table
|
|
| 1 |
|
|
| 2 |
|
|
| 3 |
|
|
|
|
#+srcname: bug-R-vertical-table
|
|
#+begin_src R :var table=bug-vert-table :results silent
|
|
mean(table)
|
|
#+end_src
|
|
|
|
** DEFERRED org bug/request: prevent certain org behaviour within code blocks
|
|
E.g. [[]] gets recognised as a link (when there's text inside the
|
|
brackets). This is bad for R code at least, and more generally
|
|
could be argued to be inappropriate. Is it difficult to get org to
|
|
ignore text in code blocks? [DED]
|
|
|
|
I believe Carsten addressed this recently on the mailing list with
|
|
the comment that it was indeed a difficult issue. I believe this
|
|
may be one area where we could wait for an upstream (org-mode) fix.
|
|
** DONE with :results replace, non-table output doesn't replace table output
|
|
And vice versa. E.g. Try this first with table and then with len(table) [DED]
|
|
#+begin_src python :var table=sandbox :results replace
|
|
table
|
|
#+end_src
|
|
|
|
| 1 | 2 | 3 |
|
|
| 4 | "schulte" | 6 |
|
|
: 2
|
|
|
|
Yes, this is certainly a problem. I fear that if we begin replacing
|
|
anything immediately following a source block (regardless of whether
|
|
it matches the type of our current results) we may accidentally delete
|
|
hand written portions of the user's org-mode buffer.
|
|
|
|
I think that the best solution here would be to actually start
|
|
labeling results with a line that looks something like...
|
|
|
|
#+results: name
|
|
|
|
This would have a couple of benefits...
|
|
1) we wouldn't have to worry about possibly deleting non-results
|
|
(which is currently an issue)
|
|
2) we could reliably replace results even if there are different types
|
|
3) we could reference the results of a source-code block in variable
|
|
definitions, which would be useful if for example we don't wish to
|
|
re-run a source-block every time because it is long-running.
|
|
|
|
Thoughts? If no-one objects, I believe I will implement the labeling
|
|
of results.
|
|
|
|
** DONE extra quotes for nested string
|
|
Well R appears to be reading the tables without issue...
|
|
|
|
these *should* be quoted
|
|
#+srcname: ls
|
|
#+begin_src sh :results replace
|
|
ls
|
|
#+end_src
|
|
|
|
| "COPYING" |
|
|
| "README.markdown" |
|
|
| "block" |
|
|
| "examples.org" |
|
|
| "existing_tools" |
|
|
| "intro.org" |
|
|
| "org-babel" |
|
|
| "rorg.org" |
|
|
| "test-export.html" |
|
|
| "test-export.org" |
|
|
|
|
#+srcname: test-quotes
|
|
#+begin_src ruby :var tab=ls
|
|
tab[1][0]
|
|
#+end_src
|
|
|
|
: README.markdown
|
|
|
|
#+srcname: test-quotes
|
|
#+begin_src R :var tab=ls
|
|
as.matrix(tab[2,])
|
|
#+end_src
|
|
|
|
: README.markdown
|
|
|
|
** DONE simple ruby arrays not working
|
|
|
|
As an example eval the following. Adding a line to test
|
|
|
|
#+srcname: simple-ruby-array
|
|
#+begin_src ruby
|
|
[3, 4, 5]
|
|
#+end_src
|
|
|
|
#+srcname: ruby-array-test
|
|
#+begin_src ruby :var ar = simple-ruby-array
|
|
ar.first
|
|
#+end_src
|
|
|
|
** DONE space trailing language name
|
|
fix regexp so it works when there's a space trailing the language name
|
|
|
|
#+srcname: test-trailing-space
|
|
#+begin_src ruby
|
|
:schulte
|
|
#+end_src
|
|
|
|
** DONE Args out of range error
|
|
|
|
The following block resulted in the error below [DED]. It ran without
|
|
error directly in the shell.
|
|
#+begin_src sh
|
|
cd ~/work/genopca
|
|
for platf in ill aff ; do
|
|
for pop in CEU YRI ASI ; do
|
|
rm -f $platf/hapmap-genos-$pop-all $platf/hapmap-rs-all
|
|
cat $platf/hapmap-genos-$pop-* > $platf/hapmap-genos-$pop-all
|
|
cat $platf/hapmap-rs-* > $platf/hapmap-rs-all
|
|
done
|
|
done
|
|
#+end_src
|
|
|
|
executing source block with sh...
|
|
finished executing source block
|
|
string-equal: Args out of range: "", -1, 0
|
|
|
|
the error =string-equal: Args out of range: "", -1, 0= looks like what
|
|
used to be output when the block returned an empty results string.
|
|
This should be fixed in the current version, you should now see the
|
|
following message =no result returned by source block=.
|
|
|
|
** DONE ruby arrays not recognized as such
|
|
|
|
Something is wrong in [[file:lisp/org-babel-script.el]] related to the
|
|
recognition of ruby arrays as such.
|
|
|
|
#+begin_src ruby :results replace
|
|
[1, 2, 3, 4]
|
|
#+end_src
|
|
|
|
| 1 | 2 | 3 | 4 |
|
|
|
|
#+begin_src python :results replace
|
|
[1, 2, 3, 4]
|
|
#+end_src
|
|
|
|
| 1 | 2 | 3 | 4 |
|
|
|
|
|
|
* Tests
|
|
|
|
Evaluate all the cells in this table for a comprehensive test of the
|
|
org-babel functionality.
|
|
*Note*: if you have customized =org-babel-default-header-args= then some
|
|
of these tests may fail.
|
|
|
|
#+TBLNAME: org-babel-tests
|
|
| functionality | block | arg | expected | results | pass |
|
|
|-------------------------+----------------------------+-----+-------------+-------------+------|
|
|
| basic evaluation | | | | | pass |
|
|
|-------------------------+----------------------------+-----+-------------+-------------+------|
|
|
| emacs lisp | basic-elisp | | 5 | 5 | pass |
|
|
| shell | basic-shell | | 6 | 6 | pass |
|
|
| ruby | basic-ruby | | org-babel | org-babel | pass |
|
|
| python | basic-python | | hello world | hello world | pass |
|
|
| R | basic-R | | 13 | 13 | pass |
|
|
|-------------------------+----------------------------+-----+-------------+-------------+------|
|
|
| tables | | | | | pass |
|
|
|-------------------------+----------------------------+-----+-------------+-------------+------|
|
|
| emacs lisp | table-elisp | | 3 | 3 | pass |
|
|
| ruby | table-ruby | | 1-2-3 | 1-2-3 | pass |
|
|
| python | table-python | | 5 | 5 | pass |
|
|
| R | table-R | | 3.5 | 3.5 | pass |
|
|
|-------------------------+----------------------------+-----+-------------+-------------+------|
|
|
| source block references | | | | | pass |
|
|
|-------------------------+----------------------------+-----+-------------+-------------+------|
|
|
| all languages | chained-ref-last | | Array | Array | pass |
|
|
|-------------------------+----------------------------+-----+-------------+-------------+------|
|
|
| source block functions | | | | | pass |
|
|
|-------------------------+----------------------------+-----+-------------+-------------+------|
|
|
| emacs lisp | defun-fibb | | fibbd | fibbd | pass |
|
|
| run over | Fibonacci | 0 | 1 | 1 | pass |
|
|
| a | Fibonacci | 1 | 1 | 1 | pass |
|
|
| variety | Fibonacci | 2 | 2 | 2 | pass |
|
|
| of | Fibonacci | 3 | 3 | 3 | pass |
|
|
| different | Fibonacci | 4 | 5 | 5 | pass |
|
|
| arguments | Fibonacci | 5 | 8 | 8 | pass |
|
|
|-------------------------+----------------------------+-----+-------------+-------------+------|
|
|
| bugs and tasks | | | | | pass |
|
|
|-------------------------+----------------------------+-----+-------------+-------------+------|
|
|
| simple ruby arrays | ruby-array-test | | 3 | 3 | pass |
|
|
| R number evaluation | bug-R-number-evaluation | | 2 | 2 | pass |
|
|
| multi-line ruby blocks | multi-line-ruby-test | | 2 | 2 | pass |
|
|
| forcing vector results | test-forced-vector-results | | Array | Array | pass |
|
|
#+TBLFM: $5='(if (= (length $3) 1) (progn (message (format "running %S" '(sbe $2 (n $3)))) (sbe $2 (n $3))) (sbe $2))::$6='(if (string= $4 $5) "pass" (format "expected %S but was %S" $4 $5))
|
|
|
|
** basic tests
|
|
|
|
#+srcname: basic-elisp
|
|
#+begin_src emacs-lisp :results silent
|
|
(+ 1 4)
|
|
#+end_src
|
|
|
|
#+srcname: basic-shell
|
|
#+begin_src sh :results silent
|
|
expr 1 + 5
|
|
#+end_src
|
|
|
|
|
|
#+srcname: basic-ruby
|
|
#+begin_src ruby :results silent
|
|
"org-babel"
|
|
#+end_src
|
|
|
|
#+srcname: basic-python
|
|
#+begin_src python :results silent
|
|
'hello world'
|
|
#+end_src
|
|
|
|
#+srcname: basic-R
|
|
#+begin_src R :results silent
|
|
b <- 9
|
|
b + 4
|
|
#+end_src
|
|
|
|
** read tables
|
|
|
|
#+tblname: test-table
|
|
| 1 | 2 | 3 |
|
|
| 4 | 5 | 6 |
|
|
|
|
#+srcname: table-elisp
|
|
#+begin_src emacs-lisp :results silent :var table=test-table
|
|
(length (car table))
|
|
#+end_src
|
|
|
|
#+srcname: table-ruby
|
|
#+begin_src ruby :results silent :var table=test-table
|
|
table.first.join("-")
|
|
#+end_src
|
|
|
|
#+srcname: table-python
|
|
#+begin_src python :var table=test-table
|
|
table[1][1]
|
|
#+end_src
|
|
|
|
#+srcname: table-R
|
|
#+begin_src R :var table=test-table
|
|
mean(mean(table))
|
|
#+end_src
|
|
|
|
** references
|
|
|
|
Lets pass a references through all of our languages...
|
|
|
|
Lets start by reversing the table from the previous examples
|
|
|
|
#+srcname: chained-ref-first
|
|
#+begin_src python :var table = test-table
|
|
table.reverse
|
|
#+end_src
|
|
|
|
Take the first part of the list
|
|
|
|
#+srcname: chained-ref-second
|
|
#+begin_src R :var table = chained-ref-first
|
|
table[1]
|
|
#+end_src
|
|
|
|
Turn the numbers into string
|
|
|
|
#+srcname: chained-ref-third
|
|
#+begin_src emacs-lisp :var table = chained-ref-second
|
|
(mapcar (lambda (el) (format "%S" el)) table)
|
|
#+end_src
|
|
|
|
and Check that it is still a list
|
|
|
|
#+srcname: chained-ref-last
|
|
#+begin_src ruby :var table=chained-ref-third
|
|
table.class.name
|
|
#+end_src
|
|
|
|
** source blocks as functions
|
|
|
|
#+srcname: defun-fibb
|
|
#+begin_src emacs-lisp :results silent
|
|
(defun fibbd (n) (if (< n 2) 1 (+ (fibbd (- n 1)) (fibbd (- n 2)))))
|
|
#+end_src
|
|
|
|
#+srcname: fibonacci
|
|
#+begin_src emacs-lisp :results silent :var n=7
|
|
(fibbd n)
|
|
#+end_src
|
|
|
|
** sbe tests
|
|
Testing the insertion of results into org-mode tables.
|
|
|
|
#+srcname: multi-line-output
|
|
#+begin_src ruby :results replace
|
|
"the first line ends here
|
|
|
|
|
|
and this is the second one
|
|
|
|
even a third"
|
|
#+end_src
|
|
|
|
#+resname:
|
|
: the first line ends here
|
|
: and this is the second one
|
|
: return even a third
|
|
|
|
#+srcname: multi-line-error
|
|
#+begin_src ruby :results replace
|
|
raise "oh nooooooooooo"
|
|
#+end_src
|
|
|
|
#+resname:
|
|
: -:5: warning: parenthesize argument(s) for future version
|
|
: -:5:in `main': oh nooooooooooo (RuntimeError)
|
|
: from -:8
|
|
|
|
| the first line ends here... | -:5: warning: parenthesize argument(s) for future version... |
|
|
#+TBLFM: $1='(sbe "multi-line-output")::$2='(sbe "multi-line-error")
|
|
|
|
** forcing results types tests
|
|
|
|
#+srcname: test-trivial-vector
|
|
#+begin_src emacs-lisp :results vector silent
|
|
8
|
|
#+end_src
|
|
|
|
#+srcname: test-forced-vector-results
|
|
#+begin_src ruby :var triv=test-trivial-vector :results silent
|
|
triv.class.name
|
|
#+end_src
|
|
|
|
|
|
* Sandbox
|
|
:PROPERTIES:
|
|
:CUSTOM_ID: sandbox
|
|
:END:
|
|
To run these examples evaluate [[file:lisp/org-babel-init.el][org-babel-init.el]]
|
|
|
|
** org-babel.el beginning functionality
|
|
|
|
#+begin_src sh :results replace
|
|
date
|
|
#+end_src
|
|
|
|
: Thu May 14 18:52:25 EDT 2009
|
|
|
|
#+begin_src ruby
|
|
Time.now
|
|
#+end_src
|
|
|
|
: Thu May 14 18:59:09 -0400 2009
|
|
|
|
#+begin_src python
|
|
"Hello World"
|
|
#+end_src
|
|
|
|
: Hello World
|
|
|
|
|
|
** org-babel-R
|
|
|
|
#+begin_src R :results replace
|
|
a <- 9
|
|
b <- 16
|
|
a + b
|
|
#+end_src
|
|
|
|
: 25
|
|
|
|
#+begin_src R
|
|
hist(rgamma(20,3,3))
|
|
#+end_src
|
|
|
|
|
|
** org-babel plays with tables
|
|
Alright, this should demonstrate both the ability of org-babel to read
|
|
tables into a lisp source code block, and to then convert the results
|
|
of the source code block into an org table. It's using the classic
|
|
"lisp is elegant" demonstration transpose function. To try this
|
|
out...
|
|
|
|
1. evaluate [[file:lisp/org-babel-init.el]] to load org-babel and friends
|
|
2. evaluate the transpose definition =\C-c\C-c= on the beginning of
|
|
the source block
|
|
3. evaluate the next source code block, this should read in the table
|
|
because of the =:var table=previous=, then transpose the table, and
|
|
finally it should insert the transposed table into the buffer
|
|
immediately following the block
|
|
|
|
*** Emacs lisp
|
|
|
|
#+begin_src emacs-lisp :results silent
|
|
(defun transpose (table)
|
|
(apply #'mapcar* #'list table))
|
|
#+end_src
|
|
|
|
|
|
#+TBLNAME: sandbox
|
|
| 1 | 2 | 3 |
|
|
| 4 | schulte | 6 |
|
|
|
|
#+begin_src emacs-lisp :var table=sandbox :results replace
|
|
(transpose table)
|
|
#+end_src
|
|
|
|
|
|
#+begin_src emacs-lisp
|
|
'(1 2 3 4 5)
|
|
#+end_src
|
|
|
|
| 1 | 2 | 3 | 4 | 5 |
|
|
|
|
*** Ruby and Python
|
|
|
|
#+begin_src ruby :var table=sandbox :results replace
|
|
table.first.join(" - ")
|
|
#+end_src
|
|
|
|
: "1 - 2 - 3"
|
|
|
|
#+begin_src python :var table=sandbox :results replace
|
|
table[0]
|
|
#+end_src
|
|
|
|
| 1 | 2 | 3 |
|
|
|
|
#+begin_src ruby :var table=sandbox :results replace
|
|
table
|
|
#+end_src
|
|
|
|
| 1 | 2 | 3 |
|
|
| 4 | "schulte" | 6 |
|
|
|
|
#+begin_src python :var table=sandbox :results replace
|
|
len(table)
|
|
#+end_src
|
|
|
|
: 2
|
|
|
|
| "__add__" | "__class__" | "__contains__" | "__delattr__" | "__delitem__" | "__delslice__" | "__doc__" | "__eq__" | "__format__" | "__ge__" | "__getattribute__" | "__getitem__" | "__getslice__" | "__gt__" | "__hash__" | "__iadd__" | "__imul__" | "__init__" | "__iter__" | "__le__" | "__len__" | "__lt__" | "__mul__" | "__ne__" | "__new__" | "__reduce__" | "__reduce_ex__" | "__repr__" | "__reversed__" | "__rmul__" | "__setattr__" | "__setitem__" | "__setslice__" | "__sizeof__" | "__str__" | "__subclasshook__" | "append" | "count" | "extend" | "index" | "insert" | "pop" | "remove" | "reverse" | "sort" |
|
|
|
|
*** (sandbox table) R
|
|
|
|
#+TBLNAME: sandbox_r
|
|
| 1 | 2 | 3 |
|
|
| 4 | schulte | 6 |
|
|
|
|
#+begin_src R :results replace
|
|
x <- c(rnorm(10, mean=-3, sd=1), rnorm(10, mean=3, sd=1))
|
|
x
|
|
#+end_src
|
|
|
|
| -3.35473133869346 |
|
|
| -2.45714878661 |
|
|
| -3.32819924928633 |
|
|
| -2.97310212756194 |
|
|
| -2.09640758369576 |
|
|
| -5.06054014378736 |
|
|
| -2.20713700711221 |
|
|
| -1.37618039712037 |
|
|
| -1.95839385821742 |
|
|
| -3.90407396475502 |
|
|
| 2.51168071590226 |
|
|
| 3.96753011570494 |
|
|
| 3.31793212627865 |
|
|
| 1.99829753972341 |
|
|
| 4.00403686419829 |
|
|
| 4.63723764452927 |
|
|
| 3.94636744261313 |
|
|
| 3.58355906547775 |
|
|
| 3.01563442274226 |
|
|
| 1.7634976849927 |
|
|
|
|
#+begin_src R var tabel=sandbox_r :results replace
|
|
tabel
|
|
#+end_src
|
|
|
|
| 1 | 2 | 3 |
|
|
| 4 | "schulte" | 6 |
|
|
|
|
*** shell
|
|
Now shell commands are converted to tables using =org-table-import=
|
|
and if these tables are non-trivial (i.e. have multiple elements) then
|
|
they are imported as org-mode tables...
|
|
|
|
#+begin_src sh :results replace
|
|
ls -l
|
|
#+end_src
|
|
|
|
| "total" | 208 | "" | "" | "" | "" | "" | "" |
|
|
| "-rw-r--r--" | 1 | "dan" | "dan" | 57 | 2009 | 15 | "block" |
|
|
| "-rw-r--r--" | 1 | "dan" | "dan" | 35147 | 2009 | 15 | "COPYING" |
|
|
| "-rw-r--r--" | 1 | "dan" | "dan" | 722 | 2009 | 18 | "examples.org" |
|
|
| "drwxr-xr-x" | 4 | "dan" | "dan" | 4096 | 2009 | 19 | "existing_tools" |
|
|
| "-rw-r--r--" | 1 | "dan" | "dan" | 2207 | 2009 | 14 | "intro.org" |
|
|
| "drwxr-xr-x" | 2 | "dan" | "dan" | 4096 | 2009 | 18 | "org-babel" |
|
|
| "-rw-r--r--" | 1 | "dan" | "dan" | 277 | 2009 | 20 | "README.markdown" |
|
|
| "-rw-r--r--" | 1 | "dan" | "dan" | 11837 | 2009 | 18 | "rorg.html" |
|
|
| "-rw-r--r--" | 1 | "dan" | "dan" | 61829 | 2009 | 19 | "#rorg.org#" |
|
|
| "-rw-r--r--" | 1 | "dan" | "dan" | 60190 | 2009 | 19 | "rorg.org" |
|
|
| "-rw-r--r--" | 1 | "dan" | "dan" | 972 | 2009 | 11 | "test-export.org" |
|
|
|
|
|
|
** silent evaluation
|
|
|
|
#+begin_src ruby
|
|
:im_the_results
|
|
#+end_src
|
|
|
|
: :im_the_results
|
|
|
|
#+begin_src ruby :results silent
|
|
:im_the_results
|
|
#+end_src
|
|
|
|
#+begin_src ruby :results replace
|
|
:im_the_results_
|
|
#+end_src
|
|
|
|
: :im_the_results_
|
|
|
|
|
|
** (sandbox) referencing other source blocks
|
|
Doing this in emacs-lisp first because it's trivial to convert
|
|
emacs-lisp results to and from emacs-lisp.
|
|
|
|
*** emacs lisp source reference
|
|
This first example performs a calculation in the first source block
|
|
named =top=, the results of this calculation are then saved into the
|
|
variable =first= by the header argument =:var first=top=, and it is
|
|
used in the calculations of the second source block.
|
|
|
|
#+SRCNAME: top
|
|
#+begin_src emacs-lisp
|
|
(+ 4 2)
|
|
#+end_src
|
|
|
|
#+begin_src emacs-lisp :var first=top :results replace
|
|
(* first 3)
|
|
#+end_src
|
|
|
|
: 18
|
|
|
|
This example is the same as the previous only the variable being
|
|
passed through is a table rather than a number.
|
|
|
|
#+begin_src emacs-lisp :results silent
|
|
(defun transpose (table)
|
|
(apply #'mapcar* #'list table))
|
|
#+end_src
|
|
|
|
#+TBLNAME: top_table
|
|
| 1 | 2 | 3 |
|
|
| 4 | schulte | 6 |
|
|
|
|
#+SRCNAME: second_src_example
|
|
#+begin_src emacs-lisp :var table=top_table
|
|
(transpose table)
|
|
#+end_src
|
|
|
|
#+begin_src emacs-lisp :var table=second_src_example :results replace
|
|
(transpose table)
|
|
#+end_src
|
|
|
|
| 1 | 2 | 3 |
|
|
| 4 | "schulte" | 6 |
|
|
*** ruby python
|
|
Now working for ruby
|
|
|
|
#+srcname: start
|
|
#+begin_src ruby
|
|
89
|
|
#+end_src
|
|
|
|
#+begin_src ruby :var other=start :results replace
|
|
2 * other
|
|
#+end_src
|
|
|
|
and for python
|
|
|
|
#+SRCNAME: start_two
|
|
#+begin_src python
|
|
98
|
|
#+end_src
|
|
|
|
#+begin_src python :var another=start_two :results replace
|
|
another*3
|
|
#+end_src
|
|
|
|
*** mixed languages
|
|
Since all variables are converted into Emacs Lisp it is no problem to
|
|
reference variables specified in another language.
|
|
|
|
#+SRCNAME: ruby-block
|
|
#+begin_src ruby
|
|
2
|
|
#+end_src
|
|
|
|
#+SRCNAME: lisp_block
|
|
#+begin_src emacs-lisp :var ruby-variable=ruby-block
|
|
(* ruby-variable 8)
|
|
#+end_src
|
|
|
|
#+begin_src python :var lisp_var=lisp_block
|
|
lisp_var + 4
|
|
#+end_src
|
|
|
|
: 20
|
|
|
|
*** R
|
|
|
|
#+srcname: first_r
|
|
#+begin_src R :results replace
|
|
a <- 9
|
|
a
|
|
#+end_src
|
|
|
|
: 9
|
|
|
|
#+begin_src R :var other=first_r :results replace
|
|
other + 2
|
|
#+end_src
|
|
|
|
: 11
|
|
|
|
|
|
** (sandbox) selective export
|
|
|
|
For exportation tests and examples see (including exportation of
|
|
inline source code blocks) [[file:test-export.org]]
|
|
|
|
|
|
** (sandbox) source blocks as functions
|
|
|
|
#+srcname: default
|
|
#+begin_src emacs-lisp :results silent
|
|
5
|
|
#+end_src
|
|
|
|
#+srcname: triple
|
|
#+begin_src emacs-lisp :var n=default :results replace
|
|
(* 3 n)
|
|
#+end_src
|
|
|
|
: 15
|
|
|
|
#+begin_src emacs-lisp :var result=triple(n=3, m=98) :results replace
|
|
result
|
|
#+end_src
|
|
|
|
: 294
|
|
|
|
The following just demonstrates the ability to assign variables to
|
|
literal values, which was not implemented until recently.
|
|
|
|
#+begin_src ruby :var num="eric" :results replace
|
|
num+" schulte "
|
|
#+end_src
|
|
|
|
: "eric schulte "
|
|
|
|
|
|
** (sandbox) inline source blocks
|
|
|
|
This is an inline source code block src_ruby{1 + 6}. And another
|
|
source block with text output src_emacs-lisp{"eric"}.
|
|
|
|
This is an inline source code block with header
|
|
arguments. src_ruby[:var n=fibbd( n = 0 )]{n}
|
|
|
|
|
|
** (sandbox) integration w/org tables
|
|
|
|
#+begin_src emacs-lisp :results silent
|
|
(defun fibbd (n) (if (< n 2) 1 (+ (fibbd (- n 1)) (fibbd (- n 2)))))
|
|
#+end_src
|
|
|
|
#+srcname: fibbd
|
|
#+begin_src emacs-lisp :var n=4 :results silent
|
|
(fibbd n)
|
|
#+end_src
|
|
|
|
#+begin_src emacs-lisp :results silent
|
|
(mapcar #'fibbd '(0 1 2 3 4 5 6 7 8))
|
|
#+end_src
|
|
|
|
Something is not working here. The function `sbe ' works fine when
|
|
called from outside of the table (see the source block below), but
|
|
produces an error when called from inside the table. I think there
|
|
must be some narrowing going on during intra-table emacs-lisp
|
|
evaluation.
|
|
|
|
| original | fibbd |
|
|
|----------+-------|
|
|
| 0 | 1 |
|
|
| 1 | 1 |
|
|
| 2 | 2 |
|
|
| 3 | 3 |
|
|
| 4 | 5 |
|
|
| 5 | 8 |
|
|
| 6 | 13 |
|
|
| 7 | 21 |
|
|
| 8 | 34 |
|
|
| 9 | 55 |
|
|
#+TBLFM: $2='(sbe "fibbd" (n $1))
|
|
|
|
silent-result
|
|
|
|
#+begin_src emacs-lisp :results silent
|
|
(sbe 'fibbd (n "8"))
|
|
#+end_src
|
|
|
|
|
|
* Buffer Dictionary
|
|
LocalWords: DBlocks dblocks org-babel el eric fontification
|
|
|
|
|