'[ {' - exclude all brackets and braces
'[ ( ^K{' - exclude everything except nested structures like do {{ ... }}
+=item B<-dwic>, B<--delete-weld-interfering-commas>
+
+If the closing tokens of two nested containers are separated by a comma, then
+welding cannot occur. Any commas in this situation are optional trailing
+commas and can be removed if desired. This can be done by hand, but on large
+scripts it might be easier to use this parameter. The parameter B<-dwic> tells
+perltidy to remove any such commas that it finds. For example, using a
+previous example with an added comma, we see that the comma prevents welding:
+
+ # perltidy -wn
+ skip_symbols(
+ [ qw(
+ Perl_dump_fds
+ Perl_ErrorNo
+ Perl_GetVars
+ PL_sys_intern
+ ) ],
+ );
+
+If this is not desired, then the comma can be removed manually or by using B<-dwic>, as follows:
+
+ # perltidy -wn -dwic
+ skip_symbols( [ qw(
+ Perl_dump_fds
+ Perl_ErrorNo
+ Perl_GetVars
+ PL_sys_intern
+ ) ] );
+
+Here are some points to note about the B<-dwic> parameter
+
+=over 4
+
+=item *
+
+This operation is not reversible, so please check results of using this parameter carefully.
+
+=item *
+
+Removing these isolated trailing commas is necessary for welding to be
+possible, but not sufficient.
+
+=back
+
+
=item B<Vertical tightness> of non-block curly braces, parentheses, and square brackets.
These parameters control what shall be called vertical tightness. Here are the
"09" => 30, "10" => 31, "11" => 30, "12" => 31
);
+=item B<-wtc=s>, B<--want-trailing-commas=s>
+
+A trailing comma is a comma following the last item of a list. Perl allows
+trailing commas but they are not required. By default, perltidy does not add
+or delete trailing commas, but it is possible to do this with the following set of three related parameters:
+
+ --want-trailing-commas=s, -wtc=s - defines where trailing commas are wanted
+ --add-trailing-commas, -atc - gives permission to add trailing commas to match the style
+ --delete-trailing-commas, -dtc - gives permission to delete trailing commas which do not match the style
+
+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 commas
+ s=b trailing commas should be 'bare' (comma followed by newline)
+ s=h trailing commas should be 'bare' for lists of key=>value pairs, or other lists with about one comma 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-comma>, or B<-atc> is set. And perltidy only removes unwanted trailing commas
+if the flag B<--delete-trailing-comma> is set.
+
+Here are some example parameter combinations and their meanings
+
+ -wtc=0 -dtc : delete all trailing commas
+ -wtc=1 -atc : put trailing commas on all lists
+ -wtc=m -atc : all multi-line lists get trailing commas;
+ single line lists may or may not have trailing commas
+ -wtc=m -atc -dtc : all multi-line lists get trailing commas, and
+ any trailing commas on single line lists are removed.
+
+For example, we can add a comma after the variable C<$Root> in the example
+a few lines above using
+
+ # perltidy -wtc=m -atc
+ bless {
+ B => $B,
+ Root => $Root,
+ } => $package;
+
+This could also be achieved in this case with B<-wtc=b -atc> because
+the trailing comma here is bare (separated from the closing brace by a newline).
+And it could also be achieved with B<-wtc=h -atc> because this particular
+list is a list of key=>value pairs.
+
+It is possible to apply a different style to different types of containing
+tokens 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
+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.
+
+Here are some points regarding adding and deleting trailing commas:
+
+=over 4
+
+=item *
+
+For the implementation of these parameters, a B<list> is basically taken to be a sequence of items in a container (parens, square brackets, or braces) which is not a code block, separated by one or more commas.
+
+So a paren-less list of parameters is not a list by this definition.
+
+And note that if the only comma in a list is a trailing comma, and it is
+deleted with these commands, then that container will no longer be a list by
+this definition. Consequently, a trailing comma cannot later be added to that
+container.
+
+=item *
+
+By B<multiline> list is meant a list for which the opening and closing tokens
+are 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.
+
+=item *
+
+The decision regarding whether or not a list is multiline or bare is
+made based on the B<input> stream. In some cases it may take an iteration
+or two to reach a final state.
+
+=item *
+
+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.
+
+=back
+
=back
=head2 Retaining or Ignoring Existing Line Breaks
projects / perltidy.git / commitdiff