# Perltidy Change Log
-## 2024 02 02.03
+## 2024 02 02.04
- Add options --dump-mismatched-args (or -dma) and
--warn-mismatched-arg-types=s (or -wmat=s). These options look
It takes a string parameter which is 1 or '*' to activate all checks.
It may be customized with two additional parameters if necessary to
avoid needless warnings, --warn-mismatched-arg-exclusion-list=s and
- --warn-mismatched-arg-count-cutoff=n. These are explained in the manual.
+ --warn-mismatched-arg-undercount-cutoff=n. These are explained in the manual.
- Add option --valign-wide-equals, or -vwe, for issue git #135.
Setting this parameter causes the following assignment operators
=head1 VERSION
-This man page documents perltidy version 20240202.03
+This man page documents perltidy version 20240202.04
=head1 BUG REPORTS
<h1>Perltidy Change Log</h1>
-<h2>2024 02 02.03</h2>
+<h2>2024 02 02.04</h2>
-<pre><code>- Add option --valign-wide-equals, or -vwe, for issue git #135.
+<pre><code>- Add options --dump-mismatched-args (or -dma) and
+ --warn-mismatched-arg-types=s (or -wmat=s). These options look
+ for and report instances where the number of args expected by a
+ sub appear to differ from the number passed to the sub. The -dump
+ version writes the results for a single file to standard output
+ and exits:
+
+ perltidy -dma somefile.pl >results.txt
+
+ The -warn version formats as normal but reports any issues as warnings in
+ the error file:
+
+ perltidy -wmat=1 somefile.pl
+
+ It takes a string parameter which is 1 or '*' to activate all checks.
+ It may be customized with two additional parameters if necessary to
+ avoid needless warnings, --warn-mismatched-arg-exclusion-list=s and
+ --warn-mismatched-arg-undercount-cutoff=n. These are explained in the manual.
+
+- Add option --valign-wide-equals, or -vwe, for issue git #135.
Setting this parameter causes the following assignment operators
= **= += *= &= <<= &&= -= /= |= >>= ||= //= .= %= ^= x=
$str .= $rfields->[$j];
$str_len += $rfield_lengths->[$j];
- This option currently is off by default to avoid changing existing formatting.
+ This option currently is off by default to avoid changing existing
+ formatting.
+
+- Previously, a line break was made before a short concatenated terminal
+ quoted string, such as "\n", if the previous line had a greater
+ starting indentation. The break is now placed after the short quote.
+ This keeps code a little more compact. For example:
+
+# old rule: break before "\n" here because '$name' has more indentation:
+my $html = $this->SUPER::genObject( $query, $bindNode, $field . ":$var",
+ $name, "remove", "UNCHECKED" )
+ . "\n";
+
+# new rule: break after a short terminal quote like "\n" for compactness;
+my $html = $this->SUPER::genObject( $query, $bindNode, $field . ":$var",
+ $name, "remove", "UNCHECKED" ) . "\n";
- In the option --dump-block-summary, the number of sub arguments indicated
for each sub now includes any leading object variable passed with
- fixed issue git#13, needless trailing whitespace in error message
- fixed issue git#9: if the -ce (--cuddled-else) flag is used,
- do not try to form new one line blocks for a block type
+ do not try to form new one line blocks for a block type
specified with -cbl, particularly map, sort, grep
- iteration speedup for unchanged code. Previously, when iterations were
<h1 id="VERSION">VERSION</h1>
-<p>This man page documents Perl::Tidy version 20240202.03</p>
+<p>This man page documents Perl::Tidy version 20240202.04</p>
<h1 id="LICENSE">LICENSE</h1>
[ 10.9, 10.9, 11 ],
);</code></pre>
-<p>The current default alignment is strict left justification:</p>
+<p>The default is <b>-vsn</b>. This can be turned off to get is strict left justification:</p>
<pre><code> # perltidy -nvsn
my @correct = (
[ 10.9, 10.9, 11 ],
);</code></pre>
-<p>In a future release <b>-vsn</b> will become the default.</p>
-
<p>Some points regarding <b>-vsn</b> are:</p>
<ul>
<li><p>This option is mainly limited to lists of comma-separated numbers. For multiline lists of numbers, having trailing commas can sometimes improve the results. If missing, perltidy can add them for example with parameters <b>-wtc=b -atc</b>. See <a href="#Adding-and-Deleting-Commas">"Adding and Deleting Commas"</a>.</p>
</li>
-<li><p>This option has a control parameter <b>--valign-signed-number-limit=N</b>, or <b>-vsnl=N</b>. This value controls formatting of very long columns of numbers and should not normally need to be changed. To see its purpose, consider a very long column of just unsigned numbers, say 1000 lines. If we add a single negative number, it is undesirable to move all of the other numbers over by one space. This would create many lines of file differences but not really improve the appearance when a local section of the table was viewed. The number <b>N</b> avoids this problem by not adding extra indentation to a run of more than <b>N</b> lines of unsigned numbers. The default value, <b>N=20</b>, is set to be a number of lines for which the ends of a long column of unsigned numbers are not normally both in view.</p>
+<li><p>This option has a control parameter <b>--valign-signed-number-limit=N</b>, or <b>-vsnl=N</b>. This value controls formatting of very long columns of numbers and should not normally need to be changed. To see its purpose, consider a very long column of just unsigned numbers, say 1000 lines. If we add a single negative number, it is undesirable to move all of the other numbers over by one space. This could create many lines of file differences but not really improve the appearance when a local section of the table was viewed. The number <b>N</b> avoids this problem by not adding extra indentation to a run of more than <b>N</b> lines of unsigned numbers. The default value, <b>N=20</b>, is set to be a number of lines for which the ends of a long column of unsigned numbers are not normally both in view.</p>
</li>
</ul>
<p>Otherwise, the <code>||</code> will operate on <code>$infile</code> rather than the return value of <code>open</code>.</p>
+</dd>
+<dt id="Use---dump-mismatched-args-to-find-function-calls-with-args-not-matching-sub-declarations"><b>Use --dump-mismatched-args to find function calls with args not matching sub declarations</b></dt>
+<dd>
+
+<p>The parameter <b>--dump-mismatched-args</b>, or <b>-dma</b>, causes perltidy to examine the definitions of subroutines in a file, and calls to those subs, and report any apparent differences. Like all <b>--dump</b> commands, it writes its report to standard output and exits immediately. For example</p>
+
+<pre><code> perltidy -dma somefile.pl >results.txt</code></pre>
+
+<p>Two types of issues are reported, types <b>a</b> and <b>c</b>:</p>
+
+<dl>
+
+<dt id="a:-calls-made-to-a-sub-both-with-and-without-the-arrow-operator"><b>a:</b> calls made to a sub both with and without the <b>arrow</b> operator</dt>
+<dd>
+
+<p>For example the following two lines would be reported as a mismatch:</p>
+
+<pre><code> Fault();</code></pre>
+
+<p>and</p>
+
+<pre><code> $self->Fault();</code></pre>
+
+<p>This may or may not be an error, but it is worth checking.</p>
+
+</dd>
+<dt id="c:-the-count-of-call-args-differs-from-a-sub-definition"><b>c:</b> the <b>count</b> of call args differs from a sub definition</dt>
+<dd>
+
+<p>If a sub appears to expect a specific number of args, and is called with more or less than this number, then a mismatch will be reported. For example</p>
+
+<pre><code> sub do_something {
+ my $self=shift;
+ my ($v1,$v2)=@_;
+ ...
+ }
+
+ $self->do_something(43);</code></pre>
+
+<p>In this case, the sub is expecting a total of three args (<code>$self</code>, <code>$v1</code>, and <code>$v2</code>) but only receives two (<code>$self</code> and <code>42</code>), so a mismatch is reported. This is not necessarily an error because the sub may allow for this possibility. This sometimes happens as a code evolves to have new functionality. But it can be a source of confusion, and it could be an error, so it is worth checking.</p>
+
+</dd>
+</dl>
+
+<p><b>Some Limitations:</b></p>
+
+<ul>
+
+<li><p>Only subs for which the call args are unpacked in an orderly manner at the beginning of the sub from <code>@_</code>, directly and/or with <code>shift</code> operations, are checked. Subs for which this does not appear to be the case are skipped.</p>
+
+</li>
+<li><p>Subs which appear to have no args are not checked. This is necessary to avoid false warnings when a sub actually uses args in a complex way.</p>
+
+</li>
+<li><p>Only calls which appear to be to subs defined within the file are checked.</p>
+
+</li>
+<li><p>Sub calls made without parentheses around the args are not checked.</p>
+
+</li>
+<li><p>Anonymous subs and lexical subs (introduced with 'my') are not currently checked.</p>
+
+</li>
+</ul>
+
+</dd>
+<dt id="Use---warn-mismatched-arg-types-s-to-produce-a-warning-for-function-calls-with-args-not-matching-sub-declarations"><b>Use --warn-mismatched-arg-types=s to produce a warning for function calls with args not matching sub declarations</b></dt>
+<dd>
+
+<p>The parameter <b>--warn-mismatched-arg-types=s</b>, or <b>-wmat=s</b>, can be used to produce a warning message when perltidy formats a file and certain of the above mismatchs is detected during formatting. Both checks may be requested with <b>-wmat='*'</b> or <b>-wmat=1</b>.</p>
+
+<p>The default is not to do any of these checks, which can also be indicated with <b>-wmat=0</b>.</p>
+
+<p>To restrict the check to a specific warning type, set the string equal to the letter of that warning, either <b>a</b> or <b>c</b>. For example</p>
+
+<pre><code> perltidy -wmat='c' somefile.pl</code></pre>
+
+<p>will format <i>somefile.pl</i> and report any call arg count mismatches found but will skip checking for arrow-type mismatches.</p>
+
+<p>A companion control parameter <b>--warn-mismatched-arg-exclusion-list</b>, or <b>-wmaxl=string</b>, can be given to skip the warning checks for a list of subroutine names.</p>
+
+<p>Another control parameter <b>--warn-mismatched-arg-undercount-cutoff=n</b>, or <b>-wmauc=n</b>, can be used to avoid undercount warnings when the number of args expected is <b>n</b> or less. Please note that this number <b>n</b> is the number of args from the point of view of the sub definition, so an object like <code>$self</code> passed with an arrow operator counts as one arg.</p>
+
+<p>The default value is <b>n=4</b>. This has been found to allow most programs to pass without warnings, but it should be reduced if possible for better error checking. The minimum possible value of <b>n</b> for a program can be determined by running with -wmauc=0, or by running the -dump version. The output shows, for each mismatch, the number of args expected by a sub plus the range of the number of args actually passed to it.</p>
+
+<p>For example</p>
+
+<pre><code> perltidy -wmat='*' -wmaxl='new' -wmauc=2 somefile.pl</code></pre>
+
+<p>means format <i>somefile.pl</i> as usual and check for all mismatch types. But skip checking for any sub named <code>new</code>, and only warn of undercounts for subs expecting more than 2 args.</p>
+
</dd>
</dl>
<h1 id="VERSION">VERSION</h1>
-<p>This man page documents perltidy version 20240202.03</p>
+<p>This man page documents perltidy version 20240202.04</p>
<h1 id="BUG-REPORTS">BUG REPORTS</h1>
# then the Release version must be bumped, and it is probably past time for
# a release anyway.
- $VERSION = '20240202.03';
+ $VERSION = '20240202.04';
} ## end BEGIN
sub DESTROY {
=head1 VERSION
-This man page documents Perl::Tidy version 20240202.03
+This man page documents Perl::Tidy version 20240202.04
=head1 LICENSE
use strict;
use warnings;
use English qw( -no_match_vars );
-our $VERSION = '20240202.03';
+our $VERSION = '20240202.04';
use constant EMPTY_STRING => q{};
use constant SPACE => q{ };
use strict;
use warnings;
use English qw( -no_match_vars );
-our $VERSION = '20240202.03';
+our $VERSION = '20240202.04';
use constant EMPTY_STRING => q{};
package Perl::Tidy::FileWriter;
use strict;
use warnings;
-our $VERSION = '20240202.03';
+our $VERSION = '20240202.04';
use constant DEVEL_MODE => 0;
use constant EMPTY_STRING => q{};
use Carp;
use English qw( -no_match_vars );
use List::Util qw( min max first ); # min, max first are in Perl 5.8
-our $VERSION = '20240202.03';
+our $VERSION = '20240202.04';
# 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 = '20240202.03';
+our $VERSION = '20240202.04';
use Carp;
use English qw( -no_match_vars );
use strict;
use warnings;
use Carp;
-our $VERSION = '20240202.03';
+our $VERSION = '20240202.04';
use constant DEVEL_MODE => 0;
use constant EMPTY_STRING => q{};
use strict;
use warnings;
use Carp;
-our $VERSION = '20240202.03';
+our $VERSION = '20240202.04';
use constant DEVEL_MODE => 0;
use strict;
use warnings;
-our $VERSION = '20240202.03';
+our $VERSION = '20240202.04';
BEGIN {
package Perl::Tidy::Logger;
use strict;
use warnings;
-our $VERSION = '20240202.03';
+our $VERSION = '20240202.04';
use Carp;
use English qw( -no_match_vars );
use warnings;
use English qw( -no_match_vars );
-our $VERSION = '20240202.03';
+our $VERSION = '20240202.04';
use Carp;
{ #<<< A non-indenting brace to contain all lexical variables
-our $VERSION = '20240202.03';
+our $VERSION = '20240202.04';
use English qw( -no_match_vars );
use Scalar::Util 'refaddr';
use Perl::Tidy::VerticalAligner::Alignment;
use strict;
use warnings;
-our $VERSION = '20240202.03';
+our $VERSION = '20240202.04';
sub new {
my ( $class, $rarg ) = @_;
use strict;
use warnings;
-our $VERSION = '20240202.03';
+our $VERSION = '20240202.04';
use English qw( -no_match_vars );
sub AUTOLOAD {
projects / perltidy.git / commitdiff