Perl-Tidy

 view release on metacpan or  search on metacpan

bin/perltidy  view on Meta::CPAN

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<-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:

bin/perltidy  view on Meta::CPAN

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

bin/perltidy  view on Meta::CPAN

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 case 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

bin/perltidy  view on Meta::CPAN

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" );
                } } } }

docs/BugLog.html  view on Meta::CPAN

                    $r->[2],    $r->[3], $r->[4],       # price, date, time
                    $r->[5],    $r->[6],                # change, %change
                    $r->[7],    "-", "-", "-",          # vol, avg vol, bid,ask
                    $r->[8],               $r->[9],     # previous, open
                    "$r->[10] - $r->[11]", $r->[12],    # day range,year range,
                    "-",                   "-", "-", "-", "-"
                )
            );    # eps,p/e,div,yld,cap
        }</code></pre>

<p>The following exampel shows an unexpected alignment in the cascade of trailing comments which are aligned but slowly separating from their closing containers:</p>

<pre><code>    # OLD:
    {
        $a = [
            Cascade    =&gt; $menu_cb,
            -menuitems =&gt; [
                [ Checkbutton =&gt; &#39;Oil checked&#39;, -variable =&gt; \$OIL ],
                [
                    Button   =&gt; &#39;See current values&#39;,
                    -command =&gt; [
                        \&amp;see_vars, $TOP,

                    ],    # end see_vars
                ],        # end button
            ],            # end checkbutton menuitems
        ];                # end checkbuttons cascade
    }</code></pre>

<p>This was caused by forgetting side comments only across code block changes. The new result is more reasonable:</p>

<pre><code>    # NEW:
    {
        $a = [
            Cascade    =&gt; $menu_cb,
            -menuitems =&gt; [
                [ Checkbutton =&gt; &#39;Oil checked&#39;, -variable =&gt; \$OIL ],
                [
                    Button   =&gt; &#39;See current values&#39;,
                    -command =&gt; [
                        \&amp;see_vars, $TOP,

                    ],    # end see_vars
                ],    # end button
            ],    # end checkbutton menuitems
        ];    # end checkbuttons cascade
    }</code></pre>

<p>This change will cause occasional differences in side comment locations from previous versions but overall it gives fewer unexpected results so it is a worthwhile change. 29-Dec-2020, 76993f4.</p>

</dd>
<dt id="Fixed-very-minor-inconsistency-in-redefining-lists-after-prune-step"><b>Fixed very minor inconsistency in redefining lists after prune step</b></dt>
<dd>

<p>In rare cases it is necessary to update the type of lists, and this influences vertical alignment. This update fixes a minor inconsistency in doing this. In some rare cases with complex list elements vertical alignment can be improved. 27 Dec, 202...

docs/perltidy.html  view on Meta::CPAN

<dt id="cbo-n---cuddled-break-option-n"><b>-cbo=n</b>, <b>--cuddled-break-option=n</b></dt>
<dd>

<p>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 ...

<pre><code>   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.</code></pre>

<p>The default and recommended value is <b>cbo=1</b>. 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.</p>

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

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

</dd>
<dt id="bl---opening-brace-on-new-line-or---brace-left"><b>-bl</b>, <b>--opening-brace-on-new-line</b>, or <b>--brace-left</b></dt>
<dd>

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

docs/perltidy.html  view on Meta::CPAN

          { $In .= $File;
            $count++;
          }
        close(FILE);
      }</code></pre>

<p>By default this applies to blocks associated with keywords <b>if</b>, <b>elsif</b>, <b>else</b>, <b>unless</b>, <b>for</b>, <b>foreach</b>, <b>sub</b>, <b>while</b>, <b>until</b>, and also with a preceding label. This can be changed with the param...

<p>For example, if we want to just apply this style to <code>if</code>, <code>elsif</code>, and <code>else</code> blocks, we could use <code>perltidy -bli -bbvt=1 -bbvtl=&#39;if elsif else&#39;</code>.</p>

<p>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<...

</dd>
<dt id="sot---stack-opening-tokens-and-related-flags"><b>-sot</b>, <b>--stack-opening-tokens</b> and related flags</dt>
<dd>

<p>The <b>-sot</b> flag tells perltidy to &quot;stack&quot; opening tokens when possible to avoid lines with isolated opening tokens.</p>

<p>For example:</p>

<pre><code>    # default

docs/perltidy.html  view on Meta::CPAN

<p>For detailed control of individual closing tokens the following controls can be used:</p>

<pre><code>  -sop  or --stack-opening-paren
  -sohb or --stack-opening-hash-brace
  -sosb or --stack-opening-square-bracket
  -sobb or --stack-opening-block-brace</code></pre>

<p>The flag <b>-sot</b> is an abbreviation for <b>-sop -sohb -sosb</b>.</p>

<p>The flag <b>-sobb</b> is an abbreviation for <b>-bbvt=2 -bbvtl=&#39;*&#39;</b>. This will case a cascade of opening block braces to appear on a single line, although this an uncommon occurrence except in test scripts.</p>

</dd>
<dt id="sct---stack-closing-tokens-and-related-flags"><b>-sct</b>, <b>--stack-closing-tokens</b> and related flags</dt>
<dd>

<p>The <b>-sct</b> flag tells perltidy to &quot;stack&quot; closing tokens when possible to avoid lines with isolated closing tokens.</p>

<p>For example:</p>

<pre><code>    # default

docs/perltidy.html  view on Meta::CPAN

<p>For detailed control of the stacking of individual closing tokens the following controls can be used:</p>

<pre><code>  -scp  or --stack-closing-paren
  -schb or --stack-closing-hash-brace
  -scsb or --stack-closing-square-bracket
  -scbb or --stack-closing-block-brace</code></pre>

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

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

<pre><code>    # -scbb:
    for $w1 (@w1) {
        for $w2 (@w2) {
            for $w3 (@w3) {
                for $w4 (@w4) {
                    push( @lines, &quot;$w1 $w2 $w3 $w4\n&quot; );
                } } } }</code></pre>

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