1Perl::Tags(3) User Contributed Perl Documentation Perl::Tags(3)
2
6 Perl::Tags - Generate (possibly exuberant) Ctags style tags for Perl
7 sourcecode
8
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 With Vim
15 "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 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 (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 From the Command Line
30 See the "perl-tags" in bin script provided.
32 From other editors
34 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 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 print $naive_tagger; # stringifies to ctags file
47 Recursively follows "use" and "require" statements, up to a maximum of
49 "max_level".
50
52 There are several taggers distributed with this distribution,
53 including:
54 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 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 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 Perl::Tags::Hybrid
71 Can run multiple taggers, such as ::Naive and ::PPI, combining the
72 results.
73
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 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 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
89 * Recursive, incremental tagging.
90 * parses `use_ok`/`require_ok` line from Test::More
91
93 "new"
94 Perl::Tags is an abstract baseclass. Use a class such as
95 Perl::Tags::Naive and instantiate it with "new".
96 $naive_tagger = Perl::Tags::Naive->new( max_level=>2 );
98 Accepts the following parameters
100 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 "to_string"
106 A Perl::Tags object will stringify to a textual representation of a
107 ctags file.
108 print $tagger;
110 "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 "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 "process"
122 Scan one or more Perl file for tags
123 $tagger->process(
125 files => [ 'Module.pm', 'script.pl' ]
126 );
127 $tagger->process(
128 files => 'script.pl',
129 refresh => 1,
130 );
131 "queue", "popqueue"
133 Internal methods managing the processing
134 "process_item", "process_file", "get_tags_for_file"
136 Do the heavy lifting for "process" above.
137 Taggers must override the abstract method "get_tags_for_file".
139 "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 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
153 "perl-tags" in bin
154
156 Contributions are always welcome. The repo is in git:
157 http://github.com/osfameron/perl-tags
159 Please fork and make pull request. Maint bits available on request.
161 DMITRI
163 many patches for features and bugfixes
164 wolverian
166 ::PPI subclass
167 Ian Tegebo
169 patch to use File::Temp
170 drbean
172 ::Naive::Moose, ::Naive::Spiffy and ::Naive::Lib subclasses
173 Alias
175 prodding me to make repo public
176 tsee
178 Command line interface, applying patches
179 nothingmuch
181 Andreas Koenig
182 ether
183
185 osfameron (2006-2014) - osfameron@cpan.org
186 and contributors, as above
187 For support, try emailing me or grabbing me on irc #london.pm on
189 irc.perl.org
190 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 This is licensed under the same terms as Perl itself. (Or as Vim if
196 you prefer).
197perl v5.32.1 2021-01-27 Perl::Tags(3)