fix diagnostics to report "our" vs "my" correctly
[p5sagit/p5-mst-13.2.git] / lib / Pod / Parser.pm
1 #############################################################################
2 # Pod/Parser.pm -- package which defines a base class for parsing POD docs.
3 #
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
7 # as Perl itself.
8 #############################################################################
9
10 package Pod::Parser;
11
12 use vars qw($VERSION);
13 $VERSION = 1.091;  ## Current version of this package
14 require  5.004;    ## requires this Perl version or later
15
16 #############################################################################
17
18 =head1 NAME
19
20 Pod::Parser - base class for creating POD filters and translators
21
22 =head1 SYNOPSIS
23
24     use Pod::Parser;
25
26     package MyParser;
27     @ISA = qw(Pod::Parser);
28
29     sub command { 
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;
38     }
39
40     sub verbatim { 
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;
45     }
46
47     sub textblock { 
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;
53     }
54
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
62     }
63
64     package main;
65
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($_); }
71
72 =head1 REQUIRES
73
74 perl5.004, Pod::InputObjects, Exporter, Carp
75
76 =head1 EXPORTS
77
78 Nothing.
79
80 =head1 DESCRIPTION
81
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.
86
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.
90
91 =head1 QUICK OVERVIEW
92
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:
96
97 =over 2
98
99 =item *
100
101 B<command()>
102
103 =item *
104
105 B<verbatim()>
106
107 =item *
108
109 B<textblock()>
110
111 =item *
112
113 B<interior_sequence()>
114
115 =back
116
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).
120
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()>.
124
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).
135
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.
140
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.
144
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">.
149
150 =head1 PARSING OPTIONS
151
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:
157
158 =over 3
159
160 =item B<-want_nonPODs> (default: unset)
161
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 sections 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.
170
171 =item B<-process_cut_cmd> (default: unset)
172
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).
178
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
182 it desires.
183
184 =back
185
186 Please see L<"parseopts()"> for a complete description of the interface
187 for the setting and unsetting of parse-options.
188
189 =cut
190
191 #############################################################################
192
193 use vars qw(@ISA);
194 use strict;
195 #use diagnostics;
196 use Pod::InputObjects;
197 use Carp;
198 use Exporter;
199 @ISA = qw(Exporter);
200
201 ## These "variables" are used as local "glob aliases" for performance
202 use vars qw(%myData %myOpts @input_stack);
203
204 #############################################################################
205
206 =head1 RECOMMENDED SUBROUTINE/METHOD OVERRIDES
207
208 B<Pod::Parser> provides several methods which most subclasses will probably
209 want to override. These methods are as follows:
210
211 =cut
212
213 ##---------------------------------------------------------------------------
214
215 =head1 B<command()>
216
217             $parser->command($cmd,$text,$line_num,$pod_para);
218
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:
223
224 =over 3
225
226 =item C<$cmd>
227
228 the name of the command for this POD paragraph
229
230 =item C<$text>
231
232 the paragraph text for the given POD paragraph command.
233
234 =item C<$line_num>
235
236 the line-number of the beginning of the paragraph
237
238 =item C<$pod_para>
239
240 a reference to a C<Pod::Paragraph> object which contains further
241 information about the paragraph command (see L<Pod::InputObjects>
242 for details).
243
244 =back
245
246 B<Note> that this method I<is> called for C<=pod> paragraphs.
247
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).
251
252 =cut
253
254 sub command {
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);
258 }
259
260 ##---------------------------------------------------------------------------
261
262 =head1 B<verbatim()>
263
264             $parser->verbatim($text,$line_num,$pod_para);
265
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:
269
270 =over 3
271
272 =item C<$text>
273
274 the block of text for the verbatim paragraph
275
276 =item C<$line_num>
277
278 the line-number of the beginning of the paragraph
279
280 =item C<$pod_para>
281
282 a reference to a C<Pod::Paragraph> object which contains further
283 information about the paragraph (see L<Pod::InputObjects>
284 for details).
285
286 =back
287
288 The base class implementation of this method simply prints the textblock
289 (unmodified) to the output filehandle.
290
291 =cut
292
293 sub verbatim {
294     my ($self, $text, $line_num, $pod_para) = @_;
295     my $out_fh = $self->{_OUTPUT};
296     print $out_fh $text;
297 }
298
299 ##---------------------------------------------------------------------------
300
301 =head1 B<textblock()>
302
303             $parser->textblock($text,$line_num,$pod_para);
304
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
308 parameters:
309
310 =over 3
311
312 =item C<$text>
313
314 the block of text for the a POD paragraph
315
316 =item C<$line_num>
317
318 the line-number of the beginning of the paragraph
319
320 =item C<$pod_para>
321
322 a reference to a C<Pod::Paragraph> object which contains further
323 information about the paragraph (see L<Pod::InputObjects>
324 for details).
325
326 =back
327
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
332 the returned result.
333
334 The base class implementation of this method simply prints the text block
335 as it occurred in the input stream).
336
337 =cut
338
339 sub textblock {
340     my ($self, $text, $line_num, $pod_para) = @_;
341     my $out_fh = $self->{_OUTPUT};
342     print $out_fh $self->interpolate($text, $line_num);
343 }
344
345 ##---------------------------------------------------------------------------
346
347 =head1 B<interior_sequence()>
348
349             $parser->interior_sequence($seq_cmd,$seq_arg,$pod_seq);
350
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.
364
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).
368
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.
372
373 =cut
374
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();
379 }
380
381 #############################################################################
382
383 =head1 OPTIONAL SUBROUTINE/METHOD OVERRIDES
384
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.
388
389 =cut
390
391 ##---------------------------------------------------------------------------
392
393 =head1 B<new()>
394
395             my $parser = Pod::Parser->new();
396
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:
401
402     my $parser1 = MyParser->new();
403     my $parser2 = new MyParser();
404     my $parser3 = $parser2->new();
405
406 where C<MyParser> is some subclass of B<Pod::Parser>.
407
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.
413
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()>
418 constructor, as in:
419
420     my $parser1 = MyParser->new( MYDATA => $value1, MOREDATA => $value2 );
421     my $parser2 = new MyParser( -myflag => 1 );
422
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).
428
429 =cut
430
431 sub new {
432     ## Determine if we were called via an object-ref or a classname
433     my $this = shift;
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.
437     my %params = @_;
438     my $self = { %params };
439     ## Bless ourselves into the desired class and perform any initialization
440     bless $self, $class;
441     $self->initialize();
442     return $self;
443 }
444
445 ##---------------------------------------------------------------------------
446
447 =head1 B<initialize()>
448
449             $parser->initialize();
450
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()>.
455
456 =cut
457
458 sub initialize {
459     #my $self = shift;
460     #return;
461 }
462
463 ##---------------------------------------------------------------------------
464
465 =head1 B<begin_pod()>
466
467             $parser->begin_pod();
468
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.
472
473 =cut
474
475 sub begin_pod {
476     #my $self = shift;
477     #return;
478 }
479
480 ##---------------------------------------------------------------------------
481
482 =head1 B<begin_input()>
483
484             $parser->begin_input();
485
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
489 initializations.
490
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()>.
495
496 =cut
497
498 sub begin_input {
499     #my $self = shift;
500     #return;
501 }
502
503 ##---------------------------------------------------------------------------
504
505 =head1 B<end_input()>
506
507             $parser->end_input();
508
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
512 cleanup actions.
513
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()>.
518
519 =cut
520
521 sub end_input {
522     #my $self = shift;
523     #return;
524 }
525
526 ##---------------------------------------------------------------------------
527
528 =head1 B<end_pod()>
529
530             $parser->end_pod();
531
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.
535
536 =cut
537
538 sub end_pod {
539     #my $self = shift;
540     #return;
541 }
542
543 ##---------------------------------------------------------------------------
544
545 =head1 B<preprocess_line()>
546
547           $textline = $parser->preprocess_line($text, $line_num);
548
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.
554
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.
558
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.
564
565 The base class implementation of this method returns the given text.
566
567 =cut
568
569 sub preprocess_line {
570     my ($self, $text, $line_num) = @_;
571     return  $text;
572 }
573
574 ##---------------------------------------------------------------------------
575
576 =head1 B<preprocess_paragraph()>
577
578             $textblock = $parser->preprocess_paragraph($text, $line_num);
579
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.
585
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).
589
590 This method is invoked after gathering up all the lines in a paragraph
591 and after determining the cutting state of the paragraph,
592 but before trying to further parse or interpret them. After
593 B<preprocess_paragraph()> returns, the current cutting state (which
594 is returned by C<$self-E<gt>cutting()>) is examined. If it evaluates
595 to true then input text (including the given C<$text>) is cut (not
596 processed) until the next POD directive is encountered.
597
598 Please note that the B<preprocess_line()> method is invoked I<before>
599 the B<preprocess_paragraph()> method. After all (possibly preprocessed)
600 lines in a paragraph have been assembled together and either it has been
601 determined that the paragraph is part of the POD documentation from one
602 of the selected sections or the C<-want_nonPODs> option is true, 
603 then B<preprocess_paragraph()> is invoked.
604
605 The base class implementation of this method returns the given text.
606
607 =cut
608
609 sub preprocess_paragraph {
610     my ($self, $text, $line_num) = @_;
611     return  $text;
612 }
613
614 #############################################################################
615
616 =head1 METHODS FOR PARSING AND PROCESSING
617
618 B<Pod::Parser> provides several methods to process input text. These
619 methods typically won't need to be overridden (and in some cases they
620 can't be overridden), but subclasses may want to invoke them to exploit
621 their functionality.
622
623 =cut
624
625 ##---------------------------------------------------------------------------
626
627 =head1 B<parse_text()>
628
629             $ptree1 = $parser->parse_text($text, $line_num);
630             $ptree2 = $parser->parse_text({%opts}, $text, $line_num);
631             $ptree3 = $parser->parse_text(\%opts, $text, $line_num);
632
633 This method is useful if you need to perform your own interpolation 
634 of interior sequences and can't rely upon B<interpolate> to expand
635 them in simple bottom-up order order.
636
637 The parameter C<$text> is a string or block of text to be parsed
638 for interior sequences; and the parameter C<$line_num> is the
639 line number curresponding to the beginning of C<$text>.
640
641 B<parse_text()> will parse the given text into a parse-tree of "nodes."
642 and interior-sequences.  Each "node" in the parse tree is either a
643 text-string, or a B<Pod::InteriorSequence>.  The result returned is a
644 parse-tree of type B<Pod::ParseTree>. Please see L<Pod::InputObjects>
645 for more information about B<Pod::InteriorSequence> and B<Pod::ParseTree>.
646
647 If desired, an optional hash-ref may be specified as the first argument
648 to customize certain aspects of the parse-tree that is created and
649 returned. The set of recognized option keywords are:
650
651 =over 3
652
653 =item B<-expand_seq> =E<gt> I<code-ref>|I<method-name>
654
655 Normally, the parse-tree returned by B<parse_text()> will contain an
656 unexpanded C<Pod::InteriorSequence> object for each interior-sequence
657 encountered. Specifying B<-expand_seq> tells B<parse_text()> to "expand"
658 every interior-sequence it sees by invoking the referenced function
659 (or named method of the parser object) and using the return value as the
660 expanded result.
661
662 If a subroutine reference was given, it is invoked as:
663
664   &$code_ref( $parser, $sequence )
665
666 and if a method-name was given, it is invoked as:
667
668   $parser->method_name( $sequence )
669
670 where C<$parser> is a reference to the parser object, and C<$sequence>
671 is a reference to the interior-sequence object.
672 [I<NOTE>: If the B<interior_sequence()> method is specified, then it is
673 invoked according to the interface specified in L<"interior_sequence()">].
674
675 =item B<-expand_text> =E<gt> I<code-ref>|I<method-name>
676
677 Normally, the parse-tree returned by B<parse_text()> will contain a
678 text-string for each contiguous sequence of characters outside of an
679 interior-sequence. Specifying B<-expand_text> tells B<parse_text()> to
680 "preprocess" every such text-string it sees by invoking the referenced
681 function (or named method of the parser object) and using the return value
682 as the preprocessed (or "expanded") result. [Note that if the result is
683 an interior-sequence, then it will I<not> be expanded as specified by the
684 B<-expand_seq> option; Any such recursive expansion needs to be handled by
685 the specified callback routine.]
686
687 If a subroutine reference was given, it is invoked as:
688
689   &$code_ref( $parser, $text, $ptree_node )
690
691 and if a method-name was given, it is invoked as:
692
693   $parser->method_name( $text, $ptree_node )
694
695 where C<$parser> is a reference to the parser object, C<$text> is the
696 text-string encountered, and C<$ptree_node> is a reference to the current
697 node in the parse-tree (usually an interior-sequence object or else the
698 top-level node of the parse-tree).
699
700 =item B<-expand_ptree> =E<gt> I<code-ref>|I<method-name>
701
702 Rather than returning a C<Pod::ParseTree>, pass the parse-tree as an
703 argument to the referenced subroutine (or named method of the parser
704 object) and return the result instead of the parse-tree object.
705
706 If a subroutine reference was given, it is invoked as:
707
708   &$code_ref( $parser, $ptree )
709
710 and if a method-name was given, it is invoked as:
711
712   $parser->method_name( $ptree )
713
714 where C<$parser> is a reference to the parser object, and C<$ptree>
715 is a reference to the parse-tree object.
716
717 =back
718
719 =cut
720
721 ## This global regex is used to see if the text before a '>' inside
722 ## an interior sequence looks like '-' or '=', but not '--', '==',
723 ## '!=', '$-', '$=' or <<op>>=
724 use vars qw( $ARROW_RE );
725 $ARROW_RE = join('', qw{ (?: [^-+*/=!&|%^x.<>$]= | [^-$]- )$ });
726 #$ARROW_RE = qr/(?:[^-+*/=!&|%^x.<>$]+=|[^-$]+-)$/;  ## 5.005+ only!
727
728 sub parse_text {
729     my $self = shift;
730     local $_ = '';
731
732     ## Get options and set any defaults
733     my %opts = (ref $_[0]) ? %{ shift() } : ();
734     my $expand_seq   = $opts{'-expand_seq'}   || undef;
735     my $expand_text  = $opts{'-expand_text'}  || undef;
736     my $expand_ptree = $opts{'-expand_ptree'} || undef;
737
738     my $text = shift;
739     my $line = shift;
740     my $file = $self->input_file();
741     my ($cmd, $prev)  = ('', '');
742
743     ## Convert method calls into closures, for our convenience
744     my $xseq_sub   = $expand_seq;
745     my $xtext_sub  = $expand_text;
746     my $xptree_sub = $expand_ptree;
747     if (defined $expand_seq  and  $expand_seq eq 'interior_sequence') {
748         ## If 'interior_sequence' is the method to use, we have to pass
749         ## more than just the sequence object, we also need to pass the
750         ## sequence name and text.
751         $xseq_sub = sub {
752             my ($self, $iseq) = @_;
753             my $args = join("", $iseq->parse_tree->children);
754             return  $self->interior_sequence($iseq->name, $args, $iseq);
755         };
756     }
757     ref $xseq_sub    or  $xseq_sub   = sub { shift()->$expand_seq(@_) };
758     ref $xtext_sub   or  $xtext_sub  = sub { shift()->$expand_text(@_) };
759     ref $xptree_sub  or  $xptree_sub = sub { shift()->$expand_ptree(@_) };
760     
761     ## Keep track of the "current" interior sequence, and maintain a stack
762     ## of "in progress" sequences.
763     ##
764     ## NOTE that we push our own "accumulator" at the very beginning of the
765     ## stack. It's really a parse-tree, not a sequence; but it implements
766     ## the methods we need so we can use it to gather-up all the sequences
767     ## and strings we parse. Thus, by the end of our parsing, it should be
768     ## the only thing left on our stack and all we have to do is return it!
769     ##
770     my $seq       = Pod::ParseTree->new();
771     my @seq_stack = ($seq);
772
773     ## Iterate over all sequence starts/stops, newlines, & text
774     ## (NOTE: split with capturing parens keeps the delimiters)
775     $_ = $text;
776     for ( split /([A-Z]<|>|\n)/ ) {
777         ## Keep track of line count
778         ++$line  if ($_ eq "\n");
779         ## Look for the beginning of a sequence
780         if ( /^([A-Z])(<)$/ ) {
781             ## Push a new sequence onto the stack of those "in-progress"
782             $seq = Pod::InteriorSequence->new(
783                        -name   => ($cmd = $1),
784                        -ldelim => $2,     -rdelim => '',
785                        -file   => $file,  -line   => $line
786                    );
787             (@seq_stack > 1)  and  $seq->nested($seq_stack[-1]);
788             push @seq_stack, $seq;
789         }
790         ## Look for sequence ending (preclude '->' and '=>' inside C<...>)
791         elsif ( (@seq_stack > 1)  and
792                 /^>$/ and ($cmd ne 'C' or $prev !~ /$ARROW_RE/o) )
793         {
794             ## End of current sequence, record terminating delimiter
795             $seq->rdelim($_);
796             ## Pop it off the stack of "in progress" sequences
797             pop @seq_stack;
798             ## Append result to its parent in current parse tree
799             $seq_stack[-1]->append($expand_seq ? &$xseq_sub($self,$seq) : $seq);
800             ## Remember the current cmd-name
801             $cmd = (@seq_stack > 1) ? $seq_stack[-1]->name : '';
802         }
803         elsif (length) {
804             ## In the middle of a sequence, append this text to it, and
805             ## dont forget to "expand" it if that's what the caller wanted
806             $seq->append($expand_text ? &$xtext_sub($self,$_,$seq) : $_);
807         }
808         ## Remember the "current" sequence and the previously seen token
809         ($seq, $prev) = ( $seq_stack[-1], $_ );
810     }
811
812     ## Handle unterminated sequences
813     my $errorsub = (@seq_stack > 1) ? $self->errorsub() : undef;
814     while (@seq_stack > 1) {
815        ($cmd, $file, $line) = ($seq->name, $seq->file_line);
816        pop @seq_stack;
817        my $errmsg = "** Unterminated $cmd<...> at $file line $line\n";
818        (ref $errorsub) and &{$errorsub}($errmsg)
819            or (defined $errorsub) and $self->$errorsub($errmsg)
820                or  warn($errmsg);
821        $seq_stack[-1]->append($expand_seq ? &$xseq_sub($self,$seq) : $seq);
822        $seq = $seq_stack[-1];
823     }
824
825     ## Return the resulting parse-tree
826     my $ptree = (pop @seq_stack)->parse_tree;
827     return  $expand_ptree ? &$xptree_sub($self, $ptree) : $ptree;
828 }
829
830 ##---------------------------------------------------------------------------
831
832 =head1 B<interpolate()>
833
834             $textblock = $parser->interpolate($text, $line_num);
835
836 This method translates all text (including any embedded interior sequences)
837 in the given text string C<$text> and returns the interpolated result. The
838 parameter C<$line_num> is the line number corresponding to the beginning
839 of C<$text>.
840
841 B<interpolate()> merely invokes a private method to recursively expand
842 nested interior sequences in bottom-up order (innermost sequences are
843 expanded first). If there is a need to expand nested sequences in
844 some alternate order, use B<parse_text> instead.
845
846 =cut
847
848 sub interpolate {
849     my($self, $text, $line_num) = @_;
850     my %parse_opts = ( -expand_seq => 'interior_sequence' );
851     my $ptree = $self->parse_text( \%parse_opts, $text, $line_num );
852     return  join "", $ptree->children();
853 }
854
855 ##---------------------------------------------------------------------------
856
857 =begin __PRIVATE__
858
859 =head1 B<parse_paragraph()>
860
861             $parser->parse_paragraph($text, $line_num);
862
863 This method takes the text of a POD paragraph to be processed, along
864 with its corresponding line number, and invokes the appropriate method
865 (one of B<command()>, B<verbatim()>, or B<textblock()>).
866
867 For performance reasons, this method is invoked directly without any
868 dynamic lookup; Hence subclasses may I<not> override it!
869
870 =end __PRIVATE__
871
872 =cut
873
874 sub parse_paragraph {
875     my ($self, $text, $line_num) = @_;
876     local *myData = $self;  ## alias to avoid deref-ing overhead
877     local *myOpts = ($myData{_PARSEOPTS} ||= {});  ## get parse-options
878     local $_;
879
880     ## See if we want to preprocess nonPOD paragraphs as well as POD ones.
881     my $wantNonPods = $myOpts{'-want_nonPODs'};
882
883     ## Update cutting status
884     $myData{_CUTTING} = 0 if $text =~ /^={1,2}\S/;
885
886     ## Perform any desired preprocessing if we wanted it this early
887     $wantNonPods  and  $text = $self->preprocess_paragraph($text, $line_num);
888
889     ## Ignore up until next POD directive if we are cutting
890     return if $myData{_CUTTING};
891
892     ## Now we know this is block of text in a POD section!
893
894     ##-----------------------------------------------------------------
895     ## This is a hook (hack ;-) for Pod::Select to do its thing without
896     ## having to override methods, but also without Pod::Parser assuming
897     ## $self is an instance of Pod::Select (if the _SELECTED_SECTIONS
898     ## field exists then we assume there is an is_selected() method for
899     ## us to invoke (calling $self->can('is_selected') could verify this
900     ## but that is more overhead than I want to incur)
901     ##-----------------------------------------------------------------
902
903     ## Ignore this block if it isnt in one of the selected sections
904     if (exists $myData{_SELECTED_SECTIONS}) {
905         $self->is_selected($text)  or  return ($myData{_CUTTING} = 1);
906     }
907
908     ## If we havent already, perform any desired preprocessing and
909     ## then re-check the "cutting" state
910     unless ($wantNonPods) {
911        $text = $self->preprocess_paragraph($text, $line_num);
912        return 1  unless ((defined $text) and (length $text));
913        return 1  if ($myData{_CUTTING});
914     }
915
916     ## Look for one of the three types of paragraphs
917     my ($pfx, $cmd, $arg, $sep) = ('', '', '', '');
918     my $pod_para = undef;
919     if ($text =~ /^(={1,2})(?=\S)/) {
920         ## Looks like a command paragraph. Capture the command prefix used
921         ## ("=" or "=="), as well as the command-name, its paragraph text,
922         ## and whatever sequence of characters was used to separate them
923         $pfx = $1;
924         $_ = substr($text, length $pfx);
925         $sep = /(\s+)(?=\S)/ ? $1 : '';
926         ($cmd, $text) = split(" ", $_, 2);
927         ## If this is a "cut" directive then we dont need to do anything
928         ## except return to "cutting" mode.
929         if ($cmd eq 'cut') {
930            $myData{_CUTTING} = 1;
931            return  unless $myOpts{'-process_cut_cmd'};
932         }
933     }
934     ## Save the attributes indicating how the command was specified.
935     $pod_para = new Pod::Paragraph(
936           -name      => $cmd,
937           -text      => $text,
938           -prefix    => $pfx,
939           -separator => $sep,
940           -file      => $myData{_INFILE},
941           -line      => $line_num
942     );
943     # ## Invoke appropriate callbacks
944     # if (exists $myData{_CALLBACKS}) {
945     #    ## Look through the callback list, invoke callbacks,
946     #    ## then see if we need to do the default actions
947     #    ## (invoke_callbacks will return true if we do).
948     #    return  1  unless $self->invoke_callbacks($cmd, $text, $line_num, $pod_para);
949     # }
950     if (length $cmd) {
951         ## A command paragraph
952         $self->command($cmd, $text, $line_num, $pod_para);
953     }
954     elsif ($text =~ /^\s+/) {
955         ## Indented text - must be a verbatim paragraph
956         $self->verbatim($text, $line_num, $pod_para);
957     }
958     else {
959         ## Looks like an ordinary block of text
960         $self->textblock($text, $line_num, $pod_para);
961     }
962     return  1;
963 }
964
965 ##---------------------------------------------------------------------------
966
967 =head1 B<parse_from_filehandle()>
968
969             $parser->parse_from_filehandle($in_fh,$out_fh);
970
971 This method takes an input filehandle (which is assumed to already be
972 opened for reading) and reads the entire input stream looking for blocks
973 (paragraphs) of POD documentation to be processed. If no first argument
974 is given the default input filehandle C<STDIN> is used.
975
976 The C<$in_fh> parameter may be any object that provides a B<getline()>
977 method to retrieve a single line of input text (hence, an appropriate
978 wrapper object could be used to parse PODs from a single string or an
979 array of strings).
980
981 Using C<$in_fh-E<gt>getline()>, input is read line-by-line and assembled
982 into paragraphs or "blocks" (which are separated by lines containing
983 nothing but whitespace). For each block of POD documentation
984 encountered it will invoke a method to parse the given paragraph.
985
986 If a second argument is given then it should correspond to a filehandle where
987 output should be sent (otherwise the default output filehandle is
988 C<STDOUT> if no output filehandle is currently in use).
989
990 B<NOTE:> For performance reasons, this method caches the input stream at
991 the top of the stack in a local variable. Any attempts by clients to
992 change the stack contents during processing when in the midst executing
993 of this method I<will not affect> the input stream used by the current
994 invocation of this method.
995
996 This method does I<not> usually need to be overridden by subclasses.
997
998 =cut
999
1000 sub parse_from_filehandle {
1001     my $self = shift;
1002     my %opts = (ref $_[0] eq 'HASH') ? %{ shift() } : ();
1003     my ($in_fh, $out_fh) = @_;
1004     $in_fh = \*STDIN  unless ($in_fh);
1005     local $_;
1006
1007     ## Put this stream at the top of the stack and do beginning-of-input
1008     ## processing. NOTE that $in_fh might be reset during this process.
1009     my $topstream = $self->_push_input_stream($in_fh, $out_fh);
1010     (exists $opts{-cutting})  and  $self->cutting( $opts{-cutting} );
1011
1012     ## Initialize line/paragraph
1013     my ($textline, $paragraph) = ('', '');
1014     my ($nlines, $plines) = (0, 0);
1015
1016     ## Use <$fh> instead of $fh->getline where possible (for speed)
1017     $_ = ref $in_fh;
1018     my $tied_fh = (/^(?:GLOB|FileHandle|IO::\w+)$/  or  tied $in_fh);
1019
1020     ## Read paragraphs line-by-line
1021     while (defined ($textline = $tied_fh ? <$in_fh> : $in_fh->getline)) {
1022         $textline = $self->preprocess_line($textline, ++$nlines);
1023         next  unless ((defined $textline)  &&  (length $textline));
1024         $_ = $paragraph;  ## save previous contents
1025
1026         if ((! length $paragraph) && ($textline =~ /^==/)) {
1027             ## '==' denotes a one-line command paragraph
1028             $paragraph = $textline;
1029             $plines    = 1;
1030             $textline  = '';
1031         } else {
1032             ## Append this line to the current paragraph
1033             $paragraph .= $textline;
1034             ++$plines;
1035         }
1036
1037         ## See of this line is blank and ends the current paragraph.
1038         ## If it isnt, then keep iterating until it is.
1039         next unless (($textline =~ /^\s*$/) && (length $paragraph));
1040
1041         ## Now process the paragraph
1042         parse_paragraph($self, $paragraph, ($nlines - $plines) + 1);
1043         $paragraph = '';
1044         $plines = 0;
1045     }
1046     ## Dont forget about the last paragraph in the file
1047     if (length $paragraph) {
1048        parse_paragraph($self, $paragraph, ($nlines - $plines) + 1)
1049     }
1050
1051     ## Now pop the input stream off the top of the input stack.
1052     $self->_pop_input_stream();
1053 }
1054
1055 ##---------------------------------------------------------------------------
1056
1057 =head1 B<parse_from_file()>
1058
1059             $parser->parse_from_file($filename,$outfile);
1060
1061 This method takes a filename and does the following:
1062
1063 =over 2
1064
1065 =item *
1066
1067 opens the input and output files for reading
1068 (creating the appropriate filehandles)
1069
1070 =item *
1071
1072 invokes the B<parse_from_filehandle()> method passing it the
1073 corresponding input and output filehandles.
1074
1075 =item *
1076
1077 closes the input and output files.
1078
1079 =back
1080
1081 If the special input filename "-" or "<&STDIN" is given then the STDIN
1082 filehandle is used for input (and no open or close is performed). If no
1083 input filename is specified then "-" is implied.
1084
1085 If a second argument is given then it should be the name of the desired
1086 output file. If the special output filename "-" or ">&STDOUT" is given
1087 then the STDOUT filehandle is used for output (and no open or close is
1088 performed). If the special output filename ">&STDERR" is given then the
1089 STDERR filehandle is used for output (and no open or close is
1090 performed). If no output filehandle is currently in use and no output
1091 filename is specified, then "-" is implied.
1092
1093 This method does I<not> usually need to be overridden by subclasses.
1094
1095 =cut
1096
1097 sub parse_from_file {
1098     my $self = shift;
1099     my %opts = (ref $_[0] eq 'HASH') ? %{ shift() } : ();
1100     my ($infile, $outfile) = @_;
1101     my ($in_fh,  $out_fh);
1102     my ($close_input, $close_output) = (0, 0);
1103     local *myData = $self;
1104     local $_;
1105
1106     ## Is $infile a filename or a (possibly implied) filehandle
1107     $infile  = '-'  unless ((defined $infile)  && (length $infile));
1108     if (($infile  eq '-') || ($infile =~ /^<&(STDIN|0)$/i)) {
1109         ## Not a filename, just a string implying STDIN
1110         $myData{_INFILE} = "<standard input>";
1111         $in_fh = \*STDIN;
1112     }
1113     elsif (ref $infile) {
1114         ## Must be a filehandle-ref (or else assume its a ref to an object
1115         ## that supports the common IO read operations).
1116         $myData{_INFILE} = ${$infile};
1117         $in_fh = $infile;
1118     }
1119     else {
1120         ## We have a filename, open it for reading
1121         $myData{_INFILE} = $infile;
1122         open($in_fh, "< $infile")  or
1123              croak "Can't open $infile for reading: $!\n";
1124         $close_input = 1;
1125     }
1126
1127     ## NOTE: we need to be *very* careful when "defaulting" the output
1128     ## file. We only want to use a default if this is the beginning of
1129     ## the entire document (but *not* if this is an included file). We
1130     ## determine this by seeing if the input stream stack has been set-up
1131     ## already
1132     ## 
1133     unless ((defined $outfile) && (length $outfile)) {
1134         (defined $myData{_TOP_STREAM}) && ($out_fh  = $myData{_OUTPUT})
1135                                        || ($outfile = '-');
1136     }
1137     ## Is $outfile a filename or a (possibly implied) filehandle
1138     if ((defined $outfile) && (length $outfile)) {
1139         if (($outfile  eq '-') || ($outfile =~ /^>&?(?:STDOUT|1)$/i)) {
1140             ## Not a filename, just a string implying STDOUT
1141             $myData{_OUTFILE} = "<standard output>";
1142             $out_fh  = \*STDOUT;
1143         }
1144         elsif ($outfile =~ /^>&(STDERR|2)$/i) {
1145             ## Not a filename, just a string implying STDERR
1146             $myData{_OUTFILE} = "<standard error>";
1147             $out_fh  = \*STDERR;
1148         }
1149         elsif (ref $outfile) {
1150             ## Must be a filehandle-ref (or else assume its a ref to an
1151             ## object that supports the common IO write operations).
1152             $myData{_OUTFILE} = ${$outfile};;
1153             $out_fh = $outfile;
1154         }
1155         else {
1156             ## We have a filename, open it for writing
1157             $myData{_OUTFILE} = $outfile;
1158             open($out_fh, "> $outfile")  or
1159                  croak "Can't open $outfile for writing: $!\n";
1160             $close_output = 1;
1161         }
1162     }
1163
1164     ## Whew! That was a lot of work to set up reasonably/robust behavior
1165     ## in the case of a non-filename for reading and writing. Now we just
1166     ## have to parse the input and close the handles when we're finished.
1167     $self->parse_from_filehandle(\%opts, $in_fh, $out_fh);
1168
1169     $close_input  and 
1170         close($in_fh) || croak "Can't close $infile after reading: $!\n";
1171     $close_output  and
1172         close($out_fh) || croak "Can't close $outfile after writing: $!\n";
1173 }
1174
1175 #############################################################################
1176
1177 =head1 ACCESSOR METHODS
1178
1179 Clients of B<Pod::Parser> should use the following methods to access
1180 instance data fields:
1181
1182 =cut
1183
1184 ##---------------------------------------------------------------------------
1185
1186 =head1 B<errorsub()>
1187
1188             $parser->errorsub("method_name");
1189             $parser->errorsub(\&warn_user);
1190             $parser->errorsub(sub { print STDERR, @_ });
1191
1192 Specifies the method or subroutine to use when printing error messages
1193 about POD syntax. The supplied method/subroutine I<must> return TRUE upon
1194 successful printing of the message. If C<undef> is given, then the B<warn>
1195 builtin is used to issue error messages (this is the default behavior).
1196
1197             my $errorsub = $parser->errorsub()
1198             my $errmsg = "This is an error message!\n"
1199             (ref $errorsub) and &{$errorsub}($errmsg)
1200                 or (defined $errorsub) and $parser->$errorsub($errmsg)
1201                     or  warn($errmsg);
1202
1203 Returns a method name, or else a reference to the user-supplied subroutine
1204 used to print error messages. Returns C<undef> if the B<warn> builtin
1205 is used to issue error messages (this is the default behavior).
1206
1207 =cut
1208
1209 sub errorsub {
1210    return (@_ > 1) ? ($_[0]->{_ERRORSUB} = $_[1]) : $_[0]->{_ERRORSUB};
1211 }
1212
1213 ##---------------------------------------------------------------------------
1214
1215 =head1 B<cutting()>
1216
1217             $boolean = $parser->cutting();
1218
1219 Returns the current C<cutting> state: a boolean-valued scalar which
1220 evaluates to true if text from the input file is currently being "cut"
1221 (meaning it is I<not> considered part of the POD document).
1222
1223             $parser->cutting($boolean);
1224
1225 Sets the current C<cutting> state to the given value and returns the
1226 result.
1227
1228 =cut
1229
1230 sub cutting {
1231    return (@_ > 1) ? ($_[0]->{_CUTTING} = $_[1]) : $_[0]->{_CUTTING};
1232 }
1233
1234 ##---------------------------------------------------------------------------
1235
1236 ##---------------------------------------------------------------------------
1237
1238 =head1 B<parseopts()>
1239
1240 When invoked with no additional arguments, B<parseopts> returns a hashtable
1241 of all the current parsing options.
1242
1243             ## See if we are parsing non-POD sections as well as POD ones
1244             my %opts = $parser->parseopts();
1245             $opts{'-want_nonPODs}' and print "-want_nonPODs\n";
1246
1247 When invoked using a single string, B<parseopts> treats the string as the
1248 name of a parse-option and returns its corresponding value if it exists
1249 (returns C<undef> if it doesn't).
1250
1251             ## Did we ask to see '=cut' paragraphs?
1252             my $want_cut = $parser->parseopts('-process_cut_cmd');
1253             $want_cut and print "-process_cut_cmd\n";
1254
1255 When invoked with multiple arguments, B<parseopts> treats them as
1256 key/value pairs and the specified parse-option names are set to the
1257 given values. Any unspecified parse-options are unaffected.
1258
1259             ## Set them back to the default
1260             $parser->parseopts(-process_cut_cmd => 0);
1261
1262 When passed a single hash-ref, B<parseopts> uses that hash to completely
1263 reset the existing parse-options, all previous parse-option values
1264 are lost.
1265
1266             ## Reset all options to default 
1267             $parser->parseopts( { } );
1268
1269 See L<"PARSING OPTIONS"> for more for the name and meaning of each
1270 parse-option currently recognized.
1271
1272 =cut
1273
1274 sub parseopts {
1275    local *myData = shift;
1276    local *myOpts = ($myData{_PARSEOPTS} ||= {});
1277    return %myOpts  if (@_ == 0);
1278    if (@_ == 1) {
1279       local $_ = shift;
1280       return  ref($_)  ?  $myData{_PARSEOPTS} = $_  :  $myOpts{$_};
1281    }
1282    my @newOpts = (%myOpts, @_);
1283    $myData{_PARSEOPTS} = { @newOpts };
1284 }
1285
1286 ##---------------------------------------------------------------------------
1287
1288 =head1 B<output_file()>
1289
1290             $fname = $parser->output_file();
1291
1292 Returns the name of the output file being written.
1293
1294 =cut
1295
1296 sub output_file {
1297    return $_[0]->{_OUTFILE};
1298 }
1299
1300 ##---------------------------------------------------------------------------
1301
1302 =head1 B<output_handle()>
1303
1304             $fhandle = $parser->output_handle();
1305
1306 Returns the output filehandle object.
1307
1308 =cut
1309
1310 sub output_handle {
1311    return $_[0]->{_OUTPUT};
1312 }
1313
1314 ##---------------------------------------------------------------------------
1315
1316 =head1 B<input_file()>
1317
1318             $fname = $parser->input_file();
1319
1320 Returns the name of the input file being read.
1321
1322 =cut
1323
1324 sub input_file {
1325    return $_[0]->{_INFILE};
1326 }
1327
1328 ##---------------------------------------------------------------------------
1329
1330 =head1 B<input_handle()>
1331
1332             $fhandle = $parser->input_handle();
1333
1334 Returns the current input filehandle object.
1335
1336 =cut
1337
1338 sub input_handle {
1339    return $_[0]->{_INPUT};
1340 }
1341
1342 ##---------------------------------------------------------------------------
1343
1344 =begin __PRIVATE__
1345
1346 =head1 B<input_streams()>
1347
1348             $listref = $parser->input_streams();
1349
1350 Returns a reference to an array which corresponds to the stack of all
1351 the input streams that are currently in the middle of being parsed.
1352
1353 While parsing an input stream, it is possible to invoke
1354 B<parse_from_file()> or B<parse_from_filehandle()> to parse a new input
1355 stream and then return to parsing the previous input stream. Each input
1356 stream to be parsed is pushed onto the end of this input stack
1357 before any of its input is read. The input stream that is currently
1358 being parsed is always at the end (or top) of the input stack. When an
1359 input stream has been exhausted, it is popped off the end of the
1360 input stack.
1361
1362 Each element on this input stack is a reference to C<Pod::InputSource>
1363 object. Please see L<Pod::InputObjects> for more details.
1364
1365 This method might be invoked when printing diagnostic messages, for example,
1366 to obtain the name and line number of the all input files that are currently
1367 being processed.
1368
1369 =end __PRIVATE__
1370
1371 =cut
1372
1373 sub input_streams {
1374    return $_[0]->{_INPUT_STREAMS};
1375 }
1376
1377 ##---------------------------------------------------------------------------
1378
1379 =begin __PRIVATE__
1380
1381 =head1 B<top_stream()>
1382
1383             $hashref = $parser->top_stream();
1384
1385 Returns a reference to the hash-table that represents the element
1386 that is currently at the top (end) of the input stream stack
1387 (see L<"input_streams()">). The return value will be the C<undef>
1388 if the input stack is empty.
1389
1390 This method might be used when printing diagnostic messages, for example,
1391 to obtain the name and line number of the current input file.
1392
1393 =end __PRIVATE__
1394
1395 =cut
1396
1397 sub top_stream {
1398    return $_[0]->{_TOP_STREAM} || undef;
1399 }
1400
1401 #############################################################################
1402
1403 =head1 PRIVATE METHODS AND DATA
1404
1405 B<Pod::Parser> makes use of several internal methods and data fields
1406 which clients should not need to see or use. For the sake of avoiding
1407 name collisions for client data and methods, these methods and fields
1408 are briefly discussed here. Determined hackers may obtain further
1409 information about them by reading the B<Pod::Parser> source code.
1410
1411 Private data fields are stored in the hash-object whose reference is
1412 returned by the B<new()> constructor for this class. The names of all
1413 private methods and data-fields used by B<Pod::Parser> begin with a
1414 prefix of "_" and match the regular expression C</^_\w+$/>.
1415
1416 =cut
1417
1418 ##---------------------------------------------------------------------------
1419
1420 =begin _PRIVATE_
1421
1422 =head1 B<_push_input_stream()>
1423
1424             $hashref = $parser->_push_input_stream($in_fh,$out_fh);
1425
1426 This method will push the given input stream on the input stack and
1427 perform any necessary beginning-of-document or beginning-of-file
1428 processing. The argument C<$in_fh> is the input stream filehandle to
1429 push, and C<$out_fh> is the corresponding output filehandle to use (if
1430 it is not given or is undefined, then the current output stream is used,
1431 which defaults to standard output if it doesnt exist yet).
1432
1433 The value returned will be reference to the hash-table that represents
1434 the new top of the input stream stack. I<Please Note> that it is
1435 possible for this method to use default values for the input and output
1436 file handles. If this happens, you will need to look at the C<INPUT>
1437 and C<OUTPUT> instance data members to determine their new values.
1438
1439 =end _PRIVATE_
1440
1441 =cut
1442
1443 sub _push_input_stream {
1444     my ($self, $in_fh, $out_fh) = @_;
1445     local *myData = $self;
1446
1447     ## Initialize stuff for the entire document if this is *not*
1448     ## an included file.
1449     ##
1450     ## NOTE: we need to be *very* careful when "defaulting" the output
1451     ## filehandle. We only want to use a default value if this is the
1452     ## beginning of the entire document (but *not* if this is an included
1453     ## file).
1454     unless (defined  $myData{_TOP_STREAM}) {
1455         $out_fh  = \*STDOUT  unless (defined $out_fh);
1456         $myData{_CUTTING}       = 1;   ## current "cutting" state
1457         $myData{_INPUT_STREAMS} = [];  ## stack of all input streams
1458     }
1459
1460     ## Initialize input indicators
1461     $myData{_OUTFILE} = '(unknown)'  unless (defined  $myData{_OUTFILE});
1462     $myData{_OUTPUT}  = $out_fh      if (defined  $out_fh);
1463     $in_fh            = \*STDIN      unless (defined  $in_fh);
1464     $myData{_INFILE}  = '(unknown)'  unless (defined  $myData{_INFILE});
1465     $myData{_INPUT}   = $in_fh;
1466     my $input_top     = $myData{_TOP_STREAM}
1467                       = new Pod::InputSource(
1468                             -name        => $myData{_INFILE},
1469                             -handle      => $in_fh,
1470                             -was_cutting => $myData{_CUTTING}
1471                         );
1472     local *input_stack = $myData{_INPUT_STREAMS};
1473     push(@input_stack, $input_top);
1474
1475     ## Perform beginning-of-document and/or beginning-of-input processing
1476     $self->begin_pod()  if (@input_stack == 1);
1477     $self->begin_input();
1478
1479     return  $input_top;
1480 }
1481
1482 ##---------------------------------------------------------------------------
1483
1484 =begin _PRIVATE_
1485
1486 =head1 B<_pop_input_stream()>
1487
1488             $hashref = $parser->_pop_input_stream();
1489
1490 This takes no arguments. It will perform any necessary end-of-file or
1491 end-of-document processing and then pop the current input stream from
1492 the top of the input stack.
1493
1494 The value returned will be reference to the hash-table that represents
1495 the new top of the input stream stack.
1496
1497 =end _PRIVATE_
1498
1499 =cut
1500
1501 sub _pop_input_stream {
1502     my ($self) = @_;
1503     local *myData = $self;
1504     local *input_stack = $myData{_INPUT_STREAMS};
1505
1506     ## Perform end-of-input and/or end-of-document processing
1507     $self->end_input()  if (@input_stack > 0);
1508     $self->end_pod()    if (@input_stack == 1);
1509
1510     ## Restore cutting state to whatever it was before we started
1511     ## parsing this file.
1512     my $old_top = pop(@input_stack);
1513     $myData{_CUTTING} = $old_top->was_cutting();
1514
1515     ## Dont forget to reset the input indicators
1516     my $input_top = undef;
1517     if (@input_stack > 0) {
1518        $input_top = $myData{_TOP_STREAM} = $input_stack[-1];
1519        $myData{_INFILE}  = $input_top->name();
1520        $myData{_INPUT}   = $input_top->handle();
1521     } else {
1522        delete $myData{_TOP_STREAM};
1523        delete $myData{_INPUT_STREAMS};
1524     }
1525
1526     return  $input_top;
1527 }
1528
1529 #############################################################################
1530
1531 =head1 TREE-BASED PARSING
1532
1533 If straightforward stream-based parsing wont meet your needs (as is
1534 likely the case for tasks such as translating PODs into structured
1535 markup languages like HTML and XML) then you may need to take the
1536 tree-based approach. Rather than doing everything in one pass and
1537 calling the B<interpolate()> method to expand sequences into text, it
1538 may be desirable to instead create a parse-tree using the B<parse_text()>
1539 method to return a tree-like structure which may contain an ordered list
1540 list of children (each of which may be a text-string, or a similar
1541 tree-like structure).
1542
1543 Pay special attention to L<"METHODS FOR PARSING AND PROCESSING"> and
1544 to the objects described in L<Pod::InputObjects>. The former describes
1545 the gory details and parameters for how to customize and extend the
1546 parsing behavior of B<Pod::Parser>. B<Pod::InputObjects> provides
1547 several objects that may all be used interchangeably as parse-trees. The
1548 most obvious one is the B<Pod::ParseTree> object. It defines the basic
1549 interface and functionality that all things trying to be a POD parse-tree
1550 should do. A B<Pod::ParseTree> is defined such that each "node" may be a
1551 text-string, or a reference to another parse-tree.  Each B<Pod::Paragraph>
1552 object and each B<Pod::InteriorSequence> object also supports the basic
1553 parse-tree interface.
1554
1555 The B<parse_text()> method takes a given paragraph of text, and
1556 returns a parse-tree that contains one or more children, each of which
1557 may be a text-string, or an InteriorSequence object. There are also
1558 callback-options that may be passed to B<parse_text()> to customize
1559 the way it expands or transforms interior-sequences, as well as the
1560 returned result. These callbacks can be used to create a parse-tree
1561 with custom-made objects (which may or may not support the parse-tree
1562 interface, depending on how you choose to do it).
1563
1564 If you wish to turn an entire POD document into a parse-tree, that process
1565 is fairly straightforward. The B<parse_text()> method is the key to doing
1566 this successfully. Every paragraph-callback (i.e. the polymorphic methods
1567 for B<command()>, B<verbatim()>, and B<textblock()> paragraphs) takes
1568 a B<Pod::Paragraph> object as an argument. Each paragraph object has a
1569 B<parse_tree()> method that can be used to get or set a corresponding
1570 parse-tree. So for each of those paragraph-callback methods, simply call
1571 B<parse_text()> with the options you desire, and then use the returned
1572 parse-tree to assign to the given paragraph object.
1573
1574 That gives you a parse-tree for each paragraph - so now all you need is
1575 an ordered list of paragraphs. You can maintain that yourself as a data
1576 element in the object/hash. The most straightforward way would be simply
1577 to use an array-ref, with the desired set of custom "options" for each
1578 invocation of B<parse_text>. Let's assume the desired option-set is
1579 given by the hash C<%options>. Then we might do something like the
1580 following:
1581
1582     package MyPodParserTree;
1583
1584     @ISA = qw( Pod::Parser );
1585
1586     ...
1587
1588     sub begin_pod {
1589         my $self = shift;
1590         $self->{'-paragraphs'} = [];  ## initialize paragraph list
1591     }
1592
1593     sub command { 
1594         my ($parser, $command, $paragraph, $line_num, $pod_para) = @_;
1595         my $ptree = $parser->parse_text({%options}, $paragraph, ...);
1596         $pod_para->parse_tree( $ptree );
1597         push @{ $self->{'-paragraphs'} }, $pod_para;
1598     }
1599
1600     sub verbatim { 
1601         my ($parser, $paragraph, $line_num, $pod_para) = @_;
1602         push @{ $self->{'-paragraphs'} }, $pod_para;
1603     }
1604
1605     sub textblock { 
1606         my ($parser, $paragraph, $line_num, $pod_para) = @_;
1607         my $ptree = $parser->parse_text({%options}, $paragraph, ...);
1608         $pod_para->parse_tree( $ptree );
1609         push @{ $self->{'-paragraphs'} }, $pod_para;
1610     }
1611
1612     ...
1613
1614     package main;
1615     ...
1616     my $parser = new MyPodParserTree(...);
1617     $parser->parse_from_file(...);
1618     my $paragraphs_ref = $parser->{'-paragraphs'};
1619
1620 Of course, in this module-author's humble opinion, I'd be more inclined to
1621 use the existing B<Pod::ParseTree> object than a simple array. That way
1622 everything in it, paragraphs and sequences, all respond to the same core
1623 interface for all parse-tree nodes. The result would look something like:
1624
1625     package MyPodParserTree2;
1626
1627     ...
1628
1629     sub begin_pod {
1630         my $self = shift;
1631         $self->{'-ptree'} = new Pod::ParseTree;  ## initialize parse-tree
1632     }
1633
1634     sub parse_tree {
1635         ## convenience method to get/set the parse-tree for the entire POD
1636         (@_ > 1)  and  $_[0]->{'-ptree'} = $_[1];
1637         return $_[0]->{'-ptree'};
1638     }
1639
1640     sub command { 
1641         my ($parser, $command, $paragraph, $line_num, $pod_para) = @_;
1642         my $ptree = $parser->parse_text({<<options>>}, $paragraph, ...);
1643         $pod_para->parse_tree( $ptree );
1644         $parser->parse_tree()->append( $pod_para );
1645     }
1646
1647     sub verbatim { 
1648         my ($parser, $paragraph, $line_num, $pod_para) = @_;
1649         $parser->parse_tree()->append( $pod_para );
1650     }
1651
1652     sub textblock { 
1653         my ($parser, $paragraph, $line_num, $pod_para) = @_;
1654         my $ptree = $parser->parse_text({<<options>>}, $paragraph, ...);
1655         $pod_para->parse_tree( $ptree );
1656         $parser->parse_tree()->append( $pod_para );
1657     }
1658
1659     ...
1660
1661     package main;
1662     ...
1663     my $parser = new MyPodParserTree2(...);
1664     $parser->parse_from_file(...);
1665     my $ptree = $parser->parse_tree;
1666     ...
1667
1668 Now you have the entire POD document as one great big parse-tree. You
1669 can even use the B<-expand_seq> option to B<parse_text> to insert
1670 whole different kinds of objects. Just don't expect B<Pod::Parser>
1671 to know what to do with them after that. That will need to be in your
1672 code. Or, alternatively, you can insert any object you like so long as
1673 it conforms to the B<Pod::ParseTree> interface.
1674
1675 One could use this to create subclasses of B<Pod::Paragraphs> and
1676 B<Pod::InteriorSequences> for specific commands (or to create your own
1677 custom node-types in the parse-tree) and add some kind of B<emit()>
1678 method to each custom node/subclass object in the tree. Then all you'd
1679 need to do is recursively walk the tree in the desired order, processing
1680 the children (most likely from left to right) by formatting them if
1681 they are text-strings, or by calling their B<emit()> method if they
1682 are objects/references.
1683
1684 =head1 SEE ALSO
1685
1686 L<Pod::InputObjects>, L<Pod::Select>
1687
1688 B<Pod::InputObjects> defines POD input objects corresponding to
1689 command paragraphs, parse-trees, and interior-sequences.
1690
1691 B<Pod::Select> is a subclass of B<Pod::Parser> which provides the ability
1692 to selectively include and/or exclude sections of a POD document from being
1693 translated based upon the current heading, subheading, subsubheading, etc.
1694
1695 =for __PRIVATE__
1696 B<Pod::Callbacks> is a subclass of B<Pod::Parser> which gives its users
1697 the ability the employ I<callback functions> instead of, or in addition
1698 to, overriding methods of the base class.
1699
1700 =for __PRIVATE__
1701 B<Pod::Select> and B<Pod::Callbacks> do not override any
1702 methods nor do they define any new methods with the same name. Because
1703 of this, they may I<both> be used (in combination) as a base class of
1704 the same subclass in order to combine their functionality without
1705 causing any namespace clashes due to multiple inheritance.
1706
1707 =head1 AUTHOR
1708
1709 Brad Appleton E<lt>bradapp@enteract.comE<gt>
1710
1711 Based on code for B<Pod::Text> written by
1712 Tom Christiansen E<lt>tchrist@mox.perl.comE<gt>
1713
1714 =cut
1715
1716 1;