=head1 Perltidy Style Key
-Use this document to quickly and methodically find a set of perltidy
-parameters to approximate your style. Just read each question and
-select the best answer. Enter your parameters in a file named
-F<.perltidyrc> (examples are listed at the end). Then move it to one of
-the places where perltidy will find it. You can run perltidy with the
-parameter B<-dpro> to see where these places are for your system.
+When perltidy was first developed, the main parameter choices were the number
+of indentation spaces and if the user liked cuddled else's. As the number of
+users has grown so has the number of parameters. Now there are so many that it
+can be difficult for a new user to find a good initial set. This document is
+one attempt to help with this problem, and some other suggestions are given at
+the end.
+
+Use this document to methodically find a starting set of perltidy parameters to
+approximate your style. We will be working on just one aspect of formatting at
+a time. Just read each question and select the best answer. Enter your
+parameters in a file named F<.perltidyrc> (examples are listed at the end).
+Then move it to one of the places where perltidy will find it. You can run
+perltidy with the parameter B<-dpro> to see where these places are for your
+system.
Before you begin, experiment using just C<perltidy filename.pl> on some
of your files. From the results (which you will find in files with a
. substr( $char_list, $place_2, 1 );
}
-The statement is too long for the line length (80 characters by
-default), so it has been broken into 4 lines. The second and later
-lines have some extra "continuation indentation" to help make the start
-of the statement easy to find. The default number of extra spaces is 2.
-If you prefer a number n different from 2, you may specify this with
-B<-ci=n>. It is best to keep this less than the value of the primary
-indentation.
+The statement is too long for the line length (80 characters by default), so it
+has been broken into 4 lines. The second and later lines have some extra
+"continuation indentation" to help make the start of the statement easy to
+find. The default number of extra spaces is 2. If you prefer a number n
+different from 2, you may specify this with B<-ci=n>. It is probably best if
+it does not exceed the value of the primary indentation.
=head2 Tabs
=head2 Opening Block Brace Right or Left?
-Decide which of the following opening brace styles you prefer:
+Opening and closing curly braces, parentheses, and square brackets are divided
+into two separate categories and controlled separately in most cases. The two
+categories are (1) code block curly braces, which contain perl code, and (2)
+everything else. Basically, a code block brace is one which could contain
+semicolon-terminated lines of perl code. We will first work on the scheme for
+code block curly braces.
+
+Decide which of the following opening brace styles you prefer for most blocks
+of code (with the possible exception of a B<sub block brace> which will
+be covered later):
If you like opening braces on the right, like this, go to
-L<Braces Right>.
+L<Opening Braces Right>.
if ( $flag eq "h" ) {
$headers = 0;
}
If you like opening braces on the left, like this, go to
-L<Braces Left>.
+L<Opening Braces Left>.
if ( $flag eq "h" )
{
$headers = 0;
}
-=head2 Braces Right
+=head2 Opening Braces Right
In a multi-line B<if> test expression, the default is to place
the opening brace on the left, like this:
}
If yes, you should use B<-ce>.
+Now skip ahead to L<Opening Sub Braces>.
-Now skip ahead to L<Indentation Style for Other Containers>.
-
-=head2 Braces Left
+=head2 Opening Braces Left
Use B<-bl> if you prefer this style:
The number of spaces of extra indentation will be the value specified
for continuation indentation with the B<-ci=n> parameter (2 by default).
+=head2 Opening Sub Braces
+
+By default, the opening brace of a sub block will be treated
+the same as other code blocks. If this is okay, skip ahead
+to L<Block Brace Vertical Tightness>.
+
+If you prefer an opening sub brace to be on a new line,
+like this:
+
+ sub message
+ {
+ # -sbl
+ }
+
+use B<-sbl>. If you prefer the sub brace on the right like this
+
+ sub message {
+
+ # -nsbl
+ }
+
+use B<-nsbl>.
+
+If you wish to give this opening sub brace some indentation you can do
+that with the parameters B<-bli> and B<-blil> which are described in the
+manual.
+
=head2 Block Brace Vertical Tightness
-The default is to leave the opening brace on a line by itself, like this (shown
-for B<-bli>, but also true to B<-bl>):
+If you chose to put opening block braces of all types to the right, skip
+ahead to L<Closing Block Brace Indentation>.
+
+If you chose to put braces of any type on the left, the default is to leave the
+opening brace on a line by itself, like this (shown for B<-bli>, but also true
+for B<-bl>):
if ( $flag eq "h" )
{
}
If you do not prefer this more compressed form, go to
-L<Indentation Style for Other Containers>.
+L<Opening Sub Braces>.
Otherwise use parameter B<-bbvt=n>, where n=1 or n=2. To decide,
look at this snippet:
# -bli -bbvt=2
sub _directives
- { {
+ { {
'ENDIF' => \&_endif,
- 'IF' => \&_if,
+ 'IF' => \&_if,
};
- }
+ }
The difference is that B<-bbvt=1> breaks after an opening brace if
-the next line is unbalanced, whereas B<-bbvt=2> never breaks.
+the next line is unbalanced, whereas B<-bbvt=2> never breaks.
+
+If you were expecting the 'ENDIF' word to move up vertically here, note that
+the second opening brace in the above example is not a code block brace (it is
+a hash brace), so the B<-bbvt> does not apply to it (another parameter will).
+
+=head2 Closing Block Brace Indentation
+
+The default is to place closing braces at the same indentation as the
+opening keyword or brace of that code block, as shown here:
+
+ if ($task) {
+ yyy();
+ } # default
+
+If you chose the B<-bli> style, however, the default closing braces will be
+indented one continuation indentation like the opening brace:
+
+ if ($task)
+ {
+ yyy();
+ } # -bli
+
+If you prefer to give closing block braces one full level of
+indentation, independently of how the opening brace is treated,
+for example like this:
+
+ if ($task) {
+ yyy();
+ } # -icb
+
+use B<-icb>.
+
+This completes the definition of the placement of code block braces.
=head2 Indentation Style for Other Containers
-You have a choice of two indentation schemes for non-block containers.
-The default is to use a fixed number of spaces per indentation level (the
-same number of spaces used for code blocks). Here is an example of the
-default:
+You have a choice of two basic indentation schemes for non-block containers.
+The default is to use a fixed number of spaces per indentation level (the same
+number of spaces used for code blocks, which is 4 by default). Here is an
+example of the default:
$dbh = DBI->connect(
undef, undef, undef,
}
);
+In this default indentation scheme, a simple formula is used to find the
+indentation of every line. Notice how the first 'undef' is indented 4
+spaces (one level) to the right, and how 'PrintError' is indented 4 more
+speces (one more level) to the right.
+
The alternate is to let the location of the opening paren (or square
bracket, or curly brace) define the indentation, like this:
}
);
-If you prefer the first (default) scheme, skip ahead to
-L<Closing Token Placement>.
+The first scheme is completely robust. The second scheme often looks a little
+nicer, but be aware that deeply nested structures it can be spoiled if the line
+length limit is exceeded. Also, if there are comments or blank lines within a
+complex structure perltidy will temporarily fall back on the default
+indentation scheme. You may want to try both on large sections of code to see
+which works best.
+
+If you prefer the first (default) scheme, no parameter is needed.
-If you prefer the latter scheme, use B<-lp> and continue to the next
-section.
+If you prefer the latter scheme, use B<-lp>.
=head2 Opening Vertical Tightness
+The information in this section applies mainly to the B<-lp>
+style but it also applies in some cases to the default style.
+It will be illustrated for the B<-lp> indentation style.
+
The default B<-lp> indentation style ends a line at the
opening tokens, like this:
}
);
+The difference is that the lines have been compressed vertically without
+any changes to the indentation. This can almost always be done with the
+B<-lp> indentation style, but only in limited cases for the default
+indentation style.
+
If you prefer the default, skip ahead to L<Closing Token Placement>.
Otherwise, use B<-vt=n>, where B<n> should be either 1 or 2. To help
The B<-vt=2> style does not limit itself to a single indentation step
per line.
+Note that in the above example the function 'do_sumething_about_it'
+started on a new line. This is because it follows an opening code
+block brace and is governed by the flag previously set in
+L<Block Brace Vertical Tightness>.
+
=head2 Closing Token Placement
You have several options for dealing with the terminal closing tokens of
'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'
);
-A third alternative, B<-cti=2>, indents a line with leading closing
+Another alternative, B<-cti=3>, indents a line with leading closing
paren one full indentation level:
- # perltidy -lp -cti=2
+ # perltidy -lp -cti=3
@month_of_year = (
'Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun',
'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'
'Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun',
'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec' );
-Use B<-vtc=n> if you prefer to do this, where n is either 1 or 2. To
-determine n, we have to look at something more complex. Observe the
+Perltidy will automatically do this to save space for very short lists but not
+for longer lists.
+
+Use B<-vtc=n> if you prefer to usually do this, where B<n> is either 1 or 2. To
+determine B<n>, we have to look at something more complex. Observe the
behavior of the closing tokens in the following snippet:
Here is B<-lp -vtc=1>:
$self->read_value(
$lookup->{'VFMT2'},
$loc, $lookup, $fh ) ];
-
Choose the one that you prefer. The difference is that B<-vtc=1> leaves
closing tokens at the start of a line within a list, which can assist in
you may also want to specify a value of B<-cti=n> (previous section) to
handle cases where a line begins with a closing paren.
+=head2 Stack Opening Tokens
+
+In the following snippet the opening hash brace has been placed
+alone on a new line.
+
+ $opt_c = Text::CSV_XS->new(
+ {
+ binary => 1,
+ sep_char => $opt_c,
+ always_quote => 1,
+ }
+ );
+
+If you prefer to avoid isolated opening opening tokens by
+"stacking" them together with other opening tokens like this:
+
+ $opt_c = Text::CSV_XS->new( {
+ binary => 1,
+ sep_char => $opt_c,
+ always_quote => 1,
+ }
+ );
+
+use B<-sot>.
+
+=head2 Stack Closing Tokens
+
+Likewise, in the same snippet the default formatting leaves
+the closing paren on a line by itself here:
+
+ $opt_c = Text::CSV_XS->new(
+ {
+ binary => 1,
+ sep_char => $opt_c,
+ always_quote => 1,
+ }
+ );
+
+If you would like to avoid leaving isolated closing tokens by
+stacking them with other closing tokens, like this:
+
+ $opt_c = Text::CSV_XS->new(
+ {
+ binary => 1,
+ sep_char => $opt_c,
+ always_quote => 1,
+ } );
+
+use B<-sct>.
+
+The B<-sct> flag is somewhat similar to the B<-vtc> flags, and in some cases it
+can give a similar result. The difference is that the B<-vtc> flags try to
+avoid lines with leading opening tokens by "hiding" them at the end of a
+previous line, whereas the B<-sct> flag merely tries to reduce the number of
+lines with isolated closing tokens by stacking multiple closing tokens
+together, but it does not try to hide them.
+
+The manual shows how all of these vertical tightness controls may be applied
+independently to each type of non-block opening and opening token.
+
=head2 Define Horizontal Tightness
Horizontal tightness parameters define how much space is included
%bf = map { $_ => -M $_ } grep {/\.deb$/} dirents '.'; # -bbt=1
%bf = map {$_ => -M $_} grep {/\.deb$/} dirents '.'; # -bbt=2
+=head2 Spaces between function names and opening parens
+
+The default is not to place a space after a function call:
+
+ myfunc( $a, $b, $c ); # default
+
+If you prefer a space:
+
+ myfunc ( $a, $b, $c ); # -sfp
+
+use B<-sfp>.
+
+=head2 Spaces between Perl keywords and parens
+
+The default is to place a space between only these keywords
+and an opening paren:
+
+ my local our and or eq ne if else elsif until unless
+ while for foreach return switch case given when
+
+but no others. For example, the default is:
+
+ $aa = pop(@bb);
+
+If you want a space between all Perl keywords and an opening paren,
+
+ $aa = pop (@bb);
+
+use B<-skp>. For detailed control of individual keywords, see the manual.
+
=head2 Statement Termination Semicolon Spaces
The default is not to put a space before a statement termination
If you prefer a space, like this:
- $i = 1 ;
+ $i = 1 ;
enter B<-sts>.
characters before the leading C<#> character in the input file, use
B<-isbc>.
+The manual shows many other options for controlling comments.
+
=head2 Outdenting Long Quotes
Long quoted strings may exceed the specified line length limit. The
use B<-nolq>.
+=head2 Many Other Parameters
+
+This document has only covered the most popular parameters. The manual
+contains many more and should be consulted if you did not find what you need
+here.
+
=head2 Example F<.perltidyrc> files
Now gather together all of the parameters you prefer and enter them
=head2 Additional Information
This document has covered the main parameters. Many more parameters are
-available for special purposes and for fine-tuning a style. For
-complete information see the perltidy manual
+available for special purposes and for fine-tuning a style. For complete
+information see the perltidy manual
http://perltidy.sourceforge.net/perltidy.html
For an introduction to using perltidy, see the tutorial
projects / perltidy.git / blobdiff