ob-ref.el 11 KB

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