=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<perl -c -T> 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
normally be necessary, but was added for testing purposes, because in
some versions of perl, trimming C<qw> 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<n> 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.
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<string> is a list of block types to be tagged with closing side
comments. By default, all code block types preceded by a keyword or
If B<n=1> is used, the results will be the same as B<n=2> 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
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<cbo=1>. 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<cbo=0> can produce erratic cuddling if there are numerous one-line
+blocks.
+
+The option B<cbo=2> 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:
-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<Vertical tightness> of non-block curly braces, parentheses, and square brackets.
These parameters control what shall be called vertical tightness. Here are the
main points:
=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
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
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.
=head1 VERSION
-This man page documents perltidy version 20170521.
+This man page documents perltidy version 20180220.
=head1 BUG REPORTS
=head1 COPYRIGHT
-Copyright (c) 2000-2017 by Steve Hancock
+Copyright (c) 2000-2018 by Steve Hancock
=head1 LICENSE
projects / perltidy.git / blobdiff