On Tue, Apr 17, 2001 at 09:38:46PM +0100, Matt Sergeant wrote:
> There's a few things that I really hate about POD::Parser, the most
> significant thing is that it's impossible (or at least very difficult)
> to output the results to anything other than a file.
See the section "TREE-BASED PARSING" in the Pod::Parser PODs
where it describes this and gives some code snippets for a few
different high-level examples of how to do this. It doesn't
use print at all. It only uses "print" if you override the
command(), textblock(), and verbatim() methods to invoke print.
But Pod::Parse does not call print directly for standard output
(unless you use the raw defaults for those routines - which you
usualy don't want). The TREE-BASED PARSING section in the PODs
gives a few simple examples for how to do this:
package MyPodParserTree;
@ISA = qw( Pod::Parser );
my %ptopts = ( ... ); ## options for parse_text
...
sub begin_pod {
my $self = shift;
$self->{'-paragraphs'} = []; ## initialize paragraph list
}
sub command {
my ($parser, $command, $paragraph, $line_num, $pod_para) = @_;
my $ptree = $parser->parse_text({%ptopts}, $paragraph, ...);
$pod_para->parse_tree( $ptree ); ## set parse-tree for this para
push @{ $self->{'-paragraphs'} }, $pod_para;
}
sub verbatim {
my ($parser, $paragraph, $line_num, $pod_para) = @_;
push @{ $self->{'-paragraphs'} }, $pod_para;
}
sub textblock {
my ($parser, $paragraph, $line_num, $pod_para) = @_;
my $ptree = $parser->parse_text({%ptopts}, $paragraph, ...);
$pod_para->parse_tree( $ptree ); ## set parse-tree for this para
push @{ $self->{'-paragraphs'} }, $pod_para;
}
...
package main;
...
my $parser = new MyPodParserTree(...);
$parser->parse_from_file(...);
my $paragraphs_ref = $parser->{'-paragraphs'};
If you want something more tree-like than an array to gather
your output, you can use the existing ParseTree object:
package MyPodParserTree2;
my %ptopts = ( ... ); ## options for parse_text
...
sub begin_pod {
my $self = shift;
$self->{'-ptree'} = new Pod::ParseTree; ## initialize parse-tree
}
sub parse_tree {
## convenience method to get/set the parse-tree for the entire POD
## and store it in this PodParser subclass instance
(@_ > 1) and $_[0]->{'-ptree'} = $_[1];
return $_[0]->{'-ptree'};
}
sub command {
my ($parser, $command, $paragraph, $line_num, $pod_para) = @_;
my $ptree = $parser->parse_text({%ptopts}, $paragraph, ...);
$pod_para->parse_tree( $ptree ); ## set parse-tree for this para
$parser->parse_tree()->append( $pod_para );
}
sub verbatim {
my ($parser, $paragraph, $line_num, $pod_para) = @_;
$parser->parse_tree()->append( $pod_para );
}
sub textblock {
my ($parser, $paragraph, $line_num, $pod_para) = @_;
my $ptree = $parser->parse_text({%ptopts}, $paragraph, ...);
$pod_para->parse_tree( $ptree ); ## set parse-tree for this para
$parser->parse_tree()->append( $pod_para );
}
...
package main;
...
my $parser = new MyPodParserTree2(...);
$parser->parse_from_file(...);
my $ptree = $parser->parse_tree;
...
Now you have the entire POD document as one great big
parse-tree. If desired, you can use the "-expand_seq"
to parse_text() to insert whole different kinds of objects
of your own choosing rather than parse-tree objects. Just
don't expect Pod::Parser to know what to do with them after
that. That will need to be in your code. Or, alternatively,
you can insert any object you like so long as it conforms to
the Pod::ParseTree interface.
So avoiding printing to a filehandle altogether shouldn't be so
bad in Pod::Parser if you are willing to build up the entire
parse-tree. If you still want to do it in "streaming style"
then I suppose you could do that on a paragraph by paragraph
basis.
Again, It all depends entirely on what you put into the
command(), verbatim(), and textblock() methods that you
override. If those don't call "print", than neither will
Pod::Parser (except for errors, but that can be overridden
too). You just need to define those methods to call either
parse_text (to return a parse-tree) or to call interporale
(to return a string) at your desire and decide what to do with
the result for that paragraph.
Granted - I'm sure you will probably still prefer Pod::Tree
to Pod::Parser, but do know that more support does exist
in Pod::Parser for what you are trying to do (if you can
manage to stick with reading the PODs long enough to get
to the last-section on tree-based parsing :-)
--
Brad Appleton <[EMAIL PROTECTED]> http://www.bradapp.net/
"And miles to go before I sleep." -- Robert Frost
