# Perltidy Change Log
+## 2020 10 01.01
+
- Add flag -xci, --extended-continuation-indentation, regarding issue git #28
+ - Fix issue git #42, clarify how --break-at-old-logical-breakpoints works.
+
- Fix issue git #41, typo in manual regarding -fsb
- Fix issue git #40: when using the -bli option, a closing brace followed by
=item B<-xci>, B<--extended-continuation-indentation>
-This flag causes continuation indentation to "extend" deeper into containers.
-It is a fairly recent addition and is set off by default to avoid disturbing
-existing formatting. If you use a continuation indentation equal to the
-indentation, you will probably want to set this flag.
+This flag causes continuation indentation to "extend" deeper into structures.
+If you use B<-ci=n> and B<-i=n> with the same value of B<n> you will probably
+want to set this flag. Since this is a fairly new flag, the default is B<-nxci>
+to avoid disturbing existing formatting.
Here is an explanation. There are two common strategies for continuation
indentation. One is the strategy recommend in the original perl style
guidelines, in which B<-ci=2> and B<-i=4>. The other is the strategy is the
-strategy recommended in the Perl Best Practices (B<-pbp>) by Conway, in which
-B<-ci=4> and B<-i=4>. The default formatting in perltidy works fairly well
-with the orignal perl style, but problems arise when B<-ci> and B<-i> are given
-equal values as in the B<pbp> style, particularly with ternary statements. The
-B<-xci> flag was added to fix this.
+strategy recommended for example in the "Perl Best Practices" book by Conway,
+in which B<-ci=4> and B<-i=4>. The default formatting in perltidy works fairly
+well with the orignal perl style, but problems arise when B<-ci> and B<-i> are
+given equal values as in the B<pbp> style, particularly with ternary
+statements. The B<-xci> flag was added to fix this. It may be used with
+any value of B<-ci> but is particularly helpful when B<-ci> and B<-i> are given
+similar values.
-For an illustration, please see the section on the B<--perl-best-practices> flag.
+For an illustration, please see the section L<"B<-pbp>, B<--perl-best-practices>">.
=item B<-sil=n> B<--starting-indentation-level=n>
=head1 VERSION
-This man page documents perltidy version 20201001
+This man page documents perltidy version 20201001.01
=head1 BUG REPORTS
<ul id="index">
+ <li><a href="#Issues-fixed-after-release-20201001">Issues fixed after release 20201001</a></li>
<li><a href="#Issues-fixed-after-release-20200907">Issues fixed after release 20200907</a></li>
+ <li><a href="#POD-ERRORS">POD ERRORS</a></li>
</ul>
+<h1 id="Issues-fixed-after-release-20201001">Issues fixed after release 20201001</h1>
+
+<dl>
+
+<dt id="terminal-braces-not-indenting-correctly-with--bli-formatting-issue-git-40"><b>terminal braces not indenting correctly with -bli formatting, issue git #40</b></dt>
+<dd>
+
+<p>This problem is illustrated with the following snippet when run with -bli -blil='*'</p>
+
+<pre><code> #-bli -bli list='*'
+ try
+ {
+ die;
+ }
+ catch
+ {
+ die;
+ }; # <-- this was not indenting</code></pre>
+
+<p>This was due to conflicting rules and was fixed 1 Oct 2020 in commit 'fix issue git #40, incorrect closing brace indentation with -bli', a5aefe9.</p>
+
+<p>At the same time, it was noted that block types sort/map/grep and eval were not following -bli formatting when -blil='*' and this was fixed. For example, with corrected formatting, we would have</p>
+
+<pre><code> # perltidy -bli -blil='*'
+ eval
+ {
+ my $app = App::perlbrew->new( "install-patchperl", "-q" );
+ $app->run();
+ }
+ or do
+ {
+ $error = $@;
+ $produced_error = 1;
+ };</code></pre>
+
+</dd>
+</dl>
+
<h1 id="Issues-fixed-after-release-20200907">Issues fixed after release 20200907</h1>
<p>This is a detailed log of changes since the release 20200907. All bugs were found with the help of automated random testing.</p>
</dd>
</dl>
+<h1 id="POD-ERRORS">POD ERRORS</h1>
+
+<p>Hey! <b>The above document had some coding errors, which are explained below:</b></p>
+
+<dl>
+
+<dt id="Around-line-3">Around line 3:</dt>
+<dd>
+
+<p>'=item' outside of any '=over'</p>
+
+</dd>
+<dt id="Around-line-36">Around line 36:</dt>
+<dd>
+
+<p>You forgot a '=back' before '=head1'</p>
+
+</dd>
+</dl>
+
</body>
<h1>Perltidy Change Log</h1>
+<h2>2020 10 01.01</h2>
+
+<pre><code>- Add flag -xci, --extended-continuation-indentation, regarding issue git #28
+
+- Fix issue git #42, clarify how --break-at-old-logical-breakpoints works.
+
+- Fix issue git #41, typo in manual regarding -fsb
+
+- Fix issue git #40: when using the -bli option, a closing brace followed by
+ a semicolon was not being indented.
+</code></pre>
+
<h2>2020 10 01</h2>
<pre><code>- Robustness of perltidy has been significantly improved. Updating is recommended. Continual
<h1 id="VERSION">VERSION</h1>
-<p>This man page documents Perl::Tidy version 20201001</p>
+<p>This man page documents Perl::Tidy version 20201001.01</p>
<h1 id="LICENSE">LICENSE</h1>
<p>The value given to <b>-ci</b> is also used by some commands when a small space is required. Examples are commands for outdenting labels, <b>-ola</b>, and control keywords, <b>-okw</b>.</p>
-<p>When default values are not used, it is highly recommended that the value <b>n</b> given with <b>-ci=n</b> be no more than about one-half of the number of spaces assigned to a full indentation level on the <b>-i=n</b> command. The reason is that discontinuities in the definition and control of continuation indentation arise in complex code, and this rule helps to smooth out these discontinuities.</p>
+<p>When default values are not used, it is recommended that either</p>
+
+<p>(1) the value <b>n</b> given with <b>-ci=n</b> be no more than about one-half of the number of spaces assigned to a full indentation level on the <b>-i=n</b> command, or</p>
+
+<p>(2) the flag <b>-extended-continuation-indentation</b> is used (see next section).</p>
+
+</dd>
+<dt id="xci---extended-continuation-indentation"><b>-xci</b>, <b>--extended-continuation-indentation</b></dt>
+<dd>
+
+<p>This flag causes continuation indentation to "extend" deeper into structures. If you use <b>-ci=n</b> and <b>-i=n</b> with the same value of <b>n</b> you will probably want to set this flag. Since this is a fairly new flag, the default is <b>-nxci</b> to avoid disturbing existing formatting.</p>
+
+<p>Here is an explanation. There are two common strategies for continuation indentation. One is the strategy recommend in the original perl style guidelines, in which <b>-ci=2</b> and <b>-i=4</b>. The other is the strategy is the strategy recommended for example in the "Perl Best Practices" book by Conway, in which <b>-ci=4</b> and <b>-i=4</b>. The default formatting in perltidy works fairly well with the orignal perl style, but problems arise when <b>-ci</b> and <b>-i</b> are given equal values as in the <b>pbp</b> style, particularly with ternary statements. The <b>-xci</b> flag was added to fix this. It may be used with any value of <b>-ci</b> but is particularly helpful when <b>-ci</b> and <b>-i</b> are given similar values.</p>
+
+<p>For an illustration, please see the section <a href="#pbp---perl-best-practices">"<b>-pbp</b>, <b>--perl-best-practices</b>"</a>.</p>
</dd>
<dt id="sil-n---starting-indentation-level-n"><b>-sil=n</b> <b>--starting-indentation-level=n</b></dt>
<pre><code> # perltidy -nwrs='-'
my @newkeys = map $_ -$nrecs + @data, @oldkeys;</code></pre>
+<p>For another example, the following two lines will be parsed without syntax error:</p>
+
+<pre><code> # original programming, syntax ok
+ for my $severity ( reverse $SEVERITY_LOWEST+1 .. $SEVERITY_HIGHEST ) { ... }
+
+ # perltidy default, syntax ok
+ for my $severity ( reverse $SEVERITY_LOWEST + 1 .. $SEVERITY_HIGHEST ) { ... }</code></pre>
+
+<p>But the following will give a syntax error:</p>
+
+<pre><code> # perltidy -nwrs='+', syntax error:
+ for my $severity ( reverse $SEVERITY_LOWEST +1 .. $SEVERITY_HIGHEST ) { ... }</code></pre>
+
+<p>To avoid subtle parsing problems like this, it is best to avoid spacing a binary operator asymetrically with a space on the left but not on the right.</p>
+
</dd>
<dt id="Space-between-specific-keywords-and-opening-paren">Space between specific keywords and opening paren</dt>
<dd>
<p>The reason this is not recommended is that spacing a function paren can make a program vulnerable to parsing problems by Perl. For example, the following two-line program will run as written but will have a syntax error if reformatted with -sfp:</p>
-<pre><code> if ( -e filename() ) { print "exists\n"; }
+<pre><code> if ( -e filename() ) { print "I'm here\n"; }
sub filename { return $0 }</code></pre>
-<p>The syntax error can be removed if the line order is reversed, so that Perl parses 'sub filename' first.</p>
+<p>In this particular case the syntax error can be removed if the line order is reversed, so that Perl parses 'sub filename' first.</p>
</dd>
<dt id="spp-n-or---space-prototype-paren-n"><b>-spp=n</b> or <b>--space-prototype-paren=n</b></dt>
<dt id="fse-string---format-skipping-end-string"><b>-fse=string</b>, <b>--format-skipping-end=string</b></dt>
<dd>
-<p>The <b>-fsb=string</b> is the corresponding parameter used to change the ending marker for format skipping. The default is equivalent to -fse='#<<<'.</p>
+<p>The <b>-fse=string</b> is the corresponding parameter used to change the ending marker for format skipping. The default is equivalent to -fse='#<<<'.</p>
<p>The beginning and ending strings may be the same, but it is preferable to make them different for clarity.</p>
<p>By default, if a logical expression is broken at a <code>&&</code>, <code>||</code>, <code>and</code>, or <code>or</code>, then the container will remain broken. Also, breaks at internal keywords <code>if</code> and <code>unless</code> will normally be retained. To prevent this, and thus form longer lines, use <b>-nbol</b>.</p>
+<p>Please note that this flag does not duplicate old logical breakpoints. They are merely used as a hint with this flag that a statement should remain broken. Without this flag, perltidy will normally try to combine relatively short expressions into a single line.</p>
+
+<p>For example, given this snippet:</p>
+
+<pre><code> return unless $cmd = $cmd || ($dot
+ && $Last_Shell) || &prompt('|');
+
+ # perltidy -bol [default]
+ return
+ unless $cmd = $cmd
+ || ( $dot
+ && $Last_Shell )
+ || &prompt('|');
+
+ # perltidy -nbol
+ return unless $cmd = $cmd || ( $dot && $Last_Shell ) || &prompt('|');</code></pre>
+
</dd>
<dt id="bom---break-at-old-method-breakpoints"><b>-bom</b>, <b>--break-at-old-method-breakpoints</b></dt>
<dd>
<p>Please note that this parameter set includes -st and -se flags, which make perltidy act as a filter on one file only. These can be overridden by placing <b>-nst</b> and/or <b>-nse</b> after the -pbp parameter.</p>
-<p>Also note that the value of continuation indentation, -ci=4, is equal to the value of the full indentation, -i=4. In some complex statements perltidy will produce nicer results with -ci=2. This can be implemented by including -ci=2 after the -pbp parameter. For example,</p>
+<p>Also note that the value of continuation indentation, -ci=4, is equal to the value of the full indentation, -i=4. It is recommended that the either (1) the parameter <b>-ci=2</b> be used instead, or the flag <b>-xci</b> be set. This will help show structure, particularly when there are ternary statements. The following snippet illustrates these options.</p>
<pre><code> # perltidy -pbp
$self->{_text} = (
$page
? ( $section ? ' in ' : '' ) . "the $page$page_ext manpage"
: ' elsewhere in this document'
- );</code></pre>
+ );
+
+ # perltidy -pbp -xci
+ $self->{_text} = (
+ !$section ? ''
+ : $type eq 'item' ? "the $section entry"
+ : "the section on $section"
+ )
+ . ( $page
+ ? ( $section ? ' in ' : '' ) . "the $page$page_ext manpage"
+ : ' elsewhere in this document'
+ );</code></pre>
+
+<p>The <b>-xci</b> flag was developed after the <b>-pbp</b> parameters were published so you need to include it separately.</p>
</dd>
<dt id="One-line-blocks">One-line blocks</dt>
<p>There are a few points to note regarding one-line blocks. A one-line block is something like this,</p>
-<pre><code> if ($x > 0) { $y = 1 / $x } </code></pre>
-
<p>where the contents within the curly braces is short enough to fit on a single line.</p>
<p>With few exceptions, perltidy retains existing one-line blocks, if it is possible within the line-length constraint, but it does not attempt to form new ones. In other words, perltidy will try to follow the one-line block style of the input file.</p>
<h1 id="VERSION">VERSION</h1>
-<p>This man page documents perltidy version 20201001</p>
+<p>This man page documents perltidy version 20201001.01</p>
<h1 id="BUG-REPORTS">BUG REPORTS</h1>
# Release version must be bumped, and it is probably past time for a
# release anyway.
- $VERSION = '20201001';
+ $VERSION = '20201001.01';
}
sub DESTROY {
=head1 VERSION
-This man page documents Perl::Tidy version 20201001
+This man page documents Perl::Tidy version 20201001.01
=head1 LICENSE
package Perl::Tidy::Debugger;
use strict;
use warnings;
-our $VERSION = '20201001';
+our $VERSION = '20201001.01';
sub new {
package Perl::Tidy::DevNull;
use strict;
use warnings;
-our $VERSION = '20201001';
+our $VERSION = '20201001.01';
sub new { my $self = shift; return bless {}, $self }
sub print { return }
sub close { return }
package Perl::Tidy::Diagnostics;
use strict;
use warnings;
-our $VERSION = '20201001';
+our $VERSION = '20201001.01';
sub AUTOLOAD {
package Perl::Tidy::FileWriter;
use strict;
use warnings;
-our $VERSION = '20201001';
+our $VERSION = '20201001.01';
sub AUTOLOAD {
{ #<<< A non-indenting brace to contain all lexical variables
use Carp;
-our $VERSION = '20201001';
+our $VERSION = '20201001.01';
# The Tokenizer will be loaded with the Formatter
##use Perl::Tidy::Tokenizer; # for is_keyword()
package Perl::Tidy::HtmlWriter;
use strict;
use warnings;
-our $VERSION = '20201001';
+our $VERSION = '20201001.01';
use File::Basename;
use strict;
use warnings;
use Carp;
-our $VERSION = '20201001';
+our $VERSION = '20201001.01';
sub AUTOLOAD {
use strict;
use warnings;
use Carp;
-our $VERSION = '20201001';
+our $VERSION = '20201001.01';
sub AUTOLOAD {
package Perl::Tidy::IndentationItem;
use strict;
use warnings;
-our $VERSION = '20201001';
+our $VERSION = '20201001.01';
BEGIN {
package Perl::Tidy::LineBuffer;
use strict;
use warnings;
-our $VERSION = '20201001';
+our $VERSION = '20201001.01';
sub AUTOLOAD {
package Perl::Tidy::LineSink;
use strict;
use warnings;
-our $VERSION = '20201001';
+our $VERSION = '20201001.01';
sub AUTOLOAD {
package Perl::Tidy::LineSource;
use strict;
use warnings;
-our $VERSION = '20201001';
+our $VERSION = '20201001.01';
sub AUTOLOAD {
package Perl::Tidy::Logger;
use strict;
use warnings;
-our $VERSION = '20201001';
+our $VERSION = '20201001.01';
sub AUTOLOAD {
package Perl::Tidy::Tokenizer;
use strict;
use warnings;
-our $VERSION = '20201001';
+our $VERSION = '20201001.01';
use Perl::Tidy::LineBuffer;
use Carp;
package Perl::Tidy::VerticalAligner;
use strict;
use warnings;
-our $VERSION = '20201001';
+our $VERSION = '20201001.01';
use Perl::Tidy::VerticalAligner::Alignment;
use Perl::Tidy::VerticalAligner::Line;
{ #<<< A non-indenting brace
-our $VERSION = '20201001';
+our $VERSION = '20201001.01';
# _column_ # the current column number
# _starting_column_ # column number when created
package Perl::Tidy::VerticalAligner::Line;
use strict;
use warnings;
-our $VERSION = '20201001';
+our $VERSION = '20201001.01';
BEGIN {
my $i = 0;