Please see the section L<"B<-pbp>, B<--perl-best-practices>"> for an example of
how this flag can improve the formatting of ternary statements. It can also
-improve indentation of some multi-line qw lists as shown below.
+improve indentation of some multiline qw lists as shown below.
# perltidy
foreach $color (
A limitation on B<-lp>, but not B<-xlp>, 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, multi-line quotes, or side comments between the
+blank lines, block comments, multiline quotes, or side comments between the
opening and closing parens, braces, or brackets. It will also occur if a
-multi-line anonymous sub occurs within a container since that will impose
+multiline anonymous sub occurs within a container since that will impose
specific line breaks (such as line breaks after statements).
=item *
=item B<Trimming whitespace around C<qw> quotes>
B<-tqw> or B<--trim-qw> provide the default behavior of trimming
-spaces around multi-line C<qw> quotes and indenting them appropriately.
+spaces around multiline C<qw> quotes and indenting them appropriately.
B<-ntqw> or B<--notrim-qw> cause leading and trailing whitespace around
-multi-line C<qw> quotes to be left unchanged. This option will not
+multiline C<qw> quotes to be left unchanged. This option will not
normally be necessary, but was added for testing purposes, because in
some versions of perl, trimming C<qw> quotes changes the syntax tree.
A trailing comma is a comma following the last item of a list. Perl allows
trailing commas but they are not required. Including them can sometimes
-simplify the maintenance of large or complex lists.
+simplify the maintenance of large or complex lists, and help display structure.
By default, perltidy does not add
or delete trailing commas, but it is possible to manipulate them with the
following set of related parameters:
=over 4
=item *
-B<--want-trailing-commas=s, -wtc=s> - defines where trailing commas are wanted
+B<--want-trailing-commas=s, -wtc=s> - defines where trailing commas are wanted (the style)
=item *
B<--add-trailing-commas, -atc> - gives permission to add trailing commas to match the style wanted
=item *
B<--delete-trailing-commas, -dtc> - gives permission to delete trailing commas which do not match the style wanted
-=item *
-B<--add-lone-trailing-commas, -altc> - gives permission to add a comma if it will be the only comma. This is off by default and explained below.
-
-=item *
-B<--delete-lone-trailing-commas, -dltc> - gives permission to delete the only comma in a list. This is on by default and explained below.
-
=back
The parameter B<--want-trailing-commas=s>, or B<-wtc=s>, defines a preferred style. The string B<s> indicates which lists should get trailing commas, as follows:
s=0 : no list should have a trailing comma
- s=1 or * : every list should have a trailing comma
- s=m a multi-line list should have a trailing comma
- s=b trailing commas should be 'bare' (comma followed by newline)
- s=h lists of key=>value pairs, with about one one '=>' and one ',' per line,
- with a bare trailing comma
- s=i lists with about one comma per line, with a bare trailing comma
+ s=1 or '*' : every list should have a trailing comma
+ s=m multiline list
+ s=b multiline list with bare trailing comma
+ s=i multiline list with bare trailing comma and about one comma per line
+ s=h multiline list with bare trailing comma and about one key=>value pair per line
s=' ' or -wtc not defined : leave trailing commas unchanged [DEFAULT].
-This parameter by itself only indicates the where trailing commas are
-wanted. Perltidy only adds these trailing commas if the flag B<--add-trailing-commas>, or B<-atc> is set. And perltidy only removes unwanted trailing commas
-if the flag B<--delete-trailing-commas>, or B<-dtc> is set.
+A multiline list here is a list for which the opening and closing container
+tokens are on different lines. A bare trailing comma is a comma followed
+by a newline.
+
+This parameter by itself only indicates where trailing commas are wanted.
+Perltidy only adds these trailing commas if the flag B<--add-trailing-commas>,
+or B<-atc> is set. And perltidy only removes unwanted trailing commas if the
+flag B<--delete-trailing-commas>, or B<-dtc> is set.
Here are some example parameter combinations and their meanings
-wtc=0 -dtc : delete all trailing commas
- -wtc=1 -atc : all lists get trailing commas
- -wtc=m -atc : all multi-line lists get trailing commas, but
+ -wtc=1 -atc : add trailing commas to all lists
+ -wtc=m -atc : all multiline lists get trailing commas, but
single line lists remain unchanged.
- -wtc=m -dtc : multi-line lists remain unchanged, but
+ -wtc=b -atc : all multiline lists whose closing bracket starts a
+ new line get trailing commas, all other
+ lists remain unchanged.
+ -wtc=m -dtc : multiline lists remain unchanged, but
any trailing commas on single line lists are removed.
- -wtc=m -atc -dtc : all multi-line lists get trailing commas, and
+ -wtc=m -atc -dtc : all multiline lists get trailing commas, and
any trailing commas on single line lists are removed.
For example, given the following input without a trailing comma
newline). And it could also be achieved with B<-wtc=h> because this particular
list is a list of key=>value pairs.
-The above styles should cover the main of situations of interest, but it is
-possible to apply a different style to each type of container token by
+It is possible to apply a different style to each type of container token by
including an opening token ahead of the style character in the above table.
For example
-wtc='(m [b'
-means that lists within parens should have multi-line trailing commas, and that
+means that lists within parens should have multiline trailing commas, and that
lists within square brackets have bare trailing commas. Since there is no
specification for curly braces in this example, their trailing commas would
remain unchanged.
-wtc = 'w(m'
-means that trailing commas are wanted for multi-line parenthesized lists following a function call or keyword.
+means that trailing commas are wanted for multiline parenthesized lists following a function call or keyword.
B<Some points to note> regarding adding and deleting trailing commas:
=item *
-By B<multiline> list is meant a list for which the first comma and trailing comma
-are on different lines.
+A B<multiline> list is a list for which the opening and closing brackets
+on different lines.
=item *
A B<bare> trailing comma 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 multi-line list.
+bare trailing comma is a special case of a multiline list.
+
+=item *
+
+Perltidy does not add a trailing comma to a list which appears to be near a
+B<stability limit>. So if a comma is unexpectedly not added, this is probably
+the reason.
+
+The rules for avoiding instability are complex, but here is a simple example:
+
+ # perltidy -atc -dtc -wtc=b
+ $menuitem_paste->signal_connect( 'activate' => sub { create_paste_window() }
+ );
+
+A trailing comma is not added in this example because it will cause the default
+line length to be exceeded. This in turn will cause a different break point to
+occur for which the comma is no longer bare. So if a comma were added, it would
+get deleted on the next pass or iteration, an unstable situation.
=item *
-The decision regarding whether or not a list is multi-line or bare is made
-based on the B<input> stream if only one iteration is made, which is the
-default.
+It is a good idea to turn on the B<--converge> parameter when adding and
+deleting trailing commas. The reason is that the decision regarding whether or
+not a list is multiline or bare is made based on the B<input> stream if only
+one iteration is made, which is the default.
-It can sometimes be preferable to base decisions on trailing commas
-on the final line breaks rather than the initial line breaks.
-This can be accomplished by telling perltidy to perform two or more internal
-iterations, for example with the B<--converge> parameter. In this case
-any comma addition or deletion operations are postponed until the
-start of the second iteration, after changes in line breaks have been made.
-For a discussion see L<https://github.com/perltidy/perltidy/issues/156>.
+When iterations are requested with the B<--converge> parameter, any comma
+addition or deletion operations are postponed until the start of the second
+iteration, after changes in line breaks have been made. For a discussion see
+L<https://github.com/perltidy/perltidy/issues/156>.
A parameter B<--delay-trailing-comma-operations>, or B<-dtco>, is available to
control behavior if desired. Negating this parameter, with B<-ndtco>, tells
perltidy to always use the starting state to make decisions regarding comma
-addition and deletion, even when iterations are requested.
+addition and deletion, even when iterations are requested. This should not
+normally be necessary.
=item *
B<Special Considerations for Lone Trailing Commas>
Adding or deleting the only comma in a list can have some implications which
-need to be explained and possibly controlled.
+need to be explained and possibly controlled. Two additional controls are
+available for these lone commas:
+
+=over 4
+
+=item *
+B<--add-lone-trailing-commas, -altc> - gives permission to add a comma if it will be the only comma. This is on by default and explained below.
+
+=item *
+B<--delete-lone-trailing-commas, -dltc> - gives permission to delete the only comma in a list. This is on by default and explained below.
-The main issue with deleting a lone comma is that if it
-is deleted, then it might not be possible add it back automatically
-since perltidy uses the existance of commas to help locate lists. For example,
-given
+=back
+
+The main issue with deleting a lone comma is that if it is deleted, then it
+might not be possible add it back automatically since perltidy uses the
+existance of commas to help locate containers where commas are appropriate. For
+example, given
my ( $self, ) = @_;
parameter is a fine-tuning control for B<--delete-trailing-commas> which
must also be set for it to have any effect.
-Perltidy can add a lone comma to certain lists which themselves contain
-lists. For example, a comma can be added after the closing hash brace in
-the following snippet:
+However, if a single item in a list is itself is a list with multiple lines,
+such as the item in braces here
$self->make_grammar(
{
}
);
-However, the parameter B<--add-lone-trailing-commas> must be set to allow such
-a comma to be added. The reason is that adding such a comma would prevent the
-B<--weld-nested-containers> flag from operating on this structure. This can be
-confusing, so this parameter is off by default. Note that this parameter is a
-fine-tuning control for B<--add-trailing-commas> which must also be set for it
-to have any effect. To illustrate its use on the above example:
+then perltidy can add a lone comma:
- # perltidy -atc -altc -wtc=b
+ # perltidy -atc -wtc=b
$self->make_grammar(
{
iterator => $self->_iterator,
},
);
-This comma can be removed to allow welding with the control described in the
-next section.
+It turns out that these cases usually coincide with situations where the
+B<--weld-nested-containers>, or B<-wn>, would apply. For example, applying
+B<-wn> to the example without the comma gives
+
+ # perltidy -wn
+ $self->make_grammar( {
+ iterator => $self->_iterator,
+ parser => $self,
+ version => $self->version,
+ } );
+
+But if there is a trailing comma after the closing brace, then the weld
+operation is blocked and fails. A parameter B<--add-lone-trailing-commas>, or
+B<-altc> is available to provide some control. It allows these commas to be
+added, provide that B<--add-trailing-commas> is also set. It is on by default.
+Users of B<-wn> may want to turn it off with B<--noadd-lone-trailing-commas>,
+B<-naltc> to prevent such commas from being added.
+
+If such commas do get added, then can be removed to allow welding with the
+control described in the next section.
=item B<-dwic>, B<--delete-weld-interfering-commas>
include any of the words C<sort>, C<map>, C<grep>, C<eval>, or it may be C<*>
to indicate all of these.
-So for example to prevent multi-line B<eval> blocks from becoming one-line
-blocks, the command would be B<-olbxl='eval'>. In this case, existing one-line B<eval> blocks will remain on one-line if possible, and existing multi-line
-B<eval> blocks will remain multi-line blocks.
+So for example to prevent multiline B<eval> blocks from becoming one-line
+blocks, the command would be B<-olbxl='eval'>. In this case, existing one-line B<eval> blocks will remain on one-line if possible, and existing multiline
+B<eval> blocks will remain multiline blocks.
=item B<-olbn=n>, B<--one-line-block-nesting=n>
projects / perltidy.git / commitdiff