ctags.1

ultraEdit的Ctag标签工具的实现源代码

(case-insensitive; either built-in or user-defined) to be used for every
supplied file instead of automatically selecting the language based upon its
extension. In addition, the special value \fIauto\fP indicates that the
language should be automatically selected (which effectively disables this
option).

.TP 5
\fB--languages\fP=\fI[+|-]list\fP
Specifies the languages for which tag generation is enabled, with \fIlist\fP
containing a comma-separated list of language names (case-insensitive; either
built-in or user-defined). If the first language of \fIlist\fP is not preceded
by either a '+' or '-', the current list will be cleared before adding or
removing the languages in \fIlist\fP. Until a '-' is encountered, each
language in the list will be added to the current list. As either the '+' or
'-' is encountered in the list, the languages following it are added or
removed from the current list, respectively. Thus, it becomes simple to
replace the current list with a new one, or to add or remove languages from
the current list. The actual list of files for which tags will be generated
depends upon the language extension mapping in effect (see the \fB--langmap\fP
option). Note that all languages, including user-defined languages are enabled
unless explicitly disabled using this option. Language names included in
\fIlist\fP may be any built-in language or one previously defined with
\fB--langdef\fP. The default is "all", which is also accepted as a valid
argument. See the \fB--list-languages\fP option for a complete list of the
built-in language names.

.TP 5
\fB--license\fP
Prints a summary of the software license to standard output, and then exits.

.TP 5
\fB--line-directives\fP[=\fIyes\fP|\fIno\fP]
Specifies whether "#line" directives should be recognized. These are present
in the output of preprocessors and contain the line number, and possibly the
file name, of the original source file(s) from which the preprocessor output
file was generated. When enabled, this option will cause \fBctags\fP to
generate tag entries marked with the file names and line numbers of their
locations original source file(s), instead of their actual locations in the
preprocessor output. The actual file names placed into the tag file will have
the same leading path components as the preprocessor output file, since it is
assumed that the original source files are located relative to the
preprocessor output file (unless, of course, the #line directive specifies an
absolute path). This option is off by default. \fBNote:\fP This option is
generally only useful when used together with the \fB--excmd\fP=\fInumber\fP
(\fB-n\fP) option. Also, you may have to use either the \fB--langmap\fP or
\fB--language-force\fP option if the extension of the preprocessor output file
is not known to \fBctags\fP.

.TP 5
\fB--links\fP[=\fIyes\fP|\fIno\fP]
Indicates whether symbolic links (if supported) should be followed. When
disabled, symbolic links are ignored. This option is on by default.

.TP 5
\fB--list-kinds\fP[=\fIlanguage\fP|\fIall\fP]
Lists the tag kinds recognized for either the specified language or all
languages, and then exits. Each kind of tag recorded in the tag file is
represented by a one-letter flag, which is also used to filter the tags placed
into the output through use of the \fB--<LANG>-kinds\fP option. Note that some
languages and/or tag kinds may be implemented using regular expressions and
may not be available if regex support is not compiled into \fBctags\fP (see
the \fB--regex-<LANG>\fP option). Each kind listed is enabled unless followed
by "[off]".

.TP 5
\fB--list-maps\fP[=\fIlanguage\fP|\fIall\fP]
Lists the file extensions and file name patterns which associate a file name
with a language for either the specified language or all languages, and then
exits. See the \fB--langmap\fP option, and \fBSOURCE FILES\fP, above.

.TP 5
\fB--list-languages\fP
Lists the names of the languages understood by \fBctags\fP, and then exits.
These language names are case insensitive and may be used in the
\fB--language-force\fP, \fB--languages\fP, \fB--<LANG>-kinds\fP, and
\fB--regex-<LANG>\fP options.

.TP 5
\fB--options\fP=\fIfile\fP
Read additional options from \fIfile\fP. As a special case, if
\fB--options\fP=\fINONE\fP is specified as the first option on the command
line, it will disable the automatic reading of any configuration options from
either a file or the environment (see \fBFILES\fP).

.TP 5
\fB--recurse\fP[=\fIyes\fP|\fIno\fP]
Recurse into directories encountered in the list of supplied files. If the
list of supplied files is empty and no file list is specified with the
\fB-L\fP option, then the current directory (i.e. ".") is assumed. Symbolic
links are followed. If you don't like these behaviors, either explicitly
specify the files or pipe the output of \fBfind\fP(1) into \fBctags -L-\fP
instead. \fBNote:\fP This option is not supported on all platforms at present.
It is available if the output of the \fB--help\fP option includes this option.
See, also, the \fB--exclude\fP to limit recursion.

.TP 5
\fB--regex-<LANG>\fP=\fI/regexp/replacement/[kind-spec/][flags]\fP
The \fI/regexp/replacement/\fP pair define a regular expression replacement
pattern, similar in style to \fBsed\fP substitution commands, with which to
generate tags from source files mapped to the named language, \fB<LANG>\fP,
(case-insensitive; either a built-in or user-defined language). The regular
expression, \fIregexp\fP, defines an extended regular expression (roughly that
used by \fBegrep\fP(1)), which is used to locate a single source line
containing a tag and may specify tab characters using \\t. When a matching
line is found, a tag will be generated for the name defined by
\fIreplacement\fP, which generally will contain the special back-references
\\1 through \\9 to refer to matching sub-expression groups within
\fIregexp\fP. The '/' separator characters shown in the parameter to the
option can actually be replaced by any character. Note that whichever
separator character is used will have to be escaped with a backslash ('\\')
character wherever it is used in the parameter as something other than a
separator. The regular expression defined by this option is added to the
current list of regular expressions for the specified language unless the
parameter is omitted, in which case the current list is cleared.

Unless modified by \fIflags\fP, \fIregexp\fP is interpreted as a Posix
extended regular expression. The \fIreplacement\fP should expand for all
matching lines to a non-empty string of characters, or a warning message will
be reported. An optional kind specifier for tags matching \fIregexp\fP may
follow \fIreplacement\fP, which will determine what kind of tag is reported in
the "kind" extension field (see \fBTAG FILE FORMAT\fP, below). The full form
of \fIkind-spec\fP is in the form of a single letter, a comma, a name (without
spaces), a comma, a description, followed by a separator, which specify
the short and long forms of the kind value and its textual description
(displayed using \fB--list-kinds\fP). Either the kind name and/or the
description may be omitted. If \fIkind-spec\fP is omitted, it defaults to
"\fIr,regex\fP". Finally, \fIflags\fP are one or more single-letter characters
having the following effect upon the interpretation of \fIregexp\fP:

.PP
.RS 8
.TP 4
.I b
The pattern is interpreted as a Posix basic regular expression.
.TP 4
.I e
The pattern is interpreted as a Posix extended regular expression (default).
.TP 4
.I i
The regular expression is to be applied in a case-insensitive manner.
.RE

.RS 5
Note that this option is available only if \fBctags\fP was compiled with
support for regular expressions, which depends upon your platform. You can
determine if support for regular expressions is compiled in by examining the
output of the \fB--version\fP option, which will include "+regex" in the
compiled feature list.

For more information on the regular expressions used by \fBctags\fP, see
either the \fBregex(5,7)\fP man page, or the GNU info documentation for regex
(e.g. "info regex").
.RE

.TP 5
\fB--sort\fP[=\fIyes\fP|\fIno\fP|\fIfoldcase\fP]
Indicates whether the tag file should be sorted on the tag name (default is
\fIyes\fP). Note that the original \fBvi\fP(1) required sorted tags. 
The \fIfoldcase\fP value specifies case insensitive (or case-folded) sorting.
Fast binary searches of tag files sorted with case-folding will require
special support from tools using tag files, such as that found in the ctags
readtags library, or Vim version 6.2 or higher (using "set ignorecase"). This
option must appear before the first file name. [Ignored in etags mode]

.TP 5
\fB--tag-relative\fP[=\fIyes\fP|\fIno\fP]
Indicates that the file paths recorded in the tag file should be relative to
the directory containing the tag file, rather than relative to the current
directory, unless the files supplied on the command line are specified with
absolute paths. This option must appear before the first file name. The
default is \fIyes\fP when running in etags mode (see the \fB-e\fP
option), \fIno\fP otherwise.

.TP 5
\fB--totals\fP[=\fIyes\fP|\fIno\fP]
Prints statistics about the source files read and the tag file written during
the current invocation of \fBctags\fP. This option is off by default.
This option must appear before the first file name.

.TP 5
\fB--verbose\fP[=\fIyes\fP|\fIno\fP]
Enable verbose mode. This prints out information on option processing and a
brief message describing what action is being taken for each file considered
by \fBctags\fP. Normally, \fBctags\fP does not read command line arguments
until after options are read from the configuration files (see \fBFILES\fP,
below) and the \fBCTAGS\fP environment variable. However, if this option is
the first argument on the command line, it will take effect before any options
are read from these sources. The default is \fIno\fP.

.TP 5
\fB--version\fP
Prints a version identifier for \fBctags\fP to standard output, and then
exits. This is guaranteed to always contain the string "Exuberant Ctags".


.SH "OPERATIONAL DETAILS"

As \fBctags\fP considers each file name in turn, it tries to determine the
language of the file by applying the following three tests in order: if the
file extension has been mapped to a language, if the file name matches a shell
pattern mapped to a language, and finally if the file is executable and its
first line specifies an interpreter using the Unix-style "#!" specification
(if supported on the platform). If a language was identified, the file is
opened and then the appropriate language parser is called to operate on the
currently open file. The parser parses through the file and adds an entry to
the tag file for each language object it is written to handle. See
\fBTAG FILE FORMAT\fP, below, for details on these entries.

This implementation of \fBctags\fP imposes no formatting requirements on C
code as do legacy implementations. Older implementations of ctags tended to
rely upon certain formatting assumptions in order to help it resolve coding
dilemmas caused by preprocessor conditionals.

In general, \fBctags\fP tries to be smart about conditional preprocessor
directives. If a preprocessor conditional is encountered within a statement
which defines a tag, \fBctags\fP follows only the first branch of that
conditional (except in the special case of "#if 0", in which case it follows
only the last branch). The reason for this is that failing to pursue only one
branch can result in ambiguous syntax, as in the following example:

.RS
#ifdef TWO_ALTERNATIVES
.br
struct {
.br
#else
.br
union {
.br
#endif
.RS 4
short a;
.br
long b;
.RE
}
.RE

Both branches cannot be followed, or braces become unbalanced and \fBctags\fP
would be unable to make sense of the syntax.

If the application of this heuristic fails to properly parse a file,
generally due to complicated and inconsistent pairing within the conditionals,
\fBctags\fP will retry the file using a different heuristic which does not
selectively follow conditional preprocessor branches, but instead falls back
to relying upon a closing brace ("}") in column 1 as indicating the end of a
block once any brace imbalance results from following a #if conditional branch.

\fBCtags\fP will also try to specially handle arguments lists enclosed in
double sets of parentheses in order to accept the following conditional
construct:

.RS
extern void foo __ARGS((int one, char two));
.RE

Any name immediately preceding the "((" will be automatically ignored and
the previous name will be used.

C++ operator definitions are specially handled. In order for consistency with
all types of operators (overloaded and conversion), the operator name in the
tag file will always be preceded by the string "operator " (i.e. even if the
actual operator definition was written as "operator<<").

After creating or appending to the tag file, it is sorted by the tag name,
removing identical tag lines.


.SH "TAG FILE FORMAT"

When not running in etags mode, each entry in the tag file consists of a
separate line, each looking like this in the most general case:

.RS 1
tag_name<TAB>file_name<TAB>ex_cmd;"<TAB>extension_fields
.RE

The fields and separators of these lines are specified as follows:

.PD 0
.RS 4
.TP 4
1.
tag name
.TP 4
2.
single tab character
.TP 4
3.
name of the file in which the object associated with the tag is located
.TP 4
4.
single tab character
.TP 4
5.
EX command used to locate the tag within the file; generally a search pattern