From b2511ca040025d7309778561b8e7c368781ad59f Mon Sep 17 00:00:00 2001 From: Steve Hancock Date: Tue, 5 Sep 2023 07:54:25 -0700 Subject: [PATCH] bump version to .04 --- CHANGES.md | 2 +- bin/perltidy | 29 +++--- docs/ChangeLog.html | 60 +++++++++++ docs/Tidy.html | 2 +- docs/perltidy.html | 112 +++++++++++++++++++-- lib/Perl/Tidy.pm | 2 +- lib/Perl/Tidy.pod | 2 +- lib/Perl/Tidy/Debugger.pm | 2 +- lib/Perl/Tidy/Diagnostics.pm | 2 +- lib/Perl/Tidy/FileWriter.pm | 2 +- lib/Perl/Tidy/Formatter.pm | 2 +- lib/Perl/Tidy/HtmlWriter.pm | 2 +- lib/Perl/Tidy/IOScalar.pm | 2 +- lib/Perl/Tidy/IOScalarArray.pm | 2 +- lib/Perl/Tidy/IndentationItem.pm | 2 +- lib/Perl/Tidy/Logger.pm | 2 +- lib/Perl/Tidy/Tokenizer.pm | 2 +- lib/Perl/Tidy/VerticalAligner.pm | 2 +- lib/Perl/Tidy/VerticalAligner/Alignment.pm | 2 +- lib/Perl/Tidy/VerticalAligner/Line.pm | 2 +- 20 files changed, 198 insertions(+), 37 deletions(-) diff --git a/CHANGES.md b/CHANGES.md index 1e66f82d..4f516031 100644 --- a/CHANGES.md +++ b/CHANGES.md @@ -1,6 +1,6 @@ # Perltidy Change Log -## 2023 07 01.03 +## 2023 07 01.04 - Add parameters -wme, or --warn-missing-else, and -ame, or --add-missing else. The parameter -wme tells perltidy to issue diff --git a/bin/perltidy b/bin/perltidy index fd188ed0..606e7d82 100755 --- a/bin/perltidy +++ b/bin/perltidy @@ -3861,18 +3861,17 @@ commas are removed. =head2 Missing Else Blocks -One defensive programming technique is to require every B chain be -terminated with an B block, even if it is not strictly required, +One defensive programming technique is to require that every B +chain be terminated with an B block, even though it is not required, to insure that there are no holes in the logic. -For example, consider the following snippet from an actual program: +For example, consider the following snippet: if ( $level == 3 ) { $val = $global{'section'} } elsif ( $level == 2 ) { $val = $global{'chapter'} } What if the variable B<$level> is neither 2 nor 3? Maybe the original -programmer knew that this was okay, but a new programmer might not be sure -sure. +programmer knew that this was okay, but a new programmer might be unsure. Perltidy has always written this information in its B file (search for B). But a problem is that you have to turn on the log file and @@ -3884,11 +3883,13 @@ or both. =item B<-wme>, B<--warn-missing-else> -This flag tells perltidy to issue a warning if a program is missing a terminal B block. +This flag tells perltidy to issue a warning if a program is missing a terminal B block. The default is not to issue such warnings. =item B<-ame>, B<--add-missing-else> -This flag tells perltidy to output an empty else block wherever a program is missing a terminal B block. +This flag tells perltidy to output an empty else block wherever a program is +missing a terminal B block. To get a warning when this is done you can +also set B<-wme>. The default is not to add missing else blocks. =item B<-amec=s>, B<--add-missing-else-comment=s> @@ -3900,23 +3901,24 @@ This string is an optional side comment which will be placed within a new empty For example, on the above example we get - # perltidy -ame + # perltidy -ame -wme if ( $level == 3 ) { $val = $global{'section'} } elsif ( $level == 2 ) { $val = $global{'chapter'} } else { ##FIXME - added with perltidy -ame } -The comment should be changed appropriately after the code is inspected. For -example, we might decide that it fine as is: +Any B<##FIXME> comments should be changed appropriately after the code is +inspected. For example, we might decide that it fine as is, and just leave +a note for the next programmer: if ( $level == 3 ) { $val = $global{'section'} } elsif ( $level == 2 ) { $val = $global{'chapter'} } else { - # ok - ignore other level values are safely ignored + # ok - other $level values can be safely ignored } -Or maybe it is a potential problem: +Or maybe it should never happen: if ( $level == 3 ) { $val = $global{'section'} } elsif ( $level == 2 ) { $val = $global{'chapter'} } @@ -3927,7 +3929,6 @@ Or maybe it is a potential problem: Note that this operation cannot be undone, so be careful to inspect the new code carefully. - =head2 Retaining or Ignoring Existing Line Breaks Several additional parameters are available for controlling the extent @@ -5868,7 +5869,7 @@ The perltidy binary uses the Perl::Tidy module and is installed when that module =head1 VERSION -This man page documents perltidy version 20230701.03 +This man page documents perltidy version 20230701.04 =head1 BUG REPORTS diff --git a/docs/ChangeLog.html b/docs/ChangeLog.html index 8bc3f428..2a2ecc57 100644 --- a/docs/ChangeLog.html +++ b/docs/ChangeLog.html @@ -1,5 +1,65 @@

Perltidy Change Log

+

2023 07 01.04

+ +
- Add parameters -wme, or --warn-missing-else, and -ame,
+  or --add-missing else.  The parameter -wme tells perltidy to issue
+  a warning to the error output if an if-elsif-elsif-... chain does
+  not end in an else block.  The parameter -ame tells perltidy to
+  insert an else block at the end of such a chain if there is none.
+
+  For example, given the following snippet:
+
+    if    ( $level == 3 ) { $val = $global{'section'} }
+    elsif ( $level == 2 ) { $val = $global{'chapter'} }
+
+  # perltidy -ame
+    if    ( $level == 3 ) { $val = $global{'section'} }
+    elsif ( $level == 2 ) { $val = $global{'chapter'} }
+    else {
+        ##FIXME - added with perltidy -ame
+    }
+
+  The resulting code should be carefully reviewed, and the comment should
+  be updated as appropriate.  The comment can be changed with parameter
+  -amec=s, where 's' is the comment in the else block.  The man pages
+  have more details.
+
+- The syntax of the parameter --use-feature=class, or -uf=class, which
+  new in the previous release, has been changed slightly for clarity.
+  The default behavior, which occurs if this flag is not entered, is
+  to automatically try to handle both old and new uses of the keywords
+  'class', 'method', 'field', and 'ADJUST'.
+  To force these keywords to only follow the -use feature 'class' syntax,
+  enter --use-feature=class.
+  To force perltidy to ignore the -use feature 'class' syntax, enter
+  --use-feature=noclass.
+
+- Issue git #122. Added parameter -lrt=n1:n2, or --line-range-tidy=n1:n2
+  to limit tidy operations to a limited line range.  Line numbers start
+  with 1. The man pages have details.
+
+- Some fairly rare instances of incorrect spacing have been fixed.  The
+  problem was that the tokenizer being overly conservative in marking
+  terms as possible filehandles. This cause the space after the possible
+  filehandle to be frozen to its input value in order not to introduce
+  an error in case Perl had to guess.  The problem was fixed by having the
+  tokenizer look ahead for operators which can eliminate the uncertainty.
+  To illustrate, in the following line the term ``$d`` was previouly
+  marked as a possible file handle, so no space was added after it.
+
+      print $d== 1 ? " [ON]\n" : $d ? " [$d]\n" : "\n";
+
+  In the current version, the next token is seen to be an equality, so
+  ``$d`` is marked as an ordinary identifier and normal spacing rules
+  can apply:
+
+      print $d == 1 ? " [ON]\n" : $d ? " [$d]\n" : "\n";
+
+- This version runs 7 to 10 percent faster than the previous release on
+  large files, depending on options and file type.
+
+

2023 07 01

- Issue git #121. Added parameters -xbt, or --extended-block-tightness,
diff --git a/docs/Tidy.html b/docs/Tidy.html
index b13fbac0..3a2e9e9a 100644
--- a/docs/Tidy.html
+++ b/docs/Tidy.html
@@ -399,7 +399,7 @@
 
 
VERSION

 
-
This man page documents Perl::Tidy version 20230701

+
This man page documents Perl::Tidy version 20230701.04

 
 
LICENSE

 
diff --git a/docs/perltidy.html b/docs/perltidy.html
index 1f760629..1664dcec 100644
--- a/docs/perltidy.html
+++ b/docs/perltidy.html
@@ -28,12 +28,14 @@
       
  • Whitespace Control
    • 
       
  • Comment Controls
    • 
       
  • Skipping Selected Sections of Code
    • 
+      
  • Formatting a Limited Range of Lines
    • 
       
  • Line Break Control
    • 
       
  • Controlling Breaks at Braces, Parens, and Square Brackets
    • 
       
  • Welding
    • 
       
  • Breaking Before or After Operators
    • 
       
  • Controlling List Formatting
    • 
       
  • Adding and Deleting Commas
    • 
+      
  • Missing Else Blocks
    • 
       
  • Retaining or Ignoring Existing Line Breaks
    • 
       
  • Blank Line Control
    • 
       
  • Styles
    • 
@@ -1285,7 +1287,7 @@
           && ( $a->{'title'} eq $b->{'title'} )
           && ( $a->{'href'} eq $b->{'href'} ) );
    -

    Note that this is considered to be a different operation from "vertical alignment" because space at just one line is being adjusted, whereas in "vertical alignment" the spaces at all lines are being adjusted. So it sort of a local version of vertical alignment.

    +

    Note that this is considered to be a different operation from "vertical alignment" because space at just one line is being adjusted, whereas in "vertical alignment" the spaces at all lines are being adjusted. So it is sort of a local version of vertical alignment.

    Here is an example involving a ternary operator:

    @@ -1775,6 +1777,27 @@ +

    Formatting a Limited Range of Lines

    + +

    A command --line-range-tidy=n1:n2 is available to process just a selected range of lines of an input stream with perltidy. This command is mainly of interest for programming interactive code editors. When it is used, the entire input stream is read but just the selected range of lines of the input file are processed by the perltidy tokenizer and formatter, and then the stream is reassembled for output. The selected lines need to contain a complete statement or balanced container. Otherwise, a syntax error will occur and the code will not be tidied. There are a couple of limitations on the use of this command: (1) it may not be applied to multiple files, and (2) it only applies to code tidying and not, for example, html formatting.

    + +
    + +
    -lrt=n1:n2, --line-range-tidy=n1:n2
    +
    + +

    The range of lines is specified by integers n1 and n2, where n1 is the first line number to be formatted (start counting with 1) and n2 is the last line number to be formatted. If n2 is not given, or exceeds the actual number of lines, then formatting continues to the end of the file.

    + +

    Examples:

    + +
      -line-range-tidy=43:109      # tidy lines 43 through 109
+  -line-range-tidy=' 43 : 109' # tidy lines 43 through 109 (spaces ok in quotes)
+  -line-range-tidy=1:          # tidy all lines
+  -line-range-tidy=0:90        # ERROR (n1 must be >= 1)
    + +
    +
    +

    Line Break Control

    The parameters in this and the next sections control breaks after non-blank lines of code. Blank lines are controlled separately by parameters in the section "Blank Line Control".

    @@ -2361,9 +2384,7 @@

    One limitation is that any line length limit still applies and can cause long welded sections to be broken into multiple lines.

    -

    Another limitation is that an opening symbol which delimits quoted text cannot be included in a welded pair. This is because quote delimiters are treated specially in perltidy.

    - -

    Finally, the stacking of containers defined by this flag have priority over any other container stacking flags. This is because any welding is done first.

    +

    Also, the stacking of containers defined by this flag have priority over any other container stacking flags. This is because any welding is done first.

    -wfc, --weld-fat-comma
    @@ -3041,6 +3062,70 @@ +

    Missing Else Blocks

    + +

    One defensive programming technique is to require that every if-elsif- chain be terminated with an else block, even though it is not required, to insure that there are no holes in the logic.

    + +

    For example, consider the following snippet:

    + +
        if    ( $level == 3 ) { $val = $global{'section'} }
+    elsif ( $level == 2 ) { $val = $global{'chapter'} }
    + +

    What if the variable $level is neither 2 nor 3? Maybe the original programmer knew that this was okay, but a new programmer might be unsure.

    + +

    Perltidy has always written this information in its LOG file (search for No else block). But a problem is that you have to turn on the log file and look for it. The parameters in this section can either issue a warning if an else is missing, or even insert an empty else block where one is missing, or both.

    + +
    + +
    -wme, --warn-missing-else
    +
    + +

    This flag tells perltidy to issue a warning if a program is missing a terminal else block. The default is not to issue such warnings.

    + +
    +
    -ame, --add-missing-else
    +
    + +

    This flag tells perltidy to output an empty else block wherever a program is missing a terminal else block. To get a warning when this is done you can also set -wme. The default is not to add missing else blocks.

    + +
    +
    -amec=s, --add-missing-else-comment=s
    +
    + +

    This string is an optional side comment which will be placed within a new empty else block. The default is:

    + +
        -amec='##FIXME - added with perltidy -ame'
    + +
    +
    + +

    For example, on the above example we get

    + +
        # perltidy -ame -wme
+    if    ( $level == 3 ) { $val = $global{'section'} }
+    elsif ( $level == 2 ) { $val = $global{'chapter'} }
+    else {
+        ##FIXME - added with perltidy -ame
+    }
    + +

    Any ##FIXME comments should be changed appropriately after the code is inspected. For example, we might decide that it fine as is, and just leave a note for the next programmer:

    + +
        if    ( $level == 3 ) { $val = $global{'section'} }
+    elsif ( $level == 2 ) { $val = $global{'chapter'} }
+    else {
+        # ok - other $level values can be safely ignored
+    }
    + +

    Or maybe it should never happen:

    + +
        if    ( $level == 3 ) { $val = $global{'section'} }
+    elsif ( $level == 2 ) { $val = $global{'chapter'} }
+    else {
+        die("unexpected value of level=$level\n);
+    }
    + +

    Note that this operation cannot be undone, so be careful to inspect the new code carefully.

    +

    Retaining or Ignoring Existing Line Breaks

    Several additional parameters are available for controlling the extent to which line breaks in the input script influence the output script. In most cases, the default parameter values are set so that, if a choice is possible, the output style follows the input style. For example, if a short logical container is broken in the input script, then the default behavior is for it to remain broken in the output script.

    @@ -3908,7 +3993,22 @@
    -uf=s, --use-feature=s
    -

    This flag tells perltidy to allow the syntax associated a pragma in string s. Currently only the recognized values for the string are s='class' or string s=' '. The default is --use-feature='class'. This enables perltidy to recognized the special words class, method, field, and ADJUST. If this causes a conflict with other uses of these words, the default can be turned off with --use-feature=' '.

    +

    This flag tells perltidy to allow or disallow the syntax associated a pragma in string s. The current possible settings are:

    + +
      + +

    • --use-feature='class'. This tells perltidy to recognized the special words class, method, field, and ADJUST as defined for this feature.

      + +
      • +

    • --use-feature='noclass'. This tells perltidy not to treat words class, method, field, ADJUST specially.

      + +
      • +

    • Neither of these (--use-feature not defined). This is the DEFAULT and recommended setting. In this case perltidy will try to automatically handle both the newer --use-feature 'class' syntax as well as some conflicting uses of some of these special words by exisiting modules.

      + +
      • +
    + +

    Note that this parameter is independent of any use feature control lines within a script. Perltidy does not look for or read such control lines. This is because perltidy must be able to work on small chunks of code sent from an editor, so it cannot assume that such lines will be within the lines being formatted.

    @@ -4491,7 +4591,7 @@

    VERSION

    -

    This man page documents perltidy version 20230701

    +

    This man page documents perltidy version 20230701.04

    BUG REPORTS

    diff --git a/lib/Perl/Tidy.pm b/lib/Perl/Tidy.pm index 1d504d36..f5a1fc67 100644 --- a/lib/Perl/Tidy.pm +++ b/lib/Perl/Tidy.pm @@ -111,7 +111,7 @@ BEGIN { # then the Release version must be bumped, and it is probably past time for # a release anyway. - $VERSION = '20230701.03'; + $VERSION = '20230701.04'; } ## end BEGIN sub DESTROY { diff --git a/lib/Perl/Tidy.pod b/lib/Perl/Tidy.pod index baea366c..65ad5014 100644 --- a/lib/Perl/Tidy.pod +++ b/lib/Perl/Tidy.pod @@ -469,7 +469,7 @@ The module 'Perl::Tidy' comes with a binary 'perltidy' which is installed when t =head1 VERSION -This man page documents Perl::Tidy version 20230701.03 +This man page documents Perl::Tidy version 20230701.04 =head1 LICENSE diff --git a/lib/Perl/Tidy/Debugger.pm b/lib/Perl/Tidy/Debugger.pm index 3dd9005b..8e1a3fe6 100644 --- a/lib/Perl/Tidy/Debugger.pm +++ b/lib/Perl/Tidy/Debugger.pm @@ -8,7 +8,7 @@ package Perl::Tidy::Debugger; use strict; use warnings; use English qw( -no_match_vars ); -our $VERSION = '20230701.03'; +our $VERSION = '20230701.04'; use constant EMPTY_STRING => q{}; use constant SPACE => q{ }; diff --git a/lib/Perl/Tidy/Diagnostics.pm b/lib/Perl/Tidy/Diagnostics.pm index b94b0501..6a16e978 100644 --- a/lib/Perl/Tidy/Diagnostics.pm +++ b/lib/Perl/Tidy/Diagnostics.pm @@ -18,7 +18,7 @@ package Perl::Tidy::Diagnostics; use strict; use warnings; use English qw( -no_match_vars ); -our $VERSION = '20230701.03'; +our $VERSION = '20230701.04'; use constant EMPTY_STRING => q{}; diff --git a/lib/Perl/Tidy/FileWriter.pm b/lib/Perl/Tidy/FileWriter.pm index 17d3cc53..0250311e 100644 --- a/lib/Perl/Tidy/FileWriter.pm +++ b/lib/Perl/Tidy/FileWriter.pm @@ -7,7 +7,7 @@ package Perl::Tidy::FileWriter; use strict; use warnings; -our $VERSION = '20230701.03'; +our $VERSION = '20230701.04'; use constant DEVEL_MODE => 0; use constant EMPTY_STRING => q{}; diff --git a/lib/Perl/Tidy/Formatter.pm b/lib/Perl/Tidy/Formatter.pm index dbb07c05..93dde3b0 100644 --- a/lib/Perl/Tidy/Formatter.pm +++ b/lib/Perl/Tidy/Formatter.pm @@ -53,7 +53,7 @@ use constant SPACE => 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 = '20230701.03'; +our $VERSION = '20230701.04'; # The Tokenizer will be loaded with the Formatter ##use Perl::Tidy::Tokenizer; # for is_keyword() diff --git a/lib/Perl/Tidy/HtmlWriter.pm b/lib/Perl/Tidy/HtmlWriter.pm index 0f34fb69..157b670e 100644 --- a/lib/Perl/Tidy/HtmlWriter.pm +++ b/lib/Perl/Tidy/HtmlWriter.pm @@ -7,7 +7,7 @@ package Perl::Tidy::HtmlWriter; use strict; use warnings; -our $VERSION = '20230701.03'; +our $VERSION = '20230701.04'; use English qw( -no_match_vars ); use File::Basename; diff --git a/lib/Perl/Tidy/IOScalar.pm b/lib/Perl/Tidy/IOScalar.pm index 07ede06f..1c2a4147 100644 --- a/lib/Perl/Tidy/IOScalar.pm +++ b/lib/Perl/Tidy/IOScalar.pm @@ -10,7 +10,7 @@ package Perl::Tidy::IOScalar; use strict; use warnings; use Carp; -our $VERSION = '20230701.03'; +our $VERSION = '20230701.04'; use constant DEVEL_MODE => 0; use constant EMPTY_STRING => q{}; diff --git a/lib/Perl/Tidy/IOScalarArray.pm b/lib/Perl/Tidy/IOScalarArray.pm index 1f5a35fa..2c462886 100644 --- a/lib/Perl/Tidy/IOScalarArray.pm +++ b/lib/Perl/Tidy/IOScalarArray.pm @@ -14,7 +14,7 @@ package Perl::Tidy::IOScalarArray; use strict; use warnings; use Carp; -our $VERSION = '20230701.03'; +our $VERSION = '20230701.04'; use constant DEVEL_MODE => 0; diff --git a/lib/Perl/Tidy/IndentationItem.pm b/lib/Perl/Tidy/IndentationItem.pm index 85f1a4f2..d444b5e2 100644 --- a/lib/Perl/Tidy/IndentationItem.pm +++ b/lib/Perl/Tidy/IndentationItem.pm @@ -8,7 +8,7 @@ package Perl::Tidy::IndentationItem; use strict; use warnings; -our $VERSION = '20230701.03'; +our $VERSION = '20230701.04'; BEGIN { diff --git a/lib/Perl/Tidy/Logger.pm b/lib/Perl/Tidy/Logger.pm index a303ba18..aa23eaa8 100644 --- a/lib/Perl/Tidy/Logger.pm +++ b/lib/Perl/Tidy/Logger.pm @@ -8,7 +8,7 @@ package Perl::Tidy::Logger; use strict; use warnings; -our $VERSION = '20230701.03'; +our $VERSION = '20230701.04'; use English qw( -no_match_vars ); use constant DEVEL_MODE => 0; diff --git a/lib/Perl/Tidy/Tokenizer.pm b/lib/Perl/Tidy/Tokenizer.pm index c2b495e8..012adca2 100644 --- a/lib/Perl/Tidy/Tokenizer.pm +++ b/lib/Perl/Tidy/Tokenizer.pm @@ -22,7 +22,7 @@ use strict; use warnings; use English qw( -no_match_vars ); -our $VERSION = '20230701.03'; +our $VERSION = '20230701.04'; use Carp; diff --git a/lib/Perl/Tidy/VerticalAligner.pm b/lib/Perl/Tidy/VerticalAligner.pm index 9fcd525b..3d676a0f 100644 --- a/lib/Perl/Tidy/VerticalAligner.pm +++ b/lib/Perl/Tidy/VerticalAligner.pm @@ -3,7 +3,7 @@ use strict; use warnings; use Carp; use English qw( -no_match_vars ); -our $VERSION = '20230701.03'; +our $VERSION = '20230701.04'; use Perl::Tidy::VerticalAligner::Alignment; use Perl::Tidy::VerticalAligner::Line; diff --git a/lib/Perl/Tidy/VerticalAligner/Alignment.pm b/lib/Perl/Tidy/VerticalAligner/Alignment.pm index 3f396f41..7b8798a7 100644 --- a/lib/Perl/Tidy/VerticalAligner/Alignment.pm +++ b/lib/Perl/Tidy/VerticalAligner/Alignment.pm @@ -10,7 +10,7 @@ use warnings; { #<<< A non-indenting brace -our $VERSION = '20230701.03'; +our $VERSION = '20230701.04'; sub new { my ( $class, $rarg ) = @_; diff --git a/lib/Perl/Tidy/VerticalAligner/Line.pm b/lib/Perl/Tidy/VerticalAligner/Line.pm index 4ad8aec6..97bca6b3 100644 --- a/lib/Perl/Tidy/VerticalAligner/Line.pm +++ b/lib/Perl/Tidy/VerticalAligner/Line.pm @@ -10,7 +10,7 @@ package Perl::Tidy::VerticalAligner::Line; use strict; use warnings; use English qw( -no_match_vars ); -our $VERSION = '20230701.03'; +our $VERSION = '20230701.04'; sub AUTOLOAD { -- 2.39.5