lib/Pod/Select.pm

   1 #############################################################################
   2 # Pod/Select.pm -- function to select portions of 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::Select;
  11
  12 use vars qw($VERSION);
  13 $VERSION = 1.30;  ## Current version of this package
  14 require  5.005;    ## requires this Perl version or later
  15
  16 #############################################################################
  17
  18 =head1 NAME
  19
  20 Pod::Select, podselect() - extract selected sections of POD from input
  21
  22 =head1 SYNOPSIS
  23
  24     use Pod::Select;
  25
  26     ## Select all the POD sections for each file in @filelist
  27     ## and print the result on standard output.
  28     podselect(@filelist);
  29
  30     ## Same as above, but write to tmp.out
  31     podselect({-output => "tmp.out"}, @filelist):
  32
  33     ## Select from the given filelist, only those POD sections that are
  34     ## within a 1st level section named any of: NAME, SYNOPSIS, OPTIONS.
  35     podselect({-sections => ["NAME|SYNOPSIS", "OPTIONS"]}, @filelist):
  36
  37     ## Select the "DESCRIPTION" section of the PODs from STDIN and write
  38     ## the result to STDERR.
  39     podselect({-output => ">&STDERR", -sections => ["DESCRIPTION"]}, \*STDIN);
  40
  41 or
  42
  43     use Pod::Select;
  44
  45     ## Create a parser object for selecting POD sections from the input
  46     $parser = new Pod::Select();
  47
  48     ## Select all the POD sections for each file in @filelist
  49     ## and print the result to tmp.out.
  50     $parser->parse_from_file("<&STDIN", "tmp.out");
  51
  52     ## Select from the given filelist, only those POD sections that are
  53     ## within a 1st level section named any of: NAME, SYNOPSIS, OPTIONS.
  54     $parser->select("NAME|SYNOPSIS", "OPTIONS");
  55     for (@filelist) { $parser->parse_from_file($_); }
  56
  57     ## Select the "DESCRIPTION" and "SEE ALSO" sections of the PODs from
  58     ## STDIN and write the result to STDERR.
  59     $parser->select("DESCRIPTION");
  60     $parser->add_selection("SEE ALSO");
  61     $parser->parse_from_filehandle(\*STDIN, \*STDERR);
  62
  63 =head1 REQUIRES
  64
  65 perl5.005, Pod::Parser, Exporter, Carp
  66
  67 =head1 EXPORTS
  68
  69 podselect()
  70
  71 =head1 DESCRIPTION
  72
  73 B<podselect()> is a function which will extract specified sections of
  74 pod documentation from an input stream. This ability is provided by the
  75 B<Pod::Select> module which is a subclass of B<Pod::Parser>.
  76 B<Pod::Select> provides a method named B<select()> to specify the set of
  77 POD sections to select for processing/printing. B<podselect()> merely
  78 creates a B<Pod::Select> object and then invokes the B<podselect()>
  79 followed by B<parse_from_file()>.
  80
  81 =head1 SECTION SPECIFICATIONS
  82
  83 B<podselect()> and B<Pod::Select::select()> may be given one or more
  84 "section specifications" to restrict the text processed to only the
  85 desired set of sections and their corresponding subsections.  A section
  86 specification is a string containing one or more Perl-style regular
  87 expressions separated by forward slashes ("/").  If you need to use a
  88 forward slash literally within a section title you can escape it with a
  89 backslash ("\/").
  90
  91 The formal syntax of a section specification is:
  92
  93 =over 4
  94
  95 =item *
  96
  97 I<head1-title-regex>/I<head2-title-regex>/...
  98
  99 =back
 100
 101 Any omitted or empty regular expressions will default to ".*".
 102 Please note that each regular expression given is implicitly
 103 anchored by adding "^" and "$" to the beginning and end.  Also, if a
 104 given regular expression starts with a "!" character, then the
 105 expression is I<negated> (so C<!foo> would match anything I<except>
 106 C<foo>).
 107
 108 Some example section specifications follow.
 109
 110 =over 4
 111
 112 =item *
 113
 114 Match the C<NAME> and C<SYNOPSIS> sections and all of their subsections:
 115
 116 C<NAME|SYNOPSIS>
 117
 118 =item *
 119
 120 Match only the C<Question> and C<Answer> subsections of the C<DESCRIPTION>
 121 section:
 122
 123 C<DESCRIPTION/Question|Answer>
 124
 125 =item *
 126
 127 Match the C<Comments> subsection of I<all> sections:
 128
 129 C</Comments>
 130
 131 =item *
 132
 133 Match all subsections of C<DESCRIPTION> I<except> for C<Comments>:
 134
 135 C<DESCRIPTION/!Comments>
 136
 137 =item *
 138
 139 Match the C<DESCRIPTION> section but do I<not> match any of its subsections:
 140
 141 C<DESCRIPTION/!.+>
 142
 143 =item *
 144
 145 Match all top level sections but none of their subsections:
 146
 147 C</!.+>
 148
 149 =back
 150
 151 =begin _NOT_IMPLEMENTED_
 152
 153 =head1 RANGE SPECIFICATIONS
 154
 155 B<podselect()> and B<Pod::Select::select()> may be given one or more
 156 "range specifications" to restrict the text processed to only the
 157 desired ranges of paragraphs in the desired set of sections. A range
 158 specification is a string containing a single Perl-style regular
 159 expression (a regex), or else two Perl-style regular expressions
 160 (regexs) separated by a ".." (Perl's "range" operator is "..").
 161 The regexs in a range specification are delimited by forward slashes
 162 ("/").  If you need to use a forward slash literally within a regex you
 163 can escape it with a backslash ("\/").
 164
 165 The formal syntax of a range specification is:
 166
 167 =over 4
 168
 169 =item *
 170
 171 /I<start-range-regex>/[../I<end-range-regex>/]
 172
 173 =back
 174
 175 Where each the item inside square brackets (the ".." followed by the
 176 end-range-regex) is optional. Each "range-regex" is of the form:
 177
 178     =cmd-expr text-expr
 179
 180 Where I<cmd-expr> is intended to match the name of one or more POD
 181 commands, and I<text-expr> is intended to match the paragraph text for
 182 the command. If a range-regex is supposed to match a POD command, then
 183 the first character of the regex (the one after the initial '/')
 184 absolutely I<must> be a single '=' character; it may not be anything
 185 else (not even a regex meta-character) if it is supposed to match
 186 against the name of a POD command.
 187
 188 If no I<=cmd-expr> is given then the text-expr will be matched against
 189 plain textblocks unless it is preceded by a space, in which case it is
 190 matched against verbatim text-blocks. If no I<text-expr> is given then
 191 only the command-portion of the paragraph is matched against.
 192
 193 Note that these two expressions are each implicitly anchored. This
 194 means that when matching against the command-name, there will be an
 195 implicit '^' and '$' around the given I<=cmd-expr>; and when matching
 196 against the paragraph text there will be an implicit '\A' and '\Z'
 197 around the given I<text-expr>.
 198
 199 Unlike with section-specs, the '!' character does I<not> have any special
 200 meaning (negation or otherwise) at the beginning of a range-spec!
 201
 202 Some example range specifications follow.
 203
 204 =over 4
 205
 206 =item
 207 Match all C<=for html> paragraphs:
 208
 209 C</=for html/>
 210
 211 =item
 212 Match all paragraphs between C<=begin html> and C<=end html>
 213 (note that this will I<not> work correctly if such sections
 214 are nested):
 215
 216 C</=begin html/../=end html/>
 217
 218 =item
 219 Match all paragraphs between the given C<=item> name until the end of the
 220 current section:
 221
 222 C</=item mine/../=head\d/>
 223
 224 =item
 225 Match all paragraphs between the given C<=item> until the next item, or
 226 until the end of the itemized list (note that this will I<not> work as
 227 desired if the item contains an itemized list nested within it):
 228
 229 C</=item mine/../=(item|back)/>
 230
 231 =back
 232
 233 =end _NOT_IMPLEMENTED_
 234
 235 =cut
 236
 237 #############################################################################
 238
 239 use strict;
 240 #use diagnostics;
 241 use Carp;
 242 use Pod::Parser 1.04;
 243 use vars qw(@ISA @EXPORT $MAX_HEADING_LEVEL);
 244
 245 @ISA = qw(Pod::Parser);
 246 @EXPORT = qw(&podselect);
 247
 248 ## Maximum number of heading levels supported for '=headN' directives
 249 *MAX_HEADING_LEVEL = \3;
 250
 251 #############################################################################
 252
 253 =head1 OBJECT METHODS
 254
 255 The following methods are provided in this module. Each one takes a
 256 reference to the object itself as an implicit first parameter.
 257
 258 =cut
 259
 260 ##---------------------------------------------------------------------------
 261
 262 ## =begin _PRIVATE_
 263 ##
 264 ## =head1 B<_init_headings()>
 265 ##
 266 ## Initialize the current set of active section headings.
 267 ##
 268 ## =cut
 269 ##
 270 ## =end _PRIVATE_
 271
 272 use vars qw(%myData @section_headings);
 273
 274 sub _init_headings {
 275     my $self = shift;
 276     local *myData = $self;
 277
 278     ## Initialize current section heading titles if necessary
 279     unless (defined $myData{_SECTION_HEADINGS}) {
 280         local *section_headings = $myData{_SECTION_HEADINGS} = [];
 281         for (my $i = 0; $i < $MAX_HEADING_LEVEL; ++$i) {
 282             $section_headings[$i] = '';
 283         }
 284     }
 285 }
 286
 287 ##---------------------------------------------------------------------------
 288
 289 =head1 B<curr_headings()>
 290
 291             ($head1, $head2, $head3, ...) = $parser->curr_headings();
 292             $head1 = $parser->curr_headings(1);
 293
 294 This method returns a list of the currently active section headings and
 295 subheadings in the document being parsed. The list of headings returned
 296 corresponds to the most recently parsed paragraph of the input.
 297
 298 If an argument is given, it must correspond to the desired section
 299 heading number, in which case only the specified section heading is
 300 returned. If there is no current section heading at the specified
 301 level, then C<undef> is returned.
 302
 303 =cut
 304
 305 sub curr_headings {
 306     my $self = shift;
 307     $self->_init_headings()  unless (defined $self->{_SECTION_HEADINGS});
 308     my @headings = @{ $self->{_SECTION_HEADINGS} };
 309     return (@_ > 0  and  $_[0] =~ /^\d+$/) ? $headings[$_[0] - 1] : @headings;
 310 }
 311
 312 ##---------------------------------------------------------------------------
 313
 314 =head1 B<select()>
 315
 316             $parser->select($section_spec1,$section_spec2,...);
 317
 318 This method is used to select the particular sections and subsections of
 319 POD documentation that are to be printed and/or processed. The existing
 320 set of selected sections is I<replaced> with the given set of sections.
 321 See B<add_selection()> for adding to the current set of selected
 322 sections.
 323
 324 Each of the C<$section_spec> arguments should be a section specification
 325 as described in L<"SECTION SPECIFICATIONS">.  The section specifications
 326 are parsed by this method and the resulting regular expressions are
 327 stored in the invoking object.
 328
 329 If no C<$section_spec> arguments are given, then the existing set of
 330 selected sections is cleared out (which means C<all> sections will be
 331 processed).
 332
 333 This method should I<not> normally be overridden by subclasses.
 334
 335 =cut
 336
 337 use vars qw(@selected_sections);
 338
 339 sub select {
 340     my $self = shift;
 341     my @sections = @_;
 342     local *myData = $self;
 343     local $_;
 344
 345 ### NEED TO DISCERN A SECTION-SPEC FROM A RANGE-SPEC (look for m{^/.+/$}?)
 346
 347     ##---------------------------------------------------------------------
 348     ## The following is a blatant hack for backward compatibility, and for
 349     ## implementing add_selection(). If the *first* *argument* is the
 350     ## string "+", then the remaining section specifications are *added*
 351     ## to the current set of selections; otherwise the given section
 352     ## specifications will *replace* the current set of selections.
 353     ##
 354     ## This should probably be fixed someday, but for the present time,
 355     ## it seems incredibly unlikely that "+" would ever correspond to
 356     ## a legitimate section heading
 357     ##---------------------------------------------------------------------
 358     my $add = ($sections[0] eq "+") ? shift(@sections) : "";
 359
 360     ## Reset the set of sections to use
 361     unless (@sections > 0) {
 362         delete $myData{_SELECTED_SECTIONS}  unless ($add);
 363         return;
 364     }
 365     $myData{_SELECTED_SECTIONS} = []
 366         unless ($add  &&  exists $myData{_SELECTED_SECTIONS});
 367     local *selected_sections = $myData{_SELECTED_SECTIONS};
 368
 369     ## Compile each spec
 370     my $spec;
 371     for $spec (@sections) {
 372         if ( defined($_ = &_compile_section_spec($spec)) ) {
 373             ## Store them in our sections array
 374             push(@selected_sections, $_);
 375         }
 376         else {
 377             carp "Ignoring section spec \"$spec\"!\n";
 378         }
 379     }
 380 }
 381
 382 ##---------------------------------------------------------------------------
 383
 384 =head1 B<add_selection()>
 385
 386             $parser->add_selection($section_spec1,$section_spec2,...);
 387
 388 This method is used to add to the currently selected sections and
 389 subsections of POD documentation that are to be printed and/or
 390 processed. See <select()> for replacing the currently selected sections.
 391
 392 Each of the C<$section_spec> arguments should be a section specification
 393 as described in L<"SECTION SPECIFICATIONS">. The section specifications
 394 are parsed by this method and the resulting regular expressions are
 395 stored in the invoking object.
 396
 397 This method should I<not> normally be overridden by subclasses.
 398
 399 =cut
 400
 401 sub add_selection {
 402     my $self = shift;
 403     $self->select("+", @_);
 404 }
 405
 406 ##---------------------------------------------------------------------------
 407
 408 =head1 B<clear_selections()>
 409
 410             $parser->clear_selections();
 411
 412 This method takes no arguments, it has the exact same effect as invoking
 413 <select()> with no arguments.
 414
 415 =cut
 416
 417 sub clear_selections {
 418     my $self = shift;
 419     $self->select();
 420 }
 421
 422 ##---------------------------------------------------------------------------
 423
 424 =head1 B<match_section()>
 425
 426             $boolean = $parser->match_section($heading1,$heading2,...);
 427
 428 Returns a value of true if the given section and subsection heading
 429 titles match any of the currently selected section specifications in
 430 effect from prior calls to B<select()> and B<add_selection()> (or if
 431 there are no explictly selected/deselected sections).
 432
 433 The arguments C<$heading1>, C<$heading2>, etc. are the heading titles of
 434 the corresponding sections, subsections, etc. to try and match.  If
 435 C<$headingN> is omitted then it defaults to the current corresponding
 436 section heading title in the input.
 437
 438 This method should I<not> normally be overridden by subclasses.
 439
 440 =cut
 441
 442 sub match_section {
 443     my $self = shift;
 444     my (@headings) = @_;
 445     local *myData = $self;
 446
 447     ## Return true if no restrictions were explicitly specified
 448     my $selections = (exists $myData{_SELECTED_SECTIONS})
 449                        ?  $myData{_SELECTED_SECTIONS}  :  undef;
 450     return  1  unless ((defined $selections) && (@{$selections} > 0));
 451
 452     ## Default any unspecified sections to the current one
 453     my @current_headings = $self->curr_headings();
 454     for (my $i = 0; $i < $MAX_HEADING_LEVEL; ++$i) {
 455         (defined $headings[$i])  or  $headings[$i] = $current_headings[$i];
 456     }
 457
 458     ## Look for a match against the specified section expressions
 459     my ($section_spec, $regex, $negated, $match);
 460     for $section_spec ( @{$selections} ) {
 461         ##------------------------------------------------------
 462         ## Each portion of this spec must match in order for
 463         ## the spec to be matched. So we will start with a
 464         ## match-value of 'true' and logically 'and' it with
 465         ## the results of matching a given element of the spec.
 466         ##------------------------------------------------------
 467         $match = 1;
 468         for (my $i = 0; $i < $MAX_HEADING_LEVEL; ++$i) {
 469             $regex   = $section_spec->[$i];
 470             $negated = ($regex =~ s/^\!//);
 471             $match  &= ($negated ? ($headings[$i] !~ /${regex}/)
 472                                  : ($headings[$i] =~ /${regex}/));
 473             last unless ($match);
 474         }
 475         return  1  if ($match);
 476     }
 477     return  0;  ## no match
 478 }
 479
 480 ##---------------------------------------------------------------------------
 481
 482 =head1 B<is_selected()>
 483
 484             $boolean = $parser->is_selected($paragraph);
 485
 486 This method is used to determine if the block of text given in
 487 C<$paragraph> falls within the currently selected set of POD sections
 488 and subsections to be printed or processed. This method is also
 489 responsible for keeping track of the current input section and
 490 subsections. It is assumed that C<$paragraph> is the most recently read
 491 (but not yet processed) input paragraph.
 492
 493 The value returned will be true if the C<$paragraph> and the rest of the
 494 text in the same section as C<$paragraph> should be selected (included)
 495 for processing; otherwise a false value is returned.
 496
 497 =cut
 498
 499 sub is_selected {
 500     my ($self, $paragraph) = @_;
 501     local $_;
 502     local *myData = $self;
 503
 504     $self->_init_headings()  unless (defined $myData{_SECTION_HEADINGS});
 505
 506     ## Keep track of current sections levels and headings
 507     $_ = $paragraph;
 508     if (/^=((?:sub)*)(?:head(?:ing)?|sec(?:tion)?)(\d*)\s+(.*)\s*$/)
 509     {
 510         ## This is a section heading command
 511         my ($level, $heading) = ($2, $3);
 512         $level = 1 + (length($1) / 3)  if ((! length $level) || (length $1));
 513         ## Reset the current section heading at this level
 514         $myData{_SECTION_HEADINGS}->[$level - 1] = $heading;
 515         ## Reset subsection headings of this one to empty
 516         for (my $i = $level; $i < $MAX_HEADING_LEVEL; ++$i) {
 517             $myData{_SECTION_HEADINGS}->[$i] = '';
 518         }
 519     }
 520
 521     return  $self->match_section();
 522 }
 523
 524 #############################################################################
 525
 526 =head1 EXPORTED FUNCTIONS
 527
 528 The following functions are exported by this module. Please note that
 529 these are functions (not methods) and therefore C<do not> take an
 530 implicit first argument.
 531
 532 =cut
 533
 534 ##---------------------------------------------------------------------------
 535
 536 =head1 B<podselect()>
 537
 538             podselect(\%options,@filelist);
 539
 540 B<podselect> will print the raw (untranslated) POD paragraphs of all
 541 POD sections in the given input files specified by C<@filelist>
 542 according to the given options.
 543
 544 If any argument to B<podselect> is a reference to a hash
 545 (associative array) then the values with the following keys are
 546 processed as follows:
 547
 548 =over 4
 549
 550 =item B<-output>
 551
 552 A string corresponding to the desired output file (or ">&STDOUT"
 553 or ">&STDERR"). The default is to use standard output.
 554
 555 =item B<-sections>
 556
 557 A reference to an array of sections specifications (as described in
 558 L<"SECTION SPECIFICATIONS">) which indicate the desired set of POD
 559 sections and subsections to be selected from input. If no section
 560 specifications are given, then all sections of the PODs are used.
 561
 562 =begin _NOT_IMPLEMENTED_
 563
 564 =item B<-ranges>
 565
 566 A reference to an array of range specifications (as described in
 567 L<"RANGE SPECIFICATIONS">) which indicate the desired range of POD
 568 paragraphs to be selected from the desired input sections. If no range
 569 specifications are given, then all paragraphs of the desired sections
 570 are used.
 571
 572 =end _NOT_IMPLEMENTED_
 573
 574 =back
 575
 576 All other arguments should correspond to the names of input files
 577 containing POD sections. A file name of "-" or "<&STDIN" will
 578 be interpeted to mean standard input (which is the default if no
 579 filenames are given).
 580
 581 =cut
 582
 583 sub podselect {
 584     my(@argv) = @_;
 585     my %defaults = ();
 586     my $pod_parser = new Pod::Select(%defaults);
 587     my $num_inputs = 0;
 588     my $output = ">&STDOUT";
 589     my %opts;
 590     local $_;
 591     for (@argv) {
 592         if (ref($_)) {
 593         next unless (ref($_) eq 'HASH');
 594             %opts = (%defaults, %{$_});
 595
 596             ##-------------------------------------------------------------
 597             ## Need this for backward compatibility since we formerly used
 598             ## options that were all uppercase words rather than ones that
 599             ## looked like Unix command-line options.
 600             ## to be uppercase keywords)
 601             ##-------------------------------------------------------------
 602             %opts = map {
 603                 my ($key, $val) = (lc $_, $opts{$_});
 604                 $key =~ s/^(?=\w)/-/;
 605                 $key =~ /^-se[cl]/  and  $key  = '-sections';
 606                 #! $key eq '-range'    and  $key .= 's';
 607                 ($key => $val);
 608             } (keys %opts);
 609
 610             ## Process the options
 611             (exists $opts{'-output'})  and  $output = $opts{'-output'};
 612
 613             ## Select the desired sections
 614             $pod_parser->select(@{ $opts{'-sections'} })
 615                 if ( (defined $opts{'-sections'})
 616                      && ((ref $opts{'-sections'}) eq 'ARRAY') );
 617
 618             #! ## Select the desired paragraph ranges
 619             #! $pod_parser->select(@{ $opts{'-ranges'} })
 620             #!     if ( (defined $opts{'-ranges'})
 621             #!          && ((ref $opts{'-ranges'}) eq 'ARRAY') );
 622         }
 623         else {
 624             $pod_parser->parse_from_file($_, $output);
 625             ++$num_inputs;
 626         }
 627     }
 628     $pod_parser->parse_from_file("-")  unless ($num_inputs > 0);
 629 }
 630
 631 #############################################################################
 632
 633 =head1 PRIVATE METHODS AND DATA
 634
 635 B<Pod::Select> makes uses a number of internal methods and data fields
 636 which clients should not need to see or use. For the sake of avoiding
 637 name collisions with client data and methods, these methods and fields
 638 are briefly discussed here. Determined hackers may obtain further
 639 information about them by reading the B<Pod::Select> source code.
 640
 641 Private data fields are stored in the hash-object whose reference is
 642 returned by the B<new()> constructor for this class. The names of all
 643 private methods and data-fields used by B<Pod::Select> begin with a
 644 prefix of "_" and match the regular expression C</^_\w+$/>.
 645
 646 =cut
 647
 648 ##---------------------------------------------------------------------------
 649
 650 =begin _PRIVATE_
 651
 652 =head1 B<_compile_section_spec()>
 653
 654             $listref = $parser->_compile_section_spec($section_spec);
 655
 656 This function (note it is a function and I<not> a method) takes a
 657 section specification (as described in L<"SECTION SPECIFICATIONS">)
 658 given in C<$section_sepc>, and compiles it into a list of regular
 659 expressions. If C<$section_spec> has no syntax errors, then a reference
 660 to the list (array) of corresponding regular expressions is returned;
 661 otherwise C<undef> is returned and an error message is printed (using
 662 B<carp>) for each invalid regex.
 663
 664 =end _PRIVATE_
 665
 666 =cut
 667
 668 sub _compile_section_spec {
 669     my ($section_spec) = @_;
 670     my (@regexs, $negated);
 671
 672     ## Compile the spec into a list of regexs
 673     local $_ = $section_spec;
 674     s|\\\\|\001|g;  ## handle escaped backward slashes
 675     s|\\/|\002|g;   ## handle escaped forward slashes
 676
 677     ## Parse the regexs for the heading titles
 678     @regexs = split('/', $_, $MAX_HEADING_LEVEL);
 679
 680     ## Set default regex for ommitted levels
 681     for (my $i = 0; $i < $MAX_HEADING_LEVEL; ++$i) {
 682         $regexs[$i]  = '.*'  unless ((defined $regexs[$i])
 683                                      && (length $regexs[$i]));
 684     }
 685     ## Modify the regexs as needed and validate their syntax
 686     my $bad_regexs = 0;
 687     for (@regexs) {
 688         $_ .= '.+'  if ($_ eq '!');
 689         s|\001|\\\\|g;       ## restore escaped backward slashes
 690         s|\002|\\/|g;        ## restore escaped forward slashes
 691         $negated = s/^\!//;  ## check for negation
 692         eval "/$_/";         ## check regex syntax
 693         if ($@) {
 694             ++$bad_regexs;
 695             carp "Bad regular expression /$_/ in \"$section_spec\": $@\n";
 696         }
 697         else {
 698             ## Add the forward and rear anchors (and put the negator back)
 699             $_ = '^' . $_  unless (/^\^/);
 700             $_ = $_ . '$'  unless (/\$$/);
 701             $_ = '!' . $_  if ($negated);
 702         }
 703     }
 704     return  (! $bad_regexs) ? [ @regexs ] : undef;
 705 }
 706
 707 ##---------------------------------------------------------------------------
 708
 709 =begin _PRIVATE_
 710
 711 =head2 $self->{_SECTION_HEADINGS}
 712
 713 A reference to an array of the current section heading titles for each
 714 heading level (note that the first heading level title is at index 0).
 715
 716 =end _PRIVATE_
 717
 718 =cut
 719
 720 ##---------------------------------------------------------------------------
 721
 722 =begin _PRIVATE_
 723
 724 =head2 $self->{_SELECTED_SECTIONS}
 725
 726 A reference to an array of references to arrays. Each subarray is a list
 727 of anchored regular expressions (preceded by a "!" if the expression is to
 728 be negated). The index of the expression in the subarray should correspond
 729 to the index of the heading title in C<$self-E<gt>{_SECTION_HEADINGS}>
 730 that it is to be matched against.
 731
 732 =end _PRIVATE_
 733
 734 =cut
 735
 736 #############################################################################
 737
 738 =head1 SEE ALSO
 739
 740 L<Pod::Parser>
 741
 742 =head1 AUTHOR
 743
 744 Please report bugs using L<http://rt.cpan.org>.
 745
 746 Brad Appleton E<lt>bradapp@enteract.comE<gt>
 747
 748 Based on code for B<pod2text> written by
 749 Tom Christiansen E<lt>tchrist@mox.perl.comE<gt>
 750
 751 =cut
 752
 753 1;
 754 # vim: ts=4 sw=4 et