update docs for -altc -dltc (formerly -atlc -dtlc)

diff --git a/bin/perltidy b/bin/perltidy
index 3dfb41e9e2b3f81042f5afa0faca1a54599e4a29..840f259af8a06cd494d71d83214c9d540b5e6821 100755 (executable)
--- a/bin/perltidy
+++ b/bin/perltidy
@@ -3790,7 +3790,9 @@ This option is on by default.  Use B<-ndrc> to turn it off.
 =item B<--want-trailing-commas=s> or B<-wtc=s>, B<--add-trailing-commas> or B<-atc>, and B<--delete-trailing-commas> or B<-dtc>
 
 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
+trailing commas but they are not required.  Including them can sometimes
+simplify the maintenance of large or complex lists.
+By default, perltidy does not add
 or delete trailing commas, but it is possible to manipulate them with the
 following set of three related parameters:
 
@@ -3805,6 +3807,12 @@ B<--add-trailing-commas,    -atc>   - gives permission to add trailing commas to
 =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:
@@ -3886,7 +3894,7 @@ For example,
 
 means that trailing commas are wanted for multi-line parenthesized lists following a function call or keyword.
 
-Here are some points to note regarding adding and deleting trailing commas:
+B<Some points to note> regarding adding and deleting trailing commas:
 
 =over 4
 
@@ -3900,19 +3908,6 @@ something that fits this definition of a list.
 Note that a paren-less list of parameters is not a list by this definition, so
 these parameters have no effect on a paren-less list.
 
-Another consequence is that if the only comma in a list is deleted, then it
-cannot later be added back with these parameters because the container no
-longer fits this definition of a list.  For example, given
-
-    my ( $self, ) = @_;
-
-and if we remove the comma with
-
-    # perltidy -wtc=m -dtc
-    my ( $self ) = @_;
-
-then we cannot use these trailing comma controls to add this comma back.
-
 =item *
 
 By B<multiline> list is meant a list for which the first comma and trailing comma
@@ -3942,6 +3937,63 @@ can be useful on a temporary basis for reformatting a script.
 
 =back
 
+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.
+
+The main issue with deleting a lone comma is that if the only comma in a list
+is deleted, then it might not be possible to later add it back automatically
+since perltidy uses the existance of commas to help locate lists. For example,
+given
+
+    my ( $self, ) = @_;
+
+and if we remove the comma with
+
+    # perltidy -wtc=m -dtc
+    my ( $self ) = @_;
+
+then we cannot use the trailing comma controls to add this comma back. The
+parameter B<--delete-lone-trailing-commas> allows such a comma to be deleted,
+and is on by default, but can be turned off to prevent this. This might
+be useful is if one is experimenting with formatting options and wants
+to restrict testing to operations which are reversible.  Note that this
+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:
+
+    $self->make_grammar(
+        {
+            iterator => $self->_iterator,
+            parser   => $self,
+            version  => $self->version,
+        }
+    );
+
+However, the parameter B<--add-lone-trailing-commas> must be set to allow such
+a comma to be added.  This parameter is off by default.  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, or undesirable if the
+welding control is also being used.  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:
+
+    # perltidy -atc -altc -wtc=b
+    $self->make_grammar(
+        {
+            iterator => $self->_iterator,
+            parser   => $self,
+            version  => $self->version,
+        },
+    );
+
+If we later decide we would prefer to remove this comma to allow welding,
+it can be removed with the control in the next section.
+
 =item B<-dwic>,  B<--delete-weld-interfering-commas>
 
 If the closing tokens of two nested containers are separated by a comma, then
@@ -3950,33 +4002,32 @@ this situation are optional trailing commas and can be removed with B<-dwic>.
 For example, a comma in this script prevents welding:
 
     # perltidy -wn
-    skip_symbols(
-        [ qw(
-            Perl_dump_fds
-            Perl_ErrorNo
-            Perl_GetVars
-            PL_sys_intern
-        ) ],
+    $self->make_grammar(
+        {
+            iterator => $self->_iterator,
+            parser   => $self,
+            version  => $self->version,
+        },
     );
 
 Using B<-dwic> removes the comma and allows welding:
 
     # perltidy -wn -dwic
-    skip_symbols( [ qw(
-        Perl_dump_fds
-        Perl_ErrorNo
-        Perl_GetVars
-        PL_sys_intern
-    ) ] );
+    $self->make_grammar( {
+        iterator => $self->_iterator,
+        parser   => $self,
+        version  => $self->version,
+    } );
 
-Since the default is not to add or delete commas, this feature is off by default.
+This feature is off by default.
 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.
+This operation is not always reversible, so please check results of using this
+parameter carefully.
 
 =item *
 
@@ -3984,6 +4035,10 @@ Removing this type of isolated trailing comma is necessary for welding to be
 possible, but not sufficient.  So welding will not always occur where these
 commas are removed.
 
+=item *
+
+This operation is independent of B<--add-trailing-commas> and B<--delete-trailing-commas>.  If it conflicts with any of those settings, it has priority.
+
 =back
 
 =back

diff --git a/lib/Perl/Tidy.pm b/lib/Perl/Tidy.pm
index a49ebc73b59c682779b6ac087f57f1ff766ed148..602e07d70bdc0293f319fceb19bb909acfbba632 100644 (file)
--- a/lib/Perl/Tidy.pm
+++ b/lib/Perl/Tidy.pm
@@ -3509,7 +3509,7 @@ sub generate_options {
     $category = 3;    # Whitespace control
     ########################################
     $add_option->( 'add-trailing-commas',                       'atc',   '!' );
-    $add_option->( 'add-trailing-lone-commas',                  'atlc',  '!' );
+    $add_option->( 'add-lone-trailing-commas',                  'altc',  '!' );
     $add_option->( 'add-semicolons',                            'asc',   '!' );
     $add_option->( 'add-whitespace',                            'aws',   '!' );
     $add_option->( 'block-brace-tightness',                     'bbt',   '=i' );
@@ -3517,7 +3517,7 @@ sub generate_options {
     $add_option->( 'delete-old-whitespace',                     'dws',   '!' );
     $add_option->( 'delete-repeated-commas',                    'drc',   '!' );
     $add_option->( 'delete-trailing-commas',                    'dtc',   '!' );
-    $add_option->( 'delete-trailing-lone-commas',               'dtlc',  '!' );
+    $add_option->( 'delete-lone-trailing-commas',               'dltc',  '!' );
     $add_option->( 'delete-weld-interfering-commas',            'dwic',  '!' );
     $add_option->( 'delete-semicolons',                         'dsm',   '!' );
     $add_option->( 'function-paren-vertical-alignment',         'fpva',  '!' );
@@ -3851,7 +3851,7 @@ sub generate_options {
       cuddled-break-option=1
       delete-old-newlines
       delete-repeated-commas
-      delete-trailing-lone-commas
+      delete-lone-trailing-commas
       delete-semicolons
       dump-block-minimum-lines=20
       dump-block-types=sub

diff --git a/lib/Perl/Tidy/Formatter.pm b/lib/Perl/Tidy/Formatter.pm
index a6587093c7a20f87e2a788d7ec38e2df61513ecf..b143c8f99347650ab423bb8b24e9ef8f96ec2d9c 100644 (file)
--- a/lib/Perl/Tidy/Formatter.pm
+++ b/lib/Perl/Tidy/Formatter.pm
@@ -202,7 +202,7 @@ my (
     $rOpts_add_newlines,
     $rOpts_add_whitespace,
     $rOpts_add_trailing_commas,
-    $rOpts_add_trailing_lone_commas,
+    $rOpts_add_lone_trailing_commas,
     $rOpts_blank_lines_after_opening_block,
     $rOpts_block_brace_tightness,
     $rOpts_block_brace_vertical_tightness,
@@ -225,7 +225,7 @@ my (
     $rOpts_delete_old_whitespace,
     $rOpts_delete_side_comments,
     $rOpts_delete_trailing_commas,
-    $rOpts_delete_trailing_lone_commas,
+    $rOpts_delete_lone_trailing_commas,
     $rOpts_delete_weld_interfering_commas,
     $rOpts_extended_continuation_indentation,
     $rOpts_format_skipping,
@@ -2537,7 +2537,7 @@ sub initialize_global_option_vars {
 
     $rOpts_add_newlines             = $rOpts->{'add-newlines'};
     $rOpts_add_trailing_commas      = $rOpts->{'add-trailing-commas'};
-    $rOpts_add_trailing_lone_commas = $rOpts->{'add-trailing-lone-commas'};
+    $rOpts_add_lone_trailing_commas = $rOpts->{'add-lone-trailing-commas'};
     $rOpts_add_whitespace           = $rOpts->{'add-whitespace'};
     $rOpts_blank_lines_after_opening_block =
       $rOpts->{'blank-lines-after-opening-block'};
@@ -2575,8 +2575,8 @@ sub initialize_global_option_vars {
       $rOpts->{'extended-continuation-indentation'};
     $rOpts_delete_side_comments   = $rOpts->{'delete-side-comments'};
     $rOpts_delete_trailing_commas = $rOpts->{'delete-trailing-commas'};
-    $rOpts_delete_trailing_lone_commas =
-      $rOpts->{'delete-trailing-lone-commas'};
+    $rOpts_delete_lone_trailing_commas =
+      $rOpts->{'delete-lone-trailing-commas'};
     $rOpts_delete_weld_interfering_commas =
       $rOpts->{'delete-weld-interfering-commas'};
     $rOpts_format_skipping   = $rOpts->{'format-skipping'};
@@ -11059,7 +11059,7 @@ sub respace_tokens_inner_loop {
 
                                     # ... or exception for nested container
                                     || (
-                                        $rOpts_add_trailing_lone_commas
+                                        $rOpts_add_lone_trailing_commas
                                         && $is_closing_type{
                                             $last_nonblank_code_type}
                                     )
@@ -11081,7 +11081,7 @@ sub respace_tokens_inner_loop {
                                 && %trailing_comma_rules
                                 && $rtype_count
                                 && $rtype_count->{','}
-                                && (   $rOpts_delete_trailing_lone_commas
+                                && (   $rOpts_delete_lone_trailing_commas
                                     || $rtype_count->{','} > 1
                                     || $rtype_count->{'=>'} )
                               )

diff --git a/t/snippets/atlc2.par b/t/snippets/atlc2.par
index 54274fe53010fdbec107cb9639f39220f27db135..918e6ae5c815b57c98f937ea0b55411c7ae87ce3 100644 (file)
--- a/t/snippets/atlc2.par
+++ b/t/snippets/atlc2.par
@@ -1 +1 @@
--atlc -atc -wtc=m
+-altc -atc -wtc=m

diff --git a/t/snippets/dtlc2.par b/t/snippets/dtlc2.par
index d6328f574d1a591ad71458eec5c7505a91db7853..10e60c4b6e99c16c69f6157b4dedb4621526bf67 100644 (file)
--- a/t/snippets/dtlc2.par
+++ b/t/snippets/dtlc2.par
@@ -1 +1 @@
--dtc -wtc=0 -ndtlc
+-dtc -wtc=0 -ndltc

diff --git a/t/snippets/packing_list.txt b/t/snippets/packing_list.txt
index a16c48ecfe2781440aed2175c0f7721807c43d9a..bd32abd7026df390c77123ef4addae1c3c0fb168 100644 (file)
--- a/t/snippets/packing_list.txt
+++ b/t/snippets/packing_list.txt
@@ -444,6 +444,14 @@
 ../snippets3.t gnu1.def
 ../snippets30.t        git143.def
 ../snippets30.t        git143.git143
+../snippets30.t        atlc.atlc1
+../snippets30.t        atlc.atlc2
+../snippets30.t        atlc.def
+../snippets30.t        dtlc.def
+../snippets30.t        dtlc.dtlc1
+../snippets30.t        dtlc.dtlc2
+../snippets30.t        git146.def
+../snippets30.t        git146.git146
 ../snippets4.t gnu1.gnu
 ../snippets4.t gnu2.def
 ../snippets4.t gnu2.gnu
@@ -564,11 +572,3 @@
 ../snippets9.t rt98902.def
 ../snippets9.t rt98902.rt98902
 ../snippets9.t rt99961.def
-../snippets30.t        atlc.atlc1
-../snippets30.t        atlc.atlc2
-../snippets30.t        atlc.def
-../snippets30.t        dtlc.def
-../snippets30.t        dtlc.dtlc1
-../snippets30.t        dtlc.dtlc2
-../snippets30.t        git146.def
-../snippets30.t        git146.git146

diff --git a/t/snippets30.t b/t/snippets30.t
index 92a7128aec4c6b24295027bd3b987bb5ac1d9e75..be08287c2a60c97c251b89798dbc8d3737f98fcb 100644 (file)
--- a/t/snippets30.t
+++ b/t/snippets30.t
@@ -29,14 +29,14 @@ BEGIN {
     ###########################################
     $rparams = {
         'atlc1'  => "-atc -wtc=m",
-        'atlc2'  => "-atlc -atc -wtc=m",
+        'atlc2'  => "-altc -atc -wtc=m",
         'def'    => "",
         'dtlc1'  => "-dtc -wtc=0",
-        'dtlc2'  => "-dtc -wtc=0 -ndtlc",
+        'dtlc2'  => "-dtc -wtc=0 -ndltc",
         'git143' => "-atc -wtc=h",
         'git146' => <<'----------',
 # testing three dash parameters
----add-trailing-commas 
+---add-trailing-commas
 ---unknown-future-option
 ---wtc=h
 ----------