Parse:...ntCTags(3pm)

📦
version 1.02 · 8 versions
, in ubuntu stonking

💖 Parse::ExuberantCTags 💖

okay so bestie, welcome to Parse::ExuberantCTags — the Perl module that efficiently parses exuberant ctags files. yes ma'am, parsing tags at speed, that's the whole vibe. ✨

🌸 SYNOPSIS 🌸

use Parse::ExuberantCTags;
my $parser = Parse::ExuberantCTags->new( 'tags_filename' );

# find a given tag that starts with 'foo' and do not ignore case
my $tag = $parser->findTag("foo", ignore_case => 0, partial => 1);
if (defined $tag) {
  print $tag->{name}, "\n";
}
$tag = $parser->findNextTag();
# ...

# iterator interface (use findTag instead, it does a binary search)
$tag = $parser->firstTag;
while (defined($tag = $parser->nextTag)) {
  # use the tag structure
}

🦋 DESCRIPTION 🦋

So this Perl module parses ctags files, and it handles both traditional ctags and extended ctags files — like the ones Exuberant ctags produces. To the best of my knowledge it does not handle emacs-style "etags" files. not the vibe, sorry. 🙈

The module is basically a wrapper around the readtags library that normally ships with Exuberant ctags. If you don't know what that is, bestie, go have a lil look at <http://ctags.sourceforge.net/>. And here's the tea: to use this module you do not need Exuberant ctags on your system, because the module ships its own copy of readtags. 💅 Quoting the readtags documentation:

The functions defined in this interface are intended to provide tag file support to a software tool. The tag lookups provided are sufficiently fast enough to permit opening a sorted tag file, searching for a matching tag, then closing the tag file each time a tag is looked up (search times are on the order of hundreths of a second, even for huge tag files). This is the recommended use of this library for most tool applications. Adhering to this approach permits a user to regenerate a tag file at will without the tool needing to detect and resynchronize with changes to the tag file. Even for an unsorted 24MB tag file, tag searches take about one second.

Take away from all that: tag files should be sorted by the generating program. periodt. 🔥

🎀 TAG FORMAT 🎀

Every method that returns a tag entry returns tags in the exact same format. Examples count for a billion words, so here's one:

{
  name              => 'IO::File',
  file              => '/usr/lib/perl/5.10/IO/File.pm',
  fileScope         => 0,
  kind              => 'p',
  addressPattern    => '/package IO::File;/',
  addressLineNumber => 3,
  extension         => {
    class => 'IO::File',
  },
}

So the structure has:

  • name — the name of the tag
  • file — the file it was found in
  • fileScope — a flag saying whether the tag is scoped to the file only
  • kind — the type of the tag entry
  • addressPattern — the ex search pattern for locating the definition
  • addressLineNumber — the line number
  • extension — key/value pairs from the extension section of the tag

ngl, not all of these fields are guaranteed to be there. Especially the extension section, which will be empty if the tags file doesn't use the extended format. Refer to the ctags reference for the details, iykyk. 📖

✨ METHODS ✨

💜 new

You give it the name of a file to read the tags from, it opens that file and hands you back a Parse::ExuberantCTags object on success — and false otherwise. that's it, that's the whole serve. 🫶

💖 findTag

First argument is the name of the tag you're hunting for.

After the tag name, two optional arguments (key/value pairs) are supported:

  • partial = 1 — makes the tag name match if it's the start of a tag.
  • ignore_case = 1 — makes the search ignore the case of the tag. ⚠️ Note that setting ignore_case to true results in a slower linear search instead of a binary search! not the fast path, bestie.

Returns a tag structure, or undef if nothing matched. 😭

🌈 findNextTag

Returns the next tag that matches the previous search (peep findTag). Returns undef if no more tags match.

🍓 firstTag

Returns the first tag in the file. Returns undef if the file is empty.

🧚 nextTag

Returns the next tag, or undef if the end of the file is reached.

💀 CAVEATS 💀

The SetSortType call is currently not supported. Let the author know if you need it and he'll add a wrapper. fr fr.

⭐ SEE ALSO ⭐

👑 AUTHOR 👑

Steffen Mueller, <smueller@cpan.org>

This Perl module is a wrapper around the readtags library that is shipped as part of the exuberant ctags program. A copy of readtags is included with this module. readtags was put in the public domain by its author. The full copyright/license information from the code is:

Copyright (c) 1996-2003, Darren Hiebert
This source code is released into the public domain.

The XS wrapper and this document are:

Copyright (C) 2009-2010 by Steffen Mueller

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.6 or, at your option, any later version of Perl 5 you may have available.

and that's the whole page, bestie!! 🎀 this lil writeup came to you courtesy of perl v5.42.3, dated 2026-08-19 — iconic, no notes, slay 💅✨

📦 where this page comes from