modified kgb input scheme

diff --git a/bin/perltidy b/bin/perltidy
index 94257ffbde0c46eab9e50cb5f72c4a58b3ede330..c7e3ea79b85ed744461028973d9a0783fd45c0c0 100755 (executable)
--- a/bin/perltidy
+++ b/bin/perltidy
@@ -2671,23 +2671,23 @@ called here B<keyword group blanks>, and all of the parameters begin with
 B<--keyword-group-blanks*>, or B<-kgb*> for short.  The default settings do not
 employ these controls but they can be enabled with the following parameters:
 
-B<--keyword-group-blanks-list=s>,   or B<-kgbl=s>; B<s> is a quoted string
+B<--keyword-group-blanks-list=s>,   or B<-kgbl=s>; B<s> is a quoted string of keywords
 
-B<--keyword-group-blanks-count=n>,  or B<-kgbc=n>; B<n> is an integer [def 5]
+B<--keyword-group-blanks-count=n>,  or B<-kgbc=n>; B<n> is a threshold group size
 
-B<--keyword-group-blanks-before=n>, or B<-kgbb=n>; B<n> is 0, 1, or 2
+B<--keyword-group-blanks-before=n>, or B<-kgbb=n>; B<n> = (0, 1, or 2) controls a leading blank
 
-B<--keyword-group-blanks-after=n>,  or B<-kgba=n>; B<n> is 0, 1, or 2
+B<--keyword-group-blanks-after=n>,  or B<-kgba=n>; B<n> = (0, 1, or 2) controls a trailing blank
 
-B<--keyword-group-blanks-inside>, or B<-kgbi> is an on/off switch
+B<--keyword-group-blanks-inside>, or B<-kgbi> is a switch for adding blanks between subgroups
 
-B<--keyword-group-blanks-delete>, or B<-kgbd> is an on/off switch
+B<--keyword-group-blanks-delete>, or B<-kgbd> is a switch for removing initial blank lines between keywords
 
-In addition, the following abbreviations are available to simplify usage:
+In addition, the following abbreviations are available to for simplified usage:
 
-B<--keyword-group-blanks>,   or B<-kgb>,  is short for B<-kgbb=1 -kgba=1 kgbi>
+B<--keyword-group-blanks>,   or B<-kgb>,  is short for B<-kgbb=2 -kgba=2 kgbi>
 
-B<--nokeyword-group-blanks>, or B<-nkgb>, is short for B<-kgbb=0 -kgba=0 nkgbi>
+B<--nokeyword-group-blanks>, or B<-nkgb>, is short for B<-kgbb=1 -kgba=1 nkgbi>
 
 Before describing the meaning of the parameters in detail let us look at an
 example which is formatted with default parameter settings.
@@ -2709,20 +2709,20 @@ example which is formatted with default parameter settings.
 using B<perltidy -kgb> gives:
 
         print "Entering test 2\n";
-                                            <-this blank controlled by -kgbb
+                                      <----------this blank controlled by -kgbb
         use Test;
         use Encode qw(from_to encode decode
           encode_utf8 decode_utf8
           find_encoding is_utf8);
         use charnames qw(greek);
-                                            <-this blank controlled by -kgbi
+                                      <---------this blank controlled by -kgbi
         my @encodings     = grep( /iso-?8859/, Encode::encodings() );
         my @character_set = ( '0' .. '9', 'A' .. 'Z', 'a' .. 'z' );
         my @source        = qw(ascii iso8859-1 cp1250);
         my @destiny       = qw(cp1047 cp37 posix-bc);
         my @ebcdic_sets   = qw(cp1047 cp37 posix-bc);
         my $str           = join( '', map( chr($_), 0x20 .. 0x7E ) );
-                                             <-this blank controlled by -kgba
+                                      <----------this blank controlled by -kgba
         return unless ($str);
 
 Blank lines have been introduced around the B<my> and B<use> sequences.  What
@@ -2743,22 +2743,19 @@ our my sub">, but any list of keywords may be used.
 
 B<--keyword-group-blanks-count=n>, or B<-kgbc=n>, where B<n> is the minimum
 number of consecutive keyword statements to which these controls apply.  The
-default is B<n=5>.
+default is B<n=5>. The special value B<n=0> can be used to turn off all 
+searching for keyword groups.
 
 B<--keyword-group-blanks-before=n>, or B<-kgbb=n>, specifies whether
 a blank should appear before the first line of the group, as follows:
 
-   n=0 => no change to the input file is made 
-   n=1 => a blank line is introduced if possible
-   n=2 => an existing blank line will be removed
+   n=0 => (delete) an existing blank line will be removed
+   n=1 => (stable) no change to the input file is made  [DEFAULT]
+   n=2 => (insert) a blank line is introduced if possible
 
 B<--keyword-group-blanks-after=n>, or B<-kgba=n>, likewise specifies
 whether a blank should appear after the last line of the group, using the same
-scheme:
-
-   n=0 => no change to the input file is made [Default]
-   n=1 => a blank line is introduced if possible 
-   n=2 => an existing blank line will be removed
+scheme (0=delete, 1=stable, 2=insert).
 
 B<--keyword-group-blanks-inside>, or B<-kgbi>, controls
 the insertion of blank lines between the first and last statement of the entire

diff --git a/docs/perltidy.html b/docs/perltidy.html
index 6713a9f5da952601a634617cc5a6cd25313e0569..500198c8e1da5528c72b49830208cad8f7bd8782 100644 (file)
--- a/docs/perltidy.html
+++ b/docs/perltidy.html
@@ -2113,23 +2113,23 @@
 
 <p>It is common in Perl programs to have consecutive statements beginning with a certain common keyword, or one of a certain set of keywords. For example near the top of a program there might be a series of <b>use</b> statements or a series of <b>my</b> declarations. The parameters in this section provide control over the placement of blank lines within and around such groups of statements. These blank lines are called here <b>keyword group blanks</b>, and all of the parameters begin with <b>--keyword-group-blanks*</b>, or <b>-kgb*</b> for short. The default settings do not employ these controls but they can be enabled with the following parameters:</p>
 
-<p><b>--keyword-group-blanks-list=s</b>, or <b>-kgbl=s</b>; <b>s</b> is a quoted string</p>
+<p><b>--keyword-group-blanks-list=s</b>, or <b>-kgbl=s</b>; <b>s</b> is a quoted string of keywords</p>
 
-<p><b>--keyword-group-blanks-count=n</b>, or <b>-kgbc=n</b>; <b>n</b> is an integer [def 5]</p>
+<p><b>--keyword-group-blanks-count=n</b>, or <b>-kgbc=n</b>; <b>n</b> is a threshold group size</p>
 
-<p><b>--keyword-group-blanks-before=n</b>, or <b>-kgbb=n</b>; <b>n</b> is 0, 1, or 2</p>
+<p><b>--keyword-group-blanks-before=n</b>, or <b>-kgbb=n</b>; <b>n</b> = (0, 1, or 2) controls a leading blank</p>
 
-<p><b>--keyword-group-blanks-after=n</b>, or <b>-kgba=n</b>; <b>n</b> is 0, 1, or 2</p>
+<p><b>--keyword-group-blanks-after=n</b>, or <b>-kgba=n</b>; <b>n</b> = (0, 1, or 2) controls a trailing blank</p>
 
-<p><b>--keyword-group-blanks-inside</b>, or <b>-kgbi</b> is an on/off switch</p>
+<p><b>--keyword-group-blanks-inside</b>, or <b>-kgbi</b> is a switch for adding blanks between subgroups</p>
 
-<p><b>--keyword-group-blanks-delete</b>, or <b>-kgbd</b> is an on/off switch</p>
+<p><b>--keyword-group-blanks-delete</b>, or <b>-kgbd</b> is a switch for removing initial blank lines between keywords</p>
 
-<p>In addition, the following abbreviations are available to simplify usage:</p>
+<p>In addition, the following abbreviations are available to for simplified usage:</p>
 
-<p><b>--keyword-group-blanks</b>, or <b>-kgb</b>, is short for <b>-kgbb=1 -kgba=1 kgbi</b></p>
+<p><b>--keyword-group-blanks</b>, or <b>-kgb</b>, is short for <b>-kgbb=2 -kgba=2 kgbi</b></p>
 
-<p><b>--nokeyword-group-blanks</b>, or <b>-nkgb</b>, is short for <b>-kgbb=0 -kgba=0 nkgbi</b></p>
+<p><b>--nokeyword-group-blanks</b>, or <b>-nkgb</b>, is short for <b>-kgbb=1 -kgba=1 nkgbi</b></p>
 
 <p>Before describing the meaning of the parameters in detail let us look at an example which is formatted with default parameter settings.</p>
 
@@ -2150,20 +2150,20 @@
 <p>using <b>perltidy -kgb</b> gives:</p>
 
 <pre><code>        print &quot;Entering test 2\n&quot;;
-                                            &lt;-this blank controlled by -kgbb
+                                      &lt;----------this blank controlled by -kgbb
         use Test;
         use Encode qw(from_to encode decode
           encode_utf8 decode_utf8
           find_encoding is_utf8);
         use charnames qw(greek);
-                                            &lt;-this blank controlled by -kgbi
+                                      &lt;---------this blank controlled by -kgbi
         my @encodings     = grep( /iso-?8859/, Encode::encodings() );
         my @character_set = ( &#39;0&#39; .. &#39;9&#39;, &#39;A&#39; .. &#39;Z&#39;, &#39;a&#39; .. &#39;z&#39; );
         my @source        = qw(ascii iso8859-1 cp1250);
         my @destiny       = qw(cp1047 cp37 posix-bc);
         my @ebcdic_sets   = qw(cp1047 cp37 posix-bc);
         my $str           = join( &#39;&#39;, map( chr($_), 0x20 .. 0x7E ) );
-                                             &lt;-this blank controlled by -kgba
+                                      &lt;----------this blank controlled by -kgba
         return unless ($str);</code></pre>
 
 <p>Blank lines have been introduced around the <b>my</b> and <b>use</b> sequences. What happened is that the default keyword list includes <b>my</b> and <b>use</b> but not <b>print</b> and <b>return</b>. So a continuous sequence of nine <b>my</b> and <b>use</b> statements was located. This number exceeds the default threshold of five, so blanks were placed before and after the entire group. Then, since there was also a subsequence of six <b>my</b> lines, a blank line was introduced to separate them.</p>
@@ -2172,19 +2172,15 @@
 
 <p><b>--keyword-group-blanks-list=s</b>, or <b>-kgbl=s</b>, where <b>s</b> is a quoted string, defines the set of keywords which will be formed into groups. The string is a space separated list of keywords. The default set is <b>s=&quot;use require local our my sub&quot;</b>, but any list of keywords may be used.</p>
 
-<p><b>--keyword-group-blanks-count=n</b>, or <b>-kgbc=n</b>, where <b>n</b> is the minimum number of consecutive keyword statements to which these controls apply. The default is <b>n=5</b>.</p>
+<p><b>--keyword-group-blanks-count=n</b>, or <b>-kgbc=n</b>, where <b>n</b> is the minimum number of consecutive keyword statements to which these controls apply. The default is <b>n=5</b>. The special value <b>n=0</b> can be used to turn off all searching for keyword groups.</p>
 
 <p><b>--keyword-group-blanks-before=n</b>, or <b>-kgbb=n</b>, specifies whether a blank should appear before the first line of the group, as follows:</p>
 
-<pre><code>   n=0 =&gt; no change to the input file is made 
-   n=1 =&gt; a blank line is introduced if possible
-   n=2 =&gt; an existing blank line will be removed</code></pre>
+<pre><code>   n=0 =&gt; (delete) an existing blank line will be removed
+   n=1 =&gt; (stable) no change to the input file is made  [DEFAULT]
+   n=2 =&gt; (insert) a blank line is introduced if possible</code></pre>
 
-<p><b>--keyword-group-blanks-after=n</b>, or <b>-kgba=n</b>, likewise specifies whether a blank should appear after the last line of the group, using the same scheme:</p>
-
-<pre><code>   n=0 =&gt; no change to the input file is made [Default]
-   n=1 =&gt; a blank line is introduced if possible 
-   n=2 =&gt; an existing blank line will be removed</code></pre>
+<p><b>--keyword-group-blanks-after=n</b>, or <b>-kgba=n</b>, likewise specifies whether a blank should appear after the last line of the group, using the same scheme (0=delete, 1=stable, 2=insert).</p>
 
 <p><b>--keyword-group-blanks-inside</b>, or <b>-kgbi</b>, controls the insertion of blank lines between the first and last statement of the entire group. If there is a continuous run of a single statement type with more than the minimum threshold number (as specified with <b>-kgbc=n</b>) then this switch causes a blank line be inserted between this subgroup and the others. In the example above this happened between the <b>use</b> and <b>my</b> statements.</p>
 

diff --git a/lib/Perl/Tidy.pm b/lib/Perl/Tidy.pm
index a96846c33df467060e0a5cbd922f095e32cc62dc..ca7c485b505ee3fe40e6d2f31b591b82a982c72b 100644 (file)
--- a/lib/Perl/Tidy.pm
+++ b/lib/Perl/Tidy.pm
@@ -1937,8 +1937,8 @@ sub generate_options {
 
       noblanks-after-comments
       keyword-group-blanks-count=5
-      keyword-group-blanks-before=0
-      keyword-group-blanks-after=0
+      keyword-group-blanks-before=1
+      keyword-group-blanks-after=1
       nokeyword-group-blanks-inside
       nokeyword-group-blanks-delete
 
@@ -2080,10 +2080,10 @@ sub generate_options {
         'noblanks-before-subs' => [qw(blbs=0 blbp=0)],
         'nbbs'                 => [qw(blbs=0 blbp=0)],
 
-        'keyword-group-blanks'   => [qw(kgbb=1 kgbi kgba=1)],
-        'kgb'                    => [qw(kgbb=1 kgbi kgba=1)],
-        'nokeyword-group-blanks' => [qw(kgbb=0 nkgbi kgba=0)],
-        'nkgb'                   => [qw(kgbb=0 nkgbi kgba=0)],
+        'keyword-group-blanks'   => [qw(kgbb=2 kgbi kgba=2)],
+        'kgb'                    => [qw(kgbb=2 kgbi kgba=2)],
+        'nokeyword-group-blanks' => [qw(kgbb=1 nkgbi kgba=1)],
+        'nkgb'                   => [qw(kgbb=1 nkgbi kgba=1)],
 
         'break-at-old-trinary-breakpoints' => [qw(bot)],
 

diff --git a/lib/Perl/Tidy/Formatter.pm b/lib/Perl/Tidy/Formatter.pm
index 58f74df7e210f8ed36d82e26aedf705480232cba..749fd31352d7574fceb0b85009817c71542b281c 100644 (file)
--- a/lib/Perl/Tidy/Formatter.pm
+++ b/lib/Perl/Tidy/Formatter.pm
@@ -978,18 +978,20 @@ sub keyword_group_scan {
     my $Opt_blanks_after  = $rOpts->{'keyword-group-blanks-after'};    # '-kgba'
     my $Opt_blanks_inside = $rOpts->{'keyword-group-blanks-inside'};   # '-kgbi'
     my $Opt_blanks_delete = $rOpts->{'keyword-group-blanks-delete'};   # '-kgbd'
+    my $Opt_long_count    = $rOpts->{'keyword-group-blanks-count'};    # '-kgbc'
+
+    # codes for $Opt_blanks_before and $Opt_blanks_after:
+    # 0 = never (delete if exist)
+    # 1 = stable (keep unchanged)
+    # 2 = always (insert if missing)
 
     return $rhash_of_desires
-      unless ( $Opt_blanks_before
-        || $Opt_blanks_after
-        || $Opt_blanks_inside 
+      unless $Opt_long_count > 0
+      && ( $Opt_blanks_before != 1
+        || $Opt_blanks_after != 1
+        || $Opt_blanks_inside
         || $Opt_blanks_delete );
 
-    $Opt_blanks_before = 0 unless defined($Opt_blanks_before);
-    $Opt_blanks_after  = 0 unless defined($Opt_blanks_after);
-
-
-    my $Opt_long_count = $rOpts->{'keyword-group-blanks-count'};    # '-kgbc'
     my $Opt_blanks_after_comments = $rOpts->{'blanks-after-comments'};  # '-bac'
     my $Opt_pattern               = $keyword_group_list_pattern;
 
@@ -1083,7 +1085,7 @@ sub keyword_group_scan {
                     if (   $Opt_blanks_after_comments
                         || $code_type !~ /(BC|SBC|SBCX)/ )
                     {
-                        if ( $Opt_blanks_before == 1 ) {
+                        if ( $Opt_blanks_before == 2 ) {
                             $rhash_of_desires->{ $ibeg - 1 } = 1;
                             if ( defined( $rhash_of_desires->{$ibeg} )
                                 && $rhash_of_desires->{$ibeg} == 2 )
@@ -1091,7 +1093,7 @@ sub keyword_group_scan {
                                 $rhash_of_desires->{$ibeg} = 0;
                             }
                         }
-                        elsif ( $Opt_blanks_before == 2 ) {
+                        elsif ( $Opt_blanks_before == 0 ) {
                             $delete_if_blank->( $ibeg - 1 );
                         }
                     }
@@ -1117,10 +1119,10 @@ sub keyword_group_scan {
                         && $iend < @{$rlines}
                         && $CODE_type ne 'HSC' )
                     {
-                        if ( $Opt_blanks_after == 1 ) {
+                        if ( $Opt_blanks_after == 2 ) {
                             $rhash_of_desires->{$iend} = 1;
                         }
-                        elsif ( $Opt_blanks_after == 2 ) {
+                        elsif ( $Opt_blanks_after == 0 ) {
                             $delete_if_blank->( $iend + 1 );
                         }
                     }