1 #############################################################################
2 # Pod/Parser.pm -- package which defines a base class for parsing POD docs.
4 # Copyright (C) 1996-1999 by Bradford Appleton. All rights reserved.
5 # This file is part of "PodParser". PodParser is free software;
6 # you can redistribute it and/or modify it under the same terms
8 #############################################################################
12 use vars qw($VERSION);
13 $VERSION = 1.085; ## Current version of this package
14 require 5.004; ## requires this Perl version or later
16 #############################################################################
20 Pod::Parser - base class for creating POD filters and translators
27 @ISA = qw(Pod::Parser);
30 my ($parser, $command, $paragraph, $line_num) = @_;
31 ## Interpret the command and its text; sample actions might be:
32 if ($command eq 'head1') { ... }
33 elsif ($command eq 'head2') { ... }
34 ## ... other commands and their actions
35 my $out_fh = $parser->output_handle();
36 my $expansion = $parser->interpolate($paragraph, $line_num);
37 print $out_fh $expansion;
41 my ($parser, $paragraph, $line_num) = @_;
42 ## Format verbatim paragraph; sample actions might be:
43 my $out_fh = $parser->output_handle();
44 print $out_fh $paragraph;
48 my ($parser, $paragraph, $line_num) = @_;
49 ## Translate/Format this block of text; sample actions might be:
50 my $out_fh = $parser->output_handle();
51 my $expansion = $parser->interpolate($paragraph, $line_num);
52 print $out_fh $expansion;
55 sub interior_sequence {
56 my ($parser, $seq_command, $seq_argument) = @_;
57 ## Expand an interior sequence; sample actions might be:
58 return "*$seq_argument*" if ($seq_command = 'B');
59 return "`$seq_argument'" if ($seq_command = 'C');
60 return "_${seq_argument}_'" if ($seq_command = 'I');
61 ## ... other sequence commands and their resulting text
66 ## Create a parser object and have it parse file whose name was
67 ## given on the command-line (use STDIN if no files were given).
68 $parser = new MyParser();
69 $parser->parse_from_filehandle(\*STDIN) if (@ARGV == 0);
70 for (@ARGV) { $parser->parse_from_file($_); }
74 perl5.004, Pod::InputObjects, Exporter, Carp
82 B<Pod::Parser> is a base class for creating POD filters and translators.
83 It handles most of the effort involved with parsing the POD sections
84 from an input stream, leaving subclasses free to be concerned only with
85 performing the actual translation of text.
87 B<Pod::Parser> parses PODs, and makes method calls to handle the various
88 components of the POD. Subclasses of B<Pod::Parser> override these methods
89 to translate the POD into whatever output format they desire.
93 To create a POD filter for translating POD documentation into some other
94 format, you create a subclass of B<Pod::Parser> which typically overrides
95 just the base class implementation for the following methods:
113 B<interior_sequence()>
117 You may also want to override the B<begin_input()> and B<end_input()>
118 methods for your subclass (to perform any needed per-file and/or
119 per-document initialization or cleanup).
121 If you need to perform any preprocesssing of input before it is parsed
122 you may want to override one or more of B<preprocess_line()> and/or
123 B<preprocess_paragraph()>.
125 Sometimes it may be necessary to make more than one pass over the input
126 files. If this is the case you have several options. You can make the
127 first pass using B<Pod::Parser> and override your methods to store the
128 intermediate results in memory somewhere for the B<end_pod()> method to
129 process. You could use B<Pod::Parser> for several passes with an
130 appropriate state variable to control the operation for each pass. If
131 your input source can't be reset to start at the beginning, you can
132 store it in some other structure as a string or an array and have that
133 structure implement a B<getline()> method (which is all that
134 B<parse_from_filehandle()> uses to read input).
136 Feel free to add any member data fields you need to keep track of things
137 like current font, indentation, horizontal or vertical position, or
138 whatever else you like. Be sure to read L<"PRIVATE METHODS AND DATA">
139 to avoid name collisions.
141 For the most part, the B<Pod::Parser> base class should be able to
142 do most of the input parsing for you and leave you free to worry about
143 how to intepret the commands and translate the result.
145 Note that all we have described here in this quick overview overview is
146 the simplest most striaghtforward use of B<Pod::Parser> to do stream-based
147 parsing. It is also possible to use the B<Pod::Parser::parse_text> function
148 to do more sophisticated tree-based parsing. See L<"TREE-BASED PARSING">.
150 =head1 PARSING OPTIONS
152 A I<parse-option> is simply a named option of B<Pod::Parser> with a
153 value that corresponds to a certain specified behavior. These various
154 behaviors of B<Pod::Parser> may be enabled/disabled by setting or
155 or unsetting one or more I<parse-options> using the B<parseopts()> method.
156 The set of currently accepted parse-options is as follows:
160 =item B<-want_nonPODs> (default: unset)
162 Normally (by default) B<Pod::Parser> will only provide access to
163 the POD sections of the input. Input paragraphs that are not part
164 of the POD-format documentation are not made available to the caller
165 (not even using B<preprocess_paragraph()>). Setting this option to a
166 non-empty, non-zero value will allow B<preprocess_paragraph()> to see
167 non-POD sectioins of the input as well as POD sections. The B<cutting()>
168 method can be used to determine if the corresponding paragraph is a POD
169 paragraph, or some other input paragraph.
171 =item B<-process_cut_cmd> (default: unset)
173 Normally (by default) B<Pod::Parser> handles the C<=cut> POD directive
174 by itself and does not pass it on to the caller for processing. Setting
175 this option to non-empty, non-zero value will cause B<Pod::Parser> to
176 pass the C<=cut> directive to the caller just like any other POD command
177 (and hence it may be processed by the B<command()> method).
179 B<Pod::Parser> will still interpret the C<=cut> directive to mean that
180 "cutting mode" has been (re)entered, but the caller will get a chance
181 to capture the actual C<=cut> paragraph itself for whatever purpose
186 Please see L<"parseopts()"> for a complete description of the interface
187 for the setting and unsetting of parse-options.
191 #############################################################################
196 use Pod::InputObjects;
201 ## These "variables" are used as local "glob aliases" for performance
202 use vars qw(%myData %myOpts @input_stack);
204 #############################################################################
206 =head1 RECOMMENDED SUBROUTINE/METHOD OVERRIDES
208 B<Pod::Parser> provides several methods which most subclasses will probably
209 want to override. These methods are as follows:
213 ##---------------------------------------------------------------------------
217 $parser->command($cmd,$text,$line_num,$pod_para);
219 This method should be overridden by subclasses to take the appropriate
220 action when a POD command paragraph (denoted by a line beginning with
221 "=") is encountered. When such a POD directive is seen in the input,
222 this method is called and is passed:
228 the name of the command for this POD paragraph
232 the paragraph text for the given POD paragraph command.
236 the line-number of the beginning of the paragraph
240 a reference to a C<Pod::Paragraph> object which contains further
241 information about the paragraph command (see L<Pod::InputObjects>
246 B<Note> that this method I<is> called for C<=pod> paragraphs.
248 The base class implementation of this method simply treats the raw POD
249 command as normal block of paragraph text (invoking the B<textblock()>
250 method with the command paragraph).
255 my ($self, $cmd, $text, $line_num, $pod_para) = @_;
256 ## Just treat this like a textblock
257 $self->textblock($pod_para->raw_text(), $line_num, $pod_para);
260 ##---------------------------------------------------------------------------
264 $parser->verbatim($text,$line_num,$pod_para);
266 This method may be overridden by subclasses to take the appropriate
267 action when a block of verbatim text is encountered. It is passed the
268 following parameters:
274 the block of text for the verbatim paragraph
278 the line-number of the beginning of the paragraph
282 a reference to a C<Pod::Paragraph> object which contains further
283 information about the paragraph (see L<Pod::InputObjects>
288 The base class implementation of this method simply prints the textblock
289 (unmodified) to the output filehandle.
294 my ($self, $text, $line_num, $pod_para) = @_;
295 my $out_fh = $self->{_OUTPUT};
299 ##---------------------------------------------------------------------------
301 =head1 B<textblock()>
303 $parser->textblock($text,$line_num,$pod_para);
305 This method may be overridden by subclasses to take the appropriate
306 action when a normal block of POD text is encountered (although the base
307 class method will usually do what you want). It is passed the following
314 the block of text for the a POD paragraph
318 the line-number of the beginning of the paragraph
322 a reference to a C<Pod::Paragraph> object which contains further
323 information about the paragraph (see L<Pod::InputObjects>
328 In order to process interior sequences, subclasses implementations of
329 this method will probably want to invoke either B<interpolate()> or
330 B<parse_text()>, passing it the text block C<$text>, and the corresponding
331 line number in C<$line_num>, and then perform any desired processing upon
334 The base class implementation of this method simply prints the text block
335 as it occurred in the input stream).
340 my ($self, $text, $line_num, $pod_para) = @_;
341 my $out_fh = $self->{_OUTPUT};
342 print $out_fh $self->interpolate($text, $line_num);
345 ##---------------------------------------------------------------------------
347 =head1 B<interior_sequence()>
349 $parser->interior_sequence($seq_cmd,$seq_arg,$pod_seq);
351 This method should be overridden by subclasses to take the appropriate
352 action when an interior sequence is encountered. An interior sequence is
353 an embedded command within a block of text which appears as a command
354 name (usually a single uppercase character) followed immediately by a
355 string of text which is enclosed in angle brackets. This method is
356 passed the sequence command C<$seq_cmd> and the corresponding text
357 C<$seq_arg>. It is invoked by the B<interpolate()> method for each interior
358 sequence that occurs in the string that it is passed. It should return
359 the desired text string to be used in place of the interior sequence.
360 The C<$pod_seq> argument is a reference to a C<Pod::InteriorSequence>
361 object which contains further information about the interior sequence.
362 Please see L<Pod::InputObjects> for details if you need to access this
363 additional information.
365 Subclass implementations of this method may wish to invoke the
366 B<nested()> method of C<$pod_seq> to see if it is nested inside
367 some other interior-sequence (and if so, which kind).
369 The base class implementation of the B<interior_sequence()> method
370 simply returns the raw text of the interior sequence (as it occurred
371 in the input) to the caller.
375 sub interior_sequence {
376 my ($self, $seq_cmd, $seq_arg, $pod_seq) = @_;
377 ## Just return the raw text of the interior sequence
378 return $pod_seq->raw_text();
381 #############################################################################
383 =head1 OPTIONAL SUBROUTINE/METHOD OVERRIDES
385 B<Pod::Parser> provides several methods which subclasses may want to override
386 to perform any special pre/post-processing. These methods do I<not> have to
387 be overridden, but it may be useful for subclasses to take advantage of them.
391 ##---------------------------------------------------------------------------
395 my $parser = Pod::Parser->new();
397 This is the constructor for B<Pod::Parser> and its subclasses. You
398 I<do not> need to override this method! It is capable of constructing
399 subclass objects as well as base class objects, provided you use
400 any of the following constructor invocation styles:
402 my $parser1 = MyParser->new();
403 my $parser2 = new MyParser();
404 my $parser3 = $parser2->new();
406 where C<MyParser> is some subclass of B<Pod::Parser>.
408 Using the syntax C<MyParser::new()> to invoke the constructor is I<not>
409 recommended, but if you insist on being able to do this, then the
410 subclass I<will> need to override the B<new()> constructor method. If
411 you do override the constructor, you I<must> be sure to invoke the
412 B<initialize()> method of the newly blessed object.
414 Using any of the above invocations, the first argument to the
415 constructor is always the corresponding package name (or object
416 reference). No other arguments are required, but if desired, an
417 associative array (or hash-table) my be passed to the B<new()>
420 my $parser1 = MyParser->new( MYDATA => $value1, MOREDATA => $value2 );
421 my $parser2 = new MyParser( -myflag => 1 );
423 All arguments passed to the B<new()> constructor will be treated as
424 key/value pairs in a hash-table. The newly constructed object will be
425 initialized by copying the contents of the given hash-table (which may
426 have been empty). The B<new()> constructor for this class and all of its
427 subclasses returns a blessed reference to the initialized object (hash-table).
432 ## Determine if we were called via an object-ref or a classname
434 my $class = ref($this) || $this;
435 ## Any remaining arguments are treated as initial values for the
436 ## hash that is used to represent this object.
438 my $self = { %params };
439 ## Bless ourselves into the desired class and perform any initialization
445 ##---------------------------------------------------------------------------
447 =head1 B<initialize()>
449 $parser->initialize();
451 This method performs any necessary object initialization. It takes no
452 arguments (other than the object instance of course, which is typically
453 copied to a local variable named C<$self>). If subclasses override this
454 method then they I<must> be sure to invoke C<$self-E<gt>SUPER::initialize()>.
463 ##---------------------------------------------------------------------------
465 =head1 B<begin_pod()>
467 $parser->begin_pod();
469 This method is invoked at the beginning of processing for each POD
470 document that is encountered in the input. Subclasses should override
471 this method to perform any per-document initialization.
480 ##---------------------------------------------------------------------------
482 =head1 B<begin_input()>
484 $parser->begin_input();
486 This method is invoked by B<parse_from_filehandle()> immediately I<before>
487 processing input from a filehandle. The base class implementation does
488 nothing, however, subclasses may override it to perform any per-file
491 Note that if multiple files are parsed for a single POD document
492 (perhaps the result of some future C<=include> directive) this method
493 is invoked for every file that is parsed. If you wish to perform certain
494 initializations once per document, then you should use B<begin_pod()>.
503 ##---------------------------------------------------------------------------
505 =head1 B<end_input()>
507 $parser->end_input();
509 This method is invoked by B<parse_from_filehandle()> immediately I<after>
510 processing input from a filehandle. The base class implementation does
511 nothing, however, subclasses may override it to perform any per-file
514 Please note that if multiple files are parsed for a single POD document
515 (perhaps the result of some kind of C<=include> directive) this method
516 is invoked for every file that is parsed. If you wish to perform certain
517 cleanup actions once per document, then you should use B<end_pod()>.
526 ##---------------------------------------------------------------------------
532 This method is invoked at the end of processing for each POD document
533 that is encountered in the input. Subclasses should override this method
534 to perform any per-document finalization.
543 ##---------------------------------------------------------------------------
545 =head1 B<preprocess_line()>
547 $textline = $parser->preprocess_line($text, $line_num);
549 This method should be overridden by subclasses that wish to perform
550 any kind of preprocessing for each I<line> of input (I<before> it has
551 been determined whether or not it is part of a POD paragraph). The
552 parameter C<$text> is the input line; and the parameter C<$line_num> is
553 the line number of the corresponding text line.
555 The value returned should correspond to the new text to use in its
556 place. If the empty string or an undefined value is returned then no
557 further processing will be performed for this line.
559 Please note that the B<preprocess_line()> method is invoked I<before>
560 the B<preprocess_paragraph()> method. After all (possibly preprocessed)
561 lines in a paragraph have been assembled together and it has been
562 determined that the paragraph is part of the POD documentation from one
563 of the selected sections, then B<preprocess_paragraph()> is invoked.
565 The base class implementation of this method returns the given text.
569 sub preprocess_line {
570 my ($self, $text, $line_num) = @_;
574 ##---------------------------------------------------------------------------
576 =head1 B<preprocess_paragraph()>
578 $textblock = $parser->preprocess_paragraph($text, $line_num);
580 This method should be overridden by subclasses that wish to perform any
581 kind of preprocessing for each block (paragraph) of POD documentation
582 that appears in the input stream. The parameter C<$text> is the POD
583 paragraph from the input file; and the parameter C<$line_num> is the
584 line number for the beginning of the corresponding paragraph.
586 The value returned should correspond to the new text to use in its
587 place If the empty string is returned or an undefined value is
588 returned, then the given C<$text> is ignored (not processed).
590 This method is invoked after gathering up all thelines in a paragraph
591 but before trying to further parse or interpret them. After
592 B<preprocess_paragraph()> returns, the current cutting state (which
593 is returned by C<$self-E<gt>cutting()>) is examined. If it evaluates
594 to false then input text (including the given C<$text>) is cut (not
595 processed) until the next POD directive is encountered.
597 Please note that the B<preprocess_line()> method is invoked I<before>
598 the B<preprocess_paragraph()> method. After all (possibly preprocessed)
599 lines in a paragraph have been assembled together and it has been
600 determined that the paragraph is part of the POD documentation from one
601 of the selected sections, then B<preprocess_paragraph()> is invoked.
603 The base class implementation of this method returns the given text.
607 sub preprocess_paragraph {
608 my ($self, $text, $line_num) = @_;
612 #############################################################################
614 =head1 METHODS FOR PARSING AND PROCESSING
616 B<Pod::Parser> provides several methods to process input text. These
617 methods typically won't need to be overridden (and in some cases they
618 can't be overridden), but subclasses may want to invoke them to exploit
623 ##---------------------------------------------------------------------------
625 =head1 B<parse_text()>
627 $ptree1 = $parser->parse_text($text, $line_num);
628 $ptree2 = $parser->parse_text({%opts}, $text, $line_num);
629 $ptree3 = $parser->parse_text(\%opts, $text, $line_num);
631 This method is useful if you need to perform your own interpolation
632 of interior sequences and can't rely upon B<interpolate> to expand
633 them in simple bottom-up order order.
635 The parameter C<$text> is a string or block of text to be parsed
636 for interior sequences; and the parameter C<$line_num> is the
637 line number curresponding to the beginning of C<$text>.
639 B<parse_text()> will parse the given text into a parse-tree of "nodes."
640 and interior-sequences. Each "node" in the parse tree is either a
641 text-string, or a B<Pod::InteriorSequence>. The result returned is a
642 parse-tree of type B<Pod::ParseTree>. Please see L<Pod::InputObjects>
643 for more information about B<Pod::InteriorSequence> and B<Pod::ParseTree>.
645 If desired, an optional hash-ref may be specified as the first argument
646 to customize certain aspects of the parse-tree that is created and
647 returned. The set of recognized option keywords are:
651 =item B<-expand_seq> =E<gt> I<code-ref>|I<method-name>
653 Normally, the parse-tree returned by B<parse_text()> will contain an
654 unexpanded C<Pod::InteriorSequence> object for each interior-sequence
655 encountered. Specifying B<-expand_seq> tells B<parse_text()> to "expand"
656 every interior-sequence it sees by invoking the referenced function
657 (or named method of the parser object) and using the return value as the
660 If a subroutine reference was given, it is invoked as:
662 &$code_ref( $parser, $sequence )
664 and if a method-name was given, it is invoked as:
666 $parser->method_name( $sequence )
668 where C<$parser> is a reference to the parser object, and C<$sequence>
669 is a reference to the interior-sequence object.
670 [I<NOTE>: If the B<interior_sequence()> method is specified, then it is
671 invoked according to the interface specified in L<"interior_sequence()">].
673 =item B<-expand_text> =E<gt> I<code-ref>|I<method-name>
675 Normally, the parse-tree returned by B<parse_text()> will contain a
676 text-string for each contiguous sequence of characters outside of an
677 interior-sequence. Specifying B<-expand_text> tells B<parse_text()> to
678 "preprocess" every such text-string it sees by invoking the referenced
679 function (or named method of the parser object) and using the return value
680 as the preprocessed (or "expanded") result. [Note that if the result is
681 an interior-sequence, then it will I<not> be expanded as specified by the
682 B<-expand_seq> option; Any such recursive expansion needs to be handled by
683 the specified callback routine.]
685 If a subroutine reference was given, it is invoked as:
687 &$code_ref( $parser, $text, $ptree_node )
689 and if a method-name was given, it is invoked as:
691 $parser->method_name( $text, $ptree_node )
693 where C<$parser> is a reference to the parser object, C<$text> is the
694 text-string encountered, and C<$ptree_node> is a reference to the current
695 node in the parse-tree (usually an interior-sequence object or else the
696 top-level node of the parse-tree).
698 =item B<-expand_ptree> =E<gt> I<code-ref>|I<method-name>
700 Rather than returning a C<Pod::ParseTree>, pass the parse-tree as an
701 argument to the referenced subroutine (or named method of the parser
702 object) and return the result instead of the parse-tree object.
704 If a subroutine reference was given, it is invoked as:
706 &$code_ref( $parser, $ptree )
708 and if a method-name was given, it is invoked as:
710 $parser->method_name( $ptree )
712 where C<$parser> is a reference to the parser object, and C<$ptree>
713 is a reference to the parse-tree object.
719 ## This global regex is used to see if the text before a '>' inside
720 ## an interior sequence looks like '-' or '=', but not '--', '==',
721 ## '!=', '$-', '$=' or <<op>>=
722 use vars qw( $ARROW_RE );
723 $ARROW_RE = join('', qw{ (?: [^-+*/=!&|%^x.<>$]= | [^-$]- )$ });
724 #$ARROW_RE = qr/(?:[^-+*/=!&|%^x.<>$]+=|[^-$]+-)$/; ## 5.005+ only!
730 ## Get options and set any defaults
731 my %opts = (ref $_[0]) ? %{ shift() } : ();
732 my $expand_seq = $opts{'-expand_seq'} || undef;
733 my $expand_text = $opts{'-expand_text'} || undef;
734 my $expand_ptree = $opts{'-expand_ptree'} || undef;
738 my $file = $self->input_file();
739 my ($cmd, $prev) = ('', '');
741 ## Convert method calls into closures, for our convenience
742 my $xseq_sub = $expand_seq;
743 my $xtext_sub = $expand_text;
744 my $xptree_sub = $expand_ptree;
745 if (defined $expand_seq and $expand_seq eq 'interior_sequence') {
746 ## If 'interior_sequence' is the method to use, we have to pass
747 ## more than just the sequence object, we also need to pass the
748 ## sequence name and text.
750 my ($self, $iseq) = @_;
751 my $args = join("", $iseq->parse_tree->children);
752 return $self->interior_sequence($iseq->name, $args, $iseq);
755 ref $xseq_sub or $xseq_sub = sub { shift()->$expand_seq(@_) };
756 ref $xtext_sub or $xtext_sub = sub { shift()->$expand_text(@_) };
757 ref $xptree_sub or $xptree_sub = sub { shift()->$expand_ptree(@_) };
759 ## Keep track of the "current" interior sequence, and maintain a stack
760 ## of "in progress" sequences.
762 ## NOTE that we push our own "accumulator" at the very beginning of the
763 ## stack. It's really a parse-tree, not a sequence; but it implements
764 ## the methods we need so we can use it to gather-up all the sequences
765 ## and strings we parse. Thus, by the end of our parsing, it should be
766 ## the only thing left on our stack and all we have to do is return it!
768 my $seq = Pod::ParseTree->new();
769 my @seq_stack = ($seq);
771 ## Iterate over all sequence starts/stops, newlines, & text
772 ## (NOTE: split with capturing parens keeps the delimiters)
774 for ( split /([A-Z]<|>|\n)/ ) {
775 ## Keep track of line count
776 ++$line if ($_ eq "\n");
777 ## Look for the beginning of a sequence
778 if ( /^([A-Z])(<)$/ ) {
779 ## Push a new sequence onto the stack of those "in-progress"
780 $seq = Pod::InteriorSequence->new(
781 -name => ($cmd = $1),
782 -ldelim => $2, -rdelim => '',
783 -file => $file, -line => $line
785 (@seq_stack > 1) and $seq->nested($seq_stack[-1]);
786 push @seq_stack, $seq;
788 ## Look for sequence ending (preclude '->' and '=>' inside C<...>)
789 elsif ( (@seq_stack > 1) and
790 /^>$/ and ($cmd ne 'C' or $prev !~ /$ARROW_RE/o) )
792 ## End of current sequence, record terminating delimiter
794 ## Pop it off the stack of "in progress" sequences
796 ## Append result to its parent in current parse tree
797 $seq_stack[-1]->append($expand_seq ? &$xseq_sub($self,$seq) : $seq);
798 ## Remember the current cmd-name
799 $cmd = (@seq_stack > 1) ? $seq_stack[-1]->name : '';
802 ## In the middle of a sequence, append this text to it, and
803 ## dont forget to "expand" it if that's what the caller wanted
804 $seq->append($expand_text ? &$xtext_sub($self,$_,$seq) : $_);
806 ## Remember the "current" sequence and the previously seen token
807 ($seq, $prev) = ( $seq_stack[-1], $_ );
810 ## Handle unterminated sequences
811 my $errorsub = (@seq_stack > 1) ? $self->errorsub() : undef;
812 while (@seq_stack > 1) {
813 ($cmd, $file, $line) = ($seq->name, $seq->file_line);
815 my $errmsg = "** Unterminated $cmd<...> at $file line $line\n";
816 (ref $errorsub) and &{$errorsub}($errmsg)
817 or (defined $errorsub) and $self->$errorsub($errmsg)
819 $seq_stack[-1]->append($expand_seq ? &$xseq_sub($self,$seq) : $seq);
820 $seq = $seq_stack[-1];
823 ## Return the resulting parse-tree
824 my $ptree = (pop @seq_stack)->parse_tree;
825 return $expand_ptree ? &$xptree_sub($self, $ptree) : $ptree;
828 ##---------------------------------------------------------------------------
830 =head1 B<interpolate()>
832 $textblock = $parser->interpolate($text, $line_num);
834 This method translates all text (including any embedded interior sequences)
835 in the given text string C<$text> and returns the interpolated result. The
836 parameter C<$line_num> is the line number corresponding to the beginning
839 B<interpolate()> merely invokes a private method to recursively expand
840 nested interior sequences in bottom-up order (innermost sequences are
841 expanded first). If there is a need to expand nested sequences in
842 some alternate order, use B<parse_text> instead.
847 my($self, $text, $line_num) = @_;
848 my %parse_opts = ( -expand_seq => 'interior_sequence' );
849 my $ptree = $self->parse_text( \%parse_opts, $text, $line_num );
850 return join "", $ptree->children();
853 ##---------------------------------------------------------------------------
857 =head1 B<parse_paragraph()>
859 $parser->parse_paragraph($text, $line_num);
861 This method takes the text of a POD paragraph to be processed, along
862 with its corresponding line number, and invokes the appropriate method
863 (one of B<command()>, B<verbatim()>, or B<textblock()>).
865 For performance reasons, this method is invoked directly without any
866 dynamic lookup; Hence subclasses may I<not> override it!
872 sub parse_paragraph {
873 my ($self, $text, $line_num) = @_;
874 local *myData = $self; ## alias to avoid deref-ing overhead
875 local *myOpts = ($myData{_PARSEOPTS} ||= {}); ## get parse-options
878 ## See if we want to preprocess nonPOD paragraphs as well as POD ones.
879 my $wantNonPods = $myOpts{'-want_nonPODs'} || 0;
881 ## Perform any desired preprocessing if we wanted it this early
882 $wantNonPods and $text = $self->preprocess_paragraph($text, $line_num);
884 ## This is the end of a non-empty paragraph
885 ## Ignore up until next POD directive if we are cutting
886 if ($myData{_CUTTING}) {
887 return unless ($text =~ /^={1,2}\S/);
888 $myData{_CUTTING} = 0;
891 ## Now we know this is block of text in a POD section!
893 ##-----------------------------------------------------------------
894 ## This is a hook (hack ;-) for Pod::Select to do its thing without
895 ## having to override methods, but also without Pod::Parser assuming
896 ## $self is an instance of Pod::Select (if the _SELECTED_SECTIONS
897 ## field exists then we assume there is an is_selected() method for
898 ## us to invoke (calling $self->can('is_selected') could verify this
899 ## but that is more overhead than I want to incur)
900 ##-----------------------------------------------------------------
902 ## Ignore this block if it isnt in one of the selected sections
903 if (exists $myData{_SELECTED_SECTIONS}) {
904 $self->is_selected($text) or return ($myData{_CUTTING} = 1);
907 ## If we havent already, perform any desired preprocessing and
908 ## then re-check the "cutting" state
909 unless ($wantNonPods) {
910 $text = $self->preprocess_paragraph($text, $line_num);
911 return 1 unless ((defined $text) and (length $text));
912 return 1 if ($myData{_CUTTING});
915 ## Look for one of the three types of paragraphs
916 my ($pfx, $cmd, $arg, $sep) = ('', '', '', '');
917 my $pod_para = undef;
918 if ($text =~ /^(={1,2})(?=\S)/) {
919 ## Looks like a command paragraph. Capture the command prefix used
920 ## ("=" or "=="), as well as the command-name, its paragraph text,
921 ## and whatever sequence of characters was used to separate them
923 $_ = substr($text, length $pfx);
924 $sep = /(\s+)(?=\S)/ ? $1 : '';
925 ($cmd, $text) = split(" ", $_, 2);
926 ## If this is a "cut" directive then we dont need to do anything
927 ## except return to "cutting" mode.
929 $myData{_CUTTING} = 1;
930 return unless $myOpts{'-process_cut_cmd'};
933 ## Save the attributes indicating how the command was specified.
934 $pod_para = new Pod::Paragraph(
939 -file => $myData{_INFILE},
942 # ## Invoke appropriate callbacks
943 # if (exists $myData{_CALLBACKS}) {
944 # ## Look through the callback list, invoke callbacks,
945 # ## then see if we need to do the default actions
946 # ## (invoke_callbacks will return true if we do).
947 # return 1 unless $self->invoke_callbacks($cmd, $text, $line_num, $pod_para);
950 ## A command paragraph
951 $self->command($cmd, $text, $line_num, $pod_para);
953 elsif ($text =~ /^\s+/) {
954 ## Indented text - must be a verbatim paragraph
955 $self->verbatim($text, $line_num, $pod_para);
958 ## Looks like an ordinary block of text
959 $self->textblock($text, $line_num, $pod_para);
964 ##---------------------------------------------------------------------------
966 =head1 B<parse_from_filehandle()>
968 $parser->parse_from_filehandle($in_fh,$out_fh);
970 This method takes an input filehandle (which is assumed to already be
971 opened for reading) and reads the entire input stream looking for blocks
972 (paragraphs) of POD documentation to be processed. If no first argument
973 is given the default input filehandle C<STDIN> is used.
975 The C<$in_fh> parameter may be any object that provides a B<getline()>
976 method to retrieve a single line of input text (hence, an appropriate
977 wrapper object could be used to parse PODs from a single string or an
980 Using C<$in_fh-E<gt>getline()>, input is read line-by-line and assembled
981 into paragraphs or "blocks" (which are separated by lines containing
982 nothing but whitespace). For each block of POD documentation
983 encountered it will invoke a method to parse the given paragraph.
985 If a second argument is given then it should correspond to a filehandle where
986 output should be sent (otherwise the default output filehandle is
987 C<STDOUT> if no output filehandle is currently in use).
989 B<NOTE:> For performance reasons, this method caches the input stream at
990 the top of the stack in a local variable. Any attempts by clients to
991 change the stack contents during processing when in the midst executing
992 of this method I<will not affect> the input stream used by the current
993 invocation of this method.
995 This method does I<not> usually need to be overridden by subclasses.
999 sub parse_from_filehandle {
1001 my %opts = (ref $_[0] eq 'HASH') ? %{ shift() } : ();
1002 my ($in_fh, $out_fh) = @_;
1003 $in_fh = \*STDIN unless ($in_fh);
1006 ## Put this stream at the top of the stack and do beginning-of-input
1007 ## processing. NOTE that $in_fh might be reset during this process.
1008 my $topstream = $self->_push_input_stream($in_fh, $out_fh);
1009 (exists $opts{-cutting}) and $self->cutting( $opts{-cutting} );
1011 ## Initialize line/paragraph
1012 my ($textline, $paragraph) = ('', '');
1013 my ($nlines, $plines) = (0, 0);
1015 ## Use <$fh> instead of $fh->getline where possible (for speed)
1017 my $tied_fh = (/^(?:GLOB|FileHandle|IO::\w+)$/ or tied $in_fh);
1019 ## Read paragraphs line-by-line
1020 while (defined ($textline = $tied_fh ? <$in_fh> : $in_fh->getline)) {
1021 $textline = $self->preprocess_line($textline, ++$nlines);
1022 next unless ((defined $textline) && (length $textline));
1023 $_ = $paragraph; ## save previous contents
1025 if ((! length $paragraph) && ($textline =~ /^==/)) {
1026 ## '==' denotes a one-line command paragraph
1027 $paragraph = $textline;
1031 ## Append this line to the current paragraph
1032 $paragraph .= $textline;
1036 ## See of this line is blank and ends the current paragraph.
1037 ## If it isnt, then keep iterating until it is.
1038 next unless (($textline =~ /^\s*$/) && (length $paragraph));
1040 ## Now process the paragraph
1041 parse_paragraph($self, $paragraph, ($nlines - $plines) + 1);
1045 ## Dont forget about the last paragraph in the file
1046 if (length $paragraph) {
1047 parse_paragraph($self, $paragraph, ($nlines - $plines) + 1)
1050 ## Now pop the input stream off the top of the input stack.
1051 $self->_pop_input_stream();
1054 ##---------------------------------------------------------------------------
1056 =head1 B<parse_from_file()>
1058 $parser->parse_from_file($filename,$outfile);
1060 This method takes a filename and does the following:
1066 opens the input and output files for reading
1067 (creating the appropriate filehandles)
1071 invokes the B<parse_from_filehandle()> method passing it the
1072 corresponding input and output filehandles.
1076 closes the input and output files.
1080 If the special input filename "-" or "<&STDIN" is given then the STDIN
1081 filehandle is used for input (and no open or close is performed). If no
1082 input filename is specified then "-" is implied.
1084 If a second argument is given then it should be the name of the desired
1085 output file. If the special output filename "-" or ">&STDOUT" is given
1086 then the STDOUT filehandle is used for output (and no open or close is
1087 performed). If the special output filename ">&STDERR" is given then the
1088 STDERR filehandle is used for output (and no open or close is
1089 performed). If no output filehandle is currently in use and no output
1090 filename is specified, then "-" is implied.
1092 This method does I<not> usually need to be overridden by subclasses.
1096 sub parse_from_file {
1098 my %opts = (ref $_[0] eq 'HASH') ? %{ shift() } : ();
1099 my ($infile, $outfile) = @_;
1100 my ($in_fh, $out_fh);
1101 my ($close_input, $close_output) = (0, 0);
1102 local *myData = $self;
1105 ## Is $infile a filename or a (possibly implied) filehandle
1106 $infile = '-' unless ((defined $infile) && (length $infile));
1107 if (($infile eq '-') || ($infile =~ /^<&(STDIN|0)$/i)) {
1108 ## Not a filename, just a string implying STDIN
1109 $myData{_INFILE} = "<standard input>";
1112 elsif (ref $infile) {
1113 ## Must be a filehandle-ref (or else assume its a ref to an object
1114 ## that supports the common IO read operations).
1115 $myData{_INFILE} = ${$infile};
1119 ## We have a filename, open it for reading
1120 $myData{_INFILE} = $infile;
1121 open($in_fh, "< $infile") or
1122 croak "Can't open $infile for reading: $!\n";
1126 ## NOTE: we need to be *very* careful when "defaulting" the output
1127 ## file. We only want to use a default if this is the beginning of
1128 ## the entire document (but *not* if this is an included file). We
1129 ## determine this by seeing if the input stream stack has been set-up
1132 unless ((defined $outfile) && (length $outfile)) {
1133 (defined $myData{_TOP_STREAM}) && ($out_fh = $myData{_OUTPUT})
1134 || ($outfile = '-');
1136 ## Is $outfile a filename or a (possibly implied) filehandle
1137 if ((defined $outfile) && (length $outfile)) {
1138 if (($outfile eq '-') || ($outfile =~ /^>&?(?:STDOUT|1)$/i)) {
1139 ## Not a filename, just a string implying STDOUT
1140 $myData{_OUTFILE} = "<standard output>";
1143 elsif ($outfile =~ /^>&(STDERR|2)$/i) {
1144 ## Not a filename, just a string implying STDERR
1145 $myData{_OUTFILE} = "<standard error>";
1148 elsif (ref $outfile) {
1149 ## Must be a filehandle-ref (or else assume its a ref to an
1150 ## object that supports the common IO write operations).
1151 $myData{_OUTFILE} = ${$outfile};;
1155 ## We have a filename, open it for writing
1156 $myData{_OUTFILE} = $outfile;
1157 open($out_fh, "> $outfile") or
1158 croak "Can't open $outfile for writing: $!\n";
1163 ## Whew! That was a lot of work to set up reasonably/robust behavior
1164 ## in the case of a non-filename for reading and writing. Now we just
1165 ## have to parse the input and close the handles when we're finished.
1166 $self->parse_from_filehandle(\%opts, $in_fh, $out_fh);
1169 close($in_fh) || croak "Can't close $infile after reading: $!\n";
1171 close($out_fh) || croak "Can't close $outfile after writing: $!\n";
1174 #############################################################################
1176 =head1 ACCESSOR METHODS
1178 Clients of B<Pod::Parser> should use the following methods to access
1179 instance data fields:
1183 ##---------------------------------------------------------------------------
1185 =head1 B<errorsub()>
1187 $parser->errorsub("method_name");
1188 $parser->errorsub(\&warn_user);
1189 $parser->errorsub(sub { print STDERR, @_ });
1191 Specifies the method or subroutine to use when printing error messages
1192 about POD syntax. The supplied method/subroutine I<must> return TRUE upon
1193 successful printing of the message. If C<undef> is given, then the B<warn>
1194 builtin is used to issue error messages (this is the default behavior).
1196 my $errorsub = $parser->errorsub()
1197 my $errmsg = "This is an error message!\n"
1198 (ref $errorsub) and &{$errorsub}($errmsg)
1199 or (defined $errmsg) and $parser->$errorsub($errmsg)
1202 Returns a method name, or else a reference to the user-supplied subroutine
1203 used to print error messages. Returns C<undef> if the B<warn> builtin
1204 is used to issue error messages (this is the default behavior).
1209 return (@_ > 1) ? ($_[0]->{_ERRORSUB} = $_[1]) : $_[0]->{_ERRORSUB};
1212 ##---------------------------------------------------------------------------
1216 $boolean = $parser->cutting();
1218 Returns the current C<cutting> state: a boolean-valued scalar which
1219 evaluates to true if text from the input file is currently being "cut"
1220 (meaning it is I<not> considered part of the POD document).
1222 $parser->cutting($boolean);
1224 Sets the current C<cutting> state to the given value and returns the
1230 return (@_ > 1) ? ($_[0]->{_CUTTING} = $_[1]) : $_[0]->{_CUTTING};
1233 ##---------------------------------------------------------------------------
1235 ##---------------------------------------------------------------------------
1237 =head1 B<parseopts()>
1239 When invoked with no additional arguments, B<parseopts> returns a hashtable
1240 of all the current parsing options.
1242 ## See if we are parsing non-POD sections as well as POD ones
1243 my %opts = $parser->parseopts();
1244 $opts{'-want_nonPODs}' and print "-want_nonPODs\n";
1246 When invoked using a single string, B<parseopts> treats the string as the
1247 name of a parse-option and returns its corresponding value if it exists
1248 (returns C<undef> if it doesn't).
1250 ## Did we ask to see '=cut' paragraphs?
1251 my $want_cut = $parser->parseopts('-process_cut_cmd');
1252 $want_cut and print "-process_cut_cmd\n";
1254 When invoked with multiple arguments, B<parseopts> treats them as
1255 key/value pairs and the specified parse-option names are set to the
1256 given values. Any unspecified parse-options are unaffected.
1258 ## Set them back to the default
1259 $parser->parseopts(-process_cut_cmd => 0);
1261 When passed a single hash-ref, B<parseopts> uses that hash to completely
1262 reset the existing parse-options, all previous parse-option values
1265 ## Reset all options to default
1266 $parser->parseopts( { } );
1268 See L<"PARSING OPTIONS"> for more for the name and meaning of each
1269 parse-option currently recognized.
1274 local *myData = shift;
1275 local *myOpts = ($myData{_PARSEOPTS} ||= {});
1276 return %myOpts if (@_ == 0);
1279 return ref($_) ? $myData{_PARSEOPTS} = $_ : $myOpts{$_};
1281 my @newOpts = (%myOpts, @_);
1282 $myData{_PARSEOPTS} = { @newOpts };
1285 ##---------------------------------------------------------------------------
1287 =head1 B<output_file()>
1289 $fname = $parser->output_file();
1291 Returns the name of the output file being written.
1296 return $_[0]->{_OUTFILE};
1299 ##---------------------------------------------------------------------------
1301 =head1 B<output_handle()>
1303 $fhandle = $parser->output_handle();
1305 Returns the output filehandle object.
1310 return $_[0]->{_OUTPUT};
1313 ##---------------------------------------------------------------------------
1315 =head1 B<input_file()>
1317 $fname = $parser->input_file();
1319 Returns the name of the input file being read.
1324 return $_[0]->{_INFILE};
1327 ##---------------------------------------------------------------------------
1329 =head1 B<input_handle()>
1331 $fhandle = $parser->input_handle();
1333 Returns the current input filehandle object.
1338 return $_[0]->{_INPUT};
1341 ##---------------------------------------------------------------------------
1345 =head1 B<input_streams()>
1347 $listref = $parser->input_streams();
1349 Returns a reference to an array which corresponds to the stack of all
1350 the input streams that are currently in the middle of being parsed.
1352 While parsing an input stream, it is possible to invoke
1353 B<parse_from_file()> or B<parse_from_filehandle()> to parse a new input
1354 stream and then return to parsing the previous input stream. Each input
1355 stream to be parsed is pushed onto the end of this input stack
1356 before any of its input is read. The input stream that is currently
1357 being parsed is always at the end (or top) of the input stack. When an
1358 input stream has been exhausted, it is popped off the end of the
1361 Each element on this input stack is a reference to C<Pod::InputSource>
1362 object. Please see L<Pod::InputObjects> for more details.
1364 This method might be invoked when printing diagnostic messages, for example,
1365 to obtain the name and line number of the all input files that are currently
1373 return $_[0]->{_INPUT_STREAMS};
1376 ##---------------------------------------------------------------------------
1380 =head1 B<top_stream()>
1382 $hashref = $parser->top_stream();
1384 Returns a reference to the hash-table that represents the element
1385 that is currently at the top (end) of the input stream stack
1386 (see L<"input_streams()">). The return value will be the C<undef>
1387 if the input stack is empty.
1389 This method might be used when printing diagnostic messages, for example,
1390 to obtain the name and line number of the current input file.
1397 return $_[0]->{_TOP_STREAM} || undef;
1400 #############################################################################
1402 =head1 PRIVATE METHODS AND DATA
1404 B<Pod::Parser> makes use of several internal methods and data fields
1405 which clients should not need to see or use. For the sake of avoiding
1406 name collisions for client data and methods, these methods and fields
1407 are briefly discussed here. Determined hackers may obtain further
1408 information about them by reading the B<Pod::Parser> source code.
1410 Private data fields are stored in the hash-object whose reference is
1411 returned by the B<new()> constructor for this class. The names of all
1412 private methods and data-fields used by B<Pod::Parser> begin with a
1413 prefix of "_" and match the regular expression C</^_\w+$/>.
1417 ##---------------------------------------------------------------------------
1421 =head1 B<_push_input_stream()>
1423 $hashref = $parser->_push_input_stream($in_fh,$out_fh);
1425 This method will push the given input stream on the input stack and
1426 perform any necessary beginning-of-document or beginning-of-file
1427 processing. The argument C<$in_fh> is the input stream filehandle to
1428 push, and C<$out_fh> is the corresponding output filehandle to use (if
1429 it is not given or is undefined, then the current output stream is used,
1430 which defaults to standard output if it doesnt exist yet).
1432 The value returned will be reference to the hash-table that represents
1433 the new top of the input stream stack. I<Please Note> that it is
1434 possible for this method to use default values for the input and output
1435 file handles. If this happens, you will need to look at the C<INPUT>
1436 and C<OUTPUT> instance data members to determine their new values.
1442 sub _push_input_stream {
1443 my ($self, $in_fh, $out_fh) = @_;
1444 local *myData = $self;
1446 ## Initialize stuff for the entire document if this is *not*
1447 ## an included file.
1449 ## NOTE: we need to be *very* careful when "defaulting" the output
1450 ## filehandle. We only want to use a default value if this is the
1451 ## beginning of the entire document (but *not* if this is an included
1453 unless (defined $myData{_TOP_STREAM}) {
1454 $out_fh = \*STDOUT unless (defined $out_fh);
1455 $myData{_CUTTING} = 1; ## current "cutting" state
1456 $myData{_INPUT_STREAMS} = []; ## stack of all input streams
1459 ## Initialize input indicators
1460 $myData{_OUTFILE} = '(unknown)' unless (defined $myData{_OUTFILE});
1461 $myData{_OUTPUT} = $out_fh if (defined $out_fh);
1462 $in_fh = \*STDIN unless (defined $in_fh);
1463 $myData{_INFILE} = '(unknown)' unless (defined $myData{_INFILE});
1464 $myData{_INPUT} = $in_fh;
1465 my $input_top = $myData{_TOP_STREAM}
1466 = new Pod::InputSource(
1467 -name => $myData{_INFILE},
1469 -was_cutting => $myData{_CUTTING}
1471 local *input_stack = $myData{_INPUT_STREAMS};
1472 push(@input_stack, $input_top);
1474 ## Perform beginning-of-document and/or beginning-of-input processing
1475 $self->begin_pod() if (@input_stack == 1);
1476 $self->begin_input();
1481 ##---------------------------------------------------------------------------
1485 =head1 B<_pop_input_stream()>
1487 $hashref = $parser->_pop_input_stream();
1489 This takes no arguments. It will perform any necessary end-of-file or
1490 end-of-document processing and then pop the current input stream from
1491 the top of the input stack.
1493 The value returned will be reference to the hash-table that represents
1494 the new top of the input stream stack.
1500 sub _pop_input_stream {
1502 local *myData = $self;
1503 local *input_stack = $myData{_INPUT_STREAMS};
1505 ## Perform end-of-input and/or end-of-document processing
1506 $self->end_input() if (@input_stack > 0);
1507 $self->end_pod() if (@input_stack == 1);
1509 ## Restore cutting state to whatever it was before we started
1510 ## parsing this file.
1511 my $old_top = pop(@input_stack);
1512 $myData{_CUTTING} = $old_top->was_cutting();
1514 ## Dont forget to reset the input indicators
1515 my $input_top = undef;
1516 if (@input_stack > 0) {
1517 $input_top = $myData{_TOP_STREAM} = $input_stack[-1];
1518 $myData{_INFILE} = $input_top->name();
1519 $myData{_INPUT} = $input_top->handle();
1521 delete $myData{_TOP_STREAM};
1522 delete $myData{_INPUT_STREAMS};
1528 #############################################################################
1530 =head1 TREE-BASED PARSING
1532 If straightforward stream-based parsing wont meet your needs (as is
1533 likely the case for tasks such as translating PODs into structured
1534 markup languages like HTML and XML) then you may need to take the
1535 tree-based approach. Rather than doing everything in one pass and
1536 calling the B<interpolate()> method to expand sequences into text, it
1537 may be desirable to instead create a parse-tree using the B<parse_text()>
1538 method to return a tree-like structure which may contain an ordered list
1539 list of children (each of which may be a text-string, or a similar
1540 tree-like structure).
1542 Pay special attention to L<"METHODS FOR PARSING AND PROCESSING"> and
1543 to the objects described in L<Pod::InputObjects>. The former describes
1544 the gory details and parameters for how to customize and extend the
1545 parsing behavior of B<Pod::Parser>. B<Pod::InputObjects> provides
1546 several objects that may all be used interchangeably as parse-trees. The
1547 most obvious one is the B<Pod::ParseTree> object. It defines the basic
1548 interface and functionality that all things trying to be a POD parse-tree
1549 should do. A B<Pod::ParseTree> is defined such that each "node" may be a
1550 text-string, or a reference to another parse-tree. Each B<Pod::Paragraph>
1551 object and each B<Pod::InteriorSequence> object also supports the basic
1552 parse-tree interface.
1554 The B<parse_text()> method takes a given paragraph of text, and
1555 returns a parse-tree that contains one or more children, each of which
1556 may be a text-string, or an InteriorSequence object. There are also
1557 callback-options that may be passed to B<parse_text()> to customize
1558 the way it expands or transforms interior-sequences, as well as the
1559 returned result. These callbacks can be used to create a parse-tree
1560 with custom-made objects (which may or may not support the parse-tree
1561 interface, depending on how you choose to do it).
1563 If you wish to turn an entire POD document into a parse-tree, that process
1564 is fairly straightforward. The B<parse_text()> method is the key to doing
1565 this successfully. Every paragraph-callback (i.e. the polymorphic methods
1566 for B<command()>, B<verbatim()>, and B<textblock()> paragraphs) takes
1567 a B<Pod::Paragraph> object as an argument. Each paragraph object has a
1568 B<parse_tree()> method that can be used to get or set a corresponding
1569 parse-tree. So for each of those paragraph-callback methods, simply call
1570 B<parse_text()> with the options you desire, and then use the returned
1571 parse-tree to assign to the given paragraph object.
1573 That gives you a parse-tree for each paragraph - so now all you need is
1574 an ordered list of paragraphs. You can maintain that yourself as a data
1575 element in the object/hash. The most straightforward way would be simply
1576 to use an array-ref, with the desired set of custom "options" for each
1577 invocation of B<parse_text>. Let's assume the desired option-set is
1578 given by the hash C<%options>. Then we might do something like the
1581 package MyPodParserTree;
1583 @ISA = qw( Pod::Parser );
1589 $self->{'-paragraphs'} = []; ## initialize paragraph list
1593 my ($parser, $command, $paragraph, $line_num, $pod_para) = @_;
1594 my $ptree = $parser->parse_text({%options}, $paragraph, ...);
1595 $pod_para->parse_tree( $ptree );
1596 push @{ $self->{'-paragraphs'} }, $pod_para;
1600 my ($parser, $paragraph, $line_num, $pod_para) = @_;
1601 push @{ $self->{'-paragraphs'} }, $pod_para;
1605 my ($parser, $paragraph, $line_num, $pod_para) = @_;
1606 my $ptree = $parser->parse_text({%options}, $paragraph, ...);
1607 $pod_para->parse_tree( $ptree );
1608 push @{ $self->{'-paragraphs'} }, $pod_para;
1615 my $parser = new MyPodParserTree(...);
1616 $parser->parse_from_file(...);
1617 my $paragraphs_ref = $parser->{'-paragraphs'};
1619 Of course, in this module-author's humble opinion, I'd be more inclined to
1620 use the existing B<Pod::ParseTree> object than a simple array. That way
1621 everything in it, paragraphs and sequences, all respond to the same core
1622 interface for all parse-tree nodes. The result would look something like:
1624 package MyPodParserTree2;
1630 $self->{'-ptree'} = new Pod::ParseTree; ## initialize parse-tree
1634 ## convenience method to get/set the parse-tree for the entire POD
1635 (@_ > 1) and $_[0]->{'-ptree'} = $_[1];
1636 return $_[0]->{'-ptree'};
1640 my ($parser, $command, $paragraph, $line_num, $pod_para) = @_;
1641 my $ptree = $parser->parse_text({<<options>>}, $paragraph, ...);
1642 $pod_para->parse_tree( $ptree );
1643 $parser->parse_tree()->append( $pod_para );
1647 my ($parser, $paragraph, $line_num, $pod_para) = @_;
1648 $parser->parse_tree()->append( $pod_para );
1652 my ($parser, $paragraph, $line_num, $pod_para) = @_;
1653 my $ptree = $parser->parse_text({<<options>>}, $paragraph, ...);
1654 $pod_para->parse_tree( $ptree );
1655 $parser->parse_tree()->append( $pod_para );
1662 my $parser = new MyPodParserTree2(...);
1663 $parser->parse_from_file(...);
1664 my $ptree = $parser->parse_tree;
1667 Now you have the entire POD document as one great big parse-tree. You
1668 can even use the B<-expand_seq> option to B<parse_text> to insert
1669 whole different kinds of objects. Just don't expect B<Pod::Parser>
1670 to know what to do with them after that. That will need to be in your
1671 code. Or, alternatively, you can insert any object you like so long as
1672 it conforms to the B<Pod::ParseTree> interface.
1674 One could use this to create subclasses of B<Pod::Paragraphs> and
1675 B<Pod::InteriorSequences> for specific commands (or to create your own
1676 custom node-types in the parse-tree) and add some kind of B<emit()>
1677 method to each custom node/subclass object in the tree. Then all you'd
1678 need to do is recursively walk the tree in the desired order, processing
1679 the children (most likely from left to right) by formatting them if
1680 they are text-strings, or by calling their B<emit()> method if they
1681 are objects/references.
1685 L<Pod::InputObjects>, L<Pod::Select>
1687 B<Pod::InputObjects> defines POD input objects corresponding to
1688 command paragraphs, parse-trees, and interior-sequences.
1690 B<Pod::Select> is a subclass of B<Pod::Parser> which provides the ability
1691 to selectively include and/or exclude sections of a POD document from being
1692 translated based upon the current heading, subheading, subsubheading, etc.
1695 B<Pod::Callbacks> is a subclass of B<Pod::Parser> which gives its users
1696 the ability the employ I<callback functions> instead of, or in addition
1697 to, overriding methods of the base class.
1700 B<Pod::Select> and B<Pod::Callbacks> do not override any
1701 methods nor do they define any new methods with the same name. Because
1702 of this, they may I<both> be used (in combination) as a base class of
1703 the same subclass in order to combine their functionality without
1704 causing any namespace clashes due to multiple inheritance.
1708 Brad Appleton E<lt>bradapp@enteract.comE<gt>
1710 Based on code for B<Pod::Text> written by
1711 Tom Christiansen E<lt>tchrist@mox.perl.comE<gt>