code.delx.au - gnu-emacs/blob - lisp/emacs-lisp/autoload.el

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