File Coverage

blib/lib/Perl/Critic/Policy/Community/PreferredAlternatives.pm
Criterion Covered Total %
statement 22 23 95.6
branch 2 2 100.0
condition 6 9 66.6
subroutine 9 10 90.0
pod 4 5 80.0
total 43 49 87.7


line stmt bran cond sub pod time code
1             package Perl::Critic::Policy::Community::PreferredAlternatives;
2              
3 1     1   475 use strict;
  1         2  
  1         30  
4 1     1   5 use warnings;
  1         4  
  1         29  
5              
6 1     1   6 use Perl::Critic::Utils qw(:severities :classification :ppi);
  1         3  
  1         66  
7 1     1   388 use parent 'Perl::Critic::Policy';
  1         3  
  1         6  
8              
9             our $VERSION = 'v1.0.1';
10              
11             sub supported_parameters {
12             (
13             {
14 4     4 0 17826 name => 'allowed_modules',
15             description => 'Modules that you want to allow, despite there being a preferred alternative.',
16             behavior => 'string list',
17             },
18             )
19             }
20 8     8 1 85 sub default_severity { $SEVERITY_LOW }
21 0     0 1 0 sub default_themes { 'community' }
22 4     4 1 40006 sub applies_to { 'PPI::Statement::Include' }
23              
24             my %modules = (
25             'Getopt::Std' => 'Getopt::Std was the original very simplistic command-line option processing module. It is now obsoleted by the much more complete solution Getopt::Long, which also supports short options, and is wrapped by module such as Getopt::Long::Descriptive and Getopt::Long::Modern for simpler usage.',
26             'JSON' => 'JSON.pm is old and full of slow logic. Use JSON::MaybeXS instead, it is a drop-in replacement in most cases.',
27             'List::MoreUtils' => 'List::MoreUtils is a far more complex distribution than it needs to be. Use List::SomeUtils instead, or see List::Util or List::UtilsBy for alternatives.',
28             'Mouse' => 'Mouse was created to be a faster version of Moose, a niche that has since been better filled by Moo. Use Moo instead.',
29             'Readonly' => 'Readonly.pm is buggy and slow. Use Const::Fast or ReadonlyX instead, or the core pragma constant.',
30             );
31              
32             sub _violation {
33 8     8   180 my ($self, $module, $elem) = @_;
34 8         27 my $desc = "Used module $module";
35 8   33     31 my $expl = $modules{$module} // "Module $module has preferred alternatives.";
36 8         34 return $self->violation($desc, $expl, $elem);
37             }
38              
39             sub violates {
40 22     22 1 2070 my ($self, $elem) = @_;
41 22 100 66     62 return () unless defined $elem->module and exists $modules{$elem->module} and not exists $self->{_allowed_modules}{$elem->module};
      100        
42 8         611 return $self->_violation($elem->module, $elem);
43             }
44              
45             1;
46              
47             =head1 NAME
48              
49             Perl::Critic::Policy::Community::PreferredAlternatives - Various modules with
50             preferred alternatives
51              
52             =head1 DESCRIPTION
53              
54             Various modules have alternatives that are preferred by some subsets of the
55             community, for various reasons which may include: buggy behavior, cruft,
56             performance problems, maintainer issues, or simply better modern replacements.
57             This is a low severity complement to
58             L<Perl::Critic::Policy::Community::DiscouragedModules>.
59              
60             =head1 MODULES
61              
62             =head2 Getopt::Std
63              
64             L<Getopt::Std> was the original very simplistic command-line option processing
65             module. It is now obsoleted by the much more complete solution L<Getopt::Long>,
66             which also supports short options, and is wrapped by modules such as
67             L<Getopt::Long::Descriptive> and L<Getopt::Long::Modern> for simpler usage.
68              
69             =head2 JSON
70              
71             L<JSON>.pm is old and full of slow logic. Use L<JSON::MaybeXS> instead, it is a
72             drop-in replacement in most cases.
73              
74             =head2 List::MoreUtils
75              
76             L<List::MoreUtils> is a far more complex distribution than it needs to be. Use
77             L<List::SomeUtils> instead, or see L<List::Util> or L<List::UtilsBy> for
78             alternatives.
79              
80             =head2 Mouse
81              
82             L<Mouse> was created to be a faster version of L<Moose>, a niche that has since
83             been better filled by L<Moo>. Use L<Moo> instead.
84              
85             =head2 Readonly
86              
87             L<Readonly>.pm is buggy and slow. Use L<Const::Fast> or L<ReadonlyX> instead,
88             or the core pragma L<constant>.
89              
90             =head1 AFFILIATION
91              
92             This policy is part of L<Perl::Critic::Community>.
93              
94             =head1 CONFIGURATION
95              
96             Occasionally you may find yourself needing to use one of these non-preferred
97             modules, and do not want the warnings. You can do so by putting something like
98             the following in a F<.perlcriticrc> file like this:
99              
100             [Community::PreferredAlternatives]
101             allowed_modules = Getopt::Std JSON
102              
103             The same option is offered for L<Perl::Critic::Policy::Community::DiscouragedModules>.
104              
105             =head1 AUTHOR
106              
107             Dan Book, C<dbook@cpan.org>
108              
109             =head1 COPYRIGHT AND LICENSE
110              
111             Copyright 2015, Dan Book.
112              
113             This library is free software; you may redistribute it and/or modify it under
114             the terms of the Artistic License version 2.0.
115              
116             =head1 SEE ALSO
117              
118             L<Perl::Critic>