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

    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

 extract

     my $result = PPIx::Document->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.

    The $result is the found name as a string under -api => 0 and a
    PPIx::DocumentName::Result object under -api => 1. If the name is not
    found, then it will be undef (with either API). Note that
    PPIx::DocumentName::Result is stringified to the found name, so in many
    circumstances the new API can be used in the same way as the old.

 extract_via_statement

      my $result = 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.

    The $result is the found name as a string under -api => 0 and a
    PPIx::DocumentName::Result object under -api => 1. If the name is not
    found, then it will be undef (with either API).

 extract_via_comment

      my $result = 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.

    The $result is the found name as a string under -api => 0 and a
    PPIx::DocumentName::Result object under -api => 1. If the name is not
    found, then it will be undef (with either API).

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.

SEE ALSO

    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.

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

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.

