.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "PPIx::DocumentName 3pm" .TH PPIx::DocumentName 3pm "2021-01-08" "perl v5.32.0" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" PPIx::DocumentName \- Utility to extract a name from a PPI Document .SH "VERSION" .IX Header "VERSION" version 0.001003 .SH "DESCRIPTION" .IX Header "DESCRIPTION" This module contains a few utilities for extracting a \*(L"name\*(R" out of an arbitrary Perl file. .PP Typically, this is the \f(CW\*(C`module\*(C'\fR name, in the form: .PP .Vb 1 \& package Foo .Ve .PP However, it also supports extraction of an override statement in the form: .PP .Vb 1 \& # PODNAME: OverrideName::Goes::Here .Ve .PP Which may be more applicable for documents that lack a \f(CW\*(C`package\*(C'\fR statement, or the \f(CW\*(C`package\*(C'\fR statement may be \*(L"wrong\*(R", but they still need the document parsed under the guise of having a name ( for purposes such as \s-1POD\s0 ) .SH "USAGE" .IX Header "USAGE" The recommended approach is simply: .PP .Vb 1 \& use PPIx::DocumentName; \& \& # Get a PPI Document Somehow \& return PPIx::DocumentName\->extract( $ppi_document ); .Ve .SH "METHODS" .IX Header "METHODS" .SS "extract" .IX Subsection "extract" .Vb 1 \& my $docname = PPIx::DocumentName\->extract( $ppi_document ); .Ve .PP This will first attempt to extract a name via the \f(CW\*(C`PODNAME: \*(C'\fR comment notation, and then fall back to using a \f(CW\*(C`package Package::Name\*(C'\fR statement. .PP \&\f(CW$ppi_document\fR is ideally a \f(CW\*(C`PPI::Document\*(C'\fR, but will be auto-up-cast if it is any of the parameters \f(CW\*(C`PPI::Document\->new()\*(C'\fR understands. .SS "extract_via_statement" .IX Subsection "extract_via_statement" .Vb 1 \& my $docname = PPIx::DocumentName\->extract_via_statement( $ppi_document ); .Ve .PP This only extract \f(CW\*(C`package Package::Name\*(C'\fR statement based document names. .PP \&\f(CW$ppi_document\fR is ideally a \f(CW\*(C`PPI::Document\*(C'\fR, but will be auto-up-cast if it is any of the parameters \f(CW\*(C`PPI::Document\->new()\*(C'\fR understands. .SS "extract_via_comment" .IX Subsection "extract_via_comment" .Vb 1 \& my $docname = PPIx::DocumentName\->extract_via_comment( $ppi_document ); .Ve .PP This will only extract \f(CW\*(C`PODNAME: \*(C'\fR comment based document names. .PP \&\f(CW$ppi_document\fR is ideally a \f(CW\*(C`PPI::Document\*(C'\fR, but will be auto-up-cast if it is any of the parameters \f(CW\*(C`PPI::Document\->new()\*(C'\fR understands. .SH "ALTERNATIVE NAMES" .IX Header "ALTERNATIVE NAMES" Other things I could have called this .IP "\(bu" 4 \&\f(CW\*(C`PPIx::PodName\*(C'\fR \- But it isn't, because it doesn't extract from \f(CW\*(C`POD\*(C'\fR, only returns data that may be useful \fB\s-1FOR\s0\fR \&\f(CW\*(C`POD\*(C'\fR .IP "\(bu" 4 \&\f(CW\*(C`PPIx::ModuleName\*(C'\fR \- But it kinda isn't either, because its more generic than that and is tailored to extracting \&\*(L"a name\*(R" out of any \s-1PPI\s0 Document, and they're \fI\s-1NOT\s0\fR all modules. .SH "SIMILAR MODULES" .IX Header "SIMILAR MODULES" Modules that are perceptibly similar to this ones tasks ( but are subtly different in important ways ) are as follows: .IP "\(bu" 4 \&\f(CW\*(C`Module::Metadata\*(C'\fR \- 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. .Sp Module::Metadata is predominantly concerned with extracting \fI\s-1ALL\s0\fR name spaces and \fI\s-1ALL\s0\fR versions from a module for the purposes of indexing and indexing related tasks. This also means it has a notion of \*(L"hideable\*(R" name spaces with the purpose of hiding them from \f(CW\*(C`CPAN\*(C'\fR. .Sp Due to being core as well, it is not able to use \f(CW\*(C`PPI\*(C'\fR 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. .Sp Whereas \f(CW\*(C`PPIx::DocumentName\*(C'\fR only cares about the \fIfirst\fR name of a given class, and it cares much more about nested strings being ignored intentionally. It also has a motive to show names \fIeven\fR for documents that won't be indexed ( And \f(CW\*(C`Module::Metadata\*(C'\fR has no short term plans on exposing hidden document names ). .Sp \&\f(CW\*(C`PPIx::DocumentName\*(C'\fR also has special logic for the \f(CW\*(C`PODNAME: \*(C'\fR declaration, and may eventually support other mechanisms for extracting a name from \*(L"a document\*(R", which will be not in \f(CW\*(C`Module::Metadata\*(C'\fR's collection of desired use-cases. .IP "\(bu" 4 \&\f(CW\*(C`Module::Extract::Namespaces\*(C'\fR \- This is probably closer to \&\f(CW\*(C`PPIx::DocumentName\*(C'\fR's requirements, using \f(CW\*(C`PPI\*(C'\fR to extract content. .Sp Most of \f(CW\*(C`Module::Extract::Namespaces\*(C'\fR's code seems to be glue for legacy versions of \f(CW\*(C`PPI\*(C'\fR and the remaining code is for loading modules from \f(CW@INC\fR ( Which we don't need ), or special casing \s-1IO\s0 ( Which is also not necessary, as this module assumes you're moderately acquainted with \f(CW\*(C`PPI\*(C'\fR and can do \s-1IO\s0 yourself ) .Sp \&\f(CW\*(C`Module::Extract::Namespaces\*(C'\fR also obliterates document comments, which of course stands in the way of our auxiliary requirements re \f(CW\*(C`PODNAME: \*(C'\fR declarations. .Sp It will also not be flexible enough to support other name extraction features we may eventually add. .Sp And like \f(CW\*(C`Module::Metadata\*(C'\fR, it also focuses on extracting \fImany\fR \f(CW\*(C`package\*(C'\fR declarations where this module prefers to extract only the \fIfirst\fR. .SH "ACKNOWLEDGEMENTS" .IX Header "ACKNOWLEDGEMENTS" The bulk of this logic was extrapolated from \f(CW\*(C`Pod::Weaver::Section::Name\*(C'\fR and a related role, \f(CW\*(C`Pod::Weaver::Role::StringFromComment\*(C'\fR. .PP Thanks to \f(CW\*(C`RJBS\*(C'\fR for the initial implementation and \f(CW\*(C`DROLSKY\*(C'\fR for some of the improvement patches. .SH "AUTHOR" .IX Header "AUTHOR" Kent Fredric .SH "COPYRIGHT AND LICENSE" .IX Header "COPYRIGHT AND LICENSE" This software is copyright (c) 2017 by Kent Fredric . .PP This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.