lib/Pod/Parser.pm

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