2

I have a POD document. Now, I want to convert that POD to a parsed section like usage/description and get it in a string.

Why not pod2usage?

This doesn't help me to get the output in string but in STDOUT/file. I am stressing on the point "getting it in string", because I want to display the POD in "pages" if the length exceeds screen length. pod2usage doesn't print them in pages :(

Can somebody tell me which module to use for this purpose?

3 Answers 3

2

Pod::Usage, which is referenced on the bottom of the pod2usage man page.

1

From the Pod::Parser documentation:

Alternatively, an IO::String object is also accepted as an output file handle.

So this is perfectly legal:

#!/usr/bin/perl
use strict;
use IO::String;
use Pod::Text;
my $buffer;
my $io = IO::String->new($buffer);
my $parser= Pod::Text->new (sentence => 0, width => 78);
$parser->parse_from_file('/usr/share/perl5/Net/Jabber.pm',$io);
print $buffer;

On the other hand, remember that you can capture the output of any command using backticks, e.g.

$text = `/usr/bin/pod2usage /usr/share/perl5/Net/Jabber.pm`;

or qx{} for clarity:

$text = qx{/usr/bin/pod2usage /usr/share/perl5/Net/Jabber.pm};
5
  • 2
    IO::String is useful for all sorts of things. Oct 5, 2009 at 5:53
  • 1
    Indeed, but if you are sure to be running in a perl5.8-or later environment, you can just use scalar references instead.
    – Ether
    Oct 5, 2009 at 6:04
  • Since Pod::Text derives from Pod::Simple, you can say: my $string; $parser->output_string(\$string); right below your Pod::Text->new line, and then you'll get all your output written out to $string. Pod::Text makes a lot more sense than backticks/qx{} IMO, since it's cross-platform.
    – Gaurav
    Oct 5, 2009 at 6:09
  • i am using 5.8.8 version only.. I have got all output to a string.. then to print only one section of POD(eg: synopsis), do i have to do manual parsing? or is there any modules which provides way to extract that also?
    – Anandan
    Oct 5, 2009 at 9:16
  • That's the exact description of Pod::Select ^_^
    – codehead
    Oct 5, 2009 at 13:24
1

You don't have to do all of the Pod parsing yourself; most of it is done already with Pod::Simple. You can write a short subclass to do whatever you need. I have a chapter in Mastering Perl that goes into the details, but you can also look at my Pod::Perldoc::TOC module to see a short example.

Basically, you handle the =head1 elements, but skip the ones that aren't SYNOPSIS. Once you run into the right =head1, set a flag and process the section until you run into another =head1, at which point you stop parsing. You can do anything you like between the =head1's, including appending to a variable.

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.