From: Steve Hancock Date: Thu, 24 Jan 2019 00:32:33 +0000 (-0800) Subject: document -olbs=n and add test snippet X-Git-Tag: 20190601~15 X-Git-Url: https://git.donarmstrong.com/?a=commitdiff_plain;h=217e707e3e1e2fa8529165472a9fdf70a73ef977;p=perltidy.git document -olbs=n and add test snippet --- diff --git a/bin/perltidy b/bin/perltidy index 66dee3d1..db794dfa 100755 --- a/bin/perltidy +++ b/bin/perltidy @@ -2936,6 +2936,87 @@ after the -pbp parameter. For example, =back +=item One-line blocks + +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. + +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. + +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. + +The main exception is that perltidy will attempt to form new one-line +blocks following the keywords C, C, and C, because +these code blocks are often small and most clearly displayed in a single +line. + +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. + +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. + +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: + + cat infile | perltidy -nanl | perltidy >outfile + +When executed on this snippet + + if ( $? == -1 ) { + die "failed to execute: $!\n"; + } + if ( $? == -1 ) { + print "Had enough.\n"; + die "failed to execute: $!\n"; + } + +the result is + + if ( $? == -1 ) { die "failed to execute: $!\n"; } + if ( $? == -1 ) { + print "Had enough.\n"; + die "failed to execute: $!\n"; + } + +This shows that blocks with a single statement become one-line blocks. + + +=item B<-olbs=n>, B<--one-line-block-semicolons=n> + +This flag controls the placement of semicolons at the end of one-line blocks. +Semicolons are optional before a closing block brace, and frequently they are +omitted at the end of a one-line block containing just a single statement. +By default, perltidy follows the input file regarding these semicolons, +but this behavior can be controlled by this flag. The values of n are: + + n=0 remove terminal semicolons in one-line blocks having a single statement + n=1 stable; keep input file placement of terminal semicolons [DEFAULT ] + n=2 add terminal semicolons in all one-line blocks + +Note that the B option has no effect if adding semicolons is prohibited +with the B<-nasc> flag. Also not that while B adds missing semicolons to +all one-line blocks, regardless of complexity, the B option only removes +ending semicolons which terminate one-line blocks containing just one +semicolon. So these two options are not exact inverses. + + =head2 Controlling Vertical Alignment Vertical alignment refers to lining up certain symbols in list of consecutive @@ -3167,68 +3248,6 @@ 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 One-line blocks - -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. - -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. - -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. - -The main exception is that perltidy will attempt to form new one-line -blocks following the keywords C, C, and C, because -these code blocks are often small and most clearly displayed in a single -line. - -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. - -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. - -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: - - cat infile | perltidy -nanl | perltidy >outfile - -When executed on this snippet - - if ( $? == -1 ) { - die "failed to execute: $!\n"; - } - if ( $? == -1 ) { - print "Had enough.\n"; - die "failed to execute: $!\n"; - } - -the result is - - if ( $? == -1 ) { die "failed to execute: $!\n"; } - if ( $? == -1 ) { - print "Had enough.\n"; - die "failed to execute: $!\n"; - } - -This shows that blocks with a single statement become one-line blocks. - - =item Debugging The following flags are available for debugging: diff --git a/docs/perltidy.html b/docs/perltidy.html index 37420dff..f2f0b873 100644 --- a/docs/perltidy.html +++ b/docs/perltidy.html @@ -2318,6 +2318,66 @@ +
+ +
One-line blocks
+
+ +

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.

+ +

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.

+ +

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 -nasc option is used) if the block is a code block.

+ +

The main exception is that perltidy will attempt to form new one-line blocks following the keywords map, eval, and sort, because these code blocks are often small and most clearly displayed in a single line.

+ +

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.

+ +

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.

+ +

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 -noadd-newlines and then once again with normal parameters, like this:

+ +
     cat infile | perltidy -nanl | perltidy >outfile
+ +

When executed on this snippet

+ +
    if ( $? == -1 ) {
+        die "failed to execute: $!\n";
+    }
+    if ( $? == -1 ) {
+        print "Had enough.\n";
+        die "failed to execute: $!\n";
+    }
+ +

the result is

+ +
    if ( $? == -1 ) { die "failed to execute: $!\n"; }
+    if ( $? == -1 ) {
+        print "Had enough.\n";
+        die "failed to execute: $!\n";
+    }
+ +

This shows that blocks with a single statement become one-line blocks.

+ +
+
-olbs=n, --one-line-block-semicolons=n
+
+ +

This flag controls the placement of semicolons at the end of one-line blocks. Semicolons are optional before a closing block brace, and frequently they are omitted at the end of a one-line block containing just a single statement. By default, perltidy follows the input file regarding these semicolons, but this behavior can be controlled by this flag. The values of n are:

+ +
  n=0 remove terminal semicolons in one-line blocks having a single statement
+  n=1 stable; keep input file placement of terminal semicolons [DEFAULT ]
+  n=2 add terminal semicolons in all one-line blocks
+ +

Note that the n=2 option has no effect if adding semicolons is prohibited with the -nasc flag. Also not that while n=2 adds missing semicolons to all one-line blocks, regardless of complexity, the n=0 option only removes ending semicolons which terminate one-line blocks containing just one semicolon. So these two options are not exact inverses.

+ +
+
+

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:

@@ -2466,50 +2526,6 @@

Another use for --mangle is to combine it with -dac to reduce the file size of a perl script.

- -
One-line blocks
-
- -

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.

- -

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.

- -

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 -nasc option is used) if the block is a code block.

- -

The main exception is that perltidy will attempt to form new one-line blocks following the keywords map, eval, and sort, because these code blocks are often small and most clearly displayed in a single line.

- -

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.

- -

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.

- -

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 -noadd-newlines and then once again with normal parameters, like this:

- -
     cat infile | perltidy -nanl | perltidy >outfile
- -

When executed on this snippet

- -
    if ( $? == -1 ) {
-        die "failed to execute: $!\n";
-    }
-    if ( $? == -1 ) {
-        print "Had enough.\n";
-        die "failed to execute: $!\n";
-    }
- -

the result is

- -
    if ( $? == -1 ) { die "failed to execute: $!\n"; }
-    if ( $? == -1 ) {
-        print "Had enough.\n";
-        die "failed to execute: $!\n";
-    }
- -

This shows that blocks with a single statement become one-line blocks.

-
Debugging
@@ -2880,6 +2896,18 @@

You forgot a '=back' before '=head2'

+
+
Around line 2939:
+
+ +

'=item' outside of any '=over'

+ +
+
Around line 3020:
+
+ +

You forgot a '=back' before '=head2'

+
diff --git a/t/snippets/expect/olbs.def b/t/snippets/expect/olbs.def new file mode 100644 index 00000000..1a37af39 --- /dev/null +++ b/t/snippets/expect/olbs.def @@ -0,0 +1,6 @@ +for $x ( 1, 2 ) { s/(.*)/+$1/ } +for $x ( 1, 2 ) { s/(.*)/+$1/ } # side comment +if ( $editlblk eq 1 ) { $editlblk = "on"; $editlblkchecked = "checked" } +for $x ( 1, 2 ) { s/(.*)/+$1/; } +for $x ( 1, 2 ) { s/(.*)/+$1/; } # side comment +if ( $editlblk eq 1 ) { $editlblk = "on"; $editlblkchecked = "checked"; } diff --git a/t/snippets/expect/olbs.olbs0 b/t/snippets/expect/olbs.olbs0 new file mode 100644 index 00000000..0d708c62 --- /dev/null +++ b/t/snippets/expect/olbs.olbs0 @@ -0,0 +1,6 @@ +for $x ( 1, 2 ) { s/(.*)/+$1/ } +for $x ( 1, 2 ) { s/(.*)/+$1/ } # side comment +if ( $editlblk eq 1 ) { $editlblk = "on"; $editlblkchecked = "checked" } +for $x ( 1, 2 ) { s/(.*)/+$1/ } +for $x ( 1, 2 ) { s/(.*)/+$1/ } # side comment +if ( $editlblk eq 1 ) { $editlblk = "on"; $editlblkchecked = "checked"; } diff --git a/t/snippets/expect/olbs.olbs2 b/t/snippets/expect/olbs.olbs2 new file mode 100644 index 00000000..fe2048b9 --- /dev/null +++ b/t/snippets/expect/olbs.olbs2 @@ -0,0 +1,6 @@ +for $x ( 1, 2 ) { s/(.*)/+$1/; } +for $x ( 1, 2 ) { s/(.*)/+$1/; } # side comment +if ( $editlblk eq 1 ) { $editlblk = "on"; $editlblkchecked = "checked"; } +for $x ( 1, 2 ) { s/(.*)/+$1/; } +for $x ( 1, 2 ) { s/(.*)/+$1/; } # side comment +if ( $editlblk eq 1 ) { $editlblk = "on"; $editlblkchecked = "checked"; } diff --git a/t/snippets/olbs.in b/t/snippets/olbs.in new file mode 100644 index 00000000..1a37af39 --- /dev/null +++ b/t/snippets/olbs.in @@ -0,0 +1,6 @@ +for $x ( 1, 2 ) { s/(.*)/+$1/ } +for $x ( 1, 2 ) { s/(.*)/+$1/ } # side comment +if ( $editlblk eq 1 ) { $editlblk = "on"; $editlblkchecked = "checked" } +for $x ( 1, 2 ) { s/(.*)/+$1/; } +for $x ( 1, 2 ) { s/(.*)/+$1/; } # side comment +if ( $editlblk eq 1 ) { $editlblk = "on"; $editlblkchecked = "checked"; } diff --git a/t/snippets/olbs0.par b/t/snippets/olbs0.par new file mode 100644 index 00000000..9e2d7527 --- /dev/null +++ b/t/snippets/olbs0.par @@ -0,0 +1 @@ +-olbs=0 diff --git a/t/snippets/olbs2.par b/t/snippets/olbs2.par new file mode 100644 index 00000000..99bc4529 --- /dev/null +++ b/t/snippets/olbs2.par @@ -0,0 +1 @@ +-olbs=2 diff --git a/t/snippets/packing_list.txt b/t/snippets/packing_list.txt index 4a4fc6e8..24cd258b 100644 --- a/t/snippets/packing_list.txt +++ b/t/snippets/packing_list.txt @@ -279,3 +279,6 @@ ../snippets9.t rt98902.def ../snippets9.t rt98902.rt98902 ../snippets9.t rt99961.def +../snippets15.t olbs.def +../snippets15.t olbs.olbs0 +../snippets15.t olbs.olbs2 diff --git a/t/snippets15.t b/t/snippets15.t index 21c705e8..97c28756 100644 --- a/t/snippets15.t +++ b/t/snippets15.t @@ -3,6 +3,9 @@ # Contents: #1 gnu5.gnu #2 wngnu1.def +#3 olbs.def +#4 olbs.olbs0 +#5 olbs.olbs2 # To locate test #13 you can search for its name or the string '#13' @@ -20,8 +23,10 @@ BEGIN { # BEGIN SECTION 1: Parameter combinations # ########################################### $rparams = { - 'def' => "", - 'gnu' => "-gnu", + 'def' => "", + 'gnu' => "-gnu", + 'olbs0' => "-olbs=0", + 'olbs2' => "-olbs=2", }; ############################ @@ -39,6 +44,15 @@ BEGIN { ; ---------- + 'olbs' => <<'----------', +for $x ( 1, 2 ) { s/(.*)/+$1/ } +for $x ( 1, 2 ) { s/(.*)/+$1/ } # side comment +if ( $editlblk eq 1 ) { $editlblk = "on"; $editlblkchecked = "checked" } +for $x ( 1, 2 ) { s/(.*)/+$1/; } +for $x ( 1, 2 ) { s/(.*)/+$1/; } # side comment +if ( $editlblk eq 1 ) { $editlblk = "on"; $editlblkchecked = "checked"; } +---------- + 'wngnu1' => <<'----------', # test with -wn -gnu foreach my $parameter ( @@ -102,6 +116,45 @@ BEGIN { } #2........... }, + + 'olbs.def' => { + source => "olbs", + params => "def", + expect => <<'#3...........', +for $x ( 1, 2 ) { s/(.*)/+$1/ } +for $x ( 1, 2 ) { s/(.*)/+$1/ } # side comment +if ( $editlblk eq 1 ) { $editlblk = "on"; $editlblkchecked = "checked" } +for $x ( 1, 2 ) { s/(.*)/+$1/; } +for $x ( 1, 2 ) { s/(.*)/+$1/; } # side comment +if ( $editlblk eq 1 ) { $editlblk = "on"; $editlblkchecked = "checked"; } +#3........... + }, + + 'olbs.olbs0' => { + source => "olbs", + params => "olbs0", + expect => <<'#4...........', +for $x ( 1, 2 ) { s/(.*)/+$1/ } +for $x ( 1, 2 ) { s/(.*)/+$1/ } # side comment +if ( $editlblk eq 1 ) { $editlblk = "on"; $editlblkchecked = "checked" } +for $x ( 1, 2 ) { s/(.*)/+$1/ } +for $x ( 1, 2 ) { s/(.*)/+$1/ } # side comment +if ( $editlblk eq 1 ) { $editlblk = "on"; $editlblkchecked = "checked"; } +#4........... + }, + + 'olbs.olbs2' => { + source => "olbs", + params => "olbs2", + expect => <<'#5...........', +for $x ( 1, 2 ) { s/(.*)/+$1/; } +for $x ( 1, 2 ) { s/(.*)/+$1/; } # side comment +if ( $editlblk eq 1 ) { $editlblk = "on"; $editlblkchecked = "checked"; } +for $x ( 1, 2 ) { s/(.*)/+$1/; } +for $x ( 1, 2 ) { s/(.*)/+$1/; } # side comment +if ( $editlblk eq 1 ) { $editlblk = "on"; $editlblkchecked = "checked"; } +#5........... + }, }; my $ntests = 0 + keys %{$rtests};