Parsing Pod::Text

neo1491 has asked for the wisdom of the Perl Monks concerning the following question:

I have a library which contains several subroutines. Each one has a POD header. Example...

#!C:/Perl/bin/perl.exe -w
use strict;
use warnings;
use Pod::Text;

#------------------------------
=pod

=head2 HelpFOO

   ($status) = FOO($input);

Input

    $input = the first parameter

Output

    status (Success) - 0
           (Failure) - non zero

Description

    Description of what FOO does

    Usage: FOO(input)

=cut
#------------------------------

sub FOO {
    my $input = shift;
    if (!defined($input)){
        my $parser = Pod::Text-> new(sentance=>,width=>78);
        $parser->parse_from_file($0, "-"); 
    }
}

#------------------------------
=pod

=head2 HelpBAR

   ($status) = BAR($input);

Input

    $input = the first parameter

Output

    status (Success) - 0
           (Failure) - non zero

Description

    Description of what BAR does

    Usage: BAR(input)

=cut
#------------------------------

sub BAR {
    my $input = shift;
    if (!defined($input)){
        my $parser = Pod::Text-> new(sentance=>,width=>78);
        $parser->parse_from_file($0, "-"); 
    }
}

#execute
FOO();
[download]

I'm trying to print the POD as a "usage statement" if the correct parameters aren't passed to the subroutine, but I only want to print the POD which relates to the specific subroutine (I only want to print HelpFOO, not HelpFOO and HelpBAR). Any ideas? Thanks!

Comment on Parsing Pod::Text Download Code

Replies are listed 'Best First'.
Re: Parsing Pod::Text by leocharre (Priest) on Jul 16, 2009 at 18:22 UTC
I think what you're suggesting is overkill. The user should RTFM as needed. That said, what you need to do is parse the pod. From my own embarrassing hack ( LEOCHARRE::CLI2 is decent) : # BEIGN HELP , USAGE, MAN ETC sub main::man { if( defined $main::usage ){ my $output = $main::usage; print STDERR "$output\n"; } elsif( defined &main::usage ){ my $output = main::usage(); print STDERR "$output\n"; } else { my $name = main::_scriptname(); print `man $name`; } exit; } # END HELP sub main::_scriptname{ my $name = $0 or return; $name=~s/^.+\///; return $name; } [download] Of course, you need to take this further, you need to actually parse the pod.. Look into PPI- Maybe PPI can help isolate the pod, and you can pick at it with something like Pod::Simple::SimpleTree	[reply] [d/l]
Re: Parsing Pod::Text by neo1491 (Beadle) on Jul 16, 2009 at 18:57 UTC
Thanks!	[reply]
Re^2: Parsing Pod::Text by leocharre (Priest) on Jul 17, 2009 at 14:12 UTC
There's something to be said about what the user expects. On posix, I expect all cli stuff to roughly do the following when something goes wrong.. If an internal error occurred, I don't see the manual or usage examples, I see what the error message is, the thing really dies out. If there's a usage error, or a missing argument or I see the -h or --help flag, I expect to see the brief usage statement.. such as: `command-name [OPTIONS].. OTHERARGS.. Brief one sentence description of command usefulness. -h help -v version -o other command flag -a string this one takes an arg For more info, try 'man command-name'` [download] And that's it, period.. no manual info this far. Just a brief warning maybe, and usage. Maybe not even usage if you don't want to - unless they ask for -h(elp), but an error. See the 'locate' command for example of this, try 'locate', and you get warning, try 'locate -h' and you get brief usage, try 'man locate' and you get the whole enchillada. If the user specifially request the manual- then I show the manual, all of it- that pertains to that command.	[reply] [d/l]