From: Steve Hancock Date: Wed, 1 Feb 2023 02:14:16 +0000 (-0800) Subject: Bump to v 20221112.05; update one-line block docs X-Git-Tag: 20221112.05^0 X-Git-Url: https://git.donarmstrong.com/?a=commitdiff_plain;h=030e5570121e5a9aaa64bf10c6a4dfc7ce7b16eb;p=perltidy.git Bump to v 20221112.05; update one-line block docs --- diff --git a/CHANGES.md b/CHANGES.md index 1a9f84b7..bcf9422d 100644 --- a/CHANGES.md +++ b/CHANGES.md @@ -1,6 +1,6 @@ # Perltidy Change Log -## 2022 11 12.04 +## 2022 11 12.05 - Added parameter --one-line-block-exclusion-list=s, or -olbxl=s, where s is a list of block types which should not automatically be turned diff --git a/bin/perltidy b/bin/perltidy index 02a6a779..b6fe8706 100755 --- a/bin/perltidy +++ b/bin/perltidy @@ -2345,7 +2345,7 @@ following set of parameters could be used: perltidy -ce -cbl='else elsif continue' -cblx -=item B<-cbo=n>, B<--cuddled-break-option=n> +=item B<-cbo=n>, B<--cuddled-break-option=n> Cuddled formatting is only possible between a pair of code blocks if the closing brace of the first block starts a new line. If a block is encountered @@ -4326,9 +4326,9 @@ B<-nst> and/or B<-nse> after the -pbp parameter. Also note that the value of continuation indentation, -ci=4, is equal to the value of the full indentation, -i=4. It is recommended that the either (1) the -parameter B<-ci=2> be used instead, or the flag B<-xci> be set. This will help -show structure, particularly when there are ternary statements. The following -snippet illustrates these options. +parameter B<-ci=2> be used instead, or (2) the flag B<-xci> be set. This will +help show structure, particularly when there are ternary statements. The +following snippet illustrates these options. # perltidy -pbp $self->{_text} = ( @@ -4368,78 +4368,72 @@ snippet illustrates these options. The B<-xci> flag was developed after the B<-pbp> parameters were published so you need to include it separately. -=item B +=back + +=head2 One-Line Blocks -There are a few points to note regarding one-line blocks. A one-line -block is something like this, +A one-line block is a block of code where the contents within the curly braces +is short enough to fit on a single line. For example, if ( -e $file ) { print "'$file' exists\n" } -where the contents within the curly braces is short enough to fit -on a single line. +The alternative, a block which spans multiple lines, is said to be a broken +block. With few exceptions, perltidy retains existing one-line blocks, if it +is possible within the line-length constraint, but it does not attempt to form +new ones. In other words, perltidy will try to follow the input file regarding +broken and unbroken blocks. -With few exceptions, perltidy retains existing one-line blocks, if it -is possible within the line-length constraint, but it does not attempt -to form new ones. In other words, perltidy will try to follow the -one-line block style of the input file. +The main exception to this rule is that perltidy will attempt to form new +one-line blocks following the keywords C, C, and C, C, +because these code blocks are often small and most clearly displayed in a +single line. This behavior can be controlled with the flag +B<--one-line-block-exclusion-list> described below. -If an existing one-line block is longer than the maximum line length, -however, it will be broken into multiple lines. When this happens, perltidy -checks for and adds any optional terminating semicolon (unless the B<-nasc> -option is used) if the block is a code block. +When the B style is used, the default treatment of one-line blocks +may interfere with the cuddled style. In this case, the default behavior may +be changed with the flag B<--cuddled-break-option=n> described elsehwere. -The main exception is that perltidy will attempt to form new one-line -blocks following the keywords C, C, and C, C, because -these code blocks are often small and most clearly displayed in a single -line. This behavior can be controlled with the flag B<--one-line-block-exclusion-list> described below. +When an existing one-line block is longer than the maximum line length, and +must therefore be broken into multiple lines, perltidy checks for and adds any +optional terminating semicolon (unless the B<-nasc> option is used) if the +block is a code block. -One-line block rules can conflict with the cuddled-else option. When -the cuddled-else option is used, perltidy retains existing one-line -blocks, even if they do not obey cuddled-else formatting. +=over 4 -Occasionally, when one-line blocks get broken because they exceed the -available line length, the formatting will violate the requested brace style. -If this happens, reformatting the script a second time should correct -the problem. +=item B<-olbxl=s>, B<--one-line-block-exclusion-list=s> -Sometimes it might be desirable to convert a script to have one-line blocks -whenever possible. Although there is currently no flag for this, a simple -workaround is to execute perltidy twice, once with the flag B<-noadd-newlines> -and then once again with normal parameters, like this: +As noted above, perltidy will, by default, attempt to create new one-line +blocks for certain block types. This flag allows the user to prevent this behavior for the block types listed in the string B. The list B may +include any of the words C, C, C, C, or it may be C<*> +to indicate all of these. - cat infile | perltidy -nanl | perltidy >outfile +So for example to prevent multi-line B blocks from becomming one-line +blocks, the command would be B<-olbxl='eval'>. In this case, existing one-line B blocks will remain on one-line if possible, and existing multi-line +B blocks will remain multi-line blocks. -When executed on this snippet +=item B<-olbn=n>, B<--one-line-block-nesting=n> - if ( $? == -1 ) { - die "failed to execute: $!\n"; - } - if ( $? == -1 ) { - print "Had enough.\n"; - die "failed to execute: $!\n"; - } +Nested one-line blocks are lines with code blocks which themselves contain code +blocks. For example, the following line is a nested one-line block. -the result is + foreach (@list) { if ($_ eq $asked_for) { last } ++$found } - if ( $? == -1 ) { die "failed to execute: $!\n"; } - if ( $? == -1 ) { - print "Had enough.\n"; - die "failed to execute: $!\n"; - } +The default behavior is to break such lines into multiple lines, but this +behavior can be controlled with this flag. The values of n are: -This shows that blocks with a single statement become one-line blocks. + n=0 break nested one-line blocks into multiple lines [DEFAULT] + n=1 stable: keep existing nested-one line blocks intact -=item B<-olbxl=s>, B<--one-line-block-exclusion-list=s> +For the above example, the default formatting (B<-olbn=0>) is -As noted above, perltidy will, by default, attempt to create new one-line -blocks for certain block types. This flag allows the user to prevent this -behavior for the block types listed in the string B. The list B may -include any of the words C, C, C, C, or it may be C<*> -to indicate all of these. + foreach (@list) { + if ( $_ eq $asked_for ) { last } + ++$found; + } -So for example to prevent multi-line 'eval' blocks from becomming one-line -blocks, the command would be B<-olbxl='eval'>. In this case, existing one-line B blocks will remain on one-line if possible, and existing multi-line -B blocks will remain multi-line blocks. +If the parameter B<-olbn=1> is given, then the line will be left intact if it +is a single line in the source, or it will be broken into multiple lines if it +is broken in multiple lines in the source. =item B<-olbs=n>, B<--one-line-block-semicolons=n> @@ -4459,29 +4453,47 @@ all one-line blocks, regardless of complexity, the B option only removes ending semicolons which terminate one-line blocks containing just one semicolon. So these two options are not exact inverses. -=item B<-olbn=n>, B<--one-line-block-nesting=n> +=item B -Nested one-line blocks are lines with code blocks which themselves contain code -blocks. For example, the following line is a nested one-line block. +Sometimes it might be desirable to convert a script to have one-line blocks +whenever possible. Although there is currently no flag for this, a simple +workaround is to execute perltidy twice, once with the flag B<-noadd-newlines> +and then once again with normal parameters, like this: - foreach (@list) { if ($_ eq $asked_for) { last } ++$found } + cat infile | perltidy -nanl | perltidy >outfile -The default behavior is to break such lines into multiple lines, but this -behavior can be controlled with this flag. The values of n are: +When executed on this snippet - n=0 break nested one-line blocks into multiple lines [DEFAULT] - n=1 stable: keep existing nested-one line blocks intact + if ( $? == -1 ) { + die "failed to execute: $!\n"; + } + if ( $? == -1 ) { + print "Had enough.\n"; + die "failed to execute: $!\n"; + } -For the above example, the default formatting (B<-olbn=0>) is +the result is - foreach (@list) { - if ( $_ eq $asked_for ) { last } - ++$found; + if ( $? == -1 ) { die "failed to execute: $!\n"; } + if ( $? == -1 ) { + print "Had enough.\n"; + die "failed to execute: $!\n"; } -If the parameter B<-olbn=1> is given, then the line will be left intact if it -is a single line in the source, or it will be broken into multiple lines if it -is broken in multiple lines in the source. +This shows that blocks with a single statement become one-line blocks. + +=item B + +There is no automatic way to break existing long one-line blocks into multiple +lines, but this can be accomplished by processing a script, or section of a +script, with a short value of the parameter B. Then, +when the script is reformatted again with the normal parameters, the blocks +which were broken will remain broken (with the exceptions noted above). + +Another trick for doing this for certain block types is to format one time with +the B<-cuddled-else> flag and B<--cuddled-break-option=2>. Then format again +with the normal parameters. This will break any one-line blocks which are +involved in a cuddled-else style. =back @@ -4648,16 +4660,12 @@ This flag allows perltidy to handle certain common extensions to the standard syntax without complaint. For example, without this flag a structure such as the following would generate -a syntax error and the braces would not be balanced: +a syntax error: - method deposit( Num $amount) { + Method deposit( Num $amount) { $self->balance( $self->balance + $amount ); } -For one of the extensions, module Switch::Plain, colons are marked as labels. -If you use this module, you may want to also use the B<--nooutdent-labels> flag -to prevent lines such as 'default:' from being outdented. - This flag is enabled by default but it can be deactivated with B<-nxs>. Probably the only reason to deactivate this flag is to generate more diagnostic messages when debugging a script. @@ -5545,7 +5553,7 @@ The perltidy binary uses the Perl::Tidy module and is installed when that module =head1 VERSION -This man page documents perltidy version 20221112.04 +This man page documents perltidy version 20221112.05 =head1 BUG REPORTS diff --git a/lib/Perl/Tidy.pm b/lib/Perl/Tidy.pm index 8fe08edc..a8d6b834 100644 --- a/lib/Perl/Tidy.pm +++ b/lib/Perl/Tidy.pm @@ -113,7 +113,7 @@ BEGIN { # then the Release version must be bumped, and it is probably past time for # a release anyway. - $VERSION = '20221112.04'; + $VERSION = '20221112.05'; } sub DESTROY { diff --git a/lib/Perl/Tidy.pod b/lib/Perl/Tidy.pod index 3981a317..864111f5 100644 --- a/lib/Perl/Tidy.pod +++ b/lib/Perl/Tidy.pod @@ -475,7 +475,7 @@ The module 'Perl::Tidy' comes with a binary 'perltidy' which is installed when t =head1 VERSION -This man page documents Perl::Tidy version 20221112.04 +This man page documents Perl::Tidy version 20221112.05 =head1 LICENSE diff --git a/lib/Perl/Tidy/Debugger.pm b/lib/Perl/Tidy/Debugger.pm index b2dd78d4..24896f3c 100644 --- a/lib/Perl/Tidy/Debugger.pm +++ b/lib/Perl/Tidy/Debugger.pm @@ -8,7 +8,7 @@ package Perl::Tidy::Debugger; use strict; use warnings; use English qw( -no_match_vars ); -our $VERSION = '20221112.04'; +our $VERSION = '20221112.05'; use constant EMPTY_STRING => q{}; use constant SPACE => q{ }; diff --git a/lib/Perl/Tidy/DevNull.pm b/lib/Perl/Tidy/DevNull.pm index 84258520..bb41468a 100644 --- a/lib/Perl/Tidy/DevNull.pm +++ b/lib/Perl/Tidy/DevNull.pm @@ -7,7 +7,7 @@ package Perl::Tidy::DevNull; use strict; use warnings; -our $VERSION = '20221112.04'; +our $VERSION = '20221112.05'; sub new { my $self = shift; return bless {}, $self } sub print { return } sub close { return } diff --git a/lib/Perl/Tidy/Diagnostics.pm b/lib/Perl/Tidy/Diagnostics.pm index 7a82aa88..6b27ec31 100644 --- a/lib/Perl/Tidy/Diagnostics.pm +++ b/lib/Perl/Tidy/Diagnostics.pm @@ -21,7 +21,7 @@ package Perl::Tidy::Diagnostics; use strict; use warnings; use English qw( -no_match_vars ); -our $VERSION = '20221112.04'; +our $VERSION = '20221112.05'; use constant EMPTY_STRING => q{}; diff --git a/lib/Perl/Tidy/FileWriter.pm b/lib/Perl/Tidy/FileWriter.pm index 58b7e22c..6db1293b 100644 --- a/lib/Perl/Tidy/FileWriter.pm +++ b/lib/Perl/Tidy/FileWriter.pm @@ -7,7 +7,7 @@ package Perl::Tidy::FileWriter; use strict; use warnings; -our $VERSION = '20221112.04'; +our $VERSION = '20221112.05'; use constant DEVEL_MODE => 0; use constant EMPTY_STRING => q{}; diff --git a/lib/Perl/Tidy/Formatter.pm b/lib/Perl/Tidy/Formatter.pm index ca8a4f0b..0aa02702 100644 --- a/lib/Perl/Tidy/Formatter.pm +++ b/lib/Perl/Tidy/Formatter.pm @@ -53,7 +53,7 @@ use constant SPACE => q{ }; use Carp; use English qw( -no_match_vars ); use List::Util qw( min max ); # min, max are in Perl 5.8 -our $VERSION = '20221112.04'; +our $VERSION = '20221112.05'; # The Tokenizer will be loaded with the Formatter ##use Perl::Tidy::Tokenizer; # for is_keyword() diff --git a/lib/Perl/Tidy/HtmlWriter.pm b/lib/Perl/Tidy/HtmlWriter.pm index c6fe7c55..c8d75560 100644 --- a/lib/Perl/Tidy/HtmlWriter.pm +++ b/lib/Perl/Tidy/HtmlWriter.pm @@ -7,7 +7,7 @@ package Perl::Tidy::HtmlWriter; use strict; use warnings; -our $VERSION = '20221112.04'; +our $VERSION = '20221112.05'; use English qw( -no_match_vars ); use File::Basename; diff --git a/lib/Perl/Tidy/IOScalar.pm b/lib/Perl/Tidy/IOScalar.pm index 64a171db..8a78e6d5 100644 --- a/lib/Perl/Tidy/IOScalar.pm +++ b/lib/Perl/Tidy/IOScalar.pm @@ -10,7 +10,7 @@ package Perl::Tidy::IOScalar; use strict; use warnings; use Carp; -our $VERSION = '20221112.04'; +our $VERSION = '20221112.05'; use constant EMPTY_STRING => q{}; diff --git a/lib/Perl/Tidy/IOScalarArray.pm b/lib/Perl/Tidy/IOScalarArray.pm index 3b62a32a..339582f2 100644 --- a/lib/Perl/Tidy/IOScalarArray.pm +++ b/lib/Perl/Tidy/IOScalarArray.pm @@ -14,7 +14,7 @@ package Perl::Tidy::IOScalarArray; use strict; use warnings; use Carp; -our $VERSION = '20221112.04'; +our $VERSION = '20221112.05'; sub AUTOLOAD { diff --git a/lib/Perl/Tidy/IndentationItem.pm b/lib/Perl/Tidy/IndentationItem.pm index f456eb55..71a253e0 100644 --- a/lib/Perl/Tidy/IndentationItem.pm +++ b/lib/Perl/Tidy/IndentationItem.pm @@ -8,7 +8,7 @@ package Perl::Tidy::IndentationItem; use strict; use warnings; -our $VERSION = '20221112.04'; +our $VERSION = '20221112.05'; BEGIN { diff --git a/lib/Perl/Tidy/LineBuffer.pm b/lib/Perl/Tidy/LineBuffer.pm index 1b0e91ea..c0192547 100644 --- a/lib/Perl/Tidy/LineBuffer.pm +++ b/lib/Perl/Tidy/LineBuffer.pm @@ -12,7 +12,7 @@ package Perl::Tidy::LineBuffer; use strict; use warnings; -our $VERSION = '20221112.04'; +our $VERSION = '20221112.05'; sub AUTOLOAD { diff --git a/lib/Perl/Tidy/LineSink.pm b/lib/Perl/Tidy/LineSink.pm index 2e2af90d..4db6a4cd 100644 --- a/lib/Perl/Tidy/LineSink.pm +++ b/lib/Perl/Tidy/LineSink.pm @@ -8,7 +8,7 @@ package Perl::Tidy::LineSink; use strict; use warnings; -our $VERSION = '20221112.04'; +our $VERSION = '20221112.05'; sub AUTOLOAD { diff --git a/lib/Perl/Tidy/LineSource.pm b/lib/Perl/Tidy/LineSource.pm index b97533dd..3c089a09 100644 --- a/lib/Perl/Tidy/LineSource.pm +++ b/lib/Perl/Tidy/LineSource.pm @@ -9,7 +9,7 @@ package Perl::Tidy::LineSource; use strict; use warnings; use English qw( -no_match_vars ); -our $VERSION = '20221112.04'; +our $VERSION = '20221112.05'; use constant DEVEL_MODE => 0; diff --git a/lib/Perl/Tidy/Logger.pm b/lib/Perl/Tidy/Logger.pm index dde26e30..43617e23 100644 --- a/lib/Perl/Tidy/Logger.pm +++ b/lib/Perl/Tidy/Logger.pm @@ -8,7 +8,7 @@ package Perl::Tidy::Logger; use strict; use warnings; -our $VERSION = '20221112.04'; +our $VERSION = '20221112.05'; use English qw( -no_match_vars ); use constant DEVEL_MODE => 0; diff --git a/lib/Perl/Tidy/Tokenizer.pm b/lib/Perl/Tidy/Tokenizer.pm index d5bbeaba..0d45e745 100644 --- a/lib/Perl/Tidy/Tokenizer.pm +++ b/lib/Perl/Tidy/Tokenizer.pm @@ -23,7 +23,7 @@ use strict; use warnings; use English qw( -no_match_vars ); -our $VERSION = '20221112.04'; +our $VERSION = '20221112.05'; use Perl::Tidy::LineBuffer; use Carp; diff --git a/lib/Perl/Tidy/VerticalAligner.pm b/lib/Perl/Tidy/VerticalAligner.pm index 76b72917..d22a265f 100644 --- a/lib/Perl/Tidy/VerticalAligner.pm +++ b/lib/Perl/Tidy/VerticalAligner.pm @@ -3,7 +3,7 @@ use strict; use warnings; use Carp; use English qw( -no_match_vars ); -our $VERSION = '20221112.04'; +our $VERSION = '20221112.05'; use Perl::Tidy::VerticalAligner::Alignment; use Perl::Tidy::VerticalAligner::Line; diff --git a/lib/Perl/Tidy/VerticalAligner/Alignment.pm b/lib/Perl/Tidy/VerticalAligner/Alignment.pm index b1b037bb..f612f74f 100644 --- a/lib/Perl/Tidy/VerticalAligner/Alignment.pm +++ b/lib/Perl/Tidy/VerticalAligner/Alignment.pm @@ -10,7 +10,7 @@ use warnings; { #<<< A non-indenting brace -our $VERSION = '20221112.04'; +our $VERSION = '20221112.05'; sub new { my ( $class, $rarg ) = @_; diff --git a/lib/Perl/Tidy/VerticalAligner/Line.pm b/lib/Perl/Tidy/VerticalAligner/Line.pm index e11f6661..31057434 100644 --- a/lib/Perl/Tidy/VerticalAligner/Line.pm +++ b/lib/Perl/Tidy/VerticalAligner/Line.pm @@ -10,7 +10,7 @@ package Perl::Tidy::VerticalAligner::Line; use strict; use warnings; use English qw( -no_match_vars ); -our $VERSION = '20221112.04'; +our $VERSION = '20221112.05'; sub AUTOLOAD {