RE: pod::simple::text

[John E Guillory]

Just a note to say thanks for the replies. I'm using regex suggested by Grant 
and have made more progress in a morning than I did in a day trying to figure 
out a pod parser.   -John

-----Original Message-----
From: Shawn H Corey [mailto:shawnhco...@gmail.com] 
Sent: Thursday, June 26, 2014 7:38 AM
To: pod-people@perl.org
Subject: Re: pod::simple::text

On Thu, 26 Jun 2014 15:40:14 +1200
Grant McLean <gr...@mclean.net.nz> 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