org-agenda: Set default-directory when exporting agenda
[org-mode.git] / doc / library-of-babel.org
1 #+title:    The Library of Babel
2 #+author:     Org-mode People
3 #+STARTUP:  hideblocks
4
5 * Introduction
6
7 The Library of Babel is an extensible collection of ready-made and
8 easily-shortcut-callable source-code blocks for handling common tasks.
9 Org-babel comes pre-populated with the source-code blocks located in
10 this file.  It is possible to add source-code blocks from any org-mode
11 file to the library by calling =(org-babel-lob-ingest
12 "path/to/file.org")=.
13
14 This file is included in worg mainly less for viewing through the web
15 interface, and more for contribution through the worg git repository.
16 If you have code snippets that you think others may find useful please
17 add them to this file and [[file:~/src/worg/worg-git.org::contribute-to-worg][contribute them]] to worg.
18
19 The raw Org-mode text of this file can be downloaded at
20 [[repofile:contrib/babel/library-of-babel.org][library-of-babel.org]]
21
22 * Simple
23
24 A collection of simple utility functions:
25
26 #+name: echo
27 #+begin_src emacs-lisp :var input="echo'd"
28   input
29 #+end_src
30
31 * File I/O
32
33 ** Reading and writing files
34
35 Read the contents of the file at =file=.  The =:results vector= and
36 =:results scalar= header arguments can be used to read the contents of
37 file as either a table or a string.
38
39 #+name: read
40 #+begin_src emacs-lisp :var file="" :var format=""
41   (if (string= format "csv")
42       (with-temp-buffer
43         (org-table-import (expand-file-name file) nil)
44         (org-table-to-lisp))
45     (with-temp-buffer
46       (insert-file-contents (expand-file-name file))
47       (buffer-string)))
48 #+end_src
49
50 Write =data= to a file at =file=.  If =data= is a list, then write it
51 as a table in traditional Org-mode table syntax.
52
53 #+name: write
54 #+begin_src emacs-lisp :var data="" :var file="" :var ext='()
55   (flet ((echo (r) (if (stringp r) r (format "%S" r))))
56     (with-temp-file file
57       (case (and (listp data)
58                  (or ext (intern (file-name-extension file))))
59         ('tsv (insert (orgtbl-to-tsv data '(:fmt echo))))
60         ('csv (insert (orgtbl-to-csv data '(:fmt echo))))
61         (t    (org-babel-insert-result data)))))
62   nil
63 #+end_src
64
65 ** Remote files
66
67 *** json
68
69 Read local or remote file in [[http://www.json.org/][json]] format into emacs-lisp objects.
70
71 #+name: json
72 #+begin_src emacs-lisp :var file='() :var url='()
73   (require 'json)
74   (cond
75    (file
76     (with-temp-filebuffer file
77       (goto-char (point-min))
78       (json-read)))
79    (url
80     (require 'w3m)
81     (with-temp-buffer
82       (w3m-retrieve url)
83       (goto-char (point-min))
84       (json-read))))
85 #+end_src
86
87 *** Google docs
88
89 The following code blocks make use of the [[http://code.google.com/p/googlecl/][googlecl]] Google command line
90 tool.  This tool provides functionality for accessing Google services
91 from the command line, and the following code blocks use /googlecl/
92 for reading from and writing to Google docs with Org-mode code blocks.
93
94 **** Read a document from Google docs
95
96 The =google= command seems to be throwing "Moved Temporarily" errors
97 when trying to download textual documents, but this is working fine
98 for spreadsheets.
99
100 #+name: gdoc-read
101 #+begin_src emacs-lisp :var title="example" :var format="csv"
102   (let* ((file (concat title "." format))
103          (cmd (format "google docs get --format %S --title %S" format title)))
104     (message cmd) (message (shell-command-to-string cmd))
105     (prog1 (if (string= format "csv")
106                (with-temp-buffer
107                  (org-table-import (shell-quote-argument file) '(4))
108                  (org-table-to-lisp))
109              (with-temp-buffer
110                (insert-file-contents (shell-quote-argument file))
111                (buffer-string)))
112       (delete-file file)))
113 #+end_src
114
115 For example, a line like the following can be used to read the
116 contents of a spreadsheet named =num-cells= into a table.
117 : #+call: gdoc-read(title="num-cells"")
118
119 A line like the following can be used to read the contents of a
120 document as a string.
121
122 : #+call: gdoc-read(title="loremi", :format "txt")
123
124 **** Write a document to a Google docs
125
126 Write =data= to a google document named =title=.  If =data= is tabular
127 it will be saved to a spreadsheet, otherwise it will be saved as a
128 normal document.
129
130 #+name: gdoc-write
131 #+begin_src emacs-lisp :var title="babel-upload" :var data=fibs(n=10) :results silent
132   (let* ((format (if (listp data) "csv" "txt"))
133          (tmp-file (make-temp-file "org-babel-google-doc" nil (concat "." format)))
134          (cmd (format "google docs upload --title %S %S" title tmp-file)))
135     (with-temp-file tmp-file
136       (insert
137        (if (listp data)
138            (orgtbl-to-csv
139             data '(:fmt (lambda (el) (if (stringp el) el (format "%S" el)))))
140          (if (stringp data) data (format "%S" data)))))
141     (message cmd)
142     (prog1 (shell-command-to-string cmd) (delete-file tmp-file)))
143 #+end_src
144
145 example usage
146 : #+name: fibs
147 : #+begin_src emacs-lisp :var n=8
148 :   (flet ((fib (m) (if (< m 2) 1 (+ (fib (- m 1)) (fib (- m 2))))))
149 :     (mapcar (lambda (el) (list el (fib el))) (number-sequence 0 (- n 1))))
150 : #+end_src
151 :
152 : #+call: gdoc-write(title="fibs", data=fibs(n=10))
153
154 * Plotting code
155
156 ** R
157
158 Plot column 2 (y axis) against column 1 (x axis). Columns 3 and
159 beyond, if present, are ignored.
160
161 #+name: R-plot
162 #+begin_src R :var data=R-plot-example-data
163 plot(data)
164 #+end_src
165
166 #+tblname: R-plot-example-data
167 | 1 |  2 |
168 | 2 |  4 |
169 | 3 |  9 |
170 | 4 | 16 |
171 | 5 | 25 |
172
173 #+call: R-plot(data=R-plot-example-data)
174
175 #+resname: R-plot(data=R-plot-example-data)
176 : nil
177
178 ** Gnuplot
179
180 * Org reference
181
182 ** Headline references
183
184 #+name: headline
185 #+begin_src emacs-lisp :var headline=top :var file='()
186   (save-excursion
187     (when file (get-file-buffer file))
188     (org-open-link-from-string (org-make-link-string headline))
189     (save-restriction
190       (org-narrow-to-subtree)
191       (buffer-string)))
192 #+end_src
193
194 #+call: headline(headline="headline references")
195
196 * Tables
197
198 ** LaTeX Table Export
199
200 *** booktabs
201
202 This source block can be used to wrap a table in the latex =booktabs=
203 environment. The source block adds a =toprule= and =bottomrule= (so
204 don't use =hline= at the top or bottom of the table).  The =hline=
205 after the header is replaced with a =midrule=.
206
207 Note that this function bypasses the Org-mode LaTeX exporter and calls
208 =orgtbl-to-generic= to create the output table.  This means that the
209 entries in the table are not translated from Org-mode to LaTeX.
210
211 It takes the following arguments -- all but the first two are
212 optional.
213
214 | arg   | description                                |
215 |-------+--------------------------------------------|
216 | table | a reference to the table                   |
217 | align | alignment string                           |
218 | env   | optional environment, default to "tabular" |
219 | width | optional width specification string        |
220
221 #+name: booktabs
222 #+begin_src emacs-lisp :var table='((:head) hline (:body)) :var align='() :var env="tabular" :var width='() :noweb yes :results latex
223   (flet ((to-tab (tab)
224                  (orgtbl-to-generic
225                   (mapcar (lambda (lis)
226                             (if (listp lis)
227                                 (mapcar (lambda (el)
228                                           (if (stringp el)
229                                               el
230                                             (format "%S" el))) lis)
231                               lis)) tab)
232                   (list :lend " \\\\" :sep " & " :hline "\\hline"))))
233     (org-fill-template
234      "
235   \\begin{%env}%width%align
236   \\toprule
237   %table
238   \\bottomrule
239   \\end{%env}\n"
240      (list
241       (cons "env"       (or env "table"))
242       (cons "width"     (if width (format "{%s}" width) ""))
243       (cons "align"     (if align (format "{%s}" align) ""))
244       (cons "table"
245             ;; only use \midrule if it looks like there are column headers
246             (if (equal 'hline (second table))
247                 (concat (to-tab (list (first table)))
248                         "\n\\midrule\n"
249                         (to-tab (cddr table)))
250               (to-tab table))))))
251 #+end_src
252
253 *** longtable
254
255 This block can be used to wrap a table in the latex =longtable=
256 environment, it takes the following arguments -- all but the first two
257 are optional.
258
259 | arg       | description                                                 |
260 |-----------+-------------------------------------------------------------|
261 | table     | a reference to the table                                    |
262 | align     | optional alignment string                                   |
263 | width     | optional width specification string                         |
264 | hline     | the string to use as hline separator, defaults to "\\hline" |
265 | head      | optional "head" string                                      |
266 | firsthead | optional "firsthead" string                                 |
267 | foot      | optional "foot" string                                      |
268 | lastfoot  | optional "lastfoot" string                                  |
269
270 #+name: longtable
271 #+begin_src emacs-lisp :var table='((:table)) :var align='() :var width='() :var hline="\\hline" :var firsthead='() :var head='() :var foot='() :var lastfoot='() :noweb yes :results latex
272   (org-fill-template
273    "
274   \\begin{longtable}%width%align
275   %firsthead
276   %head
277   %foot
278   %lastfoot
279
280   %table
281   \\end{longtable}\n"
282    (list
283     (cons "width"     (if width (format "{%s}" width) ""))
284     (cons "align"     (if align (format "{%s}" align) ""))
285     (cons "firsthead" (if firsthead (concat firsthead "\n\\endfirsthead\n") ""))
286     (cons "head"      (if head (concat head "\n\\endhead\n") ""))
287     (cons "foot"      (if foot (concat foot "\n\\endfoot\n") ""))
288     (cons "lastfoot"  (if lastfoot (concat lastfoot "\n\\endlastfoot\n") ""))
289     (cons "table" (orgtbl-to-generic
290                    (mapcar (lambda (lis)
291                              (if (listp lis)
292                                  (mapcar (lambda (el)
293                                            (if (stringp el)
294                                                el
295                                              (format "%S" el))) lis)
296                                lis)) table)
297                    (list :lend " \\\\" :sep " & " :hline hline)))))
298 #+end_src
299
300 *** booktabs-notes
301
302 This source block builds on [[booktabs]].  It accepts two additional
303 arguments, both of which are optional.
304
305 #+tblname: arguments
306 | arg    | description                                          |
307 |--------+------------------------------------------------------|
308 | notes  | an org-mode table with footnotes                     |
309 | lspace | if non-nil, insert =addlinespace= after =bottomrule= |
310
311 An example footnote to the =arguments= table specifies the column
312 span. Note the use of LaTeX, rather than Org-mode, markup.
313
314 #+tblname: arguments-notes
315 | \multicolumn{2}{l}{This is a footnote to the \emph{arguments} table.} |
316
317 #+name: booktabs-notes
318 #+begin_src emacs-lisp :var table='((:head) hline (:body)) :var notes='() :var align='() :var env="tabular" :var width='() :var lspace='() :noweb yes :results latex
319   (flet ((to-tab (tab)
320                  (orgtbl-to-generic
321                   (mapcar (lambda (lis)
322                             (if (listp lis)
323                                 (mapcar (lambda (el)
324                                           (if (stringp el)
325                                               el
326                                             (format "%S" el))) lis)
327                               lis)) tab)
328                   (list :lend " \\\\" :sep " & " :hline "\\hline"))))
329     (org-fill-template
330      "
331     \\begin{%env}%width%align
332     \\toprule
333     %table
334     \\bottomrule%spacer
335     %notes
336     \\end{%env}\n"
337      (list
338       (cons "env"       (or env "table"))
339       (cons "width"     (if width (format "{%s}" width) ""))
340       (cons "align"     (if align (format "{%s}" align) ""))
341       (cons "spacer"    (if lspace "\\addlinespace" ""))
342       (cons "table"
343             ;; only use \midrule if it looks like there are column headers
344             (if (equal 'hline (second table))
345                 (concat (to-tab (list (first table)))
346                         "\n\\midrule\n"
347                         (to-tab (cddr table)))
348               (to-tab table)))
349       (cons "notes" (if notes (to-tab notes) ""))
350       )))
351 #+end_src
352
353 ** Elegant lisp for transposing a matrix
354
355 #+tblname: transpose-example
356 | 1 | 2 | 3 |
357 | 4 | 5 | 6 |
358
359 #+name: transpose
360 #+begin_src emacs-lisp :var table=transpose-example
361   (apply #'mapcar* #'list table)
362 #+end_src
363
364 #+resname:
365 | 1 | 4 |
366 | 2 | 5 |
367 | 3 | 6 |
368
369 ** Convert every element of a table to a string
370
371 #+tblname: hetero-table
372 | 1 | 2 | 3 |
373 | a | b | c |
374
375 #+name: all-to-string
376 #+begin_src emacs-lisp :var tbl='()
377   (defun all-to-string (tbl)
378     (if (listp tbl)
379         (mapcar #'all-to-string tbl)
380       (if (stringp tbl)
381           tbl
382         (format "%s" tbl))))
383   (all-to-string tbl)
384 #+end_src
385
386 #+begin_src emacs-lisp :var tbl=hetero-table
387   (mapcar (lambda (row) (mapcar (lambda (cell) (stringp cell)) row)) tbl)
388 #+end_src
389
390 #+name:
391 | nil | nil | nil |
392 | t   | t   | t   |
393
394 #+begin_src emacs-lisp :var tbl=all-to-string(hetero-table)
395   (mapcar (lambda (row) (mapcar (lambda (cell) (stringp cell)) row)) tbl)
396 #+end_src
397
398 #+name:
399 | t | t | t |
400 | t | t | t |
401
402 * Misc
403
404 ** File-specific Version Control logging
405    :PROPERTIES:
406    :AUTHOR: Luke Crook
407    :END:
408
409 This function will attempt to retrieve the entire commit log for the
410 file associated with the current buffer and insert this log into the
411 export. The function uses the Emacs VC commands to interface to the
412 local version control system, but has only been tested to work with
413 Git. 'limit' is currently unsupported.
414
415 #+name: vc-log
416 #+headers: :var limit=-1
417 #+headers: :var buf=(buffer-name (current-buffer))
418 #+begin_src emacs-lisp
419   ;; Most of this code is copied from vc.el vc-print-log
420   (require 'vc)
421   (when (vc-find-backend-function
422          (vc-backend (buffer-file-name (get-buffer buf))) 'print-log)
423     (let ((limit -1)
424           (vc-fileset nil)
425           (backend nil)
426           (files nil))
427       (with-current-buffer (get-buffer buf)
428         (setq vc-fileset (vc-deduce-fileset t)) ; FIXME: Why t? --Stef
429         (setq backend (car vc-fileset))
430         (setq files (cadr vc-fileset)))
431       (with-temp-buffer
432         (let ((status (vc-call-backend
433                        backend 'print-log files (current-buffer))))
434           (when (and (processp status)   ; Make sure status is a process
435                      (= 0 (process-exit-status status))) ; which has not terminated
436             (while (not (eq 'exit (process-status status)))
437               (sit-for 1 t)))
438           (buffer-string)))))
439 #+end_src
440
441 ** Trivial python code blocks
442
443 #+name: python-identity
444 #+begin_src python :var a=1
445 a
446 #+end_src
447
448 #+name: python-add
449 #+begin_src python :var a=1 :var b=2
450 a + b
451 #+end_src
452
453 ** Arithmetic
454
455 #+name: lob-add
456 #+begin_src emacs-lisp :var a=0 :var b=0
457   (+ a b)
458 #+end_src
459
460 #+name: lob-minus
461 #+begin_src emacs-lisp :var a=0 :var b=0
462   (- a b)
463 #+end_src
464
465 #+name: lob-times
466 #+begin_src emacs-lisp :var a=0 :var b=0
467   (* a b)
468 #+end_src
469
470 #+name: lob-div
471 #+begin_src emacs-lisp :var a=0 :var b=0
472   (/ a b)
473 #+end_src
474
475 * GANTT Charts
476
477 The =elispgantt= source block was sent to the mailing list by Eric
478 Fraga.  It was modified slightly by Tom Dye.
479
480 #+name: elispgantt
481 #+begin_src emacs-lisp :var table=gantttest
482   (let ((dates "")
483         (entries (nthcdr 2 table))
484         (milestones "")
485         (nmilestones 0)
486         (ntasks 0)
487         (projecttime 0)
488         (tasks "")
489         (xlength 1))
490     (message "Initial: %s\n" table)
491     (message "Entries: %s\n" entries)
492     (while entries
493       (let ((entry (first entries)))
494         (if (listp entry)
495             (let ((id (first entry))
496                   (type (nth 1 entry))
497                   (label (nth 2 entry))
498                   (task (nth 3 entry))
499                   (dependencies (nth 4 entry))
500                   (start (nth 5 entry))
501                   (duration (nth 6 entry))
502                   (end (nth 7 entry))
503                   (alignment (nth 8 entry)))
504               (if (> start projecttime) (setq projecttime start))
505               (if (string= type "task")
506                   (let ((end (+ start duration))
507                         (textposition (+ start (/ duration 2)))
508                         (flush ""))
509                     (if (string= alignment "left")
510                         (progn
511                           (setq textposition start)
512                           (setq flush "[left]"))
513                       (if (string= alignment "right")
514                           (progn
515                             (setq textposition end)
516                             (setq flush "[right]"))))
517                     (setq tasks
518                           (format "%s  \\gantttask{%s}{%s}{%d}{%d}{%d}{%s}\n"
519                                   tasks label task start end textposition flush))
520                     (setq ntasks (+ 1 ntasks))
521                     (if (> end projecttime)
522                         (setq projecttime end)))
523                 (if (string= type "milestone")
524                     (progn
525                       (setq milestones
526                             (format
527                              "%s  \\ganttmilestone{$\\begin{array}{c}\\mbox{%s}\\\\ \\mbox{%s}\\end{array}$}{%d}\n"
528                              milestones label task start))
529                       (setq nmilestones (+ 1 nmilestones)))
530                   (if (string= type "date")
531                       (setq dates (format "%s  \\ganttdateline{%s}{%d}\n"
532                                           dates label start))
533                     (message "Ignoring entry with type %s\n" type)))))
534           (message "Ignoring non-list entry %s\n" entry)) ; end if list entry
535         (setq entries (cdr entries))))  ; end while entries left
536     (format "\\pgfdeclarelayer{background}
537   \\pgfdeclarelayer{foreground}
538   \\pgfsetlayers{background,foreground}
539   \\renewcommand{\\ganttprojecttime}{%d}
540   \\renewcommand{\\ganttntasks}{%d}
541   \\noindent
542   \\begin{tikzpicture}[y=-0.75cm,x=0.75\\textwidth]
543     \\begin{pgfonlayer}{background}
544       \\draw[very thin, red!10!white] (0,1+\\ganttntasks) grid [ystep=0.75cm,xstep=1/\\ganttprojecttime] (1,0);
545       \\draw[\\ganttdatelinecolour] (0,0) -- (1,0);
546       \\draw[\\ganttdatelinecolour] (0,1+\\ganttntasks) -- (1,1+\\ganttntasks);
547     \\end{pgfonlayer}
548   %s
549   %s
550   %s
551   \\end{tikzpicture}" projecttime ntasks tasks milestones dates))
552 #+end_src
553
554 * Available languages
555   :PROPERTIES:
556   :AUTHOR:   Bastien
557   :END:
558
559 ** From Org's core
560
561 | Language   | Identifier | Language       | Identifier |
562 |------------+------------+----------------+------------|
563 | Asymptote  | asymptote  | Awk            | awk        |
564 | Emacs Calc | calc       | C              | C          |
565 | C++        | C++        | Clojure        | clojure    |
566 | CSS        | css        | ditaa          | ditaa      |
567 | Graphviz   | dot        | Emacs Lisp     | emacs-lisp |
568 | gnuplot    | gnuplot    | Haskell        | haskell    |
569 | Javascript | js         | LaTeX          | latex      |
570 | Ledger     | ledger     | Lisp           | lisp       |
571 | Lilypond   | lilypond   | MATLAB         | matlab     |
572 | Mscgen     | mscgen     | Objective Caml | ocaml      |
573 | Octave     | octave     | Org-mode       | org        |
574 |            |            | Perl           | perl       |
575 | Plantuml   | plantuml   | Python         | python     |
576 | R          | R          | Ruby           | ruby       |
577 | Sass       | sass       | Scheme         | scheme     |
578 | GNU Screen | screen     | shell          | sh         |
579 | SQL        | sql        | SQLite         | sqlite     |
580
581 ** From Org's contrib/babel/langs
582
583 - ob-oz.el, by Torsten Anders and Eric Schulte
584 - ob-fomus.el, by Torsten Anders