org-elisp-symbol.el 5.5 KB

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