Pod::MinimumVersion3pm

Usage

 use Pod::MinimumVersion;
 my $pmv = Pod::MinimumVersion->new (filename => '/some/foo.pl');
 print $pmv->minimum_version,"\n";
 print $pmv->reports;

Overview

"Pod::MinimumVersion" parses the POD in a Perl script, module, or document, and reports what version of Perl is required to process the directives in it with "pod2man" etc.

Checks

The following POD features are identified.

•

5.004: new "=for", "=begin" and "=end"

•

5.005: new L<display text|target> style display part

•

5.6.0: new C<< foo >> etc double-angles

•

5.8.0: new "=head3" and "=head4"

•

5.8.0: new L<http://some.where.com> URLs. (Before 5.8 the "/" is a "section" separator, giving very poor output.)

•

5.8.0: new E<apos>, E<sol>, E<verbar> chars. (Documented in 5.6.0, but pod2man doesn't recognise them until 5.8.)

•

5.10.0: new "=encoding" command. (Documented in 5.8.0, but "pod2man" doesn't recognise it until 5.10.)

•

5.12.0: new L<display text|http://some.where.com> URL with text. (Before 5.12 the combination of display part and URL was explicitly disallowed by perlpodspec.)

POD syntax errors are quietly ignored currently. The intention is only to check what "pod2man" would act on but it's probably a good idea to use "Pod::Checker" first.

"J<< >>" for "Pod::MultiLang" is recognised and is allowed for any Perl, including with double-angles. The assumption is that if you're writing that then you'll first crunch with the "Pod::MultiLang" tools, so it's not important what "pod2man" thinks of it.

Functions

"$pmv = Pod::MinimumVersion->new (key => value, ...)"

Create and return a new "Pod::MinimumVersion" object which will analyze a document. The document is supplied as one of

    filehandle => $fh,
    string     => 'something',
    filename   => '/my/dir/foo.pod',

For "filehandle" and "string", a "filename" can be supplied too to give a name in the reports. The handle or string is what's actually read.

The "above_version" option lets you set a Perl version of you have or are targeting, so reports are only about features above that level.

    above_version => '5.006',

"$version = $pmv->minimum_version ()"

"$report = $pmv->minimum_report ()"

Return the minimum Perl required for the document in $pmv.

"minimum_version" returns a "version" number object (see version). "minimum_report" returns a "Pod::MinimumVersion::Report" object (see "REPORT OBJECTS" below).

"@reports = $pmv->reports ()"

Return a list of "Pod::MinimumVersion::Report" objects concerning the document in $pmv.

These multiple reports let you identify multiple places that a particular Perl is required. With the "above_version" option the reports are only about things higher than that.

"minimum_version" and "minimum_report" are simply the highest Perl among these multiple reports.

Report objects

A "Pod::MinimumVersion::Report" object holds a location within a document and a reason that a particular Perl is needed at that point. The hash fields are

    filename   string
    linenum    integer, with 1 for the first line
    version    version.pm object
    why        string

"$str = $report->as_string"

Return a formatted string for the report. Currently this is in GNU file:line style, simply

    <filename>:<linenum>: <version> due to <why>

Home page

http://user42.tuxfamily.org/pod-minimumversion/index.html