contrib/babel/lisp/org-babel-ref.el

   1 ;;; org-babel-ref.el --- org-babel functions for referencing external data
   2
   3 ;; Copyright (C) 2009 Eric Schulte, Dan Davison
   4
   5 ;; Author: Eric Schulte, Dan Davison
   6 ;; Keywords: literate programming, reproducible research
   7 ;; Homepage: http://orgmode.org
   8 ;; Version: 0.01
   9
  10 ;;; License:
  11
  12 ;; This program 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, or (at your option)
  15 ;; any later version.
  16 ;;
  17 ;; This program 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; see the file COPYING.  If not, write to the
  24 ;; Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
  25 ;; Boston, MA 02110-1301, USA.
  26
  27 ;;; Commentary:
  28
  29 ;; Functions for referencing data from the header arguments of a
  30 ;; org-babel block.  The syntax of such a reference should be
  31 ;;
  32 ;;   #+VAR: variable-name=file:resource-id
  33 ;;
  34 ;; - variable-name :: the name of the variable to which the value
  35 ;;                    will be assigned
  36 ;;
  37 ;; - file :: path to the file containing the resource, or omitted if
  38 ;;           resource is in the current file
  39 ;;
  40 ;; - resource-id :: the id or name of the resource
  41 ;;
  42 ;; So an example of a simple src block referencing table data in the
  43 ;; same file would be
  44 ;;
  45 ;;  #+TBLNAME: sandbox
  46 ;;  | 1 |       2 | 3 |
  47 ;;  | 4 | org-babel | 6 |
  48 ;;
  49 ;;  #+begin_src emacs-lisp :var table=sandbox
  50 ;;  (message table)
  51 ;;  #+end_src
  52 ;;
  53
  54 ;;; Code:
  55 (require 'org-babel)
  56
  57 (defun org-babel-ref-variables (params)
  58   "Takes a parameter alist, and return an alist of variable
  59 names, and the emacs-lisp representation of the related value."
  60   (let ((assignments
  61          (delq nil (mapcar (lambda (pair) (if (eq (car pair) :var) (cdr pair))) params)))
  62         (other-params (assq-delete-all :var params)))
  63     (mapcar (lambda (assignment) (org-babel-ref-parse assignment other-params)) assignments)))
  64
  65 (defun org-babel-ref-parse (assignment params)
  66   "Parse a variable ASSIGNMENT in a header argument.  If the
  67 right hand side of the assignment has a literal value return that
  68 value, otherwise interpret as a reference to an external resource
  69 and find it's value using `org-babel-ref-resolve-reference'.
  70 Return a list with two elements.  The first element of the list
  71 will be the name of the variable, and the second will be an
  72 emacs-lisp representation of the value of the variable."
  73   (if (string-match
  74        "[ \f\t\n\r\v]*\\(.+?\\)[ \f\t\n\r\v]*=[ \f\t\n\r\v]*\\(.+\\)[ \f\t\n\r\v]*" assignment)
  75       (let ((var (match-string 1 assignment))
  76             (ref (match-string 2 assignment)))
  77         (cons (intern var)
  78               (or (org-babel-ref-literal ref)
  79                   (org-babel-ref-resolve-reference ref params))))))
  80
  81 (defun org-babel-ref-literal (ref)
  82   "Determine if the right side of a header argument variable
  83 assignment is a literal value or is a reference to some external
  84 resource.  If REF is literal then return it's value, otherwise
  85 return nil."
  86   (let ((out (org-babel-read ref)))
  87     (if (equal out ref)
  88         (if (string-match "^\".+\"$" ref)
  89             (read ref))
  90       out)))
  91
  92 (defun org-babel-ref-resolve-reference (ref params)
  93   "Resolve the reference and return its value"
  94   (save-excursion
  95     (let ((case-fold-search t)
  96           type args new-refere new-referent result lob-info)
  97       ;; assign any arguments to pass to source block
  98       (when (string-match "^\\(.+?\\)\(\\(.*\\)\)$" ref)
  99         (setq new-refere (match-string 1 ref))
 100         (setq new-referent (match-string 2 ref))
 101         ;; (message "new-refere=%S, new-referent=%S" new-refere new-referent) ;; debugging
 102         (when (> (length new-refere) 0)
 103           (if (> (length new-referent) 0)
 104               (setq args (mapcar (lambda (ref) (cons :var ref))
 105                                  (org-babel-ref-split-args new-referent))))
 106           ;; (message "args=%S" args) ;; debugging
 107           (setq ref new-refere)))
 108       (when (string-match "\\(.+\\):\\(.+\\)" ref)
 109         (find-file (match-string 1 ref))
 110         (setf ref (match-string 2 ref)))
 111       (goto-char (point-min))
 112       (if (let ((result_regexp (concat "^#\\+\\(TBL\\|RES\\)NAME:[ \t]*"
 113                                        (regexp-quote ref) "[ \t]*$"))
 114                 (regexp (concat "^#\\+SRCNAME:[ \t]*"
 115                                 (regexp-quote ref) "\\(\(.*\)\\)?" "[ \t]*$")))
 116             ;; goto ref in the current buffer
 117             (or (and (not args)
 118                      (or (re-search-forward result_regexp nil t)
 119                          (re-search-forward result_regexp nil t)))
 120                 (re-search-forward regexp nil t)
 121                 (re-search-backward regexp nil t)
 122                 ;; check the Library of Babel
 123                 (setq lob-info (cdr (assoc (intern ref) org-babel-library-of-babel)))))
 124           (unless lob-info (goto-char (match-beginning 0)))
 125         ;; ;; TODO: allow searching for names in other buffers
 126         ;; (setq id-loc (org-id-find ref 'marker)
 127         ;;       buffer (marker-buffer id-loc)
 128         ;;       loc (marker-position id-loc))
 129         ;; (move-marker id-loc nil)
 130         (progn (message (format "reference '%s' not found in this buffer" ref))
 131                (error (format "reference '%s' not found in this buffer" ref))))
 132       (if lob-info
 133           (setq type 'lob)
 134         (while (not (setq type (org-babel-ref-at-ref-p)))
 135           (forward-line 1)
 136           (beginning-of-line)
 137           (if (or (= (point) (point-min)) (= (point) (point-max)))
 138               (error "reference not found"))))
 139       (setq params (org-babel-merge-params params args))
 140       (setq result
 141             (case type
 142               ('results-line (org-babel-read-result))
 143               ('table (org-babel-read-table))
 144               ('source-block (org-babel-execute-src-block t nil params))
 145               ('lob (org-babel-execute-src-block t lob-info params))))
 146       (if (symbolp result) (format "%S" result) result))))
 147
 148 (defun org-babel-ref-split-args (arg-string)
 149   "Split ARG-STRING into top-level arguments of balanced parenthesis."
 150   (let ((index 0) (depth 0) (buffer "") holder return)
 151     ;; crawl along string, splitting at any ","s which are on the top level
 152     (while (< index (length arg-string))
 153       (setq holder (substring arg-string index (+ 1 index)))
 154       (setq buffer (concat buffer holder))
 155       (setq index (+ 1 index))
 156       (cond
 157        ((string= holder ",")
 158         (when (= depth 0)
 159           (setq return (reverse (cons (substring buffer 0 -1) return)))
 160           (setq buffer "")))
 161        ((string= holder "(") (setq depth (+ depth 1)))
 162        ((string= holder ")") (setq depth (- depth 1)))))
 163     (mapcar #'org-babel-trim (reverse (cons buffer return)))))
 164
 165 (defun org-babel-ref-at-ref-p ()
 166   "Return the type of reference located at point or nil if none
 167 of the supported reference types are found.  Supported reference
 168 types are tables and source blocks."
 169   (cond ((org-at-table-p) 'table)
 170         ((looking-at "^#\\+BEGIN_SRC") 'source-block)
 171         ((looking-at "^#\\+RESNAME:") 'results-line)))
 172
 173 (provide 'org-babel-ref)
 174 ;;; org-babel-ref.el ends here