From cd8eacad39f3baecc4c7a1555f9b976a09097528 Mon Sep 17 00:00:00 2001 From: Steve Hancock Date: Mon, 15 Jul 2024 10:20:44 -0700 Subject: [PATCH] update docs for -altc -dltc (formerly -atlc -dtlc) --- bin/perltidy | 115 ++++++++++++++++++++++++++---------- lib/Perl/Tidy.pm | 6 +- lib/Perl/Tidy/Formatter.pm | 14 ++--- t/snippets/atlc2.par | 2 +- t/snippets/dtlc2.par | 2 +- t/snippets/packing_list.txt | 16 ++--- t/snippets30.t | 6 +- 7 files changed, 108 insertions(+), 53 deletions(-) diff --git a/bin/perltidy b/bin/perltidy index 3dfb41e9..840f259a 100755 --- 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 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 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 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 + +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 a49ebc73..602e07d7 100644 --- 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 a6587093..b143c8f9 100644 --- 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 54274fe5..918e6ae5 100644 --- 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 d6328f57..10e60c4b 100644 --- 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 a16c48ec..bd32abd7 100644 --- 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 92a7128a..be08287c 100644 --- 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 ---------- -- 2.39.5