PPIx::...Result(3pm)

💖 PPIx::DocumentName::Result — bestie edition 💖

okay so this is the man page for PPIx::DocumentName::Result, which is the Full result set for PPIx::DocumentName. yes the header calls it PPIx::...Result(3pm) because man pages love abbreviating for no reason, but it's the same girl. she's from the User Contributed Perl Documentation collection and she is serving.

---

✨ NAME ✨

PPIx::DocumentName::Result — Full result set for PPIx::DocumentName

no cap, that's literally it. that's the whole name.

---

🌸 VERSION 🌸

version 1.01

---

🦋 SYNOPSIS 🦋

here's the vibe, bestie. you use PPIx::DocumentName at version 1.00 or later with the -api => 1 flag, and you get back a result object:

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";

# get the full PPI::Document object for the entire document
my $ppi = $result->document;

# get the node where we found the name
# (usually a PPI::Statement::Package or PPI::Token::Comment)
my $node = $result->node;

# get the location where we found the name
my $location = $result->node->location;

like… the fact that you can just say "$result" and it gives you the name? iconic behavior honestly. 💅

---

💜 DESCRIPTION 💜

so this class is the whole result set that PPIx::DocumentName hands you when it's running under its shiny new -api => 1 API. she's the receipts. she holds everything. 🧾✨

---

👑 METHODS 👑

💫 name

my $name = $result->name;

gives you back the name that was found in the document. that's it. that's the method. simple, clean, slaying. 💖

💫 to_string

my $str = $result->to_string;
my $str = "$result";

converts this object into a string. same exact thing as the name method, no difference, fr fr. and plot twist: this method also gets invoked automatically if you stringify the object inside a double quoted string. so "$result" is just calling this behind the scenes. sneaky but cute. 🙈

💫 document

my $ppi = $result->document;

returns the PPI::Document of the document. the whole entire thing. 🫶

💫 node

my $node = $result->node;

returns the PPI::Node where the name was found. usually this is gonna be either PPI::Statement::Package or PPI::Token::Comment — although, and I quote, other types could be used in the future. so stay flexible, bestie. 🌈

---

🌟 SEE ALSO 🌟

• PPIx::DocumentName — the main module that generates objects of this class. she's the mother. the icon. the moment. 👑

---

🚨 CAVEATS 🚨

listen up because this one is important and I'm not gonna sugarcoat it. 💀

for node to actually be useful, the document object needs to remain in scope. that is the main reason the result object keeps it around in the first place. so if you want to use the node to get the location information, make sure you do NOT throw away the result object. do not. I'm begging.

if you yeet the result object, your node goes with it and you get undef. tragic. avoidable.

Bad:

my $node = PPIx::DocumentName->extract( $ppi_document )->node;
my $location = $node->location;  # undef

Fine:

my $result = PPIx::DocumentName->extract( $ppi_document );
my $node = $result->node;
my $location = $node->location;  # ok

see the difference? in the bad one the result object is gone by the time you ask for the location, so it's giving undef. in the fine one you hold onto $result like the main character she is, and everything works. ✨

---

🎀 AUTHORS 🎀

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

two legends. we stan. 🫶

---

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

---

and that's the whole page, bestie!! perl v5.32.1, dated 2021-09-30 — so this doc is a lil vintage but she still ate. go forth and extract those document names. 💖✨🎀🦋🌸💅