view release on metacpan or  search on metacpan

bin/perltidy  view on Meta::CPAN

chain if possible.

=item B<-cb>,   B<--cuddled-blocks>

This flag is equivalent to B<--cuddled-else> (B<-ce>).


=item B<-cbl>,    B<--cuddled-block-list>

The built-in default cuddled block types are B<else, elsif, continue, catch, finally>.

Additional block types to which the B<--cuddled-blocks> style applies can be defined by
this parameter.  This parameter is a character string, giving a list of
block types separated by commas or spaces.  For example, to cuddle code blocks
of type sort, map and grep, in addition to the default types, the string could
be set to

  -cbl="sort map grep"

or equivalently

  -cbl=sort,map,grep

Note however that these particular block types are typically short so there might not be much
opportunity for the cuddled format style.

Using commas avoids the need to protect spaces with quotes.

As a diagnostic check, the flag B<--dump-cuddled-block-list> or B<-dcbl> can be
used to view the hash of values that are generated by this flag.

Finally, note that the B<--cuddled-block-list> parameter by itself merely
specifies which blocks are formatted with the cuddled format. It has no effect
unless this formatting style is activated with B<--cuddled-else>.

=item B<-cblx>,    B<--cuddled-block-list-exclusive>

When cuddled else formatting is selected with B<--cuddled-else>, setting this
flag causes perltidy to ignore its built-in defaults and rely exclusively on
the block types specified on the B<--cuddled-block-list> flag described in the
previous section.  For example, to avoid using cuddled B<catch> and B<finally>,
which are among the defaults, the following set of parameters could be used:

  perltidy -ce -cbl='else elsif continue' -cblx

=item B<-cbo=n>, B<--cuddled-break-option=n>

Cuddled formatting is only possible between a pair of code blocks if the
closing brace of the first block starts a new line. If a block is encountered
which is entirely on a single line, and cuddled formatting is selected, it is
necessary to make a decision as to whether or not to "break" the block, meaning
to cause it to span multiple lines.  This parameter controls that decision. The
options are:

   cbo=0  Never force a short block to break.
   cbo=1  If the first of a pair of blocks is broken in the input
          file, then break the second [DEFAULT].
   cbo=2  Break open all blocks for maximal cuddled formatting.

The default and recommended value is B<cbo=1>.  With this value, if the starting
block of a chain spans multiple lines, then a cascade of breaks will occur for
remaining blocks causing the entire chain to be cuddled.

The option B<cbo=0> can produce erratic cuddling if there are numerous one-line
blocks.

The option B<cbo=2> produces maximal cuddling but will not allow any short blocks.

=item B<-blpc>, B<--blank-lines-prevent-cuddles>

By default, cuddling operations occur even if a blank line separates a closing
brace from the line to which it will be joined.  This flag can be set to
prevent cuddling across such a blank line.  For example, cuddling will
be prevented in the following example because of the -blpc flag:

    # perltidy -ce -blpc
    if ($task) {
        yyy();
    }

    else {
        zzz();
    }

=item B<-bl>, B<--opening-brace-on-new-line>, or B<--brace-left>

Use the flag B<-bl> to place an opening block brace on a new line:

  if ( $input_file eq '-' )
  {
      ...
  }

By default it applies to all structural blocks except B<sort map grep eval> and
anonymous subs.

The default is B<-nbl> which places an opening brace on the same line as
the keyword introducing it if possible.  For example,

  # default
  if ( $input_file eq '-' ) {
     ...
  }

When B<-bl> is set, the blocks to which this applies can be controlled with the
parameters B<--brace-left-list> and B<--brace-left-exclusion-list> described in the next sections.

=item B<-bll=s>, B<--brace-left-list=s>

Use this parameter to change the types of block braces for which the
B<-bl> flag applies; see L<"Specifying Block Types">.  For example,
B<-bll='if elsif else sub'> would apply it to only C<if/elsif/else>
and named sub blocks.  The default is all blocks, B<-bll='*'>.

=item B<-blxl=s>, B<--brace-left-exclusion-list=s>

Use this parameter to exclude types of block braces for which the
B<-bl> flag applies; see L<"Specifying Block Types">.  For example,
the default settings B<-bll='*'> and B<-blxl='sort map grep eval asub'>
mean all blocks except B<sort map grep eval> and anonymous sub blocks.

bin/perltidy  view on Meta::CPAN

B<--square-bracket-vertical-tightness=n>, and B<-sbvtc=n> or
B<--square-bracket-vertical-tightness-closing=n>.

Finally, the parameters for controlling non-code block braces are
B<-bvt=n> or B<--brace-vertical-tightness=n>, and B<-bvtc=n> or
B<--brace-vertical-tightness-closing=n>.

In fact, the parameter B<-vt=n> is actually just an abbreviation for
B<-pvt=n -bvt=n sbvt=n>, and likewise B<-vtc=n> is an abbreviation
for B<-pvtc=n -bvtc=n -sbvtc=n>.

=item B<-bbvt=n> or B<--block-brace-vertical-tightness=n>

The B<-bbvt=n> flag is just like the B<-vt=n> flag but applies
to opening code block braces.

 -bbvt=0 break after opening block brace (default).
 -bbvt=1 do not break unless this would produce more than one
         step in indentation in a line.
 -bbvt=2 do not break after opening block brace.

It is necessary to also use either B<-bl> or B<-bli> for this to work,
because, as with other vertical tightness controls, it is implemented by
simply overwriting a line ending with an opening block brace with the
subsequent line.  For example:

    # perltidy -bli -bbvt=0
    if ( open( FILE, "< $File" ) )
      {
        while ( $File = <FILE> )
          {
            $In .= $File;
            $count++;
          }
        close(FILE);
      }

    # perltidy -bli -bbvt=1
    if ( open( FILE, "< $File" ) )
      { while ( $File = <FILE> )
          { $In .= $File;
            $count++;
          }
        close(FILE);
      }

By default this applies to blocks associated with keywords B<if>,
B<elsif>, B<else>, B<unless>, B<for>, B<foreach>, B<sub>, B<while>,
B<until>, and also with a preceding label.  This can be changed with
the parameter B<-bbvtl=string>, or
B<--block-brace-vertical-tightness-list=string>, where B<string> is a
space-separated list of block types.  For more information on the
possible values of this string, see L<"Specifying Block Types">

For example, if we want to just apply this style to C<if>,
C<elsif>, and C<else> blocks, we could use
C<perltidy -bli -bbvt=1 -bbvtl='if elsif else'>.

There is no vertical tightness control for closing block braces; with
one exception they will be placed on separate lines.
The exception is that a cascade of closing block braces may
be stacked on a single line.  See B<--stack-closing-block-brace>.

=item B<-sot>,  B<--stack-opening-tokens> and related flags

The B<-sot> flag tells perltidy to "stack" opening tokens
when possible to avoid lines with isolated opening tokens.

For example:

    # default
    $opt_c = Text::CSV_XS->new(
        {
            binary       => 1,
            sep_char     => $opt_c,
            always_quote => 1,
        }
    );

    # -sot
    $opt_c = Text::CSV_XS->new( {
            binary       => 1,
            sep_char     => $opt_c,
            always_quote => 1,
        }
    );

For detailed control of individual closing tokens the following
controls can be used:

  -sop  or --stack-opening-paren
  -sohb or --stack-opening-hash-brace
  -sosb or --stack-opening-square-bracket
  -sobb or --stack-opening-block-brace

The flag B<-sot> is an abbreviation for B<-sop -sohb -sosb>.

The flag B<-sobb> is an abbreviation for B<-bbvt=2 -bbvtl='*'>.  This
will cause a cascade of opening block braces to appear on a single line,
although this an uncommon occurrence except in test scripts.

=item B<-sct>,  B<--stack-closing-tokens> and related flags

The B<-sct> flag tells perltidy to "stack" closing tokens
when possible to avoid lines with isolated closing tokens.

For example:

    # default
    $opt_c = Text::CSV_XS->new(
        {
            binary       => 1,
            sep_char     => $opt_c,
            always_quote => 1,
        }
    );

    # -sct
    $opt_c = Text::CSV_XS->new(
        {
            binary       => 1,
            sep_char     => $opt_c,
            always_quote => 1,
        } );

The B<-sct> flag is somewhat similar to the B<-vtc>
(B<--vertical-tightness-closing> 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 them
but does not try to hide them.  For example:

    # -vtc=2
    $opt_c = Text::CSV_XS->new(
        {
            binary       => 1,
            sep_char     => $opt_c,
            always_quote => 1, } );

For detailed control of the stacking of individual closing tokens the
following controls can be used:

  -scp  or --stack-closing-paren
  -schb or --stack-closing-hash-brace
  -scsb or --stack-closing-square-bracket
  -scbb or --stack-closing-block-brace

The flag B<-sct> is an abbreviation for stacking the non-block closing
tokens, B<-scp -schb -scsb>.

Stacking of closing block braces, B<-scbb>, causes a cascade of isolated
closing block braces to be combined into a single line as in the following
example:

    # -scbb:
    for $w1 (@w1) {
        for $w2 (@w2) {
            for $w3 (@w3) {
                for $w4 (@w4) {
                    push( @lines, "$w1 $w2 $w3 $w4\n" );
                } } } }

To simplify input even further for the case in which both opening and closing
non-block containers are stacked, the flag B<-sac> or B<--stack-all-containers>
is an abbreviation for B<--stack-opening-tokens --stack-closing-tokens>.

Please note that if both opening and closing tokens are to be stacked, then the
newer flag B<--weld-nested-containers> may be preferable because it insures that
stacking is always done symmetrically.  It also removes an extra level of
unnecessary indentation within welded containers.  It is able to do this
because it works on formatting globally rather than locally, as the B<--stack-opening-tokens> and B<--stack-closing-tokens> flags do.

=back

=head2 Breaking Before or After Operators

Four command line parameters provide some control over whether
a line break should be before or after specific token types.
Two parameters give detailed control:

B<-wba=s> or B<--want-break-after=s>, and

B<-wbb=s> or B<--want-break-before=s>.

These parameters are each followed by a quoted string, B<s>, containing
a list of token types (separated only by spaces).  No more than one of each
of these parameters should be specified, because repeating a
command-line parameter always overwrites the previous one before
perltidy ever sees it.

By default, perltidy breaks B<after> these token types:
  % + - * / x != == >= <= =~ !~ < >  | &
  = **= += *= &= <<= &&= -= /= |= >>= ||= //= .= %= ^= x=

And perltidy breaks B<before> these token types by default:
  . << >> -> && || //

To illustrate, to cause a break after a concatenation operator, C<'.'>,
rather than before it, the command line would be

  -wba="."

As another example, the following command would cause a break before
math operators C<'+'>, C<'-'>, C<'/'>, and C<'*'>:

  -wbb="+ - / *"

These commands should work well for most of the token types that perltidy uses
(use B<--dump-token-types> for a list).  Also try the B<-D> flag on a short
snippet of code and look at the .DEBUG file to see the tokenization.  However,
for a few token types there may be conflicts with hardwired logic which cause