ol-elisp-symbol.el (5476B)
1 ;;; ol-elisp-symbol.el --- Links to Emacs-lisp symbols 2 ;; 3 ;; Copyright 2007-2021 Free Software Foundation, Inc. 4 ;; 5 ;; Author: Bastien Guerry <bzg@gnu.org> 6 ;; Version: 0.2 7 ;; Keywords: org, remember, lisp 8 ;; Homepage: https://git.sr.ht/~bzg/org-contrib 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 <https://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 'ol-elisp-symbol) 78 (require 'ol) 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 (symbol arg) 86 (org-link-open-as-file symbol arg)) 87 88 (defun org-elisp-symbol-store-link () 89 "Store a link to an emacs-lisp elisp-symbol." 90 (when (eq major-mode 'emacs-lisp-mode) 91 (save-excursion 92 (or (looking-at "^(") (beginning-of-defun)) 93 (looking-at "^(\\([a-z]+\\) \\([^)\n ]+\\) ?\n?[ \t]*\\(?:(\\(.*\\))\\)?") 94 (let* ((end (save-excursion 95 (save-match-data 96 (end-of-defun) (point)))) 97 (def (match-string 1)) 98 (name (match-string 2)) 99 (sym-name (intern-soft name)) 100 (stype (cond ((commandp sym-name) "Command") 101 ((functionp sym-name) "Function") 102 ((user-variable-p sym-name) "User variable") 103 ((string= def "defvar") "Variable") 104 ((string= def "defmacro") "Macro") 105 ((string= def "defun") "Function or command") 106 (t "Symbol"))) 107 (args (if (match-string 3) 108 (mapconcat (lambda (a) (unless (string-match "^&" a) a)) 109 (split-string (match-string 3)) " ") 110 "no arg")) 111 (docstring (cond ((functionp sym-name) 112 (or (documentation sym-name) 113 "[no documentation]")) 114 ((string-match "[Vv]ariable" stype) 115 (documentation-property sym-name 116 'variable-documentation)) 117 (t "no documentation"))) 118 (doc (and (string-match "^\\([^\n]+\\)$" docstring) 119 (match-string 1 docstring))) 120 (fixme (save-excursion 121 (beginning-of-defun) (end-of-defun) 122 (if (re-search-forward "^;+ ?FIXME[ :]*\\(.*\\)$" end t) 123 (match-string 1) "nothing to fix"))) 124 (comment (save-excursion 125 (beginning-of-defun) (end-of-defun) 126 (if (re-search-forward "^;;+ ?\\(.*\\)$" end t) 127 (match-string 1) "no comment"))) 128 keys keys-desc link description) 129 (if (equal stype "Command") 130 (setq keys (where-is-internal sym-name) 131 keys-desc 132 (if keys (mapconcat 'key-description keys " ") "none"))) 133 (setq link (concat "file:" (abbreviate-file-name buffer-file-name) 134 "::" def " " name)) 135 (setq description (concat stype ": " name)) 136 (org-store-link-props 137 :type "elisp-symbol" 138 :link link 139 :description description 140 :def def 141 :name name 142 :stype stype 143 :args args 144 :keys keys-desc 145 :docstring docstring 146 :doc doc 147 :fixme fixme 148 :comment comment))))) 149 150 (provide 'org-elisp-symbol) 151 152 153 ;;;;########################################################################## 154 ;;;; User Options, Variables 155 ;;;;########################################################################## 156 157 ;;; ol-elisp-symbol.el ends here