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