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:

  1. I'm writing the same thing twice. Oh the shame!
  2. 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]

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]

      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]
        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]
      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]

Back to Seekers of Perl Wisdom