<p>If the path contains spaces, it should be placed in quotes.</p>
-<p>This parameter will be ignored if output is being directed to standard output, or if it is being specified explicitly with the <b>-outfile=s</b> parameter.</p>
+<p>This parameter will be ignored if output is being directed to standard output, or if it is being specified explicitly with the <b>--outfile=s</b> parameter.</p>
</dd>
<dt id="b---backup-and-modify-in-place"><b>-b</b>, <b>--backup-and-modify-in-place</b></dt>
<p>A <b>-b</b> flag will be ignored if input is from standard input or goes to standard output, or if the <b>-html</b> flag is set.</p>
-<p>In particular, if you want to use both the <b>-b</b> flag and the <b>--perl-best-practices</b> (<b>-pbp</b>) flag, then you must put a <b>-nostandard-output</b> (<b>-nst</b>) flag after the <b>-pbp</b> flag because it contains a <b>--standard-output</b> flag as one of its components, which means that output will go to the standard output stream.</p>
+<p>In particular, if you want to use both the <b>-b</b> flag and the <b>--perl-best-practices</b> (<b>-pbp</b>) flag, then you must put a <b>--nostandard-output</b> (<b>-nst</b>) flag after the <b>-pbp</b> flag because it contains a <b>--standard-output</b> flag as one of its components, which means that output will go to the standard output stream.</p>
</dd>
<dt id="bext-ext---backup-file-extension-ext"><b>-bext</b>=ext, <b>--backup-file-extension</b>=ext</dt>
<p>If <b>--format=tidy</b> (the default) then perltidy will reformat the input file, and if <b>--format=html</b> then perltidy will produce html output.</p>
-<p>For convenience, the abbreviation <b>--tidy</b> is equivalent to <b>--format=tidy</b>, and <b>--html</b> is equivalent to <b>--format=html</b>.</p>
+<p>For convenience, the abbreviation <b>--tidy</b> is equivalent to <b>--format=tidy</b>, and <b>-html</b> is equivalent to <b>--format=html</b>.</p>
</dd>
<dt id="notidy"><b>--notidy</b></dt>
<li><p>A limitation on <b>-lp</b>, but not <b>-xlp</b>, occurs in situations where perltidy does not have complete freedom to choose line breaks. Then it may temporarily revert to its default indentation method. This can occur for example if there are blank lines, block comments, multiline quotes, or side comments between the opening and closing parens, braces, or brackets. It will also occur if a multiline anonymous sub occurs within a container since that will impose specific line breaks (such as line breaks after statements).</p>
</li>
-<li><p>For both the <b>-lp</b> and <b>-xlp</b> flags, any parameter which significantly restricts the ability of perltidy to choose newlines will conflict with these flags and will cause them to be deactivated. These include <b>--indent-only</b>, <b>--freeze-newlines</b>, <b>-noadd-newlines</b>, and <b>-nodelete-old-newlines</b>.</p>
+<li><p>For both the <b>-lp</b> and <b>-xlp</b> flags, any parameter which significantly restricts the ability of perltidy to choose newlines will conflict with these flags and will cause them to be deactivated. These include <b>--indent-only</b>, <b>--freeze-newlines</b>, <b>--noadd-newlines</b>, and <b>--nodelete-old-newlines</b>.</p>
</li>
<li><p>The <b>-lp</b> and <b>-xlp</b> options may not be used together with the <b>-t</b> tabs option. They may, however, be used with the <b>-et=n</b> tab method</p>
<p>The default is not to do this, indicated by <b>-nicb</b>.</p>
+</dd>
+<dt id="ils---indent-leading-semicolon"><b>-ils</b>, <b>--indent-leading-semicolon</b></dt>
+<dd>
+
+<p>A line which begins with a leading semicolon will, by default, have the extra number of indentation spaces defined by <b>--continuation-indentation=n</b>. This extra indentation can be removed by setting <b>-nils</b>.</p>
+
+<pre><code> # default
+ $z = sqrt( $x**2 + $y**2 )
+
+ ; # <-- indented by ci spaces
+
+ # -nils
+ $z = sqrt( $x**2 + $y**2 )
+
+ ; # <-- not indented by ci spaces</code></pre>
+
+<p>Note that leading semicolons do not normally occur unless requested with <b>--break-at-old-semicolon-breakpoints</b> or forced, for example by a blank line as in this example.</p>
+
</dd>
<dt id="nib---non-indenting-braces"><b>-nib</b>, <b>--non-indenting-braces</b></dt>
<dd>
<dt id="xbt---extended-block-tightness"><b>-xbt</b>, <b>--extended-block-tightness</b></dt>
<dd>
-<p>The previous section described two controls for spacing within curly braces, namely <b>-block-brace-tightness=n</b> for code block braces and <b>-brace-tightness=n</b> for all other braces.</p>
+<p>The previous section described two controls for spacing within curly braces, namely <b>--block-brace-tightness=n</b> for code block braces and <b>--brace-tightness=n</b> for all other braces.</p>
<p>There is a little fuzziness in this division of brace types though because the curly braces considered by perltidy to contain code blocks for formatting purposes, such as highlighting code structure, exclude some of the small code blocks used by Perl mainly for isolating terms. These include curly braces following a keyword where an indirect object might occur, or curly braces following a type symbol. For example, perltidy does not mark the following braces as code block braces:</p>
<dt id="fnl---freeze-newlines"><b>-fnl</b>, <b>--freeze-newlines</b></dt>
<dd>
-<p>If you do not want any changes to the line breaks within lines of code in your script, set <b>-fnl</b>, and they will remain fixed, and the rest of the commands in this section and sections <a href="#Controlling-List-Formatting">"Controlling List Formatting"</a>, <a href="#Retaining-or-Ignoring-Existing-Line-Breaks">"Retaining or Ignoring Existing Line Breaks"</a>. You may want to use <b>-nooutdent-long-lines</b> with this.</p>
+<p>If you do not want any changes to the line breaks within lines of code in your script, set <b>-fnl</b>, and they will remain fixed, and the rest of the commands in this section and sections <a href="#Controlling-List-Formatting">"Controlling List Formatting"</a>, <a href="#Retaining-or-Ignoring-Existing-Line-Breaks">"Retaining or Ignoring Existing Line Breaks"</a>. You may want to use <b>--nooutdent-long-lines</b> with this.</p>
<p>Note: If you also want to keep your blank lines exactly as they are, you can use the <b>--freeze-blank-lines</b> flag which is described in the section <a href="#Blank-Line-Control">"Blank Line Control"</a>.</p>
# -nce (default)
if ($task) {
- yyy();
+ yyy();
}
else {
- zzz();
+ zzz();
}</code></pre>
<p>In this example the keyword <b>else</b> is placed on the same line which begins with the preceding closing block brace and is followed by its own opening block brace on the same line. Other keywords and function names which are formatted with this "cuddled" style are <b>elsif</b>, <b>continue</b>, <b>catch</b>, <b>finally</b>.</p>
<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 type sort, map and grep, in addition to the default types, the string could be set to</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 type sort, map and grep, in addition to the default types, the string could be set to</p>
<pre><code> -cbl="sort map grep"</code></pre>
<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 previous section. For example, to avoid using cuddled <b>catch</b> and <b>finally</b>, which are among the defaults, the following set of parameters could be used:</p>
+<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 previous section. For example, to avoid using cuddled <b>catch</b> and <b>finally</b>, which are among the defaults, the following set of parameters could be used:</p>
<pre><code> perltidy -ce -cbl='else elsif continue' -cblx</code></pre>
...
}</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>
+<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>
<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 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</b> and <b>--stack-closing-tokens</b> flags do.</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 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</b> and <b>--stack-closing-tokens</b> flags do.</p>
</dd>
</dl>
= **= += *= &= <<= &&= -= /= |= >>= ||= //= .= %= ^= 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, to break before all operators except an <b>=</b> one could use <code>--bbao -wba='='</code> rather than listing every single perl operator except <b>=</b> on a <b>-wbb</b> flag.</p>
+<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, to break before all operators except an <b>=</b> one could use <code>-bbao -wba='='</code> rather than listing every single perl operator except <b>=</b> on a <b>-wbb</b> flag.</p>
<dl>
'g', Canvas => $overview_canvas
);</code></pre>
-<p>formatting with <code>-wtc=f(b) -atc</code> will not add a trailing comma because the list will be flattend and the comma will not remain bare. But we can add a trailing comma, and keep the container open, with</p>
+<p>formatting with <code>-wtc=f(b) -atc</code> will not add a trailing comma because the list will be flattened and the comma will not remain bare. But we can add a trailing comma, and keep the container open, with</p>
<pre><code> # perltidy -wtc='f(b' -atc -btct='f(b'
plot(
'track.id' => { -ident => 'none_search.id' },
} )->as_query;</code></pre>
-<p>You may want to include the <b>-weld-nested-containers</b> flag in this case to keep nested braces and parens together, as in the last line.</p>
+<p>You may want to include the <b>--weld-nested-containers</b> flag in this case to keep nested braces and parens together, as in the last line.</p>
</dd>
<dt id="bos---break-at-old-semicolon-breakpoints"><b>-bos</b>, <b>--break-at-old-semicolon-breakpoints</b></dt>
<pre><code> $z = sqrt( $x**2 + $y**2 );</code></pre>
-<p>The result using <b>perltidy -bos</b> keeps the isolated semicolon:</p>
+<p>Using the <-bos> flag keeps the isolated semicolon:</p>
-<pre><code> $z = sqrt( $x**2 + $y**2 )
+<pre><code> # perltidy -bos
+ $z = sqrt( $x**2 + $y**2 )
;</code></pre>
+<p>The extra continuation indentation spaces on the semicolon can be removed by also setting <b>--noindent-leading-semicolon</b>.</p>
+
+<pre><code> # perltidy -bos -nils
+ $z = sqrt( $x**2 + $y**2 )
+ ;</code></pre>
+
<p>The default is not to do this, <b>-nbos</b>.</p>
</dd>
<dt id="Forming-new-one-line-blocks"><b>Forming new one-line blocks</b></dt>
<dd>
-<p>Sometimes it might be desirable to convert a script to have one-line blocks whenever possible. Although there is currently no flag for this, a simple workaround is to execute perltidy twice, once with the flag <b>-noadd-newlines</b> and then once again with normal parameters, like this:</p>
+<p>Sometimes it might be desirable to convert a script to have one-line blocks whenever possible. Although there is currently no flag for this, a simple workaround is to execute perltidy twice, once with the flag <b>--noadd-newlines</b> and then once again with normal parameters, like this:</p>
<pre><code> cat infile | perltidy -nanl | perltidy >outfile</code></pre>
<p>There is no automatic way to break existing long one-line blocks into multiple lines, but this can be accomplished by processing a script, or section of a script, with a short value of the parameter <b>maximum-line-length=n</b>. Then, when the script is reformatted again with the normal parameters, the blocks which were broken will remain broken (with the exceptions noted above).</p>
-<p>Another trick for doing this for certain block types is to format one time with the <b>-cuddled-else</b> flag and <b>--cuddled-break-option=2</b>. Then format again with the normal parameters. This will break any one-line blocks which are involved in a cuddled-else style.</p>
+<p>Another trick for doing this for certain block types is to format one time with the <b>--cuddled-else</b> flag and <b>--cuddled-break-option=2</b>. Then format again with the normal parameters. This will break any one-line blocks which are involved in a cuddled-else style.</p>
</dd>
</dl>
<p>The following flags are available for debugging. Note that all commands named <b>--dump-...</b> will simply write some requested information to standard output and then immediately exit.</p>
-<p><b>--dump-cuddled-block-list</b> or <b>-dcbl</b> will dump to standard output the internal hash of cuddled block types created by a <b>-cuddled-block-list</b> input string.</p>
+<p><b>--dump-cuddled-block-list</b> or <b>-dcbl</b> will dump to standard output the internal hash of cuddled block types created by a <b>--cuddled-block-list</b> input string.</p>
<p><b>--dump-defaults</b> or <b>-ddf</b> will write the default option set to standard output and quit</p>
$self->gnab_gib(42);</code></pre>
-<p>In this case, the sub is expecting a total of three args (<code>$self</code>, <code>$v1</code>, and <code>$v2</code>) but only receives two (<code>$self</code> and <code>42</code>), so an undercount is reported. This is not necessarily an error because the sub may allow for this possibility, but it is worth checking. The simple static processing done by perltidy cannot determine which sub args are optional.</p>
+<p>In this case, the sub is expecting a total of three args (<code>$self</code>, <code>$v1</code>, and <code>$v2</code>) but only receives two (<code>$self</code> and <code>42</code>), so an undercount is reported. This is not necessarily an error because the sub may allow for this possibility, but it is worth checking.</p>
+
+<p>Although it is not possible to automatically determine which sub args are optional, if optional sub args are enclosed in an extra set of parentheses, perltidy will take this a signal that they are optional and not issue a warning. So if the above example is written as</p>
+
+<pre><code> sub gnab_gib {
+ my $self = shift;
+ my ( $v1, ($v2) ) = @_; # <-- extra parens on $v2 indicate optional
+ ...;
+ }</code></pre>
+
+<p>then perltidy will consider that the second arg is optional and not issue a warning for:</p>
+
+<pre><code> $self->gnab_gib(42);</code></pre>
+
+<p>For multiple default call args, place one set of parens around them all. Some examples:</p>
+
+<pre><code> my ( $v1, ( $v2, $v3 ) ) = @_; # <-- $v2 and $v3 are optional
+ my ( ($v1) ) = @_; # <-- $v1 is optional</code></pre>
</dd>
<dt id="i:-indeterminate:-a-specific-number-of-expected-args-for-a-sub-could-not-be-determined-but-it-is-called-with-a-specific-number.-This-issue-is-reported-for-the---dump--option-but-not-the---warn--option"><b>i:</b> <b>indeterminate:</b> a specific number of expected args for a sub could not be determined, but it is called with a specific number. This issue is reported for the <b>--dump-</b> option but not the <b>--warn-</b> option.</dt>
<p>The default value is <b>n=4</b>. This has been found to allow most programs to pass without warnings, but it should be reduced if possible for better error checking. The minimum possible value of <b>n</b> needed to avoid triggering an error for a program can be determined by running with <b>-wma -wmauc=0</b>. If there are undercount errors, a note at the bottom of the error output indicates the value of <b>n</b> required to avoid reporting them.</p>
+<p>As noted above for the parameter <b>--dump-mismatched-args</b>, if optional call args are enclosed in separate parentheses, then perltidy will recognize them as optional args and avoid needless warnings. If this method is used, then <b>-wmauc=0</b> should be used for maximal checking.</p>
+
</li>
<li><p><b>--warn-mismatched-arg-overcount-cutoff=n</b>, or <b>-wmaoc=n</b>, can be used to avoid <b>overcount</b> warnings when the expected number of args is less than <b>n</b>. The default value is <b>n=1</b>. This avoids warning messages for subroutines which are dummy placeholders for possible expansion.</p>
<h1 id="VERSION">VERSION</h1>
-<p>This man page documents perltidy version 20240903.06</p>
+<p>This man page documents perltidy version 20240903.07</p>
<h1 id="BUG-REPORTS">BUG REPORTS</h1>
projects / perltidy.git / commitdiff