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<trailing commas>.
+The string B<s> 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(
+ '<Page_Down>' => xx,
+ );
+
+The default formatting would flatten this into a single line. But the
+container can be kept open with
+
+ # perltidy -btct='b'
+ $w->bind(
+ '<Page_Down>' => 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<s=m> and B<s=1> can be used to open up containers with
+non-bare trailing commas. For example, given this input
+
+ $w->bind( '<Page_Down>' => xx, );
+
+we can break it open with
+
+ # perltidy -btct=1
+ $w->bind(
+ '<Page_Down>' => xx,
+ );
+
+Afterwards, we could switch to B<btct=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<n> is a positive number, and the computed number of fields for any table
=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.
'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' ],
# 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 ];
}
}
# 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 ];
}
}
# 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;
}
}
+ $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
projects / perltidy.git / commitdiff