Module:...mespaces(3)

💖 Module::Extract::Namespaces 💖

okay bestie, so this is a page from the User Contributed Perl Documentation for Module:...mespaces(3) — yes the man name is literally abbreviated with dots like that, it's giving cryptic-but-cute. Let's get into it 🦋

---

✨ NAME ✨

Module::Extract::Namespaces — extract the package declarations from a module 💅

Like, it goes into a module and pulls out the package lines. That's the whole job. Iconic.

---

🌸 SYNOPSIS 🌸

use Module::Extract::Namespaces;

# in scalar context, extract first package namespace
my $namespace  = Module::Extract::Namespaces->from_file( $filename );
if( Module::Extract::Namespaces->error ) { ... }

# in list context, extract all namespaces
my @namespaces = Module::Extract::Namespaces->from_file( $filename );
if( Module::Extract::Namespaces->error ) { ... }

# can do the Perl 5.12 package syntax with possible versions
# in list context, extract all namespaces and versions as duples
my @namespaces = Module::Extract::Namespaces->from_file( $filename, 1 );
if( Module::Extract::Namespaces->error ) { ... }

---

💜 DESCRIPTION 💜

This module extracts package declarations from Perl code without running the code. no eval, no executing, no nothing — it just reads. periodt 🔥

It does not extract:

• packages declared dynamically (e.g. in "eval")
• packages created as part of a fully qualified variable name

so like, sneaky runtime-declared packages? not our problem bestie. 🙈

🎀 Class methods 🎀

• from_module( MODULE, [ @DIRS ] ) — Extract the namespaces declared in MODULE. In list context, it returns all of the namespaces, including possible duplicates. In scalar context it returns the first declared namespace.

You can specify a list of directories to search for the module. If you don't, it uses @INC by default.

If it cannot find MODULE, it returns undef in scalar context and the empty list in list context.

On failure it returns nothing, but you have to check with "error" to see if that is really an error or a file with no namespaces in it.

• from_file( FILENAME [,WITH_VERSIONS] ) — Extract the namespaces declared in FILENAME. In list context, it returns all of the namespaces, including possible duplicates. In scalar context it returns the first declared namespace.

If FILENAME does not exist, it returns undef in scalar context and the empty list in list context.

On failure it returns nothing, but you have to check with "error" to see if that is really an error or a file with no namespaces in it.

ngl the "returns nothing but maybe it's fine" thing is a whole vibe check you have to do yourself. check "error", bestie. every time. 💀

🧚 Subclassable hooks 🧚

• $class->pdom_base_class() — Return the base class for the PDOM. This is "PPI" by default. If you want to use something else, you'll have to change all the other PDOM methods to adapt to the different interface.

This is the class name to use with "require" to load the module that while handle the parsing.

• $class->pdom_document_class() — Return the class name to use to create the PDOM object. This is "PPI::Document".
• get_pdom( FILENAME ) — Creates the PDOM from FILENAME. This depends on calls to "pdom_base_class" and "pdom_document_class".
• $class->pdom_preprocess( PDOM ) — Override this method to play with the PDOM before extracting the package declarations.

By default, it strips Pod and comments from the PDOM.

• $class->pdom_strip_pod( PDOM ) — Strips Pod documentation from the PDOM.
• $class->pdom_strip_comments( PDOM ) — Strips comments from the PDOM.
• $class->get_namespaces_from_pdom( PDOM ) — Extract the namespaces from the PDOM. It returns a list of package names in the order that it finds them in the PDOM. It does not remove duplicates (do that later if you like).
• $class->get_namespaces_and_versions_from_pdom( PDOM ) — This extracts version information if the package statement uses the Perl 5.12 syntax:

package NAME VERSION BLOCK

Extract the namespaces from the PDOM. It returns a list anonymous arrays of package names and versions in the order that it finds them in the PDOM. It does not remove duplicates (do that later if you like).

• $class->error — Return the error from the last call to "get_modules".

---

👑 TO DO 👑

• Add caching based on file digest?

one single to-do and it's a question mark. the humility. the main character energy. 😭

---

🌈 SOURCE AVAILABILITY 🌈

This code is in Github:

http://github.com/briandfoy/module-extract-namespaces

---

💖 AUTHOR 💖

brian d foy, "<briandfoy@pobox.com>"

This module was partially funded by The Perl Foundation (www.perlfoundation.org) and LogicLAB (www.logiclab.dk), both of whom provided travel assistance to the 2008 Oslo QA Hackathon where I created this module.

---

⭐ COPYRIGHT AND LICENSE ⭐

Copyright © 2008-2025, brian d foy <briandfoy@pobox.com>. All rights reserved.

You may redistribute this under the Artistic License 2.0.

---

and that's the whole page bestie 🫶 this was perl v5.42.0, dated 2025-07-25 — go forth and extract those namespaces, slay 💅✨