--- /dev/null
+=head1 Perltidy Style Key
+
+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<perltidy filename.pl> on some
+of your files. From the results (which you will find in files with a
+F<.tdy> extension), you will get a sense of what formatting changes, if
+any, you'd like to make. If the default formatting is acceptable, you
+do not need a F<.perltidyrc> file.
+
+=head2 Use as Filter?
+
+Do you almost always want to run perltidy as a standard filter on just
+one input file? If yes, use B<-st> and B<-se>.
+
+=head2 Line Length Setting
+
+Perltidy will set line breaks to prevent lines from exceeding the
+maximum line length.
+
+Do you want the maximum line length to be 80 columns? If no, use
+B<-l=n>, where B<n> is the number of columns you prefer.
+
+=head2 Indentation in Code Blocks
+
+In the block below, the variable C<$anchor> is one indentation level deep
+and is indented by 4 spaces as shown here:
+
+ if ( $flag eq "a" ) {
+ $anchor = $header;
+ }
+
+If you want to change this to be a different number B<n> of spaces
+per indentation level, use B<-i=n>.
+
+=head2 Continuation Indentation
+
+Look at the statement beginning with C<$anchor>:
+
+ if ( $flag eq "a" ) {
+ $anchor =
+ substr( $header, 0, 6 )
+ . substr( $char_list, $place_1, 1 )
+ . 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 probably best if
+it does not exceed the value of the primary indentation.
+
+=head2 Tabs
+
+The default, and recommendation, is to represent leading whitespace
+with actual space characters. However, if you prefer to entab
+leading whitespace with one tab character for each B<n> spaces,
+use B<-et=n>. Typically, B<n> would be 8.
+
+=head2 Opening Block Brace Right or Left?
+
+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<Opening Braces Right>.
+
+ if ( $flag eq "h" ) {
+ $headers = 0;
+ }
+
+If you like opening braces on the left, like this, go to
+L<Opening Braces Left>.
+
+ if ( $flag eq "h" )
+ {
+ $headers = 0;
+ }
+
+=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 ( $bigwasteofspace1 && $bigwasteofspace2
+ || $bigwasteofspace3 && $bigwasteofspace4 )
+ {
+ big_waste_of_time();
+ }
+
+This helps to visually separate the block contents from the test
+expression.
+
+An alternative is to keep the brace on the right even for
+multiple-line test expressions, like this:
+
+ if ( $bigwasteofspace1 && $bigwasteofspace2
+ || $bigwasteofspace3 && $bigwasteofspace4 ) {
+ big_waste_of_time();
+ }
+
+If you prefer this alternative, use B<-bar>.
+
+=head2 Cuddled Else?
+
+Do you prefer this B<Cuddled Else> style
+
+ if ( $flag eq "h" ) {
+ $headers = 0;
+ } elsif ( $flag eq "f" ) {
+ $sectiontype = 3;
+ } else {
+ print "invalid option: " . substr( $arg, $i, 1 ) . "\n";
+ dohelp();
+ }
+
+instead of this default style?
+
+ if ( $flag eq "h" ) {
+ $headers = 0;
+ }
+ elsif ( $flag eq "f" ) {
+ $sectiontype = 3;
+ }
+ else {
+ print "invalid option: " . substr( $arg, $i, 1 ) . "\n";
+ dohelp();
+ }
+
+If yes, you should use B<-ce>.
+Now skip ahead to L<Opening Sub Braces>.
+
+=head2 Opening Braces Left
+
+Use B<-bl> if you prefer this style:
+
+ if ( $flag eq "h" )
+ {
+ $headers = 0;
+ }
+
+Use B<-bli> if you prefer this indented-brace style:
+
+ if ( $flag eq "h" )
+ {
+ $headers = 0;
+ }
+
+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
+
+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" )
+ {
+ $headers = 0;
+ }
+
+But you may also use this more compressed style if you wish:
+
+ if ( $flag eq "h" )
+ { $headers = 0;
+ }
+
+If you do not prefer this more compressed form, go to
+L<Opening Sub Braces>.
+
+Otherwise use parameter B<-bbvt=n>, where n=1 or n=2. To decide,
+look at this snippet:
+
+ # -bli -bbvt=1
+ sub _directives
+ {
+ {
+ 'ENDIF' => \&_endif,
+ 'IF' => \&_if,
+ };
+ }
+
+ # -bli -bbvt=2
+ sub _directives
+ { {
+ 'ENDIF' => \&_endif,
+ '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.
+
+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 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,
+ {
+ PrintError => 0,
+ RaiseError => 1
+ }
+ );
+
+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:
+
+ $dbh = DBI->connect(
+ undef, undef, undef,
+ {
+ PrintError => 0,
+ RaiseError => 1
+ }
+ );
+
+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>.
+
+=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:
+
+ $dbh = DBI->connect(
+ undef, undef, undef,
+ {
+ PrintError => 0,
+ RaiseError => 1
+ }
+ );
+
+Here is a tighter alternative, which does not end a line
+with the opening tokens:
+
+ $dbh = DBI->connect( undef, undef, undef,
+ { PrintError => 0,
+ RaiseError => 1
+ }
+ );
+
+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
+decide, observe the first three opening parens in the following snippet
+and choose the value of n you prefer. Here it is with B<-lp -vt=1>:
+
+ if (
+ !defined(
+ start_slip( $DEVICE, $PHONE, $ACCOUNT, $PASSWORD,
+ $LOCAL, $REMOTE, $NETMASK, $MTU
+ )
+ )
+ && $continuation_flag
+ )
+ {
+ do_something_about_it();
+ }
+
+And here it is again formatted with B<-lp -vt=2>:
+
+ if ( !defined( start_slip( $DEVICE, $PHONE, $ACCOUNT, $PASSWORD,
+ $LOCAL, $REMOTE, $NETMASK, $MTU
+ )
+ )
+ && $continuation_flag
+ )
+ {
+ do_something_about_it();
+ }
+
+The B<-vt=1> style tries to display the structure by preventing more
+than one step in indentation per line. In this example, the first two
+opening parens were not followed by balanced lines, so B<-vt=1> broke
+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<Block Brace Vertical Tightness>.
+
+=head2 Closing Token Placement
+
+You have several options for dealing with the terminal closing tokens of
+non-blocks. In the following examples, a closing parenthesis is shown, but
+these parameters apply to closing square brackets and non-block curly braces as
+well.
+
+The default behavior for parenthesized relatively large lists is to place the
+closing paren on a separate new line. The flag B<-cti=n> controls the amount
+of indentation of such a closing paren.
+
+The default, B<-cti=0>, for a line beginning with a closing paren, is to use
+the indentation defined by the next (lower) indentation level. This works
+well for the default indentation scheme:
+
+ # perltidy
+ @month_of_year = (
+ 'Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun',
+ 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'
+ );
+
+but it may not look very good with the B<-lp> indentation scheme:
+
+ # perltidy -lp
+ @month_of_year = (
+ 'Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun',
+ 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'
+ );
+
+An alternative which works well with B<-lp> indentation is B<-cti=1>,
+which aligns the closing paren vertically with its
+opening paren, if possible:
+
+ # perltidy -lp -cti=1
+ @month_of_year = (
+ 'Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun',
+ 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'
+ );
+
+Another alternative, B<-cti=3>, indents a line with leading closing
+paren one full indentation level:
+
+ # perltidy -lp -cti=3
+ @month_of_year = (
+ 'Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun',
+ 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'
+ );
+
+If you prefer the closing paren on a separate line like this,
+note the value of B<-cti=n> that you prefer and skip ahead to
+L<Define Horizontal Tightness>.
+
+Finally, the question of paren indentation can be avoided by placing it
+at the end of the previous line, like this:
+
+ @month_of_year = (
+ 'Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun',
+ 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec' );
+
+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>:
+
+ $srec->{'ACTION'} = [
+ $self->read_value(
+ $lookup->{'VFMT'},
+ $loc, $lookup, $fh
+ ),
+ $self->read_value(
+ $lookup->{'VFMT2'},
+ $loc, $lookup, $fh
+ ) ];
+
+Here is B<-lp -vtc=2>:
+
+ $srec->{'ACTION'} = [
+ $self->read_value(
+ $lookup->{'VFMT'},
+ $loc, $lookup, $fh ),
+ $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
+keeping hierarchical lists readable. The B<-vtc=2> style always tries
+to move closing tokens to the end of a line.
+
+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
+within a set of container tokens.
+
+For parentheses, decide which of the following values of B<-pt=n>
+you prefer:
+
+ if ( ( my $len_tab = length( $tabstr ) ) > 0 ) { # -pt=0
+ if ( ( my $len_tab = length($tabstr) ) > 0 ) { # -pt=1 (default)
+ if ((my $len_tab = length($tabstr)) > 0) { # -pt=2
+
+For n=0, space is always used, and for n=2, space is never used. For
+the default n=1, space is used if the parentheses contain more than
+one token.
+
+For square brackets, decide which of the following values of B<-sbt=n>
+you prefer:
+
+ $width = $col[ $j + $k ] - $col[ $j ]; # -sbt=0
+ $width = $col[ $j + $k ] - $col[$j]; # -sbt=1 (default)
+ $width = $col[$j + $k] - $col[$j]; # -sbt=2
+
+For curly braces, decide which of the following values of B<-bt=n>
+you prefer:
+
+ $obj->{ $parsed_sql->{ 'table' }[0] }; # -bt=0
+ $obj->{ $parsed_sql->{'table'}[0] }; # -bt=1 (default)
+ $obj->{$parsed_sql->{'table'}[0]}; # -bt=2
+
+For code block curly braces, decide which of the following values of
+B<-bbt=n> you prefer:
+
+ %bf = map { $_ => -M $_ } grep { /\.deb$/ } dirents '.'; # -bbt=0 (default)
+ %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
+semicolon, like this:
+
+ $i = 1;
+
+If you prefer a space, like this:
+
+ $i = 1 ;
+
+enter B<-sts>.
+
+=head2 For Loop Semicolon Spaces
+
+The default is to place a space before a semicolon in a for statement,
+like this:
+
+ for ( @a = @$ap, $u = shift @a ; @a ; $u = $v ) { # -sfs (default)
+
+If you prefer no such space, like this:
+
+ for ( @a = @$ap, $u = shift @a; @a; $u = $v ) { # -nsfs
+
+enter B<-nsfs>.
+
+=head2 Block Comment Indentation
+
+Block comments are comments which occupy a full line, as opposed to side
+comments. The default is to indent block comments with the same
+indentation as the code block that contains them (even though this
+will allow long comments to exceed the maximum line length).
+
+If you would like block comments indented except when this would cause
+the maximum line length to be exceeded, use B<-olc>. This will cause a
+group of consecutive block comments to be outdented by the amount needed
+to prevent any one from exceeding the maximum line length.
+
+If you never want block comments indented, use B<-nibc>.
+
+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
+default, when this happens, is to outdent them to the first column.
+Here is an example of an outdented long quote:
+
+ if ($source_stream) {
+ if ( @ARGV > 0 ) {
+ die
+ "You may not specify any filenames when a source array is given\n";
+ }
+ }
+
+The effect is not too different from using a here document to represent
+the quote. If you prefer to leave the quote indented, like this:
+
+ if ($source_stream) {
+ if ( @ARGV > 0 ) {
+ die
+ "You may not specify any filenames when a source array is given\n";
+ }
+ }
+
+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
+in a file called F<.perltidyrc>.
+
+Here are some example F<.perltidyrc> files and the corresponding style.
+
+Here is a little test snippet, shown the way it would appear with
+the default style.
+
+ for (@methods) {
+ push (
+ @results,
+ {
+ name => $_->name,
+ help => $_->help,
+ }
+ );
+ }
+
+You do not need a F<.perltidyrc> file for this style.
+
+Here is the same snippet
+
+ for (@methods)
+ {
+ push(@results,
+ { name => $_->name,
+ help => $_->help,
+ }
+ );
+ }
+
+for a F<.perltidyrc> file containing these parameters:
+
+ -bl
+ -lp
+ -cti=1
+ -vt=1
+ -pt=2
+
+You do not need to place just one parameter per line, but this may be
+convenient for long lists. You may then hide any parameter by placing
+a C<#> symbol before it.
+
+And here is the snippet
+
+ for (@methods) {
+ push ( @results,
+ { name => $_->name,
+ help => $_->help,
+ } );
+ }
+
+for a F<.perltidyrc> file containing these parameters:
+
+ -lp
+ -vt=1
+ -vtc=1
+
+=head2 Tidyview
+
+There is a graphical program called B<tidyview> 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
+http://perltidy.sourceforge.net/perltidy.html
+
+For an introduction to using perltidy, see the tutorial
+http://perltidy.sourceforge.net/tutorial.html
+
+Suggestions for improving this document are welcome and may be sent to
+perltidy at users.sourceforge.net
+
+=cut
projects / perltidy.git / blobdiff