org-elisp-symbol.el 5.6 KB

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