Merge branch 'maint'
[org-mode.git] / lisp / ob-ref.el
blob5a3c8ba2e4894521b6ec3b41e8198d5fcbbee47b
1 ;;; ob-ref.el --- org-babel functions for referencing external data
3 ;; Copyright (C) 2009-2013 Free Software Foundation, Inc.
5 ;; Authors: Eric Schulte
6 ;; Dan Davison
7 ;; Keywords: literate programming, reproducible research
8 ;; Homepage: http://orgmode.org
10 ;; This file is part of GNU Emacs.
12 ;; GNU Emacs is free software: you can redistribute it and/or modify
13 ;; it under the terms of the GNU General Public License as published by
14 ;; the Free Software Foundation, either version 3 of the License, or
15 ;; (at your option) any later version.
17 ;; GNU Emacs is distributed in the hope that it will be useful,
18 ;; but WITHOUT ANY WARRANTY; without even the implied warranty of
19 ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
20 ;; GNU General Public License for more details.
22 ;; You should have received a copy of the GNU General Public License
23 ;; along with GNU Emacs. If not, see <http://www.gnu.org/licenses/>.
25 ;;; Commentary:
27 ;; Functions for referencing data from the header arguments of a
28 ;; org-babel block. The syntax of such a reference should be
30 ;; #+VAR: variable-name=file:resource-id
32 ;; - variable-name :: the name of the variable to which the value
33 ;; will be assigned
35 ;; - file :: path to the file containing the resource, or omitted if
36 ;; resource is in the current file
38 ;; - resource-id :: the id or name of the resource
40 ;; So an example of a simple src block referencing table data in the
41 ;; same file would be
43 ;; #+NAME: sandbox
44 ;; | 1 | 2 | 3 |
45 ;; | 4 | org-babel | 6 |
47 ;; #+begin_src emacs-lisp :var table=sandbox
48 ;; (message table)
49 ;; #+end_src
51 ;;; Code:
52 (require 'ob-core)
53 (eval-when-compile
54 (require 'cl))
56 (declare-function org-remove-if-not "org" (predicate seq))
57 (declare-function org-at-table-p "org" (&optional table-type))
58 (declare-function org-count "org" (CL-ITEM CL-SEQ))
59 (declare-function org-at-item-p "org-list" ())
60 (declare-function org-narrow-to-subtree "org" ())
61 (declare-function org-id-find-id-in-file "org-id" (id file &optional markerp))
62 (declare-function org-id-find-id-file "org-id" (id))
63 (declare-function org-show-context "org" (&optional key))
64 (declare-function org-pop-to-buffer-same-window
65 "org-compat" (&optional buffer-or-name norecord label))
67 (defvar org-babel-ref-split-regexp
68 "[ \f\t\n\r\v]*\\(.+?\\)[ \f\t\n\r\v]*=[ \f\t\n\r\v]*\\(.+\\)[ \f\t\n\r\v]*")
70 (defvar org-babel-update-intermediate nil
71 "Update the in-buffer results of code blocks executed to resolve references.")
73 (defun org-babel-ref-parse (assignment)
74 "Parse a variable ASSIGNMENT in a header argument.
75 If the right hand side of the assignment has a literal value
76 return that value, otherwise interpret as a reference to an
77 external resource and find its value using
78 `org-babel-ref-resolve'. Return a list with two elements. The
79 first element of the list will be the name of the variable, and
80 the second will be an emacs-lisp representation of the value of
81 the variable."
82 (when (string-match org-babel-ref-split-regexp assignment)
83 (let ((var (match-string 1 assignment))
84 (ref (match-string 2 assignment)))
85 (cons (intern var)
86 (let ((out (save-excursion
87 (when org-babel-current-src-block-location
88 (goto-char org-babel-current-src-block-location))
89 (org-babel-read ref))))
90 (if (equal out ref)
91 (if (string-match "^\".*\"$" ref)
92 (read ref)
93 (org-babel-ref-resolve ref))
94 out))))))
96 (defun org-babel-ref-goto-headline-id (id)
97 (goto-char (point-min))
98 (let ((rx (regexp-quote id)))
99 (or (re-search-forward
100 (concat "^[ \t]*:CUSTOM_ID:[ \t]+" rx "[ \t]*$") nil t)
101 (let* ((file (org-id-find-id-file id))
102 (m (when file (org-id-find-id-in-file id file 'marker))))
103 (when (and file m)
104 (message "file:%S" file)
105 (org-pop-to-buffer-same-window (marker-buffer m))
106 (goto-char m)
107 (move-marker m nil)
108 (org-show-context)
109 t)))))
111 (defun org-babel-ref-headline-body ()
112 (save-restriction
113 (org-narrow-to-subtree)
114 (buffer-substring
115 (save-excursion (goto-char (point-min))
116 (forward-line 1)
117 (when (looking-at "[ \t]*:PROPERTIES:")
118 (re-search-forward ":END:" nil)
119 (forward-char))
120 (point))
121 (point-max))))
123 (defvar org-babel-library-of-babel)
124 (defun org-babel-ref-resolve (ref)
125 "Resolve the reference REF and return its value."
126 (save-window-excursion
127 (save-excursion
128 (let ((case-fold-search t)
129 type args new-refere new-header-args new-referent result
130 lob-info split-file split-ref index index-row index-col id)
131 ;; if ref is indexed grab the indices -- beware nested indices
132 (when (and (string-match "\\[\\([^\\[]+\\)\\]$" ref)
133 (let ((str (substring ref 0 (match-beginning 0))))
134 (= (org-count ?( str) (org-count ?) str))))
135 (setq index (match-string 1 ref))
136 (setq ref (substring ref 0 (match-beginning 0))))
137 ;; assign any arguments to pass to source block
138 (when (string-match
139 "^\\(.+?\\)\\(\\[\\(.*\\)\\]\\|\\(\\)\\)\(\\(.*\\)\)$" ref)
140 (setq new-refere (match-string 1 ref))
141 (setq new-header-args (match-string 3 ref))
142 (setq new-referent (match-string 5 ref))
143 (when (> (length new-refere) 0)
144 (when (> (length new-referent) 0)
145 (setq args (mapcar (lambda (ref) (cons :var ref))
146 (org-babel-ref-split-args new-referent))))
147 (when (> (length new-header-args) 0)
148 (setq args (append (org-babel-parse-header-arguments
149 new-header-args) args)))
150 (setq ref new-refere)))
151 (when (string-match "^\\(.+\\):\\(.+\\)$" ref)
152 (setq split-file (match-string 1 ref))
153 (setq split-ref (match-string 2 ref))
154 (find-file split-file) (setq ref split-ref))
155 (save-restriction
156 (widen)
157 (goto-char (point-min))
158 (if (let ((src-rx (org-babel-named-src-block-regexp-for-name ref))
159 (res-rx (org-babel-named-data-regexp-for-name ref)))
160 ;; goto ref in the current buffer
162 ;; check for code blocks
163 (re-search-forward src-rx nil t)
164 ;; check for named data
165 (re-search-forward res-rx nil t)
166 ;; check for local or global headlines by id
167 (setq id (org-babel-ref-goto-headline-id ref))
168 ;; check the Library of Babel
169 (setq lob-info (cdr (assoc (intern ref)
170 org-babel-library-of-babel)))))
171 (unless (or lob-info id) (goto-char (match-beginning 0)))
172 ;; ;; TODO: allow searching for names in other buffers
173 ;; (setq id-loc (org-id-find ref 'marker)
174 ;; buffer (marker-buffer id-loc)
175 ;; loc (marker-position id-loc))
176 ;; (move-marker id-loc nil)
177 (error "Reference '%s' not found in this buffer" ref))
178 (cond
179 (lob-info (setq type 'lob))
180 (id (setq type 'id))
181 ((and (looking-at org-babel-src-name-regexp)
182 (save-excursion
183 (forward-line 1)
184 (or (looking-at org-babel-src-block-regexp)
185 (looking-at org-babel-multi-line-header-regexp))))
186 (setq type 'source-block))
187 (t (while (not (setq type (org-babel-ref-at-ref-p)))
188 (forward-line 1)
189 (beginning-of-line)
190 (if (or (= (point) (point-min)) (= (point) (point-max)))
191 (error "Reference not found")))))
192 (let ((params (append args '((:results . "silent")))))
193 (setq result
194 (case type
195 (results-line (org-babel-read-result))
196 (table (org-babel-read-table))
197 (list (org-babel-read-list))
198 (file (org-babel-read-link))
199 (source-block (org-babel-execute-src-block
200 nil nil (if org-babel-update-intermediate
201 nil params)))
202 (lob (org-babel-execute-src-block
203 nil lob-info params))
204 (id (org-babel-ref-headline-body)))))
205 (if (symbolp result)
206 (format "%S" result)
207 (if (and index (listp result))
208 (org-babel-ref-index-list index result)
209 result)))))))
211 (defun org-babel-ref-index-list (index lis)
212 "Return the subset of LIS indexed by INDEX.
214 Indices are 0 based and negative indices count from the end of
215 LIS, so 0 references the first element of LIS and -1 references
216 the last. If INDEX is separated by \",\"s then each \"portion\"
217 is assumed to index into the next deepest nesting or dimension.
219 A valid \"portion\" can consist of either an integer index, two
220 integers separated by a \":\" in which case the entire range is
221 returned, or an empty string or \"*\" both of which are
222 interpreted to mean the entire range and as such are equivalent
223 to \"0:-1\"."
224 (if (and (> (length index) 0) (string-match "^\\([^,]*\\),?" index))
225 (let* ((ind-re "\\(\\([-[:digit:]]+\\):\\([-[:digit:]]+\\)\\|\*\\)")
226 (lgth (length lis))
227 (portion (match-string 1 index))
228 (remainder (substring index (match-end 0)))
229 (wrap (lambda (num) (if (< num 0) (+ lgth num) num)))
230 (open (lambda (ls) (if (and (listp ls) (= (length ls) 1)) (car ls) ls))))
231 (funcall
232 open
233 (mapcar
234 (lambda (sub-lis)
235 (if (listp sub-lis)
236 (org-babel-ref-index-list remainder sub-lis)
237 sub-lis))
238 (if (or (= 0 (length portion)) (string-match ind-re portion))
239 (mapcar
240 (lambda (n) (nth n lis))
241 (apply 'org-number-sequence
242 (if (and (> (length portion) 0) (match-string 2 portion))
243 (list
244 (funcall wrap (string-to-number (match-string 2 portion)))
245 (funcall wrap (string-to-number (match-string 3 portion))))
246 (list (funcall wrap 0) (funcall wrap -1)))))
247 (list (nth (funcall wrap (string-to-number portion)) lis))))))
248 lis))
250 (defun org-babel-ref-split-args (arg-string)
251 "Split ARG-STRING into top-level arguments of balanced parenthesis."
252 (mapcar #'org-babel-trim (org-babel-balanced-split arg-string 44)))
254 (defvar org-bracket-link-regexp)
255 (defun org-babel-ref-at-ref-p ()
256 "Return the type of reference located at point.
257 Return nil if none of the supported reference types are found.
258 Supported reference types are tables and source blocks."
259 (cond ((org-at-table-p) 'table)
260 ((org-at-item-p) 'list)
261 ((looking-at "^[ \t]*#\\+BEGIN_SRC") 'source-block)
262 ((looking-at org-bracket-link-regexp) 'file)
263 ((looking-at org-babel-result-regexp) 'results-line)))
265 (provide 'ob-ref)
269 ;;; ob-ref.el ends here