ctags.1

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

.TP 5
\fB--exclude\fP=[\fIpattern\fP]
Add \fIpattern\fP to a list of excluded files and directories. This option
may be specified as many times as desired. For each file name considered by
\fBctags\fP, each \fIpattern\fP specified using this option will be compared
against both the complete path (e.g. some/path/base.ext) and the base name
(e.g. base.ext) of the file, thus allowing patterns which match a given file
name irrespective of its path, or match only a specific path. If appropriate
support is available from the runtime library of your C compiler, then
\fIpattern\fP may contain the usual shell wildcards (not regular expressions)
common on Unix (be sure to quote the option parameter to protect the wildcards
from being expanded by the shell before being passed to \fBctags\fP; also be
aware that wildcards can match the slash character, '/'). You can determine if
shell wildcards are available on your platform by examining the output of the
\fB--version\fP option, which will include "+wildcards" in the compiled
feature list; otherwise, \fIpattern\fP is matched against file names using a
simple textual comparison.

If \fIpattern\fP begins with the character '@', then the rest of the string
is interpreted as a file name from which to read exclusion patterns, one per
line. If \fIpattern\fP is empty, the list of excluded patterns is cleared.
Note that at program startup, the default exclude list contains "EIFGEN",
"SCCS", "RCS", and "CVS", which are names of directories for which it is
generally not desirable to descend while processing the \fB--recurse\fP
option.

.TP 5
\fB--excmd\fP=\fItype\fP
Determines the type of EX command used to locate tags in the source file.
[Ignored in etags mode]

The valid values for \fItype\fP (either the entire word or the first letter is
accepted) are:

.RS 5
.TP 9
.I number
Use only line numbers in the tag file for locating tags. This has four
advantages:
.PD 0
.RS 9
.TP 4
1.
Significantly reduces the size of the resulting tag file.
.TP 4
2.
Eliminates failures to find tags because the line defining the tag has
changed, causing the pattern match to fail (note that some editors, such as
\fBvim\fP, are able to recover in many such instances).
.TP 4
3.
Eliminates finding identical matching, but incorrect, source lines (see
\fBBUGS\fP, below).
.TP 4
4.
Retains separate entries in the tag file for lines which are identical in
content. In \fIpattern\fP mode, duplicate entries are dropped because the
search patterns they generate are identical, making the duplicate entries
useless.
.RE
.PD 1

.IP
However, this option has one significant drawback: changes to the source files
can cause the line numbers recorded in the tag file to no longer correspond
to the lines in the source file, causing jumps to some tags to miss the target
definition by one or more lines. Basically, this option is best used when the
source code to which it is applied is not subject to change. Selecting this
option type causes the following options to be ignored: \fB-BF\fP.

.TP 9
.I pattern
Use only search patterns for all tags, rather than the line numbers usually
used for macro definitions. This has the advantage of not referencing obsolete
line numbers when lines have been added or removed since the tag file was
generated.

.TP 9
.I mixed
In this mode, patterns are generally used with a few exceptions. For C, line
numbers are used for macro definition tags. This was the default format
generated by the original \fBctags\fP and is, therefore, retained as the
default for this option. For Fortran, line numbers are used for common blocks
because their corresponding source lines are generally identical, making
pattern searches useless for finding all matches.
.RE

.TP 5
\fB--extra\fP=\fI[+|-]flags\fP
Specifies whether to include extra tag entries for certain kinds of
information. The parameter \fIflags\fP is a set of one-letter flags, each
representing one kind of extra tag entry to include in the tag file. If
\fIflags\fP is preceded by by either the '+' or '-' character, the effect of
each flag is added to, or removed from, those currently enabled; otherwise the
flags replace any current settings. The meaning of each flag is as follows:

.PP
.RS 8
.TP 4
.I f
Include an entry for the base file name of every source file (e.g.
"example.c"), which addresses the first line of the file.
.TP 4
.I q
Include an extra class-qualified tag entry for each tag which is a member
of a class (for languages for which this information is extracted; currently
C++, Eiffel, and Java). The actual form of the qualified tag depends upon the
language from which the tag was derived (using a form that is most natural for
how qualified calls are specified in the language). For C++, it is in the form
"class::member"; for Eiffel and Java, it is in the form "class.member". This
may allow easier location of a specific tags when multiple occurrences of a
tag name occur in the tag file. Note, however, that this could potentially
more than double the size of the tag file.
.RE

.TP 5
\fB--fields\fP=\fI[+|-]flags\fP
Specifies the available extension fields which are to be included in the
entries of the tag file (see \fBTAG FILE FORMAT\fP, below, for more
information). The parameter \fIflags\fP is a set of one-letter flags, each
representing one type of extension field to include, with the following
meanings (disabled by default unless indicated):

.PP
.PD 0
.RS 8
.TP 4
.I a
Access (or export) of class members
.TP 4
.I f
File-restricted scoping [enabled]
.TP 4
.I i
Inheritance information
.TP 4
.I k
Kind of tag as a single letter [enabled]
.TP 4
.I K
Kind of tag as full name
.TP 4
.I l
Language of source file containing tag
.TP 4
.I m
Implementation information
.TP 4
.I n
Line number of tag definition
.TP 4
.I s
Scope of tag definition [enabled]
.TP 4
.I S
Signature of routine (e.g. prototype or parameter list)
.TP 4
.I z
Include the "kind:" key in kind field
.PD 1
.RE

.RS 5
Each letter or group of letters may be preceded by either '+' to add it to the
default set, or '-' to exclude it. In the absence of any preceding '+' or '-'
sign, only those kinds explicitly listed in \fIflags\fP will be included in
the output (i.e. overriding the default set). This option is ignored if the
option \fB--format\fP=\fI1\fP has been specified. The default value 
of this options is \fIfks\fP.
.RE

.TP 5
\fB--file-scope\fP[=\fIyes\fP|\fIno\fP]
Indicates whether tags scoped only for a single file (i.e. tags which cannot
be seen outside of the file in which they are defined, such as "static" tags)
should be included in the output. See, also, the \fB-h\fP option. This option
is enabled by default.

.TP 5
\fB--filter\fP[=\fIyes\fP|\fIno\fP]
Causes \fBctags\fP to behave as a filter, reading source file names from
standard input and printing their tags to standard output on a file-by-file
basis. If \fB--sorted\fP is enabled, tags are sorted only within the source
file in which they are defined. File names are read from standard output in
line-oriented input mode (see note for \fB-L\fP option) and only after file
names listed on the command line or from any file supplied using the \fB-L\fP
option. When this option is enabled, the options \fB-f\fP, \fB-o\fP,
and \fB--totals\fP are ignored. This option is quite esoteric and is disabled
by default. This option must appear before the first file name.

.TP 5
\fB--filter-terminator\fP=\fIstring\fP
Specifies a string to print to standard output following the tags for each
file name parsed when the \fB--filter\fP option is enabled. This may permit an
application reading the output of ctags to determine when the output for each
file is finished. Note that if the file name read is a directory and
\fB--recurse\fP is enabled, this string will be printed only one once at the
end of all tags found for by descending the directory. This string will always
be separated from the last tag line for the file by its terminating newline.
This option is quite esoteric and is empty by default. This option must appear
before the first file name.

.TP 5
\fB--format\fP=\fIlevel\fP
Change the format of the output tag file. Currently the only valid values for
\fIlevel\fP are \fI1\fP or \fI2\fP. Level 1 specifies the original tag file
format and level 2 specifies a new extended format containing extension fields
(but in a manner which retains backward-compatibility with original
\fBvi\fP(1) implementations). The default level is 2. This option must appear
before the first file name. [Ignored in etags mode]

.TP 5
.B \--help
Prints to standard output a detailed usage description, and then exits.

.TP 5
\fB--if0\fP[=\fIyes\fP|\fIno\fP]
Indicates a preference as to whether code within an "#if 0" branch of a
preprocessor conditional should be examined for non-macro tags (macro tags are
always included). Because the intent of this construct is to disable code, the
default value of this options is \fIno\fP. Note that this indicates a
preference only and does not guarantee skipping code within an "#if 0" branch,
since the fall-back algorithm used to generate tags when preprocessor
conditionals are too complex follows all branches of a conditional. This
option is disabled by default.

.TP 5
\fB--<LANG>-kinds\fP=\fI[+|-]kinds\fP
Specifies a list of language-specific kinds of tags (or kinds) to include in
the output file for a particular language, where \fB<LANG>\fP is
case-insensitive and is one of the built-in language names (see the
\fB--list-languages\fP option for a complete list). The parameter \fIkinds\fP
is a group of one-letter flags designating kinds of tags (particular to the
language) to either include or exclude from the output. The specific sets of
flags recognized for each language, their meanings and defaults may be list
using the \fB--list-kinds\fP option. Each letter or group of letters may be
preceded by either '+' to add it to, or '-' to remove it from, the default
set. In the absence of any preceding '+' or '-' sign, only those kinds
explicitly listed in \fIkinds\fP will be included in the output (i.e.
overriding the default for the specified language).

As an example for the C language, in order to add prototypes and external
variable declarations to the default set of tag kinds, but exclude macros,
use \fB--c-kinds\fP=\fI+px-d\fP; to include only tags for functions, use
\fB--c-kinds\fP=\fIf\fP.

.TP 5
\fB--langdef\fP=\fIname\fP
Defines a new user-defined language, \fIname\fP, to be parsed with regular
expressions. Once defined, \fIname\fP may be used in other options taking
language names. The typical use of this option is to first define the
language, then map file names to it using \fI--langmap\fP, then specify
regular expressions using \fI--regex-<LANG>\fP to define how its tags are
found.

.TP 5
\fB--langmap\fP=\fImap[,map[...]]\fP
Controls how file names are mapped to languages (see the \fB--list-maps\fP
option). Each comma-separated \fImap\fP consists of the language name (either
a built-in or user-defined language), a colon, and a list of file extensions
and/or file name patterns. A file extension is specified by preceding the
extension with a period (e.g. ".c"). A file name pattern is specified by
enclosing the pattern in parentheses (e.g. "([Mm]akefile)"). If appropriate
support is available from the runtime library of your C compiler, then the
file name pattern may contain the usual shell wildcards common on Unix (be
sure to quote the option parameter to protect the wildcards from being
expanded by the shell before being passed to \fBctags\fP). You can determine
if shell wildcards are available on your platform by examining the output of
the \fB--version\fP option, which will include "+wildcards" in the compiled
feature list; otherwise, the file name patterns are matched against file names
using a simple textual comparison.

If the first character in a map is a plus sign, then the extensions and file
name patterns in that map will be appended to the current map for that
language; otherwise, the map will replace the current map. For example, to
specify that only files with extensions of .c and .x are to be treated as C
language files, use "\fB--langmap\fP=\fIc:.c.x\fP"; to also add files with
extensions of .j as Java language files, specify
"\fB--langmap\fP=\fIc:.c.x,java:+.j\fP". To map makefiles (.e.g files
named either "Makefile", "makefile", or having the extension ".mak") to a
language called "make", specify "\fB--langmap\fP=\fImake:([Mm]akefile).mak\fP".
To map files having no extension, specify a period not followed by a
non-period character (e.g. ".", "..x", ".x."). To clear the mapping for a
particular language (thus inhibiting automatic generation of tags for that
language), specify an empty extension list (e.g.
"\fB--langmap\fP=\fIfortran:\fP"). To restore the default language mappings
for all a particular language, supply the keyword "default" for the mapping.
To specify restore the default language mappings for all languages, specify
"\fB--langmap\fP=\fIdefault\fP". Note that file extensions are tested before
file name patterns when inferring the language of a file.

.TP 5
\fB--language-force\fP=\fIlanguage\fP
By default, \fBctags\fP automatically selects the language of a source file,
ignoring those files whose language cannot be determined (see
\fBSOURCE FILES\fP, above). This option forces the specified \fIlanguage\fP