Tag Syntax Tags Select Tags Table

20.13.2: Creating Tags Tables

The etags program is used to create a tags table file. It knows the syntax of several languages, as described in Tag Syntax. Here is how to run etags:

etags inputfiles...

The etags program reads the specified files, and writes a tags table named `TAGS' in the current working directory. etags recognizes the language used in an input file based on its file name and contents. You can specify the language with the `--language=name' option, described below.

If the tags table data become outdated due to changes in the files described in the table, the way to update the tags table is the same way it was made in the first place. It is not necessary to do this often.

If the tags table fails to record a tag, or records it for the wrong file, then Emacs cannot possibly find its definition. However, if the position recorded in the tags table becomes a little bit wrong (due to some editing in the file that the tag definition is in), the only consequence is a slight delay in finding the tag. Even if the stored position is very wrong, Emacs will still find the tag, but it must search the entire file for it.

So you should update a tags table when you define new tags that you want to have listed, or when you move tag definitions from one file to another, or when changes become substantial. Normally there is no need to update the tags table after each edit, or even every day.

One tags table can effectively include another. Specify the included tags file name with the `--include=file' option when creating the file that is to include it. The latter file then acts as if it contained all the files specified in the included file, as well as the files it directly contains.

If you specify the source files with relative file names when you run etags, the tags file will contain file names relative to the directory where the tags file was initially written. This way, you can move an entire directory tree containing both the tags file and the source files, and the tags file will still refer correctly to the source files.

If you specify absolute file names as arguments to etags, then the tags file will contain absolute file names. This way, the tags file will still refer to the same files even if you move it, as long as the source files remain in the same place. Absolute file names start with `/', or with `device:/' on MS-DOS and MS-Windows.

When you want to make a tags table from a great number of files, you may have problems listing them on the command line, because some systems have a limit on its length. The simplest way to circumvent this limit is to tell etags to read the file names from its standard input, by typing a dash in place of the file names, like this:

find . -name "*.[chCH]" -print | etags -

Use the option `--language=name' to specify the language explicitly. You can intermix these options with file names; each one applies to the file names that follow it. Specify `--language=auto' to tell etags to resume guessing the language from the file names and file contents. Specify `--language=none' to turn off language-specific processing entirely; then etags recognizes tags by regexp matching alone. `etags --help' prints the list of the languages etags knows, and the file name rules for guessing the language.

The `--regex' option provides a general way of recognizing tags based on regexp matching. You can freely intermix it with file names. Each `--regex' option adds to the preceding ones, and applies only to the following files. The syntax is:

--regex=/tagregexp[/nameregexp]/

where tagregexp is used to match the lines to tag. It is always anchored, that is, it behaves as if preceded by `^'. If you want to account for indentation, just match any initial number of blanks by beginning your regular expression with `[ \t]*'. In the regular expressions, `\' quotes the next character, and `\t' stands for the tab character. Note that etags does not handle the other C escape sequences for special characters.

The syntax of regular expressions in etags is the same as in Emacs, augmented with the interval operator, which works as in grep and ed. The syntax of an interval operator is `\{m,n\}', and its meaning is to match the preceding expression at least m times and up to n times.

You should not match more characters with tagregexp than that needed to recognize what you want to tag. If the match is such that more characters than needed are unavoidably matched by tagregexp, you may find useful to add a nameregexp, in order to narrow the tag scope. You can find some examples below.

The `-R' option deletes all the regexps defined with `--regex' options. It applies to the file names following it, as you can see from the following example:

etags --regex=/reg1/ voo.doo --regex=/reg2/ \
    bar.ber -R --lang=lisp los.er

Here etags chooses the parsing language for `voo.doo' and `bar.ber' according to their contents. etags also uses reg1 to recognize additional tags in `voo.doo', and both reg1 and reg2 to recognize additional tags in `bar.ber'. etags uses the Lisp tags rules, and no regexp matching, to recognize tags in `los.er'.

Here are some more examples. The regexps are quoted to protect them from shell interpretation.

• Tag the DEFVAR macros in the emacs source files:

  --regex='/[ \t]*DEFVAR_[A-Z_ \t(]+"\([^"]+\)"/'
  

• Tag VHDL files (this example is a single long line, broken here for formatting reasons):

  --language=none
  --regex='/[ \t]*\(ARCHITECTURE\|CONFIGURATION\) +[^ ]* +OF/'
  --regex='/[ \t]*\(ATTRIBUTE\|ENTITY\|FUNCTION\|PACKAGE\
  \( BODY\)?\|PROCEDURE\|PROCESS\|TYPE\)[ \t]+\([^ \t(]+\)/\3/'
  

• Tag Tcl files (this last example shows the usage of a nameregexp):

  --lang=none --regex='/proc[ \t]+\([^ \t]+\)/\1/'
  

For a list of the other available etags options, execute etags --help.

Tag Syntax

Tags

Select Tags Table