X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=bin%2Fperltidy;h=9839ed4ef8e9447aa16b656e42cefd0a5e7b8206;hb=refs%2Ftags%2Fupstream%2F20180220;hp=174f792ab0b17455702263ac7971e4b07396fb4c;hpb=d08e4809a710a08f2cc0cb5a6f3964582098e84c;p=perltidy.git diff --git a/bin/perltidy b/bin/perltidy index 174f792..9839ed4 100755 --- a/bin/perltidy +++ b/bin/perltidy @@ -471,6 +471,9 @@ unstable editing). =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 @@ -1053,6 +1056,23 @@ multi-line C quotes to be left unchanged. This option will not normally be necessary, but was added for testing purposes, because in some versions of perl, trimming C quotes changes the syntax tree. +=item B<-sbq=n> or B<--space-backslash-quote=n> + +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: + + -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. + =item Trimming trailing whitespace from lines of POD B<-trp> or B<--trim-pod> will remove trailing whitespace from lines of POD. @@ -1214,7 +1234,7 @@ order to update, delete, and format them. Any comment identified as a closing side comment will be placed just a single space to the right of its closing brace. -=item B<-cscl=string>, or B<--closing-side-comment-list-string> +=item B<-cscl=string>, or B<--closing-side-comment-list> where C is a list of block types to be tagged with closing side comments. By default, all code block types preceded by a keyword or @@ -1274,6 +1294,7 @@ side comments. If B is used, the results will be the same as B whenever the resulting line length is less than the maximum allowed. + =item B<-cscb>, or B<--closing-side-comments-balanced> When using closing-side-comments, and the closing-side-comment-maximum-text @@ -1582,6 +1603,133 @@ alternatives: zzz(); } +=item B<-cb>, B<--cuddled-blocks> + +This flag enables the "cuddled else" format style on a chain of specified block +types. The default is to apply it to a chain consisting of try-catch-finally +blocks, but it can apply to any desired chain of blocks by specifying their +names on a separate parameter B<-cbl>, described in the next section. + + # perltidy -cb: + try { + throw Error::Simple( "ok 2\n", 2 ); + } catch Error::Simple with { + my $err = shift; + print "$err"; + } finally { + print "ok 3\n"; + }; + +Cuddling between a pair of code blocks requires that the closing brace of the +first block start a new line. If this block is entirely on one line in the +input file, it is necessary to decide if it should be broken to allow cuddling. +This decision is controlled by the flag B<-cbo=n> discussed below. The default +and recommended value of B<-cbo=1> bases this decision on the first block in +the chain. If it spans multiple lines then cuddling is made and continues +along the chain, regardless of the sizes of subsequent blocks. Otherwise, short +lines remain intact. + +So for example, the B<-cb> flag would not have any effect if the above snippet +is rewritten as + + try { throw Error::Simple( "ok 2\n", 2 ); } + catch Error::Simple with { my $err = shift; print "$err"; } + finally { print "ok 3\n"; }; + +If the first block spans multiple lines, then cuddling can be done and will +continue for the subsequent blocks in the chain, as illustrated in the previous +snippet. + +If there are blank lines between cuddled blocks they will be eliminated. If +there are comments after the closing brace where cuddling would occur then +cuddling will be prevented. If this occurs, cuddling will restart later in the +chain if possible. + +The default for this parameter is B<--nocuddled-blocks> + +=item B<-cbl>, B<--cuddled-block-list> + +The block types to which the B<-cuddled-blocks> style applies is defined by +this parameter. This parameter is a character string, giving a list of +block types separated by dashes. + +The default value for this string is + + -cbl="try-catch-finally" + +This string will cause cuddled formatting to be applied to every block in a chain +starting with a "try" and followed by any number of "catch" and "finally" +blocks. + +In general, a string describing a chain of blocks has the form + + -cbl="word1-word2-word3-...-wordn" + +In this case, a chain begins when an opening block brace preceded by word1 in +the list is encountered. The chain continues if the closing block brace is +followed immediately by any of word2, word3, etc. + +If the leading word, word1, might be repeated later in a chain then it should +also be included amoung the secondary words. + +Multiple chain types may be specified by separating the strings with commas or +spaces. So for example if we have two chains of code blocks, f1-f2-f3 and g1-g2-g3-g4, +they could be specified as + + -cbl="f1-f2-f3 g1-g2-g3-g4" +or + -cbl=f1-f2-f3,g1-g2-g3-g4 + +Spaces are easier to read but commas may avoid quotation difficulties when +entering data in a command shell. + +To define secondary words that apply to all block types, other than those explicitly specified, +the leading word can be omitted. For example, the built-in cuddled-else format specified by +the B<-ce> flag can be approximately specified by + + -cbl="if-else-elsif unless-else-elsif -continue" +or + -cbl=if-else-elsif,unless-else-elsif,-continue + +The final string -continue allows cuddling the optional continue block +which may follow may other block types. + +As a diagnostic check, the flag B<--dump-cuddled-block-list> or B<-dcbl> can be +used to view the hash of values this flag creates. + +Finally, note that the B<-cbl> flag by itself merely specifies which blocks are formatted +with the cuddled format. It has no effect unless this formatting style is activated with +B<-cb>. + + +=item B<-cbo=n>, B<--cuddled-break-option=n> + +Cuddled formatting is only possible between a pair of code blocks if the +closing brace of the first block starts a new line. If a block is encountered +which is entirely on a single line, and cuddled formatting is selected, it is +necessary to make a decision as to whether or not to "break" the block, meaning +to cause it to span multiple lines. This parameter controls that decision. The +options are: + + cbo=0 Never force a short block to break. + cbo=1 If the first of a pair of blocks is broken in the input file, + then break the second. + cbo=2 Break open all blocks for maximal cuddled formatting. + +The default and recommended value is B. With this value, if the starting +block of a chain spans multiple lines, then a cascade of breaks will occur for +remaining blocks causing the entire chain to be cuddled. + +The option B can produce erratic cuddling if there are numerous one-line +blocks. + +The option B produces maximal cuddling but will not allow any short blocks. + +Note: at present, this option currently only applies to blocks controlled by +the B<-cb> flag. Cuddling under the B<-ce> flag corresponds approximately to +B<-cbo=1> but cannot currently be changed. + + =item B<-bl>, B<--opening-brace-on-new-line> Use the flag B<-bl> to place the opening brace on a new line: @@ -1714,7 +1862,104 @@ separately if desired: -ohbr or --opening-hash-brace-right -osbr or --opening-square-bracket-right -=item Vertical tightness of non-block curly braces, parentheses, and square brackets. +=item B<-wn>, B<--weld-nested-containers> + +The B<-wn> flag causes closely nested pairs of opening and closing container +symbols (curly braces, brackets, or parens) to be "welded" together, meaning +that they are treated as if combined into a single unit, with the indentation +of the innermost code reduced to be as if there were just a single container +symbol. + +For example: + + # default formatting + do { + { + next if $x == $y; + } + } until $x++ > $z; + + # perltidy -wn + do { { + next if $x == $y; + } } until $x++ > $z; + +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. + +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 +opening or closing symbols may join together in weld. For example, here are +three levels of wrapped function calls: + + # default formatting + my (@date_time) = Localtime( + Date_to_Time( + Add_Delta_DHMS( + $year, $month, $day, $hour, $minute, $second, + '0', $offset, '0', '0' + ) + ) + ); + + # perltidy -wn + my (@date_time) = Localtime( Date_to_Time( Add_Delta_DHMS( + $year, $month, $day, $hour, $minute, $second, + '0', $offset, '0', '0' + ) ) ); + +Notice how the indentation of the inner lines are reduced by two levels in this +case. This example also shows the typical result of this formatting, namely it +is a sandwich consisting of an initial opening layer, a central section of any +complexity forming the "meat" of the sandwich, and a final closing layer. This +predictable structure helps keep the compacted structure readable. + +The inner sandwich layer is required to be at least one line thick. If this +cannot be achieved, welding does not occur. This constraint can cause +formatting to take a couple of iterations to stabilize when it is first applied +to a script. The B<-conv> flag can be used to insure that the final format is +achieved in a single run. + +Here is an example illustrating a welded container within a welded containers: + + # default formatting + $x->badd( + bmul( + $class->new( + abs( + $sx * int( $xr->numify() ) & $sy * int( $yr->numify() ) + ) + ), + $m + ) + ); + + # perltidy -wn + $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 limitiation is that any line length limit still applies and can cause long +welded sections to be broken into multiple lines. + +Another limitation is that an opening symbol which delimits quoted text cannot +be included in a welded pair. This is because quote delimiters are treated +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 of non-block curly braces, parentheses, and square brackets. These parameters control what shall be called vertical tightness. Here are the main points: @@ -2528,6 +2773,36 @@ after the -pbp parameter. For example, =back +=head2 Controlling Vertical Alignment + +Vertical alignment refers to lining up certain symbols in list of consecutive +similar lines to improve readability. For example, the "fat commas" are +aligned in the following statement: + + $data = $pkg->new( + PeerAddr => join( ".", @port[ 0 .. 3 ] ), + PeerPort => $port[4] * 256 + $port[5], + 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. + + %option_range = ( + 'format' => [ 'tidy', 'html', 'user' ], + 'output-line-ending' => [ 'dos', 'win', 'mac', 'unix' ], + 'character-encoding' => [ 'none', 'utf8' ], + + 'block-brace-tightness' => [ 0, 2 ], + 'brace-tightness' => [ 0, 2 ], + 'paren-tightness' => [ 0, 2 ], + 'square-bracket-tightness' => [ 0, 2 ], + ); + + =head2 Other Controls =over 4 @@ -2767,6 +3042,10 @@ the problem. The following flags are available for debugging: +B<--dump-cuddled-block-list> or B<-dcbl> will dump to standard output the +internal hash of cuddled block types created by a B<-cuddled-block-list> input +string. + B<--dump-defaults> or B<-ddf> will write the default option set to standard output and quit B<--dump-profile> or B<-dpro> will write the name of the current @@ -2797,6 +3076,11 @@ Memoization can reduce run time when running perltidy repeatedly in a single process. It is on by default but can be deactivated for testing with B<-nmem>. +B<--file-size-order> or B<-fso> will cause files to be processed in order of +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<-DEBUG> will write a file with extension F<.DEBUG> for each input file showing the tokenization of all lines of code. @@ -3196,7 +3480,7 @@ perlstyle(1), Perl::Tidy(3) =head1 VERSION -This man page documents perltidy version 20170521. +This man page documents perltidy version 20180220. =head1 BUG REPORTS @@ -3208,7 +3492,7 @@ To report a new bug or problem, use the link on this page. =head1 COPYRIGHT -Copyright (c) 2000-2017 by Steve Hancock +Copyright (c) 2000-2018 by Steve Hancock =head1 LICENSE