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