.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Parse::ExuberantCTags 3pm"
.TH Parse::ExuberantCTags 3pm "2020-11-09" "perl v5.32.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Parse::ExuberantCTags \- Efficiently parse exuberant ctags files
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 2
\&  use Parse::ExuberantCTags;
\&  my $parser = Parse::ExuberantCTags\->new( \*(Aqtags_filename\*(Aq );
\&  
\&  # find a given tag that starts with \*(Aqfoo\*(Aq and do not ignore case
\&  my $tag = $parser\->findTag("foo", ignore_case => 0, partial => 1);
\&  if (defined $tag) {
\&    print $tag\->{name}, "\en";
\&  }
\&  $tag = $parser\->findNextTag();
\&  # ...
\&  
\&  # iterator interface (use findTag instead, it does a binary search)
\&  $tag = $parser\->firstTag;
\&  while (defined($tag = $parser\->nextTag)) {
\&    # use the tag structure
\&  }
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This Perl module parses \fIctags\fR files and handles both traditional
ctags as well as extended ctags files such as produced with \fIExuberant
ctags\fR. To the best of my knowledge, it does not handle emacs-style "\fIetags\fR"
files.
.PP
The module is implemented as a wrapper around the \fIreadtags\fR library that normally
ships with \fIExuberant ctags\fR. If you do not know what that is, you are
encouraged to have a look at <http://ctags.sourceforge.net/>. In order to use
this module, you do not need \fIExuberant ctags\fR on your system. The module
ships a copy of \fIreadtags\fR. Quoting the \fIreadtags\fR documentation:
.PP
.Vb 9
\&  The functions defined in this interface are intended to provide tag file
\&  support to a software tool. The tag lookups provided are sufficiently fast
\&  enough to permit opening a sorted tag file, searching for a matching tag,
\&  then closing the tag file each time a tag is looked up (search times are
\&  on the order of hundreths of a second, even for huge tag files). This is
\&  the recommended use of this library for most tool applications. Adhering
\&  to this approach permits a user to regenerate a tag file at will without
\&  the tool needing to detect and resynchronize with changes to the tag file.
\&  Even for an unsorted 24MB tag file, tag searches take about one second.
.Ve
.PP
Take away from this that tag files should be sorted by the generating program.
.SH "TAG FORMAT"
.IX Header "TAG FORMAT"
The methods that return a tag entry all return tags in the same format.
Examples count for a billion words:
.PP
.Vb 11
\&  {
\&    name              => \*(AqIO::File\*(Aq,
\&    file              => \*(Aq/usr/lib/perl/5.10/IO/File.pm\*(Aq,
\&    fileScope         => 0,
\&    kind              => \*(Aqp\*(Aq,
\&    addressPattern    => \*(Aq/package IO::File;/\*(Aq,
\&    addressLineNumber => 3,
\&    extension         => {
\&      class => \*(AqIO::File\*(Aq,
\&    },
\&  }
.Ve
.PP
The structure has the name of the tag (\f(CW\*(C`name\*(C'\fR), the file it was found in
(\f(CW\*(C`file\*(C'\fR), a flag indicating whether the tag is scoped to the file only,
the type of the tag entry (\f(CW\*(C`kind\*(C'\fR), the \f(CW\*(C`ex\*(C'\fR search pattern for locating
the definition (\f(CW\*(C`addressPattern\*(C'\fR), the line number (\f(CW\*(C`addressLineNumber\*(C'\fR),
and then key/value pairs from the extension section of the tag.
.PP
Not all of the fields are guaranteed to be available. Particularly the \f(CW\*(C`extension\*(C'\fR
section will be empty if the tags file doesn't make use of the extended format.
Refer to the ctags reference for details.
.SH "METHODS"
.IX Header "METHODS"
.SS "new"
.IX Subsection "new"
Given the name of a file to read the tags from, opens that file and returns
a \f(CW\*(C`Parse::ExuberantCTags\*(C'\fR object on success, false otherwise.
.SS "findTag"
.IX Subsection "findTag"
Takes the name of the tag to be sought as first argument.
.PP
Following the tag name, two optional arguments (key/value pairs)
are supported:
.PP
Setting \f(CW\*(C`<partial =\*(C'\fR 1>> makes the tag name match if it's the
start of a tag. Setting \f(CW\*(C`<ignore_case =\*(C'\fR 1>> makes the search ignore
the case of the tag. Note that setting \f(CW\*(C`<ignore_case\*(C'\fR> to true
results in a slower linear instead of a binary search!
.PP
Returns a tag structure or undef if none matched.
.SS "findNextTag"
.IX Subsection "findNextTag"
Returns the next tag that matches the previous search (see \f(CW\*(C`findTag\*(C'\fR).
.PP
Returns undef if no more tags match.
.SS "firstTag"
.IX Subsection "firstTag"
Returns the first tag in the file. Returns undef if the file is emtpy.
.SS "nextTag"
.IX Subsection "nextTag"
Returns the next tag or undef if the end of the file is reached.
.SH "CAVEATS"
.IX Header "CAVEATS"
The SetSortType call is currently not supported. Let me know if you
need it and I'll add a wrapper.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Exuberant ctags homepage: <http://ctags.sourceforge.net/>
.PP
Wikipedia on ctags: <http://en.wikipedia.org/wiki/Ctags>
.PP
Module that can produce ctags files from Perl code: Perl::Tags
.PP
File::PackageIndexer
.SH "AUTHOR"
.IX Header "AUTHOR"
Steffen Mueller, <smueller@cpan.org>
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
This Perl module is a wrapper around the \fIreadtags\fR library
that is shipped as part of the exuberant ctags program.
A copy of \fIreadtags\fR is included with this module.
\&\fIreadtags\fR was put in the public domain by its author. The full
copyright/license information from the code is:
.PP
.Vb 2
\&  Copyright (c) 1996\-2003, Darren Hiebert
\&  This source code is released into the public domain.
.Ve
.PP
The \s-1XS\s0 wrapper and this document are:
.PP
Copyright (C) 2009\-2010 by Steffen Mueller
.PP
This library is free software; you can redistribute it and/or modify
it under the same terms as Perl itself, either Perl version 5.6 or,
at your option, any later version of Perl 5 you may have available.