apidocs.perl

filter: Statementstmt 97.4% 113 / 116 Branchbran 76.0% 38 / 50 Conditioncond 88.4% 23 / 26 MC/DCmcdc 81.2% 13 / 16 Subroutinesub 100% 3 / 3 Podpod n/a totaltotal 90.0% 190 / 211 CC 10 SCAR 22.4
CC
10
Cov
91%
make_func_list
11.1
BEGIN
1.0
BEGIN
1.0
CRAP 9.4
« blib/lib/Imager/Matrix2d.pm ↑ Summary blib/lib/Imager/Color/Float.pm »
1 #!perl -w
2 1 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
3 1 ▶use ExtUtils::Manifest 'maniread';
Subroutine BEGIN: called CC=1 SCAR=0.0
4  
5 1 ▶my $outname = shift || '-';
Condition50%1/2
shift @ARGV || '-'
l!l
10
MC/DC0%0/1
shift @ARGV || '-'
shift @ARGV
Truth table50%1/2
A
A= shift @ARGV
Aresult
11
00
6  
7 1 my @funcs = make_func_list();
8 1 my %funcs = map { $_ => 1 } @funcs;
9  
10 # look for files to parse
11  
12 1 my $mani = maniread;
13 1 my @files = sort grep /\.(c|im|h)$/, keys %$mani;
14  
15 # scan each file for =item <func>\b
16 1 my $func;
17 my $start;
18 1 my %alldocs;
19 1 my @funcdocs;
20 1 my %from;
21 1 my $category;
22 1 my %funccats;
23 1 my %cats;
24 1 my $synopsis = '';
25 1 my %funcsyns;
26 my $order;
27 1 my %order;
28 1 for my $file (@files) {
29 105 ▶ open SRC, "< $file"
Branch: 1 branch
BranchTrueFalseTotal
open SRC, "< $file" or die "Cannot open $file for documentation: $!\n" 105 0 105
30 or die "Cannot open $file for documentation: $!\n";
31 105 ▶ while (<SRC>) {
Branch: 1 branch
BranchTrueFalseTotal
if (defined($_ = readline SRC)) 68725 105 68830
32 68725 ▶ if (/^=item (\w+)\b/ && $funcs{$1}) {
Branch: 3 branches
BranchTrueFalseTotal
if (/^=item (\w+)\b/ and $funcs{$1}) { } 167 68558 68725
elsif ($func and /^=(cut|head)/) { } 167 68391 68558
elsif ($func) { } 1729 66662 68391
Condition100%3/3
/^=item (\w+)\b/ and $funcs{$1}
!ll&&!rl&&r
68126432167
MC/DC100%2/2
/^=item (\w+)\b/ and $funcs{$1}
/^=item (\w+)\b/ $funcs{$1}
Truth table100%3/3
A and B
A= /^=item (\w+)\b/B= $funcs{$1}
ABresult
0X0
100
111
33 167 $func = $1;
34 167 $start = $.;
35 167 @funcdocs = $_;
36 }
37 ▶ elsif ($func && /^=(cut|head)/) {
Condition100%3/3
$func and /^=(cut|head)/
!ll&&!rl&&r
666621729167
MC/DC100%2/2
$func and /^=(cut|head)/
$func /^=(cut|head)/
Truth table100%3/3
A and B
A= $funcB= /^=(cut|head)/
ABresult
0X0
100
111
38 167 ▶ if ($funcs{$func}) { # only save the API functions
Branch: 1 branch
BranchTrueFalseTotal
if ($funcs{$func}) 167 0 167
39 167 $alldocs{$func} = [ @funcdocs ];
40 167 $from{$func} = "File $file";
41 167 ▶ if ($category) {
Branch: 1 branch
BranchTrueFalseTotal
if ($category) 156 11 167
42 156 $funccats{$func} = $category;
43 156 push @{$cats{$category}}, $func;
44 }
45 167 ▶ if ($synopsis) {
Branch: 1 branch
BranchTrueFalseTotal
if ($synopsis) 69 98 167
46 69 $funcsyns{$func} = $synopsis;
47 }
48 167 ▶ defined $order or $order = 50;
Branch: 1 branch
BranchTrueFalseTotal
defined $order or $order = 50 16 151 167
49 167 $order{$func} = $order;
50 }
51 167 undef $func;
52 167 undef $category;
53 167 undef $order;
54 167 $synopsis = '';
55 }
56 elsif ($func) {
57 1729 ▶ if (/^=category (.*)/) {
Branch: 3 branches
BranchTrueFalseTotal
if (/^=category (.*)/) { } 156 1573 1729
elsif (/^=synopsis (.*)/) { } 90 1483 1573
elsif (/^=order (.*)$/) { } 16 1467 1483
58 156 $category = $1;
59 }
60 elsif (/^=synopsis (.*)/) {
61 90 ▶ unless (length $synopsis) {
Branch: 1 branch
BranchTrueFalseTotal
unless (length $synopsis) 69 21 90
62 69 push @funcdocs, "\n";
63 }
64 90 $synopsis .= "$1\n";
65 90 push @funcdocs, " $1\n";
66 }
67 elsif (/^=order (.*)$/) {
68 16 $order = $1;
69 16 ▶ $order =~ /^\d+$/
Branch: 1 branch
BranchTrueFalseTotal
$order =~ /^\d+$/ or die "=order must specify a number for $func in $file\n" 16 0 16
70 or die "=order must specify a number for $func in $file\n";
71 }
72 else {
73 1467 push @funcdocs, $_;
74 }
75 }
76 }
77 $func and
78 105 ▶ die "Documentation for $func not followed by =cut or =head in $file\n";
Branch: 1 branch
BranchTrueFalseTotal
$func and die "Documentation for $func not followed by =cut or =head in $file\n" 0 105 105
79
80 105 close SRC;
81 }
82  
83 1 ▶open OUT, "> $outname"
Branch: 1 branch
BranchTrueFalseTotal
open OUT, "> $outname" or die "Cannot open ${outname}: $!" 1 0 1
84 or die "Cannot open $outname: $!";
85  
86 # I keep this file in git and as part of the dist, make sure newlines
87 # don't mess me up
88 1 binmode OUT;
89  
90 1 print OUT <<'EOS';
91 Do not edit this file, it is generated automatically by apidocs.perl
92 from Imager's source files.
93  
94 Each function description has a comment listing the source file where
95 you can find the documentation.
96  
97 =head1 NAME
98  
99 Imager::APIRef - Imager's C API - reference.
100  
101 =head1 SYNOPSIS
102  
103 i_color color;
104 color.rgba.r = 255; color.rgba.g = 0; color.rgba.b = 255;
105 double x[] = { ... };
106 double y[] = { ... };
107 i_polygon_t poly;
108 poly.count = sizeof(x) / sizeof(*x);
109 poly.x = x;
110 poly.y = y;
111  
112 EOS
113  
114 1 for my $cat (sort { lc $a cmp lc $b } keys %cats) {
115 18 print OUT "\n # $cat\n";
116 18 my @funcs = @{$cats{$cat}};
117 18 my %orig;
118 18 @orig{@funcs} = 0 .. $#funcs;
119 18 ▶ @funcs = sort { $order{$a} <=> $order{$b} || $orig{$a} <=> $orig{$b} } @funcs;
Condition100%3/3
$order{$a} <=> $order{$b} || $orig{$a} <=> $orig{$b}
l!l&&r!l&&!r
492212
MC/DC100%2/2
$order{$a} <=> $order{$b} || $orig{$a} <=> $orig{$b}
$order{$a} <=> $order{$b} $orig{$a} <=> $orig{$b}
Truth table100%3/3
A || B
A= $order{$a} <=> $order{$b}B= $orig{$a} <=> $orig{$b}
ABresult
1X1
011
000
120 18 for my $func (grep $funcsyns{$_}, @funcs) {
121 66 my $syn = $funcsyns{$func};
122 66 $syn =~ s/^/ /gm;
123 66 print OUT $syn;
124 }
125 }
126  
127 1 print OUT <<'EOS';
128  
129 =head1 DESCRIPTION
130  
131 EOS
132  
133 1 my %undoc = %funcs;
134  
135 1 for my $cat (sort { lc $a cmp lc $b } keys %cats) {
136 18 print OUT "=head2 $cat\n\n=over\n\n";
137 my @ordered_funcs = sort {
138 387 ▶ $order{$a} <=> $order{$b}
Condition100%3/3
$order{$a} <=> $order{$b} || lc $a cmp lc $b
l!l&&r!l&&!r
373482
MC/DC100%2/2
$order{$a} <=> $order{$b} || lc $a cmp lc $b
$order{$a} <=> $order{$b} lc $a cmp lc $b
Truth table100%3/3
A || B
A= $order{$a} <=> $order{$b}B= lc $a cmp lc $b
ABresult
1X1
011
000
139 || lc $a cmp lc $b
140 18 } @{$cats{$cat}};
141 18 for my $func (@ordered_funcs) {
142 156 print OUT @{$alldocs{$func}}, "\n";
143 156 print OUT "=for comment\nFrom: $from{$func}\n\n";
144 156 delete $undoc{$func};
145 }
146 18 print OUT "\n=back\n\n";
147 }
148  
149 # see if we have an uncategorised section
150 1 ▶if (grep $alldocs{$_}, keys %undoc) {
Branch: 1 branch
BranchTrueFalseTotal
if (grep $alldocs{$_}, keys %undoc) 1 0 1
151 1 print OUT "=head2 Uncategorized functions\n\n=over\n\n";
152 #print join(",", grep !exists $order{$_}, @funcs), "\n";
153 1 ▶ for my $func (sort { $order{$a} <=> $order{$b} || $a cmp $b }
Condition66%4/6
$order{$a} <=> $order{$b} || $a cmp $b
l!l&&r!l&&!r
0280
$undoc{$_} && $alldocs{$_}
!ll&&!rl&&r
154411
MC/DC0%0/2
$order{$a} <=> $order{$b} || $a cmp $b
$order{$a} <=> $order{$b} $a cmp $b
MC/DC100%2/2
$undoc{$_} && $alldocs{$_}
$undoc{$_} $alldocs{$_}
Truth table33%1/3
A || B
A= $order{$a} <=> $order{$b}B= $a cmp $b
ABresult
1X1
011
000
Truth table100%3/3
A && B
A= $undoc{$_}B= $alldocs{$_}
ABresult
0X0
100
111
154 grep $undoc{$_} && $alldocs{$_}, @funcs) {
155 11 print OUT @{$alldocs{$func}}, "\n";
156 11 print OUT "=for comment\nFrom: $from{$func}\n\n";
157 11 delete $undoc{$func};
158 }
159 1 print OUT "\n\n=back\n\n";
160 }
161  
162 1 ▶if (keys %undoc) {
Branch: 1 branch
BranchTrueFalseTotal
if (keys %undoc) 1 0 1
163 1 print OUT <<'EOS';
164  
165 =head1 UNDOCUMENTED
166  
167 The following API functions are undocumented so far, hopefully this
168 will change:
169  
170 =over
171  
172 EOS
173  
174 1 print OUT "=item *\n\nB<$_>\n\n" for sort keys %undoc;
175  
176 1 print OUT "\n\n=back\n\n";
177 }
178  
179 1 print OUT <<'EOS';
180  
181 =head1 AUTHOR
182  
183 Tony Cook <tony@develop-help.com>
184  
185 =head1 SEE ALSO
186  
187 Imager, Imager::API, Imager::ExtUtils, Imager::Inline
188  
189 =cut
190 EOS
191  
192 1 close OUT;
193  
194  
195 1 ▶sub make_func_list {
Subroutine make_func_list: called CC=10 SCAR=24.1
196 1 my @funcs =
197 qw(i_img i_color i_fcolor i_fill_t mm_log mm_log i_color_model_t
198 im_context_t i_img_dim i_img_dim_u im_slot_t
199 i_polygon_t i_poly_fill_mode_t i_mutex_t
200 i_img_has_alpha i_DF i_DFc i_DFp i_DFcp i_psamp_bits i_gsamp_bits
201 i_psamp i_psampf mymalloc myrealloc myfree);
202 1 ▶ open FUNCS, "< imexttypes.h"
Branch: 1 branch
BranchTrueFalseTotal
open FUNCS, "< imexttypes.h" or die "Cannot open imexttypes.h: $!\n" 1 0 1
203 or die "Cannot open imexttypes.h: $!\n";
204 1 my $in_struct;
205 1 ▶ while (<FUNCS>) {
Branch: 1 branch
BranchTrueFalseTotal
if (defined($_ = readline FUNCS)) 292 0 292
206 292 ▶ /^typedef struct/ && ++$in_struct;
Branch: 1 branch
BranchTrueFalseTotal
/^typedef struct/ and ++$in_struct 1 291 292
207 292 ▶ if ($in_struct && !/SKIP/ && /\(\*f_(i[om]?_\w+)/) {
Branch: 1 branch
BranchTrueFalseTotal
if ($in_struct and not /SKIP/ and /\(\*f_(i[om]?_\w+)/) 143 149 292
Condition100%6/6
$in_struct and not /SKIP/ and /\(\*f_(i[om]?_\w+)/
!ll&&!rl&&r
6287143
$in_struct and not /SKIP/
!ll&&!rl&&r
4616230
MC/DC100%3/3
$in_struct and not /SKIP/ and /\(\*f_(i[om]?_\w+)/
$in_struct not /SKIP/ /\(\*f_(i[om]?_\w+)/
Truth table100%4/4
A and not(B) and C
A= $in_structB= not /SKIP/C= /\(\*f_(i[om]?_\w+)/
ABCresult
0XX0
10X0
1100
1111
208 143 my $name = $1;
209 143 $name =~ s/_imp$//;
210 143 push @funcs, $name;
211 }
212 292 ▶ if (/^\} im_ext_funcs;$/) {
Branch: 1 branch
BranchTrueFalseTotal
if (/^\} im_ext_funcs;$/) 1 291 292
213 1 ▶ $in_struct
Branch: 1 branch
BranchTrueFalseTotal
$in_struct or die "Found end of functions structure but not the start" 1 0 1
214 or die "Found end of functions structure but not the start";
215  
216 1 close FUNCS;
217 1 return @funcs;
218 }
219 }
220 0 ▶ if ($in_struct) {
Branch: 1 branch
BranchTrueFalseTotal
if ($in_struct) { } 0 0 0
221 0 die "Found start of the functions structure but not the end\n";
222 }
223 else {
224 0 die "Found neither the start nor end of the functions structure\n";
225 }
226 }
227  
228 =head1 NAME
229  
230 apidocs.perl - parse Imager's source for POD documenting the C API
231  
232 =head1 SYNOPSIS
233  
234 perl apidocs.perl lib/Imager/APIRef.pod
235  
236 =head1 DESCRIPTION
237  
238 Parses Imager's C sources, including .c, .h and .im files searching
239 for function documentation.
240  
241 Besides the normal POD markup, the following can be included:
242  
243 =over
244  
245 =item =category I<category-name>
246  
247 The category the function should be in.
248  
249 =item =synopsis I<sample-code>
250  
251 Sample code using the function to include in the Imager::APIRef SYNOPSIS
252  
253 =item =order I<integer>
254  
255 Allows a function to be listed out of order. If this isn't specified
256 it defaults to 50, so a value of 10 will cause the function to be
257 listed at the beginning of its category, or 90 to list at the end.
258  
259 Functions with equal order are otherwise ordered by name.
260  
261 =back
262  
263 =head1 AUTHOR
264  
265 Tony Cook <tony@develop-help.com>
266  
267 =cut
268  
« blib/lib/Imager/Matrix2d.pm ↑ Summary blib/lib/Imager/Color/Float.pm »