perltidy -ce -cbl='else elsif continue' -cblx
-=item B<-cbo=n>, B<--cuddled-break-option=n>
+=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
Also note that the value of continuation indentation, -ci=4, is equal to the
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.
+parameter B<-ci=2> be used instead, or (2) 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} = (
The B<-xci> flag was developed after the B<-pbp> parameters were published so you need
to include it separately.
-=item B<One-line blocks>
+=back
+
+=head2 One-Line Blocks
-There are a few points to note regarding one-line blocks. A one-line
-block is something like this,
+A one-line block is a block of code where the contents within the curly braces
+is short enough to fit on a single line. For example,
if ( -e $file ) { print "'$file' exists\n" }
-where the contents within the curly braces is short enough to fit
-on a single line.
+The alternative, a block which spans multiple lines, is said to be a broken
+block. With few exceptions, perltidy retains existing one-line blocks, if it
+is possible within the line-length constraint, but it does not attempt to form
+new ones. In other words, perltidy will try to follow the input file regarding
+broken and unbroken blocks.
-With few exceptions, perltidy retains existing one-line blocks, if it
-is possible within the line-length constraint, but it does not attempt
-to form new ones. In other words, perltidy will try to follow the
-one-line block style of the input file.
+The main exception to this rule is that perltidy will attempt to form new
+one-line blocks following the keywords C<map>, C<eval>, and C<sort>, C<eval>,
+because these code blocks are often small and most clearly displayed in a
+single line. This behavior can be controlled with the flag
+B<--one-line-block-exclusion-list> described below.
-If an existing one-line block is longer than the maximum line length,
-however, it will be broken into multiple lines. When this happens, perltidy
-checks for and adds any optional terminating semicolon (unless the B<-nasc>
-option is used) if the block is a code block.
+When the B<cuddled-else> style is used, the default treatment of one-line blocks
+may interfere with the cuddled style. In this case, the default behavior may
+be changed with the flag B<--cuddled-break-option=n> described elsehwere.
-The main exception is that perltidy will attempt to form new one-line
-blocks following the keywords C<map>, C<eval>, and C<sort>, C<eval>, because
-these code blocks are often small and most clearly displayed in a single
-line. This behavior can be controlled with the flag B<--one-line-block-exclusion-list> described below.
+When an existing one-line block is longer than the maximum line length, and
+must therefore be broken into multiple lines, perltidy checks for and adds any
+optional terminating semicolon (unless the B<-nasc> option is used) if the
+block is a code block.
-One-line block rules can conflict with the cuddled-else option. When
-the cuddled-else option is used, perltidy retains existing one-line
-blocks, even if they do not obey cuddled-else formatting.
+=over 4
-Occasionally, when one-line blocks get broken because they exceed the
-available line length, the formatting will violate the requested brace style.
-If this happens, reformatting the script a second time should correct
-the problem.
+=item B<-olbxl=s>, B<--one-line-block-exclusion-list=s>
-Sometimes it might be desirable to convert a script to have one-line blocks
-whenever possible. Although there is currently no flag for this, a simple
-workaround is to execute perltidy twice, once with the flag B<-noadd-newlines>
-and then once again with normal parameters, like this:
+As noted above, perltidy will, by default, attempt to create new one-line
+blocks for certain block types. This flag allows the user to prevent this behavior for the block types listed in the string B<s>. The list B<s> may
+include any of the words C<sort>, C<map>, C<grep>, C<eval>, or it may be C<*>
+to indicate all of these.
- cat infile | perltidy -nanl | perltidy >outfile
+So for example to prevent multi-line B<eval> blocks from becomming one-line
+blocks, the command would be B<-olbxl='eval'>. In this case, existing one-line B<eval> blocks will remain on one-line if possible, and existing multi-line
+B<eval> blocks will remain multi-line blocks.
-When executed on this snippet
+=item B<-olbn=n>, B<--one-line-block-nesting=n>
- if ( $? == -1 ) {
- die "failed to execute: $!\n";
- }
- if ( $? == -1 ) {
- print "Had enough.\n";
- die "failed to execute: $!\n";
- }
+Nested one-line blocks are lines with code blocks which themselves contain code
+blocks. For example, the following line is a nested one-line block.
-the result is
+ foreach (@list) { if ($_ eq $asked_for) { last } ++$found }
- if ( $? == -1 ) { die "failed to execute: $!\n"; }
- if ( $? == -1 ) {
- print "Had enough.\n";
- die "failed to execute: $!\n";
- }
+The default behavior is to break such lines into multiple lines, but this
+behavior can be controlled with this flag. The values of n are:
-This shows that blocks with a single statement become one-line blocks.
+ n=0 break nested one-line blocks into multiple lines [DEFAULT]
+ n=1 stable: keep existing nested-one line blocks intact
-=item B<-olbxl=s>, B<--one-line-block-exclusion-list=s>
+For the above example, the default formatting (B<-olbn=0>) is
-As noted above, perltidy will, by default, attempt to create new one-line
-blocks for certain block types. This flag allows the user to prevent this
-behavior for the block types listed in the string B<s>. The list B<s> may
-include any of the words C<sort>, C<map>, C<grep>, C<eval>, or it may be C<*>
-to indicate all of these.
+ foreach (@list) {
+ if ( $_ eq $asked_for ) { last }
+ ++$found;
+ }
-So for example to prevent multi-line 'eval' blocks from becomming one-line
-blocks, the command would be B<-olbxl='eval'>. In this case, existing one-line B<eval> blocks will remain on one-line if possible, and existing multi-line
-B<eval> blocks will remain multi-line blocks.
+If the parameter B<-olbn=1> is given, then the line will be left intact if it
+is a single line in the source, or it will be broken into multiple lines if it
+is broken in multiple lines in the source.
=item B<-olbs=n>, B<--one-line-block-semicolons=n>
ending semicolons which terminate one-line blocks containing just one
semicolon. So these two options are not exact inverses.
-=item B<-olbn=n>, B<--one-line-block-nesting=n>
+=item B<Forming new one-line blocks>
-Nested one-line blocks are lines with code blocks which themselves contain code
-blocks. For example, the following line is a nested one-line block.
+Sometimes it might be desirable to convert a script to have one-line blocks
+whenever possible. Although there is currently no flag for this, a simple
+workaround is to execute perltidy twice, once with the flag B<-noadd-newlines>
+and then once again with normal parameters, like this:
- foreach (@list) { if ($_ eq $asked_for) { last } ++$found }
+ cat infile | perltidy -nanl | perltidy >outfile
-The default behavior is to break such lines into multiple lines, but this
-behavior can be controlled with this flag. The values of n are:
+When executed on this snippet
- n=0 break nested one-line blocks into multiple lines [DEFAULT]
- n=1 stable: keep existing nested-one line blocks intact
+ if ( $? == -1 ) {
+ die "failed to execute: $!\n";
+ }
+ if ( $? == -1 ) {
+ print "Had enough.\n";
+ die "failed to execute: $!\n";
+ }
-For the above example, the default formatting (B<-olbn=0>) is
+the result is
- foreach (@list) {
- if ( $_ eq $asked_for ) { last }
- ++$found;
+ if ( $? == -1 ) { die "failed to execute: $!\n"; }
+ if ( $? == -1 ) {
+ print "Had enough.\n";
+ die "failed to execute: $!\n";
}
-If the parameter B<-olbn=1> is given, then the line will be left intact if it
-is a single line in the source, or it will be broken into multiple lines if it
-is broken in multiple lines in the source.
+This shows that blocks with a single statement become one-line blocks.
+
+=item B<Breaking existing one-line blocks>
+
+There is no automatic way to break existing long one-line blocks into multiple
+lines, but this can be accomplished by processing a script, or section of a
+script, with a short value of the parameter B<maximum-line-length=n>. Then,
+when the script is reformatted again with the normal parameters, the blocks
+which were broken will remain broken (with the exceptions noted above).
+
+Another trick for doing this for certain block types is to format one time with
+the B<-cuddled-else> flag and B<--cuddled-break-option=2>. Then format again
+with the normal parameters. This will break any one-line blocks which are
+involved in a cuddled-else style.
=back
to the standard syntax without complaint.
For example, without this flag a structure such as the following would generate
-a syntax error and the braces would not be balanced:
+a syntax error:
- method deposit( Num $amount) {
+ Method deposit( Num $amount) {
$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.
=head1 VERSION
-This man page documents perltidy version 20221112.04
+This man page documents perltidy version 20221112.05
=head1 BUG REPORTS
projects / perltidy.git / commitdiff