org-elisp-symbol.el 5.5 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162
  1. ;;; org-elisp-symbol.el --- Org links to emacs-lisp symbols
  2. ;;
  3. ;; Copyright 2007-2018 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. ;;; Code:
  75. (provide 'org-elisp-symbol)
  76. (require 'org)
  77. (org-link-set-parameters "elisp-symbol"
  78. :follow #'org-elisp-symbol-open
  79. :store #'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