From cb873887936d2c9d26749ddc40624b3cb8193244 Mon Sep 17 00:00:00 2001 From: Steve Hancock Date: Sat, 2 Nov 2024 13:09:58 -0700 Subject: [PATCH] document -btct --- CHANGES.md | 5 ++ bin/perltidy | 109 +++++++++++++++++++++++++++++++ dev-bin/perltidy_random_setup.pl | 6 +- lib/Perl/Tidy/Formatter.pm | 28 +++++--- 4 files changed, 137 insertions(+), 11 deletions(-) diff --git a/CHANGES.md b/CHANGES.md index db488da5..60af8af2 100644 --- a/CHANGES.md +++ b/CHANGES.md @@ -2,6 +2,11 @@ ## 2024 09 03.04 + - Added parameter --break-at-trailing-comma-types=s, or -btct=s, where + s is a string which selectes trailing commas. For example, -btct='f(b' + places a line break after all bare trailing commas in function calls. + The manual has details. + - Fix git #165, strings beginning with v before => gave incorrect error message - The parameter --add-lone-trailing-commas, -altc, is now on by default. diff --git a/bin/perltidy b/bin/perltidy index 6a852058..3ed9508d 100755 --- a/bin/perltidy +++ b/bin/perltidy @@ -3730,6 +3730,84 @@ the original style, yields A disadvantage of this flag compared to the methods discussed above is that all tables in the file must already be nicely formatted. +=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. +The string B selects the trailing commas, as follows: + + s=1 or '*' : every trailing comma + s=m a trailing comma in a multiline list + s=b a bare trailing comma + s=0 none + +For example, given the following input + + $w->bind( + '' => xx, + ); + +The default formatting would flatten this into a single line. But the +container can be kept open with + + # perltidy -btct='b' + $w->bind( + '' => xx, + ); + +This can be particularly useful for short function calls like this, +where the default perltidy formatting does not keep the container open. + +The options B and B can be used to open up containers with +non-bare trailing commas. For example, given this input + + $w->bind( '' => xx, ); + +we can break it open with + + # perltidy -btct=1 + $w->bind( + '' => xx, + ); + +Afterwards, we could switch to 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. + +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 + + -btct='(b' + +means that this operation should only apply to lists within parens with +trailing commas. + +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: + + '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. + +These are the same codes used for B<--line-up-parentheses-inclusion-list>. +For example, + + -btct='f(b' + +means that bare trailing commas in function call lists in the input stream +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. + =item B<-mft=n>, B<--maximum-fields-per-table=n> If B is a positive number, and the computed number of fields for any table @@ -4125,6 +4203,37 @@ probably the reason. =item * +If the parameter B<--break-at-trailing-comma-types> 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 + + plot( + 'g', Canvas => $overview_canvas + ); + +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, + ); + +As another example, given the same text on a single line without a trailing comma + + plot( 'g', Canvas => $overview_canvas ); + +we can add a trailing comma and break the container open with + + # perltidy -wtc=1 -atc -btct=1 + plot( + 'g', Canvas => $overview_canvas, + ); + +After that, we could use -btct='f(b' to keep the container open + +=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. diff --git a/dev-bin/perltidy_random_setup.pl b/dev-bin/perltidy_random_setup.pl index d1fea210..27fbc267 100755 --- a/dev-bin/perltidy_random_setup.pl +++ b/dev-bin/perltidy_random_setup.pl @@ -911,11 +911,13 @@ EOM 'want-call-parens' => [ '&', 'open', 'close' ], 'nowant-call-parens' => [ 'pop', 'open' ], - 'want-trailing-commas' => [ '0', '*', 'm', 'b', 'h', 'i', ' ' ], + 'want-trailing-commas' => + [ '0', '*', 'm', 'b', 'h', 'i', ' ', 'f(b', 'f(m', 'f(h' ], 'one-line-block-exclusion-list' => [ 'sort', 'map', 'grep', 'eval', '*', 'zzyzx' ], - 'break-at-trailing-comma-types' => [ '0', '1', 'm', 'b' ], + 'break-at-trailing-comma-types' => + [ '0', '1', 'm', 'b', 'f(b', 'f(m', 'f(1' ], 'use-feature' => [ 'class', ' ', 'xyzzy' ], diff --git a/lib/Perl/Tidy/Formatter.pm b/lib/Perl/Tidy/Formatter.pm index a69818ea..4d838073 100644 --- a/lib/Perl/Tidy/Formatter.pm +++ b/lib/Perl/Tidy/Formatter.pm @@ -3436,8 +3436,8 @@ sub initialize_trailing_comma_break_rules { # handle the common case of a single control character, like -btct='b' if ( length($option) == 1 ) { - foreach (@all_keys) { - $rule_hash{$_} = [ $option, EMPTY_STRING ]; + foreach my $key (@all_keys) { + $rule_hash{$key} = [ $option, EMPTY_STRING ]; } } @@ -3603,12 +3603,12 @@ sub initialize_trailing_comma_rules { # handle the common case of a single control character, like -wtc='b' if ( length($option) == 1 ) { - foreach (@all_keys) { + foreach my $key (@all_keys) { my $paren_flag = EMPTY_STRING; - my $stable = defined( $trailing_comma_break_rules{$_} ); - if ( $_ eq ')' ) { $stable &&= $paren_flag eq $tc_paren_flag } - $rule_hash{add}->{$_} = [ $option, $paren_flag, $stable ]; - $rule_hash{delete}->{$_} = [ $option, $paren_flag, $stable ]; + my $stable = defined( $trailing_comma_break_rules{$key} ); + if ( $key eq ')' ) { $stable &&= $paren_flag eq $tc_paren_flag } + $rule_hash{add}->{$key} = [ $option, $paren_flag, $stable ]; + $rule_hash{delete}->{$key} = [ $option, $paren_flag, $stable ]; } } @@ -3692,8 +3692,9 @@ sub initialize_trailing_comma_rules { # New bare commas are stable if -bctc is set, and # also paren flags do not disagree - my $stable = defined( $trailing_comma_break_rules{$_} ); - if ( $_ eq ')' ) { + my $stable = + defined( $trailing_comma_break_rules{$key} ); + if ( $key eq ')' ) { $stable &&= $paren_flag eq $tc_paren_flag; } @@ -15373,6 +15374,15 @@ sub store_new_token { } + $last_last_nonblank_code_type = $last_nonblank_code_type; + $last_last_nonblank_code_token = $last_nonblank_code_token; + + $last_nonblank_code_type = $type; + $last_nonblank_code_token = $token; + + # This sub is currently called to store non-block types ',' and '->', so: + $last_nonblank_block_type = EMPTY_STRING; + return; } ## end sub store_new_token -- 2.39.5