1 ;;; ob-ref.el --- org-babel functions for referencing external data
3 ;; Copyright (C) 2009-2011 Free Software Foundation, Inc.
5 ;; Author: Eric Schulte
7 ;; Keywords: literate programming, reproducible research
8 ;; Homepage: http://orgmode.org
11 ;; This file is part of GNU Emacs.
13 ;; GNU Emacs is free software: you can redistribute it and/or modify
14 ;; it under the terms of the GNU General Public License as published by
15 ;; the Free Software Foundation, either version 3 of the License, or
16 ;; (at your option) any later version.
18 ;; GNU Emacs is distributed in the hope that it will be useful,
19 ;; but WITHOUT ANY WARRANTY; without even the implied warranty of
20 ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
21 ;; GNU General Public License for more details.
23 ;; You should have received a copy of the GNU General Public License
24 ;; along with GNU Emacs. If not, see <http://www.gnu.org/licenses/>.
28 ;; Functions for referencing data from the header arguments of a
29 ;; org-babel block. The syntax of such a reference should be
31 ;; #+VAR: variable-name=file:resource-id
33 ;; - variable-name :: the name of the variable to which the value
36 ;; - file :: path to the file containing the resource, or omitted if
37 ;; resource is in the current file
39 ;; - resource-id :: the id or name of the resource
41 ;; So an example of a simple src block referencing table data in the
46 ;; | 4 | org-babel | 6 |
48 ;; #+begin_src emacs-lisp :var table=sandbox
57 (declare-function org-remove-if-not
"org" (predicate seq
))
58 (declare-function org-at-table-p
"org" (&optional table-type
))
59 (declare-function org-count
"org" (CL-ITEM CL-SEQ
))
60 (declare-function org-at-item-p
"org-list" ())
61 (declare-function org-narrow-to-subtree
"org" ())
62 (declare-function org-id-find-id-in-file
"org-id" (id file
&optional markerp
))
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 (defun org-babel-ref-parse (assignment)
71 "Parse a variable ASSIGNMENT in a header argument.
72 If the right hand side of the assignment has a literal value
73 return that value, otherwise interpret as a reference to an
74 external resource and find it's value using
75 `org-babel-ref-resolve'. Return a list with two elements. The
76 first element of the list will be the name of the variable, and
77 the second will be an emacs-lisp representation of the value of
79 (when (string-match org-babel-ref-split-regexp assignment
)
80 (let ((var (match-string 1 assignment
))
81 (ref (match-string 2 assignment
)))
83 (let ((out (org-babel-read ref
)))
85 (if (string-match "^\".*\"$" ref
)
87 (org-babel-ref-resolve ref
))
90 (defun org-babel-ref-goto-headline-id (id)
91 (goto-char (point-min))
92 (let ((rx (regexp-quote id
)))
93 (or (re-search-forward
94 (concat "^[ \t]*:CUSTOM_ID:[ \t]+" rx
"[ \t]*$") nil t
)
95 (let* ((file (org-id-find-id-file id
))
96 (m (when file
(org-id-find-id-in-file id file
'marker
))))
98 (message "file:%S" file
)
99 (org-pop-to-buffer-same-window (marker-buffer m
))
105 (defun org-babel-ref-headline-body ()
107 (org-narrow-to-subtree)
109 (save-excursion (goto-char (point-min))
111 (when (looking-at "[ \t]*:PROPERTIES:")
112 (re-search-forward ":END:" nil
)
117 (defvar org-babel-library-of-babel
)
118 (defun org-babel-ref-resolve (ref)
119 "Resolve the reference REF and return its value."
120 (save-window-excursion
122 (let ((case-fold-search t
)
123 type args new-refere new-header-args new-referent result
124 lob-info split-file split-ref index index-row index-col id
)
125 ;; if ref is indexed grab the indices -- beware nested indices
126 (when (and (string-match "\\[\\([^\\[]+\\)\\]$" ref
)
127 (let ((str (substring ref
0 (match-beginning 0))))
128 (= (org-count ?
( str
) (org-count ?
) str
))))
129 (setq index
(match-string 1 ref
))
130 (setq ref
(substring ref
0 (match-beginning 0))))
131 ;; assign any arguments to pass to source block
133 "^\\(.+?\\)\\(\\[\\(.*\\)\\]\\|\\(\\)\\)\(\\(.*\\)\)$" ref
)
134 (setq new-refere
(match-string 1 ref
))
135 (setq new-header-args
(match-string 3 ref
))
136 (setq new-referent
(match-string 5 ref
))
137 (when (> (length new-refere
) 0)
138 (when (> (length new-referent
) 0)
139 (setq args
(mapcar (lambda (ref) (cons :var ref
))
140 (org-babel-ref-split-args new-referent
))))
141 (when (> (length new-header-args
) 0)
142 (setq args
(append (org-babel-parse-header-arguments
143 new-header-args
) args
)))
144 (setq ref new-refere
)))
145 (when (string-match "^\\(.+\\):\\(.+\\)$" ref
)
146 (setq split-file
(match-string 1 ref
))
147 (setq split-ref
(match-string 2 ref
))
148 (find-file split-file
) (setq ref split-ref
))
151 (goto-char (point-min))
152 (if (let* ((rx (regexp-quote ref
))
153 (res-rx (concat org-babel-result-regexp rx
"[ \t]*$"))
154 (src-rx (concat org-babel-src-name-regexp
155 rx
"\\(\(.*\)\\)?" "[ \t]*$")))
156 ;; goto ref in the current buffer
158 (or (re-search-forward res-rx nil t
)
159 (re-search-backward res-rx nil t
)))
160 (re-search-forward src-rx nil t
)
161 (re-search-backward src-rx nil t
)
162 ;; check for local or global headlines by id
163 (setq id
(org-babel-ref-goto-headline-id ref
))
164 ;; check the Library of Babel
165 (setq lob-info
(cdr (assoc (intern ref
)
166 org-babel-library-of-babel
)))))
167 (unless (or lob-info id
) (goto-char (match-beginning 0)))
168 ;; ;; TODO: allow searching for names in other buffers
169 ;; (setq id-loc (org-id-find ref 'marker)
170 ;; buffer (marker-buffer id-loc)
171 ;; loc (marker-position id-loc))
172 ;; (move-marker id-loc nil)
173 (error "reference '%s' not found in this buffer" ref
))
175 (lob-info (setq type
'lob
))
177 (t (while (not (setq type
(org-babel-ref-at-ref-p)))
180 (if (or (= (point) (point-min)) (= (point) (point-max)))
181 (error "reference not found")))))
182 (let ((params (append args
'((:results .
"silent")))))
185 (results-line (org-babel-read-result))
186 (table (org-babel-read-table))
187 (list (org-babel-read-list))
188 (file (org-babel-read-link))
189 (source-block (org-babel-execute-src-block nil nil params
))
190 (lob (org-babel-execute-src-block
191 nil lob-info params
))
192 (id (org-babel-ref-headline-body)))))
195 (if (and index
(listp result
))
196 (org-babel-ref-index-list index result
)
199 (defun org-babel-ref-index-list (index lis
)
200 "Return the subset of LIS indexed by INDEX.
202 Indices are 0 based and negative indices count from the end of
203 LIS, so 0 references the first element of LIS and -1 references
204 the last. If INDEX is separated by \",\"s then each \"portion\"
205 is assumed to index into the next deepest nesting or dimension.
207 A valid \"portion\" can consist of either an integer index, two
208 integers separated by a \":\" in which case the entire range is
209 returned, or an empty string or \"*\" both of which are
210 interpreted to mean the entire range and as such are equivalent
212 (if (and (> (length index
) 0) (string-match "^\\([^,]*\\),?" index
))
213 (let ((ind-re "\\(\\([-[:digit:]]+\\):\\([-[:digit:]]+\\)\\|\*\\)")
214 (length (length lis
))
215 (portion (match-string 1 index
))
216 (remainder (substring index
(match-end 0))))
217 (flet ((wrap (num) (if (< num
0) (+ length num
) num
))
218 (open (ls) (if (and (listp ls
) (= (length ls
) 1)) (car ls
) ls
)))
223 (org-babel-ref-index-list remainder sub-lis
)
225 (if (or (= 0 (length portion
)) (string-match ind-re portion
))
227 (lambda (n) (nth n lis
))
228 (apply 'org-number-sequence
229 (if (and (> (length portion
) 0) (match-string 2 portion
))
231 (wrap (string-to-number (match-string 2 portion
)))
232 (wrap (string-to-number (match-string 3 portion
))))
233 (list (wrap 0) (wrap -
1)))))
234 (list (nth (wrap (string-to-number portion
)) lis
)))))))
237 (defun org-babel-ref-split-args (arg-string)
238 "Split ARG-STRING into top-level arguments of balanced parenthesis."
239 (let ((index 0) (depth 0) (buffer "") holder return
)
240 ;; crawl along string, splitting at any ","s which are on the top level
241 (while (< index
(length arg-string
))
242 (setq holder
(substring arg-string index
(+ 1 index
)))
243 (setq buffer
(concat buffer holder
))
244 (setq index
(+ 1 index
))
246 ((string= holder
",")
248 (setq return
(cons (substring buffer
0 -
1) return
))
250 ((or (string= holder
"(") (string= holder
"[")) (setq depth
(+ depth
1)))
251 ((or (string= holder
")") (string= holder
"]")) (setq depth
(- depth
1)))))
252 (mapcar #'org-babel-trim
(reverse (cons buffer return
)))))
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
)))
269 ;;; ob-ref.el ends here