在使用Pod::Simple::HTML之前用Pod::Weaver预处理POD

Question

我正在尝试创建一个Pod::Simple::HTML的简单子类，以便与Pod::Simple::HTMLBatch一起使用。我想用荚：：韦弗对所有的过氧化物酶进行预处理。但是，我无法找到使用Pod::Weaver处理字符串文档时应该使用的API/命令。完成我想要的事情的基本要点是：

use strict;
use warnings;
use Pod::Simple::HTMLBatch;

my $batchconv = Pod::Simple::HTMLBatch->new;
$batchconv->html_render_class('My::Pod');
$batchconv->batch_convert( ['path/to/code'], 'path/to/output' );

package My::Pod;
use Pod::Weaver;
use parent qw(Pod::Simple::HTML);

sub parse_file {
    my ($self, $in_file) = @_;

    my $new_doc = 'Pod::Weaver transformed pod here'

    return $self->SUPER::parse_string_document($new_doc);
}

有没有人做过类似的事？有人能告诉我如何用Pod:Weaver来转换$in_file (它可以是.pm或.pod文件)吗？

Answer 1

事实证明，这比预期的要难得多，这可能是个坏主意。我们真正需要的是一个新的实用工具，用于将Pod::Elemental文档转换为(X)HTML(5)，与Pod：：Simple：(X)HTML兼容(以便我们可以继续使用旧的CSS样式)。如果有人写/找到合适的模块并在这里发布，我将接受另一个答案。

所以我就是这么做的。我不得不子类POD：：简单：：搜索，因为它使用正则表达式检查文件，该正则表达式不包括与Pod::Weaver一起使用的=method。对于每个文件，我必须创建一个PPI文档并去掉POD，然后将POD连接起来，并将其转化为Pod::Elemental文档。Pod::Elemental::PerlMunger就是这样做的，这就是Dist::Zilla使用的内容。

package My::Pod;
use strict;
use warnings;

use Pod::Weaver;
use Pod::Elemental;
use Software::License::Perl_5;
use PPI;
use List::MoreUtils qw(any);
use parent qw(Pod::Simple::HTML);

my $weaver = Pod::Weaver->new_with_default_config;
my $license = Software::License::Perl_5->new({
  holder => 'DFKI',
});

sub parse_file {
    my ($self, $in_file) = @_;

    my $doc = get_doc($in_file);

    my $document = $weaver->weave_document({
        pod_document => $doc->{pod},
        ppi_document => $doc->{ppi},
        authors => ['Nathan Glenn <garfieldnate@gmail.com>'],
        license => $license,
    });

    return $self->SUPER::parse_string_document($document->as_pod_string);
}

#return {ppi, pod}
#Most of this taken from Pod::Elemental::PerlMunger
sub get_doc {
    my ($file_name) = @_;

    my $ppi_document = PPI::Document->new($file_name);
    confess(PPI::Document->errstr) unless $ppi_document;

    my @pod_tokens = map {"$_"} @{ $ppi_document->find('PPI::Token::Pod') || [] };
    $ppi_document->prune('PPI::Token::Pod');

    my $finder = sub {
        my $node = $_[1];
        return 0 unless any { $node->isa($_) }
           qw( PPI::Token::Quote PPI::Token::QuoteLike PPI::Token::HereDoc );
        return 1 if $node->content =~ /^=[a-z]/m;
        return 0;
    };

    if ($ppi_document->find_first($finder)) {
       warn "can't get POD from $file_name: there is POD inside string literals";
    }

    my $pod_str = join "\n", @pod_tokens;
    my $pod_document = Pod::Elemental->read_string($pod_str);

    return {ppi => $ppi_document, pod => $pod_document};
}

# search package to tell Pod::Simple::HTMLBatch that everything has POD
package My::Pod::Search;
use parent qw(Pod::Simple::Search);

#override this method to allow whatever kinds of POD commands (=method, etc.)
#mostly copied from Pod::Simple::Search
sub contains_pod {
    my($self, $file) = @_;
    my $verbose = $self->{'verbose'};

    # check for one line of POD
    $verbose > 1 and print " Scanning $file for pod...\n";
    unless( open(MAYBEPOD,"<$file") ) {
        print "Error: $file is unreadable: $!\n";
        return undef;
    }


    local $_;
    while( <MAYBEPOD> ) {
        # a more forgiving pod regex for things like =method
        if(m/^=(.+)\b/s) {
          close(MAYBEPOD) || die "Bizarre error closing $file: $!\nAborting";
          chomp;
          $verbose > 1 and print "  Found some pod ($_) in $file\n";
          return 1;
        }
    }
    close(MAYBEPOD) || die "Bizarre error closing $file: $!\nAborting";
    $verbose > 1 and print "  No POD in $file, skipping.\n";
    return 0;
}

package main;

my $batchconv = Pod::Simple::HTMLBatch->new;
$batchconv->html_render_class('My::Pod');
$batchconv->search_class('My::Pod::Search');
$batchconv->batch_convert( ['path/to/code'], 'path/to/output' );