(autoload-ensure-default-file, autoload-insert-section-header)
[bpt/emacs.git] / lisp / emacs-lisp / autoload.el
1 ;;; autoload.el --- maintain autoloads in loaddefs.el
2
3 ;; Copyright (C) 1991, 1992, 1993, 1994, 1995, 1996, 1997, 2001
4 ;; Free Software Foundation, Inc.
5
6 ;; Author: Roland McGrath <roland@gnu.org>
7 ;; Keywords: maint
8
9 ;; This file is part of GNU Emacs.
10
11 ;; GNU Emacs is free software; you can redistribute it and/or modify
12 ;; it under the terms of the GNU General Public License as published by
13 ;; the Free Software Foundation; either version 2, or (at your option)
14 ;; any later version.
15
16 ;; GNU Emacs is distributed in the hope that it will be useful,
17 ;; but WITHOUT ANY WARRANTY; without even the implied warranty of
18 ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
19 ;; GNU General Public License for more details.
20
21 ;; You should have received a copy of the GNU General Public License
22 ;; along with GNU Emacs; see the file COPYING. If not, write to the
23 ;; Free Software Foundation, Inc., 59 Temple Place - Suite 330,
24 ;; Boston, MA 02111-1307, USA.
25
26 ;;; Commentary:
27
28 ;; This code helps GNU Emacs maintainers keep the loaddefs.el file up to
29 ;; date. It interprets magic cookies of the form ";;;###autoload" in
30 ;; lisp source files in various useful ways. To learn more, read the
31 ;; source; if you're going to use this, you'd better be able to.
32
33 ;;; Code:
34
35 (defvar generated-autoload-file "loaddefs.el"
36 "*File \\[update-file-autoloads] puts autoloads into.
37 A `.el' file can set this in its local variables section to make its
38 autoloads go somewhere else. The autoload file is assumed to contain a
39 trailer starting with a FormFeed character.")
40
41 (defconst generate-autoload-cookie ";;;###autoload"
42 "Magic comment indicating the following form should be autoloaded.
43 Used by \\[update-file-autoloads]. This string should be
44 meaningless to Lisp (e.g., a comment).
45
46 This string is used:
47
48 ;;;###autoload
49 \(defun function-to-be-autoloaded () ...)
50
51 If this string appears alone on a line, the following form will be
52 read and an autoload made for it. If there is further text on the line,
53 that text will be copied verbatim to `generated-autoload-file'.")
54
55 (defconst generate-autoload-section-header "\f\n;;;### "
56 "String that marks the form at the start of a new file's autoload section.")
57
58 (defconst generate-autoload-section-trailer "\n;;;***\n"
59 "String which indicates the end of the section of autoloads for a file.")
60
61 (defconst generate-autoload-section-continuation ";;;;;; "
62 "String to add on each continuation of the section header form.")
63
64 (defun make-autoload (form file)
65 "Turn FORM into an autoload or defvar for source file FILE.
66 Returns nil if FORM is not a special autoload form (i.e. a function definition
67 or macro definition or a defcustom)."
68 (let ((car (car-safe form)) expand)
69 (cond
70 ;; For complex cases, try again on the macro-expansion.
71 ((and (memq car '(easy-mmode-define-global-mode
72 easy-mmode-define-minor-mode define-minor-mode))
73 (setq expand (let ((load-file-name file)) (macroexpand form)))
74 (eq (car expand) 'progn)
75 (memq :autoload-end expand))
76 (let ((end (memq :autoload-end expand)))
77 ;; Cut-off anything after the :autoload-end marker.
78 (setcdr end nil)
79 (cons 'progn
80 (mapcar (lambda (form) (make-autoload form file))
81 (cdr expand)))))
82
83 ;; For special function-like operators, use the `autoload' function.
84 ((memq car '(defun define-skeleton defmacro define-derived-mode
85 define-generic-mode easy-mmode-define-minor-mode
86 easy-mmode-define-global-mode
87 define-minor-mode defun*))
88 (let* ((macrop (eq car 'defmacro))
89 (name (nth 1 form))
90 (body (nthcdr (get car 'doc-string-elt) form))
91 (doc (if (stringp (car body)) (pop body))))
92 ;; `define-generic-mode' quotes the name, so take care of that
93 (list 'autoload (if (listp name) name (list 'quote name)) file doc
94 (or (and (memq car '(define-skeleton define-derived-mode
95 define-generic-mode
96 easy-mmode-define-global-mode
97 easy-mmode-define-minor-mode
98 define-minor-mode)) t)
99 (eq (car-safe (car body)) 'interactive))
100 (if macrop (list 'quote 'macro) nil))))
101
102 ;; Convert defcustom to a simpler (and less space-consuming) defvar,
103 ;; but add some extra stuff if it uses :require.
104 ((eq car 'defcustom)
105 (let ((varname (car-safe (cdr-safe form)))
106 (init (car-safe (cdr-safe (cdr-safe form))))
107 (doc (car-safe (cdr-safe (cdr-safe (cdr-safe form)))))
108 (rest (cdr-safe (cdr-safe (cdr-safe (cdr-safe form))))))
109 (if (not (plist-get rest :require))
110 `(defvar ,varname ,init ,doc)
111 `(progn
112 (defvar ,varname ,init ,doc)
113 (custom-add-to-group ,(plist-get rest :group)
114 ',varname 'custom-variable)
115 (custom-add-load ',varname
116 ,(plist-get rest :require))))))
117
118 ;; nil here indicates that this is not a special autoload form.
119 (t nil))))
120
121 ;;; Forms which have doc-strings which should be printed specially.
122 ;;; A doc-string-elt property of ELT says that (nth ELT FORM) is
123 ;;; the doc-string in FORM.
124 ;;;
125 ;;; There used to be the following note here:
126 ;;; ;;; Note: defconst and defvar should NOT be marked in this way.
127 ;;; ;;; We don't want to produce defconsts and defvars that
128 ;;; ;;; make-docfile can grok, because then it would grok them twice,
129 ;;; ;;; once in foo.el (where they are given with ;;;###autoload) and
130 ;;; ;;; once in loaddefs.el.
131 ;;;
132 ;;; Counter-note: Yes, they should be marked in this way.
133 ;;; make-docfile only processes those files that are loaded into the
134 ;;; dumped Emacs, and those files should never have anything
135 ;;; autoloaded here. The above-feared problem only occurs with files
136 ;;; which have autoloaded entries *and* are processed by make-docfile;
137 ;;; there should be no such files.
138
139 (put 'autoload 'doc-string-elt 3)
140 (put 'defun 'doc-string-elt 3)
141 (put 'defun* 'doc-string-elt 3)
142 (put 'defvar 'doc-string-elt 3)
143 (put 'defcustom 'doc-string-elt 3)
144 (put 'defconst 'doc-string-elt 3)
145 (put 'defmacro 'doc-string-elt 3)
146 (put 'defsubst 'doc-string-elt 3)
147 (put 'define-skeleton 'doc-string-elt 2)
148 (put 'define-derived-mode 'doc-string-elt 4)
149 (put 'easy-mmode-define-minor-mode 'doc-string-elt 2)
150 (put 'define-minor-mode 'doc-string-elt 2)
151 (put 'define-generic-mode 'doc-string-elt 7)
152 ;; defin-global-mode has no explicit docstring.
153 (put 'easy-mmode-define-global-mode 'doc-string-elt 1000)
154
155
156 (defun autoload-trim-file-name (file)
157 ;; Returns a relative pathname of FILE
158 ;; starting from the directory that loaddefs.el is in.
159 ;; That is normally a directory in load-path,
160 ;; which means Emacs will be able to find FILE when it looks.
161 ;; Any extra directory names here would prevent finding the file.
162 (setq file (expand-file-name file))
163 (file-relative-name file
164 (file-name-directory generated-autoload-file)))
165
166 (defun autoload-read-section-header ()
167 "Read a section header form.
168 Since continuation lines have been marked as comments,
169 we must copy the text of the form and remove those comment
170 markers before we call `read'."
171 (save-match-data
172 (let ((beginning (point))
173 string)
174 (forward-line 1)
175 (while (looking-at generate-autoload-section-continuation)
176 (forward-line 1))
177 (setq string (buffer-substring beginning (point)))
178 (with-current-buffer (get-buffer-create " *autoload*")
179 (erase-buffer)
180 (insert string)
181 (goto-char (point-min))
182 (while (search-forward generate-autoload-section-continuation nil t)
183 (replace-match " "))
184 (goto-char (point-min))
185 (read (current-buffer))))))
186
187 ;; !! Requires OUTBUF to be bound !!
188 (defun autoload-print-form (form)
189 "Print FORM such that make-docfile will find the docstrings."
190 (cond
191 ;; If the form is a sequence, recurse.
192 ((eq (car form) 'progn) (mapcar 'autoload-print-form (cdr form)))
193 ;; Symbols at the toplevel are meaningless.
194 ((symbolp form) nil)
195 (t
196 (let ((doc-string-elt (get (car-safe form) 'doc-string-elt)))
197 (if (and doc-string-elt (stringp (nth doc-string-elt form)))
198 ;; We need to hack the printing because the
199 ;; doc-string must be printed specially for
200 ;; make-docfile (sigh).
201 (let* ((p (nthcdr (1- doc-string-elt) form))
202 (elt (cdr p)))
203 (setcdr p nil)
204 (princ "\n(" outbuf)
205 (let ((print-escape-newlines t)
206 (print-escape-nonascii t))
207 (mapcar (lambda (elt)
208 (prin1 elt outbuf)
209 (princ " " outbuf))
210 form))
211 (princ "\"\\\n" outbuf)
212 (let ((begin (with-current-buffer outbuf (point))))
213 (princ (substring (prin1-to-string (car elt)) 1)
214 outbuf)
215 ;; Insert a backslash before each ( that
216 ;; appears at the beginning of a line in
217 ;; the doc string.
218 (with-current-buffer outbuf
219 (save-excursion
220 (while (search-backward "\n(" begin t)
221 (forward-char 1)
222 (insert "\\"))))
223 (if (null (cdr elt))
224 (princ ")" outbuf)
225 (princ " " outbuf)
226 (princ (substring (prin1-to-string (cdr elt)) 1)
227 outbuf))
228 (terpri outbuf)))
229 (let ((print-escape-newlines t)
230 (print-escape-nonascii t))
231 (print form outbuf)))))))
232
233 (defun autoload-ensure-default-file (file)
234 "Make sure that the autoload file FILE exists and if not create it."
235 (unless (file-exists-p file)
236 (write-region
237 (concat ";;; " (file-name-nondirectory file)
238 " --- automatically extracted autoloads\n"
239 ";;\n"
240 ";;; Code:\n\n"
241 "\f\n;; Local Variables:\n"
242 ";; version-control: never\n"
243 ";; no-byte-compile: t\n"
244 ";; no-update-autoloads: t\n"
245 ";; End:\n"
246 ";;; " (file-name-nondirectory file)
247 "ends here\n")
248 nil file))
249 file)
250
251 (defun autoload-insert-section-header (outbuf autoloads load-name file time)
252 "Insert the section-header line,
253 which lists the file name and which functions are in it, etc."
254 (insert generate-autoload-section-header)
255 (prin1 (list 'autoloads autoloads load-name
256 (if (stringp file) (autoload-trim-file-name file) file)
257 time)
258 outbuf)
259 (terpri outbuf)
260 ;; Break that line at spaces, to avoid very long lines.
261 ;; Make each sub-line into a comment.
262 (with-current-buffer outbuf
263 (save-excursion
264 (forward-line -1)
265 (while (not (eolp))
266 (move-to-column 64)
267 (skip-chars-forward "^ \n")
268 (or (eolp)
269 (insert "\n" generate-autoload-section-continuation))))))
270
271 (defun generate-file-autoloads (file)
272 "Insert at point a loaddefs autoload section for FILE.
273 autoloads are generated for defuns and defmacros in FILE
274 marked by `generate-autoload-cookie' (which see).
275 If FILE is being visited in a buffer, the contents of the buffer
276 are used."
277 (interactive "fGenerate autoloads for file: ")
278 (let ((outbuf (current-buffer))
279 (autoloads-done '())
280 (load-name (let ((name (file-name-nondirectory file)))
281 (if (string-match "\\.elc?$" name)
282 (substring name 0 (match-beginning 0))
283 name)))
284 (print-length nil)
285 (print-readably t) ; This does something in Lucid Emacs.
286 (float-output-format nil)
287 (done-any nil)
288 (visited (get-file-buffer file))
289 output-end)
290
291 ;; If the autoload section we create here uses an absolute
292 ;; pathname for FILE in its header, and then Emacs is installed
293 ;; under a different path on another system,
294 ;; `update-autoloads-here' won't be able to find the files to be
295 ;; autoloaded. So, if FILE is in the same directory or a
296 ;; subdirectory of the current buffer's directory, we'll make it
297 ;; relative to the current buffer's directory.
298 (setq file (expand-file-name file))
299 (let* ((source-truename (file-truename file))
300 (dir-truename (file-name-as-directory
301 (file-truename default-directory)))
302 (len (length dir-truename)))
303 (if (and (< len (length source-truename))
304 (string= dir-truename (substring source-truename 0 len)))
305 (setq file (substring source-truename len))))
306
307 (message "Generating autoloads for %s..." file)
308 (save-excursion
309 (unwind-protect
310 (progn
311 (if visited
312 (set-buffer visited)
313 ;; It is faster to avoid visiting the file.
314 (set-buffer (get-buffer-create " *generate-autoload-file*"))
315 (kill-all-local-variables)
316 (erase-buffer)
317 (setq buffer-undo-list t
318 buffer-read-only nil)
319 (emacs-lisp-mode)
320 (insert-file-contents file nil))
321 (save-excursion
322 (save-restriction
323 (widen)
324 (goto-char (point-min))
325 (while (not (eobp))
326 (skip-chars-forward " \t\n\f")
327 (cond
328 ((looking-at (regexp-quote generate-autoload-cookie))
329 (search-forward generate-autoload-cookie)
330 (skip-chars-forward " \t")
331 (setq done-any t)
332 (if (eolp)
333 ;; Read the next form and make an autoload.
334 (let* ((form (prog1 (read (current-buffer))
335 (or (bolp) (forward-line 1))))
336 (autoload (make-autoload form load-name)))
337 (if autoload
338 (setq autoloads-done (cons (nth 1 form)
339 autoloads-done))
340 (setq autoload form))
341 (autoload-print-form autoload))
342
343 ;; Copy the rest of the line to the output.
344 (princ (buffer-substring
345 (progn
346 ;; Back up over whitespace, to preserve it.
347 (skip-chars-backward " \f\t")
348 (if (= (char-after (1+ (point))) ? )
349 ;; Eat one space.
350 (forward-char 1))
351 (point))
352 (progn (forward-line 1) (point)))
353 outbuf)))
354 ((looking-at ";")
355 ;; Don't read the comment.
356 (forward-line 1))
357 (t
358 (forward-sexp 1)
359 (forward-line 1)))))))
360 (or visited
361 ;; We created this buffer, so we should kill it.
362 (kill-buffer (current-buffer)))
363 (set-buffer outbuf)
364 (setq output-end (point-marker))))
365 (if done-any
366 (progn
367 ;; Insert the section-header line
368 ;; which lists the file name and which functions are in it, etc.
369 (autoload-insert-section-header outbuf autoloads-done load-name file
370 (nth 5 (file-attributes file)))
371 (insert ";;; Generated autoloads from "
372 (autoload-trim-file-name file) "\n")
373 (goto-char output-end)
374 (insert generate-autoload-section-trailer)))
375 (message "Generating autoloads for %s...done" file)))
376 \f
377 ;;;###autoload
378 (defun update-file-autoloads (file)
379 "Update the autoloads for FILE in `generated-autoload-file'
380 \(which FILE might bind in its local variables).
381 Return FILE if there was no autoload cookie in it."
382 (interactive "fUpdate autoloads for file: ")
383 (let ((load-name (let ((name (file-name-nondirectory file)))
384 (if (string-match "\\.elc?$" name)
385 (substring name 0 (match-beginning 0))
386 name)))
387 (found nil)
388 (existing-buffer (get-file-buffer file))
389 (no-autoloads nil))
390 (save-excursion
391 ;; We want to get a value for generated-autoload-file from
392 ;; the local variables section if it's there.
393 (if existing-buffer
394 (set-buffer existing-buffer))
395 ;; We must read/write the file without any code conversion,
396 ;; but still decode EOLs.
397 (let ((coding-system-for-read 'raw-text))
398 (set-buffer (find-file-noselect
399 (autoload-ensure-default-file
400 (expand-file-name generated-autoload-file
401 (expand-file-name "lisp"
402 source-directory)))))
403 ;; This is to make generated-autoload-file have Unix EOLs, so
404 ;; that it is portable to all platforms.
405 (setq buffer-file-coding-system 'raw-text-unix))
406 (or (> (buffer-size) 0)
407 (error "Autoloads file %s does not exist" buffer-file-name))
408 (or (file-writable-p buffer-file-name)
409 (error "Autoloads file %s is not writable" buffer-file-name))
410 (save-excursion
411 (save-restriction
412 (widen)
413 (goto-char (point-min))
414 ;; Look for the section for LOAD-NAME.
415 (while (and (not found)
416 (search-forward generate-autoload-section-header nil t))
417 (let ((form (autoload-read-section-header)))
418 (cond ((string= (nth 2 form) load-name)
419 ;; We found the section for this file.
420 ;; Check if it is up to date.
421 (let ((begin (match-beginning 0))
422 (last-time (nth 4 form))
423 (file-time (nth 5 (file-attributes file))))
424 (if (and (or (null existing-buffer)
425 (not (buffer-modified-p existing-buffer)))
426 (listp last-time) (= (length last-time) 2)
427 (not (autoload-before-p last-time file-time)))
428 (progn
429 (if (interactive-p)
430 (message "\
431 Autoload section for %s is up to date."
432 file))
433 (setq found 'up-to-date))
434 (search-forward generate-autoload-section-trailer)
435 (delete-region begin (point))
436 (setq found t))))
437 ((string< load-name (nth 2 form))
438 ;; We've come to a section alphabetically later than
439 ;; LOAD-NAME. We assume the file is in order and so
440 ;; there must be no section for LOAD-NAME. We will
441 ;; insert one before the section here.
442 (goto-char (match-beginning 0))
443 (setq found 'new)))))
444 (or found
445 (progn
446 (setq found 'new)
447 ;; No later sections in the file. Put before the last page.
448 (goto-char (point-max))
449 (search-backward "\f" nil t)))
450 (or (eq found 'up-to-date)
451 (and (eq found 'new)
452 ;; Check that FILE has any cookies before generating a
453 ;; new section for it.
454 (save-excursion
455 (if existing-buffer
456 (set-buffer existing-buffer)
457 ;; It is faster to avoid visiting the file.
458 (set-buffer (get-buffer-create " *autoload-file*"))
459 (kill-all-local-variables)
460 (erase-buffer)
461 (setq buffer-undo-list t
462 buffer-read-only nil)
463 (emacs-lisp-mode)
464 (insert-file-contents file nil))
465 (save-excursion
466 (save-restriction
467 (widen)
468 (goto-char (point-min))
469 (prog1
470 (if (re-search-forward
471 (concat "^" (regexp-quote
472 generate-autoload-cookie))
473 nil t)
474 nil
475 (if (interactive-p)
476 (message "%s has no autoloads" file))
477 (setq no-autoloads t)
478 t)
479 (or existing-buffer
480 (kill-buffer (current-buffer))))))))
481 (generate-file-autoloads file))))
482 (and (interactive-p)
483 (buffer-modified-p)
484 (save-buffer))
485
486 (if no-autoloads file))))
487
488 (defun autoload-before-p (time1 time2)
489 (or (< (car time1) (car time2))
490 (and (= (car time1) (car time2))
491 (< (nth 1 time1) (nth 1 time2)))))
492
493 (defun autoload-remove-section (begin)
494 (goto-char begin)
495 (search-forward generate-autoload-section-trailer)
496 (delete-region begin (point)))
497
498 ;;;###autoload
499 (defun update-autoloads-from-directories (&rest dirs)
500 "\
501 Update loaddefs.el with all the current autoloads from DIRS, and no old ones.
502 This uses `update-file-autoloads' (which see) do its work."
503 (interactive "DUpdate autoloads from directory: ")
504 (let* ((files (apply 'nconc
505 (mapcar (lambda (dir)
506 (directory-files (expand-file-name dir)
507 ;; FIXME: add .gz etc...
508 t "^[^=.].*\\.el\\'"))
509 dirs)))
510 (this-time (current-time))
511 (no-autoloads nil) ;files with no autoload cookies.
512 (autoloads-file
513 (expand-file-name generated-autoload-file
514 (expand-file-name "lisp" source-directory)))
515 (top-dir (file-name-directory autoloads-file)))
516
517 (with-current-buffer
518 (find-file-noselect (autoload-ensure-default-file autoloads-file))
519 (save-excursion
520
521 ;; Canonicalize file names and remove the autoload file itself.
522 (setq files (delete (autoload-trim-file-name buffer-file-name)
523 (mapcar 'autoload-trim-file-name files)))
524
525 (goto-char (point-min))
526 (while (search-forward generate-autoload-section-header nil t)
527 (let* ((form (autoload-read-section-header))
528 (file (nth 3 form)))
529 (cond ((and (consp file) (stringp (car file)))
530 ;; This is a list of files that have no autoload cookies.
531 ;; There shouldn't be more than one such entry.
532 ;; Remove the obsolete section.
533 (autoload-remove-section (match-beginning 0))
534 (let ((last-time (nth 4 form)))
535 (dolist (file file)
536 (let ((file-time (nth 5 (file-attributes file))))
537 (when (and file-time
538 (not (autoload-before-p last-time
539 file-time)))
540 ;; file unchanged
541 (push file no-autoloads)
542 (setq files (delete file files)))))))
543 ((not (stringp file)))
544 ((not (file-exists-p (expand-file-name file top-dir)))
545 ;; Remove the obsolete section.
546 (autoload-remove-section (match-beginning 0)))
547 ((equal (nth 4 form) (nth 5 (file-attributes file)))
548 ;; File hasn't changed.
549 nil)
550 (t
551 (update-file-autoloads file)))
552 (setq files (delete file files)))))
553 ;; Elements remaining in FILES have no existing autoload sections yet.
554 (setq no-autoloads
555 (append no-autoloads
556 (delq nil (mapcar 'update-file-autoloads files))))
557 (when no-autoloads
558 ;; Add the `no-autoloads' section.
559 (goto-char (point-max))
560 (search-backward "\f" nil t)
561 (autoload-insert-section-header
562 (current-buffer) nil nil no-autoloads this-time)
563 (insert generate-autoload-section-trailer))
564
565 (save-buffer))))
566
567 ;;;###autoload
568 (defun batch-update-autoloads ()
569 "Update loaddefs.el autoloads in batch mode.
570 Calls `update-autoloads-from-directories' on the command line arguments."
571 (apply 'update-autoloads-from-directories command-line-args-left)
572 (setq command-line-args-left nil))
573
574 (provide 'autoload)
575
576 ;;; autoload.el ends here