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>
would cause file F<testcfg> to be used instead of the
default F<.perltidyrc>.
+A pathname begins with three dots, e.g. ".../.perltidyrc", indicates that
+the file should be searched for starting in the current directory and
+working upwards. This makes it easier to have multiple projects each with
+their own .perltidyrc in their root directories.
+
=item B<-opt>, B<--show-options>
Write a list of all options used to the F<.LOG> file.
=over 4
+=item B<--notidy>
+
+This flag disables all formatting and causes the input to be copied unchanged
+to the output except for possible changes in line ending characters and any
+pre- and post-filters. This can be useful in conjunction with a hierarchical
+set of F<.perltidyrc> files to avoid unwanted code tidying. See also
+L<Skipping Selected Sections of Code> for a way to avoid tidying specific
+sections of code.
+
=item B<-l=n>, B<--maximum-line-length=n>
The default maximum line length is n=80 characters. Perltidy will try
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
perltidy has trouble determining the input file line ending, it will
revert to the default behavior of using the line ending of the host system.
+=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 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. 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
=head2 Code Indentation Control
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 20090616.
+This man page documents perltidy version 20120701.
=head1 CREDITS
=head1 COPYRIGHT
-Copyright (c) 2000-2008 by Steve Hancock
+Copyright (c) 2000-2010 by Steve Hancock
=head1 LICENSE