Function: visit-tags-table

visit-tags-table is an autoloaded, interactive and byte-compiled function defined in etags.el.gz.

Signature

(visit-tags-table FILE &optional LOCAL)

Documentation

Tell tags commands to use tags table file FILE.

FILE should be the name of a file created with the etags program. A directory name is ok too; it means file TAGS in that directory.

Normally M-x visit-tags-table (visit-tags-table) sets the global value of tags-file-name. With a prefix arg, set the buffer-local value instead. When called from Lisp, if the optional arg LOCAL is non-nil, set the local value. When you find a tag with M-x find-tag (find-tag), the buffer it finds the tag in is given a local value of this variable which is the name of the tags file the tag was in.

View in manual

Probably introduced at or before Emacs version 17.

Key Bindings

Source Code

;; Defined in /usr/src/emacs/lisp/progmodes/etags.el.gz
;;;###autoload
(defun visit-tags-table (file &optional local)
  "Tell tags commands to use tags table file FILE.
FILE should be the name of a file created with the `etags' program.
A directory name is ok too; it means file TAGS in that directory.

Normally \\[visit-tags-table] sets the global value of `tags-file-name'.
With a prefix arg, set the buffer-local value instead.  When called
from Lisp, if the optional arg LOCAL is non-nil, set the local value.
When you find a tag with \\[find-tag], the buffer it finds the tag
in is given a local value of this variable which is the name of the tags
file the tag was in."
  (interactive
   (let ((default-tag-dir
           (or (locate-dominating-file default-directory "TAGS")
               default-directory)))
     (list (read-file-name
            (format-prompt "Visit tags table" "TAGS")
            ;; default to TAGS from default-directory up to root.
            default-tag-dir
            (expand-file-name "TAGS" default-tag-dir)
            t)
           current-prefix-arg)))

  (or (stringp file) (signal 'wrong-type-argument (list 'stringp file)))
  ;; Bind tags-file-name so we can control below whether the local or
  ;; global value gets set.
  ;; Calling visit-tags-table-buffer with tags-file-name set to FILE will
  ;; initialize a buffer for FILE and set tags-file-name to the
  ;; fully-expanded name.
  (let ((tags-file-name file)
        (cbuf (current-buffer)))
    (save-excursion
      (or (visit-tags-table-buffer file)
	  (signal 'file-missing (list "Visiting tags table"
				      "No such file or directory"
				      file)))
      ;; Set FILE to the expanded name.  Do that in the buffer we
      ;; started from, because visit-tags-table-buffer switches
      ;; buffers after updating tags-file-name, so if tags-file-name
      ;; is local in the buffer we started, that value is only visible
      ;; in that buffer.
      (setq file (with-current-buffer cbuf tags-file-name))))
  (if local
      (progn
        ;; Force recomputation of tags-completion-table.
        (setq-local tags-completion-table nil)
        ;; Set the local value of tags-file-name.
        (setq-local tags-file-name file))
    ;; Set the global value of tags-file-name.
    (setq-default tags-file-name file)
    (setq tags-completion-table nil)))