=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
B<-nce> or B<--nocuddled-else>. Here is a comparison of the
alternatives:
+ # -ce
if ($task) {
yyy();
- } else { # -ce
+ } else {
zzz();
}
+ # -nce (default)
if ($task) {
yyy();
}
- else { # -nce (default)
+ else {
zzz();
}
+In this example the keyword B<else> is placed on the same line which begins with
+the preceding closing block brace and is followed by its own opening block brace
+on the same line. Other keywords and function names which are formatted with
+this "cuddled" style are B<elsif>, B<continue>, B<catch>, B<finally>.
+
+Other block types can be formatted by specifying their names on a
+separate parameter B<-cbl>, described in a later section.
+
+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<-ce> flag would not have any effect if the above snippet
+is rewritten as
+
+ if ($task) { yyy() }
+ else { zzz() }
+
+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.
+
+=item B<-cb>, B<--cuddled-blocks>
+
+This flag is equivalent to B<-ce>.
+
+
+=item B<-cbl>, B<--cuddled-block-list>
+
+The built-in default cuddled block types are B<else, elsif, continue, catch, finally>.
+
+Additional block types to which the B<-cuddled-blocks> style applies can be defined by
+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
+
+ -cbl=sort,map,grep
+
+Note however that these particular block types are typically short so there might not be much
+opportunity for the cuddled format style.
+
+Using commas avoids the need to protect spaces with quotes.
+
+As a diagnostic check, the flag B<--dump-cuddled-block-list> or B<-dcbl> can be
+used to view the hash of values that are generated by this flag.
+
+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<-ce>.
+
+=item B<-cblx>, B<--cuddled-block-list-exclusive>
+
+When cuddled else formatting is selected with B<-ce>, setting this flag causes
+perltidy to ignore its built-in defaults and rely exclusively on the block types
+specified on the B<-cbl> flag described in the previous section. For example,
+to avoid using cuddled B<catch> and B<finally>, which among in the defaults, the
+following set of parameters could be used:
+
+ perltidy -ce -cbl='else elsif continue' -cblx
+
+
+=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 [DEFAULT].
+ 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.
+
+
=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<--no-timestamp> or B<-nts> will eliminate any time stamps in output files to prevent
+differences in dates from causing test installation scripts to fail. There are just
+a couple of places where timestamps normally occur. One is in the headers of
+html files, and another is when the B<-cscw> option is selected. The default is
+to allow timestamps (B<--timestamp> or B<-ts>).
+
+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 20181120
=head1 BUG REPORTS
-A list of current bugs and issues can be found at the CPAN site
-
- https://rt.cpan.org/Public/Dist/Display.html?Name=Perl-Tidy
+A list of current bugs and issues can be found at the CPAN site L<https://rt.cpan.org/Public/Dist/Display.html?Name=Perl-Tidy>
To report a new bug or problem, use the link on this page.
+The source code repository is at L<https://github.com/perltidy/perltidy>.
+
=head1 COPYRIGHT
-Copyright (c) 2000-2017 by Steve Hancock
+Copyright (c) 2000-2018 by Steve Hancock
=head1 LICENSE
projects / perltidy.git / blobdiff