PPIx::DocumentName3pm

Usage

 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;

 use PPIx::DocumentName;  # assumes -api => 0
 my $name = PPIx::DocumentName->extract( $ppi_document );
 
 # say the "name" of the document
 say $name;

Version

version 1.01

Overview

This module contains a few utilities for extracting a "name" out of an arbitrary Perl file.

Typically, this is the "module" name, in the form:

  package Foo

However, it also supports extraction of an override statement in the form:

  # PODNAME: OverrideName::Goes::Here

Which may be more applicable for documents that lack a "package" statement, or the "package" statement may be "wrong", but they still need the document parsed under the guise of having a name ( for purposes such as POD )

Methods

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

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

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

Caveats

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 are using an older version of Perl this module will complain loudly if you are using an older Perl with the newer API. If you don't like the warning, then either use the old API or upgrade to Perl 5.10+.

Under the older API ("-api => 0"; the default), "extract_via_statement", unlike the other methods in this module, returns empty list instead of undef when it does find a name. When using the newer API ("-api => 1"), calls are consistent in scalar and list context. New code should therefore use the newer API.

Alternative names

Other things I could have called this

•

"PPIx::PodName" - But it isn't, because it doesn't extract from "POD", only returns data that may be useful FOR "POD"

•

"PPIx::ModuleName" - But it kinda isn't either, because its more generic than that and is tailored to extracting "a name" out of any PPI Document, and they're NOT all modules.

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.

Copyright and license

This software is copyright (c) 2015-2021 by Kent Fredric <[email protected]>.

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