X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=docs%2Fstylekey.pod;h=7927aa256a61bf20b47a55c7a39fd2e88c309102;hb=8aa69fbac36a21cad0a1c0d5b3452a546d427d7f;hp=ee49994ae659c0c4d5469538af5d062bf86f5b12;hpb=ed1fffa086693c62340599065543ee1d5c09ee8f;p=perltidy.git diff --git a/docs/stylekey.pod b/docs/stylekey.pod index ee49994..7927aa2 100644 --- a/docs/stylekey.pod +++ b/docs/stylekey.pod @@ -1,11 +1,21 @@ =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. + +=head2 Before You Start Before you begin, experiment using just C on some of your files. From the results (which you will find in files with a @@ -49,13 +59,12 @@ Look at the statement beginning with C<$anchor>: . 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 @@ -66,24 +75,33 @@ use B<-et=n>. Typically, B would be 8. =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 which will +be covered later): If you like opening braces on the right, like this, go to -L. +L. if ( $flag eq "h" ) { $headers = 0; } If you like opening braces on the left, like this, go to -L. +L. if ( $flag eq "h" ) { $headers = 0; } -=head2 Braces Right +=head2 Opening Braces Right In a multi-line B test expression, the default is to place the opening brace on the left, like this: @@ -134,10 +152,9 @@ instead of this default style? } If yes, you should use B<-ce>. +Now skip ahead to L. -Now skip ahead to L. - -=head2 Braces Left +=head2 Opening Braces Left Use B<-bl> if you prefer this style: @@ -156,10 +173,41 @@ Use B<-bli> if you prefer this indented-brace 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. + +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. + +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" ) { @@ -173,7 +221,7 @@ But you may also use this more compressed style if you wish: } If you do not prefer this more compressed form, go to -L. +L. Otherwise use parameter B<-bbvt=n>, where n=1 or n=2. To decide, look at this snippet: @@ -189,21 +237,54 @@ 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, @@ -213,6 +294,11 @@ default: } ); +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: @@ -224,14 +310,23 @@ bracket, or curly brace) define the indentation, like this: } ); -If you prefer the first (default) scheme, skip ahead to -L. +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: @@ -252,6 +347,11 @@ with the opening tokens: } ); +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. Otherwise, use B<-vt=n>, where B should be either 1 or 2. To help @@ -290,6 +390,11 @@ after them. 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. + =head2 Closing Token Placement You have several options for dealing with the terminal closing tokens of @@ -329,10 +434,10 @@ opening paren, if possible: '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' @@ -349,8 +454,11 @@ at the end of the previous line, like this: '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 is either 1 or 2. To +determine B, 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>: @@ -374,7 +482,6 @@ Here is B<-lp -vtc=2>: $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 @@ -385,6 +492,66 @@ If you choose B<-vtc=1>, 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 @@ -422,6 +589,36 @@ B<-bbt=n> you prefer: %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 @@ -431,7 +628,7 @@ semicolon, like this: If you prefer a space, like this: - $i = 1 ; + $i = 1 ; enter B<-sts>. @@ -466,6 +663,8 @@ If block comments may only be indented if they have some space 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 @@ -491,6 +690,12 @@ the quote. If you prefer to leave the quote indented, like this: 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 @@ -551,11 +756,20 @@ for a F<.perltidyrc> file containing these parameters: -vt=1 -vtc=1 +=head2 Tidyview + +There is a graphical program called B which you can use to read a +preliminary F<.perltidyrc> file, make trial adjustments and immediately see +their effect on a test file, and then write a new F<.perltidyrc>. You can +download a copy at + +http://sourceforge.net/projects/tidyview + =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