docs/stylekey.html

   1 <?xml version="1.0" ?>
   2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
   3 <html xmlns="http://www.w3.org/1999/xhtml">
   4 <head>
   5 <title></title>
   6 <meta http-equiv="content-type" content="text/html; charset=utf-8" />
   7 <link rev="made" href="mailto:root@localhost" />
   8 </head>
   9
  10 <body>
  11
  12
  13
  14 <ul id="index">
  15   <li><a href="#Perltidy-Style-Key">Perltidy Style Key</a>
  16     <ul>
  17       <li><a href="#Before-You-Start">Before You Start</a></li>
  18       <li><a href="#Use-as-Filter">Use as Filter?</a></li>
  19       <li><a href="#Line-Length-Setting">Line Length Setting</a></li>
  20       <li><a href="#Indentation-in-Code-Blocks">Indentation in Code Blocks</a></li>
  21       <li><a href="#Continuation-Indentation">Continuation Indentation</a></li>
  22       <li><a href="#Tabs">Tabs</a></li>
  23       <li><a href="#Opening-Block-Brace-Right-or-Left">Opening Block Brace Right or Left?</a></li>
  24       <li><a href="#Opening-Braces-Right">Opening Braces Right</a></li>
  25       <li><a href="#Cuddled-Else">Cuddled Else?</a></li>
  26       <li><a href="#Opening-Braces-Left">Opening Braces Left</a></li>
  27       <li><a href="#Opening-Sub-Braces">Opening Sub Braces</a></li>
  28       <li><a href="#Block-Brace-Vertical-Tightness">Block Brace Vertical Tightness</a></li>
  29       <li><a href="#Closing-Block-Brace-Indentation">Closing Block Brace Indentation</a></li>
  30       <li><a href="#Indentation-Style-for-Other-Containers">Indentation Style for Other Containers</a></li>
  31       <li><a href="#Opening-Vertical-Tightness">Opening Vertical Tightness</a></li>
  32       <li><a href="#Closing-Token-Placement">Closing Token Placement</a></li>
  33       <li><a href="#Stack-Opening-Tokens">Stack Opening Tokens</a></li>
  34       <li><a href="#Stack-Closing-Tokens">Stack Closing Tokens</a></li>
  35       <li><a href="#Define-Horizontal-Tightness">Define Horizontal Tightness</a></li>
  36       <li><a href="#Spaces-between-function-names-and-opening-parens">Spaces between function names and opening parens</a></li>
  37       <li><a href="#Spaces-between-Perl-keywords-and-parens">Spaces between Perl keywords and parens</a></li>
  38       <li><a href="#Statement-Termination-Semicolon-Spaces">Statement Termination Semicolon Spaces</a></li>
  39       <li><a href="#For-Loop-Semicolon-Spaces">For Loop Semicolon Spaces</a></li>
  40       <li><a href="#Block-Comment-Indentation">Block Comment Indentation</a></li>
  41       <li><a href="#Outdenting-Long-Quotes">Outdenting Long Quotes</a></li>
  42       <li><a href="#Many-Other-Parameters">Many Other Parameters</a></li>
  43       <li><a href="#Example-.perltidyrc-files">Example .perltidyrc files</a></li>
  44       <li><a href="#Tidyview">Tidyview</a></li>
  45       <li><a href="#Additional-Information">Additional Information</a></li>
  46     </ul>
  47   </li>
  48 </ul>
  49
  50 <h1 id="Perltidy-Style-Key">Perltidy Style Key</h1>
  51
  52 <p>When perltidy was first developed, the main parameter choices were the number of indentation spaces and if the user liked cuddled else&#39;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.</p>
  53
  54 <p>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 <i>.perltidyrc</i> (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</b> to see where these places are for your system.</p>
  55
  56 <h2 id="Before-You-Start">Before You Start</h2>
  57
  58 <p>Before you begin, experiment using just <code>perltidy filename.pl</code> on some of your files. From the results (which you will find in files with a <i>.tdy</i> extension), you will get a sense of what formatting changes, if any, you&#39;d like to make. If the default formatting is acceptable, you do not need a <i>.perltidyrc</i> file.</p>
  59
  60 <h2 id="Use-as-Filter">Use as Filter?</h2>
  61
  62 <p>Do you almost always want to run perltidy as a standard filter on just one input file? If yes, use <b>-st</b> and <b>-se</b>.</p>
  63
  64 <h2 id="Line-Length-Setting">Line Length Setting</h2>
  65
  66 <p>Perltidy will set line breaks to prevent lines from exceeding the maximum line length.</p>
  67
  68 <p>Do you want the maximum line length to be 80 columns? If no, use <b>-l=n</b>, where <b>n</b> is the number of columns you prefer.</p>
  69
  70 <h2 id="Indentation-in-Code-Blocks">Indentation in Code Blocks</h2>
  71
  72 <p>In the block below, the variable <code>$anchor</code> is one indentation level deep and is indented by 4 spaces as shown here:</p>
  73
  74 <pre><code>    if ( $flag eq &quot;a&quot; ) {
  75         $anchor = $header;
  76     }  </code></pre>
  77
  78 <p>If you want to change this to be a different number <b>n</b> of spaces per indentation level, use <b>-i=n</b>.</p>
  79
  80 <h2 id="Continuation-Indentation">Continuation Indentation</h2>
  81
  82 <p>Look at the statement beginning with <code>$anchor</code>:</p>
  83
  84 <pre><code>    if ( $flag eq &quot;a&quot; ) {
  85         $anchor =
  86           substr( $header, 0, 6 )
  87           . substr( $char_list, $place_1, 1 )
  88           . substr( $char_list, $place_2, 1 );
  89     }</code></pre>
  90
  91 <p>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 &quot;continuation indentation&quot; 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</b>. It is probably best if it does not exceed the value of the primary indentation.</p>
  92
  93 <h2 id="Tabs">Tabs</h2>
  94
  95 <p>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</b> spaces, use <b>-et=n</b>. Typically, <b>n</b> would be 8.</p>
  96
  97 <h2 id="Opening-Block-Brace-Right-or-Left">Opening Block Brace Right or Left?</h2>
  98
  99 <p>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.</p>
 100
 101 <p>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</b> which will be covered later):</p>
 102
 103 <p>If you like opening braces on the right, like this, go to <a href="#Opening-Braces-Right">&quot;Opening Braces Right&quot;</a>.</p>
 104
 105 <pre><code>    if ( $flag eq &quot;h&quot; ) {
 106         $headers = 0;
 107     }  </code></pre>
 108
 109 <p>If you like opening braces on the left, like this, go to <a href="#Opening-Braces-Left">&quot;Opening Braces Left&quot;</a>.</p>
 110
 111 <pre><code>    if ( $flag eq &quot;h&quot; )
 112     {
 113         $headers = 0;
 114     }</code></pre>
 115
 116 <h2 id="Opening-Braces-Right">Opening Braces Right</h2>
 117
 118 <p>In a multi-line <b>if</b> test expression, the default is to place the opening brace on the left, like this:</p>
 119
 120 <pre><code>    if ( $bigwasteofspace1 &amp;&amp; $bigwasteofspace2
 121         || $bigwasteofspace3 &amp;&amp; $bigwasteofspace4 )
 122     {
 123         big_waste_of_time();
 124     }</code></pre>
 125
 126 <p>This helps to visually separate the block contents from the test expression.</p>
 127
 128 <p>An alternative is to keep the brace on the right even for multiple-line test expressions, like this:</p>
 129
 130 <pre><code>    if ( $bigwasteofspace1 &amp;&amp; $bigwasteofspace2
 131         || $bigwasteofspace3 &amp;&amp; $bigwasteofspace4 ) {
 132         big_waste_of_time();
 133     }</code></pre>
 134
 135 <p>If you prefer this alternative, use <b>-bar</b>.</p>
 136
 137 <h2 id="Cuddled-Else">Cuddled Else?</h2>
 138
 139 <p>Do you prefer this <b>Cuddled Else</b> style</p>
 140
 141 <pre><code>    if ( $flag eq &quot;h&quot; ) {
 142         $headers = 0;
 143     } elsif ( $flag eq &quot;f&quot; ) {
 144         $sectiontype = 3;
 145     } else {
 146         print &quot;invalid option: &quot; . substr( $arg, $i, 1 ) . &quot;\n&quot;;
 147         dohelp();
 148     }</code></pre>
 149
 150 <p>instead of this default style?</p>
 151
 152 <pre><code>    if ( $flag eq &quot;h&quot; ) {
 153         $headers = 0;
 154     }
 155     elsif ( $flag eq &quot;f&quot; ) {
 156         $sectiontype = 3;
 157     }
 158     else {
 159         print &quot;invalid option: &quot; . substr( $arg, $i, 1 ) . &quot;\n&quot;;
 160         dohelp();
 161     }</code></pre>
 162
 163 <p>If yes, you should use <b>-ce</b>. Now skip ahead to <a href="#Opening-Sub-Braces">&quot;Opening Sub Braces&quot;</a>.</p>
 164
 165 <h2 id="Opening-Braces-Left">Opening Braces Left</h2>
 166
 167 <p>Use <b>-bl</b> if you prefer this style:</p>
 168
 169 <pre><code>    if ( $flag eq &quot;h&quot; )
 170     {
 171         $headers = 0;
 172     }</code></pre>
 173
 174 <p>Use <b>-bli</b> if you prefer this indented-brace style:</p>
 175
 176 <pre><code>    if ( $flag eq &quot;h&quot; )
 177       {
 178         $headers = 0;
 179       }</code></pre>
 180
 181 <p>The number of spaces of extra indentation will be the value specified for continuation indentation with the <b>-ci=n</b> parameter (2 by default).</p>
 182
 183 <h2 id="Opening-Sub-Braces">Opening Sub Braces</h2>
 184
 185 <p>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 <a href="#Block-Brace-Vertical-Tightness">&quot;Block Brace Vertical Tightness&quot;</a>.</p>
 186
 187 <p>If you prefer an opening sub brace to be on a new line, like this:</p>
 188
 189 <pre><code>    sub message
 190     {
 191         # -sbl
 192     }</code></pre>
 193
 194 <p>use <b>-sbl</b>. If you prefer the sub brace on the right like this</p>
 195
 196 <pre><code>    sub message {
 197
 198         # -nsbl
 199     }</code></pre>
 200
 201 <p>use <b>-nsbl</b>.</p>
 202
 203 <p>If you wish to give this opening sub brace some indentation you can do that with the parameters <b>-bli</b> and <b>-blil</b> which are described in the manual.</p>
 204
 205 <h2 id="Block-Brace-Vertical-Tightness">Block Brace Vertical Tightness</h2>
 206
 207 <p>If you chose to put opening block braces of all types to the right, skip ahead to <a href="#Closing-Block-Brace-Indentation">&quot;Closing Block Brace Indentation&quot;</a>.</p>
 208
 209 <p>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</b>, but also true for <b>-bl</b>):</p>
 210
 211 <pre><code>    if ( $flag eq &quot;h&quot; )
 212       {
 213         $headers = 0;
 214       }</code></pre>
 215
 216 <p>But you may also use this more compressed style if you wish:</p>
 217
 218 <pre><code>    if ( $flag eq &quot;h&quot; )
 219       { $headers = 0;
 220       }</code></pre>
 221
 222 <p>If you do not prefer this more compressed form, go to <a href="#Opening-Sub-Braces">&quot;Opening Sub Braces&quot;</a>.</p>
 223
 224 <p>Otherwise use parameter <b>-bbvt=n</b>, where n=1 or n=2. To decide, look at this snippet:</p>
 225
 226 <pre><code>    # -bli -bbvt=1
 227     sub _directives
 228       {
 229         {
 230             &#39;ENDIF&#39; =&gt; \&amp;_endif,
 231                &#39;IF&#39; =&gt; \&amp;_if,
 232         };
 233       }
 234
 235     # -bli -bbvt=2
 236     sub _directives
 237     {   {
 238             &#39;ENDIF&#39; =&gt; \&amp;_endif,
 239             &#39;IF&#39;    =&gt; \&amp;_if,
 240         };
 241     }</code></pre>
 242
 243 <p>The difference is that <b>-bbvt=1</b> breaks after an opening brace if the next line is unbalanced, whereas <b>-bbvt=2</b> never breaks.</p>
 244
 245 <p>If you were expecting the &#39;ENDIF&#39; 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</b> does not apply to it (another parameter will).</p>
 246
 247 <h2 id="Closing-Block-Brace-Indentation">Closing Block Brace Indentation</h2>
 248
 249 <p>The default is to place closing braces at the same indentation as the opening keyword or brace of that code block, as shown here:</p>
 250
 251 <pre><code>        if ($task) {
 252             yyy();
 253         }            # default</code></pre>
 254
 255 <p>If you chose the <b>-bli</b> style, however, the default closing braces will be indented one continuation indentation like the opening brace:</p>
 256
 257 <pre><code>        if ($task)
 258           {
 259             yyy();
 260           }    # -bli</code></pre>
 261
 262 <p>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:</p>
 263
 264 <pre><code>        if ($task) {
 265             yyy();
 266             }          # -icb</code></pre>
 267
 268 <p>use <b>-icb</b>.</p>
 269
 270 <p>This completes the definition of the placement of code block braces.</p>
 271
 272 <h2 id="Indentation-Style-for-Other-Containers">Indentation Style for Other Containers</h2>
 273
 274 <p>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:</p>
 275
 276 <pre><code>    $dbh = DBI-&gt;connect(
 277         undef, undef, undef,
 278         {
 279             PrintError =&gt; 0,
 280             RaiseError =&gt; 1
 281         }
 282     );</code></pre>
 283
 284 <p>In this default indentation scheme, a simple formula is used to find the indentation of every line. Notice how the first &#39;undef&#39; is indented 4 spaces (one level) to the right, and how &#39;PrintError&#39; is indented 4 more speces (one more level) to the right.</p>
 285
 286 <p>The alternate is to let the location of the opening paren (or square bracket, or curly brace) define the indentation, like this:</p>
 287
 288 <pre><code>    $dbh = DBI-&gt;connect(
 289                          undef, undef, undef,
 290                          {
 291                            PrintError =&gt; 0,
 292                            RaiseError =&gt; 1
 293                          }
 294     );</code></pre>
 295
 296 <p>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.</p>
 297
 298 <p>If you prefer the first (default) scheme, no parameter is needed.</p>
 299
 300 <p>If you prefer the latter scheme, use <b>-lp</b>.</p>
 301
 302 <h2 id="Opening-Vertical-Tightness">Opening Vertical Tightness</h2>
 303
 304 <p>The information in this section applies mainly to the <b>-lp</b> style but it also applies in some cases to the default style. It will be illustrated for the <b>-lp</b> indentation style.</p>
 305
 306 <p>The default <b>-lp</b> indentation style ends a line at the opening tokens, like this:</p>
 307
 308 <pre><code>    $dbh = DBI-&gt;connect(
 309                          undef, undef, undef,
 310                          {
 311                            PrintError =&gt; 0,
 312                            RaiseError =&gt; 1
 313                          }
 314     );</code></pre>
 315
 316 <p>Here is a tighter alternative, which does not end a line with the opening tokens:</p>
 317
 318 <pre><code>    $dbh = DBI-&gt;connect( undef, undef, undef,
 319                          { PrintError =&gt; 0,
 320                            RaiseError =&gt; 1
 321                          }
 322     );</code></pre>
 323
 324 <p>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</b> indentation style, but only in limited cases for the default indentation style.</p>
 325
 326 <p>If you prefer the default, skip ahead to <a href="#Closing-Token-Placement">&quot;Closing Token Placement&quot;</a>.</p>
 327
 328 <p>Otherwise, use <b>-vt=n</b>, where <b>n</b> 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</b>:</p>
 329
 330 <pre><code>    if (
 331          !defined(
 332                    start_slip( $DEVICE, $PHONE,  $ACCOUNT, $PASSWORD,
 333                                $LOCAL,  $REMOTE, $NETMASK, $MTU
 334                    )
 335          )
 336          &amp;&amp; $continuation_flag
 337       )
 338     {
 339         do_something_about_it();
 340     }</code></pre>
 341
 342 <p>And here it is again formatted with <b>-lp -vt=2</b>:</p>
 343
 344 <pre><code>    if ( !defined( start_slip( $DEVICE, $PHONE,  $ACCOUNT, $PASSWORD,
 345                                $LOCAL,  $REMOTE, $NETMASK, $MTU
 346                    )
 347          )
 348          &amp;&amp; $continuation_flag
 349       )
 350     {
 351         do_something_about_it();
 352     }</code></pre>
 353
 354 <p>The <b>-vt=1</b> 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</b> broke after them.</p>
 355
 356 <p>The <b>-vt=2</b> style does not limit itself to a single indentation step per line.</p>
 357
 358 <p>Note that in the above example the function &#39;do_sumething_about_it&#39; started on a new line. This is because it follows an opening code block brace and is governed by the flag previously set in <a href="#Block-Brace-Vertical-Tightness">&quot;Block Brace Vertical Tightness&quot;</a>.</p>
 359
 360 <h2 id="Closing-Token-Placement">Closing Token Placement</h2>
 361
 362 <p>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.</p>
 363
 364 <p>The default behavior for parenthesized relatively large lists is to place the closing paren on a separate new line. The flag <b>-cti=n</b> controls the amount of indentation of such a closing paren.</p>
 365
 366 <p>The default, <b>-cti=0</b>, 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:</p>
 367
 368 <pre><code>    # perltidy
 369     @month_of_year = (
 370         &#39;Jan&#39;, &#39;Feb&#39;, &#39;Mar&#39;, &#39;Apr&#39;, &#39;May&#39;, &#39;Jun&#39;,
 371         &#39;Jul&#39;, &#39;Aug&#39;, &#39;Sep&#39;, &#39;Oct&#39;, &#39;Nov&#39;, &#39;Dec&#39;
 372     );</code></pre>
 373
 374 <p>but it may not look very good with the <b>-lp</b> indentation scheme:</p>
 375
 376 <pre><code>    # perltidy -lp
 377     @month_of_year = (
 378                        &#39;Jan&#39;, &#39;Feb&#39;, &#39;Mar&#39;, &#39;Apr&#39;, &#39;May&#39;, &#39;Jun&#39;,
 379                        &#39;Jul&#39;, &#39;Aug&#39;, &#39;Sep&#39;, &#39;Oct&#39;, &#39;Nov&#39;, &#39;Dec&#39;
 380     );</code></pre>
 381
 382 <p>An alternative which works well with <b>-lp</b> indentation is <b>-cti=1</b>, which aligns the closing paren vertically with its opening paren, if possible:</p>
 383
 384 <pre><code>    # perltidy -lp -cti=1
 385     @month_of_year = (
 386                        &#39;Jan&#39;, &#39;Feb&#39;, &#39;Mar&#39;, &#39;Apr&#39;, &#39;May&#39;, &#39;Jun&#39;,
 387                        &#39;Jul&#39;, &#39;Aug&#39;, &#39;Sep&#39;, &#39;Oct&#39;, &#39;Nov&#39;, &#39;Dec&#39;
 388                      );</code></pre>
 389
 390 <p>Another alternative, <b>-cti=3</b>, indents a line with leading closing paren one full indentation level:</p>
 391
 392 <pre><code>    # perltidy -lp -cti=3
 393     @month_of_year = (
 394                        &#39;Jan&#39;, &#39;Feb&#39;, &#39;Mar&#39;, &#39;Apr&#39;, &#39;May&#39;, &#39;Jun&#39;,
 395                        &#39;Jul&#39;, &#39;Aug&#39;, &#39;Sep&#39;, &#39;Oct&#39;, &#39;Nov&#39;, &#39;Dec&#39;
 396                        );</code></pre>
 397
 398 <p>If you prefer the closing paren on a separate line like this, note the value of <b>-cti=n</b> that you prefer and skip ahead to <a href="#Define-Horizontal-Tightness">&quot;Define Horizontal Tightness&quot;</a>.</p>
 399
 400 <p>Finally, the question of paren indentation can be avoided by placing it at the end of the previous line, like this:</p>
 401
 402 <pre><code>    @month_of_year = (
 403         &#39;Jan&#39;, &#39;Feb&#39;, &#39;Mar&#39;, &#39;Apr&#39;, &#39;May&#39;, &#39;Jun&#39;,
 404         &#39;Jul&#39;, &#39;Aug&#39;, &#39;Sep&#39;, &#39;Oct&#39;, &#39;Nov&#39;, &#39;Dec&#39; );</code></pre>
 405
 406 <p>Perltidy will automatically do this to save space for very short lists but not for longer lists.</p>
 407
 408 <p>Use <b>-vtc=n</b> if you prefer to usually do this, where <b>n</b> is either 1 or 2. To determine <b>n</b>, we have to look at something more complex. Observe the behavior of the closing tokens in the following snippet:</p>
 409
 410 <p>Here is <b>-lp -vtc=1</b>:</p>
 411
 412 <pre><code>    $srec-&gt;{&#39;ACTION&#39;} = [
 413                           $self-&gt;read_value(
 414                                              $lookup-&gt;{&#39;VFMT&#39;},
 415                                              $loc, $lookup, $fh
 416                           ),
 417                           $self-&gt;read_value(
 418                                              $lookup-&gt;{&#39;VFMT2&#39;},
 419                                              $loc, $lookup, $fh
 420                           ) ];</code></pre>
 421
 422 <p>Here is <b>-lp -vtc=2</b>:</p>
 423
 424 <pre><code>    $srec-&gt;{&#39;ACTION&#39;} = [
 425                           $self-&gt;read_value(
 426                                              $lookup-&gt;{&#39;VFMT&#39;},
 427                                              $loc, $lookup, $fh ),
 428                           $self-&gt;read_value(
 429                                              $lookup-&gt;{&#39;VFMT2&#39;},
 430                                              $loc, $lookup, $fh ) ];</code></pre>
 431
 432 <p>Choose the one that you prefer. The difference is that <b>-vtc=1</b> leaves closing tokens at the start of a line within a list, which can assist in keeping hierarchical lists readable. The <b>-vtc=2</b> style always tries to move closing tokens to the end of a line.</p>
 433
 434 <p>If you choose <b>-vtc=1</b>, you may also want to specify a value of <b>-cti=n</b> (previous section) to handle cases where a line begins with a closing paren.</p>
 435
 436 <h2 id="Stack-Opening-Tokens">Stack Opening Tokens</h2>
 437
 438 <p>In the following snippet the opening hash brace has been placed alone on a new line.</p>
 439
 440 <pre><code>    $opt_c = Text::CSV_XS-&gt;new(
 441         {
 442             binary       =&gt; 1,
 443             sep_char     =&gt; $opt_c,
 444             always_quote =&gt; 1,
 445         }
 446     );</code></pre>
 447
 448 <p>If you prefer to avoid isolated opening tokens by &quot;stacking&quot; them together with other opening tokens like this:</p>
 449
 450 <pre><code>    $opt_c = Text::CSV_XS-&gt;new( {
 451             binary       =&gt; 1,
 452             sep_char     =&gt; $opt_c,
 453             always_quote =&gt; 1,
 454         }
 455     );</code></pre>
 456
 457 <p>use <b>-sot</b>.</p>
 458
 459 <h2 id="Stack-Closing-Tokens">Stack Closing Tokens</h2>
 460
 461 <p>Likewise, in the same snippet the default formatting leaves the closing paren on a line by itself here:</p>
 462
 463 <pre><code>    $opt_c = Text::CSV_XS-&gt;new(
 464         {
 465             binary       =&gt; 1,
 466             sep_char     =&gt; $opt_c,
 467             always_quote =&gt; 1,
 468         }
 469     );</code></pre>
 470
 471 <p>If you would like to avoid leaving isolated closing tokens by stacking them with other closing tokens, like this:</p>
 472
 473 <pre><code>    $opt_c = Text::CSV_XS-&gt;new(
 474         {
 475             binary       =&gt; 1,
 476             sep_char     =&gt; $opt_c,
 477             always_quote =&gt; 1,
 478         } );</code></pre>
 479
 480 <p>use <b>-sct</b>.</p>
 481
 482 <p>The <b>-sct</b> flag is somewhat similar to the <b>-vtc</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 &quot;hiding&quot; them at the end of a previous line, whereas the <b>-sct</b> 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.</p>
 483
 484 <p>The manual shows how all of these vertical tightness controls may be applied independently to each type of non-block opening and opening token.</p>
 485
 486 <h2 id="Define-Horizontal-Tightness">Define Horizontal Tightness</h2>
 487
 488 <p>Horizontal tightness parameters define how much space is included within a set of container tokens.</p>
 489
 490 <p>For parentheses, decide which of the following values of <b>-pt=n</b> you prefer:</p>
 491
 492 <pre><code> if ( ( my $len_tab = length( $tabstr ) ) &gt; 0 ) {  # -pt=0
 493  if ( ( my $len_tab = length($tabstr) ) &gt; 0 ) {    # -pt=1 (default)
 494  if ((my $len_tab = length($tabstr)) &gt; 0) {        # -pt=2</code></pre>
 495
 496 <p>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.</p>
 497
 498 <p>For square brackets, decide which of the following values of <b>-sbt=n</b> you prefer:</p>
 499
 500 <pre><code> $width = $col[ $j + $k ] - $col[ $j ];  # -sbt=0
 501  $width = $col[ $j + $k ] - $col[$j];    # -sbt=1 (default)
 502  $width = $col[$j + $k] - $col[$j];      # -sbt=2 </code></pre>
 503
 504 <p>For curly braces, decide which of the following values of <b>-bt=n</b> you prefer:</p>
 505
 506 <pre><code> $obj-&gt;{ $parsed_sql-&gt;{ &#39;table&#39; }[0] };    # -bt=0
 507  $obj-&gt;{ $parsed_sql-&gt;{&#39;table&#39;}[0] };      # -bt=1 (default)
 508  $obj-&gt;{$parsed_sql-&gt;{&#39;table&#39;}[0]};        # -bt=2</code></pre>
 509
 510 <p>For code block curly braces, decide which of the following values of <b>-bbt=n</b> you prefer:</p>
 511
 512 <pre><code> %bf = map { $_ =&gt; -M $_ } grep { /\.deb$/ } dirents &#39;.&#39;; # -bbt=0 (default)
 513  %bf = map { $_ =&gt; -M $_ } grep {/\.deb$/} dirents &#39;.&#39;;   # -bbt=1
 514  %bf = map {$_ =&gt; -M $_} grep {/\.deb$/} dirents &#39;.&#39;;     # -bbt=2</code></pre>
 515
 516 <h2 id="Spaces-between-function-names-and-opening-parens">Spaces between function names and opening parens</h2>
 517
 518 <p>The default is not to place a space after a function call:</p>
 519
 520 <pre><code>  myfunc( $a, $b, $c );    # default </code></pre>
 521
 522 <p>If you prefer a space:</p>
 523
 524 <pre><code>  myfunc ( $a, $b, $c );   # -sfp</code></pre>
 525
 526 <p>use <b>-sfp</b>.</p>
 527
 528 <h2 id="Spaces-between-Perl-keywords-and-parens">Spaces between Perl keywords and parens</h2>
 529
 530 <p>The default is to place a space between only these keywords and an opening paren:</p>
 531
 532 <pre><code>   my local our and or eq ne if else elsif until unless
 533    while for foreach return switch case given when</code></pre>
 534
 535 <p>but no others. For example, the default is:</p>
 536
 537 <pre><code>    $aa = pop(@bb);</code></pre>
 538
 539 <p>If you want a space between all Perl keywords and an opening paren,</p>
 540
 541 <pre><code>    $aa = pop (@bb);</code></pre>
 542
 543 <p>use <b>-skp</b>. For detailed control of individual keywords, see the manual.</p>
 544
 545 <h2 id="Statement-Termination-Semicolon-Spaces">Statement Termination Semicolon Spaces</h2>
 546
 547 <p>The default is not to put a space before a statement termination semicolon, like this:</p>
 548
 549 <pre><code>    $i = 1;</code></pre>
 550
 551 <p>If you prefer a space, like this:</p>
 552
 553 <pre><code>    $i = 1 ; </code></pre>
 554
 555 <p>enter <b>-sts</b>.</p>
 556
 557 <h2 id="For-Loop-Semicolon-Spaces">For Loop Semicolon Spaces</h2>
 558
 559 <p>The default is to place a space before a semicolon in a for statement, like this:</p>
 560
 561 <pre><code> for ( @a = @$ap, $u = shift @a ; @a ; $u = $v ) {  # -sfs (default)</code></pre>
 562
 563 <p>If you prefer no such space, like this:</p>
 564
 565 <pre><code> for ( @a = @$ap, $u = shift @a; @a; $u = $v ) {    # -nsfs</code></pre>
 566
 567 <p>enter <b>-nsfs</b>.</p>
 568
 569 <h2 id="Block-Comment-Indentation">Block Comment Indentation</h2>
 570
 571 <p>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).</p>
 572
 573 <p>If you would like block comments indented except when this would cause the maximum line length to be exceeded, use <b>-olc</b>. 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.</p>
 574
 575 <p>If you never want block comments indented, use <b>-nibc</b>.</p>
 576
 577 <p>If block comments may only be indented if they have some space characters before the leading <code>#</code> character in the input file, use <b>-isbc</b>.</p>
 578
 579 <p>The manual shows many other options for controlling comments.</p>
 580
 581 <h2 id="Outdenting-Long-Quotes">Outdenting Long Quotes</h2>
 582
 583 <p>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:</p>
 584
 585 <pre><code>        if ($source_stream) {
 586             if ( @ARGV &gt; 0 ) {
 587                 die
 588  &quot;You may not specify any filenames when a source array is given\n&quot;;
 589             }
 590         }</code></pre>
 591
 592 <p>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:</p>
 593
 594 <pre><code>        if ($source_stream) {
 595             if ( @ARGV &gt; 0 ) {
 596                 die
 597                   &quot;You may not specify any filenames when a source array is given\n&quot;;
 598             }
 599         }</code></pre>
 600
 601 <p>use <b>-nolq</b>.</p>
 602
 603 <h2 id="Many-Other-Parameters">Many Other Parameters</h2>
 604
 605 <p>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.</p>
 606
 607 <h2 id="Example-.perltidyrc-files">Example <i>.perltidyrc</i> files</h2>
 608
 609 <p>Now gather together all of the parameters you prefer and enter them in a file called <i>.perltidyrc</i>.</p>
 610
 611 <p>Here are some example <i>.perltidyrc</i> files and the corresponding style.</p>
 612
 613 <p>Here is a little test snippet, shown the way it would appear with the default style.</p>
 614
 615 <pre><code>    for (@methods) {
 616         push (
 617             @results,
 618             {
 619                 name =&gt; $_-&gt;name,
 620                 help =&gt; $_-&gt;help,
 621             }
 622         );
 623     }</code></pre>
 624
 625 <p>You do not need a <i>.perltidyrc</i> file for this style.</p>
 626
 627 <p>Here is the same snippet</p>
 628
 629 <pre><code>    for (@methods)
 630     {
 631         push(@results,
 632              {  name =&gt; $_-&gt;name,
 633                 help =&gt; $_-&gt;help,
 634              }
 635             );
 636     }</code></pre>
 637
 638 <p>for a <i>.perltidyrc</i> file containing these parameters:</p>
 639
 640 <pre><code> -bl
 641  -lp
 642  -cti=1
 643  -vt=1
 644  -pt=2</code></pre>
 645
 646 <p>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 <code>#</code> symbol before it.</p>
 647
 648 <p>And here is the snippet</p>
 649
 650 <pre><code>    for (@methods) {
 651         push ( @results,
 652                { name =&gt; $_-&gt;name,
 653                  help =&gt; $_-&gt;help,
 654                } );
 655     }</code></pre>
 656
 657 <p>for a <i>.perltidyrc</i> file containing these parameters:</p>
 658
 659 <pre><code> -lp
 660  -vt=1
 661  -vtc=1</code></pre>
 662
 663 <h2 id="Tidyview">Tidyview</h2>
 664
 665 <p>There is a graphical program called <b>tidyview</b> which you can use to read a preliminary <i>.perltidyrc</i> file, make trial adjustments and immediately see their effect on a test file, and then write a new <i>.perltidyrc</i>. You can download a copy at</p>
 666
 667 <p>http://sourceforge.net/projects/tidyview</p>
 668
 669 <h2 id="Additional-Information">Additional Information</h2>
 670
 671 <p>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</p>
 672
 673 <p>For an introduction to using perltidy, see the tutorial http://perltidy.sourceforge.net/tutorial.html</p>
 674
 675 <p>Suggestions for improving this document are welcome and may be sent to perltidy at users.sourceforge.net</p>
 676
 677
 678 </body>
 679
 680 </html>
 681
 682