Parse POD of a method from perl module

[perlUser9]

Hi I am trying to parse the POD for a particular method from a Perl module. For ex if I have a module named MyModule.pm as below:
package MyModule;
=head1 Subroutine1
My POD for Subroutine1
=cut
sub Subroutine1
{
...
...
}

=head1 Subroutine2
My POD for Subroutine2
=cut
sub Subroutine2
{
...
...
}
1;

Now I want to get the POD of Subroutine2 in a string. Can anyone please suggest if there is a Perl module which can parse the POD for the particular method?

[Anonymous Monk]

Pod::Simple::SimpleTree or Pod::Simple::DumpAsXML + XML::Twig/XML::LibXML...

Pod::Coverage and Module::Info and Re: 'extract' subs from source code,

Vim::Tag - Generate perl tags for vim

Perl::Tags - Generate (possibly exuberant) Ctags style tags for Perl sourcecode

ppi_dumper

[LanX]

Parsing POD is pretty straight forward, cause the format is simple.

The real complication is parsing the corresponding Perl sub names.

like

- how to parse Perlcode? (dynamic sub names, dynamic vs static)

- are all sub's source supposed to follow directly to the POD?

- are subs described in head2-items following a special head1-item? (like INTERFACE)

Could you please give us more informations about what you are trying to achieve?

Unfortunately solutions in Perl are not very DRY (thats why I envy Python for stealing docstrings from Lisp)

For instance one of my last employers used a POD server which automatically parsed all installed modules to create CPAN like web-pages including TOCs listing each function/method.

Following the links you got the POD for each sub and the code was JS-folded in between.

Thats what you want? For instance this solution would imply switching from head1 to head2 in your POD.

[perlUser9]

Hi Rolf, Thanks for your reply. I need to retrieve the POD for a specific method and want to provide that to RIDE (IDE for Robot framework I am using). I need to show the POD as a description/information about the method in RIDE. I saw couple of Perl modules like Pod::Simple, Pod::Parser but they work on the whole module. And my requirement is for the method.

[LanX]

i.o.W. your input are
• name of the head1
• path of a module
and you just want the POD-content, no source code?

As mentioned ready-to-use solutions expect you to follow certain conventions!

But a simple perl-script to parse everything between =head1 NAME and =cut is straight forwardly implemented with a flip-flop range and easily adapted if your format has variations (different conventions¹)

¹) e.g are you aware that your example is "invalid" POD b/c of missing empty lines?

[RonW]

Try Pod::Select

[muba]

I can second that. I've had success with Pod::Select in the past.

[kcott]

G'day perlUser9,

Welcome to the monastery.

This seems to do what you want. Using your example code, this outputs just "My POD for Subroutine2\n". I added some extra dummy POD for test purposes.

#!/usr/bin/env perl

use strict;
use warnings;

my $wanted_sub = 'Subroutine2';
my $pod_string;

{
    local $/ = "\n=head1 ";

    while (<DATA>) {
        if (/\A $wanted_sub $/mx) {
            ($pod_string = $_) =~ s/\A .+? ^ ( .+? ) =cut .* \z/$1/msx
+;
            last;
        }
    }
}

print $pod_string;

__DATA__
package MyModule;
=head1 Subroutine1
My POD for Subroutine1
=cut
sub Subroutine1
{
...
...
}

=head1 Subroutine2
My POD for Subroutine2

=head2 Dummy Heading 2

=over 4

=item whatever

qwerty

=item blah

asdfgh

=back

Some text

=cut
sub Subroutine2
{
...
...
}
1;

Output:

My POD for Subroutine2

=head2 Dummy Heading 2

=over 4

=item whatever

qwerty

=item blah

asdfgh

=back

Some text

[Anonymous Monk]

Hi All, Thanks a lot for your help. I wrote my code to extract the POD for a particular method and used Pod::Text module to covert the pod to plain text. Thanks again for the guidance.