PPIx::...ntName(3pm)

💖 PPIx::DocumentName — the manual, but make it cute ✨

okay bestie, so this is PPIx::DocumentName, a lil utility that pulls a name out of a PPI Document. It ships as part of User Contributed Perl Documentation, and it's sitting at version 1.01 right now. Periodt. 👑

---

🌸 NAME 🌸

PPIx::DocumentName — utility to extract a name from a PPI Document 🎀

🦋 VERSION 🦋

version 1.01

✨ SYNOPSIS ✨

New API:

use PPIx::DocumentName 1.00 -api => 1;
my $result = PPIx::DocumentName->extract( $ppi_document );

# say the "name" of the document
say $result->name;

# the result object can also be stringified into the name found:
say "$result";

# the line number, column, filename etc. where the name was found
my $location = $result->node->location;

Old API:

use PPIx::DocumentName;  # assumes -api => 0
my $name = PPIx::DocumentName->extract( $ppi_document );

# say the "name" of the document
say $name;

---

💜 DESCRIPTION 💜

So this module is literally a lil grab-bag of utilities for extracting a "name" out of any random Perl file you throw at it. 🫶

Most of the time that's the "module" name, looking like this:

package Foo

But plot twist — it can also pull out an override statement shaped like this:

# PODNAME: OverrideName::Goes::Here

And that second one matters for documents that have no package statement at all, or whose package statement is just straight-up wrong, but which still need to be parsed as though they had a name. It's giving "POD purposes", iykyk. 💅

🔥 METHODS 🔥

🌟 extract

my $result = PPIx::Document->extract( $ppi_document);

Okay so first thing it does: it tries to grab a name through the "PODNAME: " comment notation, and then falls back to using a package Package::Name statement. Bestie tries the cute way first, then the boring way. 💖

$ppi_document is ideally a PPI::Document, but it'll get auto-up-cast if you hand it any of the parameters PPI::Document->new() understands. No stress.

Now, $result? Under -api => 0 it's just the found name as a string. Under -api => 1 it's a PPIx::DocumentName::Result object. If the name isn't found, you get undef — with either API, no favourites. And heads up: PPIx::DocumentName::Result stringifies to the found name, so honestly in a lot of situations the new API can be used exactly like the old one. Slay. ✨

🌟 extract_via_statement

my $result = PPIx::DocumentName->extract_via_statement( $ppi_document );

This one only extracts package Package::Name statement-based document names. That's it, that's the whole vibe.

$ppi_document is ideally a PPI::Document, but will be auto-up-cast if it's any of the parameters PPI::Document->new() understands.

$result is the found name as a string under -api => 0, and a PPIx::DocumentName::Result object under -api => 1. If the name isn't found, it's undef (with either API). 💀

🌟 extract_via_comment

my $result = PPIx::DocumentName->extract_via_comment( $ppi_document );

This one will only extract "PODNAME: " comment-based document names. Same energy, different source. 🎀

$ppi_document is ideally a PPI::Document, but will be auto-up-cast if it's any of the parameters PPI::Document->new() understands.

$result is the found name as a string under -api => 0, and a PPIx::DocumentName::Result object under -api => 1. If the name isn't found, it's undef (with either API). 💖

---

😭 CAVEATS 😭

Listen, this part is important, don't skip it. 🚨

The newer API (-api => 1) is packaged scoped in Perl 5.6 and 5.8. In newer Perls the API is block scoped, as it should be. Because this can cause bugs if you're running an older version of Perl, this module will complain loudly if you use an older Perl with the newer API. Not me being dramatic, that's literally the behaviour. So if you don't like the warning? Either use the old API, or upgrade to Perl 5.10+. Your call, bestie. 💅

Under the older API (-api => 0, the default), extract_via_statement — unlike the other methods in this module — returns an empty list instead of undef when it does find a name. Yeah. Inconsistent, I know. 😭 When you're on the newer API (-api => 1), calls are consistent in scalar and list context. So new code should use the newer API. Periodt. 👑

🌈 ALTERNATIVE NAMES 🌈

Other things I could have called this:

• "PPIx::PodName" — but it isn't, because it doesn't extract from "POD", it only returns data that may be useful FOR "POD" 💅
• "PPIx::ModuleName" — but it kinda isn't either, because it's more generic than that and is tailored to extracting "a name" out of any PPI Document, and they're NOT all modules. 🙈

👑 SEE ALSO 👑

Modules that are perceptibly similar to this one's tasks (but are subtly different in important ways) are as follows:

• "Module::Metadata" — Module::Metadata does a bunch of things this module explicitly doesn't want or need to do, and it lacks a bunch of features this module needs. 🧚

Module::Metadata is predominantly concerned with extracting ALL name spaces and ALL versions from a module for the purposes of indexing and indexing-related tasks. This also means it has a notion of "hideable" name spaces with the purpose of hiding them from "CPAN".

Due to being core as well, it is not able to use "PPI" for its features, so the above concerns mean it is also mostly based on careful regex parsing, which can easily be false tripped on miscellaneous in-document content. 😬

Whereas "PPIx::DocumentName" only cares about the first name of a given class, and it cares much more about nested strings being ignored intentionally. It also has a motive to show names even for documents that won't be indexed (and "Module::Metadata" has no short term plans on exposing hidden document names).

"PPIx::DocumentName" also has special logic for the "PODNAME: " declaration, and may eventually support other mechanisms for extracting a name from "a document", which will be not in "Module::Metadata"'s collection of desired use-cases. ✨

• "Module::Extract::Namespaces" — this is probably closer to "PPIx::DocumentName"'s requirements, using "PPI" to extract content.

Most of "Module::Extract::Namespaces"'s code seems to be glue for legacy versions of "PPI", and the remaining code is for loading modules from @INC (which we don't need), or special casing IO (which is also not necessary, as this module assumes you're moderately acquainted with "PPI" and can do IO yourself). 🫶

"Module::Extract::Namespaces" also obliterates document comments, which of course stands in the way of our auxiliary requirements re "PODNAME: " declarations. 💀

It will also not be flexible enough to support other name extraction features we may eventually add.

And like "Module::Metadata", it also focuses on extracting many "package" declarations where this module prefers to extract only the first. 🌟

• "PPIx::DocumentName::Result" — comes with this module, and contains the results of this module, when using the newer -api => 1 API. 🎀

🫶 ACKNOWLEDGEMENTS 🫶

The bulk of this logic was extrapolated from "Pod::Weaver::Section::Name" and a related role, "Pod::Weaver::Role::StringFromComment".

Thanks to "RJBS" <cpan:///author/RJBS> for the initial implementation, and "DROLSKY" <cpan:///author/DROLSKY> for some of the improvement patches. Absolute icons, both of them. 💖

🌸 AUTHORS 🌸

• Kent Fredric <kentnl@cpan.org>
• Graham Ollis <plicease@cpan.org>

💅 COPYRIGHT AND LICENSE 💅

This software is copyright (c) 2015-2021 by Kent Fredric <kentfredric@gmail.com>.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.

---

okay so that's the whole page, no cap. 🎀

and that's a wrap, bestie — this was PPIx::DocumentName(3pm) from User Contributed Perl Documentation, perl v5.32.1, dated 2021-09-30. go forth and extract those names. slay. 💖✨🦋