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 use Perl::Tags;
11 my $naive_tagger = Perl::Tags::Naive->new( max_level=>2 );
12 $naive_tagger->process(
13 files => ['Foo.pm', 'bar.pl'],
14 refresh=>1
15 );
16 Recursively follows "use" and "require" statements, up to a maximum of
18 "max_level".
19 The implemented tagger, "Perl::Tags::Naive" is a more-or-less straight
21 ripoff, slightly updated, of the original pltags code, and is rather
22 naive. It should be possible to subclass using something like "PPI" or
23 "Text::Balanced", though be aware that this is alpha software and the
24 internals are subject to change (so get in touch to let me know what
25 you want to do and I'll try to help).
26
28 * Recursive, incremental tagging.
29 * parses `use_ok`/`require_ok` line from Test::More
30
32 "Perl::Tags" is designed to be used with vim. My
33 "~/.vim/ftplugin/perl.vim" contains the following:
34 setlocal iskeyword+=: " make tags with :: in them useful
36 if ! exists("s:defined_functions")
38 function s:init_tags()
39 perl <<EOF
40 use Perl::Tags;
41 $naive_tagger = Perl::Tags::Naive->new( max_level=>2 );
42 # only go one level down by default
43 EOF
44 endfunction
45 " let vim do the tempfile cleanup and protection
47 let s:tagsfile = tempname()
48 function s:do_tags(filename)
50 perl <<EOF
51 my $filename = VIM::Eval('a:filename');
52 $naive_tagger->process(files => $filename, refresh=>1 );
54 my $tagsfile=VIM::Eval('s:tagsfile');
56 VIM::SetOption("tags+=$tagsfile");
57 # of course, it may not even output, for example, if there's nothing new to process
59 $naive_tagger->output( outfile => $tagsfile );
60 EOF
61 endfunction
62 call s:init_tags() " only the first time
64 let s:defined_functions = 1
66 endif
67 call s:do_tags(expand('%'))
69 augroup perltags
71 au!
72 autocmd BufRead,BufWritePost *.pm,*.pl call s:do_tags(expand('%'))
73 augroup END
74 Note the following:
76 · You will need to have a vim with perl compiled in it. Debuntu
78 packages this as "vim-perl". Alternatively you can compile from
79 source (you'll need Perl + the development headers "libperl-dev").
80 · The "EOF" in the examples has to be at the beginning of the line
82 (the verbatim text above has leading whitespace)
83
85 "new"
86 Perl::Tags is an abstract baseclass. Perl::Tags::Naive is provided and
87 can be instantiated with "new".
88 $naive_tagger = Perl::Tags::Naive->new( max_level=>2 );
90 Accepts the following parameters
92 max_level: levels of "use" statements to descend into, default 2
94 do_variables: tag variables? default 1 (true)
95 exts: use the Exuberant extensions
96 "to_string"
98 A Perl::Tags object will stringify to a textual representation of a
99 ctags file.
100 print $tagger;
102 "clean_file"
104 Delete all tags, but without touching the "order" seen, that way, if
105 the tags are recreated, they will remain near the top of the
106 "interestingness" tree
107 "output"
109 Save the file to disk if it has changed. (The private "{is_dirty}"
110 attribute is used, as the tags object may be made up incrementally and
111 recursively within your IDE.
112 "process"
114 Scan one or more Perl file for tags
115 $tagger->process(
117 files => [ 'Module.pm', 'script.pl' ]
118 );
119 $tagger->process(
120 files => 'script.pl',
121 refresh => 1,
122 );
123 "queue", "popqueue"
125 Internal methods managing the processing
126 "process_item", "process_file"
128 Do the heavy lifting for "process" above.
129 "register"
131 The parsing is done by a number of lightweight objects (parsers) which
132 look for subroutine references, variables, module inclusion etc. When
133 they are successful, they call the "register" method in the main tags
134 object.
135 "get_parsers"
137 Return the parses for this object. Abstract, see Perl::Tags::Naive
138 below.
139
141 A naive implementation. That is to say, it's based on the classic
142 "pltags.pl" script distributed with Perl, which is by and large a
143 better bet than the results produced by "ctags". But a "better"
144 approach may be to integrate this with PPI.
145 Subclassing
147 See TodoTagger in the "t/" directory of the distribution for a fully
148 working example (tested in <t/02_subclass.t>). You may want to reuse
149 parsers in the ::Naive package, or use all of the existing parsers and
150 add your own.
151 package My::Tagger;
153 use Perl::Tags;
154 our @ISA = qw( Perl::Tags::Naive );
155 sub get_parsers {
157 my $self = shift;
158 return (
159 $self->can('todo_line'), # a new parser
160 $self->SUPER::get_parsers(), # all ::Naive's parsers
161 # or maybe...
162 $self->can('variable'), # one of ::Naive's parsers
163 );
164 }
165 sub todo_line {
167 # your new parser code here!
168 }
169 sub package_line {
170 # override one of ::Naive's parsers
171 }
172 Because ::Naive uses "can('parser')" instead of "\&parser", you can
174 just override a particular parser by redefining in the subclass.
175 "get_parsers"
177 The following parsers are defined by this module.
178 "trim"
180 A filter rather than a parser, removes whitespace and comments.
181 "variable"
183 Tags definitions of "my", "our", and "local" variables.
184 Returns a Perl::Tags::Tag::Var if found
186 "package_line"
188 Parse a package declaration, returning a Perl::Tags::Tag::Package
189 if found.
190 "sub_line"
192 Parse the declaration of a subroutine, returning a
193 Perl::Tags::Tag::Sub if found.
194 "use_constant"
196 Parse a use constant directive
197 "use_line"
199 Parse a use, require, and also a use_ok line (from Test::More).
200 Uses a dummy tag (Perl::Tags::Tag::Recurse to do so).
201 "label_line"
203 Parse label declaration
204
206 A superclass for tags
207 "new"
209 Returns a new tag object
210 "type", "modify_options"
212 Abstract methods
213 "to_string"
215 A tag stringifies to an appropriate line in a ctags file.
216 "on_register"
218 Allows tag to meddle with process when registered with the main tagger
219 object. Return false if want to prevent registration (true normally).`
220
222 "type": p
223 "modify_options"
224 Sets static=0
225 "on_register"
227 Sets the package name
228
230 "type": v
231 "on_register"
232 Make a tag for this variable unless we're told not to. We
233 assume that a variable is always static, unless it appears
234 in a package before any sub. (Not necessarily true, but
235 it's ok for most purposes and Vim works fine even if it is
236 incorrect)
237 - pltags.pl comments
238
240 "type": s
241 "on_register"
242 Make a tag for this sub unless we're told not to. We assume
243 that a sub is static, unless it appears in a package. (Not
244 necessarily true, but it's ok for most purposes and Vim works
245 fine even if it is incorrect)
246 - pltags comments
247
249 "type": c
251 "type": l
253 "type": dummy
254 "on_register"
255 Recurse adding this new module to the queue.
256
258 Contributions are always welcome. The repo is in git:
259 http://github.com/osfameron/perl-tags
261 Please fork and make pull request. Maint bits available on request.
263 wolverian
265 ::PPI subclass
266 Ian Tegebo
268 patch to use File::Temp
269 DMITRI
271 patch to parse constant and label declarations
272 drbean
274 ::Naive::Spiffy and ::Naive::Lib subclasses
275 Alias
277 prodding me to make repo public
278 nothingmuch
280 ::PPI fixes
281 tsee
283 Command line interface, applying patches
284
286 osfameron (2006-2009) - osfameron@cpan.org
287 and contributors, as above
288 For support, try emailing me or grabbing me on irc #london.pm on
290 irc.perl.org
291 This was originally ripped off pltags.pl, as distributed with vim and
293 available from <http://www.mscha.com/mscha.html?pltags#tools> Version
294 2.3, 28 February 2002 Written by Michael Schaap <pltags@mscha.com>.
295 This is licensed under the same terms as Perl itself. (Or as Vim if
297 you prefer).
298perl v5.12.0 2009-11-24 Perl::Tags(3)