Question

我正在尝试创建Pod::Simple::HTML的简单子类，以便与Pod::Simple::HTMLBatch一起使用。我希望所有的POD都使用POD::Weaver进行预处理。但是，我无法找到使用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::Simple::Search，因为它使用正则表达式检查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' );

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

1 个答案: