Perl::Tags(3)

💖 Perl::Tags — the manual, but make it cute 💖

okay so bestie, lemme put you on. this is Perl::Tags, and it generates (possibly exuberant) Ctags style tags for your Perl sourcecode. yes. it tags your Perl. it's giving ✨developer tooling✨ and honestly? iconic.

---

✨ SYNOPSIS ✨

🦋 Using Perl::Tags to assist your development

Perl::Tags is literally designed to be integrated into your development environment. here are a few ways to use it, no gatekeeping:

💅 With Vim

Perl::Tags was originally designed to be used with vim. see <https://github.com/osfameron/perl-tags-vim> for an easily installable Plugin. obsessed.

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. periodt.

🌸 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. it just keeps going, bestie 💫

---

🔍 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. lowkey the MVP fr fr.

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. the trade-off is real 😭
• Perl::Tags::Hybrid — Can run multiple taggers, such as ::Naive and ::PPI, combining the results. the way that it just merges everything? slay.

---

🌈 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. it's giving ✨inception✨ ngl

---

💖 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. no skipping this one bestie, it's abstract, it won't work without it 💀

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.

• DMITRI — many patches for features and bugfixes
• wolverian — ::PPI subclass
• Ian Tegebo — patch to use File::Temp
• drbean — ::Naive::Moose, ::Naive::Spiffy and ::Naive::Lib subclasses
• Alias — prodding me to make repo public
• tsee — Command line interface, applying patches
• nothingmuch
• Andreas Koenig
• ether

---

💜 AUTHOR and LICENSE 💜

osfameron (2006-2014) - 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).

---

and that's the whole page bestie! 💅 this was generated by perl v5.42.0 on 2025-07-25, and yeah it's the Perl::Tags(3) manual. go forth and tag ur Perl, you main character 🦋✨💖