NAME Perl::Tags - Generate (possibly exuberant) Ctags style tags for Perl sourcecode SYNOPSIS Using Perl::Tags to assist your development "Perl::Tags" is designed to be integrated into your development environment. Here are a few ways to use it: With Vim "Perl::Tags" was originally designed to be used with vim. See for an easily installable Plugin. NB: 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"). (Note that "perl-tags-vim" includes its own copy of "Perl::Tags" through the magic of git submodules and App::FatPacker, so you don't need to install this module from CPAN if you are only intending to use it with Vim as above!) From the Command Line See the "perl-tags" in bin script provided. From other editors Any editor that supports ctags should be able to use this output. Documentation and code patches on how to do this are welcome. Using the Perl::Tags module within your code use Perl::Tags; my $naive_tagger = Perl::Tags::Naive->new( max_level=>2 ); $naive_tagger->process( files => ['Foo.pm', 'bar.pl'], refresh=>1 ); print $naive_tagger; # stringifies to ctags file Recursively follows "use" and "require" statements, up to a maximum of "max_level". DETAILS There are several taggers distributed with this distribution, including: Perl::Tags::Naive This is a more-or-less straight ripoff, slightly updated, of the original pltags code. This is a "naive" tagger, in that it makes pragmatic assumptions about what Perl code usually looks like (e.g. it doesn't actually parse the code.) This is fast, lightweight, and often Good Enough. This has additional subclasses such as Perl::Tags::Naive::Moose to parse Moose declarations, and Perl::Tags::Naive::Lib to parse "use lib". Perl::Tags::PPI Uses the PPI module to do a deeper analysis and parsing of your Perl code. This is more accurate, but slower. Perl::Tags::Hybrid Can run multiple taggers, such as ::Naive and ::PPI, combining the results. EXTENDING Documentation patches are welcome: in the meantime, have a look at Perl::Tags::Naive and its subclasses for a simple line-by-line method of tagging files. Alternatively Perl::Tags::PPI uses PPI's built in method of parsing Perl documents. In general, you will want to override the "get_tags_for_file" method, returning a list of "Perl::Tags::Tag" objects to be registered. For recursively checking other modules, return a "Perl::Tags::Tag::Recurse" object, which does *not* create a new tag in the resulting perltags file, but instead processes the next file recursively. FEATURES * Recursive, incremental tagging. * parses `use_ok`/`require_ok` line from Test::More METHODS "new" Perl::Tags is an abstract baseclass. Use a class such as Perl::Tags::Naive and instantiate it 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", "get_tags_for_file" Do the heavy lifting for "process" above. Taggers *must* override the abstract method "get_tags_for_file". "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. Note that if your tagger wants to register not a new *declaration* but rather a *usage* of another module, then your tagger should return a "Perl::Tags::Tag::Recurse" object. This is a pseudo-tag which causes the linked module to be scanned in turn. See Perl::Tags::Naive's handling of "use" statements as an example! SEE ALSO "perl-tags" in bin 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::Moose, ::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 Version 2.3, 28 February 2002 Written by Michael Schaap . This is licensed under the same terms as Perl itself. (Or as Vim if you prefer).