1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
|
# Copyright 2010, 2011, 2012, 2013, 2014, 2015, 2016, 2017 Kevin Ryde
# This file is part of Perl-Critic-Pulp.
# Perl-Critic-Pulp is free software; you can redistribute it and/or modify
# it under the terms of the GNU General Public License as published by the
# Free Software Foundation; either version 3, or (at your option) any later
# version.
#
# Perl-Critic-Pulp is distributed in the hope that it will be useful, but
# WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
# or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
# for more details.
#
# You should have received a copy of the GNU General Public License along
# with Perl-Critic-Pulp. If not, see <http://www.gnu.org/licenses/>.
# maybe allow comma for
# =head1 Foo
# And something,
# =head2 Item
# perlcritic -s ProhibitParagraphEndComma ProhibitParagraphEndComma.pm
# perlcritic -s ProhibitParagraphEndComma /usr/share/perl5/IO/Socket/INET6.pm
# perlcritic -s ProhibitParagraphEndComma /usr/share/perl5/MIME/Body.pm /usr/share/perl5/XML/Twig.pm
package Perl::Critic::Policy::Documentation::ProhibitParagraphEndComma;
use 5.006;
use strict;
use warnings;
use base 'Perl::Critic::Policy';
use Perl::Critic::Utils;
# uncomment this to run the ### lines
# use Smart::Comments;
our $VERSION = 96;
use constant supported_parameters => ();
use constant default_severity => $Perl::Critic::Utils::SEVERITY_LOWEST;
use constant default_themes => qw(pulp cosmetic);
use constant applies_to => 'PPI::Document';
sub violates {
my ($self, $elem, $document) = @_;
### ProhibitParagraphEndComma on: $elem->content
my $parser = Perl::Critic::Pulp::PodParser::ProhibitParagraphEndComma->new
(policy => $self);
$parser->parse_from_elem ($elem);
$parser->check_last;
return $parser->violations;
}
package Perl::Critic::Pulp::PodParser::ProhibitParagraphEndComma;
use strict;
use warnings;
use base 'Perl::Critic::Pulp::PodParser';
sub new {
my $class = shift;
### new() ...
return $class->SUPER::new (last_text => '',
last_command => '',
@_);
}
sub command {
my ($self, $command, $text, $linenum, $paraobj) = @_;
### command(): $command
# "=begin :foo" means pod markup continues. Ignore the =begin and
# continue processing POD within it. Any other begin is a new block
# something and preceding comma not allowed.
#
if ($command eq 'for'
|| $command eq 'pod'
|| ($command eq 'begin' && $text =~ /^\s*:/)
|| $command eq 'end') {
return; # ignore these completely
}
if ($command eq 'item' && $self->{'last_command'} eq 'item') {
# Paragraphs in =item list can end in successive commas.
} elsif ($command eq 'over') {
} else {
$self->check_last;
}
$self->{'last_text'} = '';
$self->{'last_command'} = $command;
}
sub textblock {
my ($self, $text, $linenum, $paraobj) = @_;
### textblock(): $text
$self->check_last;
# sometimes $text=undef from Pod::Parser
if (! defined $text) { $text = ''; }
$self->{'last_linenum'} = $linenum;
$self->{'last_text'} = $text;
}
sub verbatim {
my ($self, $text, $linenum, $paraobj) = @_;
# anything before a verbatim is ok
$self->{'last_text'} = '';
}
sub check_last {
my ($self) = @_;
### check_last() ...
### in_begin: $self->{'in_begin'}
if ($self->{'in_begin'} && $self->{'in_begin'} !~ /^:/) {
# =begin block of non-: means not pod markup
} elsif ($self->{'last_text'} =~ /(,\s*)$/s) {
### last_text ends comma ...
my $pos = length($self->{'last_text'}) - length($1); # position of comma
$self->violation_at_linenum_and_textpos
("Paragraph ends with comma",
$self->{'last_linenum'}, $self->{'last_text'}, $pos);
}
$self->{'last_text'} = '';
}
1;
__END__
=for stopwords Ryde
=head1 NAME
Perl::Critic::Policy::Documentation::ProhibitParagraphEndComma - avoid comma at end of section
=head1 DESCRIPTION
This policy is part of the L<C<Perl::Critic::Pulp>|Perl::Critic::Pulp>
add-on. It asks you not to end a POD paragraph with a comma.
Some text, # bad, meant to be a full-stop?
Some more text.
Usually such a comma is meant to be a full-stop, or perhaps omitted at the
end of a "SEE ALSO" list
=for ProhibitVerbatimMarkup allow next 2
=head1 SEE ALSO
L<Foo>,
L<Bar>, # bad, meant to be omitted?
A paragraph before an C<=over> or a verbatim block is allowed to end with a
comma, that being taken as introducing a quotation or example,
For example, # ok, introduce an example
foo(1+2+3)
Or one of, # ok, introduce an itemized list
=over
=item Foo
=head2 Disabling
If you don't care about this you can disable C<ProhibitParagraphEndComma>
from your F<.perlcriticrc> in the usual way (see
L<Perl::Critic/CONFIGURATION>),
[-Documentation::ProhibitParagraphEndComma]
=head1 SEE ALSO
L<Perl::Critic::Pulp>, L<Perl::Critic>
L<Perl::Critic::Policy::Documentation::ProhibitParagraphTwoDots>
=head1 HOME PAGE
http://user42.tuxfamily.org/perl-critic-pulp/index.html
=head1 COPYRIGHT
Copyright 2010, 2011, 2012, 2013, 2014, 2015, 2016, 2017 Kevin Ryde
Perl-Critic-Pulp is free software; you can redistribute it and/or modify it
under the terms of the GNU General Public License as published by the Free
Software Foundation; either version 3, or (at your option) any later
version.
Perl-Critic-Pulp is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for
more details.
You should have received a copy of the GNU General Public License along with
Perl-Critic-Pulp. If not, see <http://www.gnu.org/licenses/>.
=cut
|
