=item B<-btct=s>, B<--break-at-trailing-comma-types=s>
-A trailing comma is an optional comma following the last item of a list.
-The B<-btct=s> tells perltidy to end a line at selected B<trailing commas>.
+A B<trailing comma> is an optional comma following the last item of a list.
+The B<-btct=s> tells perltidy to end a line at selected trailing commas.
The string B<s> selects the trailing commas, as follows:
s=1 or '*' : every trailing comma
'<Page_Down>' => xx,
);
-Afterwards, we could switch to B<btct=b> since the trailing comma is
-now bare. But the B<-btct> parameter must be retained in this case because
-otherwise perltidy will by default flatten this small list.
+Afterwards, we could switch to B<btct=b> since the trailing comma is now bare.
+But the B<-btct> parameter must be retained in this case because otherwise this
+small list will be flattened the next time it is formatted.
-It is possible restrict the application of this logic to specific container
-types by including an opening token ahead of the letter in the above table.
-For example
+This logic can be restricted to specific container types by including an
+opening token ahead of the letter in the above table. For example
-btct='(b'
-means that this operation should only apply to lists within parens with
-trailing commas.
+means that this operation should only apply to bare trailing commas within
+parentheses.
For parentheses, an additional item of information which can be given is an
alphanumeric letter which is used to limit the selection further depending on
should be followed by line breaks in the formatted output stream.
The section L<"Adding and Deleting Commas"> describes additional controls for
-working with trailing commas, and which can be combined with the
-B<-break-trailing-comma-types> parameter to control list formatting.
+working with trailing commas. These can be combined with the
+B<-break-trailing-comma-types> parameter for additional control of list
+formatting.
=item B<-mft=n>, B<--maximum-fields-per-table=n>
if only one iteration is made, which is the default.
When iterations are requested with the B<--converge> parameter, any comma
-addition or deletion operations are postponed until the start of the
-B<second iteration>, after most changes in line breaks have been made.
+deletion operations are postponed until the start of the B<second iteration>,
+after most changes in line breaks have been made.
To illustrate, if we start with
'g', Canvas => $overview_canvas
);
-we can add a trailing comma, and keep the container open, with
+formatting with C<-wtc=f(b) -atc> 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
# perltidy -wtc='f(b' -atc -btct='f(b'
plot(
'g', Canvas => $overview_canvas,
);
-After that, we could use C<-btct='f(b'> to keep the container open
+After that, we could use C<-btct='f(b'> to keep the container open.
=item *
=head1 VERSION
-This man page documents perltidy version 20240903.04
+This man page documents perltidy version 20240903.05
=head1 BUG REPORTS
<dt id="dws---delete-old-whitespace"><b>-dws</b>, <b>--delete-old-whitespace</b></dt>
<dd>
-<p>Setting this option allows perltidy to remove some old whitespace between characters, if necessary. This is the default. If you do not want any old whitespace removed, use <b>-ndws</b> or <b>--nodelete-old-whitespace</b>.</p>
+<p>Setting this option allows perltidy to remove optional whitespace between characters in the input file. The default is to not to do this (<b>-nodelete-old-whitespace</b>). This parameter has little effect by itself. But in combination with <b>--noadd-whitespace</b> it will cause most of the whitespace in a file to be removed.</p>
</dd>
<dt id="Detailed-whitespace-controls-around-tokens"><b>Detailed whitespace controls around tokens</b></dt>
<p>A disadvantage of this flag compared to the methods discussed above is that all tables in the file must already be nicely formatted.</p>
+</dd>
+<dt id="btct-s---break-at-trailing-comma-types-s"><b>-btct=s</b>, <b>--break-at-trailing-comma-types=s</b></dt>
+<dd>
+
+<p>A <b>trailing comma</b> is an optional comma following the last item of a list. The <b>-btct=s</b> tells perltidy to end a line at selected trailing commas. The string <b>s</b> selects the trailing commas, as follows:</p>
+
+<pre><code> s=1 or '*' : every trailing comma
+ s=m a trailing comma in a multiline list
+ s=b a bare trailing comma
+ s=0 none</code></pre>
+
+<p>For example, given the following input</p>
+
+<pre><code> $w->bind(
+ '<Page_Down>' => xx,
+ );</code></pre>
+
+<p>The default formatting would flatten this into a single line. But the container can be kept open with</p>
+
+<pre><code> # perltidy -btct='b'
+ $w->bind(
+ '<Page_Down>' => xx,
+ );</code></pre>
+
+<p>This can be particularly useful for short function calls like this, where the default perltidy formatting does not keep the container open.</p>
+
+<p>The options <b>s=m</b> and <b>s=1</b> can be used to open up containers with non-bare trailing commas. For example, given this input</p>
+
+<pre><code> $w->bind( '<Page_Down>' => xx, );</code></pre>
+
+<p>we can break it open with</p>
+
+<pre><code> # perltidy -btct=1
+ $w->bind(
+ '<Page_Down>' => xx,
+ );</code></pre>
+
+<p>Afterwards, we could switch to <b>btct=b</b> since the trailing comma is now bare. But the <b>-btct</b> parameter must be retained in this case because otherwise this small list will be flattened the next time it is formatted.</p>
+
+<p>This logic can be restricted to specific container types by including an opening token ahead of the letter in the above table. For example</p>
+
+<pre><code> -btct='(b'</code></pre>
+
+<p>means that this operation should only apply to bare trailing commas within parentheses.</p>
+
+<p>For parentheses, an additional item of information which can be given is an alphanumeric letter which is used to limit the selection further depending on the type of token immediately before the opening paren. The possible letters are currently 'k', 'K', 'f', 'F', 'w', and 'W', with these meanings for matching whatever precedes an opening paren:</p>
+
+<pre><code> 'k' matches if the previous nonblank token is a perl built-in keyword
+ 'K' matches if 'k' does not, meaning that the previous token is not a keyword.
+ 'f' matches if the previous token is a function other than a keyword.
+ 'F' matches if 'f' does not.
+ 'w' matches if either 'k' or 'f' match.
+ 'W' matches if 'w' does not.</code></pre>
+
+<p>These are the same codes used for <b>--line-up-parentheses-inclusion-list</b>. For example,</p>
+
+<pre><code> -btct='f(b'</code></pre>
+
+<p>means that bare trailing commas in function call lists in the input stream should be followed by line breaks in the formatted output stream.</p>
+
+<p>The section <a href="#Adding-and-Deleting-Commas">"Adding and Deleting Commas"</a> describes additional controls for working with trailing commas. These can be combined with the <b>-break-trailing-comma-types</b> parameter for additional control of list formatting.</p>
+
</dd>
<dt id="mft-n---maximum-fields-per-table-n"><b>-mft=n</b>, <b>--maximum-fields-per-table=n</b></dt>
<dd>
<li><p>If the option <b>--space-function-paren</b> is employed, it is ignored for these special function calls because it would deactivate them.</p>
</li>
-<li><p>Otherwise the various formatting control flags operate on these lists the same as for other comma-separated lists. In particular, note that if <b>--break-at-old-comma-breakpoints</b>, or <b>-boc</b>, is set, then the old line break locations will be retained.</p>
+<li><p>Otherwise the various formatting control flags operate on these lists the same as for other comma-separated lists. In particular, note that if <b>--break-at-old-comma-breakpoints</b>, or <b>-boc</b>, is set, then the old line break locations will be retained. And old line breaks will be retained if there are any blank lines between the opening and closing parens.</p>
</li>
<li><p>Before using this option for the first time, it is a good idea to scan the code and decide if any lists have a special order which should be retained. This can be accomplished for example by changing the quote delimiters to something other than parens, or by inserting a blank line as discussed at the start of this section.</p>
</li>
<li><p>A <b>bare trailing comma</b> is a comma which is at the end of a line. That is, the closing container token follows on a different line. So a list with a bare trailing comma is a special case of a multiline list.</p>
+</li>
+<li><p>In fact the above options for trailing commas can be seen as a hierarchy of nesting sets which can be expressed as</p>
+
+<pre><code> 1 > m > b > i > h > 0</code></pre>
+
+<p>This indicates that multiline trailing commas <b>m</b> are a subset of all trailing commas, and bare trailing commas <b>b</b> are a subset of all multiline trailing commas, and so on.</p>
+
</li>
</ul>
<pre><code> -wtc='+h -b' -atc -dtc</code></pre>
-<p>means that missing trailing commas should be added to lists of key => values pairs, and trailing commas which are not bare should be removed. No other changes are made. When both plus and minus terms are used like this, they must not be in conflict. This can be shown to be equivalent to requiring that the letter of the plus term does not occur before the letter of the minus term in their hierarchical order <b>m</b>, <b>b</b>, <b>i</b>, <b>h</b>. In this example, the plus term <b>h</b> follows the minus term <b>b</b> in the list, so there is no conflict.</p>
+<p>means that missing trailing commas should be added to lists of key => value pairs, and trailing commas which are not bare should be removed. No other changes are made. When both plus and minus terms are used like this, they must not be in conflict. There is no conflict in this example because the trailing comma locations of the key=>value pairs selected by the <b>+h</b> term are a subset of all bare trailing commas, and thus will not be deleted by the <b>-b</b> term. The general rule is that the letter of the plus term should occur after the letter of the minus term in the hierarchical nesting order, <b>1 > m > b > i > h > 0</b>.</p>
<p><b>Some points to note</b> regarding adding and deleting trailing commas:</p>
<li><p>It is recommended to also use the <b>--converge</b> parameter when adding and/or deleting trailing commas, especially if the formatter may be making other line break changes at the same time. The reason is that the decision regarding whether or not a list is multiline or bare is made based on the <b>input</b> stream if only one iteration is made, which is the default.</p>
-<p>When iterations are requested with the <b>--converge</b> parameter, any comma addition or deletion operations are postponed until the start of the <b>second iteration</b>, after most changes in line breaks have been made.</p>
+<p>When iterations are requested with the <b>--converge</b> parameter, any comma deletion operations are postponed until the start of the <b>second iteration</b>, after most changes in line breaks have been made.</p>
<p>To illustrate, if we start with</p>
b => 2
);</code></pre>
-<p>we delete a comma which has become bare, which is not what is wanted. This happened because the change was based on the starting rather than the final line breaks. Rerunning with <b>--converge</b> added fixes things</p>
+<p>we delete a comma which has become bare, which is not what is wanted. This happened because the change was based on the starting rather than the final line breaks. Running with <b>--converge</b> gives the desired result:</p>
<pre><code> # perltidy -wtc=b -dtc --converge
f(
b => 2,
);</code></pre>
-<p>because changes are based on the line breaks after the first iteration.</p>
+<p>because comma changes are based on the line breaks after the first iteration.</p>
+
+<p>The additional computer time needed by the <b>--converge</b> option to do another iteration or two will not be noticeable except for files with many thousands of lines.</p>
<p>A parameter <b>--delay-trailing-comma-operations</b>, or <b>-dtco</b>, is available to control this behavior if desired. Negating this parameter, with <b>-ndtco</b>, tells perltidy to always use the starting state to make decisions regarding comma addition and deletion, even when iterations are requested. This should not normally be necessary.</p>
</li>
-<li><p>Perltidy does not add a trailing comma to a list which appears to be near a <b>stability limit</b>. So if a comma is unexpectedly not added, this is probably the reason.</p>
+<li><p>Perltidy does not add a trailing comma in some <b>edge cases</b> which appear to be near a stability limit. So if a comma is unexpectedly not added, this is probably the reason.</p>
-<p>This issue can be illustrated with the following example. The closing brace is at column 80, the default line length:</p>
+</li>
+<li><p>If the parameter <b>--break-at-trailing-comma-types</b> is also employed, it operates on the state after any adding or deleting of commas. And it will allow trailing commas to be added in most edge cases. For example, given the following input text</p>
-<pre><code> # perltidy -atc -dtc -wtc=b
- $menuitem_paste->signal_connect( 'activate' => sub { create_paste_window() }
+<pre><code> plot(
+ 'g', Canvas => $overview_canvas
);</code></pre>
-<p>Adding a trailing comma would cause the maximum line length to be exceeded. This in turn would cause a different break point to occur for which the comma is no longer bare. So it would get deleted on the next formatting pass, returning things to the starting state. This is is an unstable situation.</p>
+<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>
+
+<pre><code> # perltidy -wtc='f(b' -atc -btct='f(b'
+ plot(
+ 'g', Canvas => $overview_canvas,
+ );</code></pre>
+
+<p>As another example, given the same text on a single line without a trailing comma</p>
+
+<pre><code> plot( 'g', Canvas => $overview_canvas );</code></pre>
-<p>The rules used to detect and avoid instability work well but are not precise, so in some cases where perltidy will not add a comma, it may be possible to add a stable trailing comma with editing. For example, if the above example were run with <b>-l=81 -atc -wtc=b</b>, perltidy would still not add a trailing comma, even though it would be stable.</p>
+<p>we can add a trailing comma and break the container open with</p>
+
+<pre><code> # perltidy -wtc=1 -atc -btct=1
+ plot(
+ 'g', Canvas => $overview_canvas,
+ );</code></pre>
+
+<p>After that, we could use <code>-btct='f(b'</code> to keep the container open.</p>
</li>
<li><p>When using these parameters for the first time it is a good idea to practice on some test scripts and verify that the results are as expected.</p>
<p>The parameters in the <i>.perltidyrc</i> file are installed first, so any parameters given on the command line will have priority over them.</p>
-<p>To avoid confusion, perltidy ignores any command in the .perltidyrc file which would cause some kind of dump and an exit. These are:</p>
+<p>To avoid confusion, perltidy ignores any command in the .perltidyrc file which would cause some kind of dump and an exit. These include:</p>
<pre><code> -h -v -ddf -dln -dop -dsn -dtt -dwls -dwrs -ss</code></pre>
<li><p>It may be simplest to develop and test configuration files with alternative names, and invoke them with <b>-pro=filename</b> on the command line. Then rename the desired file to <i>.perltidyrc</i> when finished.</p>
</li>
-<li><p>The parameters in the <i>.perltidyrc</i> file can be switched off with the <b>-npro</b> option.</p>
+<li><p>The parameters in the <i>.perltidyrc</i> file can be switched off with the <b>-npro</b> option on the command line.</p>
</li>
<li><p>Any parameter in the <i>.perltidyrc</i> file can be overridden with a replacement value on the command line. This is because the command line is processed after the <i>.perltidyrc</i> file.</p>
<pre><code> perltidy -dbs -dbl=1 -dbt='* closure' somefile.pl >blocks.csv</code></pre>
</li>
-<li><p>This selects every if-chain which contains 2 or more <b>elsif</b> blocks:</p>
+<li><p>This selects every if-chain which contains 2 or more <code>elsif</code> blocks:</p>
<pre><code> perltidy -dbs -dbl=1 -dbt='elsif2' somefile.pl >blocks.csv</code></pre>
+</li>
+<li><p>This selects every <code>while</code> block with 6 or more code lines</p>
+
+<pre><code> perltidy -dbs -dbt=while -dbl=6 somfile.pl >while.csv</code></pre>
+
</li>
</ul>
<h1 id="VERSION">VERSION</h1>
-<p>This man page documents perltidy version 20240903.03</p>
+<p>This man page documents perltidy version 20240903.05</p>
<h1 id="BUG-REPORTS">BUG REPORTS</h1>
projects / perltidy.git / commitdiff