From: Steve Hancock Date: Thu, 24 Jun 2021 13:15:31 +0000 (-0700) Subject: update to version 20210625 X-Git-Tag: 20210625^0 X-Git-Url: https://git.donarmstrong.com/?a=commitdiff_plain;h=a4ff53d388aef33b765949b519ac0ddb37739e01;p=perltidy.git update to version 20210625 --- diff --git a/CHANGES.md b/CHANGES.md index fb9e07f0..0646e2ae 100644 --- a/CHANGES.md +++ b/CHANGES.md @@ -1,29 +1,34 @@ # Perltidy Change Log -## 2021 04 02.01 +## 2021 06 25 + + - This release adds several new requested parameters. No significant bugs have + been found since the last release, but a number of minor problems have been + corrected. - Added a new option '--code-skipping', requested in git #65, in which code between comment lines '#<>V' is passed verbatim to the output - stream without error checking. It is simmilar to --format skipping - but there is no error checking, and is useful for skipping an extended - syntax. + stream without error checking. It is simmilar to --format-skipping + but there is no error checking of the skipped code. This can be useful for + skipping past code which employs an extended syntax. - Added a new option for closing paren placement, -vtc=3, requested in rt #136417. - - Some nested structures formatted with the -lp indentation option may have - some changes in indentation. This is due to some updates which were made to - prevent formatting instability when line lengths are limited by the maximum line - length. Most scripts will not be affected. - - Added flag -atnl, --add-terminal-newline, to help issue git #58. - This flag, which is enabled by default, allows perltidy to terminate - the last line of the output stream with a newline character, regardless - of whether or not the input stream was terminated with a newline - character. If this flag is negated, with -natnl, then perltidy will - add a terminal newline to the the output stream only if the input + This flag tells perltidy to terminate the last line of the output stream + with a newline character, regardless of whether or not the input stream + was terminated with a newline character. This is the default. + If this flag is negated, with -natnl, then perltidy will add a terminal + newline character to the the output stream only if the input stream is terminated with a newline. - - Numerous minor fixes have been made. A more complete list of updates is at: + - Some nested structures formatted with the -lp indentation option may have + some changes in indentation. This is due to updates which were made to + prevent formatting instability when line lengths are limited by the maximum line + length. Most scripts will not be affected. If this causes unwanted formatting + changes, try increasing the --maximum-line-length by a few characters. + + - Numerous minor fixes have been made. A complete list is at: https://github.com/perltidy/perltidy/blob/master/local-docs/BugLog.pod diff --git a/bin/perltidy b/bin/perltidy index ff29964d..8e0a8c1c 100755 --- a/bin/perltidy +++ b/bin/perltidy @@ -4776,7 +4776,7 @@ The perltidy binary uses the Perl::Tidy module and is installed when that module =head1 VERSION -This man page documents perltidy version 20210402.01 +This man page documents perltidy version 20210625 =head1 BUG REPORTS diff --git a/dev-bin/perltidy_random_setup.pl b/dev-bin/perltidy_random_setup.pl index 4222028e..e30d52a3 100755 --- a/dev-bin/perltidy_random_setup.pl +++ b/dev-bin/perltidy_random_setup.pl @@ -1118,6 +1118,9 @@ EOM delete-pod tabs entab-leading-whitespace + recombine + code-skipping-begin + code-skipping-end ); my %skip; diff --git a/docs/BugLog.html b/docs/BugLog.html index eb46caba..a770e72d 100644 --- a/docs/BugLog.html +++ b/docs/BugLog.html @@ -12,6 +12,7 @@ +

Issues fixed after release 20210402

+ +
+ +
Adjust tolerances to fix some unstable edge cases
+
+ +

Testing with random input parameters produced a number of edge cases of unstable formatting which were traced to the parameter combinations which included -lp and some other unusual settings.

+ +

This fixes cases b1103 b1134 b1135 b1136 b1138 b1140 b1143 b1144 b1145 b1146 b1147 b1148 b1151 b1152 b1153 b1154 b1156 b1157 b1163 b1164 b1165

+ +

There are no other known cases of formatting instability at the present time, but testing with random input parameters will continue.

+ +

21 Jun 2021.

+ +
+
Adjust tolerances to fix some unstable edge cases
+
+ +

Testing with random input parameters produced a number of edge cases of unstable formatting which were traced to the parameter combinations which included -bbxi=2 and -cab=2. A small adjustment to length tolerances was made to fix the problem.

+ +

This fixes cases b1137 b1149 b1150 b1155 b1158 b1159 b1160 b1161 b1166 b1167 b1168.

+ +

19 Jun 2021, 4d4970a.

+ +
+
Added flag -atnl, --add-terminal-newline, see git #58
+
+ +

This flag, which is enabled by default, allows perltidy to terminate the last line of the output stream with a newline character, regardless of whether or not the input stream was terminated with a newline character. If this flag is negated, with -natnl, then perltidy will add a terminal newline to the the output stream only if the input stream is terminated with a newline.

+ +

Negating this flag may be useful for manipulating one-line scripts intended for use on a command line.

+ +

This update also removes the description of the obsolete --check-syntax flag from the man pages and help text.

+ +

18 Jun 2021, 6f83170.

+ +
+
Allow --delete-side-comments to work with -nanl
+
+ +

The -nanl flag (--noadd-newlines) was preventing side comments from being deleted, for example:

+ +
    # perltidy -dsc -nanl
+    calc()    # side comment
+ +

The same issue was happening for --delete-closing-side comments. This has been fixed.

+ +

18 Jun 2021, dbfd802.

+ +
+
Update welding rule to avoid unstable states
+
+ +

Testing with random input parameters produced a formatting instability involving an unusual parameter combination:

+ +
    --noadd-whitespace
+    --break-before-paren=3
+    --continuation-indentation=8
+    --delete-old-whitespace
+    --line-up-parentheses
+    --weld-nested-containers
+ +

and the following code

+ +
        if(defined$hints{family}){
+            @infos=({
+                     family=>$hints{family},
+                     socktype=>$hints{socktype},
+                     protocol=>$hints{protocol},
+            });
+        }
+ +

This update fixes the problem, case b1162.

+ +

18 Jun 2021, 76873ea.

+ +
+
Convert some weld sub calls to hash lookups
+
+ +

This is a minor optimization. These subs are eliminated: is_welded_right_at_K, is_welded_left_at_K, weld_len_right_at_K.

+ +

17 Jun 2021, 1691013.

+ +
+
Update LineSink.pm to allow undefined line endings
+
+ +

This update is necessary to eventually prevent an unwanted terminal newline being added to a file.

+ +

17 Jun 2021, 2600533.

+ +
+
Fix incorrect sub call
+
+ +

This fixes an incorrect call which could cause an incorrect weld.

+ +

16 Jun 2021, 068a28b.

+ +
+
Add --code-skipping option, see git #65
+
+ +

Added a new option '--code-skipping', requested in git #65, in which code between comment lines '#<<V' and '#>>V' is passed verbatim to the output stream without error checking. It is simmilar to --format skipping but there is no error checking, and is useful for skipping an extended syntax.

+ +

16 Jun 2021, 99ec876.

+ +
+
Handle nested print format blocks
+
+ +

Perltidy was producing an error at nested print format blocks, such as

+ +
    format NEST =
+    @<<<
+    {
+        my $birds = "birds";
+        local *NEST = *BIRDS{FORMAT};
+        write NEST;
+        format BIRDS =
+    @<<<<<
+    $birds;
+    .
+    "nest"
+      }
+    .
+ +

It was ending the first format at the first '.' rather than the second '.' in this example. This update fixes this, issue c019.

+ +

13 Jun 2021.

+ +
+
Allow stacked labels without spaces
+
+ +

When labels are stacked in a single line, such as

+ +

A:B:C:

+ +

the default is to space them:

+ +

A: B: C:

+ +

This update allows the spaces to be removed if desired:

+ +

# perltidy -naws -dws A:B:C:

+ +

13 Jun 2021, c2a63b2

+ +
+
Fix edge cases of instability involving -wn -lp
+
+ +

Random testing produced some cases of instability involving -wn -lp and some unusual additional parameters. These were traced to a test for welding, and were fixed by refining a certain tolerance. This fixes cases b1141, b1142.

+ +

12 Jun 2021, 125494b.

+ +
+
Remove incorrect warning at repeated function paren call
+
+ +

This update removes an incorrect error messagge at the construct ')('. To illustrate, the following is a valid program:

+ +
    my @words = qw(To view this email as a web page go here);
+    my @subs;
+    push @subs, sub { my $i=shift; $i %= @words; print "$words[$i] "; return $subs[0]};
+    $subs[0](0)(1)(2)(3)(4)(5)(6)(7)(8)(9)(10)(11);
+    print "\n";
+ +

However perltidy was giving an error message at the ')(' combination, which is unusual in perl scripts. This update fixes this.

+ +

These are function call parens, so logically they should be under control of the -sfp or --space-function-parens parameter. I wrote a patch to do this, but decided not to implement it. The reason is that, as noted in the manual, subtle errors in perl scripts can occur when spaces are placed before parens. So, to avoid possible problems, the -sfp parameter will be restricted to spaces between a bareword [assumed to be a function] and a paren.

+ +

This update is in Tokenizer.pm and fixes case c017.

+ +

6 Jun 2021, 6551d65.

+ +
+
Add warning when lexical sub names match some builtins
+
+ +

This update adds a warning when lexical subs have names which match some builtin names which will almost certainly cause a parsing error in the current version of perltidy. For example, the following program is valid and will run, but perltidy will produce an error.

+ +
    use feature qw(lexical_subs);
+    use warnings; no warnings "experimental::lexical_subs";
+    {
+      my sub y { print "Hello from y: $_[0]\n"; }
+      y(1);
+    }
+ +

6 Jun 2021, 32729fb.

+ +
+
Minor cleanups
+
+ +

This update fixes a case of formatting instability recently found with random testing. It also does some minor coding cleanups.

+ +

This fixes case b1139.

+ +

5 Jun 2021, b8527ab.

+ +
+
Revised data structures for welding
+
+ +

This update replaces the data structures used for the welding option with simpler but more general structures. This cleans up the code and will simplify future coding. No formatting changes should occur with this update.

+ +

4 Jun 2021, 4a886c8.

+ +
+
improved treatment of lexical subs
+
+ +

This update improves the treatment of lexical subs. Previously they were formatted correctly but an error would have been produced if the same name was used for lexical subs defined in different blocks.

+ +

For example, running the previous version of perltidy on the following:

+ +
    use feature qw(lexical_subs);
+    use warnings; no warnings "experimental::lexical_subs";
+    {
+        my sub hello { print "Hello from hello1\n" }
+        {
+            my sub hello { print "Hello from hello2\n" }
+            hello();
+        }
+        hello();
+    }
+    {
+        my sub hello { print "Hello from hello3\n" }
+        hello();
+    }
+ +

gave the (incorrect) error message:

+ +
    6: already saw definition of 'sub hello' in package 'main' at line 4
+    12: already saw definition of 'sub hello' in package 'main' at line 6
+ +

This update fixes that.

+ +

1 Jun 2021, 85ecb7a.

+ +
+
add v-string underscores; warn of leading commas
+
+ +

This update cleans up a couple of open issues in the tokenizer.

+ +

A warning message will be produced for a list which begins with a comma:

+ +
            my %string = (
+              ,       "saddr",    $stest,  "daddr",
+              $dtest, "source",   $sname,  "dest")
+ +

This warning had been temporarily deactivated.

+ +

Underscores in v-strings without a leading 'v' are now parsed correctly.

+ +

Several comments have been updated.

+ +

31 May 2021, ef44e70.

+ +
+
Fix parsing error at operator following a comma
+
+ +

The following lines are syntactically correct but some were producing a syntax error

+ +
    print "hello1\n", || print "hi1\n";
+    print "hello2\n", && print "bye2\n";
+    print "hello3\n", or print "bye3\n";
+    print "hello4\n", and print "bye4\n";
+ +

For example, the first line produced this message

+ +
    1: print "hello1\n", || print "hi1\n";
+                       - ^
+    found || where term expected (previous token underlined)
+ +

This has been fixed. This fixes case c015.

+ +

27 May 2021, b537a72.

+ +
+
Added optional o in octal number definitions
+
+ +

An optional letter 'o' or 'O' in the octal representation of numbers, which was added in perl version 5.33.5, is now recogized. The leading zero is still required.

+ +

For example:

+ +
    $a = 0o100;
+    $a = 0O100;
+ +

26 May 2021, 544df8c.

+ +
+
Fix several problems with -lp formatting
+
+ +

This update fixes several problems with -lp formatting which are all somewhat related.

+ +

ISSUE #1 (cases c002 and c004): A problem involving -lp -wn and certain qw lists

+ +

The last line of a welded qw list was being outdented even if it contained text as well as the closing container token. This update fixes the problem and simplifies the logic.

+ +

A few examples (all use 'perltidy -wn -lp'):

+ +
    # OLD and NEW: OK, closing qw paren is on separate line
+    $roads->add_capacity_path( qw( CoolCity 10 ChocolateGulch 8
+                               PecanPeak 10 BlueberryWoods 6
+                               HotCity
+    ) );
+
+    # OLD: poor; outdented text not aligned with previous text
+    $roads->add_capacity_path( qw( CoolCity 10 ChocolateGulch 8
+                               PecanPeak 10 BlueberryWoods 6
+    HotCity ) );
+
+    # NEW:
+    $roads->add_capacity_path( qw( CoolCity 10 ChocolateGulch 8
+                               PecanPeak 10 BlueberryWoods 6
+                               HotCity ) );
+
+    # OLD:
+    $roads->add_capacity_path( qw( ChocolateGulch 3 StrawberryFields 0
+    StrawberryFields ) );
+
+    # NEW:
+    $roads->add_capacity_path( qw( ChocolateGulch 3 StrawberryFields 0
+                               StrawberryFields ) );
+
+    # OLD:
+    my $mon_name = ( qw(January February March April
+                     May June July August
+    September October November December) )[$mon];
+
+    # NEW
+    my $mon_name = ( qw(January February March April
+                     May June July August
+                     September October November December) )[$mon];
+ +

ISSUE #2 (case c007): A rare program error could be triggered with -lp -xci

+ +

In some very rare circumstances it was possible to trigger a "Program error" message. The program still ran to completion. The conditions for this to occur were that flags -lp -xci were set, and that there was a container of sort/map/grep blocks, and there was a side comment on the closing paren. For example:

+ +
    # OLD: perltidy -lp -xci, gave an error message and extra indentation here
+    my %specified_opts = (
+          (
+                          map { /^no-?(.*)$/i ? ($1 => 0) : ($_ => 1) }
+                          map { /^--([\-_\w]+)$/ } @ARGV
+          ),    # this comment caused an error with flags -lp -xci
+    );
+
+    # NEW: perltidy -lp -xci, no error
+    my %specified_opts = (
+          (
+             map { /^no-?(.*)$/i ? ( $1 => 0 ) : ( $_ => 1 ) }
+             map { /^--([\-_\w]+)$/ } @ARGV
+          ),    # this comment caused an error with flags -lp -xci
+    );
+ +

ISSUE #3 (case c008): In some unusual cases the -lp formatting style was not being applied when it should have been. For example (text is shifted right):

+ +
    # NEW: perltidy -lp
+    $result = runperl(
+        switches => [ '-I.', "-w" ],
+        stderr   => 1,
+        prog     => <<'PROG' );
+    SIG
+    PROG
+
+    # NEW: perltidy -lp
+    $result = runperl(
+                       switches => [ '-I.', "-w" ],
+                       stderr   => 1,
+                       prog     => <<'PROG' );
+    SIG
+    PROG
+ +

25 May 2021, 6947fe9.

+ +
+
Modify welding rules
+
+ +

This is an update to the patch 19 Apr 2021, eeeaf09. It restricts that patch to -lp formatting mode.

+ +

This fixes case b1131.

+ +

21 May 2021, a4ec4c1.

+ +
+
Fix inconsistency involving counting commas
+
+ +

Random testing produced a formatting instability involving the combination of flags -bbp=2 -xci -vt=2 -bvtc=2. The problem was traced to an error in counting the number of line ending commas in lists.

+ +

This fixes case b1130.

+ +

15 May 2021, 90cceb1.

+ +
+
Slightly modify line breaks for -lp indentation
+
+ +

Random testing produced an edge case of formatting instability for -lp indentation which was traced to checking for an old line break at a '=>'. This has been fixed. Some existing formatting with deeply nested structures may be slightly changed due to the fix, but most existing formatting will be unchanged.

+ +

This fixes b1035.

+ +

15 May 2021, dd42648.

+ +
+
Rewrite coding for -bom flag
+
+ +

Random testing produced some examples of formatting instability involving the -bom flag in combination with certain other flags which are fixed with this update. As part of this update, a previous update to fix case b977 (21 Feb 2021, commit 28114e9) was revised to use a better criterion for deciding when not to keep a ')->' break. The previous criterion was that the opening and closing containers should be separated by more than one line. The new criterion is that they should contain a list. This still fixes case b977. Another case, b1120, was fixed by requiring that only parentheses expressions be considered for keeping a line break, not '}->' or ']->'.

+ +

Some issues are illustrated in the following examples using '-bom -gnu'. In the first example the leading ')->' was being lost due to the old b977 fix:

+ +
    # input:
+    $show = $top->Entry( '-width' => 20,
+                       )->pack('-side' => 'left');
+
+    # OLD: perltidy -gnu -bom
+    $show = $top->Entry('-width' => 20,)->pack('-side' => 'left');
+
+    # NEW: perltidy -gnu -bom
+    $show = $top->Entry(
+                        '-width' => 20,
+                       )->pack('-side' => 'left');
+ +

In the following example a leading '->' was being lost. The NEW version keeps the leading '->' but has to give up on the -lp alignment because of complexity:

+ +
        # input
+        $_make_phase_arg = join(" ",
+                           map {CPAN::HandleConfig
+                                 ->safe_quote($_)} @{$prefs->{$phase}{args}},
+                          );
+
+        # OLD: perltidy -gnu -bom
+        $_make_phase_arg = join(" ",
+                                map { CPAN::HandleConfig->safe_quote($_) }
+                                  @{$prefs->{$phase}{args}},
+                               );
+
+        # NEW: perltidy -gnu -bom
+        $_make_phase_arg = join(
+            " ",
+            map {
+                CPAN::HandleConfig
+                  ->safe_quote($_)
+            } @{$prefs->{$phase}{args}},
+        );
+ +

In the following example, a leading ')->' was being converted to a leading '->' due to the old b977 fix:

+ +
    # Starting script
+    $lb = $t->Scrolled("Listbox", -scrollbars => "osoe"
+                      )->pack(-fill => "both", -expand => 1);
+
+    # OLD: perltidy -bom -gnu
+    $lb = $t->Scrolled( "Listbox", -scrollbars => "osoe" )
+      ->pack( -fill => "both", -expand => 1 );
+
+    # NEW: perltidy -bom -gnu
+    $lb = $t->Scrolled(
+                       "Listbox", -scrollbars => "osoe"
+                      )->pack(-fill => "both", -expand => 1);
+ +

In the following example, a leading ')->' was being lost, again due to the old b977 fix:

+ +
    $myDiag->Label(-text => $text,
+                                  )->pack(-fill => 'x',
+                                                  -padx => 3,
+                                                  -pady => 3);
+
+    # OLD: -gnu -bom
+    $myDiag->Label(-text => $text,)->pack(
+                                          -fill => 'x',
+                                          -padx => 3,
+                                          -pady => 3
+                                         );
+
+    # NEW -gnu -bom
+    $myDiag->Label(
+                   -text => $text,
+      )->pack(
+              -fill => 'x',
+              -padx => 3,
+              -pady => 3
+             );
+ +

This update fixes case b1120 and revises the fix for b977.

+ +

13 May 2021, d0ac5e9.

+ +
+
Adjust tolerances for some line length tests
+
+ +

Random testing produced some edge cases of unstable formatting involving the -lp format. These were fixed by using a slightly larger tolerance in the length test for containers which were broken in the input file.

+ +

This fixes cases b1059 b1063 b1117.

+ +

13 May 2021, 24a11d3.

+ +
+
Do not apply -lp formatting to containers with here-doc text
+
+ +

If a container contains text of a here-doc then the indentation is fixed by the here-doc text, so applying -lp formatting does not work well. So this update turns off the -lp formatting in this case.

+ +

But note that if a container contains a here target but not the here text so it still gets the -lp indentation:

+ +
    # perltidy -lp
+    &WH::Spell::AddSpell(
+                          "Cause Light Wounds", "WFP",
+                          "CauseLightWounds",   <<'EOH');
+    ...
+    EOH
+ +

This fixes case b1081.

+ +

10 May 2021, 4f7a56b.

+ +
+
Fix some edge welding cases
+
+ +

Some adjustments in welding coding was made to maintain stability for some unusual parameter combinations.

+ +

This fixes cases b1111 b1112.

+ +

9 May 2021, 68f619a.

+ +
+
Improve tolerance for welding qw quotes
+
+ +

The tolerance for welding qw quotes has been update to be the same as used for welding other tokens. This fixes case b1129.

+ +

9 May 2021, d1de85f.

+ +
+
Revise weld tolerances, simplify code, fix welded ci
+
+ +

The welding process uses a tolerance to keep results stable. Basically, a zero tolerance is used if it looks like it is welding an existing weld, while a finite tolerance is used otherwise. The effect is to reject a few marginal welds to gain stability. The coding to do this was simplified and the tolerance was made more precise to fix case b1124.

+ +

Another change with this update is that at welded containers, the value of the -ci flag of an outer opening token is transferred to the inner opening token. This may improve some indentation in a few cases if the -lp flag is also used. It has no effect if -lp is not used.

+ +
    # OLD: perltidy -wn -gnu
+    emit_symbols([qw(
+     ctermid
+     get_sysinfo
+     Perl_OS2_init
+     ...
+     CroakWinError
+    )]);
+
+    # NEW: perltidy -wn -gnu
+    emit_symbols([qw(
+        ctermid
+        get_sysinfo
+        Perl_OS2_init
+        ...
+        CroakWinError
+    )]);
+ +

9 May 2021, ad8870b.

+ +
+
Correct brace types mismarked by tokenizer, update
+
+ +

This is a generalization of commit 7d3bf4 in which the tokenizer sends a signal to the formatter if the type of a brace following an unknown bareword had to be guessed. The formatter has more information and can fix the problem. This fixes case b1128.

+ +

8 May 2021, b3eaf23.

+ +
+
Added warning when -ci has to be reduced; ref rt #136415
+
+ +

In commit c16c5ee an update was made to prevent instability with -xci when the value of -ci exceeds -i (which is not recommended). This update adds a warning message to avoid confusing the user.

+ +

7 May 2021, e9e14e4.

+ +
+
Improve indentation of welded multiline qw quotes
+
+ +

Formatting of multiline qw lists with welding works best if the opening and closing qw tokens are on separate lines, like this:

+ +
    # perltidy -wn
+    my $mon_name = ( qw(
+        January February March April
+        May June July August
+        September October November December
+    ) )[$mon];
+
+    # perltidy -wn -lp
+    my $mon_name = ( qw(
+                     January February March April
+                     May June July August
+                     September October November December
+    ) )[$mon];
+ +

Otherwise formatting can be poor, particularly if the last line has text and a closing container.

+ +
    # OLD: perltidy -wn
+    my $mon_name = ( qw(January February March April
+        May June July August
+    September October November December) )[$mon];
+ +

Note that perltidy does not change the line breaks within multiline quotes, so they must be changed by hand if desired.

+ +

This update indents the last line of a multiline quote which contains both text and the closing token, such as:

+ +
    # NEW: perltidy -wn
+    my $mon_name = ( qw(January February March April
+        May June July August
+        September October November December) )[$mon];
+ +

This update is only when the -lp flag is not used. If -lp is used and the last line contains text, the last line is still outdented:

+ +
    $ OLD and NEW: perltidy -wn -lp
+    my $mon_name = ( qw(January February March April
+                     May June July August
+    September October November December) )[$mon];
+ +

This is difficult to fix. The best solution is to place the closing qw qw containers on a separate line.

+ +

This fix is for case c002.

+ +

6 May 2021, 176f8a7.

+ +
+
Test length of closing multiline qw quote before welding
+
+ +

Random testing produced an unstable state which was due to not checking for excessive length of the last line of a multiline qw quote. A check was added, this fixes issue b1039.

+ +

5 May 2021, b72ad24.

+ +
+
Update welding rule to avoid blinking states
+
+ +

Random testing with unusual parameter combinations produced some unstable welds. For example case b1106 has these parameters

+ +
    --noadd-whitespace
+    --continuation-indentation=6
+    --delete-old-whitespace
+    --line-up-parentheses
+    --maximum-line-length=36
+    --variable-maximum-line-length
+    --weld-nested-containers
+ +

and was switching between these two states:

+ +
            return map{
+                ($_,[$self->$_(@_[1..$#_])])
+            }@every;
+
+            return map { (
+                $_, [ $self->$_( @_[ 1 .. $#_ ] ) ]
+            ) } @every;
+ +

An existing rule, WELD RULE 2, was updated to prevent welding to an intact one-line weld, as in the first snippet, if it is on a separate line from the first opening token. With this change, both of these states are stable.

+ +

This update fixes cases b1082 b1102 b1106 b1115.

+ +

4 May 2021, 07efa9d.

+ +
+
Fix problem of conflict of -otr and -lp
+
+ +

Several random test cases produced an instability involving -otr and -lp. In -lp mode, when an opening paren follows an equals and is far to the right, a break is made at the equals to minimize the indentation of the next lines. The -otr flag is a suggestion that an opening paren should be place on the right. A check has been made to avoid this in -lp mode following an equals, since that defeats the purpose of the original break.

+ +

This fixes cases b964 b1040 b1062 b1083 b1089.

+ +

4 May 2021, 24a0d32.

+ +
+
Add option -pvtc=3, requested in rt136417
+
+ +

A new integer option, n=3, has been added to the vertical tightness closing flags. For a container with n=3, the closing token will behave as for n=0 if the opening token is preceded by an '=' or '=>', and like n=1 otherwise.

+ +

3 May 2021, 93063a7.

+ +
+
Fix vertical alignment issue in rt136416
+
+ +

This update fixes a problem with unwanted vertical alignment rasied in rt#136416. The example is

+ +
    use File::Spec::Functions 'catfile', 'catdir';
+    use Mojo::Base 'Mojolicious',        '-signatures';
+ +

An update was made to reject alignments in use statements with different module names. The test file t/snippets/align35.in has more examples.

+ +

3 May 2021, 048126c.

+ +
+
Fix some rare issues with the -lp option
+
+ +

Random testing produced some rare cases of unstable formatting involving the -lp option which are fixed with this update. This is a generalization of commit edc7878 of 23 Jan 2021. This fixes cases b1109 b1110.

+ +

2 May 2021, a8d1c8b.

+ +
+
Correct brace types mismarked by tokenizer
+
+ +

This is a generalization of commit 7d23bf4 to fix some additional cases found in random testing in which the type of a curly brace could not be determined in the tokenizer and was not being corrected by the formatter.

+ +

This fixes cases b1125 b1126 b1127.

+ +

2 May 2021i, dac97cb.

+ +
+
Avoid instability of combination -bbx=2 -lp and -xci
+
+ +

Random testing produced several cases in which the flags -bbx=2 -lp and -xci were causing formatting instability. The fix is to locally turn off -xci when -lp and -bbx=2 are in effect. This is an extension of commit 2b05051.

+ +

This fixes cases b1090 b1095 b1101 b1116 b1118 b1121 b1122 b1099

+ +

1 May 2021, 4cb81ba.

+ +
+
Restrict use of flag -cab=3 to simple structures
+
+ +

Logic was added to turn off -cab=3 in complex structures. Otherwise, instability can occur. When it is overridden the behavior of the closest match, -cab=2, is used instead.

+ +

For example, using these parameters for case b1113

+ +
    --noadd-whitespace
+    --break-before-hash-brace-and-indent=2
+    --break-before-hash-brace=1
+    --comma-arrow-breakpoints=3
+    --continuation-indentation=9
+    --maximum-line-length=76
+    --variable-maximum-line-length
+ +

formatting of the following snippet was unstable:

+ +
    $STYLESHEET{'html-light'}={
+        'tags'=>{
+            'predefined identifier'=>
+                     {
+                'start'=>'<font color="#2040a0"><strong>',
+                'stop'=>'</strong></font>'
+                     },
+        }
+    };
+ +

This update fixes cases b1096 b1113.

+ +

29 Apr 2021, 32a1830.

+ +
+
Update docs for git #64 regarding -lp and side comments
+
+ +

The wording regarding when -lp reverts to the default indentation scheme has been revised to include side comment as follows:

+ +

In situations where perltidy does not have complete freedom to choose line breaks it may temporarily revert to its default indentation method. This can occur for example if there are blank lines, block comments, multi-line quotes, or side comments between the opening and closing parens, braces, or brackets.

+ +

The word 'may' is significant for side comments. In a list which is just one level deep side comments will work (perhaps with -iscl if side comments are long). For example this is ok

+ +
    # perltidy -lp
+    $gif->arc(
+               50, 50,     # Center x, y.
+               30, 30,     # Width, Height.
+               0,  360,    # Start Angle, End Angle.
+               $red
+    );
+ +

But if a list is more than one level deep then the default indentation is used.

+ +

28 Apr 2021, 49977b8.

+ +
+
Fix line break rules for uncontained commas + cleanups
+
+ +

This is an adjustment of update 344519e which had to do with breaking lines with commas which were not inside of a container. In a few cases it was producing very long lines when -l=0 was set. The solution was to remove the concatenation operator from the list of operators at which breaks were prevented.

+ +

Other updates are: Remove unused indentation table. Correct maximum_line_length table for -vmll when -wc is also set. Also fix whitespace rule for '$ =' within a signature to fix case b1123.

+ +

26 Apr 2021, d014c2a.

+ +
+
Fix problem with -wn and -wc=n
+
+ +

Random testing produced some cases in which the -wn flag was unstable when -wc=n was used with very small n. This has been fixed.

+ +

This fixes cases: b1098 b1107 25 Apr 2021, 92babdf.

+ +
+
Adjust line break rules for uncontained commas
+
+ +

Random testing produced case c1119 which was unstable due to the formatting rules for breaking lines at commas which occur outside of containers. The rules were modified to fix the problem.

+ +

20 Apr 2021, 344519e.

+ +
+
Fix a bad line break choice at a slash
+
+ +

Random testing produced case c001 in which the following snipppet

+ +
   ok $mi/(@mtime-1) >= 0.75 && $ai/(@atime-1) >= 0.75 &&
+             $ss/(@mtime+@atime) >= 0.2;
+ +

when processed with these parameters

+ +
    --maximum-line-length=20
+    --nowant-right-space=' / '
+    --want-break-before='* /'
+ +

produced the following result

+ +
    ok $mi
+      /( @mtime - 1 ) >=
+      0.75
+      && $ai
+      /( @atime - 1 )
+      >= 0.75
+      && $ss
+      /( @mtime +
+          @atime ) >=
+      0.2;
+ +

using 'perl -cw' on this snippet gives a syntax error

+ +
    syntax error at /tmp/issues.t line 5, near "/( "
+        (Might be a runaway multi-line // string starting on line 2)
+ +

The error is due to perl's weird parsing rules near a possible indrect object. This is a situation where perltidy must ignore a user spacing and line break request. This should have been done but in this case a flag to prevent this was not being propagated to later stages of formatting. This has been fixed.

+ +

20 Apr 2021, 4fbc69a.

+ +
+
Fix rare problem with -lp -wn
+
+ +

Random testing produced case b1114 which gave unstable formatting with these parameters

+ +
    --noadd-whitespace
+    --indent-columns=8
+    --line-up-parentheses
+    --maximum-line-length=25
+    --weld-nested-containers
+ +

and this snippet

+ +
    is(length(pack("j", 0)),
+        $Config{ivsize});
+ +

Fixed 19 Apr 2021, eeeaf09.

+ +
+
Fix issue git#63
+
+ +

The following lines produced an error message due to the side comment

+ +
    my $fragment = $parser->    #parse_html_string
+      parse_balanced_chunk($I);
+ +

Fixed 18 Apr 2021, c2030cf.

+ +
+
Avoid welding at sort/map/grep paren calls
+
+ +

Random testing produced several cases of unstable welds in which the inner container something like 'sort ('. The problem was that there are special rules which prevent a break following such a paren. The problem was fixed by preventing welds at these locations.

+ +

This update fixes cases b1077 b1092 b1093 b1094 b1104 b1105 b1108.

+ +

17 Apr 2021, d679b48.

+ +
+
Fix issue git#62
+
+ +

This fixes issue git #62. A similar issue for the % operator was fixed. 17 Apr 2021, f80d677.

+ +
+
Fix problem involving -bbx=2 -xci -osbr and similar -otr flags
+
+ +

Random testing produced case b1100 in which the output style produced by the --opening-token-right flags interfered with counting line-ending commas, and this in turn caused the -bbx flag to turn off the -xci flag. This problem was fixed.

+ +

15 Apr 2021, 21ef53b.

+ +
+
Fix rare line break problem
+
+ +

Random testing produced case b1097 with this parameter set

+ +
    --brace-vertical-tightness-closing=1
+    --continuation-indentation=8
+    --indent-columns=10
+    --maximum-line-length=36
+ +

and either this output

+ +
          my (@files) = @{
+                    $args{-files} };
+ +

or this output

+ +
          my (@files) =
+                  @{ $args{-files}
+                  };
+ +

The different results were caused by the unusual combination of parameters. The problem was fixed by not allowing the formatter to consider existing breaks at highly stressed locations such as these.

+ +

15 Apr 2021, 9f15b9d.

+ +
+
Fix problem parsing anonymous subs with attribute lists
+
+ +

Random testing produced case b994 with unstable formatting:

+ +
    do
+    sub :
+    lvalue
+    {
+    return;
+    }
+ +

when run with parameters:

+ +
    --continuation-indentation=0
+    --ignore-old-breakpoints
+    --maximum-line-length=7
+    --opening-anonymous-sub-brace-on-new-line
+ +

The line 'sub :' was being correctly parsed but the following opening block brace was not correctly marked as an anonymous sub brace. This fixes cases b994 and b1053.

+ +

15 Apr 2021, 84c1123.

+ +
+
Correct brace types mismarked by tokenizer
+
+ +

Testing with random parameters produced a case in which a brace following an unknown bareword was marked by the tokenizer as a code block brace rather than a hash brace. This can cause poor formatting. The problem was solved by having the tokenizer send a signal to the formatter if a block type was guessed. The formatter has more information and can fix the problem. This fixes case b1085.

+ +

11 Apr 2021, 7d23bf4.

+ +
+
Unify coding for welded quotes and other welded containers
+
+ +

Random testing produced some cases where welded quotes were not converging. These were found to be due to the same problem previouly encountered and fixed for normal containers. The problem was fixed by moving the corrected coding to a new common sub.

+ +

This update fixes cases b1066 b1067 b1071 b1079 b1080.

+ +

10 Apr 2021, 5d73dd5.

+ +
+
Slight change in weld length calculation
+
+ +

Random testing produced some cases of instability with some unusual input parameter combinations involving the -wn parameter. This was fixed by revising a line length calculation. This fixes cases b604 and b605.

+ +

9 Apr 2021, a25cfaa.

+ +
+
Improve treatment of -vmll with -wn
+
+ +

Random testing showed a weakness in the treatment of the -vmll flag in combination with the -wn flag. This has been fixed.

+ +

This fixes cases b866 b1074 b1075 b1084 b1086 b1087 b1088

+ +

8 Apr 2021, a6effa3.

+ +
+
Merge weld rule 6 into rule 3
+
+ +

One of the welding rules, RULE 6, has been merged into RULE 3 for generality. This rule restricts welding to an opening container followed by a bare word, which can cause instability in some cases. The updated code is less restrictive and fixes some cases recently found with random testing, b1078 b1091.

+ +

8 Apr 2021, f28ab55.

+ +
+
Moved logic of previous update to the FileWriter module
+
+ +

The previous update regarding blank line generation was not sufficiently general to handle all possible parameter combinations. The problem was solved and simplified by moving the logic to a lower level, in the FileWriter module.

+ +

6 Apr 2021, 756e930.

+ +
+
Fix problem with excess blank line generation with -blao
+
+ +

Random testing produced some cases where excess blank lines could be generated with the parameter -blank-lines-after-opening-block. Case b1073 has the following script

+ +
    sub stop {
+
+        1;
+    }
+ +

and the following parameters

+ +
    --blank-lines-after-opening-block=2
+    --maximum-consecutive-blank-lines=10
+    --maximum-line-length=15
+ +

When run, blank lines keep getting generated until the maximum is reached. This has been fixed.

+ +

6 Apr 2021, 9216298.

+ +
+
Fix edge case involving -wn and -lp or -bbao
+
+ +

A change was made to a welding rule involving the -lp option or -wbb='=', and very short maximum line lengths. This correctly fixes case b1041. It replaces a fix for this case reported on 2 Apr 2021.

+ +

5 Apr 2021.

+ +
+
Modify a condition for applying -bbx=2
+
+ +

Random testing produced some edge cases in which formatting with the -bbx=2 flags, in combination with certain other parameters, was not converging. An existing criterion for the -bbx=2 flag to apply is that there be a broken sub-list with at least one line-ending comma. This was updated to also require either a fat comma or one additional line-ending comma. This filters out some problem cases without changing much existing formatting.

+ +

This update fixes cases b1068 b1069 b1070 b1072 b1073 b1076.

+ +

5 Apr 2021, 16c4591.

+ +
+
Improve previous -wn update
+
+ +

The previous update produced some problems in testing which are corrected with this update.

+ +

5 Apr 2021, ffef089.

+ +
+
Fix rare convergence problem with -wn
+
+ +

Random testing produced some cases in which unusual parameter combinations caused lack of convergence for the -wn flag. The problem was fixed by adjusting a tolerance in the line length calculation.

+ +

This fixes cases b1041 b1055.

+ +

2 Apr 2021, a8b6259.

+ +
+
Avoid conflict of -bli and -xci
+
+ +

Random testing produced a case with the combination -bli and -xci which did not converge. This was fixed by turning off -xci for braces under -bli control.

+ +

This fixes case b1065.

+ +

2 Apr 2021, d20ea80.

+ +
+
+

Issues fixed after release 20210111

@@ -31,7 +1111,7 @@

This fixes cases b1033 b1036 b1037 b1038 b1042 b1043 b1044 b1045 b1046 b1047 b1051 b1052 b1061.

-

30 Mar 2021.

+

30 Mar 2021, 2b05051.

Fix rule for welding with barewords
diff --git a/docs/ChangeLog.html b/docs/ChangeLog.html index a90acbb7..9e27ae07 100644 --- a/docs/ChangeLog.html +++ b/docs/ChangeLog.html @@ -1,5 +1,38 @@

Perltidy Change Log

+

2021 06 25

+ +
- This release adds several new requested parameters.  No significant bugs have 
+  been found since the last release, but a number of minor problems have been 
+  corrected.
+
+- Added a new option '--code-skipping', requested in git #65, in which code
+  between comment lines '#<<V' and '#>>V' is passed verbatim to the output
+  stream without error checking.  It is simmilar to --format-skipping
+  but there is no error checking of the skipped code. This can be useful for 
+  skipping past code which employs an extended syntax.
+
+- Added a new option for closing paren placement, -vtc=3, requested in rt #136417.
+
+- Added flag -atnl, --add-terminal-newline, to help issue git #58.
+  This flag tells perltidy to terminate the last line of the output stream 
+  with a newline character, regardless of whether or not the input stream 
+  was terminated with a newline character.  This is the default.
+  If this flag is negated, with -natnl, then perltidy will add a terminal
+  newline character to the the output stream only if the input
+  stream is terminated with a newline.
+
+- Some nested structures formatted with the -lp indentation option may have
+  some changes in indentation.  This is due to updates which were made to
+  prevent formatting instability when line lengths are limited by the maximum line
+  length. Most scripts will not be affected. If this causes unwanted formatting
+  changes, try increasing the --maximum-line-length by a few characters.
+
+- Numerous minor fixes have been made. A complete list is at:
+
+       https://github.com/perltidy/perltidy/blob/master/local-docs/BugLog.pod
+
+

2021 04 02

- This release fixes several non-critical bugs which have been found since the last
diff --git a/docs/Tidy.html b/docs/Tidy.html
index 3f13488d..50966cfe 100644
--- a/docs/Tidy.html
+++ b/docs/Tidy.html
@@ -372,7 +372,7 @@
 
 
VERSION

 
-
This man page documents Perl::Tidy version 20210402

+
This man page documents Perl::Tidy version 20210625

 
 
LICENSE

 
diff --git a/docs/index.html b/docs/index.html
index fb382596..4e671a1d 100644
--- a/docs/index.html
+++ b/docs/index.html
@@ -67,6 +67,6 @@ are mainly for older sytems but also tell how to use perltidy without doing an i
 
 
FEEDBACK / BUG REPORTS

 
-
A list of current bugs and issues can be found at the CPAN site https://rt.cpan.org/Public/Dist/Display.html?Name=Perl-Tidy

+
The best place to report bugs and issues is GitHub

 
-
To report a new bug or problem, use the link on this page .

+
Bugs and issues can also be reported at the CPAN site https://rt.cpan.org/Public/Dist/Display.html?Name=Perl-Tidy

diff --git a/docs/index.md b/docs/index.md
index 573f4d3c..1a73ea8f 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -70,6 +70,6 @@ are mainly for older sytems but also tell how to use perltidy without doing an i
 
 ## FEEDBACK / BUG REPORTS
 
-A list of current bugs and issues can be found at the CPAN site [https://rt.cpan.org/Public/Dist/Display.html?Name=Perl-Tidy](https://rt.cpan.org/Public/Dist/Display.html?Name=Perl-Tidy)
+The best place to report bugs and issues is [GitHub](https://github.com/perltidy/perltidy/issues)
 
-To report a new bug or problem, use the link on this page .
+Bugs and issues can also be reported at the CPAN site [https://rt.cpan.org/Public/Dist/Display.html?Name=Perl-Tidy](https://rt.cpan.org/Public/Dist/Display.html?Name=Perl-Tidy)
diff --git a/docs/perltidy.html b/docs/perltidy.html
index d6f0f51f..107db3f2 100644
--- a/docs/perltidy.html
+++ b/docs/perltidy.html
@@ -424,26 +424,6 @@
- -
-syn, --check-syntax
-
- -

This flag is now ignored for safety, but the following documentation has been retained for reference.

- -

This flag causes perltidy to run perl -c -T to check syntax of input and output. (To change the flags passed to perl, see the next item, -pscf). The results are written to the .LOG file, which will be saved if an error is detected in the output script. The output script is not checked if the input script has a syntax error. Perltidy does its own checking, but this option employs perl to get a "second opinion".

- -

If perl reports errors in the input file, they will not be reported in the error output unless the --warning-output flag is given.

- -

The default is NOT to do this type of syntax checking (although perltidy will still do as much self-checking as possible). The reason is that it causes all code in BEGIN blocks to be executed, for all modules being used, and this opens the door to security issues and infinite loops when running perltidy.

- -
-
-pscf=s, -perl-syntax-check-flags=s
-
- -

When perl is invoked to check syntax, the normal flags are -c -T. In addition, if the -x flag is given to perltidy, then perl will also be passed a -x flag. It should not normally be necessary to change these flags, but it can be done with the -pscf=s flag. For example, if the taint flag, -T, is not wanted, the flag could be set to be just -pscf=-c.

- -

Perltidy will pass your string to perl with the exception that it will add a -c and -x if appropriate. The .LOG file will show exactly what flags were passed to perl.

-
-xs, --extended-syntax
@@ -460,6 +440,8 @@

This flag is enabled by default but it can be deactivated with -nxs. Probably the only reason to deactivate this flag is to generate more diagnostic messages when debugging a script.

+

For another method of handling extended syntax see the section "Skipping Selected Sections of Code".

+
-io, --indent-only
@@ -526,6 +508,14 @@

This flag tells perltidy to write its output files with the same line endings as the input file, if possible. It should work for dos, unix, and mac line endings. It will only work if perltidy input comes from a filename (rather than stdin, for example). If perltidy has trouble determining the input file line ending, it will revert to the default behavior of using the line ending of the host system.

+
+
-atnl, --add-terminal-newline
+
+ +

This flag, which is enabled by default, allows perltidy to terminate the last line of the output stream with a newline character, regardless of whether or not the input stream was terminated with a newline character. If this flag is negated, with -natnl, then perltidy will add a terminal newline to the the output stream only if the input stream is terminated with a newline.

+ +

Negating this flag may be useful for manipulating one-line scripts intended for use on a command line.

+
-it=n, --iterations=n
@@ -632,12 +622,14 @@

If the available line length (see -l=n ) does not permit this much space, perltidy will use less. For alternate placement of the closing paren, see the next section.

-

This option has no effect on code BLOCKS, such as if/then/else blocks, which always use whatever is specified with -i=n. Also, the existence of line breaks and/or block comments between the opening and closing parens may cause perltidy to temporarily revert to its default method.

+

This option has no effect on code BLOCKS, such as if/then/else blocks, which always use whatever is specified with -i=n.

-

Note: The -lp option may not be used together with the -t tabs option. It may, however, be used with the -et=n tab method.

+

In situations where perltidy does not have complete freedom to choose line breaks it may temporarily revert to its default indentation method. This can occur for example if there are blank lines, block comments, multi-line quotes, or side comments between the opening and closing parens, braces, or brackets.

In addition, any parameter which significantly restricts the ability of perltidy to choose newlines will conflict with -lp and will cause -lp to be deactivated. These include -io, -fnl, -nanl, and -ndnl. The reason is that the -lp indentation style can require the careful coordination of an arbitrary number of break points in hierarchical lists, and these flags may prevent that.

+

The -lp option may not be used together with the -t tabs option. It may, however, be used with the -et=n tab method.

+
-lpxl=s, --line-up-parentheses-exclusion-list
@@ -1552,16 +1544,13 @@

Skipping Selected Sections of Code

-

Selected lines of code may be passed verbatim to the output without any formatting. This feature is enabled by default but can be disabled with the --noformat-skipping or -nfs flag. It should be used sparingly to avoid littering code with markers, but it might be helpful for working around occasional problems. For example it might be useful for keeping the indentation of old commented code unchanged, keeping indentation of long blocks of aligned comments unchanged, keeping certain list formatting unchanged, or working around a glitch in perltidy.

+

Selected lines of code may be passed verbatim to the output without any formatting by marking the starting and ending lines with special comments. There are two options for doing this. The first option is called --format-skipping or -fs, and the second option is called --code-skipping or -cs.

-
+

In both cases the lines of code will be output without any changes. The difference is that in --format-skipping perltidy will still parse the marked lines of code and check for errors, whereas in --code-skipping perltidy will simply pass the lines to the output without any checking.

-
-fs, --format-skipping
-
+

Both of these features are enabled by default and are invoked with special comment markers. --format-skipping uses starting and ending markers '#<<<' and '#>>>', like this:

-

This flag, which is enabled by default, causes any code between special beginning and ending comment markers to be passed to the output without formatting. The default beginning marker is #<<< and the default ending marker is #>>> but they may be changed (see next items below). Additional text may appear on these special comment lines provided that it is separated from the marker by at least one space. For example

- -
 #<<<  do not let perltidy touch this
+
 #<<<  format skipping: do not let perltidy change my nice formatting
     my @list = (1,
                 1, 1,
                 1, 2, 1,
@@ -1569,16 +1558,47 @@
                 1, 4, 6, 4, 1,);
  #>>>

 
-
Format skipping begins when a format skipping comment is seen and continues until either a format-skipping end pattern is found or until the end of file.

+
--code-skipping uses starting and ending markers '#<<V' and '#>>V', like this:

+
+
 #<<V  code skipping: perltidy will pass this verbatim without error checking
+
+    token ident_digit {
+        [ [ <?word> | _ | <?digit> ] <?ident_digit>
+        |   <''>
+        ]
+    };
+
+ #>>V

+
+
Additional text may appear on the special comment lines provided that it is separated from the marker by at least one space, as in the above examples.

+
+
It is recommended to use --code-skipping only if you need to hide a block of an extended syntax which would produce errors if parsed by perltidy, and use --format-skipping otherwise. This is because the --format-skipping option provides the benefits of error checking, and there are essentially no limitations on which lines to which it can be applied. The --code-skipping option, on the other hand, does not do error checking and its use is more restrictive because the code which remains, after skipping the marked lines, must be syntactically correct code with balanced containers.

+
+
These features should be used sparingly to avoid littering code with markers, but they can be helpful for working around occasional problems.

+
+
Note that it may be possible to avoid the use of --format-skipping for the specific case of a comma-separated list of values, as in the above example, by simply inserting a blank or comment somewhere between the opening and closing parens. See the section "Controlling List Formatting".

+
+
The following sections describe the available controls for these options. They should not normally be needed.

+
+

+
+
-fs, --format-skipping

+

 
-
The comment markers may be placed at any location that a block comment may appear. If they do not appear to be working, use the -log flag and examine the .LOG file. Use -nfs to disable this feature.

+
As explained above, this flag, which is enabled by default, causes any code between special beginning and ending comment markers to be passed to the output without formatting. The code between the comments is still checked for errors however. The default beginning marker is #<<< and the default ending marker is #>>>.

 
-
This method works for any code. For the specific case of a comma-separated list of values, as in this example, another possibility is to insert a blank or comment somewhere between the opening and closing parens. See the section "Controlling List Formatting".

+
Format skipping begins when a format skipping beginning comment is seen and continues until a format-skipping ending comment is found.

+
+
This feature can be disabled with -nfs. This should not normally be necessary.

 
 

 
-fsb=string, --format-skipping-begin=string

 

 
+
This and the next parameter allow the special beginning and ending comments to be changed. However, it is recommended that they only be changed if there is a conflict between the default values and some other use. If they are used, it is recommended that they only be entered in a .perltidyrc file, rather than on a command line. This is because properly escaping these parameters on a command line can be difficult.

+
+
If changed comment markers do not appear to be working, use the -log flag and examine the .LOG file to see if and where they are being detected.

+
 
The -fsb=string parameter may be used to change the beginning marker for format skipping. The default is equivalent to -fsb='#<<<'. The string that you enter must begin with a # and should be in quotes as necessary to get past the command shell of your system. It is actually the leading text of a pattern that is constructed by appending a '\s', so you must also include backslashes for characters to be taken literally rather than as patterns.

 
 
Some examples show how example strings become patterns:

@@ -1595,6 +1615,26 @@
 
 
The beginning and ending strings may be the same, but it is preferable to make them different for clarity.

 
+

+
-cs, --code-skipping

+

+
+
As explained above, this flag, which is enabled by default, causes any code between special beginning and ending comment markers to be directly passed to the output without any error checking or formatting. Essentially, perltidy treats it as if it were a block of arbitrary text. The default beginning marker is #<<V and the default ending marker is #>>V.

+
+
This feature can be disabled with -ncs. This should not normally be necessary.

+
+

+
-csb=string, --code-skipping-begin=string

+

+
+
This may be used to change the beginning comment for a --code-skipping section, and its use is similar to the -fsb=string. The default is equivalent to -csb='#<<V'.

+
+

+
-cse=string, --code-skipping-end=string

+

+
+
This may be used to change the ending comment for a --code-skipping section, and its use is similar to the -fse=string. The default is equivalent to -cse='#>>V'.

+
 

 

 
@@ -2105,10 +2145,12 @@
 
 
    '^('   - the weld must not start with a paren
     '.('   - the second and later tokens may not be parens
+    '.w('  - the second and later tokens may not keyword or function call parens
     '('    - no parens in a weld
     '^K('  - exclude a leading paren preceded by a non-keyword
     '.k('  - exclude a secondary paren preceded by a keyword
-    '[ {'  - exclude all brackets and braces

+    '[ {'  - exclude all brackets and braces
+    '[ ( ^K{' - exclude everything except nested structures like do {{  ... }}
Vertical tightness of non-block curly braces, parentheses, and square brackets.
@@ -2135,9 +2177,11 @@ -vtc=1 do not break before a closing token which is followed by a semicolon or another closing token, and is not in a list environment. - -vtc=2 never break before a closing token. + -vtc=2 never break before a closing token. + -vtc=3 Like -vtc=1 except always break before a closing token + if the corresponding opening token follows an = or =>. -

The rules for -vtc=1 are designed to maintain a reasonable balance between tightness and readability in complex lists.

+

The rules for -vtc=1 and -vtc=3 are designed to maintain a reasonable balance between tightness and readability in complex lists.

  • Different controls may be applied to different token types, and it is also possible to control block braces; see below.

    @@ -2169,7 +2213,24 @@ %romanNumerals = ( one => 'I', two => 'II', three => 'III', - four => 'IV', ); + four => 'IV', ); + + # perltidy -vtc=3 + my_function( + one => 'I', + two => 'II', + three => 'III', + four => 'IV', ); + + # perltidy -vtc=3 + %romanNumerals = ( + one => 'I', + two => 'II', + three => 'III', + four => 'IV', + ); + +

    In the last example for -vtc=3, the opening paren is preceded by an equals so the closing paren is placed on a new line.

    The difference between -vt=1 and -vt=2 is shown here:

    @@ -2198,13 +2259,13 @@

    The -vt=n and -vtc=n parameters apply to each type of container token. If desired, vertical tightness controls can be applied independently to each of the closing container token types.

    -

    The parameters for controlling parentheses are -pvt=n or --paren-vertical-tightness=n, and -pcvt=n or --paren-vertical-tightness-closing=n.

    +

    The parameters for controlling parentheses are -pvt=n or --paren-vertical-tightness=n, and -pvtc=n or --paren-vertical-tightness-closing=n.

    -

    Likewise, the parameters for square brackets are -sbvt=n or --square-bracket-vertical-tightness=n, and -sbcvt=n or --square-bracket-vertical-tightness-closing=n.

    +

    Likewise, the parameters for square brackets are -sbvt=n or --square-bracket-vertical-tightness=n, and -sbvtc=n or --square-bracket-vertical-tightness-closing=n.

    -

    Finally, the parameters for controlling non-code block braces are -bvt=n or --brace-vertical-tightness=n, and -bcvt=n or --brace-vertical-tightness-closing=n.

    +

    Finally, the parameters for controlling non-code block braces are -bvt=n or --brace-vertical-tightness=n, and -bvtc=n or --brace-vertical-tightness-closing=n.

    -

    In fact, the parameter -vt=n is actually just an abbreviation for -pvt=n -bvt=n sbvt=n, and likewise -vtc=n is an abbreviation for -pvtc=n -bvtc=n sbvtc=n.

    +

    In fact, the parameter -vt=n is actually just an abbreviation for -pvt=n -bvt=n sbvt=n, and likewise -vtc=n is an abbreviation for -pvtc=n -bvtc=n -sbvtc=n.

    • -bbvt=n or --block-brace-vertical-tightness=n
    @@ -2554,7 +2615,8 @@

    This flag will also look for and keep a 'cuddled' style of calls, in which lines begin with a closing paren followed by a call arrow, as in this example:

    -
      my $q = $rs->related_resultset(
+
      # perltidy -bom -wn
+  my $q = $rs->related_resultset(
       'CDs'
   )->related_resultset(
       'Tracks'
@@ -2792,7 +2854,7 @@
 
 
      perltidy -blao=2 -blbc=2 -blaol='*' -blbcl='*' filename
    
 
-
    Now suppose the script continues to be developed, but at some later date we decide we don't want these spaces after all. we might expect that running with the flags -blao=0 and -blbc=0 will undo them. However, by default perltidy retains single blank lines, so the blank lines remain.
    
+
    Now suppose the script continues to be developed, but at some later date we decide we don't want these spaces after all. We might expect that running with the flags -blao=0 and -blbc=0 will undo them. However, by default perltidy retains single blank lines, so the blank lines remain.
    
 
 
    We can easily fix this by telling perltidy to ignore old blank lines by including the added parameter -kbl=0 and rerunning. Then the unwanted blank lines will be gone. However, this will cause all old blank lines to be ignored, perhaps even some that were added by hand to improve formatting. So please be cautious when using these parameters.
    
 
@@ -3224,15 +3286,21 @@
         -opt2
         }
    
 
-
    where newword is the abbreviation, and opt1, etc, are existing parameters or other abbreviations. The main syntax requirement is that the new abbreviation along with its opening curly brace must begin on a new line. Space before and after the curly braces is optional. For a specific example, the following line
    
+
    where newword is the abbreviation, and opt1, etc, are existing parameters or other abbreviations. The main syntax requirement is that the new abbreviation along with its opening curly brace must begin on a new line. Space before and after the curly braces is optional.
    
+
+
    For a specific example, the following line
    
+
+
            oneliner { --maximum-line-length=0 --noadd-newlines --noadd-terminal-newline}
    
+
+
    or equivalently with abbreviations
    
 
-
            airy {-bl -pt=0 -bt=0 -sbt=0}
    
+
            oneliner { -l=0 -nanl -natnl }
    
 
-
    could be placed in a .perltidyrc file, and then invoked at will with
    
+
    could be placed in a .perltidyrc file to temporarily override the maximum line length with a large value, to temporarily prevent new line breaks from being added, and to prevent an extra newline character from being added the file. All other settings in the .perltidyrc file still apply. Thus it provides a way to format a long 'one liner' when perltidy is invoked with
    
 
-
            perltidy -airy somefile.pl
    
+
            perltidy --oneliner ...
    
 
-
    (Either -airy or --airy may be used).
    
+
    (Either -oneliner or --oneliner may be used).
    
 
 
 
    Skipping leading non-perl commands with -x or --look-for-hash-bang
    
@@ -3539,23 +3607,23 @@
 
 
    The following list shows all short parameter names which allow a prefix 'n' to produce the negated form:
    
 
-
     D      anl    asbl   asc    ast    asu    aws    b      baa    baao   
- bar    bbao   bbb    bbc    bbs    bl     bli    boa    boc    bok    
- bol    bom    bos    bot    cblx   ce     conv   csc    cscb   cscw   
- dac    dbc    dcbl   dcsc   ddf    dln    dnl    dop    dp     dpro   
- dsc    dsm    dsn    dtt    dwls   dwrs   dws    f      fll    frm    
- fs     fso    gcs    hbc    hbcm   hbco   hbh    hbhh   hbi    hbj    
- hbk    hbm    hbn    hbp    hbpd   hbpu   hbq    hbs    hbsc   hbv    
- hbw    hent   hic    hicm   hico   hih    hihh   hii    hij    hik    
- him    hin    hip    hipd   hipu   hiq    his    hisc   hiv    hiw    
- hsc    html   ibc    icb    icp    iob    isbc   iscl   kgb    kgbd   
- kgbi   kis    lal    log    lop    lp     lsl    mem    nib    ohbr   
- okw    ola    olc    oll    olq    opr    opt    osbc   osbr   otr    
- ple    pod    pvl    q      sac    sbc    sbl    scbb   schb   scp    
- scsb   sct    se     sfp    sfs    skp    sob    sobb   sohb   sop    
- sosb   sot    ssc    st     sts    t      tac    tbc    toc    tp     
- tqw    trp    ts     tsc    tso    vmll   w      wn     x      xci    
- xs     
    
+
     D      anl    asbl   asc    ast    asu    atnl   aws    b      baa
+ baao   bar    bbao   bbb    bbc    bbs    bl     bli    boa    boc
+ bok    bol    bom    bos    bot    cblx   ce     conv   cs     csc
+ cscb   cscw   dac    dbc    dcbl   dcsc   ddf    dln    dnl    dop
+ dp     dpro   dsc    dsm    dsn    dtt    dwls   dwrs   dws    f
+ fll    fpva   frm    fs     fso    gcs    hbc    hbcm   hbco   hbh
+ hbhh   hbi    hbj    hbk    hbm    hbn    hbp    hbpd   hbpu   hbq
+ hbs    hbsc   hbv    hbw    hent   hic    hicm   hico   hih    hihh
+ hii    hij    hik    him    hin    hip    hipd   hipu   hiq    his
+ hisc   hiv    hiw    hsc    html   ibc    icb    icp    iob    isbc
+ iscl   kgb    kgbd   kgbi   kis    lal    log    lop    lp     lsl
+ mem    nib    ohbr   okw    ola    olc    oll    olq    opr    opt
+ osbc   osbr   otr    ple    pod    pvl    q      sac    sbc    sbl
+ scbb   schb   scp    scsb   sct    se     sfp    sfs    skp    sob
+ sobb   sohb   sop    sosb   sot    ssc    st     sts    t      tac
+ tbc    toc    tp     tqw    trp    ts     tsc    tso    vmll   w
+ wn     x      xci    xs
    
 
 
    Equivalently, the prefix 'no' or 'no-' on the corresponding long names may be used.
    
 
@@ -3633,7 +3701,7 @@
 
 
    VERSION
    
 
-
    This man page documents perltidy version 20210402
    
+
    This man page documents perltidy version 20210625
    
 
 
    BUG REPORTS
    
 
diff --git a/lib/Perl/Tidy.pm b/lib/Perl/Tidy.pm
index c5330593..2fe7cd15 100644
--- a/lib/Perl/Tidy.pm
+++ b/lib/Perl/Tidy.pm
@@ -110,7 +110,7 @@ BEGIN {
     # Release version must be bumped, and it is probably past time for a
     # release anyway.
 
-    $VERSION = '20210402.01';
+    $VERSION = '20210625';
 }
 
 sub DESTROY {
diff --git a/lib/Perl/Tidy.pod b/lib/Perl/Tidy.pod
index 88810b0b..68c07d6d 100644
--- a/lib/Perl/Tidy.pod
+++ b/lib/Perl/Tidy.pod
@@ -432,7 +432,7 @@ The module 'Perl::Tidy' comes with a binary 'perltidy' which is installed when t
 
 =head1 VERSION
 
-This man page documents Perl::Tidy version 20210402.01
+This man page documents Perl::Tidy version 20210625
 
 =head1 LICENSE
 
diff --git a/lib/Perl/Tidy/Debugger.pm b/lib/Perl/Tidy/Debugger.pm
index bee1705b..f2a44d55 100644
--- a/lib/Perl/Tidy/Debugger.pm
+++ b/lib/Perl/Tidy/Debugger.pm
@@ -7,7 +7,7 @@
 package Perl::Tidy::Debugger;
 use strict;
 use warnings;
-our $VERSION = '20210402.01';
+our $VERSION = '20210625';
 
 sub new {
 
diff --git a/lib/Perl/Tidy/DevNull.pm b/lib/Perl/Tidy/DevNull.pm
index 6a69d8c5..4bbcf676 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 = '20210402.01';
+our $VERSION = '20210625';
 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 5201e6c9..416fbe56 100644
--- a/lib/Perl/Tidy/Diagnostics.pm
+++ b/lib/Perl/Tidy/Diagnostics.pm
@@ -20,7 +20,7 @@
 package Perl::Tidy::Diagnostics;
 use strict;
 use warnings;
-our $VERSION = '20210402.01';
+our $VERSION = '20210625';
 
 sub AUTOLOAD {
 
diff --git a/lib/Perl/Tidy/FileWriter.pm b/lib/Perl/Tidy/FileWriter.pm
index 7ef2bdba..94bdac1b 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 = '20210402.01';
+our $VERSION = '20210625';
 
 use constant DEVEL_MODE => 0;
 
diff --git a/lib/Perl/Tidy/Formatter.pm b/lib/Perl/Tidy/Formatter.pm
index f0762949..93eeaf0d 100644
--- a/lib/Perl/Tidy/Formatter.pm
+++ b/lib/Perl/Tidy/Formatter.pm
@@ -49,7 +49,7 @@ use constant DEVEL_MODE => 0;
 { #<<< A non-indenting brace to contain all lexical variables
 
 use Carp;
-our $VERSION = '20210402.01';
+our $VERSION = '20210625';
 
 # The Tokenizer will be loaded with the Formatter
 ##use Perl::Tidy::Tokenizer;    # for is_keyword()
@@ -15489,7 +15489,7 @@ sub set_continuation_breaks {
 
         # The -xci option alone also needs a slightly larger tol for non-lists
         elsif ( $rOpts->{'extended-continuation-indentation'} ) {
-               $length_tol_boost = 1;
+            $length_tol_boost = 1;
         }
         return;
     }
diff --git a/lib/Perl/Tidy/HtmlWriter.pm b/lib/Perl/Tidy/HtmlWriter.pm
index 87787c74..fc89c922 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 = '20210402.01';
+our $VERSION = '20210625';
 
 use File::Basename;
 
diff --git a/lib/Perl/Tidy/IOScalar.pm b/lib/Perl/Tidy/IOScalar.pm
index a829f89e..06b8e5a9 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 = '20210402.01';
+our $VERSION = '20210625';
 
 sub AUTOLOAD {
 
diff --git a/lib/Perl/Tidy/IOScalarArray.pm b/lib/Perl/Tidy/IOScalarArray.pm
index 0225d06e..66091600 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 = '20210402.01';
+our $VERSION = '20210625';
 
 sub AUTOLOAD {
 
diff --git a/lib/Perl/Tidy/IndentationItem.pm b/lib/Perl/Tidy/IndentationItem.pm
index d87dc6d5..0c0c47fe 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 = '20210402.01';
+our $VERSION = '20210625';
 
 BEGIN {
 
diff --git a/lib/Perl/Tidy/LineBuffer.pm b/lib/Perl/Tidy/LineBuffer.pm
index fb938873..83a58ee5 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 = '20210402.01';
+our $VERSION = '20210625';
 
 sub AUTOLOAD {
 
diff --git a/lib/Perl/Tidy/LineSink.pm b/lib/Perl/Tidy/LineSink.pm
index dcee5caa..1f070451 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 = '20210402.01';
+our $VERSION = '20210625';
 
 sub AUTOLOAD {
 
diff --git a/lib/Perl/Tidy/LineSource.pm b/lib/Perl/Tidy/LineSource.pm
index 5bacab23..0f5ace0b 100644
--- a/lib/Perl/Tidy/LineSource.pm
+++ b/lib/Perl/Tidy/LineSource.pm
@@ -8,7 +8,7 @@
 package Perl::Tidy::LineSource;
 use strict;
 use warnings;
-our $VERSION = '20210402.01';
+our $VERSION = '20210625';
 
 sub AUTOLOAD {
 
diff --git a/lib/Perl/Tidy/Logger.pm b/lib/Perl/Tidy/Logger.pm
index 93c5c19e..0c06a8c6 100644
--- a/lib/Perl/Tidy/Logger.pm
+++ b/lib/Perl/Tidy/Logger.pm
@@ -7,7 +7,7 @@
 package Perl::Tidy::Logger;
 use strict;
 use warnings;
-our $VERSION = '20210402.01';
+our $VERSION = '20210625';
 
 sub AUTOLOAD {
 
diff --git a/lib/Perl/Tidy/Tokenizer.pm b/lib/Perl/Tidy/Tokenizer.pm
index dcbd47b7..69a578d2 100644
--- a/lib/Perl/Tidy/Tokenizer.pm
+++ b/lib/Perl/Tidy/Tokenizer.pm
@@ -21,7 +21,7 @@
 package Perl::Tidy::Tokenizer;
 use strict;
 use warnings;
-our $VERSION = '20210402.01';
+our $VERSION = '20210625';
 
 use Perl::Tidy::LineBuffer;
 use Carp;
diff --git a/lib/Perl/Tidy/VerticalAligner.pm b/lib/Perl/Tidy/VerticalAligner.pm
index e45d3e55..f8a476fa 100644
--- a/lib/Perl/Tidy/VerticalAligner.pm
+++ b/lib/Perl/Tidy/VerticalAligner.pm
@@ -1,7 +1,7 @@
 package Perl::Tidy::VerticalAligner;
 use strict;
 use warnings;
-our $VERSION = '20210402.01';
+our $VERSION = '20210625';
 
 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 5ad921e9..d8b06b00 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 = '20210402.01';
+our $VERSION = '20210625';
 
 #    _column_          # the current column number
 #    _saved_column_    # a place for temporary storage
diff --git a/lib/Perl/Tidy/VerticalAligner/Line.pm b/lib/Perl/Tidy/VerticalAligner/Line.pm
index 2acb263f..f1ee84b9 100644
--- a/lib/Perl/Tidy/VerticalAligner/Line.pm
+++ b/lib/Perl/Tidy/VerticalAligner/Line.pm
@@ -8,7 +8,7 @@
 package Perl::Tidy::VerticalAligner::Line;
 use strict;
 use warnings;
-our $VERSION = '20210402.01';
+our $VERSION = '20210625';
 
 BEGIN {
     my $i = 0;
diff --git a/local-docs/BugLog.pod b/local-docs/BugLog.pod
index 198fef78..a9b883bd 100644
--- a/local-docs/BugLog.pod
+++ b/local-docs/BugLog.pod
@@ -762,7 +762,7 @@ determined in the tokenizer and was not being corrected by the formatter.
 
 This fixes cases b1125 b1126 b1127.
 
-2 May 2021i, dac97cb.
+2 May 2021, dac97cb.
 
 =item B