Name of the output file (only if a single input file is being
processed). If no output file is specified, and output is not
-redirected to the standard output, the output will go to F<filename.tdy>.
+redirected to the standard output (see B<-st>), the output will go to
+F<filename.tdy>. [Note: - does not redirect to standard output. Use
+B<-st> instead.]
=item B<-st>, B<--standard-output>
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();
}
-=item B<-cb>, B<--cuddled-blocks>
+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>.
-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";
- };
+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
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
+So for example, the B<-ce> 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 ($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
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
+=item B<-cb>, B<--cuddled-blocks>
- -cbl="word1-word2-word3-...-wordn"
+This flag is equivalent to B<-ce>.
-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.
+=item B<-cbl>, B<--cuddled-block-list>
-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
+The built-in default cuddled block types are B<else, elsif, continue, catch, finally>.
- -cbl="f1-f2-f3 g1-g2-g3-g4"
-or
- -cbl=f1-f2-f3,g1-g2-g3-g4
+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"
-Spaces are easier to read but commas may avoid quotation difficulties when
-entering data in a command shell.
+or equivalently
-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=sort,map,grep
- -cbl="if-else-elsif unless-else-elsif -continue"
-or
- -cbl=if-else-elsif,unless-else-elsif,-continue
+Note however that these particular block types are typically short so there might not be much
+opportunity for the cuddled format style.
-The final string -continue allows cuddling the optional continue block
-which may follow may other block types.
+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 this flag creates.
+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<-cb>.
+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>
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.
+ 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
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>
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
+One limitation 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
The flag B<-sot> is an abbreviation for B<-sop -sohb -sosb>.
-The flag B<-sobb> is a abbreviation for B<-bbvt=2 -bbvtl='*'>. This
+The flag B<-sobb> is an abbreviation for B<-bbvt=2 -bbvtl='*'>. This
will case a cascade of opening block braces to appear on a single line,
although this an uncommon occurrence except in test scripts.
at internal keywords C<if> and C<unless> will normally be retained.
To prevent this, and thus form longer lines, use B<-nbol>.
+=item B<-bom>, B<--break-at-old-method-breakpoints>
+
+By default, a method call arrow C<-E<gt>> is considered a candidate for
+a breakpoint, but method chains will fill to the line width before a break is
+considered. With B<-bom>, breaks before the arrow are preserved, so if you
+have preformatted a method chain:
+
+ my $q = $rs
+ ->related_resultset('CDs')
+ ->related_resultset('Tracks')
+ ->search({
+ 'track.id' => {-ident => 'none_search.id'},
+ })->as_query;
+
+It will B<keep> these breaks, rather than become this:
+
+ my $q = $rs->related_resultset('CDs')->related_resultset('Tracks')->search({
+ 'track.id' => {-ident => 'none_search.id'},
+ })->as_query;
+
+This flag will also look for and keep a 'cuddled' style of calls,
+in which lines begin with a closing paren followed by a call arrow,
+as in this example:
+
+ my $q = $rs->related_resultset(
+ 'CDs'
+ )->related_resultset(
+ 'Tracks'
+ )->search( {
+ 'track.id' => { -ident => 'none_search.id' },
+ } )->as_query;
+
+You may want to include the B<-weld-nested-containers> flag in this case to keep
+nested braces and parens together, as in the last line.
+
+
=item B<-bok>, B<--break-at-old-keyword-breakpoints>
By default, perltidy will retain a breakpoint before keywords which may
=back
+B<Controls for blank lines around lines of consecutive keywords>
+
+The parameters in this section provide some control over the placement of blank
+lines within and around groups of statements beginning with selected keywords.
+These blank lines are called here B<keyword group blanks>, and all of the
+parameters begin with B<--keyword-group-blanks*>, or B<-kgb*> for short. The
+default settings do not employ these controls but they can be enabled with the
+following parameters:
+
+B<-kgbl=s> or B<--keyword-group-blanks-list=s>; B<s> is a quoted string of keywords
+
+B<-kgbs=s> or B<--keyword-group-blanks-size=s>; B<s> gives the number of keywords required to form a group.
+
+B<-kgbb=n> or B<--keyword-group-blanks-before=n>; B<n> = (0, 1, or 2) controls a leading blank
+
+B<-kgba=n> or B<--keyword-group-blanks-after=n>; B<n> = (0, 1, or 2) controls a trailing blank
+
+B<-kgbi> or B<--keyword-group-blanks-inside> is a switch for adding blanks between subgroups
+
+B<-kgbd> or B<--keyword-group-blanks-delete> is a switch for removing initial blank lines between keywords
+
+B<-kgbr=n> or B<--keyword-group-blanks-repeat-count=n> can limit the number of times this logic is applied
+
+In addition, the following abbreviations are available to for simplified usage:
+
+B<-kgb> or B<--keyword-group-blanks> is short for B<-kgbb=2 -kgba=2 kgbi>
+
+B<-nkgb> or B<--nokeyword-group-blanks>, is short for B<-kgbb=1 -kgba=1 nkgbi>
+
+Before describing the meaning of the parameters in detail let us look at an
+example which is formatted with default parameter settings.
+
+ print "Entering test 2\n";
+ use Test;
+ use Encode qw(from_to encode decode
+ encode_utf8 decode_utf8
+ find_encoding is_utf8);
+ use charnames qw(greek);
+ my @encodings = grep( /iso-?8859/, Encode::encodings() );
+ my @character_set = ( '0' .. '9', 'A' .. 'Z', 'a' .. 'z' );
+ my @source = qw(ascii iso8859-1 cp1250);
+ my @destiny = qw(cp1047 cp37 posix-bc);
+ my @ebcdic_sets = qw(cp1047 cp37 posix-bc);
+ my $str = join( '', map( chr($_), 0x20 .. 0x7E ) );
+ return unless ($str);
+
+using B<perltidy -kgb> gives:
+
+ print "Entering test 2\n";
+ <----------this blank controlled by -kgbb
+ use Test;
+ use Encode qw(from_to encode decode
+ encode_utf8 decode_utf8
+ find_encoding is_utf8);
+ use charnames qw(greek);
+ <---------this blank controlled by -kgbi
+ my @encodings = grep( /iso-?8859/, Encode::encodings() );
+ my @character_set = ( '0' .. '9', 'A' .. 'Z', 'a' .. 'z' );
+ my @source = qw(ascii iso8859-1 cp1250);
+ my @destiny = qw(cp1047 cp37 posix-bc);
+ my @ebcdic_sets = qw(cp1047 cp37 posix-bc);
+ my $str = join( '', map( chr($_), 0x20 .. 0x7E ) );
+ <----------this blank controlled by -kgba
+ return unless ($str);
+
+Blank lines have been introduced around the B<my> and B<use> sequences. What
+happened is that the default keyword list includes B<my> and B<use> but not
+B<print> and B<return>. So a continuous sequence of nine B<my> and B<use>
+statements was located. This number exceeds the default threshold of five, so
+blanks were placed before and after the entire group. Then, since there was
+also a subsequence of six B<my> lines, a blank line was introduced to separate
+them.
+
+Finer control over blank placement can be achieved by using the individual
+parameters rather than the B<-kgb> flag. The individual controls are as follows.
+
+B<-kgbl=s> or B<--keyword-group-blanks-list=s>, where B<s> is a quoted string,
+defines the set of keywords which will be formed into groups. The string is a
+space separated list of keywords. The default set is B<s="use require local
+our my">, but any list of keywords may be used. Comment lines may also be included in a keyword group, even though they are not keywords. To include ordinary block comments, include the symbol B<BC>. To include static block comments (which normally begin with '##'), include the symbol B<SBC>.
+
+B<-kgbs=s> or B<--keyword-group-blanks-size=s>, where B<s> is a string
+describing the number of consecutive keyword statements forming a group. If
+B<s> is an integer then it is the minimum number required for a group. A
+maximum value may also be given with the format B<s=min.max>, where B<min> is
+the minimum number and B<max> is the maximum number, and the min and max values
+are separated by one or more dots. No groups will be found if the maximum is
+less than the minimum. The maximum is unlimited if not given. The default is
+B<s=5>. Some examples:
+
+ s min max number for group
+ 3 3 unlimited 3 or more
+ 1.1 1 1 1
+ 1..3 1 3 1 to 3
+ 1.0 1 0 (no match)
+
+
+B<-kgbb=n> or B<--keyword-group-blanks-before=n> specifies whether
+a blank should appear before the first line of the group, as follows:
+
+ n=0 => (delete) an existing blank line will be removed
+ n=1 => (stable) no change to the input file is made [DEFAULT]
+ n=2 => (insert) a blank line is introduced if possible
+
+B<-kgba=n> or B<--keyword-group-blanks-after=n> likewise specifies
+whether a blank should appear after the last line of the group, using the same
+scheme (0=delete, 1=stable, 2=insert).
+
+B<-kgbi> or B<--keyword-group-blanks-inside> controls
+the insertion of blank lines between the first and last statement of the entire
+group. If there is a continuous run of a single statement type with more than
+the minimum threshold number (as specified with B<-kgbs=s>) then this
+switch causes a blank line be inserted between this
+subgroup and the others. In the example above this happened between the
+B<use> and B<my> statements.
+
+B<-kgbd> or B<--keyword-group-blanks-delete> controls the deletion of any
+blank lines that exist in the the group when it is first scanned. When
+statements are initially scanned, any existing blank lines are included in the
+collection. Any such orignial blank lines will be deleted before any other
+insertions are made when the parameter B<-kgbd> is set. The default is not to
+do this, B<-nkgbd>.
+
+B<-kgbr=n> or B<--keyword-group-blanks-repeat-count=n> specifies B<n>, the
+maximum number of times this logic will be applied to any file. The special
+value B<n=0> is the same as n=infinity which means it will be applied to an
+entire script [Default]. A value B<n=1> could be used to make it apply just
+one time for example. This might be useful for adjusting just the B<use>
+statements in the top part of a module for example.
+
+B<-kgb> or B<--keyword-group-blanks> is an abbreviation equivalent to setting
+B<-kgbb=1 -kgba=1 -kgbi>. This turns on keyword group formatting with a set of
+default values.
+
+B<-nkgb> or B<--nokeyword-group-blanks> is equivalent to B<-kgbb=0 -kgba
+nkgbi>. This flag turns off keyword group blank lines and is the default
+setting.
+
+Here are a few notes about the functioning of this technique.
+
+=over 4
+
+=item *
+
+These parameters are probably more useful as part of a major code reformatting
+operation rather than as a routine formatting operation.
+
+In particular, note that deleting old blank lines with B<-kgbd> is an
+irreversible operation so it should be applied with care. Existing blank lines
+may be serving an important role in controlling vertical alignment.
+
+=item *
+
+Conflicts which arise among these B<kgb*> parameters and other blank line
+controls are generally resolved by producing the maximum number of blank lines
+implied by any parameter.
+
+For example, if the flags B<--freeze-blank-lines>, or
+B<--keep-old-blank-lines=2>, are set, then they have priority over any blank
+line deletion implied by the B<-kgb> flags of this section, so no blank lines
+will be deleted.
+
+For another example, if a keyword group ends at a B<sub> and the flag B<kgba=0> requests no blank line there, but we also have B<--blank-lines-before-subs=2>, then two blank lines will still be introduced before the sub.
+
+=item *
+
+The introduction of blank lines does not occur if it would conflict with other
+input controls or code validity. For example, a blank line will not be placed
+within a here-doc or within a section of code marked with format skipping
+comments. And in general, a blank line will only be introduced at the end of a
+group if the next statement is a line of code.
+
+=item *
+
+The count which is used to determine the group size is not the number of lines
+but rather the total number of keywords which are found. Individual statements
+with a certain leading keyword may continue on multiple lines, but if any of
+these lines is nested more than one level deep then that group will be ended.
+
+=item *
+
+The search for groups of lines with similar leading keywords is based on the
+input source, not the final formatted source. Consequently, if the source code
+is badly formatted, it would be best to make a first formatting pass without
+these options.
+
+=back
+
=head2 Styles
A style refers to a convenient collection of existing parameters.
: ' elsewhere in this document'
);
+
+=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<map>, C<eval>, and C<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 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<n=2> option has no effect if adding semicolons is prohibited
+with the B<-nasc> flag. Also not that while B<n=2> adds missing semicolons to
+all one-line blocks, regardless of complexity, the B<n=0> option only removes
+ending semicolons which terminate one-line blocks containing just one
+semicolon. So these two options are not exact inverses.
+
=back
+
=head2 Controlling Vertical Alignment
Vertical alignment refers to lining up certain symbols in list of consecutive
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<map>, C<eval>, and C<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.
-
=item Debugging
The following flags are available for debugging:
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
=head1 VERSION
-This man page documents perltidy version 20180220.
+This man page documents perltidy version 20190601
=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-2018 by Steve Hancock
projects / perltidy.git / blobdiff