ctags.1

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

(either /pattern/ or ?pattern?) or line number (see \fB--excmd\fP). Tag file
format 2 (see \fB--format\fP) extends this EX command under certain
circumstances to include a set of extension fields (described below) embedded
in an EX comment immediately appended to the EX command, which leaves it
backward-compatible with original \fBvi\fP(1) implementations.
.RE
.PD 1

A few special tags are written into the tag file for internal purposes. These
tags are composed in such a way that they always sort to the top of the file.
Therefore, the first two characters of these tags are used a magic number to
detect a tag file for purposes of determining whether a valid tag file is
being overwritten rather than a source file.

Note that the name of each source file will be recorded in the tag file
exactly as it appears on the command line. Therefore, if the path you
specified on the command line was relative to the current directory, then it
will be recorded in that same manner in the tag file. See, however, the
\fB--tag-relative\fP option for how this behavior can be modified.

Extension fields are tab-separated key-value pairs appended to the end of the
EX command as a comment, as described above. These key value pairs appear in
the general form "\fIkey\fP:\fIvalue\fP". Their presence in the lines of the
tag file are controlled by the \fB--fields\fP option. The possible keys and
the meaning of their values are as follows:

.TP 12
.I access
Indicates the visibility of this class member, where \fIvalue\fP is specific
to the language.

.TP 12
.I file
Indicates that the tag has file-limited visibility. This key has no
corresponding value.

.TP 12
.I kind
Indicates the type, or kind, of tag. Its value is either one of the
corresponding one-letter flags described under the various
\fB--<LANG>-kinds\fP options above, or a full name. It is permitted (and is,
in fact, the default) for the key portion of this field to be omitted. The
optional behaviors are controlled with the \fB--fields\fP option.

.TP 12
.I implementation
When present, this indicates a limited implementation (abstract vs. concrete)
of a routine or class, where \fIvalue\fP is specific to the language
("virtual" or "pure virtual" for C++; "abstract" for Java).

.TP 12
.I inherits
When present, \fIvalue\fP. is a comma-separated list of classes from which
this class is derived (i.e. inherits from).

.TP 12
.I signature
When present, \fIvalue\fP. is a language-dependent representation of the
signature of a routine. A routine signature in its complete form specifies the
return type of a routine and its formal argument list. This extension field is
presently supported only for C-based languages and does not include the return
type.

.PP
In addition, information on the scope of the tag definition may be available,
with the key portion equal to some language-dependent construct name and its
value the name declared for that construct in the program. This scope entry
indicates the scope in which the tag was found. For example, a tag generated
for a C structure member would have a scope looking like "struct:myStruct".


.SH "HOW TO USE WITH VI"
Vi will, by default, expect a tag file by the name "tags" in the current
directory. Once the tag file is built, the following commands exercise the tag
indexing feature:
.TP 12
.B vi -t tag
Start vi and position the cursor at the file and line where "tag" is defined.
.TP 12
.B :ta tag
Find a tag.
.TP 12
.B Ctrl-]
Find the tag under the cursor.
.TP 12
.B Ctrl-T
Return to previous location before jump to tag (not widely implemented).


.SH "HOW TO USE WITH GNU EMACS"
Emacs will, by default, expect a tag file by the name "TAGS" in the current
directory. Once the tag file is built, the following commands exercise the
tag indexing feature:
.TP 10
.B "M-x visit-tags-table <RET> FILE <RET>"
Select the tag file, "FILE", to use.
.TP 10
.B "M-. [TAG] <RET>"
Find the first definition of TAG. The default tag is the identifier under the
cursor.
.TP 10
.B "M-*"
Pop back to where you previously invoked "M-.".
.TP 10
.B "C-u M-."
Find the next definition for the last tag.

.PP
For more commands, see the \fITags\fP topic in the Emacs info document.


.SH "HOW TO USE WITH NEDIT"
NEdit version 5.1 and later can handle the new extended tag file format (see
\fB--format\fP). To make NEdit use the tag file, select "File->Load Tags
File". To jump to the definition for a tag, highlight the word, the press
Ctrl-D. NEdit 5.1 can can read multiple tag files from different directories.
Setting the X resource nedit.tagFile to the name of a tag file instructs NEdit
to automatically load that tag file at startup time.


.SH "CAVEATS"
Because \fBctags\fP is neither a preprocessor nor a compiler, use of
preprocessor macros can fool \fBctags\fP into either missing tags or
improperly generating inappropriate tags. Although \fBctags\fP has been
designed to handle certain common cases, this is the single biggest cause of
reported problems. In particular, the use of preprocessor constructs which
alter the textual syntax of C can fool \fBctags\fP. You can work around many
such problems by using the \fB-I\fP option.

White space is treated as a separator for file names and options read from
list files, specified using the \fB-L\fP option, and in filter mode (specified
using the \fB--filter\fP option). Therefore, it is not currently possible to
supply file names or other options containing embedded white space (spaces,
etc.) through these options.

Note that when \fBctags\fP generates uses patterns for locating tags (see
the \fB--excmd\fP option), it is entirely possible that the wrong line may be
found by your editor if there exists another source line which is identical to
the line containing the tag. The following example demonstrates this condition:

.RS
int variable;

/* ... */
.br
void foo(variable)
.br
int variable;
.br
{
.RS 4
/* ... */
.RE
}
.RE

Depending upon which editor you use and where in the code you happen to be, it
is possible that the search pattern may locate the local parameter declaration
in foo() before it finds the actual global variable definition, since the
lines (and therefore their search patterns are identical). This can be avoided
by use of the \fB--excmd\fP=\fIn\fP option.


.SH "BUGS"
\fBCtags\fP has more options than \fBls\fP(1).

When parsing a C++ member function definition (e.g. "className::function"),
\fBctags\fP cannot determine whether the scope specifier is a class name or a
namespace specifier and always lists it as a class name in the scope portion
of the extension fields. Also, if a C++ function is defined outside of the
class declaration (the usual case), the access specification (i.e. public,
protected, or private) and implementation information (e.g. virtual, pure
virtual) contained in the function declaration are not known when the tag is
generated for the function definition. It will, however be available for
prototypes (e.g \fB--c++-kinds\fP=\fI+p\fP).

No qualified tags are generated for language objects inherited into a class.


.SH "ENVIRONMENT VARIABLES"

.TP 8
.B CTAGS
If this environment variable exists, it will be expected to contain a set of
default options which are read when \fBctags\fP starts, after the
configuration files listed in \fBFILES\fP, below, are read, but before any
command line options are read. Options appearing on the command line will
override options specified in this variable. Only options will be read from
this variable. Note that all white space in this variable in considered a
separator, making it impossible to pass an option parameter containing an
embedded space. If this is a problem, use a configuration file instead.

.TP 8
.B ETAGS
Similar to the \fBCTAGS\fP variable above, this variable, if found, will be
read when \fBetags\fP starts. If this variable is not found, \fBetags\fP will
try to use \fBCTAGS\fP instead.

.TP 8
.B TMPDIR
On Unix-like hosts where mkstemp() is available, the value of this variable
specifies the directory in which to place temporary files. This can be useful
if the size of a temporary file becomes too large to fit on the partition
holding the default temporary directory defined at compilation time.
\fBctags\fP creates temporary files only if either (1) an emacs-style tag file
is being generated, (2) the tag file is being sent to standard output, or (3)
the program was compiled to use an internal sort algorithm to sort the tag
files instead of the the sort utility of the operating system. If the sort
utility of the operating system is being used, it will generally observe this
variable also. Note that if \fBctags\fP is setuid, the value of TMPDIR will be
ignored.


.SH "FILES"
.PD 0
.I /ctags.cnf (on MSDOS, MSWindows only)
.br
.I /etc/ctags.conf
.br
.I /usr/local/etc/ctags.conf
.br
.I $HOME/.ctags ($HOME/ctags.cnf on MSDOS, MSWindows)
.br
.I .ctags (ctags.cnf on MSDOS, MSWindows)
.IP
If any of these configuration files exist, each will be expected to contain a
set of default options which are read in the order listed when \fBctags\fP
starts, but before the \fBCTAGS\fP environment variable is read or any command
line options are read. This makes it possible to set up site-wide, personal
or project-level defaults. It is possible to compile \fBctags\fP to read an
additional configuration file before any of those shown above, which will be
indicated if the output produced by the \fB--version\fP option lists the
"custom-conf" feature. Options appearing in the \fBCTAGS\fP environment
variable or on the command line will override options specified in these
files. Only options will be read from these files. Note that the option files
are read in line-oriented mode in which spaces are significant (since
shell quoting is not possible). Each line of the file is read as one command
line parameter (as if it were quoted with single quotes). Therefore, use new
lines to indicate separate command-line arguments.
.PD 1

.TP
.I tags
The default tag file created by \fBctags\fP.
.TP
.I TAGS
The default tag file created by \fBetags\fP.

.SH "SEE ALSO"
The official Exuberant Ctags web site at:

.RS
http://ctags.sourceforge.net
.RE

Also \fBex\fP(1), \fBvi\fP(1), \fBelvis\fP, or, better yet, \fBvim\fP, the
official editor of \fBctags\fP. For more information on \fBvim\fP, see the VIM
Pages web site at:

.RS
http://www.vim.org/
.RE


.SH "AUTHOR"
Darren Hiebert <[e-mail]>
.br
http://DarrenHiebert.com/


.SH "MOTIVATION"
"Think ye at all times of rendering some service to every member of the human
race."

"All effort and exertion put forth by man from the fullness of his heart is
worship, if it is prompted by the highest motives and the will to do service
to humanity."

.RS
\-- From the Baha'i Writings
.RE


.SH "CREDITS"
This version of \fBctags\fP was originally derived from and inspired by the
ctags program by Steve Kirkendall <[e-mail]> that comes with the
Elvis vi clone (though virtually none of the original code remains).

Credit is also due Bram Moolenaar <[e-mail]>, the author of \fBvim\fP, who
has devoted so much of his time and energy both to developing the editor as a
service to others, and to helping the orphans of Uganda.

The section entitled "HOW TO USE WITH GNU EMACS" was shamelessly stolen from
the info page for GNU \fBetags\fP.