my $arg_string = undef;
# give Macs a chance to provide command line parameters
-if ($^O =~ /Mac/) {
- $arg_string =
- MacPerl::Ask( 'Please enter @ARGV (-h for help)',
- defined $ARGV[0] ? "\"$ARGV[0]\"" : "" );
+if ( $^O =~ /Mac/ ) {
+ $arg_string = MacPerl::Ask(
+ 'Please enter @ARGV (-h for help)',
+ defined $ARGV[0] ? "\"$ARGV[0]\"" : ""
+ );
}
-Perl::Tidy::perltidy(argv => $arg_string);
+Perl::Tidy::perltidy( argv => $arg_string );
__END__
This will produce a file F<somefile.pl.tdy> containing the script reformatted
using the default options, which approximate the style suggested in
-perlstyle(1). Perltidy never changes the input file.
+perlstyle(1). The source file F<somefile.pl> is unchanged.
perltidy *.pl
=item B<-b>, B<--backup-and-modify-in-place>
Modify the input file or files in-place and save the original with the
-extension F<.bak>. Any existing F<.bak> file will be deleted. See next item
-for changing the default backup extension.
+extension F<.bak>. Any existing F<.bak> file will be deleted. See next
+item for changing the default backup extension, and for eliminating the
+backup file altogether.
A B<-b> flag will be ignored if input is from standard input, or
if the B<-html> flag is set.
=item B<-bext>=ext, B<--backup-file-extension>=ext
-Change the extension of the backup file to be something other than the
-default F<.bak>. See L<Specifying File Extensions>.
+This parameter serves two purposes: (1) to change the extension of the backup
+file to be something other than the default F<.bak>, and (2) to indicate
+that no backup file should be saved.
+
+To change the default extension to something other than F<.bak> see
+L<Specifying File Extensions>.
+
+A backup file of the source is always written, but you can request that it
+be deleted at the end of processing if there were no errors. This is risky
+unless the source code is being maintained with a source code control
+system.
+
+To indicate that the backup should be deleted include one forward slash,
+B</>, in the extension. If any text remains after the slash is removed
+it will be used to define the backup file extension (which is always
+created and only deleted if there were no errors).
+
+Here are some examples:
+
+ Parameter Extension Backup File Treatment
+ <-bext=bak> F<.bak> Keep (same as the default behavior)
+ <-bext='/'> F<.bak> Delete if no errors
+ <-bext='/backup'> F<.backup> Delete if no errors
+ <-bext='original/'> F<.original> Delete if no errors
=item B<-w>, B<--warning-output>
If perl reports errors in the input file, they will not be reported in
the error output unless the B<--warning-output> flag is given.
-The default is B<not> to do this type of syntax checking (although
+The default is B<NOT> to do this type of syntax checking (although
perltidy will still do as much self-checking as possible). The reason
is that it causes all code in BEGIN blocks to be executed, for all
modules being used, and this opens the door to security issues and
=item B<-it=n>, B<--iterations=n>
This flag causes perltidy to do B<n> complete iterations. The reason for this
-flag is that code beautification is a somewhat iterative process and in some
+flag is that code beautification is an iterative process and in some
cases the output from perltidy can be different if it is applied a second time.
For most purposes the default of B<n=1> should be satisfactory. However B<n=2>
can be useful when a major style change is being made, or when code is being
-beautified on check-in to a source code control system. The run time will be
-approximately proportional to B<n>, and it should seldom be necessary to use a
-value greater than B<n=2>. This flag has no effect when perltidy is used to generate html.
+beautified on check-in to a source code control system. It has been found to
+be extremely rare for the output to change after 2 iterations. If a value
+B<n> is greater than 2 is input then a convergence test will be used to stop
+the iterations as soon as possible, almost always after 2 iterations.
+
+This flag has no effect when perltidy is used to generate html.
=back
By default, perltidy examines the input file and tries to determine the
starting indentation level. While it is often zero, it may not be
-zero for a code snippet being sent from an editing session. If the
-default method does not work correctly, or you want to change the
+zero for a code snippet being sent from an editing session.
+
+To guess the starting indentation level perltidy simply assumes that
+indentation scheme used to create the code snippet is the same as is being used
+for the current perltidy process. This is the only sensible guess that can be
+made. It should be correct if this is true, but otherwise it probably won't.
+For example, if the input script was written with -i=2 and the current peltidy
+flags have -i=4, the wrong initial indentation will be guessed for a code
+snippet which has non-zero initial indentation. Likewise, if an entabbing
+scheme is used in the input script and not in the current process then the
+guessed indentation will be wrong.
+
+If the default method does not work correctly, or you want to change the
starting level, use B<-sil=n>, to force the starting level to be n.
=item List indentation using B<-lp>, B<--line-up-parentheses>
my ( $a, $b, $c ) = @_; # default
my( $a, $b, $c ) = @_; # -nsak="my local our"
+The abbreviation B<-nsak='*'> is equivalent to including all of the
+keywords in the above list.
+
+When both B<-nsak=s> and B<-sak=s> commands are included, the B<-nsak=s>
+command is executed first. For example, to have space after only the
+keywords (my, local, our) you could use B<-nsak="*" -sak="my local our">.
+
To put a space after all keywords, see the next item.
=item Space between all keywords and opening parens
then it will remain broken. To prevent this, and thereby
form longer lines, use B<-nbot>.
+=item B<-boa>, B<--break-at-old-attribute-breakpoints>
+
+By default, if an attribute list is broken at a C<:> in the source file, then
+it will remain broken. For example, given the following code, the line breaks
+at the ':'s will be retained:
+
+ my @field
+ : field
+ : Default(1)
+ : Get('Name' => 'foo') : Set('Name');
+
+If the attributes are on a single line in the source code then they will remain
+on a single line if possible.
+
+To prevent this, and thereby always form longer lines, use B<-nboa>.
+
=item B<-iob>, B<--ignore-old-breakpoints>
Use this flag to tell perltidy to ignore existing line breaks to the
default. Use B<-nbbc> or B<--noblanks-before-comments> to prevent
such blank lines from being introduced.
+=item B<-blbs=n>, B<--blank-lines-before-subs=n>
+
+The parameter B<-blbs=n> requests that least B<n> blank lines precede a sub
+definition which does not follow a comment and which is more than one-line
+long. The default is <-blbs=1>. B<BEGIN> and B<END> blocks are included.
+
+The requested number of blanks statement will be inserted regardless of of the
+value of B<--maximum-consecutive-blank-lines=n> (B<-mbl=n>) with the exception
+that if B<-mbl=0> then no blanks will be output.
+
+This parameter interacts with the value B<k> of the parameter B<--maximum-consecutive-blank-lines=k> (B<-mbl=k>) as follows:
+
+1. If B<-mbl=0> then no blanks will be output. This allows all blanks to be suppressed with a single parameter. Otherwise,
+
+2. If the number of old blank lines in the script is less than B<n> then
+additional blanks will be inserted to make the total B<n> regardless of the
+value of B<-mbl=k>.
+
+3. If the number of old blank lines in the script equals or exceeds B<n> then
+this parameter has no effect, however the total will not exceed
+value specified on the B<-mbl=k> flag.
+
+
+=item B<-blbp=n>, B<--blank-lines-before-packages=n>
+
+The parameter B<-blbp=n> requests that least B<n> blank lines precede a package
+which does not follow a comment. The default is <-blbp=1>.
+
+This parameter interacts with the value B<k> of the parameter
+B<--maximum-consecutive-blank-lines=k> (B<-mbl=k>) in the same way as described
+for the previous item B<-blbs=n>.
+
+
=item B<-bbs>, B<--blanks-before-subs>
-A blank line will be introduced before a B<sub> definition, unless it is a
-one-liner or preceded by a comment. A blank line will also be introduced
-before a B<package> statement and a B<BEGIN> and B<END> block. This is the
-default. The intention is to help display the structure of a program by
-setting off certain key sections of code. This is negated with B<-nbbs> or
-B<--noblanks-before-subs>.
+For compatability with previous versions, B<-bbs> or B<--blanks-before-subs>
+is equivalent to F<-blbp=1> and F<-blbs=1>.
+
+Likewise, B<-nbbs> or B<--noblanks-before-subs>
+is equivalent to F<-blbp=0> and F<-blbs=0>.
=item B<-bbb>, B<--blanks-before-blocks>
=item B<-mbl=n> B<--maximum-consecutive-blank-lines=n>
-This parameter specifies the maximum number of consecutive
-blank lines which will be output within code sections of a
-script. The default is n=1. If the input file has more
-than n consecutive blank lines, the number will be reduced
-to n. If B<n=0> then no blank lines will be output (unless
-all old blank lines are retained with the B<-kbl=2> flag of
-the next section).
+This parameter specifies the maximum number of consecutive blank lines which
+will be output within code sections of a script. The default is n=1. If the
+input file has more than n consecutive blank lines, the number will be reduced
+to n except as noted above for the B<-blbp> and B<-blbs> parameters. If B<n=0>
+then no blank lines will be output (unless all old blank lines are retained
+with the B<-kbl=2> flag of the next section).
This flag obviously does not apply to pod sections,
here-documents, and quotes.
The configuation file is free format, and simply a list of parameters, just as
they would be entered on a command line. Any number of lines may be used, with
any number of parameters per line, although it may be easiest to read with one
-parameter per line. Blank lines are ignored, and text after a '#' is ignored
-to the end of a line.
+parameter per line. Comment text begins with a #, and there must
+also be a space before the # for side comments. It is a good idea to
+put complex parameters in either single or double quotes.
Here is an example of a F<.perltidyrc> file:
=head1 VERSION
-This man page documents perltidy version 20101217.
+This man page documents perltidy version 20120701.
=head1 CREDITS
projects / perltidy.git / blobdiff