# Perltidy Change Log
+## 2021 07 17
+
+ - This release is being made mainly because of the next item, in which an
+ error message about an uninitialized value error message could be produced
+ in certain cases when format-skipping is used. The error message was
+ annoying but harmless to formatting.
+
+ - Fixed an undefined variable message, see git #67. When a format skipping
+ comment '#<<' is placed before the first line of code in a script, a
+ message 'Use of uninitialized value $Ktoken_vars in numeric ...' can
+ occur.
+
+ - A warning will no longer be given if a script has an opening code-skipping
+ 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
+ this information.
+
+ - Removed the limit on -ci=n when -xci is set, reference: rt #136415.
+ This update removes a limit in the previous two versions in which the
+ value of -ci=n was limited to the value of -i=n when -xci was set.
+ This limit had been placed to avoid some formatting instabilities,
+ but recent coding improvements allow the limit to be removed.
+
+ - The -wn and -bbxx=n flags were not working together correctly. This has
+ been fixed.
+
+ - This version may produce occasional differences in formatting compared to
+ previous versions, mainly for lines which are near the specified line
+ length limit. This is due to ongoing efforts to eliminate edge cases of
+ formatting instability.
+
+ - Numerous minor fixes have been made. A complete list is at:
+
+ https://github.com/perltidy/perltidy/blob/master/local-docs/BugLog.pod
+
+## 2021 06 25
+
+ - This release adds several new requested parameters. No significant bugs have
+ been found since the last release, but a number of minor problems have been
+ corrected.
+
+ - Added a new option '--code-skipping', requested in git #65, in which code
+ between comment lines '#<<V' and '#>>V' is passed verbatim to the output
+ stream without error checking. It is simmilar to --format-skipping
+ but there is no error checking of the skipped code. This can be useful for
+ skipping past code which employs an extended syntax.
+
+ - Added a new option for closing paren placement, -vtc=3, requested in rt #136417.
+
+ - Added flag -atnl, --add-terminal-newline, to help issue git #58.
+ This flag tells perltidy to terminate the last line of the output stream
+ with a newline character, regardless of whether or not the input stream
+ was terminated with a newline character. This is the default.
+ If this flag is negated, with -natnl, then perltidy will add a terminal
+ newline character to the the output stream only if the input
+ stream is terminated with a newline.
+
+ - Some nested structures formatted with the -lp indentation option may have
+ some changes in indentation. This is due to updates which were made to
+ prevent formatting instability when line lengths are limited by the maximum line
+ length. Most scripts will not be affected. If this causes unwanted formatting
+ changes, try increasing the --maximum-line-length by a few characters.
+
+ - Numerous minor fixes have been made. A complete list is at:
+
+ https://github.com/perltidy/perltidy/blob/master/local-docs/BugLog.pod
+
+## 2021 04 02
+
+ - This release fixes several non-critical bugs which have been found since the last
+ release. An effort has been made to keep existing formatting unchanged.
+
+ - Fixed issue git #57 regarding uninitialized warning flag.
+
+ - Added experimental flag -lpxl=s requested in issue git #56 to provide some
+ control over which containers get -lp indentation.
+
+ - Fixed issue git #55 regarding lack of coordination of the --break-before-xxx
+ 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
+ being formatted according to these flags.
+
+ - 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
+ existing formatting is not changed. Use '-nfpva' to turn off unwanted
+ vertical alignment. To illustrate the possibilities:
+
+ # perltidy [default]
+ myfun( $aaa, $b, $cc );
+ mylongfun( $a, $b, $c );
+
+ # perltidy -sfp
+ myfun ( $aaa, $b, $cc );
+ mylongfun ( $a, $b, $c );
+
+ # perltidy -sfp -nfpva
+ myfun ( $aaa, $b, $cc );
+ mylongfun ( $a, $b, $c );
+
+ - Fixed issue git #51, a closing qw bare paren was not being outdented when
+ the -nodelete-old-newlines flag was set.
+
+ - Fixed numerous edge cases involving unusual parameter combinations which
+ could cause alternating output states. Most scripts will not be
+ changed by these fixes.
+
+ - A more complete list of updates is at
+
+ https://github.com/perltidy/perltidy/blob/master/local-docs/BugLog.pod
+
+## 2021 01 11
+
+ - Fixed issue git #49, -se breaks warnings exit status behavior.
+ The exit status flag was not always being set when the -se flag was set.
+
+ - Some improvements have been made in the method for aligning side comments.
+ One of the problems that was fixed is that there was a tendency for side comment
+ placement to drift to the right in long scripts. Programs with side comments
+ may have a few changes.
+
+ - Some improvements have been made in formatting qw quoted lists. This
+ fixes issue git #51, in which closing qw pattern delimiters not always
+ following the settings specified by the --closing-token-indentation=n settings.
+ Now qw closing delimiters ')', '}' and ']' follow these flags, and the
+ delimiter '>' follows the flag for ')'. Other qw pattern delimiters remain
+ indented as the are now. This change will cause some small formatting changes
+ in some existing programs.
+
+ - Another change involving qw lists is that they get full indentation,
+ rather than just continuation indentation, if
+
+ (1) the closing delimiter is one of } ) ] > and is on a separate line,
+ (2) the opening delimiter (i.e. 'qw{' ) is also on a separate line, and
+ (3) the -xci flag (--extended-continuation-indentation) is set.
+
+ This improves formatting when qw lists are contained in other lists. For example,
+
+ # OLD: perltidy
+ foreach $color (
+ qw(
+ AntiqueWhite3 Bisque1 Bisque2 Bisque3 Bisque4
+ SlateBlue3 RoyalBlue1 SteelBlue2 DeepSkyBlue3
+ ),
+ qw(
+ LightBlue1 DarkSlateGray1 Aquamarine2 DarkSeaGreen2
+ SeaGreen1 Yellow1 IndianRed1 IndianRed2 Tan1 Tan4
+ )
+ )
+
+ # NEW, perltidy -xci
+ foreach $color (
+ qw(
+ AntiqueWhite3 Bisque1 Bisque2 Bisque3 Bisque4
+ SlateBlue3 RoyalBlue1 SteelBlue2 DeepSkyBlue3
+ ),
+ qw(
+ LightBlue1 DarkSlateGray1 Aquamarine2 DarkSeaGreen2
+ SeaGreen1 Yellow1 IndianRed1 IndianRed2 Tan1 Tan4
+ )
+ )
+
+ - Some minor improvements have been made to the rules for formatting
+ some edge vertical alignment cases, usually involving two dissimilar lines.
+
+ - A more complete list of updates is at
+
+ https://github.com/perltidy/perltidy/blob/master/local-docs/BugLog.pod
+
+## 2020 12 07
+
+ - Fixed issue git #47, incorrect welding of anonymous subs.
+ An incorrect weld format was being made when the --weld-nested-containers option
+ (-wn) was used in to format a function which returns a list of anonymous subs.
+ For example, the following snippet was incorrectly being welded.
+
+ $promises[$i]->then(
+ sub { $all->resolve(@_); () },
+ sub {
+ $results->[$i] = [@_];
+ $all->reject(@$results) if --$remaining <= 0;
+ return ();
+ }
+ );
+
+ This was due to an error introduced in v20201201 related to parsing sub
+ signatures. Reformatting with the current version will fix the problem.
+
+## 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
+ been found and fixed as listed below.
+
+ - This version is about 20% faster than the previous version due to optimizations
+ made with the help of Devel::NYTProf.
+
+ - Added flag -wnxl=s, --weld-nested-exclusion-list=s, to provide control which containers
+ are welded with the --weld-nested-containers parameter. This is related to issue git #45.
+
+ - Merged pull request git #46 which fixes the docs regarding the -fse flag.
+
+ - Fixed issue git #45, -vtc=n flag was ignored when -wn was set.
+
+ - 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.
+
+ - 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
+ 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
+ the ending indentation differs from the starting indentation by more than
+ 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
+ but is off by default.
+
+ - 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
+ 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,
+ --perl-best-practices, where n=4).
+
+ - Fix issue git #42, clarify how --break-at-old-logical-breakpoints works.
+ The man page was updated to note that it does not cause all logical breakpoints
+ to be replicated in the output file.
+
+ - 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
+ 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
+ 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
+ improve formatting when there are numerous overloaded operators. For
+ example
+
+ use overload
+ '+' => sub {
+ ...
+
+ - 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
+ normal spacing rules were not applied. For example
+
+ OLD:
+ sub echo ($message= 'Hello World!' ) {
+ ...;
+ }
+
+ NEW:
+ sub echo ( $message = 'Hello World!' ) {
+ ...;
+ }
+
+ - 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
+
+ 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.
+ Many involve references to uninitialized variables when perltidy is fed random text and random
+ 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='->'.
+
+ - Added parameters -bbhb=n (--break-before-hash-brace=n), -bbsb=n (--break-before-square-bracket=n),
+ and -bbp=n (--break-before-paren=n) suggested in git #38. These provide control over the
+ opening container token of a multiple-line list. Related new parameters -bbhbi=n, -bbsbi=n, -bbpi=n
+ control indentation of these tokens.
+
+ - Added keyword 'isa'.
+
+## 2020 09 07
+
+ - Fixed bug git #37, an error when the combination -scbb -csc was used.
+ It occurs in perltidy versions 20200110, 20200619, and 20200822. What happens is
+ that when two consecutive lines with isolated closing braces had new side
+ 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.
+
+ 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
+ with a special side comment, '#<<<'. For example,
+
+ { #<<< a closure to contain lexical vars
+
+ my $var; # this line does not indent
+
+ }
+
+ # this line cannot 'see' $var;
+
+ 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.
+
+ - 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
+ 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.
+
+ This is a significant bug in version 20200616 which can corrupt data if
+ perltidy is run as a filter on encoded text.
+**Please upgrade**
+
+ - Fix issue RT #133161, perltidy -html was not working on pod
+
+ - Fix issue git #33, allow control of space after '->'
+
+ - Vertical alignment has been improved. Numerous minor issues have
+ been fixed.
+
+ - Formatting with the -lp option is improved.
+
+ - Fixed issue git #32, misparse of bare 'ref' in ternary
+
+ - When --assert-tidy is used and triggers an error, the first difference
+ between input and output files is shown in the error output. This is
+ a partial response to issue git #30.
+
+## 2020 06 19
+
+ - Added support for Switch::Plain syntax, issue git #31.
+
+ - Fixed minor problem where trailing 'unless' clauses were not
+ getting vertically aligned.
+
+ - Added a parameter --logical-padding or -lop to allow logical padding
+ to be turned off. Requested by git #29. This flag is on by default.
+ The man pages have examples.
+
+ - Added a parameter -kpit=n to control spaces inside of parens following
+ certain keywords, requested in git#26. This flag is off by default.
+
+ - Added fix for git#25, improve vertical alignment for long lists with
+ varying numbers of items per line.
+
+ - calls to the module Perl::Tidy can now capture any output produced
+ by a debug flag or one of the 'tee' flags through the new 'debugfile' and
+ 'teefile' call parameters. These output streams are rarely used but
+ they are now treated the same as any 'logfile' stream.
+
+ - add option --break-at-old-semicolon-breakpoints', -bos, requested
+ in RT#131644. This flag will keep lines beginning with a semicolon.
+
+ - Added --use-unicode-gcstring to control use of Unicode::GCString for
+ evaluating character widths of encoded data. The default is
+ not to use this (--nouse-unicode-gcstring). If this flag is set,
+ perltidy will look for Unicode::GCString and, if found, will use it
+ to evaluate character display widths. This can improve displayed
+ vertical alignment for files with wide characters. It is a nice
+ feature but it is off by default to avoid conflicting formatting
+ when there are multiple developers. Perltidy installation does not
+ require Unicode::GCString, so users wanting to use this feature need
+ set this flag and also to install Unicode::GCString separately.
+
+ - Added --character-encoding=guess or -guess to have perltidy guess
+ if a file (or other input stream) is encoded as -utf8 or some
+ other single-byte encoding. This is useful when processing a mixture
+ of file types, such as utf8 and latin-1.
+
+ Please Note: The default encoding has been set to be 'guess'
+ instead of 'none'. This seems like the best default, since
+ it allows perltidy work properly with both
+ utf8 files and older latin-1 files. The guess mode uses Encode::Guess,
+ which is included in standard perl distributions, and only tries to
+ guess if a file is utf8 or not, never any other encoding. If the guess is
+ utf8, and if the file successfully decodes as utf8, then it the encoding
+ is assumed to be utf8. Otherwise, no encoding is assumed.
+ If you do not want to use this new default guess mode, or have a
+ problem with it, you can set --character-encoding=none (the previous
+ default) or --character-encoding=utf8 (if you deal with utf8 files).
+
+ - Specific encodings of input files other than utf8 may now be given, for
+ example --character-encoding=euc-jp.
+
+ - Fix for git#22, Preserve function signature on a single line. An
+ unwanted line break was being introduced when a closing signature paren
+ followed a closing do brace.
+
+ - Fix RT#132059, the -dac parameter was not working and caused an error exit
+
+ - When -utf8 is used, any error output is encoded as utf8
+
+ - Fix for git#19, adjust line break around an 'xor'
+
+ - Fix for git#18, added warning for missing comma before unknown bare word.
+
## 2020 01 10
- This release adds a flag to control the feature RT#130394 (allow short nested blocks)
projects / perltidy.git / blobdiff