NAME

       PPIx::DocumentName - Utility to extract a name from a PPI Document

VERSION

       version 0.001003

DESCRIPTION

       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 )

USAGE

       The recommended approach is simply:

         use PPIx::DocumentName;

         # Get a PPI Document Somehow
         return PPIx::DocumentName->extract( $ppi_document );

METHODS

   extract
         my $docname = PPIx::DocumentName->extract( $ppi_document );

       This will first attempt to extract a name via the "PODNAME: " comment notation, and then
       fall back to using a "package Package::Name" statement.

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

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

       This only extract "package Package::Name" statement based document names.

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

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

       This will only extract "PODNAME: " comment based document names.

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

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.

SIMILAR MODULES

       Modules that are perceptibly similar to this ones 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.

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.

AUTHOR

       Kent Fredric <kentnl@cpan.org>

COPYRIGHT AND LICENSE

       This software is copyright (c) 2017 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.