<h1>Perltidy Change Log</h1>
+<h2>2023 03 09</h2>
+
+<pre><code>- No significant bugs have been found since the last release to CPAN.
+ Several minor issues have been fixed, and some new parameters have been
+ added, as follows:
+
+- Added parameter --one-line-block-exclusion-list=s, or -olbxl=s, where
+ s is a list of block types which should not automatically be turned
+ into one-line blocks. This implements the issue raised in PR #111.
+ The list s may include any of the words 'sort map grep eval', or
+ it may be '*' to indicate all of these. So for example to prevent
+ multi-line 'eval' blocks from becoming one-line blocks, the command
+ would be -olbxl='eval'.
+
+- For the -b (--backup-and-modify-in-place) option, the file timestamps
+ are changing (git #113, rt#145999). First, if there are no formatting
+ changes to an input file, it will keep its original modification time.
+ Second, any backup file will keep its original modification time. This
+ was previously true for --backup-method=move but not for the default
+ --backup-method=copy. The purpose of these changes is to avoid
+ triggering Makefile operations when there are no actual file changes.
+ If this causes a problem please open an issue for discussion on github.
+
+- A change was made to the way line breaks are made at the '.'
+ operator when the user sets -wba='.' to requests breaks after a '.'
+ ( this setting is not recommended because it can be hard to read ).
+ The goal of the change is to make switching from breaks before '.'s
+ to breaks after '.'s just move the dots from the end of
+ lines to the beginning of lines. For example:
+
+ # default and recommended (--want-break-before='.'):
+ $output_rules .=
+ ( 'class'
+ . $dir
+ . '.stamp: $('
+ . $dir
+ . '_JAVA)' . "\n" . "\t"
+ . '$(CLASSPATH_ENV) $(JAVAC) -d $(JAVAROOT) '
+ . '$(JAVACFLAGS) $?' . "\n" . "\t"
+ . 'echo timestamp > class'
+ . $dir
+ . '.stamp'
+ . "\n" );
+
+ # perltidy --want-break-after='.'
+ $output_rules .=
+ ( 'class' .
+ $dir .
+ '.stamp: $(' .
+ $dir .
+ '_JAVA)' . "\n" . "\t" .
+ '$(CLASSPATH_ENV) $(JAVAC) -d $(JAVAROOT) ' .
+ '$(JAVACFLAGS) $?' . "\n" . "\t" .
+ 'echo timestamp > class' .
+ $dir .
+ '.stamp' .
+ "\n" );
+
+ For existing code formatted with -wba='.', this may cause some
+ changes in the formatting of code with long concatenation chains.
+
+- Added option --use-feature=class, or -uf=class, for issue rt #145706.
+ This adds keywords 'class', 'method', 'field', and 'ADJUST' in support of
+ this feature which is being tested for future inclusion in Perl.
+ An effort has been made to avoid conflicts with past uses of these
+ words, especially 'method' and 'class'. The default setting
+ is --use-feature=class. If this causes a conflict, this option can
+ be turned off by entering -uf=' '.
+
+ In other words, perltidy should work for both old and new uses of
+ these keywords with the default settings, but this flag is available
+ if a conflict arises.
+
+- Added option -bfvt=n, or --brace-follower-vertical-tightness=n,
+ for part of issue git #110. For n=2, this option looks for lines
+ which would otherwise be, by default,
+
+ }
+ or ..
+
+ and joins them into a single line
+
+ } or ..
+
+ where the or can be one of a number of logical operators or if unless.
+ The default is not to do this and can be indicated with n=1.
+
+- Added option -cpb, or --cuddled-paren-brace, for issue git #110.
+ This option will cause perltidy to join two lines which
+ otherwise would be, by default,
+
+ )
+ {
+
+ into a single line
+
+ ) {
+
+- Some minor changes to existing formatted output may occur as a result
+ of fixing minor formatting issues with edge cases. This is especially
+ true for code which uses the -lp or -xlp styles.
+
+- Added option -dbs, or --dump-block-summary, to dump summary
+ information about code blocks in a file to standard output.
+ The basic command is:
+
+ perltidy -dbs somefile.pl >blocks.csv
+
+ Instead of formatting ``somefile.pl``, this dumps the following
+ comma-separated items describing its blocks to the standard output:
+
+ filename - the name of the file
+ line - the line number of the opening brace of this block
+ line_count - the number of lines between opening and closing braces
+ code_lines - the number of lines excluding blanks, comments, and pod
+ type - the block type (sub, for, foreach, ...)
+ name - the block name if applicable (sub name, label, asub name)
+ depth - the nesting depth of the opening block brace
+ max_change - the change in depth to the most deeply nested code block
+ block_count - the total number of code blocks nested in this block
+ mccabe_count - the McCabe complexity measure of this code block
+
+ This can be useful for code restructuring. The man page for perltidy
+ has more information and describes controls for selecting block types.
+
+- This version was stress-tested for over 100 cpu hours with random
+ input parameters. No failures to converge, internal fault checks,
+ undefined variable references or other irregularities were seen.
+
+- This version runs a few percent faster than the previous release on
+ large files due to optimizations made with the help of Devel::NYTProf.
+</code></pre>
+
+<h2>2022 11 12</h2>
+
+<pre><code>- Fix rt #145095, undef warning in Perl before 5.12. Version 20221112 is
+ identical to 2022111 except for this fix for older versions of Perl.
+
+- No significant bugs have been found since the last release to CPAN.
+ Several minor issues have been fixed, and some new parameters have been
+ added, as follows:
+
+- Fixed rare problem with irregular indentation involving --cuddled-else,
+ usually also with the combination -xci and -lp. Reported in rt #144979.
+
+- Add option --weld-fat-comma (-wfc) for issue git #108. When -wfc
+ is set, along with -wn, perltidy is allowed to weld an opening paren
+ to an inner opening container when they are separated by a hash key
+ and fat comma (=>). For example:
+
+ # perltidy -wn
+ elf->call_method(
+ method_name_foo => {
+ some_arg1 => $foo,
+ some_other_arg3 => $bar->{'baz'},
+ }
+ );
+
+ # perltidy -wn -wfc
+ elf->call_method( method_name_foo => {
+ some_arg1 => $foo,
+ some_other_arg3 => $bar->{'baz'},
+ } );
+
+ This flag is off by default.
+
+- Fix issue git #106. This fixes some edge cases of formatting with the
+ combination -xlp -pt=2, mainly for two-line lists with short function
+ names. One indentation space is removed to improve alignment:
+
+ # OLD: perltidy -xlp -pt=2
+ is($module->VERSION, $expected,
+ "$main_module->VERSION matches $module->VERSION ($expected)");
+
+ # NEW: perltidy -xlp -pt=2
+ is($module->VERSION, $expected,
+ "$main_module->VERSION matches $module->VERSION ($expected)");
+
+- Fix for issue git #105, incorrect formatting with 5.36 experimental
+ for_list feature.
+
+- Fix for issue git #103. For parameter -b, or --backup-and-modify-in-place,
+ the default backup method has been changed to preserve the inode value
+ of the file being formatted. If this causes a problem, the previous
+ method is available and can be used by setting -backup-mode='move', or
+ -bm='move'. The new default corresponds to -bm='copy'. The difference
+ between the two methods is as follows. For the older method,
+ -bm='move', the input file was moved to the backup, and a new file was
+ created for the formatted output. This caused the inode to change. For
+ the new default method, -bm='copy', the input is copied to the backup
+ and then the input file is reopened and rewritten. This preserves the
+ file inode. Tests have not produced any problems with this change, but
+ before using the --backup-and-modify-in-place parameter please verify
+ that it works correctly in your environment and operating system. The
+ initial update for this had an error which was caught and fixed
+ in git #109.
+
+- Fix undefined value message when perltidy -D is used (git #104)
+
+- Fixed an inconsistency in html colors near pointers when -html is used.
+ Previously, a '->' at the end of a line got the 'punctuation color', black
+ by default but a '->' before an identifier got the color of the following
+ identifier. Now all pointers get the same color, which is black by default.
+ Also, previously a word following a '->' was given the color of a bareword,
+ black by default, but now it is given the color of an identifier.
+
+- Fixed incorrect indentation of any function named 'err'. This was
+ due to some old code from when "use feature 'err'" was valid.
+
+ # OLD:
+ my ($curr) = current();
+ err (@_);
+
+ # NEW:
+ my ($curr) = current();
+ err(@_);
+
+- Added parameter --delete-repeated-commas (-drc) to delete repeated
+ commas. This is off by default. For example, given:
+
+ ignoreSpec( $file, "file",, \%spec, \%Rspec );
+
+ # perltidy -drc:
+ ignoreSpec( $file, "file", \%spec, \%Rspec );
+
+- Add continuation indentation to long C-style 'for' terms; i.e.
+
+ # OLD
+ for (
+ $j = $i - $shell ;
+ $j >= 0
+ && ++$ncomp
+ && $array->[$j] gt $array->[ $j + $shell ] ;
+ $j -= $shell
+ )
+
+ # NEW
+ for (
+ $j = $i - $shell ;
+ $j >= 0
+ && ++$ncomp
+ && $array->[$j] gt $array->[ $j + $shell ] ;
+ $j -= $shell
+ )
+
+ This will change some existing formatting with very long 'for' terms.
+
+- The following new parameters are available for manipulating
+ trailing commas of lists. They are described in the manual.
+
+ --want-trailing-commas=s, -wtc=s
+ --add-trailing-commas, -atc
+ --delete-trailing-commas, -dtc
+ --delete-weld-interfering-commas, -dwic
+
+- Files with errors due to missing, extra or misplaced parens, braces,
+ or square brackets are now written back out verbatim, without any
+ attempt at formatting.
+
+- This version runs 10 to 15 percent faster than the previous
+ release on large files due to optimizations made with the help of
+ Devel::NYTProf.
+
+- This version was stress-tested for over 200 cpu hours with random
+ input parameters. No failures to converge, internal fault checks,
+ undefined variable references or other irregularities were seen.
+</code></pre>
+
+<h2>2022 06 13</h2>
+
+<pre><code>- 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-exclusion-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.
+</code></pre>
+
<h2>2022 02 17</h2>
<pre><code>- A new flag, --encode-output-strings, or -eos, has been added to resolve