Perl Critic
1.0.0
perl ::评论家 - 最佳实践的评论perl源代码。
use Perl::Critic;
my $file = shift;
my $critic = Perl::Critic->new();
my @violations = $critic->critique($file);
print @violations;
Perl ::评论家是一个可扩展的框架，用于创建和应用编码标准到Perl源代码。本质上，它是静态源代码分析引擎。 perl ::评论家与许多perl ::评论::试图执行各种编码准则的政策模块分发。大多数政策模块基于达米安·康威（Damian Conway）的书《珀尔（Perl）的最佳实践》 。但是，Perl ::评论家不仅限于PBP，甚至会支持与Conway相矛盾的政策。您可以通过perl ::评论家界面启用，禁用和自定义这些策略。您还可以创建适合自己口味的新政策模块。
有关Perl ::评论家的命令行接口，请参阅Perlcritic的文档。如果您想将Perl ::评论家与您的构建过程集成，请测试:: Perl ::评论家提供适合测试程序的界面。另外，Test :: Perl :: Critic ::渐进级对于逐渐将编码标准应用于旧版代码很有用。为了最终的方便（以某种灵活性为代价），请参阅Pragma的批评。
如果您想在不安装任何内容的情况下尝试Perl ::评论家，则可以在http://perlcritic.com上提供一个网络服务。 Web服务尚未支持本机Perl :: Critic API中可用的所有配置功能，但它应该使您对其的作用有一个好了解。
同样，ActivePerl包括一个非常光滑的图形界面，称为perlcritic-gui 。您可以从http://www.activestate.com获得免费的社区版ActivePerl。
perl ::评论家在佩尔（Perl）上回到佩尔（Perl）5.10.1。它依靠PPI模块来完成解析perl的繁重工作。
Perl::Critic模块被认为是公共班级。其接口的任何更改都将通过折旧周期进行。
new( [ -profile => $FILE, -severity => $N, -theme => $string, -include => @PATTERNS, -exclude => @PATTERNS, -top => $N, -only => $B, -profile-strictness => $PROFILE_STRICTNESS_{WARN|FATAL|QUIET}, -force => $B, -verbose => $N ], -color => $B, -pager => $string, -allow-unsafe => $B, -criticism-fatal => $B)
new()
返回对新Perl ::评论家对象的引用。大多数参数只是直接传递到Perl :: Critic :: config，但我也在这里描述了它们。所有参数的默认值可以在.perlcriticrc文件中定义。有关此信息的更多信息，请参见“配置”部分。所有论点都是可选的键值对，如下：
- profile是配置文件的途径。如果未定义$FILE ，请perl :: Critis :: Config尝试在当前目录中查找.perlcriticrc配置文件，然后在主目录中找到。另外，您可以将PERLCRITIC环境变量设置为指向另一个位置的文件。如果找不到配置文件，或者$FILE是一个空字符串，则所有策略都将加载其默认配置。有关更多信息，请参见“配置”。
- 严重程度是最低严重程度。只有大于$N严重程度的政策模块才能应用。严重性值是整数范围从1（最小违规）到5（最严重的违规行为）。默认值为5。对于给定的-profile较低的-severity ，通常会揭示更多违反政策的行为。您可以在.perlcriticrc文件中设置此选项的默认值。用户可以重新定义其.perlcriticrc文件中任何策略的严重性级别。有关更多信息，请参见“配置”。
如果您很难记住严重性“ 5”是最限制的水平，那么您可以使用以下命名值之一：
SEVERITY NAME ...is equivalent to... SEVERITY NUMBER
--------------------------------------------------------
-severity => 'gentle' -severity => 5
-severity => 'stern' -severity => 4
-severity => 'harsh' -severity => 3
-severity => 'cruel' -severity => 2
-severity => 'brutal' -severity => 1
名字反映了该守则被批评的严重程度： gentle批评只报告了最严重的违规行为，依此类推，直到brutal批评，甚至报告了最小的违规行为。
-是特殊表达，它决定了哪些政策基于其各自的主题应用。例如，以下将仅加载具有“错误”和“ PBP”主题的策略：
my $critic = Perl::Critic->new( -theme => 'bugs && pbp' );
除非明确给出-severity选项，否则设置-theme将-severity设置为1。您可以在.perlcriticrc文件中设置此选项的默认值。有关主题的更多信息，请参见“政策主题”部分。
- 包括对字符串@PATTERNS列表的引用。与所有其他设置无关，将始终加载至少一个m/$PATTERN/ixms策略模块。例如：
my $critic = Perl::Critic->new(-include => ['layout'], -severity => 4);
这将导致Perl ::评论家应用所有CodeLayout::*策略模块，即使它们的严重性级别小于4。您可以在.perlcriticrc文件中设置此选项的默认值。您也可以与-exclude选项结合使用-include 。请注意，当策略匹配这两种模式时， -exclude优先于-include 。
-Exclude是对字符串@PATTERNS列表的引用。与所有其他设置无关，将不会加载至少一个m/$PATTERN/ixms策略模块。例如：
my $critic = Perl::Critic->new(-exclude => ['strict'], -severity => 1);
这将导致Perl ::评论家不应用RequireUseStrict和ProhibitNoStrict策略”模块，即使它们具有大于1的严重性级别。您可以在.perlcriticrc文件中为此选项设置默认值。您也可以与-include选项一起使用-exclude 。请注意，当策略匹配这两种模式时， -exclude优先于-include 。
- 单调是弦PATTERN 。只能使用与m/$PATTERN/ixms匹配的策略。不匹配的政策将被排除在外。此选项优先于-severity ， -theme ， -include ， -exclude和-only选项。您可以在.perlcriticrc文件中设置此选项的默认值。
-TOP是按其严重程度排名时要返回的最大违规数量。这必须是一个积极的整数。违规行为仍然按照文件内发生的顺序返回。除非明确给出-severity选项，否则将-top默默设置为将-severity设置为1。您可以在.perlcriticrc文件中设置此选项的默认值。
- 仅是布尔值。如果设置为真值，Perl :: Criter只会从用户个人资料中提到的策略中进行选择。如果设置为假值（默认值），则Perl ::评论家从其网站上找到的所有策略中选择。您可以在.perlcriticrc文件中设置此选项的默认值。
- profile-trictness是一个枚举的价值，是perl :: critis :: critis :: utils :: utils :: constants（默认），“ $ profile_strictness_fatal”中的“ $ profile_strictness_warn”之一。如果设置为perl :: critis :: utils ::常数为“ $ profile_strictness_fatal”，则perl :: Critic将对在.perlcriticrc或通过-profile opare oparife fatal指定的文件中发现的问题发出某些警告。例如，Perl ::评论家通常只warn说涉及不存在的政策的个人资料，但这种价值使这种情况致命。相应地，perl :: Critic :: utils ::常数使Perl :: Critic闭嘴。
-force是一个布尔值，它控制着perl ::评论家是否观察到您的代码中的神奇的"## no critic"注释。如果设置为真值，Perl ::评论家将分析所有代码。如果设置为false值（默认值）perl ::评论家将忽略用这些注释标记的代码。有关更多信息，请参见“弯曲规则”。您可以在.perlcriticrc文件中设置此选项的默认值。
- 静脉可以是正整数（从1到11），也可以是文字格式规范。参见Perl ::评论家::违反格式规格的解释。您可以在.perlcriticrc文件中设置此选项的默认值。
-Unsafe指示Perl ::评论家允许使用作者标记为“不安全”的政策。此类政策可能会编译不信任的代码或做其他邪恶的事情。
-Perl ::评论家未使用- 颜色和- pager ，而是为了perlcritic的好处而提供。
- 批评者未使用批评战术，而是出于批评的好处。
- 彩色 - 彩色- 颜色 - 五个高， - 彩色 - 五个介质， -color-coreverity-low和-color-colory-lowest- perl :: critist in Cittor in crialted of Perlcritic的好处。每个都设置为术语:: ansicolor颜色规范，以显示违反相应严重性的违规行为。
- perl ::评论家未使用侵略性和- 罪行，而无侵略性则不使用，而是为了perlcritic的好处而提供，仅会显示要显示的相关文件名。
critique( $source_code )
使用已加载到该引擎中的所有策略的Perl :: Criver Engine运行$source_code 。如果$source_code是标量参考，则将其视为实际的perl代码字符串。如果$source_code是对PPI ::文档实例的引用，则该实例直接使用。否则，将其视为包含Perl代码的本地文件的途径。此方法返回perl :: Critic ::违反对象的违规对象的列表。该列表按顺序排序，即违规行为出现在代码中。如果没有违规行为，此方法将返回一个空列表。
add_policy( -policy => $policy_name, -params => %param_hash )
创建一个策略对象并将其加载到该评论家中。如果无法实例化对象，它将抛出致命的例外。否则，它将返回对该评论家的参考。
-policy是Perl :: Critic ::政策子类模块的名称。 'Perl::Critic::Policy'部分可以为简洁而省略。需要这个论点。
-Params是对策略参数哈希的可选参考。该哈希参考的内容将传递到策略模块的构造函数中。有关其支持的参数的描述，请参见相关策略模块中的文档。
policies()
返回包含对已加载到该引擎的所有策略对象的引用的列表。对象将按其加载顺序。
config()
返回perl :: Critic ::配置对象，该对象是为该评论家创建或给出的。
statistics()
返回为这个评论家创建的Perl ::评论::统计对象。统计对象累积了该评论家分析的所有文件的数据。
对于那些喜欢具有功能接口的人，可以根据请求导出critique方法并将其称为静态函数。如果第一个论点是hashref，则它的内容用于内部构建新的perl ::评论家对象。该哈希的键应与Perl::Critic::new()方法支持的密钥相同。这里有一些例子：
use Perl::Critic qw(critique);
# Use default parameters...
@violations = critique( $some_file );
# Use custom parameters...
@violations = critique( {-severity => 2}, $some_file );
# As a one-liner
%> perl -MPerl::Critic=critique -e 'print critique(shift)' some_file.pm
目前均未支持其他对象方法作为静态功能。对不起。
Perl ::评论家和每个策略模块的大多数设置都可以由配置文件控制。默认配置文件称为.perlcriticrc 。 perl ::评论家将首先在当前目录中查找此文件，然后在您的主目录中查找此文件。另外，您可以设置PERLCRITIC环境变量，以明确指向另一个位置的另一个文件。如果这些文件都不存在，并且未给出-profile选项给构造函数，则将在Perl :: critis :: policy Namespace中找到的所有模块都带有其默认配置。
配置文件的格式是一系列INI风格的块，其中包含由'='隔开的键值对。评论应以“＃”开头，如果需要的话，可以放在单独的行或名称值对之后。
Perl ::评论家本身的默认设置可以在第一个命名块之前设置。例如，将这些或全部的任何或全部放在配置文件的顶部都会为相应的构造函数参数设置默认值。
severity = 3 #Integer or named level
only = 1 #Zero or One
force = 0 #Zero or One
verbose = 4 #Integer or format spec
top = 50 #A positive integer
theme = (pbp || security) && bugs #A theme expression
include = NamingConventions ClassHierarchies #Space-delimited list
exclude = Variables Modules::RequirePackage #Space-delimited list
criticism-fatal = 1 #Zero or One
color = 1 #Zero or One
allow-unsafe = 1 #Zero or One
pager = less #pager to pipe output to
配置文件的其余部分是这样的一系列块：
[Perl::Critic::Policy::Category::PolicyName]
severity = 1
set_themes = foo bar
add_themes = baz
maximum_violations_per_document = 57
arg1 = value1
arg2 = value2
Perl::Critic::Policy::Category::PolicyName是实现策略的模块的全名。根据Damian Conway的书Perl最佳实践中的最佳实践中的目录，与Perl ::评论家分发的政策模块已分为类别。对于简洁起见，您可以省略模块名称的'Perl::Critic::Policy'部分。
severity是您希望分配给政策的重要性。所有政策模块均定义为默认严重性值，范围从1（最少）到5（最严重）。但是，您可能会不同意默认的严重性，并根据自己的编码理念选择更高或更低的严重性。您可以将severity设置为1到5的整数，也可以使用等效名称之一：
SEVERITY NAME ...is equivalent to... SEVERITY NUMBER
----------------------------------------------------
gentle 5
stern 4
harsh 3
cruel 2
brutal 1
名字反映了该守则被批评的严重程度： gentle批评只报告了最严重的违规行为，依此类推，直到brutal批评，甚至报告了最小的违规行为。
set_themes为策略设置主题，并覆盖其默认主题。该论点是一个或多个空格偏置的字母数字单词的字符串。主题不敏感。有关更多信息，请参见“政策主题”。
add_themes将此策略的默认主题附加。该论点是一个或多个空格限制的单词的字符串。主题是不敏感的。有关更多信息，请参见“政策主题”。
maximum_violations_per_document限制了策略将返回给定文档的违规数量。某些政策具有默认限制；请参阅单个政策的文档，以查看是否存在。要强制策略没有限制，请为此参数的值指定“ no_limit”或空字符串。
其余的键值对是配置参数，将传递到该策略的构造函数中。大多数策略对象的构造函数不支持参数，而确实应该有合理的默认值。有关更多详细信息，请参见有关适当策略模块的文档。
您可以通过将A - “”预先为配置文件中的模块名称进行准备，而不是重新定义给定策略的严重性，而是可以完全禁用策略。无论如何提供给perl ::评论家构造者的 - -severity ，因此永远不会加载该政策。
一种简单的配置可能看起来像这样：
#--------------------------------------------------------------
# I think these are really important, so always load them
[TestingAndDebugging::RequireUseStrict]
severity = 5
[TestingAndDebugging::RequireUseWarnings]
severity = 5
#--------------------------------------------------------------
# I think these are less important, so only load when asked
[Variables::ProhibitPackageVars]
severity = 2
[ControlStructures::ProhibitPostfixControls]
allow = if unless # My custom configuration
severity = cruel # Same as "severity = 2"
#--------------------------------------------------------------
# Give these policies a custom theme. I can activate just
# these policies by saying `perlcritic -theme larry`
[Modules::RequireFilenameMatchesPackage]
add_themes = larry
[TestingAndDebugging::RequireTestLabels]
add_themes = larry curly moe
#--------------------------------------------------------------
# I do not agree with these at all, so never load them
[-NamingConventions::Capitalization]
[-ValuesAndExpressions::ProhibitMagicNumbers]
#--------------------------------------------------------------
# For all other Policies, I accept the default severity,
# so no additional configuration is required for them.
有关其他配置示例，请参见此分布的此examples目录中包含的perlcriticrc文件。
达米安·康威（Damian Conway）自己的perl ::评论家的配置也包括在此分布中作为examples/perlcriticrc-conway 。
Perl ::评论家分发了大量的政策模块。在同伴文档perl :: Critic :: PolicySummary和单个模块本身中更详细地描述了它们。说"perlcritic -doc PATTERN"以查看与正则态度m/PATTERN/ixms匹配的所有策略模块的perldoc
CPAN上有许多其他策略分布。如果Perl ::评论家不包含您想要的政策，那么某些人可能已经写了它。有关其中一些分布的列表，请参见下面的“请参见”部分。
每个策略都用一个或多个“主题”定义。主题可用于创建任意策略组。他们旨在提供选择您首选的一组政策的替代机制。例如，在分析测试程序时，您可能希望禁用一定部分的策略。相反，您可能希望在分析模块时仅启用特定的策略子集。
与Perl ::评论家一起发货的政策已被打破以下主题。这只是我们提供一些基本逻辑分组的尝试。您可以自由发明适合您需求的新主题。
THEME DESCRIPTION
--------------------------------------------------------------------------
core All policies that ship with Perl::Critic
pbp Policies that come directly from "Perl Best Practices"
bugs Policies that that prevent or reveal bugs
certrec Policies that CERT recommends
certrule Policies that CERT considers rules
maintenance Policies that affect the long-term health of the code
cosmetic Policies that only have a superficial effect
complexity Policies that specifically relate to code complexity
security Policies that relate to security issues
tests Policies that are specific to test programs
任何政策都可能符合多个主题。说"perlcritic -list"以获取所有可用策略和与每个策略相关的主题的列表。您还可以更改.perlcriticrc文件中任何策略的主题。有关此信息的更多信息，请参见“配置”部分。
使用-theme选项，您可以创建一个任意复杂的规则，该规则确定将加载哪些策略。优先级与常规PERL代码相同，您也可以使用括号来执行优先级。受支持的运营商是：
Operator Alternative Example
-----------------------------------------------------------------
&& and 'pbp && core'
|| or 'pbp || (bugs && security)'
! not 'pbp && ! (portability || complexity)'
主题名称是不敏感的。如果将-theme设置为一个空字符串，则将其评估为所有策略。
perl ::评论家对您的代码采取了硬线方法：您要么遵守或不遵守。在现实世界中，完全遵守编码标准并不总是实用的（甚至可能）。在这种情况下，明智的做法是表明您有意违反标准，并且您对此有充分的理由（DGR）。
为了帮助这些情况，您可以通过使用注释来指示Perl ::评论家忽略某些行或代码块：
require 'LegacyLibaray1.pl'; ## no critic
require 'LegacyLibrary2.pl'; ## no critic
for my $element (@list) {
## no critic
$foo = ""; #Violates 'ProhibitEmptyQuotes'
$barf = bar() if $foo; #Violates 'ProhibitPostfixControls'
#Some more evil code...
## use critic
#Some good code...
do_something($_);
}
"## no critic"注释直接perl ::评论家忽略剩余的代码，直到找到"## use critic"注释。如果"## no critic"注释与代码语句同一行，则只有该行被忽略了。要指导Perlcritic忽略"## no critic"注释，请使用--force选项。
裸露的"## no critic"注释可以禁用所有主动政策。如果您只想禁用特定的策略，请添加策略名称作为参数的列表，就像您对"no strict"或"no warnings"布拉格马斯一样。例如，这将禁用ProhibitEmptyQuotes和ProhibitPostfixControls政策，直到块结束或下一个"## use critic"注释（以先到者为准）：
## no critic (EmptyQuotes, PostfixControls)
# Now exempt from ValuesAndExpressions::ProhibitEmptyQuotes
$foo = "";
# Now exempt ControlStructures::ProhibitPostfixControls
$barf = bar() if $foo;
# Still subjected to ValuesAndExpression::RequireNumberSeparators
$long_int = 10000000000;
由于策略名称与"## no critic"论点相匹配，因此您可以缩写策略名称或以这样的镜头禁用整个政策家庭：
## no critic (NamingConventions)
# Now exempt from NamingConventions::Capitalization
my $camelHumpVar = 'foo';
# Now exempt from NamingConventions::Capitalization
sub camelHumpSub {}
该参数列表必须包含在括号或括号中，并且必须包含一个或多个逗号分隔的裸字（例如不要使用引号）。可以嵌套"## no critic"注释，并且内部注释命名的策略将被禁用，而那些已经禁用了外部注释。
某些政策（例如Subroutines::ProhibitExcessComplexity适用于整个代码。在这些情况下，必须出现"## no critic"注释在报告违法行为的线上。例如：
sub complicated_function { ## no critic (ProhibitExcessComplexity)
# Your code here...
}
诸如Documentation::RequirePodSections类的策略适用于整个文档，在这种情况下，违反了第1行。
明智地使用此功能。 "## no critic"注释应在最小的范围或单个代码行中使用。而且，您应该始终对要禁用哪些政策尽可能具体（即永远不会使用裸露的"## no critic" ）。如果Perl ::评论家抱怨您的代码，请在诉诸此功能之前尝试找到合规的解决方案。
编码标准是个人的，高度主观的。 Perl ::评论家的目标是帮助您编写符合一组最佳实践的代码。我们的主要目标不是决定这些做法是什么，而是要实施他人发现的实践。最终，您制定规则-Perl ::评论家只是鼓励一致性的工具。如果您认为有一项重要的政策很重要，或者我们已经忽略了，我们将非常感谢贡献，或者您可以简单地将自己的私人政策加载到Perl ::评论家中。
Perl ::评论家的模块化设计旨在促进新政策的添加。您需要对PPI有一定的了解，但是大多数策略模块非常简单，只需要大约20行代码。请参阅此分布中包含的Perl :: Critic ::开发人员文件，以逐步演示如何创建新的策略模块。
如果您开发了任何新的政策模块，请随时将它们发送到<[email protected]> ，我很乐意考虑将它们放入Perl ::评论家发行。或者，如果您想直接从事Perl ::评论家项目，则可以通过https://github.com/perl-critic/perl-critic.git提供我们的存储库。
Perl ::评论家团队也可以租用。如果您的组织具有自己的编码标准，我们可以制定自定义政策来执行您的本地准则。或者，如果您的代码基库容易出现特定的缺陷模式，我们可以设计政策，以帮助您在生产之前捕获这些昂贵的缺陷。要与perl ::评论家团队讨论您的需求，只需联系<[email protected]> 。
perl ::评论家需要以下模块：
B ::关键字
config :: tiny
异常::班级
文件:: Spec
文件:: Spec :: Unix
文件::哪个
列表:: Someutils
列表:: util
模块::可插的
perl ::整理
Pod :: spell
PPI
pod ::明文
POD :: SELECT
pod ::用法
可读
标量:: util
字符串::格式
术语:: ansicolor
文字:: parsewords
版本
鼓励您在https://groups.google.com/d/forum/perl-critic上订阅公共邮件列表。开发团队的至少一名成员通常会在IRC：//irc.perl.org/#perlcritic中闲逛，您可以在Twitter上关注Perl ::评论家，网址为https：//twitter.com/perlcritic。
有许多其他策略分布。这里列出了一些：
perl ::评论家::更多
perl ::评论家::刘海
perl ::评论家:: lax
perl ::评论家:: STRICTERSUBS
Perl ::评论家:: Swift
perl ::评论家:: TICS
这些分布使您可以在单位测试中使用perl ::评论家：
测试:: Perl ::评论家
测试:: Perl ::评论家::进步
还有一个分布将安装所有Perl ::评论家相关的模块：开发团队已知的模块：
任务:: Perl ::评论家
对人类的审查很难进行审查，更不用说机器了。如果您发现了任何错误，尤其是来自Perl :: Critic :: Policy的错误persions或False-Vistives，请在https://github.com/perl-critic/perl-critic/issues上提交它们。谢谢。
亚当·肯尼迪（Adam Kennedy） - 创造了PPI，Perl ::评论家的心灵和灵魂。
达米安·康威（Damian Conway） - 终于写Perl最佳实践:)
克里斯·多兰（Chris Dolan） - 贡献最佳功能和政策模块。
安迪·莱斯特（Andy Lester） - 明智的圣人和全能测试的主人。
艾略特·尚克（Elliot Shank） - 自称质量的怪胎。
朱塞佩·马克西亚（Giuseppe Maxia） - 为了所有的伟大想法和积极的鼓励。
和我的妻子沙龙（Sharon） - 忍受了我的全夜代码会议。
还要感谢Perl Foundation提供的赠款，以支持Chris Dolan的项目，以实施二十个PBP政策。 http://www.perlfoundation.org/april_1_2007_new_grant_awards
Thanks also to this incomplete laundry list of folks who have contributed to Perl::Critic in some way: Gregory Oschwald, Mike O'Regan, Tom Hukins, Omer Gazit, Evan Zacks, Paul Howarth, Sawyer X, Christian Walde, Dave Rolsky, Jakub Wilk, Roy Ivy III, Oliver Trosien, Glenn Fowler, Matt Creenan, Alex Balhatchet, Sebastian Paaske Tørholm, Stuart A Johnston, Dan Book, Steven Humphrey, James Raspass, Nick Tonkin, Harrison Katz, Douglas Sims, Mark Fowler, Alan Berndt, Neil Bowers, Sergey Romanov, Gabor Szabo, Graham Knop, Mike Eldridge, David Steinbrunner, Kirk Kimmel，Guillaume Aubert，Dave Cross，Anirvan Chatterjee，Todd Rinaldo，Graham Ollis，Karen Etheridge，JonasBrømsø，Olaf Alders，Jim Keenan，SlavenRezić，SzymonNieznański。
jeffrey ryan thalhammer [email protected]
版权（C）2005-2018富有想象力的软件系统。保留所有权利。
该程序是免费软件；您可以将其重新分配和/或以与Perl本身相同的条款进行修改。可以在此模块中包含的许可文件中找到此许可证的全文。
