1Perl::Tags(3)         User Contributed Perl Documentation        Perl::Tags(3)
2
3
4

NAME

6       Perl::Tags - Generate (possibly exuberant) Ctags style tags for Perl
7       sourcecode
8

SYNOPSIS

10   Using Perl::Tags to assist your development
11       "Perl::Tags" is designed to be integrated into your development
12       environment.  Here are a few ways to use it:
13
14       With Vim
15
16       "Perl::Tags" was originally designed to be used with vim.  See
17       <https://github.com/osfameron/perl-tags-vim> for an easily installable
18       Plugin.
19
20       NB: You will need to have a vim with perl compiled in it.  Debuntu
21       packages this as "vim-perl". Alternatively you can compile from source
22       (you'll need Perl + the development headers "libperl-dev").
23
24       (Note that "perl-tags-vim" includes its own copy of "Perl::Tags"
25       through the magic of git submodules and App::FatPacker, so you don't
26       need to install this module from CPAN if you are only intending to use
27       it with Vim as above!)
28
29       From the Command Line
30
31       See the "perl-tags" in bin script provided.
32
33       From other editors
34
35       Any editor that supports ctags should be able to use this output.
36       Documentation and code patches on how to do this are welcome.
37
38   Using the Perl::Tags module within your code
39               use Perl::Tags;
40               my $naive_tagger = Perl::Tags::Naive->new( max_level=>2 );
41               $naive_tagger->process(
42                   files => ['Foo.pm', 'bar.pl'],
43                   refresh=>1
44               );
45
46               print $naive_tagger; # stringifies to ctags file
47
48       Recursively follows "use" and "require" statements, up to a maximum of
49       "max_level".
50

DETAILS

52       There are several taggers distributed with this distribution,
53       including:
54
55       Perl::Tags::Naive
56           This is a more-or-less straight ripoff, slightly updated, of the
57           original pltags code.  This is a "naive" tagger, in that it makes
58           pragmatic assumptions about what Perl code usually looks like (e.g.
59           it doesn't actually parse the code.)  This is fast, lightweight,
60           and often Good Enough.
61
62           This has additional subclasses such as Perl::Tags::Naive::Moose to
63           parse Moose declarations, and Perl::Tags::Naive::Lib to parse "use
64           lib".
65
66       Perl::Tags::PPI
67           Uses the PPI module to do a deeper analysis and parsing of your
68           Perl code.  This is more accurate, but slower.
69
70       Perl::Tags::Hybrid
71           Can run multiple taggers, such as ::Naive and ::PPI, combining the
72           results.
73

EXTENDING

75       Documentation patches are welcome: in the meantime, have a look at
76       Perl::Tags::Naive and its subclasses for a simple line-by-line method
77       of tagging files.  Alternatively Perl::Tags::PPI uses PPI's built in
78       method of parsing Perl documents.
79
80       In general, you will want to override the "get_tags_for_file" method,
81       returning a list of "Perl::Tags::Tag" objects to be registered.
82
83       For recursively checking other modules, return a
84       "Perl::Tags::Tag::Recurse" object, which does not create a new tag in
85       the resulting perltags file, but instead processes the next file
86       recursively.
87

FEATURES

89           * Recursive, incremental tagging.
90           * parses `use_ok`/`require_ok` line from Test::More
91

METHODS

93   "new"
94       Perl::Tags is an abstract baseclass.  Use a class such as
95       Perl::Tags::Naive and instantiate it with "new".
96
97           $naive_tagger = Perl::Tags::Naive->new( max_level=>2 );
98
99       Accepts the following parameters
100
101           max_level:    levels of "use" statements to descend into, default 2
102           do_variables: tag variables?  default 1 (true)
103           exts:         use the Exuberant extensions
104
105   "to_string"
106       A Perl::Tags object will stringify to a textual representation of a
107       ctags file.
108
109           print $tagger;
110
111   "clean_file"
112       Delete all tags, but without touching the "order" seen, that way, if
113       the tags are recreated, they will remain near the top of the
114       "interestingness" tree
115
116   "output"
117       Save the file to disk if it has changed.  (The private "{is_dirty}"
118       attribute is used, as the tags object may be made up incrementally and
119       recursively within your IDE.
120
121   "process"
122       Scan one or more Perl file for tags
123
124           $tagger->process(
125               files => [ 'Module.pm',  'script.pl' ]
126           );
127           $tagger->process(
128               files   => 'script.pl',
129               refresh => 1,
130           );
131
132   "queue", "popqueue"
133       Internal methods managing the processing
134
135   "process_item", "process_file", "get_tags_for_file"
136       Do the heavy lifting for "process" above.
137
138       Taggers must override the abstract method "get_tags_for_file".
139
140   "register"
141       The parsing is done by a number of lightweight objects (parsers) which
142       look for subroutine references, variables, module inclusion etc.  When
143       they are successful, they call the "register" method in the main tags
144       object.
145
146       Note that if your tagger wants to register not a new declaration but
147       rather a usage of another module, then your tagger should return a
148       "Perl::Tags::Tag::Recurse" object.  This is a pseudo-tag which causes
149       the linked module to be scanned in turn.  See Perl::Tags::Naive's
150       handling of "use" statements as an example!
151

SEE ALSO

153       "perl-tags" in bin
154

CONTRIBUTIONS

156       Contributions are always welcome.  The repo is in git:
157
158           http://github.com/osfameron/perl-tags
159
160       Please fork and make pull request.  Maint bits available on request.
161
162       DMITRI
163           many patches for features and bugfixes
164
165       wolverian
166           ::PPI subclass
167
168       Ian Tegebo
169           patch to use File::Temp
170
171       drbean
172           ::Naive::Moose, ::Naive::Spiffy and ::Naive::Lib subclasses
173
174       Alias
175           prodding me to make repo public
176
177       tsee
178           Command line interface, applying patches
179
180       nothingmuch
181       Andreas Koenig
182       ether
183

AUTHOR and LICENSE

185           osfameron (2006-2014) - osfameron@cpan.org
186                                   and contributors, as above
187
188       For support, try emailing me or grabbing me on irc #london.pm on
189       irc.perl.org
190
191       This was originally ripped off pltags.pl, as distributed with vim and
192       available from <http://www.mscha.com/mscha.html?pltags#tools> Version
193       2.3, 28 February 2002 Written by Michael Schaap <pltags@mscha.com>.
194
195       This is licensed under the same terms as Perl itself.  (Or as Vim if
196       you prefer).
197
198
199
200perl v5.36.0                      2023-01-20                     Perl::Tags(3)
Impressum