Description

Vtags stands for Very fast tags for emacs. Vtags is elisp code to search and parse sorted ctags files. It is intended as a replacement for the current etags package.

Introduction

What are tags? If you are a software developer you are probably already familiar with ctags and etags. For the benefit of those unfamiliar with the concept here is the description paraphrased from the ctags manual:
The ctags and etags programs generate an index (or "tag") file for a variety of language objects found in file(s). This tag file allows these items to be quickly and easily located by a text editor or other utility. A "tag" signifies a language object for which an index entry is available (or, alternatively, the index entry created for that object).
The tags generated by ctags are recognized by a wide variety of text editors, most notably Vi and its derivatives, but not Emacs which uses the tag file format generated by etags.

On large projects it is not unusual to have multi-MB tag files. One of the main drawbacks of etags is that the tags are not sorted so that tag lookup is linear and slow. Another shortcoming of using etags and Emacs is that the entire tag file is loaded into memory, which, when combined with the linear search, leads to interminable garbage collection and memory exhaustion. The vtags project addresses these issues. It does a binary search without reading the entire tag file into memory.

Currently, vtags has the following basic functionality:

The main functions are: 
     vtags-find                     - Find tag whose name contains TAGNAME.
     vtags-next-placeholder         - go up in tag stack
     vtags-prev-placeholder         - go down in tag stack
     vtags-set-tagfile              - set the tag file used by vtags-find
One of the main features of vtags is that it is implemented entirely in elisp. There are no OS dependencies and no auxiliary applications to compile.

Vtags has been tested with several versions of Emacs, up-to and including GNU Emacs 21.2.1 and XEmacs 21.4, using output from Exuberant Ctags 5.2.2.

Related Links

Exuberant Ctags

GNU GLOBAL source code tag system

Implementation notes

Summary

The source code for vtags is fairly self-explanatory ... BWA-HA-HA-HA, heh, heh. OK, here is a brief outline: vtags-find calls vtags-look which does the binary search. During the search a buffer named *Vtags-Look-Buffer* is used as working area for storing chunks of the tag file. Matching entries are stored in the buffer named *Vtags-Buffer*. If only one entry matches, then vtags-source is called. vtags-source parses the entry and calls find-file. If more than one entry matches, then the user is presented with the matching entries in *Vtags-Buffer*. The buffer is in vtags-mode. In this mode entries can be selected by 'f', RET, or mouse-button-2. Selecting an entry causes vtags-source to parse the entry and call find-file.

Binary search

The binary search portion of vtags originally relied on the "look" program available on most Unix platforms. The program was called like this 

     (shell-command (concat  "look "  tagname " " tag-path ) t))
from within vtags-find and the output was dumped into a buffer and parsed. However, for aesthetics and for portability and to avoid the overhead of "shell-command", we decided to re-implement that portion in elisp and we called the new function vtags-look. The vtags-look function uses binary search until the search is narrowed to a single 8192 byte block of memory, at which point it continues with a linear search.

Key bindings

There are no default key binding for vtags. Add the following to your startup file (e.g. .emacs) with the [ ]'s filled in with whatever function keys you chose and with path set to point to your tags file: 

;        (load "/path/to/vtags")
;        (vtags-set-tagfile "/path/to/my/tags")
;        (global-set-key [f5] 'vtags-find);        
;        (global-set-key [f6] 'vtags-prev-placeholder)
;        (global-set-key [f7] 'vtags-goto-current-placeholder)
;        (global-set-key [f8] 'vtags-next-placeholder)
;        (global-set-key [f9] 'vtags-point-to-placeholder)
;        (global-set-key [f10] 'vtags-reset-placeholders)


      Copyright (c)  2004-2005 Edward Bishop
      Permission is granted to copy, distribute and/or modify this document
      under the terms of the GNU Free Documentation License, Version 1.2
      or any later version published by the Free Software Foundation;
      with no Invariant Sections, no Front-Cover Texts, and no Back-Cover
	 Texts.  A copy of the license is included in the section entitled "GNU
      Free Documentation License".