contrib/lisp/org-elisp-symbol.el

   1 ;;; org-elisp-symbol.el --- Org links to emacs-lisp symbols
   2 ;;
   3 ;; Copyright 2007-2017 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-link-set-parameters "elisp-symbol"
  82                          :follow #'org-elisp-symbol-open
  83                          :store #'org-elisp-symbol-store-link)
  84
  85 (defun org-elisp-symbol-open (path)
  86   "Visit the emacs-lisp elisp-symbol at PATH."
  87   (let* ((search (when (string-match "::\\(.+\\)\\'" path)
  88                    (match-string 1 path)))
  89          (path (substring path 0 (match-beginning 0))))
  90     (org-open-file path t nil search)))
  91
  92 (defun org-elisp-symbol-store-link ()
  93   "Store a link to an emacs-lisp elisp-symbol."
  94   (when (eq major-mode 'emacs-lisp-mode)
  95     (save-excursion
  96       (or (looking-at "^(") (beginning-of-defun))
  97       (looking-at "^(\\([a-z]+\\) \\([^)\n ]+\\) ?\n?[ \t]*\\(?:(\\(.*\\))\\)?")
  98       (let* ((end (save-excursion
  99                     (save-match-data
 100                       (end-of-defun) (point))))
 101              (def (match-string 1))
 102              (name (match-string 2))
 103              (sym-name (intern-soft name))
 104              (stype (cond ((commandp sym-name) "Command")
 105                           ((functionp sym-name) "Function")
 106                           ((user-variable-p sym-name) "User variable")
 107                           ((string= def "defvar") "Variable")
 108                           ((string= def "defmacro") "Macro")
 109                           ((string= def "defun") "Function or command")
 110                           (t "Symbol")))
 111              (args (if (match-string 3)
 112                        (mapconcat (lambda (a) (unless (string-match "^&" a) a))
 113                                   (split-string (match-string 3)) " ")
 114                      "no arg"))
 115              (docstring (cond ((functionp sym-name)
 116                                (or (documentation sym-name)
 117                                    "[no documentation]"))
 118                               ((string-match "[Vv]ariable" stype)
 119                                (documentation-property sym-name
 120                                                        'variable-documentation))
 121                               (t "no documentation")))
 122              (doc (and (string-match "^\\([^\n]+\\)$" docstring)
 123                        (match-string 1 docstring)))
 124              (fixme (save-excursion
 125                       (beginning-of-defun) (end-of-defun)
 126                       (if (re-search-forward "^;+ ?FIXME[ :]*\\(.*\\)$" end t)
 127                           (match-string 1) "nothing to fix")))
 128              (comment (save-excursion
 129                         (beginning-of-defun) (end-of-defun)
 130                         (if (re-search-forward "^;;+ ?\\(.*\\)$" end t)
 131                             (match-string 1) "no comment")))
 132              keys keys-desc link description)
 133         (if (equal stype "Command")
 134             (setq keys (where-is-internal sym-name)
 135                   keys-desc
 136                   (if keys (mapconcat 'key-description keys " ") "none")))
 137         (setq link (concat "file:" (abbreviate-file-name buffer-file-name)
 138                            "::" def " " name))
 139         (setq description (concat stype ": " name))
 140         (org-store-link-props
 141          :type "elisp-symbol"
 142          :link link
 143          :description description
 144          :def def
 145          :name name
 146          :stype stype
 147          :args args
 148          :keys keys-desc
 149          :docstring docstring
 150          :doc doc
 151          :fixme fixme
 152          :comment comment)))))
 153
 154 (provide 'org-elisp-symbol)
 155
 156 \f
 157 ;;;;##########################################################################
 158 ;;;;  User Options, Variables
 159 ;;;;##########################################################################
 160
 161 ;;; org-elisp-symbol.el ends here