view release on metacpan or  search on metacpan

docs/perltidy.html  view on Meta::CPAN

<p>Other block types can be formatted by specifying their names on a separate parameter <b>--cuddled-block-list</b>, described in a later section.</p>

<p>Cuddling between a pair of code blocks requires that the closing brace of the first block start a new line. If this block is entirely on one line in the input file, it is necessary to decide if it should be broken to allow cuddling. This decision ...

<p>So for example, the <b>--cuddled-else</b> flag would not have any effect if the above snippet is rewritten as</p>

<pre><code>if ($task) { yyy() }
else {    zzz() }</code></pre>

<p>If the first block spans multiple lines, then cuddling can be done and will continue for the subsequent blocks in the chain, as illustrated in the previous snippet.</p>

<p>If there are blank lines between cuddled blocks they will be eliminated (unless the flag <b>--blank-lines-prevent-cuddles</b> is set; it is described below). If there are comments after the closing brace where cuddling would occur then cuddling wi...

</dd>
<dt id="cb---cuddled-blocks"><b>-cb</b>, <b>--cuddled-blocks</b></dt>
<dd>

<p>This flag is equivalent to <b>--cuddled-else</b> (<b>-ce</b>).</p>

</dd>
<dt id="cbl---cuddled-block-list"><b>-cbl</b>, <b>--cuddled-block-list</b></dt>
<dd>

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

<p>Additional block types to which the <b>--cuddled-blocks</b> 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 typ...

<pre><code>-cbl=&quot;sort map grep&quot;</code></pre>

<p>or equivalently</p>

<pre><code>-cbl=sort,map,grep</code></pre>

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

<p>Using commas avoids the need to protect spaces with quotes.</p>

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

<p>Finally, note that the <b>--cuddled-block-list</b> 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</b>.</p>

</dd>
<dt id="cblx---cuddled-block-list-exclusive"><b>-cblx</b>, <b>--cuddled-block-list-exclusive</b></dt>
<dd>

<p>When cuddled else formatting is selected with <b>--cuddled-else</b>, 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</b> flag described in the previ...

<pre><code>perltidy -ce -cbl=&#39;else elsif continue&#39; -cblx</code></pre>

</dd>
<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="blpc---blank-lines-prevent-cuddles"><b>-blpc</b>, <b>--blank-lines-prevent-cuddles</b></dt>
<dd>

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

<pre><code># perltidy -ce -blpc
if ($task) {
    yyy();
}

else {
    zzz();
}</code></pre>

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

<pre><code>if ( $input_file eq &#39;-&#39; )
{
    ...
}</code></pre>

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

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

<pre><code># default
if ( $input_file eq &#39;-&#39; ) {
   ...
}</code></pre>

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

</dd>
<dt id="bll-s---brace-left-list-s"><b>-bll=s</b>, <b>--brace-left-list=s</b></dt>
<dd>

<p>Use this parameter to change the types of block braces for which the <b>-bl</b> flag applies; see <a href="#Specifying-Block-Types">&quot;Specifying Block Types&quot;</a>. For example, <b>-bll=&#39;if elsif else sub&#39;</b> would apply it to only...

</dd>
<dt id="blxl-s---brace-left-exclusion-list-s"><b>-blxl=s</b>, <b>--brace-left-exclusion-list=s</b></dt>
<dd>

<p>Use this parameter to exclude types of block braces for which the <b>-bl</b> flag applies; see <a href="#Specifying-Block-Types">&quot;Specifying Block Types&quot;</a>. For example, the default settings <b>-bll=&#39;*&#39;</b> and <b>-blxl=&#39;so...

<p>Note that the lists <b>-bll=s</b> and <b>-blxl=s</b> control the behavior of the <b>-bl</b> flag but have no effect unless the <b>-bl</b> flag is set. These two lists provide complete control for this flag, but two shortcut flags are available and...

</dd>
<dt id="sbl---opening-sub-brace-on-new-line"><b>-sbl</b>, <b>--opening-sub-brace-on-new-line</b></dt>
<dd>

docs/perltidy.html  view on Meta::CPAN

            )
);</code></pre>

<p>With <b>-vt=1</b>, the line ending in <code>add(</code> does not combine with the next line because the next line is not balanced. This can help with readability, but <b>-vt=2</b> can be used to ignore this rule.</p>

<p>The tightest, and least readable, code is produced with both <code>-vt=2</code> and <code>-vtc=2</code>:</p>

<pre><code># perltidy -lp -vt=2 -vtc=2
$init-&gt;add( mysprintf( &quot;(void)find_threadsv(%s);&quot;,
                       cstring( $threadsv_names[ $op-&gt;targ ] ) ) );</code></pre>

<p>Notice how the code in all of these examples collapses vertically as <b>-vt</b> increases, but the indentation remains unchanged. This is because perltidy implements the <b>-vt</b> parameter by first formatting as if <b>-vt=0</b>, and then simply ...

<p>The <b>-vt=n</b> and <b>-vtc=n</b> parameters apply to each type of container token. If desired, vertical tightness controls can be applied independently to each of the closing container token types.</p>

<p>The parameters for controlling parentheses are <b>-pvt=n</b> or <b>--paren-vertical-tightness=n</b>, and <b>-pvtc=n</b> or <b>--paren-vertical-tightness-closing=n</b>.</p>

<p>Likewise, the parameters for square brackets are <b>-sbvt=n</b> or <b>--square-bracket-vertical-tightness=n</b>, and <b>-sbvtc=n</b> or <b>--square-bracket-vertical-tightness-closing=n</b>.</p>

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

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

</dd>
<dt id="bbvt-n-or---block-brace-vertical-tightness-n"><b>-bbvt=n</b> or <b>--block-brace-vertical-tightness=n</b></dt>
<dd>

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

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

<p>It is necessary to also use either <b>-bl</b> or <b>-bli</b> 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 exam...

<pre><code># perltidy -bli -bbvt=0
if ( open( FILE, &quot;&lt; $File&quot; ) )
  {
    while ( $File = &lt;FILE&gt; )
      {
        $In .= $File;
        $count++;
      }
    close(FILE);
  }

# perltidy -bli -bbvt=1
if ( open( FILE, &quot;&lt; $File&quot; ) )
  { while ( $File = &lt;FILE&gt; )
      { $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
$opt_c = Text::CSV_XS-&gt;new(
    {
        binary       =&gt; 1,
        sep_char     =&gt; $opt_c,
        always_quote =&gt; 1,
    }
);

# -sot
$opt_c = Text::CSV_XS-&gt;new( {
        binary       =&gt; 1,
        sep_char     =&gt; $opt_c,
        always_quote =&gt; 1,
    }
);</code></pre>

<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 cause 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
$opt_c = Text::CSV_XS-&gt;new(
    {
        binary       =&gt; 1,
        sep_char     =&gt; $opt_c,
        always_quote =&gt; 1,
    }
);

# -sct
$opt_c = Text::CSV_XS-&gt;new(
    {
        binary       =&gt; 1,
        sep_char     =&gt; $opt_c,
        always_quote =&gt; 1,
    } );</code></pre>

<p>The <b>-sct</b> flag is somewhat similar to the <b>-vtc</b> (<b>--vertical-tightness-closing</b> flags, and in some cases it can give a similar result. The difference is that the <b>-vtc</b> flags try to avoid lines with leading opening tokens by ...

<pre><code># -vtc=2
$opt_c = Text::CSV_XS-&gt;new(
    {
        binary       =&gt; 1,
        sep_char     =&gt; $opt_c,
        always_quote =&gt; 1, } );</code></pre>

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

<p>Please note that if both opening and closing tokens are to be stacked, then the newer flag <b>--weld-nested-containers</b> may be preferable because it insures that stacking is always done symmetrically. It also removes an extra level of unnecessa...

</dd>
</dl>

<h2 id="Breaking-Before-or-After-Operators">Breaking Before or After Operators</h2>

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

<p><b>-wba=s</b> or <b>--want-break-after=s</b>, and</p>

<p><b>-wbb=s</b> or <b>--want-break-before=s</b>.</p>

<p>These parameters are each followed by a quoted string, <b>s</b>, 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 overw...

<p>By default, perltidy breaks <b>after</b> these token types: % + - * / x != == &gt;= &lt;= =~ !~ &lt; &gt; | &amp; = **= += *= &amp;= &lt;&lt;= &amp;&amp;= -= /= |= &gt;&gt;= ||= //= .= %= ^= x=</p>

<p>And perltidy breaks <b>before</b> these token types by default: . &lt;&lt; &gt;&gt; -&gt; &amp;&amp; || //</p>

<p>To illustrate, to cause a break after a concatenation operator, <code>&#39;.&#39;</code>, rather than before it, the command line would be</p>

<pre><code>-wba=&quot;.&quot;</code></pre>

<p>As another example, the following command would cause a break before math operators <code>&#39;+&#39;</code>, <code>&#39;-&#39;</code>, <code>&#39;/&#39;</code>, and <code>&#39;*&#39;</code>:</p>

<pre><code>-wbb=&quot;+ - / *&quot;</code></pre>

<p>These commands should work well for most of the token types that perltidy uses (use <b>--dump-token-types</b> for a list). Also try the <b>-D</b> flag on a short snippet of code and look at the .DEBUG file to see the tokenization. However, for a f...

<p><b>WARNING</b> Be sure to put these tokens in quotes to avoid having them misinterpreted by your command shell.</p>

<p>Two additional parameters are available which, though they provide no further capability, can simplify input are:</p>

<p><b>-baao</b> or <b>--break-after-all-operators</b>,</p>

<p><b>-bbao</b> or <b>--break-before-all-operators</b>.</p>

<p>The <b>-baao</b> flag sets the default to be to break after all of the following operators:</p>

<pre><code>% + - * / x != == &gt;= &lt;= =~ !~ &lt; &gt; | &amp; ^ |. &amp;. ^.
= **= += *= &amp;= &lt;&lt;= &amp;&amp;= -= /= |= &gt;&gt;= ||= //= .= %= ^= x= |.= &amp;.= ^.=
. : ? &amp;&amp; || and or err xor</code></pre>

<p>and the <b>-bbao</b> flag sets the default to break before all of these operators. These can be used to define an initial break preference which can be fine-tuned with the <b>--want-break-after</b> and <b>--want-break-before</b> flags. For example...

<dl>

<dt id="bal-n---break-after-labels-n"><b>-bal=n, --break-after-labels=n</b></dt>
<dd>