code.delx.au - gnu-emacs/blob - lisp/progmodes/etags.el

   1 ;;; etags.el --- etags facility for Emacs
   2 ;; Copyright (C) 1985, 1986, 1988, 1989, 1992, 1993, 1994, 1995, 1996, 1998
   3 ;;      Free Software Foundation, Inc.
   4
   5 ;; Author: Roland McGrath <roland@gnu.ai.mit.edu>
   6 ;; Keywords: tools
   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 ;;; Code:
  26
  27 (require 'ring)
  28
  29 ;;;###autoload
  30 (defvar tags-file-name nil
  31   "*File name of tags table.
  32 To switch to a new tags table, setting this variable is sufficient.
  33 If you set this variable, do not also set `tags-table-list'.
  34 Use the `etags' program to make a tags table file.")
  35 ;; Make M-x set-variable tags-file-name like M-x visit-tags-table.
  36 ;;;###autoload (put 'tags-file-name 'variable-interactive "fVisit tags table: ")
  37
  38 (defgroup etags nil "Tags tables"
  39   :group 'tools)
  40
  41 ;;;###autoload
  42 ;; Use `visit-tags-table-buffer' to cycle through tags tables in this list.
  43 (defcustom tags-table-list nil
  44   "*List of file names of tags tables to search.
  45 An element that is a directory means the file \"TAGS\" in that directory.
  46 To switch to a new list of tags tables, setting this variable is sufficient.
  47 If you set this variable, do not also set `tags-file-name'.
  48 Use the `etags' program to make a tags table file."
  49   :group 'etags
  50   :type '(repeat file))
  51
  52 ;;;###autoload
  53 (defcustom tags-add-tables 'ask-user
  54   "*Control whether to add a new tags table to the current list.
  55 t means do; nil means don't (always start a new list).
  56 Any other value means ask the user whether to add a new tags table
  57 to the current list (as opposed to starting a new list)."
  58   :group 'etags
  59   :type '(choice (const :tag "Do" t)
  60                  (const :tag "Don't" nil)
  61                  (const :tag "Ask" ask-user)))
  62
  63 (defcustom tags-revert-without-query nil
  64   "*Non-nil means reread a TAGS table without querying, if it has changed."
  65   :group 'etags
  66   :type 'boolean)
  67
  68 (defvar tags-table-computed-list nil
  69   "List of tags tables to search, computed from `tags-table-list'.
  70 This includes tables implicitly included by other tables.  The list is not
  71 always complete: the included tables of a table are not known until that
  72 table is read into core.  An element that is `t' is a placeholder
  73 indicating that the preceding element is a table that has not been read
  74 into core and might contain included tables to search.
  75 See `tags-table-check-computed-list'.")
  76
  77 (defvar tags-table-computed-list-for nil
  78   "Value of `tags-table-list' that `tags-table-computed-list' corresponds to.
  79 If `tags-table-list' changes, `tags-table-computed-list' is thrown away and
  80 recomputed; see `tags-table-check-computed-list'.")
  81
  82 (defvar tags-table-list-pointer nil
  83   "Pointer into `tags-table-computed-list' for the current state of searching.
  84 Use `visit-tags-table-buffer' to cycle through tags tables in this list.")
  85
  86 (defvar tags-table-list-started-at nil
  87   "Pointer into `tags-table-computed-list', where the current search started.")
  88
  89 (defvar tags-table-set-list nil
  90   "List of sets of tags table which have been used together in the past.
  91 Each element is a list of strings which are file names.")
  92
  93 ;;;###autoload
  94 (defcustom find-tag-hook nil
  95   "*Hook to be run by \\[find-tag] after finding a tag.  See `run-hooks'.
  96 The value in the buffer in which \\[find-tag] is done is used,
  97 not the value in the buffer \\[find-tag] goes to."
  98   :group 'etags
  99   :type 'hook)
 100
 101 ;;;###autoload
 102 (defcustom find-tag-default-function nil
 103   "*A function of no arguments used by \\[find-tag] to pick a default tag.
 104 If nil, and the symbol that is the value of `major-mode'
 105 has a `find-tag-default-function' property (see `put'), that is used.
 106 Otherwise, `find-tag-default' is used."
 107   :group 'etags
 108   :type 'function)
 109
 110 (defcustom find-tag-marker-ring-length 16
 111   "*Length of marker rings `find-tag-marker-ring' and `tags-location-ring'."
 112   :group 'etags
 113   :type 'integer
 114   :version "20.3")
 115
 116 (defvar find-tag-marker-ring (make-ring find-tag-marker-ring-length)
 117   "Ring of markers which are locations from which \\[find-tag] was invoked.")
 118
 119 (defvar default-tags-table-function nil
 120   "If non-nil, a function to choose a default tags file for a buffer.
 121 This function receives no arguments and should return the default
 122 tags table file to use for the current buffer.")
 123
 124 (defvar tags-location-ring (make-ring find-tag-marker-ring-length)
 125   "Ring of markers which are locations visited by \\[find-tag].
 126 Pop back to the last location with \\[negative-argument] \\[find-tag].")
 127 \f
 128 ;; Tags table state.
 129 ;; These variables are local in tags table buffers.
 130
 131 (defvar tags-table-files nil
 132   "List of file names covered by current tags table.
 133 nil means it has not yet been computed; use `tags-table-files' to do so.")
 134
 135 (defvar tags-completion-table nil
 136   "Alist of tag names defined in current tags table.")
 137
 138 (defvar tags-included-tables nil
 139   "List of tags tables included by the current tags table.")
 140
 141 (defvar next-file-list nil
 142   "List of files for \\[next-file] to process.")
 143 \f
 144 ;; Hooks for file formats.
 145
 146 (defvar tags-table-format-hooks '(etags-recognize-tags-table
 147                                   recognize-empty-tags-table)
 148   "List of functions to be called in a tags table buffer to identify the type of tags table.
 149 The functions are called in order, with no arguments,
 150 until one returns non-nil.  The function should make buffer-local bindings
 151 of the format-parsing tags function variables if successful.")
 152
 153 (defvar file-of-tag-function nil
 154   "Function to do the work of `file-of-tag' (which see).")
 155 (defvar tags-table-files-function nil
 156   "Function to do the work of `tags-table-files' (which see).")
 157 (defvar tags-completion-table-function nil
 158   "Function to build the tags-completion-table.")
 159 (defvar snarf-tag-function nil
 160   "Function to get info about a matched tag for `goto-tag-location-function'.")
 161 (defvar goto-tag-location-function nil
 162   "Function of to go to the location in the buffer specified by a tag.
 163 One argument, the tag info returned by `snarf-tag-function'.")
 164 (defvar find-tag-regexp-search-function nil
 165   "Search function passed to `find-tag-in-order' for finding a regexp tag.")
 166 (defvar find-tag-regexp-tag-order nil
 167   "Tag order passed to `find-tag-in-order' for finding a regexp tag.")
 168 (defvar find-tag-regexp-next-line-after-failure-p nil
 169   "Flag passed to `find-tag-in-order' for finding a regexp tag.")
 170 (defvar find-tag-search-function nil
 171   "Search function passed to `find-tag-in-order' for finding a tag.")
 172 (defvar find-tag-tag-order nil
 173   "Tag order passed to `find-tag-in-order' for finding a tag.")
 174 (defvar find-tag-next-line-after-failure-p nil
 175   "Flag passed to `find-tag-in-order' for finding a tag.")
 176 (defvar list-tags-function nil
 177   "Function to do the work of `list-tags' (which see).")
 178 (defvar tags-apropos-function nil
 179   "Function to do the work of `tags-apropos' (which see).")
 180 (defvar tags-included-tables-function nil
 181   "Function to do the work of `tags-included-tables' (which see).")
 182 (defvar verify-tags-table-function nil
 183   "Function to return t iff current buffer contains valid tags file.")
 184 \f
 185 ;; Initialize the tags table in the current buffer.
 186 ;; Returns non-nil iff it is a valid tags table.  On
 187 ;; non-nil return, the tags table state variable are
 188 ;; made buffer-local and initialized to nil.
 189 (defun initialize-new-tags-table ()
 190   (set (make-local-variable 'tags-table-files) nil)
 191   (set (make-local-variable 'tags-completion-table) nil)
 192   (set (make-local-variable 'tags-included-tables) nil)
 193   (setq find-tag-marker-ring (make-ring find-tag-marker-ring-length))
 194   (setq tags-location-ring (make-ring find-tag-marker-ring-length))
 195   ;; Value is t if we have found a valid tags table buffer.
 196   (let ((hooks tags-table-format-hooks))
 197     (while (and hooks
 198                 (not (funcall (car hooks))))
 199       (setq hooks (cdr hooks)))
 200     hooks))
 201
 202 ;;;###autoload
 203 (defun visit-tags-table (file &optional local)
 204   "Tell tags commands to use tags table file FILE.
 205 FILE should be the name of a file created with the `etags' program.
 206 A directory name is ok too; it means file TAGS in that directory.
 207
 208 Normally \\[visit-tags-table] sets the global value of `tags-file-name'.
 209 With a prefix arg, set the buffer-local value instead.
 210 When you find a tag with \\[find-tag], the buffer it finds the tag
 211 in is given a local value of this variable which is the name of the tags
 212 file the tag was in."
 213   (interactive (list (read-file-name "Visit tags table: (default TAGS) "
 214                                      default-directory
 215                                      (expand-file-name "TAGS"
 216                                                        default-directory)
 217                                      t)
 218                      current-prefix-arg))
 219   (or (stringp file) (signal 'wrong-type-argument (list 'stringp file)))
 220   ;; Bind tags-file-name so we can control below whether the local or
 221   ;; global value gets set.  Calling visit-tags-table-buffer will
 222   ;; initialize a buffer for the file and set tags-file-name to the
 223   ;; Calling visit-tags-table-buffer with tags-file-name set to FILE will
 224   ;; initialize a buffer for FILE and set tags-file-name to the
 225   ;; fully-expanded name.
 226   (let ((tags-file-name file))
 227     (save-excursion
 228       (or (visit-tags-table-buffer file)
 229           (signal 'file-error (list "Visiting tags table"
 230                                     "file does not exist"
 231                                     file)))
 232       ;; Set FILE to the expanded name.
 233       (setq file tags-file-name)))
 234   (if local
 235       ;; Set the local value of tags-file-name.
 236       (set (make-local-variable 'tags-file-name) file)
 237     ;; Set the global value of tags-file-name.
 238     (setq-default tags-file-name file)))
 239
 240 (defun tags-table-check-computed-list ()
 241   "Compute `tags-table-computed-list' from `tags-table-list' if necessary."
 242   (let ((expanded-list (mapcar 'tags-expand-table-name tags-table-list)))
 243     (or (equal tags-table-computed-list-for expanded-list)
 244         ;; The list (or default-directory) has changed since last computed.
 245         (let* ((compute-for (mapcar 'copy-sequence expanded-list))
 246                (tables (copy-sequence compute-for)) ;Mutated in the loop.
 247                (computed nil)
 248                table-buffer)
 249
 250           (while tables
 251             (setq computed (cons (car tables) computed)
 252                   table-buffer (get-file-buffer (car tables)))
 253             (if (and table-buffer
 254                      ;; There is a buffer visiting the file.  Now make sure
 255                      ;; it is initialized as a tag table buffer.
 256                      (save-excursion
 257                        (tags-verify-table (buffer-file-name table-buffer))))
 258                 (save-excursion
 259                   (set-buffer table-buffer)
 260                   (if (tags-included-tables)
 261                       ;; Insert the included tables into the list we
 262                       ;; are processing.
 263                       (setcdr tables (nconc (mapcar 'tags-expand-table-name
 264                                                     (tags-included-tables))
 265                                             (cdr tables)))))
 266               ;; This table is not in core yet.  Insert a placeholder
 267               ;; saying we must read it into core to check for included
 268               ;; tables before searching the next table in the list.
 269               (setq computed (cons t computed)))
 270             (setq tables (cdr tables)))
 271
 272           ;; Record the tags-table-list value (and the context of the
 273           ;; current directory) we computed from.
 274           (setq tags-table-computed-list-for compute-for
 275                 tags-table-computed-list (nreverse computed))))))
 276
 277 ;; Extend `tags-table-computed-list' to remove the first `t' placeholder.
 278 ;; An element of the list that is `t' is a placeholder indicating that the
 279 ;; preceding element is a table that has not been read into core and might
 280 ;; contain included tables to search.  On return, the first placeholder
 281 ;; element will be gone and the element before it read into core and its
 282 ;; included tables inserted into the list.
 283 (defun tags-table-extend-computed-list ()
 284   (let ((list tags-table-computed-list))
 285     (while (not (eq (nth 1 list) t))
 286       (setq list (cdr list)))
 287     (save-excursion
 288       (if (tags-verify-table (car list))
 289           ;; We are now in the buffer visiting (car LIST).  Extract its
 290           ;; list of included tables and insert it into the computed list.
 291           (let ((tables (tags-included-tables))
 292                 (computed nil)
 293                 table-buffer)
 294             (while tables
 295               (setq computed (cons (car tables) computed)
 296                     table-buffer (get-file-buffer (car tables)))
 297               (if table-buffer
 298                   (save-excursion
 299                     (set-buffer table-buffer)
 300                     (if (tags-included-tables)
 301                         ;; Insert the included tables into the list we
 302                         ;; are processing.
 303                         (setcdr tables (append (tags-included-tables)
 304                                                tables))))
 305                 ;; This table is not in core yet.  Insert a placeholder
 306                 ;; saying we must read it into core to check for included
 307                 ;; tables before searching the next table in the list.
 308                 (setq computed (cons t computed)))
 309               (setq tables (cdr tables)))
 310             (setq computed (nreverse computed))
 311             ;; COMPUTED now contains the list of included tables (and
 312             ;; tables included by them, etc.).  Now splice this into the
 313             ;; current list.
 314             (setcdr list (nconc computed (cdr (cdr list)))))
 315         ;; It was not a valid table, so just remove the following placeholder.
 316         (setcdr list (cdr (cdr list)))))))
 317
 318 ;; Expand tags table name FILE into a complete file name.
 319 (defun tags-expand-table-name (file)
 320   (setq file (expand-file-name file))
 321   (if (file-directory-p file)
 322       (expand-file-name "TAGS" file)
 323     file))
 324
 325 ;; Like member, but comparison is done after tags-expand-table-name on both
 326 ;; sides and elements of LIST that are t are skipped.
 327 (defun tags-table-list-member (file list)
 328   (setq file (tags-expand-table-name file))
 329   (while (and list
 330               (or (eq (car list) t)
 331                   (not (string= file (tags-expand-table-name (car list))))))
 332     (setq list (cdr list)))
 333   list)
 334
 335 (defun tags-verify-table (file)
 336   "Read FILE into a buffer and verify that it is a valid tags table.
 337 Sets the current buffer to one visiting FILE (if it exists).
 338 Returns non-nil iff it is a valid table."
 339   (if (get-file-buffer file)
 340       ;; The file is already in a buffer.  Check for the visited file
 341       ;; having changed since we last used it.
 342       (let (win)
 343         (set-buffer (get-file-buffer file))
 344         (setq win (or verify-tags-table-function (initialize-new-tags-table)))
 345         (if (or (verify-visited-file-modtime (current-buffer))
 346                 ;; Decide whether to revert the file.
 347                 ;; revert-without-query can say to revert
 348                 ;; or the user can say to revert.
 349                 (not (or (let ((tail revert-without-query)
 350                                (found nil))
 351                            (while tail
 352                              (if (string-match (car tail) buffer-file-name)
 353                                  (setq found t))
 354                              (setq tail (cdr tail)))
 355                            found)
 356                          tags-revert-without-query
 357                          (yes-or-no-p
 358                           (format "Tags file %s has changed, read new contents? "
 359                                   file)))))
 360             (and verify-tags-table-function
 361                  (funcall verify-tags-table-function))
 362           (revert-buffer t t)
 363           (initialize-new-tags-table)))
 364     (and (file-exists-p file)
 365          (progn
 366            (set-buffer (find-file-noselect file))
 367            (or (string= file buffer-file-name)
 368                ;; find-file-noselect has changed the file name.
 369                ;; Propagate the change to tags-file-name and tags-table-list.
 370                (let ((tail (member file tags-table-list)))
 371                  (if tail
 372                      (setcar tail buffer-file-name))
 373                  (if (eq file tags-file-name)
 374                      (setq tags-file-name buffer-file-name))))
 375            (initialize-new-tags-table)))))
 376
 377 ;; Subroutine of visit-tags-table-buffer.  Search the current tags tables
 378 ;; for one that has tags for THIS-FILE (or that includes a table that
 379 ;; does).  Return the name of the first table table listing THIS-FILE; if
 380 ;; the table is one included by another table, it is the master table that
 381 ;; we return.  If CORE-ONLY is non-nil, check only tags tables that are
 382 ;; already in buffers--don't visit any new files.
 383 (defun tags-table-including (this-file core-only)
 384   (let ((tables tags-table-computed-list)
 385         (found nil))
 386     ;; Loop over the list, looking for a table containing tags for THIS-FILE.
 387     (while (and (not found)
 388                 tables)
 389
 390       (if core-only
 391           ;; Skip tables not in core.
 392           (while (eq (nth 1 tables) t)
 393             (setq tables (cdr (cdr tables))))
 394         (if (eq (nth 1 tables) t)
 395             ;; This table has not been read into core yet.  Read it in now.
 396             (tags-table-extend-computed-list)))
 397
 398       (if tables
 399           ;; Select the tags table buffer and get the file list up to date.
 400           (let ((tags-file-name (car tables)))
 401             (visit-tags-table-buffer 'same)
 402             (if (member this-file (mapcar 'expand-file-name
 403                                           (tags-table-files)))
 404                 ;; Found it.
 405                 (setq found tables))))
 406       (setq tables (cdr tables)))
 407     (if found
 408         ;; Now determine if the table we found was one included by another
 409         ;; table, not explicitly listed.  We do this by checking each
 410         ;; element of the computed list to see if it appears in the user's
 411         ;; explicit list; the last element we will check is FOUND itself.
 412         ;; Then we return the last one which did in fact appear in
 413         ;; tags-table-list.
 414         (let ((could-be nil)
 415               (elt tags-table-computed-list))
 416           (while (not (eq elt (cdr found)))
 417             (if (tags-table-list-member (car elt) tags-table-list)
 418                 ;; This table appears in the user's list, so it could be
 419                 ;; the one which includes the table we found.
 420                 (setq could-be (car elt)))
 421             (setq elt (cdr elt))
 422             (if (eq t (car elt))
 423                 (setq elt (cdr elt))))
 424           ;; The last element we found in the computed list before FOUND
 425           ;; that appears in the user's list will be the table that
 426           ;; included the one we found.
 427           could-be))))
 428
 429 ;; Subroutine of visit-tags-table-buffer.  Move tags-table-list-pointer
 430 ;; along and set tags-file-name.  Returns nil when out of tables.
 431 (defun tags-next-table ()
 432   ;; If there is a placeholder element next, compute the list to replace it.
 433   (while (eq (nth 1 tags-table-list-pointer) t)
 434     (tags-table-extend-computed-list))
 435
 436   ;; Go to the next table in the list.
 437   (setq tags-table-list-pointer (cdr tags-table-list-pointer))
 438   (or tags-table-list-pointer
 439       ;; Wrap around.
 440       (setq tags-table-list-pointer tags-table-computed-list))
 441
 442   (if (eq tags-table-list-pointer tags-table-list-started-at)
 443       ;; We have come full circle.  No more tables.
 444       (setq tags-table-list-pointer nil)
 445     ;; Set tags-file-name to the name from the list.  It is already expanded.
 446     (setq tags-file-name (car tags-table-list-pointer))))
 447
 448 (defun visit-tags-table-buffer (&optional cont)
 449   "Select the buffer containing the current tags table.
 450 If optional arg is a string, visit that file as a tags table.
 451 If optional arg is t, visit the next table in `tags-table-list'.
 452 If optional arg is the atom `same', don't look for a new table;
 453  just select the buffer visiting `tags-file-name'.
 454 If arg is nil or absent, choose a first buffer from information in
 455  `tags-file-name', `tags-table-list', `tags-table-list-pointer'.
 456 Returns t if it visits a tags table, or nil if there are no more in the list."
 457
 458   ;; Set tags-file-name to the tags table file we want to visit.
 459   (cond ((eq cont 'same)
 460          ;; Use the ambient value of tags-file-name.
 461          (or tags-file-name
 462              (error "%s"
 463                     (substitute-command-keys
 464                      (concat "No tags table in use; "
 465                              "use \\[visit-tags-table] to select one")))))
 466
 467         ((eq t cont)
 468          ;; Find the next table.
 469          (if (tags-next-table)
 470              ;; Skip over nonexistent files.
 471              (while (and (not (or (get-file-buffer tags-file-name)
 472                                   (file-exists-p tags-file-name)))
 473                          (tags-next-table)))))
 474
 475         (t
 476          ;; Pick a table out of our hat.
 477          (tags-table-check-computed-list) ;Get it up to date, we might use it.
 478          (setq tags-file-name
 479                (or
 480                 ;; If passed a string, use that.
 481                 (if (stringp cont)
 482                     (prog1 cont
 483                       (setq cont nil)))
 484                 ;; First, try a local variable.
 485                 (cdr (assq 'tags-file-name (buffer-local-variables)))
 486                 ;; Second, try a user-specified function to guess.
 487                 (and default-tags-table-function
 488                      (funcall default-tags-table-function))
 489                 ;; Third, look for a tags table that contains tags for the
 490                 ;; current buffer's file.  If one is found, the lists will
 491                 ;; be frobnicated, and CONT will be set non-nil so we don't
 492                 ;; do it below.
 493                 (and buffer-file-name
 494                      (or
 495                       ;; First check only tables already in buffers.
 496                       (tags-table-including buffer-file-name t)
 497                       ;; Since that didn't find any, now do the
 498                       ;; expensive version: reading new files.
 499                       (tags-table-including buffer-file-name nil)))
 500                 ;; Fourth, use the user variable tags-file-name, if it is
 501                 ;; not already in the current list.
 502                 (and tags-file-name
 503                      (not (tags-table-list-member tags-file-name
 504                                                   tags-table-computed-list))
 505                      tags-file-name)
 506                 ;; Fifth, use the user variable giving the table list.
 507                 ;; Find the first element of the list that actually exists.
 508                 (let ((list tags-table-list)
 509                       file)
 510                   (while (and list
 511                               (setq file (tags-expand-table-name (car list)))
 512                               (not (get-file-buffer file))
 513                               (not (file-exists-p file)))
 514                     (setq list (cdr list)))
 515                   (car list))
 516                 ;; Finally, prompt the user for a file name.
 517                 (expand-file-name
 518                  (read-file-name "Visit tags table: (default TAGS) "
 519                                  default-directory
 520                                  "TAGS"
 521                                  t))))))
 522
 523   ;; Expand the table name into a full file name.
 524   (setq tags-file-name (tags-expand-table-name tags-file-name))
 525
 526   (if (and (eq cont t)
 527            (null tags-table-list-pointer))
 528       ;; All out of tables.
 529       nil
 530
 531     ;; Verify that tags-file-name names a valid tags table.
 532     ;; Bind another variable with the value of tags-file-name
 533     ;; before we switch buffers, in case tags-file-name is buffer-local.
 534     (let ((curbuf (current-buffer))
 535           (local-tags-file-name tags-file-name))
 536       (if (tags-verify-table local-tags-file-name)
 537
 538           ;; We have a valid tags table.
 539           (progn
 540             ;; Bury the tags table buffer so it
 541             ;; doesn't get in the user's way.
 542             (bury-buffer (current-buffer))
 543
 544             ;; If this was a new table selection (CONT is nil), make
 545             ;; sure tags-table-list includes the chosen table, and
 546             ;; update the list pointer variables.
 547             (or cont
 548                 ;; Look in the list for the table we chose.
 549                 (let ((found (tags-table-list-member
 550                               local-tags-file-name
 551                               tags-table-computed-list)))
 552                   (if found
 553                       ;; There it is.  Just switch to it.
 554                       (setq tags-table-list-pointer found
 555                             tags-table-list-started-at found)
 556
 557                     ;; The table is not in the current set.
 558                     ;; Try to find it in another previously used set.
 559                     (let ((sets tags-table-set-list))
 560                       (while (and sets
 561                                   (not (tags-table-list-member
 562                                         local-tags-file-name
 563                                         (car sets))))
 564                         (setq sets (cdr sets)))
 565                       (if sets
 566                           ;; Found in some other set.  Switch to that set.
 567                           (progn
 568                             (or (memq tags-table-list tags-table-set-list)
 569                                 ;; Save the current list.
 570                                 (setq tags-table-set-list
 571                                       (cons tags-table-list
 572                                             tags-table-set-list)))
 573                             (setq tags-table-list (car sets)))
 574
 575                         ;; Not found in any existing set.
 576                         (if (and tags-table-list
 577                                  (or (eq t tags-add-tables)
 578                                      (and tags-add-tables
 579                                           (y-or-n-p
 580                                            (concat "Keep current list of "
 581                                                    "tags tables also? ")))))
 582                             ;; Add it to the current list.
 583                             (setq tags-table-list (cons local-tags-file-name
 584                                                         tags-table-list))
 585
 586                           ;; Make a fresh list, and store the old one.
 587                           (message "Starting a new list of tags tables")
 588                           (or (null tags-table-list)
 589                               (memq tags-table-list tags-table-set-list)
 590                               (setq tags-table-set-list
 591                                     (cons tags-table-list
 592                                           tags-table-set-list)))
 593                           (setq tags-table-list (list local-tags-file-name))))
 594
 595                       ;; Recompute tags-table-computed-list.
 596                       (tags-table-check-computed-list)
 597                       ;; Set the tags table list state variables to start
 598                       ;; over from tags-table-computed-list.
 599                       (setq tags-table-list-started-at tags-table-computed-list
 600                             tags-table-list-pointer
 601                             tags-table-computed-list)))))
 602
 603             ;; Return of t says the tags table is valid.
 604             t)
 605
 606         ;; The buffer was not valid.  Don't use it again.
 607         (set-buffer curbuf)
 608         (kill-local-variable 'tags-file-name)
 609         (if (eq local-tags-file-name tags-file-name)
 610             (setq tags-file-name nil))
 611         (error "File %s is not a valid tags table" local-tags-file-name)))))
 612
 613 (defun tags-reset-tags-tables ()
 614   "Reset tags state to cancel effect of any previous \\[visit-tags-table] or \\[find-tag]."
 615   (interactive)
 616   (setq tags-file-name nil
 617         tags-location-ring (progn
 618                              (mapcar (lambda (m)
 619                                        (set-marker m nil))
 620                                      tags-location-ring)
 621                              (make-ring find-tag-marker-ring-length))
 622         find-tag-marker-ring (progn
 623                                (mapcar (lambda (m)
 624                                          (set-marker m nil))
 625                                        find-tag-marker-ring)
 626                                (make-ring find-tag-marker-ring-length))
 627         tags-table-list nil
 628         tags-table-computed-list nil
 629         tags-table-computed-list-for nil
 630         tags-table-list-pointer nil
 631         tags-table-list-started-at nil
 632         tags-table-set-list nil))
 633 \f
 634 (defun file-of-tag ()
 635   "Return the file name of the file whose tags point is within.
 636 Assumes the tags table is the current buffer.
 637 File name returned is relative to tags table file's directory."
 638   (funcall file-of-tag-function))
 639
 640 ;;;###autoload
 641 (defun tags-table-files ()
 642   "Return a list of files in the current tags table.
 643 Assumes the tags table is the current buffer.  The file names are returned
 644 as they appeared in the `etags' command that created the table, usually
 645 without directory names."
 646   (or tags-table-files
 647       (setq tags-table-files
 648             (funcall tags-table-files-function))))
 649
 650 (defun tags-included-tables ()
 651   "Return a list of tags tables included by the current table.
 652 Assumes the tags table is the current buffer."
 653   (or tags-included-tables
 654       (setq tags-included-tables (funcall tags-included-tables-function))))
 655 \f
 656 ;; Build tags-completion-table on demand.  The single current tags table
 657 ;; and its included tags tables (and their included tables, etc.) have
 658 ;; their tags included in the completion table.
 659 (defun tags-completion-table ()
 660   (or tags-completion-table
 661       (condition-case ()
 662           (prog2
 663            (message "Making tags completion table for %s..." buffer-file-name)
 664            (let ((included (tags-included-tables))
 665                  (table (funcall tags-completion-table-function)))
 666              (save-excursion
 667                ;; Iterate over the list of included tables, and combine each
 668                ;; included table's completion obarray to the parent obarray.
 669                (while included
 670                  ;; Visit the buffer.
 671                  (let ((tags-file-name (car included)))
 672                    (visit-tags-table-buffer 'same))
 673                  ;; Recurse in that buffer to compute its completion table.
 674                  (if (tags-completion-table)
 675                      ;; Combine the tables.
 676                      (mapatoms (function
 677                                 (lambda (sym)
 678                                   (intern (symbol-name sym) table)))
 679                                tags-completion-table))
 680                  (setq included (cdr included))))
 681              (setq tags-completion-table table))
 682            (message "Making tags completion table for %s...done"
 683                     buffer-file-name))
 684         (quit (message "Tags completion table construction aborted.")
 685               (setq tags-completion-table nil)))))
 686
 687 ;; Completion function for tags.  Does normal try-completion,
 688 ;; but builds tags-completion-table on demand.
 689 (defun tags-complete-tag (string predicate what)
 690   (save-excursion
 691     ;; If we need to ask for the tag table, allow that.
 692     (let ((enable-recursive-minibuffers t))
 693       (visit-tags-table-buffer))
 694     (if (eq what t)
 695         (all-completions string (tags-completion-table) predicate)
 696       (try-completion string (tags-completion-table) predicate))))
 697 \f
 698 ;; Return a default tag to search for, based on the text at point.
 699 (defun find-tag-default ()
 700   (save-excursion
 701     (while (looking-at "\\sw\\|\\s_")
 702       (forward-char 1))
 703     (if (or (re-search-backward "\\sw\\|\\s_"
 704                                 (save-excursion (beginning-of-line) (point))
 705                                 t)
 706             (re-search-forward "\\(\\sw\\|\\s_\\)+"
 707                                (save-excursion (end-of-line) (point))
 708                                t))
 709         (progn (goto-char (match-end 0))
 710                (buffer-substring (point)
 711                                  (progn (forward-sexp -1)
 712                                         (while (looking-at "\\s'")
 713                                           (forward-char 1))
 714                                         (point))))
 715       nil)))
 716
 717 ;; Read a tag name from the minibuffer with defaulting and completion.
 718 (defun find-tag-tag (string)
 719   (let* ((default (funcall (or find-tag-default-function
 720                                (get major-mode 'find-tag-default-function)
 721                                'find-tag-default)))
 722          (spec (completing-read (if default
 723                                     (format "%s(default %s) " string default)
 724                                   string)
 725                                 'tags-complete-tag
 726                                 nil nil nil nil default)))
 727     (if (equal spec "")
 728         (or default (error "There is no default tag"))
 729       spec)))
 730
 731 (defvar last-tag nil
 732   "Last tag found by \\[find-tag].")
 733
 734 ;; Get interactive args for find-tag{-noselect,-other-window,-regexp}.
 735 (defun find-tag-interactive (prompt &optional no-default)
 736   (if current-prefix-arg
 737       (list nil (if (< (prefix-numeric-value current-prefix-arg) 0)
 738                     '-
 739                   t))
 740     (list (if no-default
 741               (read-string prompt)
 742             (find-tag-tag prompt)))))
 743
 744 (defvar find-tag-history nil)
 745
 746 ;;;###autoload
 747 (defun find-tag-noselect (tagname &optional next-p regexp-p)
 748   "Find tag (in current tags table) whose name contains TAGNAME.
 749 Returns the buffer containing the tag's definition and moves its point there,
 750 but does not select the buffer.
 751 The default for TAGNAME is the expression in the buffer near point.
 752
 753 If second arg NEXT-P is t (interactively, with prefix arg), search for
 754 another tag that matches the last tagname or regexp used.  When there are
 755 multiple matches for a tag, more exact matches are found first.  If NEXT-P
 756 is the atom `-' (interactively, with prefix arg that is a negative number
 757 or just \\[negative-argument]), pop back to the previous tag gone to.
 758
 759 If third arg REGEXP-P is non-nil, treat TAGNAME as a regexp.
 760
 761 A marker representing the point when this command is onvoked is pushed
 762 onto a ring and may be popped back to with \\[pop-tag-mark].
 763 Contrast this with the ring of marks gone to by the command.
 764
 765 See documentation of variable `tags-file-name'."
 766   (interactive (find-tag-interactive "Find tag: "))
 767
 768   (setq find-tag-history (cons tagname find-tag-history))
 769   ;; Save the current buffer's value of `find-tag-hook' before selecting the
 770   ;; tags table buffer.
 771   (let ((local-find-tag-hook find-tag-hook))
 772     (if (eq '- next-p)
 773         ;; Pop back to a previous location.
 774         (if (ring-empty-p tags-location-ring)
 775             (error "No previous tag locations")
 776           (let ((marker (ring-remove tags-location-ring 0)))
 777             (prog1
 778                 ;; Move to the saved location.
 779                 (set-buffer (or (marker-buffer marker)
 780                                 (error "The marked buffer has been deleted")))
 781               (goto-char (marker-position marker))
 782               ;; Kill that marker so it doesn't slow down editing.
 783               (set-marker marker nil nil)
 784               ;; Run the user's hook.  Do we really want to do this for pop?
 785               (run-hooks 'local-find-tag-hook))))
 786       ;; Record whence we came.
 787       (ring-insert find-tag-marker-ring (point-marker))
 788       (if next-p
 789           ;; Find the same table we last used.
 790           (visit-tags-table-buffer 'same)
 791         ;; Pick a table to use.
 792         (visit-tags-table-buffer)
 793         ;; Record TAGNAME for a future call with NEXT-P non-nil.
 794         (setq last-tag tagname))
 795       ;; Record the location so we can pop back to it later.
 796       (let ((marker (make-marker)))
 797         (save-excursion
 798           (set-buffer
 799            ;; find-tag-in-order does the real work.
 800            (find-tag-in-order
 801             (if next-p last-tag tagname)
 802             (if regexp-p
 803                 find-tag-regexp-search-function
 804               find-tag-search-function)
 805             (if regexp-p
 806                 find-tag-regexp-tag-order
 807               find-tag-tag-order)
 808             (if regexp-p
 809                 find-tag-regexp-next-line-after-failure-p
 810               find-tag-next-line-after-failure-p)
 811             (if regexp-p "matching" "containing")
 812             (not next-p)))
 813           (set-marker marker (point))
 814           (run-hooks 'local-find-tag-hook)
 815           (ring-insert tags-location-ring marker)
 816           (current-buffer))))))
 817
 818 ;;;###autoload
 819 (defun find-tag (tagname &optional next-p regexp-p)
 820   "Find tag (in current tags table) whose name contains TAGNAME.
 821 Select the buffer containing the tag's definition, and move point there.
 822 The default for TAGNAME is the expression in the buffer around or before point.
 823
 824 If second arg NEXT-P is t (interactively, with prefix arg), search for
 825 another tag that matches the last tagname or regexp used.  When there are
 826 multiple matches for a tag, more exact matches are found first.  If NEXT-P
 827 is the atom `-' (interactively, with prefix arg that is a negative number
 828 or just \\[negative-argument]), pop back to the previous tag gone to.
 829
 830 If third arg REGEXP-P is non-nil, treat TAGNAME as a regexp.
 831
 832 A marker representing the point when this command is onvoked is pushed
 833 onto a ring and may be popped back to with \\[pop-tag-mark].
 834 Contrast this with the ring of marks gone to by the command.
 835
 836 See documentation of variable `tags-file-name'."
 837   (interactive (find-tag-interactive "Find tag: "))
 838   (switch-to-buffer (find-tag-noselect tagname next-p regexp-p)))
 839 ;;;###autoload (define-key esc-map "." 'find-tag)
 840
 841 ;;;###autoload
 842 (defun find-tag-other-window (tagname &optional next-p regexp-p)
 843   "Find tag (in current tags table) whose name contains TAGNAME.
 844 Select the buffer containing the tag's definition in another window, and
 845 move point there.  The default for TAGNAME is the expression in the buffer
 846 around or before point.
 847
 848 If second arg NEXT-P is t (interactively, with prefix arg), search for
 849 another tag that matches the last tagname or regexp used.  When there are
 850 multiple matches for a tag, more exact matches are found first.  If NEXT-P
 851 is negative (interactively, with prefix arg that is a negative number or
 852 just \\[negative-argument]), pop back to the previous tag gone to.
 853
 854 If third arg REGEXP-P is non-nil, treat TAGNAME as a regexp.
 855
 856 A marker representing the point when this command is onvoked is pushed
 857 onto a ring and may be popped back to with \\[pop-tag-mark].
 858 Contrast this with the ring of marks gone to by the command.
 859
 860 See documentation of variable `tags-file-name'."
 861   (interactive (find-tag-interactive "Find tag other window: "))
 862
 863   ;; This hair is to deal with the case where the tag is found in the
 864   ;; selected window's buffer; without the hair, point is moved in both
 865   ;; windows.  To prevent this, we save the selected window's point before
 866   ;; doing find-tag-noselect, and restore it after.
 867   (let* ((window-point (window-point (selected-window)))
 868          (tagbuf (find-tag-noselect tagname next-p regexp-p))
 869          (tagpoint (progn (set-buffer tagbuf) (point))))
 870     (set-window-point (prog1
 871                           (selected-window)
 872                         (switch-to-buffer-other-window tagbuf)
 873                         ;; We have to set this new window's point; it
 874                         ;; might already have been displaying a
 875                         ;; different portion of tagbuf, in which case
 876                         ;; switch-to-buffer-other-window doesn't set
 877                         ;; the window's point from the buffer.
 878                         (set-window-point (selected-window) tagpoint))
 879                       window-point)))
 880 ;;;###autoload (define-key ctl-x-4-map "." 'find-tag-other-window)
 881
 882 ;;;###autoload
 883 (defun find-tag-other-frame (tagname &optional next-p)
 884   "Find tag (in current tags table) whose name contains TAGNAME.
 885 Select the buffer containing the tag's definition in another frame, and
 886 move point there.  The default for TAGNAME is the expression in the buffer
 887 around or before point.
 888
 889 If second arg NEXT-P is t (interactively, with prefix arg), search for
 890 another tag that matches the last tagname or regexp used.  When there are
 891 multiple matches for a tag, more exact matches are found first.  If NEXT-P
 892 is negative (interactively, with prefix arg that is a negative number or
 893 just \\[negative-argument]), pop back to the previous tag gone to.
 894
 895 If third arg REGEXP-P is non-nil, treat TAGNAME as a regexp.
 896
 897 A marker representing the point when this command is onvoked is pushed
 898 onto a ring and may be popped back to with \\[pop-tag-mark].
 899 Contrast this with the ring of marks gone to by the command.
 900
 901 See documentation of variable `tags-file-name'."
 902   (interactive (find-tag-interactive "Find tag other frame: "))
 903   (let ((pop-up-frames t))
 904     (find-tag-other-window tagname next-p)))
 905 ;;;###autoload (define-key ctl-x-5-map "." 'find-tag-other-frame)
 906
 907 ;;;###autoload
 908 (defun find-tag-regexp (regexp &optional next-p other-window)
 909   "Find tag (in current tags table) whose name matches REGEXP.
 910 Select the buffer containing the tag's definition and move point there.
 911
 912 If second arg NEXT-P is t (interactively, with prefix arg), search for
 913 another tag that matches the last tagname or regexp used.  When there are
 914 multiple matches for a tag, more exact matches are found first.  If NEXT-P
 915 is negative (interactively, with prefix arg that is a negative number or
 916 just \\[negative-argument]), pop back to the previous tag gone to.
 917
 918 If third arg OTHER-WINDOW is non-nil, select the buffer in another window.
 919
 920 A marker representing the point when this command is onvoked is pushed
 921 onto a ring and may be popped back to with \\[pop-tag-mark].
 922 Contrast this with the ring of marks gone to by the command.
 923
 924 See documentation of variable `tags-file-name'."
 925   (interactive (find-tag-interactive "Find tag regexp: " t))
 926   ;; We go through find-tag-other-window to do all the display hair there.
 927   (funcall (if other-window 'find-tag-other-window 'find-tag)
 928            regexp next-p t))
 929 ;;;###autoload (define-key esc-map [?\C-.] 'find-tag-regexp)
 930
 931 ;;;###autoload (define-key esc-map "*" 'pop-tag-mark)
 932
 933 ;;;###autoload
 934 (defun pop-tag-mark ()
 935   "Pop back to where \\[find-tag] was last invoked.
 936
 937 This is distinct from invoking \\[find-tag] with a negative argument
 938 since that pops a stack of markers at which tags were found, not from
 939 where they were found."
 940   (interactive)
 941   (if (ring-empty-p find-tag-marker-ring)
 942       (error "No previous locations for find-tag invocation"))
 943   (let ((marker (ring-remove find-tag-marker-ring 0)))
 944     (switch-to-buffer (or (marker-buffer marker)
 945                           (error "The marked buffer has been deleted")))
 946     (goto-char (marker-position marker))
 947     (set-marker marker nil nil)))
 948 \f
 949 ;; Internal tag finding function.
 950
 951 ;; PATTERN is a string to pass to second arg SEARCH-FORWARD-FUNC, and to
 952 ;; any member of the function list ORDER (third arg).  If ORDER is nil,
 953 ;; use saved state to continue a previous search.
 954
 955 ;; Fourth arg MATCHING is a string, an English '-ing' word, to be used in
 956 ;; an error message.
 957
 958 ;; Fifth arg NEXT-LINE-AFTER-FAILURE-P is non-nil if after a failed match,
 959 ;; point should be moved to the next line.
 960
 961 ;; Algorithm is as follows.  For each qualifier-func in ORDER, go to
 962 ;; beginning of tags file, and perform inner loop: for each naive match for
 963 ;; PATTERN found using SEARCH-FORWARD-FUNC, qualify the naive match using
 964 ;; qualifier-func.  If it qualifies, go to the specified line in the
 965 ;; specified source file and return.  Qualified matches are remembered to
 966 ;; avoid repetition.  State is saved so that the loop can be continued.
 967
 968 (defvar tag-lines-already-matched nil)  ;matches remembered here between calls
 969
 970 (defun find-tag-in-order (pattern
 971                           search-forward-func
 972                           order
 973                           next-line-after-failure-p
 974                           matching
 975                           first-search)
 976   (let (file                            ;name of file containing tag
 977         tag-info                        ;where to find the tag in FILE
 978         (first-table t)
 979         (tag-order order)
 980         (match-marker (make-marker))
 981         goto-func
 982         )
 983     (save-excursion
 984
 985       (if first-search
 986           ;; This is the start of a search for a fresh tag.
 987           ;; Clear the list of tags matched by the previous search.
 988           ;; find-tag-noselect has already put us in the first tags table
 989           ;; buffer before we got called.
 990           (setq tag-lines-already-matched nil)
 991         ;; Continuing to search for the tag specified last time.
 992         ;; tag-lines-already-matched lists locations matched in previous
 993         ;; calls so we don't visit the same tag twice if it matches twice
 994         ;; during two passes with different qualification predicates.
 995         ;; Switch to the current tags table buffer.
 996         (visit-tags-table-buffer 'same))
 997
 998       ;; Get a qualified match.
 999       (catch 'qualified-match-found
1000
1001         ;; Iterate over the list of tags tables.
1002         (while (or first-table
1003                    (visit-tags-table-buffer t))
1004
1005           (and first-search first-table
1006                ;; Start at beginning of tags file.
1007                (goto-char (point-min)))
1008
1009           (setq first-table nil)
1010
1011           ;; Iterate over the list of ordering predicates.
1012           (while order
1013             (while (funcall search-forward-func pattern nil t)
1014               ;; Naive match found.  Qualify the match.
1015               (and (funcall (car order) pattern)
1016                    ;; Make sure it is not a previous qualified match.
1017                    (not (member (set-marker match-marker (save-excursion
1018                                                            (beginning-of-line)
1019                                                            (point)))
1020                                 tag-lines-already-matched))
1021                    (throw 'qualified-match-found nil))
1022               (if next-line-after-failure-p
1023                   (forward-line 1)))
1024             ;; Try the next flavor of match.
1025             (setq order (cdr order))
1026             (goto-char (point-min)))
1027           (setq order tag-order))
1028         ;; We throw out on match, so only get here if there were no matches.
1029         ;; Clear out the markers we use to avoid duplicate matches so they
1030         ;; don't slow down editting and are immediately available for GC.
1031         (while tag-lines-already-matched
1032           (set-marker (car tag-lines-already-matched) nil nil)
1033           (setq tag-lines-already-matched (cdr tag-lines-already-matched)))
1034         (set-marker match-marker nil nil)
1035         (error "No %stags %s %s" (if first-search "" "more ")
1036                matching pattern))
1037
1038       ;; Found a tag; extract location info.
1039       (beginning-of-line)
1040       (setq tag-lines-already-matched (cons match-marker
1041                                             tag-lines-already-matched))
1042       ;; Expand the filename, using the tags table buffer's default-directory.
1043       (setq file (expand-file-name (file-of-tag))
1044             tag-info (funcall snarf-tag-function))
1045
1046       ;; Get the local value in the tags table buffer before switching buffers.
1047       (setq goto-func goto-tag-location-function)
1048
1049       ;; Find the right line in the specified file.
1050       (set-buffer (find-file-noselect file))
1051       (widen)
1052       (push-mark)
1053       (funcall goto-func tag-info)
1054
1055       ;; Return the buffer where the tag was found.
1056       (current-buffer))))
1057 \f
1058 ;; `etags' TAGS file format support.
1059
1060 ;; If the current buffer is a valid etags TAGS file, give it local values of
1061 ;; the tags table format variables, and return non-nil.
1062 (defun etags-recognize-tags-table ()
1063   (and (etags-verify-tags-table)
1064        ;; It is annoying to flash messages on the screen briefly,
1065        ;; and this message is not useful.  -- rms
1066        ;; (message "%s is an `etags' TAGS file" buffer-file-name)
1067        (mapcar (function (lambda (elt)
1068                            (set (make-local-variable (car elt)) (cdr elt))))
1069                '((file-of-tag-function . etags-file-of-tag)
1070                  (tags-table-files-function . etags-tags-table-files)
1071                  (tags-completion-table-function . etags-tags-completion-table)
1072                  (snarf-tag-function . etags-snarf-tag)
1073                  (goto-tag-location-function . etags-goto-tag-location)
1074                  (find-tag-regexp-search-function . re-search-forward)
1075                  (find-tag-regexp-tag-order . (tag-re-match-p))
1076                  (find-tag-regexp-next-line-after-failure-p . t)
1077                  (find-tag-search-function . search-forward)
1078                  (find-tag-tag-order . (tag-exact-file-name-match-p
1079                                         tag-exact-match-p
1080                                         tag-symbol-match-p
1081                                         tag-word-match-p
1082                                         tag-any-match-p))
1083                  (find-tag-next-line-after-failure-p . nil)
1084                  (list-tags-function . etags-list-tags)
1085                  (tags-apropos-function . etags-tags-apropos)
1086                  (tags-included-tables-function . etags-tags-included-tables)
1087                  (verify-tags-table-function . etags-verify-tags-table)
1088                  ))))
1089
1090 ;; Return non-nil iff the current buffer is a valid etags TAGS file.
1091 (defun etags-verify-tags-table ()
1092   ;; Use eq instead of = in case char-after returns nil.
1093   (eq (char-after 1) ?\f))
1094
1095 (defun etags-file-of-tag ()
1096   (save-excursion
1097     (re-search-backward "\f\n\\([^\n]+\\),[0-9]*\n")
1098     (expand-file-name (buffer-substring (match-beginning 1) (match-end 1))
1099                       (file-truename default-directory))))
1100
1101
1102 (defun etags-tags-completion-table ()
1103   (let ((table (make-vector 511 0)))
1104     (save-excursion
1105       (goto-char (point-min))
1106       ;; This monster regexp matches an etags tag line.
1107       ;;   \1 is the string to match;
1108       ;;   \2 is not interesting;
1109       ;;   \3 is the guessed tag name; XXX guess should be better eg DEFUN
1110       ;;   \4 is not interesting;
1111       ;;   \5 is the explicitly-specified tag name.
1112       ;;   \6 is the line to start searching at;
1113       ;;   \7 is the char to start searching at.
1114       (while (re-search-forward
1115               "^\\(\\([^\177]+[^-a-zA-Z0-9_$\177]+\\)?\\([-a-zA-Z0-9_$?:]+\\)\
1116 \[^-a-zA-Z0-9_$?:\177]*\\)\177\\(\\([^\n\001]+\\)\001\\)?\
1117 \\([0-9]+\\)?,\\([0-9]+\\)?\n"
1118               nil t)
1119         (intern (if (match-beginning 5)
1120                     ;; There is an explicit tag name.
1121                     (buffer-substring (match-beginning 5) (match-end 5))
1122                   ;; No explicit tag name.  Best guess.
1123                   (buffer-substring (match-beginning 3) (match-end 3)))
1124                 table)))
1125     table))
1126
1127 (defun etags-snarf-tag ()
1128   (let (tag-text line startpos)
1129     (if (save-excursion
1130           (forward-line -1)
1131           (looking-at "\f\n"))
1132         ;; The match was for a source file name, not any tag within a file.
1133         ;; Give text of t, meaning to go exactly to the location we specify,
1134         ;; the beginning of the file.
1135         (setq tag-text t
1136               line nil
1137               startpos 1)
1138
1139       ;; Find the end of the tag and record the whole tag text.
1140       (search-forward "\177")
1141       (setq tag-text (buffer-substring (1- (point))
1142                                        (save-excursion (beginning-of-line)
1143                                                        (point))))
1144       ;; Skip explicit tag name if present.
1145       (search-forward "\001" (save-excursion (forward-line 1) (point)) t)
1146       (if (looking-at "[0-9]")
1147           (setq line (string-to-int (buffer-substring
1148                                      (point)
1149                                      (progn (skip-chars-forward "0-9")
1150                                             (point))))))
1151       (search-forward ",")
1152       (if (looking-at "[0-9]")
1153           (setq startpos (string-to-int (buffer-substring
1154                                          (point)
1155                                          (progn (skip-chars-forward "0-9")
1156                                                 (point)))))))
1157     ;; Leave point on the next line of the tags file.
1158     (forward-line 1)
1159     (cons tag-text (cons line startpos))))
1160
1161 ;; TAG-INFO is a cons (TEXT LINE . POSITION) where TEXT is the initial part
1162 ;; of a line containing the tag and POSITION is the character position of
1163 ;; TEXT within the file (starting from 1); LINE is the line number.  If
1164 ;; TEXT is t, it means the tag refers to exactly LINE or POSITION
1165 ;; (whichever is present, LINE having preference, no searching.  Either
1166 ;; LINE or POSITION may be nil; POSITION is used if present.  If the tag
1167 ;; isn't exactly at the given position then look around that position using
1168 ;; a search window which expands until it hits the start of file.
1169 (defun etags-goto-tag-location (tag-info)
1170   (let ((startpos (cdr (cdr tag-info)))
1171         (line (car (cdr tag-info)))
1172         offset found pat)
1173     (if (eq (car tag-info) t)
1174         ;; Direct file tag.
1175         (cond (line (goto-line line))
1176               (startpos (goto-char startpos))
1177               (t (error "etags.el BUG: bogus direct file tag")))
1178       ;; This constant is 1/2 the initial search window.
1179       ;; There is no sense in making it too small,
1180       ;; since just going around the loop once probably
1181       ;; costs about as much as searching 2000 chars.
1182       (setq offset 1000
1183             found nil
1184             pat (concat (if (eq selective-display t)
1185                             "\\(^\\|\^m\\)" "^")
1186                         (regexp-quote (car tag-info))))
1187       ;; The character position in the tags table is 0-origin.
1188       ;; Convert it to a 1-origin Emacs character position.
1189       (if startpos (setq startpos (1+ startpos)))
1190       ;; If no char pos was given, try the given line number.
1191       (or startpos
1192           (if line
1193               (setq startpos (progn (goto-line line)
1194                                     (point)))))
1195       (or startpos
1196           (setq startpos (point-min)))
1197       ;; First see if the tag is right at the specified location.
1198       (goto-char startpos)
1199       (setq found (looking-at pat))
1200       (while (and (not found)
1201                   (progn
1202                     (goto-char (- startpos offset))
1203                     (not (bobp))))
1204         (setq found
1205               (re-search-forward pat (+ startpos offset) t)
1206               offset (* 3 offset)))     ; expand search window
1207       (or found
1208           (re-search-forward pat nil t)
1209           (error "Rerun etags: `%s' not found in %s"
1210                  pat buffer-file-name)))
1211     ;; Position point at the right place
1212     ;; if the search string matched an extra Ctrl-m at the beginning.
1213     (and (eq selective-display t)
1214          (looking-at "\^m")
1215          (forward-char 1))
1216     (beginning-of-line)))
1217
1218 (defun etags-list-tags (file)
1219   (goto-char 1)
1220   (if (not (search-forward (concat "\f\n" file ",") nil t))
1221       nil
1222     (forward-line 1)
1223     (while (not (or (eobp) (looking-at "\f")))
1224       (let ((tag (buffer-substring (point)
1225                                    (progn (skip-chars-forward "^\177")
1226                                           (point)))))
1227         (princ (if (looking-at "[^\n]+\001")
1228                    ;; There is an explicit tag name; use that.
1229                    (buffer-substring (1+ (point)) ;skip \177
1230                                      (progn (skip-chars-forward "^\001")
1231                                             (point)))
1232                  tag)))
1233       (terpri)
1234       (forward-line 1))
1235     t))
1236
1237 (defun etags-tags-apropos (string)
1238   (goto-char 1)
1239   (while (re-search-forward string nil t)
1240     (beginning-of-line)
1241     (princ (buffer-substring (point)
1242                              (progn (skip-chars-forward "^\177")
1243                                     (point))))
1244     (terpri)
1245     (forward-line 1)))
1246
1247 (defun etags-tags-table-files ()
1248   (let ((files nil)
1249         beg)
1250     (goto-char (point-min))
1251     (while (search-forward "\f\n" nil t)
1252       (setq beg (point))
1253       (end-of-line)
1254       (skip-chars-backward "^," beg)
1255       (or (looking-at "include$")
1256           (setq files (cons (buffer-substring beg (1- (point))) files))))
1257     (nreverse files)))
1258
1259 (defun etags-tags-included-tables ()
1260   (let ((files nil)
1261         beg)
1262     (goto-char (point-min))
1263     (while (search-forward "\f\n" nil t)
1264       (setq beg (point))
1265       (end-of-line)
1266       (skip-chars-backward "^," beg)
1267       (if (looking-at "include$")
1268           ;; Expand in the default-directory of the tags table buffer.
1269           (setq files (cons (expand-file-name (buffer-substring beg (1- (point))))
1270                             files))))
1271     (nreverse files)))
1272 \f
1273 ;; Empty tags file support.
1274
1275 ;; Recognize an empty file and give it local values of the tags table format
1276 ;; variables which do nothing.
1277 (defun recognize-empty-tags-table ()
1278   (and (zerop (buffer-size))
1279        (mapcar (function (lambda (sym)
1280                            (set (make-local-variable sym) 'ignore)))
1281                '(tags-table-files-function
1282                  tags-completion-table-function
1283                  find-tag-regexp-search-function
1284                  find-tag-search-function
1285                  tags-apropos-function
1286                  tags-included-tables-function))
1287        (set (make-local-variable 'verify-tags-table-function)
1288             (function (lambda ()
1289                         (zerop (buffer-size)))))))
1290 \f
1291 ;;; Match qualifier functions for tagnames.
1292 ;;; XXX these functions assume etags file format.
1293
1294 ;; This might be a neat idea, but it's too hairy at the moment.
1295 ;;(defmacro tags-with-syntax (&rest body)
1296 ;;  (` (let ((current (current-buffer))
1297 ;;         (otable (syntax-table))
1298 ;;         (buffer (find-file-noselect (file-of-tag)))
1299 ;;         table)
1300 ;;       (unwind-protect
1301 ;;         (progn
1302 ;;           (set-buffer buffer)
1303 ;;           (setq table (syntax-table))
1304 ;;           (set-buffer current)
1305 ;;           (set-syntax-table table)
1306 ;;           (,@ body))
1307 ;;       (set-syntax-table otable)))))
1308 ;;(put 'tags-with-syntax 'edebug-form-spec '(&rest form))
1309
1310 ;; t if point is at a tag line that matches TAG exactly.
1311 ;; point should be just after a string that matches TAG.
1312 (defun tag-exact-match-p (tag)
1313   ;; The match is really exact if there is an explicit tag name.
1314   (or (and (eq (char-after (point)) ?\001)
1315            (eq (char-after (- (point) (length tag) 1)) ?\177))
1316       ;; We are not on the explicit tag name, but perhaps it follows.
1317       (looking-at (concat "[^\177\n]*\177" (regexp-quote tag) "\001"))))
1318
1319 ;; t if point is at a tag line that matches TAG as a symbol.
1320 ;; point should be just after a string that matches TAG.
1321 (defun tag-symbol-match-p (tag)
1322   (and (looking-at "\\Sw.*\177") (looking-at "\\S_.*\177")
1323        (save-excursion
1324          (backward-char (1+ (length tag)))
1325          (and (looking-at "\\Sw") (looking-at "\\S_")))))
1326
1327 ;; t if point is at a tag line that matches TAG as a word.
1328 ;; point should be just after a string that matches TAG.
1329 (defun tag-word-match-p (tag)
1330   (and (looking-at "\\b.*\177")
1331        (save-excursion (backward-char (length tag))
1332                        (looking-at "\\b"))))
1333
1334 (defun tag-exact-file-name-match-p (tag)
1335   (and (looking-at ",")
1336        (save-excursion (backward-char (length tag))
1337                        (looking-at "\f\n"))))
1338
1339 ;; t if point is in a tag line with a tag containing TAG as a substring.
1340 (defun tag-any-match-p (tag)
1341   (looking-at ".*\177"))
1342
1343 ;; t if point is at a tag line that matches RE as a regexp.
1344 (defun tag-re-match-p (re)
1345   (save-excursion
1346     (beginning-of-line)
1347     (let ((bol (point)))
1348       (and (search-forward "\177" (save-excursion (end-of-line) (point)) t)
1349            (re-search-backward re bol t)))))
1350 \f
1351 ;;;###autoload
1352 (defun next-file (&optional initialize novisit)
1353   "Select next file among files in current tags table.
1354
1355 A first argument of t (prefix arg, if interactive) initializes to the
1356 beginning of the list of files in the tags table.  If the argument is
1357 neither nil nor t, it is evalled to initialize the list of files.
1358
1359 Non-nil second argument NOVISIT means use a temporary buffer
1360  to save time and avoid uninteresting warnings.
1361
1362 Value is nil if the file was already visited;
1363 if the file was newly read in, the value is the filename."
1364   ;; Make the interactive arg t if there was any prefix arg.
1365   (interactive (list (if current-prefix-arg t)))
1366   (cond ((not initialize)
1367          ;; Not the first run.
1368          )
1369         ((eq initialize t)
1370          ;; Initialize the list from the tags table.
1371          (save-excursion
1372            ;; Visit the tags table buffer to get its list of files.
1373            (visit-tags-table-buffer)
1374            ;; Copy the list so we can setcdr below, and expand the file
1375            ;; names while we are at it, in this buffer's default directory.
1376            (setq next-file-list (mapcar 'expand-file-name (tags-table-files)))
1377            ;; Iterate over all the tags table files, collecting
1378            ;; a complete list of referenced file names.
1379            (while (visit-tags-table-buffer t)
1380              ;; Find the tail of the working list and chain on the new
1381              ;; sublist for this tags table.
1382              (let ((tail next-file-list))
1383                (while (cdr tail)
1384                  (setq tail (cdr tail)))
1385                ;; Use a copy so the next loop iteration will not modify the
1386                ;; list later returned by (tags-table-files).
1387                (if tail
1388                    (setcdr tail (mapcar 'expand-file-name (tags-table-files)))
1389                  (setq next-file-list (mapcar 'expand-file-name
1390                                               (tags-table-files))))))))
1391         (t
1392          ;; Initialize the list by evalling the argument.
1393          (setq next-file-list (eval initialize))))
1394   (if next-file-list
1395       ()
1396     (and novisit
1397          (get-buffer " *next-file*")
1398          (kill-buffer " *next-file*"))
1399     (error "All files processed"))
1400   (let* ((next (car next-file-list))
1401          (new (not (get-file-buffer next))))
1402     ;; Advance the list before trying to find the file.
1403     ;; If we get an error finding the file, don't get stuck on it.
1404     (setq next-file-list (cdr next-file-list))
1405     (if (not (and new novisit))
1406         (set-buffer (find-file-noselect next novisit))
1407       ;; Like find-file, but avoids random warning messages.
1408       (set-buffer (get-buffer-create " *next-file*"))
1409       (kill-all-local-variables)
1410       (erase-buffer)
1411       (setq new next)
1412       (insert-file-contents new nil))
1413     new))
1414
1415 (defvar tags-loop-operate nil
1416   "Form for `tags-loop-continue' to eval to change one file.")
1417
1418 (defvar tags-loop-scan
1419   '(error "%s"
1420           (substitute-command-keys
1421            "No \\[tags-search] or \\[tags-query-replace] in progress"))
1422   "Form for `tags-loop-continue' to eval to scan one file.
1423 If it returns non-nil, this file needs processing by evalling
1424 \`tags-loop-operate'.  Otherwise, move on to the next file.")
1425
1426 ;;;###autoload
1427 (defun tags-loop-continue (&optional first-time)
1428   "Continue last \\[tags-search] or \\[tags-query-replace] command.
1429 Used noninteractively with non-nil argument to begin such a command (the
1430 argument is passed to `next-file', which see).
1431
1432 Two variables control the processing we do on each file: the value of
1433 `tags-loop-scan' is a form to be executed on each file to see if it is
1434 interesting (it returns non-nil if so) and `tags-loop-operate' is a form to
1435 evaluate to operate on an interesting file.  If the latter evaluates to
1436 nil, we exit; otherwise we scan the next file."
1437   (interactive)
1438   (let (new
1439         (messaged nil))
1440     (while
1441         (progn
1442           ;; Scan files quickly for the first or next interesting one.
1443           (while (or first-time
1444                      (save-restriction
1445                        (widen)
1446                        (not (eval tags-loop-scan))))
1447             (setq new (next-file first-time t))
1448             ;; If NEW is non-nil, we got a temp buffer,
1449             ;; and NEW is the file name.
1450             (if (or messaged
1451                     (and (not first-time)
1452                          (> baud-rate search-slow-speed)
1453                          (setq messaged t)))
1454                 (message "Scanning file %s..." (or new buffer-file-name)))
1455             (setq first-time nil)
1456             (goto-char (point-min)))
1457
1458           ;; If we visited it in a temp buffer, visit it now for real.
1459           (if new
1460               (let ((pos (point)))
1461                 (erase-buffer)
1462                 (set-buffer (find-file-noselect new))
1463                 (setq new nil)          ;No longer in a temp buffer.
1464                 (widen)
1465                 (goto-char pos)))
1466
1467           (switch-to-buffer (current-buffer))
1468
1469           ;; Now operate on the file.
1470           ;; If value is non-nil, continue to scan the next file.
1471           (eval tags-loop-operate)))
1472     (and messaged
1473          (null tags-loop-operate)
1474          (message "Scanning file %s...found" buffer-file-name))))
1475 ;;;###autoload (define-key esc-map "," 'tags-loop-continue)
1476
1477 ;;;###autoload
1478 (defun tags-search (regexp &optional file-list-form)
1479   "Search through all files listed in tags table for match for REGEXP.
1480 Stops when a match is found.
1481 To continue searching for next match, use command \\[tags-loop-continue].
1482
1483 See documentation of variable `tags-file-name'."
1484   (interactive "sTags search (regexp): ")
1485   (if (and (equal regexp "")
1486            (eq (car tags-loop-scan) 're-search-forward)
1487            (null tags-loop-operate))
1488       ;; Continue last tags-search as if by M-,.
1489       (tags-loop-continue nil)
1490     (setq tags-loop-scan
1491           (list 're-search-forward (list 'quote regexp) nil t)
1492           tags-loop-operate nil)
1493     (tags-loop-continue (or file-list-form t))))
1494
1495 ;;;###autoload
1496 (defun tags-query-replace (from to &optional delimited file-list-form)
1497   "Query-replace-regexp FROM with TO through all files listed in tags table.
1498 Third arg DELIMITED (prefix arg) means replace only word-delimited matches.
1499 If you exit (\\[keyboard-quit] or ESC), you can resume the query-replace
1500 with the command \\[tags-loop-continue].
1501
1502 See documentation of variable `tags-file-name'."
1503   (interactive (query-replace-read-args "Tags query replace (regexp)" t))
1504   (setq tags-loop-scan (list 'prog1
1505                              (list 'if (list 're-search-forward
1506                                              (list 'quote from) nil t)
1507                                    ;; When we find a match, move back
1508                                    ;; to the beginning of it so perform-replace
1509                                    ;; will see it.
1510                                    '(goto-char (match-beginning 0))))
1511         tags-loop-operate (list 'perform-replace
1512                                 (list 'quote from) (list 'quote to)
1513                                 t t (list 'quote delimited)))
1514   (tags-loop-continue (or file-list-form t)))
1515 \f
1516 (defun tags-complete-tags-table-file (string predicate what)
1517   (save-excursion
1518     ;; If we need to ask for the tag table, allow that.
1519     (let ((enable-recursive-minibuffers t))
1520       (visit-tags-table-buffer))
1521     (if (eq what t)
1522         (all-completions string (mapcar 'list (tags-table-files))
1523                          predicate)
1524       (try-completion string (mapcar 'list (tags-table-files))
1525                       predicate))))
1526
1527 ;;;###autoload
1528 (defun list-tags (file &optional next-match)
1529   "Display list of tags in file FILE.
1530 This searches only the first table in the list, and no included tables.
1531 FILE should be as it appeared in the `etags' command, usually without a
1532 directory specification."
1533   (interactive (list (completing-read "List tags in file: "
1534                                       'tags-complete-tags-table-file
1535                                       nil t nil)))
1536   (with-output-to-temp-buffer "*Tags List*"
1537     (princ "Tags in file ")
1538     (princ file)
1539     (terpri)
1540     (save-excursion
1541       (let ((first-time t)
1542             (gotany nil))
1543         (while (visit-tags-table-buffer (not first-time))
1544           (setq first-time nil)
1545           (if (funcall list-tags-function file)
1546               (setq gotany t)))
1547         (or gotany
1548             (error "File %s not in current tags tables" file))))))
1549
1550 ;;;###autoload
1551 (defun tags-apropos (regexp)
1552   "Display list of all tags in tags table REGEXP matches."
1553   (interactive "sTags apropos (regexp): ")
1554   (with-output-to-temp-buffer "*Tags List*"
1555     (princ "Tags matching regexp ")
1556     (prin1 regexp)
1557     (terpri)
1558     (save-excursion
1559       (let ((first-time t))
1560         (while (visit-tags-table-buffer (not first-time))
1561           (setq first-time nil)
1562           (funcall tags-apropos-function regexp))))))
1563 \f
1564 ;;; XXX Kludge interface.
1565
1566 ;; XXX If a file is in multiple tables, selection may get the wrong one.
1567 ;;;###autoload
1568 (defun select-tags-table ()
1569   "Select a tags table file from a menu of those you have already used.
1570 The list of tags tables to select from is stored in `tags-table-set-list';
1571 see the doc of that variable if you want to add names to the list."
1572   (interactive)
1573   (pop-to-buffer "*Tags Table List*")
1574   (setq buffer-read-only nil)
1575   (erase-buffer)
1576   (let ((set-list tags-table-set-list)
1577         (desired-point nil))
1578     (if tags-table-list
1579         (progn
1580           (setq desired-point (point-marker))
1581           (princ tags-table-list (current-buffer))
1582           (insert "\C-m")
1583           (prin1 (car tags-table-list) (current-buffer)) ;invisible
1584           (insert "\n")))
1585     (while set-list
1586       (if (eq (car set-list) tags-table-list)
1587           ;; Already printed it.
1588           ()
1589         (princ (car set-list) (current-buffer))
1590         (insert "\C-m")
1591         (prin1 (car (car set-list)) (current-buffer)) ;invisible
1592         (insert "\n"))
1593       (setq set-list (cdr set-list)))
1594     (if tags-file-name
1595         (progn
1596           (or desired-point
1597               (setq desired-point (point-marker)))
1598           (insert tags-file-name "\C-m")
1599           (prin1 tags-file-name (current-buffer)) ;invisible
1600           (insert "\n")))
1601     (setq set-list (delete tags-file-name
1602                            (apply 'nconc (cons (copy-sequence tags-table-list)
1603                                                (mapcar 'copy-sequence
1604                                                        tags-table-set-list)))))
1605     (while set-list
1606       (insert (car set-list) "\C-m")
1607       (prin1 (car set-list) (current-buffer)) ;invisible
1608       (insert "\n")
1609       (setq set-list (delete (car set-list) set-list)))
1610     (goto-char 1)
1611     (insert-before-markers
1612      "Type `t' to select a tags table or set of tags tables:\n\n")
1613     (if desired-point
1614         (goto-char desired-point))
1615     (set-window-start (selected-window) 1 t))
1616   (set-buffer-modified-p nil)
1617   (select-tags-table-mode))
1618
1619 (defvar select-tags-table-mode-map)
1620 (let ((map (make-sparse-keymap)))
1621   (define-key map "t" 'select-tags-table-select)
1622   (define-key map " " 'next-line)
1623   (define-key map "\^?" 'previous-line)
1624   (define-key map "n" 'next-line)
1625   (define-key map "p" 'previous-line)
1626   (define-key map "q" 'select-tags-table-quit)
1627   (setq select-tags-table-mode-map map))
1628
1629 (defun select-tags-table-mode ()
1630   "Major mode for choosing a current tags table among those already loaded.
1631
1632 \\{select-tags-table-mode-map}"
1633   (interactive)
1634   (kill-all-local-variables)
1635   (setq buffer-read-only t
1636         major-mode 'select-tags-table-mode
1637         mode-name "Select Tags Table")
1638   (use-local-map select-tags-table-mode-map)
1639   (setq selective-display t
1640         selective-display-ellipses nil))
1641
1642 (defun select-tags-table-select ()
1643   "Select the tags table named on this line."
1644   (interactive)
1645   (search-forward "\C-m")
1646   (let ((name (read (current-buffer))))
1647     (visit-tags-table name)
1648     (select-tags-table-quit)
1649     (message "Tags table now %s" name)))
1650
1651 (defun select-tags-table-quit ()
1652   "Kill the buffer and delete the selected window."
1653   (interactive)
1654   (quit-window t (selected-window)))
1655 \f
1656 ;;; Note, there is another definition of this function in bindings.el.
1657 ;;;###autoload
1658 (defun complete-tag ()
1659   "Perform tags completion on the text around point.
1660 Completes to the set of names listed in the current tags table.
1661 The string to complete is chosen in the same way as the default
1662 for \\[find-tag] (which see)."
1663   (interactive)
1664   (or tags-table-list
1665       tags-file-name
1666       (error "%s"
1667              (substitute-command-keys
1668               "No tags table loaded; try \\[visit-tags-table]")))
1669   (let ((pattern (funcall (or find-tag-default-function
1670                               (get major-mode 'find-tag-default-function)
1671                               'find-tag-default)))
1672         beg
1673         completion)
1674     (or pattern
1675         (error "Nothing to complete"))
1676     (search-backward pattern)
1677     (setq beg (point))
1678     (forward-char (length pattern))
1679     (setq completion (try-completion pattern 'tags-complete-tag nil))
1680     (cond ((eq completion t))
1681           ((null completion)
1682            (message "Can't find completion for \"%s\"" pattern)
1683            (ding))
1684           ((not (string= pattern completion))
1685            (delete-region beg (point))
1686            (insert completion))
1687           (t
1688            (message "Making completion list...")
1689            (with-output-to-temp-buffer "*Completions*"
1690              (display-completion-list
1691               (all-completions pattern 'tags-complete-tag nil)))
1692            (message "Making completion list...%s" "done")))))
1693 \f
1694 (provide 'etags)
1695
1696 ;;; etags.el ends here