From: Steve Hancock Date: Sun, 14 Jan 2024 23:15:28 +0000 (-0800) Subject: update docs X-Git-Tag: 20230912.13~12 X-Git-Url: https://git.donarmstrong.com/?a=commitdiff_plain;h=73a3168958abc05cde2e8b9399ffd60f5b724a3c;p=perltidy.git update docs --- diff --git a/bin/perltidy b/bin/perltidy index f320a302..28e5854a 100755 --- a/bin/perltidy +++ b/bin/perltidy @@ -5460,7 +5460,7 @@ perltidy development. =head2 Analyzing Code Perltidy reports any obvious issues that are found during formatting, such as -unbalanced braces. But Several parameters are available for making certain +unbalanced braces. But several parameters are available for making certain additional checks for issues which might be of interest to a programmer. =over 4 @@ -5606,7 +5606,8 @@ in the output with one of the letters, B, B, B

, and B as follows: These are variables which are re-declared in the scope of a variable with the identical name. This can be confusing (perhaps not when the code is first -written, but possibly later during maintenance work). Note that this is +written, but possibly later during maintenance work). This issue can be +avoided by renaming one of the conflicting variables. Note that this is similar to the B policy B. =item B @@ -5614,35 +5615,49 @@ similar to the B policy B. These are variables which have the same bareword name but a different sigil (B<$>, B<@>, or B<%>) as another variable in the same scope. For example, this occurs if variables B<$data> and B<%data> share the same scope. This can be -confusing. +confusing and can be avoided by renaming one of the variables. =item B These are lexical variables which are declared in one package and still visible -in subroutines of a different package in the same file. This can be confusing. -This check is limited to packages which are not enclosed in block braces in -order skip temporary package changes. +in subroutines of a different package in the same file. This can be confusing, +and it might cause the program to run differently, or fail, if the the packages +were ever split into separate files. This issue can usually be avoided by +placing code in block braces of some type. For example, this issue is often +found in test code, and might be fixed by using the structure + + main(); + + sub main { #<<< + ## old main code goes here + } + +The B comment C<#<<<> is not required but will keep the +indentation of the old code unchanged. It should be noted that this check is +limited to packages which are not enclosed in block braces in order skip +temporary package changes. =item B These are variables which are declared with a C and not referenced again within their scope. Calling them B is convenient but not really -accurate. There are many reasons for having such variables. For example, they -might occur in a list of values provided by another routine or data structure, -and therefor must be listed, even though they might not be referenced again. Or -they might be defined for possible future program development, clarity or -debugging. But sometimes they can occur due to being orphaned by a coding -change, due to a misspelling, or by having an unintentional preceding C. -So it is worth reviewing them, especially for new code. Here is an -example of an unused variable in a script located with this method: +accurate; this is a "gray area" for a program. There are many reasons for +having such variables. For example, they might occur in a list of values +provided by another routine or data structure, and therefor must be listed, +even though they might not be referenced again. Or they might be defined for +possible future program development, clarity or debugging. B sometimes +they can occur due to being orphaned by a coding change, due to a misspelling, +or by having an unintentional preceding C. So it is worth reviewing them, +especially for new code. Here is an example of an unused variable in a script +located with this method: BEGIN { my $string = "" } ... $string .= "ok"; -This looks nice, but the scope of the C declaration is limited to the -surrounding braces, so it is not the same variable as the other C<$string> -and is therefore reported as unused. This problem would have +This looks nice at first glance, but the scope of the C declaration is +limited to the surrounding braces, so it is not the same variable as the other +C<$string> and must therefore be reported as unused. This problem would have also been caught by perl if the author had used C. =back diff --git a/local-docs/tutorial.pod b/local-docs/tutorial.pod index 27166576..c9747d3e 100644 --- a/local-docs/tutorial.pod +++ b/local-docs/tutorial.pod @@ -459,10 +459,10 @@ tokens which successive lines have in common, such as the B<=> here: my $debug_file = $self->{_debug_file}; my $is_encoded_data = $self->{_is_encoded_data}; -Vertical alignment is automatic, but stops at blank lines. So a blank line can -be inserted to stop an unwanted alignment. So, for example, we can -can insert a blank line to break the alignment in the above example -like this: +Vertical alignment is automatic unless it has been deactivated by one of its +controls, but it always stops and tries to restart at blank lines. So a blank +line can be inserted to stop an unwanted alignment. So, for example, we can +can insert a blank line to break the alignment in the above example like this: my $self = shift; @@ -482,6 +482,14 @@ lines to be skipped with special comments like this: 1, 4, 6, 4, 1,); #>>> +A related comment control is B<--code-skipping>, indicated with '#<. and +'#>>V>', which simply passes lines of code to the output without tokenization. +This is useful for some extended syntaxes. Another is +B<--non-indenting-braces>, indicated by placing a side comment '#<<<' following +a block brace, which prevents code within the marked braces from getting an +extra level indentation. This is useful if we want to put braces around code +and want to minimize the changes in formatting. + =head2 Finding Unused Variables Perltidy has several parameters which can assist in locating problems in code. diff --git a/perltidyrc b/perltidyrc index 4c3fb243..36421a91 100644 --- a/perltidyrc +++ b/perltidyrc @@ -8,9 +8,16 @@ # warnings --warning-output + +# all if-elsif chains must end in an else block --warn-missing-else + +# warn if any of the 'unusual' variables are seen --warn-variable-types='*' +# user define subs must have args in parens +--want-call-parens='&' + # add comment with sub name to closing sub brace --closing-side-comments --closing-side-comment-list='sub' @@ -18,3 +25,6 @@ # add trailing commas to last item of a bare hash list --want-trailing-commas='h' --add-trailing-commas + +# this should eventually become the default +--delete-repeated-commas