From: Steve Hancock Date: Mon, 8 Jul 2024 15:49:37 +0000 (-0700) Subject: update docs for -wmr -dmr X-Git-Tag: 20240511.05~4 X-Git-Url: https://git.donarmstrong.com/?a=commitdiff_plain;h=920988d74668ce98937e467c05f2d1e088058da5;p=perltidy.git update docs for -wmr -dmr --- diff --git a/CHANGES.md b/CHANGES.md index 5555ee03..a0bb50c8 100644 --- a/CHANGES.md +++ b/CHANGES.md @@ -2,6 +2,27 @@ ## 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. @@ -17,7 +38,7 @@ 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 @@ -114,7 +135,7 @@ 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 diff --git a/bin/perltidy b/bin/perltidy index 6b96fd35..e30ca0c8 100755 --- a/bin/perltidy +++ b/bin/perltidy @@ -6215,7 +6215,8 @@ will format F and report any arrow-type mismatches and overcount mi 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 @@ -6249,6 +6250,80 @@ and only warn of undercounts for subs expecting more than 2 args. =back +=item B 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 calls requesting values from a sub without a return statement. + +=item B (B): the number of values wanted by the caller exceeds the number returned by the sub. + +=item B (B): 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 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, B, or B. For example + + perltidy -wmrt='x o' somefile.pl + +will format F and report issue types B and B but not type +B. 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 The first $VERSION line of a file which might be eval'd by MakeMaker diff --git a/lib/Perl/Tidy/Formatter.pm b/lib/Perl/Tidy/Formatter.pm index ab76aa64..4eed7499 100644 --- a/lib/Perl/Tidy/Formatter.pm +++ b/lib/Perl/Tidy/Formatter.pm @@ -15425,25 +15425,36 @@ sub cross_check_call_args { 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 = @@ -15490,7 +15501,6 @@ sub cross_check_call_args { #---------------------------------- # 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. @@ -15871,6 +15881,7 @@ sub cross_check_call_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