blib/lib/Perl/Critic/Policy/Documentation/PodSpelling.pm

filter: Statementstmt 46.7% 65 / 139 Branchbran 11.3% 5 / 44 Conditioncond 16.6% 1 / 6 MC/DCmcdc 0.0% 0 / 4 Subroutinesub 65.6% 21 / 32 Podpod 71.4% 5 / 7 totaltotal 41.8% 97 / 232 CC 25 SCAR 34.9
CC
25
Cov
38%
_run_spell_command
132.0
_load_stop_words_file
42.0
violates
12.0
CRAP 32.8
« blib/lib/Perl/Critic/Policy/Modules/ProhibitConditionalUseStatements.pm ↑ Summary blib/lib/Perl/Critic/Policy/InputOutput/ProhibitTwoArgOpen.pm »
1 package Perl::Critic::Policy::Documentation::PodSpelling;
2  
3 40 ▶use 5.010001;
Subroutine BEGIN: called CC=1 SCAR=0.0
4 40 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
5 40 ▶use warnings;
Subroutine BEGIN: called CC=1 SCAR=0.0
6  
7 40 ▶use English qw(-no_match_vars);
Subroutine BEGIN: called CC=1 SCAR=0.0
8 40 ▶use Readonly;
Subroutine BEGIN: called CC=1 SCAR=0.0
9  
10 40 ▶use File::Spec;
Subroutine BEGIN: called CC=1 SCAR=0.0
11 40 ▶use File::Temp;
Subroutine BEGIN: called CC=1 SCAR=0.0
12 40 ▶use List::SomeUtils qw(uniq);
Subroutine BEGIN: called CC=1 SCAR=0.0
13 40 ▶use Pod::Spell qw< >;
Subroutine BEGIN: called CC=1 SCAR=0.0
14 40 ▶use Pod::Wordlist;
Subroutine BEGIN: called CC=1 SCAR=0.0
15 40 ▶use Text::ParseWords qw< >;
Subroutine BEGIN: called CC=1 SCAR=0.0
16  
17 40 use Perl::Critic::Utils qw(
18 :characters
19 :booleans
20 :severities
21 40 ▶);
Subroutine BEGIN: called CC=1 SCAR=0.0
22 40 ▶use Perl::Critic::Exception::Fatal::Generic qw{ throw_generic };
Subroutine BEGIN: called CC=1 SCAR=0.0
23  
24 40 ▶use parent 'Perl::Critic::Policy';
Subroutine BEGIN: called CC=1 SCAR=0.0
25  
26 40 our $VERSION = '1.150';
27  
28 #-----------------------------------------------------------------------------
29  
30 40 Readonly::Scalar my $DESC => q{Check the spelling in your POD};
31 40 Readonly::Scalar my $EXPL => [148];
32  
33 #-----------------------------------------------------------------------------
34  
35 sub supported_parameters {
36 return (
37 {
38 95 ▶ name => 'spell_command',
Subroutine supported_parameters: called CC=1 SCAR=0.0
Pod undocumented
39 description => 'The command to invoke to check spelling.',
40 default_string => 'aspell list',
41 behavior => 'string',
42 },
43 {
44 name => 'stop_words',
45 description => 'The words to not consider as misspelled.',
46 default_string => $EMPTY,
47 behavior => 'string list',
48 },
49 {
50 name => 'stop_words_file',
51 description => 'A file containing words to not consider as misspelled.',
52 default_string => $EMPTY,
53 behavior => 'string',
54 },
55 );
56 }
57  
58 85 ▶sub default_severity { return $SEVERITY_LOWEST }
Subroutine default_severity: called CC=1 SCAR=0.0
Pod documented
59 89 ▶sub default_themes { return qw( core cosmetic pbp ) }
Subroutine default_themes: called CC=1 SCAR=0.0
Pod documented
60 0 ▶sub applies_to { return 'PPI::Document' }
Subroutine applies_to: not called CC=1 SCAR=6.9
Pod documented
61  
62 #-----------------------------------------------------------------------------
63  
64 40 my $got_sigpipe = 0;
65 sub got_sigpipe {
66 0 ▶ return $got_sigpipe;
Subroutine got_sigpipe: not called CC=1 SCAR=6.9
Pod undocumented
67 }
68  
69 #-----------------------------------------------------------------------------
70  
71 sub initialize_if_enabled {
72 23 ▶ my ( $self, $config ) = @_;
Subroutine initialize_if_enabled: called CC=4 SCAR=19.2
Pod documented
73  
74 23 ▶ eval { require File::Which; 1 } or return $FALSE;
Branch: 1 branch
BranchTrueFalseTotal
eval { do { require File::Which; 1 } } or return $Perl::Critic::Policy::Documentation::PodSpelling::FALSE 0 23 23
75  
76 23 ▶ return $FALSE if not $self->_derive_spell_command_line();
Branch: 1 branch
BranchTrueFalseTotal
unless $self->_derive_spell_command_line 23 0 23
77  
78 0 my $test_code = <<'END_TEST_CODE';
79 ;pod
80  
81 ;head1 Test The Spell Command
82  
83 ;cut
84 END_TEST_CODE
85 0 $test_code =~ s/^;/=/msx;
86 0 ▶ return $FALSE if not $self->_run_spell_command($test_code);
Branch: 1 branch
BranchTrueFalseTotal
unless $self->_run_spell_command($test_code) 0 0 0
87  
88 0 $self->_load_stop_words_file();
89  
90 0 return $TRUE;
91 }
92  
93 #-----------------------------------------------------------------------------
94  
95 sub violates {
96 0 ▶ my ( $self, $elem, $doc ) = @_;
Subroutine violates: not called CC=3 SCAR=24.8
Pod documented
97  
98 0 my $code = $doc->serialize();
99  
100 0 my $words = $self->_run_spell_command($code);
101  
102 0 ▶ return if not $words; # error running spell command
Branch: 1 branch
BranchTrueFalseTotal
unless $words 0 0 0
103  
104 0 ▶ return if not @{$words}; # no problems found
Branch: 1 branch
BranchTrueFalseTotal
unless @{$words;} 0 0 0
105  
106 0 return $self->violation( "$DESC: @{$words}", $EXPL, $doc );
107 }
108  
109 #-----------------------------------------------------------------------------
110  
111 sub _derive_spell_command_line {
112 23 ▶ my ($self) = @_;
Subroutine _derive_spell_command_line: called CC=5 SCAR=19.3
113  
114 23 my @words = Text::ParseWords::shellwords($self->_get_spell_command());
115 23 ▶ if (!@words) {
Branch: 1 branch
BranchTrueFalseTotal
unless (@words) 0 23 23
116 0 return;
117 }
118 23 ▶ if (! File::Spec->file_name_is_absolute($words[0])) {
Branch: 1 branch
BranchTrueFalseTotal
unless ("File::Spec"->file_name_is_absolute($words[0])) 23 0 23
119 23 $words[0] = File::Which::which($words[0]);
120 }
121 23 ▶ if (! $words[0] || ! -x $words[0]) {
Branch: 1 branch
BranchTrueFalseTotal
unless ($words[0] and -x $words[0]) 23 0 23
Condition33%1/3
$words[0] and -x $words[0]
!ll&&!rl&&r
2300
MC/DC0%0/2
$words[0] and -x $words[0]
$words[0] -x $words[0]
Truth table33%1/3
A and B
A= $words[0]B= -x $words[0]
ABresult
0X0
100
111
122 23 return;
123 }
124 0 $self->_set_spell_command_line(\@words);
125  
126 0 return $self->_get_spell_command_line();
127 }
128  
129 #-----------------------------------------------------------------------------
130  
131 sub _get_spell_command {
132 23 ▶ my ( $self ) = @_;
Subroutine _get_spell_command: called CC=1 SCAR=0.0
133  
134 23 return $self->{_spell_command};
135 }
136  
137 #-----------------------------------------------------------------------------
138  
139 sub _get_spell_command_line {
140 1 ▶ my ( $self ) = @_;
Subroutine _get_spell_command_line: called CC=1 SCAR=0.0
141  
142 1 return $self->{_spell_command_line};
143 }
144  
145 sub _set_spell_command_line {
146 0 ▶ my ( $self, $spell_command_line ) = @_;
Subroutine _set_spell_command_line: not called CC=1 SCAR=6.9
147  
148 0 $self->{_spell_command_line} = $spell_command_line;
149  
150 0 return;
151 }
152  
153 #-----------------------------------------------------------------------------
154  
155 sub _get_stop_words {
156 0 ▶ my ( $self ) = @_;
Subroutine _get_stop_words: not called CC=1 SCAR=6.9
157  
158 0 return $self->{_stop_words};
159 }
160  
161 sub _set_stop_words {
162 0 ▶ my ( $self, $stop_words ) = @_;
Subroutine _set_stop_words: not called CC=1 SCAR=6.9
163  
164 0 $self->{_stop_words} = $stop_words;
165  
166 0 return;
167 }
168  
169 #-----------------------------------------------------------------------------
170  
171 sub _get_stop_words_file {
172 0 ▶ my ( $self ) = @_;
Subroutine _get_stop_words_file: not called CC=1 SCAR=6.9
173  
174 0 return $self->{_stop_words_file};
175 }
176  
177 #-----------------------------------------------------------------------------
178  
179 sub _run_spell_command {
180 0 ▶ my ($self, $code) = @_;
Subroutine _run_spell_command: not called CC=11 SCAR=48.8
181  
182 0 my $outfh = File::Temp->new();
183  
184 0 my $outfile = $outfh->filename();
185 0 my @words;
186  
187 0 local $EVAL_ERROR = undef;
188  
189 eval {
190 # temporarily add our special wordlist to this annoying global
191 local %Pod::Wordlist::Wordlist = ## no critic (ProhibitPackageVars)
192 0 %{ $self->_get_stop_words() };
193  
194 0 ▶ open my $infh, '<', \$code
Branch: 1 branch
BranchTrueFalseTotal
open my $infh, "<", \$code or throw_generic("error opening scalar: $Perl::Critic::Policy::Documentation::PodSpelling::OS_ERROR") 0 0 0
195 or throw_generic "error opening scalar: $OS_ERROR";
196  
197 0 Pod::Spell->new()->parse_from_filehandle($infh, $outfh);
198 0 ▶ close $infh or throw_generic "Failed to close in memory file: $OS_ERROR";
Branch: 1 branch
BranchTrueFalseTotal
close $infh or throw_generic("Failed to close in memory file: $Perl::Critic::Policy::Documentation::PodSpelling::OS_ERROR") 0 0 0
199 0 ▶ close $outfh or throw_generic "Failed to close pod temp file: $OS_ERROR";
Branch: 1 branch
BranchTrueFalseTotal
close $outfh or throw_generic("Failed to close pod temp file: $Perl::Critic::Policy::Documentation::PodSpelling::OS_ERROR") 0 0 0
200 0 ▶ return if not -s $outfile; # Bail out if no words to spellcheck
Branch: 1 branch
BranchTrueFalseTotal
unless -s $outfile 0 0 0
201  
202 # run spell command and fetch output
203 0 ▶ local $SIG{PIPE} = sub { $got_sigpipe = 1; };
Subroutine __ANON__: not called CC=1 SCAR=6.9
204 0 my $command_line = join $SPACE, @{$self->_get_spell_command_line()};
205 0 ▶ open my $aspell_out_fh, q{-|}, "$command_line < $outfile" ## Is this portable??
Branch: 1 branch
BranchTrueFalseTotal
open my $aspell_out_fh, "-|", "$command_line < $outfile" or throw_generic("Failed to open handle to spelling program: $Perl::Critic::Policy::Documentation::PodSpelling::OS_ERROR") 0 0 0
206 or throw_generic "Failed to open handle to spelling program: $OS_ERROR";
207  
208 0 @words = uniq( <$aspell_out_fh> );
209 0 ▶ close $aspell_out_fh
Branch: 1 branch
BranchTrueFalseTotal
close $aspell_out_fh or throw_generic("Failed to close handle to spelling program: $Perl::Critic::Policy::Documentation::PodSpelling::OS_ERROR") 0 0 0
210 or throw_generic "Failed to close handle to spelling program: $OS_ERROR";
211  
212 0 chomp @words;
213  
214 # Why is this extra step needed???
215 0 @words = grep { not exists $Pod::Wordlist::Wordlist{$_} } @words; ## no critic (ProhibitPackageVars)
216 0 1;
217 }
218 0 ▶ or do {
Branch: 1 branch
BranchTrueFalseTotal
eval { do { local(%Pod::Wordlist::Wordlist) = %{$self->_get_stop_words;}; open my $infh, "<", \$code or throw_generic("error opening scalar: $Perl::Critic::Policy::Documentation::PodSpelling::OS_ERROR"); "Pod::Spell"->new->parse_from_filehandle($infh, $outfh); close $infh or throw_generic("Failed to close in memory file: $Perl::Critic::Policy::Documentation::PodSpelling::OS_ERROR"); close $outfh or throw_generic("Failed to close pod temp file: $Perl::Critic::Policy::Documentation::PodSpelling::OS_ERROR"); return unless -s $outfile; local $SIG{"PIPE"} = sub { $got_sigpipe = 1; } ; my $command_line = join($Perl::Critic::Policy::Documentation::PodSpelling::SPACE, @{$self->_get_spell_command_line;}); open my $aspell_out_fh, "-|", "$command_line < $outfile" or throw_generic("Failed to open handle to spelling program: $Perl::Critic::Policy::Documentation::PodSpelling::OS_ERROR"); @words = &uniq(readline $aspell_out_fh); close $aspell_out_fh or throw_generic("Failed to close handle to spelling program: $Perl::Critic::Policy::Documentation::PodSpelling::OS_ERROR"); chomp @words; @words = grep({not exists $Pod::Wordlist::Wordlist{$_};} @words); 1 } } or do { if ($Perl::Critic::Policy::Documentation::PodSpelling::EVAL_ERROR and not ref "Perl::Critic::Exception::Fatal::Generic"->caught) { ref $Perl::Critic::Policy::Documentation::PodSpelling::EVAL_ERROR ? $Perl::Critic::Policy::Documentation::PodSpelling::EVAL_ERROR->rethrow : die($Perl::Critic::Policy::Documentation::PodSpelling::EVAL_ERROR); } ; return } 0 0 0
219 # Eat anything we did ourselves above, propagate anything else.
220 0 ▶ if (
Branch: 1 branch
BranchTrueFalseTotal
if ($Perl::Critic::Policy::Documentation::PodSpelling::EVAL_ERROR and not ref "Perl::Critic::Exception::Fatal::Generic"->caught) 0 0 0
Condition0%0/3
$Perl::Critic::Policy::Documentation::PodSpelling::EVAL_ERROR and not ref "Perl::Critic::Exception::Fatal::Generic"->caught
!ll&&!rl&&r
000
MC/DC0%0/2
$Perl::Critic::Policy::Documentation::PodSpelling::EVAL_ERROR and not ref "Perl::Critic::Exception::Fatal::Generic"->caught
$Perl::Critic::Policy::Documentation::PodSpelling::EVAL_ERROR not ref "Perl::Critic::Exception::Fatal::Generic"->caught
Truth table0%0/3
A and not(B)
A= $Perl::Critic::Policy::Documentation::PodSpelling::EVAL_ERRORB= not ref "Perl::Critic::Exception::Fatal::Generic"->caught
ABresult
0X0
100
111
221 $EVAL_ERROR
222 and not ref Perl::Critic::Exception::Fatal::Generic->caught()
223 ) {
224 0 ▶ ref $EVAL_ERROR ? $EVAL_ERROR->rethrow() : die $EVAL_ERROR; ## no critic (ErrorHandling::RequireCarping)
Branch: 1 branch
BranchTrueFalseTotal
ref $Perl::Critic::Policy::Documentation::PodSpelling::EVAL_ERROR ? : 0 0 0
225 }
226  
227 0 return;
228 };
229  
230 0 return [ @words ];
231 }
232  
233 #-----------------------------------------------------------------------------
234  
235 sub _load_stop_words_file {
236 0 ▶ my ($self) = @_;
Subroutine _load_stop_words_file: not called CC=6 SCAR=37.4
237  
238 0 my %stop_words = %{ $self->_get_stop_words() };
239  
240 0 ▶ my $file_name = $self->_get_stop_words_file() or return;
Branch: 1 branch
BranchTrueFalseTotal
my $file_name = $self->_get_stop_words_file or return 0 0 0
241  
242 open my $handle, '<', $file_name
243 0 ▶ or do { warn qq<Could not open "$file_name": $OS_ERROR\n>; return; };
Branch: 1 branch
BranchTrueFalseTotal
open my $handle, "<", $file_name or do { warn qq[Could not open "$file_name": $Perl::Critic::Policy::Documentation::PodSpelling::OS_ERROR\n]; return } 0 0 0
244  
245 0 ▶ while ( my $line = <$handle> ) {
Branch: 1 branch
BranchTrueFalseTotal
if (defined(my $line = readline $handle)) 0 0 0
246 0 ▶ if ( my $word = _word_from_line($line) ) {
Branch: 1 branch
BranchTrueFalseTotal
if (my $word = _word_from_line($line)) 0 0 0
247 0 $stop_words{$word} = 1;
248 }
249 }
250  
251 0 ▶ close $handle or warn qq<Could not close "$file_name": $OS_ERROR\n>;
Branch: 1 branch
BranchTrueFalseTotal
close $handle or warn qq[Could not close "$file_name": $Perl::Critic::Policy::Documentation::PodSpelling::OS_ERROR\n] 0 0 0
252  
253 0 $self->_set_stop_words(\%stop_words);
254  
255 0 return;
256 }
257  
258 sub _word_from_line {
259 0 ▶ my ($line) = @_;
Subroutine _word_from_line: not called CC=1 SCAR=6.9
260  
261 0 $line =~ s< [#] .* \z ><>xms;
262 0 $line =~ s< \s+ \z ><>xms;
263 0 $line =~ s< \A \s+ ><>xms;
264  
265 0 return $line;
266 }
267  
268 #-----------------------------------------------------------------------------
269  
270 40 1;
271  
272 __END__
273  
274 #-----------------------------------------------------------------------------
275  
276 =pod
277  
278 =for stopwords foobie foobie-bletch Hmm stopwords
279  
280 =head1 NAME
281  
282 Perl::Critic::Policy::Documentation::PodSpelling - Check your spelling.
283  
284  
285 =head1 AFFILIATION
286  
287 This Policy is part of the core L<Perl::Critic|Perl::Critic>
288 distribution.
289  
290  
291 =head1 DESCRIPTION
292  
293 Did you write the documentation? Check.
294  
295 Did you document all of the public methods? Check.
296  
297 Is your documentation readable? Hmm...
298  
299 Ideally, we'd like Perl::Critic to tell you when your documentation is
300 inadequate. That's hard to code, though. So, inspired by
301 L<Test::Spelling|Test::Spelling>, this module checks the spelling of
302 your POD. It does this by pulling the prose out of the code and
303 passing it to an external spell checker. It skips over words you
304 flagged to ignore. If the spell checker returns any misspelled words,
305 this policy emits a violation.
306  
307 If anything else goes wrong -- we can't locate the spell checking program or
308 (gasp!) your module has no POD -- then this policy passes.
309  
310 To add exceptions on a module-by-module basis, add "stopwords" as
311 described in L<Pod::Spell|Pod::Spell>. For example:
312  
313 =for stopwords gibbles
314  
315 =head1 Gibble::Manip -- manipulate your gibbles
316  
317 =cut
318  
319  
320 =head1 CONFIGURATION
321  
322 This policy can be configured to tell which spell checker to use or to
323 set a global list of spelling exceptions. To do this, put entries in
324 a F<.perlcriticrc> file like this:
325  
326 [Documentation::PodSpelling]
327 spell_command = aspell list
328 stop_words = gibbles foobar
329 stop_words_file = some/path/with/stop/words.txt
330  
331 The default spell command is C<aspell list> and it is interpreted as a
332 shell command. We parse the individual arguments via
333 L<Text::ParseWords|Text::ParseWords> so feel free to use quotes around
334 your arguments. If the executable path is an absolute file name, it
335 is used as-is. If it is a relative file name, we employ
336 L<File::Which|File::Which> to convert it to an absolute path via the
337 C<PATH> environment variable. As described in Pod::Spell and
338 Test::Spelling, the spell checker must accept text on STDIN and print
339 misspelled words one per line on STDOUT.
340  
341 You can specify global stop words via the C<stop_words> and
342 C<stop_words_file> options. The former is simply split up on
343 whitespace. The latter is looked at line by line, with anything after
344 an octothorp ("#") removed and then leading and trailing whitespace
345 removed. Silly example valid file contents:
346  
347 # It's a comment!
348  
349 foo
350 arglbargl # Some other comment.
351 bar
352  
353 The values from C<stop_words> and C<stop_words_file> are merged
354 together into a single list of exemptions.
355  
356  
357 =head1 NOTES
358  
359 A spell checking program is not included with Perl::Critic.
360  
361 The results of failures for this policy can be confusing when F<aspell>
362 complains about words containing punctuation such as hyphens and apostrophes.
363 In this situation F<aspell> will often only emit part of the word that it
364 thinks is misspelled. For example, if you ask F<aspell> to check
365 "foobie-bletch", the output only complains about "foobie". Unfortunately,
366 you'll have to look through your POD to figure out what the real word that
367 F<aspell> is complaining about is. One thing to try is looking at the output
368 of C<< perl -MPod::Spell -e 'print
369 Pod::Spell->new()->parse_from_file("lib/Your/Module.pm")' >> to see what is
370 actually being checked for spelling.
371  
372  
373 =head1 PREREQUISITES
374  
375 This policy will disable itself if L<File::Which|File::Which> is not
376 available.
377  
378  
379 =head1 CREDITS
380  
381 Initial development of this policy was supported by a grant from the
382 Perl Foundation.
383  
384  
385 =head1 AUTHOR
386  
387 Chris Dolan <cdolan@cpan.org>
388  
389  
390 =head1 COPYRIGHT
391  
392 Copyright (c) 2007-2023 Chris Dolan. Many rights reserved.
393  
394 This program is free software; you can redistribute it and/or modify
395 it under the same terms as Perl itself. The full text of this license
396 can be found in the LICENSE file included with this module
397  
398 =cut
399  
400 # Local Variables:
401 # mode: cperl
402 # cperl-indent-level: 4
403 # fill-column: 78
404 # indent-tabs-mode: nil
405 # c-indentation-style: bsd
406 # End:
407 # ex: set ts=8 sts=4 sw=4 tw=78 ft=perl expandtab shiftround :
« blib/lib/Perl/Critic/Policy/Modules/ProhibitConditionalUseStatements.pm ↑ Summary blib/lib/Perl/Critic/Policy/InputOutput/ProhibitTwoArgOpen.pm »