perltidy Files

## Changes from version 20230912 to version 20240202

    - 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.
      This can be useful for developing a uniform style for selected operators.
      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

      This is very useful for locating problem areas and bugs in code.

    - 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 maximum or
      maximum range is exceeded, the new default behavior is to write a
      warning message, reset the value to its default setting, and continue.
      This default behavior can be changed with the new 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 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'
      or '$class' arg.

    - Added flag --space-signature-paren=n, or -ssp=n (issue git #125).
      This flag works the same as the existing flag --space-prototype-paren=n
      except that it applies to the space before the opening paren of a sub
      signature instead of a sub prototype.  Previously, there was no control
      over this (a space always occurred). For example, given the following
      line:

        sub circle( $xc, $yc, $rad );

      The following results can now be obtained, according to the value of n:

        sub circle( $xc, $yc, $rad );   # n=0 [no space]
        sub circle( $xc, $yc, $rad );   # n=1 [default; same as input]
        sub circle ( $xc, $yc, $rad );  # n=2 [space]

      The spacing in previous versions of perltidy corresponded to n=2 (always
      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
      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.

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

    - When braces are detected to be unbalanced, an attempt is made to
      localize the error by comparing the indentation at closing braces
      with their actual nesting levels. This can be useful for files which
      have previously been formatted by perltidy. To illustrate, a test was
      made in which the closing brace at line 30644 was commented out in
      a file with a total of over 62000 lines.  The new error message is

        Final nesting depth of '{'s is 1
        The most recent un-matched '{' is on line 6858
        ...
        Table of nesting level differences at closing braces.
        This might help localize brace errors if the file was previously formatted.
        line:  (brace level) - (level expected from old indentation)
        30643: 0
        30645: 1

      Previously, the error file only indicated that the error in this case
      was somewhere after line 6858, so the new table is very helpful. Closing
      brace indentation is checked because it is unambiguous and can be done
      very efficiently.

    - The -DEBUG option no longer automatically also writes a .LOG file.
      Use --show-options if the .LOG file is needed.

    - The run time of this version with all new options in use is no greater
      than that of the previous version thanks to optimization work.