hoonlint

filter: Statementstmt 90.9% 111 / 122 Branchbran 50.0% 19 / 38 Conditioncond 33.3% 2 / 6 MC/DCmcdc 0.0% 0 / 4 Subroutinesub 84.6% 11 / 13 Podpod n/a totaltotal 78.1% 143 / 183 CC 9 SCAR 14.1
CC
9
Cov
80%
parseReportItems
8.6
slurp
2.0
__ANON__
2.0
CRAP 4.1
« blib/lib/MarpaX/Hoonlint.pm ↑ Summary
1 #!perl
2  
3 6 ▶use 5.010;
Subroutine BEGIN: called CC=1 SCAR=0.0
4 6 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
5 6 ▶use warnings;
Subroutine BEGIN: called CC=1 SCAR=0.0
6  
7 6 ▶use Data::Dumper;
Subroutine BEGIN: called CC=1 SCAR=0.0
8 6 ▶use English qw( -no_match_vars );
Subroutine BEGIN: called CC=1 SCAR=0.0
9 6 ▶use Scalar::Util qw(looks_like_number weaken);
Subroutine BEGIN: called CC=1 SCAR=0.0
10 6 ▶use Getopt::Long;
Subroutine BEGIN: called CC=1 SCAR=0.0
11  
12 6 ▶use MarpaX::Hoonlint;
Subroutine BEGIN: called CC=1 SCAR=0.0
13  
14 1 ▶sub slurpStdin {
Subroutine slurpStdin: called CC=1 SCAR=0.0
15 1 local $RS = undef;
16 1 my $file = <STDIN>;
17 1 return \$file;
18 }
19  
20 18 ▶sub slurp {
Subroutine slurp: called CC=2 SCAR=7.0
21 18 my ($fileName) = @_;
22 18 local $RS = undef;
23 18 my $fh;
24 18 ▶ open $fh, q{<}, $fileName or die "Cannot open $fileName";
Branch: 1 branch
BranchTrueFalseTotal
open $fh, "<", $fileName or die "Cannot open $fileName" 18 0 18
25 18 my $file = <$fh>;
26 18 close $fh;
27 18 return \$file;
28 }
29  
30 12 ▶sub parseReportItems {
Subroutine parseReportItems: called CC=8 SCAR=21.6
31 12 my ( $config, $reportItems ) = @_;
32 12 my $fileName = $config->{fileName};
33 12 my %itemHash = ();
34 12 my %unusedItemHash = ();
35  
36 0 ▶ my $itemError = sub {
Subroutine __ANON__: not called CC=1 SCAR=6.9
37 0 my ( $error, $line ) = @_;
38 0 return qq{Error in item file "$fileName": $error\n}
39 . qq{ Problem with line: $line\n};
40 12 };
41  
42 12 ITEM: for my $itemLine ( split "\n", ${$reportItems} ) {
43 24 my $rawItemLine = $itemLine;
44 24 $itemLine =~ s/\s*[#].*$//; # remove comments and preceding whitespace
45 24 $itemLine =~ s/^\s*//; # remove leading whitespace
46 24 $itemLine =~ s/\s*$//; # remove trailing whitespace
47 24 ▶ next ITEM unless $itemLine;
Branch: 1 branch
BranchTrueFalseTotal
unless $itemLine 0 24 24
48 24 my ( $thisFileName, $lc, $policy, $subpolicy, $message ) = split /\s+/, $itemLine, 5;
49 24 ▶ return undef, $itemError->( "Problem in report line", $rawItemLine )
Branch: 1 branch
BranchTrueFalseTotal
unless $thisFileName 0 24 24
50 if not $thisFileName;
51  
52 return undef,
53 24 ▶ $itemError->( qq{Malformed line:column in item line: "$lc"},
Branch: 1 branch
BranchTrueFalseTotal
unless $lc =~ /^[0-9]+[:][0-9]+$/ 0 24 24
54 $rawItemLine )
55 unless $lc =~ /^[0-9]+[:][0-9]+$/;
56 24 my ( $line, $column ) = split ':', $lc, 2;
57 24 ▶ $itemError->( qq{Malformed line:column in item line: "$lc"}, $rawItemLine )
Branch: 1 branch
BranchTrueFalseTotal
unless &Scalar::Util::looks_like_number($line) and &Scalar::Util::looks_like_number($column) 0 24 24
Condition33%1/3
&Scalar::Util::looks_like_number($line) and &Scalar::Util::looks_like_number($column)
!ll&&!rl&&r
0024
MC/DC0%0/2
&Scalar::Util::looks_like_number($line) and &Scalar::Util::looks_like_number($column)
&Scalar::Util::looks_like_number($line) &Scalar::Util::looks_like_number($column)
Truth table33%1/3
A and B
A= &Scalar::Util::looks_like_number($line)B= &Scalar::Util::looks_like_number($column)
ABresult
0X0
100
111
58 unless Scalar::Util::looks_like_number($line)
59 and Scalar::Util::looks_like_number($column);
60 24 ▶ next ITEM unless $thisFileName eq $fileName;
Branch: 1 branch
BranchTrueFalseTotal
unless $thisFileName eq $fileName 18 6 24
61  
62 # We reassemble line:column to "normalize" it -- be indifferent to
63 # leading zeros, etc.
64 6 my $lcTag = join ':', $line, $column;
65 6 $itemHash{$lcTag}{$policy}{$subpolicy} = $message;
66 6 $unusedItemHash{$lcTag}{$policy}{$subpolicy} = 1;
67 }
68 12 return \%itemHash, \%unusedItemHash;
69 }
70  
71 6 my $verbose; # right now does nothing
72 my $inclusionsFileName;
73 6 my @suppressionsFileNames;
74 6 my @policiesArg;
75 6 my $contextSize = 0;
76 6 my $displayDetails = 1;
77 6 my $fileList;
78  
79 6 ▶GetOptions(
Branch: 1 branch
BranchTrueFalseTotal
&GetOptions("verbose", \$verbose, "context|C:i", \$contextSize, "displayDetails|details:i", \$displayDetails, "filelist|f:s", \$fileList, "inclusions-file|I=s", \$inclusionsFileName, "suppressions_file|S=s", \@suppressionsFileNames, "policy|P=s", \@policiesArg) or die "Error in command line arguments\n" 6 0 6
80 "verbose" => \$verbose,
81 "context|C:i" => \$contextSize,
82 "displayDetails|details:i" => \$displayDetails,
83 "filelist|f:s" => \$fileList,
84 "inclusions-file|I=s" => \$inclusionsFileName,
85 "suppressions_file|S=s" => \@suppressionsFileNames,
86 "policy|P=s" => \@policiesArg,
87 ) or die("Error in command line arguments\n");
88  
89 0 ▶sub usage {
Subroutine usage: not called CC=1 SCAR=6.9
90 0 die "usage: $PROGRAM_NAME [options ...] fileName\n";
91 }
92  
93 6 my @fileNames = ();
94 GET_FILE_LIST: {
95 6 ▶ last GET_FILE_LIST unless $fileList;
Branch: 1 branch
BranchTrueFalseTotal
unless $fileList 5 1 6
96 1 ▶ if ($fileList eq '-') {
Branch: 1 branch
BranchTrueFalseTotal
if ($fileList eq "-") 1 0 1
97 1 push @fileNames, (split "\n", ${ slurpStdin() });
98 1 last GET_FILE_LIST;
99 }
100 0 push @fileNames, (split "\n", ${ slurp($fileList) });
101 }
102 6 push @fileNames, @ARGV;
103 6 ▶die "No files specified\n" if scalar @fileNames <= 0;
Branch: 1 branch
BranchTrueFalseTotal
if scalar @fileNames <= 0 0 6 6
104  
105 # Config is essentially a proto-lint-instance, containing all
106 # variables which are from some kind of "environment", which
107 # the lint instance must treat as a constant. From the POV
108 # of the lint instance, the config is a global, but this is
109 # not necessarily the case.
110 #
111 # The archetypal example of a config is the "environment"
112 # created by the invocation of the `hoonlint` Perl script
113 # which contains information taken from the command line
114 # arguments and read from various files.
115  
116 6 my %sharedConfig = ();
117  
118 6 my @policies = ();
119 6 push @policies, @policiesArg;
120  
121 # Default policy
122 6 ▶@policies = ('Test::Whitespace') if not scalar @policies;
Branch: 1 branch
BranchTrueFalseTotal
unless scalar @policies 6 0 6
123 6 ▶die "Multiple policies not yet implemented" if scalar @policies != 1;
Branch: 1 branch
BranchTrueFalseTotal
if scalar @policies != 1 0 6 6
124 6 my %policies = ();
125 6 for my $shortPolicyName (@policies) {
126 6 my $fullPolicyName = 'MarpaX::Hoonlint::Policy::' . $shortPolicyName;
127  
128 # "require policy name" is a hack until I create the full directory
129 # structure required to make this a Perl module
130 6 my $eval_ok = eval "require $fullPolicyName";
131 6 ▶ die $EVAL_ERROR if not $eval_ok;
Branch: 1 branch
BranchTrueFalseTotal
unless $eval_ok 0 6 6
132 6 $policies{$shortPolicyName} = $fullPolicyName;
133 }
134 6 $sharedConfig{policies} = \%policies;
135  
136 6 my $defaultSuppressionFile = 'hoonlint.suppressions';
137 6 ▶if ( not @suppressionsFileNames
Branch: 1 branch
BranchTrueFalseTotal
if (not @suppressionsFileNames and -f $defaultSuppressionFile) 0 6 6
Condition33%1/3
not @suppressionsFileNames and -f $defaultSuppressionFile
!ll&&!rl&&r
600
MC/DC0%0/2
not @suppressionsFileNames and -f $defaultSuppressionFile
not @suppressionsFileNames -f $defaultSuppressionFile
Truth table33%1/3
not(A) and B
A= not @suppressionsFileNamesB= -f $defaultSuppressionFile
ABresult
0X0
100
111
138 and -f $defaultSuppressionFile )
139 {
140 0 @suppressionsFileNames = ($defaultSuppressionFile);
141 }
142  
143 6 my $pSuppressions;
144 {
145 6 my @suppressions = ();
146 6 for my $fileName (@suppressionsFileNames) {
147 6 push @suppressions, ${ slurp($fileName) };
148 }
149 6 $pSuppressions = \( join "", @suppressions );
150 }
151  
152 6 $sharedConfig{contextSize} = $contextSize;
153 SET_DISPLAY_DETAILS: {
154 6 ▶ if ( not defined $displayDetails ) {
Branch: 1 branch
BranchTrueFalseTotal
unless (defined $displayDetails) 0 6 6
155 0 ▶ $sharedConfig{displayDetails} = $contextSize >= 1 ? 1 : 0;
Branch: 1 branch
BranchTrueFalseTotal
$contextSize >= 1 ? : 0 0 0
156 0 last SET_DISPLAY_DETAILS;
157 }
158 6 $sharedConfig{displayDetails} = $displayDetails;
159 }
160  
161 6 for my $fileName (@fileNames) {
162 12 my %config = %sharedConfig;
163 12 $config{fileName} = $fileName;
164 12 my $pHoonSource = slurp($fileName);
165 12 $config{pHoonSource} = $pHoonSource;
166  
167 12 my ( $suppressions, $unusedSuppressions ) =
168 parseReportItems( \%config, $pSuppressions );
169 12 ▶ die $unusedSuppressions if not $suppressions;
Branch: 1 branch
BranchTrueFalseTotal
unless $suppressions 0 12 12
170 12 $config{suppressions} = $suppressions;
171 12 $config{unusedSuppressions} = $unusedSuppressions;
172  
173 12 my $pInclusions;
174 12 my ( $inclusions, $unusedInclusions );
175 12 ▶ if ( defined $inclusionsFileName ) {
Branch: 1 branch
BranchTrueFalseTotal
if (defined $inclusionsFileName) 0 12 12
176 0 $pInclusions = slurp($inclusionsFileName);
177 0 ( $inclusions, $unusedInclusions ) =
178 parseReportItems( \%config, $pInclusions );
179 0 ▶ die $unusedInclusions if not $inclusions;
Branch: 1 branch
BranchTrueFalseTotal
unless $inclusions 0 0 0
180 }
181 12 $config{inclusions} = $inclusions;
182 12 $config{unusedInclusions} = $unusedInclusions;
183  
184 12 MarpaX::Hoonlint->new( \%config );
185 }
186  
187 =pod
188  
189 =encoding UTF-8
190  
191 =head1 NAME
192  
193 hoonlint - lint utility for the Hoon language
194  
195 =head1 SYNOPSIS
196  
197 hoonlint [options] FILE ...
198  
199 =head1 Status
200  
201 This software is alpha -- it should be useable,
202 but features are evolving
203 and subject to change without notice.
204  
205 =head2 Updates
206  
207 Once MarpaX::Hoonlint leaves alpha,
208 users should consult Marpa::R2's "updates" page,
209 which contains notes, errata, etc.,
210 added since the most recent release.
211 The "updates" page is C<UPDATES.md> in the
212 current repo.
213 At this point, the link is
214 L<https://github.com/jeffreykegler/hoonlint/blob/master/UPDATES.md>.
215  
216 =head1 Description
217  
218 The C<hoonlint> command runs checks on one or more hoon
219 files.
220 These may be specified on the command line,
221 or via the C<-f> option.
222  
223 =head2 Simple example
224  
225 The command
226  
227 hoonlint hoons/examples/toe.hoon
228  
229 lint the Tic-tac-toe example for Hoon
230 (which can be found at
231 L<https://github.com/jeffreykegler/hoonlint/blob/cf60f1d5eeb8a0270c9d5a80f096e17fabe6a8b8/cpan/hoons/examples/toe.hoon>)
232 and produces the following output:
233  
234 hoons/examples/toe.hoon 58:16 Test::Whitespace wutcol:indent backdented element #2 @58:16; overindented by 1
235  
236 In this
237  
238 =over 4
239  
240 * C<hoon/examples/toe.hoon> is the name of the file.
241  
242 * C<58:16> is the line number and column of the problem, both 1-based.
243  
244 * C<Test::Whitespace> is the policy name.
245  
246 * C<wutcol:indent> is the subpolicy name.
247  
248 * A human-readable description of the lint issue.
249 The rest of the line is describes the lint issue.
250 In this case,
251 the 2nd runechild of a WUTCOL hoon statement (which is located at line 58, column 16)
252 is overindented by 1.
253  
254 =back
255  
256 =head2 Example with context
257  
258 The message of the simple example
259 becomes a little more understandable, if we ask hoonlint to show the code.
260 The C<-C 5> option request 5 lines of context, so that the command
261  
262 hoonlint -C 5 toe.hoon
263  
264 produces the following output:
265  
266 53 == :: 53
267 54 ++ mo ^- {(unit fact) ^game} :: 54
268 55 ?< is :: 55
269 56 =/ next/side (~(set bo a.game) here) :: 56
270 57> ?: ~(win bo next) :: 57
271 [ hoons/examples/toe.hoon 58:16 Test::Whitespace wutcol:indent backdented element #2 @58:16; overindented by 1
272 anchor column is "?:" @57:13
273 ]
274 58! [[~ %win ?:(w.game %x %o)] nu] :: 58
275 59 [~ game(w !w.game, a z.game, z next)] :: 59
276 60 -- :: 60
277 61 -- :: 62
278 62 -- :: 63
279  
280 In the above, the original lint message is shown in square brackets, just before the line
281 (58) to which it refers.
282 Following the original lint message,
283 also within the square brackets,
284 are additional details:
285  
286 anchor column is "?:" @57:13
287  
288 Backdenting is relative to an anchor column, and this detail tells
289 us where C<hoonlint> thought the anchor column was.
290  
291 Each line of code is preceded by its line number and an optional tag,
292 either a zap (C<!>) or a gar (C<< > >>).
293 A zap indicates a line with a lint issue.
294 A gar indicates a "topic" line -- a lint which does not actually contain
295 an issue, but which is relevant to a lint issue.
296 In this case, line 57 contains the beginning of the hoon statement
297 which has the backdenting issue.
298  
299 =head2 Example without details
300  
301 It is also possible to have context without details.
302 The command
303  
304 hoonlint -C 2 --details=0 fizzbuzz.hoon
305  
306 runs on Hoon's fizzbuzz example.
307 It asks for 2 context lines,
308 with no details.
309 (The fizzbuzz example can be found at
310 L<https://github.com/jeffreykegler/hoonlint/blob/cf60f1d5eeb8a0270c9d5a80f096e17fabe6a8b8/cpan/hoons/examples/fizzbuzz.hoon>.)
311 It produces the following output:
312  
313 4 ^- (list tape)
314 5> ?: =(end count)
315 [ fizzbuzz.hoon 6:4 Test::Whitespace wutcol:indent backdented element #2 @6:4; overindented by 1 ]
316 6! ~
317 7 :-
318  
319 =head1 Options
320  
321 =over 4
322  
323 =item B<-C I<NUM>>, B<--context=I<NUM>>
324  
325 Display I<NUM> lines of context before and after
326 the issue message.
327 If I<NUM> is 0, no context is displayed.
328 By default, I<NUM> is 0.
329  
330 =item B<--displayDetails=I<NUM>> B<--details=I<NUM>>
331  
332 Display I<NUM> levels of detail for the error message.
333 (Currently at most 1 level of detail is implemented.)
334 Some issue messages have no details available.
335 I<NUM> defaults to 1 if more than one line of context
336 is being displayed.
337 I<NUM> defaults to 0 is no lines of context are being
338 displayed.
339  
340 =item B<-f I<listFile>>, B<--filelist=I<listFile>>
341  
342 Add the files in the file named I<listFile>
343 to the files to be processed by C<hoonlint>.
344 If I<listFile> is C<->, read the list of files
345 from STDIN.
346  
347 =item B<-P I<policy>>, B<--policy=I<policy>>
348  
349 Set the policy that C<hoonlint>
350 is running to I<policy>.
351 C<Test::Whitespace> is the default.
352  
353 Currently,
354 C<Test::Whitespace> is
355 the only policy implemented.
356 It's conventions are documented in L<a separate
357 document|https://jeffreykegler.github.io/hoonlint/misc/whitespace.html>.
358  
359 =back
360  
361 =head1 SUPPORT
362  
363 Support for and information about F<hoonlint> can be found at:
364  
365 =over 4
366  
367 =item * Source repository
368  
369 L<https://github.com/jeffreykegler/hoonlint>
370  
371 =item * The Marpa IRC Channel
372  
373 #marpa at freenode.net
374  
375 =item * The Marpa mailing list
376  
377 L<http://groups.google.com/group/marpa-parser>
378  
379 =back
380  
381 =head1 FAQ
382  
383 =head2 How do I install hoonlint?
384  
385 MarpaX::Hoonlint is an ordinary Perl CPAN module,
386 and installs in the usual ways.
387 CPAN.org has
388 L<a page on installing modules|https://www.cpan.org/modules/INSTALL.html>,
389 which contains more than you need to know.
390 However, since many in hoonlint's intended audience
391 will be new to Perl, here is
392 what most newcomers need to know:
393  
394 =over 4
395  
396 * First, install Perl. You need at least Perl 5.10.1.
397 Almost every UNIX system will come with such a Perl.
398  
399 * Second, run this command:
400  
401 cpan App::cpanminus
402  
403 * Third, run this command:
404  
405 cpanm MarpaX::Hoonlint
406  
407 =back
408  
409 That's it.
410  
411 =head2 How do I install hoonlint from the Git repo?
412  
413 Do the following:
414  
415 =over 4
416  
417 * First, clone the git repo.
418  
419 * Second, install Perl. You need at least Perl 5.10.1.
420 Almost every UNIX system will come with such a Perl.
421  
422 * Third, download the L<cpanm> command.
423  
424 cpan App::cpanminus
425  
426 * From the directory of the downloaded git repo,
427 run this command
428  
429 cpanm ./cpan
430  
431 =back
432  
433 =head1 ACKNOWLEDGEMENTS
434  
435 C<hoonlint> was made possible by the generous support of
436 an anonymous member of the Hoon community.
437  
438 =head1 AUTHOR
439  
440 Jeffrey Kegler, C<< <jkegl at cpan.org> >>
441  
442 =head1 COPYRIGHT & LICENSE
443  
444 The MIT License (MIT)
445  
446 Copyright (c) 2018 Urbit
447  
448 Permission is hereby granted, free of charge, to any person obtaining a copy
449 of this software and associated documentation files (the "Software"), to deal
450 in the Software without restriction, including without limitation the rights
451 to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
452 copies of the Software, and to permit persons to whom the Software is
453 furnished to do so, subject to the following conditions:
454  
455 The above copyright notice and this permission notice shall be included in all
456 copies or substantial portions of the Software.
457  
458 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
459 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
460 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
461 AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
462 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
463 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
464 SOFTWARE.
465  
466 =cut
467  
468 1;
469  
470 # vim: expandtab shiftwidth=4:
« blib/lib/MarpaX/Hoonlint.pm ↑ Summary