| 1 | #!/usr/local/bin/perl | ||||||||||||||||||||||||||||
| 2 | |||||||||||||||||||||||||||||
| 3 | package main; | ||||||||||||||||||||||||||||
| 4 | |||||||||||||||||||||||||||||
| 5 | 1 | ▶ | use 5.010001; | ||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||
| 6 | 1 | ▶ | use strict; | ||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||
| 7 | 1 | ▶ | use warnings; | ||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||
| 8 | |||||||||||||||||||||||||||||
| 9 | 1 | ▶ | use Perl::Critic::Command qw< run >; | ||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||
| 10 | |||||||||||||||||||||||||||||
| 11 | #----------------------------------------------------------------------------- | ||||||||||||||||||||||||||||
| 12 | |||||||||||||||||||||||||||||
| 13 | 1 | our $VERSION = '1.150'; | |||||||||||||||||||||||||||
| 14 | |||||||||||||||||||||||||||||
| 15 | #----------------------------------------------------------------------------- | ||||||||||||||||||||||||||||
| 16 | # Begin program. Don't run when loaded as a library | ||||||||||||||||||||||||||||
| 17 | |||||||||||||||||||||||||||||
| 18 | # This %ENV check is to allow perlcritic to function when bundled under PAR, | ||||||||||||||||||||||||||||
| 19 | # which invokes this program not as the top stack frame. -- rjbs, 2008-08-11 | ||||||||||||||||||||||||||||
| 20 | 1 | ▶ | exit run() if not caller or $ENV{PAR_0}; | ||||||||||||||||||||||||||
|
Branch: 1 branch
Condition33%1/3
not caller or $ENV{"PAR_0"}
MC/DC0%0/2
not caller or $ENV{"PAR_0"}
not caller
$ENV{"PAR_0"}
Truth table33%1/3
not(A) or B
A= not callerB= $ENV{"PAR_0"}
| |||||||||||||||||||||||||||||
| 21 | |||||||||||||||||||||||||||||
| 22 | #----------------------------------------------------------------------------- | ||||||||||||||||||||||||||||
| 23 | 1 | 1; | |||||||||||||||||||||||||||
| 24 | |||||||||||||||||||||||||||||
| 25 | __END__ | ||||||||||||||||||||||||||||
| 26 | |||||||||||||||||||||||||||||
| 27 | #----------------------------------------------------------------------------- | ||||||||||||||||||||||||||||
| 28 | |||||||||||||||||||||||||||||
| 29 | =pod | ||||||||||||||||||||||||||||
| 30 | |||||||||||||||||||||||||||||
| 31 | =for stopwords DGR INI-style vim-fu minibuffer -noprofile API | ||||||||||||||||||||||||||||
| 32 | -profileproto -profile-proto ben Jore formatter Peshak pbp Komodo | ||||||||||||||||||||||||||||
| 33 | screenshots tty emacs gVIM plugin Perlish templating ActivePerl | ||||||||||||||||||||||||||||
| 34 | ActiveState Twitter macOS | ||||||||||||||||||||||||||||
| 35 | |||||||||||||||||||||||||||||
| 36 | =head1 NAME | ||||||||||||||||||||||||||||
| 37 | |||||||||||||||||||||||||||||
| 38 | C<perlcritic> - Command-line interface to critique Perl source. | ||||||||||||||||||||||||||||
| 39 | |||||||||||||||||||||||||||||
| 40 | |||||||||||||||||||||||||||||
| 41 | =head1 SYNOPSIS | ||||||||||||||||||||||||||||
| 42 | |||||||||||||||||||||||||||||
| 43 | perlcritic [-12345 | --brutal | --cruel | --harsh | --stern | --gentle] | ||||||||||||||||||||||||||||
| 44 | [--severity number | name] [{-p | --profile} file | --noprofile] | ||||||||||||||||||||||||||||
| 45 | [--top [ number ]] [--theme expression] [--include pattern] | ||||||||||||||||||||||||||||
| 46 | [--exclude pattern] [{-s | --single-policy} pattern] | ||||||||||||||||||||||||||||
| 47 | [--only | --noonly] [--profile-strictness {warn|fatal|quiet}] | ||||||||||||||||||||||||||||
| 48 | [--force | --noforce] [--statistics] [--statistics-only] | ||||||||||||||||||||||||||||
| 49 | [--count | -C] [--verbose {number | format}] [--allow-unsafe] | ||||||||||||||||||||||||||||
| 50 | [--color | --nocolor] [--pager pager] [--quiet] | ||||||||||||||||||||||||||||
| 51 | [--color-severity-highest color_specification] | ||||||||||||||||||||||||||||
| 52 | [--color-severity-high color_specification] | ||||||||||||||||||||||||||||
| 53 | [--color-severity-medium color_specification] | ||||||||||||||||||||||||||||
| 54 | [--color-severity-low color_specification] | ||||||||||||||||||||||||||||
| 55 | [--color-severity-lowest color_specification] | ||||||||||||||||||||||||||||
| 56 | [--files-with-violations | -l] | ||||||||||||||||||||||||||||
| 57 | [--files-without-violations | -L] | ||||||||||||||||||||||||||||
| 58 | [--program-extensions file_name_extension] | ||||||||||||||||||||||||||||
| 59 | {FILE | DIRECTORY | STDIN} | ||||||||||||||||||||||||||||
| 60 | |||||||||||||||||||||||||||||
| 61 | perlcritic --profile-proto | ||||||||||||||||||||||||||||
| 62 | |||||||||||||||||||||||||||||
| 63 | perlcritic { --list | --list-enabled | --list-themes | --doc pattern [...] } | ||||||||||||||||||||||||||||
| 64 | |||||||||||||||||||||||||||||
| 65 | perlcritic { --help | --options | --man | --version } | ||||||||||||||||||||||||||||
| 66 | |||||||||||||||||||||||||||||
| 67 | |||||||||||||||||||||||||||||
| 68 | =head1 DESCRIPTION | ||||||||||||||||||||||||||||
| 69 | |||||||||||||||||||||||||||||
| 70 | C<perlcritic> is a Perl source code analyzer. It is the executable front-end | ||||||||||||||||||||||||||||
| 71 | to the L<Perl::Critic> engine, which attempts to identify awkward, hard to | ||||||||||||||||||||||||||||
| 72 | read, error-prone, or unconventional constructs in your code. Most of the | ||||||||||||||||||||||||||||
| 73 | rules are based on Damian Conway's book B<Perl Best Practices>. However, | ||||||||||||||||||||||||||||
| 74 | C<perlcritic> is B<not> limited to enforcing PBP, and it will even support | ||||||||||||||||||||||||||||
| 75 | rules that contradict Conway. All rules can easily be configured or disabled | ||||||||||||||||||||||||||||
| 76 | to your liking. | ||||||||||||||||||||||||||||
| 77 | |||||||||||||||||||||||||||||
| 78 | This documentation only covers how to drive this command. For all other | ||||||||||||||||||||||||||||
| 79 | information, such as API reference and alternative interfaces, please see the | ||||||||||||||||||||||||||||
| 80 | documentation for L<Perl::Critic> itself. | ||||||||||||||||||||||||||||
| 81 | |||||||||||||||||||||||||||||
| 82 | |||||||||||||||||||||||||||||
| 83 | =head1 USAGE EXAMPLES | ||||||||||||||||||||||||||||
| 84 | |||||||||||||||||||||||||||||
| 85 | Before getting into all the gory details, here are some basic usage | ||||||||||||||||||||||||||||
| 86 | examples to help get you started. | ||||||||||||||||||||||||||||
| 87 | |||||||||||||||||||||||||||||
| 88 | # Report only most severe violations (severity = 5) | ||||||||||||||||||||||||||||
| 89 | perlcritic YourModule.pm | ||||||||||||||||||||||||||||
| 90 | |||||||||||||||||||||||||||||
| 91 | # Same as above, but read input from STDIN | ||||||||||||||||||||||||||||
| 92 | perlcritic | ||||||||||||||||||||||||||||
| 93 | |||||||||||||||||||||||||||||
| 94 | # Recursively process all Perl files beneath directory | ||||||||||||||||||||||||||||
| 95 | perlcritic /some/directory | ||||||||||||||||||||||||||||
| 96 | |||||||||||||||||||||||||||||
| 97 | # Report slightly less severe violations too (severity >= 4) | ||||||||||||||||||||||||||||
| 98 | perlcritic -4 YourModule.pm | ||||||||||||||||||||||||||||
| 99 | |||||||||||||||||||||||||||||
| 100 | # Same as above, but using named severity level | ||||||||||||||||||||||||||||
| 101 | perlcritic --stern YourModule.pm | ||||||||||||||||||||||||||||
| 102 | |||||||||||||||||||||||||||||
| 103 | # Report all violations, regardless of severity (severity >= 1) | ||||||||||||||||||||||||||||
| 104 | perlcritic -1 YourModule.pm | ||||||||||||||||||||||||||||
| 105 | |||||||||||||||||||||||||||||
| 106 | # Same as above, but using named severity level | ||||||||||||||||||||||||||||
| 107 | perlcritic --brutal YourModule.pm | ||||||||||||||||||||||||||||
| 108 | |||||||||||||||||||||||||||||
| 109 | # Report only violations of things from "Perl Best Practices" | ||||||||||||||||||||||||||||
| 110 | perlcritic --theme pbp YourModule.pm | ||||||||||||||||||||||||||||
| 111 | |||||||||||||||||||||||||||||
| 112 | # Report top 20 most severe violations (severity >= 1) | ||||||||||||||||||||||||||||
| 113 | perlcritic --top YourModule.pm | ||||||||||||||||||||||||||||
| 114 | |||||||||||||||||||||||||||||
| 115 | # Report additional violations of Policies that match m/variables/xms | ||||||||||||||||||||||||||||
| 116 | perlcritic --include variables YourModule.pm | ||||||||||||||||||||||||||||
| 117 | |||||||||||||||||||||||||||||
| 118 | # Use defaults from somewhere other than ~/.perlcriticrc | ||||||||||||||||||||||||||||
| 119 | perlcritic --profile project/specific/perlcriticrc YourModule.pm | ||||||||||||||||||||||||||||
| 120 | |||||||||||||||||||||||||||||
| 121 | |||||||||||||||||||||||||||||
| 122 | =head1 ARGUMENTS | ||||||||||||||||||||||||||||
| 123 | |||||||||||||||||||||||||||||
| 124 | The arguments are paths to the files you wish to analyze. You may specify | ||||||||||||||||||||||||||||
| 125 | multiple files. If an argument is a directory, C<perlcritic> will analyze all | ||||||||||||||||||||||||||||
| 126 | Perl files below the directory. If no arguments are specified, then input is | ||||||||||||||||||||||||||||
| 127 | read from STDIN. | ||||||||||||||||||||||||||||
| 128 | |||||||||||||||||||||||||||||
| 129 | |||||||||||||||||||||||||||||
| 130 | =head1 OPTIONS | ||||||||||||||||||||||||||||
| 131 | |||||||||||||||||||||||||||||
| 132 | Option names can be abbreviated to uniqueness and can be stated with singe or | ||||||||||||||||||||||||||||
| 133 | double dashes, and option values can be separated from the option name by a | ||||||||||||||||||||||||||||
| 134 | space or '=' (as with L<Getopt::Long>). Option names are also case-sensitive. | ||||||||||||||||||||||||||||
| 135 | |||||||||||||||||||||||||||||
| 136 | =over | ||||||||||||||||||||||||||||
| 137 | |||||||||||||||||||||||||||||
| 138 | =item C<--profile FILE> or C<-p FILE> | ||||||||||||||||||||||||||||
| 139 | |||||||||||||||||||||||||||||
| 140 | Directs C<perlcritic> to use a profile named by FILE rather than looking for | ||||||||||||||||||||||||||||
| 141 | the default F<.perlcriticrc> file in the current directory or your home | ||||||||||||||||||||||||||||
| 142 | directory. See L<Perl::Critic/"CONFIGURATION"> for more information. | ||||||||||||||||||||||||||||
| 143 | |||||||||||||||||||||||||||||
| 144 | =item C<--noprofile> | ||||||||||||||||||||||||||||
| 145 | |||||||||||||||||||||||||||||
| 146 | Directs C<perlcritic> not to load any configuration file, thus reverting to | ||||||||||||||||||||||||||||
| 147 | the default configuration for all Policies. | ||||||||||||||||||||||||||||
| 148 | |||||||||||||||||||||||||||||
| 149 | =item C<--severity N> | ||||||||||||||||||||||||||||
| 150 | |||||||||||||||||||||||||||||
| 151 | Directs C<perlcritic> to only apply Policies with a severity greater than | ||||||||||||||||||||||||||||
| 152 | C<N>. Severity values are integers ranging from 1 (least severe) to 5 (most | ||||||||||||||||||||||||||||
| 153 | severe). The default is 5. For a given C<--profile>, decreasing the | ||||||||||||||||||||||||||||
| 154 | C<--severity> will usually produce more violations. You can set the default | ||||||||||||||||||||||||||||
| 155 | value for this option in your F<.perlcriticrc> file. You can also redefine | ||||||||||||||||||||||||||||
| 156 | the C<severity> for any Policy in your F<.perlcriticrc> file. See | ||||||||||||||||||||||||||||
| 157 | L<"CONFIGURATION"> for more information. | ||||||||||||||||||||||||||||
| 158 | |||||||||||||||||||||||||||||
| 159 | =item C<-5 | -4 | -3 | -2 | -1> | ||||||||||||||||||||||||||||
| 160 | |||||||||||||||||||||||||||||
| 161 | These are numeric shortcuts for setting the C<--severity> option. For | ||||||||||||||||||||||||||||
| 162 | example, C<"-4"> is equivalent to C<"--severity 4">. If multiple shortcuts | ||||||||||||||||||||||||||||
| 163 | are specified, then the most restrictive one wins. If an explicit | ||||||||||||||||||||||||||||
| 164 | C<--severity> option is also given, then all shortcut options are silently | ||||||||||||||||||||||||||||
| 165 | ignored. NOTE: Be careful not to put one of the number severity shortcut | ||||||||||||||||||||||||||||
| 166 | options immediately after the C<--top> flag or C<perlcritic> will interpret it | ||||||||||||||||||||||||||||
| 167 | as the number of violations to report. | ||||||||||||||||||||||||||||
| 168 | |||||||||||||||||||||||||||||
| 169 | =item C<--severity NAME> | ||||||||||||||||||||||||||||
| 170 | |||||||||||||||||||||||||||||
| 171 | If it is difficult for you to remember whether severity "5" is the most or | ||||||||||||||||||||||||||||
| 172 | least restrictive level, then you can use one of these named values: | ||||||||||||||||||||||||||||
| 173 | |||||||||||||||||||||||||||||
| 174 | SEVERITY NAME ...is equivalent to... SEVERITY NUMBER | ||||||||||||||||||||||||||||
| 175 | -------------------------------------------------------- | ||||||||||||||||||||||||||||
| 176 | --severity gentle --severity 5 | ||||||||||||||||||||||||||||
| 177 | --severity stern --severity 4 | ||||||||||||||||||||||||||||
| 178 | --severity harsh --severity 3 | ||||||||||||||||||||||||||||
| 179 | --severity cruel --severity 2 | ||||||||||||||||||||||||||||
| 180 | --severity brutal --severity 1 | ||||||||||||||||||||||||||||
| 181 | |||||||||||||||||||||||||||||
| 182 | =item C<--gentle | --stern | --harsh | --cruel | --brutal> | ||||||||||||||||||||||||||||
| 183 | |||||||||||||||||||||||||||||
| 184 | These are named shortcuts for setting the C<--severity> option. For example, | ||||||||||||||||||||||||||||
| 185 | C<"--cruel"> is equivalent to C<"--severity 2">. If multiple shortcuts are | ||||||||||||||||||||||||||||
| 186 | specified, then the most restrictive one wins. If an explicit C<--severity> | ||||||||||||||||||||||||||||
| 187 | option is also given, then all shortcut options are silently ignored. | ||||||||||||||||||||||||||||
| 188 | |||||||||||||||||||||||||||||
| 189 | =item C<--theme RULE> | ||||||||||||||||||||||||||||
| 190 | |||||||||||||||||||||||||||||
| 191 | Directs C<perlcritic> to apply only Policies with themes that satisfy the | ||||||||||||||||||||||||||||
| 192 | C<RULE>. Themes are arbitrary names for groups of related policies. You can | ||||||||||||||||||||||||||||
| 193 | combine theme names with boolean operators to create an arbitrarily complex | ||||||||||||||||||||||||||||
| 194 | C<RULE>. For example, the following would apply only Policies that have a | ||||||||||||||||||||||||||||
| 195 | 'bugs' AND 'pbp' theme: | ||||||||||||||||||||||||||||
| 196 | |||||||||||||||||||||||||||||
| 197 | $> perlcritic --theme='bugs && pbp' MyModule.pm | ||||||||||||||||||||||||||||
| 198 | |||||||||||||||||||||||||||||
| 199 | Unless the C<--severity> option is explicitly given, setting C<--theme> | ||||||||||||||||||||||||||||
| 200 | silently causes the C<--severity> to be set to 1. You can set the default | ||||||||||||||||||||||||||||
| 201 | value for this option in your F<.perlcriticrc> file. See | ||||||||||||||||||||||||||||
| 202 | L<Perl::Critic/"POLICY THEMES"> for more information about themes. | ||||||||||||||||||||||||||||
| 203 | |||||||||||||||||||||||||||||
| 204 | =item C<--include PATTERN> | ||||||||||||||||||||||||||||
| 205 | |||||||||||||||||||||||||||||
| 206 | Directs C<perlcritic> to apply additional Policies that match the regex | ||||||||||||||||||||||||||||
| 207 | C</PATTERN/imx>. Use this option to temporarily override your profile and/or | ||||||||||||||||||||||||||||
| 208 | the severity settings at the command-line. For example: | ||||||||||||||||||||||||||||
| 209 | |||||||||||||||||||||||||||||
| 210 | perlcritic --include=layout my_file.pl | ||||||||||||||||||||||||||||
| 211 | |||||||||||||||||||||||||||||
| 212 | This would cause C<perlcritic> to apply all the C<CodeLayout::*> policies even | ||||||||||||||||||||||||||||
| 213 | if they have a severity level that is less than the default level of 5, or | ||||||||||||||||||||||||||||
| 214 | have been disabled in your F<.perlcriticrc> file. You can specify multiple | ||||||||||||||||||||||||||||
| 215 | C<--include> options and you can use it in conjunction with the C<--exclude> | ||||||||||||||||||||||||||||
| 216 | option. Note that C<--exclude> takes precedence over C<--include> when a | ||||||||||||||||||||||||||||
| 217 | Policy matches both patterns. You can set the default value for this option | ||||||||||||||||||||||||||||
| 218 | in your F<.perlcriticrc> file. | ||||||||||||||||||||||||||||
| 219 | |||||||||||||||||||||||||||||
| 220 | =item C<--exclude PATTERN> | ||||||||||||||||||||||||||||
| 221 | |||||||||||||||||||||||||||||
| 222 | Directs C<perlcritic> to not apply any Policy that matches the regex | ||||||||||||||||||||||||||||
| 223 | C</PATTERN/imx>. Use this option to temporarily override your profile and/or | ||||||||||||||||||||||||||||
| 224 | the severity settings at the command-line. For example: | ||||||||||||||||||||||||||||
| 225 | |||||||||||||||||||||||||||||
| 226 | perlcritic --exclude=strict my_file.pl | ||||||||||||||||||||||||||||
| 227 | |||||||||||||||||||||||||||||
| 228 | This would cause C<perlcritic> to not apply the C<RequireUseStrict> and | ||||||||||||||||||||||||||||
| 229 | C<ProhibitNoStrict> Policies even though they have the highest severity level. | ||||||||||||||||||||||||||||
| 230 | You can specify multiple C<--exclude> options and you can use it in | ||||||||||||||||||||||||||||
| 231 | conjunction with the C<--include> option. Note that C<--exclude> takes | ||||||||||||||||||||||||||||
| 232 | precedence over C<--include> when a Policy matches both patterns. You can set | ||||||||||||||||||||||||||||
| 233 | the default value for this option in your F<.perlcriticrc> file. | ||||||||||||||||||||||||||||
| 234 | |||||||||||||||||||||||||||||
| 235 | =item C<--single-policy PATTERN> or C<-s PATTERN> | ||||||||||||||||||||||||||||
| 236 | |||||||||||||||||||||||||||||
| 237 | Directs C<perlcritic> to apply just one Policy module matching the regex | ||||||||||||||||||||||||||||
| 238 | C</PATTERN/ixms>, and exclude all other Policies. This option has precedence | ||||||||||||||||||||||||||||
| 239 | over the C<--severity>, C<--theme>, C<--include>, C<--exclude>, and C<--only> | ||||||||||||||||||||||||||||
| 240 | options. For example: | ||||||||||||||||||||||||||||
| 241 | |||||||||||||||||||||||||||||
| 242 | perlcritic --single-policy=nowarnings my_file.pl | ||||||||||||||||||||||||||||
| 243 | |||||||||||||||||||||||||||||
| 244 | This would cause C<perlcritic> to apply just the C<ProhibitNoWarnings> Policy, | ||||||||||||||||||||||||||||
| 245 | regardless of the severity level setting. No other Policies would be applied. | ||||||||||||||||||||||||||||
| 246 | |||||||||||||||||||||||||||||
| 247 | This is equivalent to what one might intend by... | ||||||||||||||||||||||||||||
| 248 | |||||||||||||||||||||||||||||
| 249 | perlcritic --exclude=. --include=nowarnings my_file.pl | ||||||||||||||||||||||||||||
| 250 | |||||||||||||||||||||||||||||
| 251 | ... but this won't work because the C<--exclude> option overrides the | ||||||||||||||||||||||||||||
| 252 | C<--include> option. | ||||||||||||||||||||||||||||
| 253 | |||||||||||||||||||||||||||||
| 254 | The equivalent of this option can be accomplished by creating a custom profile | ||||||||||||||||||||||||||||
| 255 | containing only the desired policy and then running... | ||||||||||||||||||||||||||||
| 256 | |||||||||||||||||||||||||||||
| 257 | perlcritic --profile=customprofile --only my_file.pl | ||||||||||||||||||||||||||||
| 258 | |||||||||||||||||||||||||||||
| 259 | =item C<--top [ N ]> | ||||||||||||||||||||||||||||
| 260 | |||||||||||||||||||||||||||||
| 261 | Directs C<perlcritic> to report only the top C<N> Policy violations in each | ||||||||||||||||||||||||||||
| 262 | file, ranked by their severity. If C<N> is not specified, it defaults to 20. | ||||||||||||||||||||||||||||
| 263 | If the C<--severity> option (or one of the shortcuts) is not explicitly given, | ||||||||||||||||||||||||||||
| 264 | the C<--top> option implies that the minimum severity level is "1" (i.e. | ||||||||||||||||||||||||||||
| 265 | "brutal"). Users can redefine the severity for any Policy in their | ||||||||||||||||||||||||||||
| 266 | F<.perlcriticrc> file. See L<"CONFIGURATION"> for more information. You can | ||||||||||||||||||||||||||||
| 267 | set the default value for this option in your F<.perlcriticrc> file. NOTE: Be | ||||||||||||||||||||||||||||
| 268 | careful not to put one of the severity shortcut options immediately after the | ||||||||||||||||||||||||||||
| 269 | C<--top> flag or C<perlcritic> will interpret it as the number of violations | ||||||||||||||||||||||||||||
| 270 | to report. | ||||||||||||||||||||||||||||
| 271 | |||||||||||||||||||||||||||||
| 272 | =item C<--force> | ||||||||||||||||||||||||||||
| 273 | |||||||||||||||||||||||||||||
| 274 | Directs C<perlcritic> to ignore the magical C<"## no critic"> annotations in | ||||||||||||||||||||||||||||
| 275 | the source code. See L<"BENDING THE RULES"> for more information. You can set | ||||||||||||||||||||||||||||
| 276 | the default value for this option in your F<.perlcriticrc> file. | ||||||||||||||||||||||||||||
| 277 | |||||||||||||||||||||||||||||
| 278 | =item C<--statistics> | ||||||||||||||||||||||||||||
| 279 | |||||||||||||||||||||||||||||
| 280 | Causes several statistics about the code being scanned and the violations | ||||||||||||||||||||||||||||
| 281 | found to be reported after any other output. | ||||||||||||||||||||||||||||
| 282 | |||||||||||||||||||||||||||||
| 283 | =item C<--statistics-only> | ||||||||||||||||||||||||||||
| 284 | |||||||||||||||||||||||||||||
| 285 | Like the C<--statistics> option, but suppresses normal output and only shows | ||||||||||||||||||||||||||||
| 286 | the statistics. | ||||||||||||||||||||||||||||
| 287 | |||||||||||||||||||||||||||||
| 288 | =item C<--verbose N | FORMAT> | ||||||||||||||||||||||||||||
| 289 | |||||||||||||||||||||||||||||
| 290 | Sets the verbosity level or format for reporting violations. If given a | ||||||||||||||||||||||||||||
| 291 | number (C<N>), C<perlcritic> reports violations using one of the predefined | ||||||||||||||||||||||||||||
| 292 | formats described below. If given a string (C<FORMAT>), it is interpreted to | ||||||||||||||||||||||||||||
| 293 | be an actual format specification. If the C<--verbose> option is not | ||||||||||||||||||||||||||||
| 294 | specified, it defaults to either 4 or 5, depending on whether multiple files | ||||||||||||||||||||||||||||
| 295 | were given as arguments to C<perlcritic>. You can set the default value for | ||||||||||||||||||||||||||||
| 296 | this option in your F<.perlcriticrc> file. | ||||||||||||||||||||||||||||
| 297 | |||||||||||||||||||||||||||||
| 298 | Verbosity Format Specification | ||||||||||||||||||||||||||||
| 299 | ----------- ------------------------------------------------------- | ||||||||||||||||||||||||||||
| 300 | 1 "%f:%l:%c:%m\n", | ||||||||||||||||||||||||||||
| 301 | 2 "%f: (%l:%c) %m\n", | ||||||||||||||||||||||||||||
| 302 | 3 "%m at %f line %l\n", | ||||||||||||||||||||||||||||
| 303 | 4 "%m at line %l, column %c. %e. (Severity: %s)\n", | ||||||||||||||||||||||||||||
| 304 | 5 "%f: %m at line %l, column %c. %e. (Severity: %s)\n", | ||||||||||||||||||||||||||||
| 305 | 6 "%m at line %l, near '%r'. (Severity: %s)\n", | ||||||||||||||||||||||||||||
| 306 | 7 "%f: %m at line %l near '%r'. (Severity: %s)\n", | ||||||||||||||||||||||||||||
| 307 | 8 "[%p] %m at line %l, column %c. (Severity: %s)\n", | ||||||||||||||||||||||||||||
| 308 | 9 "[%p] %m at line %l, near '%r'. (Severity: %s)\n", | ||||||||||||||||||||||||||||
| 309 | 10 "%m at line %l, column %c.\n %p (Severity: %s)\n%d\n", | ||||||||||||||||||||||||||||
| 310 | 11 "%m at line %l, near '%r'.\n %p (Severity: %s)\n%d\n" | ||||||||||||||||||||||||||||
| 311 | |||||||||||||||||||||||||||||
| 312 | Formats are a combination of literal and escape characters similar to the way | ||||||||||||||||||||||||||||
| 313 | C<sprintf> works. See L<String::Format|String::Format> for a full explanation | ||||||||||||||||||||||||||||
| 314 | of the formatting capabilities. Valid escape characters are: | ||||||||||||||||||||||||||||
| 315 | |||||||||||||||||||||||||||||
| 316 | Escape Meaning | ||||||||||||||||||||||||||||
| 317 | ------- ------------------------------------------------------------ | ||||||||||||||||||||||||||||
| 318 | %c Column number where the violation occurred | ||||||||||||||||||||||||||||
| 319 | %d Full diagnostic discussion of the violation | ||||||||||||||||||||||||||||
| 320 | %e Explanation of violation or page numbers in PBP | ||||||||||||||||||||||||||||
| 321 | %F Just the name of the file where the violation occurred. | ||||||||||||||||||||||||||||
| 322 | %f Path to the file where the violation occurred. | ||||||||||||||||||||||||||||
| 323 | %l Line number where the violation occurred | ||||||||||||||||||||||||||||
| 324 | %m Brief description of the violation | ||||||||||||||||||||||||||||
| 325 | %P Full name of the Policy module that created the violation | ||||||||||||||||||||||||||||
| 326 | %p Name of the Policy without the Perl::Critic::Policy:: prefix | ||||||||||||||||||||||||||||
| 327 | %r The string of source code that caused the violation | ||||||||||||||||||||||||||||
| 328 | %C The class of the PPI::Element that caused the violation | ||||||||||||||||||||||||||||
| 329 | %s The severity level of the violation | ||||||||||||||||||||||||||||
| 330 | |||||||||||||||||||||||||||||
| 331 | The purpose of these formats is to provide some compatibility with text | ||||||||||||||||||||||||||||
| 332 | editors that have an interface for parsing certain kinds of input. See | ||||||||||||||||||||||||||||
| 333 | L<"EDITOR INTEGRATION"> for more information about that. | ||||||||||||||||||||||||||||
| 334 | |||||||||||||||||||||||||||||
| 335 | =item C<--list> | ||||||||||||||||||||||||||||
| 336 | |||||||||||||||||||||||||||||
| 337 | Displays a condensed listing of all the L<Perl::Critic::Policy> modules that | ||||||||||||||||||||||||||||
| 338 | are found on this machine. This option lists I<all> Policies, regardless of | ||||||||||||||||||||||||||||
| 339 | your F<.perlcriticrc> or command line options. For each Policy, the name, | ||||||||||||||||||||||||||||
| 340 | default severity and default themes are shown. | ||||||||||||||||||||||||||||
| 341 | |||||||||||||||||||||||||||||
| 342 | =item C<--list-enabled> | ||||||||||||||||||||||||||||
| 343 | |||||||||||||||||||||||||||||
| 344 | Displays a condensed listing of all the L<Perl::Critic::Policy> modules that | ||||||||||||||||||||||||||||
| 345 | I<would> be enforced, if you were actually going to critique a file with this | ||||||||||||||||||||||||||||
| 346 | command. This is useful when you've constructed a complicated command or | ||||||||||||||||||||||||||||
| 347 | modified your F<.perlcriticrc> file and you want to see exactly which Policies | ||||||||||||||||||||||||||||
| 348 | are going to be enforced (or not enforced, as the case may be). For each | ||||||||||||||||||||||||||||
| 349 | Policy, the name, default severity and default themes are shown. | ||||||||||||||||||||||||||||
| 350 | |||||||||||||||||||||||||||||
| 351 | =item C<--list-themes> | ||||||||||||||||||||||||||||
| 352 | |||||||||||||||||||||||||||||
| 353 | Displays a list of all the themes of the L<Perl::Critic::Policy> modules that | ||||||||||||||||||||||||||||
| 354 | are found on this machine. | ||||||||||||||||||||||||||||
| 355 | |||||||||||||||||||||||||||||
| 356 | =item C<--profile-proto> | ||||||||||||||||||||||||||||
| 357 | |||||||||||||||||||||||||||||
| 358 | Displays an expanded listing of all the L<Perl::Critic::Policy> modules that | ||||||||||||||||||||||||||||
| 359 | are found on this machine. For each Policy, the name, default severity and | ||||||||||||||||||||||||||||
| 360 | default themes are shown, as well as the name of any additional parameters | ||||||||||||||||||||||||||||
| 361 | that the Policy supports. The format is suitable as a prototype for your | ||||||||||||||||||||||||||||
| 362 | F<.perlcriticrc> file. | ||||||||||||||||||||||||||||
| 363 | |||||||||||||||||||||||||||||
| 364 | =item C<--only> | ||||||||||||||||||||||||||||
| 365 | |||||||||||||||||||||||||||||
| 366 | Directs perlcritic to apply only Policies that are explicitly mentioned in | ||||||||||||||||||||||||||||
| 367 | your F<.perlcriticrc> file. This is useful if you want to use just a small | ||||||||||||||||||||||||||||
| 368 | subset of Policies without having to disable all the others. You can set the | ||||||||||||||||||||||||||||
| 369 | default value for this option in your F<.perlcriticrc> file. | ||||||||||||||||||||||||||||
| 370 | |||||||||||||||||||||||||||||
| 371 | =item C<--profile-strictness {warn|fatal|quiet}> | ||||||||||||||||||||||||||||
| 372 | |||||||||||||||||||||||||||||
| 373 | Directs perlcritic how to treat certain recoverable problems found in a | ||||||||||||||||||||||||||||
| 374 | F<.perlcriticrc> or file specified via the C<--profile> option. Valid values | ||||||||||||||||||||||||||||
| 375 | are C<warn> (the default), C<fatal>, and C<quiet>. For example, perlcritic | ||||||||||||||||||||||||||||
| 376 | normally only warns about profiles referring to non-existent Policies, but | ||||||||||||||||||||||||||||
| 377 | this option can make this situation fatal. You can set the default value for | ||||||||||||||||||||||||||||
| 378 | this option in your F<.perlcriticrc> file. | ||||||||||||||||||||||||||||
| 379 | |||||||||||||||||||||||||||||
| 380 | =item C<--count> | ||||||||||||||||||||||||||||
| 381 | |||||||||||||||||||||||||||||
| 382 | =item C<-C> | ||||||||||||||||||||||||||||
| 383 | |||||||||||||||||||||||||||||
| 384 | Display only the number of violations for each file. Use this feature to get | ||||||||||||||||||||||||||||
| 385 | a quick handle on where a large pile of code might need the most attention. | ||||||||||||||||||||||||||||
| 386 | |||||||||||||||||||||||||||||
| 387 | =item C<--color> | ||||||||||||||||||||||||||||
| 388 | |||||||||||||||||||||||||||||
| 389 | =item C<--colour> | ||||||||||||||||||||||||||||
| 390 | |||||||||||||||||||||||||||||
| 391 | This option is on when outputting to a tty. When set, Severity 5 and 4 are | ||||||||||||||||||||||||||||
| 392 | colored red and yellow, respectively. Colorization only happens if | ||||||||||||||||||||||||||||
| 393 | L<Term::ANSIColor> is installed. For Windows environments, | ||||||||||||||||||||||||||||
| 394 | L<Win32::Console::ANSI> must also be installed. | ||||||||||||||||||||||||||||
| 395 | Negate this switch to disable color. You can set the default value for this | ||||||||||||||||||||||||||||
| 396 | option in your F<.perlcriticrc> file. | ||||||||||||||||||||||||||||
| 397 | |||||||||||||||||||||||||||||
| 398 | =item C<--pager PAGER_COMMAND_STRING> | ||||||||||||||||||||||||||||
| 399 | |||||||||||||||||||||||||||||
| 400 | If set, perlcritic will pipe it's output to the given PAGER_COMMAND_STRING. | ||||||||||||||||||||||||||||
| 401 | You can set the default value for this option in your F<.perlcriticrc> file. | ||||||||||||||||||||||||||||
| 402 | |||||||||||||||||||||||||||||
| 403 | Setting a pager turns off color by default. You will have to turn color on | ||||||||||||||||||||||||||||
| 404 | explicitly. If you want color, you'll probably also want to tell your pager | ||||||||||||||||||||||||||||
| 405 | to display raw characters. For C<less> and C<more>, use the -R switch. | ||||||||||||||||||||||||||||
| 406 | |||||||||||||||||||||||||||||
| 407 | =item C<--color-severity-highest COLOR_SPECIFICATION> | ||||||||||||||||||||||||||||
| 408 | |||||||||||||||||||||||||||||
| 409 | Specifies the color to be used for highest severity violations, as a | ||||||||||||||||||||||||||||
| 410 | Term::ANSIColor color specification. Can also be specified as C<--colour- | ||||||||||||||||||||||||||||
| 411 | severity-highest>, C<--color-severity-5>, or C<--colour-severity-5>. | ||||||||||||||||||||||||||||
| 412 | |||||||||||||||||||||||||||||
| 413 | =item C<--color-severity-high COLOR_SPECIFICATION> | ||||||||||||||||||||||||||||
| 414 | |||||||||||||||||||||||||||||
| 415 | Specifies the color to be used for high severity violations, as a | ||||||||||||||||||||||||||||
| 416 | Term::ANSIColor color specification. Can also be specified as C<--colour- | ||||||||||||||||||||||||||||
| 417 | severity-high>, C<--color-severity-4>, or C<--colour-severity-4>. | ||||||||||||||||||||||||||||
| 418 | |||||||||||||||||||||||||||||
| 419 | =item C<--color-severity-medium COLOR_SPECIFICATION> | ||||||||||||||||||||||||||||
| 420 | |||||||||||||||||||||||||||||
| 421 | Specifies the color to be used for medium severity violations, as a | ||||||||||||||||||||||||||||
| 422 | Term::ANSIColor color specification. Can also be specified as C<--colour- | ||||||||||||||||||||||||||||
| 423 | severity-medium>, C<--color-severity-3>, or C<--colour-severity-3>. | ||||||||||||||||||||||||||||
| 424 | |||||||||||||||||||||||||||||
| 425 | =item C<--color-severity-low COLOR_SPECIFICATION> | ||||||||||||||||||||||||||||
| 426 | |||||||||||||||||||||||||||||
| 427 | Specifies the color to be used for low severity violations, as a | ||||||||||||||||||||||||||||
| 428 | Term::ANSIColor color specification. Can also be specified as C<--colour- | ||||||||||||||||||||||||||||
| 429 | severity-low>, C<--color-severity-2>, or C<--colour-severity-2>. | ||||||||||||||||||||||||||||
| 430 | |||||||||||||||||||||||||||||
| 431 | =item C<--color-severity-lowest COLOR_SPECIFICATION> | ||||||||||||||||||||||||||||
| 432 | |||||||||||||||||||||||||||||
| 433 | Specifies the color to be used for lowest severity violations, as a | ||||||||||||||||||||||||||||
| 434 | Term::ANSIColor color specification. Can also be specified as C<--colour- | ||||||||||||||||||||||||||||
| 435 | severity-lowest>, C<--color-severity-1>, or C<--colour-severity-1>. | ||||||||||||||||||||||||||||
| 436 | |||||||||||||||||||||||||||||
| 437 | =item C<--files-with-violations> | ||||||||||||||||||||||||||||
| 438 | |||||||||||||||||||||||||||||
| 439 | Display only the names of files with violations. Use this feature with | ||||||||||||||||||||||||||||
| 440 | --single-policy to find files that contain violations of a given policy. Can | ||||||||||||||||||||||||||||
| 441 | also be specified as C<--l>. | ||||||||||||||||||||||||||||
| 442 | |||||||||||||||||||||||||||||
| 443 | =item C<--files-without-violations> | ||||||||||||||||||||||||||||
| 444 | |||||||||||||||||||||||||||||
| 445 | Display only the names of files without violations. Use this feature with | ||||||||||||||||||||||||||||
| 446 | --single-policy to find files that do not contain violations of a given | ||||||||||||||||||||||||||||
| 447 | policy. Can also be specified as C<--L>. | ||||||||||||||||||||||||||||
| 448 | |||||||||||||||||||||||||||||
| 449 | =item C<--program-extensions file_name_extension> | ||||||||||||||||||||||||||||
| 450 | |||||||||||||||||||||||||||||
| 451 | Tell C<perlcritic> to treat files whose names end in the given file name | ||||||||||||||||||||||||||||
| 452 | extension as programs, not as modules. If a leading '.' is desired it must be | ||||||||||||||||||||||||||||
| 453 | explicitly specified, e.g. | ||||||||||||||||||||||||||||
| 454 | |||||||||||||||||||||||||||||
| 455 | --program-extensions .pl | ||||||||||||||||||||||||||||
| 456 | |||||||||||||||||||||||||||||
| 457 | The matching is case-sensitive, and the option may be specified as many times | ||||||||||||||||||||||||||||
| 458 | as desired, e.g. | ||||||||||||||||||||||||||||
| 459 | |||||||||||||||||||||||||||||
| 460 | --program-extensions .pl --program-extensions .cgi | ||||||||||||||||||||||||||||
| 461 | |||||||||||||||||||||||||||||
| 462 | The above can also be done by quoting the file name extensions: | ||||||||||||||||||||||||||||
| 463 | |||||||||||||||||||||||||||||
| 464 | --program-extensions '.pl .cgi' | ||||||||||||||||||||||||||||
| 465 | |||||||||||||||||||||||||||||
| 466 | Files whose name ends in '.PL' will always be considered programs. | ||||||||||||||||||||||||||||
| 467 | |||||||||||||||||||||||||||||
| 468 | =item C<--doc PATTERN> | ||||||||||||||||||||||||||||
| 469 | |||||||||||||||||||||||||||||
| 470 | Displays the perldoc for all L<Perl::Critic::Policy> modules that match | ||||||||||||||||||||||||||||
| 471 | C<m/PATTERN/ixms>. Since Policy modules tend to have rather long names, this | ||||||||||||||||||||||||||||
| 472 | just provides a more convenient way to say something like: C<"perldoc | ||||||||||||||||||||||||||||
| 473 | Perl::Critic::Policy::ValuesAndExpressions::RequireUpperCaseH | ||||||||||||||||||||||||||||
| 474 | eredocTerminator"> at the command prompt. | ||||||||||||||||||||||||||||
| 475 | |||||||||||||||||||||||||||||
| 476 | =item C<--allow-unsafe> | ||||||||||||||||||||||||||||
| 477 | |||||||||||||||||||||||||||||
| 478 | This option directs C<perlcritic> to allow the use of Policies that have been | ||||||||||||||||||||||||||||
| 479 | marked as "unsafe". Unsafe Policies may result in risky operations by | ||||||||||||||||||||||||||||
| 480 | compiling and executing the code they analyze. All the Policies that ship in | ||||||||||||||||||||||||||||
| 481 | the core L<Perl::Critic> distribution are safe. However, third- party | ||||||||||||||||||||||||||||
| 482 | Policies, such as those in the L<Perl::Critic::Dynamic> distribution are not | ||||||||||||||||||||||||||||
| 483 | safe. Note that "safety" is honorary -- if a Policy author marks a Policy as | ||||||||||||||||||||||||||||
| 484 | safe, it is not a guarantee that it won't do nasty things. B<If you don't | ||||||||||||||||||||||||||||
| 485 | trust your Policies and the code you are analyzing, then do not use this | ||||||||||||||||||||||||||||
| 486 | switch>. | ||||||||||||||||||||||||||||
| 487 | |||||||||||||||||||||||||||||
| 488 | =item C<--quiet> | ||||||||||||||||||||||||||||
| 489 | |||||||||||||||||||||||||||||
| 490 | Suppress the "source OK" message when no violations are found. | ||||||||||||||||||||||||||||
| 491 | |||||||||||||||||||||||||||||
| 492 | =item C<--help> | ||||||||||||||||||||||||||||
| 493 | |||||||||||||||||||||||||||||
| 494 | =item C<-?> | ||||||||||||||||||||||||||||
| 495 | |||||||||||||||||||||||||||||
| 496 | =item C<-H> | ||||||||||||||||||||||||||||
| 497 | |||||||||||||||||||||||||||||
| 498 | Displays a brief summary of options and exits. | ||||||||||||||||||||||||||||
| 499 | |||||||||||||||||||||||||||||
| 500 | =item C<--options> | ||||||||||||||||||||||||||||
| 501 | |||||||||||||||||||||||||||||
| 502 | Displays the descriptions of the options and exits. While this output is | ||||||||||||||||||||||||||||
| 503 | long, it it nowhere near the length of the output of C<--man>. | ||||||||||||||||||||||||||||
| 504 | |||||||||||||||||||||||||||||
| 505 | =item C<--man> | ||||||||||||||||||||||||||||
| 506 | |||||||||||||||||||||||||||||
| 507 | Displays the complete C<perlcritic> manual and exits. | ||||||||||||||||||||||||||||
| 508 | |||||||||||||||||||||||||||||
| 509 | =item C<--version> | ||||||||||||||||||||||||||||
| 510 | |||||||||||||||||||||||||||||
| 511 | Displays the version number of C<perlcritic> and exits. | ||||||||||||||||||||||||||||
| 512 | |||||||||||||||||||||||||||||
| 513 | =back | ||||||||||||||||||||||||||||
| 514 | |||||||||||||||||||||||||||||
| 515 | =head1 CONFIGURATION | ||||||||||||||||||||||||||||
| 516 | |||||||||||||||||||||||||||||
| 517 | Most of the settings for Perl::Critic and each of the Policy modules can be | ||||||||||||||||||||||||||||
| 518 | controlled by a configuration file. The default configuration file is called | ||||||||||||||||||||||||||||
| 519 | F<.perlcriticrc>. C<perlcritic> will look for this file in the current | ||||||||||||||||||||||||||||
| 520 | directory first, and then in your home directory. Alternatively, you can set | ||||||||||||||||||||||||||||
| 521 | the C<PERLCRITIC> environment variable to explicitly point to a different file | ||||||||||||||||||||||||||||
| 522 | in another location. If none of these files exist, and the C<--profile> | ||||||||||||||||||||||||||||
| 523 | option is not given on the command-line, then all Policies will be loaded with | ||||||||||||||||||||||||||||
| 524 | their default configuration. | ||||||||||||||||||||||||||||
| 525 | |||||||||||||||||||||||||||||
| 526 | The format of the configuration file is a series of INI-style blocks that | ||||||||||||||||||||||||||||
| 527 | contain key-value pairs separated by "=". Comments should start with "#" and | ||||||||||||||||||||||||||||
| 528 | can be placed on a separate line or after the name-value pairs if you desire. | ||||||||||||||||||||||||||||
| 529 | |||||||||||||||||||||||||||||
| 530 | Default settings for perlcritic itself can be set B<before the first named | ||||||||||||||||||||||||||||
| 531 | block.> For example, putting any or all of these at the top of your | ||||||||||||||||||||||||||||
| 532 | F<.perlcriticrc> file will set the default value for the corresponding | ||||||||||||||||||||||||||||
| 533 | command-line argument. | ||||||||||||||||||||||||||||
| 534 | |||||||||||||||||||||||||||||
| 535 | severity = 3 #Integer or named level | ||||||||||||||||||||||||||||
| 536 | only = 1 #Zero or One | ||||||||||||||||||||||||||||
| 537 | force = 0 #Zero or One | ||||||||||||||||||||||||||||
| 538 | verbose = 4 #Integer or format spec | ||||||||||||||||||||||||||||
| 539 | top = 50 #A positive integer | ||||||||||||||||||||||||||||
| 540 | theme = (pbp + security) * bugs #A theme expression | ||||||||||||||||||||||||||||
| 541 | include = NamingConventions ClassHierarchies #Space-delimited list | ||||||||||||||||||||||||||||
| 542 | exclude = Variables Modules::RequirePackage #Space-delimited list | ||||||||||||||||||||||||||||
| 543 | |||||||||||||||||||||||||||||
| 544 | The remainder of the configuration file is a series of blocks like this: | ||||||||||||||||||||||||||||
| 545 | |||||||||||||||||||||||||||||
| 546 | [Perl::Critic::Policy::Category::PolicyName] | ||||||||||||||||||||||||||||
| 547 | severity = 1 | ||||||||||||||||||||||||||||
| 548 | set_themes = foo bar | ||||||||||||||||||||||||||||
| 549 | add_themes = baz | ||||||||||||||||||||||||||||
| 550 | arg1 = value1 | ||||||||||||||||||||||||||||
| 551 | arg2 = value2 | ||||||||||||||||||||||||||||
| 552 | |||||||||||||||||||||||||||||
| 553 | C<Perl::Critic::Policy::Category::PolicyName> is the full name of a module | ||||||||||||||||||||||||||||
| 554 | that implements the policy. The Policy modules distributed with Perl::Critic | ||||||||||||||||||||||||||||
| 555 | have been grouped into categories according to the table of contents in Damian | ||||||||||||||||||||||||||||
| 556 | Conway's book B<Perl Best Practices>. For brevity, you can omit the | ||||||||||||||||||||||||||||
| 557 | C<'Perl::Critic::Policy'> part of the module name. | ||||||||||||||||||||||||||||
| 558 | |||||||||||||||||||||||||||||
| 559 | C<severity> is the level of importance you wish to assign to the Policy. All | ||||||||||||||||||||||||||||
| 560 | Policy modules are defined with a default severity value ranging from 1 (least | ||||||||||||||||||||||||||||
| 561 | severe) to 5 (most severe). However, you may disagree with the default | ||||||||||||||||||||||||||||
| 562 | severity and choose to give it a higher or lower severity, based on your own | ||||||||||||||||||||||||||||
| 563 | coding philosophy. You can set the C<severity> to an integer from 1 to 5, or | ||||||||||||||||||||||||||||
| 564 | use one of the equivalent names: | ||||||||||||||||||||||||||||
| 565 | |||||||||||||||||||||||||||||
| 566 | SEVERITY NAME ...is equivalent to... SEVERITY NUMBER | ||||||||||||||||||||||||||||
| 567 | ---------------------------------------------------- | ||||||||||||||||||||||||||||
| 568 | gentle 5 | ||||||||||||||||||||||||||||
| 569 | stern 4 | ||||||||||||||||||||||||||||
| 570 | harsh 3 | ||||||||||||||||||||||||||||
| 571 | cruel 2 | ||||||||||||||||||||||||||||
| 572 | brutal 1 | ||||||||||||||||||||||||||||
| 573 | |||||||||||||||||||||||||||||
| 574 | C<set_themes> sets the theme for the Policy and overrides its default theme. | ||||||||||||||||||||||||||||
| 575 | The argument is a string of one or more whitespace-delimited alphanumeric | ||||||||||||||||||||||||||||
| 576 | words. Themes are case-insensitive. See L<"POLICY THEMES"> for more | ||||||||||||||||||||||||||||
| 577 | information. | ||||||||||||||||||||||||||||
| 578 | |||||||||||||||||||||||||||||
| 579 | C<add_themes> appends to the default themes for this Policy. The argument is | ||||||||||||||||||||||||||||
| 580 | a string of one or more whitespace-delimited words. Themes are case- | ||||||||||||||||||||||||||||
| 581 | insensitive. See L<"POLICY THEMES"> for more information. | ||||||||||||||||||||||||||||
| 582 | |||||||||||||||||||||||||||||
| 583 | The remaining key-value pairs are configuration parameters that will be passed | ||||||||||||||||||||||||||||
| 584 | into the constructor of that Policy. The constructors for most Policy modules | ||||||||||||||||||||||||||||
| 585 | do not support arguments, and those that do should have reasonable defaults. | ||||||||||||||||||||||||||||
| 586 | See the documentation on the appropriate Policy module for more details. | ||||||||||||||||||||||||||||
| 587 | |||||||||||||||||||||||||||||
| 588 | Instead of redefining the severity for a given Policy, you can completely | ||||||||||||||||||||||||||||
| 589 | disable a Policy by prepending a '-' to the name of the module in your | ||||||||||||||||||||||||||||
| 590 | configuration file. In this manner, the Policy will never be loaded, | ||||||||||||||||||||||||||||
| 591 | regardless of the C<--severity> given on the command line. | ||||||||||||||||||||||||||||
| 592 | |||||||||||||||||||||||||||||
| 593 | A simple configuration might look like this: | ||||||||||||||||||||||||||||
| 594 | |||||||||||||||||||||||||||||
| 595 | #-------------------------------------------------------------- | ||||||||||||||||||||||||||||
| 596 | # I think these are really important, so always load them | ||||||||||||||||||||||||||||
| 597 | |||||||||||||||||||||||||||||
| 598 | [TestingAndDebugging::RequireUseStrict] | ||||||||||||||||||||||||||||
| 599 | severity = 5 | ||||||||||||||||||||||||||||
| 600 | |||||||||||||||||||||||||||||
| 601 | [TestingAndDebugging::RequireUseWarnings] | ||||||||||||||||||||||||||||
| 602 | severity = 5 | ||||||||||||||||||||||||||||
| 603 | |||||||||||||||||||||||||||||
| 604 | #-------------------------------------------------------------- | ||||||||||||||||||||||||||||
| 605 | # I think these are less important, so only load when asked | ||||||||||||||||||||||||||||
| 606 | |||||||||||||||||||||||||||||
| 607 | [Variables::ProhibitPackageVars] | ||||||||||||||||||||||||||||
| 608 | severity = 2 | ||||||||||||||||||||||||||||
| 609 | |||||||||||||||||||||||||||||
| 610 | [ControlStructures::ProhibitPostfixControls] | ||||||||||||||||||||||||||||
| 611 | allow = if unless # My custom configuration | ||||||||||||||||||||||||||||
| 612 | severity = cruel # Same as "severity = 2" | ||||||||||||||||||||||||||||
| 613 | |||||||||||||||||||||||||||||
| 614 | #-------------------------------------------------------------- | ||||||||||||||||||||||||||||
| 615 | # Give these policies a custom theme. I can activate just | ||||||||||||||||||||||||||||
| 616 | # these policies by saying "perlcritic --theme 'larry || curly'" | ||||||||||||||||||||||||||||
| 617 | |||||||||||||||||||||||||||||
| 618 | [Modules::RequireFilenameMatchesPackage] | ||||||||||||||||||||||||||||
| 619 | add_themes = larry | ||||||||||||||||||||||||||||
| 620 | |||||||||||||||||||||||||||||
| 621 | [TestingAndDebugging::RequireTestLabels] | ||||||||||||||||||||||||||||
| 622 | add_themes = curly moe | ||||||||||||||||||||||||||||
| 623 | |||||||||||||||||||||||||||||
| 624 | #-------------------------------------------------------------- | ||||||||||||||||||||||||||||
| 625 | # I do not agree with these at all, so never load them | ||||||||||||||||||||||||||||
| 626 | |||||||||||||||||||||||||||||
| 627 | [-NamingConventions::Capitalization] | ||||||||||||||||||||||||||||
| 628 | [-ValuesAndExpressions::ProhibitMagicNumbers] | ||||||||||||||||||||||||||||
| 629 | |||||||||||||||||||||||||||||
| 630 | #-------------------------------------------------------------- | ||||||||||||||||||||||||||||
| 631 | # For all other Policies, I accept the default severity, | ||||||||||||||||||||||||||||
| 632 | # so no additional configuration is required for them. | ||||||||||||||||||||||||||||
| 633 | |||||||||||||||||||||||||||||
| 634 | Note that all policies included with the Perl::Critic distribution that have | ||||||||||||||||||||||||||||
| 635 | integer parameters accept underscores ("_") in their values, as with Perl | ||||||||||||||||||||||||||||
| 636 | numeric literals. For example, | ||||||||||||||||||||||||||||
| 637 | |||||||||||||||||||||||||||||
| 638 | [ValuesAndExpressions::RequireNumberSeparators] | ||||||||||||||||||||||||||||
| 639 | min_value = 1_000 | ||||||||||||||||||||||||||||
| 640 | |||||||||||||||||||||||||||||
| 641 | For additional configuration examples, see the F<perlcriticrc> file that is | ||||||||||||||||||||||||||||
| 642 | included in this F<examples> directory of this distribution. | ||||||||||||||||||||||||||||
| 643 | |||||||||||||||||||||||||||||
| 644 | Damian Conway's own Perl::Critic configuration is also included in this | ||||||||||||||||||||||||||||
| 645 | distribution as F<examples/perlcriticrc-conway>. | ||||||||||||||||||||||||||||
| 646 | |||||||||||||||||||||||||||||
| 647 | |||||||||||||||||||||||||||||
| 648 | =head1 THE POLICIES | ||||||||||||||||||||||||||||
| 649 | |||||||||||||||||||||||||||||
| 650 | A large number of Policy modules are distributed with Perl::Critic. They are | ||||||||||||||||||||||||||||
| 651 | described briefly in the companion document L<Perl::Critic::PolicySummary> and | ||||||||||||||||||||||||||||
| 652 | in more detail in the individual modules themselves. Say C<"perlcritic --doc | ||||||||||||||||||||||||||||
| 653 | PATTERN"> to see the perldoc for all Policy modules that match the regex | ||||||||||||||||||||||||||||
| 654 | C<m/PATTERN/ixms> | ||||||||||||||||||||||||||||
| 655 | |||||||||||||||||||||||||||||
| 656 | There are a number of distributions of additional policies on CPAN. If | ||||||||||||||||||||||||||||
| 657 | L<Perl::Critic> doesn't contain a policy that you want, some one may have | ||||||||||||||||||||||||||||
| 658 | already written it. See L<Perl::Critic/"SEE ALSO"> for a list of some of | ||||||||||||||||||||||||||||
| 659 | these distributions. | ||||||||||||||||||||||||||||
| 660 | |||||||||||||||||||||||||||||
| 661 | |||||||||||||||||||||||||||||
| 662 | =head1 POLICY THEMES | ||||||||||||||||||||||||||||
| 663 | |||||||||||||||||||||||||||||
| 664 | Each Policy is defined with one or more "themes". Themes can be used to | ||||||||||||||||||||||||||||
| 665 | create arbitrary groups of Policies. They are intended to provide an | ||||||||||||||||||||||||||||
| 666 | alternative mechanism for selecting your preferred set of Policies. For | ||||||||||||||||||||||||||||
| 667 | example, you may wish disable a certain set of Policies when analyzing test | ||||||||||||||||||||||||||||
| 668 | programs. Conversely, you may wish to enable only a specific subset of | ||||||||||||||||||||||||||||
| 669 | Policies when analyzing modules. | ||||||||||||||||||||||||||||
| 670 | |||||||||||||||||||||||||||||
| 671 | The Policies that ship with Perl::Critic are have been divided into the | ||||||||||||||||||||||||||||
| 672 | following themes. This is just our attempt to provide some basic logical | ||||||||||||||||||||||||||||
| 673 | groupings. You are free to invent new themes that suit your needs. | ||||||||||||||||||||||||||||
| 674 | |||||||||||||||||||||||||||||
| 675 | THEME DESCRIPTION | ||||||||||||||||||||||||||||
| 676 | ------------------------------------------------------------------------ | ||||||||||||||||||||||||||||
| 677 | core All policies that ship with Perl::Critic | ||||||||||||||||||||||||||||
| 678 | pbp Policies that come directly from "Perl Best Practices" | ||||||||||||||||||||||||||||
| 679 | bugs Policies that that prevent or reveal bugs | ||||||||||||||||||||||||||||
| 680 | certrec Policies that CERT recommends | ||||||||||||||||||||||||||||
| 681 | certrule Policies that CERT considers rules | ||||||||||||||||||||||||||||
| 682 | maintenance Policies that affect the long-term health of the code | ||||||||||||||||||||||||||||
| 683 | cosmetic Policies that only have a superficial effect | ||||||||||||||||||||||||||||
| 684 | complexity Policies that specifically relate to code complexity | ||||||||||||||||||||||||||||
| 685 | security Policies that relate to security issues | ||||||||||||||||||||||||||||
| 686 | tests Policies that are specific to test programs | ||||||||||||||||||||||||||||
| 687 | |||||||||||||||||||||||||||||
| 688 | Say C<"perlcritic --list"> to get a listing of all available policies and the | ||||||||||||||||||||||||||||
| 689 | themes that are associated with each one. You can also change the theme for | ||||||||||||||||||||||||||||
| 690 | any Policy in your F<.perlcriticrc> file. See the L<"CONFIGURATION"> section | ||||||||||||||||||||||||||||
| 691 | for more information about that. | ||||||||||||||||||||||||||||
| 692 | |||||||||||||||||||||||||||||
| 693 | Using the C<--theme> command-line option, you can create an arbitrarily | ||||||||||||||||||||||||||||
| 694 | complex rule that determines which Policies to apply. Precedence is the same | ||||||||||||||||||||||||||||
| 695 | as regular Perl code, and you can use parentheses to enforce precedence as | ||||||||||||||||||||||||||||
| 696 | well. Supported operators are: | ||||||||||||||||||||||||||||
| 697 | |||||||||||||||||||||||||||||
| 698 | Operator Altertative Example | ||||||||||||||||||||||||||||
| 699 | ----------------------------------------------------------------- | ||||||||||||||||||||||||||||
| 700 | && and 'pbp && core' | ||||||||||||||||||||||||||||
| 701 | || or 'pbp || (bugs && security)' | ||||||||||||||||||||||||||||
| 702 | ! not 'pbp && ! (portability || complexity)' | ||||||||||||||||||||||||||||
| 703 | |||||||||||||||||||||||||||||
| 704 | Theme names are case-insensitive. If the C<--theme> is set to an empty | ||||||||||||||||||||||||||||
| 705 | string, then it evaluates as true all Policies. | ||||||||||||||||||||||||||||
| 706 | |||||||||||||||||||||||||||||
| 707 | |||||||||||||||||||||||||||||
| 708 | =head1 BENDING THE RULES | ||||||||||||||||||||||||||||
| 709 | |||||||||||||||||||||||||||||
| 710 | Perl::Critic takes a hard-line approach to your code: either you comply or you | ||||||||||||||||||||||||||||
| 711 | don't. In the real world, it is not always practical (or even possible) to | ||||||||||||||||||||||||||||
| 712 | fully comply with coding standards. In such cases, it is wise to show that | ||||||||||||||||||||||||||||
| 713 | you are knowingly violating the standards and that you have a Damn Good Reason | ||||||||||||||||||||||||||||
| 714 | (DGR) for doing so. | ||||||||||||||||||||||||||||
| 715 | |||||||||||||||||||||||||||||
| 716 | To help with those situations, you can direct Perl::Critic to ignore certain | ||||||||||||||||||||||||||||
| 717 | lines or blocks of code by using annotations: | ||||||||||||||||||||||||||||
| 718 | |||||||||||||||||||||||||||||
| 719 | require 'LegacyLibaray1.pl'; ## no critic | ||||||||||||||||||||||||||||
| 720 | require 'LegacyLibrary2.pl'; ## no critic | ||||||||||||||||||||||||||||
| 721 | |||||||||||||||||||||||||||||
| 722 | for my $element (@list) { | ||||||||||||||||||||||||||||
| 723 | |||||||||||||||||||||||||||||
| 724 | ## no critic | ||||||||||||||||||||||||||||
| 725 | |||||||||||||||||||||||||||||
| 726 | $foo = ""; #Violates 'ProhibitEmptyQuotes' | ||||||||||||||||||||||||||||
| 727 | $barf = bar() if $foo; #Violates 'ProhibitPostfixControls' | ||||||||||||||||||||||||||||
| 728 | #Some more evil code... | ||||||||||||||||||||||||||||
| 729 | |||||||||||||||||||||||||||||
| 730 | ## use critic | ||||||||||||||||||||||||||||
| 731 | |||||||||||||||||||||||||||||
| 732 | #Some good code... | ||||||||||||||||||||||||||||
| 733 | do_something($_); | ||||||||||||||||||||||||||||
| 734 | } | ||||||||||||||||||||||||||||
| 735 | |||||||||||||||||||||||||||||
| 736 | The C<"## no critic"> annotations direct Perl::Critic to ignore the remaining | ||||||||||||||||||||||||||||
| 737 | lines of code until a C<"## use critic"> annotation is found. If the C<"## no | ||||||||||||||||||||||||||||
| 738 | critic"> annotation is on the same line as a code statement, then only that | ||||||||||||||||||||||||||||
| 739 | line of code is overlooked. To direct perlcritic to ignore the C<"## no | ||||||||||||||||||||||||||||
| 740 | critic"> annotations, use the C<--force> option. | ||||||||||||||||||||||||||||
| 741 | |||||||||||||||||||||||||||||
| 742 | A bare C<"## no critic"> annotation disables all the active Policies. If you | ||||||||||||||||||||||||||||
| 743 | wish to disable only specific Policies, add a list of Policy names as | ||||||||||||||||||||||||||||
| 744 | arguments just as you would for the C<"no strict"> or C<"no warnings"> pragma. | ||||||||||||||||||||||||||||
| 745 | For example, this would disable the C<ProhibitEmptyQuotes> and | ||||||||||||||||||||||||||||
| 746 | C<ProhibitPostfixControls> policies until the end of the block or until the | ||||||||||||||||||||||||||||
| 747 | next C<"## use critic"> annotation (whichever comes first): | ||||||||||||||||||||||||||||
| 748 | |||||||||||||||||||||||||||||
| 749 | ## no critic (EmptyQuotes, PostfixControls); | ||||||||||||||||||||||||||||
| 750 | |||||||||||||||||||||||||||||
| 751 | # Now exempt from ValuesAndExpressions::ProhibitEmptyQuotes | ||||||||||||||||||||||||||||
| 752 | $foo = ""; | ||||||||||||||||||||||||||||
| 753 | |||||||||||||||||||||||||||||
| 754 | # Now exempt ControlStructures::ProhibitPostfixControls | ||||||||||||||||||||||||||||
| 755 | $barf = bar() if $foo; | ||||||||||||||||||||||||||||
| 756 | |||||||||||||||||||||||||||||
| 757 | # Still subject to ValuesAndExpression::RequireNumberSeparators | ||||||||||||||||||||||||||||
| 758 | $long_int = 10000000000; | ||||||||||||||||||||||||||||
| 759 | |||||||||||||||||||||||||||||
| 760 | Since the Policy names are matched against the C<"## no critic"> arguments as | ||||||||||||||||||||||||||||
| 761 | regular expressions, you can abbreviate the Policy names or disable an entire | ||||||||||||||||||||||||||||
| 762 | family of Policies in one shot like this: | ||||||||||||||||||||||||||||
| 763 | |||||||||||||||||||||||||||||
| 764 | ## no critic (NamingConventions) | ||||||||||||||||||||||||||||
| 765 | |||||||||||||||||||||||||||||
| 766 | # Now exempt from NamingConventions::Capitalization | ||||||||||||||||||||||||||||
| 767 | my $camelHumpVar = 'foo'; | ||||||||||||||||||||||||||||
| 768 | |||||||||||||||||||||||||||||
| 769 | # Now exempt from NamingConventions::Capitalization | ||||||||||||||||||||||||||||
| 770 | sub camelHumpSub {} | ||||||||||||||||||||||||||||
| 771 | |||||||||||||||||||||||||||||
| 772 | The argument list must be enclosed in parentheses and must contain one or more | ||||||||||||||||||||||||||||
| 773 | comma-separated barewords (i.e. don't use quotes). The C<"## no critic"> | ||||||||||||||||||||||||||||
| 774 | annotations can be nested, and Policies named by an inner annotation will be | ||||||||||||||||||||||||||||
| 775 | disabled along with those already disabled an outer annotation. | ||||||||||||||||||||||||||||
| 776 | |||||||||||||||||||||||||||||
| 777 | Some Policies like C<Subroutines::ProhibitExcessComplexity> apply to an entire | ||||||||||||||||||||||||||||
| 778 | block of code. In those cases, C<"## no critic"> must appear on the line | ||||||||||||||||||||||||||||
| 779 | where the violation is reported. For example: | ||||||||||||||||||||||||||||
| 780 | |||||||||||||||||||||||||||||
| 781 | sub complicated_function { ## no critic (ProhibitExcessComplexity) | ||||||||||||||||||||||||||||
| 782 | # Your code here... | ||||||||||||||||||||||||||||
| 783 | } | ||||||||||||||||||||||||||||
| 784 | |||||||||||||||||||||||||||||
| 785 | Some Policies like C<Documentation::RequirePodSections> apply to the entire | ||||||||||||||||||||||||||||
| 786 | document, in which case violations are reported at line 1. But if the file | ||||||||||||||||||||||||||||
| 787 | requires a shebang line, it is impossible to put C<"## no critic"> on the | ||||||||||||||||||||||||||||
| 788 | first line of the file. This is a known limitation and it will be addressed | ||||||||||||||||||||||||||||
| 789 | in a future release. As a workaround, you can disable the affected policies | ||||||||||||||||||||||||||||
| 790 | at the command-line or in your F<.perlcriticrc> file. But beware that this | ||||||||||||||||||||||||||||
| 791 | will affect the analysis of B<all> files. | ||||||||||||||||||||||||||||
| 792 | |||||||||||||||||||||||||||||
| 793 | Use this feature wisely. C<"## no critic"> should be used in the smallest | ||||||||||||||||||||||||||||
| 794 | possible scope, or only on individual lines of code. And you should always be | ||||||||||||||||||||||||||||
| 795 | as specific as possible about which policies you want to disable (i.e. never | ||||||||||||||||||||||||||||
| 796 | use a bare C<"## no critic">). If Perl::Critic complains about your code, try | ||||||||||||||||||||||||||||
| 797 | and find a compliant solution before resorting to this feature. | ||||||||||||||||||||||||||||
| 798 | |||||||||||||||||||||||||||||
| 799 | |||||||||||||||||||||||||||||
| 800 | =head1 EDITOR INTEGRATION | ||||||||||||||||||||||||||||
| 801 | |||||||||||||||||||||||||||||
| 802 | For ease-of-use, C<perlcritic> can be integrated with your favorite text | ||||||||||||||||||||||||||||
| 803 | editor. The output-formatting capabilities of C<perlcritic> are specifically | ||||||||||||||||||||||||||||
| 804 | intended for use with the "grep" or "compile" modes available in editors like | ||||||||||||||||||||||||||||
| 805 | C<emacs> and C<vim>. In these modes, you can run an arbitrary command and the | ||||||||||||||||||||||||||||
| 806 | editor will parse the output into an interactive buffer that you can click on | ||||||||||||||||||||||||||||
| 807 | and jump to the relevant line of code. | ||||||||||||||||||||||||||||
| 808 | |||||||||||||||||||||||||||||
| 809 | The Perl::Critic team thanks everyone who has helped integrate Perl-Critic | ||||||||||||||||||||||||||||
| 810 | with their favorite editor. Your contributions in particular have made Perl- | ||||||||||||||||||||||||||||
| 811 | Critic a convenient and user-friendly tool for Perl developers of all stripes. | ||||||||||||||||||||||||||||
| 812 | We sincerely appreciate your hard work. | ||||||||||||||||||||||||||||
| 813 | |||||||||||||||||||||||||||||
| 814 | |||||||||||||||||||||||||||||
| 815 | =head2 EMACS | ||||||||||||||||||||||||||||
| 816 | |||||||||||||||||||||||||||||
| 817 | Joshua ben Jore has authored a minor-mode for emacs that allows you to run | ||||||||||||||||||||||||||||
| 818 | perlcritic on the current region or buffer. You can run it on demand, or | ||||||||||||||||||||||||||||
| 819 | configure it to run automatically when you save the buffer. The output appears | ||||||||||||||||||||||||||||
| 820 | in a hot-linked compiler buffer. The code and installation instructions can | ||||||||||||||||||||||||||||
| 821 | be found in the F<extras> directory inside this distribution. | ||||||||||||||||||||||||||||
| 822 | |||||||||||||||||||||||||||||
| 823 | |||||||||||||||||||||||||||||
| 824 | =head2 VIM | ||||||||||||||||||||||||||||
| 825 | |||||||||||||||||||||||||||||
| 826 | Scott Peshak has published F<perlchecker.vim>, which is available at | ||||||||||||||||||||||||||||
| 827 | L<http://www.vim.org/scripts/script.php?script_id=1731>. | ||||||||||||||||||||||||||||
| 828 | |||||||||||||||||||||||||||||
| 829 | |||||||||||||||||||||||||||||
| 830 | =head2 gVIM | ||||||||||||||||||||||||||||
| 831 | |||||||||||||||||||||||||||||
| 832 | Fritz Mehner recently added support for C<perlcritic> to his fantastic gVIM | ||||||||||||||||||||||||||||
| 833 | plugin. In addition to providing a very Perlish IDE, Fritz's plugin enables | ||||||||||||||||||||||||||||
| 834 | one-click access to C<perlcritic> and many other very useful utilities. And | ||||||||||||||||||||||||||||
| 835 | all is seamlessly integrated into the editor. See | ||||||||||||||||||||||||||||
| 836 | L<http://lug.fh-swf.de/vim/vim-perl/screenshots-en.html> for complete details. | ||||||||||||||||||||||||||||
| 837 | |||||||||||||||||||||||||||||
| 838 | |||||||||||||||||||||||||||||
| 839 | =head2 EPIC | ||||||||||||||||||||||||||||
| 840 | |||||||||||||||||||||||||||||
| 841 | EPIC is an open source Perl IDE based on the Eclipse platform. Features | ||||||||||||||||||||||||||||
| 842 | include syntax highlighting, on-the-fly syntax check, content assist, code | ||||||||||||||||||||||||||||
| 843 | completion, perldoc support, source formatting with L<Perl::Tidy|Perl::Tidy>, | ||||||||||||||||||||||||||||
| 844 | code templates, a regular expression editing tool, and integration with the | ||||||||||||||||||||||||||||
| 845 | Perl debugger. Recent versions of EPIC also have built-in support for | ||||||||||||||||||||||||||||
| 846 | Perl::Critic. At least one Perl::Critic contributor swears by EPIC. Go to | ||||||||||||||||||||||||||||
| 847 | L<http://e-p-i-c.sourceforge.net> for more information about EPIC. | ||||||||||||||||||||||||||||
| 848 | |||||||||||||||||||||||||||||
| 849 | =head2 BBEdit | ||||||||||||||||||||||||||||
| 850 | |||||||||||||||||||||||||||||
| 851 | Josh Clark has produced an excellent Perl-Critic plugin for BBEdit. See | ||||||||||||||||||||||||||||
| 852 | L<http://globalmoxie.com/projects/bbedit-perl-critic/index.shtml> for | ||||||||||||||||||||||||||||
| 853 | download, installation, and usage instructions. Apple users rejoice! | ||||||||||||||||||||||||||||
| 854 | |||||||||||||||||||||||||||||
| 855 | |||||||||||||||||||||||||||||
| 856 | =head2 Komodo | ||||||||||||||||||||||||||||
| 857 | |||||||||||||||||||||||||||||
| 858 | Komodo is a proprietary IDE for Perl and several other dynamic languages. | ||||||||||||||||||||||||||||
| 859 | Starting in version 5.1.1, Komodo has built-in support for Perl-Critic, if you | ||||||||||||||||||||||||||||
| 860 | have the L<Perl::Critic> and L<criticism> modules installed. Free trial | ||||||||||||||||||||||||||||
| 861 | copies of Komodo can be obtained from the ActiveState website at | ||||||||||||||||||||||||||||
| 862 | L<http://www.activestate.com>. | ||||||||||||||||||||||||||||
| 863 | |||||||||||||||||||||||||||||
| 864 | |||||||||||||||||||||||||||||
| 865 | =head2 ActivePerl | ||||||||||||||||||||||||||||
| 866 | |||||||||||||||||||||||||||||
| 867 | ActivePerl includes a very slick graphical interface for configuring and | ||||||||||||||||||||||||||||
| 868 | running Perl-Critic called C<perlcritic-gui>. A free community edition of | ||||||||||||||||||||||||||||
| 869 | ActivePerl can be obtained from the ActiveState website at | ||||||||||||||||||||||||||||
| 870 | L<http://www.activestate.com>. | ||||||||||||||||||||||||||||
| 871 | |||||||||||||||||||||||||||||
| 872 | |||||||||||||||||||||||||||||
| 873 | =head2 Visual Studio Code | ||||||||||||||||||||||||||||
| 874 | |||||||||||||||||||||||||||||
| 875 | Visual Studio Code is a lightweight but powerful source code editor which | ||||||||||||||||||||||||||||
| 876 | runs on your desktop and is available for Windows, macOS and Linux. | ||||||||||||||||||||||||||||
| 877 | |||||||||||||||||||||||||||||
| 878 | The perlcritic extension can be found here: | ||||||||||||||||||||||||||||
| 879 | L<https://marketplace.visualstudio.com/items?itemName=sfodje.perlcritic> | ||||||||||||||||||||||||||||
| 880 | |||||||||||||||||||||||||||||
| 881 | The steps to install the perlcritic extension: | ||||||||||||||||||||||||||||
| 882 | |||||||||||||||||||||||||||||
| 883 | =over | ||||||||||||||||||||||||||||
| 884 | |||||||||||||||||||||||||||||
| 885 | =item 1. Menu: View->Command Palette | ||||||||||||||||||||||||||||
| 886 | |||||||||||||||||||||||||||||
| 887 | =item 2. Type in "Extensions" | ||||||||||||||||||||||||||||
| 888 | |||||||||||||||||||||||||||||
| 889 | =item 3. Select "Extensions: Install Extension" | ||||||||||||||||||||||||||||
| 890 | |||||||||||||||||||||||||||||
| 891 | =item 4. In the search box type "perlcritic" and the extensions pane will open. | ||||||||||||||||||||||||||||
| 892 | |||||||||||||||||||||||||||||
| 893 | =item 5. perlcritic should be the first entry | ||||||||||||||||||||||||||||
| 894 | |||||||||||||||||||||||||||||
| 895 | =item 6. Select the "install" button | ||||||||||||||||||||||||||||
| 896 | |||||||||||||||||||||||||||||
| 897 | =item 7. Once installed go to Preferences->Settings | ||||||||||||||||||||||||||||
| 898 | |||||||||||||||||||||||||||||
| 899 | =item 8. Type in "perlcritic" in the search box | ||||||||||||||||||||||||||||
| 900 | |||||||||||||||||||||||||||||
| 901 | =item 9. The settings options for perlcritic will show and you configure the extension here. | ||||||||||||||||||||||||||||
| 902 | |||||||||||||||||||||||||||||
| 903 | =item 9a. If you want perlcritic to run automatically when the file is saved, select "only critique on save". | ||||||||||||||||||||||||||||
| 904 | |||||||||||||||||||||||||||||
| 905 | =back | ||||||||||||||||||||||||||||
| 906 | |||||||||||||||||||||||||||||
| 907 | Open a Perl file. Save it and perlcritic should fire. There is a triangle | ||||||||||||||||||||||||||||
| 908 | with an exclamation point on the status bar. Click it and it will open the | ||||||||||||||||||||||||||||
| 909 | issues that perlcritic has found. | ||||||||||||||||||||||||||||
| 910 | |||||||||||||||||||||||||||||
| 911 | |||||||||||||||||||||||||||||
| 912 | =head1 EXIT STATUS | ||||||||||||||||||||||||||||
| 913 | |||||||||||||||||||||||||||||
| 914 | If C<perlcritic> has any errors itself, exits with status == 1. If there are | ||||||||||||||||||||||||||||
| 915 | no errors, but C<perlcritic> finds Policy violations in your source code, | ||||||||||||||||||||||||||||
| 916 | exits with status == 2. If there were no errors and no violations were found, | ||||||||||||||||||||||||||||
| 917 | exits with status == 0. | ||||||||||||||||||||||||||||
| 918 | |||||||||||||||||||||||||||||
| 919 | |||||||||||||||||||||||||||||
| 920 | =head1 THE L<Perl::Critic> PHILOSOPHY | ||||||||||||||||||||||||||||
| 921 | |||||||||||||||||||||||||||||
| 922 | =over | ||||||||||||||||||||||||||||
| 923 | |||||||||||||||||||||||||||||
| 924 | Coding standards are deeply personal and highly subjective. The goal of | ||||||||||||||||||||||||||||
| 925 | Perl::Critic is to help you write code that conforms with a set of best | ||||||||||||||||||||||||||||
| 926 | practices. Our primary goal is not to dictate what those practices are, but | ||||||||||||||||||||||||||||
| 927 | rather, to implement the practices discovered by others. Ultimately, you make | ||||||||||||||||||||||||||||
| 928 | the rules -- Perl::Critic is merely a tool for encouraging consistency. If | ||||||||||||||||||||||||||||
| 929 | there is a policy that you think is important or that we have overlooked, we | ||||||||||||||||||||||||||||
| 930 | would be very grateful for contributions, or you can simply load your own | ||||||||||||||||||||||||||||
| 931 | private set of policies into Perl::Critic. | ||||||||||||||||||||||||||||
| 932 | |||||||||||||||||||||||||||||
| 933 | =back | ||||||||||||||||||||||||||||
| 934 | |||||||||||||||||||||||||||||
| 935 | |||||||||||||||||||||||||||||
| 936 | =head1 EXTENDING THE CRITIC | ||||||||||||||||||||||||||||
| 937 | |||||||||||||||||||||||||||||
| 938 | The modular design of Perl::Critic is intended to facilitate the addition of | ||||||||||||||||||||||||||||
| 939 | new Policies. You'll need to have some understanding of L<PPI>, but most | ||||||||||||||||||||||||||||
| 940 | Policy modules are pretty straightforward and only require about 20 lines of | ||||||||||||||||||||||||||||
| 941 | code. Please see the L<Perl::Critic::DEVELOPER> file included in this | ||||||||||||||||||||||||||||
| 942 | distribution for a step-by-step demonstration of how to create new Policy | ||||||||||||||||||||||||||||
| 943 | modules. | ||||||||||||||||||||||||||||
| 944 | |||||||||||||||||||||||||||||
| 945 | If you develop any new Policy modules, feel free to send them to C<< | ||||||||||||||||||||||||||||
| 946 | <team@perlcritic.com> >> and I'll be happy to consider putting them into the | ||||||||||||||||||||||||||||
| 947 | Perl::Critic distribution. Or if you would like to work on the Perl::Critic | ||||||||||||||||||||||||||||
| 948 | project directly, you can fork our repository at | ||||||||||||||||||||||||||||
| 949 | L<https://github.com/Perl-Critic/Perl-Critic.git>. | ||||||||||||||||||||||||||||
| 950 | |||||||||||||||||||||||||||||
| 951 | The Perl::Critic team is also available for hire. If your organization has | ||||||||||||||||||||||||||||
| 952 | its own coding standards, we can create custom Policies to enforce your local | ||||||||||||||||||||||||||||
| 953 | guidelines. Or if your code base is prone to a particular defect pattern, we | ||||||||||||||||||||||||||||
| 954 | can design Policies that will help you catch those costly defects B<before> | ||||||||||||||||||||||||||||
| 955 | they go into production. To discuss your needs with the Perl::Critic team, | ||||||||||||||||||||||||||||
| 956 | just contact C<< <team@perlcritic.com> >>. | ||||||||||||||||||||||||||||
| 957 | |||||||||||||||||||||||||||||
| 958 | |||||||||||||||||||||||||||||
| 959 | =head1 CONTACTING THE DEVELOPMENT TEAM | ||||||||||||||||||||||||||||
| 960 | |||||||||||||||||||||||||||||
| 961 | You are encouraged to subscribe to the mailing list at | ||||||||||||||||||||||||||||
| 962 | L<https://groups.google.com/d/forum/perl-critic>. | ||||||||||||||||||||||||||||
| 963 | At least one member of the development team is usually hanging around in | ||||||||||||||||||||||||||||
| 964 | L<irc://irc.perl.org/#perlcritic> and you can follow Perl::Critic on Twitter, | ||||||||||||||||||||||||||||
| 965 | at L<https://twitter.com/perlcritic>. | ||||||||||||||||||||||||||||
| 966 | |||||||||||||||||||||||||||||
| 967 | |||||||||||||||||||||||||||||
| 968 | =head1 SEE ALSO | ||||||||||||||||||||||||||||
| 969 | |||||||||||||||||||||||||||||
| 970 | There are a number of distributions of additional Policies available. A few | ||||||||||||||||||||||||||||
| 971 | are listed here: | ||||||||||||||||||||||||||||
| 972 | |||||||||||||||||||||||||||||
| 973 | L<Perl::Critic::More> | ||||||||||||||||||||||||||||
| 974 | |||||||||||||||||||||||||||||
| 975 | L<Perl::Critic::Bangs> | ||||||||||||||||||||||||||||
| 976 | |||||||||||||||||||||||||||||
| 977 | L<Perl::Critic::Lax> | ||||||||||||||||||||||||||||
| 978 | |||||||||||||||||||||||||||||
| 979 | L<Perl::Critic::StricterSubs> | ||||||||||||||||||||||||||||
| 980 | |||||||||||||||||||||||||||||
| 981 | L<Perl::Critic::Swift> | ||||||||||||||||||||||||||||
| 982 | |||||||||||||||||||||||||||||
| 983 | L<Perl::Critic::Tics> | ||||||||||||||||||||||||||||
| 984 | |||||||||||||||||||||||||||||
| 985 | These distributions enable you to use Perl::Critic in your unit tests: | ||||||||||||||||||||||||||||
| 986 | |||||||||||||||||||||||||||||
| 987 | L<Test::Perl::Critic> | ||||||||||||||||||||||||||||
| 988 | |||||||||||||||||||||||||||||
| 989 | L<Test::Perl::Critic::Progressive> | ||||||||||||||||||||||||||||
| 990 | |||||||||||||||||||||||||||||
| 991 | There is also a distribution that will install all the Perl::Critic related | ||||||||||||||||||||||||||||
| 992 | modules known to the development team: | ||||||||||||||||||||||||||||
| 993 | |||||||||||||||||||||||||||||
| 994 | L<Task::Perl::Critic> | ||||||||||||||||||||||||||||
| 995 | |||||||||||||||||||||||||||||
| 996 | |||||||||||||||||||||||||||||
| 997 | =head1 BUGS | ||||||||||||||||||||||||||||
| 998 | |||||||||||||||||||||||||||||
| 999 | Scrutinizing Perl code is hard for humans, let alone machines. If you find | ||||||||||||||||||||||||||||
| 1000 | any bugs, particularly false-positives or false-negatives from a | ||||||||||||||||||||||||||||
| 1001 | Perl::Critic::Policy, please submit them at | ||||||||||||||||||||||||||||
| 1002 | L<https://github.com/Perl-Critic/Perl-Critic/issues>. Thanks. | ||||||||||||||||||||||||||||
| 1003 | |||||||||||||||||||||||||||||
| 1004 | =head1 CREDITS | ||||||||||||||||||||||||||||
| 1005 | |||||||||||||||||||||||||||||
| 1006 | Adam Kennedy - For creating L<PPI>, the heart and soul of L<Perl::Critic>. | ||||||||||||||||||||||||||||
| 1007 | |||||||||||||||||||||||||||||
| 1008 | Damian Conway - For writing B<Perl Best Practices>, finally :) | ||||||||||||||||||||||||||||
| 1009 | |||||||||||||||||||||||||||||
| 1010 | Chris Dolan - For contributing the best features and Policy modules. | ||||||||||||||||||||||||||||
| 1011 | |||||||||||||||||||||||||||||
| 1012 | Andy Lester - Wise sage and master of all-things-testing. | ||||||||||||||||||||||||||||
| 1013 | |||||||||||||||||||||||||||||
| 1014 | Elliot Shank - The self-proclaimed quality freak. | ||||||||||||||||||||||||||||
| 1015 | |||||||||||||||||||||||||||||
| 1016 | Giuseppe Maxia - For all the great ideas and positive encouragement. | ||||||||||||||||||||||||||||
| 1017 | |||||||||||||||||||||||||||||
| 1018 | and Sharon, my wife - For putting up with my all-night code sessions. | ||||||||||||||||||||||||||||
| 1019 | |||||||||||||||||||||||||||||
| 1020 | Thanks also to the Perl Foundation for providing a grant to support Chris | ||||||||||||||||||||||||||||
| 1021 | Dolan's project to implement twenty PBP policies. | ||||||||||||||||||||||||||||
| 1022 | L<http://www.perlfoundation.org/april_1_2007_new_grant_awards> | ||||||||||||||||||||||||||||
| 1023 | |||||||||||||||||||||||||||||
| 1024 | |||||||||||||||||||||||||||||
| 1025 | =head1 AUTHOR | ||||||||||||||||||||||||||||
| 1026 | |||||||||||||||||||||||||||||
| 1027 | Jeffrey Ryan Thalhammer <jeff@imaginative-software.com> | ||||||||||||||||||||||||||||
| 1028 | |||||||||||||||||||||||||||||
| 1029 | |||||||||||||||||||||||||||||
| 1030 | =head1 COPYRIGHT | ||||||||||||||||||||||||||||
| 1031 | |||||||||||||||||||||||||||||
| 1032 | Copyright (c) 2005-2021 Imaginative Software Systems. All rights reserved. | ||||||||||||||||||||||||||||
| 1033 | |||||||||||||||||||||||||||||
| 1034 | This program is free software; you can redistribute it and/or modify | ||||||||||||||||||||||||||||
| 1035 | it under the same terms as Perl itself. The full text of this license | ||||||||||||||||||||||||||||
| 1036 | can be found in the LICENSE file included with this module. | ||||||||||||||||||||||||||||
| 1037 | |||||||||||||||||||||||||||||
| 1038 | =cut | ||||||||||||||||||||||||||||
| 1039 | |||||||||||||||||||||||||||||
| 1040 | ############################################################################## | ||||||||||||||||||||||||||||
| 1041 | # Local Variables: | ||||||||||||||||||||||||||||
| 1042 | # mode: cperl | ||||||||||||||||||||||||||||
| 1043 | # cperl-indent-level: 4 | ||||||||||||||||||||||||||||
| 1044 | # fill-column: 78 | ||||||||||||||||||||||||||||
| 1045 | # indent-tabs-mode: nil | ||||||||||||||||||||||||||||
| 1046 | # c-indentation-style: bsd | ||||||||||||||||||||||||||||
| 1047 | # End: | ||||||||||||||||||||||||||||
| 1048 | # ex: set ts=8 sts=4 sw=4 tw=78 ft=perl expandtab shiftround : | ||||||||||||||||||||||||||||