line |
stmt |
bran |
cond |
sub |
pod |
time |
code |
1
|
|
|
|
|
|
|
#!/usr/local/bin/perl |
2
|
|
|
|
|
|
|
|
3
|
|
|
|
|
|
|
eval 'exec /usr/local/bin/perl -S $0 ${1+"$@"}' |
4
|
|
|
|
|
|
|
if 0; # not running under some shell |
5
|
|
|
|
|
|
|
|
6
|
|
|
|
|
|
|
package main; |
7
|
|
|
|
|
|
|
|
8
|
1
|
|
|
1
|
|
376366
|
use 5.006001; |
|
1
|
|
|
|
|
5
|
|
9
|
1
|
|
|
1
|
|
6
|
use strict; |
|
1
|
|
|
|
|
3
|
|
|
1
|
|
|
|
|
35
|
|
10
|
1
|
|
|
1
|
|
5
|
use warnings; |
|
1
|
|
|
|
|
3
|
|
|
1
|
|
|
|
|
53
|
|
11
|
|
|
|
|
|
|
|
12
|
1
|
|
|
1
|
|
669
|
use Perl::ToPerl6::Command qw< run >; |
|
1
|
|
|
|
|
3
|
|
|
1
|
|
|
|
|
30
|
|
13
|
|
|
|
|
|
|
|
14
|
|
|
|
|
|
|
#----------------------------------------------------------------------------- |
15
|
|
|
|
|
|
|
|
16
|
|
|
|
|
|
|
our $VERSION = '0.031'; |
17
|
|
|
|
|
|
|
|
18
|
|
|
|
|
|
|
#----------------------------------------------------------------------------- |
19
|
|
|
|
|
|
|
# Begin program. Don't run when loaded as a library |
20
|
|
|
|
|
|
|
|
21
|
|
|
|
|
|
|
# This %ENV check is to allow perlmogrify to function when bundled under PAR, |
22
|
|
|
|
|
|
|
# which invokes this program not as the top stack frame. -- rjbs, 2008-08-11 |
23
|
|
|
|
|
|
|
exit run() if not caller or $ENV{PAR_0}; |
24
|
|
|
|
|
|
|
|
25
|
|
|
|
|
|
|
#----------------------------------------------------------------------------- |
26
|
|
|
|
|
|
|
1; |
27
|
|
|
|
|
|
|
|
28
|
|
|
|
|
|
|
__END__ |
29
|
|
|
|
|
|
|
|
30
|
|
|
|
|
|
|
#----------------------------------------------------------------------------- |
31
|
|
|
|
|
|
|
|
32
|
|
|
|
|
|
|
=pod |
33
|
|
|
|
|
|
|
|
34
|
|
|
|
|
|
|
=for stopwords DGR INI-style vim-fu minibuffer -noprofile API |
35
|
|
|
|
|
|
|
-profileproto -profile-proto ben Jore formatter Peshak pbp Komodo |
36
|
|
|
|
|
|
|
screenshots tty emacs gVIM plugin Perlish templating ActivePerl |
37
|
|
|
|
|
|
|
ActiveState Twitter |
38
|
|
|
|
|
|
|
|
39
|
|
|
|
|
|
|
=head1 NAME |
40
|
|
|
|
|
|
|
|
41
|
|
|
|
|
|
|
C<perlmogrify> - Command-line interface to transform Perl source. |
42
|
|
|
|
|
|
|
|
43
|
|
|
|
|
|
|
|
44
|
|
|
|
|
|
|
=head1 SYNOPSIS |
45
|
|
|
|
|
|
|
|
46
|
|
|
|
|
|
|
perlmogrify [-12345 | --brutal | --cruel | --harsh | --stern | --gentle] |
47
|
|
|
|
|
|
|
[--severity number | name] [{-p | --profile} file | --noprofile] |
48
|
|
|
|
|
|
|
[--top [ number ]] [--theme expression] [--include pattern] |
49
|
|
|
|
|
|
|
[--exclude pattern] [{-s | --single-transformer} pattern] |
50
|
|
|
|
|
|
|
[--only | --noonly] [--profile-strictness {warn|fatal|quiet}] |
51
|
|
|
|
|
|
|
[--force | --noforce] [--statistics] [--statistics-only] |
52
|
|
|
|
|
|
|
[--count | -C] [--verbose {number | format}] [--allow-unsafe] |
53
|
|
|
|
|
|
|
[--color | --nocolor] [--pager pager] [--quiet] |
54
|
|
|
|
|
|
|
[--color-severity-highest color_specification] |
55
|
|
|
|
|
|
|
[--color-severity-high color_specification] |
56
|
|
|
|
|
|
|
[--color-severity-medium color_specification] |
57
|
|
|
|
|
|
|
[--color-severity-low color_specification] |
58
|
|
|
|
|
|
|
[--color-severity-lowest color_specification] |
59
|
|
|
|
|
|
|
[--files-with-transformations | -l] |
60
|
|
|
|
|
|
|
[--files-without-transformations | -L] |
61
|
|
|
|
|
|
|
[--program-extensions file_name_extension] |
62
|
|
|
|
|
|
|
{FILE | DIRECTORY | STDIN} |
63
|
|
|
|
|
|
|
|
64
|
|
|
|
|
|
|
perlmogrify --profile-proto |
65
|
|
|
|
|
|
|
|
66
|
|
|
|
|
|
|
perlmogrify { --list | --list-enabled | --list-themes | --doc pattern [...] } |
67
|
|
|
|
|
|
|
|
68
|
|
|
|
|
|
|
perlmogrify { --help | --options | --man | --version } |
69
|
|
|
|
|
|
|
|
70
|
|
|
|
|
|
|
|
71
|
|
|
|
|
|
|
=head1 DESCRIPTION |
72
|
|
|
|
|
|
|
|
73
|
|
|
|
|
|
|
C<perlmogrify> is a Perl5 to Perl6 code transformer. It's the executable front |
74
|
|
|
|
|
|
|
end to L<Perl::ToPerl6>, which is a configurable, extensible code transfomer. |
75
|
|
|
|
|
|
|
Most of the code transfoermers were developed simply by taking sample Perl5 |
76
|
|
|
|
|
|
|
source and hand-editing it until it compiled under Perl6. |
77
|
|
|
|
|
|
|
|
78
|
|
|
|
|
|
|
The author hopes that the resultant Perl6 code is semantically correct, but |
79
|
|
|
|
|
|
|
makes no guarantees. The framework is completely based on L<Perl::Critic> |
80
|
|
|
|
|
|
|
and lets you use all of the extant L<Perl::Critic> options and .perlcriticrc |
81
|
|
|
|
|
|
|
configurations, under the name of '.perlmogrifyrc'. |
82
|
|
|
|
|
|
|
|
83
|
|
|
|
|
|
|
Code transformers can have options passed to them, but at the moment none of |
84
|
|
|
|
|
|
|
the core code transformers have options. Some basic options, such as |
85
|
|
|
|
|
|
|
transforming C<qw(a b c)> into more Perl6ish C<< <a b c> >> may be supported |
86
|
|
|
|
|
|
|
later on, but the general idea is transforming syntactically correct Perl5 |
87
|
|
|
|
|
|
|
code into Perl6. |
88
|
|
|
|
|
|
|
|
89
|
|
|
|
|
|
|
This documentation only covers how to drive this command. For all other |
90
|
|
|
|
|
|
|
information, such as API reference and alternative interfaces, please see the |
91
|
|
|
|
|
|
|
documentation for L<Perl::ToPerl6> itself. |
92
|
|
|
|
|
|
|
|
93
|
|
|
|
|
|
|
=head1 USAGE EXAMPLES |
94
|
|
|
|
|
|
|
|
95
|
|
|
|
|
|
|
Before getting into all the gory details, here are some basic usage |
96
|
|
|
|
|
|
|
examples to help get you started. |
97
|
|
|
|
|
|
|
|
98
|
|
|
|
|
|
|
# Apply only core transformations |
99
|
|
|
|
|
|
|
perlmogrify YourModule.pm |
100
|
|
|
|
|
|
|
|
101
|
|
|
|
|
|
|
# Same as above, but read input from STDIN |
102
|
|
|
|
|
|
|
perlmogrify |
103
|
|
|
|
|
|
|
|
104
|
|
|
|
|
|
|
# Recursively process all Perl files beneath directory |
105
|
|
|
|
|
|
|
perlmogrify /some/directory |
106
|
|
|
|
|
|
|
|
107
|
|
|
|
|
|
|
# Apply slightly less severe transformations too (severity >= 4) |
108
|
|
|
|
|
|
|
perlmogrify -4 YourModule.pm |
109
|
|
|
|
|
|
|
|
110
|
|
|
|
|
|
|
# Same as above, but using named severity level |
111
|
|
|
|
|
|
|
perlmogrify --stern YourModule.pm |
112
|
|
|
|
|
|
|
|
113
|
|
|
|
|
|
|
# Apply all transformations, regardless of severity (severity >= 1) |
114
|
|
|
|
|
|
|
perlmogrify -1 YourModule.pm |
115
|
|
|
|
|
|
|
|
116
|
|
|
|
|
|
|
# Same as above, but using named severity level |
117
|
|
|
|
|
|
|
perlmogrify --brutal YourModule.pm |
118
|
|
|
|
|
|
|
|
119
|
|
|
|
|
|
|
# Apply only core transformations |
120
|
|
|
|
|
|
|
perlmogrify --theme core YourModule.pm |
121
|
|
|
|
|
|
|
|
122
|
|
|
|
|
|
|
# Apply additional transformations that match m/variables/xms |
123
|
|
|
|
|
|
|
perlmogrify --include variables YourModule.pm |
124
|
|
|
|
|
|
|
|
125
|
|
|
|
|
|
|
# Use defaults from somewhere other than ~/.perlmogrifyrc |
126
|
|
|
|
|
|
|
perlmogrify --profile project/specific/perlmogrifyrc YourModule.pm |
127
|
|
|
|
|
|
|
|
128
|
|
|
|
|
|
|
|
129
|
|
|
|
|
|
|
=head1 ARGUMENTS |
130
|
|
|
|
|
|
|
|
131
|
|
|
|
|
|
|
The arguments are paths to the files you wish to analyze. You may specify |
132
|
|
|
|
|
|
|
multiple files. If an argument is a directory, C<perlmogrify> will analyze all |
133
|
|
|
|
|
|
|
Perl files below the directory. If no arguments are specified, then input is |
134
|
|
|
|
|
|
|
read from STDIN. |
135
|
|
|
|
|
|
|
|
136
|
|
|
|
|
|
|
|
137
|
|
|
|
|
|
|
=head1 OPTIONS |
138
|
|
|
|
|
|
|
|
139
|
|
|
|
|
|
|
Option names can be abbreviated to uniqueness and can be stated with single or |
140
|
|
|
|
|
|
|
double dashes, and option values can be separated from the option name by a |
141
|
|
|
|
|
|
|
space or '=' (as with L<Getopt::Long>). Option names are also case-sensitive. |
142
|
|
|
|
|
|
|
|
143
|
|
|
|
|
|
|
Most of these options come from the original L<Perl::Critic> module, and are |
144
|
|
|
|
|
|
|
more relevant to its operation. They'll remain in the L<Perl::ToPerl6> source |
145
|
|
|
|
|
|
|
and be pressed into new duties as time allows. |
146
|
|
|
|
|
|
|
|
147
|
|
|
|
|
|
|
The documentation still reflects their L<Perl::Critic> usages, but again this |
148
|
|
|
|
|
|
|
will be rewritten as time allows. |
149
|
|
|
|
|
|
|
|
150
|
|
|
|
|
|
|
=over |
151
|
|
|
|
|
|
|
|
152
|
|
|
|
|
|
|
=item C<--profile FILE> or C<-p FILE> |
153
|
|
|
|
|
|
|
|
154
|
|
|
|
|
|
|
Directs C<perlmogrify> to use a profile named by FILE rather than looking for |
155
|
|
|
|
|
|
|
the default F<.perlmogrifyrc> file in the current directory or your home |
156
|
|
|
|
|
|
|
directory. See L<Perl::ToPerl6/"CONFIGURATION"> for more information. |
157
|
|
|
|
|
|
|
|
158
|
|
|
|
|
|
|
=item C<--noprofile> |
159
|
|
|
|
|
|
|
|
160
|
|
|
|
|
|
|
Directs C<perlmogrify> not to load any configuration file, thus reverting to |
161
|
|
|
|
|
|
|
the default configuration for all Transformers. |
162
|
|
|
|
|
|
|
|
163
|
|
|
|
|
|
|
=item C<--severity N> |
164
|
|
|
|
|
|
|
|
165
|
|
|
|
|
|
|
Directs C<perlmogrify> to only apply Transformers with a severity greater than |
166
|
|
|
|
|
|
|
C<N>. Severity values are integers ranging from 1 (least severe) to 5 (most |
167
|
|
|
|
|
|
|
severe). The default is 5. For a given C<--profile>, decreasing the |
168
|
|
|
|
|
|
|
C<--severity> will usually produce more transformations. You can set the default |
169
|
|
|
|
|
|
|
value for this option in your F<.perlmogrifyrc> file. You can also redefine |
170
|
|
|
|
|
|
|
the C<severity> for any Transformer in your F<.perlmogrifyrc> file. See |
171
|
|
|
|
|
|
|
L<"CONFIGURATION"> for more information. |
172
|
|
|
|
|
|
|
|
173
|
|
|
|
|
|
|
=item C<-5 | -4 | -3 | -2 | -1> |
174
|
|
|
|
|
|
|
|
175
|
|
|
|
|
|
|
These are numeric shortcuts for setting the C<--severity> option. For |
176
|
|
|
|
|
|
|
example, C<"-4"> is equivalent to C<"--severity 4">. If multiple shortcuts |
177
|
|
|
|
|
|
|
are specified, then the most restrictive one wins. If an explicit |
178
|
|
|
|
|
|
|
C<--severity> option is also given, then all shortcut options are silently |
179
|
|
|
|
|
|
|
ignored. NOTE: Be careful not to put one of the number severity shortcut |
180
|
|
|
|
|
|
|
options immediately after the C<--top> flag or C<perlmogrify> will interpret it |
181
|
|
|
|
|
|
|
as the number of transformations to report. |
182
|
|
|
|
|
|
|
|
183
|
|
|
|
|
|
|
=item C<--severity NAME> |
184
|
|
|
|
|
|
|
|
185
|
|
|
|
|
|
|
If it is difficult for you to remember whether severity "5" is the most or |
186
|
|
|
|
|
|
|
least restrictive level, then you can use one of these named values: |
187
|
|
|
|
|
|
|
|
188
|
|
|
|
|
|
|
SEVERITY NAME ...is equivalent to... SEVERITY NUMBER |
189
|
|
|
|
|
|
|
-------------------------------------------------------- |
190
|
|
|
|
|
|
|
--severity gentle --severity 5 |
191
|
|
|
|
|
|
|
--severity stern --severity 4 |
192
|
|
|
|
|
|
|
--severity harsh --severity 3 |
193
|
|
|
|
|
|
|
--severity cruel --severity 2 |
194
|
|
|
|
|
|
|
--severity brutal --severity 1 |
195
|
|
|
|
|
|
|
|
196
|
|
|
|
|
|
|
=item C<--gentle | --stern | --harsh | --cruel | --brutal> |
197
|
|
|
|
|
|
|
|
198
|
|
|
|
|
|
|
These are named shortcuts for setting the C<--severity> option. For example, |
199
|
|
|
|
|
|
|
C<"--cruel"> is equivalent to C<"--severity 2">. If multiple shortcuts are |
200
|
|
|
|
|
|
|
specified, then the most restrictive one wins. If an explicit C<--severity> |
201
|
|
|
|
|
|
|
option is also given, then all shortcut options are silently ignored. |
202
|
|
|
|
|
|
|
|
203
|
|
|
|
|
|
|
=item C<--theme RULE> |
204
|
|
|
|
|
|
|
|
205
|
|
|
|
|
|
|
Directs C<perlmogrify> to apply only Transformers with themes that satisfy the |
206
|
|
|
|
|
|
|
C<RULE>. Themes are arbitrary names for groups of related transformers. |
207
|
|
|
|
|
|
|
You can combine theme names with boolean operators to create an arbitrarily |
208
|
|
|
|
|
|
|
complex C<RULE>. For example, the following would apply only Transformers that |
209
|
|
|
|
|
|
|
have a 'bugs' AND 'core' theme: |
210
|
|
|
|
|
|
|
|
211
|
|
|
|
|
|
|
$> perlmogrify --theme='bugs && core' MyModule.pm |
212
|
|
|
|
|
|
|
|
213
|
|
|
|
|
|
|
Unless the C<--severity> option is explicitly given, setting C<--theme> |
214
|
|
|
|
|
|
|
silently causes the C<--severity> to be set to 1. You can set the default |
215
|
|
|
|
|
|
|
value for this option in your F<.perlmogrifyrc> file. See |
216
|
|
|
|
|
|
|
L<Perl::ToPerl6/"TRANSFORMER THEMES"> for more information about themes. |
217
|
|
|
|
|
|
|
|
218
|
|
|
|
|
|
|
=item C<--include PATTERN> |
219
|
|
|
|
|
|
|
|
220
|
|
|
|
|
|
|
Directs C<perlmogrify> to apply additional Transformers that match the regex |
221
|
|
|
|
|
|
|
C</PATTERN/imx>. Use this option to temporarily override your profile and/or |
222
|
|
|
|
|
|
|
the severity settings at the command-line. For example: |
223
|
|
|
|
|
|
|
|
224
|
|
|
|
|
|
|
perlmogrify --include=layout my_file.pl |
225
|
|
|
|
|
|
|
|
226
|
|
|
|
|
|
|
This would cause C<perlmogrify> to apply all the C<CodeLayout::*> transformers |
227
|
|
|
|
|
|
|
even if they have a severity level that is less than the default level of 5, or |
228
|
|
|
|
|
|
|
have been disabled in your F<.perlmogrifyrc> file. You can specify multiple |
229
|
|
|
|
|
|
|
C<--include> options and you can use it in conjunction with the C<--exclude> |
230
|
|
|
|
|
|
|
option. Note that C<--exclude> takes precedence over C<--include> when a |
231
|
|
|
|
|
|
|
Transformer matches both patterns. You can set the default value for this |
232
|
|
|
|
|
|
|
option in your F<.perlmogrifyrc> file. |
233
|
|
|
|
|
|
|
|
234
|
|
|
|
|
|
|
=item C<--exclude PATTERN> |
235
|
|
|
|
|
|
|
|
236
|
|
|
|
|
|
|
Directs C<perlmogrify> to not apply any Transformer that matches the regex |
237
|
|
|
|
|
|
|
C</PATTERN/imx>. Use this option to temporarily override your profile and/or |
238
|
|
|
|
|
|
|
the severity settings at the command-line. For example: |
239
|
|
|
|
|
|
|
|
240
|
|
|
|
|
|
|
perlmogrify --exclude=strict my_file.pl |
241
|
|
|
|
|
|
|
|
242
|
|
|
|
|
|
|
This would cause C<perlmogrify> to not apply the C<RequireUseStrict> and |
243
|
|
|
|
|
|
|
C<ProhibitNoStrict> Transformers even though they have the highest severity |
244
|
|
|
|
|
|
|
level. You can specify multiple C<--exclude> options and you can use it in |
245
|
|
|
|
|
|
|
conjunction with the C<--include> option. Note that C<--exclude> takes |
246
|
|
|
|
|
|
|
precedence over C<--include> when a Transformer matches both patterns. You can set |
247
|
|
|
|
|
|
|
the default value for this option in your F<.perlmogrifyrc> file. |
248
|
|
|
|
|
|
|
|
249
|
|
|
|
|
|
|
=item C<--single-transformer PATTERN> or C<-s PATTERN> |
250
|
|
|
|
|
|
|
|
251
|
|
|
|
|
|
|
Directs C<perlmogrify> to apply just one Transformer module matching the regex |
252
|
|
|
|
|
|
|
C</PATTERN/ixms>, and exclude all other Transformers. This option has |
253
|
|
|
|
|
|
|
precedence over the C<--severity>, C<--theme>, C<--include>, C<--exclude>, and |
254
|
|
|
|
|
|
|
C<--only> options. For example: |
255
|
|
|
|
|
|
|
|
256
|
|
|
|
|
|
|
perlmogrify --single-transformer=nowarnings my_file.pl |
257
|
|
|
|
|
|
|
|
258
|
|
|
|
|
|
|
This would cause C<perlmogrify> to apply just the C<ProhibitNoWarnings> |
259
|
|
|
|
|
|
|
Transformer, regardless of the severity level setting. No other Transformers |
260
|
|
|
|
|
|
|
would be applied. |
261
|
|
|
|
|
|
|
|
262
|
|
|
|
|
|
|
This is equivalent to what one might intend by... |
263
|
|
|
|
|
|
|
|
264
|
|
|
|
|
|
|
perlmogrify --exclude=. --include=nowarnings my_file.pl |
265
|
|
|
|
|
|
|
|
266
|
|
|
|
|
|
|
... but this won't work because the C<--exclude> option overrides the |
267
|
|
|
|
|
|
|
C<--include> option. |
268
|
|
|
|
|
|
|
|
269
|
|
|
|
|
|
|
The equivalent of this option can be accomplished by creating a custom profile |
270
|
|
|
|
|
|
|
containing only the desired transformer and then running... |
271
|
|
|
|
|
|
|
|
272
|
|
|
|
|
|
|
perlmogrify --profile=customprofile --only my_file.pl |
273
|
|
|
|
|
|
|
|
274
|
|
|
|
|
|
|
=item C<--top [ N ]> |
275
|
|
|
|
|
|
|
|
276
|
|
|
|
|
|
|
Directs C<perlmogrify> to report only the top C<N> Transformer transformations |
277
|
|
|
|
|
|
|
in each file, ranked by their severity. If C<N> is not specified, it defaults |
278
|
|
|
|
|
|
|
to 20. If the C<--severity> option (or one of the shortcuts) is not explicitly |
279
|
|
|
|
|
|
|
given, the C<--top> option implies that the minimum severity level is "1" (i.e. |
280
|
|
|
|
|
|
|
"brutal"). Users can redefine the severity for any Transformer in their |
281
|
|
|
|
|
|
|
F<.perlmogrifyrc> file. See L<"CONFIGURATION"> for more information. You can |
282
|
|
|
|
|
|
|
set the default value for this option in your F<.perlmogrifyrc> file. NOTE: Be |
283
|
|
|
|
|
|
|
careful not to put one of the severity shortcut options immediately after the |
284
|
|
|
|
|
|
|
C<--top> flag or C<perlmogrify> will interpret it as the number of |
285
|
|
|
|
|
|
|
transformations to report. |
286
|
|
|
|
|
|
|
|
287
|
|
|
|
|
|
|
=item C<--force> |
288
|
|
|
|
|
|
|
|
289
|
|
|
|
|
|
|
Directs C<perlmogrify> to ignore the magical C<"## no mogrify"> annotations in |
290
|
|
|
|
|
|
|
the source code. See L<"BENDING THE RULES"> for more information. You can set |
291
|
|
|
|
|
|
|
the default value for this option in your F<.perlmogrifyrc> file. |
292
|
|
|
|
|
|
|
|
293
|
|
|
|
|
|
|
=item C<--statistics> |
294
|
|
|
|
|
|
|
|
295
|
|
|
|
|
|
|
Causes several statistics about the code being scanned and the transformations |
296
|
|
|
|
|
|
|
found to be reported after any other output. |
297
|
|
|
|
|
|
|
|
298
|
|
|
|
|
|
|
=item C<--statistics-only> |
299
|
|
|
|
|
|
|
|
300
|
|
|
|
|
|
|
Like the C<--statistics> option, but suppresses normal output and only shows |
301
|
|
|
|
|
|
|
the statistics. |
302
|
|
|
|
|
|
|
|
303
|
|
|
|
|
|
|
=item C<--verbose N | FORMAT> |
304
|
|
|
|
|
|
|
|
305
|
|
|
|
|
|
|
Sets the verbosity level or format for reporting transformations. If given a |
306
|
|
|
|
|
|
|
number (C<N>), C<perlmogrify> reports transformations using one of the predefined |
307
|
|
|
|
|
|
|
formats described below. If given a string (C<FORMAT>), it is interpreted to |
308
|
|
|
|
|
|
|
be an actual format specification. If the C<--verbose> option is not |
309
|
|
|
|
|
|
|
specified, it defaults to either 4 or 5, depending on whether multiple files |
310
|
|
|
|
|
|
|
were given as arguments to C<perlmogrify>. You can set the default value for |
311
|
|
|
|
|
|
|
this option in your F<.perlmogrifyrc> file. |
312
|
|
|
|
|
|
|
|
313
|
|
|
|
|
|
|
Verbosity Format Specification |
314
|
|
|
|
|
|
|
----------- ------------------------------------------------------- |
315
|
|
|
|
|
|
|
1 "%f:%l:%c:%m\n", |
316
|
|
|
|
|
|
|
2 "%f: (%l:%c) %m\n", |
317
|
|
|
|
|
|
|
3 "%m at %f line %l\n", |
318
|
|
|
|
|
|
|
4 "%m at line %l, column %c. %e. (Severity: %s)\n", |
319
|
|
|
|
|
|
|
5 "%f: %m at line %l, column %c. %e. (Severity: %s)\n", |
320
|
|
|
|
|
|
|
6 "%m at line %l, near '%r'. (Severity: %s)\n", |
321
|
|
|
|
|
|
|
7 "%f: %m at line %l near '%r'. (Severity: %s)\n", |
322
|
|
|
|
|
|
|
8 "[%p] %m at line %l, column %c. (Severity: %s)\n", |
323
|
|
|
|
|
|
|
9 "[%p] %m at line %l, near '%r'. (Severity: %s)\n", |
324
|
|
|
|
|
|
|
10 "%m at line %l, column %c.\n %p (Severity: %s)\n%d\n", |
325
|
|
|
|
|
|
|
11 "%m at line %l, near '%r'.\n %p (Severity: %s)\n%d\n" |
326
|
|
|
|
|
|
|
|
327
|
|
|
|
|
|
|
Formats are a combination of literal and escape characters similar to the way |
328
|
|
|
|
|
|
|
C<sprintf> works. See L<String::Format|String::Format> for a full explanation |
329
|
|
|
|
|
|
|
of the formatting capabilities. Valid escape characters are: |
330
|
|
|
|
|
|
|
|
331
|
|
|
|
|
|
|
Escape Meaning |
332
|
|
|
|
|
|
|
------- ------------------------------------------------------------ |
333
|
|
|
|
|
|
|
%c Column number where the transformation occurred |
334
|
|
|
|
|
|
|
%d Full diagnostic discussion of the transformation |
335
|
|
|
|
|
|
|
%e Explanation of transformation |
336
|
|
|
|
|
|
|
%F Just the name of the file where the transformation occurred. |
337
|
|
|
|
|
|
|
%f Path to the file where the transformation occurred. |
338
|
|
|
|
|
|
|
%l Line number where the transformation occurred |
339
|
|
|
|
|
|
|
%m Brief description of the transformation |
340
|
|
|
|
|
|
|
%P Full name of the Transformer module that created the transformation |
341
|
|
|
|
|
|
|
%p Name of the Transformer without the Perl::ToPerl6::Transformer:: prefix |
342
|
|
|
|
|
|
|
%r The string of source code that caused the transformation |
343
|
|
|
|
|
|
|
%C The class of the PPI::Element that caused the transformation |
344
|
|
|
|
|
|
|
%s The severity level of the transformation |
345
|
|
|
|
|
|
|
|
346
|
|
|
|
|
|
|
The purpose of these formats is to provide some compatibility with text |
347
|
|
|
|
|
|
|
editors that have an interface for parsing certain kinds of input. See |
348
|
|
|
|
|
|
|
L<"EDITOR INTEGRATION"> for more information about that. |
349
|
|
|
|
|
|
|
|
350
|
|
|
|
|
|
|
=item C<--list> |
351
|
|
|
|
|
|
|
|
352
|
|
|
|
|
|
|
Displays a condensed listing of all the L<Perl::ToPerl6::Transformer> modules |
353
|
|
|
|
|
|
|
that are found on this machine. This option lists I<all> Transformers, |
354
|
|
|
|
|
|
|
regardless of your F<.perlmogrifyrc> or command line options. For each |
355
|
|
|
|
|
|
|
Transformer, the name, default severity and default themes are shown. |
356
|
|
|
|
|
|
|
|
357
|
|
|
|
|
|
|
=item C<--list-enabled> |
358
|
|
|
|
|
|
|
|
359
|
|
|
|
|
|
|
Displays a condensed listing of all the L<Perl::ToPerl6::Transformer> modules |
360
|
|
|
|
|
|
|
that I<would> be applied, if you were actually going to transform a file with |
361
|
|
|
|
|
|
|
this command. This is useful when you've constructed a complicated command or |
362
|
|
|
|
|
|
|
modified your F<.perlmogrifyrc> file and you want to see exactly which |
363
|
|
|
|
|
|
|
Transformers are going to be enforced (or not enforced, as the case may be). |
364
|
|
|
|
|
|
|
For each Transformer, the name, default severity and default themes are shown. |
365
|
|
|
|
|
|
|
|
366
|
|
|
|
|
|
|
=item C<--list-themes> |
367
|
|
|
|
|
|
|
|
368
|
|
|
|
|
|
|
Displays a list of all the themes of the L<Perl::ToPerl6::Transformer> modules |
369
|
|
|
|
|
|
|
that are found on this machine. |
370
|
|
|
|
|
|
|
|
371
|
|
|
|
|
|
|
=item C<--profile-proto> |
372
|
|
|
|
|
|
|
|
373
|
|
|
|
|
|
|
Displays an expanded listing of all the L<Perl::ToPerl6::Transformer> modules |
374
|
|
|
|
|
|
|
that are found on this machine. For each Transformer, the name, default |
375
|
|
|
|
|
|
|
severity and default themes are shown, as well as the name of any additional |
376
|
|
|
|
|
|
|
parameters that the Transformer supports. The format is suitable as a |
377
|
|
|
|
|
|
|
prototype for your F<.perlmogrifyrc> file. |
378
|
|
|
|
|
|
|
|
379
|
|
|
|
|
|
|
=item C<--only> |
380
|
|
|
|
|
|
|
|
381
|
|
|
|
|
|
|
Directs perlmogrify to apply only Transformers that are explicitly mentioned in |
382
|
|
|
|
|
|
|
your F<.perlmogrifyrc> file. This is useful if you want to use just a small |
383
|
|
|
|
|
|
|
subset of Transformers without having to disable all the others. You can set |
384
|
|
|
|
|
|
|
the default value for this option in your F<.perlmogrifyrc> file. |
385
|
|
|
|
|
|
|
|
386
|
|
|
|
|
|
|
=item C<--profile-strictness {warn|fatal|quiet}> |
387
|
|
|
|
|
|
|
|
388
|
|
|
|
|
|
|
Directs perlmogrify how to treat certain recoverable problems found in a |
389
|
|
|
|
|
|
|
F<.perlmogrifyrc> or file specified via the C<--profile> option. Valid values |
390
|
|
|
|
|
|
|
are C<warn> (the default), C<fatal>, and C<quiet>. For example, perlmogrify |
391
|
|
|
|
|
|
|
normally only warns about profiles referring to non-existent Transformers, but |
392
|
|
|
|
|
|
|
this option can make this situation fatal. You can set the default value for |
393
|
|
|
|
|
|
|
this option in your F<.perlmogrifyrc> file. |
394
|
|
|
|
|
|
|
|
395
|
|
|
|
|
|
|
=item C<--count> |
396
|
|
|
|
|
|
|
|
397
|
|
|
|
|
|
|
=item C<-C> |
398
|
|
|
|
|
|
|
|
399
|
|
|
|
|
|
|
Display only the number of transformations for each file. Use this feature to |
400
|
|
|
|
|
|
|
get a quick handle on where a large pile of code might need the most attention. |
401
|
|
|
|
|
|
|
|
402
|
|
|
|
|
|
|
=item C<--color> |
403
|
|
|
|
|
|
|
=item C<--colour> |
404
|
|
|
|
|
|
|
|
405
|
|
|
|
|
|
|
This option is on when outputting to a tty. When set, Severity 5 and 4 are |
406
|
|
|
|
|
|
|
colored red and yellow, respectively. Colorization only happens if |
407
|
|
|
|
|
|
|
L<Term::ANSIColor> is installed and it only works on non-Windows environments. |
408
|
|
|
|
|
|
|
Negate this switch to disable color. You can set the default value for this |
409
|
|
|
|
|
|
|
option in your F<.perlmogrifyrc> file. |
410
|
|
|
|
|
|
|
|
411
|
|
|
|
|
|
|
=item C<--pager PAGER_COMMAND_STRING> |
412
|
|
|
|
|
|
|
|
413
|
|
|
|
|
|
|
If set, perlmogrify will pipe it's output to the given PAGER_COMMAND_STRING. |
414
|
|
|
|
|
|
|
You can set the default value for this option in your F<.perlmogrifyrc> file. |
415
|
|
|
|
|
|
|
|
416
|
|
|
|
|
|
|
Setting a pager turns off color by default. You will have to turn color on |
417
|
|
|
|
|
|
|
explicitly. If you want color, you'll probably also want to tell your pager |
418
|
|
|
|
|
|
|
to display raw characters. For C<less> and C<more>, use the -R switch. |
419
|
|
|
|
|
|
|
|
420
|
|
|
|
|
|
|
=item C<--color-severity-highest COLOR_SPECIFICATION> |
421
|
|
|
|
|
|
|
|
422
|
|
|
|
|
|
|
Specifies the color to be used for highest severity transformations, as a |
423
|
|
|
|
|
|
|
Term::ANSIColor color specification. Can also be specified as C<--colour- |
424
|
|
|
|
|
|
|
severity-highest>, C<--color-severity-5>, or C<--colour-severity-5>. |
425
|
|
|
|
|
|
|
|
426
|
|
|
|
|
|
|
=item C<--color-severity-high COLOR_SPECIFICATION> |
427
|
|
|
|
|
|
|
|
428
|
|
|
|
|
|
|
Specifies the color to be used for high severity transformations, as a |
429
|
|
|
|
|
|
|
Term::ANSIColor color specification. Can also be specified as C<--colour- |
430
|
|
|
|
|
|
|
severity-high>, C<--color-severity-4>, or C<--colour-severity-4>. |
431
|
|
|
|
|
|
|
|
432
|
|
|
|
|
|
|
=item C<--color-severity-medium COLOR_SPECIFICATION> |
433
|
|
|
|
|
|
|
|
434
|
|
|
|
|
|
|
Specifies the color to be used for medium severity transformations, as a |
435
|
|
|
|
|
|
|
Term::ANSIColor color specification. Can also be specified as C<--colour- |
436
|
|
|
|
|
|
|
severity-medium>, C<--color-severity-3>, or C<--colour-severity-3>. |
437
|
|
|
|
|
|
|
|
438
|
|
|
|
|
|
|
=item C<--color-severity-low COLOR_SPECIFICATION> |
439
|
|
|
|
|
|
|
|
440
|
|
|
|
|
|
|
Specifies the color to be used for low severity transformations, as a |
441
|
|
|
|
|
|
|
Term::ANSIColor color specification. Can also be specified as C<--colour- |
442
|
|
|
|
|
|
|
severity-low>, C<--color-severity-2>, or C<--colour-severity-2>. |
443
|
|
|
|
|
|
|
|
444
|
|
|
|
|
|
|
=item C<--color-severity-lowest COLOR_SPECIFICATION> |
445
|
|
|
|
|
|
|
|
446
|
|
|
|
|
|
|
Specifies the color to be used for lowest severity transformations, as a |
447
|
|
|
|
|
|
|
Term::ANSIColor color specification. Can also be specified as C<--colour- |
448
|
|
|
|
|
|
|
severity-lowest>, C<--color-severity-1>, or C<--colour-severity-1>. |
449
|
|
|
|
|
|
|
|
450
|
|
|
|
|
|
|
=item C<--files-with-transformations> |
451
|
|
|
|
|
|
|
|
452
|
|
|
|
|
|
|
Display only the names of files with transformations. Use this feature with |
453
|
|
|
|
|
|
|
--single-transformer to find files that contain transformations of a given |
454
|
|
|
|
|
|
|
transformer. Can also be specified as C<--l>. |
455
|
|
|
|
|
|
|
|
456
|
|
|
|
|
|
|
=item C<--files-without-transformations> |
457
|
|
|
|
|
|
|
|
458
|
|
|
|
|
|
|
Display only the names of files without transformations. Use this feature with |
459
|
|
|
|
|
|
|
--single-transformer to find files that do not contain transformations of a |
460
|
|
|
|
|
|
|
given transformer. Can also be specified as C<--L>. |
461
|
|
|
|
|
|
|
|
462
|
|
|
|
|
|
|
=item C<--program-extensions file_name_extension> |
463
|
|
|
|
|
|
|
|
464
|
|
|
|
|
|
|
Tell C<perlmogrify> to treat files whose names end in the given file name |
465
|
|
|
|
|
|
|
extension as programs, not as modules. If a leading '.' is desired it must be |
466
|
|
|
|
|
|
|
explicitly specified, e.g. |
467
|
|
|
|
|
|
|
|
468
|
|
|
|
|
|
|
--program-extensions .pl |
469
|
|
|
|
|
|
|
|
470
|
|
|
|
|
|
|
The matching is case-sensitive, and the option may be specified as many times |
471
|
|
|
|
|
|
|
as desired, e.g. |
472
|
|
|
|
|
|
|
|
473
|
|
|
|
|
|
|
--program-extensions .pl --program-extensions .cgi |
474
|
|
|
|
|
|
|
|
475
|
|
|
|
|
|
|
The above can also be done by quoting the file name extensions: |
476
|
|
|
|
|
|
|
|
477
|
|
|
|
|
|
|
--program-extensions '.pl .cgi' |
478
|
|
|
|
|
|
|
|
479
|
|
|
|
|
|
|
Files whose name ends in '.PL' will always be considered programs. |
480
|
|
|
|
|
|
|
|
481
|
|
|
|
|
|
|
=item C<--doc PATTERN> |
482
|
|
|
|
|
|
|
|
483
|
|
|
|
|
|
|
Displays the perldoc for all L<Perl::ToPerl6::Transformer> modules that match |
484
|
|
|
|
|
|
|
C<m/PATTERN/ixms>. Since Transformer modules tend to have rather long names, this |
485
|
|
|
|
|
|
|
just provides a more convenient way to say something like: C<"perldoc |
486
|
|
|
|
|
|
|
Perl::ToPerl6::Transformer::ValuesAndExpressions::RequireUpperCaseH |
487
|
|
|
|
|
|
|
eredocTerminator"> at the command prompt. |
488
|
|
|
|
|
|
|
|
489
|
|
|
|
|
|
|
=item C<--allow-unsafe> |
490
|
|
|
|
|
|
|
|
491
|
|
|
|
|
|
|
This option directs C<perlmogrify> to allow the use of Transformers that have |
492
|
|
|
|
|
|
|
been marked as "unsafe". Unsafe Transformers may result in risky operations by |
493
|
|
|
|
|
|
|
compiling and executing the code they analyze. All the Transformers that ship |
494
|
|
|
|
|
|
|
in the core L<Perl::ToPerl6> distribution are safe. However, third- party |
495
|
|
|
|
|
|
|
Transformers, such as those in the L<Perl::ToPerl6::Dynamic> distribution are |
496
|
|
|
|
|
|
|
not safe. Note that "safety" is honorary -- if a Transformer author marks a |
497
|
|
|
|
|
|
|
Transformer as safe, it is not a guarantee that it won't do nasty things. |
498
|
|
|
|
|
|
|
B<If you don't trust your Transformers and the code you are analyzing, then do |
499
|
|
|
|
|
|
|
not use this switch>. |
500
|
|
|
|
|
|
|
|
501
|
|
|
|
|
|
|
=item C<--quiet> |
502
|
|
|
|
|
|
|
|
503
|
|
|
|
|
|
|
Suppress the "source OK" message when no transformations are found. |
504
|
|
|
|
|
|
|
|
505
|
|
|
|
|
|
|
=item C<--help> |
506
|
|
|
|
|
|
|
|
507
|
|
|
|
|
|
|
=item C<-?> |
508
|
|
|
|
|
|
|
|
509
|
|
|
|
|
|
|
=item C<-H> |
510
|
|
|
|
|
|
|
|
511
|
|
|
|
|
|
|
Displays a brief summary of options and exits. |
512
|
|
|
|
|
|
|
|
513
|
|
|
|
|
|
|
=item C<--options> |
514
|
|
|
|
|
|
|
|
515
|
|
|
|
|
|
|
Displays the descriptions of the options and exits. While this output is |
516
|
|
|
|
|
|
|
long, it it nowhere near the length of the output of C<--man>. |
517
|
|
|
|
|
|
|
|
518
|
|
|
|
|
|
|
=item C<--man> |
519
|
|
|
|
|
|
|
|
520
|
|
|
|
|
|
|
Displays the complete C<perlmogrify> manual and exits. |
521
|
|
|
|
|
|
|
|
522
|
|
|
|
|
|
|
=item C<--version> |
523
|
|
|
|
|
|
|
|
524
|
|
|
|
|
|
|
=item C<-V> |
525
|
|
|
|
|
|
|
|
526
|
|
|
|
|
|
|
Displays the version number of C<perlmogrify> and exits. |
527
|
|
|
|
|
|
|
|
528
|
|
|
|
|
|
|
=back |
529
|
|
|
|
|
|
|
|
530
|
|
|
|
|
|
|
=head1 CONFIGURATION |
531
|
|
|
|
|
|
|
|
532
|
|
|
|
|
|
|
Most of the settings for Perl::ToPerl6 and each of the Transformer modules can |
533
|
|
|
|
|
|
|
be controlled by a configuration file. The default configuration file is |
534
|
|
|
|
|
|
|
called F<.perlmogrifyrc>. C<perlmogrify> will look for this file in the |
535
|
|
|
|
|
|
|
current directory first, and then in your home directory. Alternatively, you |
536
|
|
|
|
|
|
|
can set the C<PERLMOGRIFY> environment variable to explicitly point to a |
537
|
|
|
|
|
|
|
different file in another location. If none of these files exist, and the |
538
|
|
|
|
|
|
|
C<--profile> option is not given on the command-line, then all Transformers |
539
|
|
|
|
|
|
|
will be loaded with their default configuration. |
540
|
|
|
|
|
|
|
|
541
|
|
|
|
|
|
|
The format of the configuration file is a series of INI-style blocks that |
542
|
|
|
|
|
|
|
contain key-value pairs separated by "=". Comments should start with "#" and |
543
|
|
|
|
|
|
|
can be placed on a separate line or after the name-value pairs if you desire. |
544
|
|
|
|
|
|
|
|
545
|
|
|
|
|
|
|
Default settings for perlmogrify itself can be set B<before the first named |
546
|
|
|
|
|
|
|
block.> For example, putting any or all of these at the top of your |
547
|
|
|
|
|
|
|
F<.perlmogrifyrc> file will set the default value for the corresponding |
548
|
|
|
|
|
|
|
command-line argument. |
549
|
|
|
|
|
|
|
|
550
|
|
|
|
|
|
|
severity = 3 #Integer or named level |
551
|
|
|
|
|
|
|
only = 1 #Zero or One |
552
|
|
|
|
|
|
|
force = 0 #Zero or One |
553
|
|
|
|
|
|
|
verbose = 4 #Integer or format spec |
554
|
|
|
|
|
|
|
top = 50 #A positive integer |
555
|
|
|
|
|
|
|
theme = (pbp + security) * bugs #A theme expression |
556
|
|
|
|
|
|
|
include = NamingConventions ClassHierarchies #Space-delimited list |
557
|
|
|
|
|
|
|
exclude = Variables Modules::RequirePackage #Space-delimited list |
558
|
|
|
|
|
|
|
|
559
|
|
|
|
|
|
|
The remainder of the configuration file is a series of blocks like this: |
560
|
|
|
|
|
|
|
|
561
|
|
|
|
|
|
|
[Perl::ToPerl6::Transformer::Category::TransformerName] |
562
|
|
|
|
|
|
|
severity = 1 |
563
|
|
|
|
|
|
|
set_themes = foo bar |
564
|
|
|
|
|
|
|
add_themes = baz |
565
|
|
|
|
|
|
|
arg1 = value1 |
566
|
|
|
|
|
|
|
arg2 = value2 |
567
|
|
|
|
|
|
|
|
568
|
|
|
|
|
|
|
C<Perl::ToPerl6::Transformer::Category::TransformerName> is the full name of a |
569
|
|
|
|
|
|
|
module that implements the transformer. |
570
|
|
|
|
|
|
|
|
571
|
|
|
|
|
|
|
C<severity> is the level of importance you wish to assign to the Transformer. |
572
|
|
|
|
|
|
|
All Transformer modules are defined with a default severity value ranging from 1 |
573
|
|
|
|
|
|
|
(least severe) to 5 (most severe). However, you may disagree with the default |
574
|
|
|
|
|
|
|
severity and choose to give it a higher or lower severity, based on your own |
575
|
|
|
|
|
|
|
coding philosophy. You can set the C<severity> to an integer from 1 to 5, or |
576
|
|
|
|
|
|
|
use one of the equivalent names: |
577
|
|
|
|
|
|
|
|
578
|
|
|
|
|
|
|
SEVERITY NAME ...is equivalent to... SEVERITY NUMBER |
579
|
|
|
|
|
|
|
---------------------------------------------------- |
580
|
|
|
|
|
|
|
gentle 5 |
581
|
|
|
|
|
|
|
stern 4 |
582
|
|
|
|
|
|
|
harsh 3 |
583
|
|
|
|
|
|
|
cruel 2 |
584
|
|
|
|
|
|
|
brutal 1 |
585
|
|
|
|
|
|
|
|
586
|
|
|
|
|
|
|
C<set_themes> sets the theme for the Transformer and overrides its default |
587
|
|
|
|
|
|
|
theme. The argument is a string of one or more whitespace-delimited |
588
|
|
|
|
|
|
|
alphanumeric words. Themes are case-insensitive. See L<"TRANSFORMER THEMES"> |
589
|
|
|
|
|
|
|
for more information. |
590
|
|
|
|
|
|
|
|
591
|
|
|
|
|
|
|
C<add_themes> appends to the default themes for this Transformer. The argument |
592
|
|
|
|
|
|
|
is a string of one or more whitespace-delimited words. Themes are case- |
593
|
|
|
|
|
|
|
insensitive. See L<"TRANSFORMER THEMES"> for more information. |
594
|
|
|
|
|
|
|
|
595
|
|
|
|
|
|
|
The remaining key-value pairs are configuration parameters that will be passed |
596
|
|
|
|
|
|
|
into the constructor of that Transformer. The constructors for most Transformer modules |
597
|
|
|
|
|
|
|
do not support arguments, and those that do should have reasonable defaults. |
598
|
|
|
|
|
|
|
See the documentation on the appropriate Transformer module for more details. |
599
|
|
|
|
|
|
|
|
600
|
|
|
|
|
|
|
Instead of redefining the severity for a given Transformer, you can completely |
601
|
|
|
|
|
|
|
disable a Transformer by prepending a '-' to the name of the module in your |
602
|
|
|
|
|
|
|
configuration file. In this manner, the Transformer will never be loaded, |
603
|
|
|
|
|
|
|
regardless of the C<--severity> given on the command line. |
604
|
|
|
|
|
|
|
|
605
|
|
|
|
|
|
|
A simple configuration might look like this: |
606
|
|
|
|
|
|
|
|
607
|
|
|
|
|
|
|
#-------------------------------------------------------------- |
608
|
|
|
|
|
|
|
# I think these are really important, so always load them |
609
|
|
|
|
|
|
|
|
610
|
|
|
|
|
|
|
[TestingAndDebugging::RequireUseStrict] |
611
|
|
|
|
|
|
|
severity = 5 |
612
|
|
|
|
|
|
|
|
613
|
|
|
|
|
|
|
[TestingAndDebugging::RequireUseWarnings] |
614
|
|
|
|
|
|
|
severity = 5 |
615
|
|
|
|
|
|
|
|
616
|
|
|
|
|
|
|
#-------------------------------------------------------------- |
617
|
|
|
|
|
|
|
# I think these are less important, so only load when asked |
618
|
|
|
|
|
|
|
|
619
|
|
|
|
|
|
|
[Variables::ProhibitPackageVars] |
620
|
|
|
|
|
|
|
severity = 2 |
621
|
|
|
|
|
|
|
|
622
|
|
|
|
|
|
|
[ControlStructures::ProhibitPostfixControls] |
623
|
|
|
|
|
|
|
allow = if unless # My custom configuration |
624
|
|
|
|
|
|
|
severity = cruel # Same as "severity = 2" |
625
|
|
|
|
|
|
|
|
626
|
|
|
|
|
|
|
#-------------------------------------------------------------- |
627
|
|
|
|
|
|
|
# Give these transformers a custom theme. I can activate just |
628
|
|
|
|
|
|
|
# these transformers by saying "perlmogrify --theme 'larry || curly'" |
629
|
|
|
|
|
|
|
|
630
|
|
|
|
|
|
|
[Modules::RequireFilenameMatchesPackage] |
631
|
|
|
|
|
|
|
add_themes = larry |
632
|
|
|
|
|
|
|
|
633
|
|
|
|
|
|
|
[TestingAndDebugging::RequireTestLabels] |
634
|
|
|
|
|
|
|
add_themes = curly moe |
635
|
|
|
|
|
|
|
|
636
|
|
|
|
|
|
|
#-------------------------------------------------------------- |
637
|
|
|
|
|
|
|
# I do not agree with these at all, so never load them |
638
|
|
|
|
|
|
|
|
639
|
|
|
|
|
|
|
[-NamingConventions::Capitalization] |
640
|
|
|
|
|
|
|
[-ValuesAndExpressions::ProhibitMagicNumbers] |
641
|
|
|
|
|
|
|
|
642
|
|
|
|
|
|
|
#-------------------------------------------------------------- |
643
|
|
|
|
|
|
|
# For all other Transformers, I accept the default severity, |
644
|
|
|
|
|
|
|
# so no additional configuration is required for them. |
645
|
|
|
|
|
|
|
|
646
|
|
|
|
|
|
|
Note that all transformers included with the Perl::ToPerl6 distribution that have |
647
|
|
|
|
|
|
|
integer parameters accept underscores ("_") in their values, as with Perl |
648
|
|
|
|
|
|
|
numeric literals. For example, |
649
|
|
|
|
|
|
|
|
650
|
|
|
|
|
|
|
[ValuesAndExpressions::RequireNumberSeparators] |
651
|
|
|
|
|
|
|
min_value = 1_000 |
652
|
|
|
|
|
|
|
|
653
|
|
|
|
|
|
|
For additional configuration examples, see the F<perlmogrifyrc> file that is |
654
|
|
|
|
|
|
|
included in this F<examples> directory of this distribution. |
655
|
|
|
|
|
|
|
|
656
|
|
|
|
|
|
|
Damian Conway's own Perl::ToPerl6 configuration is also included in this |
657
|
|
|
|
|
|
|
distribution as F<examples/perlmogrifyrc-conway>. |
658
|
|
|
|
|
|
|
|
659
|
|
|
|
|
|
|
|
660
|
|
|
|
|
|
|
=head1 THE POLICIES |
661
|
|
|
|
|
|
|
|
662
|
|
|
|
|
|
|
A large number of Transformer modules are distributed with Perl::ToPerl6. They are |
663
|
|
|
|
|
|
|
described briefly in the companion document L<Perl::ToPerl6::TransformerSummary> and |
664
|
|
|
|
|
|
|
in more detail in the individual modules themselves. Say C<"perlmogrify --doc |
665
|
|
|
|
|
|
|
PATTERN"> to see the perldoc for all Transformer modules that match the regex |
666
|
|
|
|
|
|
|
C<m/PATTERN/ixms> |
667
|
|
|
|
|
|
|
|
668
|
|
|
|
|
|
|
There are a number of distributions of additional transformers on CPAN. If |
669
|
|
|
|
|
|
|
L<Perl::ToPerl6> doesn't contain a transformer that you want, someone may have |
670
|
|
|
|
|
|
|
already written it. See L<Perl::ToPerl6/"SEE ALSO"> for a list of some of |
671
|
|
|
|
|
|
|
these distributions. |
672
|
|
|
|
|
|
|
|
673
|
|
|
|
|
|
|
|
674
|
|
|
|
|
|
|
=head1 POLICY THEMES |
675
|
|
|
|
|
|
|
|
676
|
|
|
|
|
|
|
Each Transformer is defined with one or more "themes". Themes can be used to |
677
|
|
|
|
|
|
|
create arbitrary groups of Transformers. They are intended to provide an |
678
|
|
|
|
|
|
|
alternative mechanism for selecting your preferred set of Transformers. For |
679
|
|
|
|
|
|
|
example, you may wish disable a certain set of Transformers when analyzing test |
680
|
|
|
|
|
|
|
programs. Conversely, you may wish to enable only a specific subset of |
681
|
|
|
|
|
|
|
Transformers when analyzing modules. |
682
|
|
|
|
|
|
|
|
683
|
|
|
|
|
|
|
The Transformers that ship with Perl::ToPerl6 are have been divided into the |
684
|
|
|
|
|
|
|
following themes. This is just our attempt to provide some basic logical |
685
|
|
|
|
|
|
|
groupings. You are free to invent new themes that suit your needs. |
686
|
|
|
|
|
|
|
|
687
|
|
|
|
|
|
|
THEME DESCRIPTION |
688
|
|
|
|
|
|
|
------------------------------------------------------------------------ |
689
|
|
|
|
|
|
|
core All transformers that ship with Perl::ToPerl6 |
690
|
|
|
|
|
|
|
pbp Transformers that come directly from "Perl Best Practices" |
691
|
|
|
|
|
|
|
bugs Transformers that that prevent or reveal bugs |
692
|
|
|
|
|
|
|
certrec Transformers that CERT recommends |
693
|
|
|
|
|
|
|
certrule Transformers that CERT considers rules |
694
|
|
|
|
|
|
|
maintenance Transformers that affect the long-term health of the code |
695
|
|
|
|
|
|
|
cosmetic Transformers that only have a superficial effect |
696
|
|
|
|
|
|
|
complexity Transformers that specificaly relate to code complexity |
697
|
|
|
|
|
|
|
security Transformers that relate to security issues |
698
|
|
|
|
|
|
|
tests Transformers that are specific to test programs |
699
|
|
|
|
|
|
|
|
700
|
|
|
|
|
|
|
Say C<"perlmogrify --list"> to get a listing of all available transformers and the |
701
|
|
|
|
|
|
|
themes that are associated with each one. You can also change the theme for |
702
|
|
|
|
|
|
|
any Transformer in your F<.perlmogrifyrc> file. See the L<"CONFIGURATION"> section |
703
|
|
|
|
|
|
|
for more information about that. |
704
|
|
|
|
|
|
|
|
705
|
|
|
|
|
|
|
Using the C<--theme> command-line option, you can create an arbitrarily |
706
|
|
|
|
|
|
|
complex rule that determines which Transformers to apply. Precedence is the same |
707
|
|
|
|
|
|
|
as regular Perl code, and you can use parentheses to enforce precedence as |
708
|
|
|
|
|
|
|
well. Supported operators are: |
709
|
|
|
|
|
|
|
|
710
|
|
|
|
|
|
|
Operator Altertative Example |
711
|
|
|
|
|
|
|
----------------------------------------------------------------- |
712
|
|
|
|
|
|
|
&& and 'pbp && core' |
713
|
|
|
|
|
|
|
|| or 'pbp || (bugs && security)' |
714
|
|
|
|
|
|
|
! not 'pbp && ! (portability || complexity)' |
715
|
|
|
|
|
|
|
|
716
|
|
|
|
|
|
|
Theme names are case-insensitive. If the C<--theme> is set to an empty |
717
|
|
|
|
|
|
|
string, then it evaluates as true all Transformers. |
718
|
|
|
|
|
|
|
|
719
|
|
|
|
|
|
|
|
720
|
|
|
|
|
|
|
=head1 BENDING THE RULES |
721
|
|
|
|
|
|
|
|
722
|
|
|
|
|
|
|
For whatever reason, you may want to mark certain sections of code as |
723
|
|
|
|
|
|
|
"do not transform". You can do that in three basic ways - The '## no mogrify' |
724
|
|
|
|
|
|
|
marker tells the engine to skip transformations on the line it's on. |
725
|
|
|
|
|
|
|
|
726
|
|
|
|
|
|
|
The '## no mogrify' comment on its own line suppresses transformation until |
727
|
|
|
|
|
|
|
a '## use mogrify' comment on its own line, or the end of the file, whichever |
728
|
|
|
|
|
|
|
comes first. |
729
|
|
|
|
|
|
|
|
730
|
|
|
|
|
|
|
require 'LegacyLibaray1.pl'; ## no mogrify |
731
|
|
|
|
|
|
|
require 'LegacyLibrary2.pl'; ## no mogrify |
732
|
|
|
|
|
|
|
|
733
|
|
|
|
|
|
|
for my $element (@list) { |
734
|
|
|
|
|
|
|
|
735
|
|
|
|
|
|
|
## no mogrify |
736
|
|
|
|
|
|
|
|
737
|
|
|
|
|
|
|
$foo = ""; # Don't transform this |
738
|
|
|
|
|
|
|
$barf = bar() if $foo; # or this |
739
|
|
|
|
|
|
|
#Some more evil code... |
740
|
|
|
|
|
|
|
|
741
|
|
|
|
|
|
|
## use mogrify |
742
|
|
|
|
|
|
|
|
743
|
|
|
|
|
|
|
#Some good code... |
744
|
|
|
|
|
|
|
do_something($_); |
745
|
|
|
|
|
|
|
} |
746
|
|
|
|
|
|
|
|
747
|
|
|
|
|
|
|
The C<"## no mogrify"> annotations direct Perl::ToPerl6 to ignore the remaining |
748
|
|
|
|
|
|
|
lines of code until a C<"## use mogrify"> annotation is found. If the C<"## no |
749
|
|
|
|
|
|
|
mogrify"> annotation is on the same line as a code statement, then only that |
750
|
|
|
|
|
|
|
line of code is overlooked. To direct perlmogrify to ignore the C<"## no |
751
|
|
|
|
|
|
|
mogrify"> annotations, use the C<--force> option. |
752
|
|
|
|
|
|
|
|
753
|
|
|
|
|
|
|
A bare C<"## no mogrify"> annotation disables all the active Transformers. |
754
|
|
|
|
|
|
|
If you wish to disable only specific Transformers, add a list of Transformer |
755
|
|
|
|
|
|
|
names as arguments just as you would for the C<"no strict"> or C<"no warnings"> |
756
|
|
|
|
|
|
|
pragma. For example, this would disable the C<Variables::FormatSigils> and |
757
|
|
|
|
|
|
|
C<Variables::FormatHashKeys> transformers until the end of the block or until |
758
|
|
|
|
|
|
|
the next C<"## use mogrify"> annotation (whichever comes first): |
759
|
|
|
|
|
|
|
|
760
|
|
|
|
|
|
|
## no mogrify (Variables::FormatSigils, Variables::FormatHashKeys); |
761
|
|
|
|
|
|
|
|
762
|
|
|
|
|
|
|
# Now exempt from the aforementioned transformers: |
763
|
|
|
|
|
|
|
$foo[0] = $x{foo-bar}; |
764
|
|
|
|
|
|
|
|
765
|
|
|
|
|
|
|
$barf = bar() if $foo; |
766
|
|
|
|
|
|
|
|
767
|
|
|
|
|
|
|
$long_int = 10000000000; |
768
|
|
|
|
|
|
|
|
769
|
|
|
|
|
|
|
Since the Transformer names are matched against the C<"## no mogrify"> arguments |
770
|
|
|
|
|
|
|
as regular expressions, you can abbreviate the Transformer names or disable an |
771
|
|
|
|
|
|
|
entire family of Transformers in one shot like this: |
772
|
|
|
|
|
|
|
|
773
|
|
|
|
|
|
|
## no mogrify (Variables) |
774
|
|
|
|
|
|
|
|
775
|
|
|
|
|
|
|
# Now exempt from Variables::FormatSigils |
776
|
|
|
|
|
|
|
my $camelHumpVar = 'foo'; |
777
|
|
|
|
|
|
|
|
778
|
|
|
|
|
|
|
The argument list must be enclosed in parentheses and must contain one or more |
779
|
|
|
|
|
|
|
comma-separated barewords (i.e. don't use quotes). The C<"## no mogrify"> |
780
|
|
|
|
|
|
|
annotations can be nested, and Transformers named by an inner annotation will be |
781
|
|
|
|
|
|
|
disabled along with those already disabled an outer annotation. |
782
|
|
|
|
|
|
|
|
783
|
|
|
|
|
|
|
Some Transformer like C<Subroutines::ProhibitExcessComplexity> apply to an |
784
|
|
|
|
|
|
|
entire block of code. In those cases, C<"## no mogrify"> must appear on the |
785
|
|
|
|
|
|
|
line where the transformations is reported. For example: |
786
|
|
|
|
|
|
|
|
787
|
|
|
|
|
|
|
sub complicated_function { ## no mogrify (ProhibitExcessComplexity) |
788
|
|
|
|
|
|
|
# Your code here... |
789
|
|
|
|
|
|
|
} |
790
|
|
|
|
|
|
|
|
791
|
|
|
|
|
|
|
Some Transformers like C<File::Script> apply to the entire document, in which |
792
|
|
|
|
|
|
|
case transformations are reported at line 1. But if the file |
793
|
|
|
|
|
|
|
requires a shebang line, it is impossible to put C<"## no mogrify"> on the |
794
|
|
|
|
|
|
|
first line of the file. This is a known limitation and it will be addressed |
795
|
|
|
|
|
|
|
in a future release. As a workaround, you can disable the affected transformers |
796
|
|
|
|
|
|
|
at the command-line or in your F<.perlmogrifyrc> file. But beware that this |
797
|
|
|
|
|
|
|
will affect the analysis of B<all> files. |
798
|
|
|
|
|
|
|
|
799
|
|
|
|
|
|
|
Use this feature wisely. C<"## no mogrify"> should be used in the smallest |
800
|
|
|
|
|
|
|
possible scope, or only on individual lines of code. And you should always be |
801
|
|
|
|
|
|
|
as specific as possible about which transformers you want to disable (i.e. never |
802
|
|
|
|
|
|
|
use a bare C<"## no mogrify">). If Perl::ToPerl6 complains about your code, try |
803
|
|
|
|
|
|
|
and find a compliant solution before resorting to this feature. |
804
|
|
|
|
|
|
|
|
805
|
|
|
|
|
|
|
|
806
|
|
|
|
|
|
|
=head1 EXIT STATUS |
807
|
|
|
|
|
|
|
|
808
|
|
|
|
|
|
|
If C<perlmogrify> has any errors itself, exits with status == 1. If there are |
809
|
|
|
|
|
|
|
no errors, but C<perlmogrify> finds Transformer transformations in your source |
810
|
|
|
|
|
|
|
code, exits with status == 2. If there were no errors and no transformations |
811
|
|
|
|
|
|
|
were found, exits with status == 0. |
812
|
|
|
|
|
|
|
|
813
|
|
|
|
|
|
|
|
814
|
|
|
|
|
|
|
=head1 THE L<Perl::ToPerl6> PHILOSOPHY |
815
|
|
|
|
|
|
|
|
816
|
|
|
|
|
|
|
=over |
817
|
|
|
|
|
|
|
|
818
|
|
|
|
|
|
|
Minimal changes for maximum effect. The transformers themselves are designed |
819
|
|
|
|
|
|
|
without assumptions of the order they run in, even though there's a |
820
|
|
|
|
|
|
|
quick-and-dirty C<run_before()>, C<run_after()> feature implemented so that |
821
|
|
|
|
|
|
|
modules can ask to be run before or after a given module or modules. |
822
|
|
|
|
|
|
|
|
823
|
|
|
|
|
|
|
Transformers should assume in general that they're running on Perl5 code, |
824
|
|
|
|
|
|
|
although you can try out the 'run_before()' feature if you want to assert that |
825
|
|
|
|
|
|
|
a particular transformer has been run before yours. |
826
|
|
|
|
|
|
|
|
827
|
|
|
|
|
|
|
The goal overall is to just help get a Perl codebase to the point where it'll |
828
|
|
|
|
|
|
|
compile under Perl6 with minimal changes. To that end the code is designed |
829
|
|
|
|
|
|
|
to make just the bare minimum of changes, and where possible use Perl5-shaped |
830
|
|
|
|
|
|
|
constructs, such as :P5 modifiers. |
831
|
|
|
|
|
|
|
|
832
|
|
|
|
|
|
|
=back |
833
|
|
|
|
|
|
|
|
834
|
|
|
|
|
|
|
|
835
|
|
|
|
|
|
|
=head1 EXTENDING THE MOGRIFIER |
836
|
|
|
|
|
|
|
|
837
|
|
|
|
|
|
|
The simplest way to go about this is find a module in the list that performs a |
838
|
|
|
|
|
|
|
task like what you want, copy that, and start walking its PPI tree. Each module |
839
|
|
|
|
|
|
|
is presumed to act on one node of the tree at a time, in other words C<$elem> |
840
|
|
|
|
|
|
|
will always be a single element of the type you're modifying. This keeps code |
841
|
|
|
|
|
|
|
simple, and lets the main body collect statistics about what it's modifying. |
842
|
|
|
|
|
|
|
|
843
|
|
|
|
|
|
|
For instance, when running it you'll get an *awful* lot of output about what |
844
|
|
|
|
|
|
|
the modules are doing, complete with line and column numbers of where the |
845
|
|
|
|
|
|
|
modifications are happening. This is more or less so that you can trace back |
846
|
|
|
|
|
|
|
to the point of origin when a module does something you don't expect. |
847
|
|
|
|
|
|
|
|
848
|
|
|
|
|
|
|
Your module receives the original document in C<$doc> and the element to |
849
|
|
|
|
|
|
|
process in C<$elem>. If you make no modifications to the element, just return. |
850
|
|
|
|
|
|
|
Otherwise, calling C<transformation()> tells the main application that your |
851
|
|
|
|
|
|
|
module has changed source. |
852
|
|
|
|
|
|
|
|
853
|
|
|
|
|
|
|
Just to keep the source tree clean and reasonably Perlish, I try to create new |
854
|
|
|
|
|
|
|
tokens for whitespace and such where it's practical. Please also note that |
855
|
|
|
|
|
|
|
at some points I'm forced to violate PPI encapsulation, for instance |
856
|
|
|
|
|
|
|
changing brace styles or a heredoc's marker. |
857
|
|
|
|
|
|
|
|
858
|
|
|
|
|
|
|
Something else to keep in mind as you're creating tests is that the |
859
|
|
|
|
|
|
|
expression you're looking for won't always begin at the start of a |
860
|
|
|
|
|
|
|
L<PPI::Statement>. As a trivial example, C<$x++> may occur at the end of |
861
|
|
|
|
|
|
|
a long statement, such as C<1 if $x++>. So, when creating your test suites |
862
|
|
|
|
|
|
|
be sure that at least a few of your test cases don't begin precisely at |
863
|
|
|
|
|
|
|
the statement boundary. |
864
|
|
|
|
|
|
|
|
865
|
|
|
|
|
|
|
Feel free to send me a pull request on GitHub if you've developed a module |
866
|
|
|
|
|
|
|
and want it integrated. |
867
|
|
|
|
|
|
|
|
868
|
|
|
|
|
|
|
|
869
|
|
|
|
|
|
|
=head1 CONTACTING THE DEVELOPMENT TEAM |
870
|
|
|
|
|
|
|
|
871
|
|
|
|
|
|
|
Currently the development team is just me, [mailto:drforr@pobox.com] or send |
872
|
|
|
|
|
|
|
me a pull request for the appropriate module on GitHUb. I'll keep an eye out |
873
|
|
|
|
|
|
|
for requests and integrate them as they come in, or within a reasonable time |
874
|
|
|
|
|
|
|
frame. |
875
|
|
|
|
|
|
|
|
876
|
|
|
|
|
|
|
You can also catch me on IRC at either [irc://irc.perl.org/#perl] or |
877
|
|
|
|
|
|
|
[irc://irc.freenode.net/#perl], and follow me on Twitter at |
878
|
|
|
|
|
|
|
[https://twitter.com/drforr] |
879
|
|
|
|
|
|
|
|
880
|
|
|
|
|
|
|
=head1 BUGS |
881
|
|
|
|
|
|
|
|
882
|
|
|
|
|
|
|
Feel free to submit bugs via either RT or GitHub. GitHub and personal email |
883
|
|
|
|
|
|
|
gets checked more frequently, or just bounce me a note on IRC if I happen to |
884
|
|
|
|
|
|
|
be active. |
885
|
|
|
|
|
|
|
|
886
|
|
|
|
|
|
|
=head1 CREDITS |
887
|
|
|
|
|
|
|
|
888
|
|
|
|
|
|
|
Jeffrey Thalhammer - For creating the framework I'm shamelessly ripping off, so I don't have to create an entire plugin architecture. |
889
|
|
|
|
|
|
|
|
890
|
|
|
|
|
|
|
Adam Kennedy - For creating L<PPI>, the heart and soul of L<Perl::ToPerl6>. |
891
|
|
|
|
|
|
|
|
892
|
|
|
|
|
|
|
Damian Conway - For writing B<Perl Best Practices>, finally :) |
893
|
|
|
|
|
|
|
|
894
|
|
|
|
|
|
|
Chris Dolan - For contributing the best features and Transformer modules. |
895
|
|
|
|
|
|
|
|
896
|
|
|
|
|
|
|
Andy Lester - Wise sage and master of all-things-testing. |
897
|
|
|
|
|
|
|
|
898
|
|
|
|
|
|
|
Elliot Shank - The self-proclaimed quality freak. |
899
|
|
|
|
|
|
|
|
900
|
|
|
|
|
|
|
Giuseppe Maxia - For all the great ideas and positive encouragement. |
901
|
|
|
|
|
|
|
|
902
|
|
|
|
|
|
|
and Sharon, my wife - For putting up with my all-night code sessions. |
903
|
|
|
|
|
|
|
|
904
|
|
|
|
|
|
|
Thanks also to the Perl Foundation for providing a grant to support Chris |
905
|
|
|
|
|
|
|
Dolan's project to implement twenty PBP transformers. |
906
|
|
|
|
|
|
|
L<http://www.perlfoundation.org/april_1_2007_new_grant_awards> |
907
|
|
|
|
|
|
|
|
908
|
|
|
|
|
|
|
|
909
|
|
|
|
|
|
|
=head1 AUTHOR |
910
|
|
|
|
|
|
|
|
911
|
|
|
|
|
|
|
Jeffrey Goff <drforr@pobox.com> |
912
|
|
|
|
|
|
|
|
913
|
|
|
|
|
|
|
=head1 AUTHOR EMERITUS |
914
|
|
|
|
|
|
|
|
915
|
|
|
|
|
|
|
Jeffrey Ryan Thalhammer <jeff@imaginative-software.com> |
916
|
|
|
|
|
|
|
|
917
|
|
|
|
|
|
|
|
918
|
|
|
|
|
|
|
=head1 COPYRIGHT |
919
|
|
|
|
|
|
|
|
920
|
|
|
|
|
|
|
Copyright (c) 2015 Jeffrey Goff <drforr@pobox.com>. All rights reserved. |
921
|
|
|
|
|
|
|
|
922
|
|
|
|
|
|
|
This program is free software; you can redistribute it and/or modify |
923
|
|
|
|
|
|
|
it under the same terms as Perl itself. The full text of this license |
924
|
|
|
|
|
|
|
can be found in the LICENSE file included with this module. |
925
|
|
|
|
|
|
|
|
926
|
|
|
|
|
|
|
=cut |
927
|
|
|
|
|
|
|
|
928
|
|
|
|
|
|
|
############################################################################## |
929
|
|
|
|
|
|
|
# Local Variables: |
930
|
|
|
|
|
|
|
# mode: cperl |
931
|
|
|
|
|
|
|
# cperl-indent-level: 4 |
932
|
|
|
|
|
|
|
# fill-column: 78 |
933
|
|
|
|
|
|
|
# indent-tabs-mode: nil |
934
|
|
|
|
|
|
|
# c-indentation-style: bsd |
935
|
|
|
|
|
|
|
# End: |
936
|
|
|
|
|
|
|
# ex: set ts=8 sts=4 sw=4 tw=78 ft=perl expandtab shiftround : |