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