fix to prevent block comments from becoming hanging side comments

diff --git a/lib/Perl/Tidy/Formatter.pm b/lib/Perl/Tidy/Formatter.pm
index 5364ae168b44022a25deb01a1635b11794ce706d..afa2b0f9c699987e4a19703096ebb1668ae1f57f 100644 (file)
--- a/lib/Perl/Tidy/Formatter.pm
+++ b/lib/Perl/Tidy/Formatter.pm
@@ -148,6 +148,7 @@ my (
     $rOpts_block_brace_tightness,
     $rOpts_block_brace_vertical_tightness,
     $rOpts_stack_closing_block_brace,
+    $rOpts_maximum_consecutive_blank_lines,
 
     $rOpts_recombine,
     $rOpts_add_newlines,
@@ -1434,8 +1435,10 @@ EOM
     $rOpts_block_brace_vertical_tightness =
       $rOpts->{'block-brace-vertical-tightness'};
     $rOpts_stack_closing_block_brace = $rOpts->{'stack-closing-block-brace'};
-    $rOpts_recombine                 = $rOpts->{'recombine'};
-    $rOpts_add_newlines              = $rOpts->{'add-newlines'};
+    $rOpts_maximum_consecutive_blank_lines =
+      $rOpts->{'maximum-consecutive-blank-lines'};
+    $rOpts_recombine    = $rOpts->{'recombine'};
+    $rOpts_add_newlines = $rOpts->{'add-newlines'};
     $rOpts_break_at_old_comma_breakpoints =
       $rOpts->{'break-at-old-comma-breakpoints'};
     $rOpts_ignore_old_breakpoints    = $rOpts->{'ignore-old-breakpoints'};
@@ -4426,15 +4429,20 @@ sub dump_verbatim {
         # extract what we need for this line..
 
         my $input_line_number = $line_of_tokens->{_line_number};
-
-        my $rK_range = $line_of_tokens->{_rK_range};
+        my $input_line        = $line_of_tokens->{_line_text};
+        my $rK_range          = $line_of_tokens->{_rK_range};
         my ( $Kfirst, $Klast ) = @{$rK_range};
-        my $jmax = -1;
-        if ( defined($Kfirst) ) { $jmax = $Klast - $Kfirst }
-        my $input_line = $line_of_tokens->{_line_text};
+        my $jmax = defined($Kfirst) ? $Klast - $Kfirst : -1;
 
+        my $is_block_comment        = 0;
+        my $has_side_comment        = 0;
         my $is_static_block_comment = 0;
 
+        if ( $jmax >= 0 && $rLL->[$Klast]->[_TYPE_] eq '#' ) {
+            if   ( $jmax == 0 ) { $is_block_comment = 1; }
+            else                { $has_side_comment = 1 }
+        }
+
         # Handle a continued quote..
         if ( $line_of_tokens->{_starting_in_quote} ) {
 
@@ -4444,17 +4452,13 @@ sub dump_verbatim {
                 if ( ( $input_line =~ "\t" ) ) {
                     $self->note_embedded_tab($input_line_number);
                 }
-                $Last_line_had_side_comment = 0;
-                return 'VB';
+                $CODE_type = 'VB';
+                goto RETURN;
             }
         }
 
-        my $is_block_comment =
-          ( $jmax == 0 && $rLL->[$Kfirst]->[_TYPE_] eq '#' );
-
         # Write line verbatim if we are in a formatting skip section
         if ($In_format_skipping_section) {
-            $Last_line_had_side_comment = 0;
 
             # Note: extra space appended to comment simplifies pattern matching
             if ( $is_block_comment
@@ -4464,7 +4468,8 @@ sub dump_verbatim {
                 $In_format_skipping_section = 0;
                 write_logfile_entry("Exiting formatting skip section\n");
             }
-            return 'FS';
+            $CODE_type = 'FS';
+            goto RETURN;
         }
 
         # See if we are entering a formatting skip section
@@ -4475,8 +4480,8 @@ sub dump_verbatim {
         {
             $In_format_skipping_section = 1;
             write_logfile_entry("Entering formatting skip section\n");
-            $Last_line_had_side_comment = 0;
-            return 'FS';
+            $CODE_type = 'FS';
+            goto RETURN;
         }
 
         # ignore trailing blank tokens (they will get deleted later)
@@ -4486,8 +4491,8 @@ sub dump_verbatim {
 
         # Handle a blank line..
         if ( $jmax < 0 ) {
-            $Last_line_had_side_comment = 0;
-            return 'BL';
+            $CODE_type = 'BL';
+            goto RETURN;
         }
 
         # see if this is a static block comment (starts with ## by default)
@@ -4528,25 +4533,36 @@ sub dump_verbatim {
                                                     # like this
           )
         {
-            $Last_line_had_side_comment = 1;
-            return 'HSC';
+            $has_side_comment = 1;
+            $CODE_type        = 'HSC';
+            goto RETURN;
         }
 
-        # remember if this line has a side comment
-        $Last_line_had_side_comment =
-          ( $jmax > 0 && $rLL->[$Klast]->[_TYPE_] eq '#' );
-
         # Handle a block (full-line) comment..
         if ($is_block_comment) {
 
             if ($is_static_block_comment_without_leading_space) {
-                return 'SBCX';
+                $CODE_type = 'SBCX';
+                goto RETURN;
             }
             elsif ($is_static_block_comment) {
-                return 'SBC';
+                $CODE_type = 'SBC';
+                goto RETURN;
+            }
+            elsif ($Last_line_had_side_comment
+                && !$rOpts_maximum_consecutive_blank_lines
+                && $rLL->[$Kfirst]->[_LEVEL_] > 0 )
+            {
+                # Emergency fix to keep a block comment from becoming a hanging
+                # side comment.  This fix is for the case that blank lines
+                # cannot be inserted.  There is related code in sub
+                # 'process_line_of_CODE'
+                $CODE_type = 'SBCX';
+                goto RETURN;
             }
             else {
-                return 'BC';
+                $CODE_type = 'BC';
+                goto RETURN;
             }
         }
 
@@ -4582,7 +4598,11 @@ sub dump_verbatim {
 
             # This code type has lower priority than others
             $CODE_type = 'VER' unless ($CODE_type);
+            goto RETURN;
         }
+
+      RETURN:
+        $Last_line_had_side_comment = $has_side_comment;
         return $CODE_type;
     }
 } ## end closure scan_comments
@@ -8645,13 +8665,13 @@ EOM
                 # only if allowed
                 && $rOpts->{'blanks-before-comments'}
 
-                # if this is NOT an empty comment
-                && (   $rtok_first->[_TOKEN_] ne '#' 
-
-                # FIXME: FUTURE UPDATE; still needs to be coordinated with user parameters
-               # unless following a side comment (otherwise need to insert
-               # blank to prevent creating a hanging side comment)
-                    ) #|| $last_line_had_side_comment )
+                # if this is NOT an empty comment, unless it follows a side
+                # comment and could become a hanging side comment.
+                && (
+                    $rtok_first->[_TOKEN_] ne '#'
+                    || (   $last_line_had_side_comment
+                        && $rLL->[$K_first]->[_LEVEL_] > 0 )
+                )
 
                 # not after a short line ending in an opening token
                 # because we already have space above this comment.
@@ -8683,11 +8703,11 @@ EOM
             else {
 
                 # switching to new output stream
-                $self->flush();    
-                
+                $self->flush();
+
                 # Note that last arg in call here is 'undef' for comments
                 $file_writer_object->write_code_line(
-                    $rtok_first->[_TOKEN_] . "\n", undef ); 
+                    $rtok_first->[_TOKEN_] . "\n", undef );
                 $self->[_last_line_leading_type_] = '#';
             }
             return;

diff --git a/local-docs/BugLog.pod b/local-docs/BugLog.pod
index 17eb906dad40d8051686dac8b5c785d95dd1e9d5..0cd7d207b2adc3c6f1234376a3d7c436a1b3d765 100644 (file)
--- a/local-docs/BugLog.pod
+++ b/local-docs/BugLog.pod
@@ -2,6 +2,34 @@
 
 =over 4
 
+=item B<fix to prevent conversion of a block comment to hanging side comment>
+
+A rare situation was identified during testing in which a block comment could
+be converted to be a hanging side comment.  For example:
+
+    sub macro_get_names {    #
+    #
+    # %name = macro_get_names();  (key=macrohandle, value=macroname)
+    #
+        local (%name) = ();
+        ...
+    }
+
+For the following specific contitions the block comment in line 2 could be
+converted into a hanging side comment, which is undesirable:
+
+   1. It contains nothing except for a '#'
+   2. It follows a line with side comment
+   3. It has indentation level > 0
+
+An update was made to prevent this from happening.  There are two cases,
+depending on the value of --maximum-consecutive-blank-lines, or -mbl.  If this
+value is positive (the default) then a blank line is inserted above the block
+comment to prevent it from becoming a hanging side comment.  If this -mbl is
+zero, then the comment is converted to be a static block comment which again
+prevents it from becoming a hanging side comment. This fix was made 23 Nov
+2020.
+
 =item B<improved convergence test>
 
 A better test for convergence has been added. When iterations are requested,
@@ -9,7 +37,7 @@ the new test will stop after the first pass if no changes in line break
 locations are made.  Previously, at least two passes were required to verify
 convergnece unless the output stream had the same checksum as the input stream.
 Extensive testing has been made to verify the correctness of the new test.
-This update was made 23 Nov 2020.
+This update was made 23 Nov 2020, 29efb63.
 
 =item B<fixed problem with vertical alignments involving 'if' statements>
 

diff --git a/t/snippets/comments.in b/t/snippets/comments.in
index 7c0deb71a825100c5958e04fad6d57ecf167a064..a8e39452b7729ab5ad860ad0103e4aa2c60f0f62 100644 (file)
--- a/t/snippets/comments.in
+++ b/t/snippets/comments.in
@@ -4,7 +4,7 @@ sub length { return length($_[0]) }    # side comment
                              # hanging side comment
                              # very longgggggggggggggggggggggggggggggggggggggggggggggggggggg hanging side comment
 
-# side comments following open brace are not currently treated as hanging side comments
+# a blank will be inserted to prevent forming a hanging side comment
 sub macro_get_names { #
 # 
 # %name = macro_get_names();  (key=macrohandle, value=macroname)

diff --git a/t/snippets/expect/comments.comments1 b/t/snippets/expect/comments.comments1
index a53e5e627814d08588b6ffdec3b6980fc275c6fe..fbe3ff025d0120107763b5c5fdbca7d7435b1350 100644 (file)
--- a/t/snippets/expect/comments.comments1
+++ b/t/snippets/expect/comments.comments1
@@ -5,8 +5,9 @@ sub length { return length( $_[0] ) }  # side comment
 # hanging side comment
 # very longgggggggggggggggggggggggggggggggggggggggggggggggggggg hanging side comment
 
-# side comments following open brace are not currently treated as hanging side comments
+# a blank will be inserted to prevent forming a hanging side comment
 sub macro_get_names {                  #
+
 #
 # %name = macro_get_names();  (key=macrohandle, value=macroname)
 #

diff --git a/t/snippets/expect/comments.comments3 b/t/snippets/expect/comments.comments3
index ec1cc230208c877101894898ce8ab6f2f83affb1..077d0818adb89b37f76deee40bf4598a83021d87 100644 (file)
--- a/t/snippets/expect/comments.comments3
+++ b/t/snippets/expect/comments.comments3
@@ -4,8 +4,9 @@ sub length { return length( $_[0] ) }    # side comment
                                          # hanging side comment
  # very longgggggggggggggggggggggggggggggggggggggggggggggggggggg hanging side comment
 
-# side comments following open brace are not currently treated as hanging side comments
+# a blank will be inserted to prevent forming a hanging side comment
 sub macro_get_names {    #
+
 #
 # %name = macro_get_names();  (key=macrohandle, value=macroname)
 #

diff --git a/t/snippets/expect/comments.comments4 b/t/snippets/expect/comments.comments4
index e862a51fbb6877a1988c24d105e8b18d9cfe8ac3..58638d2b9171ee4126a8fde80638c4a565ed0389 100644 (file)
--- a/t/snippets/expect/comments.comments4
+++ b/t/snippets/expect/comments.comments4
@@ -4,8 +4,9 @@ sub length { return length( $_[0] ) }    # side comment
                                          # hanging side comment
  # very longgggggggggggggggggggggggggggggggggggggggggggggggggggg hanging side comment
 
-# side comments following open brace are not currently treated as hanging side comments
+# a blank will be inserted to prevent forming a hanging side comment
 sub macro_get_names {    #
+
     #
     # %name = macro_get_names();  (key=macrohandle, value=macroname)
     #

diff --git a/t/snippets/expect/comments.comments5 b/t/snippets/expect/comments.comments5
index 158df431f17d7d4438bc3577388e9cee05cc60ce..9d6a92efb55cfa23e7a0c9f5330ede9285279371 100644 (file)
--- a/t/snippets/expect/comments.comments5
+++ b/t/snippets/expect/comments.comments5
@@ -2,7 +2,7 @@
 # an initial hash bang line cannot be deleted with -dp
 sub length { return length( $_[0] ) }
 
-# side comments following open brace are not currently treated as hanging side comments
+# a blank will be inserted to prevent forming a hanging side comment
 sub macro_get_names {
     #
     # %name = macro_get_names();  (key=macrohandle, value=macroname)

diff --git a/t/snippets/expect/comments.def b/t/snippets/expect/comments.def
index 09d57974c66a53ceef6816a46e9e8646d185560c..58ffcdf78d4818a696238a4823535cbc20a194bc 100644 (file)
--- a/t/snippets/expect/comments.def
+++ b/t/snippets/expect/comments.def
@@ -4,8 +4,9 @@ sub length { return length( $_[0] ) }    # side comment
                                          # hanging side comment
  # very longgggggggggggggggggggggggggggggggggggggggggggggggggggg hanging side comment
 
-# side comments following open brace are not currently treated as hanging side comments
+# a blank will be inserted to prevent forming a hanging side comment
 sub macro_get_names {    #
+
     #
     # %name = macro_get_names();  (key=macrohandle, value=macroname)
     #

diff --git a/t/snippets/packing_list.txt b/t/snippets/packing_list.txt
index 12dc2604f5b624a58653a69a1eb39465cf28366c..385985a8bce29b612c74bf8c6525ff4750d638b5 100644 (file)
--- a/t/snippets/packing_list.txt
+++ b/t/snippets/packing_list.txt
@@ -304,6 +304,7 @@
 ../snippets23.t        wnxl.wnxl2
 ../snippets23.t        wnxl.wnxl3
 ../snippets23.t        wnxl.wnxl4
+../snippets23.t        align34.def
 ../snippets3.t ce_wn1.ce_wn
 ../snippets3.t ce_wn1.def
 ../snippets3.t colin.colin
@@ -444,4 +445,3 @@
 ../snippets9.t rt98902.def
 ../snippets9.t rt98902.rt98902
 ../snippets9.t rt99961.def
-../snippets23.t        align34.def

diff --git a/t/snippets17.t b/t/snippets17.t
index 49c0874bfab026661827b26be66f4323118d1c9e..318c19044af624dd3dffa269cebc14f6cdf0c950 100644 (file)
--- a/t/snippets17.t
+++ b/t/snippets17.t
@@ -94,7 +94,7 @@ sub length { return length($_[0]) }    # side comment
                              # hanging side comment
                              # very longgggggggggggggggggggggggggggggggggggggggggggggggggggg hanging side comment
 
-# side comments following open brace are not currently treated as hanging side comments
+# a blank will be inserted to prevent forming a hanging side comment
 sub macro_get_names { #
 # 
 # %name = macro_get_names();  (key=macrohandle, value=macroname)
@@ -346,8 +346,9 @@ sub length { return length( $_[0] ) }  # side comment
 # hanging side comment
 # very longgggggggggggggggggggggggggggggggggggggggggggggggggggg hanging side comment
 
-# side comments following open brace are not currently treated as hanging side comments
+# a blank will be inserted to prevent forming a hanging side comment
 sub macro_get_names {                  #
+
 #
 # %name = macro_get_names();  (key=macrohandle, value=macroname)
 #
@@ -500,8 +501,9 @@ sub length { return length( $_[0] ) }    # side comment
                                          # hanging side comment
  # very longgggggggggggggggggggggggggggggggggggggggggggggggggggg hanging side comment
 
-# side comments following open brace are not currently treated as hanging side comments
+# a blank will be inserted to prevent forming a hanging side comment
 sub macro_get_names {    #
+
 #
 # %name = macro_get_names();  (key=macrohandle, value=macroname)
 #
@@ -592,8 +594,9 @@ sub length { return length( $_[0] ) }    # side comment
                                          # hanging side comment
  # very longgggggggggggggggggggggggggggggggggggggggggggggggggggg hanging side comment
 
-# side comments following open brace are not currently treated as hanging side comments
+# a blank will be inserted to prevent forming a hanging side comment
 sub macro_get_names {    #
+
     #
     # %name = macro_get_names();  (key=macrohandle, value=macroname)
     #
@@ -693,8 +696,9 @@ sub length { return length( $_[0] ) }    # side comment
                                          # hanging side comment
  # very longgggggggggggggggggggggggggggggggggggggggggggggggggggg hanging side comment
 
-# side comments following open brace are not currently treated as hanging side comments
+# a blank will be inserted to prevent forming a hanging side comment
 sub macro_get_names {    #
+
     #
     # %name = macro_get_names();  (key=macrohandle, value=macroname)
     #

diff --git a/t/snippets18.t b/t/snippets18.t
index cd9863881f7d4412a45cb4b78d8395c5d9397784..0ff631114e141d04c14a7d141ccbc73e03773134 100644 (file)
--- a/t/snippets18.t
+++ b/t/snippets18.t
@@ -123,7 +123,7 @@ sub length { return length($_[0]) }    # side comment
                              # hanging side comment
                              # very longgggggggggggggggggggggggggggggggggggggggggggggggggggg hanging side comment
 
-# side comments following open brace are not currently treated as hanging side comments
+# a blank will be inserted to prevent forming a hanging side comment
 sub macro_get_names { #
 # 
 # %name = macro_get_names();  (key=macrohandle, value=macroname)
@@ -359,7 +359,7 @@ my ( $a, $b, $c ) = @_;    # test -nsak="my for"
 # an initial hash bang line cannot be deleted with -dp
 sub length { return length( $_[0] ) }
 
-# side comments following open brace are not currently treated as hanging side comments
+# a blank will be inserted to prevent forming a hanging side comment
 sub macro_get_names {
     #
     # %name = macro_get_names();  (key=macrohandle, value=macroname)