Perl::Tags(3) User Contributed Perl Documentation Perl::Tags(3)NAMEPerl::Tags - Generate (possibly exuberant) Ctags style tags for Perl
sourcecode
SYNOPSIS
use Perl::Tags;
my $naive_tagger = Perl::Tags::Naive->new( max_level=>2 );
$naive_tagger->process(
files => ['Foo.pm', 'bar.pl'],
refresh=>1
);
Recursively follows "use" and "require" statements, up to a maximum of
"max_level".
The implemented tagger, "Perl::Tags::Naive" is a more-or-less straight
ripoff, slightly updated, of the original pltags code, and is rather
naive. It should be possible to subclass using something like "PPI" or
"Text::Balanced", though be aware that this is alpha software and the
internals are subject to change (so get in touch to let me know what
you want to do and I'll try to help).
FEATURES
* Recursive, incremental tagging.
* parses `use_ok`/`require_ok` line from Test::More
USING with VIM
"Perl::Tags" is designed to be used with vim. My
"~/.vim/ftplugin/perl.vim" contains the following:
setlocal iskeyword+=: " make tags with :: in them useful
if ! exists("s:defined_functions")
function s:init_tags()
perl <<EOF
use Perl::Tags;
$naive_tagger = Perl::Tags::Naive->new( max_level=>2 );
# only go one level down by default
EOF
endfunction
" let vim do the tempfile cleanup and protection
let s:tagsfile = tempname()
function s:do_tags(filename)
perl <<EOF
my $filename = VIM::Eval('a:filename');
$naive_tagger->process(files => $filename, refresh=>1 );
my $tagsfile=VIM::Eval('s:tagsfile');
VIM::SetOption("tags+=$tagsfile");
# of course, it may not even output, for example, if there's nothing new to process
$naive_tagger->output( outfile => $tagsfile );
EOF
endfunction
call s:init_tags() " only the first time
let s:defined_functions = 1
endif
call s:do_tags(expand('%'))
augroup perltags
au!
autocmd BufRead,BufWritePost *.pm,*.pl call s:do_tags(expand('%'))
augroup END
Note the following:
· You will need to have a vim with perl compiled in it. Debuntu
packages this as "vim-perl". Alternatively you can compile from
source (you'll need Perl + the development headers "libperl-dev").
· The "EOF" in the examples has to be at the beginning of the line
(the verbatim text above has leading whitespace)
METHODS
"new"
Perl::Tags is an abstract baseclass. Perl::Tags::Naive is provided and
can be instantiated with "new".
$naive_tagger = Perl::Tags::Naive->new( max_level=>2 );
Accepts the following parameters
max_level: levels of "use" statements to descend into, default 2
do_variables: tag variables? default 1 (true)
exts: use the Exuberant extensions
"to_string"
A Perl::Tags object will stringify to a textual representation of a
ctags file.
print $tagger;
"clean_file"
Delete all tags, but without touching the "order" seen, that way, if
the tags are recreated, they will remain near the top of the
"interestingness" tree
"output"
Save the file to disk if it has changed. (The private "{is_dirty}"
attribute is used, as the tags object may be made up incrementally and
recursively within your IDE.
"process"
Scan one or more Perl file for tags
$tagger->process(
files => [ 'Module.pm', 'script.pl' ]
);
$tagger->process(
files => 'script.pl',
refresh => 1,
);
"queue", "popqueue"
Internal methods managing the processing
"process_item", "process_file"
Do the heavy lifting for "process" above.
"register"
The parsing is done by a number of lightweight objects (parsers) which
look for subroutine references, variables, module inclusion etc. When
they are successful, they call the "register" method in the main tags
object.
"get_parsers"
Return the parses for this object. Abstract, see Perl::Tags::Naive
below.
"Perl::Tags::Naive"
A naive implementation. That is to say, it's based on the classic
"pltags.pl" script distributed with Perl, which is by and large a
better bet than the results produced by "ctags". But a "better"
approach may be to integrate this with PPI.
Subclassing
See TodoTagger in the "t/" directory of the distribution for a fully
working example (tested in <t/02_subclass.t>). You may want to reuse
parsers in the ::Naive package, or use all of the existing parsers and
add your own.
package My::Tagger;
use Perl::Tags;
our @ISA = qw( Perl::Tags::Naive );
sub get_parsers {
my $self = shift;
return (
$self->can('todo_line'), # a new parser
$self->SUPER::get_parsers(), # all ::Naive's parsers
# or maybe...
$self->can('variable'), # one of ::Naive's parsers
);
}
sub todo_line {
# your new parser code here!
}
sub package_line {
# override one of ::Naive's parsers
}
Because ::Naive uses "can('parser')" instead of "\&parser", you can
just override a particular parser by redefining in the subclass.
"get_parsers"
The following parsers are defined by this module.
"trim"
A filter rather than a parser, removes whitespace and comments.
"variable"
Tags definitions of "my", "our", and "local" variables.
Returns a Perl::Tags::Tag::Var if found
"package_line"
Parse a package declaration, returning a Perl::Tags::Tag::Package
if found.
"sub_line"
Parse the declaration of a subroutine, returning a
Perl::Tags::Tag::Sub if found.
"use_constant"
Parse a use constant directive
"use_line"
Parse a use, require, and also a use_ok line (from Test::More).
Uses a dummy tag (Perl::Tags::Tag::Recurse to do so).
"label_line"
Parse label declaration
"Perl::Tags::Tag"
A superclass for tags
"new"
Returns a new tag object
"type", "modify_options"
Abstract methods
"to_string"
A tag stringifies to an appropriate line in a ctags file.
"on_register"
Allows tag to meddle with process when registered with the main tagger
object. Return false if want to prevent registration (true normally).`
"Perl::Tags::Tag::Package"
"type": p
"modify_options"
Sets static=0
"on_register"
Sets the package name
"Perl::Tags::Tag::Var"
"type": v
"on_register"
Make a tag for this variable unless we're told not to. We
assume that a variable is always static, unless it appears
in a package before any sub. (Not necessarily true, but
it's ok for most purposes and Vim works fine even if it is
incorrect)
- pltags.pl comments
"Perl::Tags::Tag::Sub"
"type": s
"on_register"
Make a tag for this sub unless we're told not to. We assume
that a sub is static, unless it appears in a package. (Not
necessarily true, but it's ok for most purposes and Vim works
fine even if it is incorrect)
- pltags comments
"Perl::Tags::Tag::Constant"
"type": c
"Perl::Tags::Tag::Label"
"type": l
"Perl::Tags::Tag::Recurse"
"type": dummy
"on_register"
Recurse adding this new module to the queue.
CONTRIBUTIONS
Contributions are always welcome. The repo is in git:
http://github.com/osfameron/perl-tags
Please fork and make pull request. Maint bits available on request.
wolverian
::PPI subclass
Ian Tegebo
patch to use File::Temp
DMITRI
patch to parse constant and label declarations
drbean
::Naive::Spiffy and ::Naive::Lib subclasses
Alias
prodding me to make repo public
nothingmuch
::PPI fixes
tsee
Command line interface, applying patches
AUTHOR and LICENSE
osfameron (2006-2009) - osfameron@cpan.org
and contributors, as above
For support, try emailing me or grabbing me on irc #london.pm on
irc.perl.org
This was originally ripped off pltags.pl, as distributed with vim and
available from <http://www.mscha.com/mscha.html?pltags#tools> Version
2.3, 28 February 2002 Written by Michael Schaap <pltags@mscha.com>.
This is licensed under the same terms as Perl itself. (Or as Vim if
you prefer).
perl v5.14.1 2009-11-24 Perl::Tags(3)
