Perl-Tidy
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. If there are comments after the closing brace where cuddling would occur then cuddling will be prevented. If this occurs, cuddling will restart later in the chain if possible...
</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="sort map grep"</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='else elsif continue' -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="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 '-' )
{
...
}</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 '-' ) {
...
}</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">"Specifying Block Types"</a>. For example, <b>-bll='if elsif else sub'</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">"Specifying Block Types"</a>. For example, the default settings <b>-bll='*'</b> and <b>-blxl='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>
<p>The flag <b>-sbl</b> provides a shortcut way to turn on <b>-bl</b> just for named subs. The same effect can be achieved by turning on <b>-bl</b> with the block list set as <b>-bll='sub'</b>. To avoid conflicts, it is recommended to either ...
<p>For example,</p>
<pre><code> perltidy -sbl</code></pre>
<p>produces this result:</p>
<pre><code> sub message
{
if (!defined($_[0])) {
print("Hello, World\n");
}
else {
print($_[0], "\n");
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->add( mysprintf( "(void)find_threadsv(%s);",
cstring( $threadsv_names[ $op->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, "< $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);
}</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='if elsif else'</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 "stack" opening tokens when possible to avoid lines with isolated opening tokens.</p>
<p>For example:</p>
<pre><code> # 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,
}
);</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='*'</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 "stack" closing tokens when possible to avoid lines with isolated closing tokens.</p>
<p>For example:</p>
<pre><code> # 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,
} );</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->new(
{
binary => 1,
sep_char => $opt_c,
always_quote => 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, "$w1 $w2 $w3 $w4\n" );
} } } }</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 != == >= <= =~ !~ < > | & = **= += *= &= <<= &&= -= /= |= >>= ||= //= .= %= ^= x=</p>
<p>And perltidy breaks <b>before</b> these token types by default: . << >> -> && || //</p>
<p>To illustrate, to cause a break after a concatenation operator, <code>'.'</code>, rather than before it, the command line would be</p>
<pre><code> -wba="."</code></pre>
<p>As another example, the following command would cause a break before math operators <code>'+'</code>, <code>'-'</code>, <code>'/'</code>, and <code>'*'</code>:</p>
<pre><code> -wbb="+ - / *"</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 != == >= <= =~ !~ < > | &
= **= += *= &= <<= &&= -= /= |= >>= ||= //= .= %= ^= x=
. : ? && || 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>
( run in 1.125 second using v1.01-cache-2.11-cpan-0bb4e1dffa6 )