etags揭秘

etags是一个索引源代码的工具，经过一段时间的使用，发现某些行为与手册上的描述不一致，还有一些地方的描述比较模糊。通过阅读源代码，发现了一些不曾出现在手册上的规则，也明白了一些原来感觉很模糊的地方。

etags分为两个部分：可执行程序etags，由lib-src/etags.c编译而来，用于扫描源代码，生成TAGS文件；etags.el是Emacs的一部分，它使用TAGS文件来完成定位、查找等各项工作。

生成TAGS文件

生成TAGS文件的方式很简单，比如给Emacs源代码生成TAGS文件

$ etags src/*.[hc] lib-src/*.[hc] lib/*.[hc] \
    lisp/*.el lisp/*/*.el

这条命令在当前目录生成一个TAGS文件。

另外一种复杂的方式是生成多个TAGS文件，然后使用--include生成一个主文件，如

$ for dir in src lib-src lib; do \
    pushed $dir; \
    etags *.[hc] -o TAGS.sub; \
    INCLUDES="$INCLUDES --include $PWD/TAGS.sub"; \
    popd \
  done

$ for dir in lisp lisp/*; do \
    pushd $dir; \
    etags *.[hc] -o TAGS.sub; \
    INCLUDES="$INCLUDES --include $PWD/TAGS.sub"; \
    popd \
  done

$ etags -o TAGS $INCLUDES

按照手册的说法，使用这两种方式生成的TAGS文件的效果应该是一样的。然而在实际使用中，我发现它们的行为有较大差别，至少对于部分命令如此，根据我的感受，推荐使用第一种方式生成TAGS文件，第二种方式的体验较差。

首先是find-tag命令，使用第一种方式生成的TAGS文件能够更快定位，而第二种方式则需要更多次地用C-u M-.查找。

其次是list-tags命令，第一种方式可以正常工作，而第二种则完全不能工作，因为list-tags只查找在主TAGS文件里引用的那些文件，然而这个TAGS里只有include指令，没有引用任何源文件，因此甚至没法完成输入（我个人认为这是个bug），如下图：

使用TAGS文件

在Emacs里运行M-x visit-tags-table RET，然后输入TAGS文件路径即可。Emacs将这个文件放在一个buffer里面，并将major mode设置为tags-table-mode。在使用过程中，我们并不会直接使用这个buffer，而是通过一系列命令（比如find-tag）间接使用它。

如果我们希望切换到另一个项目的TAGS文件，比如从Emacs切换到gcc，那么只需要再次调用M-x visit-tags-table并读入gcc相关的TAGS文件即可。需要注意的是，在第二次（以及之后）调用visit-tags-table的时候，会被询问：

Keep current list of tags tables also? (y or n)

这时需要回答n。之后Emacs会显示一条信息：

Starting a new list of tags tables

这时我们再使用任何etags命令，就只操作在gcc的TAGS文件上，Emacs的TAGS文件不会参与任何操作。如果想切换回Emacs的TAGS文件，只需调用select-tags-table，然后按照提示在相应TAGS文件上按t键即可。

那我们如果回答y会如何呢？在这种情况下，Emacs的TAGS文件和gcc的TAGS文件会同时参与etags命令。具体的影响可能有以下几种：

tag数量增大，使得etags命令执行时间变长，响应迟钝；
如果两个TAGS文件里面有类似或相同的tag，则会严重影响使用体验；

因此，如果没有特殊的需求，最好不要合并不同项目的TAGS文件。

理解了TAGS文件、文件集合和集合的集合这三个概念，就可以根据自己需要，选择回答y还是n。

TAGS文件（tags-file-name）: 初始值为用户创建的TAGS文件，如："/home/liang/src/gcc/4.6.1/TAGS"。如果是用上述第二种方式创建的，在使用过程中tags-file-name的值可能会发生改变，它指向当前正在访问的TAGS文件。
文件集合（tags-table-list）: 在回答 “Keep current list of tags tables also?” 时选择y而合并了不同项目的TAGS文件而形成的集合，如：("/home/liang/project/emacs/trunk/TAGS" "/home/liang/src/gcc/4.6.1/TAGS")
集合的集合（tags-table-set-list）: 在回答 “Keep current list of tags tables also?” 时选择n，而将之前的文件集合搁置，重新组建新的文件集合，这些文件的集合放在一起，就是集合的集合。从数据结构上来说，它就是tags-table-list可能取值的集合。如：(("/home/liang/project/emacs/trunk/TAGS" "/home/liang/src/gcc/4.6.1/TAGS") ("/home/liang/project/go/go/src/TAGS") ("/home/liang/src/gcc/4.6.1/TAGS"))

TAGS文件格式

TAGS文件不一定非要用etags程序生成，如果理解了它的文件格式，自己手写一个，照样能用，或者另外写个程序生成也可以。具体的格式描述参见源代码下的etc/ETAGS.EBNF文件。这里面有两个概念非常重要，即：explicit tag name和implicit tag name。etags程序会尽量使用implicit tag name，以减小TAGS文件的大小。所以我们在生成TAGS文件的时候，也应该尽量遵守这个规则，毕竟文件越小，响应越快。

implict tag name的例子如下：

find_base_value ^?998,33275

explicit tag name的例子如下：

static char *reg_seen;^?reg_seen^A1175,38518

其中^?和^A是分隔符，分别对应字符\177和\001。后面两个数字分别为行号和行首字符位置。

判断是否可以使用implicit tag name的规则如下（摘自etags.c）：

 * make_tag creates tags with "implicit tag names" (unnamed tags)
 * if the following are all true, assuming NONAM=" \f\t\n\r()=,;":
 *  1. NAME does not contain any of the characters in NONAM;
 *  2. LINESTART contains name as either a rightmost, or rightmost but
 *     one character, substring;
 *  3. the character, if any, immediately before NAME in LINESTART must
 *     be a character in NONAM;
 *  4. the character, if any, immediately after NAME in LINESTART must
 *     also be a character in NONAM.

由于reg_seen左边的字符为*，不属于NONAM，不符合生成implicit tag name的规则，所以必须生成explicit tag name，即之后重复出现的reg_seen部分。

索引etags不认识的语言

etags默认支持多种编程语言或者文档结构，在这种情况下，etags能够根据上述规则尽量使用implicit tag name。对于etags不支持的语言，我们可以使用--regex选项来指导etags生成TAGS文件，这时就要我们自己注意，在能够使用implicit tag name的情况下尽量使用，以减小文件大小。当然，生成更多的explicit tag name并不会产生任何正确性的问题。

下面的例子是用来索引go源程序的：

$ find . -name "*.go" | \
etags --language=none \
    --regex='/type[ \t]+[^ \t]+[ \t]/' \
    --regex='/func[ \t]+[^( \t]+[( \t]/' \
    --regex='/func[ \t]+([ \t]*[^( \t]*[ \t]+\*?\([^) \t]+\)[ \t]*)[ \t]*\([^( \t]+\)[( \t]/\1.\2/' -

前面两个regex产生implicit tag name，最后一个regex生成explicit tag name，它生成的tag line如下：

func (url *URL) IsAbs(^?URL.IsAbs^A611,16231

也就是说，对于有receiver的函数，我们使用explicit tag name来进行更精确地定位，即通过M-x find-tag RET URL.IsAbs RET定位该函数的定义位置。

改进与BUG

我希望find-tag能够智能一点，比如在etags.c文件里运行M-x find-tag RET LOOKING_AT RET，不要跳到ebrowse.c文件里，而是定位到etags.c里的定义，即优先选择本文件里出现的tag。有人已经提出了类似的需求，但是一直没有实现。

另外，list-tags有个bug，不能正确处理explicit tag name，比如M-x list-tags RET src/buffer.c RET，然后在*Tags List* buffer的第三行按回车，会看到错误信息为

Rerun etags: `^current_buffer' not found in /User/wangliang/src/emacs/trunk/src/buffer.c

修改的方法很简单，patch如下：

diff --git a/lisp/progmodes/etags.el b/lisp/progmodes/etags.el
index d321e9c..f38af05 100644
--- a/lisp/progmodes/etags.el
+++ b/lisp/progmodes/etags.el
@@ -1409,7 +1409,7 @@ hits the start of file."
 	  tag tag-info pt)
     (forward-line 1)
     (while (not (or (eobp) (looking-at "\f")))
-      (setq tag-info (save-excursion (funcall snarf-tag-function t))
+      (setq tag-info (save-excursion (funcall snarf-tag-function nil))
 	    tag (car tag-info)
 	    pt (with-current-buffer standard-output (point)))
       (princ tag)

list-tags可以列出一个文件里的所有tag，所以我想是否可以把这个功能和Anything集成起来，实现类似anything+imenu的功能。通常来讲，anything+etags能够比anything+imenu获得更多的candidates。具体实现如下：

(defun wl-list-tags (file)
  (with-current-buffer (get-file-buffer tags-file-name)
    (goto-char (point-min))
    (when (re-search-forward
	   (concat "\f\n"
		   (if (< (length default-directory)
			  (length file))
		       (concat "\\(.*"
			       file
			       "\\|"
			       (substring file (length default-directory))
			       "\\)")
		     file)
		   ",") nil t)
      (let (tags)
	(forward-line 1)
	(while (not (or (eobp) (looking-at "\f")))
	  (add-to-list 'tags
		       (cons (car (save-excursion (funcall snarf-tag-function t)))
			     (save-excursion (funcall snarf-tag-function nil))))
	  (forward-line 1))
	tags))))

(defun wl-anything-c-etags-in-current-buffer ()
  (when (buffer-file-name)
    (let ((file (buffer-file-name))
	  (first-time t)
	  tags tmp)
      (while (visit-tags-table-buffer (not first-time))
	(setq first-time nil)
	(setq tmp (wl-list-tags file))
	(when tmp
	  (setq tags (append tmp tags))))
      tags)))

(defvar wl-anything-c-source-etags-in-current-buffer
  '((name . "Tags")
    (candidates . (lambda ()
		    (when (or tags-file-name
			      tags-table-list)
		      (with-current-buffer anything-current-buffer
			(wl-anything-c-etags-in-current-buffer)))))
    (action . (("Find tag" . (lambda (tag-info)
			       (etags-goto-tag-location tag-info)))))
    (persistent-action . (("Find tag" . (lambda (tag-info)
					  (etags-goto-tag-location tag-info)))))))

(defun wl-anything-etags-in-currect-buffer ()
  (interactive)
  (anything 'wl-anything-c-source-etags-in-current-buffer
            nil nil nil nil "*anything etags for buffer*"))

调用命令wl-anything-etags-in-currect-buffer，就可以列出当前buffer里面的所有tag，供选择定位。效果如图：

而wl-anything-c-source-etags-in-current-buffer作为一个symbol可以和其它source symbol组合起来使用，如：

(setq wl-anything-sources
      (append anything-for-files-prefered-list
	      '(anything-c-source-emacs-process
		anything-c-source-imenu
		wl-anything-c-source-etags-in-current-buffer)))

(defun wl-anything ()
  (interactive)
  (anything wl-anything-sources))

其实Anything默认已经集成了etags，只不过用法不一样，它显示TAGS文件里面的所有tag供选择，但是要求当前buffer对应的文件必须被TAGS文件索引，否则提示创建TAGS文件。

如果觉得传统的使用方式——M-.加C-u M-.——不爽，可以使用tags-apropos列出所有匹配正则表达式的tag，如果想限定到完全匹配的symbol，可以使用如下wl-etags-apropos-symbol命令：

(eval-after-load 'etags
  '(progn
     (defun wl-etags-apropos-symbol (tagname)
       (interactive (find-tag-interactive "Locate tag: "))
       (tags-apropos (concat "\\_<" tagname "\\_>")))))