# HG changeset patch # User Francesco Potort # Date 941474440 0 # Node ID 6651db4a4b1f3af46395d14a84d89fb36cb17670 # Parent 6119687f6888a1e12c2bc517ff8201f2e7c34dfd Document regexp changes in etags. diff -r 6119687f6888 -r 6651db4a4b1f etc/NEWS --- a/etc/NEWS Mon Nov 01 15:52:18 1999 +0000 +++ b/etc/NEWS Mon Nov 01 16:40:40 1999 +0000 @@ -386,11 +386,17 @@ *** In DOS, etags looks for file.cgz if it cannot find file.c. +*** New option --ignore-case-regex is an alternative to --regex. It is now + possible to bind a regexp to a language, by prepending the regexp with + {lang}, where lang is one of the languages that `etags --help' prints + out. This feature is useful especially for regex files, where each + line contains a regular expression. The manual contains details. + *** In C and derived languages, etags creates tags for function declarations when given the --declarations option. *** In C++, tags are created for "operator". The tags have the form -"operator+", without spaces between the keyword and the operator. +"operator+", without spaces between the keyword and the operator. *** New language Ada: tags are functions, procedures, packages, tasks, and types. @@ -409,8 +415,6 @@ *** .ss files are Scheme files. -*** New option --ignore-case-regex is an alternative to --regex. - ** Emacs now attempts to determine the initial language environment and preferred and locale coding systems systematically from the LC_ALL, LC_CTYPE, and LANG environment variables during startup. diff -r 6119687f6888 -r 6651db4a4b1f man/programs.texi --- a/man/programs.texi Mon Nov 01 15:52:18 1999 +0000 +++ b/man/programs.texi Mon Nov 01 16:40:40 1999 +0000 @@ -1604,7 +1604,7 @@ @menu * Tag Syntax:: Tag syntax for various types of code and text files. * Create Tags Table:: Creating a tags table with @code{etags}. -* Using Regexps:: Create arbitrary tags using regular expressions. +* Etags Regexps:: Create arbitrary tags using regular expressions. * Select Tags Table:: How to visit a tags table. * Find Tag:: Commands to find the definition of a specific tag. * Tags Search:: Using a tags table for searching and replacing. @@ -1804,9 +1804,9 @@ is to tell @code{etags} to read the file names from its standard input, by typing a dash in place of the file names, like this: -@example +@smallexample find . -name "*.[chCH]" -print | etags - -@end example +@end smallexample Use the option @samp{--language=@var{name}} to specify the language explicitly. You can intermix these options with file names; each one @@ -1815,38 +1815,33 @@ language from the file names and file contents. Specify @samp{--language=none} to turn off language-specific processing entirely; then @code{etags} recognizes tags by regexp matching alone -(@pxref{Using Regexps}). @samp{etags --help} prints the list of the -languages @code{etags} knows, and the file name rules for guessing the -language. - -@node Using Regexps -@subsection Using Regexps +(@pxref{Etags Regexps}). + + @samp{etags --help} prints the list of the languages @code{etags} +knows, and the file name rules for guessing the language. It also prints +a list of all the available @code{etags} options, together with a short +explanation. + +@node Etags Regexps +@subsection Etags Regexps The @samp{--regex} option provides a general way of recognizing tags based on regexp matching. You can freely intermix it with file names. Each @samp{--regex} option adds to the preceding ones, and applies only to the following files. The syntax is: -@example +@smallexample --regex=/@var{tagregexp}[/@var{nameregexp}]/ -@end example - -or - -@example ---ignore-case-regex=/@var{tagregexp}[/@var{nameregexp}]/ -@end example +@end smallexample @noindent -where @var{tagregexp} is used to match the lines to tag. The second -form for the option syntax ignores the case when searching a match for -the regular expression. @var{tagregexp} is always anchored, that is, it -behaves as if preceded by @samp{^}. If you want to account for -indentation, just match any initial number of blanks by beginning your -regular expression with @samp{[ \t]*}. In the regular expressions, -@samp{\} quotes the next character, and @samp{\t} stands for the tab -character. Note that @code{etags} does not handle the other C escape -sequences for special characters. +where @var{tagregexp} is used to match the lines to tag. It is always +anchored, that is, it behaves as if preceded by @samp{^}. If you want +to account for indentation, just match any initial number of blanks by +beginning your regular expression with @samp{[ \t]*}. In the regular +expressions, @samp{\} quotes the next character, and @samp{\t} stands +for the tab character. Note that @code{etags} does not handle the other +C escape sequences for special characters. @cindex interval operator (in regexps) The syntax of regular expressions in @code{etags} is the same as in @@ -1863,19 +1858,19 @@ accurately and to do completion on tag names more reliably. You can find some examples below. - The option @samp{--case-folded-regexp} (or @samp{-c}) si like + The option @samp{--ignore-case-regex} (or @samp{-c}) is like @samp{--regex}, except that the regular expression provided will be -matched with case folded, i.e. case-insensitively, which is appropriate -for various programming languages. +matched without regard to case, which is appropriate for various +programming languages. The @samp{-R} option deletes all the regexps defined with @samp{--regex} options. It applies to the file names following it, as you can see from the following example: -@example +@smallexample etags --regex=/@var{reg1}/ voo.doo --regex=/@var{reg2}/ \ bar.ber -R --lang=lisp los.er -@end example +@end smallexample @noindent Here @code{etags} chooses the parsing language for @file{voo.doo} and @@ -1885,16 +1880,54 @@ @file{bar.ber}. @code{etags} uses the Lisp tags rules, and no regexp matching, to recognize tags in @file{los.er}. + A regular expression can be bound to a given language, by prepending +it with @samp{@{lang@}}. When you do this, @code{etags} will use the +regular expression only for files of that language. @samp{etags --help} +prints the list of languages recognised by @code{etags}. The following +example tags the @code{DEFVAR} macros in the Emacs source files. +@code{etags} applies this regular expression to C files only: + +@smallexample +--regex='@{c@}/[ \t]*DEFVAR_[A-Z_ \t(]+"\([^"]+\)"/' +@end smallexample + +@noindent +This feature is particularly useful when storing a list of regular +expressions in a file. The following option syntax instructs +@code{etags} to read two files of regular expressions. The regular +expressions contained in the second file are matched without regard to +case. + +@smallexample +--regex=@@first-file --ignore-case-regex=@@second-file +@end smallexample + +@noindent +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 @samp{@@}, @code{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 +@samp{emacs.tags} with the following contents (the first line in the +file is a comment): + +@smallexample + -- This is for GNU Emacs source files +@{c@}/[ \t]*DEFVAR_[A-Z_ \t(]+"\([^"]+\)"/\1/ +@end smallexample + +@noindent +and then use it like this: + +@smallexample +etags --regex=@@emacs.tags *.[ch] */*.[ch] +@end smallexample + Here are some more examples. The regexps are quoted to protect them from shell interpretation. @itemize @bullet -@item -Tag the @code{DEFVAR} macros in the emacs source files: - -@smallexample ---regex='/[ \t]*DEFVAR_[A-Z_ \t(]+"\([^"]+\)"/' -@end smallexample @item Tag VHDL files (this example is a single long line, broken here for @@ -1915,9 +1948,6 @@ @end smallexample @end itemize - For a list of the other available @code{etags} options, execute -@code{etags --help}. - @node Select Tags Table @subsection Selecting a Tags Table