W.2.3 Etags Regexps

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 (as will usually be the case), you should add a nameregexp, to pick out just the tag. This will enable Emacs to find tags more accurately and to do completion on tag names more reliably. You can find some examples below.

The option `--ignore-case-regex' (or `-c') works like `--regex', except that matching ignores case. This is appropriate for certain programming languages.

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'.

You can specify a regular expression for a particular language, by writing `{lang}' in front of it. Then etags will use the regular expression only for files of that language. (`etags --help' prints the list of languages recognized by etags.) The following example tags the DEFVAR macros in the Emacs source files, for the C language only:

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

This feature is particularly useful when you store a list of regular expressions in a file. The following option syntax instructs etags to read two files of regular expressions. The regular expressions contained in the second file are matched without regard to case.

--regex=@first-file --ignore-case-regex=@second-file

A regex file contains one regular expressions per line. Empty lines, and lines beginning with space or tab are ignored. When the first character in a line is `@', etags assumes that the rest of the line is the name of a file of regular expressions; thus, one such file can include another file. All the other lines are taken to be regular expressions. If the first non-whitespace text on the line is `--', that line is a comment.

For example, one can create a file called `emacs.tags' with the following contents:

-- This is for GNU Emacs C source files {c}/[ \t]*DEFVAR_[A-Z_ \t(]+"\([^"]+\)"/\1/

and then use it like this:

etags --regex=@emacs.tags *.[ch] */*.[ch]

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

• Tag Octave files:

  etags --language=none \ --regex='/[ \t]*function.*=[ \t]*\([^ \t]*\)[ \t]*(/\1/' \ --regex='/###key \(.*\)/\1/' \ --regex='/[ \t]*global[ \t].*/' \ *.m

  Note that tags are not generated for scripts, so that you have to add a line by yourself of the form `###key scriptname' if you want to jump to it.

• Tag Tcl files:

  etags --language=none --regex='/proc[ \t]+\([^ \t]+\)/\1/' *.tcl

• Tag VHDL files:

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