On Thu, 26 Jun 2014 15:40:14 +1200
Grant McLean <[email protected]> wrote:
> On Wed, 2014-06-25 at 18:05 +0000, John E Guillory wrote:
> > Hello,
> >
> > I thought I wasn’t this new to perl but …
> >
> > How does one use pod::simple::text to print out a section of POD,
> > say the DESCRIPTION section?
>
> Pod::Simple provides some core POD parsing functionality which is
> shared by a number of formatter classes. There isn't any sort of
> query API that would allow you to specify which sections of the POD
> you want.
>
> If you do want to produce formatted plain-text output of just the
> DESCRIPTION section, then probably the easiest way is to slurp in all
> the POD source; use a regex to extract the section you want; and then
> pass that to a formatter:
>
> my($pod_source) =
> read_file($source_file) =~
> m{^(=head1\s+DESCRIPTION.*?)(?:^=head1.*)?\z}ms;
>
> my $parser = Pod::Simple::Text->new();
> $parser->parse_string_document($pod_source);
>
> The parser(/formatter) will write its output to STDOUT unless you call
> $parser->output_fh with an alternative filehandle.
>
> An alternative approach would be to subclass Pod::Simple::Text and
> maintain a flag indicating when the parser is 'in' the DESCRIPTION
> section and suppress all output when the flag is not set.
> Unfortunately the "suppress all output" bit is tricky since all the
> methods that produce formatted output write directly to the output
> filehandle.
>
> Regards
> Grant
>
>
Pod::Usage can extract sections for a POD. It come with perl.
#!/usr/bin/perl
use Pod::Usage;
# Documentation levels
my $DOC_USAGE => 0;
my $DOC_HELP => 1;
my $DOC_VER => 2;
my $DOC_MAN => 3;
# --------------------------------------
# Subroutines
# --------------------------------------
# Name: print_documentation
# Usage: print_documentation( $documentation_level );
# Purpose: Print the usage, help, or man documentation.
# Returns: Does not return.
# Parameters: $documentation_level -- how much documentation to display.
# 0 == usage
# 1 == help
# 2 == version
# other == man
#
sub print_documentation {
my $level = shift @_ || $DOC_USAGE;
my @doc_options = (
# DOC_USAGE
{
-exitval => 2,
-verbose => 99,
-sections => 'USAGE',
},
# DOC_HELP
{
-exitval => 2,
-verbose => 99,
-sections => 'NAME|VERSION|USAGE|REQUIRED ARGUMENTS|OPTIONS',
},
# DOC_VER
{
-exitval => 2,
-verbose => 99,
-sections => 'NAME|VERSION',
},
# DOC_MAN
{
-exitval => 2,
-verbose => 2,
},
);
# validate level
$level =~ tr [0-9] []cds;
$level ||= $DOC_USAGE;
$level = $DOC_USAGE if $level >= @doc_options;
# print the documentation
pod2usage( $doc_options[$level] );
}
--
Don't stop where the ink does.
Shawn
