From 57d829ae0e2c75828f8ecc9c7139579350927dbc Mon Sep 17 00:00:00 2001 From: Don Armstrong Date: Sun, 24 Oct 2021 14:59:00 -0700 Subject: [PATCH] New upstream version 20210717 --- .pre-commit-hooks.yaml | 8 + BUGS.md | 15 + CHANGES.md | 439 + MANIFEST | 15 +- META.json | 7 +- META.yml | 5 +- README.md | 5 +- bin/perltidy | 1323 +- docs/BugLog.html | 4266 ++ docs/ChangeLog.html | 451 + docs/Tidy.html | 16 +- docs/index.html | 4 +- docs/index.md | 4 +- docs/perltidy.html | 996 +- examples/fix-scbb-csc-bug.pl | 99 + examples/perltidy_hide.pl | 43 + lib/Perl/Tidy.pm | 1088 +- lib/Perl/Tidy.pod | 16 +- lib/Perl/Tidy/Debugger.pm | 36 +- lib/Perl/Tidy/DevNull.pm | 2 +- lib/Perl/Tidy/Diagnostics.pm | 28 +- lib/Perl/Tidy/FileWriter.pm | 335 +- lib/Perl/Tidy/Formatter.pm | 33433 +++++++++------- lib/Perl/Tidy/HtmlWriter.pm | 54 +- lib/Perl/Tidy/IOScalar.pm | 28 +- lib/Perl/Tidy/IOScalarArray.pm | 28 +- lib/Perl/Tidy/IndentationItem.pm | 186 +- lib/Perl/Tidy/LineBuffer.pm | 28 +- lib/Perl/Tidy/LineSink.pm | 138 +- lib/Perl/Tidy/LineSource.pm | 42 +- lib/Perl/Tidy/Logger.pm | 93 +- lib/Perl/Tidy/Tokenizer.pm | 3191 +- lib/Perl/Tidy/VerticalAligner.pm | 6471 +-- lib/Perl/Tidy/VerticalAligner/Alignment.pm | 156 +- lib/Perl/Tidy/VerticalAligner/Line.pm | 294 +- t/atee.t | 88 + t/{filter_example.t.SKIP => filter_example.t} | 23 +- t/snippets1.t | 28 +- t/snippets10.t | 187 +- t/snippets11.t | 29 +- t/snippets12.t | 44 +- t/snippets13.t | 45 +- t/snippets14.t | 61 +- t/snippets15.t | 39 +- t/snippets16.t | 97 +- t/snippets17.t | 1126 + t/snippets18.t | 909 + t/snippets19.t | 629 + t/snippets2.t | 25 +- t/snippets20.t | 716 + t/snippets21.t | 865 + t/snippets22.t | 775 + t/snippets23.t | 776 + t/snippets24.t | 927 + t/snippets3.t | 25 +- t/snippets4.t | 31 +- t/snippets5.t | 82 +- t/snippets6.t | 29 +- t/snippets7.t | 32 +- t/snippets8.t | 25 +- t/snippets9.t | 25 +- t/test-eol.t | 4 + t/testwide.t | 33 +- 63 files changed, 42167 insertions(+), 18851 deletions(-) create mode 100644 .pre-commit-hooks.yaml create mode 100644 docs/BugLog.html create mode 100755 examples/fix-scbb-csc-bug.pl create mode 100755 examples/perltidy_hide.pl create mode 100644 t/atee.t rename t/{filter_example.t.SKIP => filter_example.t} (63%) create mode 100644 t/snippets17.t create mode 100644 t/snippets18.t create mode 100644 t/snippets19.t create mode 100644 t/snippets20.t create mode 100644 t/snippets21.t create mode 100644 t/snippets22.t create mode 100644 t/snippets23.t create mode 100644 t/snippets24.t diff --git a/.pre-commit-hooks.yaml b/.pre-commit-hooks.yaml new file mode 100644 index 0000000..d0cdce5 --- /dev/null +++ b/.pre-commit-hooks.yaml @@ -0,0 +1,8 @@ +- id: perltidy + name: perltidy + description: Run the perltidy source code formatter on Perl source files + minimum_pre_commit_version: 2.1.0 + entry: perltidy --nostandard-output --backup-and-modify-in-place + args: [--standard-error-output, --backup-file-extension=/] + language: perl + types: [perl] diff --git a/BUGS.md b/BUGS.md index 1ec2b48..a64b8ae 100644 --- a/BUGS.md +++ b/BUGS.md @@ -38,6 +38,21 @@ perltidy is untangling complex ternary statements. Use the iteration parameter **-it=2** if it is important that the results be unchanged on subsequent passes, but note that this doubles the run time. +## Perltidy does not look for here-document targets inside of quoted strings + +For example, consider the following script + +``` +print "${ \<>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' 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) diff --git a/MANIFEST b/MANIFEST index 491c114..454c8cd 100644 --- a/MANIFEST +++ b/MANIFEST @@ -1,7 +1,9 @@ +.pre-commit-hooks.yaml bin/perltidy BUGS.md CHANGES.md COPYING +docs/BugLog.html docs/ChangeLog.html docs/index.html docs/index.md @@ -17,10 +19,12 @@ examples/ex_mp.pl examples/filter_example.in examples/filter_example.pl examples/find_naughty.pl +examples/fix-scbb-csc-bug.pl examples/lextest examples/perlcomment.pl examples/perllinetype.pl examples/perlmask.pl +examples/perltidy_hide.pl examples/perltidy_okw.pl examples/perltidyrc_dump.pl examples/perlxmltok.pl @@ -52,7 +56,8 @@ Makefile.PL MANIFEST This list of files pm2pl README.md -t/filter_example.t.SKIP +t/atee.t +t/filter_example.t t/snippets1.t t/snippets10.t t/snippets11.t @@ -61,7 +66,15 @@ t/snippets13.t t/snippets14.t t/snippets15.t t/snippets16.t +t/snippets17.t +t/snippets18.t +t/snippets19.t t/snippets2.t +t/snippets20.t +t/snippets21.t +t/snippets22.t +t/snippets23.t +t/snippets24.t t/snippets3.t t/snippets4.t t/snippets5.t diff --git a/META.json b/META.json index 3cbfead..2478d27 100644 --- a/META.json +++ b/META.json @@ -4,13 +4,13 @@ "Steve Hancock " ], "dynamic_config" : 1, - "generated_by" : "ExtUtils::MakeMaker version 7.0401, CPAN::Meta::Converter version 2.150001", + "generated_by" : "ExtUtils::MakeMaker version 7.62, CPAN::Meta::Converter version 2.150010", "license" : [ "gpl_2" ], "meta-spec" : { "url" : "http://search.cpan.org/perldoc?CPAN::Meta::Spec", - "version" : "2" + "version" : 2 }, "name" : "Perl-Tidy", "no_index" : { @@ -39,5 +39,6 @@ "web" : "https://github.com/perltidy/perltidy" } }, - "version" : "20200110" + "version" : "20210717", + "x_serialization_backend" : "JSON::PP version 4.04" } diff --git a/META.yml b/META.yml index dc8cc55..9f9ba2d 100644 --- a/META.yml +++ b/META.yml @@ -7,7 +7,7 @@ build_requires: configure_requires: ExtUtils::MakeMaker: '0' dynamic_config: 1 -generated_by: 'ExtUtils::MakeMaker version 7.0401, CPAN::Meta::Converter version 2.150001' +generated_by: 'ExtUtils::MakeMaker version 7.62, CPAN::Meta::Converter version 2.150010' license: gpl meta-spec: url: http://module-build.sourceforge.net/META-spec-v1.4.html @@ -19,4 +19,5 @@ no_index: - inc resources: repository: https://github.com/perltidy/perltidy.git -version: '20200110' +version: '20210717' +x_serialization_backend: 'CPAN::Meta::YAML version 0.012' diff --git a/README.md b/README.md index e077071..bc6a23e 100644 --- a/README.md +++ b/README.md @@ -1,11 +1,14 @@ +[![Build Status](https://travis-ci.com/perltidy/perltidy.svg?branch=master)](https://travis-ci.com/perltidy/perltidy) + # Welcome to Perltidy -Perltidy is a tool to indent and reformat scripts written in Perl5. +Perltidy is a tool to indent and reformat scripts written in Perl. Perltidy is free software released under the GNU General Public License -- please see the included file "COPYING" for details. Documentation can be found at the web site [at GitHub](https://perltidy.github.io/perltidy/) or [at Sourceforge](http://perltidy.sourceforge.net) +or [at metacpan](https://metacpan.org/pod/distribution/Perl-Tidy/bin/perltidy) A copy of the web site is contained in the docs folder of the distribution. diff --git a/bin/perltidy b/bin/perltidy index 93a22c4..34c6b51 100755 --- a/bin/perltidy +++ b/bin/perltidy @@ -221,7 +221,7 @@ The path should end in a valid path separator character, but perltidy will try to add one if it is missing. For example - + perltidy somefile.pl -opath=/tmp/ will produce F. Otherwise, F will @@ -284,8 +284,7 @@ B<--nowarning-output>, is not to include these warnings. =item B<-q>, B<--quiet> -Deactivate error messages and syntax checking (for running under -an editor). +Deactivate error messages (for running under an editor). For example, if you use a vi-style editor, such as vim, you may execute perltidy as a filter from within the editor using something like @@ -368,6 +367,8 @@ This error message will cause the process to return a non-zero exit code. The test for this is made by comparing an MD5 hash value for the input and output code streams. This flag has no other effect on the functioning of perltidy. This might be useful for certain code maintenance operations. +Note: you will not see this message if you have error messages turned off with the +-quiet flag. =item B<-asu>, B<--assert-untidy> @@ -386,6 +387,8 @@ For example, will cause the perltidy to treate the words 'method', 'fun', '_sub' and 'M4' to be treated the same as if they were 'sub'. Note that if the alias words are separated by spaces then the string of words should be placed in quotes. +Note that several other parameters accept a list of keywords, including 'sub' (see L). +You do not need to include any sub aliases in these lists. Just include keyword 'sub' if you wish, and all aliases are automatically included. =back @@ -413,7 +416,13 @@ Use n columns per indentation level (default n=4). The default maximum line length is n=80 characters. Perltidy will try to find line break points to keep lines below this length. However, long quotes and side comments may cause lines to exceed this length. -Setting B<-l=0> is equivalent to setting B<-l=(a large number)>. + +The default length of 80 comes from the past when this was the standard CRT +screen width. Many programmers prefer to increase this to something like 120. + +Setting B<-l=0> is equivalent to setting B<-l=(a very large number)>. But this is +not recommended because, for example, a very long list will be formatted in a +single long line. =item B<-vmll>, B<--variable-maximum-line-length> @@ -459,7 +468,7 @@ although B<-wc=n> may of course be used without B<-vmll>. The default is not to use this, which can also be indicated using B<-wc=0>. -=item tabs +=item B Using tab characters will almost certainly lead to future portability and maintenance problems, so the default and recommendation is not to @@ -477,8 +486,13 @@ here-documents, they will remain. =item B<-et=n>, B<--entab-leading-whitespace> This flag causes each B initial space characters to be replaced by -one tab character. Note that the integer B is completely independent -of the integer specified for indentation parameter, B<-i=n>. +one tab character. + +The value of the integer B can be any value but can be coordinated with the +number of spaces used for intentation. For example, B<-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 B with what your +display software assumes for the spacing of a tab. =item B<-t>, B<--tabs> @@ -486,7 +500,8 @@ This flag causes one leading tab character to be inserted for each level of indentation. Certain other features are incompatible with this option, and if these options are also given, then a warning message will be issued and this flag will be unset. One example is the B<-lp> -option. +option. This flag is retained for backwards compatibility, but +if you use tabs, the B<-et=n> flag is recommended. =item B<-dt=n>, B<--default-tabsize=n> @@ -503,41 +518,6 @@ unstable editing). =back -=item B<-syn>, B<--check-syntax> - -This flag is now ignored for safety, but the following documentation -has been retained for reference. - -This flag causes perltidy to run C to check syntax of input -and output. (To change the flags passed to perl, see the next -item, B<-pscf>). The results are written to the F<.LOG> file, which -will be saved if an error is detected in the output script. The output -script is not checked if the input script has a syntax error. Perltidy -does its own checking, but this option employs perl to get a "second -opinion". - -If perl reports errors in the input file, they will not be reported in -the error output unless the B<--warning-output> flag is given. - -The default is B to do this type of syntax checking (although -perltidy will still do as much self-checking as possible). The reason -is that it causes all code in BEGIN blocks to be executed, for all -modules being used, and this opens the door to security issues and -infinite loops when running perltidy. - -=item B<-pscf=s>, B<-perl-syntax-check-flags=s> - -When perl is invoked to check syntax, the normal flags are C<-c -T>. In -addition, if the B<-x> flag is given to perltidy, then perl will also be -passed a B<-x> flag. It should not normally be necessary to change -these flags, but it can be done with the B<-pscf=s> flag. For example, -if the taint flag, C<-T>, is not wanted, the flag could be set to be just -B<-pscf=-c>. - -Perltidy will pass your string to perl with the exception that it will -add a B<-c> and B<-x> if appropriate. The F<.LOG> file will show -exactly what flags were passed to perl. - =item B<-xs>, B<--extended-syntax> A problem with formatting Perl code is that some modules can introduce new @@ -551,10 +531,15 @@ a syntax error and the braces would not be balanced: $self->balance( $self->balance + $amount ); } +For one of the extensions, module Switch::Plain, colons are marked as labels. +If you use this module, you may want to also use the B<--nooutdent-labels> flag +to prevent lines such as 'default:' from being outdented. + This flag is enabled by default but it can be deactivated with B<-nxs>. Probably the only reason to deactivate this flag is to generate more diagnostic messages when debugging a script. +For another method of handling extended syntax see the section L. =item B<-io>, B<--indent-only> @@ -587,22 +572,71 @@ this flag is in effect. =item B<-enc=s>, B<--character-encoding=s> -where B=B or B. This flag tells perltidy the character encoding -of both the input and output character streams. The value B causes the -stream to be read and written as UTF-8. The value B causes the stream to -be processed without special encoding assumptions. At present there is no -automatic detection of character encoding (even if there is a C<'use utf8'> -statement in your code) so this flag must be set for streams encoded in UTF-8. -Incorrectly setting this parameter can cause data corruption, so please -carefully check the output. +This flag indicates the character encoding, if any, of the input data stream. +Perltidy does not look for the encoding directives in the soure stream, such +as B, and instead relies on this flag to determine the encoding. +(Note that perltidy often works on snippets of code rather than complete files +so it cannot rely on B directives). + +The possible values for B are (1) the name of an encoding recognized by the +Encode.pm module, (2) B if no encoding is used, or (3) if +perltidy should guess. + +For example, the value B causes the stream to be read and written as +UTF-8. If the input stream cannot be decoded with a specified encoding then +processing is not done. -The default is B. +The value B causes the stream to be processed without special encoding +assumptions. This is appropriate for files which are written in single-byte +character encodings such as latin-1. -The abbreviations B<-utf8> or B<-UTF8> are equivalent to B<-enc=utf8>. -So to process a file named B which is encoded in UTF-8 you can use: +The value B tells perltidy to guess between either utf8 encoding or no +encoding (meaning one character per byte). The guess uses the Encode::Guess +module and this restricted range of guesses covers the most common cases. +Testing showed that considering any greater number of encodings as guess +suspects is too risky. + +The current default is B. + +The abbreviations B<-utf8> or B<-UTF8> are equivalent to B<-enc=utf8>, and the +abbreviation B<-guess> is equivalent to <-enc=guess>. So to process a file +named B which is encoded in UTF-8 you can use: perltidy -utf8 file.pl +or + perltidy -guess file.pl + +To process a file in B you could use + + perltidy -enc=euc-jp file.pl + +A perltidy output file is unencoded if the input file is unencoded, and +otherwise it is encoded as B, even if the input encoding was not +B. + +=item B<-gcs>, B<--use-unicode-gcstring> + +This flag controls whether or not perltidy may use module Unicode::GCString to +obtain accurate display widths of wide characters. The default +is B<--nouse-unicode-gcstring>. + +If this flag is set, and text is encoded, perltidy will look for the module +Unicode::GCString and, if found, will use it to obtain 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. + +If this flag is set and perltidy does not find module Unicode::GCString, +a warning message will be produced and processing will continue but without +the potential benefit provided by the module. + +Also note that actual vertical alignment depends upon the fonts used by the +text display software, so vertical alignment may not be optimal even when +Unicode::GCString is used. + =item B<-ole=s>, B<--output-line-ending=s> where s=C, C, C, or C. This flag tells perltidy @@ -619,6 +653,17 @@ input comes from a filename (rather than stdin, for example). If perltidy has trouble determining the input file line ending, it will revert to the default behavior of using the line ending of the host system. +=item B<-atnl>, B<--add-terminal-newline> + +This flag, which is enabled by default, allows 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. If this flag is +negated, with B<-natnl>, then perltidy will add a terminal newline to the the +output stream only if the input stream is terminated with a newline. + +Negating this flag may be useful for manipulating one-line scripts intended for +use on a command line. + =item B<-it=n>, B<--iterations=n> This flag causes perltidy to do B complete iterations. The reason for this @@ -641,8 +686,10 @@ control. For all practical purposes one either does or does not want to be sure that the output is converged, and there is no penalty to using a large iteration limit since perltidy will check for convergence and stop iterating as soon as possible. The default is B<-nconv> (no convergence check). Using -B<-conv> will approximately double run time since normally one extra iteration -is required to verify convergence. +B<-conv> will approximately double run time since typically one extra iteration +is required to verify convergence. No extra iterations are required if no new +line breaks are made, and two extra iterations are occasionally needed when +reformatting complex code structures, such as deeply nested ternary statements. =back @@ -667,9 +714,49 @@ The value given to B<-ci> is also used by some commands when a small space is required. Examples are commands for outdenting labels, B<-ola>, and control keywords, B<-okw>. -When default values are not used, it is suggested that the value B -given with B<-ci=n> be no more than about one-half of the number of -spaces assigned to a full indentation level on the B<-i=n> command. +When default values are not used, it is recommended that either + +(1) the value B given with B<-ci=n> be no more than about one-half of the +number of spaces assigned to a full indentation level on the B<-i=n> command, or + +(2) the flag B<-extended-continuation-indentation> is used (see next section). + +=item B<-xci>, B<--extended-continuation-indentation> + +This flag allows perltidy to use some improvements which have been made to its +indentation model. One of the things it does is "extend" continuation +indentation deeper into structures, hence the name. The improved indentation +is particularly noticeable when the flags B<-ci=n> and B<-i=n> use the same value of +B. There are no significant disadvantages to using this flag, but to avoid +disturbing existing formatting the default is not to use it, B<-nxci>. + +Please see the section L<"B<-pbp>, B<--perl-best-practices>"> for an example of +how this flag can improve the formatting of ternary statements. It can also +improve indentation of some multi-line qw lists as shown below. + + # perltidy + foreach $color ( + qw( + AntiqueWhite3 Bisque1 Bisque2 Bisque3 Bisque4 + SlateBlue3 RoyalBlue1 SteelBlue2 DeepSkyBlue3 + ), + qw( + LightBlue1 DarkSlateGray1 Aquamarine2 DarkSeaGreen2 + SeaGreen1 Yellow1 IndianRed1 IndianRed2 Tan1 Tan4 + ) + ) + + # 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 + ) + ) =item B<-sil=n> B<--starting-indentation-level=n> @@ -690,7 +777,7 @@ guessed indentation will be wrong. If the default method does not work correctly, or you want to change the starting level, use B<-sil=n>, to force the starting level to be n. -=item List indentation using B<-lp>, B<--line-up-parentheses> +=item B using B<-lp>, B<--line-up-parentheses> By default, perltidy indents lists with 4 spaces, or whatever value is specified with B<-i=n>. Here is a small list formatted in this way: @@ -717,13 +804,12 @@ space, perltidy will use less. For alternate placement of the closing paren, see the next section. This option has no effect on code BLOCKS, such as if/then/else blocks, -which always use whatever is specified with B<-i=n>. Also, the -existence of line breaks and/or block comments between the opening and -closing parens may cause perltidy to temporarily revert to its default -method. +which always use whatever is specified with B<-i=n>. -Note: The B<-lp> option may not be used together with the B<-t> tabs option. -It may, however, be used with the B<-et=n> tab method. +In situations where perltidy does not have complete freedom to choose line +breaks it may temporarily revert to its default indentation method. This can +occur for example if there are blank lines, block comments, multi-line quotes, +or side comments between the opening and closing parens, braces, or brackets. In addition, any parameter which significantly restricts the ability of perltidy to choose newlines will conflict with B<-lp> and will cause @@ -732,6 +818,72 @@ B<-ndnl>. The reason is that the B<-lp> indentation style can require the careful coordination of an arbitrary number of break points in hierarchical lists, and these flags may prevent that. +The B<-lp> option may not be used together with the B<-t> tabs option. +It may, however, be used with the B<-et=n> tab method. + + +=item B<-lpxl=s>, B<--line-up-parentheses-exclusion-list> + +This is an experimental parameter; the details might change as experience +with it is gained. + +The B<-lp> indentation style works well for some types of coding but can +produce very long lines when variables have long names and/or containers are +very deeply nested. The B<-lpxl=s> flag is intended to help mitigate this problem by +providing control over the containers to which the B<-lp> indentation style is +applied. The B<-lp> flag by default is "greedy" and applies to as many +containers as possible. This flag specifies a list of things which should +B be use B<-lp> indentation. + +This list is a string with space-separated items. Each item consists of up to +three pieces of information in this order: (1) an optional letter code (2) a +required container type, and (3) an optional numeric code. + +The only required piece of information is a container type, which is one of +'(', '[', or '{'. For example the string + + -lpxl='[ {' + +means do B include use -lp formatting within square-bracets or braces. The only unspecified +container is '(', so this string means that only the contents within parens will use -lp indentation. + +An optional numeric code may follow any of the container types to further refine the selection based +on container contents. The numeric codes are: + + '0' or blank: no check on contents + '1' reject -lp unless the contents is a simple list without sublists + '2' reject -lp unless the contents is a simple list without sublists, without + code blocks, and without ternary operators + +For example, + + -lpxl = '[ { (2' + +means only apply -lp to parenthesized lists which do not contain any sublists, +code blocks or ternary expressions. + +A third optional item of information which can be given for parens is an alphanumeric +letter which is used to limit the selection further depending on the type of +token immediately before the paren. The possible letters are currently 'k', +'K', 'f', 'F', 'w', and 'W', with these meanings: + + 'k' matches if the previous nonblank token is a perl builtin keyword (such as 'if', 'while'), + 'K' matches if 'k' does not, meaning that the previous token is not a keyword. + 'f' matches if the previous token is a function other than a keyword. + 'F' matches if 'f' does not. + 'w' matches if either 'k' or 'f' match. + 'W' matches if 'w' does not. + +For example, + + -lpxl = '[ { F(2' + +means only apply -lp to parenthesized lists which follow a function call and +which do not contain any sublists, code blocks or ternary expressions. The logic +of writing these codes is somewhat counter-intuitive because they describe what is not +getting the -lp indentation. So the 'F' indicates that non-function calls are +not getting -lp, or in other words that function calls are getting the -lp indentation. + =item B<-cti=n>, B<--closing-token-indentation> The B<-cti=n> flag controls the indentation of a line beginning with @@ -746,7 +898,7 @@ a C<)>, C<]>, or a non-block C<}>. Such a line receives: The flags B<-cti=1> and B<-cti=2> work well with the B<-lp> flag (previous section). - + # perltidy -lp -cti=1 @month_of_year = ( 'Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', @@ -790,6 +942,61 @@ terminates a code block . For example, The default is not to do this, indicated by B<-nicb>. + +=item B<-nib>, B<--non-indenting-braces> + +Normally, lines of code contained within a pair of block braces receive one +additional level of indentation. This flag, which is enabled by default, +causes perltidy to look for +opening block braces which are followed by a special side comment. This special +side comment is B<#<<<> by default. If found, the code between this opening brace and its +corresponding closing brace will not be given the normal extra indentation +level. For example: + + { #<<< a closure to contain lexical vars + + my $var; # this line does not get one level of indentation + ... + + } + + # this line does not 'see' $var; + +This can be useful, for example, when combining code from different files. +Different sections of code can be placed within braces to keep their lexical +variables from being visible to the end of the file. To keep the new braces +from causing all of their contained code to be indented if you run perltidy, +and possibly introducing new line breaks in long lines, you can mark the +opening braces with this special side comment. + +Only the opening brace needs to be marked, since perltidy knows where the +closing brace is. Braces contained within marked braces may also be marked +as non-indenting. + +If your code happens to have some opening braces followed by '#<<<', and you +don't want this behavior, you can use B<-nnib> to deactivate it. To make it +easy to remember, the default string is the same as the string for starting a +B section. There is no confusion because in that case it is +for a block comment rather than a side-comment. + +The special side comment can be changed with the next parameter. + + +=item B<-nibp=s>, B<--non-indenting-brace-prefix=s> + +The B<-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. + +For example, to match the side comment '#++', the parameter would be + + -nibp='#\+\+' + + =item B<-olq>, B<--outdent-long-quotes> When B<-olq> is set, lines which is a quoted string longer than the @@ -804,7 +1011,7 @@ B<--outdent-long-comments>, and it is included for compatibility with previous versions of perltidy. The negation of this also works, B<-noll> or B<--nooutdent-long-lines>, and is equivalent to setting B<-nolq> and B<-nolc>. -=item Outdenting Labels: B<-ola>, B<--outdent-labels> +=item B B<-ola>, B<--outdent-labels> This command will cause labels to be outdented by 2 spaces (or whatever B<-ci> has been set to), if possible. This is the default. For example: @@ -818,7 +1025,7 @@ has been set to), if possible. This is the default. For example: Use B<-nola> to not outdent labels. -=item Outdenting Keywords +=item B =over 4 @@ -842,7 +1049,7 @@ For example, using C on the previous example gives: The default is not to do this. -=item Specifying Outdented Keywords: B<-okwl=string>, B<--outdent-keyword-list=string> +=item B B<-okwl=string>, B<--outdent-keyword-list=string> This command can be used to change the keywords which are outdented with the B<-okw> command. The parameter B is a required list of perl @@ -872,7 +1079,7 @@ causes the rest of the whitespace commands in this section, the Code Indentation section, and the Comment Control section to be ignored. -=item Tightness of curly braces, parentheses, and square brackets. +=item B Here the term "tightness" will mean the closeness with which pairs of enclosing tokens, such as parentheses, contain the quantities @@ -968,7 +1175,7 @@ comment). =item B<-aws>, B<--add-whitespace> -Setting this option allows perltidy to add certain whitespace improve +Setting this option allows perltidy to add certain whitespace to improve code readability. This is the default. If you do not want any whitespace added, but are willing to have some whitespace deleted, use B<-naws>. (Use B<-fws> to leave whitespace completely unchanged). @@ -980,7 +1187,7 @@ between characters, if necessary. This is the default. If you do not want any old whitespace removed, use B<-ndws> or B<--nodelete-old-whitespace>. -=item Detailed whitespace controls around tokens +=item B For those who want more detailed control over the whitespace around tokens, there are four parameters which can directly modify the default @@ -1029,12 +1236,87 @@ and look at the .DEBUG file to see the tokenization. B Be sure to put these tokens in quotes to avoid having them misinterpreted by your command shell. -=item Space between specific keywords and opening paren +=item B + +The various parameters controlling whitespace within a program are requests which perltidy follows as well as possible, but there are a number of situations where changing whitespace could change program behavior and is not done. Some of these are obvious; for example, we should not remove the space between the two plus symbols in '$x+ +$y' to avoid creating a '++' operator. Some are more subtle and involve the whitespace around bareword symbols and locations of possible filehandles. For example, consider the problem of formatting the following subroutine: + + sub print_div { + my ($x,$y)=@_; + print $x/$y; + } + +Suppose the user requests that / signs have a space to the left but not to the right. Perltidy will refuse to do this, but if this were done the result would be + + sub print_div { + my ($x,$y)=@_; + print $x /$y; + } + +If formatted in this way, the program will not run (at least with recent versions of perl) because the $x is taken to be a filehandle and / is assumed to start a quote. In a complex program, there might happen to be a / which terminates the multiline quote without a syntax error, allowing the program to run, but not as intended. + +Related issues arise with other binary operator symbols, such as + and -, and in older versions of perl there could be problems with ternary operators. So to avoid changing program behavior, perltidy has the simple rule that whitespace around possible filehandles is left unchanged. Likewise, whitespace around barewords is left unchanged. The reason is that if the barewords are defined in other modules, or in code that has not even been written yet, perltidy will not have seen their prototypes and must treat them cautiously. + +In perltidy this is implemented in the tokenizer by marking token following a +B keyword as a special type B. When formatting is being done, +whitespace following this token type is generally left unchanged as a precaution +against changing program behavior. This is excessively conservative but simple +and easy to implement. Keywords which are treated similarly to B include +B, B, B, B. Changes in spacing around parameters +following these keywords may have to be made manually. For example, the space, +or lack of space, after the parameter $foo in the following line will be +unchanged in formatting. + + system($foo ); + system($foo); + +To find if a token is of type B you can use B. For the +first line above the result is + + 1: system($foo ); + 1: kkkkkk{ZZZZb}; + +which shows that B is type B (keyword) and $foo is type B. + +=item B + +Despite these precautions, it is still possible to introduce syntax errors with +some asymmetric whitespace rules, particularly when call parameters are not +placed in containing parens or braces. For example, the following two lines will +be parsed by perl without a syntax error: + + # original programming, syntax ok + my @newkeys = map $_-$nrecs+@data, @oldkeys; + + # perltidy default, syntax ok + my @newkeys = map $_ - $nrecs + @data, @oldkeys; + +But the following will give a syntax error: + + # perltidy -nwrs='-' + my @newkeys = map $_ -$nrecs + @data, @oldkeys; + +For another example, the following two lines will be parsed without syntax error: + + # original programming, syntax ok + for my $severity ( reverse $SEVERITY_LOWEST+1 .. $SEVERITY_HIGHEST ) { ... } + + # perltidy default, syntax ok + for my $severity ( reverse $SEVERITY_LOWEST + 1 .. $SEVERITY_HIGHEST ) { ... } + +But the following will give a syntax error: + + # perltidy -nwrs='+', syntax error: + for my $severity ( reverse $SEVERITY_LOWEST +1 .. $SEVERITY_HIGHEST ) { ... } + +To avoid subtle parsing problems like this, it is best to avoid spacing a +binary operator asymetrically with a space on the left but not on the right. + +=item B When an opening paren follows a Perl keyword, no space is introduced after the keyword, unless it is (by default) one of these: - my local our and or eq ne if else elsif until unless + my local our and or xor eq ne if else elsif until unless while for foreach return switch case given when These defaults can be modified with two commands: @@ -1057,7 +1339,7 @@ keywords (my, local, our) you could use B<-nsak="*" -sak="my local our">. To put a space after all keywords, see the next item. -=item Space between all keywords and opening parens +=item B When an opening paren follows a function or keyword, no space is introduced after the keyword except for the keywords noted in the previous item. To @@ -1066,12 +1348,12 @@ use the command: B<-skp> or B<--space-keyword-paren> -You will probably also want to use the flag B<-sfp> (next item) too. +You may also want to use the flag B<-sfp> (next item) too. -=item Space between all function names and opening parens +=item B -When an opening paren follows a function the default is not to introduce -a space. To cause a space to be introduced use: +When an opening paren follows a function the default and recommended formatting +is not to introduce a space. To cause a space to be introduced use: B<-sfp> or B<--space-function-paren> @@ -1080,6 +1362,32 @@ B<-sfp> or B<--space-function-paren> You will probably also want to use the flag B<-skp> (previous item) too. +The reason this is not recommended is that spacing a function paren can make a +program vulnerable to parsing problems by Perl. For example, the following +two-line program will run as written but will have a syntax error if +reformatted with -sfp: + + if ( -e filename() ) { print "I'm here\n"; } + sub filename { return $0 } + +In this particular case the syntax error can be removed if the line order is +reversed, so that Perl parses 'sub filename' first. + +=item B<-fpva> or B<--function-paren-vertical-alignment> + +A side-effect of using the B<-sfp> flag is that the parens may become vertically +aligned. For example, + + # perltidy -sfp + myfun ( $aaa, $b, $cc ); + mylongfun ( $a, $b, $c ); + +This is the default behavior. To prevent this alignment use B<-nfpva>: + + # perltidy -sfp -nfpva + myfun ( $aaa, $b, $cc ); + mylongfun ( $a, $b, $c ); + =item B<-spp=n> or B<--space-prototype-paren=n> This flag can be used to control whether a function prototype is preceded by a space. For example, the following prototype does not have a space. @@ -1099,7 +1407,99 @@ applying the different options would be: sub usage(); # n=1 [default; follows input] sub usage (); # n=2 [space] -=item Trimming whitespace around C quotes +=item B<-kpit=n> or B<--keyword-paren-inner-tightness=n> + +The space inside of an opening paren, which itself follows a certain keyword, +can be controlled by this parameter. The space on the inside of the +corresponding closing paren will be treated in the same (balanced) manner. +This parameter has precedence over any other paren spacing rules. The values +of B are as follows: + + -kpit=0 means always put a space (not tight) + -kpit=1 means ignore this parameter [default] + -kpit=2 means never put a space (tight) + +To illustrate, the following snippet is shown formatted in three ways: + + if ( seek( DATA, 0, 0 ) ) { ... } # perltidy (default) + if (seek(DATA, 0, 0)) { ... } # perltidy -pt=2 + if ( seek(DATA, 0, 0) ) { ... } # perltidy -pt=2 -kpit=0 + +In the second case the -pt=2 parameter makes all of the parens tight. In the +third case the -kpit=0 flag causes the space within the 'if' parens to have a +space, since 'if' is one of the keywords to which the -kpit flag applies by +default. The remaining parens are still tight because of the -pt=2 parameter. + +The set of keywords to which this parameter applies are by default are: + + if elsif unless while until for foreach + +These can be changed with the parameter B<-kpitl=s> described in the next section. + + +=item B<-kpitl=string> or B<--keyword-paren-inner-tightness=string> + +This command can be used to change the keywords to which the the B<-kpit=n> +command applies. The parameter B is a required list either keywords or +functions, which should be placed in quotes if there are more than one. By +itself, this parameter does not cause any change in spacing, so the B<-kpit=n> +command is still required. + +For example, the commands C<-kpitl="if else while" -kpit=2> will cause the just +the spaces inside parens following 'if', 'else', and 'while' keywords to +follow the tightness value indicated by the B<-kpit=2> flag. + +=item B<-lop> or B<--logical-padding> + +In the following example some extra space has been inserted on the second +line between the two open parens. This extra space is called "logical padding" +and is intended to help align similar things vertically in some logical +or ternary expressions. + + # perltidy [default formatting] + $same = + ( ( $aP eq $bP ) + && ( $aS eq $bS ) + && ( $aT eq $bT ) + && ( $a->{'title'} eq $b->{'title'} ) + && ( $a->{'href'} eq $b->{'href'} ) ); + +Note that this is considered to be a different operation from "vertical +alignment" because space at just one line is being adjusted, whereas in +"vertical alignment" the spaces at all lines are being adjusted. So it sort of +a local version of vertical alignment. + +Here is an example involving a ternary operator: + + # perltidy [default formatting] + $bits = + $top > 0xffff ? 32 + : $top > 0xff ? 16 + : $top > 1 ? 8 + : 1; + +This behavior is controlled with the flag B<--logical-padding>, which is set +'on' by default. If it is not desired it can be turned off using +B<--nological-padding> or B<-nlop>. The above two examples become, with +B<-nlop>: + + # perltidy -nlop + $same = + ( ( $aP eq $bP ) + && ( $aS eq $bS ) + && ( $aT eq $bT ) + && ( $a->{'title'} eq $b->{'title'} ) + && ( $a->{'href'} eq $b->{'href'} ) ); + + # perltidy -nlop + $bits = + $top > 0xffff ? 32 + : $top > 0xff ? 16 + : $top > 1 ? 8 + : 1; + + +=item B quotes> B<-tqw> or B<--trim-qw> provide the default behavior of trimming spaces around multi-line C quotes and indenting them appropriately. @@ -1111,22 +1511,22 @@ some versions of perl, trimming C quotes changes the syntax tree. =item B<-sbq=n> or B<--space-backslash-quote=n> -Lines like +lines like $str1=\"string1"; $str2=\'string2'; can confuse syntax highlighters unless a space is included between the backslash and the single or double quotation mark. -This can be controlled with the value of B as follows: +this can be controlled with the value of B as follows: -sbq=0 means no space between the backslash and quote -sbq=1 means follow the example of the source code -sbq=2 means always put a space between the backslash and quote -The default is B<-sbq=1>, meaning that a space will be used 0if there is one in the source code. +The default is B<-sbq=1>, meaning that a space will be used if there is one in the source code. -=item Trimming trailing whitespace from lines of POD +=item B B<-trp> or B<--trim-pod> will remove trailing whitespace from lines of POD. The default is not to do this. @@ -1218,7 +1618,7 @@ To deactivate this feature, use B<-nhsc> or B<--nohanging-side-comments>. If block comments are preceded by a blank line, or have no leading whitespace, they will not be mistaken as hanging side comments. -=item Closing Side Comments +=item B A closing side comment is a special comment which perltidy can automatically create and place after the closing brace of a code block. @@ -1428,7 +1828,7 @@ else. You can always remove them with B<-dcsc>. =back -=item Static Block Comments +=item B Static block comments are block comments with a special leading pattern, C<##> by default, which will be treated slightly differently from other @@ -1521,7 +1921,7 @@ spaces (or whatever B<-ci=n> has been set to), if possible. =back -=item Static Side Comments +=item B Static side comments are side comments with a special leading pattern. This option can be useful for controlling how commented code is displayed @@ -1551,33 +1951,26 @@ expression to be formed. =back - =back =head2 Skipping Selected Sections of Code Selected lines of code may be passed verbatim to the output without any -formatting. This feature is enabled by default but can be disabled with -the B<--noformat-skipping> or B<-nfs> flag. It should be used sparingly to -avoid littering code with markers, but it might be helpful for working -around occasional problems. For example it might be useful for keeping -the indentation of old commented code unchanged, keeping indentation of -long blocks of aligned comments unchanged, keeping certain list -formatting unchanged, or working around a glitch in perltidy. - -=over 4 +formatting by marking the starting and ending lines with special comments. +There are two options for doing this. The first option is called +B<--format-skipping> or B<-fs>, and the second option is called +B<--code-skipping> or B<-cs>. -=item B<-fs>, B<--format-skipping> +In both cases the lines of code will be output without any changes. +The difference is that in B<--format-skipping> +perltidy will still parse the marked lines of code and check for errors, +whereas in B<--code-skipping> perltidy will simply pass the lines to the output without any checking. -This flag, which is enabled by default, causes any code between -special beginning and ending comment markers to be passed to the -output without formatting. The default beginning marker is #<<< -and the default ending marker is #>>> but they -may be changed (see next items below). Additional text may appear on -these special comment lines provided that it is separated from the -marker by at least one space. For example +Both of these features are enabled by default and are invoked with special +comment markers. B<--format-skipping> uses starting and ending markers '#<<<' +and '#>>>', like this: - #<<< do not let perltidy touch this + #<<< format skipping: do not let perltidy change my nice formatting my @list = (1, 1, 1, 1, 2, 1, @@ -1585,12 +1978,69 @@ marker by at least one space. For example 1, 4, 6, 4, 1,); #>>> -The comment markers may be placed at any location that a block comment may -appear. If they do not appear to be working, use the -log flag and examine the -F<.LOG> file. Use B<-nfs> to disable this feature. +B<--code-skipping> uses starting and ending markers '#<>V', like +this: + + #< | _ | ] + | <''> + ] + }; + + #>>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. + +It is recommended to use B<--code-skipping> only if you need to hide a block of +an extended syntax which would produce errors if parsed by perltidy, and use +B<--format-skipping> otherwise. This is because the B<--format-skipping> +option provides the benefits of error checking, and there are essentially no +limitations on which lines to which it can be applied. The B<--code-skipping> +option, on the other hand, does not do error checking and its use is more +restrictive because the code which remains, after skipping the marked lines, +must be syntactically correct code with balanced containers. + +These features should be used sparingly to avoid littering code with markers, +but they can be helpful for working around occasional problems. + +Note that it may be possible to avoid the use of B<--format-skipping> for the +specific case of a comma-separated list of values, as in the above example, by +simply inserting a blank or comment somewhere between the opening and closing +parens. See the section L. + +The following sections describe the available controls for these options. They +should not normally be needed. + +=over 4 + +=item B<-fs>, B<--format-skipping> + +As explained above, this flag, which is enabled by default, causes any code +between special beginning and ending comment markers to be passed to the output +without formatting. The code between the comments is still checked for errors +however. The default beginning marker is #<<< and the default ending marker is +#>>>. + +Format skipping begins when a format skipping beginning comment is seen and +continues until a format-skipping ending comment is found. + +This feature can be disabled with B<-nfs>. This should not normally be necessary. =item B<-fsb=string>, B<--format-skipping-begin=string> +This and the next parameter allow the special beginning and ending comments to +be changed. However, it is recommended that they only be changed if there is a +conflict between the default values and some other use. If they are used, it +is recommended that they only be entered in a B<.perltidyrc> file, rather than +on a command line. This is because properly escaping these parameters on a +command line can be difficult. + +If changed comment markers do not appear to be working, use the B<-log> flag and +examine the F<.LOG> file to see if and where they are being detected. + The B<-fsb=string> parameter may be used to change the beginning marker for format skipping. The default is equivalent to -fsb='#<<<'. The string that you enter must begin with a # and should be in quotes as necessary to get past @@ -1606,10 +2056,34 @@ Some examples show how example strings become patterns: =item B<-fse=string>, B<--format-skipping-end=string> -The B<-fsb=string> is the corresponding parameter used to change the +The B<-fse=string> is the corresponding parameter used to change the ending marker for format skipping. The default is equivalent to -fse='#<<<'. +The beginning and ending strings may be the same, but it is preferable +to make them different for clarity. + +=item B<-cs>, B<--code-skipping> + +As explained above, this flag, which is enabled by default, causes any code +between special beginning and ending comment markers to be directly passed to +the output without any error checking or formatting. Essentially, perltidy +treats it as if it were a block of arbitrary text. The default beginning +marker is #<>V. + +This feature can be disabled with B<-ncs>. This should not normally be +necessary. + +=item B<-csb=string>, B<--code-skipping-begin=string> + +This may be used to change the beginning comment for a B<--code-skipping> section, and its use is similar to the B<-fsb=string>. +The default is equivalent to -csb='#<, B<--code-skipping-end=string> + +This may be used to change the ending comment for a B<--code-skipping> section, and its use is similar to the B<-fse=string>. +The default is equivalent to -cse='#>>V'. + =back =head2 Line Break Control @@ -1704,7 +2178,7 @@ this parameter. This parameter is a character string, giving a list of block types separated by commas or spaces. For example, to cuddle code blocks of type sort, map and grep, in addition to the default types, the string could be set to - + -cbl="sort map grep" or equivalently @@ -1890,6 +2364,142 @@ separately if desired: -ohbr or --opening-hash-brace-right -osbr or --opening-square-bracket-right +=item B<-bbhb=n>, B<--break-before-hash-brace=n> and related flags + +When a list of items spans multiple lines, the default formatting is to place +the opening brace (or other container token) at the end of the starting line, +like this: + + $romanNumerals = { + one => 'I', + two => 'II', + three => 'III', + four => 'IV', + }; + +This flag can change the default behavior to cause a line break to be placed +before the opening brace according to the value given to the integer B: + + -bbhb=0 never break [default] + -bbhb=1 stable: break if the input script had a break + -bbhb=2 break if list is 'complex' (see note below) + -bbhb=3 always break + +For example, + + # perltidy -bbhb=3 + $romanNumerals = + { + one => 'I', + two => 'II', + three => 'III', + four => 'IV', + }; + +There are several points to note about this flag: + +=over 4 + +=item * + +This parameter only applies if the opening brace is preceded by an '=' +or '=>'. + +=item * + +This parameter only applies if the contents of the container looks like a list. +The contents need to contain some commas or '=>'s at the next interior level to +be considered a list. + +=item * + +For the B option, a list is considered 'complex' if it is part of a nested list +structure which spans multiple lines in the input file. + +=item * + +If multiple opening tokens have been 'welded' together with the B<-wn> parameter, then +this parameter has no effect. + +=item * + +The indentation of the braces will normally be one level of continuation +indentation by default. This can be changed with the parameter +B<-bbhbi=n> in the next section. + +=item * + +Similar flags for controlling parens and square brackets are given in the subsequent section. + +=back + +=item B<-bbhbi=n>, B<--break-before-hash-brace-and-indent=n> + +This flag is a companion to B<-bbhb=n> for controlling the indentation of an opening hash brace +which is placed on a new line by that parameter. The indentation is as follows: + + -bbhbi=0 one continuation level [default] + -bbhbi=1 outdent by one continuation level + -bbhbi=2 indent one full indentation level + +For example: + + # perltidy -bbhb=3 -bbhbi=1 + $romanNumerals = + { + one => 'I', + two => 'II', + three => 'III', + four => 'IV', + }; + + # perltidy -bbhb=3 -bbhbi=2 + $romanNumerals = + { + one => 'I', + two => 'II', + three => 'III', + four => 'IV', + }; + +Note that this parameter has no effect unless B<-bbhb=n> is also set. + +=item B<-bbsb=n>, B<--break-before-square-bracket=n> + +This flag is similar to the flag described above, except it applies to lists contained within square brackets. + + -bbsb=0 never break [default] + -bbsb=1 stable: break if the input script had a break + -bbsb=2 break if list is 'complex' (part of nested list structure) + -bbsb=3 always break + +=item B<-bbsbi=n>, B<--break-before-square-bracket-and-indent=n> + +This flag is a companion to B<-bbsb=n> for controlling the indentation of an opening square bracket +which is placed on a new line by that parameter. The indentation is as follows: + + -bbsbi=0 one continuation level [default] + -bbsbi=1 outdent by one continuation level + -bbsbi=2 indent one full indentation level + +=item B<-bbp=n>, B<--break-before-paren=n> + +This flag is similar to B<-bbhb=n>, described above, except it applies to lists contained within parens. + + -bbp=0 never break [default] + -bbp=1 stable: break if the input script had a break + -bpb=2 break if list is 'complex' (part of nested list structure) + -bbp=3 always break + +=item B<-bbpi=n>, B<--break-before-paren-and-indent=n> + +This flag is a companion to B<-bbp=n> for controlling the indentation of an opening paren +which is placed on a new line by that parameter. The indentation is as follows: + + -bbpi=0 one continuation level [default] + -bbpi=1 outdent by one continuation level + -bbpi=2 indent one full indentation level + =item B<-wn>, B<--weld-nested-containers> The B<-wn> flag causes closely nested pairs of opening and closing container @@ -1914,10 +2524,12 @@ For example: When this flag is set perltidy makes a preliminary pass through the file and identifies all nested pairs of containers. To qualify as a nested pair, the -closing container symbols must be immediately adjacent. The opening symbols -must either be adjacent, or, if the outer opening symbol is an opening -paren, they may be separated by any single non-container symbol or something -that looks like a function evaluation. +closing container symbols must be immediately adjacent and the opening symbols +must either (1) be adjacent as in the above example, or (2) have an anonymous +sub declaration following an outer opening container symbol which is not a +code block brace, or (3) have an outer opening paren separated from the inner +opening symbol by any single non-container symbol or something that looks like +a function evaluation, as illustrated in the next examples. Any container symbol may serve as both the inner container of one pair and as the outer container of an adjacent pair. Consequently, any number of adjacent @@ -1974,6 +2586,16 @@ Here is an example illustrating a welded container within a welded containers: $m ) ); +The welded closing tokens are by default on a separate line but this can be +modified with the B<-vtc=n> flag (described in the next section). For example, +the same example adding B<-vtc=2> is + + # perltidy -wn -vtc=2 + $x->badd( bmul( + $class->new( abs( + $sx * int( $xr->numify() ) & $sy * int( $yr->numify() ) ) ), + $m ) ); + This format option is quite general but there are some limitations. One limitation is that any line length limit still applies and can cause long @@ -1986,6 +2608,101 @@ specially in perltidy. Finally, the stacking of containers defined by this flag have priority over any other container stacking flags. This is because any welding is done first. +=item B<-wnxl=s>, B<--weld-nested-exclusion-list> + +The B<-wnxl=s> flag provides some control over the types of containers which +can be welded. The B<-wn> flag by default is "greedy" in welding adjacent +containers. If it welds more types of containers than desired, this flag +provides a capability to reduce the amount of welding by specifying a list +of things which should B be welded. + +The logic in perltidy to apply this is straightforward. As each container +token is being considered for joining a weld, any exclusion rules are consulted +and used to reject the weld if necessary. + +This list is a string with space-separated items. Each item consists of up to +three pieces of information: (1) an optional position, (2) an optional +preceding type, and (3) a container type. + +The only required piece of information is a container type, which is one of +'(', '[', '{' or 'q'. The first three of these are container tokens and the +last represents a quoted list. For example the string + + -wnxl='[ { q' + +means do B include square-bracets, braces, or quotes in any welds. The only unspecified +container is '(', so this string means that only welds involving parens will be made. + +To illustrate, following welded snippet consists of a chain of three welded +containers with types '(' '[' and 'q': + + # perltidy -wn + skip_symbols( [ qw( + Perl_dump_fds + Perl_ErrorNo + Perl_GetVars + PL_sys_intern + ) ] ); + +Even though the qw term uses parens as the quote delimiter, it has a special +type 'q' here. If it appears in a weld it always appears at the end of the +welded chain. + +Any of the container types '[', '{', and '(' may be prefixed with a position +indicator which is either '^', to indicate the first token of a welded +sequence, or '.', to indicate an interior token of a welded sequence. (Since +a quoted string 'q' always ends a chain it does need a position indicator). + +For example, if we do not want a sequence of welded containers to start with a +square bracket we could use + + -wnxl='^[' + +In the above snippet, there is a square bracket but it does not start the chain, +so the formatting would be unchanged if it were formatted with this restriction. + +A third optional item of information which can be given is an alphanumeric +letter which is used to limit the selection further depending on the type of +token immediately before the container. If given, it goes just before the +container symbol. The possible letters are currently 'k', 'K', 'f', 'F', +'w', and 'W', with these meanings: + + 'k' matches if the previous nonblank token is a perl builtin keyword (such as 'if', 'while'), + 'K' matches if 'k' does not, meaning that the previous token is not a keyword. + 'f' matches if the previous token is a function other than a keyword. + 'F' matches if 'f' does not. + 'w' matches if either 'k' or 'f' match. + 'W' matches if 'w' does not. + +For example, compare + + # perltidy -wn + if ( defined( $_Cgi_Query{ + $Config{'methods'}{'authentication'}{'remote'}{'cgi'}{'username'} + } ) ) + +with + + # perltidy -wn -wnxl='^K( {' + if ( defined( + $_Cgi_Query{ $Config{'methods'}{'authentication'}{'remote'}{'cgi'} + {'username'} } + ) ) + +The first case does maximum welding. In the second case the leading paren is +retained by the rule (it would have been rejected if preceded by a non-keyword) +but the curly brace is rejected by the rule. + +Here are some additional example strings and their meanings: + + '^(' - the weld must not start with a paren + '.(' - the second and later tokens may not be parens + '.w(' - the second and later tokens may not keyword or function call parens + '(' - no parens in a weld + '^K(' - exclude a leading paren preceded by a non-keyword + '.k(' - exclude a secondary paren preceded by a keyword + '[ {' - exclude all brackets and braces + '[ ( ^K{' - exclude everything except nested structures like do {{ ... }} =item B of non-block curly braces, parentheses, and square brackets. @@ -2019,9 +2736,11 @@ B<--vertical-tightness-closing=n>, where by a semicolon or another closing token, and is not in a list environment. -vtc=2 never break before a closing token. + -vtc=3 Like -vtc=1 except always break before a closing token + if the corresponding opening token follows an = or =>. -The rules for B<-vtc=1> are designed to maintain a reasonable balance -between tightness and readability in complex lists. +The rules for B<-vtc=1> and B<-vtc=3> are designed to maintain a reasonable +balance between tightness and readability in complex lists. =item * @@ -2062,6 +2781,24 @@ Here are some examples: three => 'III', four => 'IV', ); + # perltidy -vtc=3 + my_function( + one => 'I', + two => 'II', + three => 'III', + four => 'IV', ); + + # perltidy -vtc=3 + %romanNumerals = ( + one => 'I', + two => 'II', + three => 'III', + four => 'IV', + ); + +In the last example for B<-vtc=3>, the opening paren is preceded by an equals +so the closing paren is placed on a new line. + The difference between B<-vt=1> and B<-vt=2> is shown here: # perltidy -lp -vt=1 @@ -2101,20 +2838,20 @@ token. If desired, vertical tightness controls can be applied independently to each of the closing container token types. The parameters for controlling parentheses are B<-pvt=n> or -B<--paren-vertical-tightness=n>, and B<-pcvt=n> or +B<--paren-vertical-tightness=n>, and B<-pvtc=n> or B<--paren-vertical-tightness-closing=n>. Likewise, the parameters for square brackets are B<-sbvt=n> or -B<--square-bracket-vertical-tightness=n>, and B<-sbcvt=n> or +B<--square-bracket-vertical-tightness=n>, and B<-sbvtc=n> or B<--square-bracket-vertical-tightness-closing=n>. Finally, the parameters for controlling non-code block braces are -B<-bvt=n> or B<--brace-vertical-tightness=n>, and B<-bcvt=n> or +B<-bvt=n> or B<--brace-vertical-tightness=n>, and B<-bvtc=n> or B<--brace-vertical-tightness-closing=n>. In fact, the parameter B<-vt=n> is actually just an abbreviation for B<-pvt=n -bvt=n sbvt=n>, and likewise B<-vtc=n> is an abbreviation -for B<-pvtc=n -bvtc=n sbvtc=n>. +for B<-pvtc=n -bvtc=n -sbvtc=n>. =item B<-bbvt=n> or B<--block-brace-vertical-tightness=n> @@ -2269,7 +3006,14 @@ example: To simplify input even further for the case in which both opening and closing non-block containers are stacked, the flag B<-sac> or B<--stack-all-containers> -is an abbreviation for B<-sot -sot>. +is an abbreviation for B<-sot -sct>. + +Please note that if both opening and closing tokens are to be stacked, then the +newer flag B<-weld-nested-containers> may be preferable because it insures that +stacking is always done symmetrically. It also removes an extra level of +unnecessary indentation within welded containers. It is able to do this +because it works on formatting globally rather than locally, as the B<-sot> and +B<-sct> flags do. =item B<-dnl>, B<--delete-old-newlines> @@ -2288,7 +3032,7 @@ This flag does not prevent perltidy from eliminating existing line breaks; see B<--freeze-newlines> to completely prevent changes to line break points. -=item Controlling whether perltidy breaks before or after operators +=item B Four command line parameters provide some control over whether a line break should be before or after specific token types. @@ -2354,19 +3098,18 @@ single perl operator except B<=> on a -wbb flag. =head2 Controlling List Formatting -Perltidy attempts to place comma-separated arrays of values in tables -which look good. Its default algorithms usually work well, and they -have been improving with each release, but several parameters are -available to control list formatting. - -=over 4 - -=item B<-boc>, B<--break-at-old-comma-breakpoints> +Perltidy attempts to format lists of comma-separated values in tables which +look good. Its default algorithms usually work well, but sometimes they don't. +In this case, there are several methods available to control list formatting. -This flag tells perltidy to try to break at all old commas. This is not -the default. Normally, perltidy makes a best guess at list formatting, -and seldom uses old comma breakpoints. Usually this works well, -but consider: +A very simple way to prevent perltidy from changing the line breaks +within a comma-separated list of values is to insert a blank line, +comment, or side-comment anywhere between the opening and closing +parens (or braces or brackets). This causes perltidy to skip +over its list formatting logic. (The reason is that any of +these items put a constraint on line breaks, and perltidy +needs complete control over line breaks within a container to +adjust a list layout). For example, let us consider my @list = (1, 1, 1, @@ -2374,13 +3117,37 @@ but consider: 1, 3, 3, 1, 1, 4, 6, 4, 1,); -The default formatting will flatten this down to one line: +The default formatting, which allows a maximum line length of 80, +will flatten this down to one line: # perltidy (default) my @list = ( 1, 1, 1, 1, 2, 1, 1, 3, 3, 1, 1, 4, 6, 4, 1, ); -which hides the structure. Using B<-boc>, plus additional flags -to retain the original style, yields +This formatting loses important information. If we place a side comment on one +of the lines, for example, we get the following result with with default formatting +parameters: + + my @list = ( + 1, # a side comment, comment, or blank keeps list intact + 1, 1, + 1, 2, 1, + 1, 3, 3, 1, + 1, 4, 6, 4, 1, + ); + +We could achieve the same result with a blank line or full comment +anywhere between the opening and closing parens. + +For another possibility see +the -fs flag in L. + +=over 4 + +=item B<-boc>, B<--break-at-old-comma-breakpoints> + +The B<-boc> flag is another way to prevent comma-separated lists from being +reformatted. Using B<-boc> on the above example, plus additional flags to retain +the original style, yields # perltidy -boc -lp -pt=2 -vt=1 -vtc=1 my @list = (1, @@ -2390,8 +3157,8 @@ to retain the original style, yields 1, 4, 6, 4, 1,); A disadvantage of this flag is that all tables in the file -must already be nicely formatted. For another possibility see -the -fs flag in L. +must already be nicely formatted. + =item B<-mft=n>, B<--maximum-fields-per-table=n> @@ -2426,7 +3193,7 @@ being forced because B<-boc> is used). The possible values of B are: n=1 stable: break at all commas after => if container is open, EXCEPT FOR one-line containers n=2 break at all commas after =>, BUT try to form the maximum - maximum one-line container lengths + one-line container lengths n=3 do not treat commas after => specially at all n=4 break everything: like n=0 but ALSO break a short container with a => not followed by a comma when -vt=0 is used @@ -2457,7 +3224,7 @@ treated specially. In this case, an item such as "01" => 31 is treated as a single item in a table. The number of fields in this table will be determined by the same rules that are used for any other table. Here is an example. - + # perltidy -cab=3 my %last_day = ( "01" => 31, "02" => 29, "03" => 31, "04" => 30, @@ -2491,6 +3258,26 @@ or C, then the container will remain broken. Also, breaks at internal keywords C and C will normally be retained. To prevent this, and thus form longer lines, use B<-nbol>. +Please note that this flag does not duplicate old logical breakpoints. They +are merely used as a hint with this flag that a statement should remain +broken. Without this flag, perltidy will normally try to combine relatively +short expressions into a single line. + +For example, given this snippet: + + return unless $cmd = $cmd || ($dot + && $Last_Shell) || &prompt('|'); + + # perltidy -bol [default] + return + unless $cmd = $cmd + || ( $dot + && $Last_Shell ) + || &prompt('|'); + + # perltidy -nbol + return unless $cmd = $cmd || ( $dot && $Last_Shell ) || &prompt('|'); + =item B<-bom>, B<--break-at-old-method-breakpoints> By default, a method call arrow C<-E> is considered a candidate for @@ -2515,6 +3302,7 @@ This flag will also look for and keep a 'cuddled' style of calls, in which lines begin with a closing paren followed by a call arrow, as in this example: + # perltidy -bom -wn my $q = $rs->related_resultset( 'CDs' )->related_resultset( @@ -2526,6 +3314,25 @@ as in this example: You may want to include the B<-weld-nested-containers> flag in this case to keep nested braces and parens together, as in the last line. +=item B<-bos>, B<--break-at-old-semicolon-breakpoints> + +Semicolons are normally placed at the end of a statement. This means that formatted lines do not normally begin with semicolons. If the input stream has some lines which begin with semicolons, these can be retained by setting this flag. For example, consider +the following two-line input snippet: + + $z = sqrt($x**2 + $y**2) + ; + +The default formatting will be: + + $z = sqrt( $x**2 + $y**2 ); + +The result using B keeps the isolated semicolon: + + $z = sqrt( $x**2 + $y**2 ) + ; + +The default is not to do this, B<-nbos>. + =item B<-bok>, B<--break-at-old-keyword-breakpoints> @@ -2545,7 +3352,7 @@ form longer lines, use B<-nbot>. By default, if an attribute list is broken at a C<:> in the source file, then it will remain broken. For example, given the following code, the line breaks at the ':'s will be retained: - + my @field : field : Default(1) @@ -2556,12 +3363,55 @@ on a single line if possible. To prevent this, and thereby always form longer lines, use B<-nboa>. +=item B + +Two command line parameters provide detailed control over whether +perltidy should keep an old line break before or after a specific +token type: + +B<-kbb=s> or B<--keep-old-breakpoints-before=s>, and + +B<-kba=s> or B<--keep-old-breakpoints-after=s> + +These parameters are each followed by a quoted string, B, containing +a list of token types (separated only by spaces). No more than one of each +of these parameters should be specified, because repeating a +command-line parameter always overwrites the previous one before +perltidy ever sees it. + +For example, -kbb='=>' means that if an input line begins with a '=>' then the +output script should also have a line break before that token. + +For example, given the script: + + method 'foo' + => [ Int, Int ] + => sub { + my ( $self, $x, $y ) = ( shift, @_ ); + ...; + }; + + # perltidy [default] + method 'foo' => [ Int, Int ] => sub { + my ( $self, $x, $y ) = ( shift, @_ ); + ...; + }; + + # perltidy -kbb='=>' + method 'foo' + => [ Int, Int ] + => sub { + my ( $self, $x, $y ) = ( shift, @_ ); + ...; + }; + =item B<-iob>, B<--ignore-old-breakpoints> Use this flag to tell perltidy to ignore existing line breaks to the maximum extent possible. This will tend to produce the longest possible containers, regardless of type, which do not exceed the line length -limit. +limit. But please note that this parameter has priority over all +other parameters requesting that certain old breakpoints be kept. =item B<-kis>, B<--keep-interior-semicolons> @@ -2716,7 +3566,7 @@ This parameter is a list of block type keywords to which the flag B<-blbc> should apply. The section L<"Specifying Block Types"> explains how to list block types. -=item Note on using the B<-blao> and B<-blbc> options. +=item B B<-blao> and B<-blbc> options. These blank line controls introduce a certain minimum number of blank lines in the text, but the final number of blank lines may be greater, depending on @@ -2732,7 +3582,7 @@ this using perltidy -blao=2 -blbc=2 -blaol='*' -blbcl='*' filename Now suppose the script continues to be developed, but at some later date we -decide we don't want these spaces after all. we might expect that running with +decide we don't want these spaces after all. We might expect that running with the flags B<-blao=0> and B<-blbc=0> will undo them. However, by default perltidy retains single blank lines, so the blank lines remain. @@ -2995,9 +3845,10 @@ perltidy act as a filter on one file only. These can be overridden by placing B<-nst> and/or B<-nse> after the -pbp parameter. Also note that the value of continuation indentation, -ci=4, is equal to the -value of the full indentation, -i=4. In some complex statements perltidy will -produce nicer results with -ci=2. This can be implemented by including -ci=2 -after the -pbp parameter. For example, +value of the full indentation, -i=4. It is recommended that the either (1) the +parameter B<-ci=2> be used instead, or the flag B<-xci> be set. This will help +show structure, particularly when there are ternary statements. The following +snippet illustrates these options. # perltidy -pbp $self->{_text} = ( @@ -3023,13 +3874,25 @@ after the -pbp parameter. For example, : ' elsewhere in this document' ); + # perltidy -pbp -xci + $self->{_text} = ( + !$section ? '' + : $type eq 'item' ? "the $section entry" + : "the section on $section" + ) + . ( $page + ? ( $section ? ' in ' : '' ) . "the $page$page_ext manpage" + : ' elsewhere in this document' + ); + +The B<-xci> flag was developed after the B<-pbp> parameters were published so you need +to include it separately. -=item One-line blocks +=item B There are a few points to note regarding one-line blocks. A one-line block is something like this, - if ($x > 0) { $y = 1 / $x } where the contents within the curly braces is short enough to fit on a single line. @@ -3133,7 +3996,7 @@ is broken in multiple lines in the source. =head2 Controlling Vertical Alignment -Vertical alignment refers to lining up certain symbols in list of consecutive +Vertical alignment refers to lining up certain symbols in a list of consecutive similar lines to improve readability. For example, the "fat commas" are aligned in the following statement: @@ -3143,11 +4006,11 @@ aligned in the following statement: Proto => 'tcp' ); -The only explicit control on vertical alignment is to turn it off using -B<-novalign>, a flag mainly intended for debugging. However, vertical -alignment can be forced to stop and restart by selectively introducing blank -lines. For example, a blank has been inserted in the following code -to keep somewhat similar things aligned. +Vertical alignment can be completely turned off using B<-novalign>, a flag +mainly intended for debugging. However, vertical alignment can be forced to +stop and restart by selectively introducing blank lines. For example, a blank +has been inserted in the following code to keep somewhat similar things +aligned. %option_range = ( 'format' => [ 'tidy', 'html', 'user' ], @@ -3160,12 +4023,26 @@ to keep somewhat similar things aligned. 'square-bracket-tightness' => [ 0, 2 ], ); +Vertical alignment is implemented by locally increasing an existing blank space +to produce alignment with an adjacent line. It cannot occur if there is no +blank space to increase. So if a particular space is removed by one of the +existing controls then vertical alignment cannot occur. Likewise, if a space is +added with one of the controls, then vertical alignment might occur. + +For example, + + # perltidy -nwls='=>' + $data = $pkg->new( + PeerAddr=> join( ".", @port[ 0 .. 3 ] ), + PeerPort=> $port[4] * 256 + $port[5], + Proto=> 'tcp' + ); =head2 Other Controls =over 4 -=item Deleting selected text +=item B Perltidy can selectively delete comments and/or pod documentation. The command B<-dac> or B<--delete-all-comments> will delete all comments @@ -3177,14 +4054,14 @@ The command B<-dp> or B<--delete-pod> will remove all pod documentation Two commands which remove comments (but not pod) are: B<-dbc> or B<--delete-block-comments> and B<-dsc> or B<--delete-side-comments>. -(Hanging side comments will be deleted with block comments here.) +(Hanging side comments will be deleted with side comments here.) The negatives of these commands also work, and are the defaults. When block comments are deleted, any leading 'hash-bang' will be retained. Also, if the B<-x> flag is used, any system commands before a leading hash-bang will be retained (even if they are in the form of comments). -=item Writing selected text to a file +=item B When perltidy writes a formatted text file, it has the ability to also send selected text to a file with a F<.TEE> extension. This text can @@ -3198,11 +4075,11 @@ not comments). The commands which write comments (but not pod) are: B<-tbc> or B<--tee-block-comments> and B<-tsc> or B<--tee-side-comments>. -(Hanging side comments will be written with block comments here.) +(Hanging side comments will be written with side comments here.) The negatives of these commands also work, and are the defaults. -=item Using a F<.perltidyrc> command file +=item B command file> If you use perltidy frequently, you probably won't be happy until you create a F<.perltidyrc> file to avoid typing commonly-used parameters. @@ -3295,7 +4172,7 @@ and B<--dump-short-names>, all described below, may all be helpful. =back -=item Creating a new abbreviation +=item B A special notation is available for use in a F<.perltidyrc> file for creating an abbreviation for a group @@ -3313,16 +4190,24 @@ where B is the abbreviation, and B, etc, are existing parameters I. The main syntax requirement is that the new abbreviation along with its opening curly brace must begin on a new line. Space before and after the curly braces is optional. -For a -specific example, the following line - airy {-bl -pt=0 -bt=0 -sbt=0} +For a specific example, the following line + + oneliner { --maximum-line-length=0 --noadd-newlines --noadd-terminal-newline} + +or equivalently with abbreviations + + oneliner { -l=0 -nanl -natnl } -could be placed in a F<.perltidyrc> file, and then invoked at will with +could be placed in a F<.perltidyrc> file to temporarily override the maximum +line length with a large value, to temporarily prevent new line breaks from +being added, and to prevent an extra newline character from being added the +file. All other settings in the F<.perltidyrc> file still apply. Thus it +provides a way to format a long 'one liner' when perltidy is invoked with - perltidy -airy somefile.pl + perltidy --oneliner ... -(Either C<-airy> or C<--airy> may be used). +(Either C<-oneliner> or C<--oneliner> may be used). =item Skipping leading non-perl commands with B<-x> or B<--look-for-hash-bang> @@ -3335,7 +4220,12 @@ lines before the "hash-bang" line. This option also invokes perl with a allow perltidy to parse interactive VMS scripts, but it should be used for any script which is normally invoked with C. -=item Making a file unreadable +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. + +=item B The goal of perltidy is to improve the readability of files, but there are two commands which have the opposite effect, B<--mangle> and @@ -3362,7 +4252,7 @@ to make the minimum number of one-line blocks. Another use for B<--mangle> is to combine it with B<-dac> to reduce the file size of a perl script. -=item Debugging +=item B The following flags are available for debugging: @@ -3411,10 +4301,50 @@ increasing size, when multiple files are being processed. This is useful during program development, when large numbers of files with varying sizes are processed, because it can reduce virtual memory usage. +B<--maximum-file-size-mb=n> or B<-maxfs=n> specifies the maximum file size in +megabytes that perltidy will attempt to format. This parameter is provided to +avoid causing system problems by accidentally attempting to format an extremely +large data file. Most perl scripts are less than about 2 MB in size. The +integer B has a default value of 10, so perltidy will skip formatting files +which have a size greater than 10 MB. The command to increase the limit to 20 +MB for example would be + + perltidy -maxfs=20 + +This only applies to files specified by filename on the command line. + +B<--maximum-level-errors=n> or B<-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 B. 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 B, or set B. + +For example, the following script has level error of 3 and will be output verbatim + + Input and default output: + {{{ + + + perltidy -maxle=100 + { + { + { + +B<--maximum-unexpected-errors=n> or B<-maxue=n> specifies the maximum number of +unexpected tokenization errors are allowed before formatting is skipped and a +script is output verbatim. The intention is to avoid accidentally formatting +a non-perl script, such as an html file for example. This check can be turned +off by setting B. + +A recommended value is B. However, the default is B (skip this check) +to avoid causing problems with scripts which have extended syntaxes. + B<-DEBUG> will write a file with extension F<.DEBUG> for each input file showing the tokenization of all lines of code. -=item Working with MakeMaker, AutoLoader and SelfLoader +=item B The first $VERSION line of a file which might be eval'd by MakeMaker is passed through unchanged except for indentation. @@ -3428,7 +4358,7 @@ Likewise, if the SelfLoader module is used, perltidy will continue formatting code after seeing a __DATA__ line. Use B<--nolook-for-selfloader>, or B<-nlsl>, to deactivate this feature. -=item Working around problems with older version of Perl +=item B Perltidy contains a number of rules which help avoid known subtleties and problems with older versions of perl, and these rules always @@ -3552,7 +4482,7 @@ default, the module Html::Entities is used to encode special symbols. This may not be the right thing for some browser/language combinations. Use --nohtml-entities or -nhent to prevent this. -=item Style Sheets +=item B