Extracting and formatting Pod sections

Mike.lifeguard has asked for the wisdom of the Perl Monks concerning the following question:

I am writing a shell with Term::Shell, which handles the guts I don't want to (read: can't) deal with. One such bit of guts is implementing `help $command` - this is done by defining sub help_command { return 'your help text'; }

However, since I'm writing Pod anyways, I end up with two problems:

I'm writing the same thing twice. Oh the shame!
The help text is an unformatted string. I'd really like to have it look and behave like the oh-so-lovely output of pod2usage.

My thinking is that in help_command(), I could extract the appropriate section of Pod from the file with Pod::Select, then format it with Pod::Text::Termcap. This would give me a single string that could be returned. I've got the formatting done, but extracting the Pod section is failing.

How can I extract the text of a section of Pod and save it to a scalar so I can massage it further? Alternatively, how can I get pod2usage to a) show only a section of Pod and b) actually work from inside Term::Shell?

=head1 delete

Delete a wiki page:

    delete "Main Page" "for teh lulz"

=cut

sub run_delete  {
    my $o       = shift;
    my $page    = shift;
    my $summary = shift || 'Vandalism';
    if (@_ > 0) {
        my $abort = prompt('y', 'Abort?', qq{Did you mean to delete [[
+$page]] with reason "$summary"?}, 'y');
        return 1 if $abort;
    }

    my $success = $u->delete($page, $summary);

    if ($success) {
        print "Deletion successful\n";
    }
    else {
        print "Deletion failed:\n"
            . "    $u->{'error'}->{'details'}\n";
    }
}
sub smry_delete {
    return 'delete a page';
}
sub help_delete {
    # There has to be some way of getting this Pod fragment
    # from the file directly. Also, if we put it here,
    # Pod::Weaver won't touch the file, and that's disappointing.
    my $pod = <<'END';
=head1 Delete a wiki page

This will delete a page on the wiki you're currently using:

    delete "Main Page" "for teh lulz"

Make sure you quote your input correctly.

=cut
END
    my $pod_parser = Pod::Text::Termcap->new(
        width       => 72,
        utf8        => 1,
    );
    my $rendered_pod;
    $pod_parser->output_string(\$rendered_pod);
    $pod_parser->parse_string_document($pod);

    return $rendered_pod;
}
[download]

Comment on Extracting and formatting Pod sections Select or Download Code

Replies are listed 'Best First'.
Re: Extracting and formatting Pod sections by Corion (Patriarch) on Aug 01, 2010 at 14:16 UTC
One nasty trick I use to get at my POD and still have it render is the following: `my $pod = <<'=cut'; =head1 delete ... =cut` [download] I'm not sure if Pod::Weaver refuses to convert that pod, but pod2html and CPAN know what to do and properly display that POD. Once you have your POD in a string, you can format it for further processing anyway.	[reply] [d/l]
Re^2: Extracting and formatting Pod sections by Mike.lifeguard (Novice) on Aug 01, 2010 at 14:28 UTC
Thanks, Corion. Let's try it!... `[PodWeaver] can't invoke PodWeaver on lib/MediaWiki/Bot/Shell.pm: there is POD inside string literals` Disappointing, but nowhere near critical. Does the POD get handled properly?... Yes! So, it looks like that'll meet my needs just fine.	[reply] [d/l]
Re^3: Extracting and formatting Pod sections by patrick.j (Acolyte) on Aug 02, 2010 at 11:48 UTC
I could help with “alternativeley a)” (haven't played with Term::… yet, sorry): you could use the `-sections` flag: like this (from Perldoc): `pod2usage(-verbose => 99, -sections => [ qw(fred fred/subsection) ] );` [download]	[reply] [d/l] [select]
Re: Extracting and formatting Pod sections by Khen1950fx (Canon) on Aug 03, 2010 at 04:45 UTC
I used Pod::Select. For me, it's the easiest way. #!/usr/bin/perl package MyShell; use base qw(Term::Shell); my $shell = MyShell->new; $shell->cmdloop; use strict; use warnings; use Term::Shell; use Pod::Select; use Pod::Usage; sub run_delete { my $o = shift; my $page = shift; my $summary = shift \|\| 'Vandalism'; if (@_ > 0) { my $abort = prompt('y', 'Abort?', qq{Did you mean to delete [[ +$page]] with reason "$summary"?}, 'y'); return 1 if $abort; } my $u; my $success = $u->delete($page, $summary); if ($success) { print "Deletion successful\n"; } else { print "Deletion failed:\n" . " $u->{'error'}->{'details'}\n"; } } sub run_smry_delete { print "delete a page", "\n"; } sub run_help_delete { my $file = '/path/to/this/script.pl'; podselect({ -sections => ["NAME\|DELETE", "OPTIONS" ]}, $file); } =head1 DELETE Delete a wiki page This will delete a page on the wiki you're currently using: delete "Main Page" "for teh lulz" Make sure you quote your input correctly. =cut [download]	[reply] [d/l]
Re^2: Extracting and formatting Pod sections by Mike.lifeguard (Novice) on Aug 05, 2010 at 00:17 UTC
Yes, but that simply prints raw Pod to STDOUT. I want to put it in a scalar so I can massage it further. (specifically, I want to use Pod::Text::Termcap to make it purty). This is the only bit I can't seem to solve.	[reply]


The stupid question is the question not asked
	PerlMonks