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