1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
|
#############################################################################
# Select.pm -- function to select portions of pod docs
#
# Based on Tom Christiansen's pod2text() function
# (with extensive modifications).
#
# Copyright (C) 1996 Tom Christiansen. All rights reserved.
# This file is part of "PodParser". PodParser is free software;
# you can redistribute it and/or modify it under the same terms
# as Perl itself.
#############################################################################
package PDL::Pod::Select;
$VERSION = 1.00; ## Current version of this package
require 5.002; ## requires Perl version 5.002 or later
=head1 NAME
podselect - function to extract selected sections of pod documentation
=head1 SYNOPSIS
use PDL::Pod::Select;
podselect (@filelist);
podselect ({OUTPUT => "tmp.out"}, @filelist):
podselect ({SELECT => ["NAME|SYNOPSIS", "OPTIONS"]}, @filelist):
podselect ({OUTPUT => ">&STDERR", SELECT => ["DESCRIPTION"]}, "-");
=head1 DESCRIPTION
B<podselect()> is a function which will extract specified sections of
pod documentation from an input stream. This ability is already provided
in the B<PDL::Pod::Parser> module. Subclasses of B<PDL::Pod::Parser> that wish to
take advantage of this feature do I<not> need to derive from
B<PDL::Pod::Select>. B<PDL::Pod::Select> merely provides a single function named
B<podselect()> which provides this capability in function form (as
opposed to object form) for extracting the raw pod docs.
=cut
#############################################################################
use Exporter ();
use PDL::Pod::Parser;
@ISA = qw(Exporter);
@EXPORT = qw(&podselect);
use strict;
use diagnostics;
use Carp;
sub version {
no strict;
return $VERSION;
}
=head2 podselect(\%options, @filelist)
B<podselect> will print the raw (untranslated) pod documentation of all
pod sections in the given input files specified by C<@filelist>
according to the given options.
If any argument to B<podselect> is a reference to a hash
(associative array) then the values with the following keys are
processed as follows:
=over 4
=item C<OUTPUT>
A string corresponding to the desired output file (or ">&STDOUT"
or ">&STDERR"). The default is to use standard output.
=item C<SELECT>
A reference to an array of sections specifications (as described in
L<PDL::Pod::Parser/"SECTION SPECIFICATIONS">) which indicate the desired set of pod
sections and subsections to be selected from input. If no section
specifications are given, then all sections of pod documentation are
used.
=back
All other arguments should correspond to the names of input files
containing pod documentation. A file name of "-" or "<&STDIN" will
be interpeted to mean standard input (which is the default if no
filenames are given).
=cut
sub podselect {
my(@argv) = @_;
my (@sections, $output);
my $pod_parser = new PDL::Pod::Parser;
my $num_inputs = 0;
local($_);
for (@argv) {
if (ref($_)) {
next unless (ref($_) eq 'HASH');
$output = $_->{OUTPUT} if (defined $_->{OUTPUT});
if ((defined $_->{SELECT}) && (ref($_->{SELECT}) eq 'ARRAY')) {
$pod_parser->select(@{$_->{SELECT}});
}
}
else {
$pod_parser->parse_from_file($_, $output);
++$num_inputs;
}
}
$pod_parser->parse_from_file("-") unless ($num_inputs > 0);
}
=head1 SEE ALSO
L<PDL::Pod::Parser>
=head1 AUTHOR
Brad Appleton E<lt>Brad_Appleton-GBDA001@email.mot.comE<gt>
Based on code for B<pod2text> written by
Tom Christiansen E<lt>tchrist@mox.perl.comE<gt>
=cut
1;
|
