1 =head1 Perltidy Style Key
3 When perltidy was first developed, the main parameter choices were the number
4 of indentation spaces and if the user liked cuddled else's. As the number of
5 users has grown so has the number of parameters. Now there are so many that it
6 can be difficult for a new user to find a good initial set. This document is
7 one attempt to help with this problem, and some other suggestions are given at
10 Use this document to methodically find a starting set of perltidy parameters to
11 approximate your style. We will be working on just one aspect of formatting at
12 a time. Just read each question and select the best answer. Enter your
13 parameters in a file named F<.perltidyrc> (examples are listed at the end).
14 Then move it to one of the places where perltidy will find it. You can run
15 perltidy with the parameter B<-dpro> to see where these places are for your
18 =head2 Before You Start
20 Before you begin, experiment using just C<perltidy filename.pl> on some
21 of your files. From the results (which you will find in files with a
22 F<.tdy> extension), you will get a sense of what formatting changes, if
23 any, you'd like to make. If the default formatting is acceptable, you
24 do not need a F<.perltidyrc> file.
28 Do you almost always want to run perltidy as a standard filter on just
29 one input file? If yes, use B<-st> and B<-se>.
31 =head2 Line Length Setting
33 Perltidy will set line breaks to prevent lines from exceeding the
36 Do you want the maximum line length to be 80 columns? If no, use
37 B<-l=n>, where B<n> is the number of columns you prefer.
39 =head2 Indentation in Code Blocks
41 In the block below, the variable C<$anchor> is one indentation level deep
42 and is indented by 4 spaces as shown here:
48 If you want to change this to be a different number B<n> of spaces
49 per indentation level, use B<-i=n>.
51 =head2 Continuation Indentation
53 Look at the statement beginning with C<$anchor>:
57 substr( $header, 0, 6 )
58 . substr( $char_list, $place_1, 1 )
59 . substr( $char_list, $place_2, 1 );
62 The statement is too long for the line length (80 characters by default), so it
63 has been broken into 4 lines. The second and later lines have some extra
64 "continuation indentation" to help make the start of the statement easy to
65 find. The default number of extra spaces is 2. If you prefer a number n
66 different from 2, you may specify this with B<-ci=n>. It is probably best if
67 it does not exceed the value of the primary indentation.
71 The default, and recommendation, is to represent leading whitespace
72 with actual space characters. However, if you prefer to entab
73 leading whitespace with one tab character for each B<n> spaces,
74 use B<-et=n>. Typically, B<n> would be 8.
76 =head2 Opening Block Brace Right or Left?
78 Opening and closing curly braces, parentheses, and square brackets are divided
79 into two separate categories and controlled separately in most cases. The two
80 categories are (1) code block curly braces, which contain perl code, and (2)
81 everything else. Basically, a code block brace is one which could contain
82 semicolon-terminated lines of perl code. We will first work on the scheme for
83 code block curly braces.
85 Decide which of the following opening brace styles you prefer for most blocks
86 of code (with the possible exception of a B<sub block brace> which will
89 If you like opening braces on the right, like this, go to
90 L<Opening Braces Right>.
96 If you like opening braces on the left, like this, go to
97 L<Opening Braces Left>.
104 =head2 Opening Braces Right
106 In a multi-line B<if> test expression, the default is to place
107 the opening brace on the left, like this:
109 if ( $bigwasteofspace1 && $bigwasteofspace2
110 || $bigwasteofspace3 && $bigwasteofspace4 )
115 This helps to visually separate the block contents from the test
118 An alternative is to keep the brace on the right even for
119 multiple-line test expressions, like this:
121 if ( $bigwasteofspace1 && $bigwasteofspace2
122 || $bigwasteofspace3 && $bigwasteofspace4 ) {
126 If you prefer this alternative, use B<-bar>.
130 Do you prefer this B<Cuddled Else> style
132 if ( $flag eq "h" ) {
134 } elsif ( $flag eq "f" ) {
137 print "invalid option: " . substr( $arg, $i, 1 ) . "\n";
141 instead of this default style?
143 if ( $flag eq "h" ) {
146 elsif ( $flag eq "f" ) {
150 print "invalid option: " . substr( $arg, $i, 1 ) . "\n";
154 If yes, you should use B<-ce>.
155 Now skip ahead to L<Opening Sub Braces>.
157 =head2 Opening Braces Left
159 Use B<-bl> if you prefer this style:
166 Use B<-bli> if you prefer this indented-brace style:
173 The number of spaces of extra indentation will be the value specified
174 for continuation indentation with the B<-ci=n> parameter (2 by default).
176 =head2 Opening Sub Braces
178 By default, the opening brace of a sub block will be treated
179 the same as other code blocks. If this is okay, skip ahead
180 to L<Block Brace Vertical Tightness>.
182 If you prefer an opening sub brace to be on a new line,
190 use B<-sbl>. If you prefer the sub brace on the right like this
199 If you wish to give this opening sub brace some indentation you can do
200 that with the parameters B<-bli> and B<-blil> which are described in the
203 =head2 Block Brace Vertical Tightness
205 If you chose to put opening block braces of all types to the right, skip
206 ahead to L<Closing Block Brace Indentation>.
208 If you chose to put braces of any type on the left, the default is to leave the
209 opening brace on a line by itself, like this (shown for B<-bli>, but also true
217 But you may also use this more compressed style if you wish:
223 If you do not prefer this more compressed form, go to
224 L<Opening Sub Braces>.
226 Otherwise use parameter B<-bbvt=n>, where n=1 or n=2. To decide,
227 look at this snippet:
246 The difference is that B<-bbvt=1> breaks after an opening brace if
247 the next line is unbalanced, whereas B<-bbvt=2> never breaks.
249 If you were expecting the 'ENDIF' word to move up vertically here, note that
250 the second opening brace in the above example is not a code block brace (it is
251 a hash brace), so the B<-bbvt> does not apply to it (another parameter will).
253 =head2 Closing Block Brace Indentation
255 The default is to place closing braces at the same indentation as the
256 opening keyword or brace of that code block, as shown here:
262 If you chose the B<-bli> style, however, the default closing braces will be
263 indented one continuation indentation like the opening brace:
270 If you prefer to give closing block braces one full level of
271 indentation, independently of how the opening brace is treated,
272 for example like this:
280 This completes the definition of the placement of code block braces.
282 =head2 Indentation Style for Other Containers
284 You have a choice of two basic indentation schemes for non-block containers.
285 The default is to use a fixed number of spaces per indentation level (the same
286 number of spaces used for code blocks, which is 4 by default). Here is an
287 example of the default:
297 In this default indentation scheme, a simple formula is used to find the
298 indentation of every line. Notice how the first 'undef' is indented 4
299 spaces (one level) to the right, and how 'PrintError' is indented 4 more
300 speces (one more level) to the right.
302 The alternate is to let the location of the opening paren (or square
303 bracket, or curly brace) define the indentation, like this:
313 The first scheme is completely robust. The second scheme often looks a little
314 nicer, but be aware that deeply nested structures it can be spoiled if the line
315 length limit is exceeded. Also, if there are comments or blank lines within a
316 complex structure perltidy will temporarily fall back on the default
317 indentation scheme. You may want to try both on large sections of code to see
320 If you prefer the first (default) scheme, no parameter is needed.
322 If you prefer the latter scheme, use B<-lp>.
324 =head2 Opening Vertical Tightness
326 The information in this section applies mainly to the B<-lp>
327 style but it also applies in some cases to the default style.
328 It will be illustrated for the B<-lp> indentation style.
330 The default B<-lp> indentation style ends a line at the
331 opening tokens, like this:
341 Here is a tighter alternative, which does not end a line
342 with the opening tokens:
344 $dbh = DBI->connect( undef, undef, undef,
350 The difference is that the lines have been compressed vertically without
351 any changes to the indentation. This can almost always be done with the
352 B<-lp> indentation style, but only in limited cases for the default
355 If you prefer the default, skip ahead to L<Closing Token Placement>.
357 Otherwise, use B<-vt=n>, where B<n> should be either 1 or 2. To help
358 decide, observe the first three opening parens in the following snippet
359 and choose the value of n you prefer. Here it is with B<-lp -vt=1>:
363 start_slip( $DEVICE, $PHONE, $ACCOUNT, $PASSWORD,
364 $LOCAL, $REMOTE, $NETMASK, $MTU
367 && $continuation_flag
370 do_something_about_it();
373 And here it is again formatted with B<-lp -vt=2>:
375 if ( !defined( start_slip( $DEVICE, $PHONE, $ACCOUNT, $PASSWORD,
376 $LOCAL, $REMOTE, $NETMASK, $MTU
379 && $continuation_flag
382 do_something_about_it();
385 The B<-vt=1> style tries to display the structure by preventing more
386 than one step in indentation per line. In this example, the first two
387 opening parens were not followed by balanced lines, so B<-vt=1> broke
390 The B<-vt=2> style does not limit itself to a single indentation step
393 Note that in the above example the function 'do_sumething_about_it'
394 started on a new line. This is because it follows an opening code
395 block brace and is governed by the flag previously set in
396 L<Block Brace Vertical Tightness>.
398 =head2 Closing Token Placement
400 You have several options for dealing with the terminal closing tokens of
401 non-blocks. In the following examples, a closing parenthesis is shown, but
402 these parameters apply to closing square brackets and non-block curly braces as
405 The default behavior for parenthesized relatively large lists is to place the
406 closing paren on a separate new line. The flag B<-cti=n> controls the amount
407 of indentation of such a closing paren.
409 The default, B<-cti=0>, for a line beginning with a closing paren, is to use
410 the indentation defined by the next (lower) indentation level. This works
411 well for the default indentation scheme:
415 'Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun',
416 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'
419 but it may not look very good with the B<-lp> indentation scheme:
423 'Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun',
424 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'
427 An alternative which works well with B<-lp> indentation is B<-cti=1>,
428 which aligns the closing paren vertically with its
429 opening paren, if possible:
431 # perltidy -lp -cti=1
433 'Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun',
434 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'
437 Another alternative, B<-cti=3>, indents a line with leading closing
438 paren one full indentation level:
440 # perltidy -lp -cti=3
442 'Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun',
443 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'
446 If you prefer the closing paren on a separate line like this,
447 note the value of B<-cti=n> that you prefer and skip ahead to
448 L<Define Horizontal Tightness>.
450 Finally, the question of paren indentation can be avoided by placing it
451 at the end of the previous line, like this:
454 'Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun',
455 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec' );
457 Perltidy will automatically do this to save space for very short lists but not
460 Use B<-vtc=n> if you prefer to usually do this, where B<n> is either 1 or 2. To
461 determine B<n>, we have to look at something more complex. Observe the
462 behavior of the closing tokens in the following snippet:
464 Here is B<-lp -vtc=1>:
466 $srec->{'ACTION'} = [
476 Here is B<-lp -vtc=2>:
478 $srec->{'ACTION'} = [
481 $loc, $lookup, $fh ),
484 $loc, $lookup, $fh ) ];
486 Choose the one that you prefer. The difference is that B<-vtc=1> leaves
487 closing tokens at the start of a line within a list, which can assist in
488 keeping hierarchical lists readable. The B<-vtc=2> style always tries
489 to move closing tokens to the end of a line.
491 If you choose B<-vtc=1>,
492 you may also want to specify a value of B<-cti=n> (previous section) to
493 handle cases where a line begins with a closing paren.
495 =head2 Stack Opening Tokens
497 In the following snippet the opening hash brace has been placed
500 $opt_c = Text::CSV_XS->new(
508 If you prefer to avoid isolated opening tokens by
509 "stacking" them together with other opening tokens like this:
511 $opt_c = Text::CSV_XS->new( {
520 =head2 Stack Closing Tokens
522 Likewise, in the same snippet the default formatting leaves
523 the closing paren on a line by itself here:
525 $opt_c = Text::CSV_XS->new(
533 If you would like to avoid leaving isolated closing tokens by
534 stacking them with other closing tokens, like this:
536 $opt_c = Text::CSV_XS->new(
545 The B<-sct> flag is somewhat similar to the B<-vtc> flags, and in some cases it
546 can give a similar result. The difference is that the B<-vtc> flags try to
547 avoid lines with leading opening tokens by "hiding" them at the end of a
548 previous line, whereas the B<-sct> flag merely tries to reduce the number of
549 lines with isolated closing tokens by stacking multiple closing tokens
550 together, but it does not try to hide them.
552 The manual shows how all of these vertical tightness controls may be applied
553 independently to each type of non-block opening and opening token.
555 =head2 Define Horizontal Tightness
557 Horizontal tightness parameters define how much space is included
558 within a set of container tokens.
560 For parentheses, decide which of the following values of B<-pt=n>
563 if ( ( my $len_tab = length( $tabstr ) ) > 0 ) { # -pt=0
564 if ( ( my $len_tab = length($tabstr) ) > 0 ) { # -pt=1 (default)
565 if ((my $len_tab = length($tabstr)) > 0) { # -pt=2
567 For n=0, space is always used, and for n=2, space is never used. For
568 the default n=1, space is used if the parentheses contain more than
571 For square brackets, decide which of the following values of B<-sbt=n>
574 $width = $col[ $j + $k ] - $col[ $j ]; # -sbt=0
575 $width = $col[ $j + $k ] - $col[$j]; # -sbt=1 (default)
576 $width = $col[$j + $k] - $col[$j]; # -sbt=2
578 For curly braces, decide which of the following values of B<-bt=n>
581 $obj->{ $parsed_sql->{ 'table' }[0] }; # -bt=0
582 $obj->{ $parsed_sql->{'table'}[0] }; # -bt=1 (default)
583 $obj->{$parsed_sql->{'table'}[0]}; # -bt=2
585 For code block curly braces, decide which of the following values of
586 B<-bbt=n> you prefer:
588 %bf = map { $_ => -M $_ } grep { /\.deb$/ } dirents '.'; # -bbt=0 (default)
589 %bf = map { $_ => -M $_ } grep {/\.deb$/} dirents '.'; # -bbt=1
590 %bf = map {$_ => -M $_} grep {/\.deb$/} dirents '.'; # -bbt=2
592 =head2 Spaces between function names and opening parens
594 The default is not to place a space after a function call:
596 myfunc( $a, $b, $c ); # default
598 If you prefer a space:
600 myfunc ( $a, $b, $c ); # -sfp
604 =head2 Spaces between Perl keywords and parens
606 The default is to place a space between only these keywords
607 and an opening paren:
609 my local our and or eq ne if else elsif until unless
610 while for foreach return switch case given when
612 but no others. For example, the default is:
616 If you want a space between all Perl keywords and an opening paren,
620 use B<-skp>. For detailed control of individual keywords, see the manual.
622 =head2 Statement Termination Semicolon Spaces
624 The default is not to put a space before a statement termination
625 semicolon, like this:
629 If you prefer a space, like this:
635 =head2 For Loop Semicolon Spaces
637 The default is to place a space before a semicolon in a for statement,
640 for ( @a = @$ap, $u = shift @a ; @a ; $u = $v ) { # -sfs (default)
642 If you prefer no such space, like this:
644 for ( @a = @$ap, $u = shift @a; @a; $u = $v ) { # -nsfs
648 =head2 Block Comment Indentation
650 Block comments are comments which occupy a full line, as opposed to side
651 comments. The default is to indent block comments with the same
652 indentation as the code block that contains them (even though this
653 will allow long comments to exceed the maximum line length).
655 If you would like block comments indented except when this would cause
656 the maximum line length to be exceeded, use B<-olc>. This will cause a
657 group of consecutive block comments to be outdented by the amount needed
658 to prevent any one from exceeding the maximum line length.
660 If you never want block comments indented, use B<-nibc>.
662 If block comments may only be indented if they have some space
663 characters before the leading C<#> character in the input file, use
666 The manual shows many other options for controlling comments.
668 =head2 Outdenting Long Quotes
670 Long quoted strings may exceed the specified line length limit. The
671 default, when this happens, is to outdent them to the first column.
672 Here is an example of an outdented long quote:
674 if ($source_stream) {
677 "You may not specify any filenames when a source array is given\n";
681 The effect is not too different from using a here document to represent
682 the quote. If you prefer to leave the quote indented, like this:
684 if ($source_stream) {
687 "You may not specify any filenames when a source array is given\n";
693 =head2 Many Other Parameters
695 This document has only covered the most popular parameters. The manual
696 contains many more and should be consulted if you did not find what you need
699 =head2 Example F<.perltidyrc> files
701 Now gather together all of the parameters you prefer and enter them
702 in a file called F<.perltidyrc>.
704 Here are some example F<.perltidyrc> files and the corresponding style.
706 Here is a little test snippet, shown the way it would appear with
719 You do not need a F<.perltidyrc> file for this style.
721 Here is the same snippet
732 for a F<.perltidyrc> file containing these parameters:
740 You do not need to place just one parameter per line, but this may be
741 convenient for long lists. You may then hide any parameter by placing
742 a C<#> symbol before it.
744 And here is the snippet
753 for a F<.perltidyrc> file containing these parameters:
761 There is a graphical program called B<tidyview> which you can use to read a
762 preliminary F<.perltidyrc> file, make trial adjustments and immediately see
763 their effect on a test file, and then write a new F<.perltidyrc>. You can
766 http://sourceforge.net/projects/tidyview
768 =head2 Additional Information
770 This document has covered the main parameters. Many more parameters are
771 available for special purposes and for fine-tuning a style. For complete
772 information see the perltidy manual
773 http://perltidy.sourceforge.net/perltidy.html
775 For an introduction to using perltidy, see the tutorial
776 http://perltidy.sourceforge.net/tutorial.html
778 Suggestions for improving this document are welcome and may be sent to
779 perltidy at users.sourceforge.net