From: Steve Hancock Date: Tue, 19 Dec 2023 15:58:12 +0000 (-0800) Subject: update docs X-Git-Tag: 20230912.08~8 X-Git-Url: https://git.donarmstrong.com/?a=commitdiff_plain;h=c1457df87f8052711e022865ce4a72bacb75d3df;p=perltidy.git update docs --- diff --git a/bin/perltidy b/bin/perltidy index b8b51e25..b8778fbf 100755 --- a/bin/perltidy +++ b/bin/perltidy @@ -5539,22 +5539,22 @@ of the letters, B, B, B

, and B as follows: =item B These are variables which are re-declared in the scope of a variable with the -identical name. This can be confusing and lead to errors being introduced -in future program modifications. +identical name. This can be confusing. This is similar to the B +policy B =item 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 and can be avoided by altering one of the variable names. +confusing. =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 only occur if -there are multiple packages in a file. It might be avoided by enclosing such -variables in a bare block to limit their scope. +in subroutines of a different package in the same file. This check is limited +to packages which are not enclosed in block braces in order skip some common +use cases. =item B @@ -5582,17 +5582,18 @@ will process F normally but issue a warning if either of the issues 's' or 'p', described above, are encountered. A limitation is that warnings may not be requested for unused variables, type -'u'. The reason is that this would produce many needless warnings, especially -when perltidy is run on small snippets of code from within an editor. +'u'. The main reason is that this would produce many needless warnings, +especially when perltidy is run on small snippets of code from within an +editor. -All possible variable warnings may be requested with B<-wv=rsp> or simply +All possible variable warnings may be requested with B<-wvt=rsp> or simply B<-wvt=1> or B<-wvt='*'>. The default is not to do these checks, and it can also be indicated with B<-wvt=0>. A companion flag, B<--warn-variable-exclusion-list=string>, or B<-wvxl=string>, can be used to skip warning checks for a list of variables. For example, - perltidy -wv=1 -wvxl='$self $class' somefile.pl + perltidy -wvt=1 -wvxl='$self $class' somefile.pl will skip all warnings for variables C<$self> and C<$class>. diff --git a/local-docs/tutorial.pod b/local-docs/tutorial.pod index c5297a3b..b8c89a18 100644 --- a/local-docs/tutorial.pod +++ b/local-docs/tutorial.pod @@ -395,39 +395,6 @@ this line: This kind of error can otherwise be hard to find. -=head2 The Log File - -One last topic that needs to be touched upon concerns the F<.LOG> file. -This is where perltidy records messages that are not normally of any -interest, but which just might occasionally be useful. This file is not -saved, though, unless perltidy detects that it has made a mistake or you -ask for it to be saved. - -There are a couple of ways to ask perltidy to save a log file. To -create a relatively sparse log file, use - - perltidy -log testfile.pl - -and for a verbose log file, use - - perltidy -g testfile.pl - -The difference is that the first form only saves detailed information at -least every 50th line, while the second form saves detailed information -about every line. - -So returning to our example, lets force perltidy to save a -verbose log file by issuing the following command - - perltidy -g testfile.pl - -You will find that a file named F has been -created in your directory. - -If you open this file, you will see that it is a text file with a -combination of warning messages and informative messages. All you need -to know for now is that it exists; someday it may be useful. - =head2 Using Perltidy as a Filter on Selected Text from an Editor Most programmer's editors allow a selected group of lines to be passed @@ -484,6 +451,27 @@ the bottom (or even midstream!). You probably cannot control this, and perltidy can't, but you need to know where to look when an actual error is detected. +=head2 Finding Unused Variables + +To get a list of unused, reused, and certain other lexical variables of +interest in a program named F you can use + + perltidy -duv testfile.pl + +where -duv is short for --dump-unusual-variables. The information will be +dumped to the standard output and perltidy will exit without formatting the +file. The lines of output identify four types of issues, namely + + u: unused variables + r: reused variable name in same scope + s: sigil change but reused bareword, such as %file and $file + p: package-crossing variables: a variable with scope in multiple packages + +These issues, although not errors, can be worth reviewing, especially for new +code. Other parameters which can be useful when reviewing code are +B<--warn-missing-else> and B<--dump-block-summary>. The manual has further +information. + =head2 Writing an HTML File Perltidy can switch between two different output modes. We have been