# Perltidy Change Log
-## 2021 10 29.04
+## 2021 10 29.05
- Two new flags have been added to provide finer vertical alignment control,
--valign-exclusion-list=s (-vxl=s) and --valign-inclusion-list=s (-vil=s).
=item B<Finer alignment control with --valign-exclusion-list=s or -vxl=s and --valign-inclusion-list=s or -vil=s>
-More detailed control of alignment types is available with these two parameters.
-Most of the alignments in typical programs occur at one of the tokens ',' '=',
-and '=>', but many others are possible. The complete list of token types where
-vertical alignment can occur is:
+More detailed control of alignment types is available with these two
+parameters. Most of the vertical alignments in typical programs occur at one
+of the tokens ',', '=', and '=>', but many other alignments are possible and are given in the following list:
= **= += *= &= <<= &&= -= /= |= >>= ||= //= .= %= ^= x=
{ ( ? : , ; => && || ~~ !~~ =~ !~ // <=> ->
if unless and or err for foreach while until
-These alignments are all enabled by default, but they can be selectively disabled by including one or more of these tokens in the list B<valign-exclusion-list=s>. For example, the following would prevent alignment at B<=> and B<if>:
+These alignments are all enabled by default, but they can be selectively disabled by including one or more of these tokens in the space-separated list B<valign-exclusion-list=s>. For example, the following would prevent alignment at B<=> and B<if>:
--valign-exclusion-list='= if'
-If it is simpler to specify only the token types which are to be aligned, use the special symbol B<*> for this list and include the types which are to be aligned in the list of B<--valign-inclusion-list>. For example,
+If it is simpler to specify only the token types which are to be aligned, then use the special symbol B<*> for this exclusion list and include the types which are to be aligned in the list of B<--valign-inclusion-list> (this works because B<*> is not one of the alignment tokens). For example,
the following parameters enable alignment only at commas and 'fat commas':
--valign-exclusion-list='*'
simply ignored. And if a parameter is entered in both lists by mistake
then the exclusion list has priority.
+The default values of these parameters enable all alignments and are equivalent to
+
+ --valign-exclusion-list=' '
+ --valign-inclusion-list='*'
+
To illustrate, consider the following snippet with default formatting
# perltidy
$co_unused = ($color) ? 'on_green' : 'reverse'; # unused
Notice in this last example that although only the equals alignment was
-excluded, the ternary alignments were also lost. This happens because
-alignments are formed from left-to-right, and if an alignment cannot be made
-then potential alignments to its right might be skipped to avoid poor alignments.
+excluded, the ternary alignments were also lost. This happens because the
+vertical aligner sweeps from left-to-right and usually stops if an important
+alignment cannot be made for some reason.
-Also notice side comments remain aligned because their alignment is
+But also notice that side comments remain aligned because their alignment is
controlled separately with the parameter B<--valign-side_comments> described above.
=back
=head1 VERSION
-This man page documents perltidy version 20211029.04
+This man page documents perltidy version 20211029.05
=head1 BUG REPORTS
<h1>Perltidy Change Log</h1>
-<h2>2021 10 29.04</h2>
+<h2>2021 10 29.05</h2>
-<pre><code>- A new flag -gal=s, --grep-alias-list=s, has been added as suggested in
+<pre><code>- Two new flags have been added to provide finer vertical alignment control,
+ --valign-exclusion-list=s (-vxl=s) and --valign-inclusion-list=s (-vil=s).
+ This has been requested several times, recently in git #79.
+
+- A new flag -gal=s, --grep-alias-list=s, has been added as suggested in
git #77. This allows code blocks passed to list operator functions to
be formatted in the same way as a code block passed to grep, map, or sort.
By default, the following list operators in List::Util are included:
<h1 id="VERSION">VERSION</h1>
-<p>This man page documents Perl::Tidy version 20211029.04</p>
+<p>This man page documents Perl::Tidy version 20211029.05</p>
<h1 id="LICENSE">LICENSE</h1>
<dt id="Controlling-code-alignment-with---valign-code-or--vc"><b>Controlling code alignment with --valign-code or -vc</b></dt>
<dd>
-<p>The <b>-vc</b> flag enables alignment of code symbols such as <b>=</b>. The default is <b>-vc</b>.</p>
+<p>The <b>-vc</b> flag enables alignment of code symbols such as <b>=</b>. The default is <b>-vc</b>. For detailed control of which symbols to align, see the <b>-valign-exclude-list</b> parameter below.</p>
</dd>
<dt id="Controlling-side-comment-alignment-with---valign-side-comments-or--vsc"><b>Controlling side comment alignment with --valign-side-comments or -vsc</b></dt>
<p>When <b>-vbc</b> is enabled, block comments can become aligned for example if one comment of a consecutive sequence of comments becomes outdented due a length in excess of the maximum line length. If this occurs, the entire group of comments will remain aligned and be outdented by the same amount. This coordinated alignment will not occur if <b>-nvbc</b> is set. The default is <b>-vbc</b>.</p>
+</dd>
+<dt id="Finer-alignment-control-with---valign-exclusion-list-s-or--vxl-s-and---valign-inclusion-list-s-or--vil-s"><b>Finer alignment control with --valign-exclusion-list=s or -vxl=s and --valign-inclusion-list=s or -vil=s</b></dt>
+<dd>
+
+<p>More detailed control of alignment types is available with these two parameters. Most of the vertical alignments in typical programs occur at one of the tokens ',', '=', and '=>', but many other alignments are possible and are given in the following list:</p>
+
+<pre><code> = **= += *= &= <<= &&= -= /= |= >>= ||= //= .= %= ^= x=
+ { ( ? : , ; => && || ~~ !~~ =~ !~ // <=> ->
+ if unless and or err for foreach while until</code></pre>
+
+<p>These alignments are all enabled by default, but they can be selectively disabled by including one or more of these tokens in the space-separated list <b>valign-exclusion-list=s</b>. For example, the following would prevent alignment at <b>=</b> and <b>if</b>:</p>
+
+<pre><code> --valign-exclusion-list='= if'</code></pre>
+
+<p>If it is simpler to specify only the token types which are to be aligned, then use the special symbol <b>*</b> for this exclusion list and include the types which are to be aligned in the list of <b>--valign-inclusion-list</b> (this works because <b>*</b> is not one of the alignment tokens). For example, the following parameters enable alignment only at commas and 'fat commas':</p>
+
+<pre><code> --valign-exclusion-list='*'
+ --valign-inclusion-list=', =>'</code></pre>
+
+<p>These parameter lists should consist of space-separated tokens from the above list of possible alignment tokens. If an unrecognized parameter appears, it is simply ignored. And if a parameter is entered in both lists by mistake then the exclusion list has priority.</p>
+
+<p>The default values of these parameters enable all alignments and are equivalent to</p>
+
+<pre><code> --valign-exclusion-list=' '
+ --valign-inclusion-list='*'</code></pre>
+
+<p>To illustrate, consider the following snippet with default formatting</p>
+
+<pre><code> # perltidy
+ $co_description = ($color) ? 'bold cyan' : ''; # description
+ $co_prompt = ($color) ? 'bold green' : ''; # prompt
+ $co_unused = ($color) ? 'on_green' : 'reverse'; # unused</code></pre>
+
+<p>To exclude all alignments except the equals we could use:</p>
+
+<pre><code> # perltidy -vxl='*' -vil='='
+ $co_description = ($color) ? 'bold cyan' : ''; # description
+ $co_prompt = ($color) ? 'bold green' : ''; # prompt
+ $co_unused = ($color) ? 'on_green' : 'reverse'; # unused</code></pre>
+
+<p>To exclude only the equals we could use:</p>
+
+<pre><code> # perltidy -vxl='='
+ $co_description = ($color) ? 'bold cyan' : ''; # description
+ $co_prompt = ($color) ? 'bold green' : ''; # prompt
+ $co_unused = ($color) ? 'on_green' : 'reverse'; # unused</code></pre>
+
+<p>Notice in this last example that although only the equals alignment was excluded, the ternary alignments were also lost. This happens because the vertical aligner sweeps from left-to-right and usually stops if an important alignment cannot be made for some reason.</p>
+
+<p>But also notice that side comments remain aligned because their alignment is controlled separately with the parameter <b>--valign-side_comments</b> described above.</p>
+
</dd>
</dl>
<h1 id="VERSION">VERSION</h1>
-<p>This man page documents perltidy version 20211029.04</p>
+<p>This man page documents perltidy version 20211029.05</p>
<h1 id="BUG-REPORTS">BUG REPORTS</h1>
# Release version must be bumped, and it is probably past time for a
# release anyway.
- $VERSION = '20211029.04';
+ $VERSION = '20211029.05';
}
sub DESTROY {
=head1 VERSION
-This man page documents Perl::Tidy version 20211029.04
+This man page documents Perl::Tidy version 20211029.05
=head1 LICENSE
package Perl::Tidy::Debugger;
use strict;
use warnings;
-our $VERSION = '20211029.04';
+our $VERSION = '20211029.05';
sub new {
package Perl::Tidy::DevNull;
use strict;
use warnings;
-our $VERSION = '20211029.04';
+our $VERSION = '20211029.05';
sub new { my $self = shift; return bless {}, $self }
sub print { return }
sub close { return }
package Perl::Tidy::Diagnostics;
use strict;
use warnings;
-our $VERSION = '20211029.04';
+our $VERSION = '20211029.05';
sub AUTOLOAD {
package Perl::Tidy::FileWriter;
use strict;
use warnings;
-our $VERSION = '20211029.04';
+our $VERSION = '20211029.05';
use constant DEVEL_MODE => 0;
{ #<<< A non-indenting brace to contain all lexical variables
use Carp;
-our $VERSION = '20211029.04';
+our $VERSION = '20211029.05';
# 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 = '20211029.04';
+our $VERSION = '20211029.05';
use File::Basename;
use strict;
use warnings;
use Carp;
-our $VERSION = '20211029.04';
+our $VERSION = '20211029.05';
sub AUTOLOAD {
use strict;
use warnings;
use Carp;
-our $VERSION = '20211029.04';
+our $VERSION = '20211029.05';
sub AUTOLOAD {
package Perl::Tidy::IndentationItem;
use strict;
use warnings;
-our $VERSION = '20211029.04';
+our $VERSION = '20211029.05';
BEGIN {
package Perl::Tidy::LineBuffer;
use strict;
use warnings;
-our $VERSION = '20211029.04';
+our $VERSION = '20211029.05';
sub AUTOLOAD {
package Perl::Tidy::LineSink;
use strict;
use warnings;
-our $VERSION = '20211029.04';
+our $VERSION = '20211029.05';
sub AUTOLOAD {
package Perl::Tidy::LineSource;
use strict;
use warnings;
-our $VERSION = '20211029.04';
+our $VERSION = '20211029.05';
sub AUTOLOAD {
package Perl::Tidy::Logger;
use strict;
use warnings;
-our $VERSION = '20211029.04';
+our $VERSION = '20211029.05';
sub AUTOLOAD {
package Perl::Tidy::Tokenizer;
use strict;
use warnings;
-our $VERSION = '20211029.04';
+our $VERSION = '20211029.05';
# this can be turned on for extra checking during development
use constant DEVEL_MODE => 0;
use strict;
use warnings;
use Carp;
-our $VERSION = '20211029.04';
+our $VERSION = '20211029.05';
use Perl::Tidy::VerticalAligner::Alignment;
use Perl::Tidy::VerticalAligner::Line;
{ #<<< A non-indenting brace
-our $VERSION = '20211029.04';
+our $VERSION = '20211029.05';
BEGIN {
package Perl::Tidy::VerticalAligner::Line;
use strict;
use warnings;
-our $VERSION = '20211029.04';
+our $VERSION = '20211029.05';
BEGIN {
projects / perltidy.git / commitdiff