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.
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
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
<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>
<p>using <b>perltidy -kgb</b> gives:</p>
<pre><code> 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);</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>
<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="use require local our my sub"</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 => 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</code></pre>
+<pre><code> 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</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 => 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</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>
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
'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)],
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;
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 )
$rhash_of_desires->{$ibeg} = 0;
}
}
- elsif ( $Opt_blanks_before == 2 ) {
+ elsif ( $Opt_blanks_before == 0 ) {
$delete_if_blank->( $ibeg - 1 );
}
}
&& $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 );
}
}