This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
remove FileHandle from list of PodParser dependencies (the
[perl5.git] / lib / Pod / Parser.pm
CommitLineData
360aca43
GS
1#############################################################################
2# Pod/Parser.pm -- package which defines a base class for parsing POD docs.
3#
664bb207 4# Copyright (C) 1996-1999 by Bradford Appleton. All rights reserved.
360aca43
GS
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
10package Pod::Parser;
11
12use vars qw($VERSION);
664bb207 13$VERSION = 1.085; ## Current version of this package
360aca43
GS
14require 5.004; ## requires this Perl version or later
15
16#############################################################################
17
18=head1 NAME
19
20Pod::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
475d79b5 74perl5.004, Pod::InputObjects, Exporter, Carp
360aca43
GS
75
76=head1 EXPORTS
77
78Nothing.
79
80=head1 DESCRIPTION
81
82B<Pod::Parser> is a base class for creating POD filters and translators.
83It handles most of the effort involved with parsing the POD sections
84from an input stream, leaving subclasses free to be concerned only with
85performing the actual translation of text.
86
87B<Pod::Parser> parses PODs, and makes method calls to handle the various
88components of the POD. Subclasses of B<Pod::Parser> override these methods
89to translate the POD into whatever output format they desire.
90
91=head1 QUICK OVERVIEW
92
93To create a POD filter for translating POD documentation into some other
94format, you create a subclass of B<Pod::Parser> which typically overrides
95just the base class implementation for the following methods:
96
97=over 2
98
99=item *
100
101B<command()>
102
103=item *
104
105B<verbatim()>
106
107=item *
108
109B<textblock()>
110
111=item *
112
113B<interior_sequence()>
114
115=back
116
117You may also want to override the B<begin_input()> and B<end_input()>
118methods for your subclass (to perform any needed per-file and/or
119per-document initialization or cleanup).
120
121If you need to perform any preprocesssing of input before it is parsed
122you may want to override one or more of B<preprocess_line()> and/or
123B<preprocess_paragraph()>.
124
125Sometimes it may be necessary to make more than one pass over the input
126files. If this is the case you have several options. You can make the
127first pass using B<Pod::Parser> and override your methods to store the
128intermediate results in memory somewhere for the B<end_pod()> method to
129process. You could use B<Pod::Parser> for several passes with an
130appropriate state variable to control the operation for each pass. If
131your input source can't be reset to start at the beginning, you can
132store it in some other structure as a string or an array and have that
133structure implement a B<getline()> method (which is all that
134B<parse_from_filehandle()> uses to read input).
135
136Feel free to add any member data fields you need to keep track of things
137like current font, indentation, horizontal or vertical position, or
138whatever else you like. Be sure to read L<"PRIVATE METHODS AND DATA">
139to avoid name collisions.
140
141For the most part, the B<Pod::Parser> base class should be able to
142do most of the input parsing for you and leave you free to worry about
143how to intepret the commands and translate the result.
144
664bb207
GS
145Note that all we have described here in this quick overview overview is
146the simplest most striaghtforward use of B<Pod::Parser> to do stream-based
147parsing. It is also possible to use the B<Pod::Parser::parse_text> function
148to do more sophisticated tree-based parsing. See L<"TREE-BASED PARSING">.
149
150=head1 PARSING OPTIONS
151
152A I<parse-option> is simply a named option of B<Pod::Parser> with a
153value that corresponds to a certain specified behavior. These various
154behaviors of B<Pod::Parser> may be enabled/disabled by setting or
155or unsetting one or more I<parse-options> using the B<parseopts()> method.
156The set of currently accepted parse-options is as follows:
157
158=over 3
159
160=item B<-want_nonPODs> (default: unset)
161
162Normally (by default) B<Pod::Parser> will only provide access to
163the POD sections of the input. Input paragraphs that are not part
164of the POD-format documentation are not made available to the caller
165(not even using B<preprocess_paragraph()>). Setting this option to a
166non-empty, non-zero value will allow B<preprocess_paragraph()> to see
167non-POD sectioins of the input as well as POD sections. The B<cutting()>
168method can be used to determine if the corresponding paragraph is a POD
169paragraph, or some other input paragraph.
170
171=item B<-process_cut_cmd> (default: unset)
172
173Normally (by default) B<Pod::Parser> handles the C<=cut> POD directive
174by itself and does not pass it on to the caller for processing. Setting
175this option to non-empty, non-zero value will cause B<Pod::Parser> to
176pass 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
179B<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
181to capture the actual C<=cut> paragraph itself for whatever purpose
182it desires.
183
184=back
185
186Please see L<"parseopts()"> for a complete description of the interface
187for the setting and unsetting of parse-options.
188
360aca43
GS
189=cut
190
191#############################################################################
192
193use vars qw(@ISA);
194use strict;
195#use diagnostics;
196use Pod::InputObjects;
197use Carp;
360aca43
GS
198use Exporter;
199@ISA = qw(Exporter);
200
201## These "variables" are used as local "glob aliases" for performance
664bb207 202use vars qw(%myData %myOpts @input_stack);
360aca43
GS
203
204#############################################################################
205
206=head1 RECOMMENDED SUBROUTINE/METHOD OVERRIDES
207
208B<Pod::Parser> provides several methods which most subclasses will probably
209want 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
219This method should be overridden by subclasses to take the appropriate
220action when a POD command paragraph (denoted by a line beginning with
221"=") is encountered. When such a POD directive is seen in the input,
222this method is called and is passed:
223
224=over 3
225
226=item C<$cmd>
227
228the name of the command for this POD paragraph
229
230=item C<$text>
231
232the paragraph text for the given POD paragraph command.
233
234=item C<$line_num>
235
236the line-number of the beginning of the paragraph
237
238=item C<$pod_para>
239
240a reference to a C<Pod::Paragraph> object which contains further
241information about the paragraph command (see L<Pod::InputObjects>
242for details).
243
244=back
245
246B<Note> that this method I<is> called for C<=pod> paragraphs.
247
248The base class implementation of this method simply treats the raw POD
249command as normal block of paragraph text (invoking the B<textblock()>
250method with the command paragraph).
251
252=cut
253
254sub 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
266This method may be overridden by subclasses to take the appropriate
267action when a block of verbatim text is encountered. It is passed the
268following parameters:
269
270=over 3
271
272=item C<$text>
273
274the block of text for the verbatim paragraph
275
276=item C<$line_num>
277
278the line-number of the beginning of the paragraph
279
280=item C<$pod_para>
281
282a reference to a C<Pod::Paragraph> object which contains further
283information about the paragraph (see L<Pod::InputObjects>
284for details).
285
286=back
287
288The base class implementation of this method simply prints the textblock
289(unmodified) to the output filehandle.
290
291=cut
292
293sub 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
305This method may be overridden by subclasses to take the appropriate
306action when a normal block of POD text is encountered (although the base
307class method will usually do what you want). It is passed the following
308parameters:
309
310=over 3
311
312=item C<$text>
313
314the block of text for the a POD paragraph
315
316=item C<$line_num>
317
318the line-number of the beginning of the paragraph
319
320=item C<$pod_para>
321
322a reference to a C<Pod::Paragraph> object which contains further
323information about the paragraph (see L<Pod::InputObjects>
324for details).
325
326=back
327
328In order to process interior sequences, subclasses implementations of
329this method will probably want to invoke either B<interpolate()> or
330B<parse_text()>, passing it the text block C<$text>, and the corresponding
331line number in C<$line_num>, and then perform any desired processing upon
332the returned result.
333
334The base class implementation of this method simply prints the text block
335as it occurred in the input stream).
336
337=cut
338
339sub 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
351This method should be overridden by subclasses to take the appropriate
352action when an interior sequence is encountered. An interior sequence is
353an embedded command within a block of text which appears as a command
354name (usually a single uppercase character) followed immediately by a
355string of text which is enclosed in angle brackets. This method is
356passed the sequence command C<$seq_cmd> and the corresponding text
357C<$seq_arg>. It is invoked by the B<interpolate()> method for each interior
358sequence that occurs in the string that it is passed. It should return
359the desired text string to be used in place of the interior sequence.
360The C<$pod_seq> argument is a reference to a C<Pod::InteriorSequence>
361object which contains further information about the interior sequence.
362Please see L<Pod::InputObjects> for details if you need to access this
363additional information.
364
365Subclass implementations of this method may wish to invoke the
366B<nested()> method of C<$pod_seq> to see if it is nested inside
367some other interior-sequence (and if so, which kind).
368
369The base class implementation of the B<interior_sequence()> method
370simply returns the raw text of the interior sequence (as it occurred
371in the input) to the caller.
372
373=cut
374
375sub 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
385B<Pod::Parser> provides several methods which subclasses may want to override
386to perform any special pre/post-processing. These methods do I<not> have to
387be 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
397This is the constructor for B<Pod::Parser> and its subclasses. You
398I<do not> need to override this method! It is capable of constructing
399subclass objects as well as base class objects, provided you use
400any of the following constructor invocation styles:
401
402 my $parser1 = MyParser->new();
403 my $parser2 = new MyParser();
404 my $parser3 = $parser2->new();
405
406where C<MyParser> is some subclass of B<Pod::Parser>.
407
408Using the syntax C<MyParser::new()> to invoke the constructor is I<not>
409recommended, but if you insist on being able to do this, then the
410subclass I<will> need to override the B<new()> constructor method. If
411you do override the constructor, you I<must> be sure to invoke the
412B<initialize()> method of the newly blessed object.
413
414Using any of the above invocations, the first argument to the
415constructor is always the corresponding package name (or object
416reference). No other arguments are required, but if desired, an
417associative array (or hash-table) my be passed to the B<new()>
418constructor, as in:
419
420 my $parser1 = MyParser->new( MYDATA => $value1, MOREDATA => $value2 );
421 my $parser2 = new MyParser( -myflag => 1 );
422
423All arguments passed to the B<new()> constructor will be treated as
424key/value pairs in a hash-table. The newly constructed object will be
425initialized by copying the contents of the given hash-table (which may
426have been empty). The B<new()> constructor for this class and all of its
427subclasses returns a blessed reference to the initialized object (hash-table).
428
429=cut
430
431sub 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
451This method performs any necessary object initialization. It takes no
452arguments (other than the object instance of course, which is typically
453copied to a local variable named C<$self>). If subclasses override this
454method then they I<must> be sure to invoke C<$self-E<gt>SUPER::initialize()>.
455
456=cut
457
458sub initialize {
459 #my $self = shift;
460 #return;
461}
462
463##---------------------------------------------------------------------------
464
465=head1 B<begin_pod()>
466
467 $parser->begin_pod();
468
469This method is invoked at the beginning of processing for each POD
470document that is encountered in the input. Subclasses should override
471this method to perform any per-document initialization.
472
473=cut
474
475sub begin_pod {
476 #my $self = shift;
477 #return;
478}
479
480##---------------------------------------------------------------------------
481
482=head1 B<begin_input()>
483
484 $parser->begin_input();
485
486This method is invoked by B<parse_from_filehandle()> immediately I<before>
487processing input from a filehandle. The base class implementation does
488nothing, however, subclasses may override it to perform any per-file
489initializations.
490
491Note that if multiple files are parsed for a single POD document
492(perhaps the result of some future C<=include> directive) this method
493is invoked for every file that is parsed. If you wish to perform certain
494initializations once per document, then you should use B<begin_pod()>.
495
496=cut
497
498sub begin_input {
499 #my $self = shift;
500 #return;
501}
502
503##---------------------------------------------------------------------------
504
505=head1 B<end_input()>
506
507 $parser->end_input();
508
509This method is invoked by B<parse_from_filehandle()> immediately I<after>
510processing input from a filehandle. The base class implementation does
511nothing, however, subclasses may override it to perform any per-file
512cleanup actions.
513
514Please 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
516is invoked for every file that is parsed. If you wish to perform certain
517cleanup actions once per document, then you should use B<end_pod()>.
518
519=cut
520
521sub end_input {
522 #my $self = shift;
523 #return;
524}
525
526##---------------------------------------------------------------------------
527
528=head1 B<end_pod()>
529
530 $parser->end_pod();
531
532This method is invoked at the end of processing for each POD document
533that is encountered in the input. Subclasses should override this method
534to perform any per-document finalization.
535
536=cut
537
538sub 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
549This method should be overridden by subclasses that wish to perform
550any kind of preprocessing for each I<line> of input (I<before> it has
551been determined whether or not it is part of a POD paragraph). The
552parameter C<$text> is the input line; and the parameter C<$line_num> is
553the line number of the corresponding text line.
554
555The value returned should correspond to the new text to use in its
556place. If the empty string or an undefined value is returned then no
557further processing will be performed for this line.
558
559Please note that the B<preprocess_line()> method is invoked I<before>
560the B<preprocess_paragraph()> method. After all (possibly preprocessed)
561lines in a paragraph have been assembled together and it has been
562determined that the paragraph is part of the POD documentation from one
563of the selected sections, then B<preprocess_paragraph()> is invoked.
564
565The base class implementation of this method returns the given text.
566
567=cut
568
569sub 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
580This method should be overridden by subclasses that wish to perform any
581kind of preprocessing for each block (paragraph) of POD documentation
582that appears in the input stream. The parameter C<$text> is the POD
583paragraph from the input file; and the parameter C<$line_num> is the
584line number for the beginning of the corresponding paragraph.
585
586The value returned should correspond to the new text to use in its
587place If the empty string is returned or an undefined value is
588returned, then the given C<$text> is ignored (not processed).
589
590This method is invoked after gathering up all thelines in a paragraph
591but before trying to further parse or interpret them. After
592B<preprocess_paragraph()> returns, the current cutting state (which
593is returned by C<$self-E<gt>cutting()>) is examined. If it evaluates
594to false then input text (including the given C<$text>) is cut (not
595processed) until the next POD directive is encountered.
596
597Please note that the B<preprocess_line()> method is invoked I<before>
598the B<preprocess_paragraph()> method. After all (possibly preprocessed)
599lines in a paragraph have been assembled together and it has been
600determined that the paragraph is part of the POD documentation from one
601of the selected sections, then B<preprocess_paragraph()> is invoked.
602
603The base class implementation of this method returns the given text.
604
605=cut
606
607sub preprocess_paragraph {
608 my ($self, $text, $line_num) = @_;
609 return $text;
610}
611
612#############################################################################
613
614=head1 METHODS FOR PARSING AND PROCESSING
615
616B<Pod::Parser> provides several methods to process input text. These
664bb207
GS
617methods typically won't need to be overridden (and in some cases they
618can't be overridden), but subclasses may want to invoke them to exploit
619their functionality.
360aca43
GS
620
621=cut
622
623##---------------------------------------------------------------------------
624
625=head1 B<parse_text()>
626
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);
630
631This method is useful if you need to perform your own interpolation
632of interior sequences and can't rely upon B<interpolate> to expand
633them in simple bottom-up order order.
634
635The parameter C<$text> is a string or block of text to be parsed
636for interior sequences; and the parameter C<$line_num> is the
637line number curresponding to the beginning of C<$text>.
638
639B<parse_text()> will parse the given text into a parse-tree of "nodes."
640and interior-sequences. Each "node" in the parse tree is either a
641text-string, or a B<Pod::InteriorSequence>. The result returned is a
642parse-tree of type B<Pod::ParseTree>. Please see L<Pod::InputObjects>
643for more information about B<Pod::InteriorSequence> and B<Pod::ParseTree>.
644
645If desired, an optional hash-ref may be specified as the first argument
646to customize certain aspects of the parse-tree that is created and
647returned. The set of recognized option keywords are:
648
649=over 3
650
651=item B<-expand_seq> =E<gt> I<code-ref>|I<method-name>
652
653Normally, the parse-tree returned by B<parse_text()> will contain an
654unexpanded C<Pod::InteriorSequence> object for each interior-sequence
655encountered. Specifying B<-expand_seq> tells B<parse_text()> to "expand"
656every interior-sequence it sees by invoking the referenced function
657(or named method of the parser object) and using the return value as the
658expanded result.
659
660If a subroutine reference was given, it is invoked as:
661
662 &$code_ref( $parser, $sequence )
663
664and if a method-name was given, it is invoked as:
665
666 $parser->method_name( $sequence )
667
668where C<$parser> is a reference to the parser object, and C<$sequence>
669is a reference to the interior-sequence object.
670[I<NOTE>: If the B<interior_sequence()> method is specified, then it is
671invoked according to the interface specified in L<"interior_sequence()">].
672
664bb207
GS
673=item B<-expand_text> =E<gt> I<code-ref>|I<method-name>
674
675Normally, the parse-tree returned by B<parse_text()> will contain a
676text-string for each contiguous sequence of characters outside of an
677interior-sequence. Specifying B<-expand_text> tells B<parse_text()> to
678"preprocess" every such text-string it sees by invoking the referenced
679function (or named method of the parser object) and using the return value
680as the preprocessed (or "expanded") result. [Note that if the result is
681an interior-sequence, then it will I<not> be expanded as specified by the
682B<-expand_seq> option; Any such recursive expansion needs to be handled by
683the specified callback routine.]
684
685If a subroutine reference was given, it is invoked as:
686
687 &$code_ref( $parser, $text, $ptree_node )
688
689and if a method-name was given, it is invoked as:
690
691 $parser->method_name( $text, $ptree_node )
692
693where C<$parser> is a reference to the parser object, C<$text> is the
694text-string encountered, and C<$ptree_node> is a reference to the current
695node in the parse-tree (usually an interior-sequence object or else the
696top-level node of the parse-tree).
697
360aca43
GS
698=item B<-expand_ptree> =E<gt> I<code-ref>|I<method-name>
699
700Rather than returning a C<Pod::ParseTree>, pass the parse-tree as an
701argument to the referenced subroutine (or named method of the parser
702object) and return the result instead of the parse-tree object.
703
704If a subroutine reference was given, it is invoked as:
705
706 &$code_ref( $parser, $ptree )
707
708and if a method-name was given, it is invoked as:
709
710 $parser->method_name( $ptree )
711
712where C<$parser> is a reference to the parser object, and C<$ptree>
713is a reference to the parse-tree object.
714
715=back
716
717=cut
718
719## This global regex is used to see if the text before a '>' inside
22641bdf 720## an interior sequence looks like '-' or '=', but not '--', '==',
664bb207 721## '!=', '$-', '$=' or <<op>>=
360aca43 722use vars qw( $ARROW_RE );
664bb207
GS
723$ARROW_RE = join('', qw{ (?: [^-+*/=!&|%^x.<>$]= | [^-$]- )$ });
724#$ARROW_RE = qr/(?:[^-+*/=!&|%^x.<>$]+=|[^-$]+-)$/; ## 5.005+ only!
360aca43
GS
725
726sub parse_text {
727 my $self = shift;
728 local $_ = '';
729
730 ## Get options and set any defaults
731 my %opts = (ref $_[0]) ? %{ shift() } : ();
732 my $expand_seq = $opts{'-expand_seq'} || undef;
664bb207 733 my $expand_text = $opts{'-expand_text'} || undef;
360aca43
GS
734 my $expand_ptree = $opts{'-expand_ptree'} || undef;
735
736 my $text = shift;
737 my $line = shift;
738 my $file = $self->input_file();
739 my ($cmd, $prev) = ('', '');
740
741 ## Convert method calls into closures, for our convenience
742 my $xseq_sub = $expand_seq;
664bb207 743 my $xtext_sub = $expand_text;
360aca43 744 my $xptree_sub = $expand_ptree;
e9fdc7d2 745 if (defined $expand_seq and $expand_seq eq 'interior_sequence') {
360aca43
GS
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.
749 $xseq_sub = sub {
750 my ($self, $iseq) = @_;
751 my $args = join("", $iseq->parse_tree->children);
752 return $self->interior_sequence($iseq->name, $args, $iseq);
753 };
754 }
755 ref $xseq_sub or $xseq_sub = sub { shift()->$expand_seq(@_) };
664bb207 756 ref $xtext_sub or $xtext_sub = sub { shift()->$expand_text(@_) };
360aca43
GS
757 ref $xptree_sub or $xptree_sub = sub { shift()->$expand_ptree(@_) };
758
759 ## Keep track of the "current" interior sequence, and maintain a stack
760 ## of "in progress" sequences.
761 ##
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!
767 ##
768 my $seq = Pod::ParseTree->new();
769 my @seq_stack = ($seq);
770
771 ## Iterate over all sequence starts/stops, newlines, & text
772 ## (NOTE: split with capturing parens keeps the delimiters)
773 $_ = $text;
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])(<)$/ ) {
e9fdc7d2 779 ## Push a new sequence onto the stack of those "in-progress"
360aca43
GS
780 $seq = Pod::InteriorSequence->new(
781 -name => ($cmd = $1),
782 -ldelim => $2, -rdelim => '',
783 -file => $file, -line => $line
784 );
785 (@seq_stack > 1) and $seq->nested($seq_stack[-1]);
786 push @seq_stack, $seq;
787 }
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) )
791 {
792 ## End of current sequence, record terminating delimiter
793 $seq->rdelim($_);
794 ## Pop it off the stack of "in progress" sequences
795 pop @seq_stack;
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 : '';
800 }
664bb207
GS
801 elsif (length) {
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) : $_);
360aca43
GS
805 }
806 ## Remember the "current" sequence and the previously seen token
807 ($seq, $prev) = ( $seq_stack[-1], $_ );
808 }
809
810 ## Handle unterminated sequences
664bb207 811 my $errorsub = (@seq_stack > 1) ? $self->errorsub() : undef;
360aca43
GS
812 while (@seq_stack > 1) {
813 ($cmd, $file, $line) = ($seq->name, $seq->file_line);
814 pop @seq_stack;
664bb207
GS
815 my $errmsg = "** Unterminated $cmd<...> at $file line $line\n";
816 (ref $errorsub) and &{$errorsub}($errmsg)
f5daac4a 817 or (defined $errorsub) and $self->$errorsub($errmsg)
664bb207 818 or warn($errmsg);
360aca43
GS
819 $seq_stack[-1]->append($expand_seq ? &$xseq_sub($self,$seq) : $seq);
820 $seq = $seq_stack[-1];
821 }
822
823 ## Return the resulting parse-tree
824 my $ptree = (pop @seq_stack)->parse_tree;
825 return $expand_ptree ? &$xptree_sub($self, $ptree) : $ptree;
826}
827
828##---------------------------------------------------------------------------
829
830=head1 B<interpolate()>
831
832 $textblock = $parser->interpolate($text, $line_num);
833
834This method translates all text (including any embedded interior sequences)
835in the given text string C<$text> and returns the interpolated result. The
836parameter C<$line_num> is the line number corresponding to the beginning
837of C<$text>.
838
839B<interpolate()> merely invokes a private method to recursively expand
840nested interior sequences in bottom-up order (innermost sequences are
841expanded first). If there is a need to expand nested sequences in
842some alternate order, use B<parse_text> instead.
843
844=cut
845
846sub interpolate {
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();
851}
852
853##---------------------------------------------------------------------------
854
855=begin __PRIVATE__
856
857=head1 B<parse_paragraph()>
858
859 $parser->parse_paragraph($text, $line_num);
860
861This method takes the text of a POD paragraph to be processed, along
862with its corresponding line number, and invokes the appropriate method
863(one of B<command()>, B<verbatim()>, or B<textblock()>).
864
664bb207
GS
865For performance reasons, this method is invoked directly without any
866dynamic lookup; Hence subclasses may I<not> override it!
360aca43
GS
867
868=end __PRIVATE__
869
870=cut
871
872sub parse_paragraph {
873 my ($self, $text, $line_num) = @_;
664bb207
GS
874 local *myData = $self; ## alias to avoid deref-ing overhead
875 local *myOpts = ($myData{_PARSEOPTS} ||= {}); ## get parse-options
360aca43
GS
876 local $_;
877
664bb207
GS
878 ## See if we want to preprocess nonPOD paragraphs as well as POD ones.
879 my $wantNonPods = $myOpts{'-want_nonPODs'} || 0;
880
881 ## Perform any desired preprocessing if we wanted it this early
882 $wantNonPods and $text = $self->preprocess_paragraph($text, $line_num);
883
360aca43
GS
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;
889 }
890
891 ## Now we know this is block of text in a POD section!
892
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 ##-----------------------------------------------------------------
901
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);
905 }
906
664bb207
GS
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});
913 }
360aca43
GS
914
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
922 $pfx = $1;
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.
928 if ($cmd eq 'cut') {
929 $myData{_CUTTING} = 1;
664bb207 930 return unless $myOpts{'-process_cut_cmd'};
360aca43
GS
931 }
932 }
933 ## Save the attributes indicating how the command was specified.
934 $pod_para = new Pod::Paragraph(
935 -name => $cmd,
936 -text => $text,
937 -prefix => $pfx,
938 -separator => $sep,
939 -file => $myData{_INFILE},
940 -line => $line_num
941 );
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);
948 # }
949 if (length $cmd) {
950 ## A command paragraph
951 $self->command($cmd, $text, $line_num, $pod_para);
952 }
953 elsif ($text =~ /^\s+/) {
954 ## Indented text - must be a verbatim paragraph
955 $self->verbatim($text, $line_num, $pod_para);
956 }
957 else {
958 ## Looks like an ordinary block of text
959 $self->textblock($text, $line_num, $pod_para);
960 }
961 return 1;
962}
963
964##---------------------------------------------------------------------------
965
966=head1 B<parse_from_filehandle()>
967
968 $parser->parse_from_filehandle($in_fh,$out_fh);
969
970This method takes an input filehandle (which is assumed to already be
971opened for reading) and reads the entire input stream looking for blocks
972(paragraphs) of POD documentation to be processed. If no first argument
973is given the default input filehandle C<STDIN> is used.
974
975The C<$in_fh> parameter may be any object that provides a B<getline()>
976method to retrieve a single line of input text (hence, an appropriate
977wrapper object could be used to parse PODs from a single string or an
978array of strings).
979
980Using C<$in_fh-E<gt>getline()>, input is read line-by-line and assembled
981into paragraphs or "blocks" (which are separated by lines containing
982nothing but whitespace). For each block of POD documentation
983encountered it will invoke a method to parse the given paragraph.
984
985If a second argument is given then it should correspond to a filehandle where
986output should be sent (otherwise the default output filehandle is
987C<STDOUT> if no output filehandle is currently in use).
988
989B<NOTE:> For performance reasons, this method caches the input stream at
990the top of the stack in a local variable. Any attempts by clients to
991change the stack contents during processing when in the midst executing
992of this method I<will not affect> the input stream used by the current
993invocation of this method.
994
995This method does I<not> usually need to be overridden by subclasses.
996
997=cut
998
999sub parse_from_filehandle {
1000 my $self = shift;
1001 my %opts = (ref $_[0] eq 'HASH') ? %{ shift() } : ();
1002 my ($in_fh, $out_fh) = @_;
22641bdf 1003 $in_fh = \*STDIN unless ($in_fh);
360aca43
GS
1004 local $_;
1005
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} );
1010
1011 ## Initialize line/paragraph
1012 my ($textline, $paragraph) = ('', '');
1013 my ($nlines, $plines) = (0, 0);
1014
1015 ## Use <$fh> instead of $fh->getline where possible (for speed)
1016 $_ = ref $in_fh;
1017 my $tied_fh = (/^(?:GLOB|FileHandle|IO::\w+)$/ or tied $in_fh);
1018
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
1024
1025 if ((! length $paragraph) && ($textline =~ /^==/)) {
1026 ## '==' denotes a one-line command paragraph
1027 $paragraph = $textline;
1028 $plines = 1;
1029 $textline = '';
1030 } else {
1031 ## Append this line to the current paragraph
1032 $paragraph .= $textline;
1033 ++$plines;
1034 }
1035
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));
1039
1040 ## Now process the paragraph
1041 parse_paragraph($self, $paragraph, ($nlines - $plines) + 1);
1042 $paragraph = '';
1043 $plines = 0;
1044 }
1045 ## Dont forget about the last paragraph in the file
1046 if (length $paragraph) {
1047 parse_paragraph($self, $paragraph, ($nlines - $plines) + 1)
1048 }
1049
1050 ## Now pop the input stream off the top of the input stack.
1051 $self->_pop_input_stream();
1052}
1053
1054##---------------------------------------------------------------------------
1055
1056=head1 B<parse_from_file()>
1057
1058 $parser->parse_from_file($filename,$outfile);
1059
1060This method takes a filename and does the following:
1061
1062=over 2
1063
1064=item *
1065
1066opens the input and output files for reading
1067(creating the appropriate filehandles)
1068
1069=item *
1070
1071invokes the B<parse_from_filehandle()> method passing it the
1072corresponding input and output filehandles.
1073
1074=item *
1075
1076closes the input and output files.
1077
1078=back
1079
1080If the special input filename "-" or "<&STDIN" is given then the STDIN
1081filehandle is used for input (and no open or close is performed). If no
1082input filename is specified then "-" is implied.
1083
1084If a second argument is given then it should be the name of the desired
1085output file. If the special output filename "-" or ">&STDOUT" is given
1086then the STDOUT filehandle is used for output (and no open or close is
1087performed). If the special output filename ">&STDERR" is given then the
1088STDERR filehandle is used for output (and no open or close is
1089performed). If no output filehandle is currently in use and no output
1090filename is specified, then "-" is implied.
1091
1092This method does I<not> usually need to be overridden by subclasses.
1093
1094=cut
1095
1096sub parse_from_file {
1097 my $self = shift;
1098 my %opts = (ref $_[0] eq 'HASH') ? %{ shift() } : ();
1099 my ($infile, $outfile) = @_;
475d79b5 1100 my ($in_fh, $out_fh);
360aca43
GS
1101 my ($close_input, $close_output) = (0, 0);
1102 local *myData = $self;
1103 local $_;
1104
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>";
1110 $in_fh = \*STDIN;
1111 }
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};
1116 $in_fh = $infile;
1117 }
1118 else {
1119 ## We have a filename, open it for reading
1120 $myData{_INFILE} = $infile;
475d79b5 1121 open($in_fh, "< $infile") or
360aca43
GS
1122 croak "Can't open $infile for reading: $!\n";
1123 $close_input = 1;
1124 }
1125
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
1130 ## already
1131 ##
1132 unless ((defined $outfile) && (length $outfile)) {
1133 (defined $myData{_TOP_STREAM}) && ($out_fh = $myData{_OUTPUT})
1134 || ($outfile = '-');
1135 }
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>";
1141 $out_fh = \*STDOUT;
1142 }
1143 elsif ($outfile =~ /^>&(STDERR|2)$/i) {
1144 ## Not a filename, just a string implying STDERR
1145 $myData{_OUTFILE} = "<standard error>";
1146 $out_fh = \*STDERR;
1147 }
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};;
1152 $out_fh = $outfile;
1153 }
1154 else {
1155 ## We have a filename, open it for writing
1156 $myData{_OUTFILE} = $outfile;
475d79b5 1157 open($out_fh, "> $outfile") or
360aca43
GS
1158 croak "Can't open $outfile for writing: $!\n";
1159 $close_output = 1;
1160 }
1161 }
1162
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);
1167
1168 $close_input and
1169 close($in_fh) || croak "Can't close $infile after reading: $!\n";
1170 $close_output and
1171 close($out_fh) || croak "Can't close $outfile after writing: $!\n";
1172}
1173
1174#############################################################################
1175
1176=head1 ACCESSOR METHODS
1177
1178Clients of B<Pod::Parser> should use the following methods to access
1179instance data fields:
1180
1181=cut
1182
1183##---------------------------------------------------------------------------
1184
664bb207
GS
1185=head1 B<errorsub()>
1186
1187 $parser->errorsub("method_name");
1188 $parser->errorsub(\&warn_user);
1189 $parser->errorsub(sub { print STDERR, @_ });
1190
1191Specifies the method or subroutine to use when printing error messages
1192about POD syntax. The supplied method/subroutine I<must> return TRUE upon
1193successful printing of the message. If C<undef> is given, then the B<warn>
1194builtin is used to issue error messages (this is the default behavior).
1195
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)
1200 or warn($errmsg);
1201
1202Returns a method name, or else a reference to the user-supplied subroutine
1203used to print error messages. Returns C<undef> if the B<warn> builtin
1204is used to issue error messages (this is the default behavior).
1205
1206=cut
1207
1208sub errorsub {
1209 return (@_ > 1) ? ($_[0]->{_ERRORSUB} = $_[1]) : $_[0]->{_ERRORSUB};
1210}
1211
1212##---------------------------------------------------------------------------
1213
360aca43
GS
1214=head1 B<cutting()>
1215
1216 $boolean = $parser->cutting();
1217
1218Returns the current C<cutting> state: a boolean-valued scalar which
1219evaluates to true if text from the input file is currently being "cut"
1220(meaning it is I<not> considered part of the POD document).
1221
1222 $parser->cutting($boolean);
1223
1224Sets the current C<cutting> state to the given value and returns the
1225result.
1226
1227=cut
1228
1229sub cutting {
1230 return (@_ > 1) ? ($_[0]->{_CUTTING} = $_[1]) : $_[0]->{_CUTTING};
1231}
1232
1233##---------------------------------------------------------------------------
1234
664bb207
GS
1235##---------------------------------------------------------------------------
1236
1237=head1 B<parseopts()>
1238
1239When invoked with no additional arguments, B<parseopts> returns a hashtable
1240of all the current parsing options.
1241
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";
1245
1246When invoked using a single string, B<parseopts> treats the string as the
1247name of a parse-option and returns its corresponding value if it exists
1248(returns C<undef> if it doesn't).
1249
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";
1253
1254When invoked with multiple arguments, B<parseopts> treats them as
1255key/value pairs and the specified parse-option names are set to the
1256given values. Any unspecified parse-options are unaffected.
1257
1258 ## Set them back to the default
1259 $parser->parseopts(-process_cut_cmd => 0);
1260
1261When passed a single hash-ref, B<parseopts> uses that hash to completely
1262reset the existing parse-options, all previous parse-option values
1263are lost.
1264
1265 ## Reset all options to default
1266 $parser->parseopts( { } );
1267
1268See L<"PARSING OPTIONS"> for more for the name and meaning of each
1269parse-option currently recognized.
1270
1271=cut
1272
1273sub parseopts {
1274 local *myData = shift;
1275 local *myOpts = ($myData{_PARSEOPTS} ||= {});
1276 return %myOpts if (@_ == 0);
1277 if (@_ == 1) {
1278 local $_ = shift;
1279 return ref($_) ? $myData{_PARSEOPTS} = $_ : $myOpts{$_};
1280 }
1281 my @newOpts = (%myOpts, @_);
1282 $myData{_PARSEOPTS} = { @newOpts };
1283}
1284
1285##---------------------------------------------------------------------------
1286
360aca43
GS
1287=head1 B<output_file()>
1288
1289 $fname = $parser->output_file();
1290
1291Returns the name of the output file being written.
1292
1293=cut
1294
1295sub output_file {
1296 return $_[0]->{_OUTFILE};
1297}
1298
1299##---------------------------------------------------------------------------
1300
1301=head1 B<output_handle()>
1302
1303 $fhandle = $parser->output_handle();
1304
1305Returns the output filehandle object.
1306
1307=cut
1308
1309sub output_handle {
1310 return $_[0]->{_OUTPUT};
1311}
1312
1313##---------------------------------------------------------------------------
1314
1315=head1 B<input_file()>
1316
1317 $fname = $parser->input_file();
1318
1319Returns the name of the input file being read.
1320
1321=cut
1322
1323sub input_file {
1324 return $_[0]->{_INFILE};
1325}
1326
1327##---------------------------------------------------------------------------
1328
1329=head1 B<input_handle()>
1330
1331 $fhandle = $parser->input_handle();
1332
1333Returns the current input filehandle object.
1334
1335=cut
1336
1337sub input_handle {
1338 return $_[0]->{_INPUT};
1339}
1340
1341##---------------------------------------------------------------------------
1342
1343=begin __PRIVATE__
1344
1345=head1 B<input_streams()>
1346
1347 $listref = $parser->input_streams();
1348
1349Returns a reference to an array which corresponds to the stack of all
1350the input streams that are currently in the middle of being parsed.
1351
1352While parsing an input stream, it is possible to invoke
1353B<parse_from_file()> or B<parse_from_filehandle()> to parse a new input
1354stream and then return to parsing the previous input stream. Each input
1355stream to be parsed is pushed onto the end of this input stack
1356before any of its input is read. The input stream that is currently
1357being parsed is always at the end (or top) of the input stack. When an
1358input stream has been exhausted, it is popped off the end of the
1359input stack.
1360
1361Each element on this input stack is a reference to C<Pod::InputSource>
1362object. Please see L<Pod::InputObjects> for more details.
1363
1364This method might be invoked when printing diagnostic messages, for example,
1365to obtain the name and line number of the all input files that are currently
1366being processed.
1367
1368=end __PRIVATE__
1369
1370=cut
1371
1372sub input_streams {
1373 return $_[0]->{_INPUT_STREAMS};
1374}
1375
1376##---------------------------------------------------------------------------
1377
1378=begin __PRIVATE__
1379
1380=head1 B<top_stream()>
1381
1382 $hashref = $parser->top_stream();
1383
1384Returns a reference to the hash-table that represents the element
1385that is currently at the top (end) of the input stream stack
1386(see L<"input_streams()">). The return value will be the C<undef>
1387if the input stack is empty.
1388
1389This method might be used when printing diagnostic messages, for example,
1390to obtain the name and line number of the current input file.
1391
1392=end __PRIVATE__
1393
1394=cut
1395
1396sub top_stream {
1397 return $_[0]->{_TOP_STREAM} || undef;
1398}
1399
1400#############################################################################
1401
1402=head1 PRIVATE METHODS AND DATA
1403
1404B<Pod::Parser> makes use of several internal methods and data fields
1405which clients should not need to see or use. For the sake of avoiding
1406name collisions for client data and methods, these methods and fields
1407are briefly discussed here. Determined hackers may obtain further
1408information about them by reading the B<Pod::Parser> source code.
1409
1410Private data fields are stored in the hash-object whose reference is
1411returned by the B<new()> constructor for this class. The names of all
1412private methods and data-fields used by B<Pod::Parser> begin with a
1413prefix of "_" and match the regular expression C</^_\w+$/>.
1414
1415=cut
1416
1417##---------------------------------------------------------------------------
1418
1419=begin _PRIVATE_
1420
1421=head1 B<_push_input_stream()>
1422
1423 $hashref = $parser->_push_input_stream($in_fh,$out_fh);
1424
1425This method will push the given input stream on the input stack and
1426perform any necessary beginning-of-document or beginning-of-file
1427processing. The argument C<$in_fh> is the input stream filehandle to
1428push, and C<$out_fh> is the corresponding output filehandle to use (if
1429it is not given or is undefined, then the current output stream is used,
1430which defaults to standard output if it doesnt exist yet).
1431
1432The value returned will be reference to the hash-table that represents
1433the new top of the input stream stack. I<Please Note> that it is
1434possible for this method to use default values for the input and output
1435file handles. If this happens, you will need to look at the C<INPUT>
1436and C<OUTPUT> instance data members to determine their new values.
1437
1438=end _PRIVATE_
1439
1440=cut
1441
1442sub _push_input_stream {
1443 my ($self, $in_fh, $out_fh) = @_;
1444 local *myData = $self;
1445
1446 ## Initialize stuff for the entire document if this is *not*
1447 ## an included file.
1448 ##
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
1452 ## file).
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
1457 }
1458
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},
1468 -handle => $in_fh,
1469 -was_cutting => $myData{_CUTTING}
1470 );
1471 local *input_stack = $myData{_INPUT_STREAMS};
1472 push(@input_stack, $input_top);
1473
1474 ## Perform beginning-of-document and/or beginning-of-input processing
1475 $self->begin_pod() if (@input_stack == 1);
1476 $self->begin_input();
1477
1478 return $input_top;
1479}
1480
1481##---------------------------------------------------------------------------
1482
1483=begin _PRIVATE_
1484
1485=head1 B<_pop_input_stream()>
1486
1487 $hashref = $parser->_pop_input_stream();
1488
1489This takes no arguments. It will perform any necessary end-of-file or
1490end-of-document processing and then pop the current input stream from
1491the top of the input stack.
1492
1493The value returned will be reference to the hash-table that represents
1494the new top of the input stream stack.
1495
1496=end _PRIVATE_
1497
1498=cut
1499
1500sub _pop_input_stream {
1501 my ($self) = @_;
1502 local *myData = $self;
1503 local *input_stack = $myData{_INPUT_STREAMS};
1504
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);
1508
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();
1513
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();
1520 } else {
1521 delete $myData{_TOP_STREAM};
1522 delete $myData{_INPUT_STREAMS};
1523 }
1524
1525 return $input_top;
1526}
1527
1528#############################################################################
1529
664bb207
GS
1530=head1 TREE-BASED PARSING
1531
1532If straightforward stream-based parsing wont meet your needs (as is
1533likely the case for tasks such as translating PODs into structured
1534markup languages like HTML and XML) then you may need to take the
1535tree-based approach. Rather than doing everything in one pass and
1536calling the B<interpolate()> method to expand sequences into text, it
1537may be desirable to instead create a parse-tree using the B<parse_text()>
1538method to return a tree-like structure which may contain an ordered list
1539list of children (each of which may be a text-string, or a similar
1540tree-like structure).
1541
1542Pay special attention to L<"METHODS FOR PARSING AND PROCESSING"> and
1543to the objects described in L<Pod::InputObjects>. The former describes
1544the gory details and parameters for how to customize and extend the
1545parsing behavior of B<Pod::Parser>. B<Pod::InputObjects> provides
1546several objects that may all be used interchangeably as parse-trees. The
1547most obvious one is the B<Pod::ParseTree> object. It defines the basic
1548interface and functionality that all things trying to be a POD parse-tree
1549should do. A B<Pod::ParseTree> is defined such that each "node" may be a
1550text-string, or a reference to another parse-tree. Each B<Pod::Paragraph>
1551object and each B<Pod::InteriorSequence> object also supports the basic
1552parse-tree interface.
1553
1554The B<parse_text()> method takes a given paragraph of text, and
1555returns a parse-tree that contains one or more children, each of which
1556may be a text-string, or an InteriorSequence object. There are also
1557callback-options that may be passed to B<parse_text()> to customize
1558the way it expands or transforms interior-sequences, as well as the
1559returned result. These callbacks can be used to create a parse-tree
1560with custom-made objects (which may or may not support the parse-tree
1561interface, depending on how you choose to do it).
1562
1563If you wish to turn an entire POD document into a parse-tree, that process
1564is fairly straightforward. The B<parse_text()> method is the key to doing
1565this successfully. Every paragraph-callback (i.e. the polymorphic methods
1566for B<command()>, B<verbatim()>, and B<textblock()> paragraphs) takes
1567a B<Pod::Paragraph> object as an argument. Each paragraph object has a
1568B<parse_tree()> method that can be used to get or set a corresponding
1569parse-tree. So for each of those paragraph-callback methods, simply call
1570B<parse_text()> with the options you desire, and then use the returned
1571parse-tree to assign to the given paragraph object.
1572
1573That gives you a parse-tree for each paragraph - so now all you need is
1574an ordered list of paragraphs. You can maintain that yourself as a data
1575element in the object/hash. The most straightforward way would be simply
1576to use an array-ref, with the desired set of custom "options" for each
1577invocation of B<parse_text>. Let's assume the desired option-set is
1578given by the hash C<%options>. Then we might do something like the
1579following:
1580
1581 package MyPodParserTree;
1582
1583 @ISA = qw( Pod::Parser );
1584
1585 ...
1586
1587 sub begin_pod {
1588 my $self = shift;
1589 $self->{'-paragraphs'} = []; ## initialize paragraph list
1590 }
1591
1592 sub command {
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;
1597 }
1598
1599 sub verbatim {
1600 my ($parser, $paragraph, $line_num, $pod_para) = @_;
1601 push @{ $self->{'-paragraphs'} }, $pod_para;
1602 }
1603
1604 sub textblock {
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;
1609 }
1610
1611 ...
1612
1613 package main;
1614 ...
1615 my $parser = new MyPodParserTree(...);
1616 $parser->parse_from_file(...);
1617 my $paragraphs_ref = $parser->{'-paragraphs'};
1618
1619Of course, in this module-author's humble opinion, I'd be more inclined to
1620use the existing B<Pod::ParseTree> object than a simple array. That way
1621everything in it, paragraphs and sequences, all respond to the same core
1622interface for all parse-tree nodes. The result would look something like:
1623
1624 package MyPodParserTree2;
1625
1626 ...
1627
1628 sub begin_pod {
1629 my $self = shift;
1630 $self->{'-ptree'} = new Pod::ParseTree; ## initialize parse-tree
1631 }
1632
1633 sub 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'};
1637 }
1638
1639 sub command {
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 );
1644 }
1645
1646 sub verbatim {
1647 my ($parser, $paragraph, $line_num, $pod_para) = @_;
1648 $parser->parse_tree()->append( $pod_para );
1649 }
1650
1651 sub textblock {
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 );
1656 }
1657
1658 ...
1659
1660 package main;
1661 ...
1662 my $parser = new MyPodParserTree2(...);
1663 $parser->parse_from_file(...);
1664 my $ptree = $parser->parse_tree;
1665 ...
1666
1667Now you have the entire POD document as one great big parse-tree. You
1668can even use the B<-expand_seq> option to B<parse_text> to insert
1669whole different kinds of objects. Just don't expect B<Pod::Parser>
1670to know what to do with them after that. That will need to be in your
1671code. Or, alternatively, you can insert any object you like so long as
1672it conforms to the B<Pod::ParseTree> interface.
1673
1674One could use this to create subclasses of B<Pod::Paragraphs> and
1675B<Pod::InteriorSequences> for specific commands (or to create your own
1676custom node-types in the parse-tree) and add some kind of B<emit()>
1677method to each custom node/subclass object in the tree. Then all you'd
1678need to do is recursively walk the tree in the desired order, processing
1679the children (most likely from left to right) by formatting them if
1680they are text-strings, or by calling their B<emit()> method if they
1681are objects/references.
1682
360aca43
GS
1683=head1 SEE ALSO
1684
1685L<Pod::InputObjects>, L<Pod::Select>
1686
1687B<Pod::InputObjects> defines POD input objects corresponding to
1688command paragraphs, parse-trees, and interior-sequences.
1689
1690B<Pod::Select> is a subclass of B<Pod::Parser> which provides the ability
1691to selectively include and/or exclude sections of a POD document from being
1692translated based upon the current heading, subheading, subsubheading, etc.
1693
1694=for __PRIVATE__
1695B<Pod::Callbacks> is a subclass of B<Pod::Parser> which gives its users
1696the ability the employ I<callback functions> instead of, or in addition
1697to, overriding methods of the base class.
1698
1699=for __PRIVATE__
1700B<Pod::Select> and B<Pod::Callbacks> do not override any
1701methods nor do they define any new methods with the same name. Because
1702of this, they may I<both> be used (in combination) as a base class of
1703the same subclass in order to combine their functionality without
1704causing any namespace clashes due to multiple inheritance.
1705
1706=head1 AUTHOR
1707
1708Brad Appleton E<lt>bradapp@enteract.comE<gt>
1709
1710Based on code for B<Pod::Text> written by
1711Tom Christiansen E<lt>tchrist@mox.perl.comE<gt>
1712
1713=cut
1714
17151;