## 2024 05 11.04
+ - Add options --dump-mismatched-returns (or -dmr) and
+ --warn-mismatched-returns (or -wmr). These options report function
+ calls where the number of requested values may disagree with sub
+ return statements. The -dump version writes the results for a single
+ file to standard output and exits:
+
+ perltidy -dmr somefile.pl >results.txt
+
+ The -warn version formats as normal but reports any issues as warnings in
+ the error file:
+
+ perltidy -wmr somefile.pl
+
+ The -warn version may be customized with the following additional
+ parameters if necessary to avoid needless warnings:
+
+ --warn-mismatched-return-types=s (or -wmrt=s),
+ --warn-mismatched-return-exclusion-list=s (or -wmrxl=s)
+
+ These are explained in the manual.
+
- Updates for issue git #151:
(1) --warn-variable-types=u is now okay if it is on the command line
with a named file.
unknown. Otherwise, a dash will be removed to make the line valid.
- Parameters --dump-mismatched-args (or -dma) and
- --warn-mismatched-arg (or -wma) have been updated to catch more
+ --warn-mismatched-args (or -wma) have been updated to catch more
arg count issues.
- Fix issue git #143, extend -add-trailing-commas to apply to a list
off by default, but it could become the default in a future version.
- Add options --dump-mismatched-args (or -dma) and
- --warn-mismatched-arg (or -wma). These options look
+ --warn-mismatched-args (or -wma). 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
B<--warn-mismatched-arg-exclusion-list>, or B<-wmaxl=string>, can be given to
skip the warning checks for a list of subroutine names, entered as a quoted
string of space- or comma-separated names. All subs with those names will be
-skipped, regardless of package.
+skipped, regardless of package. A leading and/or trailing B<*> on a name may
+be used to indicate a partial string match.
=item *
B<--warn-mismatched-arg-undercount-cutoff=n>, or B<-wmauc=n>, can be used to
=back
+=item B<Use --dump-mismatched-returns> to find function calls where the number of requested values may disagree with sub return statements
+
+The parameter B<--dump-mismatched-returns>, or B<-dmr>, examines the return
+side of sub call statements. Like all B<--dump> commands, it writes its report
+to standard output and exits immediately. For example
+
+ perltidy -dmr somefile.pl >results.txt
+
+Three types of issues are reported:
+
+=over 4
+
+=item B<x:> calls requesting values from a sub without a return statement.
+
+=item B<o:> (B<overwant>): the number of values wanted by the caller exceeds the number returned by the sub.
+
+=item B<u:> (B<underwant>): the number of values wanted by the caller is less than the number returned by the sub.
+
+=back
+
+The three issue types are illustrated with the following code
+
+ sub old_school {
+ ...
+ ( $xc, $yc ); # 2 values, no return statement
+ }
+
+ sub new_school {
+ ...
+ return ( $xc, $yc ); # 2 values
+ }
+
+ ( $x_old, $y_old ) = old_school($point); # type 'x' (no return)
+ ( $x_new, $y_new, $z_new ) = new_school($point); # type 'o' (want 3 > 2)
+ $mid = new_school($point); # type 'i' (want 1 < 2)
+
+Issues are only reported when the return transaction involves two or more list
+elements, and only when a specific number can be determined. The reported
+issues are not necessarily errors, but they might be, or might indicate
+confusing code.
+
+=item B<Use --warn-mismatched-returns> to issue warnings when the number of requested values may disagree with sub return statements
+
+This is similar to the B<-dump> parameter described above except that any
+mismatches are reported in the error file and otherwise formatting continues
+normally. The basic usage is
+
+ perltidy -wmr somefile.pl
+
+The following companion controls are available to avoid unwanted error messages:
+
+=over 4
+
+=item *
+B<--warn-mismatched-return-types=s>, or B<-wmrt=s>, can be used to limit
+checks.
+
+To restrict the checking, set the string equal to the letter(s) of that warning,
+any B<x>, B<o>, or B<u>. For example
+
+ perltidy -wmrt='x o' somefile.pl
+
+will format F<somefile.pl> and report issue types B<x> and B<o> but not type
+B<u>. All checks may be requested with B<-wmrt='*'> or B<-wmrt=1>. This is
+the default.
+
+=item *
+B<--warn-mismatched-return-exclusion-list>, or B<-wmrxl=string>, can be given to
+skip the warning checks for a list of subroutine names, entered as a quoted
+string of space- or comma-separated names. A leading and/or trailing B<*> may
+be used to indicate a partial string match.
+
+=back
+
=head2 B<Working with MakeMaker, AutoLoader and SelfLoader>
The first $VERSION line of a file which might be eval'd by MakeMaker
my ($self) = @_;
- # The current possible checks are indicated by these letters:
+ # This routine looks for issues for these parameters:
+ # --dump-mismatched-args
+ # --warn-mismatched-args
+ # --dump-mismatched-returns
+ # --warn-mismatched-returns
+
+ # It returns a hash of values with any warnings found
+
+ my $rLL = $self->[_rLL_];
+
+ # The mismatched-args checks are indicated by these letters:
# a = both method and non-method calls to a sub
# - even for two subs in a different package
# o = overcount: call arg counts exceed number expected by a sub
# u = undercount: call arg counts less than number expected by a sub
# - except if expecting N or less (N=4 by default)
# i = indeterminate: expected number of args was not determined
-
- my $rLL = $self->[_rLL_];
-
- # initialize for dump mode
my %do_mismatched_call_type = ( 'a' => 1, 'o' => 1, 'u' => 1, 'i' => 1 );
my $mismatched_arg_undercount_cutoff = 0;
my $mismatched_arg_overcount_cutoff = 0;
my $ris_mismatched_call_excluded_name = {};
- my %do_mismatched_return_type = ( 'o' => 1, 'u' => 1, 'x' => 1 );
+ # The mismatched-returns checks are indicated by these letters:
+ # x = no return statement
+ # o = 'overwant', caller wants more values than available
+ # u = 'underwant', caller wants fewer values than available
+ my %do_mismatched_return_type = ( 'x' => 1, 'o' => 1, 'u' => 1 );
my $ris_mismatched_return_excluded_name = {};
+ # initialize a cache used for efficiency
$self->initialize_self_call_cache();
my $is_dump =
#----------------------------------
# Preliminary min and max call args
#----------------------------------
-
# This is preliminary because some of the calls will eventually be
# rejected if they appear to be to external objects. This info is
# needed to optimize the sub arg search in the case of zero args.
# compare caller/sub return counts if posible
#--------------------------------------------
+ # -1=>no, 0=>either way, 1=>yes
my $lhs_ok =
!$return_count_wanted ? -1
: $return_count_wanted < 2 ? 0
projects / perltidy.git / commitdiff