comparison lisp/progmodes/etags.el @ 91776:01d2b6c9032f

Add many doc strings.

91775:aab40ecbce33

(defvar tags-included-tables-function nil
  "Function to do the work of `tags-included-tables' (which see).")
(defvar verify-tags-table-function nil
  "Function to return t if current buffer contains valid tags file.")

;; Initialize the tags table in the current buffer.
;; Returns non-nil if it is a valid tags table.  On
;; non-nil return, the tags table state variable are
;; made buffer-local and initialized to nil.
(defun initialize-new-tags-table ()
  (set (make-local-variable 'tags-table-files) nil)
  (set (make-local-variable 'tags-completion-table) nil)
  (set (make-local-variable 'tags-included-tables) nil)
  ;; We used to initialize find-tag-marker-ring and tags-location-ring
  ;; here, to new empty rings.  But that is wrong, because those

	  ;; Record the tags-table-list value (and the context of the
	  ;; current directory) we computed from.
	  (setq tags-table-computed-list-for compute-for
		tags-table-computed-list (nreverse computed))))))

;; Extend `tags-table-computed-list' to remove the first `t' placeholder.
;; An element of the list that is `t' is a placeholder indicating that the
;; preceding element is a table that has not been read into core and might
;; contain included tables to search.  On return, the first placeholder
;; element will be gone and the element before it read into core and its
;; included tables inserted into the list.
(defun tags-table-extend-computed-list ()
  (let ((list tags-table-computed-list))
    (while (not (eq (nth 1 list) t))
      (setq list (cdr list)))
    (save-excursion
      (if (tags-verify-table (car list))

	    ;; current list.
	    (setcdr list (nconc computed (cdr (cdr list)))))
	;; It was not a valid table, so just remove the following placeholder.
	(setcdr list (cdr (cdr list)))))))

;; Expand tags table name FILE into a complete file name.
(defun tags-expand-table-name (file)
  (setq file (expand-file-name file))
  (if (file-directory-p file)
      (expand-file-name "TAGS" file)
    file))

;; Like member, but comparison is done after tags-expand-table-name on both
;; sides and elements of LIST that are t are skipped.
(defun tags-table-list-member (file list)
  (setq file (tags-expand-table-name file))
  (while (and list
	      (or (eq (car list) t)
		  (not (string= file (tags-expand-table-name (car list))))))
    (setq list (cdr list)))

;; does).  Return the name of the first table table listing THIS-FILE; if
;; the table is one included by another table, it is the master table that
;; we return.  If CORE-ONLY is non-nil, check only tags tables that are
;; already in buffers--don't visit any new files.
(defun tags-table-including (this-file core-only)
  (let ((tables tags-table-computed-list)
	(found nil))
    ;; Loop over the list, looking for a table containing tags for THIS-FILE.
    (while (and (not found)
		tables)

	  ;; The last element we found in the computed list before FOUND
	  ;; that appears in the user's list will be the table that
	  ;; included the one we found.
	  could-be))))

;; Subroutine of visit-tags-table-buffer.  Move tags-table-list-pointer
;; along and set tags-file-name.  Returns nil when out of tables.
(defun tags-next-table ()
  ;; If there is a placeholder element next, compute the list to replace it.
  (while (eq (nth 1 tags-table-list-pointer) t)
    (tags-table-extend-computed-list))

  ;; Go to the next table in the list.

			      (setq tags-table-set-list
				    (cons tags-table-list
					  tags-table-set-list)))
			  ;; Clear out buffers holding old tables.
			  (dolist (table tags-table-list)
			    ;; The list can contain items `t'.
			    (if (stringp table)
				(let ((buffer (find-buffer-visiting table)))
			      (if buffer
				  (kill-buffer buffer)))))
			  (setq tags-table-list (list local-tags-file-name))))

  "Return a list of tags tables included by the current table.
Assumes the tags table is the current buffer."
  (or tags-included-tables
      (setq tags-included-tables (funcall tags-included-tables-function))))

;; Build tags-completion-table on demand.  The single current tags table
;; and its included tags tables (and their included tables, etc.) have
;; their tags included in the completion table.
(defun tags-completion-table ()
  (or tags-completion-table
      ;; No cached value for this buffer.
      (condition-case ()
	  (let (current-table combined-table)
	    (message "Making tags completion table for %s..." buffer-file-name)

	    ;; Cache the result a buffer-local variable.
	    (setq tags-completion-table combined-table))
	(quit (message "Tags completion table construction aborted.")
	      (setq tags-completion-table nil)))))

;; Completion function for tags.  Does normal try-completion,
;; but builds tags-completion-table on demand.
(defun tags-complete-tag (string predicate what)
  (save-excursion
    ;; If we need to ask for the tag table, allow that.
    (let ((enable-recursive-minibuffers t))
      (visit-tags-table-buffer))
    (if (eq what t)
	(all-completions string (tags-completion-table) predicate)
      (try-completion string (tags-completion-table) predicate))))

;; Read a tag name from the minibuffer with defaulting and completion.
(defun find-tag-tag (string)
  (let* ((completion-ignore-case (if (memq tags-case-fold-search '(t nil))
				     tags-case-fold-search
				   case-fold-search))
	 (default (funcall (or find-tag-default-function
			       (get major-mode 'find-tag-default-function)

      spec)))

(defvar last-tag nil
  "Last tag found by \\[find-tag].")

;; Get interactive args for find-tag{-noselect,-other-window,-regexp}.
(defun find-tag-interactive (prompt &optional no-default)
  (if (and current-prefix-arg last-tag)
      (list nil (if (< (prefix-numeric-value current-prefix-arg) 0)
		    '-
		  t))
    (list (if no-default
	      (read-string prompt)
	    (find-tag-tag prompt)))))

(defvar find-tag-history nil)

;; Dynamic bondage:
(eval-when-compile
  (defvar etags-case-fold-search)
  (defvar etags-syntax-table))

    (switch-to-buffer (or (marker-buffer marker)
                          (error "The marked buffer has been deleted")))
    (goto-char (marker-position marker))
    (set-marker marker nil nil)))

;; Internal tag finding function.

;; PATTERN is a string to pass to second arg SEARCH-FORWARD-FUNC, and to
;; any member of the function list ORDER (third arg).  If ORDER is nil,
;; use saved state to continue a previous search.

;; Fourth arg NEXT-LINE-AFTER-FAILURE-P is non-nil if after a failed match,
;; point should be moved to the next line.

;; Fifth arg MATCHING is a string, an English '-ing' word, to be used in
;; an error message.

;; Algorithm is as follows.  For each qualifier-func in ORDER, go to
;; beginning of tags file, and perform inner loop: for each naive match for
;; PATTERN found using SEARCH-FORWARD-FUNC, qualify the naive match using
;; qualifier-func.  If it qualifies, go to the specified line in the
;; specified source file and return.  Qualified matches are remembered to
;; avoid repetition.  State is saved so that the loop can be continued.

(defvar tag-lines-already-matched nil)	;matches remembered here between calls

(defun find-tag-in-order (pattern
			  search-forward-func
			  order
			  next-line-after-failure-p
			  matching
			  first-search)
  (let (file				;name of file containing tag
	tag-info			;where to find the tag in FILE
	(first-table t)
	(tag-order order)
	(match-marker (make-marker))

      ;; Return the buffer where the tag was found.
      (current-buffer))))

(defun tag-find-file-of-tag-noselect (file)
  ;; Find the right line in the specified file.
  ;; If we are interested in compressed-files,
  ;; we search files with extensions.
  ;; otherwise only the real file.
  (let* ((buffer-search-extensions (if (featurep 'jka-compr)
				       tags-compression-info-list
				     '("")))
	 the-buffer
	 (file-search-extensions buffer-search-extensions))

	(if (featurep 'jka-compr)
	    (error "File %s (with or without extensions %s) not found" file tags-compression-info-list)
	  (error "File %s not found" file))
      (set-buffer the-buffer))))

(defun tag-find-file-of-tag (file)
  (let ((buf (tag-find-file-of-tag-noselect file)))
    (condition-case nil
	(switch-to-buffer buf)
      (error (pop-to-buffer buf)))))

;; `etags' TAGS file format support.

;; If the current buffer is a valid etags TAGS file, give it local values of
;; the tags table format variables, and return non-nil.
(defun etags-recognize-tags-table ()
  (and (etags-verify-tags-table)
       ;; It is annoying to flash messages on the screen briefly,
       ;; and this message is not useful.  -- rms
       ;; (message "%s is an `etags' TAGS file" buffer-file-name)
       (mapc (lambda (elt) (set (make-local-variable (car elt)) (cdr elt)))

(defun etags-verify-tags-table ()
  "Return non-nil if the current buffer is a valid etags TAGS file."
  ;; Use eq instead of = in case char-after returns nil.
  (eq (char-after (point-min)) ?\f))

(defun etags-file-of-tag (&optional relative)
  (save-excursion
    (re-search-backward "\f\n\\([^\n]+\\),[0-9]*\n")
    (let ((str (buffer-substring (match-beginning 1) (match-end 1))))
      (if relative
	  str
	(expand-file-name str
			  (file-truename default-directory))))))


(defun etags-tags-completion-table ()
  (let ((table (make-vector 511 0))
	(progress-reporter
	 (make-progress-reporter
	  (format "Making tags completion table for %s..." buffer-file-name)
	  (point-min) (point-max))))

			 (buffer-substring (match-beginning 3) (match-end 3)))
		  (progress-reporter-update progress-reporter (point)))
		table)))
    table))

(defun etags-snarf-tag (&optional use-explicit)
  (let (tag-text line startpos explicit-start)
    (if (save-excursion
	  (forward-line -1)
	  (looking-at "\f\n"))
	;; The match was for a source file name, not any tag within a file.

                                                   (point)))))))
    ;; Leave point on the next line of the tags file.
    (forward-line 1)
    (cons tag-text (cons line startpos))))

;; TAG-INFO is a cons (TEXT LINE . POSITION) where TEXT is the initial part
;; of a line containing the tag and POSITION is the character position of
;; TEXT within the file (starting from 1); LINE is the line number.  If
;; TEXT is t, it means the tag refers to exactly LINE or POSITION
;; (whichever is present, LINE having preference, no searching.  Either
;; LINE or POSITION may be nil; POSITION is used if present.  If the tag
;; isn't exactly at the given position then look around that position using
;; a search window which expands until it hits the start of file.
(defun etags-goto-tag-location (tag-info)
  (let ((startpos (cdr (cdr tag-info)))
	(line (car (cdr tag-info)))
	offset found pat)
    (if (eq (car tag-info) t)
	;; Direct file tag.

    (and (eq selective-display t)
	 (looking-at "\^m")
	 (forward-char 1))
    (beginning-of-line)))

(defun etags-list-tags (file)
  (goto-char (point-min))
  (when (re-search-forward (concat "\f\n" "\\(" file "\\)" ",") nil t)
    (let ((path (save-excursion (forward-line 1) (file-of-tag)))
	  ;; Get the local value in the tags table
	  ;; buffer before switching buffers.

	    (mapatoms ins-symb symbs)
	  (dolist (sy symbs)
	    (funcall ins-symb (car sy))))
        (sort-lines nil beg (point))))))

(defun etags-tags-apropos (string)
  (when tags-apropos-verbose
    (princ "Tags in file `")
    (tags-with-face 'highlight (princ buffer-file-name))
    (princ "':\n\n"))
  (goto-char (point-min))

      (terpri)
      (forward-line 1))
    (message nil))
  (when tags-apropos-verbose (princ "\n")))

(defun etags-tags-table-files ()
  (let ((files nil)
	beg)
    (goto-char (point-min))
    (while (search-forward "\f\n" nil t)
      (setq beg (point))

      (skip-chars-backward "^," beg)
      (or (looking-at "include$")
	  (setq files (cons (buffer-substring beg (1- (point))) files))))
    (nreverse files)))

(defun etags-tags-included-tables ()
  (let ((files nil)
	beg)
    (goto-char (point-min))
    (while (search-forward "\f\n" nil t)
      (setq beg (point))

			    files))))
    (nreverse files)))

;; Empty tags file support.

;; Recognize an empty file and give it local values of the tags table format
;; variables which do nothing.
(defun tags-recognize-empty-tags-table ()
  (and (zerop (buffer-size))
       (mapc (lambda (sym) (set (make-local-variable sym) 'ignore))
	     '(tags-table-files-function
	       tags-completion-table-function
	       find-tag-regexp-search-function

;;(put 'tags-with-syntax 'edebug-form-spec '(&rest form))

;; exact file name match, i.e. searched tag must match complete file
;; name including directories parts if there are some.
(defun tag-exact-file-name-match-p (tag)
  (and (looking-at ",[0-9\n]")
       (save-excursion (backward-char (+ 2 (length tag)))
		       (looking-at "\f\n"))))
;; file name match as above, but searched tag must match the file
;; name not including the directories if there are some.
(defun tag-file-name-match-p (tag)
  (and (looking-at ",[0-9\n]")
       (save-excursion (backward-char (1+ (length tag)))
		       (looking-at "/"))))
;; this / to detect we are after a directory separator is ok for unix,
;; is there a variable that contains the regexp for directory separator
;; on whatever operating system ?
;; Looks like ms-win will lose here :).

;; t if point is at a tag line that matches TAG exactly.
;; point should be just after a string that matches TAG.
(defun tag-exact-match-p (tag)
  ;; The match is really exact if there is an explicit tag name.
  (or (and (eq (char-after (point)) ?\001)
	   (eq (char-after (- (point) (length tag) 1)) ?\177))
      ;; We are not on the explicit tag name, but perhaps it follows.
      (looking-at (concat "[^\177\n]*\177" (regexp-quote tag) "\001"))))

;; t if point is at a tag line that has an implicit name.
;; point should be just after a string that matches TAG.
(defun tag-implicit-name-match-p (tag)
  ;; Look at the comment of the make_tag function in lib-src/etags.c for
  ;; a textual description of the four rules.
  (and (string-match "^[^ \t()=,;]+$" tag) ;rule #1
       (looking-at "[ \t()=,;]?\177")	;rules #2 and #4
       (save-excursion

	 (looking-at "[\n \t()=,;]"))))	;rule #3

;; t if point is at a tag line that matches TAG as a symbol.
;; point should be just after a string that matches TAG.
(defun tag-symbol-match-p (tag)
  (and (looking-at "\\Sw.*\177") (looking-at "\\S_.*\177")
       (save-excursion
	 (backward-char (1+ (length tag)))
	 (and (looking-at "\\Sw") (looking-at "\\S_")))))

;; t if point is at a tag line that matches TAG as a word.
;; point should be just after a string that matches TAG.
(defun tag-word-match-p (tag)
  (and (looking-at "\\b.*\177")
       (save-excursion (backward-char (length tag))
		       (looking-at "\\b"))))

;; partial file name match, i.e. searched tag must match a substring
;; of the file name (potentially including a directory separator).
(defun tag-partial-file-name-match-p (tag)
  (and (looking-at ".*,[0-9\n]")
       (save-excursion (beginning-of-line)
                       (backward-char 2)
  		       (looking-at "\f\n"))))

;; t if point is in a tag line with a tag containing TAG as a substring.
(defun tag-any-match-p (tag)
  (looking-at ".*\177"))

;; t if point is at a tag line that matches RE as a regexp.
(defun tag-re-match-p (re)
  (save-excursion
    (beginning-of-line)
    (let ((bol (point)))
      (and (search-forward "\177" (save-excursion (end-of-line) (point)) t)
	   (re-search-backward re bol t)))))

			      ;; will see it.
			      (goto-char (match-beginning 0))))
	tags-loop-operate `(perform-replace ',from ',to t t ',delimited))
  (tags-loop-continue (or file-list-form t)))

(defun tags-complete-tags-table-file (string predicate what)
  (save-excursion
    ;; If we need to ask for the tag table, allow that.
    (let ((enable-recursive-minibuffers t))
      (visit-tags-table-buffer))
    (if (eq what t)

	(goto-char desired-point))
    (set-window-start (selected-window) 1 t))
  (set-buffer-modified-p nil)
  (select-tags-table-mode))

(defvar select-tags-table-mode-map
  (let ((map (make-sparse-keymap)))
    (set-keymap-parent map button-buffer-map)
    (define-key map "t" 'push-button)
    (define-key map " " 'next-line)
    (define-key map "\^?" 'previous-line)

91776:01d2b6c9032f

(defvar tags-included-tables-function nil
  "Function to do the work of `tags-included-tables' (which see).")
(defvar verify-tags-table-function nil
  "Function to return t if current buffer contains valid tags file.")

(defun initialize-new-tags-table ()
  "Initialize the tags table in the current buffer.
Return non-nil if it is a valid tags table, and
in that case, also make the tags table state variables 
buffer-local and set them to nil."
  (set (make-local-variable 'tags-table-files) nil)
  (set (make-local-variable 'tags-completion-table) nil)
  (set (make-local-variable 'tags-included-tables) nil)
  ;; We used to initialize find-tag-marker-ring and tags-location-ring
  ;; here, to new empty rings.  But that is wrong, because those

	  ;; Record the tags-table-list value (and the context of the
	  ;; current directory) we computed from.
	  (setq tags-table-computed-list-for compute-for
		tags-table-computed-list (nreverse computed))))))

(defun tags-table-extend-computed-list ()
  "Extend `tags-table-computed-list' to remove the first t placeholder.

An element of the list that is t is a placeholder indicating that the
preceding element is a table that has not been read in and might
contain included tables to search.  This function reads in the first
such table and puts its included tables into the list."
  (let ((list tags-table-computed-list))
    (while (not (eq (nth 1 list) t))
      (setq list (cdr list)))
    (save-excursion
      (if (tags-verify-table (car list))

	    ;; current list.
	    (setcdr list (nconc computed (cdr (cdr list)))))
	;; It was not a valid table, so just remove the following placeholder.
	(setcdr list (cdr (cdr list)))))))

(defun tags-expand-table-name (file)
  "Expand tags table name FILE into a complete file name."
  (setq file (expand-file-name file))
  (if (file-directory-p file)
      (expand-file-name "TAGS" file)
    file))

;; Like member, but comparison is done after tags-expand-table-name on both
;; sides and elements of LIST that are t are skipped.
(defun tags-table-list-member (file list)
  "Like (member FILE LIST) after applying `tags-expand-table-name'.
More precisely, apply `tags-expand-table-name' to FILE
and each element of LIST, returning the link whose car is the first match.
If an element of LIST is t, ignore it."
  (setq file (tags-expand-table-name file))
  (while (and list
	      (or (eq (car list) t)
		  (not (string= file (tags-expand-table-name (car list))))))
    (setq list (cdr list)))

;; does).  Return the name of the first table table listing THIS-FILE; if
;; the table is one included by another table, it is the master table that
;; we return.  If CORE-ONLY is non-nil, check only tags tables that are
;; already in buffers--don't visit any new files.
(defun tags-table-including (this-file core-only)
  "Search current tags tables for tags for THIS-FILE.
Subroutine of `visit-tags-table-buffer'.
Looks for a tags table that has such tags or that includes a table
that has them.  Returns the name of the first such table.
Non-nil CORE-ONLY means check only tags tables that are already in
buffers.  Nil CORE-ONLY is ignored."
  (let ((tables tags-table-computed-list)
	(found nil))
    ;; Loop over the list, looking for a table containing tags for THIS-FILE.
    (while (and (not found)
		tables)

	  ;; The last element we found in the computed list before FOUND
	  ;; that appears in the user's list will be the table that
	  ;; included the one we found.
	  could-be))))

(defun tags-next-table ()
  "Move `tags-table-list-pointer' along and set `tags-file-name'.
Subroutine of `visit-tags-table-buffer'.\
Returns nil when out of tables."
  ;; If there is a placeholder element next, compute the list to replace it.
  (while (eq (nth 1 tags-table-list-pointer) t)
    (tags-table-extend-computed-list))

  ;; Go to the next table in the list.

			      (setq tags-table-set-list
				    (cons tags-table-list
					  tags-table-set-list)))
			  ;; Clear out buffers holding old tables.
			  (dolist (table tags-table-list)
			    ;; The list can contain items t.
			    (if (stringp table)
				(let ((buffer (find-buffer-visiting table)))
			      (if buffer
				  (kill-buffer buffer)))))
			  (setq tags-table-list (list local-tags-file-name))))

  "Return a list of tags tables included by the current table.
Assumes the tags table is the current buffer."
  (or tags-included-tables
      (setq tags-included-tables (funcall tags-included-tables-function))))

(defun tags-completion-table ()
  "Build `tags-completion-table' on demand.
The tags included in the completion table are those in the current
tags table and its (recursively) included tags tables."
  (or tags-completion-table
      ;; No cached value for this buffer.
      (condition-case ()
	  (let (current-table combined-table)
	    (message "Making tags completion table for %s..." buffer-file-name)

	    ;; Cache the result a buffer-local variable.
	    (setq tags-completion-table combined-table))
	(quit (message "Tags completion table construction aborted.")
	      (setq tags-completion-table nil)))))

(defun tags-complete-tag (string predicate what)
  "Completion function for tags.
Does normal `try-completion', but builds `tags-completion-table' on
demand."
  (save-excursion
    ;; If we need to ask for the tag table, allow that.
    (let ((enable-recursive-minibuffers t))
      (visit-tags-table-buffer))
    (if (eq what t)
	(all-completions string (tags-completion-table) predicate)
      (try-completion string (tags-completion-table) predicate))))

(defun find-tag-tag (string)
  "Read a tag name, with defaulting and completion."
  (let* ((completion-ignore-case (if (memq tags-case-fold-search '(t nil))
				     tags-case-fold-search
				   case-fold-search))
	 (default (funcall (or find-tag-default-function
			       (get major-mode 'find-tag-default-function)

      spec)))

(defvar last-tag nil
  "Last tag found by \\[find-tag].")

(defun find-tag-interactive (prompt &optional no-default)
  "Get interactive arguments for tag functions.
The functions using this are `find-tag-noselect',
`find-tag-other-window', and `find-tag-regexp'."
  (if (and current-prefix-arg last-tag)
      (list nil (if (< (prefix-numeric-value current-prefix-arg) 0)
		    '-
		  t))
    (list (if no-default
	      (read-string prompt)
	    (find-tag-tag prompt)))))

(defvar find-tag-history nil) ; Doc string?

;; Dynamic bondage:
(eval-when-compile
  (defvar etags-case-fold-search)
  (defvar etags-syntax-table))

    (switch-to-buffer (or (marker-buffer marker)
                          (error "The marked buffer has been deleted")))
    (goto-char (marker-position marker))
    (set-marker marker nil nil)))

(defvar tag-lines-already-matched nil
  "Matches remembered between calls.") ; Doc string: calls to what?

(defun find-tag-in-order (pattern
			  search-forward-func
			  order
			  next-line-after-failure-p
			  matching
			  first-search)
  "Internal tag-finding function.
PATTERN is a string to pass to arg SEARCH-FORWARD-FUNC, and to any
member of the function list ORDER.  If ORDER is nil, use saved state
to continue a previous search.

Arg NEXT-LINE-AFTER-FAILURE-P is non-nil if after a failed match,
point should be moved to the next line.

Arg MATCHING is a string, an English `-ing' word, to be used in an
error message."
;; Algorithm is as follows:
;; For each qualifier-func in ORDER, go to beginning of tags file, and
;; perform inner loop: for each naive match for PATTERN found using
;; SEARCH-FORWARD-FUNC, qualify the naive match using qualifier-func.  If
;; it qualifies, go to the specified line in the specified source file
;; and return.  Qualified matches are remembered to avoid repetition.
;; State is saved so that the loop can be continued.
  (let (file				;name of file containing tag
	tag-info			;where to find the tag in FILE
	(first-table t)
	(tag-order order)
	(match-marker (make-marker))

      ;; Return the buffer where the tag was found.
      (current-buffer))))

(defun tag-find-file-of-tag-noselect (file)
  "Find the right line in the specified FILE."
  ;; If interested in compressed-files, search files with extensions.
  ;; Otherwise, search only the real file.
  (let* ((buffer-search-extensions (if (featurep 'jka-compr)
				       tags-compression-info-list
				     '("")))
	 the-buffer
	 (file-search-extensions buffer-search-extensions))

	(if (featurep 'jka-compr)
	    (error "File %s (with or without extensions %s) not found" file tags-compression-info-list)
	  (error "File %s not found" file))
      (set-buffer the-buffer))))

(defun tag-find-file-of-tag (file) ; Doc string?
  (let ((buf (tag-find-file-of-tag-noselect file)))
    (condition-case nil
	(switch-to-buffer buf)
      (error (pop-to-buffer buf)))))

;; `etags' TAGS file format support.

(defun etags-recognize-tags-table ()
  "If `etags-verify-tags-table', make buffer-local format variables.
If current buffer is a valid etags TAGS file, then give it
buffer-local values of tags table format variables."
  (and (etags-verify-tags-table)
       ;; It is annoying to flash messages on the screen briefly,
       ;; and this message is not useful.  -- rms
       ;; (message "%s is an `etags' TAGS file" buffer-file-name)
       (mapc (lambda (elt) (set (make-local-variable (car elt)) (cdr elt)))

(defun etags-verify-tags-table ()
  "Return non-nil if the current buffer is a valid etags TAGS file."
  ;; Use eq instead of = in case char-after returns nil.
  (eq (char-after (point-min)) ?\f))

(defun etags-file-of-tag (&optional relative) ; Doc string?
  (save-excursion
    (re-search-backward "\f\n\\([^\n]+\\),[0-9]*\n")
    (let ((str (buffer-substring (match-beginning 1) (match-end 1))))
      (if relative
	  str
	(expand-file-name str
			  (file-truename default-directory))))))


(defun etags-tags-completion-table () ; Doc string?
  (let ((table (make-vector 511 0))
	(progress-reporter
	 (make-progress-reporter
	  (format "Making tags completion table for %s..." buffer-file-name)
	  (point-min) (point-max))))

			 (buffer-substring (match-beginning 3) (match-end 3)))
		  (progress-reporter-update progress-reporter (point)))
		table)))
    table))

(defun etags-snarf-tag (&optional use-explicit) ; Doc string?
  (let (tag-text line startpos explicit-start)
    (if (save-excursion
	  (forward-line -1)
	  (looking-at "\f\n"))
	;; The match was for a source file name, not any tag within a file.

                                                   (point)))))))
    ;; Leave point on the next line of the tags file.
    (forward-line 1)
    (cons tag-text (cons line startpos))))

(defun etags-goto-tag-location (tag-info)
  "Go to location of tag specified by TAG-INFO.
TAG-INFO is a cons (TEXT LINE . POSITION).
TEXT is the initial part of a line containing the tag.
LINE is the line number.
POSITION is the (one-based) char position of TEXT within the file.

If TEXT is t, it means the tag refers to exactly LINE or POSITION,
whichever is present, LINE having preference, no searching.
Either LINE or POSITION can be nil.  POSITION is used if present.

If the tag isn't exactly at the given position, then look near that
position using a search window that expands progressively until it
hits the start of file."
  (let ((startpos (cdr (cdr tag-info)))
	(line (car (cdr tag-info)))
	offset found pat)
    (if (eq (car tag-info) t)
	;; Direct file tag.

    (and (eq selective-display t)
	 (looking-at "\^m")
	 (forward-char 1))
    (beginning-of-line)))

(defun etags-list-tags (file) ; Doc string?
  (goto-char (point-min))
  (when (re-search-forward (concat "\f\n" "\\(" file "\\)" ",") nil t)
    (let ((path (save-excursion (forward-line 1) (file-of-tag)))
	  ;; Get the local value in the tags table
	  ;; buffer before switching buffers.

	    (mapatoms ins-symb symbs)
	  (dolist (sy symbs)
	    (funcall ins-symb (car sy))))
        (sort-lines nil beg (point))))))

(defun etags-tags-apropos (string) ; Doc string?
  (when tags-apropos-verbose
    (princ "Tags in file `")
    (tags-with-face 'highlight (princ buffer-file-name))
    (princ "':\n\n"))
  (goto-char (point-min))

      (terpri)
      (forward-line 1))
    (message nil))
  (when tags-apropos-verbose (princ "\n")))

(defun etags-tags-table-files () ; Doc string?
  (let ((files nil)
	beg)
    (goto-char (point-min))
    (while (search-forward "\f\n" nil t)
      (setq beg (point))

      (skip-chars-backward "^," beg)
      (or (looking-at "include$")
	  (setq files (cons (buffer-substring beg (1- (point))) files))))
    (nreverse files)))

(defun etags-tags-included-tables () ; Doc string?
  (let ((files nil)
	beg)
    (goto-char (point-min))
    (while (search-forward "\f\n" nil t)
      (setq beg (point))

			    files))))
    (nreverse files)))

;; Empty tags file support.

(defun tags-recognize-empty-tags-table ()
  "Return non-nil if current buffer is empty.
If empty, make buffer-local values of the tags table format variables
that do nothing."
  (and (zerop (buffer-size))
       (mapc (lambda (sym) (set (make-local-variable sym) 'ignore))
	     '(tags-table-files-function
	       tags-completion-table-function
	       find-tag-regexp-search-function

;;(put 'tags-with-syntax 'edebug-form-spec '(&rest form))

;; exact file name match, i.e. searched tag must match complete file
;; name including directories parts if there are some.
(defun tag-exact-file-name-match-p (tag)
  "Return non-nil if TAG matches complete file name.
Any directory part of the file name is also matched."
  (and (looking-at ",[0-9\n]")
       (save-excursion (backward-char (+ 2 (length tag)))
		       (looking-at "\f\n"))))

;; file name match as above, but searched tag must match the file
;; name not including the directories if there are some.
(defun tag-file-name-match-p (tag)
  "Return non-nil if TAG matches file name, excluding directory part."
  (and (looking-at ",[0-9\n]")
       (save-excursion (backward-char (1+ (length tag)))
		       (looking-at "/"))))

;; this / to detect we are after a directory separator is ok for unix,
;; is there a variable that contains the regexp for directory separator
;; on whatever operating system ?
;; Looks like ms-win will lose here :).

;; t if point is at a tag line that matches TAG exactly.
;; point should be just after a string that matches TAG.
(defun tag-exact-match-p (tag)
  "Return non-nil if current tag line matches TAG exactly.
Point should be just after a string that matches TAG."
  ;; The match is really exact if there is an explicit tag name.
  (or (and (eq (char-after (point)) ?\001)
	   (eq (char-after (- (point) (length tag) 1)) ?\177))
      ;; We are not on the explicit tag name, but perhaps it follows.
      (looking-at (concat "[^\177\n]*\177" (regexp-quote tag) "\001"))))

;; t if point is at a tag line that has an implicit name.
;; point should be just after a string that matches TAG.
(defun tag-implicit-name-match-p (tag)
  "Return non-nil if current tag line has an implicit name.
Point should be just after a string that matches TAG."
  ;; Look at the comment of the make_tag function in lib-src/etags.c for
  ;; a textual description of the four rules.
  (and (string-match "^[^ \t()=,;]+$" tag) ;rule #1
       (looking-at "[ \t()=,;]?\177")	;rules #2 and #4
       (save-excursion

	 (looking-at "[\n \t()=,;]"))))	;rule #3

;; t if point is at a tag line that matches TAG as a symbol.
;; point should be just after a string that matches TAG.
(defun tag-symbol-match-p (tag)
  "Return non-nil if current tag line matches TAG as a symbol.
Point should be just after a string that matches TAG."
  (and (looking-at "\\Sw.*\177") (looking-at "\\S_.*\177")
       (save-excursion
	 (backward-char (1+ (length tag)))
	 (and (looking-at "\\Sw") (looking-at "\\S_")))))

;; t if point is at a tag line that matches TAG as a word.
;; point should be just after a string that matches TAG.
(defun tag-word-match-p (tag)
  "Return non-nil if current tag line matches TAG as a word.
Point should be just after a string that matches TAG."
  (and (looking-at "\\b.*\177")
       (save-excursion (backward-char (length tag))
		       (looking-at "\\b"))))

;; partial file name match, i.e. searched tag must match a substring
;; of the file name (potentially including a directory separator).
(defun tag-partial-file-name-match-p (tag)
  "Return non-nil if current tag matches file name.
This is a substring match, and it can include directory separators.
Point should be just after a string that matches TAG."
  (and (looking-at ".*,[0-9\n]")
       (save-excursion (beginning-of-line)
                       (backward-char 2)
  		       (looking-at "\f\n"))))

;; t if point is in a tag line with a tag containing TAG as a substring.
(defun tag-any-match-p (tag)
  "Return non-nil if current tag line contains TAG as a substring."
  (looking-at ".*\177"))

;; t if point is at a tag line that matches RE as a regexp.
(defun tag-re-match-p (re)
  "Return non-nil if current tag line matches regexp RE."
  (save-excursion
    (beginning-of-line)
    (let ((bol (point)))
      (and (search-forward "\177" (save-excursion (end-of-line) (point)) t)
	   (re-search-backward re bol t)))))

			      ;; will see it.
			      (goto-char (match-beginning 0))))
	tags-loop-operate `(perform-replace ',from ',to t t ',delimited))
  (tags-loop-continue (or file-list-form t)))

(defun tags-complete-tags-table-file (string predicate what) ; Doc string?
  (save-excursion
    ;; If we need to ask for the tag table, allow that.
    (let ((enable-recursive-minibuffers t))
      (visit-tags-table-buffer))
    (if (eq what t)

	(goto-char desired-point))
    (set-window-start (selected-window) 1 t))
  (set-buffer-modified-p nil)
  (select-tags-table-mode))

(defvar select-tags-table-mode-map ; Doc string?
  (let ((map (make-sparse-keymap)))
    (set-keymap-parent map button-buffer-map)
    (define-key map "t" 'push-button)
    (define-key map " " 'next-line)
    (define-key map "\^?" 'previous-line)