B<--keyword-group-blanks-after=n>, or B<-kgba=n>; B<n> is 0, 1, or 2
-B<--keyword-group-blanks-inside=n>, or B<-kgbi=n>; B<n> is 0 or 1
+B<--keyword-group-blanks-inside>, or B<-kgbi> is an on/off switch
-B<--keyword-group-blanks-delete>, or B<-kgbd>; is an on/off switch
+B<--keyword-group-blanks-delete>, or B<-kgbd> is an on/off switch
In addition, the following abbreviations are available to simplify usage:
-B<--keyword-group-blanks>, or B<-kgb>, is short for B<-kgbb=1 -kgba=1 -kgbi=1>
+B<--keyword-group-blanks>, or B<-kgb>, is short for B<-kgbb=1 -kgba=1 kgbi>
-B<--nokeyword-group-blanks>, or B<-nkgb>, is short for B<-kgbb=0 -kgba=0 -kgbi=0>
+B<--nokeyword-group-blanks>, or B<-nkgb>, is short for B<-kgbb=0 -kgba=0 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
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
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
return unless ($str);
Blank lines have been introduced around the B<my> and B<use> sequences. What
also a subsequence of six B<my> lines, a blank line was introduced to separate
them.
-Now suppose there had been some spaces in the starting script, such as
-
- print "Entering test 2\n";
- use Test;
- use Encode qw(from_to encode decode
- encode_utf8 decode_utf8
- find_encoding is_utf8);
-
- use charnames qw(greek);
- 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 ) );
- return unless ($str);
-
-Using just B<perltidy -kgb> would have no effect on this script because the
-groups each have fewer than the threshold number of statements. If more
-compact code is desirable there is a parameter B<-kgbd> available which
-causes perltidy to make a preliminary pass through the input script to delete
-blank lines between lines with the keywords being sought. This allows
-keyword groups of maximum possible length to be formed.
-
-So using B<perltidy -kgbd -kgb> on the above script would produce the same
-output as previously shown.
-
Finer control over blank placement can be achieved by using the individual
parameters rather than the B<-kgb> flag. The individual controls are as follows.
n=1 => a blank line is introduced if possible
n=2 => an existing blank line will be removed
-B<--keyword-group-blanks-inside=n>, or B<-kgbi=n>, specifies
-whether subgroups of a single statement type with more than the minimum number (as
-specified with B<-kgbc=n>) may be separated from the other sub-groups with
-blank lines, where
-
- n=0 => no blank internal line is introduced [Default]
- n=1 => a blank line is introduced before and after a subgroup
-
-B<--keyword-group-blanks-delete>, or B<-kgbd>, causes blank lines between two
-statements with one of the sought keywords to be deleted before groups are
-formed. This will produce the most compact code and maximum group sizes. To
-leave these blank lines unchanged use B<--nokeyword-group-blanks-delete>, or
-B<-nkgbd>. Note that the B<-kgbd> flag only removes blank lines between
-statements with one of the keywords being sought. Blanks before and after
-keyword sequences can be controlled with parameters B<-kgbb> and B<-kgba>.
-Also note that blanks deleted by this flag are not subject to any threshold
-number. All qualifying blank lines will be deleted.
-
-B<--keyword-group-blanks>, or B<-kgb>, which is equivalent to setting
-B<-kgbb=1 -kgba=1 -kgbi=1>. This turns on keyword group formatting
-with a set of default values.
-
-B<--nokeyword-group-blanks>, or B<-nkgb>, is equivalent to B<-kgbb=0 -kgba kgbi=0>.
-This flag turns off keyword group blank lines and is the default setting.
+B<--keyword-group-blanks-inside>, or B<-kgbi>, 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>) 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> and B<my> statements.
+
+B<--keyword-group-blanks-delete>, or B<-kgbd>, controls the deletion of any
+blank lines that exist in the the group when it is first scanned. When
+statements are initially scanned, any existing blank lines are included in the
+collection. Any such orignial blank lines will be deleted before any other
+insertions are made when the parameter B<-kgbd> is set. The default is not to
+do this, B<-nkgbd>.
+
+B<--keyword-group-blanks>, or B<-kgb>, is an abbreviation equivalent to setting
+B<-kgbb=1 -kgba=1 -kgbi>. This turns on keyword group formatting with a set of
+default values.
+
+B<--nokeyword-group-blanks>, or B<-nkgb>, is equivalent to B<-kgbb=0 -kgba
+nkgbi>. This flag turns off keyword group blank lines and is the default
+setting.
Here are a few notes about the functioning of this technique.
<h2>2018 11 20.01</h2>
-<pre><code>- Add repository URLs to META files
+<pre><code>- RT#12764, introduced new feature allowing placement of blanks around
+ sequences of selected keywords such as use, my, our, local. This can
+ be activated with the -kgb* series of parameters described in the manual.
+
- Rewrote vertical algnment module. It is much better at finding
patterns in complex code.
+
+- Add repository URLs to META files
</code></pre>
<h2>2018 11 20</h2>
<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-inside=n</b>, or <b>-kgbi=n</b>; <b>n</b> is 0 or 1</p>
+<p><b>--keyword-group-blanks-inside</b>, or <b>-kgbi</b> is an on/off switch</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 an on/off switch</p>
<p>In addition, the following abbreviations are available to simplify usage:</p>
-<p><b>--keyword-group-blanks</b>, or <b>-kgb</b>, is short for <b>-kgbb=1 -kgba=1 -kgbi=1</b></p>
+<p><b>--keyword-group-blanks</b>, or <b>-kgb</b>, is short for <b>-kgbb=1 -kgba=1 kgbi</b></p>
-<p><b>--nokeyword-group-blanks</b>, or <b>-nkgb</b>, is short for <b>-kgbb=0 -kgba=0 -kgbi=0</b></p>
+<p><b>--nokeyword-group-blanks</b>, or <b>-nkgb</b>, is short for <b>-kgbb=0 -kgba=0 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
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
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
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>Now suppose there had been some spaces in the starting script, such as</p>
-
-<pre><code> print "Entering test 2\n";
- use Test;
- use Encode qw(from_to encode decode
- encode_utf8 decode_utf8
- find_encoding is_utf8);
-
- use charnames qw(greek);
- 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 ) );
- return unless ($str);</code></pre>
-
-<p>Using just <b>perltidy -kgb</b> would have no effect on this script because the groups each have fewer than the threshold number of statements. If more compact code is desirable there is a parameter <b>-kgbd</b> available which causes perltidy to make a preliminary pass through the input script to delete blank lines between lines with the keywords being sought. This allows keyword groups of maximum possible length to be formed.</p>
-
-<p>So using <b>perltidy -kgbd -kgb</b> on the above script would produce the same output as previously shown.</p>
-
<p>Finer control over blank placement can be achieved by using the individual parameters rather than the <b>-kgb</b> flag. The individual controls are as follows.</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>
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-inside=n</b>, or <b>-kgbi=n</b>, specifies whether subgroups of a single statement type with more than the minimum number (as specified with <b>-kgbc=n</b>) may be separated from the other sub-groups with blank lines, where</p>
-
-<pre><code> n=0 => no blank internal line is introduced [Default]
- n=1 => a blank line is introduced before and after a subgroup</code></pre>
+<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>
-<p><b>--keyword-group-blanks-delete</b>, or <b>-kgbd</b>, causes blank lines between two statements with one of the sought keywords to be deleted before groups are formed. This will produce the most compact code and maximum group sizes. To leave these blank lines unchanged use <b>--nokeyword-group-blanks-delete</b>, or <b>-nkgbd</b>. Note that the <b>-kgbd</b> flag only removes blank lines between statements with one of the keywords being sought. Blanks before and after keyword sequences can be controlled with parameters <b>-kgbb</b> and <b>-kgba</b>. Also note that blanks deleted by this flag are not subject to any threshold number. All qualifying blank lines will be deleted.</p>
+<p><b>--keyword-group-blanks-delete</b>, or <b>-kgbd</b>, controls the deletion of any blank lines that exist in the the group when it is first scanned. When statements are initially scanned, any existing blank lines are included in the collection. Any such orignial blank lines will be deleted before any other insertions are made when the parameter <b>-kgbd</b> is set. The default is not to do this, <b>-nkgbd</b>.</p>
-<p><b>--keyword-group-blanks</b>, or <b>-kgb</b>, which is equivalent to setting <b>-kgbb=1 -kgba=1 -kgbi=1</b>. This turns on keyword group formatting with a set of default values.</p>
+<p><b>--keyword-group-blanks</b>, or <b>-kgb</b>, is an abbreviation equivalent to setting <b>-kgbb=1 -kgba=1 -kgbi</b>. This turns on keyword group formatting with a set of default values.</p>
-<p><b>--nokeyword-group-blanks</b>, or <b>-nkgb</b>, is equivalent to <b>-kgbb=0 -kgba kgbi=0</b>. This flag turns off keyword group blank lines and is the default setting.</p>
+<p><b>--nokeyword-group-blanks</b>, or <b>-nkgb</b>, is equivalent to <b>-kgbb=0 -kgba nkgbi</b>. This flag turns off keyword group blank lines and is the default setting.</p>
<p>Here are a few notes about the functioning of this technique.</p>
$add_option->( 'keyword-group-blanks-count', 'kgbc', '=i' );
$add_option->( 'keyword-group-blanks-before', 'kgbb', '=i' );
$add_option->( 'keyword-group-blanks-after', 'kgba', '=i' );
- $add_option->( 'keyword-group-blanks-inside', 'kgbi', '=i' );
+ $add_option->( 'keyword-group-blanks-inside', 'kgbi', '!' );
$add_option->( 'keyword-group-blanks-delete', 'kgbd', '!' );
$add_option->( 'blank-lines-after-opening-block', 'blao', '=i' );
'keyword-group-blanks-before' => [ 0, 2 ],
'keyword-group-blanks-after' => [ 0, 2 ],
- 'keyword-group-blanks-inside' => [ 0, 1 ],
);
# Note: we could actually allow negative ci if someone really wants it:
keyword-group-blanks-count=5
keyword-group-blanks-before=0
keyword-group-blanks-after=0
- keyword-group-blanks-inside=0
+ nokeyword-group-blanks-inside
+ nokeyword-group-blanks-delete
block-brace-tightness=0
block-brace-vertical-tightness=0
'noblanks-before-subs' => [qw(blbs=0 blbp=0)],
'nbbs' => [qw(blbs=0 blbp=0)],
- 'keyword-group-blanks' => [qw(kgbb=1 kgbi=1 kgba=1)],
- 'kgb' => [qw(kgbb=1 kgbi=1 kgba=1)],
- 'nokeyword-group-blanks' => [qw(kgbb=0 kgbi=0 kgba=0)],
- 'nkgb' => [qw(kgbb=0 kgbi=0 kgba=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)],
'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'
- my $Opt_blanks_after_comments = $rOpts->{'blanks-after-comments'}; # '-bac'
- my $Opt_pattern =
- $keyword_group_list_pattern; # like '^(my|local|our|use)$';
return $rhash_of_desires
unless ( $Opt_blanks_before
|| $Opt_blanks_after
- || $Opt_blanks_inside
+ || $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;
+
my $rlines = $self->{rlines};
my $rLL = $self->{rLL};
my $K_closing_container = $self->{K_closing_container};
# Here we place blanks around long sub-groups of keywords
# if requested.
- return unless ($Opt_blanks_inside);
+ return unless ( $Opt_blanks_inside );
my $ib = $sublist[0]->[0];
push @sublist, [ $iend + 1, "", 0 ];
my $ie = $sublist[$j]->[0] - 1;
my $num = $sublist[ $j - 1 ]->[2];
if ( $num >= $Opt_long_count ) {
- if ($Opt_blanks_inside) {
- $rhash_of_desires->{ $ib - 1 } = 1 unless ( $ib == $ibeg );
- $rhash_of_desires->{$ie} = 1 unless ( $ie == $iend );
- }
+ $rhash_of_desires->{ $ib - 1 } = 1 unless ( $ib == $ibeg );
+ $rhash_of_desires->{$ie} = 1 unless ( $ie == $iend );
}
$ib = $ie + 1;
}
my $delete_if_blank = sub {
my ($i) = @_;
+
+ # delete line $i if it is blank
return unless ( $i >= 0 && $i < @{$rlines} );
my $line_type = $rlines->[$i]->{_line_type};
return if ( $line_type ne 'CODE' );
my $delete_inner_blank_lines = sub {
# mark blank lines for deletion if requested
- return unless $Opt_blanks_delete;
+ return unless ($Opt_blanks_delete );
# remove trailing blank lines from the list
my $i_last_nonblank = $iend;
my ($bad_ending) = @_;
if ( defined($ibeg) && $ibeg >= 0 ) {
- # first do any blank deletions regardless of the count
- $delete_inner_blank_lines->();
-
# then handle sufficiently large groups
if ( $count >= $Opt_long_count ) {
+ # do any blank deletions regardless of the count
+ $delete_inner_blank_lines->();
+
if ( $ibeg > 0 ) {
my $code_type = $rlines->[ $ibeg - 1 ]->{_code_type};
}
# continue in a verbatim (VB) type; it may be quoted text
- if ( $CODE_type eq 'VB' ) {
+ # and continue in blank (BL) types
+ if ( $CODE_type eq 'VB' || $CODE_type eq 'BL') {
if ( $ibeg >= 0 ) { $iend = $i; }
next;
}
- # continue in blank (BL) types only if we are deleting blanks
- if ( $CODE_type eq 'BL' ) {
- if ( $ibeg >= 0 ) {
- if ($Opt_blanks_delete) { $iend = $i }
- else { $end_group->() }
- }
- next;
- }
-
# examine the first token of this line
my $rK_range = $line_of_tokens->{_rK_range};
( $K_first, $K_last ) = @{$rK_range};
projects / perltidy.git / commitdiff