From: Steve Hancock Date: Sat, 20 Jan 2024 23:09:30 +0000 (-0800) Subject: bump version to 20230912.13 X-Git-Tag: 20230912.13~4 X-Git-Url: https://git.donarmstrong.com/?a=commitdiff_plain;h=ab4a992b36505bf1fa65960d95f3ae02dc5dbc87;p=perltidy.git bump version to 20230912.13 --- diff --git a/CHANGES.md b/CHANGES.md index d3b82f8f..c653cac2 100644 --- a/CHANGES.md +++ b/CHANGES.md @@ -1,6 +1,6 @@ # Perltidy Change Log -## 2023 09 12.12 +## 2023 09 12.13 - Added --valign-signed-numbers, or -vsn. This improves the appearance of columns of numbers by aligning leading algebraic signs. For example: diff --git a/bin/perltidy b/bin/perltidy index 7023e4fd..da3584e5 100755 --- a/bin/perltidy +++ b/bin/perltidy @@ -5664,7 +5664,7 @@ 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 +found in test code and can sometimes be fixed by using the structure main(); @@ -5672,10 +5672,11 @@ found in test code, and might be fixed by using the structure ## 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. +The B side comment C<#<<<> is not required but will keep +the indentation of the old code unchanged. + +This check is only applied to package statements which are not enclosed in +block braces in order avoid warnings at temporary package changes. =item B @@ -6246,7 +6247,7 @@ The perltidy binary uses the Perl::Tidy module and is installed when that module =head1 VERSION -This man page documents perltidy version 20230912.12 +This man page documents perltidy version 20230912.13 =head1 BUG REPORTS diff --git a/docs/ChangeLog.html b/docs/ChangeLog.html index 6a9c567c..9a10efb8 100644 --- a/docs/ChangeLog.html +++ b/docs/ChangeLog.html @@ -1,8 +1,112 @@

Perltidy Change Log

-

2023 09 12.04

+

2023 09 12.13

-
- The --dump-block-summary (-dbs) option now includes the number of sub
+
- Added --valign-signed-numbers, or -vsn. This improves the appearance
+  of columns of numbers by aligning leading algebraic signs.  For example:
+
+        # perltidy -vsn
+        my $xyz_shield = [
+            [ -0.060,  -0.060,  0. ],
+            [  0.060,  -0.060,  0. ],
+            [  0.060,   0.060,  0. ],
+            [ -0.060,   0.060,  0. ],
+            [ -0.0925, -0.0925, 0.092 ],
+            [  0.0925, -0.0925, 0.092 ],
+            [  0.0925,  0.0925, 0.092 ],
+            [ -0.0925,  0.0925, 0.092 ],
+        ];
+
+        # perltidy -nvsn (current DEFAULT)
+        my $xyz_shield = [
+            [ -0.060,  -0.060,  0. ],
+            [ 0.060,   -0.060,  0. ],
+            [ 0.060,   0.060,   0. ],
+            [ -0.060,  0.060,   0. ],
+            [ -0.0925, -0.0925, 0.092 ],
+            [ 0.0925,  -0.0925, 0.092 ],
+            [ 0.0925,  0.0925,  0.092 ],
+            [ -0.0925, 0.0925,  0.092 ],
+        ];
+
+  This new option works well but is currently OFF to allow more testing
+  and fine-tuning. It is expected to be activated in a future release.
+
+- Added --dump-mixed-call-parens (-dmcp ) which will dump a list of
+  operators which are sometimes followed by parens and sometimes not.
+  Issue git #128. For example
+
+     perltidy -dmcp somefile.pl >out.txt
+
+  produces lines like this, where the first number is the count of
+  uses with parens, and the second number is the count without parens.
+
+    k:caller:2:1
+    k:chomp:3:4
+    k:close:7:4
+
+- Added --want-call-parens=s (-wcp=s) and --nowant-call-parens=s (-nwcp=s)
+  options which will warn of paren uses which do not match a selected
+  style. The manual has details. But for example,
+
+    perltidy -wcp='&' somefile.pl
+
+  will format as normal but warn if any user subs are called without parens.
+
+- Added --dump-unusual-variables (-duv) option to dump a list of
+  variables with certain properties of interest. For example
+
+     perltidy -duv somefile.pl >vars.txt
+
+  produces a file with lines which look something like
+
+     ...
+     1778:u: my $input_file
+     6089:r: my $j: reused - see line 6076
+
+  The values on the line which are separated by colons are:
+
+    line number   - the number of the line of the input file
+    issue         - a single letter indicating the issue, see below
+    variable name - the name of the variable, preceded by a keyword
+    note          - an optional note referring to another line
+
+  The issue is indicated by a letter which may be one of:
+    r: reused variable name
+    s: sigil change but reused bareword
+    p: lexical variable with scope in multiple packages
+    u: unused variable
+
+- Added a related flag --warn-variable-types=string (-wvt=string) option
+  to warn if certain types of variables are found in a script. The types
+  are a space-separated string which may include 'r', 's', and 'p' but
+  not 'u'. For example
+
+    perltidy -wvt='r s' somefile.pl
+
+  will check for and warn if any variabls of type 'r', or 's' are seen,
+  but not 'p'. All possible checks may be indicated with a '*' or '1':
+
+    perltidy -wvt='*' somefile.pl
+
+  The manual has further details.
+
+- All parameters taking integer values are now checked for
+  out-of-range values before processing starts. When a
+  minimum or maximum range is exceeded, the new default
+  behavior is to write a warning message, reset the
+  value to its default setting, and continue.  If this default
+  behavior causes a problem, it can be changed with the new
+  parameter B<--integer-range-check=n>, or B<-irc=n>, as follows:
+
+    n=0  skip check completely (for stress-testing perltidy only)
+    n=1  reset bad values to defaults but do not issue a warning
+    n=2  reset bad values to defaults and issue a warning [DEFAULT]
+    n=3  stop immediately if any values are out of bounds
+
+  The settings n=0 and n=1 are mainly useful for testing purposes.
+
+- The --dump-block-summary (-dbs) option now includes the number of sub
   args in the 'type' column. For example, 'sub(9)' indicates a sub
   with 9 args.  Subs whose arg count cannot easily be determined are
   indicated as 'sub(*)'. The count does not include a leading '$self'
@@ -27,7 +131,7 @@
   a space). The new default value, n=1, will produce a space if and only
   if there was a space in the input text.
 
-- The dump-block-summary option can report an if-elsif-elsif-.. chain
+- The --dump-block-summary option can report an if-elsif-elsif-.. chain
   as a single line item with the notation -dbt='elsif3', for example,
   where the '3' is an integer which specifies the minimum number of elsif
   blocks required for a chain to be reported. The manual has details.
@@ -35,6 +139,9 @@
 - Fix problem c269, in which the new -ame parameter could incorrectly
   emit an else block when two elsif blocks were separated by a hanging
   side comment (a very rare situation).
+
+- The -DEBUG option no longer automatically also writes a .LOG file.
+  Use --show-options if the .LOG file is needed.
 

 
 
2023 09 12

@@ -906,15 +1013,15 @@ signatures.  Reformatting with the current version will fix the problem.
   the -quiet flag.  This has been fixed.
 
 - Add flag -maxfs=n, --maximum-file-size-mb=n.  This parameter is provided to
-  avoid causing system problems by accidentally attempting to format an 
-  extremely large data file. The default is n=10.  The command to increase 
+  avoid causing system problems by accidentally attempting to format an
+  extremely large data file. The default is n=10.  The command to increase
   the limit to 20 MB for example would be  -mfs=20.  This only applies to
   files specified by filename on the command line.
 
-- Skip formatting if there are too many indentation level errors.  This is 
-  controlled with -maxle=n, --maximum-level-errors=n.  This means that if 
+- Skip formatting if there are too many indentation level errors.  This is
+  controlled with -maxle=n, --maximum-level-errors=n.  This means that if
   the ending indentation differs from the starting indentation by more than
-  n levels, the file will be output verbatim. The default is n=1. 
+  n levels, the file will be output verbatim. The default is n=1.
   To skip this check, set n=-1 or set n to a large number.
 
 - A related new flag, --maximum-unexpected-errors=n, or -maxue=n, is available
@@ -922,10 +1029,10 @@ signatures.  Reformatting with the current version will fix the problem.
 
 - Add flag -xci, --extended-continuation-indentation, regarding issue git #28
   This flag causes continuation indentation to "extend" deeper into structures.
-  Since this is a fairly new flag, the default is -nxci to avoid disturbing 
+  Since this is a fairly new flag, the default is -nxci to avoid disturbing
   existing formatting.  BUT you will probably see some improved formatting
-  in complex data structures by setting this flag if you currently use -ci=n 
-  and -i=n with the same value of 'n' (as is the case if you use -pbp, 
+  in complex data structures by setting this flag if you currently use -ci=n
+  and -i=n with the same value of 'n' (as is the case if you use -pbp,
   --perl-best-practices, where n=4).
 
 - Fix issue git #42, clarify how --break-at-old-logical-breakpoints works.
@@ -934,21 +1041,21 @@ signatures.  Reformatting with the current version will fix the problem.
 
 - Fix issue git #41, typo in manual regarding -fsb.
 
-- Fix issue git #40: when using the -bli option, a closing brace followed by 
-  a semicolon was not being indented.  This applies to braces which require 
+- Fix issue git #40: when using the -bli option, a closing brace followed by
+  a semicolon was not being indented.  This applies to braces which require
   semicolons, such as a 'do' block.
 
 - Added 'state' as a keyword.
 
 - A better test for convergence has been added. When iterations are requested,
   the new test will stop after the first pass if no changes in line break
-  locations are made.  Previously, file checksums were used and required at least two 
-  passes to verify convergence unless no formatting changes were made.  With the new test, 
-  only a single pass is needed when formatting changes are limited to adjustments of 
+  locations are made.  Previously, file checksums were used and required at least two
+  passes to verify convergence unless no formatting changes were made.  With the new test,
+  only a single pass is needed when formatting changes are limited to adjustments of
   indentation and whitespace on the lines of code.  Extensive testing has been made to
   verify the correctness of the new convergence test.
 
-- Line breaks are now automatically placed after 'use overload' to 
+- Line breaks are now automatically placed after 'use overload' to
   improve formatting when there are numerous overloaded operators.  For
   example
 
@@ -957,8 +1064,8 @@ signatures.  Reformatting with the current version will fix the problem.
       ...
 
 - A number of minor problems with parsing signatures and prototypes have
-  been corrected, particularly multi-line signatures. Some signatures 
-  had previously been parsed as if they were prototypes, which meant the 
+  been corrected, particularly multi-line signatures. Some signatures
+  had previously been parsed as if they were prototypes, which meant the
   normal spacing rules were not applied.  For example
 
   OLD:
@@ -972,17 +1079,17 @@ signatures.  Reformatting with the current version will fix the problem.
     }
 
 - Numerous minor issues that the average user would not encounter were found
-  and fixed. They can be seen in the more complete list of updates at 
+  and fixed. They can be seen in the more complete list of updates at
 
        https://github.com/perltidy/perltidy/blob/master/local-docs/BugLog.pod

2020 10 01

-
- Robustness of perltidy has been significantly improved.  Updating is recommended. Continual 
-  automated testing runs began about 1 Sep 2020 and numerous issues have been found and fixed. 
+
- Robustness of perltidy has been significantly improved.  Updating is recommended. Continual
+  automated testing runs began about 1 Sep 2020 and numerous issues have been found and fixed.
   Many involve references to uninitialized variables when perltidy is fed random text and random
-  control parameters. 
+  control parameters.
 
 - Added the token '->' to the list of alignment tokens, as suggested in git
   #39, so that it can be vertically aligned if a space is placed before them with -wls='->'.
@@ -1003,14 +1110,14 @@ signatures.  Reformatting with the current version will fix the problem.
   comments generated by the -csc parameter, a separating newline was missing.
   The resulting script will not then run, but worse, if it is reformatted with
   the same parameters then closing side comments could be overwritten and data
-  lost. 
+  lost.
 
   This problem was found during automated random testing.  The parameter
   -scbb is rarely used, which is probably why this has not been reported.  Please
   upgrade your version.
 
 - Added parameter --non-indenting-braces, or -nib, which prevents
-  code from indenting one level if it follows an opening brace marked 
+  code from indenting one level if it follows an opening brace marked
   with a special side comment, '#<<<'.  For example,
 
                 { #<<<   a closure to contain lexical vars
@@ -1023,17 +1130,17 @@ signatures.  Reformatting with the current version will fix the problem.
 
   This is on by default.  If your code happens to have some
   opening braces followed by '#<<<', and you
-  don't want this, you can use -nnib to deactivate it. 
+  don't want this, you can use -nnib to deactivate it.
 
 - Side comment locations reset at a line ending in a level 0 open
-  block, such as when a new multi-line sub begins.  This is intended to 
+  block, such as when a new multi-line sub begins.  This is intended to
   help keep side comments from drifting to far to the right.
 

 
 
2020 08 22

 
 
- Fix RT #133166, encoding not set for -st.  Also reported as RT #133171
-  and git #35. 
+  and git #35.
 
   This is a significant bug in version 20200616 which can corrupt data if
   perltidy is run as a filter on encoded text.
@@ -1048,7 +1155,7 @@ signatures.  Reformatting with the current version will fix the problem.
 - Vertical alignment has been improved. Numerous minor issues have
   been fixed.
 
-- Formatting with the -lp option is improved. 
+- Formatting with the -lp option is improved.
 
 - Fixed issue git #32, misparse of bare 'ref' in ternary
 
diff --git a/docs/Tidy.html b/docs/Tidy.html
index 26474489..3ed220f8 100644
--- a/docs/Tidy.html
+++ b/docs/Tidy.html
@@ -233,7 +233,7 @@
 
 
An exit value of 1 indicates that the process had to be terminated early due to errors in the input parameters. This can happen for example if a parameter is misspelled or given an invalid value. The calling program should check for this flag because if it is set the destination stream will be empty or incomplete and should be ignored. Error messages in the stderr stream will indicate the cause of any problem.

 
-
An exit value of 2 indicates that perltidy ran to completion but there there are warning messages in the stderr stream related to parameter errors or conflicts and/or warning messages in the errorfile stream relating to possible syntax errors in the source code being tidied.

+
An exit value of 2 indicates that perltidy ran to completion but there are warning messages in the stderr stream related to parameter errors or conflicts and/or warning messages in the errorfile stream relating to possible syntax errors in the source code being tidied.

 
 
In the event of a catastrophic error for which recovery is not possible perltidy terminates by making calls to croak or confess to help the programmer localize the problem. These should normally only occur during program development.

 
@@ -399,7 +399,7 @@
 
 
VERSION

 
-
This man page documents Perl::Tidy version 20230912.04

+
This man page documents Perl::Tidy version 20230912.13

 
 
LICENSE

 
diff --git a/docs/perltidy.html b/docs/perltidy.html
index dee6ace9..93da32e9 100644
--- a/docs/perltidy.html
+++ b/docs/perltidy.html
@@ -42,7 +42,11 @@
       
  • One-Line Blocks
    • 
       
  • Controlling Vertical Alignment
    • 
       
  • Extended Syntax
    • 
-      
  • Other Controls
    • 
+      
  • Deleting and Extracting Pod or Comments
    • 
+      
  • The perltidyrc file
    • 
+      
  • Debugging perltidy input
    • 
+      
  • Analyzing Code
    • 
+      
  • Working with MakeMaker, AutoLoader and SelfLoader
    • 
     
   
   
  • HTML OPTIONS
    • 
@@ -93,6 +97,8 @@
 
 
    EXAMPLES
    
 
+
    Here are some example perltidy commands followed by their meanings:
    
+
 
      perltidy somefile.pl
    
 
 
    This will produce a file somefile.pl.tdy containing the script reformatted using the default options, which approximate the style suggested in perlstyle(1). The source file somefile.pl is unchanged.
    
@@ -129,6 +135,14 @@
 
 
    Execute perltidy on file somefile.pl and save a log file somefile.pl.LOG which shows the nesting of braces, parentheses, and square brackets at the start of every line.
    
 
+
       perltidy -dbs -dbl=10 somefile.pl >blocks.csv
    
+
+
    This will dump a table of comma-separated metrics for subroutines longer than 10 lines to blocks.csv.
    
+
+
        perltidy -duv somefile.pl >vars.txt
    
+
+
    This will dump a list of unused and reused lexical variable names to vars.txt.
    
+
 
      perltidy -html somefile.pl
    
 
 
    This will produce a file somefile.pl.html containing the script with html markup. The output file will contain an embedded style sheet in the <HEAD> section which may be edited to change the appearance.
    
@@ -411,6 +425,8 @@
 
 
    The value of the integer n can be any value but can be coordinated with the number of spaces used for indentation. For example, -et=4 -ci=4 -i=4 will produce one tab for each indentation level and and one for each continuation indentation level. You may want to coordinate the value of n with what your display software assumes for the spacing of a tab.
    
 
+
    The default is not to use this, which can also be indicated using -et=0.
    
+
 
 
    -t, --tabs
    
 
    
@@ -823,7 +839,7 @@
 
    -nibp=s, --non-indenting-brace-prefix=s
    
 
    
 
-
    The -nibp=string parameter may be used to change the marker for non-indenting braces. The default is equivalent to -nibp='#<<<'. The string that you enter must begin with a # and should be in quotes as necessary to get past the command shell of your system. This string is the leading text of a regex pattern that is constructed by appending pre-pending a '^' and appending a'\s', so you must also include backslashes for characters to be taken literally rather than as patterns.
    
+
    The -nibp=string parameter may be used to change the marker for non-indenting braces. The default is equivalent to -nibp='#<<<'. The string that you enter must begin with a # and should be in quotes as necessary to get past the command shell of your system. This string is the leading text of a regex pattern that is constructed by prepending a '^' and appending a'\s', so you must also include backslashes for characters to be taken literally rather than as patterns.
    
 
 
    For example, to match the side comment '#++', the parameter would be
    
 
@@ -1377,6 +1393,8 @@
 
 
    Perltidy has a number of ways to control the appearance of both block comments and side comments. The term block comment here refers to a full-line comment, whereas side comment will refer to a comment which appears on a line to the right of some code.
    
 
+
    Perltidy does not do any word wrapping of commented text to match a selected maximum line length. This is because there is no way to determine if this is appropriate for the given content. However, an interactive program named perlcomment.pl is available in the examples folder of the perltidy distribution which can assist in doing this.
    
+
 
    
 
 
    -ibc, --indent-block-comments
    
@@ -1729,7 +1747,7 @@
 
  #>>V
    
 
-
    Additional text may appear on the special comment lines provided that it is separated from the marker by at least one space, as in the above examples.
    
+
    Additional text may appear on the special comment lines provided that it is separated from the marker by at least one space to highlight the sign, as in the above examples.
    
 
 
    Any number of code-skipping or format-skipping sections may appear in a file. If an opening code-skipping or format-skipping comment is not followed by a corresponding closing comment, then skipping continues to the end of the file. If a closing code-skipping or format-skipping comment appears in a file but does not follow a corresponding opening comment, then it is treated as an ordinary comment without any special meaning.
    
 
@@ -3714,6 +3732,20 @@
 
 
    The -xci flag was developed after the -pbp parameters were published so you need to include it separately.
    
 
+
+
    Making a file unreadable
    
+
    
+
+
    The goal of perltidy is to improve the readability of files, but there are two commands which have the opposite effect, --mangle and --extrude. They are actually merely aliases for combinations of other parameters. Both of these strip all possible whitespace, but leave comments and pod documents, so that they are essentially reversible. The difference between these is that --mangle puts the fewest possible line breaks in a script while --extrude puts the maximum possible. Note that these options do not provided any meaningful obfuscation, because perltidy can be used to reformat the files. They were originally developed to help test the tokenization logic of perltidy, but they have other uses. One use for --mangle is the following:
    
+
+
      perltidy --mangle myfile.pl -st | perltidy -o myfile.pl.new
    
+
+
    This will form the maximum possible number of one-line blocks (see next section), and can sometimes help clean up a badly formatted script.
    
+
+
    A similar technique can be used with --extrude instead of --mangle to make the minimum number of one-line blocks.
    
+
+
    Another use for --mangle is to combine it with --delete-all-comments (-dac) to reduce the file size of a perl script.
    
+
 
    
 
 
@@ -3727,7 +3759,7 @@
 
 
    The main exception to this rule is that perltidy will attempt to form new one-line blocks following the keywords map, eval, and sort, eval, because these code blocks are often small and most clearly displayed in a single line. This behavior can be controlled with the flag --one-line-block-exclusion-list described below.
    
 
-
    When the cuddled-else style is used, the default treatment of one-line blocks may interfere with the cuddled style. In this case, the default behavior may be changed with the flag --cuddled-break-option=n described elsehwere.
    
+
    When the cuddled-else style is used, the default treatment of one-line blocks may interfere with the cuddled style. In this case, the default behavior may be changed with the flag --cuddled-break-option=n described elsewhere.
    
 
 
    When an existing one-line block is longer than the maximum line length, and must therefore be broken into multiple lines, perltidy checks for and adds any optional terminating semicolon (unless the -nasc option is used) if the block is a code block.
    
 
@@ -3927,7 +3959,7 @@
 
 
    Notice in this last example that although only the equals alignment was excluded, the ternary alignments were also lost. This happens because the vertical aligner sweeps from left-to-right and usually stops if an important alignment cannot be made for some reason.
    
 
-
    But also notice that side comments remain aligned because their alignment is controlled separately with the parameter --valign-side_comments described above.
    
+
    But also notice that side comments remain aligned because their alignment is controlled separately with the parameter --valign-side-comments described above.
    
 
 
 
    Aligning postfix unless and if with --valign-if-unless or -viu
    
@@ -3949,6 +3981,36 @@
     print "RPM Output:\n"                 unless $Quiet;
     print join( "\n", @RPMOutput ) . "\n" unless $Quiet;
    + +
    Aligning signed numbers with --valign-signed-numbers or -vsn
    +
    + +

    Setting -vsn causes columns of numbers containing both signed and unsigned values to have leading signs placed in their own column. For example:

    + +
        # perltidy -vsn
+    my @correct = (
+        [  123456.79,   86753090000.868,  11 ],
+        [ -123456.79,  -86753090000.868, -11 ],
+        [  123456.001,  80.080,           10 ],
+        [ -123456.001, -80.080,           0 ],
+        [  10.9,        10.9,             11 ],
+    );
    + +

    The current default alignment is strict left justification:

    + +
        # perltidy -nvsn
+    my @correct = (
+        [ 123456.79,   86753090000.868,  11 ],
+        [ -123456.79,  -86753090000.868, -11 ],
+        [ 123456.001,  80.080,           10 ],
+        [ -123456.001, -80.080,          0 ],
+        [ 10.9,        10.9,             11 ],
+    );
    + +

    In a future release -vsn will become the default.

    + +

    This option has a control parameter --valign-signed-number-limit=N, or -vsnl=N. This value controls formatting of very long columns of numbers and should not normally need to be changed. To see the function of this parameter, consider a very long column of just unsigned numbers, say 1000 lines. If we add a single negative number, it is undesirable to move all of the other lines over by one space. This would create many lines of file differences but not really improve the appearance when a local section of the table was viewed. The number N avoids this problem by not adding extra indentation to a run of more than N lines of unsigned numbers. The default value, N=20, is set to be approximately the number of lines for which a viewer does not normally see both ends of a long column of unsigned numbers on a single page.

    +
    @@ -4031,17 +4093,25 @@

  • --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.

    +

  • 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 existing 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.

    + +
    Working around problems with older version of Perl
    +
    + +

    Perltidy contains a number of rules which help avoid known subtleties and problems with older versions of perl, and these rules always take priority over whatever formatting flags have been set. For example, perltidy will usually avoid starting a new line with a bareword, because this might cause problems if use strict is active.

    + +

    There is no way to override these rules.

    +
    -

    Other Controls

    +

    Deleting and Extracting Pod or Comments

    @@ -4073,6 +4143,12 @@

    The negatives of these commands also work, and are the defaults.

    +
    + +

    The perltidyrc file

    + +
    +
    Using a .perltidyrc command file
    @@ -4119,6 +4195,9 @@

  • The parameters in the .perltidyrc file can be switched off with the -npro option.

    +
    • +

  • Any parameter in the .perltidyrc file can be overridden with a replacement value on the command line. This is because the command line is processed after the .perltidyrc file.

    +

  • The commands --dump-options, --dump-defaults, --dump-long-names, and --dump-short-names, all described below, may all be helpful.

    @@ -4161,29 +4240,23 @@

    Please note: do not use this flag unless you are sure your script needs it. Parsing errors can occur if it does not have a hash-bang, or, for example, if the actual first hash-bang is in a here-doc. In that case a parsing error will occur because the tokenization will begin in the middle of the here-doc.

    • -
    Making a file unreadable
    -
    - -

    The goal of perltidy is to improve the readability of files, but there are two commands which have the opposite effect, --mangle and --extrude. They are actually merely aliases for combinations of other parameters. Both of these strip all possible whitespace, but leave comments and pod documents, so that they are essentially reversible. The difference between these is that --mangle puts the fewest possible line breaks in a script while --extrude puts the maximum possible. Note that these options do not provided any meaningful obfuscation, because perltidy can be used to reformat the files. They were originally developed to help test the tokenization logic of perltidy, but they have other uses. One use for --mangle is the following:

    - -
      perltidy --mangle myfile.pl -st | perltidy -o myfile.pl.new
    - -

    This will form the maximum possible number of one-line blocks (see next section), and can sometimes help clean up a badly formatted script.

    +
    -

    A similar technique can be used with --extrude instead of --mangle to make the minimum number of one-line blocks.

    +

    Debugging perltidy input

    -

    Another use for --mangle is to combine it with -dac to reduce the file size of a perl script.

    +
    - -
    Debugging
    +
    The --dump-... parameters
    -

    The following flags are available for debugging:

    +

    The following flags are available for debugging. Note that all commands named --dump-... will simply write some requested information to standard output and then immediately exit.

    --dump-cuddled-block-list or -dcbl will dump to standard output the internal hash of cuddled block types created by a -cuddled-block-list input string.

    --dump-defaults or -ddf will write the default option set to standard output and quit

    +

    --dump-integer-option-range or -dior will write a list of comma-separated values. Each line contains the name of an integer option along with its minimum, maximum, and default values.

    +

    --dump-profile or -dpro will write the name of the current configuration file and its contents to standard output and quit.

    --dump-options or -dop will write current option set to standard output and quit.

    @@ -4194,9 +4267,13 @@

    --dump-token-types or -dtt will write a list of all token types to standard output and quit.

    -

    --dump-want-left-space or -dwls will write the hash %want_left_space to standard output and quit. See the section on controlling whitespace around tokens.

    +

    --dump-want-left-space or -dwls will write the hash %want_left_space to standard output and quit. See the section on controlling whitespace around tokens.

    + +

    --dump-want-right-space or -dwrs will write the hash %want_right_space to standard output and quit. See the section on controlling whitespace around tokens.

    -

    --dump-want-right-space or -dwrs will write the hash %want_right_space to standard output and quit. See the section on controlling whitespace around tokens.

    +
    + +

    --no-memoize or -nmem will turn of memoizing. Memoization can reduce run time when running perltidy repeatedly in a single process. It is on by default but can be deactivated for testing with -nmem.

    @@ -4208,7 +4285,11 @@ 
      perltidy -maxfs=20
    -

    This only applies to files specified by filename on the command line.

    +

    This length test is applied to named files before they are read into memory. It is applied to files arriving from standard input after they are read into memory. It is not applied to character strings arriving by a call to the Perl::Tidy module.

    + +
    +
    Controls for when to stop processing
    +

    --maximum-level-errors=n or -maxle=n specifies the maximum number of indentation level errors are allowed before perltidy skips formatting and just outputs a file verbatim. The default is n=1. This means that if the final indentation of a script differs from the starting indentation by more than 1 levels, the file will be output verbatim. To avoid formatting if there are any indentation level errors use -maxle=0. To skip this check you can either set n equal to a large number, such as n=100, or set n=-1.

    @@ -4227,10 +4308,35 @@

    A recommended value is n=3. However, the default is n=0 (skip this check) to avoid causing problems with scripts which have extended syntaxes.

    -

    -DEBUG will write a file with extension .DEBUG for each input file showing the tokenization of all lines of code.

    +
    +
    Handling errors in options which take integer values
    +
    + +

    Many of the input parameters take integer values. Before processing begins, a check is made to see if any of these integer parameters exceed their valid ranges. The default behavior when a range is exceeded is to write a warning message and reset the value to its default setting. This default behavior can be changed with the parameter --integer-range-check=n, or -irc=n, as follows:

    + +
        n=0  skip check completely (for stress-testing perltidy only)
+    n=1  reset bad values to defaults but do not issue a warning
+    n=2  reset bad values to defaults and issue warning [DEFAULT]
+    n=3  stop if any values are out of bounds
    + +

    The values n=0 and n=1 are mainly useful for testing purposes.

    -
    Making a table of information on code blocks
    +
    Debugging perltidy tokenization
    +
    + +

    -DEBUG, -D will write a file with extension .DEBUG for each input file showing the tokenization of all lines of code. This can produce a lot of output and is mainly useful for debugging tokenization issues during perltidy development.

    + +
    +
    + +

    Analyzing Code

    + +

    Perltidy reports any obvious issues that are found during formatting, such as unbalanced braces. But several parameters are available for making certain additional checks for issues which might be of interest to a programmer.

    + +
    + +
    Use --dump-block-summary to make a table of information on code blocks

    A table listing information about the blocks of code in a file can be made with --dump-block-summary, or -dbs. This causes perltidy to read and parse the file, write a table of comma-separated values for selected code blocks to the standard output, and then exit. This parameter must be on the command line, not in a .perlticyrc file, and it requires a single file name on the command line. For example

    @@ -4261,7 +4367,7 @@

    --dump-block-types=s, or -dbt=s, where string s is a list of block types to be included. The type of a block is either the name of the perl builtin keyword for that block (such as sub if elsif else for foreach ..) or the word immediately before the opening brace. In addition, there are a few symbols for special block types, as follows:

       if elsif else for foreach ... any keyword introducing a block
-   sub  - any sub or anynomous sub
+   sub  - any sub or anonymous sub
    asub - any anonymous sub
    *    - any block except nameless blocks
    +    - any nested inner block loop
@@ -4307,26 +4413,159 @@
    -
    Working with MakeMaker, AutoLoader and SelfLoader
    +
    use --dump-unusual-variables to find unused, reused, and certain other variables of interest
    -

    The first $VERSION line of a file which might be eval'd by MakeMaker is passed through unchanged except for indentation. Use --nopass-version-line, or -npvl, to deactivate this feature.

    +

    Lexical variables with certain properties of interest to a programmer can be listed with --dump-unusual-variables or -duv. This parameter must be on the command line, along with a single file name. It causes perltidy to scan the file for certain variable types, write any found to the standard output, and then immediately exit without doing any formatting. For example

    -

    If the AutoLoader module is used, perltidy will continue formatting code after seeing an __END__ line. Use --nolook-for-autoloader, or -nlal, to deactivate this feature.

    +
        perltidy -duv somefile.pl >vars.txt
    -

    Likewise, if the SelfLoader module is used, perltidy will continue formatting code after seeing a __DATA__ line. Use --nolook-for-selfloader, or -nlsl, to deactivate this feature.

    +

    produces a file with lines which look something like

    + +
        1778:u: my $input_file
+    6089:r: my $j: reused - see line 6076
    + +

    The values on the line are separated by colons and have the following meaning:

    + +
        line number   - the number of the line of the input file
+    issue         - a single letter indicating the issue, see below
+    variable name - the name of the variable, preceded by a keyword
+    note          - an optional note referring to another line
    + +

    If there are a large number of issues it can be convenient to read the file into a spreadsheet. The checks are for lexical variables introduced by the keywords my and state. The types of checks which are made are identified in the output with one of the letters, r, s, p, and u as follows:

    + +
    + +
    r: reused variable name
    +
    + +

    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). This issue can be avoided by renaming one of the conflicting variables. Note that this is similar to the Perl::Critic policy Variables::ProhibitReusedNames.

    -
    Working around problems with older version of Perl
    +
    s: sigil change but reused bareword
    -

    Perltidy contains a number of rules which help avoid known subtleties and problems with older versions of perl, and these rules always take priority over whatever formatting flags have been set. For example, perltidy will usually avoid starting a new line with a bareword, because this might cause problems if use strict is active.

    +

    These are variables which have the same bareword name but a different sigil ($, @, or %) as another variable in the same scope. For example, this occurs if variables $data and %data share the same scope. This can be confusing and can be avoided by renaming one of the variables.

    -

    There is no way to override these rules.

    +
    +
    p: package-crossing variables
    +
    + +

    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, 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 non-indenting-braces comment #<<< 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.

    + +
    +
    u: unused variables
    +
    + +

    These are variables which are declared with a my and not referenced again within their scope. Calling them unused is convenient but not really 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 therefore 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 my. 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 at first glance, but the scope of the my declaration is limited to the surrounding braces, so it is not the same variable as the other $string and must therefore be reported as unused. This problem would have also been caught by perl if the author had used strict.

    +
    +
    Use --warn-variable-types to warn about certain variable types
    +
    + +

    The flag --warn-variable-types=string, or -wvt=string, can be used to produce a warning message if certain of the above variable types are encountered during formatting. All possible variable warnings may be requested with -wvt='*' or -wvt=1.

    + +

    For example,

    + +
       perltidy -wvt='*' somefile.pl
    + +

    The default is not to do any of these checks, and it can also be indicated with -wvt=0.

    + +

    To restrict the check to a specific set warnings, set the input string to be a space-separated or comma-separated list of the letters associated with the types of variables to be checked. For example:

    + +
       perltidy -wvt='s r' somefile.pl
    + +

    will process somefile.pl normally but issue a warning if either of the issues 's' or 'r', but not 'p', described above, are encountered.

    + +

    A limitation is that warnings may not be requested for unused variables, type 'u'. The is because this would produce many needless warnings, especially when perltidy is run on small snippets of code from within an editor. So unused variables can only be found with the -duv option described in the previous section.

    + +

    A companion flag, --warn-variable-exclusion-list=string, or -wvxl=string, can be used to skip warning checks for a list of variables. For example,

    + +
       perltidy -wvt='*' -wvxl='$self $class'  somefile.pl
    + +

    will do all possible checks but not report any warnings for variables $self and $class.

    + +
    +
    Use --dump-mixed-call-parens to find functions called both with and without parens
    +
    + +

    The parameter --dump-mixed-call-parens, or -dmcp, provides information on the use of call parens within a program. It produces a list of keywords and sub names which occur both both with and without parens. In other words, with a mixed style. This might be useful if one is working to standardize the call style for some particular keyword or function. For example,

    + +
       perltidy -dmcp somefile.pl >output.txt
    + +

    will analyze the text of somefile.pl, write the results to output.txt, and then immediately exit (like all dump- parameters).

    + +

    The output shows a list of operators and the number of times they were used with parens and the number of times without parens. For example, here is a small section of the output from one file in a past Perl distribution:

    + +
        k:length:17:9
+    k:open:30:9
+    k:pop:3:4
    + +

    The first line shows that the length function occurs 17 times with parens and 9 times without parens. The 'k' indicates that length is a Perl builtin keyword ('U' would mean user-defined sub, and 'w' would mean unknown bareword). So from this partial output we see that the author had a preference for parens around the args of length and open, whereas pop was about equally likely to have parens as not.

    + +

    More detailed information can be obtained with the parameters described in the next section.

    + +
    +
    Use --want-call-parens=s and --nowant-call-parens=s to warn about specific missing or extra call parens
    +
    + +

    The parameter --want-call-parens=s, or -wcp=s, can be used to to produce a warning message if call parens are missing from selected functions. Likewise, --nowant-call-parens=s, or -nwcp=s, can warn if call parens exist for selected functions. When either of these parameters are set, perltidy will report any discrepancies from the requested style in its error output.

    + +

    Before using either of these parameters, it may be helpful to first use --dump-mixed-call-parens=s, described in the previous section, to get an overview of the existing paren usage in a file.

    + +

    The string arguments s are space-separated lists of the names of the functions to be checked. The function names may be builtin keywords or user-defined subs. They may not include a package prefix or sigil. To illustrate,

    + +
       perltidy -wcp='length open' -nwcp='pop'   somefile.pl
    + +

    means that the builtin functions length and open should have parens around their call args but pop should not. The error output might contain lines such as:

    + +
        2314:open FD_TO_CLOSE: no call parens
+    3652:pop (: has call parens
+    3783:length $DB: no call parens
+    ...
    + +

    For builtin keywords which have both a block form and a trailing modifier form, such as if, only the trailing modifier form will be checked since parens are mandatory for the block form.

    + +

    The symbol & may entered instead of a function name to mean all user-defined subs not explicitly listed. So the compact expression

    + +
       perltidy -wcp='&' somefile.pl
    + +

    means that calls to all user-defined subs in the file being processed should have their call arguments enclosed in parens.

    + +

    Perltidy does not have the ability to add or delete call parens because it is difficult to automate, so changes must be made manually. When adding or removing parentheses, it is essential to pay attention to operator precedence issues. For example, if the parens in the following statement are removed, then || must be changed to or:

    + +
        open( IN, "<", $infile ) || die("cannot open $infile:$!\n");
    + +

    Otherwise, the || will operate on $infile rather than the return value of open.

    + +
    +
    + +

    Working with MakeMaker, AutoLoader and SelfLoader

    + +

    The first $VERSION line of a file which might be eval'd by MakeMaker is passed through unchanged except for indentation. Use --nopass-version-line, or -npvl, to deactivate this feature.

    + +

    If the AutoLoader module is used, perltidy will continue formatting code after seeing an __END__ line. Use --nolook-for-autoloader, or -nlal, to deactivate this feature.

    + +

    Likewise, if the SelfLoader module is used, perltidy will continue formatting code after seeing a __DATA__ line. Use --nolook-for-selfloader, or -nlsl, to deactivate this feature.

    +

    HTML OPTIONS

    @@ -4443,7 +4682,7 @@ identifier identifier i bareword, function bareword w keyword keyword k - quite, pattern quote q + quote, pattern quote q here doc text here-doc-text h here doc target here-doc-target hh punctuation punctuation pu @@ -4538,20 +4777,21 @@ b baa baao bar bbao bbb bbc bbs bl bli boa boc bok bol bom bos bot cblx ce conv cpb cs csc cscb cscw dac dbc dbs dcbl dcsc - ddf dln dnl dop dp dpro drc dsc dsm dsn - dtc dtt dwic dwls dwrs dws eos f fpva frm - fs fso gcs hbc hbcm hbco hbh hbhh hbi hbj - hbk hbm hbn hbp hbpd hbpu hbq hbs hbsc hbv - hbw hent hic hicm hico hih hihh hii hij hik - him hin hip hipd hipu hiq his hisc hiv hiw - hsc html ibc icb icp iob ipc isbc iscl kgb - kgbd kgbi kis lal log lop lp lsl mem nib - ohbr okw ola olc oll olq opr opt osbc osbr - otr ple pod pvl q sac sbc sbl scbb schb - scp scsb sct se sfp sfs skp sob sobb sohb - sop sosb sot ssc st sts t tac tbc toc - tp tqw trp ts tsc tso vbc vc viu vmll - vsc w wfc wme wn x xbt xci xlp xs + ddf dior dln dmcp dnl dop dp dpro drc dsc + dsm dsn dtc dtt duv dwic dwls dwrs dws eos + f fpva frm fs fso gcs hbc hbcm hbco hbh + hbhh hbi hbj hbk hbm hbn hbp hbpd hbpu hbq + hbs hbsc hbv hbw hent hic hicm hico hih hihh + hii hij hik him hin hip hipd hipu hiq his + hisc hiv hiw hsc html ibc icb icp iob ipc + isbc iscl kgb kgbd kgbi kis lal log lop lp + lsl mem nib ohbr okw ola olc oll olq opr + opt osbc osbr otr ple pod pvl q sac sbc + sbl scbb schb scp scsb sct se sfp sfs skp + sob sobb sohb sop sosb sot ssc st sts t + tac tbc toc tp tqw trp ts tsc tso vbc + vc viu vmll vsc vsn w wfc wme wn x + xbt xci xlp xs

    Equivalently, the prefix 'no' or 'no-' on the corresponding long names may be used.

    @@ -4629,7 +4869,7 @@

    VERSION

    -

    This man page documents perltidy version 20230912.04

    +

    This man page documents perltidy version 20230912.13

    BUG REPORTS

    @@ -4639,7 +4879,7 @@

    COPYRIGHT

    -

    Copyright (c) 2000-2023 by Steve Hancock

    +

    Copyright (c) 2000-2024 by Steve Hancock

    LICENSE

    diff --git a/docs/stylekey.html b/docs/stylekey.html index a34f3197..e70b5a65 100644 --- a/docs/stylekey.html +++ b/docs/stylekey.html @@ -28,6 +28,7 @@
  • Block Brace Vertical Tightness
  • Closing Block Brace Indentation
  • Indentation Style for Other Containers
    • +
  • Welding
  • Opening Vertical Tightness
  • Closing Token Placement
  • Stack Opening Tokens
    • @@ -41,7 +42,6 @@
  • Outdenting Long Quotes
  • Many Other Parameters
  • Example .perltidyrc files
    • -
  • Tidyview
  • Additional Information
    • @@ -57,6 +57,8 @@

    Before you begin, experiment using just perltidy filename.pl on some of your files. From the results (which you will find in files with a .tdy extension), you will get a sense of what formatting changes, if any, you'd like to make. If the default formatting is acceptable, you do not need a .perltidyrc file.

    +

    The default is based on the recommendations in the Perl style guide. It is worth noting that, although many variations are possible with the available parameters, this style has some significant advantages when small sections of code are sent to perltidy from within an editor. The reason is that perltidy can usually format a small container spanning multiple lines of code provided that the parens, braces and brackets are balanced. For the default style, the number of lines required to make a balanced selection of code is generally less than for other styles. For example, if a cuddled style is used, then an entire if-elsif- chain must be selected for formatting rather than an individual elsif block. This can be tedious and time consuming.

    +

    Use as Filter?

    Do you almost always want to run perltidy as a standard filter on just one input file? If yes, use -st and -se.

    @@ -67,13 +69,15 @@

    Do you want the maximum line length to be 80 columns? If no, use -l=n, where n is the number of columns you prefer.

    +

    When setting the maximum line length, something to consider is that perltidy will use this to decide when a list of items should be broken into multiple lines. So if it is set excessively large, lists may be so wide that they are hard to read.

    +

    Indentation in Code Blocks

    In the block below, the variable $anchor is one indentation level deep and is indented by 4 spaces as shown here:

        if ( $flag eq "a" ) {
         $anchor = $header;
-    }
    + }

    If you want to change this to be a different number n of spaces per indentation level, use -i=n.

    @@ -92,7 +96,9 @@

    Tabs

    -

    The default, and recommendation, is to represent leading whitespace with actual space characters. However, if you prefer to entab leading whitespace with one tab character for each n spaces, use -et=n. Typically, n would be 8.

    +

    The default, and recommendation, is to represent leading whitespace with actual space characters. However, if you prefer to entab leading whitespace of lines of code with one tab character for each n spaces, use -et=n. The value of n should be set to be the same as used by your display software. If there is a disagreement, then vertical alignment will not be displayed correctly.

    + +

    Please note that this number n has nothing to do with the number of spaces for one level of indentation, which is specified separately with -i=n.

    Opening Block Brace Right or Left?

    @@ -104,7 +110,7 @@ 
        if ( $flag eq "h" ) {
         $headers = 0;
-    }
    + }

    If you like opening braces on the left, like this, go to "Opening Braces Left".

    @@ -151,11 +157,11 @@ 
        if ( $flag eq "h" ) {
         $headers = 0;
-    }  
+    }
     elsif ( $flag eq "f" ) {
         $sectiontype = 3;
-    } 
-    else {    
+    }
+    else {
         print "invalid option: " . substr( $arg, $i, 1 ) . "\n";
         dohelp();
     }
    @@ -281,7 +287,7 @@ } ); -

    In this default indentation scheme, a simple formula is used to find the indentation of every line. Notice how the first 'undef' is indented 4 spaces (one level) to the right, and how 'PrintError' is indented 4 more speces (one more level) to the right.

    +

    In this default indentation scheme, a simple formula is used to find the indentation of every line. Notice how the first 'undef' is indented 4 spaces (one level) to the right, and how 'PrintError' is indented 4 more spaces (one more level) to the right.

    The alternate is to let the location of the opening paren (or square bracket, or curly brace) define the indentation, like this:

    @@ -295,9 +301,38 @@

    The first scheme is completely robust. The second scheme often looks a little nicer, but be aware that deeply nested structures it can be spoiled if the line length limit is exceeded. Also, if there are comments or blank lines within a complex structure perltidy will temporarily fall back on the default indentation scheme. You may want to try both on large sections of code to see which works best.

    +

    Also note that a disadvantage of this second scheme is that small changes in code, such as a change in the length of a sub name, can cause changes in many lines of code. For example, if we decide to change the name connect to connect_to_destination, then all of the call args would have to move right by 15 spaces. This can produce a lot of lines of differences when changes are committed.

    +

    If you prefer the first (default) scheme, no parameter is needed.

    -

    If you prefer the latter scheme, use -lp.

    +

    If you prefer the latter scheme, use --line-up-parentheses, or -lp. There is an alternative version of this option named --extended-line-up-parentheses, or -xlp which can also be used. For simplicity, the name -lp will refer to either of these options in the following text.

    + +

    Welding

    + +

    The following snippet is displayed with the default formatting:

    + +
        $opt_c = Text::CSV_XS->new(
+        {
+            binary       => 1,
+            sep_char     => $opt_c,
+            always_quote => 1,
+        }
+    );
    + +

    For this type of structure, where an inner container is nested within an outer container, we can get a more compact display with the parameter --weld-nested-containers, or -wn:

    + +
        # perltidy -wn
+    $opt_c = Text::CSV_XS->new( {
+        binary       => 1,
+        sep_char     => $opt_c,
+        always_quote => 1,
+    } );
    + +

    The name of the parameter comes from the idea that the two opening and two closing tokens have been 'welded' together to act as a single unit. The indentation spaces of the contents has also been reduced by one level.

    + +

    This is a nice transformation because it is symmetric at the opening and closing, and leaves a sort of 'sandwich' structure 0which is still quite readable.

    + +

    Some parameters available for asymmetric compressions, at just the opening or closing of complex structures, are described in the next sections.

    Opening Vertical Tightness

    @@ -483,6 +518,8 @@

    The manual shows how all of these vertical tightness controls may be applied independently to each type of non-block opening and opening token.

    +

    Also, note that --weld-nested-containers, or -wn, mentioned previously, operates like the combination of -sot and -sct and also reduces the indentation level of the contents.

    +

    Define Horizontal Tightness

    Horizontal tightness parameters define how much space is included within a set of container tokens.

    @@ -499,7 +536,7 @@ 
     $width = $col[ $j + $k ] - $col[ $j ];  # -sbt=0
  $width = $col[ $j + $k ] - $col[$j];    # -sbt=1 (default)
- $width = $col[$j + $k] - $col[$j];      # -sbt=2
    + $width = $col[$j + $k] - $col[$j]; # -sbt=2

    For curly braces, decide which of the following values of -bt=n you prefer:

    @@ -517,7 +554,7 @@

    The default is not to place a space after a function call:

    -
      myfunc( $a, $b, $c );    # default
    +
      myfunc( $a, $b, $c );    # default

    If you prefer a space:

    @@ -529,7 +566,7 @@

    The default is to place a space between only these keywords and an opening paren:

    -
       my local our and or eq ne if else elsif until unless 
+
       my local our and or eq ne if else elsif until unless
    while for foreach return switch case given when
    
 
 
    but no others. For example, the default is:
    
@@ -550,7 +587,7 @@
 
 
    If you prefer a space, like this:
    
 
-
        $i = 1 ; 
    
+
        $i = 1 ;
    
 
 
    enter -sts.
    
 
@@ -660,19 +697,11 @@
  -vt=1
  -vtc=1
    -

    Tidyview

    - -

    There is a graphical program called tidyview which you can use to read a preliminary .perltidyrc file, make trial adjustments and immediately see their effect on a test file, and then write a new .perltidyrc. You can download a copy at

    - -

    http://sourceforge.net/projects/tidyview

    -

    Additional Information

    -

    This document has covered the main parameters. Many more parameters are available for special purposes and for fine-tuning a style. For complete information see the perltidy manual http://perltidy.sourceforge.net/perltidy.html

    - -

    For an introduction to using perltidy, see the tutorial http://perltidy.sourceforge.net/tutorial.html

    +

    For further information see the perltidy documentation at Sourceforge or at metacpan. or at GitHub

    -

    Suggestions for improving this document are welcome and may be sent to perltidy at users.sourceforge.net

    +

    The source code is maintained at GitHub.

    diff --git a/docs/tutorial.html b/docs/tutorial.html index 4e11efc4..73ea4428 100644 --- a/docs/tutorial.html +++ b/docs/tutorial.html @@ -17,14 +17,18 @@
  • A First Test
  • Indentation
  • Input Flags
    • -
  • Line Length and Continuation Indentation.
    • +
  • Continuation Indentation.
    • +
  • Line Length
  • Tabs or Spaces?
  • Input/Output Control
  • Style Variations
  • Configuration Files
  • Error Reporting
    • -
  • The Log File
  • Using Perltidy as a Filter on Selected Text from an Editor
    • +
  • Adding Blank Lines to Control List Formatting
    • +
  • Adding Blank Lines to Control Vertical Alignment
    • +
  • Format Skipping
    • +
  • Finding Unused Variables
  • Writing an HTML File
  • Summary
    • @@ -69,7 +73,7 @@ print "I think that's the problem\n"; } -

    You'll notice an immediate style change from the "cuddled-else" style of the original to the default "non-cuddled-else" style. This is because perltidy has to make some kind of default selection of formatting options, and this default tries to follow the suggestions in the perlstyle man pages.

    +

    You'll notice an immediate style change from the "cuddled-else" style of the original to the default "non-cuddled-else" style. This is because perltidy has to make some kind of default selection of formatting options, and this default tries to follow the suggestions in the perlstyle man pages.

    If you prefer the original "cuddled-else" style, don't worry, you can indicate that with a -ce flag. So if you rerun with that flag

    @@ -101,7 +105,7 @@

    The short forms are convenient for entering parameters by hand, whereas the long forms, though often ridiculously long, are self-documenting and therefore useful in configuration scripts. You may use either one or two dashes ahead of the parameters. Also, the '=' sign is optional, and may be a single space instead. However, the value of a parameter must NOT be adjacent to the flag, like this -i3 (WRONG). Also, flags must be input separately, never bundled together.

    -

    Line Length and Continuation Indentation.

    +

    Continuation Indentation.

    If you change the indentation spaces you will probably also need to change the continuation indentation spaces with the parameter -ci=n. The continuation indentation is the extra indentation -- 2 spaces by default -- given to that portion of a long line which has been placed below the start of a statement. For example:

    @@ -109,7 +113,9 @@ unless sysread( $impl->{file}, $element, $impl->{group} ) and truncate( $impl->{file}, $new_end ); -

    There is no fixed rule for setting the value for -ci=n, but it should probably not exceed one-half of the number of spaces of a full indentation level.

    +

    It works well to use a value n equal to one-half the number of spaces to a full indentation level. If it is set equal to the full indentation level, then formatting will be improved by also setting --extended-continuation-indentation, or -xci. The manual has some examples.

    + +

    Line Length

    In the above snippet, the statement was broken into three lines. The actual number is governed by a parameter, the maximum line length, as well as by what perltidy considers to be good break points. The maximum line length is 80 characters by default. You can change this to be any number n with the -l=n flag. Perltidy tries to produce lines which do not exceed this length, and it does this by finding good break points. For example, the above snippet would look like this with perltidy -l=40:

    @@ -150,17 +156,21 @@

    What happens in this case is that the shell takes care of the redirected input files, '<somefile.pl', and so perltidy never sees the filename. Therefore, it knows to use the standard input and standard output channels.

    +

    If you ever find that you enter perltidy and nothing seems to happen, it could be that you did not give it source to work on. So in that case it is waiting for input from the standard input, which is probably the keyboard.

    +

    If you are executing perltidy on a file and want to force the output to standard output, rather than create a .tdy file, you can indicate this with the flag -st, like this:

     perltidy somefile.pl -st >otherfile.pl
    +

    If you just enter

    +

    You can also control the name of the output file with the -o flag, like this:

     perltidy testfile.pl -o=testfile.new.pl

    Style Variations

    -

    Perltidy has to make some kind of default selection of formatting options, and its choice is to try to follow the suggestions in the perlstyle man pages. Many programmers more or less follow these suggestions with a few exceptions. In this section we will look at just a few of the most commonly used style parameters. Later, you may want to systematically develop a set of style parameters with the help of the perltidy stylekey web page at http://perltidy.sourceforge.net/stylekey.html

    +

    Perltidy has to make some kind of default selection of formatting options, and its choice is to try to follow the suggestions in the perlstyle man pages. The default parameter settings will produce quite readable code, and should be sufficient for many purposes. Many programmers more or less follow these suggestions with a few exceptions. In this section we will look at just a few of the most commonly used style parameters. Later, you may want to systematically develop a set of style parameters with the help of the perltidy stylekey web page at http://perltidy.sourceforge.net/stylekey.html

    @@ -188,42 +198,6 @@ print "I think that's the problem\n"; } - -
    -lp, Lining up with parentheses
    -
    - -

    The -lp parameter can enhance the readability of lists by adding extra indentation. Consider:

    - -
            %romanNumerals = (
-            one   => 'I',
-            two   => 'II',
-            three => 'III',
-            four  => 'IV',
-            five  => 'V',
-            six   => 'VI',
-            seven => 'VII',
-            eight => 'VIII',
-            nine  => 'IX',
-            ten   => 'X'
-        );
    - -

    With the -lp flag, this is formatted as:

    - -
            %romanNumerals = (
-                           one   => 'I',
-                           two   => 'II',
-                           three => 'III',
-                           four  => 'IV',
-                           five  => 'V',
-                           six   => 'VI',
-                           seven => 'VII',
-                           eight => 'VIII',
-                           nine  => 'IX',
-                           ten   => 'X'
-                         );
    - -

    which is preferred by some. (I've actually used -lp and -cti=1 to format this block. The -cti=1 flag causes the closing paren to align vertically with the opening paren, which works well with the -lp indentation style). An advantage of -lp indentation are that it displays lists nicely. A disadvantage is that deeply nested lists can require a long line length.

    -
    -bt,-pt,-sbt: Container tightness
    @@ -279,7 +253,7 @@

    Here is what testfile.pl.ERR contains:

     10:    final indentation level: 1
- 
+
  Final nesting depth of '{'s is 1
  The most recent un-matched '{' is on line 6
  6: } elsif ($temperature < 68) {{
@@ -301,49 +275,93 @@
 
 
    This kind of error can otherwise be hard to find.
    
 
-
    The Log File
    
+
    Using Perltidy as a Filter on Selected Text from an Editor
    
 
-
    One last topic that needs to be touched upon concerns the .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.
    
+
    Most programmer's editors allow a selected group of lines to be passed through an external filter. Perltidy has been designed to work well as a filter, and it is well worthwhile learning the appropriate commands to do this with your editor. This means that you can enter a few keystrokes and watch a block of text get reformatted. If you are not doing this, you are missing out of a lot of fun! You may want to supply the -q flag to prevent error messages regarding incorrect syntax, since errors may be obvious in the indentation of the reformatted text. This is entirely optional, but if you do not use the -q flag, you will need to use the undo keys in case an error message appears on the screen.
    
 
-
    There are a couple of ways to ask perltidy to save a log file. To create a relatively sparse log file, use
    
+
    For example, within the vim editor it is only necessary to select the text by any of the text selection methods, and then issue the command !perltidy in command mode. Thus, an entire file can be formatted using
    
 
-
     perltidy -log testfile.pl
    
+
     :%!perltidy -q
    
 
-
    and for a verbose log file, use
    
+
    or, without the -q flag, just
    
 
-
     perltidy -g testfile.pl
    
+
     :%!perltidy
    
 
-
    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.
    
+
    It isn't necessary to format an entire file, however. Perltidy will probably work well as long as you select blocks of text whose braces, parentheses, and square brackets are properly balanced. You can even format an elsif block without the leading if block, as long as the text you select has all braces balanced.
    
 
-
    So returning to our example, lets force perltidy to save a verbose log file by issuing the following command
    
+
    For the emacs editor, first mark a region and then pipe it through perltidy. For example, to format an entire file, select it with C-x h and then pipe it with M-1 M-| and then perltidy. The numeric argument, M-1 causes the output from perltidy to replace the marked text. See "GNU Emacs Manual" for more information, http://www.gnu.org/manual/emacs-20.3/html_node/emacs_toc.html
    
 
-
     perltidy -g testfile.pl
    
+
    If you have difficulty with an editor, try the -st flag, which will force perltidy to send output to standard output. This might be needed, for example, if the editor passes text to perltidy as temporary filename instead of through the standard input. If this works, you might put the -st flag in your .perltidyrc file.
    
 
-
    You will find that a file named testfile.pl.LOG has been created in your directory.
    
+
    After you get your editor and perltidy successfully talking to each other, try formatting a snippet of code with a brace error to see what happens. (Do not use the quiet flag, -q, for this test). Perltidy will send one line starting with ## to standard error output. Your editor may either display it at the top of the reformatted text or at 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.
    
 
-
    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.
    
+
    Adding Blank Lines to Control List Formatting
    
 
-
    Using Perltidy as a Filter on Selected Text from an Editor
    
+
    In the following example, the return list of five values has been automatically formatted over two lines:
    
 
-
    Most programmer's editors allow a selected group of lines to be passed through an external filter. Perltidy has been designed to work well as a filter, and it is well worthwhile learning the appropriate commands to do this with your editor. This means that you can enter a few keystrokes and watch a block of text get reformatted. If you are not doing this, you are missing out of a lot of fun! You may want to supply the -q flag to prevent error messages regarding incorrect syntax, since errors may be obvious in the indentation of the reformatted text. This is entirely optional, but if you do not use the -q flag, you will need to use the undo keys in case an error message appears on the screen.
    
+
            my (
+            $rinput_string,        $is_encoded_data, $decoded_input_as,
+            $encoding_log_message, $length_function,
+        ) = $self->get_decoded_string_buffer($input_file);
    
 
-
    For example, within the vim editor it is only necessary to select the text by any of the text selection methods, and then issue the command !perltidy in command mode. Thus, an entire file can be formatted using
    
+
    As a general rule, if there are no blank lines or comments between the opening and closing parens, as in this example, perltidy will use an automated rule to set line breaks. Otherwise, it will keep the line breaks unchanged. So by inserting a blank line somewhere within a list we can 'freeze' the line breaks to be the way we would like.
    
 
-
     :%!perltidy -q
    
+
    For example, here is the above list with a line break at every comma, and with a blank line to prevent perltidy from changing it:
    
 
-
    or, without the -q flag, just
    
+
            my (
+            $rinput_string,
+            $is_encoded_data,
+            $decoded_input_as,
+            $encoding_log_message,
+            $length_function,
 
-
     :%!perltidy
    
+        ) = $self->get_decoded_string_buffer($input_file);
    
 
-
    It isn't necessary to format an entire file, however. Perltidy will probably work well as long as you select blocks of text whose braces, parentheses, and square brackets are properly balanced. You can even format an elsif block without the leading if block, as long as the text you select has all braces balanced.
    
+
    An easy way to switch to a single column list such as this is to select the list from within an editor and reformat with with --maximum-fields-per-table=1, or -mft=1. This will format the list in a single column. Then insert a blank line to keep this format.
    
 
-
    For the emacs editor, first mark a region and then pipe it through perltidy. For example, to format an entire file, select it with C-x h and then pipe it with M-1 M-| and then perltidy. The numeric argument, M-1 causes the output from perltidy to replace the marked text. See "GNU Emacs Manual" for more information, http://www.gnu.org/manual/emacs-20.3/html_node/emacs_toc.html
    
+
    Adding Blank Lines to Control Vertical Alignment
    
 
-
    If you have difficulty with an editor, try the -st flag, which will force perltidy to send output to standard output. This might be needed, for example, if the editor passes text to perltidy as temporary filename instead of through the standard input. If this works, you might put the -st flag in your .perltidyrc file.
    
+
    Vertical alignment refers to the insertion of blank spaces to align tokens which successive lines have in common, such as the = here:
    
 
-
    If you have some tips for making perltidy work with your editor, and are willing to share them, please email me (see below) and I'll try to incorporate them in this document or put up a link to them.
    
+
        my $self            = shift;
+    my $debug_file      = $self->{_debug_file};
+    my $is_encoded_data = $self->{_is_encoded_data};
    
 
-
    After you get your editor and perltidy successfully talking to each other, try formatting a snippet of code with a brace error to see what happens. (Do not use the quiet flag, -q, for this test). Perltidy will send one line starting with ## to standard error output. Your editor may either display it at the top of the reformatted text or at 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.
    
+
    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;
+
+    my $debug_file      = $self->{_debug_file};
+    my $is_encoded_data = $self->{_is_encoded_data};
    
+
+
    Format Skipping
    
+
+
    To have perltidy leave existing formatting unchanged, surround the lines to be skipped with special comments like this:
    
+
+
     #<<<
+    my @list = (1,
+                1, 1,
+                1, 2, 1,
+                1, 3, 3, 1,
+                1, 4, 6, 4, 1,);
+ #>>>
    
+
+
    A related comment control is --code-skipping, indicated with '#<<V>. and '#>>V>', which simply passes lines of code to the output without tokenization. This is useful for some extended syntaxes. Another is --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.
    
+
+
    Finding Unused Variables
    
+
+
    Perltidy has several parameters which can assist in locating problems in code. One of these is -dump-unusual-variables, or -duv. It will scan a file and produce a list of unused, reused, and certain other lexical variables of interest. To use it to analyze a file named testfile.pl enter:
    
+
+
     perltidy -duv testfile.pl >tmp.txt
    
+
+
    The information will be dumped to the standard output, tmp.txt in this example, 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 --warn-missing-else and --dump-block-summary. The manual has further information.
    
 
 
    Writing an HTML File
    
 
@@ -353,7 +371,7 @@
 
 
    which will produce a file testfile.pl.html. There are many parameters available for adjusting the appearance of an HTML file, but a very easy way is to just write the HTML file with this simple command and then edit the stylesheet which is embedded at its top.
    
 
-
    One important thing to know about the -html flag is that perltidy can either send its output to its beautifier or to its HTML writer, but (unfortunately) not both in a single run. So the situation can be represented like this:
    
+
    One important thing to know about the -html flag is that perltidy can either send its output to its beautifier or to its HTML writer, but not both in a single run. So the situation can be represented like this:
    
 
 
                      ------------
                   |          |     --->beautifier--> testfile.pl.tdy
@@ -361,17 +379,17 @@
                   |          |     --->HTML -------> testfile.pl.html
                   ------------
    
 
-
    And in the future, there may be more output filters. So if you would like to both beautify a script and write it to HTML, you need to do it in two steps.
    
+
    So if you would like to both beautify a script and write it to HTML, you need to do it in two steps.
    
 
 
    Summary
    
 
 
    That's enough to get started using perltidy. When you are ready to create a .perltidyrc file, you may find it helpful to use the stylekey page as a guide at http://perltidy.sourceforge.net/stylekey.html
    
 
-
    Many additional special features and capabilities can be found in the manual pages for perltidy at http://perltidy.sourceforge.net/perltidy.html
    
+
    We hope that perltidy makes perl programming a little more fun.
    
 
-
    We hope that perltidy makes perl programming a little more fun. Please check the perltidy web site http://perltidy.sourceforge.net occasionally for updates.
    
+
    Further documentation can be found at the web site at GitHub or at Sourceforge or at metacpan
    
 
-
    The author may be contacted at perltidy at users.sourceforge.net.
    
+
    Issues can be reported at GitHub
    
 
 
 
diff --git a/lib/Perl/Tidy.pm b/lib/Perl/Tidy.pm
index 0a9b3338..9fe355e2 100644
--- a/lib/Perl/Tidy.pm
+++ b/lib/Perl/Tidy.pm
@@ -131,7 +131,7 @@ BEGIN {
     # then the Release version must be bumped, and it is probably past time for
     # a release anyway.
 
-    $VERSION = '20230912.12';
+    $VERSION = '20230912.13';
 } ## end BEGIN
 
 sub DESTROY {
diff --git a/lib/Perl/Tidy.pod b/lib/Perl/Tidy.pod
index 8599a1f3..47eb9efc 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 20230912.12
+This man page documents Perl::Tidy version 20230912.13
 
 =head1 LICENSE
 
diff --git a/lib/Perl/Tidy/Debugger.pm b/lib/Perl/Tidy/Debugger.pm
index 3a004279..d2219483 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 = '20230912.12';
+our $VERSION = '20230912.13';
 
 use constant EMPTY_STRING => q{};
 use constant SPACE        => q{ };
diff --git a/lib/Perl/Tidy/Diagnostics.pm b/lib/Perl/Tidy/Diagnostics.pm
index 6f443b4e..1053132a 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 = '20230912.12';
+our $VERSION = '20230912.13';
 
 use constant EMPTY_STRING => q{};
 
diff --git a/lib/Perl/Tidy/FileWriter.pm b/lib/Perl/Tidy/FileWriter.pm
index 6527fe63..a53340ec 100644
--- a/lib/Perl/Tidy/FileWriter.pm
+++ b/lib/Perl/Tidy/FileWriter.pm
@@ -16,7 +16,7 @@
 package Perl::Tidy::FileWriter;
 use strict;
 use warnings;
-our $VERSION = '20230912.12';
+our $VERSION = '20230912.13';
 
 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 2dda478b..aff0260f 100644
--- a/lib/Perl/Tidy/Formatter.pm
+++ b/lib/Perl/Tidy/Formatter.pm
@@ -75,7 +75,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 = '20230912.12';
+our $VERSION = '20230912.13';
 
 # 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 2a2de877..85358dba 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 = '20230912.12';
+our $VERSION = '20230912.13';
 
 use Carp;
 use English qw( -no_match_vars );
diff --git a/lib/Perl/Tidy/IOScalar.pm b/lib/Perl/Tidy/IOScalar.pm
index 12350dbb..0faa728d 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 = '20230912.12';
+our $VERSION = '20230912.13';
 
 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 fdc46d18..24a21244 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 = '20230912.12';
+our $VERSION = '20230912.13';
 
 use constant DEVEL_MODE => 0;
 
diff --git a/lib/Perl/Tidy/IndentationItem.pm b/lib/Perl/Tidy/IndentationItem.pm
index 0f5852c4..bd839a3a 100644
--- a/lib/Perl/Tidy/IndentationItem.pm
+++ b/lib/Perl/Tidy/IndentationItem.pm
@@ -9,7 +9,7 @@ package Perl::Tidy::IndentationItem;
 use strict;
 use warnings;
 
-our $VERSION = '20230912.12';
+our $VERSION = '20230912.13';
 
 BEGIN {
 
diff --git a/lib/Perl/Tidy/Logger.pm b/lib/Perl/Tidy/Logger.pm
index 27722cbf..860e1f6b 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 = '20230912.12';
+our $VERSION = '20230912.13';
 use Carp;
 use English qw( -no_match_vars );
 
diff --git a/lib/Perl/Tidy/Tokenizer.pm b/lib/Perl/Tidy/Tokenizer.pm
index 17b058ce..7e3a651c 100644
--- a/lib/Perl/Tidy/Tokenizer.pm
+++ b/lib/Perl/Tidy/Tokenizer.pm
@@ -33,7 +33,7 @@ use strict;
 use warnings;
 use English qw( -no_match_vars );
 
-our $VERSION = '20230912.12';
+our $VERSION = '20230912.13';
 
 use Carp;
 
diff --git a/lib/Perl/Tidy/VerticalAligner.pm b/lib/Perl/Tidy/VerticalAligner.pm
index c6ea852c..9922e02c 100644
--- a/lib/Perl/Tidy/VerticalAligner.pm
+++ b/lib/Perl/Tidy/VerticalAligner.pm
@@ -5,7 +5,7 @@ use Carp;
 
 { #<<< A non-indenting brace to contain all lexical variables
 
-our $VERSION = '20230912.12';
+our $VERSION = '20230912.13';
 use English qw( -no_match_vars );
 use Perl::Tidy::VerticalAligner::Alignment;
 use Perl::Tidy::VerticalAligner::Line;
@@ -4881,7 +4881,7 @@ EOM
     my @unsigned_subgroups;
     my $ix_last_negative = $ix_first - 1;
     foreach my $ix ( @{$rsigned_lines} ) {
-        my $Nu = $ix - $ix_last_negative;
+        my $Nu = $ix - $ix_last_negative - 1;
         if ( $Nu > 0 && $Nu <= $rOpts_valign_signed_numbers_limit ) {
             push @unsigned_subgroups, [ $ix_last_negative + 1, $ix - 1 ];
         }
diff --git a/lib/Perl/Tidy/VerticalAligner/Alignment.pm b/lib/Perl/Tidy/VerticalAligner/Alignment.pm
index 62e8aa91..a217ed2b 100644
--- a/lib/Perl/Tidy/VerticalAligner/Alignment.pm
+++ b/lib/Perl/Tidy/VerticalAligner/Alignment.pm
@@ -9,7 +9,7 @@ package Perl::Tidy::VerticalAligner::Alignment;
 use strict;
 use warnings;
 
-our $VERSION = '20230912.12';
+our $VERSION = '20230912.13';
 
 sub new {
     my ( $class, $rarg ) = @_;
diff --git a/lib/Perl/Tidy/VerticalAligner/Line.pm b/lib/Perl/Tidy/VerticalAligner/Line.pm
index 58a802f3..0d236b24 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;
 
-our $VERSION = '20230912.12';
+our $VERSION = '20230912.13';
 use English qw( -no_match_vars );
 
 sub AUTOLOAD {