1 =head1 Perltidy Style Key
3 Use this document to quickly and methodically find a set of perltidy
4 parameters to approximate your style. Just read each question and
5 select the best answer. Enter your parameters in a file named
6 F<.perltidyrc> (examples are listed at the end). Then move it to one of
7 the places where perltidy will find it. You can run perltidy with the
8 parameter B<-dpro> to see where these places are for your system.
10 Before you begin, experiment using just C<perltidy filename.pl> on some
11 of your files. From the results (which you will find in files with a
12 F<.tdy> extension), you will get a sense of what formatting changes, if
13 any, you'd like to make. If the default formatting is acceptable, you
14 do not need a F<.perltidyrc> file.
18 Do you almost always want to run perltidy as a standard filter on just
19 one input file? If yes, use B<-st> and B<-se>.
21 =head2 Line Length Setting
23 Perltidy will set line breaks to prevent lines from exceeding the
26 Do you want the maximum line length to be 80 columns? If no, use
27 B<-l=n>, where B<n> is the number of columns you prefer.
29 =head2 Indentation in Code Blocks
31 In the block below, the variable C<$anchor> is one indentation level deep
32 and is indented by 4 spaces as shown here:
38 If you want to change this to be a different number B<n> of spaces
39 per indentation level, use B<-i=n>.
41 =head2 Continuation Indentation
43 Look at the statement beginning with C<$anchor>:
47 substr( $header, 0, 6 )
48 . substr( $char_list, $place_1, 1 )
49 . substr( $char_list, $place_2, 1 );
52 The statement is too long for the line length (80 characters by
53 default), so it has been broken into 4 lines. The second and later
54 lines have some extra "continuation indentation" to help make the start
55 of the statement easy to find. The default number of extra spaces is 2.
56 If you prefer a number n different from 2, you may specify this with
57 B<-ci=n>. It is best to keep this less than the value of the primary
62 The default, and recommendation, is to represent leading whitespace
63 with actual space characters. However, if you prefer to entab
64 leading whitespace with one tab character for each B<n> spaces,
65 use B<-et=n>. Typically, B<n> would be 8.
67 =head2 Opening Block Brace Right or Left?
69 Decide which of the following opening brace styles you prefer:
71 If you like opening braces on the right, like this, go to
78 If you like opening braces on the left, like this, go to
88 In a multi-line B<if> test expression, the default is to place
89 the opening brace on the left, like this:
91 if ( $bigwasteofspace1 && $bigwasteofspace2
92 || $bigwasteofspace3 && $bigwasteofspace4 )
97 This helps to visually separate the block contents from the test
100 An alternative is to keep the brace on the right even for
101 multiple-line test expressions, like this:
103 if ( $bigwasteofspace1 && $bigwasteofspace2
104 || $bigwasteofspace3 && $bigwasteofspace4 ) {
108 If you prefer this alternative, use B<-bar>.
112 Do you prefer this B<Cuddled Else> style
114 if ( $flag eq "h" ) {
116 } elsif ( $flag eq "f" ) {
119 print "invalid option: " . substr( $arg, $i, 1 ) . "\n";
123 instead of this default style?
125 if ( $flag eq "h" ) {
128 elsif ( $flag eq "f" ) {
132 print "invalid option: " . substr( $arg, $i, 1 ) . "\n";
136 If yes, you should use B<-ce>.
138 Now skip ahead to L<Indentation Style for Other Containers>.
142 Use B<-bl> if you prefer this style:
149 Use B<-bli> if you prefer this indented-brace style:
156 The number of spaces of extra indentation will be the value specified
157 for continuation indentation with the B<-ci=n> parameter (2 by default).
159 =head2 Block Brace Vertical Tightness
161 The default is to leave the opening brace on a line by itself, like this (shown
162 for B<-bli>, but also true to B<-bl>):
169 But you may also use this more compressed style if you wish:
175 If you do not prefer this more compressed form, go to
176 L<Indentation Style for Other Containers>.
178 Otherwise use parameter B<-bbvt=n>, where n=1 or n=2. To decide,
179 look at this snippet:
198 The difference is that B<-bbvt=1> breaks after an opening brace if
199 the next line is unbalanced, whereas B<-bbvt=2> never breaks.
201 =head2 Indentation Style for Other Containers
203 You have a choice of two indentation schemes for non-block containers.
204 The default is to use a fixed number of spaces per indentation level (the
205 same number of spaces used for code blocks). Here is an example of the
216 The alternate is to let the location of the opening paren (or square
217 bracket, or curly brace) define the indentation, like this:
227 If you prefer the first (default) scheme, skip ahead to
228 L<Closing Token Placement>.
230 If you prefer the latter scheme, use B<-lp> and continue to the next
233 =head2 Opening Vertical Tightness
235 The default B<-lp> indentation style ends a line at the
236 opening tokens, like this:
246 Here is a tighter alternative, which does not end a line
247 with the opening tokens:
249 $dbh = DBI->connect( undef, undef, undef,
255 If you prefer the default, skip ahead to L<Closing Token Placement>.
257 Otherwise, use B<-vt=n>, where B<n> should be either 1 or 2. To help
258 decide, observe the first three opening parens in the following snippet
259 and choose the value of n you prefer. Here it is with B<-lp -vt=1>:
263 start_slip( $DEVICE, $PHONE, $ACCOUNT, $PASSWORD,
264 $LOCAL, $REMOTE, $NETMASK, $MTU
267 && $continuation_flag
270 do_something_about_it();
273 And here it is again formatted with B<-lp -vt=2>:
275 if ( !defined( start_slip( $DEVICE, $PHONE, $ACCOUNT, $PASSWORD,
276 $LOCAL, $REMOTE, $NETMASK, $MTU
279 && $continuation_flag
282 do_something_about_it();
285 The B<-vt=1> style tries to display the structure by preventing more
286 than one step in indentation per line. In this example, the first two
287 opening parens were not followed by balanced lines, so B<-vt=1> broke
290 The B<-vt=2> style does not limit itself to a single indentation step
293 =head2 Closing Token Placement
295 You have several options for dealing with the terminal closing tokens of
296 non-blocks. In the following examples, a closing parenthesis is shown, but
297 these parameters apply to closing square brackets and non-block curly braces as
300 The default behavior for parenthesized relatively large lists is to place the
301 closing paren on a separate new line. The flag B<-cti=n> controls the amount
302 of indentation of such a closing paren.
304 The default, B<-cti=0>, for a line beginning with a closing paren, is to use
305 the indentation defined by the next (lower) indentation level. This works
306 well for the default indentation scheme:
310 'Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun',
311 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'
314 but it may not look very good with the B<-lp> indentation scheme:
318 'Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun',
319 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'
322 An alternative which works well with B<-lp> indentation is B<-cti=1>,
323 which aligns the closing paren vertically with its
324 opening paren, if possible:
326 # perltidy -lp -cti=1
328 'Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun',
329 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'
332 A third alternative, B<-cti=2>, indents a line with leading closing
333 paren one full indentation level:
335 # perltidy -lp -cti=2
337 'Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun',
338 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'
341 If you prefer the closing paren on a separate line like this,
342 note the value of B<-cti=n> that you prefer and skip ahead to
343 L<Define Horizontal Tightness>.
345 Finally, the question of paren indentation can be avoided by placing it
346 at the end of the previous line, like this:
349 'Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun',
350 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec' );
352 Use B<-vtc=n> if you prefer to do this, where n is either 1 or 2. To
353 determine n, we have to look at something more complex. Observe the
354 behavior of the closing tokens in the following snippet:
356 Here is B<-lp -vtc=1>:
358 $srec->{'ACTION'} = [
368 Here is B<-lp -vtc=2>:
370 $srec->{'ACTION'} = [
373 $loc, $lookup, $fh ),
376 $loc, $lookup, $fh ) ];
379 Choose the one that you prefer. The difference is that B<-vtc=1> leaves
380 closing tokens at the start of a line within a list, which can assist in
381 keeping hierarchical lists readable. The B<-vtc=2> style always tries
382 to move closing tokens to the end of a line.
384 If you choose B<-vtc=1>,
385 you may also want to specify a value of B<-cti=n> (previous section) to
386 handle cases where a line begins with a closing paren.
388 =head2 Define Horizontal Tightness
390 Horizontal tightness parameters define how much space is included
391 within a set of container tokens.
393 For parentheses, decide which of the following values of B<-pt=n>
396 if ( ( my $len_tab = length( $tabstr ) ) > 0 ) { # -pt=0
397 if ( ( my $len_tab = length($tabstr) ) > 0 ) { # -pt=1 (default)
398 if ((my $len_tab = length($tabstr)) > 0) { # -pt=2
400 For n=0, space is always used, and for n=2, space is never used. For
401 the default n=1, space is used if the parentheses contain more than
404 For square brackets, decide which of the following values of B<-sbt=n>
407 $width = $col[ $j + $k ] - $col[ $j ]; # -sbt=0
408 $width = $col[ $j + $k ] - $col[$j]; # -sbt=1 (default)
409 $width = $col[$j + $k] - $col[$j]; # -sbt=2
411 For curly braces, decide which of the following values of B<-bt=n>
414 $obj->{ $parsed_sql->{ 'table' }[0] }; # -bt=0
415 $obj->{ $parsed_sql->{'table'}[0] }; # -bt=1 (default)
416 $obj->{$parsed_sql->{'table'}[0]}; # -bt=2
418 For code block curly braces, decide which of the following values of
419 B<-bbt=n> you prefer:
421 %bf = map { $_ => -M $_ } grep { /\.deb$/ } dirents '.'; # -bbt=0 (default)
422 %bf = map { $_ => -M $_ } grep {/\.deb$/} dirents '.'; # -bbt=1
423 %bf = map {$_ => -M $_} grep {/\.deb$/} dirents '.'; # -bbt=2
425 =head2 Statement Termination Semicolon Spaces
427 The default is not to put a space before a statement termination
428 semicolon, like this:
432 If you prefer a space, like this:
438 =head2 For Loop Semicolon Spaces
440 The default is to place a space before a semicolon in a for statement,
443 for ( @a = @$ap, $u = shift @a ; @a ; $u = $v ) { # -sfs (default)
445 If you prefer no such space, like this:
447 for ( @a = @$ap, $u = shift @a; @a; $u = $v ) { # -nsfs
451 =head2 Block Comment Indentation
453 Block comments are comments which occupy a full line, as opposed to side
454 comments. The default is to indent block comments with the same
455 indentation as the code block that contains them (even though this
456 will allow long comments to exceed the maximum line length).
458 If you would like block comments indented except when this would cause
459 the maximum line length to be exceeded, use B<-olc>. This will cause a
460 group of consecutive block comments to be outdented by the amount needed
461 to prevent any one from exceeding the maximum line length.
463 If you never want block comments indented, use B<-nibc>.
465 If block comments may only be indented if they have some space
466 characters before the leading C<#> character in the input file, use
469 =head2 Outdenting Long Quotes
471 Long quoted strings may exceed the specified line length limit. The
472 default, when this happens, is to outdent them to the first column.
473 Here is an example of an outdented long quote:
475 if ($source_stream) {
478 "You may not specify any filenames when a source array is given\n";
482 The effect is not too different from using a here document to represent
483 the quote. If you prefer to leave the quote indented, like this:
485 if ($source_stream) {
488 "You may not specify any filenames when a source array is given\n";
494 =head2 Example F<.perltidyrc> files
496 Now gather together all of the parameters you prefer and enter them
497 in a file called F<.perltidyrc>.
499 Here are some example F<.perltidyrc> files and the corresponding style.
501 Here is a little test snippet, shown the way it would appear with
514 You do not need a F<.perltidyrc> file for this style.
516 Here is the same snippet
527 for a F<.perltidyrc> file containing these parameters:
535 You do not need to place just one parameter per line, but this may be
536 convenient for long lists. You may then hide any parameter by placing
537 a C<#> symbol before it.
539 And here is the snippet
548 for a F<.perltidyrc> file containing these parameters:
554 =head2 Additional Information
556 This document has covered the main parameters. Many more parameters are
557 available for special purposes and for fine-tuning a style. For
558 complete information see the perltidy manual
559 http://perltidy.sourceforge.net/perltidy.html
561 For an introduction to using perltidy, see the tutorial
562 http://perltidy.sourceforge.net/tutorial.html
564 Suggestions for improving this document are welcome and may be sent to
565 perltidy at users.sourceforge.net