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: 0.01
   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
  59 (defun org-babel-ref-variables (params)
  60   "Takes a parameter alist, and return an alist of variable
  61 names, and the emacs-lisp representation of the related value."
  62   (let ((assignments
  63          (delq nil (mapcar (lambda (pair) (if (eq (car pair) :var) (cdr pair))) params)))
  64         (others
  65          (delq nil (mapcar (lambda (pair) (unless (eq :var (car pair)) pair)) params))))
  66     (mapcar (lambda (assignment) (org-babel-ref-parse assignment)) assignments)))
  67
  68 (defvar org-babel-ref-split-regexp
  69   "[ \f\t\n\r\v]*\\(.+?\\)[ \f\t\n\r\v]*=[ \f\t\n\r\v]*\\(.+\\)[ \f\t\n\r\v]*")
  70
  71 (defun org-babel-ref-parse (assignment &optional params)
  72   "Parse a variable ASSIGNMENT in a header argument.  If the
  73 right hand side of the assignment has a literal value return that
  74 value, otherwise interpret as a reference to an external resource
  75 and find it's value using `org-babel-ref-resolve-reference'.
  76 Return a list with two elements.  The first element of the list
  77 will be the name of the variable, and the second will be an
  78 emacs-lisp representation of the value of the variable."
  79   (if (string-match org-babel-ref-split-regexp assignment)
  80       (let ((var (match-string 1 assignment))
  81             (ref (match-string 2 assignment)))
  82         (cons (intern var)
  83               ((lambda (val)
  84                  (if (equal :ob-must-be-reference val)
  85                      (org-babel-ref-resolve-reference ref params)
  86                    val)) (org-babel-ref-literal ref))))))
  87
  88 (defun org-babel-ref-literal (ref)
  89   "Determine if the right side of a header argument variable
  90 assignment is a literal value or is a reference to some external
  91 resource.  REF should be a string of the right hand side of the
  92 assignment.  If REF is literal then return it's value, otherwise
  93 return nil."
  94   (let ((out (org-babel-read ref)))
  95     (if (equal out ref)
  96         (if (string-match "^\".+\"$" ref)
  97             (read ref)
  98           :ob-must-be-reference)
  99       out)))
 100
 101 (defvar org-babel-library-of-babel)
 102 (defun org-babel-ref-resolve-reference (ref &optional params)
 103   "Resolve the reference REF and return its value."
 104   (save-excursion
 105     (let ((case-fold-search t)
 106           type args new-refere new-referent result lob-info split-file split-ref
 107           index index-row index-col)
 108       ;; if ref is indexed grab the indices -- beware nested indicies
 109       (when (and (string-match "\\[\\(.+\\)\\]" ref)
 110                  (let ((str (substring ref 0 (match-beginning 0))))
 111                    (= (length (org-remove-if-not
 112                                (lambda (el) (equal ?( el)) (string-to-list "((eric))")))
 113                       (length (org-remove-if-not
 114                                (lambda (el) (equal ?) el)) (string-to-list "((eric))"))))))
 115         (setq index (match-string 1 ref))
 116         (setq ref (substring ref 0 (match-beginning 0))))
 117       ;; assign any arguments to pass to source block
 118       (when (string-match "^\\(.+?\\)\(\\(.*\\)\)$" ref)
 119         (setq new-refere (match-string 1 ref))
 120         (setq new-referent (match-string 2 ref))
 121         ;; (message "new-refere=%S, new-referent=%S" new-refere new-referent) ;; debugging
 122         (when (> (length new-refere) 0)
 123           (if (> (length new-referent) 0)
 124               (setq args (mapcar (lambda (ref) (cons :var ref))
 125                                  (org-babel-ref-split-args new-referent))))
 126           ;; (message "args=%S" args) ;; debugging
 127           (setq ref new-refere)))
 128       (when (string-match "^\\(.+\\):\\(.+\\)$" ref)
 129         (setq split-file (match-string 1 ref))
 130         (setq split-ref (match-string 2 ref))
 131         (find-file split-file) (setq ref split-ref))
 132       (save-restriction
 133         (widen)
 134         (goto-char (point-min))
 135         (if (let ((result_regexp (concat "^[ \t]*#\\+\\(TBLNAME\\|RESNAME\\|RESULTS\\):[ \t]*"
 136                                          (regexp-quote ref) "[ \t]*$"))
 137                   (regexp (concat org-babel-src-name-regexp
 138                                   (regexp-quote ref) "\\(\(.*\)\\)?" "[ \t]*$")))
 139               ;; goto ref in the current buffer
 140               (or (and (not args)
 141                        (or (re-search-forward result_regexp nil t)
 142                            (re-search-backward result_regexp nil t)))
 143                   (re-search-forward regexp nil t)
 144                   (re-search-backward regexp nil t)
 145                   ;; check the Library of Babel
 146                   (setq lob-info (cdr (assoc (intern ref) org-babel-library-of-babel)))))
 147             (unless lob-info (goto-char (match-beginning 0)))
 148           ;; ;; TODO: allow searching for names in other buffers
 149           ;; (setq id-loc (org-id-find ref 'marker)
 150           ;;       buffer (marker-buffer id-loc)
 151           ;;       loc (marker-position id-loc))
 152           ;; (move-marker id-loc nil)
 153           (error "reference '%s' not found in this buffer" ref))
 154         (if lob-info
 155             (setq type 'lob)
 156           (while (not (setq type (org-babel-ref-at-ref-p)))
 157             (forward-line 1)
 158             (beginning-of-line)
 159             (if (or (= (point) (point-min)) (= (point) (point-max)))
 160                 (error "reference not found"))))
 161         (setq params (org-babel-merge-params params args '((:results . "silent"))))
 162         (setq result
 163               (case type
 164                 ('results-line (org-babel-read-result))
 165                 ('table (org-babel-read-table))
 166                 ('file (org-babel-read-link))
 167                 ('source-block (org-babel-execute-src-block nil nil params))
 168                 ('lob (org-babel-execute-src-block nil lob-info params))))
 169         (if (symbolp result)
 170             (format "%S" result)
 171           (if (and index (listp result))
 172               (org-babel-ref-index-list index result)
 173             result))))))
 174
 175 (defun org-babel-ref-index-list (index lis)
 176   "Return the subset of LIS indexed by INDEX.  If INDEX is
 177 separated by ,s then each PORTION is assumed to index into the
 178 next deepest nesting or dimension.  A valid PORTION can consist
 179 of either an integer index, or two integers separated by a : in
 180 which case the entire range is returned."
 181   (if (string-match "^,?\\([^,]+\\)" index)
 182       (let ((length (length lis))
 183             (portion (match-string 1 index))
 184             (remainder (substring index (match-end 0))))
 185         (flet ((wrap (num) (if (< num 0) (+ length num) num))
 186                (open (lis) (if (and (listp lis) (= (length lis) 1)) (car lis) lis)))
 187           (open
 188            (mapcar
 189             (lambda (sub-lis) (org-babel-ref-index-list remainder sub-lis))
 190             (if (string-match "\\(\\([-[:digit:]]+\\):\\([-[:digit:]]+\\)\\|\*\\)"
 191                               portion)
 192                 (mapcar (lambda (n) (nth n lis))
 193                         (apply 'number-sequence
 194                                (if (match-string 2 portion)
 195                                    (list
 196                                     (wrap (string-to-number (match-string 2 portion)))
 197                                     (wrap (string-to-number (match-string 3 portion))))
 198                                  (list (wrap 0) (wrap -1)))))
 199               (list (nth (wrap (string-to-number portion)) lis)))))))
 200     lis))
 201
 202 (defun org-babel-ref-split-args (arg-string)
 203   "Split ARG-STRING into top-level arguments of balanced parenthesis."
 204   (let ((index 0) (depth 0) (buffer "") holder return)
 205     ;; crawl along string, splitting at any ","s which are on the top level
 206     (while (< index (length arg-string))
 207       (setq holder (substring arg-string index (+ 1 index)))
 208       (setq buffer (concat buffer holder))
 209       (setq index (+ 1 index))
 210       (cond
 211        ((string= holder ",")
 212         (when (= depth 0)
 213           (setq return (reverse (cons (substring buffer 0 -1) return)))
 214           (setq buffer "")))
 215        ((or (string= holder "(") (string= holder "[")) (setq depth (+ depth 1)))
 216        ((or (string= holder ")") (string= holder "]")) (setq depth (- depth 1)))))
 217     (mapcar #'org-babel-trim (reverse (cons buffer return)))))
 218
 219 (defvar org-bracket-link-regexp)
 220 (defun org-babel-ref-at-ref-p ()
 221   "Return the type of reference located at point or nil if none
 222 of the supported reference types are found.  Supported reference
 223 types are tables and source blocks."
 224   (cond ((org-at-table-p) 'table)
 225         ((looking-at "^[ \t]*#\\+BEGIN_SRC") 'source-block)
 226         ((looking-at org-bracket-link-regexp) 'file)
 227         ((looking-at org-babel-result-regexp) 'results-line)))
 228
 229 (provide 'ob-ref)
 230
 231 ;; arch-tag: ace4a4f4-ea38-4dac-8fe6-6f52fcc43b6d
 232
 233 ;;; ob-ref.el ends here