# Perltidy Change Log
+## 2022 06 13
+
+ - No significant bugs have been found since the last release but users
+ of programs which call the Perl::Tidy module should note the first
+ item below, which changes a default setting. The main change to
+ existing formatting is the second item below, which adds vertical
+ alignment to 'use' statements.
+
+ - The flag --encode-output-strings, or -eos, is now set 'on' by default.
+ This has no effect on the use of the 'perltidy' binary script, but could
+ change the behavior of some programs which use the Perl::Tidy module on
+ files encoded in UTF-8. If any problems are noticed, an emergency fix
+ can be made by reverting to the old default by setting -neos. For
+ an explanation of why this change needs to be made see:
+
+ https://github.com/perltidy/perltidy/issues/92
+
+ https://github.com/perltidy/perltidy/blob/master/docs/eos_flag.md
+
+ - Added vertical alignment for qw quotes and empty parens in 'use'
+ statements (see issue #git 93). This new alignment is 'on' by default
+ and will change formatting as shown below. If this is not wanted it can
+ be turned off with the parameter -vxl='q' (--valign-exclude-list='q').
+
+ # old default, or -vxl='q'
+ use Getopt::Long qw(GetOptions);
+ use Fcntl qw(O_RDONLY O_WRONLY O_EXCL O_CREAT);
+ use Symbol qw(gensym);
+ use Exporter ();
+
+ # new default
+ use Getopt::Long qw(GetOptions);
+ use Fcntl qw(O_RDONLY O_WRONLY O_EXCL O_CREAT);
+ use Symbol qw(gensym);
+ use Exporter ();
+
+ - The parameter -kbb (--keep-break-before) now ignores a request to break
+ before an opening token, such as '('. Likewise, -kba (--keep-break-after)
+ now ignores a request to break after a closing token, such as ')'. This
+ change was made to avoid a rare instability discovered in random testing.
+
+ - Previously, if a -dsc command was used to delete all side comments,
+ then any special side comments for controlling non-indenting braces got
+ deleted too. Now, these control side comments are retained when -dsc is
+ set unless a -nnib (--nonon-indenting-braces) flag is also set to
+ deactivate them.
+
+ - This version runs about 10 percent faster on large files than the previous
+ release due to optimizations made with the help of Devel::NYTProf. Much
+ of the gain came from faster processing of blank tokens and comments.
+
+ - This version of perltidy was stress-tested for many cpu hours with
+ random input parameters. No failures to converge, internal fault checks,
+ undefined variable references or other irregularities were seen.
+
+## 2022 02 17
+
+ - A new flag, --encode-output-strings, or -eos, has been added to resolve
+ issue git #83. This issue involves the interface between Perl::Tidy and
+ calling programs, and Code::TidyAll (tidyall) in particular. The problem
+ is that perltidy by default returns decoded character strings, but
+ tidyall expects encoded strings. This flag provides a fix for that.
+
+ So, tidyall users who process encoded (utf8) files should update to this
+ version of Perl::Tidy and use -eos for tidyall. For further info see:
+
+ https://github.com/houseabsolute/perl-code-tidyall/issues/84, and
+ https://github.com/perltidy/perltidy/issues/83
+
+ If there are other applications having utf8 problems at the interface
+ with Perl::Tidy, this flag probably may need to be set.
+
+ - The default value of the new flag, --encode-output-strings, -eos, is currently
+ -neos BUT THIS MAY CHANGE in a future release because the current
+ default is inconvenient. So authors of programs which receive character
+ strings back from Perl::Tidy should set this flag, if necessary,
+ to avoid any problems when the default changes. For more information see the
+ above links and the Perl::Tidy man pages for example coding.
+
+ - The possible values of the string 's' for the flag '--character-encoding=s'
+ have been limited to 'utf8' (or UTF-8), 'none', or 'guess'. Previously an
+ arbitrary encoding could also be specified, but as a result of discussions
+ regarding git #83 it became clear that this could cause trouble
+ since the output encoding was still restricted to UTF-8. Users
+ who need to work in other encodings can write a short program calling
+ Perl::Tidy with pre- and post-processing to handle encoding/decoding.
+
+ - A new flag --break-after-labels=i, or -bal=i, was added for git #86. This
+ controls line breaks after labels, to provide a uniform style, as follows:
+
+ -bal=0 follows the input line breaks [DEFAULT]
+ -bal=1 always break after a label
+ -bal=2 never break after a label
+
+ For example:
+
+ # perltidy -bal=1
+ INIT:
+ {
+ $xx = 1.234;
+ }
+
+ # perltidy -bal=2
+ INIT: {
+ $xx = 1.234;
+ }
+
+ - Fix issue git #82, an error handling something like ${bareword} in a
+ possible indirect object location. Perl allows this, now perltidy does too.
+
+ - The flags -kbb=s or --keep-old-breakpoints-before=s, and its counterpart
+ -kba=s or --keep-old-breakpoints-after=s have expanded functionality
+ for the container tokens: { [ ( } ] ). The updated man pages have
+ details.
+
+ - Two new flags have been added to provide finer vertical alignment control,
+ --valign-exclusion-list=s (-vxl=s) and --valign-inclusion-list=s (-vil=s).
+ This has been requested several times, most recently in git #79, and it
+ finally got done. For example, -vil='=>' means just align on '=>'.
+
+ - A new flag -gal=s, --grep-alias-list=s, has been added as suggested in
+ git #77. This allows code blocks passed to list operator functions to
+ be formatted in the same way as a code block passed to grep, map, or sort.
+ By default, the following list operators in List::Util are included:
+
+ all any first none notall reduce reductions
+
+ They can be changed with the flag -gaxl=s, -grep-alias-exclusion-list=s
+
+ - A new flag -xlp has been added which can be set to avoid most of the
+ limitations of the -lp flag regarding side comments, blank lines, and
+ code blocks. See the man pages for more info. This fixes git #64 and git #74.
+ The older -lp flag still works.
+
+ - A new flag -lpil=s, --line-up-parentheses-inclusion-list=s, has been added
+ as an alternative to -lpxl=s, --line-up-parentheses-exclusion-list=s.
+ It supplies equivalent information but is much easier to describe and use.
+ It works for both the older -lp version and the newer -xlp.
+
+ - The coding for the older -lp flag has been updated to avoid some problems
+ and limitations. The new coding allows the -lp indentation style to
+ mix smoothly with the standard indentation in a single file. Some problems
+ where -lp and -xci flags were not working well together have been fixed, such
+ as happened in issue rt140025. As a result of these updates some minor
+ changes in existing code using the -lp style may occur.
+
+ - This version of perltidy was stress-tested for many cpu hours with
+ random input parameters. No failures to converge, internal fault checks,
+ undefined variable references or other irregularities were seen.
+
+ - Numerous minor fixes have been made, mostly very rare formatting
+ instabilities found in random testing.
+
+## 2021 10 29
+
+ - No significant bugs have been found since the last release, but several
+ minor issues have been fixed. Vertical alignment has been improved for
+ lists of call args which are not contained within parens (next item).
+
+ - Vertical alignment of function calls without parens has been improved with
+ the goal of making vertical alignment essentially the same with or
+ without parens around the call args. Some examples:
+
+ # OLD
+ mkTextConfig $c, $x, $y, -anchor => 'se', $color;
+ mkTextConfig $c, $x + 30, $y, -anchor => 's', $color;
+ mkTextConfig $c, $x + 60, $y, -anchor => 'sw', $color;
+ mkTextConfig $c, $x, $y + 30, -anchor => 'e', $color;
+
+ # NEW
+ mkTextConfig $c, $x, $y, -anchor => 'se', $color;
+ mkTextConfig $c, $x + 30, $y, -anchor => 's', $color;
+ mkTextConfig $c, $x + 60, $y, -anchor => 'sw', $color;
+ mkTextConfig $c, $x, $y + 30, -anchor => 'e', $color;
+
+ # OLD
+ is id_2obj($id), undef, "unregistered object not retrieved";
+ is scalar keys %$ob_reg, 0, "object registry empty";
+ is register($obj), $obj, "object returned by register";
+ is scalar keys %$ob_reg, 1, "object registry nonempty";
+ is id_2obj($id), $obj, "registered object retrieved";
+
+ # NEW
+ is id_2obj($id), undef, "unregistered object not retrieved";
+ is scalar keys %$ob_reg, 0, "object registry empty";
+ is register($obj), $obj, "object returned by register";
+ is scalar keys %$ob_reg, 1, "object registry nonempty";
+ is id_2obj($id), $obj, "registered object retrieved";
+
+ This will cause some changes in alignment, hopefully for the better,
+ particularly in test code which often uses numerous parenless function
+ calls with functions like 'ok', 'is', 'is_deeply', ....
+
+ - Two new parameters were added to control the block types to which the
+ -bl (--opening-brace-on-new-line) flag applies. The new parameters are
+ -block-left-list=s, or -bll=s, and --block-left-exclusion-list=s,
+ or -blxl=s. Previously the -bl flag was 'hardwired' to apply to
+ nearly all blocks. The default values of the new parameters
+ retain the the old default behavior but allow it to be changed.
+
+ - The default behavior of the -bli (-brace-left-and-indent) flag has changed
+ slightly. Previously, if you set -bli, then the -bl flag would also
+ automatically be set. Consequently, block types which were not included
+ in the default list for -bli would get -bl formatting. This is no longer done,
+ and these two styles are now controlled independently. The manual describes
+ the controls. If you want to recover the exact previous default behavior of
+ the -bli then add the -bl flag.
+
+ - A partial fix was made for issue for git #74. The -lp formatting style was
+ being lost when a one-line anonymous sub was followed by a closing brace.
+
+ - Fixed issue git #73, in which the -nfpva flag was not working correctly.
+ Some unwanted vertical alignments of spaced function perens
+ were being made.
+
+ - Updated the man pages to clarify the flags -valign and -novalign
+ for turning vertical alignment on and off (issue git #72).
+ Added parameters -vc -vsc -vbc for separately turning off vertical
+ alignment of code, side comments and block comments.
+
+ - Fixed issue git #68, where a blank line following a closing code-skipping
+ comment, '#>>V', could be lost.
+
+ - This version runs 10 to 15 percent faster on large files than the
+ previous release due to optimizations made with the help of NYTProf.
+
+ - This version of perltidy was stress-tested for many cpu hours with
+ random input parameters. No instabilities, internal fault checks,
+ undefined variable references or other irregularities were seen.
+
+ - Numerous minor fixes have been made, mostly very rare formatting instabilities
+ found in random testing. An effort has been made to minimize changes to
+ existing formatting that these fixes produce, but occasional changes
+ may occur. Many of these updates are listed at:
+
+ https://github.com/perltidy/perltidy/blob/master/local-docs/BugLog.pod
+
## 2021 07 17
- This release is being made mainly because of the next item, in which an
comment '#<<V' which is not terminated with a closing comment '#>>V'. This
makes code-skipping and format-skipping behave in a similar way: an
opening comment without a corresponding closing comment will cause
- the rest of a file to be skipped. If there is a question about which lines
- are skipped, a .LOG file can be produced with the -g flag and it will have
+ the rest of a file to be skipped. If there is a question about which lines
+ are skipped, a .LOG file can be produced with the -g flag and it will have
this information.
- Removed the limit on -ci=n when -xci is set, reference: rt #136415.
flags and the --line-up-parens flag.
- Fixed issue git #54 regarding irregular application of the --break-before-paren
- and similar --break-before-xxx flags, in which lists without commas were not
+ and similar --break-before-xxx flags, in which lists without commas were not
being formatted according to these flags.
- - Fixed issue git #53. A flag was added to turn off alignment of spaced function
+ - Fixed issue git #53. A flag was added to turn off alignment of spaced function
parens. If the --space-function-paren, -sfp flag is set, a side-effect is that the
spaced function parens may get vertically aligned. This can be undesirable,
so a new parameter '--function-paren-vertical-alignment', or '-fpva', has been
- added to turn this vertical alignment off. The default is '-fpva', so that
+ added to turn this vertical alignment off. The default is '-fpva', so that
existing formatting is not changed. Use '-nfpva' to turn off unwanted
vertical alignment. To illustrate the possibilities:
# perltidy -sfp
myfun ( $aaa, $b, $cc );
mylongfun ( $a, $b, $c );
-
+
# perltidy -sfp -nfpva
myfun ( $aaa, $b, $cc );
mylongfun ( $a, $b, $c );
## 2020 12 01
- - This release is being made primarily to make available a several new formatting
- parameters, in particular -xci, -kbb=s, -kba=s, and -wnxl=s. No significant
- bugs have been found since the previous release, but numerous minor issues have
+ - This release is being made primarily to make available a several new formatting
+ parameters, in particular -xci, -kbb=s, -kba=s, and -wnxl=s. No significant
+ bugs have been found since the previous release, but numerous minor issues have
been found and fixed as listed below.
- This version is about 20% faster than the previous version due to optimizations
- Fixed issue git #45, -vtc=n flag was ignored when -wn was set.
- - implement request RT #133649, delete-old-newlines selectively. Two parameters,
+ - implement request RT #133649, delete-old-newlines selectively. Two parameters,
-kbb=s or --keep-old-breakpoints-before=s, and
-kba=s or --keep-old-breakpoints-after=s
were added to request that old breakpoints be kept before or after
selected token types. For example, -kbb='=>' means that newlines before
fat commas should be kept.
-
+
- Fix git #44, fix exit status for assert-tidy/untidy. The exit status was
always 0 for --assert-tidy if the user had turned off all error messages with
the -quiet flag. This has been fixed.