1 #+OPTIONS: H:3 num:nil toc:2 \n:nil @:t ::t |:t ^:{} -:t f:t *:t TeX:t LaTeX:t 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)
6 #+AUTHOR: Eric Schulte, Dan Davison
7 #+EMAIL: schulte.eric at gmail dot com, davison at stats dot ox dot ac dot uk
11 # #+INFOJS_OPT: view:content
15 <p>executable source code blocks in org-mode</p>
19 <img src="images/tower-of-babel.png" alt="images/tower-of-babel.png"/>
22 <a href="http://commons.wikimedia.org/wiki/Pieter_Brueghel_the_Elder" title="">
23 <b>Pieter Brueghel the Elder</b>
27 And the Lord said, Behold, the people is one, and they have all
28 one language; and this they begin to do; and now nothing will be
29 restrained from them, which they have imagined to do. Genesis
43 :CUSTOM_ID: introduction
45 Org-babel is an extension to the very excellent [[http://orgmode.org/][Org-mode]], providing
46 the ability to execute source code in many different languages
47 within org-mode documents. The results of code execution --- text,
48 tables and graphics --- can be integrated into the powerful
49 publishing facilities of org-mode. Org-mode is an [[http://www.gnu.org/software/emacs/][Emacs]] major mode
50 for doing almost anything with plain text. If you are not familiar
51 with Org-mode please take a moment to read [[http://orgmode.org/][the Org-mode homepage]]
54 Org-babel provides the following modifications to [[http://orgmode.org/manual/Literal-examples.html][the existing
55 support]] for blocks of source code examples in the org-mode core.
57 1. Interactive source code execution
58 2. Arguments to source code blocks
59 3. Exportation of source code blocks to files (literate programming)
63 :CUSTOM_ID: getting-started
66 1) Grab the latest code from the git repo at [[http://github.com/eschulte/org-babel/tree/master][github/org-babel]]
68 git clone git://github.com/eschulte/org-babel.git
71 2) Add the following lines to your .emacs, replacing the path as
72 appropriate. A good place to check that things are up and running
73 would the examples in [[* Basic org-babel functionality][Basic org-babel functionality]].
74 #+begin_src emacs-lisp
75 (add-to-list 'load-path "/path/to/org-babel/lisp")
76 (require 'org-babel-init)
79 3) Finally, activate the subset of supported Org-babel languages
80 which you want to be able to execute on your system. As an
81 example, the following activates python, ruby and R. For a full
82 list of languages, with notes on their dependencies see the
83 [[#reference-and-documentation][Reference / Documentation]] section below.
84 #+begin_src emacs-lisp
85 (require 'org-babel-python)
86 (require 'org-babel-ruby)
87 (require 'org-babel-R)
89 ;; Once you've activated languages, load the library of babel to
90 ;; make pre-built helper functions available in the languages you will be using.
91 (org-babel-load-library-of-babel)
94 * Basic org-babel functionality
96 :CUSTOM_ID: basic-functionality
98 *** Source code blocks
100 :CUSTOM_ID: source-code-blocks
103 Org-babel is all about *source code blocks* in org mode. These are
104 blocks of code (in whatever language), that can occur anywhere in
105 an org-mode file. For example, the following is a source block
106 containing [[http://www.ruby-lang.org/][ruby]] code:
109 : "This file was last evaluated on #{Date.today}"
112 If you are unfamiliar with the notion of a source code block in
113 org-mode, please have a look at the [[http://orgmode.org/manual/Literal-examples.html][relevant manual section]] before
116 Note that above is what the source block looks like in the org-mode
117 file. We had to take [[http://orgmode.org/manual/Literal-examples.html#Literal-examples][special steps]] to make it look that way in the
118 HTML output. Normally, when exported to HTML, source blocks are
119 fontified according to their language, and the begin_src...end_src
120 mark-up is omitted, like this:
123 "This file was last evaluated on #{Date.today}"
126 From now on, if you are viewing the HTML version, you will see the
127 HTML output only. However, much of this document consists of
128 interactive examples, and therefore in order to get a feeling for the
129 mechanics of Org-babel it might make most sense to grab the plain text
131 #+HTML: <a href="org-babel-worg.org">org-babel-worg.org</a>
132 and work through it in Emacs. Alternatively the htmlized
133 version of the plain text of this file at
134 #+HTML: <a href="org-babel-worg.org.html">org-babel-worg.html</a>
135 allows the plain text version to be viewed (non-interactively) in a web browser.
136 *** Source code execution
138 :CUSTOM_ID: source-code-execution
140 For interpreted languages such as shell, python, R, etc, org-babel
141 allows source blocks to be executed: the code is passed to the
142 interpreter and you have control over what is done with the results of
143 execution. Here are three examples of code blocks in three different
144 languages, followed by their output. If you are viewing the plain text
145 version of this document in emacs, place point anywhere inside the
146 blocks and use =C-c C-c= to run the code[fn:1] (and feel free to alter
151 "This file was last evaluated on #{Date.today}"
155 : This file was last evaluated on 2009-08-09
157 **** [[http://www.r-project.org/][R]]
158 #+begin_src R :results value
159 matrix(rnorm(6), nrow=2)
163 | -0.138279734486552 | -2.2476234005706 | -0.0839549402407832 |
164 | 0.0730510956002737 | 0.0634015508602321 | 0.174013159381603 |
166 **** [[http://ditaa.sourceforge.net/][ditaa]]
167 #+begin_src ditaa :file images/blue.png :cmdline -r
178 [[file:images/blue.png]]
180 *** Source code block syntax
182 The basic syntax of source-code blocks in Org-babel is as follows:
184 : #+srcname: name(arguments)
185 : #+begin_src language header-arguments
189 - name :: This name is associated with the source-code block. This is
190 similar to the =#+tblname= lines which can be used to name tables
191 in org-mode files. By referencing the srcname of a source-code
192 block it is possible to evaluate the block from other places,
193 files, or from inside tables.
194 - arguments :: Code blocks can have arguments (see [[#arguments-to-source-code-blocks][below]]) which are
195 provided using a familiar function-call syntax similar
196 to (e.g.) python or R.
197 - language :: The language of the code in the source-code block. Valid
198 values must be members of `org-babel-interpreters'.
199 - header-arguments :: Header arguments control many facets of the
200 evaluation and output of source-code blocks. See the [[* Header Arguments][Header
201 Arguments]] section for a complete review of available header
203 - body :: The actual source code which will be evaluated. An
204 important key-binding to become familiar with is =C-c
205 '=. This calls `org-edit-special' which brings up an edit
206 buffer containing the code using the emacs major mode
207 appropriate to the language.
209 *** What happens to the results?
213 Org-babel provides two fundamentally different modes for capturing
214 the results of code evaluation, specified by the =:results= header
216 **** =:results value= (functional mode)
217 This means that the 'result' of code evaluation is defined to be
218 the *value* of the last statement in the block. Thus with this
219 setting, one can view the code block as a function with a return
220 value. And not only can you view it that way, but you can
221 actually use the return value of one source block as input for
222 another (see [[meta-programming-language]]). This setting is the
225 As an example, consider the following block of python code and its
228 #+begin_src python :results value
230 print("Hello, today's date is %s" % time.ctime())
231 print('Two plus two is')
238 Notice that in functional mode, the output consists of the value of
239 the last statement, and nothing else.
241 **** =:results output= (scripting mode)
242 With this setting, org-babel captures all the text output of the
243 code block and places it in the org buffer. One can think of this
244 as a 'scripting' mode: the code block contains a series of
245 commands, and you get the output of all the commands. Unlike in
246 the 'functional' mode, the code block has no return value. (This
247 mode will be more familiar to Sweave users).
249 Now consider the result of evaluating the same source block as
250 before, but under scripting mode.
253 #+begin_src python :results output
255 print("Hello, today's date is %s" % time.ctime())
256 print('Two plus two is')
261 : Hello, today's date is Fri Sep 4 19:49:06 2009
264 Again, we got what we asked for: all the text output (stdout) from
265 python. Since we didn't print the last value (2 + 2), we didn't get it
268 *** Arguments to source code blocks
270 :CUSTOM_ID: arguments-to-source-code-blocks
272 In addition to evaluation of code blocks, org-babel allows them to
273 be parameterised (i.e. have arguments). Thus source code blocks
274 now have the status of *functions*. Arguments to code blocks can
275 be used in both functional and scripting mode.
277 **** Simple example of using a source block as a function
279 First let's look at a very simple example. The following source
280 block defines an org-babel function that will square its input.
287 In the org-mode file that looks like this:
288 : #+srcname: square(x)
294 Now we use the source block:
297 (/for information on the/ =lob= /syntax see [[library-of-babel]]/)
301 #+resname: square(x=6)
304 **** A more complex example: using an org-table as input
306 In this example we're going to define a function to compute a
307 Fibonacci sequence, and we're going to make it take its input
308 from a table in the org-mode buffer.
310 Here are the inputs for fibonacci-seq:
312 #+tblname: fibonacci-inputs
313 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 |
314 | 2 | 4 | 6 | 8 | 10 | 12 | 14 | 16 | 18 | 20 |
316 in the Org-mode buffer this looks like
317 : #+tblname: fibonacci-inputs
318 : | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 |
319 : | 2 | 4 | 6 | 8 | 10 | 12 | 14 | 16 | 18 | 20 |
321 [[http://www.gnu.org/software/emacs/manual/elisp.html][Emacs Lisp]] source code
322 #+srcname: fibonacci-seq(fib-inputs=fibonacci-inputs)
323 #+begin_src emacs-lisp
325 (if (or (= n 0) (= n 1))
327 (+ (fibonacci (- n 1)) (fibonacci (- n 2)))))
329 (mapcar (lambda (row)
330 (mapcar #'fibonacci row)) fib-inputs)
333 in the Org-mode buffer this looks like
334 : #+srcname: fibonacci-seq(fib-inputs=fibonacci-inputs)
335 : #+begin_src emacs-lisp
336 : (defun fibonacci (n)
337 : (if (or (= n 0) (= n 1))
339 : (+ (fibonacci (- n 1)) (fibonacci (- n 2)))))
341 : (mapcar (lambda (row)
342 : (mapcar #'fibonacci row)) fib-inputs)
345 Results of Emacs Lisp code evaluation
347 | 1 | 1 | 2 | 3 | 5 | 8 | 13 | 21 | 34 | 55 |
348 | 1 | 3 | 8 | 21 | 55 | 144 | 377 | 987 | 2584 | 6765 |
350 * A meta-programming language for org-mode
352 :CUSTOM_ID: meta-programming-language
355 Since information can pass freely between source-code blocks and
356 org-mode tables you can mix and match languages using each language
357 for those tasks to which it is suited. This makes Org-mode files with
358 Org-babel into a kind of meta-functional programming language in which
359 functions from many languages can work together.
361 As an example, lets take some system diagnostics in the shell, and
362 then graph them with R.
364 1. First we create a code block containing shell code creating a list
365 of the directories in our home directory, together with their
366 sizes. Org-babel automatically converts the output into an org
369 #+srcname: directories
370 #+begin_src bash :results replace
371 cd ~ && du -sc * |grep -v total
374 #+resname: directories
376 | 12156104 | "Documents" |
377 | 3482440 | "Downloads" |
378 | 2901720 | "Library" |
380 | 16548024 | "Music" |
382 | 7649472 | "Pictures" |
390 2. Now we use a single line of R code to plot the data as a
391 pie-chart. Note the way that this source block uses the =srcname=
392 of the previous source block to obtain the data.
393 #+srcname: directory-pie-chart(dirs = directories)
394 #+begin_src R :session R-pie-example
395 pie(dirs[,1], labels = dirs[,2])
397 [[file:images/dirs.png]]
399 * Multilingual spreadsheet plugins for org-mode
401 :CUSTOM_ID: spreadsheet
404 *NOTE*: Maybe in-addition-to/in-stead-of this example we should do a
405 more traditional "spreadsheet" example with R [Eric]
407 Not only can Org-babel pass entire tables of data to source code
408 blocks (see [[arguments-to-source-code-blocks]]), Org-babel can also be
409 used to call source code blocks from *within* tables using the
410 Org-mode's [[http://orgmode.org/manual/The-spreadsheet.html#The-spreadsheet][existing spreadsheet functionality]].
412 In fact the functional test suite for Org-babel is implemented as a
413 large Org-mode table. To run the entire test suite you simple
414 evaluate the table =C-u C-c C-c=, and all of the tests are run
415 updating the table with pass/fail statistics.
417 Here's a sample of our test suite.
419 #+TBLNAME: org-babel-tests
420 | functionality | block | arg | expected | results | pass |
421 |------------------+--------------+-----+-------------+-------------+------|
422 | basic evaluation | | | | | pass |
423 |------------------+--------------+-----+-------------+-------------+------|
424 | emacs lisp | basic-elisp | 2 | 4 | 4 | pass |
425 | shell | basic-shell | | 6 | 6 | pass |
426 | ruby | basic-ruby | | org-babel | org-babel | pass |
427 | python | basic-python | | hello world | hello world | pass |
428 | R | basic-R | | 13 | 13 | pass |
429 #+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))
430 #+TBLFM: $5=""::$6=""
432 *** code blocks for tests
434 #+srcname: basic-elisp
435 #+begin_src emacs-lisp :var n=7
439 #+srcname: basic-shell
440 #+begin_src sh :results silent
444 #+srcname: date-simple
445 #+begin_src sh :results silent
449 #+srcname: basic-ruby
450 #+begin_src ruby :results silent
454 #+srcname: basic-python
455 #+begin_src python :results silent
460 #+begin_src R :results silent
465 * The Library of Babel
467 :CUSTOM_ID: library-of-babel
472 <img src="images/library-of-babel.png" alt="images/tower-of-babel.png" />
474 from <a href="http://www.poetryfoundation.org/harriet/2008/01/random-poetry-02/">poetryfoundation.org</a>
475 <a href="http://downlode.org/Etext/library_of_babel.html">Full text of the Borges short story</a>
481 As we saw above with the [[*Simple%20example%20of%20using%20a%20source%20block%20as%20a%20function][=square=]] example, once a source block
482 function has been defined it can be called using the following short
487 But what about those source code blocks which are so useful you want
488 to have them available in every org-mode buffer?
490 In addition to the current buffer, Org-babel searches for
491 pre-defined source block functions in the Library of Babel. This is
492 a user-extensible collection of ready-made source-code blocks for
493 handling common tasks. One use for the LoB (not yet done!) will be
494 to provide a choice of data graphing procedures for data held in
495 org-mode tables, using languages such as R, gnuplot, asymptote,
496 etc. If you implement something that might be of use to other org
497 users, please consider adding it to the LoB; similarly, feel free to
498 request help solving a problem using external code via org-babel --
499 there's always a chance that other org users will be able to
500 contribute some helpful code. Org-mode demonstrates that an enormous
501 amount can be achieved using plain text and emacs lisp; the LoB is
502 intended to fill in the gaps.
504 Org-babel comes pre-populated with the source-code blocks located in
505 the [[file:library-of-babel.org][library-of-babel.org]] file. It is possible to add source-code
506 blocks from any org-mode file to the library by calling
508 #+srcname: add-file-to-lob
509 #+begin_src emacs-lisp
510 (org-babel-lob-ingest "path/to/file.org")
513 Note that it is also possible to pass table values or the output of
514 a source-code block to lob functions, and it is possible to
515 reference lob functions in source block arguments.
517 * Reproducible Research
519 :CUSTOM_ID: reproducable-research
522 An article about computational science in a scientific publication is
523 not the scholarship itself, it is merely advertising of the
524 scholarship. The actual scholarship is the complete software
525 development environment and the complete set of instructions which
526 generated the figures.
531 [[http://reproducibleresearch.net/index.php/Main_Page][Reproducible Research]] (RR) is the practice of distributing along with
532 an article of research all data, code, and tools required to reproduce
533 the results discussed in the paper. As such the paper becomes not
534 only a document describing the research but a complete laboratory in
535 which the research can be reproduced and extended.
537 Org-mode already has exceptional support for [[http://orgmode.org/manual/Exporting.html#Exporting][exporting to html and
538 LaTeX]]. Org-babel makes Org-mode a tool for RR by *activating* the
539 data and source code embedded into Org-mode documents making the
540 entire document executable. This makes it not only possible, but
541 natural to distribute research in a format that encourages readers to
542 recreate your results, and perform their own analysis.
544 One notable existing RR tool is [[http://en.wikipedia.org/wiki/Sweave][Sweave]] which provides for the
545 embedding of [[http://www.r-project.org/][R]] code into LaTeX documents. While Sweave is a mature
546 and very useful tool, we believe that Org-babel has several
548 - It supports multiple languages (we're not aware of other RR tools that do this)
549 - The [[http://orgmode.org/manual/Exporting.html#Exporting][export process]] is flexible and powerful, including HTML as a target in addition to LaTeX
550 - The document can make native use of all the features of Org-mode,
551 such as those for [[http://orgmode.org/manual/Agenda-Views.html#Agenda-Views][project planning]] and [[http://orgmode.org/manual/TODO-Items.html#TODO-Items][task management]]
553 * Literate programming
555 :CUSTOM_ID: literate-programming
559 Let us change our traditional attitude to the construction of
560 programs: Instead of imagining that our main task is to instruct a
561 /computer/ what to do, let us concentrate rather on explaining to
562 /human beings/ what we want a computer to do.
564 The practitioner of literate programming can be regarded as an
565 essayist, whose main concern is with exposition and excellence of
566 style. Such an author, with thesaurus in hand, chooses the names of
567 variables carefully and explains what each variable means. He or she
568 strives for a program that is comprehensible because its concepts have
569 been introduced in an order that is best for human understanding,
570 using a mixture of formal and informal methods that reinforce each
576 Org-babel supports [[http://en.wikipedia.org/wiki/Literate_programming][Literate Programming]] (LP) by allowing the act of
577 programming to take place inside of Org-mode documents. The Org-mode
578 file can then be exported (*woven* in LP speak) to html or LaTeX for
579 consumption by a human, and the embedded source code can be extracted
580 (*tangled* in LP speak) into structured source code files for
581 consumption by a computer.
583 To support these operations Org-babel relies on Org-mode's [[http://orgmode.org/manual/Exporting.html#Exporting][existing
584 exporting functionality]] for *weaving* of documentation, and on the
585 =org-babel-tangle= function which makes use of [[http://www.cs.tufts.edu/~nr/noweb/][Noweb]] [[reference-expansion][reference syntax]]
586 for *tangling* of code files.
588 The [[literate-programming-example][following example]] demonstrates the process of *tangling* in
591 *** Simple Literate Programming Example (Noweb syntax)
593 :CUSTOM_ID: literate-programming-example
596 Tangling functionality is controlled by the =tangle= family of
597 [[header-arguments]]. These arguments can be used to turn tangling on or
598 off (the default) on the source code block, or the outline heading
601 The following demonstrates the combination of three source code blocks
602 into a single source code file using =org-babel-tangle=.
604 The following two blocks will not be tangled by default since they
605 have no =tangle= header arguments.
607 #+srcname: hello-world-prefix
608 #+begin_src sh :exports none
609 echo "/-----------------------------------------------------------\\"
612 : #+srcname: hello-world-prefix
613 : #+begin_src sh :exports none
614 : echo "/-----------------------------------------------------------\\"
617 #+srcname: hello-world-postfix
618 #+begin_src sh :exports none
619 echo "\-----------------------------------------------------------/"
622 : #+srcname: hello-world-postfix
623 : #+begin_src sh :exports none
624 : echo "\-----------------------------------------------------------/"
628 The third block does have a =tangle= header argument indicating the
629 name of the file to which it should be written. It also has [[http://www.cs.tufts.edu/~nr/noweb/][Noweb]]
630 style references to the two previous source code blocks which will be
631 expanded during tangling to include them in the output file as well.
633 #+srcname: hello-world
634 #+begin_src sh :tangle hello :exports none
635 # <<hello-world-prefix>>
636 echo "| hello world |"
637 # <<hello-world-postfix>>
640 : #+srcname: hello-world
641 : #+begin_src sh :tangle hello :exports none
642 : # <<hello-world-prefix>>
643 : echo "| hello world |"
644 : # <<hello-world-postfix>>
647 Calling =org-babel-tangle= will result in the following being written
648 to the =hello.sh= file.
650 #+srcname: hello-world-output
653 # generated by org-babel-tangle
655 # [[file:~/src/org-babel/org-babel-worg.org::#literate-programming-example][block-16]]
656 # <<hello-world-prefix>>
657 echo "/-----------------------------------------------------------\\"
659 echo "| hello world |"
660 # <<hello-world-postfix>>
661 echo "\-----------------------------------------------------------/"
665 *** Emacs Initialization with Org-babel
666 Org-babel has special support for embedding your emacs initialization
667 into Org-mode files. The =org-babel-load-file= function can be used
668 to load the emacs lisp embedded in a literate Org-mode file in the
669 same way that you might load a regular elisp file.
671 This allows you to have all the niceness of Org-mode (folding, tags,
672 notes, html export, etc...) available in your emacs initialization.
674 To try this out either see the simple [[literate-emacs-init][Literate Emacs Initialization]]
675 example directly below, or check out the Org-babel Literate
676 Programming version of Phil Hagelberg's excellent [[http://github.com/technomancy/emacs-starter-kit/tree/master][emacs-starter-kit]]
677 available at [[http://github.com/eschulte/emacs-starter-kit/tree/master][Org-babel-emacs-starter-kit]].
679 ***** Literate Emacs Initialization
681 :CUSTOM_ID: literate-emacs-init
684 For a simple example of usage follow these 4 steps.
686 1) create a directory named =.emacs.d= in the base of your home
691 2) checkout the latest versions of Org-mode and Org-babel into the src
692 subdirectory of this new directory
697 git clone git://repo.or.cz/org-mode.git
698 git clone git://github.com/eschulte/org-babel.git
700 3) place the following in a file called =init.el= in your emacs
701 initialization directory (=~/.emacs.d=).
702 #+srcname: emacs-init
703 #+begin_src emacs-lisp
704 ;;; init.el --- Where all the magic begins
706 ;; This file loads both
707 ;; - Org-mode : http://orgmode.org/ and
708 ;; - Org-babel: http://eschulte.github.com/org-babel/
710 ;; It then loads the rest of our Emacs initialization from Emacs lisp
711 ;; embedded in literate Org-mode files.
713 ;; Load up Org Mode and Org Babel for elisp embedded in Org Mode files
714 (setq dotfiles-dir (file-name-directory (or (buffer-file-name) load-file-name)))
715 (add-to-list 'load-path (expand-file-name
716 "lisp" (expand-file-name
717 "org" (expand-file-name
718 "src" dotfiles-dir))))
719 (add-to-list 'load-path (expand-file-name
720 "lisp" (expand-file-name
721 "org-babel" (expand-file-name
722 "src" dotfiles-dir))))
723 (require 'org-babel-init)
725 ;; load up all literate org-mode files in this directory
726 (mapc #'org-babel-load-file (directory-files dotfiles-dir t "\\.org$"))
728 ;;; init.el ends here
730 4) Implement all of your emacs customizations inside of elisp
731 source-code blocks located in Org-mode files in this directory.
732 They will be loaded by emacs on startup.
734 * Reference / Documentation
736 :CUSTOM_ID: reference-and-documentation
739 The following can be added to your .emacs and used to activate
740 languages. It includes a brief list of the requirements for each
741 language. *Note*: this also serves as the list of languages
742 currently supported by Org-babel.
743 #+begin_src emacs-lisp
744 ;; Uncomment each of the following require lines if you want org-babel
745 ;; to support that language. Each language has a comment explaining
746 ;; it's dependencies. See the related files in lisp/langs for more
747 ;; detailed explanations of requirements.
748 ;; (require 'org-babel-R) ;; R and ess-mode
749 ;; (require 'org-babel-asymptote) ;; asymptote
750 ;; (require 'org-babel-css) ;; none
751 ;; (require 'org-babel-ditaa) ;; ditaa
752 ;; (require 'org-babel-dot) ;; dot
753 ;; (require 'org-babel-gnuplot) ;; gnuplot, and gnuplot-mode
754 ;; (require 'org-babel-haskell) ;; haskell, haskell-mode, inf-haskell
755 ;; (require 'org-babel-ocaml) ;; ocaml, and tuareg-mode
756 ;; (require 'org-babel-python) ;; python, and python-mode
757 ;; (require 'org-babel-ruby) ;; ruby, irb, ruby-mode, and inf-ruby
758 ;; (require 'org-babel-sass) ;; sass, sass-mode
759 ;; (require 'org-babel-sql) ;; none
764 :CUSTOM_ID: header-arguments
767 - results :: results arguments specify what should be done with the
768 output of source-code blocks
769 - The following options are mutually exclusive, and specify how the
770 results should be collected from the source-code block
773 - The following options are mutually exclusive and specify what type
774 of results the code block will return
775 - vector :: specifies that the results should be interpreted as a
776 multidimensional vector (even if the vector is
777 trivial), and will be inserted into the org-mode file
779 - scalar :: specifies that the results should be interpreted as a
780 scalar value, and will be inserted into the org-mode
782 - file :: specifies that the results should be interpreted as the
783 path to a file, and will be inserted into the org-mode
785 - The following options specify how the results should be inserted
786 into the org-mode file
787 - replace :: the current results replace any previously inserted
788 results from the code block
789 - silent :: rather than being inserted into the org-mode file the
790 results are echoed into the message bar
791 - exports :: exports arguments specify what should be included in html
792 or latex exports of the org-mode file
793 - code :: the body of code is included into the exported file
794 - results :: the results of evaluating the code is included in the
796 - both :: both the code and results are included in the exported
798 - none :: nothing is included in the exported file
799 - tangle :: tangle arguments specify whether or not the source-code
800 block should be included in tangled extraction of
802 - yes :: the source-code block is exported to a source-code file
803 named after the basename (name w/o extension) of the
805 - no :: (default) the source-code block is not exported to a
807 - other :: any other string passed to the =tangle= header argument
808 is interpreted as a file basename to which the block will
811 *** Noweb reference syntax
812 The [[http://www.cs.tufts.edu/~nr/noweb/][Noweb]] Literate Programming system allows named blocks of code to
813 be referenced by using a =<<code-block-name>>= syntax. When a
814 document is tangled these references are replaced with the named code.
815 An example is provided in the [[literate-programming-example]] in this
820 [fn:1] Calling =C-c C-o= on a source-code block will open the
821 block's results in a separate buffer.