1Parse::ExuberantCTags(3U)ser Contributed Perl DocumentatiPoanrse::ExuberantCTags(3)
2
3
4

NAME

6       Parse::ExuberantCTags - Efficiently parse exuberant ctags files
7

SYNOPSIS

9         use Parse::ExuberantCTags;
10         my $parser = Parse::ExuberantCTags->new( 'tags_filename' );
11
12         # find a given tag that starts with 'foo' and do not ignore case
13         my $tag = $parser->findTag("foo", ignore_case => 0, partial => 1);
14         if (defined $tag) {
15           print $tag->{name}, "\n";
16         }
17         $tag = $parser->findNextTag();
18         # ...
19
20         # iterator interface (use findTag instead, it does a binary search)
21         $tag = $parser->firstTag;
22         while (defined($tag = $parser->nextTag)) {
23           # use the tag structure
24         }
25

DESCRIPTION

27       This Perl module parses ctags files and handles both traditional ctags
28       as well as extended ctags files such as produced with Exuberant ctags.
29       To the best of my knowledge, it does not handle emacs-style "etags"
30       files.
31
32       The module is implemented as a wrapper around the readtags library that
33       normally ships with Exuberant ctags. If you do not know what that is,
34       you are encouraged to have a look at <http://ctags.sourceforge.net/>.
35       In order to use this module, you do not need Exuberant ctags on your
36       system. The module ships a copy of readtags. Quoting the readtags
37       documentation:
38
39         The functions defined in this interface are intended to provide tag file
40         support to a software tool. The tag lookups provided are sufficiently fast
41         enough to permit opening a sorted tag file, searching for a matching tag,
42         then closing the tag file each time a tag is looked up (search times are
43         on the order of hundreths of a second, even for huge tag files). This is
44         the recommended use of this library for most tool applications. Adhering
45         to this approach permits a user to regenerate a tag file at will without
46         the tool needing to detect and resynchronize with changes to the tag file.
47         Even for an unsorted 24MB tag file, tag searches take about one second.
48
49       Take away from this that tag files should be sorted by the generating
50       program.
51

TAG FORMAT

53       The methods that return a tag entry all return tags in the same format.
54       Examples count for a billion words:
55
56         {
57           name              => 'IO::File',
58           file              => '/usr/lib/perl/5.10/IO/File.pm',
59           fileScope         => 0,
60           kind              => 'p',
61           addressPattern    => '/package IO::File;/',
62           addressLineNumber => 3,
63           extension         => {
64             class => 'IO::File',
65           },
66         }
67
68       The structure has the name of the tag ("name"), the file it was found
69       in ("file"), a flag indicating whether the tag is scoped to the file
70       only, the type of the tag entry ("kind"), the "ex" search pattern for
71       locating the definition ("addressPattern"), the line number
72       ("addressLineNumber"), and then key/value pairs from the extension
73       section of the tag.
74
75       Not all of the fields are guaranteed to be available. Particularly the
76       "extension" section will be empty if the tags file doesn't make use of
77       the extended format.  Refer to the ctags reference for details.
78

METHODS

80   new
81       Given the name of a file to read the tags from, opens that file and
82       returns a "Parse::ExuberantCTags" object on success, false otherwise.
83
84   findTag
85       Takes the name of the tag to be sought as first argument.
86
87       Following the tag name, two optional arguments (key/value pairs) are
88       supported:
89
90       Setting "<partial =" 1>> makes the tag name match if it's the start of
91       a tag. Setting "<ignore_case =" 1>> makes the search ignore the case of
92       the tag. Note that setting "<ignore_case"> to true results in a slower
93       linear instead of a binary search!
94
95       Returns a tag structure or undef if none matched.
96
97   findNextTag
98       Returns the next tag that matches the previous search (see "findTag").
99
100       Returns undef if no more tags match.
101
102   firstTag
103       Returns the first tag in the file. Returns undef if the file is emtpy.
104
105   nextTag
106       Returns the next tag or undef if the end of the file is reached.
107

CAVEATS

109       The SetSortType call is currently not supported. Let me know if you
110       need it and I'll add a wrapper.
111

SEE ALSO

113       Exuberant ctags homepage: <http://ctags.sourceforge.net/>
114
115       Wikipedia on ctags: <http://en.wikipedia.org/wiki/Ctags>
116
117       Module that can produce ctags files from Perl code: Perl::Tags
118
119       File::PackageIndexer
120

AUTHOR

122       Steffen Mueller, <smueller@cpan.org>
123

125       This Perl module is a wrapper around the readtags library that is
126       shipped as part of the exuberant ctags program.  A copy of readtags is
127       included with this module.  readtags was put in the public domain by
128       its author. The full copyright/license information from the code is:
129
130         Copyright (c) 1996-2003, Darren Hiebert
131         This source code is released into the public domain.
132
133       The XS wrapper and this document are:
134
135       Copyright (C) 2009-2010 by Steffen Mueller
136
137       This library is free software; you can redistribute it and/or modify it
138       under the same terms as Perl itself, either Perl version 5.6 or, at
139       your option, any later version of Perl 5 you may have available.
140
141
142
143perl v5.28.0                      2010-09-21          Parse::ExuberantCTags(3)
Impressum