contrib/lisp/org-elisp-symbol.el

   1 ;;; org-elisp-symbol.el --- Org links to emacs-lisp symbols
   2 ;;
   3 ;; Copyright 2007-2014 Free Software Foundation, Inc.
   4 ;;
   5 ;; Author: Bastien Guerry
   6 ;; Version: 0.2
   7 ;; Keywords: org, remember, lisp
   8 ;; URL: http://www.cognition.ens.fr/~guerry/u/org-elisp-symbol.el
   9 ;;
  10 ;; This file is not part of GNU Emacs.
  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.  If not, see <http://www.gnu.org/licenses/>.
  24 ;;
  25 ;;; Commentary:
  26 ;;
  27 ;; Org-mode already lets you store/insert links to emacs-lisp files,
  28 ;; just like any other file.  This package lets you precisely link to
  29 ;; any emacs-lisp symbol and access useful information about the symbol.
  30 ;;
  31 ;; Here is the list of available properties when linking from a elisp-symbol:
  32 ;;
  33 ;; :name        The symbol's name.
  34 ;; :stype       The symbol's type (commandp, function, etc.)
  35 ;; :def         The function used to set the symbol's value (defun, etc.)
  36 ;; :keys        The keys associated with the command.
  37 ;; :args        The arguments of the function.
  38 ;; :docstring   The docstring of the symbol.
  39 ;; :doc         The first line of the dostring.
  40 ;; :comment     A comment line just above the sexp, if any.
  41 ;; :fixme       A FIXME comment line just above the sexp, if any.
  42 ;;
  43 ;; Let's say we have a defun like this one:
  44 ;;
  45 ;; ;; FIXME update docstring
  46 ;; (defun org-export-latex-lists ()
  47 ;;   "Convert lists to LaTeX."
  48 ;;   (goto-char (point-min))
  49 ;;   (while (re-search-forward org-export-latex-list-beginning-re nil t)
  50 ;;     (beginning-of-line)
  51 ;;     (insert (org-list-to-latex (org-list-parse-list t)) "\n")))
  52 ;;
  53 ;; And a remember template like:
  54 ;;
  55 ;; (setq org-remember-templates
  56 ;;   '((?s "* DEBUG `%:name' (%:args)\n\n%?\n\nFixme: %:fixme\n  \
  57 ;;          Doc: \"%:doc\"\n\n%a")))
  58 ;;
  59 ;; Then M-x `org-remember' on this sexp will produce this buffer:
  60 ;;
  61 ;; =====================================================================
  62 ;; * DEBUG `org-export-latex-lists' ()
  63 ;;
  64 ;; <== point
  65 ;;
  66 ;; Fixme: update the docstring
  67 ;; Doc: "Convert lists to LaTeX."
  68 ;;
  69 ;; [[file:~/path/file.el::defun%20my-func][Function: my-func]]
  70 ;; =====================================================================
  71 ;;
  72 ;; Put this file into your load-path and the following into your ~/.emacs:
  73 ;;   (require 'org-elisp-symbol)
  74
  75 ;;; Code:
  76
  77 (provide 'org-elisp-symbol)
  78
  79 (require 'org)
  80
  81 (org-add-link-type "elisp-symbol" 'org-elisp-symbol-open)
  82 (add-hook 'org-store-link-functions 'org-elisp-symbol-store-link)
  83
  84 (defun org-elisp-symbol-open (path)
  85   "Visit the emacs-lisp elisp-symbol at PATH."
  86   (let* ((search (when (string-match "::\\(.+\\)\\'" path)
  87                    (match-string 1 path)))
  88          (path (substring path 0 (match-beginning 0))))
  89     (org-open-file path t nil search)))
  90
  91 (defun org-elisp-symbol-store-link ()
  92   "Store a link to an emacs-lisp elisp-symbol."
  93   (when (eq major-mode 'emacs-lisp-mode)
  94     (save-excursion
  95       (or (looking-at "^(") (beginning-of-defun))
  96       (looking-at "^(\\([a-z]+\\) \\([^)\n ]+\\) ?\n?[ \t]*\\(?:(\\(.*\\))\\)?")
  97       (let* ((end (save-excursion
  98                     (save-match-data
  99                       (end-of-defun) (point))))
 100              (def (match-string 1))
 101              (name (match-string 2))
 102              (sym-name (intern-soft name))
 103              (stype (cond ((commandp sym-name) "Command")
 104                           ((functionp sym-name) "Function")
 105                           ((user-variable-p sym-name) "User variable")
 106                           ((string= def "defvar") "Variable")
 107                           ((string= def "defmacro") "Macro")
 108                           ((string= def "defun") "Function or command")
 109                           (t "Symbol")))
 110              (args (if (match-string 3)
 111                        (mapconcat (lambda (a) (unless (string-match "^&" a) a))
 112                                   (split-string (match-string 3)) " ")
 113                      "no arg"))
 114              (docstring (cond ((functionp sym-name)
 115                                (or (documentation sym-name)
 116                                    "[no documentation]"))
 117                               ((string-match "[Vv]ariable" stype)
 118                                (documentation-property sym-name
 119                                                        'variable-documentation))
 120                               (t "no documentation")))
 121              (doc (and (string-match "^\\([^\n]+\\)$" docstring)
 122                        (match-string 1 docstring)))
 123              (fixme (save-excursion
 124                       (beginning-of-defun) (end-of-defun)
 125                       (if (re-search-forward "^;+ ?FIXME[ :]*\\(.*\\)$" end t)
 126                           (match-string 1) "nothing to fix")))
 127              (comment (save-excursion
 128                         (beginning-of-defun) (end-of-defun)
 129                         (if (re-search-forward "^;;+ ?\\(.*\\)$" end t)
 130                             (match-string 1) "no comment")))
 131              keys keys-desc link description)
 132         (if (equal stype "Command")
 133             (setq keys (where-is-internal sym-name)
 134                   keys-desc
 135                   (if keys (mapconcat 'key-description keys " ") "none")))
 136         (setq link (concat "file:" (abbreviate-file-name buffer-file-name)
 137                            "::" def " " name))
 138         (setq description (concat stype ": " name))
 139         (org-store-link-props
 140          :type "elisp-symbol"
 141          :link link
 142          :description description
 143          :def def
 144          :name name
 145          :stype stype
 146          :args args
 147          :keys keys-desc
 148          :docstring docstring
 149          :doc doc
 150          :fixme fixme
 151          :comment comment)))))
 152
 153 (provide 'org-elisp-symbol)
 154
 155 \f
 156 ;;;;##########################################################################
 157 ;;;;  User Options, Variables
 158 ;;;;##########################################################################
 159
 160 ;;; org-elisp-symbol.el ends here