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