1 ;;; check-declare.el --- Check declare-function statements
3 ;; Copyright (C) 2007 Free Software Foundation, Inc.
5 ;; Author: Glenn Morris <rgm@gnu.org>
6 ;; Keywords: lisp, tools, maint
8 ;; This file is part of GNU Emacs.
10 ;; GNU Emacs is free software; you can redistribute it and/or modify
11 ;; it under the terms of the GNU General Public License as published by
12 ;; the Free Software Foundation; either version 3, or (at your option)
15 ;; GNU Emacs is distributed in the hope that it will be useful,
16 ;; but WITHOUT ANY WARRANTY; without even the implied warranty of
17 ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
18 ;; GNU General Public License for more details.
20 ;; You should have received a copy of the GNU General Public License
21 ;; along with GNU Emacs; see the file COPYING. If not, write to the
22 ;; Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
23 ;; Boston, MA 02110-1301, USA.
27 ;; The byte-compiler often warns about undefined functions that you
28 ;; know will actually be defined when it matters. The `declare-function'
29 ;; statement allows you to suppress these warnings. This package
30 ;; checks that all such statements in a file or directory are accurate.
31 ;; The entry points are `check-declare-file' and `check-declare-directory'.
33 ;; For more information, see Info node `elisp(Declaring Functions)'.
39 (defconst check-declare-warning-buffer
"*Check Declarations Warnings*"
40 "Name of buffer used to display any `check-declare' warnings.")
42 (defun check-declare-locate (file basefile
)
43 "Return the full path of FILE.
44 Expands files with a \".c\" extension relative to the Emacs
45 \"src/\" directory. Otherwise, `locate-library' searches for FILE.
46 If that fails, expands FILE relative to BASEFILE's directory part.
47 The returned file might not exist. If FILE has an \"ext:\" prefix, so does
49 (let ((ext (string-match "^ext:" file
))
52 (setq file
(substring file
4)))
54 (if (string-equal "c" (file-name-extension file
))
55 (expand-file-name file
(expand-file-name "src" source-directory
))
56 (if (setq tfile
(locate-library (file-name-nondirectory file
)))
59 (replace-regexp-in-string "\\.elc\\'" ".el" tfile
))
60 (if (and (not (file-exists-p tfile
))
61 (file-exists-p (concat tfile
".gz")))
64 (setq tfile
(expand-file-name file
65 (file-name-directory basefile
)))
66 (if (or (file-exists-p tfile
)
67 (string-match "\\.el\\'" tfile
))
69 (concat tfile
".el")))))
70 (if ext
(concat "ext:" file
)
73 (defun check-declare-scan (file)
74 "Scan FILE for `declare-function' calls.
75 Return a list with elements of the form (FNFILE FN ARGLIST FILEONLY),
76 where only the first two elements need be present. This claims that FNFILE
77 defines FN, with ARGLIST. FILEONLY non-nil means only check that FNFILE
78 exists, not that it defines FN. This is for function definitions that we
79 don't know how to recognize (e.g. some macros)."
80 (let ((m (format "Scanning %s..." file
))
81 alist fnfile fn arglist fileonly
)
84 (insert-file-contents file
)
85 (while (re-search-forward
86 "^[ \t]*(declare-function[ \t]+\\(\\S-+\\)[ \t]+\
87 \"\\(\\S-+\\)\"" nil t
)
88 (setq fn
(match-string 1)
89 fnfile
(match-string 2)
90 fnfile
(check-declare-locate fnfile
(expand-file-name file
))
92 (skip-chars-forward " \t\n")
93 ;; Use `t' to distinguish no arglist
94 ;; specified from an empty one.
95 (if (looking-at "\\((\\|nil\\|t\\)")
96 (read (current-buffer))
99 (skip-chars-forward " \t\n")
100 (if (looking-at "\\(t\\|'\\sw+\\)")
102 alist
(cons (list fnfile fn arglist fileonly
) alist
))))
106 (defun check-declare-errmsg (errlist &optional full
)
107 "Return a string with the number of errors in ERRLIST, if any.
108 Normally just counts the number of elements in ERRLIST.
109 With optional argument FULL, sums the number of elements in each element."
111 (let ((l (length errlist
)))
116 (format "%d problem%s found" l
(if (= l
1) "" "s")))
119 (autoload 'byte-compile-arglist-signature
"bytecomp")
121 (defun check-declare-verify (fnfile fnlist
)
122 "Check that FNFILE contains function definitions matching FNLIST.
123 Each element of FNLIST has the form (FILE FN ARGLIST FILEONLY), where
124 only the first two elements need be present. This means FILE claimed FN
125 was defined in FNFILE with the specified ARGLIST. FILEONLY non-nil means
126 to only check that FNFILE exists, not that it actually defines FN.
128 Returns nil if all claims are found to be true, otherwise a list
129 of errors with elements of the form \(FILE FN TYPE), where TYPE
130 is a string giving details of the error."
131 (let ((m (format "Checking %s..." fnfile
))
132 (cflag (string-equal "c" (file-name-extension fnfile
)))
133 (ext (string-match "^ext:" fnfile
))
134 re fn sig siglist arglist type errlist minargs maxargs
)
137 (setq fnfile
(substring fnfile
4)))
138 (if (file-exists-p fnfile
)
140 (insert-file-contents fnfile
)
141 ;; defsubst's don't _have_ to be known at compile time.
142 (setq re
(format (if cflag
143 "^[ \t]*\\(DEFUN\\)[ \t]*([ \t]*\"%s\""
144 "^[ \t]*(\\(fset[ \t]+'\\|def\\(?:un\\|subst\\|\
145 ine-\\(?:derived\\|generic\\|\\(?:global\\(?:ized\\)?-\\)?minor\\)-mode\
146 \\|\\(?:ine-obsolete-function-\\)?alias[ \t]+'\\)\\)\
147 \[ \t]*%s\\([ \t;]+\\|$\\)")
148 (regexp-opt (mapcar 'cadr fnlist
) t
)))
149 (while (re-search-forward re nil t
)
150 (skip-chars-forward " \t\n")
151 (setq fn
(match-string 2)
152 type
(match-string 1)
153 ;; (min . max) for a fixed number of arguments, or
154 ;; arglists with optional elements.
155 ;; (min) for arglists with &rest.
156 ;; sig = 'err means we could not find an arglist.
159 (when (re-search-forward "," nil t
3)
160 (skip-chars-forward " \t\n")
161 ;; Assuming minargs and maxargs on same line.
162 (when (looking-at "\\([0-9]+\\)[ \t]*,[ \t]*\
163 \\([0-9]+\\|MANY\\|UNEVALLED\\)")
164 (setq minargs
(string-to-number
166 maxargs
(match-string 2))
167 (cons minargs
(unless (string-match "[^0-9]"
173 "\\`define-\\(derived\\|generic\\)-mode\\'"
177 "\\`define\\(-global\\(ized\\)?\\)?-minor-mode\\'"
182 "\\`define-obsolete-function-alias\\>"
185 ;; Can't easily check arguments in these cases.
186 ((string-match "\\`\\(defalias\\|fset\\)\\>" type
)
188 ((looking-at "\\((\\|nil\\)")
189 (byte-compile-arglist-signature
190 (read (current-buffer))))
193 ;; alist of functions and arglist signatures.
194 siglist
(cons (cons fn sig
) siglist
)))))
196 (setq arglist
(nth 2 e
)
200 (if (not (setq sig
(assoc (cadr e
) siglist
)))
201 (unless (nth 3 e
) ; fileonly
202 "function not found")
204 (cond ((eq sig
'obsolete
) ; check even when no arglist specified
206 ;; arglist t means no arglist specified, as
207 ;; opposed to an empty arglist.
209 ((eq sig t
) nil
) ; eg defalias - can't check arguments
211 "arglist not found") ; internal error
212 ((not (equal (byte-compile-arglist-signature
215 "arglist mismatch")))))
217 (setq errlist
(cons (list (car e
) (cadr e
) type
) errlist
))))
219 (if (or re
(not ext
))
220 (check-declare-errmsg errlist
)
223 "skipping external file")))
226 (defun check-declare-sort (alist)
227 "Sort a list with elements FILE (FNFILE ...).
228 Returned list has elements FNFILE (FILE ...)."
229 (let (file fnfile rest sort a
)
235 (if (setq a
(assoc fnfile sort
))
236 (setcdr a
(append (cdr a
) (list (cons file rest
))))
237 (setq sort
(cons (list fnfile
(cons file rest
)) sort
)))))
240 (defun check-declare-warn (file fn fnfile type
)
241 "Warn that FILE made a false claim about FN in FNFILE.
242 TYPE is a string giving the nature of the error. Warning is displayed in
243 `check-declare-warning-buffer'."
244 (display-warning 'check-declare
245 (format "%s said `%s' was defined in %s: %s"
246 (file-name-nondirectory file
) fn
247 (file-name-nondirectory fnfile
)
249 nil check-declare-warning-buffer
))
251 (defun check-declare-files (&rest files
)
252 "Check veracity of all `declare-function' statements in FILES.
253 Return a list of any errors found."
254 (let (alist err errlist
)
256 (setq alist
(cons (cons file
(check-declare-scan file
)) alist
)))
257 ;; Sort so that things are ordered by the files supposed to
258 ;; contain the defuns.
259 (dolist (e (check-declare-sort alist
))
260 (if (setq err
(check-declare-verify (car e
) (cdr e
)))
261 (setq errlist
(cons (cons (car e
) err
) errlist
))))
262 (if (get-buffer check-declare-warning-buffer
)
263 (kill-buffer check-declare-warning-buffer
))
264 ;; Sort back again so that errors are ordered by the files
265 ;; containing the declare-function statements.
266 (dolist (e (check-declare-sort errlist
))
268 (check-declare-warn (car e
) (cadr f
) (car f
) (nth 2 f
))))
272 (defun check-declare-file (file)
273 "Check veracity of all `declare-function' statements in FILE.
274 See `check-declare-directory' for more information."
275 (interactive "fFile to check: ")
276 (or (file-exists-p file
)
277 (error "File `%s' not found" file
))
278 (let ((m (format "Checking %s..." file
))
281 (setq errlist
(check-declare-files file
))
282 (message "%s%s" m
(check-declare-errmsg errlist
))
286 (defun check-declare-directory (root)
287 "Check veracity of all `declare-function' statements under directory ROOT.
288 Returns non-nil if any false statements are found. For this to
289 work correctly, the statements must adhere to the format
290 described in the documentation of `declare-function'."
291 (interactive "DDirectory to check: ")
292 (or (file-directory-p (setq root
(expand-file-name root
)))
293 (error "Directory `%s' not found" root
))
294 (let ((m "Checking `declare-function' statements...")
295 (m2 "Finding files with declarations...")
299 (setq files
(process-lines "find" root
"-name" "*.el"
301 "^[ ]*(declare-function" "{}" ";"))
302 (message "%s%d found" m2
(length files
))
304 (setq errlist
(apply 'check-declare-files files
))
305 (message "%s%s" m
(check-declare-errmsg errlist t
))
308 (provide 'check-declare
)
310 ;; arch-tag: a4d6cdc4-deb7-4502-b327-0e4ef3d82d96
311 ;;; check-declare.el ends here.