File Coverage

blib/script/perlmogrify
Criterion Covered Total %
statement 11 11 100.0
branch n/a
condition n/a
subroutine 4 4 100.0
pod n/a
total 15 15 100.0


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 :