1 #+OPTIONS: H:3 num:nil toc:2 \n:nil @:t ::t |:t ^:{} -:t f:t *:t TeX:t LaTeX:nil skip:nil d:(HIDE) tags:not-in-toc
2 #+STARTUP: align fold nodlcheck hidestars oddeven lognotestate hideblocks
3 #+SEQ_TODO: TODO(t) INPROGRESS(i) WAITING(w@) | DONE(d) CANCELED(c@)
4 #+TAGS: Write(w) Update(u) Fix(f) Check(c) noexport(n)
5 #+TITLE: Babel: Introduction
6 #+AUTHOR: Eric Schulte, Dan Davison, Tom Dye
7 #+EMAIL: schulte.eric at gmail dot com, davison at stats dot ox dot ac dot uk, tsd at tsdye dot com
9 #+STYLE: <style type="text/css">#outline-container-introduction{ clear:both; }</style>
10 #+STYLE: <style type="text/css">#table-of-contents{ max-width:100%; }</style>
12 #+LINK_HOME: http://orgmode.org/worg
15 <div id="subtitle" style="float: center; text-align: center;">
16 <p>executable code blocks in org-mode</p>
18 <div id="logo" style="float: left; text-align: center; max-width: 340px; font-size: 8pt; margin-left: 1em;">
20 <img src="../../images/babel/tower-of-babel.png" alt="Tower of Babel"/>
21 <div id="attr" style="margin: -0.5em;">
23 <a href="http://commons.wikimedia.org/wiki/Pieter_Brueghel_the_Elder" title="">
24 <b>Pieter Brueghel the Elder</b>
28 And the Lord said, Behold, the people is one, and they have all
29 one language; and this they begin to do; and now nothing will be
30 restrained from them, which they have imagined to do. Genesis
37 * Improving this document :noexport:
38 ** DONE Document slice indexing of tables
39 ** DONE Document synonymous alternatives
40 {call,lob}, {source, function, srcname}, {results, resname}
41 ** DONE Describe useful functions
42 - `org-babel-execute-buffer'
43 - `org-babel-execute-subtree'
45 ** DONE Language support
46 Hopefully we will be breaking out a separate section for
47 each language, and expanding the portion which documents the actual
48 usage of header-arguments and noweb references as those sections are
50 ** DONE Document noweb references
51 *** DONE Why is :noweb needed for execution but not for tangling?
53 - org-babel can now cache the results of source block execution to avoid
54 rerunning the same calculation. The cache uses a sha1 hash key of the
55 source code body and the header arguments to determine if
56 recalculation is required. These hash keys are kept mostly hidden in
57 the #+resname line of the results of the block. This behavior is
58 turned off by default. It is controlled through the :cache
59 and :nocache header arguments. To enable caching on a single block
60 add the :cache header argument, to enable global caching change the
61 value of your `org-babel-default-header-args' variable as follows
63 (setq org-babel-default-header-args
65 (assq-delete-all :nocache org-babel-default-header-args)))
67 - It is now possible to fold results by tabbing on the beginning of the
68 #+resname line. This can be done automatically to all results on
69 opening of a file by adding the following to your org-mode hook
71 (add-hook 'org-mode-hook 'org-babel-result-hide-all)
73 - allow header argument values to be lisp forms, for example the
74 following is now valid
76 :file (format "%s/images/pca-scatter.png" dir)
78 ** DONE Useful variables
79 - # -*- org-src-preserve-indentation: t -*-
80 ** TODO Language specific header arguments
81 - org-babel: capture graphical output from R
83 If a [:file filename.ext] header arg is provided, then all graphical
84 output from the source block is captured on disk, and output of the
85 source block is a link to the resulting file, as with the
86 graphics-only languages such as gnuplot, ditaa, dot, asymptote. An
87 attempt is made to find a graphics device corresponding to the file
88 extension (currently .png, .jpg, .jpeg, .tiff, .bmp, .pdf, .ps,
89 .postscript are recognised); if that fails, png format output is
92 Additionally, values for several arguments to the R graphics
93 device can be passed using header args:
95 :width :height :bg :units :pointsize
96 :antialias :quality :compression :res :type
97 :family :title :fonts :version :paper :encoding
98 :pagecentre :colormodel :useDingbats :horizontal
100 Arguments to the R graphics device that are not supported as header
101 args can be passed as a string in R argument syntax, using the header
104 An example block is (although both bg and fg can be passed directly as
107 \#+begin_src R :file z.pdf :width 8 :height 8 :R-dev-args bg="olivedrab", fg="hotpink"
108 plot(matrix(rnorm(100), ncol=2), type="l")
111 - Yes, I think we do want a version of this for python and ruby et al. In
112 your example, the filename is created in python. I suggest doing it
113 slightly differently, something like this.
115 #+srcname: fileoutput
116 #+begin_src python :file outfile.txt
117 def savetofile(result, filename):
118 with open(filename, 'w') as f:
120 savetofile(78, 'outfile.txt')
124 #+resname: fileoutput
127 This functionality is now available for ruby & python in branch
128 ded-babel of git://orgmode.org/org-mode/babel.git.
130 So here, if you specify :file <filepath> ruby/python blindly outputs a
131 link to <filepath>, regardless of the contents of the
132 code. Responsibility for creating useful contents of <filepath> lies
133 with the code. Notice that with this you have to specify the output file
134 twice: once as an org-babel directive, and once in the python code. This
135 is in contrast to the graphics languages (dot, ditaa, asymptote), where
136 the results *automatically* get sent to the file specified by :file. The
137 same is also true now for graphical output from R.
139 The difference with python, ruby et al is that they might create file
140 output in a variety of ways which we can't anticipate, so we can't
141 automatically send output to the file. In contrast, the graphics
142 language *always* create file output and always do it in the same
143 way. [And in R it is possible to divert all graphical output to file] A
144 possible extension of the above might be to use a "magic variable" so
145 that a python variable is created e.g. __org_babel_output_file__ that
146 always holds a string corresponding to the file specified by :file. Eric
147 may have further ideas / views here.
150 ** DONE What function is bound to C-c '?
151 - this document notes two different functions
154 :CUSTOM_ID: introduction
156 Babel extends the very excellent [[http://orgmode.org/][Org-mode]] with several features for
157 working with source code, including code execution. Org-mode is an
158 [[http://www.gnu.org/software/emacs/][Emacs]] major mode for doing almost anything with plain text. If you
159 are not familiar with Org-mode please take a moment to read the
160 [[http://orgmode.org/][Org-mode]] homepage before continuing.
162 As its name implies, Babel will execute code in many different
163 languages. The results of code execution --- text, tables and
164 graphics --- can be used as input to other code blocks or integrated
165 into the powerful publishing facilities of Org-mode.
167 Babel augments [[http://orgmode.org/manual/Literal-examples.html][Org-mode support for code blocks]] by providing:
169 - interactive and on-export execution of code blocks;
170 - code blocks as functions that can be parameterised, refer to
171 other code blocks, and be called remotely; and
172 - export to files for literate programming.
175 Babel provides new features on a few different fronts, and
176 different people may want to start in different places.
178 - Using 'src' blocks in Org mode ::
179 If you are not familiar with creating 'src' blocks in an Org-mode
180 buffer, and moving between that buffer and the language major-mode
181 edit buffer, then you should have a look at the relevant section
182 in the [[http://orgmode.org/manual/Literal-examples.html][Org manual]] and [[#source-code-blocks][below]], try it out, and come back.
184 The core of Babel is its ability to execute code in Org-mode
185 'src' blocks, taking input from other blocks and tables, with
186 output to further blocks and tables. This is described starting
187 [[#source-code-execution][here]].
188 - Literate Programming ::
189 If you are a programmer writing code that you would normally
190 execute in some other way (e.g. from the command line, or sourcing
191 it into an interactive session), then a simple introduction to
192 Babel is to place your code in blocks in an Org-mode file, and to
193 use Babel's [[#literate-programming][Literate Programming]] support to extract pure code
196 All of these use cases, as well as exhaustive documentation of the
197 features of Babel are covered in the [[http://orgmode.org/manual/Working-With-Source-Code.html#Working-With-Source-Code][Working with Source Code]]
198 section of the Org manual.
200 * Initial Configuration
202 :CUSTOM_ID: getting-started
206 If you have a working Emacs installation, then getting started with
207 Babel is a simple process.
209 1) It is strongly recommended that you update to the latest version
210 of Org-mode by [[file:../../org-faq.org::keeping-current-with-Org-mode-development][keeping current with Org-mode development]]. As of
211 Org-mode 7.0, Babel is included as part of Org-mode.
213 2) Optionally activate the subset of languages that you will want
214 to execute with Babel. See [[file:languages.org::#configure][Configure active languages]]
215 instructions. Emacs Lisp is activated by default so this step
216 can be skipped for now and all =emacs-lisp= examples will still
219 3) Evaluate your modified .emacs.
223 :CUSTOM_ID: source-code-blocks
226 ** Code Blocks in Org
228 :CUSTOM_ID: source-code-blocks-org
231 Babel is all about [[http://orgmode.org/manual/Literal-examples.html][code blocks]] in Org-mode. If you are
232 unfamiliar with the notion of a code block in Org-mode, where they
233 are called 'src' blocks, please have a look at the [[http://orgmode.org/manual/Literal-examples.html][Org-mode manual]]
236 Code blocks in [[#reference-and-documentation][supported languages]] can occur anywhere in an
237 Org-mode file. Code blocks can be entered directly into
238 the Org-mode file, but it is often easier to enter code with the
239 function =org-edit-src-code=, which is called with the keyboard
240 shortcut, C-c '. This places the code block in a new
241 buffer with the appropriate mode activated.
244 ,#+begin_src language org-switches
249 For example, a code block of [[http://www.ruby-lang.org/][ruby]] code looks like this in
255 ,"This file was last evaluated on #{Date.today}"
259 ** Code Blocks in Babel
261 :CUSTOM_ID: source-code-blocks-babel
264 Babel adds some new elements to code blocks. The basic
268 ,#+begin_src language org-switches header-arguments
274 - language :: The language of the code in the source-code block. Valid
275 values must be members of =org-babel-interpreters=.
276 - header-arguments :: Header arguments control many facets of the
277 evaluation and output of source-code blocks. See the [[file:reference.org::#header-arguments][Header
278 Arguments]] section for a complete review of available header
280 - body :: The source code to be evaluated. An important key-binding
281 is =​C-c '​=. This calls =org-edit-src-code=, a function that brings
282 up an edit buffer containing the code using the Emacs major mode
283 appropriate to the language. You can edit your code block
284 as you regularly would in Emacs.
286 * Source Code Execution
288 :CUSTOM_ID: source-code-execution
291 Babel executes code blocks for *interpreted* languages such
292 as shell, python, R, etc. by passing code to the interpreter, which
293 must be installed on your system. You control what is done with the
294 results of execution.
296 Here are examples of code blocks in three different languages,
297 followed by their output. If you are viewing the Org-mode version of
298 this document in Emacs, place point anywhere inside a block and press
299 C-c C-c to run the code[fn:1] (and feel free to alter it!).
301 In the Org-mode file:
303 : "This file was last evaluated on #{Date.today}"
308 "This file was last evaluated on #{Date.today}"
311 HTML export of the resulting string:
313 : This file was last evaluated on 2009-08-09
316 In the Org-mode file:
318 : echo "This file takes up `du -h org-babel.org |sed 's/\([0-9k]*\)[ ]*org-babel.org/\1/'`"
323 echo "This file takes up `du -h org-babel.org |sed 's/\([0-9k]*\)[ ]*org-babel.org/\1/'`"
326 HTML export of the resulting string:
328 : This file takes up 36K
330 *** [[http://www.r-project.org/][R]]
331 What are the most common words in this file?
332 In the Org-mode file:
333 : #+begin_src R :colnames yes
334 : words <- tolower(scan("intro.org", what="", na.strings=c("|",":")))
335 : t(sort(table(words[nchar(words) > 3]), decreasing=TRUE)[1:10])
339 #+begin_src R :colnames yes
340 words <- tolower(scan("intro.org", what="", na.strings=c("|",":")))
341 t(rev(sort(table(words[nchar(words) > 3])))[1:10])
344 | code | source | org-mode | #+end_src | #+begin_src | this | block | that | org-babel | with |
345 |------+--------+----------+-----------+-------------+------+-------+------+-----------+------|
346 | 64 | 62 | 44 | 42 | 41 | 36 | 34 | 28 | 28 | 27 |
348 *** [[http://ditaa.sourceforge.net/][ditaa]]
350 In the Org-mode file:
351 : #+begin_src ditaa :file blue.png :cmdline -r
362 #+begin_src ditaa :file blue.png :cmdline -r
372 HTML export of the resulting image:
374 [[file:../../images/babel/blue.png]]
376 ** Capturing the Results of Code Evaluation
380 Babel provides two fundamentally different modes for capturing
381 the results of code evaluation: functional mode and scripting
382 mode. The choice of mode is specified by the =:results= header
384 *** =:results value= (functional mode)
386 :CUSTOM_ID: results-value
388 The 'result' of code evaluation is the *value* of the last
389 statement in the code block. In functional mode, the
390 code block is a function with a return value. The return
391 value of one code block can be used as input for another
392 code block, even one in a different language. In this
393 way, Babel becomes a [[meta-programming-language]]. If the block
394 returns tabular data (a vector, array or table of some sort) then
395 this will be held as an Org-mode table in the buffer. This
396 setting is the default.
398 For example, consider the following block of python code and its
401 #+begin_src python :results value
403 print("Hello, today's date is %s" % time.ctime())
404 print('Two plus two is')
411 Notice that, in functional mode, the output consists of the value of
412 the last statement and nothing else.
414 *** =:results output= (scripting mode)
416 :CUSTOM_ID: results-output
419 In scripting mode, Babel captures the text output of the
420 code block and places it in the Org-mode buffer. It is
421 called scripting mode because the code block contains a series of
422 commands, and the output of each command is returned. Unlike
423 functional mode, the code block itself has no return value
424 apart from the output of the commands it contains.[fn:2]
426 Consider the result of evaluating this code block with
430 #+begin_src python :results output
432 print("Hello, today's date is %s" % time.ctime())
433 print('Two plus two is')
438 : Hello, today's date is Wed Nov 11 18:50:36 2009
441 Here, scripting mode returned the text that python sent to =stdout=. Because
442 the code block doesn't include a =print()= statement for the last
443 value, =(2 + 2)=, 4 does not appear in the results.
445 ** Session-based Evaluation
446 For some languages, such as python, R, ruby and shell, it is
447 possible to run an interactive session as an "inferior process"
448 within Emacs. This means that an environment is created containing
449 data objects that persist between different source code
450 blocks. Babel supports evaluation of code within such sessions
451 with the =:session= header argument. If the header argument is
452 given a value then that will be used as the name of the session.
453 Thus, it is possible to run separate simultaneous sessions in the
456 Session-based evaluation is particularly useful for prototyping and
457 debugging. The function =org-babel-pop-to-session= can be used to
458 switch to the session buffer.
460 Once a code block is finished, it is often best to execute it
461 outside of a session, so the state of the environment in which it
462 executes will be certain.
464 With R, the session will be under the control of [[http://ess.r-project.org/][Emacs Speaks
465 Statistics]] as usual, and the full power of ESS is thus still
466 available, both in the R session, and when switching to the R code
467 edit buffer with =​C-c '​=.
469 ** Arguments to Code Blocks
471 :CUSTOM_ID: arguments-to-source-code-blocks
473 Babel supports parameterisation of code blocks, i.e.,
474 arguments can be passed to code blocks, which gives them
475 the status of *functions*. Arguments can be passed to code blocks in
476 both functional and scripting modes.
478 *** Simple example of using a code block as a function
480 First let's look at a very simple example. The following source
481 code block defines a function, using python, that squares its argument.
488 In the Org-mode file, the function looks like this:
489 : #+source: square(x)
495 Now we use the source block:
497 : #+call: square(x=6)
498 (/for information on the/ =call= /syntax see/ [[library-of-babel]])
502 #+results: square(x=6)
505 *** A more complex example using an Org-mode table as input
507 In this example we define a function called =fibonacci-seq=, using
508 Emacs Lisp. The function =fibonacci-seq= computes a Fibonacci
509 sequence. The function takes a single argument, in this case, a
510 reference to an Org-mode table.
512 Here is the Org-mode table that is passed to =fibonacci-seq=:
514 #+tblname: fibonacci-inputs
515 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 |
516 | 2 | 4 | 6 | 8 | 10 | 12 | 14 | 16 | 18 | 20 |
518 The table looks like this in the Org-mode buffer:
519 : #+tblname: fibonacci-inputs
520 : | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 |
521 : | 2 | 4 | 6 | 8 | 10 | 12 | 14 | 16 | 18 | 20 |
523 The [[http://www.gnu.org/software/emacs/manual/elisp.html][Emacs Lisp]] source code:
524 #+srcname: fibonacci-seq(fib-inputs=fibonacci-inputs)
525 #+begin_src emacs-lisp
527 (if (or (= n 0) (= n 1))
529 (+ (fibonacci (- n 1)) (fibonacci (- n 2)))))
531 (mapcar (lambda (row)
532 (mapcar #'fibonacci row)) fib-inputs)
535 In the Org-mode buffer the function looks like this:
536 : #+srcname: fibonacci-seq(fib-inputs=fibonacci-inputs)
537 : #+begin_src emacs-lisp
538 : (defun fibonacci (n)
539 : (if (or (= n 0) (= n 1))
541 : (+ (fibonacci (- n 1)) (fibonacci (- n 2)))))
543 : (mapcar (lambda (row)
544 : (mapcar #'fibonacci row)) fib-inputs)
547 The return value of =fibonacci-seq= is a table:
549 | 1 | 1 | 2 | 3 | 5 | 8 | 13 | 21 | 34 | 55 |
550 | 1 | 3 | 8 | 21 | 55 | 144 | 377 | 987 | 2584 | 6765 |
552 ** In-line Code Blocks
553 Code can be evaluated in-line using the following syntax:
555 : Without header args: src_lang{code} or with header args: src_lang[args]{code},
556 : for example src_python[:session]{10*x}, where x is a variable existing in the
559 ** Code Block Body Expansion
560 Babel "expands" code blocks prior to evaluation, i.e., the
561 evaluated code comprises the code block contents augmented with
562 code that assigns referenced data to variables. It is possible to
563 preview expanded contents, and also to expand code during
564 tangling. Expansion takes into account header arguments and
567 - preview :: =C-c M-b p= is bound to =org-babel-expand-src-block=. It
568 can be used inside a code block to preview the expanded
569 contents. This facility is useful for debugging.
571 - tangling :: The expanded body can be tangled. Tangling this way includes
572 variable values that may be
573 - the results of other code blocks,
574 - variables stored in headline properties, or
577 One possible use for tangling expanded code block is for emacs
578 initialization. Values such as user names and passwords can be
579 stored in headline properties or in tables. The =:no-expand=
580 header argument can be used to inhibit expansion of a code block
583 Here is an example of a code block and its resulting expanded body.
585 The data are kept in a table:
587 | username | john-doe |
588 | password | abc123 |
590 The code block refers to the data table:
591 #+srcname: setup-my-account
592 #+begin_src emacs-lisp :rownames yes :var data=user-data
593 (setq my-special-username (first (first data)))
594 (setq my-special-password (first (second data)))
597 With point inside the code block, =C-c M-b p= expands the contents:
598 #+begin_src emacs-lisp
599 (let ((data (quote (("john-doe") ("abc123")))))
600 (setq my-special-username (first (first data)))
601 (setq my-special-password (first (second data)))
606 ** A Meta-programming Language for Org-mode
608 :CUSTOM_ID: meta-programming-language
611 Because the return value of a function written in one language can be
612 passed to a function written in another language, or to an Org-mode
613 table, which is itself programmable, Babel can be used as a
614 meta-functional programming language. With Babel, functions from
615 many languages can work together. You can mix and match languages,
616 using each language for the tasks to which it is best suited.
618 For example, let's take some system diagnostics in the shell and graph them with R.
620 1. Create a code block, using shell code, to list
621 directories in our home directory, together with their
622 sizes. Babel automatically converts the output into an Org-mode
625 : #+srcname: directories
626 : #+begin_src sh :results replace
627 : cd ~ && du -sc * |grep -v total
630 #+resname: directories
632 | 12156104 | "Documents" |
633 | 3482440 | "Downloads" |
634 | 2901720 | "Library" |
636 | 16548024 | "Music" |
638 | 7649472 | "Pictures" |
647 2. A function, written with a single line of R code, plots the data
648 in the Org-mode table as a
649 pie-chart. Note how this code block uses the =srcname=
650 of the previous code block to obtain the data.
652 In the Org-mode file:
653 : #+srcname: directory-pie-chart(dirs = directories)
654 : #+begin_src R :session R-pie-example :file ../../images/babel/dirs.png
655 : pie(dirs[,1], labels = dirs[,2])
659 #+srcname: directory-pie-chart(dirs = directories)
660 #+begin_src R :session R-pie-example :file ../../images/babel/dirs.png
661 pie(dirs[,1], labels = dirs[,2])
663 [[file:../../images/babel/dirs.png]]
665 * Using Code Blocks in Org Tables
667 :CUSTOM_ID: spreadsheet
670 In addition to passing data from tables as [[arguments-to-source-code-blocks][arguments]] to code
671 blocks, and [[#results-value][storing]] results as tables, Babel can be used in a
672 third way with Org-mode tables. First note that Org-mode's [[http://orgmode.org/manual/The-spreadsheet.html#The-spreadsheet][existing
673 spreadsheet functionality]] allows values in cells to be computed
674 automatically from the values of other cells, using a =#+TBLFM=
675 formula line. In this way, table computations can be carried out using
676 [[http://orgmode.org/manual/Formula-syntax-for-Calc.html#Formula-syntax-for-Calc][calc]] and [[http://orgmode.org/manual/Formula-syntax-for-Lisp.html#Formula-syntax-for-Lisp][emacs lisp]].
678 What Babel adds is the ability to use code blocks (in whatever
679 language) in the =#+TBLFM= line to perform the necessary computation.
681 *** Example 1: Data Summaries Using R
682 As a simple example, we'll fill in a cell in an Org-mode table with the
683 average value of a few numbers. First, let's make some data. The
684 following source block creates an Org-mode table filled with five random
685 numbers between 0 and 1.
687 : #+srcname: tbl-example-data()
689 : runif(n=5, min=0, max=1)
692 #+resname: tbl-example-data
693 | 0.836685163900256 |
694 | 0.696652316721156 |
695 | 0.382423302158713 |
696 | 0.987541858805344 |
697 | 0.994794291909784 |
699 Now we define a source block to calculate the mean.
701 In the Org-mode file:
702 : #+srcname: R-mean(x)
713 Finally, we create the table which is going to make use of the R
714 code. This is done using the =sbe= ('source block evaluate') macro in
715 the table formula line.
717 In the Org-mode file:
718 : #+tblname: summaries
720 : |-------------------|
721 : | 0.779619386699051 |
722 : #+TBLFM: @2$1='(sbe "R-mean" (x "tbl-example-data()"))
729 #+TBLFM: @2$1='(sbe R-mean (x tbl-example-data));%.2f
731 To recalculate the table formula, use C-u C-c C-c in the
732 table. Notice that as things stand the calculated value doesn't
733 change, because the data (held in the table above named
734 =tbl-example-data=) are static. However, if you delete that data table,
735 then the reference will be interpreted as a reference to the source
736 block responsible for generating the data; each time the table formula
737 is recalculated the source block will be evaluated again, and
738 therefore the calculated average value will change.
740 *** Example 2: Babel Test Suite
741 While developing Babel, we used a suite of tests implemented
742 as a large Org-mode table. To run the entire test suite we simply
743 evaluate the table with C-u C-c C-c: all of the tests are run,
744 the results are compared with expectations, and the table is updated
745 with results and pass/fail statistics.
747 Here's a sample of our test suite.
749 In the Org-mode file:
751 : #+TBLNAME: org-babel-tests
752 : | functionality | block | arg | expected | results | pass |
753 : |------------------+--------------+-----+-------------+-------------+------|
754 : | basic evaluation | | | | | pass |
755 : |------------------+--------------+-----+-------------+-------------+------|
756 : | emacs lisp | basic-elisp | 2 | 4 | 4 | pass |
757 : | shell | basic-shell | | 6 | 6 | pass |
758 : | ruby | basic-ruby | | org-babel | org-babel | pass |
759 : | python | basic-python | | hello world | hello world | pass |
760 : | R | basic-R | | 13 | 13 | pass |
761 : #+TBLFM: $5='(if (= (length $3) 1) (sbe $2 (n $3)) (sbe $2)) :: $6='(if (string= $4 $5) "pass" (format "expected %S but was %S" $4 $5))
765 #+TBLNAME: org-babel-tests
766 | functionality | block | arg | expected | results | pass |
767 |------------------+--------------+-----+-------------+-------------+------|
768 | basic evaluation | | | | | pass |
769 |------------------+--------------+-----+-------------+-------------+------|
770 | emacs lisp | basic-elisp | 2 | 4 | 4 | pass |
771 | shell | basic-shell | | 6 | 6 | pass |
772 | ruby | basic-ruby | | org-babel | org-babel | pass |
773 | python | basic-python | | hello world | hello world | pass |
774 | R | basic-R | | 13 | 13 | pass |
775 #+TBLFM: $5='(if (= (length $3) 1) (sbe $2 (n $3)) (sbe $2)) :: $6='(if (string= $4 $5) "pass" (format "expected %S but was %S" $4 $5))
777 **** code blocks for tests
779 In the Org-mode file:
781 : #+srcname: basic-elisp(n)
782 : #+begin_src emacs-lisp
788 #+srcname: basic-elisp(n)
789 #+begin_src emacs-lisp
793 In the Org-mode file:
794 : #+srcname: basic-shell
795 : #+begin_src sh :results silent
800 #+srcname: basic-shell
801 #+begin_src sh :results silent
805 In the Org-mode file:
806 : #+srcname: date-simple
807 : #+begin_src sh :results silent
812 #+srcname: date-simple
813 #+begin_src sh :results silent
817 In the Org-mode file:
818 : #+srcname: basic-ruby
819 : #+begin_src ruby :results silent
824 #+srcname: basic-ruby
825 #+begin_src ruby :results silent
830 : #+srcname: basic-python
831 : #+begin_src python :results silent
836 #+srcname: basic-python
837 #+begin_src python :results silent
841 In the Org-mode file:
843 : #+begin_src R :results silent
850 #+begin_src R :results silent
855 * The Library of Babel
857 :CUSTOM_ID: library-of-babel
860 (see also [[http://orgmode.org/manual/Library-of-Babel.html#Library-of-Babel][Org manual:Library-of-Babel]])
862 As we saw above with the [[*Simple%20example%20of%20using%20a%20source%20block%20as%20a%20function][=square=]] example, once a source block
863 function has been defined it can be called using the =lob= notation:
867 But what about code blocks that you want to make available to
868 every Org-mode buffer?
870 In addition to the current buffer, Babel searches for
871 pre-defined code block functions in the Library of
872 Babel. This is a user-extensible collection of ready-made source
873 code blocks for handling common tasks. One use for the Library of
874 Babel (not yet done!) will be to provide a choice of data graphing
875 procedures for data held in Org-mode tables, using languages such as
876 R, gnuplot, asymptote, etc. If you implement something that might be
877 of use to other Org-mode users, please consider adding it to the
878 Library of Babel; similarly, feel free to request help solving a
879 problem using external code via Babel -- there's always a chance
880 that other Babel users will be able to contribute some helpful
883 Babel comes pre-populated with the code blocks located in
884 the [[file:library-of-babel.org][Library of Babel]] file -- raw file at
885 #+html: <a href="http://repo.or.cz/w/org-mode.git/blob/HEAD:/contrib/babel/library-of-babel.org">library-of-babel.org</a>
886 --. It is possible to add code blocks to the library from any
887 Org-mode file using the =org-babel-lob-ingest= (bound to =C-c C-v
890 #+srcname: add-file-to-lob
891 #+begin_src emacs-lisp
892 (org-babel-lob-ingest "path/to/file.org")
895 Note that it is possible to pass table values or the output of a
896 source-code block to Library of Babel functions. It is also possible
897 to reference Library of Babel functions in arguments to code blocks.
899 * Literate Programming
901 :CUSTOM_ID: literate-programming
905 Let us change our traditional attitude to the construction of
906 programs: Instead of imagining that our main task is to instruct a
907 /computer/ what to do, let us concentrate rather on explaining to
908 /human beings/ what we want a computer to do.
910 The practitioner of literate programming can be regarded as an
911 essayist, whose main concern is with exposition and excellence of
912 style. Such an author, with thesaurus in hand, chooses the names of
913 variables carefully and explains what each variable means. He or she
914 strives for a program that is comprehensible because its concepts have
915 been introduced in an order that is best for human understanding,
916 using a mixture of formal and informal methods that reinforce each
922 Babel supports [[http://en.wikipedia.org/wiki/Literate_programming][Literate Programming]] (LP) by allowing the act of
923 programming to take place inside of Org-mode documents. The Org-mode
924 file can then be exported (*woven* in LP speak) to HTML or LaTeX for
925 consumption by a human, and the embedded source code can be extracted
926 (*tangled* in LP speak) into structured source code files for
927 consumption by a computer.
929 To support these operations Babel relies on Org-mode's [[http://orgmode.org/manual/Exporting.html#Exporting][existing
930 exporting functionality]] for *weaving* of documentation, and on the
931 =org-babel-tangle= function which makes use of [[http://www.cs.tufts.edu/~nr/noweb/][Noweb]] [[noweb-reference-syntax][reference syntax]]
932 for *tangling* of code files.
934 The [[literate-programming-example][following example]] demonstrates the process of *tangling* in
937 *** Simple Literate Programming Example (Noweb syntax)
939 :CUSTOM_ID: literate-programming-example
942 Tangling functionality is controlled by the =tangle= family of [[tangle-header-arguments][Tangle
943 header arguments]]. These arguments can be used to turn tangling on or
944 off (the default), either for the code block or the Org-mode
947 The following code blocks demonstrate how to tangle them into a
948 single source code file using =org-babel-tangle=.
950 The following two code blocks have no =tangle= header arguments
951 and so will not, by themselves, create source code files. They are
952 included in the source code file by the third code block, which
953 does have a =tangle= header argument.
955 In the Org-mode file:
956 : #+srcname: hello-world-prefix
957 : #+begin_src sh :exports none
958 : echo "/-----------------------------------------------------------\\"
962 #+srcname: hello-world-prefix
963 #+begin_src sh :exports none
964 echo "/-----------------------------------------------------------\\"
968 : #+srcname: hello-world-postfix
969 : #+begin_src sh :exports none
970 : echo "\-----------------------------------------------------------/"
974 #+srcname: hello-world-postfix
975 #+begin_src sh :exports none
976 echo "\-----------------------------------------------------------/"
980 The third code block does have a =tangle= header argument
981 indicating the name of the file to which the tangled source code will
982 be written. It also has [[http://www.cs.tufts.edu/~nr/noweb/][Noweb]] style references to the two previous
983 code blocks. These references will be expanded during tangling
984 to include them in the output file as well.
986 In the Org-mode file:
987 : #+srcname: hello-world
988 : #+begin_src sh :tangle hello :exports none :noweb yes
989 : <<hello-world-prefix>>
990 : echo "| hello world |"
991 : <<hello-world-postfix>>
995 #+srcname: hello-world
996 #+begin_src sh :tangle hello.sh :exports none :noweb yes
997 <<hello-world-prefix>>
998 echo "| hello world |"
999 <<hello-world-postfix>>
1003 Calling =org-babel-tangle= will result in the following shell source
1004 code being written to the =hello.sh= file:
1006 #+srcname: hello-world-output
1010 # [[file:~/org/temp/index.org::*Noweb%20test][hello-world]]
1012 echo "/-----------------------------------------------------------\\"
1013 echo "| hello world |"
1014 echo "\-----------------------------------------------------------/"
1015 # hello-world ends here
1018 In addition, the following syntax can be used to insert the *results*
1019 of evaluating a code block, in this case one named =example-block=.
1021 : # <<example-block()>>
1023 Any optional arguments can be passed to =example-block()= by placing the
1024 arguments inside the parentheses following the convention defined when
1025 calling source block functions (see the [[library-of-babel][Library of babel]]). For example,
1027 : # <<example-block(a=9)>>
1029 sets the value of argument \"a\" equal to \"9\". Note that
1030 these arguments are not evaluated in the current source-code
1031 block but are passed literally to =example-block()=.
1033 *** Emacs Initialization with Babel
1035 :CUSTOM_ID: emacs-initialization
1038 #+attr_html: style="float:left;"
1039 [[file:../../images/babel/dot-emacs.png]]
1041 Babel has special support for embedding your Emacs initialization
1042 into Org-mode files. The =org-babel-load-file= function can be used
1043 to load the Emacs Lisp code blocks embedded in a literate
1044 Org-mode file in the same way that you might load a regular Emacs Lisp
1045 file, such as .emacs.
1047 This allows you to make use of the nice features of Org-mode, such as folding, tags,
1048 notes, HTML export, etc., to organize and maintain your Emacs initialization.
1050 To try this out, either see the simple [[literate-emacs-init][Literate Emacs Initialization]]
1051 example, or check out the Babel Literate Programming version of
1052 Phil Hagelberg's excellent [[http://github.com/technomancy/emacs-starter-kit/tree/master][emacs-starter-kit]] available at
1053 [[http://github.com/eschulte/emacs-starter-kit/tree/master][Org-babel-emacs-starter-kit]].
1055 ***** Literate Emacs Initialization
1057 :CUSTOM_ID: literate-emacs-init
1060 For a simple example of usage, follow these 5 steps:
1062 1) create a directory named =.emacs.d= in the base of your home
1067 2) checkout the latest version of Org-mode into the src subdirectory
1068 of this new directory;
1073 git clone git://orgmode.org/org-mode.git
1075 3) place the following code block in a file called =init.el= in your Emacs
1076 initialization directory (=~/.emacs.d=).
1077 #+srcname: emacs-init
1078 #+begin_src emacs-lisp
1079 ;;; init.el --- Where all the magic begins
1081 ;; This file loads Org-mode and then loads the rest of our Emacs initialization from Emacs lisp
1082 ;; embedded in literate Org-mode files.
1084 ;; Load up Org Mode and (now included) Org Babel for elisp embedded in Org Mode files
1085 (setq dotfiles-dir (file-name-directory (or (buffer-file-name) load-file-name)))
1087 (let* ((org-dir (expand-file-name
1088 "lisp" (expand-file-name
1089 "org" (expand-file-name
1090 "src" dotfiles-dir))))
1091 (org-contrib-dir (expand-file-name
1092 "lisp" (expand-file-name
1093 "contrib" (expand-file-name
1095 (load-path (append (list org-dir org-contrib-dir)
1096 (or load-path nil))))
1097 ;; load up Org-mode and Org-babel
1098 (require 'org-install)
1099 (require 'ob-tangle))
1101 ;; load up all literate org-mode files in this directory
1102 (mapc #'org-babel-load-file (directory-files dotfiles-dir t "\\.org$"))
1104 ;;; init.el ends here
1106 4) implement all of your Emacs customizations inside of Emacs Lisp
1107 code blocks embedded in Org-mode files in this directory;
1109 5) re-start Emacs to load the customizations.
1111 * Reproducible Research
1113 :CUSTOM_ID: reproducable-research
1116 An article about computational science in a scientific publication is
1117 not the scholarship itself, it is merely advertising of the
1118 scholarship. The actual scholarship is the complete software
1119 development environment and the complete set of instructions which
1120 generated the figures.
1125 [[http://reproducibleresearch.net/index.php/Main_Page][Reproducible Research]] (RR) is the practice of distributing, along with
1126 a research publication, all data, software source code, and tools
1127 required to reproduce the results discussed in the publication. As
1128 such the RR package not only describes the research and its results,
1129 but becomes a complete laboratory in which the research can be
1130 reproduced and extended.
1132 Org-mode already has exceptional support for [[http://orgmode.org/manual/Exporting.html#Exporting][exporting to HTML and
1133 LaTeX]]. Babel makes Org-mode a tool for RR by *activating* the
1134 data and code blocks embedded in Org-mode documents; the
1135 entire document becomes executable. This makes it possible, and natural, to
1136 distribute research in a format that encourages readers to recreate
1137 results and perform their own analyses.
1139 One notable existing RR tool is [[http://en.wikipedia.org/wiki/Sweave][Sweave]], which provides a mechanism for
1140 embedding [[http://www.r-project.org/][R]] code into LaTeX documents. Sweave is a mature
1141 and very useful tool, but we believe that Babel has several
1143 - it supports multiple languages (we're not aware of other RR tools that do this);
1144 - the [[http://orgmode.org/manual/Exporting.html#Exporting][export process]] is flexible and powerful, including HTML as a
1145 target in addition to LaTeX; and
1146 - the document can make use of Org-mode features that support [[http://orgmode.org/manual/Agenda-Views.html#Agenda-Views][project
1147 planning]] and [[http://orgmode.org/manual/TODO-Items.html#TODO-Items][task management]].
1150 [fn:1] Calling =C-c C-o= on a code block will open the
1151 block's results in a separate buffer.
1153 [fn:2] This mode will be familiar to Sweave users.