lisp/ob-ref.el

   1 ;;; ob-ref.el --- org-babel functions for referencing external data
   2
   3 ;; Copyright (C) 2009, 2010  Free Software Foundation, Inc.
   4
   5 ;; Author: Eric Schulte, Dan Davison
   6 ;; Keywords: literate programming, reproducible research
   7 ;; Homepage: http://orgmode.org
   8 ;; Version: 7.3
   9
  10 ;; This file is part of GNU Emacs.
  11
  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.
  16
  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.
  21
  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/>.
  24
  25 ;;; Commentary:
  26
  27 ;; Functions for referencing data from the header arguments of a
  28 ;; org-babel block.  The syntax of such a reference should be
  29
  30 ;;   #+VAR: variable-name=file:resource-id
  31
  32 ;; - variable-name :: the name of the variable to which the value
  33 ;;                    will be assigned
  34
  35 ;; - file :: path to the file containing the resource, or omitted if
  36 ;;           resource is in the current file
  37
  38 ;; - resource-id :: the id or name of the resource
  39
  40 ;; So an example of a simple src block referencing table data in the
  41 ;; same file would be
  42
  43 ;;  #+TBLNAME: sandbox
  44 ;;  | 1 |         2 | 3 |
  45 ;;  | 4 | org-babel | 6 |
  46 ;;
  47 ;;  #+begin_src emacs-lisp :var table=sandbox
  48 ;;    (message table)
  49 ;;  #+end_src
  50
  51 ;;; Code:
  52 (require 'ob)
  53 (eval-when-compile
  54   (require 'cl))
  55
  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
  60 (defvar org-babel-ref-split-regexp
  61   "[ \f\t\n\r\v]*\\(.+?\\)[ \f\t\n\r\v]*=[ \f\t\n\r\v]*\\(.+\\)[ \f\t\n\r\v]*")
  62
  63 (defun org-babel-ref-parse (assignment)
  64   "Parse a variable ASSIGNMENT in a header argument.
  65 If the right hand side of the assignment has a literal value
  66 return that value, otherwise interpret as a reference to an
  67 external resource and find it's value using
  68 `org-babel-ref-resolve'.  Return a list with two elements.  The
  69 first element of the list will be the name of the variable, and
  70 the second will be an emacs-lisp representation of the value of
  71 the variable."
  72   (when (string-match org-babel-ref-split-regexp assignment)
  73     (let ((var (match-string 1 assignment))
  74           (ref (match-string 2 assignment)))
  75       (cons (intern var)
  76             ((lambda (val)
  77                (if (equal :ob-must-be-reference val)
  78                    (org-babel-ref-resolve ref) val))
  79              (org-babel-ref-literal ref))))))
  80
  81 (defun org-babel-ref-literal (ref)
  82   "Return the value of REF if it is a literal value.
  83 Determine if the right side of a header argument variable
  84 assignment is a literal value or is a reference to some external
  85 resource.  REF should be a string of the right hand side of the
  86 assignment.  If REF is literal then return it's value, otherwise
  87 return nil."
  88   (let ((out (org-babel-read ref)))
  89     (if (equal out ref)
  90         (if (string-match "^\".+\"$" ref)
  91             (read ref)
  92           :ob-must-be-reference)
  93       out)))
  94
  95 (defvar org-babel-library-of-babel)
  96 (defun org-babel-ref-resolve (ref)
  97   "Resolve the reference REF and return its value."
  98   (save-excursion
  99     (let ((case-fold-search t)
 100           type args new-refere new-referent result lob-info split-file split-ref
 101           index index-row index-col)
 102       ;; if ref is indexed grab the indices -- beware nested indices
 103       (when (and (string-match "\\[\\(.+\\)\\]" ref)
 104                  (let ((str (substring ref 0 (match-beginning 0))))
 105                    (= (org-count ?( str) (org-count ?) str))))
 106         (setq index (match-string 1 ref))
 107         (setq ref (substring ref 0 (match-beginning 0))))
 108       ;; assign any arguments to pass to source block
 109       (when (string-match "^\\(.+?\\)\(\\(.*\\)\)$" ref)
 110         (setq new-refere (match-string 1 ref))
 111         (setq new-referent (match-string 2 ref))
 112         (when (> (length new-refere) 0)
 113           (if (> (length new-referent) 0)
 114               (setq args (mapcar (lambda (ref) (cons :var ref))
 115                                  (org-babel-ref-split-args new-referent))))
 116           (setq ref new-refere)))
 117       (when (string-match "^\\(.+\\):\\(.+\\)$" ref)
 118         (setq split-file (match-string 1 ref))
 119         (setq split-ref (match-string 2 ref))
 120         (find-file split-file) (setq ref split-ref))
 121       (save-restriction
 122         (widen)
 123         (goto-char (point-min))
 124         (if (let ((result_regexp (concat "^[ \t]*#\\+\\(TBLNAME\\|RESNAME"
 125                                          "\\|RESULTS\\):[ \t]*"
 126                                          (regexp-quote ref) "[ \t]*$"))
 127                   (regexp (concat org-babel-src-name-regexp
 128                                   (regexp-quote ref) "\\(\(.*\)\\)?" "[ \t]*$")))
 129               ;; goto ref in the current buffer
 130               (or (and (not args)
 131                        (or (re-search-forward result_regexp nil t)
 132                            (re-search-backward result_regexp nil t)))
 133                   (re-search-forward regexp nil t)
 134                   (re-search-backward regexp nil t)
 135                   ;; check the Library of Babel
 136                   (setq lob-info (cdr (assoc (intern ref)
 137                                              org-babel-library-of-babel)))))
 138             (unless lob-info (goto-char (match-beginning 0)))
 139           ;; ;; TODO: allow searching for names in other buffers
 140           ;; (setq id-loc (org-id-find ref 'marker)
 141           ;;       buffer (marker-buffer id-loc)
 142           ;;       loc (marker-position id-loc))
 143           ;; (move-marker id-loc nil)
 144           (error "reference '%s' not found in this buffer" ref))
 145         (if lob-info
 146             (setq type 'lob)
 147           (while (not (setq type (org-babel-ref-at-ref-p)))
 148             (forward-line 1)
 149             (beginning-of-line)
 150             (if (or (= (point) (point-min)) (= (point) (point-max)))
 151                 (error "reference not found"))))
 152         (let ((params (append args '((:results . "silent")))))
 153           (setq result
 154                 (case type
 155                   ('results-line (org-babel-read-result))
 156                   ('table (org-babel-read-table))
 157                   ('file (org-babel-read-link))
 158                   ('source-block (org-babel-execute-src-block nil nil params))
 159                   ('lob (org-babel-execute-src-block nil lob-info params)))))
 160         (if (symbolp result)
 161             (format "%S" result)
 162           (if (and index (listp result))
 163               (org-babel-ref-index-list index result)
 164             result))))))
 165
 166 (defun org-babel-ref-index-list (index lis)
 167   "Return the subset of LIS indexed by INDEX.
 168
 169 Indices are 0 based and negative indices count from the end of
 170 LIS, so 0 references the first element of LIS and -1 references
 171 the last.  If INDEX is separated by \",\"s then each \"portion\"
 172 is assumed to index into the next deepest nesting or dimension.
 173
 174 A valid \"portion\" can consist of either an integer index, two
 175 integers separated by a \":\" in which case the entire range is
 176 returned, or an empty string or \"*\" both of which are
 177 interpreted to mean the entire range and as such are equivalent
 178 to \"0:-1\"."
 179   (if (and (> (length index) 0) (string-match "^\\([^,]*\\),?" index))
 180       (let ((ind-re "\\(\\([-[:digit:]]+\\):\\([-[:digit:]]+\\)\\|\*\\)")
 181             (length (length lis))
 182             (portion (match-string 1 index))
 183             (remainder (substring index (match-end 0))))
 184         (flet ((wrap (num) (if (< num 0) (+ length num) num))
 185                (open (ls) (if (and (listp ls) (= (length ls) 1)) (car ls) ls)))
 186           (open
 187            (mapcar
 188             (lambda (sub-lis) (org-babel-ref-index-list remainder sub-lis))
 189             (if (or (= 0 (length portion)) (string-match ind-re portion))
 190                 (mapcar
 191                  (lambda (n) (nth n lis))
 192                  (apply 'org-number-sequence
 193                         (if (and (> (length portion) 0) (match-string 2 portion))
 194                             (list
 195                              (wrap (string-to-number (match-string 2 portion)))
 196                              (wrap (string-to-number (match-string 3 portion))))
 197                           (list (wrap 0) (wrap -1)))))
 198               (list (nth (wrap (string-to-number portion)) lis)))))))
 199     lis))
 200
 201 (defun org-babel-ref-split-args (arg-string)
 202   "Split ARG-STRING into top-level arguments of balanced parenthesis."
 203   (let ((index 0) (depth 0) (buffer "") holder return)
 204     ;; crawl along string, splitting at any ","s which are on the top level
 205     (while (< index (length arg-string))
 206       (setq holder (substring arg-string index (+ 1 index)))
 207       (setq buffer (concat buffer holder))
 208       (setq index (+ 1 index))
 209       (cond
 210        ((string= holder ",")
 211         (when (= depth 0)
 212           (setq return (reverse (cons (substring buffer 0 -1) return)))
 213           (setq buffer "")))
 214        ((or (string= holder "(") (string= holder "[")) (setq depth (+ depth 1)))
 215        ((or (string= holder ")") (string= holder "]")) (setq depth (- depth 1)))))
 216     (mapcar #'org-babel-trim (reverse (cons buffer return)))))
 217
 218 (defvar org-bracket-link-regexp)
 219 (defun org-babel-ref-at-ref-p ()
 220   "Return the type of reference located at point.
 221 Return nil if none of the supported reference types are found.
 222 Supported reference types are tables and source blocks."
 223   (cond ((org-at-table-p) 'table)
 224         ((looking-at "^[ \t]*#\\+BEGIN_SRC") 'source-block)
 225         ((looking-at org-bracket-link-regexp) 'file)
 226         ((looking-at org-babel-result-regexp) 'results-line)))
 227
 228 (provide 'ob-ref)
 229
 230 ;; arch-tag: ace4a4f4-ea38-4dac-8fe6-6f52fcc43b6d
 231
 232 ;;; ob-ref.el ends here