Search code examples
perlperl-podperldoc

How can I print only a specific format name in a Perl POD?


I'm trying to extract a portion of a Perl POD and nothing else. If I run the following:

use strict;
use warnings;
use Pod::Simple;
use Pod::Text;

=head1 podTest

normal pod

=cut

print "normalPod:\n";
my $writeNormalPod = Pod::Text->new();
$writeNormalPod->parse_from_file(__FILE__);

=pod

all pod

=cut

print "\nallPod:\n";
my $writePod = Pod::Text->new();
$writePod->accept_targets( ('special') );
$writePod->parse_from_file(__FILE__);

=begin special

special pod

=end special

=cut

print "\nspecialPod:\n";
my $writeSpecialPod = Pod::Text->new();
# what to have here?
$writeSpecialPod->parse_from_file(__FILE__);
# in order to print "special pod" and nothing else

Then I get the output:

normalPod:
podTest
    normal pod

    all pod


allPod:
podTest
    normal pod

    all pod

special pod

specialPod:

How can I get special pod and nothing else?

Things I've tried:

  • unaccepting codes, directives, and targets
  • attaching code (and cut, pod, and whiteline) handlers
  • Web searching (at best, this turns up how to use a format name)

Is there an easy way to get only a specific format out of a POD, or should I just parse the file on my own?


Solution

  • Things I've tried: unaccepting directives

    Yes seems Pod::Simple does not have support for unaccepting standard directives. If you try:

    $writePod->unaccept_directives( 'head1' );
    

    it dies with the error message:

    But you must accept "head1" directives -- it's a builtin!
    

    You might be able to work around the restriction by sub classing Pod::Text to override its output methods. For example:

    p.pl:

    BEGIN {
    package My::Pod::Text;
    use strict;
    use warnings;
    use parent qw(Pod::Text);
    sub cmd_head1 {} #override this to not print head1
    sub cmd_para {}  #override this to not print paragraphs
    
    $INC{"My/Pod/Text.pm"} = 1;
    }
    package main;
    use feature qw(say);
    use strict;
    use warnings;
    use My::Pod::Text;
    
    =head1 podTest
    
    normal pod
    
    =begin special
    
    special pod
    
    =end special
    
    =cut
    
    my $writePod = My::Pod::Text->new();
    $writePod->accept_targets( ('special') );
    $writePod->parse_from_file(__FILE__);
    

    outputs only:

    special pod