21.11.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’) is like ‘--regex’, except that the regular expression provided will be matched without regard to case, which is appropriate for various 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.

A regular expression can be bound to a given language, by prepending it with ‘{lang}’. When you do this, etags will use the regular expression only for files of that language. ‘etags --help’ prints the list of languages recognised by etags. The following example tags the DEFVAR macros in the Emacs source files. etags applies this regular expression to C files only:

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

This feature is particularly useful when storing 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. This means that such files can be nested. All the other lines are taken to be regular expressions. For example, one can create a file called ‘emacs.tags’ with the following contents (the first line in the file is a comment):

        -- This is for GNU Emacs 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 <script-name>’ if you want to jump to it.

• Tag Tcl files:

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

• Tag VHDL files:

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