lib/PDL/Doc.pm

filter: Statementstmt 47.0% 231 / 491 Branchbran 28.1% 68 / 242 Conditioncond 28.7% 38 / 132 MC/DCmcdc 14.4% 11 / 76 Subroutinesub 53.3% 40 / 75 Podpod 88.0% 22 / 25 totaltotal 39.3% 410 / 1041 CC 283 SCAR 34.0
CC
283
Cov
39%
add_module
90.0
add_module
90.0
__ANON__
72.0
CRAP 29.9
« blib/lib/PDL/NiceSlice.pm ↑ Summary blib/lib/PDL/Transform/Cartography.pm »
1 # the filter for the PDL pod format (which is a valid general perl
2 # pod format but with special interpretation of some =for directives)
3  
4 package # hide from PAUSE/MetaCPAN
5 PDL::Doc::SelectJustPod;
6 2 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
7 2 ▶use warnings;
Subroutine BEGIN: called CC=1 SCAR=0.0
8 1 ▶use parent qw(Pod::Simple::JustPod);
Subroutine BEGIN: called CC=1 SCAR=0.0
9  
10 3 ▶sub select_head1s {
Subroutine select_head1s: called CC=2 SCAR=9.2
11 0 ▶ my ($self, @titles) = @_;
Subroutine select_head1s: not called CC=2 SCAR=9.2
12 0 $self->{interested_head1s}{$_} = 1 for @titles;
13 0 $self;
14 }
15  
16 3 ▶sub select_head2 {
Subroutine select_head2: called CC=1 SCAR=1.2
17 0 ▶ my ($self, $name) = @_;
Subroutine select_head2: not called CC=1 SCAR=1.2
18 0 $self->{interested_head2} = $name;
19 0 $self;
20 }
21  
22 7 ▶sub end_head1 {
Subroutine end_head1: called CC=1 SCAR=1.2
23 0 ▶ my $self = shift;
Subroutine end_head1: not called CC=1 SCAR=1.2
24 0 my ($text) = $self->{buffer} =~ /=head1 +(.*)\z/;
25 0 $self->{current_head1} = $text;
26 0 delete $self->{current_head2};
27 0 $self->SUPER::end_head1(@_);
28 }
29  
30 6 ▶sub end_head2 {
Subroutine end_head2: called CC=1 SCAR=1.2
31 0 ▶ my $self = shift;
Subroutine end_head2: not called CC=1 SCAR=1.2
32 0 my ($text) = $self->{buffer} =~ /=head2 +(.*)\z/;
33 0 $self->{current_head2} = $text;
34 0 $self->SUPER::end_head2(@_);
35 }
36  
37 11 ▶sub start_for {
Subroutine start_for: called CC=1 SCAR=1.2
38 0 ▶ my $self = shift;
Subroutine start_for: not called CC=1 SCAR=1.2
39 0 my ($attrs) = @_;
40 0 $self->{buffer} .= "@$attrs{qw(~really target)}\n\n";
41 }
42  
43 31 ▶sub emit {
Subroutine emit: called CC=6 SCAR=24.3
44 0 ▶ my ($self) = @_;
Subroutine emit: not called CC=6 SCAR=24.3
45 0 print { $self->{output_fh} } $self->{buffer}, "\n\n" # superclass adds "" at start which inserts a space
46 if $self->{buffer} ne ''
47 and $self->{interested_head1s}{$self->{current_head1} // ''}
48 0 ▶ and ($self->{current_head2}//'') =~ /\b\Q$self->{interested_head2}\E\b/;
Branch: 2 branches
BranchTrueFalseTotal
if $self->{"buffer"} ne "" and $self->{"interested_head1s"}{$self->{"current_head1"} // ""} and ($self->{"current_head2"} // "") =~ /\b\Q$self->{"interested_head2"}\E\b/ 0 0 0
if $self->{"buffer"} ne "" and $self->{"interested_head1s"}{$self->{"current_head1"} // ""} and ($self->{"current_head2"} // "") =~ /\b\Q$self->{"interested_head2"}\E\b/ 12 19 31
Condition45%9/20
$self->{"buffer"} ne "" and $self->{"interested_head1s"}{$self->{"current_head1"} // ""} and ($self->{"current_head2"} // "") =~ /\b\Q$self->{"interested_head2"}\E\b/
!ll&&!rl&&r
000
$self->{"buffer"} ne "" and $self->{"interested_head1s"}{$self->{"current_head1"} // ""}
!ll&&!rl&&r
000
$self->{"current_head1"} // ""
l!l
00
$self->{"current_head2"} // ""
l!l
00
$self->{"buffer"} ne "" and $self->{"interested_head1s"}{$self->{"current_head1"} // ""} and ($self->{"current_head2"} // "") =~ /\b\Q$self->{"interested_head2"}\E\b/
!ll&&!rl&&r
12812
$self->{"buffer"} ne "" and $self->{"interested_head1s"}{$self->{"current_head1"} // ""}
!ll&&!rl&&r
3920
$self->{"current_head1"} // ""
l!l
280
$self->{"current_head2"} // ""
l!l
163
MC/DC0%0/3
$self->{"buffer"} ne "" and $self->{"interested_head1s"}{$self->{"current_head1"} // ""} and ($self->{"current_head2"} // "") =~ /\b\Q$self->{"interested_head2"}\E\b/
$self->{"buffer"} ne "" $self->{"interested_head1s"}{$self->{"current_head1"} // ""} $self->{"current_head2"}
MC/DC0%0/1
$self->{"current_head1"} // ""
$self->{"current_head1"}
MC/DC100%3/3
$self->{"buffer"} ne "" and $self->{"interested_head1s"}{$self->{"current_head1"} // ""} and ($self->{"current_head2"} // "") =~ /\b\Q$self->{"interested_head2"}\E\b/
$self->{"buffer"} ne "" $self->{"interested_head1s"}{$self->{"current_head1"} // ""} $self->{"current_head2"}
MC/DC0%0/1
$self->{"current_head1"} // ""
$self->{"current_head1"}
Truth table0%0/4
A and B and C
A= $self->{"buffer"} ne ""B= $self->{"interested_head1s"}{$self->{"current_head1"} // ""}C= $self->{"current_head2"}
ABCresult
0XX0
10X0
1100
1111
Truth table0%0/2
A
A= $self->{"current_head1"}
Aresult
11
00
Truth table100%4/4
A and B and C
A= $self->{"buffer"} ne ""B= $self->{"interested_head1s"}{$self->{"current_head1"} // ""}C= $self->{"current_head2"}
ABCresult
0XX0
10X0
1100
1111
Truth table50%1/2
A
A= $self->{"current_head1"}
Aresult
11
00
49 0 $self->{buffer} = "";
50 }
51  
52 3 ▶sub end_Document { # only override is not adding "=cut"
Subroutine end_Document: called CC=1 SCAR=1.2
53 0 ▶ my $self = shift;
Subroutine end_Document: not called CC=1 SCAR=1.2
54 0 $self->emit; # Make sure buffer gets flushed
55 }
56  
57 package # hide from PAUSE/MetaCPAN
58 PDL::PodParser;
59 1 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
60 1 ▶use warnings;
Subroutine BEGIN: called CC=1 SCAR=0.0
61 1 ▶use Carp qw(confess);
Subroutine BEGIN: called CC=1 SCAR=0.0
62 1 ▶use Pod::Simple::PullParser;
Subroutine BEGIN: called CC=1 SCAR=0.0
63 1 ▶use parent qw(Pod::Text);
Subroutine BEGIN: called CC=1 SCAR=0.0
64  
65 our %Title = ('Example' => 'Example',
66 'Ref' => 'Reference',
67 'Sig' => 'Signature',
68 'Opt' => 'Options',
69 'Usage' => 'Usage',
70 'Bad' => 'Bad value support',
71 );
72  
73 my @h1s = qw(OPERATORS FUNCTIONS CONSTRUCTORS METHODS);
74 3 ▶sub new {
Subroutine new: called CC=1 SCAR=1.2
75 0 ▶ my $class = shift;
Subroutine new: not called CC=1 SCAR=1.2
76 0 my $parser = $class->SUPER::new(@_);
77 0 $parser->accept_targets(qw(bad example ref options sig usage));
78 0 @{ $parser->{interested_head1s} }{@h1s} = (1) x @h1s;
79 0 $parser->{CURFUNC} = undef;
80 0 $parser->{SYMHASH} = {};
81 0 $parser->{Mode} = "";
82 0 $parser->{verbose} = 0;
83 0 $parser->{NAME} = 'UNKNOWN';
84 0 $parser;
85 }
86  
87 7 ▶sub cmd_head1 {
Subroutine cmd_head1: called CC=2 SCAR=9.2
88 0 ▶ my ($this, $attrs, $text) = @_;
Subroutine cmd_head1: not called CC=2 SCAR=9.2
89 0 $this->{Mode} = $text;
90 0 ▶ $this->{Parmode} = $text =~ /NAME/ ? 'NAME' : 'Body';
Branch: 2 branches
BranchTrueFalseTotal
$text =~ /NAME/ ? : 0 0 0
$text =~ /NAME/ ? : 3 4 7
91 0 '';
92 }
93  
94 5 ▶sub cmd_head2 {
Subroutine cmd_head2: called CC=14 SCAR=41.1
95 0 ▶ my ($this, $attrs, $text) = @_;
Subroutine cmd_head2: not called CC=14 SCAR=41.1
96 0 ▶ return if $text =~ /^The\s/; # heuristic to deal with GSL::CDF descriptive =head2
Branch: 2 branches
BranchTrueFalseTotal
if $text =~ /^The\s/ 0 0 0
if $text =~ /^The\s/ 0 5 5
97 0 ▶ return if !$this->{interested_head1s}{$this->{Mode} // ''};
Branch: 2 branches
BranchTrueFalseTotal
unless $this->{"interested_head1s"}{$this->{"Mode"} // ""} 0 0 0
unless $this->{"interested_head1s"}{$this->{"Mode"} // ""} 1 4 5
Condition25%1/4
$this->{"Mode"} // ""
l!l
00
$this->{"Mode"} // ""
l!l
50
MC/DC0%0/1
$this->{"Mode"} // ""
$this->{"Mode"}
MC/DC0%0/1
$this->{"Mode"} // ""
$this->{"Mode"}
Truth table0%0/2
A
A= $this->{"Mode"}
Aresult
11
00
Truth table50%1/2
A
A= $this->{"Mode"}
Aresult
11
00
98 # A function can have multiple names (ex: zeros and zeroes),
99 # so split at the commas
100 0 my @funcs = split ',', $text;
101 # Remove parentheses (so myfunc and myfunc() both work)
102 0 ▶ my @names = map {$1 if m/\s*([^\s\(]+)\s*/} @funcs;
Branch: 2 branches
BranchTrueFalseTotal
if /\s*([^\s\(]+)\s*/ 0 0 0
if /\s*([^\s\(]+)\s*/ 6 0 6
103 0 ▶ confess "error parsing function list '$text'"
Branch: 2 branches
BranchTrueFalseTotal
unless @funcs == @names 0 0 0
unless @funcs == @names 0 4 4
104 unless @funcs == @names;
105 # check for signatures
106 0 my $sym = $this->{SYMHASH};
107 0 for (@funcs) {
108 0 ▶ $sym->{$1}{Module} = $this->{NAME} if m/\s*([^\s(]+)\s*/;
Branch: 2 branches
BranchTrueFalseTotal
if /\s*([^\s(]+)\s*/ 0 0 0
if /\s*([^\s(]+)\s*/ 6 0 6
109 0 ▶ $sym->{$1}{Sig} = $2 if m/\s*([^\s(]+)\s*\(\s*(.+)\s*\)\s*$/;
Branch: 2 branches
BranchTrueFalseTotal
if /\s*([^\s(]+)\s*\(\s*(.+)\s*\)\s*$/ 0 0 0
if /\s*([^\s(]+)\s*\(\s*(.+)\s*\)\s*$/ 0 6 6
110 }
111 # make the first one the current function
112 0 ▶ $sym->{$names[0]}{Names} = join(',',@names) if $#names > 0;
Branch: 2 branches
BranchTrueFalseTotal
if $#names > 0 0 0 0
if $#names > 0 1 3 4
113 0 my $name = shift @names;
114 # Make the other names cross-reference the first name
115 0 $sym->{$_}{Crossref} = $name for @names;
116 0 my $sig = $sym->{$name}{Sig};
117 # diagnostic output
118 0 ▶ print "\nFunction '".join(',',($name,@names))."'\n" if $this->{verbose};
Branch: 2 branches
BranchTrueFalseTotal
if $this->{"verbose"} 0 0 0
if $this->{"verbose"} 0 4 4
119 0 ▶ print "\n\tSignature: $sig\n" if defined $sig && $this->{verbose};
Branch: 2 branches
BranchTrueFalseTotal
if defined $sig and $this->{"verbose"} 0 0 0
if defined $sig and $this->{"verbose"} 0 4 4
Condition16%1/6
defined $sig and $this->{"verbose"}
!ll&&!rl&&r
000
defined $sig and $this->{"verbose"}
!ll&&!rl&&r
400
MC/DC0%0/2
defined $sig and $this->{"verbose"}
defined $sig $this->{"verbose"}
MC/DC0%0/2
defined $sig and $this->{"verbose"}
defined $sig $this->{"verbose"}
Truth table0%0/3
A and B
A= defined $sigB= $this->{"verbose"}
ABresult
0X0
100
111
Truth table33%1/3
A and B
A= defined $sigB= $this->{"verbose"}
ABresult
0X0
100
111
120 0 $this->{CURFUNC} = $name;
121 }
122  
123 10 ▶sub cmd_for {
Subroutine cmd_for: called CC=7 SCAR=29.2
124 0 ▶ my ($this, $attrs, $text) = @_;
Subroutine cmd_for: not called CC=7 SCAR=29.2
125 0 ▶ return if !$this->{interested_head1s}{$this->{Mode} // ''};
Branch: 2 branches
BranchTrueFalseTotal
unless $this->{"interested_head1s"}{$this->{"Mode"} // ""} 0 0 0
unless $this->{"interested_head1s"}{$this->{"Mode"} // ""} 1 9 10
Condition25%1/4
$this->{"Mode"} // ""
l!l
00
$this->{"Mode"} // ""
l!l
100
MC/DC0%0/1
$this->{"Mode"} // ""
$this->{"Mode"}
MC/DC0%0/1
$this->{"Mode"} // ""
$this->{"Mode"}
Truth table0%0/2
A
A= $this->{"Mode"}
Aresult
11
00
Truth table50%1/2
A
A= $this->{"Mode"}
Aresult
11
00
126 0 my $tgt = $attrs->{target};
127 0 ▶ $tgt = 'opt' if $tgt eq 'options';
Branch: 2 branches
BranchTrueFalseTotal
if $tgt eq "options" 0 0 0
if $tgt eq "options" 1 8 9
128 0 $this->{Parmode} = ucfirst lc $tgt;
129 0 ▶ print "switched now to '$tgt' mode\n" if $this->{verbose};
Branch: 2 branches
BranchTrueFalseTotal
if $this->{"verbose"} 0 0 0
if $this->{"verbose"} 0 9 9
130 print "\n\t$Title{$this->{Parmode}}\n"
131 0 ▶ if $this->{Parmode} !~ /Body/ && $this->{verbose};
Branch: 2 branches
BranchTrueFalseTotal
if not $this->{"Parmode"} =~ /Body/ and $this->{"verbose"} 0 0 0
if not $this->{"Parmode"} =~ /Body/ and $this->{"verbose"} 0 9 9
Condition16%1/6
not $this->{"Parmode"} =~ /Body/ and $this->{"verbose"}
!ll&&!rl&&r
000
not $this->{"Parmode"} =~ /Body/ and $this->{"verbose"}
!ll&&!rl&&r
090
MC/DC0%0/2
not $this->{"Parmode"} =~ /Body/ and $this->{"verbose"}
not $this->{"Parmode"} =~ /Body/ $this->{"verbose"}
MC/DC0%0/2
not $this->{"Parmode"} =~ /Body/ and $this->{"verbose"}
not $this->{"Parmode"} =~ /Body/ $this->{"verbose"}
Truth table0%0/3
not(A) and B
A= not $this->{"Parmode"} =~ /Body/B= $this->{"verbose"}
ABresult
0X0
100
111
Truth table33%1/3
not(A) and B
A= not $this->{"Parmode"} =~ /Body/B= $this->{"verbose"}
ABresult
0X0
100
111
132 0 '';
133 }
134  
135 10 ▶sub cmd_para {
Subroutine cmd_para: called CC=4 SCAR=18.9
136 0 ▶ my ($this, $attrs, $text) = @_;
Subroutine cmd_para: not called CC=4 SCAR=18.9
137 0 ▶ return if $this->{Mode} ne 'NAME' and !$this->{interested_head1s}{$this->{Mode} // ''};
Branch: 2 branches
BranchTrueFalseTotal
if $this->{"Mode"} ne "NAME" and not $this->{"interested_head1s"}{$this->{"Mode"} // ""} 0 0 0
if $this->{"Mode"} ne "NAME" and not $this->{"interested_head1s"}{$this->{"Mode"} // ""} 1 9 10
Condition40%4/10
$this->{"Mode"} ne "NAME" and not $this->{"interested_head1s"}{$this->{"Mode"} // ""}
!ll&&!rl&&r
000
$this->{"Mode"} // ""
l!l
00
$this->{"Mode"} ne "NAME" and not $this->{"interested_head1s"}{$this->{"Mode"} // ""}
!ll&&!rl&&r
361
$this->{"Mode"} // ""
l!l
70
MC/DC0%0/2
$this->{"Mode"} ne "NAME" and not $this->{"interested_head1s"}{$this->{"Mode"} // ""}
$this->{"Mode"} ne "NAME" not $this->{"interested_head1s"}{$this->{"Mode"} // ""}
MC/DC0%0/1
$this->{"Mode"} // ""
$this->{"Mode"}
MC/DC100%2/2
$this->{"Mode"} ne "NAME" and not $this->{"interested_head1s"}{$this->{"Mode"} // ""}
$this->{"Mode"} ne "NAME" not $this->{"interested_head1s"}{$this->{"Mode"} // ""}
MC/DC0%0/1
$this->{"Mode"} // ""
$this->{"Mode"}
Truth table0%0/3
A and not(B)
A= $this->{"Mode"} ne "NAME"B= not $this->{"interested_head1s"}{$this->{"Mode"} // ""}
ABresult
0X0
100
111
Truth table0%0/2
A
A= $this->{"Mode"}
Aresult
11
00
Truth table100%3/3
A and not(B)
A= $this->{"Mode"} ne "NAME"B= not $this->{"interested_head1s"}{$this->{"Mode"} // ""}
ABresult
0X0
100
111
Truth table50%1/2
A
A= $this->{"Mode"}
Aresult
11
00
138 0 $this->checkmode($text);
139 0 $this->{Parmode} = 'Body'; # and reset parmode
140 }
141  
142 13 ▶sub checkmode {
Subroutine checkmode: called CC=10 SCAR=33.6
143 0 ▶ my ($this,$txt,$verbatim) = @_;
Subroutine checkmode: not called CC=10 SCAR=33.6
144 0 ▶ if ($this->{Mode} =~ /NAME/ && $this->{Parmode} =~ /NAME/) {
Branch: 2 branches
BranchTrueFalseTotal
if ($this->{"Mode"} =~ /NAME/ and $this->{"Parmode"} =~ /NAME/) 0 0 0
if ($this->{"Mode"} =~ /NAME/ and $this->{"Parmode"} =~ /NAME/) 3 10 13
Condition33%2/6
$this->{"Mode"} =~ /NAME/ and $this->{"Parmode"} =~ /NAME/
!ll&&!rl&&r
000
$this->{"Mode"} =~ /NAME/ and $this->{"Parmode"} =~ /NAME/
!ll&&!rl&&r
1003
MC/DC0%0/2
$this->{"Mode"} =~ /NAME/ and $this->{"Parmode"} =~ /NAME/
$this->{"Mode"} =~ /NAME/ $this->{"Parmode"} =~ /NAME/
MC/DC50%1/2
$this->{"Mode"} =~ /NAME/ and $this->{"Parmode"} =~ /NAME/
$this->{"Mode"} =~ /NAME/ $this->{"Parmode"} =~ /NAME/
Truth table0%0/3
A and B
A= $this->{"Mode"} =~ /NAME/B= $this->{"Parmode"} =~ /NAME/
ABresult
0X0
100
111
Truth table66%2/3
A and B
A= $this->{"Mode"} =~ /NAME/B= $this->{"Parmode"} =~ /NAME/
ABresult
0X0
100
111
145 0 ▶ $this->{NAME} = $1 if $this->trim($txt) =~ /^\s*(\S+)\s*/;
Branch: 2 branches
BranchTrueFalseTotal
if $this->trim($txt) =~ /^\s*(\S+)\s*/ 0 0 0
if $this->trim($txt) =~ /^\s*(\S+)\s*/ 3 0 3
146 0 ▶ print "\nNAME\t$this->{NAME}\n" if $this->{verbose};
Branch: 2 branches
BranchTrueFalseTotal
if $this->{"verbose"} 0 0 0
if $this->{"verbose"} 0 3 3
147 0 $this->{Parmode} = 'Body';
148 0 return;
149 }
150 0 ▶ unless ($this->{Parmode} =~ /Body/) {
Branch: 2 branches
BranchTrueFalseTotal
unless ($this->{"Parmode"} =~ /Body/) 0 0 0
unless ($this->{"Parmode"} =~ /Body/) 9 1 10
151 0 my $func = $this->{CURFUNC};
152 0 ▶ die "no function defined\n" unless defined $func;
Branch: 2 branches
BranchTrueFalseTotal
unless defined $func 0 0 0
unless defined $func 0 9 9
153 $this->{SYMHASH}{$func}{$this->{Parmode}} .=
154 0 $this->trim($txt,$verbatim);
155 0 ▶ my $cr = ($verbatim && $this->{Parmode} ne 'Sig') ? "\n" : "";
Branch: 2 branches
BranchTrueFalseTotal
$verbatim && $this->{'Parmode'} ne 'Sig' ? : 0 0 0
$verbatim && $this->{'Parmode'} ne 'Sig' ? : 3 6 9
Condition50%3/6
$verbatim and $this->{"Parmode"} ne "Sig"
!ll&&!rl&&r
000
$verbatim and $this->{"Parmode"} ne "Sig"
!ll&&!rl&&r
513
MC/DC0%0/2
$verbatim and $this->{"Parmode"} ne "Sig"
$verbatim $this->{"Parmode"} ne "Sig"
MC/DC100%2/2
$verbatim and $this->{"Parmode"} ne "Sig"
$verbatim $this->{"Parmode"} ne "Sig"
Truth table0%0/3
A and B
A= $verbatimB= $this->{"Parmode"} ne "Sig"
ABresult
0X0
100
111
Truth table100%3/3
A and B
A= $verbatimB= $this->{"Parmode"} ne "Sig"
ABresult
0X0
100
111
156 0 my $out = "\n\t\t$cr".$this->trim($txt,$verbatim);
157 0 ▶ print "$out\n$cr" if $this->{verbose};
Branch: 2 branches
BranchTrueFalseTotal
if $this->{"verbose"} 0 0 0
if $this->{"verbose"} 0 9 9
158 }
159 0 $this->{Parmode} = 'Body';
160 }
161  
162 4 ▶sub cmd_verbatim {
Subroutine cmd_verbatim: called CC=3 SCAR=16.8
163 0 ▶ my ($this, $attrs, $text) = @_;
Subroutine cmd_verbatim: not called CC=3 SCAR=16.8
164 0 ▶ return if !$this->{interested_head1s}{$this->{Mode} // ''};
Branch: 2 branches
BranchTrueFalseTotal
unless $this->{"interested_head1s"}{$this->{"Mode"} // ""} 0 0 0
unless $this->{"interested_head1s"}{$this->{"Mode"} // ""} 0 4 4
Condition25%1/4
$this->{"Mode"} // ""
l!l
00
$this->{"Mode"} // ""
l!l
40
MC/DC0%0/1
$this->{"Mode"} // ""
$this->{"Mode"}
MC/DC0%0/1
$this->{"Mode"} // ""
$this->{"Mode"}
Truth table0%0/2
A
A= $this->{"Mode"}
Aresult
11
00
Truth table50%1/2
A
A= $this->{"Mode"}
Aresult
11
00
165 0 $this->checkmode($text,1);
166 }
167  
168 # this needs improvement
169 # and any formatting information should be removed?
170 # it probably depends
171 21 ▶sub trim {
Subroutine trim: called CC=8 SCAR=28.3
172 0 ▶ my ($this,$txt,$verbatim) = @_;
Subroutine trim: not called CC=8 SCAR=28.3
173 0 my $ntxt = "";
174 $txt =~ s/(signature|usage):\s*//i if $this->{Parmode} eq 'Sig' ||
175 0 ▶ $this->{Parmode} eq 'Usage';
Branch: 2 branches
BranchTrueFalseTotal
if $this->{"Parmode"} eq "Sig" or $this->{"Parmode"} eq "Usage" 0 0 0
if $this->{"Parmode"} eq "Sig" or $this->{"Parmode"} eq "Usage" 4 17 21
Condition50%3/6
$this->{"Parmode"} eq "Sig" or $this->{"Parmode"} eq "Usage"
l!l&&r!l&&!r
000
$this->{"Parmode"} eq "Sig" or $this->{"Parmode"} eq "Usage"
l!l&&r!l&&!r
2217
MC/DC0%0/2
$this->{"Parmode"} eq "Sig" or $this->{"Parmode"} eq "Usage"
$this->{"Parmode"} eq "Sig" $this->{"Parmode"} eq "Usage"
MC/DC100%2/2
$this->{"Parmode"} eq "Sig" or $this->{"Parmode"} eq "Usage"
$this->{"Parmode"} eq "Sig" $this->{"Parmode"} eq "Usage"
Truth table0%0/3
A or B
A= $this->{"Parmode"} eq "Sig"B= $this->{"Parmode"} eq "Usage"
ABresult
1X1
011
000
Truth table100%3/3
A or B
A= $this->{"Parmode"} eq "Sig"B= $this->{"Parmode"} eq "Usage"
ABresult
1X1
011
000
176 0 ▶ if ($this->{Parmode} eq 'Sig') {
Branch: 2 branches
BranchTrueFalseTotal
if ($this->{"Parmode"} eq "Sig") 0 0 0
if ($this->{"Parmode"} eq "Sig") 2 19 21
177 0 $txt =~ s/^\s*//;
178 0 $txt =~ s/\s*$//;
179 0 ▶ while( $txt =~ s/^\((.*)\)$/$1/ ) {}; # Strip BALANCED brackets
Branch: 2 branches
BranchTrueFalseTotal
if ($txt =~ s/^\((.*)\)$/$1/) 0 0 0
if ($txt =~ s/^\((.*)\)$/$1/) 2 2 4
180 }
181 0 for (split "\n", $txt) {
182 0 ▶ s/^\s*(.*)\s*$/$1/ unless $verbatim;
Branch: 2 branches
BranchTrueFalseTotal
unless $verbatim 0 0 0
unless $verbatim 15 12 27
183 0 ▶ $ntxt .= "$_\n" unless m/^\s*$/;
Branch: 2 branches
BranchTrueFalseTotal
unless /^\s*$/ 0 0 0
unless /^\s*$/ 27 0 27
184 }
185 # $txt =~ s/^\s*(.*)\s*$/$1/;
186 0 chomp $ntxt;
187 0 return $ntxt;
188 }
189  
190 =head1 NAME
191  
192 PDL::Doc - support for PDL online documentation
193  
194 =head1 SYNOPSIS
195  
196 use PDL::Doc;
197 $onlinedc = PDL::Doc->new($docfile);
198 @match = $onlinedc->search('m/slice|clump/');
199  
200 =head1 DESCRIPTION
201  
202 An implementation of online docs for PDL.
203  
204 =head1 Using PDL documentation
205  
206 PDL::Doc's main use is in the "help" (synonym "?") and "apropos"
207 (synonym "??") commands in the perldl shell. PDL::Doc provides the
208 infrastrucure to index and access PDL's documentation through these
209 commands. There is also an API for direct access to the documentation
210 database (see below).
211  
212 The PDL doc system is built on Perl's pod (Plain Old Documentation),
213 included inline with each module. The PDL core modules are
214 automatically indexed when PDL is built and installed, and there is
215 provision for indexing external modules as well.
216  
217 To include your module's pod into the Perl::Doc index, you should
218 follow the documentation conventions below.
219  
220 =head1 PDL documentation conventions
221  
222 For a package like PDL that has I<a lot> of functions it
223 is very desirable to have some form of online help to
224 make it easy for users to remind themselves of names,
225 calling conventions and typical usage of the multitude
226 of functions at their disposal. To make it straightforward
227 to extract the relevant information from the POD documentation
228 in source files that make up the PDL distribution
229 certain conventions have been adopted in formatting this
230 documentation.
231  
232 The first convention says that all documentation for
233 PDL functions appears in the POD section introduced
234 by one of the following:
235  
236 =head1 FUNCTIONS
237 =head1 OPERATORS
238 =head1 METHODS
239 =head1 CONSTRUCTORS
240  
241 If you're documenting an object-oriented interface to a class
242 that your module defines, you should use METHODS and CONSTRUCTORS
243 as appropriate. If you are simply adding functions to PDL,
244 use FUNCTIONS and OPERATORS as appropriate.
245  
246 Individual functions or methods in these section are introduced by
247  
248 =head2 funcname
249  
250 where signature is the argumentlist for a PP defined function as
251 explained in L<PDL::PP>. Generally, PDL documentation is in valid POD
252 format (see L<perlpod>) but uses the C<=for> directive in a
253 special (and non-conformant) way. The C<=for> directive is used to
254 flag to the PDL Pod
255 parser that information is following that will be used to generate
256 online help. In the POD standard, C<=for> is used to provide
257 information in I<that> paragraph. PDL uses it to signal information
258 is in the I<following> paragraph.
259  
260 The PDL Pod parser recognises the following C<=for> directives:
261  
262 =over 5
263  
264 =item Ref
265  
266 indicates that the one line reference for this function follows,
267 e.g.,
268  
269 =for ref
270  
271 Returns an ndarray of lags to parent.
272  
273 =item Sig
274  
275 the signature for the current function follows, e.g.,
276  
277 =for sig
278  
279 Signature: (a(n), [o]b(), [t]tmp(n))
280  
281 =item Usage
282  
283 an indication of the possible calling conventions for the current
284 function, e.g.,
285  
286 =for usage
287  
288 wpic($pdl,$filename[,{ options... }])
289  
290 =item Options
291  
292 lists options for the current function, e.g.,
293  
294 =for options
295  
296 CONVERTER => 'ppmtogif', # explicitly specify pbm converter
297 FLAGS => '-interlaced -transparent 0', # flags for converter
298 IFORM => 'PGM', # explicitly specify intermediate format
299 XTRAFLAGS => '-imagename iris', # additional flags to defaultflags
300 FORMAT => 'PCX', # explicitly specify output image format
301 COLOR => 'bw', # specify color conversion
302 LUT => $lut, # use color table information
303  
304  
305 =item Example
306  
307 gives examples of typical usage for the current function:
308  
309 =for example
310  
311 wpic $pdl, $file;
312 $im->wpic('web.gif',{LUT => $lut});
313 for (@images) {
314 $_->wpic($name[0],{CONVERTER => 'ppmtogif'})
315 }
316  
317 =item Bad
318  
319 provides information on how the function handles bad values. The
320 documentation under this directive should indicate if this function
321 accepts ndarrays with bad values and under what circumstances this function
322 might return ndarrays with bad values.
323  
324 =back
325  
326 The PDL podparser is implemented as a simple state machine. Any of
327 the above C<=for> statements switches the podparser into a state
328 where the following paragraph is accepted as information for the
329 respective field (C<Ref>, C<Usage>, C<Opt>, C<Example> or C<Bad>).
330 Only the text up to
331 the end of the current paragraph is accepted, for example:
332  
333 =for example
334  
335 ($x,$y) = $z->func(1,3); # this is part of the accepted info
336 $x = func($z,0,1); # this as well
337  
338 $x = func($c,$d); # but this isn't
339  
340 To make the resulting pod documentation also easily digestible for the
341 existing pod filters (pod2man, pod2text, pod2html, etc) the actual
342 textblock of information must be separated from the C<=for> directive
343 by at least one blank line. Otherwise, the textblock will be lost in
344 the translation process when the "normal" podformatters are used. The
345 general idea behind this format is that it should be easy to extract
346 the information for online documentation, automatic generation of a
347 reference card, etc but at the same time the documentation should be
348 translated by the standard podformatters without loss of contents
349 (and without requiring any changes in the existing POD format).
350  
351 The preceding explanations should be further explained by the
352 following example (extracted from PDL/IO/Misc/misc.pd):
353  
354 =head2 rcols()
355  
356 =for ref
357  
358 Read ASCII whitespaced cols from file into ndarrays efficiently.
359  
360 If no columns are specified all are assumed
361 Will optionally only process lines matching a pattern.
362 Can take file name or *HANDLE.
363  
364 =for usage
365  
366 Usage: ($x,$y,...) = rcols(*HANDLE|"filename", ["/pattern/",$col1, $col2,] ...)
367  
368 e.g.,
369  
370 =for example
371  
372 ($x,$y) = rcols 'file1'
373 ($x,$y,$z) = rcols 'file2', "/foo/",3,4
374 $x = PDL->rcols 'file1';
375  
376 Note: currently quotes are required on the pattern.
377  
378  
379 which is translated by, e.g, the standard C<pod2text> converter into:
380  
381 rcols()
382  
383 Read ASCII whitespaced cols from file into ndarrays efficiently.
384  
385 If no columns are specified all are assumed Will optionally only
386 process lines matching a pattern. Can take file name or *HANDLE.
387  
388 Usage: ($x,$y,...) = rcols(*HANDLE|"filename", ["/pattern/",$col1, $col2,] ...)
389  
390 e.g.,
391  
392 ($x,$y) = rcols 'file1'
393 ($x,$y,$z) = rcols 'file2', "/foo/",3,4
394 $x = PDL->rcols 'file1';
395  
396 Note: currently quotes are required on the pattern.
397  
398 It should be clear from the preceding example that readable output
399 can be obtained from this format using the standard converters and
400 the reader will hopefully get a feeling how they can easily intersperse
401 the special C<=for> directives with the normal POD documentation.
402  
403 =head2 Which directives should be contained in the documentation
404  
405 The module documentation should
406 start with the
407  
408 =head1 NAME
409  
410 PDL::Modulename -- do something with ndarrays
411  
412 section (as anyway required by C<pod2man>) since the PDL podparser
413 extracts the name of the module this function belongs to from
414 that section.
415  
416 Each function that is I<not> only for internal use by the module
417 should be documented, introduced with the C<=head2> directive
418 in the C<=head1 FUNCTIONS> section. The only field that every function
419 documented along these lines should have is the I<Ref> field preceding
420 a one line description of its intended functionality (suitable for
421 inclusion in a concise reference card). PP defined functions (see L<PDL::PP>)
422 should have a I<Sig> field stating their signature. To facilitate
423 maintenance of this documentation for such functions the 'Doc' field
424 has been introduced into the definition of C<pp_def> (see again L<PDL::PP>)
425 which will take care that name and signature of the so defined function
426 are documented in this way (for examples of this usage see, for example,
427 L<PDL::Slices>.
428 Similarly, the 'BadDoc' field provides a means of
429 specifying information on how the routine handles the presence of
430 bad values: this will be automatically created if
431 C<BadDoc> is not supplied, or set to C<undef>.
432  
433 Furthermore, the documentation for each function should contain
434 at least one of the I<Usage> or I<Examples> fields. Depending on the
435 calling conventions for the function under consideration presence
436 of both fields may be warranted.
437  
438 If a function has options that should be given as a hash reference in
439 the form
440  
441 {Option => Value, ...}
442  
443 then the possible options (and aproppriate values) should be explained
444 in the textblock following the C<=for Opt> directive (see example above
445 and, e.g., PDL::IO::Pic).
446  
447 It is well possible that some of these conventions appear to be clumsy
448 at times and the author is keen to hear of any suggestions for better
449 alternatives.
450  
451 =cut
452  
453 package PDL::Doc;
454 1 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
455 1 ▶use warnings;
Subroutine BEGIN: called CC=1 SCAR=0.0
456 1 ▶use Carp qw(confess);
Subroutine BEGIN: called CC=1 SCAR=0.0
457 1 ▶use File::Basename;
Subroutine BEGIN: called CC=1 SCAR=0.0
458 1 ▶use File::Spec::Functions qw(file_name_is_absolute abs2rel rel2abs catdir catfile);
Subroutine BEGIN: called CC=1 SCAR=0.0
459 1 ▶use Cwd (); # to help Debian packaging
Subroutine BEGIN: called CC=1 SCAR=0.0
460 1 ▶use Config;
Subroutine BEGIN: called CC=1 SCAR=0.0
461 1 ▶use Encode;
Subroutine BEGIN: called CC=1 SCAR=0.0
462  
463 our $pager = $ENV{PERLDOC_PAGER} // $ENV{PAGER} // $Config{pager};
464  
465 =head1 METHODS
466  
467 =head2 new
468  
469 $onlinedc = PDL::Doc->new('file.pdl',[more files]);
470  
471 =cut
472  
473 0 ▶sub new {
Subroutine new: not called CC=1 SCAR=6.9
Pod documented
474 0 ▶ my ($type,@files) = @_;
Subroutine new: not called CC=1 SCAR=6.9
Pod documented
475 0 my $this = bless {},$type;
476 0 $this->{File} = \@files;
477 0 $this->{Scanned} = [];
478 0 $this;
479 }
480  
481 =head2 new_from_hash
482  
483 $onlinedc = PDL::Doc->new_from_hash(\%hash);
484  
485 The hash must conform to the 3-level hash format.
486  
487 =cut
488  
489 1 ▶sub new_from_hash {
Subroutine new_from_hash: called CC=1 SCAR=1.2
Pod documented
490 0 ▶ my ($type, $hash) = @_;
Subroutine new_from_hash: not called CC=1 SCAR=1.2
Pod documented
491 0 my $this = bless {},$type;
492 0 $this->{File} = [];
493 0 $this->{Scanned} = [];
494 0 $this->{SYMS} = $hash;
495 0 $this;
496 }
497  
498 =head2 addfiles
499  
500 add another file to the online database associated with this object.
501  
502 =cut
503  
504 0 ▶sub addfiles {
Subroutine addfiles: not called CC=1 SCAR=6.9
Pod documented
505 0 ▶ my ($this,@files) = @_;
Subroutine addfiles: not called CC=1 SCAR=6.9
Pod documented
506 0 push @{$this->{File}}, @files;
507 }
508  
509 =head2 ensuredb
510  
511 Make sure that the database is slurped in
512  
513 =cut
514  
515 1 ▶sub ensuredb {
Subroutine ensuredb: called CC=4 SCAR=25.8
Pod documented
516 0 ▶ my ($this) = @_;
Subroutine ensuredb: not called CC=4 SCAR=25.8
Pod documented
517 0 ▶ while (my $fi = pop @{$this->{File}}) {
Branch: 2 branches
BranchTrueFalseTotal
if (my $fi = pop @{$$this{"File"};}) 0 0 0
if (my $fi = pop @{$$this{"File"};}) 0 1 1
518 0 ▶ open my $fh, $fi or confess "can't open database $fi, scan docs first";
Branch: 2 branches
BranchTrueFalseTotal
open my $fh, $fi or confess("can't open database $fi, scan docs first") 0 0 0
open my $fh, $fi or confess("can't open database $fi, scan docs first") 0 0 0
519 0 my $got_hash = decodedb($fh, $fi);
520 0 ▶ merge_hash($this->{SYMS} ||= {}, $got_hash);
Condition0%0/4
$this->{"SYMS"} ||= {}
l!l
00
$this->{"SYMS"} ||= {}
l!l
00
MC/DC0%0/1
$this->{"SYMS"} ||= {}
$this->{"SYMS"}
MC/DC0%0/1
$this->{"SYMS"} ||= {}
$this->{"SYMS"}
Truth table0%0/2
A
A= $this->{"SYMS"}
Aresult
11
00
Truth table0%0/2
A
A= $this->{"SYMS"}
Aresult
11
00
521 0 push @{$this->{Scanned}}, $fi;
522 }
523 0 return $this->{SYMS};
524 }
525  
526 =head2 savedb
527  
528 save the database (i.e., the hash of PDL symbols) to the file associated
529 with this object. As of 2.105, you B<must> supply the output file.
530  
531 =cut
532  
533 0 ▶sub savedb {
Subroutine savedb: not called CC=3 SCAR=24.8
Pod documented
534 0 ▶ my ($this, $outfile) = @_;
Subroutine savedb: not called CC=3 SCAR=24.8
Pod documented
535 0 ▶ confess "savedb: no \$outfile" if !defined $outfile;
Branch: 2 branches
BranchTrueFalseTotal
unless defined $outfile 0 0 0
unless defined $outfile 0 0 0
536 0 my $hash = $this->ensuredb;
537 0 ▶ open my $fh, '>', $outfile or confess "can't write to symdb $outfile: $!";
Branch: 2 branches
BranchTrueFalseTotal
open my $fh, ">", $outfile or confess("can't write to symdb ${outfile}: $!") 0 0 0
open my $fh, ">", $outfile or confess("can't write to symdb ${outfile}: $!") 0 0 0
538 0 encodedb($hash, $fh, dirname($outfile));
539 }
540  
541 =head2 gethash
542  
543 Return the PDL symhash (e.g. for custom search operations). To see what
544 it has stored in it in JSON format:
545  
546 perl -MPDL::Doc -MJSON::PP -e \
547 'print encode_json +PDL::Doc->new(PDL::Doc::find_dbs())->gethash' |
548 json_pp -json_opt pretty,canonical
549  
550 The symhash is a multiply nested hash ref with the following structure:
551  
552 $symhash = {
553 function_name => {
554 module::name => {
555 Module => 'module::name',
556 Sig => 'signature string',
557 Bad => 'bad documentation string',
558 ...
559 },
560 },
561 function_name => {
562 module::name => {
563 Module => 'module::name',
564 Sig => 'signature string',
565 Bad => 'bad documentation string',
566 ...
567 },
568 },
569 };
570  
571 The three-layer structure is designed to allow the symhash (and the
572 underlying database) to handle functions that have the same name but
573 reside in different module namespaces.
574  
575 The possible keys for each function/module entry include:
576  
577 Module - module name
578 Sig - signature
579 Crossref - the function name for the documentation, if it has multiple
580 names (ex: the documentation for zeros is under zeroes)
581 Names - a comma-separated string of all the function's names
582 Example - example text (optional)
583 Ref - one-line reference string
584 Opt - options
585 Usage - short usage explanation
586 Bad - explanation of behavior when it encounters bad values
587  
588 =cut
589  
590 0 ▶sub gethash { $_[0]->ensuredb }
Subroutine gethash: not called CC=1 SCAR=6.9
Pod documented
591  
592 =head2 search
593  
594 Search a PDL symhash
595  
596 =for usage
597  
598 $onldc->search($regex, $fields [, $sort])
599  
600 Searching is by default case insensitive. Other flags can be
601 given by specifying the regexp in the form C<m/regex/ismx>
602 where C</> can be replaced with any other non-alphanumeric
603 character. $fields is an array reference for all hash fields
604 (or simply a string if you only want to search one field)
605 that should be matched against the regex. Valid fields are
606  
607 Name, # name of the function
608 Module, # module the function belongs to
609 Ref, # the one-line reference description
610 Example, # the example for this function
611 Opt, # options
612 File, # the path to the source file these docs have been extracted from
613  
614 If you wish to have your results sorted by function name, pass a true
615 value for C<$sort>.
616  
617 The results will be returned as an array of triplets in the form
618  
619 @results = (
620 [funcname, module, {SYMHASH_ENTRY}],
621 [funcname, module, {SYMHASH_ENTRY}],
622 ...
623 );
624  
625 See the example at the end of the documentation to see how you might
626 use this.
627  
628 =cut
629  
630  
631 sub search {
632 1 ▶ my ($this,$pattern,$fields,$sort) = @_;
Subroutine search: called CC=14 SCAR=29.3
Pod documented
633 1 ▶ $sort = 0 unless defined $sort;
Branch: 1 branch
BranchTrueFalseTotal
unless defined $sort 0 1 1
634 1 my $hash = $this->ensuredb;
635 1 my @match = ();
636  
637 # Make a single scalar $fields work
638 1 ▶ $fields = [$fields] if ref($fields) eq '';
Branch: 1 branch
BranchTrueFalseTotal
if ref $fields eq "" 0 1 1
639  
640 1 $pattern = $this->checkregex($pattern);
641  
642 1 ▶ while (my ($name,$mods_hash) = each %$hash) {
Branch: 1 branch
BranchTrueFalseTotal
if (() = each %$hash) 2 1 3
643 2 ▶ while (my ($module,$val) = each %$mods_hash) {
Branch: 1 branch
BranchTrueFalseTotal
if (() = each %$mods_hash) 2 2 4
644 2 FIELD: for (@$fields) {
645 2 ▶ if ($_ eq 'Name' and $name =~ /$pattern/i
Branch: 1 branch
BranchTrueFalseTotal
if ($_ eq "Name" and $name =~ /$pattern/i or defined $val->{$_} and $val->{$_} =~ /$pattern/i) 1 1 2
Condition55%5/9
$_ eq "Name" and $name =~ /$pattern/i or defined $val->{$_} and $val->{$_} =~ /$pattern/i
l!l&&r!l&&!r
011
$_ eq "Name" and $name =~ /$pattern/i
!ll&&!rl&&r
200
defined $val->{$_} and $val->{$_} =~ /$pattern/i
!ll&&!rl&&r
011
MC/DC25%1/4
$_ eq "Name" and $name =~ /$pattern/i or defined $val->{$_} and $val->{$_} =~ /$pattern/i
$_ eq "Name" $name =~ /$pattern/i defined $val->{$_} $val->{$_} =~ /$pattern/i
Truth table28%2/7
A and B or C and D
A= $_ eq "Name"B= $name =~ /$pattern/iC= defined $val->{$_}D= $val->{$_} =~ /$pattern/i
ABCDresult
11XX1
0X111
10111
0X0X0
0X100
100X0
10100
646 or defined $val->{$_} and $val->{$_} =~ /$pattern/i
647 ) {
648 $val = $hash->{$val->{Crossref}}{$module} #we're going to assume that any Crossref'd documentation is also in this module
649 1 ▶ if defined $val->{Crossref} && defined $hash->{$val->{Crossref}}{$module};
Branch: 1 branch
BranchTrueFalseTotal
if defined $val->{"Crossref"} and defined $$hash{$val->{"Crossref"}}{$module} 0 1 1
Condition33%1/3
defined $val->{"Crossref"} and defined $$hash{$val->{"Crossref"}}{$module}
!ll&&!rl&&r
100
MC/DC0%0/2
defined $val->{"Crossref"} and defined $$hash{$val->{"Crossref"}}{$module}
defined $val->{"Crossref"} defined $$hash{$val->{"Crossref"}}{$module}
Truth table33%1/3
A and B
A= defined $val->{"Crossref"}B= defined $$hash{$val->{"Crossref"}}{$module}
ABresult
0X0
100
111
650 1 push @match, [$name,$module,$val];
651 1 last FIELD;
652 }
653 }
654 }
655 }
656 0 ▶ @match = sort {$a->[0] cmp $b->[0]} @match if (@match && $sort);
Branch: 1 branch
BranchTrueFalseTotal
if @match and $sort 1 0 1
Condition33%1/3
@match and $sort
!ll&&!rl&&r
001
MC/DC0%0/2
@match and $sort
@match $sort
Truth table33%1/3
A and B
A= @matchB= $sort
ABresult
0X0
100
111
657 1 return @match;
658 }
659  
660  
661 # parse a regexp in the form
662 # m/^[a-z]+/ismx
663 # where the pairs of '/' can be replaced by any other pair of matching
664 # characters
665 # if the expression doesn't start with 'm' followed by a nonalphanumeric
666 # character, return as-is
667 sub checkregex {
668 1 ▶ my ($this,$regex) = @_;
Subroutine checkregex: called CC=5 SCAR=29.7
Pod undocumented
669 1 ▶ return "(?i)$regex" unless $regex =~ /^m[^a-z,A-Z,0-9]/;
Branch: 1 branch
BranchTrueFalseTotal
unless $regex =~ /^m[^a-z,A-Z,0-9]/ 1 0 1
670 0 my $sep = substr($regex,1,1);
671 0 substr($regex,0,2) = '';
672 0 $sep = '(?<!\\\\)\\'.$sep; # Avoid '\' before the separator
673  
674 0 my ($pattern,$mod) = split($sep,$regex,2);
675 0 ▶ confess "unknown regex modifiers '$mod'" if $mod && $mod !~ /[imsx]+/;
Branch: 1 branch
BranchTrueFalseTotal
if $mod and not $mod =~ /[imsx]+/ 0 0 0
Condition0%0/3
$mod and not $mod =~ /[imsx]+/
!ll&&!rl&&r
000
MC/DC0%0/2
$mod and not $mod =~ /[imsx]+/
$mod not $mod =~ /[imsx]+/
Truth table0%0/3
A and not(B)
A= $modB= not $mod =~ /[imsx]+/
ABresult
0X0
100
111
676 0 ▶ $pattern = "(?$mod)$pattern" if $mod;
Branch: 1 branch
BranchTrueFalseTotal
if $mod 0 0 0
677 0 return $pattern;
678 }
679  
680 =head2 scan
681  
682 Scan a source file using the PDL podparser to extract information
683 for online documentation
684  
685 =cut
686  
687 sub scan {
688 0 ▶ my ($this,$file,$verbose) = @_;
Subroutine scan: not called CC=6 SCAR=37.4
Pod documented
689 0 ▶ confess "can't find file '$file'" unless -f $file;
Branch: 1 branch
BranchTrueFalseTotal
unless -f $file 0 0 0
690 0 $file = Cwd::abs_path($file); # help Debian packaging
691 0 ▶ $verbose //= 0;
Condition0%0/2
$verbose //= 0
l!l
00
MC/DC0%0/1
$verbose //= 0
$verbose
Truth table0%0/2
A
A= $verbose
Aresult
11
00
692 0 ▶ my $text = do { open my $infile, '<', $file or die "$file: $!"; local $/; <$infile> };
Branch: 1 branch
BranchTrueFalseTotal
open my $infile, "<", $file or die "${file}: $!" 0 0 0
693 # Handle RPM etc. case where we are building away from the final location
694 0 my $file2 = $file;
695 0 ▶ $file2 =~ s/^$ENV{BUILDROOTPREFIX}// if $ENV{BUILDROOTPREFIX};
Branch: 1 branch
BranchTrueFalseTotal
if $ENV{"BUILDROOTPREFIX"} 0 0 0
696 0 my $mod_hash = scantext($text, $file2, $verbose);
697 0 ▶ merge_hash($this->{SYMS} ||= {}, $mod_hash);
Condition0%0/2
$this->{"SYMS"} ||= {}
l!l
00
MC/DC0%0/1
$this->{"SYMS"} ||= {}
$this->{"SYMS"}
Truth table0%0/2
A
A= $this->{"SYMS"}
Aresult
11
00
698 0 scalar values %$mod_hash; # how many functions found
699 }
700  
701 =head2 scantree
702  
703 Scan whole directory trees for online documentation in
704 C<.pm> (module definition) and C<*.pod> (general
705 documentation) files (using the File::Find module).
706  
707 =cut
708  
709 sub scantree {
710 0 ▶ my ($this,$dir,$verbose) = @_;
Subroutine scantree: not called CC=5 SCAR=34.0
Pod documented
711 0 ▶ if (!-d $dir) {
Branch: 1 branch
BranchTrueFalseTotal
unless (-d $dir) 0 0 0
712 0 ▶ print "$dir not found\n" if $verbose;
Branch: 1 branch
BranchTrueFalseTotal
if $verbose 0 0 0
713 0 return 0;
714 }
715 0 ▶ $verbose //= 0;
Condition0%0/2
$verbose //= 0
l!l
00
MC/DC0%0/1
$verbose //= 0
$verbose
Truth table0%0/2
A
A= $verbose
Aresult
11
00
716 0 require File::Find;
717 0 ▶ print "Scanning $dir ... \n\n" if $verbose;
Branch: 1 branch
BranchTrueFalseTotal
if $verbose 0 0 0
718 0 my $ntot = 0;
719 my $sub = sub {
720 0 ▶ return if -d $File::Find::name;
Subroutine __ANON__: not called CC=8 SCAR=42.8
Branch: 1 branch
BranchTrueFalseTotal
if -d $File::Find::name 0 0 0
721 return if
722 0 ▶ $File::Find::dir !~ /script$/ and
Branch: 1 branch
BranchTrueFalseTotal
unless $File::Find::dir =~ /script$/ or $File::Find::name =~ /\.(?:pm|pod)$/ 0 0 0
Condition0%0/3
$File::Find::dir =~ /script$/ or $File::Find::name =~ /\.(?:pm|pod)$/
l!l&&r!l&&!r
000
MC/DC0%0/2
$File::Find::dir =~ /script$/ or $File::Find::name =~ /\.(?:pm|pod)$/
$File::Find::dir =~ /script$/ $File::Find::name =~ /\.(?:pm|pod)$/
Truth table0%0/3
A or B
A= $File::Find::dir =~ /script$/B= $File::Find::name =~ /\.(?:pm|pod)$/
ABresult
1X1
011
000
723 $File::Find::name !~ /\.(?:pm|pod)$/;
724 0 ▶ return if $File::Find::name =~ /(?:PP\.pm)$/ or
Branch: 1 branch
BranchTrueFalseTotal
if $File::Find::name =~ /(?:PP\.pm)$/ or $File::Find::dir =~ m[/PP] 0 0 0
Condition0%0/3
$File::Find::name =~ /(?:PP\.pm)$/ or $File::Find::dir =~ m[/PP]
l!l&&r!l&&!r
000
MC/DC0%0/2
$File::Find::name =~ /(?:PP\.pm)$/ or $File::Find::dir =~ m[/PP]
$File::Find::name =~ /(?:PP\.pm)$/ $File::Find::dir =~ m[/PP]
Truth table0%0/3
A or B
A= $File::Find::name =~ /(?:PP\.pm)$/B= $File::Find::dir =~ m[/PP]
ABresult
1X1
011
000
725 $File::Find::dir =~ m#/PP#;
726 0 ▶ printf "%-20s", $_.'...' if $verbose;
Branch: 1 branch
BranchTrueFalseTotal
if $verbose 0 0 0
727 0 $ntot += my $n = $this->scan($File::Find::name,$verbose);
728 0 ▶ print "\t$n functions\n" if $verbose;
Branch: 1 branch
BranchTrueFalseTotal
if $verbose 0 0 0
729 0 };
730 File::Find::find({
731 no_chdir => 1,
732 wanted => $sub,
733 0 ▶ preprocess => sub { sort @_ }
Subroutine __ANON__: not called CC=1 SCAR=6.9
734 0 }, $dir);
735 0 print " found $ntot functions in $dir\n";
736 0 $ntot;
737 }
738  
739  
740 =head2 funcdocs
741  
742 extract the complete documentation about a function from its
743 source file using the PDL::PodParser filter.
744  
745 =cut
746  
747 sub funcdocs {
748 0 ▶ my ($this,$func,$module,$fout) = @_;
Subroutine funcdocs: not called CC=6 SCAR=37.4
Pod documented
749 0 my $hash = $this->ensuredb;
750 0 ▶ confess "unknown function '$func'" unless defined($hash->{$func});
Branch: 1 branch
BranchTrueFalseTotal
unless defined $hash->{$func} 0 0 0
751 0 ▶ confess "funcdocs now requires 3 arguments" if defined fileno $module;
Branch: 1 branch
BranchTrueFalseTotal
if defined fileno $module 0 0 0
752 0 my $file = $hash->{$func}{$module}{File};
753 0 my $dbf = $hash->{$func}{$module}{Dbfile};
754 0 ▶ $file = Cwd::abs_path($file) if file_name_is_absolute($file);
Branch: 1 branch
BranchTrueFalseTotal
if file_name_is_absolute($file) 0 0 0
755 0 $dbf = Cwd::abs_path($dbf); # help Debian packaging
756 0 ▶ $file = rel2abs($file, dirname($dbf))
Branch: 1 branch
BranchTrueFalseTotal
if not file_name_is_absolute($file) and $dbf 0 0 0
Condition0%0/3
not file_name_is_absolute($file) and $dbf
!ll&&!rl&&r
000
MC/DC0%0/2
not file_name_is_absolute($file) and $dbf
not file_name_is_absolute($file) $dbf
Truth table0%0/3
not(A) and B
A= not file_name_is_absolute($file)B= $dbf
ABresult
0X0
100
111
757 if !file_name_is_absolute($file) && $dbf;
758 0 funcdocs_fromfile($func,$file,$fout);
759 }
760  
761 =head1 FUNCTIONS
762  
763 =head2 decodedb
764  
765 $hash = decodedb($fh, $filename);
766  
767 Decode the 3-level hash out of a saved PDL::Doc database.
768  
769 =cut
770  
771 sub decodedb {
772 2 ▶ my ($fh, $filename) = @_;
Subroutine decodedb: called CC=3 SCAR=11.0
Pod documented
773 2 binmode $fh;
774 2 my %hash;
775 2 ▶ while (read $fh, my $plen, 2) {
Branch: 1 branch
BranchTrueFalseTotal
if (read $fh, my $plen, 2) 4 2 6
776 4 my ($len) = unpack "v", $plen;
777 4 read $fh, my($txt), $len;
778 4 $txt = Encode::decode('UTF-8', $txt);
779 4 my ($sym, $module, @a) = split chr(0), $txt;
780 4 ▶ push @a, "" if @a % 2; # Add null string at end if necessary -- solves bug with missing REF section.
Branch: 1 branch
BranchTrueFalseTotal
if @a % 2 0 4 4
781 4 $hash{$sym}{$module} = { @a, Dbfile => $filename }; # keep the origin pdldoc.db path
782 }
783 2 \%hash;
784 }
785  
786 =head2 merge_hash
787  
788 merge_hash(\%pdldoc_into, \%pdldoc_from); # for 3-level hash only
789  
790 Merge a 3-level PDL::Doc hash into another one.
791  
792 =cut
793  
794 sub merge_hash {
795 1 ▶ my ($into, $from) = @_;
Subroutine merge_hash: called CC=3 SCAR=11.0
Pod documented
796 1 for my $func (keys %$from) {
797 1 my $val = $from->{$func};
798 # copy the 3-layer hash/database structure: $into->{funcname}{'PDL::SomeModule'} = {Ref=>...}
799 1 for my $func_mod (keys %$val) {
800 1 $into->{$func}{$func_mod} = $val->{$func_mod};
801 }
802 }
803 }
804  
805 =head2 encodedb
806  
807 encodedb($hash, $fh, $outdir);
808  
809 =cut
810  
811 sub encodedb {
812 2 ▶ my ($hash, $fh, $outdir) = @_;
Subroutine encodedb: called CC=5 SCAR=16.4
Pod documented
813 2 binmode $fh;
814 2 for my $name (sort keys %$hash) {
815 4 my $mods_hash = $hash->{$name};
816 4 for my $module (sort keys %$mods_hash) {
817 4 my $val = $mods_hash->{$module};
818 4 my $fi = $val->{File};
819 4 ▶ $val->{File} = abs2rel($fi, $outdir)
Branch: 1 branch
BranchTrueFalseTotal
if file_name_is_absolute($fi) and -f $fi 0 4 4
Condition33%1/3
file_name_is_absolute($fi) and -f $fi
!ll&&!rl&&r
400
MC/DC0%0/2
file_name_is_absolute($fi) and -f $fi
file_name_is_absolute($fi) -f $fi
Truth table33%1/3
A and B
A= file_name_is_absolute($fi)B= -f $fi
ABresult
0X0
100
111
820 #store paths to *.pm files relative to pdldoc.db
821 if file_name_is_absolute($fi) && -f $fi;
822 4 delete $val->{Dbfile}; # no need to store Dbfile
823 4 my $txt = Encode::encode('UTF-8', join chr(0),$name,$module,map +($_=>$val->{$_}), sort keys %$val);
824 4 print $fh pack("v",length($txt)).$txt;
825 }
826 }
827 }
828  
829 =head2 scantext
830  
831 $hash = scantext($module_text, $filename, $verbose);
832  
833 Scan a single string (intended to be the contents of a file),
834 returning a hash of the functions found therein.
835  
836 =cut
837  
838 sub scantext {
839 3 ▶ my ($text, $filename, $verbose) = @_;
Subroutine scantext: called CC=15 SCAR=29.9
Pod documented
840 3 my $parser = PDL::PodParser->new;
841 3 ▶ $parser->{verbose} = $verbose if ($verbose//0) > 0;
Branch: 1 branch
BranchTrueFalseTotal
if ($verbose // 0) > 0 0 3 3
Condition50%1/2
$verbose // 0
l!l
03
MC/DC0%0/1
$verbose // 0
$verbose
Truth table50%1/2
A
A= $verbose
Aresult
11
00
842 3 open my $outfile, '>', \(my $outfile_text);
843 3 $parser->output_fh($outfile);
844 3 eval { $parser->parse_string_document($text) };
845 3 ▶ warn "cannot parse: $@" if $@ and $@ ne "no function defined\n";
Branch: 1 branch
BranchTrueFalseTotal
if $@ and $@ ne "no function defined\n" 0 3 3
Condition33%1/3
$@ and $@ ne "no function defined\n"
!ll&&!rl&&r
300
MC/DC0%0/2
$@ and $@ ne "no function defined\n"
$@ $@ ne "no function defined\n"
Truth table33%1/3
A and B
A= $@B= $@ ne "no function defined\n"
ABresult
0X0
100
111
846 3 my %hash;
847 3 $_->{File} = $filename for values %{ $parser->{SYMHASH} };
848 3 for my $key (sort keys %{ $parser->{SYMHASH} }) {
849 6 my $val = $parser->{SYMHASH}{$key};
850 #set up the 3-layer hash/database structure: $hash{funcname}{'PDL::SomeModule'} = $val
851 6 ▶ if (defined($val->{Module})) {
Branch: 1 branch
BranchTrueFalseTotal
if (defined $val->{'Module'}) { } 6 0 6
852 6 $hash{$key}{$val->{Module}} = $val;
853 } else {
854 0 warn "no Module for $key in $filename\n";
855 }
856 }
857 # pass2 - scan for module name and function
858 3 $parser = Pod::Simple::PullParser->new;
859 3 $parser->set_source(\$text);
860 3 my $title = eval { $parser->get_title };
861 3 ▶ warn("cannot parse '$filename'"), return \%hash if $@;
Branch: 1 branch
BranchTrueFalseTotal
if $@ 0 3 3
862 3 my ($name,$does) = split /\s*-+\s*/, $title, 2;
863 3 ▶ $does = 'Hmmm ????' if $does and $does =~ /^\s*$/;
Branch: 1 branch
BranchTrueFalseTotal
if $does and $does =~ /^\s*$/ 0 3 3
Condition33%1/3
$does and $does =~ /^\s*$/
!ll&&!rl&&r
030
MC/DC0%0/2
$does and $does =~ /^\s*$/
$does $does =~ /^\s*$/
Truth table33%1/3
A and B
A= $doesB= $does =~ /^\s*$/
ABresult
0X0
100
111
864 3 ▶ my $type =
Branch: 2 branches
BranchTrueFalseTotal
$filename =~ /script/ ? : 0 3 3
$filename =~ /\.pod$/ ? : 1 2 3
865 $filename =~ /script/ ? 'Script:' :
866 $filename =~ /\.pod$/ ? 'Manual:' :
867 'Module:';
868 3 ▶ $hash{$name}{$name} = {Ref=>"$type $does",File=>$filename} if $name and $name !~ /^\s*$/;
Branch: 1 branch
BranchTrueFalseTotal
if $name and not $name =~ /^\s*$/ 3 0 3
Condition33%1/3
$name and not $name =~ /^\s*$/
!ll&&!rl&&r
003
MC/DC0%0/2
$name and not $name =~ /^\s*$/
$name not $name =~ /^\s*$/
Truth table33%1/3
A and not(B)
A= $nameB= not $name =~ /^\s*$/
ABresult
0X0
100
111
869 3 \%hash;
870 }
871  
872 sub funcdocs_fromfile {
873 0 ▶ my ($func,$file) = @_;
Subroutine funcdocs_fromfile: not called CC=5 SCAR=34.0
Pod undocumented
874 0 ▶ confess "can't find file '$file'" unless -f $file;
Branch: 1 branch
BranchTrueFalseTotal
unless -f $file 0 0 0
875 0 ▶ local $SIG{PIPE}= sub {}; # Prevent crashing if user exits the pager
Subroutine __ANON__: not called CC=1 SCAR=6.9
876 0 ▶ open my $in, '<', $file or confess "can't open file $file";
Branch: 1 branch
BranchTrueFalseTotal
open my $in, "<", $file or confess("can't open file $file") 0 0 0
877 0 my $out = $_[2];
878 0 ▶ open $out, "| pod2text | $PDL::Doc::pager" if !defined $out;
Branch: 1 branch
BranchTrueFalseTotal
unless defined $out 0 0 0
879 0 ▶ confess "can't open output handle" unless $out;
Branch: 1 branch
BranchTrueFalseTotal
unless $out 0 0 0
880 0 getfuncdocs($func,$in,$out);
881 0 print $out "Docs from $file\n\n";
882 }
883  
884 sub getfuncdocs {
885 3 ▶ my ($func,$in,$out) = @_;
Subroutine getfuncdocs: called CC=1 SCAR=0.0
Pod undocumented
886 3 my $parser = PDL::Doc::SelectJustPod->new;
887 3 $parser->select_head1s(qw(OPERATORS FUNCTIONS CONSTRUCTORS METHODS));
888 3 $parser->select_head2($func);
889 3 $parser->parse_from_file($in,$out);
890 }
891  
892 =head2 find_dbs
893  
894 =for ref
895  
896 Find the available doc databases for use by PDL::Doc objects.
897  
898 =for usage
899  
900 use PDL::Doc;
901 my $onlinedoc = PDL::Doc->new(PDL::Doc::find_dbs());
902  
903 =cut
904  
905 sub _find_inc {
906 0 ▶ my ($what, $want_dir, $only_one) = @_;
Subroutine _find_inc: not called CC=7 SCAR=40.3
907 0 my @ret;
908 0 for my $dir (@INC) {
909 0 ▶ my $ent = $want_dir ? catdir($dir, @$what) : catfile($dir, @$what);
Branch: 1 branch
BranchTrueFalseTotal
$want_dir ? : 0 0 0
910 0 ▶ push @ret, $ent if $want_dir ? -d $ent : -f $ent;
Branch: 2 branches
BranchTrueFalseTotal
if $want_dir ? -d $ent : -f $ent 0 0 0
$want_dir ? : 0 0 0
911 0 ▶ return @ret if $only_one and @ret;
Branch: 1 branch
BranchTrueFalseTotal
if $only_one and @ret 0 0 0
Condition0%0/3
$only_one and @ret
!ll&&!rl&&r
000
MC/DC0%0/2
$only_one and @ret
$only_one @ret
Truth table0%0/3
A and B
A= $only_oneB= @ret
ABresult
0X0
100
111
912 }
913 0 @ret;
914 }
915  
916 sub find_dbs {
917 0 ▶ my @found = _find_inc([qw(PDL pdldoc.db)], 0, 1); # CORE21 get rid
Subroutine find_dbs: not called CC=6 SCAR=37.4
Pod documented
918 0 my %db_seen;
919 0 for my $dir (_find_inc([qw(PDL Pdldoc)], 1)) {
920 0 ▶ my @c = do { opendir my $dirfh, $dir or die "$dir: $!"; grep !/^\./, readdir $dirfh };
Branch: 1 branch
BranchTrueFalseTotal
opendir my $dirfh, $dir or die "${dir}: $!" 0 0 0
921 0 ▶ for my $f (grep /\.db$/ && -f catfile($dir, $_), @c) {
Condition0%0/3
/\.db$/ && -f catfile($dir, $_)
!ll&&!rl&&r
000
MC/DC0%0/2
/\.db$/ && -f catfile($dir, $_)
/\.db$/ -f catfile($dir, $_)
Truth table0%0/3
A && B
A= /\.db$/B= -f catfile($dir, $_)
ABresult
0X0
100
111
922 0 ▶ next if $db_seen{$f}++; # ignore any later ones in @INC
Branch: 1 branch
BranchTrueFalseTotal
if $db_seen{$f}++ 0 0 0
923 0 push @found, catfile($dir, $f);
924 }
925 }
926 0 @found;
927 }
928  
929 =head2 gen_db
930  
931 =for usage
932  
933 use PDL::Doc;
934 PDL::Doc::gen_db($db_file, $blib_dir, $script_dir);
935  
936 =for ref
937  
938 Generate a C<pdldoc> database into the given location, for just the
939 given directories.
940  
941 Added in 2.106 for the new C<pdldoc> scheme of one database file
942 per distribution in a centralised directory. Replaces C<add_module>.
943 Used by L<PDL::Core::Dev/pdlpp_postamble>.
944  
945 =cut
946  
947 sub gen_db {
948 0 ▶ my ($db_file, @dirs) = @_;
Subroutine gen_db: not called CC=7 SCAR=40.3
Pod documented
949 0 ▶ die "gen_db: No directories given\n" if !@dirs;
Branch: 1 branch
BranchTrueFalseTotal
unless @dirs 0 0 0
950 0 ▶ die "gen_db: No docs database file given\n" if !defined $db_file;
Branch: 1 branch
BranchTrueFalseTotal
unless defined $db_file 0 0 0
951 0 ▶ unlink $db_file if -e $db_file and !-w $db_file;
Branch: 1 branch
BranchTrueFalseTotal
if -e $db_file and not -w $db_file 0 0 0
Condition0%0/3
-e $db_file and not -w $db_file
!ll&&!rl&&r
000
MC/DC0%0/2
-e $db_file and not -w $db_file
-e $db_file not -w $db_file
Truth table0%0/3
A and not(B)
A= -e $db_fileB= not -w $db_file
ABresult
0X0
100
111
952 0 my $pdldoc = PDL::Doc->new;
953 0 my $n = 0;
954 0 $n += $pdldoc->scantree($_) for @dirs;
955 0 ▶ if (!$n) {
Branch: 1 branch
BranchTrueFalseTotal
unless ($n) 0 0 0
956 0 print "PDL docs database $db_file would be empty - stopping.\n";
957 0 return;
958 }
959 0 require File::Basename;
960 0 require File::Path;
961 0 umask 0022;
962 0 File::Path::make_path(File::Basename::dirname($db_file));
963 0 $pdldoc->savedb($db_file);
964 0 print "PDL docs database $db_file created - total $n functions.\n";
965 }
966  
967 =head2 add_module
968  
969 =for ref
970  
971 Replaced with PDL::Core::Dev pdldoc_add in 2.106.
972  
973 As of 2.106, C<pdldoc> documentation is stored in one centrally-installed file per distribution. If your distribution is pure-Perl, you need this in your F<Makefile.PL>:
974  
975 use PDL::Core::Dev;
976 sub MY::postamble { ::pdldoc_add() }
977  
978 If your distribution already has a C<postamble> that calls
979 L<PDL::Core::Dev/pdlpp_postamble>, this will be magically done for
980 you.
981  
982 =cut
983  
984 sub add_module {
985 0 ▶ my ($module) = @_;
Subroutine add_module: not called CC=9 SCAR=45.0
Pod documented
986 0 my ($file) = find_dbs();
987 0 ▶ die "Unable to find docs database - therefore not updating it.\n" if !defined $file;
Branch: 1 branch
BranchTrueFalseTotal
unless defined $file 0 0 0
988 0 ▶ die "No write permission for $file - not updating docs database.\n"
Branch: 1 branch
BranchTrueFalseTotal
unless -w $file 0 0 0
989 if !-w $file;
990 0 print "Found docs database $file\n";
991 0 my $pdldoc = PDL::Doc->new($file);
992 0 my @pkg = my @mfile = split /::/, $module;
993 0 my $mlast = pop @mfile;
994 0 my @found;
995 0 for (qw(.pm .pod)) {
996 0 my @this = _find_inc([@mfile, $mlast.$_], 0, 1);
997 0 ▶ push(@found, @this), last if @this;
Branch: 1 branch
BranchTrueFalseTotal
if @this 0 0 0
998 }
999 0 ▶ die "Unable to find a .pm or .pod file in \@INC for module $module\n" if !@found;
Branch: 1 branch
BranchTrueFalseTotal
unless @found 0 0 0
1000 0 $pdldoc->ensuredb;
1001 0 my $n = 0;
1002 0 $n += $pdldoc->scan($_) for @found;
1003 0 print "Added @found, $n functions.\n";
1004 0 $n += $pdldoc->scantree($_) for _find_inc(\@pkg, 1, 1);
1005 0 eval { $pdldoc->savedb($file); };
1006 0 ▶ warn $@ if $@;
Branch: 1 branch
BranchTrueFalseTotal
if $@ 0 0 0
1007 0 print "PDL docs database updated - total $n functions.\n";
1008 }
1009  
1010 =head1 PDL::DOC EXAMPLE
1011  
1012 Here's an example of how you might use the PDL Doc database in your
1013 own code.
1014  
1015 use PDL::Doc;
1016 # Find the pdl documentation
1017 my ($file) = PDL::Doc::find_dbs();
1018 die "Unable to find docs database!\n" unless defined $file;
1019 print "Found docs database $file\n";
1020 my $pdldoc = PDL::Doc->new($file);
1021 # Print the reference line for zeroes:
1022 print map{$_->{Ref}} values %{$pdldoc->gethash->{zeroes}};
1023 # Or, if you remember that zeroes is in PDL::Core:
1024 print $pdldoc->gethash->{zeroes}{'PDL::Core'}{Ref};
1025  
1026 # Get info for all the functions whose examples use zeroes
1027 my @entries = $pdldoc->search('zeroes','Example',1,1);
1028  
1029 # All the functions that use zeroes in their example:
1030 print "Functions that use 'zeroes' in their examples include:\n";
1031 foreach my $entry (@entries) {
1032 # Unpack the entry
1033 my ($func_name, $module, $sym_hash) = @$entry;
1034 print "$func_name\n";
1035 }
1036 print "\n";
1037  
1038 #Or, more concisely:
1039 print map "$_->[0]\n", @entries;
1040  
1041 # Let's look at the function 'mpdl'
1042 @entries = $pdldoc->search('mpdl', 'Name');
1043 # I know there's only one:
1044 my $entry = $entries[0];
1045 my ($func_name, undef, $sym_hash) = @$entry;
1046 print "mpdl info:\n";
1047 foreach my $key (sort keys %$sym_hash) {
1048 # Unpack the entry
1049 print "---$key---\n$sym_hash->{$key}\n";
1050 }
1051  
1052 =head2 Finding Modules
1053  
1054 How can you tell if you've got a module for one of your entries?
1055 The Ref entry will begin with 'Module:' if it's a module. In code:
1056  
1057 # Prints:
1058 # Module: fundamental PDL functionality and vectorization/broadcasting
1059 print $pdldoc->gethash->{'PDL::Core'}{'PDL::Core'}{Ref}, "\n"
1060  
1061 =head1 BUGS
1062  
1063 Quite a few shortcomings which will hopefully be fixed following
1064 discussions on the pdl-devel mailing list.
1065  
1066 =head1 AUTHOR
1067  
1068 Copyright 1997 Christian Soeller E<lt>c.soeller@auckland.ac.nzE<gt>
1069 and Karl Glazebrook E<lt>kgb@aaoepp.aao.gov.auE<gt>
1070  
1071 Further contributions copyright 2010 David Mertens
1072 E<lt>dcmertens.perl@gmail.comE<gt>
1073  
1074 Documentation database restructuring 2019 Derek Lamb
1075  
1076 All rights reserved. There is no warranty. You are allowed
1077 to redistribute this software / documentation under certain
1078 conditions. For details, see the file COPYING in the PDL
1079 distribution. If this file is separated from the PDL distribution,
1080 the copyright notice should be included in the file.
1081  
1082 =cut
1083  
1084 1;
« blib/lib/PDL/NiceSlice.pm ↑ Summary blib/lib/PDL/Transform/Cartography.pm »