"Fossies" - the Fresh Open Source Software Archive  

Source code changes of the file "bin/perltidy" between
Perl-Tidy-20210402.tar.gz and Perl-Tidy-20210717.tar.gz

About: Perltidy is a Perl script indenter and reformatter (beautifier).

perltidy  (Perl-Tidy-20210402):perltidy  (Perl-Tidy-20210717)
skipping to change at line 503 skipping to change at line 503
produce one tab for each indentation level and and one for each continuation produce one tab for each indentation level and and one for each continuation
indentation level. You may want to coordinate the value of B<n> with what your indentation level. You may want to coordinate the value of B<n> with what your
display software assumes for the spacing of a tab. display software assumes for the spacing of a tab.
=item B<-t>, B<--tabs> =item B<-t>, B<--tabs>
This flag causes one leading tab character to be inserted for each level This flag causes one leading tab character to be inserted for each level
of indentation. Certain other features are incompatible with this of indentation. Certain other features are incompatible with this
option, and if these options are also given, then a warning message will option, and if these options are also given, then a warning message will
be issued and this flag will be unset. One example is the B<-lp> be issued and this flag will be unset. One example is the B<-lp>
option. This flag is retained for backwards compatability, but option. This flag is retained for backwards compatibility, but
if you use tabs, the B<-et=n> flag is recommended. if you use tabs, the B<-et=n> flag is recommended.
=item B<-dt=n>, B<--default-tabsize=n> =item B<-dt=n>, B<--default-tabsize=n>
If the first line of code passed to perltidy contains leading tabs but no If the first line of code passed to perltidy contains leading tabs but no
tab scheme is specified for the output stream then perltidy must guess how many tab scheme is specified for the output stream then perltidy must guess how many
spaces correspond to each leading tab. This number of spaces B<n> spaces correspond to each leading tab. This number of spaces B<n>
corresponding to each leading tab of the input stream may be specified with corresponding to each leading tab of the input stream may be specified with
B<-dt=n>. The default is B<n=8>. B<-dt=n>. The default is B<n=8>.
This flag has no effect if a tab scheme is specified for the output stream, This flag has no effect if a tab scheme is specified for the output stream,
because then the input stream is assumed to use the same tab scheme and because then the input stream is assumed to use the same tab scheme and
indentation spaces as for the output stream (any other assumption would lead to indentation spaces as for the output stream (any other assumption would lead to
unstable editing). unstable editing).
=back =back
=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
will be saved if an error is detected in the output script. The output
script is not checked if the input script has a syntax error. Perltidy
does its own checking, but this option employs perl to get a "second
opinion".
If perl reports errors in the input file, they will not be reported in
the error output unless the B<--warning-output> flag is given.
The default is B<NOT> to do this type of syntax checking (although
perltidy will still do as much self-checking as possible). The reason
is that it causes all code in BEGIN blocks to be executed, for all
modules being used, and this opens the door to security issues and
infinite loops when running perltidy.
=item B<-pscf=s>, B<-perl-syntax-check-flags=s>
When perl is invoked to check syntax, the normal flags are C<-c -T>. In
addition, if the B<-x> flag is given to perltidy, then perl will also be
passed a B<-x> flag. It should not normally be necessary to change
these flags, but it can be done with the B<-pscf=s> flag. For example,
if the taint flag, C<-T>, is not wanted, the flag could be set to be just
B<-pscf=-c>.
Perltidy will pass your string to perl with the exception that it will
add a B<-c> and B<-x> if appropriate. The F<.LOG> file will show
exactly what flags were passed to perl.
=item B<-xs>, B<--extended-syntax> =item B<-xs>, B<--extended-syntax>
A problem with formatting Perl code is that some modules can introduce new A problem with formatting Perl code is that some modules can introduce new
syntax. This flag allows perltidy to handle certain common extensions syntax. This flag allows perltidy to handle certain common extensions
to the standard syntax without complaint. to the standard syntax without complaint.
For example, without this flag a structure such as the following would generate 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 and the braces would not be balanced:
method deposit( Num $amount) { method deposit( Num $amount) {
skipping to change at line 577 skipping to change at line 542
} }
For one of the extensions, module Switch::Plain, colons are marked as labels. 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 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. to prevent lines such as 'default:' from being outdented.
This flag is enabled by default but it can be deactivated with B<-nxs>. 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 Probably the only reason to deactivate this flag is to generate more diagnostic
messages when debugging a script. messages when debugging a script.
For another method of handling extended syntax see the section L<Skipping Select
ed Sections of Code>.
=item B<-io>, B<--indent-only> =item B<-io>, B<--indent-only>
This flag is used to deactivate all whitespace and line break changes This flag is used to deactivate all whitespace and line break changes
within non-blank lines of code. within non-blank lines of code.
When it is in effect, the only change to the script will be When it is in effect, the only change to the script will be
to the indentation and to the number of blank lines. to the indentation and to the number of blank lines.
And any flags controlling whitespace and newlines will be ignored. You And any flags controlling whitespace and newlines will be ignored. You
might want to use this if you are perfectly happy with your whitespace might want to use this if you are perfectly happy with your whitespace
and line breaks, and merely want perltidy to handle the indentation. and line breaks, and merely want perltidy to handle the indentation.
(This also speeds up perltidy by well over a factor of two, so it might be (This also speeds up perltidy by well over a factor of two, so it might be
skipping to change at line 688 skipping to change at line 655
=item B<-ple>, B<--preserve-line-endings> =item B<-ple>, B<--preserve-line-endings>
This flag tells perltidy to write its output files with the same line This flag tells perltidy to write its output files with the same line
endings as the input file, if possible. It should work for endings as the input file, if possible. It should work for
B<dos>, B<unix>, and B<mac> line endings. It will only work if perltidy B<dos>, B<unix>, and B<mac> line endings. It will only work if perltidy
input comes from a filename (rather than stdin, for example). If input comes from a filename (rather than stdin, for example). If
perltidy has trouble determining the input file line ending, it will perltidy has trouble determining the input file line ending, it will
revert to the default behavior of using the line ending of the host system. revert to the default behavior of using the line ending of the host system.
=item B<-atnl>, B<--add-terminal-newline>
This flag, which is enabled by default, allows perltidy to terminate the last
line of the output stream with a newline character, regardless of whether or
not the input stream was terminated with a newline character. If this flag is
negated, with B<-natnl>, then perltidy will add a terminal newline to the the
output stream only if the input stream is terminated with a newline.
Negating this flag may be useful for manipulating one-line scripts intended for
use on a command line.
=item B<-it=n>, B<--iterations=n> =item B<-it=n>, B<--iterations=n>
This flag causes perltidy to do B<n> complete iterations. The reason for this This flag causes perltidy to do B<n> complete iterations. The reason for this
flag is that code beautification is an iterative process and in some flag is that code beautification is an iterative process and in some
cases the output from perltidy can be different if it is applied a second time. cases the output from perltidy can be different if it is applied a second time.
For most purposes the default of B<n=1> should be satisfactory. However B<n=2> For most purposes the default of B<n=1> should be satisfactory. However B<n=2>
can be useful when a major style change is being made, or when code is being can be useful when a major style change is being made, or when code is being
beautified on check-in to a source code control system. It has been found to beautified on check-in to a source code control system. It has been found to
be extremely rare for the output to change after 2 iterations. If a value be extremely rare for the output to change after 2 iterations. If a value
B<n> is greater than 2 is input then a convergence test will be used to stop B<n> is greater than 2 is input then a convergence test will be used to stop
skipping to change at line 750 skipping to change at line 728
(1) the value B<n> given with B<-ci=n> be no more than about one-half of the (1) the value B<n> given with B<-ci=n> be no more than about one-half of the
number of spaces assigned to a full indentation level on the B<-i=n> command, or number of spaces assigned to a full indentation level on the B<-i=n> command, or
(2) the flag B<-extended-continuation-indentation> is used (see next section). (2) the flag B<-extended-continuation-indentation> is used (see next section).
=item B<-xci>, B<--extended-continuation-indentation> =item B<-xci>, B<--extended-continuation-indentation>
This flag allows perltidy to use some improvements which have been made to its This flag allows perltidy to use some improvements which have been made to its
indentation model. One of the things it does is "extend" continuation indentation model. One of the things it does is "extend" continuation
indentation deeper into structures, hence the name. The improved indentation indentation deeper into structures, hence the name. The improved indentation
is particularly noticable when the flags B<-ci=n> and B<-i=n> use the same value of is particularly noticeable when the flags B<-ci=n> and B<-i=n> use the same valu e of
B<n>. There are no significant disadvantages to using this flag, but to avoid B<n>. There are no significant disadvantages to using this flag, but to avoid
disturbing existing formatting the default is not to use it, B<-nxci>. disturbing existing formatting the default is not to use it, B<-nxci>.
Please see the section L<"B<-pbp>, B<--perl-best-practices>"> for an example of Please see the section L<"B<-pbp>, B<--perl-best-practices>"> for an example of
how this flag can improve the formatting of ternary statements. It can also how this flag can improve the formatting of ternary statements. It can also
improve indentation of some multi-line qw lists as shown below. improve indentation of some multi-line qw lists as shown below.
# perltidy # perltidy
foreach $color ( foreach $color (
qw( qw(
skipping to change at line 828 skipping to change at line 806
@month_of_year = ( @month_of_year = (
'Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun',
'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec' 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'
); );
If the available line length (see B<-l=n> ) does not permit this much If the available line length (see B<-l=n> ) does not permit this much
space, perltidy will use less. For alternate placement of the space, perltidy will use less. For alternate placement of the
closing paren, see the next section. closing paren, see the next section.
This option has no effect on code BLOCKS, such as if/then/else blocks, This option has no effect on code BLOCKS, such as if/then/else blocks,
which always use whatever is specified with B<-i=n>. Also, the which always use whatever is specified with B<-i=n>.
existence of line breaks and/or block comments between the opening and
closing parens may cause perltidy to temporarily revert to its default
method.
Note: The B<-lp> option may not be used together with the B<-t> tabs option. In situations where perltidy does not have complete freedom to choose line
It may, however, be used with the B<-et=n> tab method. breaks it may temporarily revert to its default indentation method. This can
occur for example if there are blank lines, block comments, multi-line quotes,
or side comments between the opening and closing parens, braces, or brackets.
In addition, any parameter which significantly restricts the ability of In addition, any parameter which significantly restricts the ability of
perltidy to choose newlines will conflict with B<-lp> and will cause perltidy to choose newlines will conflict with B<-lp> and will cause
B<-lp> to be deactivated. These include B<-io>, B<-fnl>, B<-nanl>, and B<-lp> to be deactivated. These include B<-io>, B<-fnl>, B<-nanl>, and
B<-ndnl>. The reason is that the B<-lp> indentation style can require B<-ndnl>. The reason is that the B<-lp> indentation style can require
the careful coordination of an arbitrary number of break points in the careful coordination of an arbitrary number of break points in
hierarchical lists, and these flags may prevent that. hierarchical lists, and these flags may prevent that.
The B<-lp> option may not be used together with the B<-t> tabs option.
It may, however, be used with the B<-et=n> tab method.
=item B<-lpxl=s>, B<--line-up-parentheses-exclusion-list> =item B<-lpxl=s>, B<--line-up-parentheses-exclusion-list>
This is an experimental parameter; the details might change as experience This is an experimental parameter; the details might change as experience
with it is gained. with it is gained.
The B<-lp> indentation style works well for some types of coding but can The B<-lp> indentation style works well for some types of coding but can
produce very long lines when variables have long names and/or containers are produce very long lines when variables have long names and/or containers are
very deeply nested. The B<-lpxl=s> flag is intended to help mitigate this probl em by very deeply nested. The B<-lpxl=s> flag is intended to help mitigate this probl em by
providing control over the containers to which the B<-lp> indentation style is providing control over the containers to which the B<-lp> indentation style is
applied. The B<-lp> flag by default is "greedy" and applies to as many applied. The B<-lp> flag by default is "greedy" and applies to as many
skipping to change at line 866 skipping to change at line 846
This list is a string with space-separated items. Each item consists of up to This list is a string with space-separated items. Each item consists of up to
three pieces of information in this order: (1) an optional letter code (2) a three pieces of information in this order: (1) an optional letter code (2) a
required container type, and (3) an optional numeric code. required container type, and (3) an optional numeric code.
The only required piece of information is a container type, which is one of The only required piece of information is a container type, which is one of
'(', '[', or '{'. For example the string '(', '[', or '{'. For example the string
-lpxl='[ {' -lpxl='[ {'
means do B<NOT> include use -lp formatting within square-bracets or braces. The only unspecified means do B<NOT> include use -lp formatting within square-bracets or braces. The only unspecified
container is '(', so this string means that only the contens within parens will use -lp indentation. container is '(', so this string means that only the contents within parens will use -lp indentation.
An optional numeric code may follow any of the container types to further refine the selection based An optional numeric code may follow any of the container types to further refine the selection based
on container contents. The numeric codes are: on container contents. The numeric codes are:
'0' or blank: no check on contents '0' or blank: no check on contents
'1' reject -lp unless the contents is a simple list without sublists '1' reject -lp unless the contents is a simple list without sublists
'2' reject -lp unless the contents is a simple list without sublists, without '2' reject -lp unless the contents is a simple list without sublists, without
code blocks, and without ternary operators code blocks, and without ternary operators
For example, For example,
skipping to change at line 1298 skipping to change at line 1278
1: system($foo ); 1: system($foo );
1: kkkkkk{ZZZZb}; 1: kkkkkk{ZZZZb};
which shows that B<system> is type B<k> (keyword) and $foo is type B<Z>. which shows that B<system> is type B<k> (keyword) and $foo is type B<Z>.
=item B<Note2: Perltidy's whitespace rules are not perfect> =item B<Note2: Perltidy's whitespace rules are not perfect>
Despite these precautions, it is still possible to introduce syntax errors with Despite these precautions, it is still possible to introduce syntax errors with
some asymmetric whitespace rules, particularly when call parameters are not some asymmetric whitespace rules, particularly when call parameters are not
placed in containg parens or braces. For example, the following two lines will placed in containing parens or braces. For example, the following two lines wil l
be parsed by perl without a syntax error: be parsed by perl without a syntax error:
# original programming, syntax ok # original programming, syntax ok
my @newkeys = map $_-$nrecs+@data, @oldkeys; my @newkeys = map $_-$nrecs+@data, @oldkeys;
# perltidy default, syntax ok # perltidy default, syntax ok
my @newkeys = map $_ - $nrecs + @data, @oldkeys; my @newkeys = map $_ - $nrecs + @data, @oldkeys;
But the following will give a syntax error: But the following will give a syntax error:
skipping to change at line 1969 skipping to change at line 1949
which identifies these comments, so it must enable a valid regular which identifies these comments, so it must enable a valid regular
expression to be formed. expression to be formed.
=back =back
=back =back
=head2 Skipping Selected Sections of Code =head2 Skipping Selected Sections of Code
Selected lines of code may be passed verbatim to the output without any Selected lines of code may be passed verbatim to the output without any
formatting. This feature is enabled by default but can be disabled with formatting by marking the starting and ending lines with special comments.
the B<--noformat-skipping> or B<-nfs> flag. It should be used sparingly to There are two options for doing this. The first option is called
avoid littering code with markers, but it might be helpful for working B<--format-skipping> or B<-fs>, and the second option is called
around occasional problems. For example it might be useful for keeping B<--code-skipping> or B<-cs>.
the indentation of old commented code unchanged, keeping indentation of
long blocks of aligned comments unchanged, keeping certain list In both cases the lines of code will be output without any changes.
formatting unchanged, or working around a glitch in perltidy. The difference is that in B<--format-skipping>
perltidy will still parse the marked lines of code and check for errors,
=over 4 whereas in B<--code-skipping> perltidy will simply pass the lines to the output
without any checking.
=item B<-fs>, B<--format-skipping>
Both of these features are enabled by default and are invoked with special
comment markers. B<--format-skipping> uses starting and ending markers '#<<<'
and '#>>>', like this:
This flag, which is enabled by default, causes any code between #<<< format skipping: do not let perltidy change my nice formatting
special beginning and ending comment markers to be passed to the
output without formatting. The default beginning marker is #<<<
and the default ending marker is #>>> but they
may be changed (see next items below). Additional text may appear on
these special comment lines provided that it is separated from the
marker by at least one space. For example
#<<< do not let perltidy touch this
my @list = (1, my @list = (1,
1, 1, 1, 1,
1, 2, 1, 1, 2, 1,
1, 3, 3, 1, 1, 3, 3, 1,
1, 4, 6, 4, 1,); 1, 4, 6, 4, 1,);
#>>> #>>>
Format skipping begins when a format skipping comment is seen and continues B<--code-skipping> uses starting and ending markers '#<<V' and '#>>V', like
until either a format-skipping end pattern is found or until the end of file. this:
#<<V code skipping: perltidy will pass this verbatim without error checking
token ident_digit {
[ [ <?word> | _ | <?digit> ] <?ident_digit>
| <''>
]
};
#>>V
Additional text may appear on the special comment lines provided that it
is separated from the marker by at least one space, as in the above examples.
It is recommended to use B<--code-skipping> only if you need to hide a block of
an extended syntax which would produce errors if parsed by perltidy, and use
B<--format-skipping> otherwise. This is because the B<--format-skipping>
option provides the benefits of error checking, and there are essentially no
limitations on which lines to which it can be applied. The B<--code-skipping>
option, on the other hand, does not do error checking and its use is more
restrictive because the code which remains, after skipping the marked lines,
must be syntactically correct code with balanced containers.
These features should be used sparingly to avoid littering code with markers,
but they can be helpful for working around occasional problems.
Note that it may be possible to avoid the use of B<--format-skipping> for the
specific case of a comma-separated list of values, as in the above example, by
simply inserting a blank or comment somewhere between the opening and closing
parens. See the section L<Controlling List Formatting>.
The following sections describe the available controls for these options. They
should not normally be needed.
=over 4
=item B<-fs>, B<--format-skipping>
The comment markers may be placed at any location that a block comment may As explained above, this flag, which is enabled by default, causes any code
appear. If they do not appear to be working, use the -log flag and examine the between special beginning and ending comment markers to be passed to the output
F<.LOG> file. Use B<-nfs> to disable this feature. without formatting. The code between the comments is still checked for errors
however. The default beginning marker is #<<< and the default ending marker is
This method works for any code. For the specific case of a comma-separated list #>>>.
of values, as in this example, another possibility is to insert a blank or
comment somewhere between the opening and closing parens. See the section Format skipping begins when a format skipping beginning comment is seen and
L<Controlling List Formatting>. continues until a format-skipping ending comment is found.
This feature can be disabled with B<-nfs>. This should not normally be necessa
ry.
=item B<-fsb=string>, B<--format-skipping-begin=string> =item B<-fsb=string>, B<--format-skipping-begin=string>
This and the next parameter allow the special beginning and ending comments to
be changed. However, it is recommended that they only be changed if there is a
conflict between the default values and some other use. If they are used, it
is recommended that they only be entered in a B<.perltidyrc> file, rather than
on a command line. This is because properly escaping these parameters on a
command line can be difficult.
If changed comment markers do not appear to be working, use the B<-log> flag and
examine the F<.LOG> file to see if and where they are being detected.
The B<-fsb=string> parameter may be used to change the beginning marker for The B<-fsb=string> parameter may be used to change the beginning marker for
format skipping. The default is equivalent to -fsb='#<<<'. The string that format skipping. The default is equivalent to -fsb='#<<<'. The string that
you enter must begin with a # and should be in quotes as necessary to get past you enter must begin with a # and should be in quotes as necessary to get past
the command shell of your system. It is actually the leading text of a pattern the command shell of your system. It is actually the leading text of a pattern
that is constructed by appending a '\s', so you must also include backslashes that is constructed by appending a '\s', so you must also include backslashes
for characters to be taken literally rather than as patterns. for characters to be taken literally rather than as patterns.
Some examples show how example strings become patterns: Some examples show how example strings become patterns:
-fsb='#\{\{\{' becomes /^#\{\{\{\s/ which matches #{{{ but not #{{{{ -fsb='#\{\{\{' becomes /^#\{\{\{\s/ which matches #{{{ but not #{{{{
skipping to change at line 2033 skipping to change at line 2056
=item B<-fse=string>, B<--format-skipping-end=string> =item B<-fse=string>, B<--format-skipping-end=string>
The B<-fse=string> is the corresponding parameter used to change the The B<-fse=string> is the corresponding parameter used to change the
ending marker for format skipping. The default is equivalent to ending marker for format skipping. The default is equivalent to
-fse='#<<<'. -fse='#<<<'.
The beginning and ending strings may be the same, but it is preferable The beginning and ending strings may be the same, but it is preferable
to make them different for clarity. to make them different for clarity.
=item B<-cs>, B<--code-skipping>
As explained above, this flag, which is enabled by default, causes any code
between special beginning and ending comment markers to be directly passed to
the output without any error checking or formatting. Essentially, perltidy
treats it as if it were a block of arbitrary text. The default beginning
marker is #<<V and the default ending marker is #>>V.
This feature can be disabled with B<-ncs>. This should not normally be
necessary.
=item B<-csb=string>, B<--code-skipping-begin=string>
This may be used to change the beginning comment for a B<--code-skipping> sectio
n, and its use is similar to the B<-fsb=string>.
The default is equivalent to -csb='#<<V'.
=item B<-cse=string>, B<--code-skipping-end=string>
This may be used to change the ending comment for a B<--code-skipping> section,
and its use is similar to the B<-fse=string>.
The default is equivalent to -cse='#>>V'.
=back =back
=head2 Line Break Control =head2 Line Break Control
The parameters in this section control breaks after The parameters in this section control breaks after
non-blank lines of code. Blank lines are controlled non-blank lines of code. Blank lines are controlled
separately by parameters in the section L<Blank Line separately by parameters in the section L<Blank Line
Control>. Control>.
=over 4 =over 4
skipping to change at line 2643 skipping to change at line 2687
) ) ) )
The first case does maximum welding. In the second case the leading paren is The first case does maximum welding. In the second case the leading paren is
retained by the rule (it would have been rejected if preceded by a non-keyword) retained by the rule (it would have been rejected if preceded by a non-keyword)
but the curly brace is rejected by the rule. but the curly brace is rejected by the rule.
Here are some additional example strings and their meanings: Here are some additional example strings and their meanings:
'^(' - the weld must not start with a paren '^(' - the weld must not start with a paren
'.(' - the second and later tokens may not be parens '.(' - the second and later tokens may not be parens
'.w(' - the second and later tokens may not keyword or function call parens
'(' - no parens in a weld '(' - no parens in a weld
'^K(' - exclude a leading paren preceded by a non-keyword '^K(' - exclude a leading paren preceded by a non-keyword
'.k(' - exclude a secondary paren preceded by a keyword '.k(' - exclude a secondary paren preceded by a keyword
'[ {' - exclude all brackets and braces '[ {' - exclude all brackets and braces
'[ ( ^K{' - exclude everything except nested structures like do {{ ... }}
=item B<Vertical tightness> of non-block curly braces, parentheses, and square b rackets. =item B<Vertical tightness> of non-block curly braces, parentheses, and square b rackets.
These parameters control what shall be called vertical tightness. Here are the These parameters control what shall be called vertical tightness. Here are the
main points: main points:
=over 4 =over 4
=item * =item *
skipping to change at line 2680 skipping to change at line 2726
=item * =item *
Closing tokens (except for block braces) are controlled by B<-vtc=n>, or Closing tokens (except for block braces) are controlled by B<-vtc=n>, or
B<--vertical-tightness-closing=n>, where B<--vertical-tightness-closing=n>, where
-vtc=0 always break a line before a closing token (default), -vtc=0 always break a line before a closing token (default),
-vtc=1 do not break before a closing token which is followed -vtc=1 do not break before a closing token which is followed
by a semicolon or another closing token, and is not in by a semicolon or another closing token, and is not in
a list environment. a list environment.
-vtc=2 never break before a closing token. -vtc=2 never break before a closing token.
-vtc=3 Like -vtc=1 except always break before a closing token
if the corresponding opening token follows an = or =>.
The rules for B<-vtc=1> are designed to maintain a reasonable balance The rules for B<-vtc=1> and B<-vtc=3> are designed to maintain a reasonable
between tightness and readability in complex lists. balance between tightness and readability in complex lists.
=item * =item *
Different controls may be applied to different token types, Different controls may be applied to different token types,
and it is also possible to control block braces; see below. and it is also possible to control block braces; see below.
=item * =item *
Finally, please note that these vertical tightness flags are merely Finally, please note that these vertical tightness flags are merely
hints to the formatter, and it cannot always follow them. Things which hints to the formatter, and it cannot always follow them. Things which
skipping to change at line 2723 skipping to change at line 2771
three => 'III', three => 'III',
four => 'IV', four => 'IV',
); );
# perltidy -lp -vt=1 -vtc=1 # perltidy -lp -vt=1 -vtc=1
%romanNumerals = ( one => 'I', %romanNumerals = ( one => 'I',
two => 'II', two => 'II',
three => 'III', three => 'III',
four => 'IV', ); four => 'IV', );
# perltidy -vtc=3
my_function(
one => 'I',
two => 'II',
three => 'III',
four => 'IV', );
# perltidy -vtc=3
%romanNumerals = (
one => 'I',
two => 'II',
three => 'III',
four => 'IV',
);
In the last example for B<-vtc=3>, the opening paren is preceded by an equals
so the closing paren is placed on a new line.
The difference between B<-vt=1> and B<-vt=2> is shown here: The difference between B<-vt=1> and B<-vt=2> is shown here:
# perltidy -lp -vt=1 # perltidy -lp -vt=1
$init->add( $init->add(
mysprintf( "(void)find_threadsv(%s);", mysprintf( "(void)find_threadsv(%s);",
cstring( $threadsv_names[ $op->targ ] ) cstring( $threadsv_names[ $op->targ ] )
) )
); );
# perltidy -lp -vt=2 # perltidy -lp -vt=2
skipping to change at line 2762 skipping to change at line 2828
if B<-vt=0>, and then simply overwriting one output line on top of the if B<-vt=0>, and then simply overwriting one output line on top of the
next, if possible, to achieve the desired vertical tightness. The next, if possible, to achieve the desired vertical tightness. The
B<-lp> indentation style has been designed to allow this vertical B<-lp> indentation style has been designed to allow this vertical
collapse to occur, which is why it is required for the B<-vt> parameter. collapse to occur, which is why it is required for the B<-vt> parameter.
The B<-vt=n> and B<-vtc=n> parameters apply to each type of container The B<-vt=n> and B<-vtc=n> parameters apply to each type of container
token. If desired, vertical tightness controls can be applied token. If desired, vertical tightness controls can be applied
independently to each of the closing container token types. independently to each of the closing container token types.
The parameters for controlling parentheses are B<-pvt=n> or The parameters for controlling parentheses are B<-pvt=n> or
B<--paren-vertical-tightness=n>, and B<-pcvt=n> or B<--paren-vertical-tightness=n>, and B<-pvtc=n> or
B<--paren-vertical-tightness-closing=n>. B<--paren-vertical-tightness-closing=n>.
Likewise, the parameters for square brackets are B<-sbvt=n> or Likewise, the parameters for square brackets are B<-sbvt=n> or
B<--square-bracket-vertical-tightness=n>, and B<-sbcvt=n> or B<--square-bracket-vertical-tightness=n>, and B<-sbvtc=n> or
B<--square-bracket-vertical-tightness-closing=n>. B<--square-bracket-vertical-tightness-closing=n>.
Finally, the parameters for controlling non-code block braces are Finally, the parameters for controlling non-code block braces are
B<-bvt=n> or B<--brace-vertical-tightness=n>, and B<-bcvt=n> or B<-bvt=n> or B<--brace-vertical-tightness=n>, and B<-bvtc=n> or
B<--brace-vertical-tightness-closing=n>. B<--brace-vertical-tightness-closing=n>.
In fact, the parameter B<-vt=n> is actually just an abbreviation for In fact, the parameter B<-vt=n> is actually just an abbreviation for
B<-pvt=n -bvt=n sbvt=n>, and likewise B<-vtc=n> is an abbreviation B<-pvt=n -bvt=n sbvt=n>, and likewise B<-vtc=n> is an abbreviation
for B<-pvtc=n -bvtc=n sbvtc=n>. for B<-pvtc=n -bvtc=n -sbvtc=n>.
=item B<-bbvt=n> or B<--block-brace-vertical-tightness=n> =item B<-bbvt=n> or B<--block-brace-vertical-tightness=n>
The B<-bbvt=n> flag is just like the B<-vt=n> flag but applies The B<-bbvt=n> flag is just like the B<-vt=n> flag but applies
to opening code block braces. to opening code block braces.
-bbvt=0 break after opening block brace (default). -bbvt=0 break after opening block brace (default).
-bbvt=1 do not break unless this would produce more than one -bbvt=1 do not break unless this would produce more than one
step in indentation in a line. step in indentation in a line.
-bbvt=2 do not break after opening block brace. -bbvt=2 do not break after opening block brace.
skipping to change at line 3225 skipping to change at line 3291
It will B<keep> these breaks, rather than become this: It will B<keep> these breaks, rather than become this:
my $q = $rs->related_resultset('CDs')->related_resultset('Tracks')->search({ my $q = $rs->related_resultset('CDs')->related_resultset('Tracks')->search({
'track.id' => {-ident => 'none_search.id'}, 'track.id' => {-ident => 'none_search.id'},
})->as_query; })->as_query;
This flag will also look for and keep a 'cuddled' style of calls, 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, in which lines begin with a closing paren followed by a call arrow,
as in this example: as in this example:
# perltidy -bom -wn
my $q = $rs->related_resultset( my $q = $rs->related_resultset(
'CDs' 'CDs'
)->related_resultset( )->related_resultset(
'Tracks' 'Tracks'
)->search( { )->search( {
'track.id' => { -ident => 'none_search.id' }, 'track.id' => { -ident => 'none_search.id' },
} )->as_query; } )->as_query;
You may want to include the B<-weld-nested-containers> flag in this case to keep 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. nested braces and parens together, as in the last line.
skipping to change at line 3501 skipping to change at line 3568
cannot be exactly undone, so some experimentation with these controls is cannot be exactly undone, so some experimentation with these controls is
recommended before using them. recommended before using them.
For example, suppose that for some reason we decide to introduce one blank For example, suppose that for some reason we decide to introduce one blank
space at the beginning and ending of all blocks. We could do space at the beginning and ending of all blocks. We could do
this using this using
perltidy -blao=2 -blbc=2 -blaol='*' -blbcl='*' filename perltidy -blao=2 -blbc=2 -blaol='*' -blbcl='*' filename
Now suppose the script continues to be developed, but at some later date we Now suppose the script continues to be developed, but at some later date we
decide we don't want these spaces after all. we might expect that running with decide we don't want these spaces after all. We might expect that running with
the flags B<-blao=0> and B<-blbc=0> will undo them. However, by default the flags B<-blao=0> and B<-blbc=0> will undo them. However, by default
perltidy retains single blank lines, so the blank lines remain. perltidy retains single blank lines, so the blank lines remain.
We can easily fix this by telling perltidy to ignore old blank lines by We can easily fix this by telling perltidy to ignore old blank lines by
including the added parameter B<-kbl=0> and rerunning. Then the unwanted blank including the added parameter B<-kbl=0> and rerunning. Then the unwanted blank
lines will be gone. However, this will cause all old blank lines to be lines will be gone. However, this will cause all old blank lines to be
ignored, perhaps even some that were added by hand to improve formatting. So ignored, perhaps even some that were added by hand to improve formatting. So
please be cautious when using these parameters. please be cautious when using these parameters.
=item B<-mbl=n> B<--maximum-consecutive-blank-lines=n> =item B<-mbl=n> B<--maximum-consecutive-blank-lines=n>
skipping to change at line 4105 skipping to change at line 4172
newword { newword {
-opt1 -opt1
-opt2 -opt2
} }
where B<newword> is the abbreviation, and B<opt1>, etc, are existing parameters where B<newword> is the abbreviation, and B<opt1>, etc, are existing parameters
I<or other abbreviations>. The main syntax requirement is that the new I<or other abbreviations>. The main syntax requirement is that the new
abbreviation along with its opening curly brace must begin on a new line. abbreviation along with its opening curly brace must begin on a new line.
Space before and after the curly braces is optional. Space before and after the curly braces is optional.
For a
specific example, the following line
airy {-bl -pt=0 -bt=0 -sbt=0} For a specific example, the following line
oneliner { --maximum-line-length=0 --noadd-newlines --noadd-terminal-new
line}
or equivalently with abbreviations
oneliner { -l=0 -nanl -natnl }
could be placed in a F<.perltidyrc> file, and then invoked at will with could be placed in a F<.perltidyrc> file to temporarily override the maximum
line length with a large value, to temporarily prevent new line breaks from
being added, and to prevent an extra newline character from being added the
file. All other settings in the F<.perltidyrc> file still apply. Thus it
provides a way to format a long 'one liner' when perltidy is invoked with
perltidy -airy somefile.pl perltidy --oneliner ...
(Either C<-airy> or C<--airy> may be used). (Either C<-oneliner> or C<--oneliner> may be used).
=item Skipping leading non-perl commands with B<-x> or B<--look-for-hash-bang> =item Skipping leading non-perl commands with B<-x> or B<--look-for-hash-bang>
If your script has leading lines of system commands or other text which If your script has leading lines of system commands or other text which
are not valid perl code, and which are separated from the start of the are not valid perl code, and which are separated from the start of the
perl code by a "hash-bang" line, ( a line of the form C<#!...perl> ), perl code by a "hash-bang" line, ( a line of the form C<#!...perl> ),
you must use the B<-x> flag to tell perltidy not to parse and format any you must use the B<-x> flag to tell perltidy not to parse and format any
lines before the "hash-bang" line. This option also invokes perl with a lines before the "hash-bang" line. This option also invokes perl with a
-x flag when checking the syntax. This option was originally added to -x flag when checking the syntax. This option was originally added to
allow perltidy to parse interactive VMS scripts, but it should be used allow perltidy to parse interactive VMS scripts, but it should be used
skipping to change at line 4567 skipping to change at line 4642
For example, suppose the file is F<somefile.pl>. For C<-bext=old>, a '.' is For example, suppose the file is F<somefile.pl>. For C<-bext=old>, a '.' is
added to give F<somefile.pl.old>. For C<-bext=.old>, no additional '.' is added to give F<somefile.pl.old>. For C<-bext=.old>, no additional '.' is
added, so again the backup file is F<somefile.pl.old>. For C<-bext=~>, then no added, so again the backup file is F<somefile.pl.old>. For C<-bext=~>, then no
dot is added, and the backup file will be F<somefile.pl~> . dot is added, and the backup file will be F<somefile.pl~> .
=head1 SWITCHES WHICH MAY BE NEGATED =head1 SWITCHES WHICH MAY BE NEGATED
The following list shows all short parameter names which allow a prefix The following list shows all short parameter names which allow a prefix
'n' to produce the negated form: 'n' to produce the negated form:
D anl asbl asc ast asu aws b baa baao D anl asbl asc ast asu atnl aws b baa
bar bbao bbb bbc bbs bl bli boa boc bok baao bar bbao bbb bbc bbs bl bli boa boc
bol bom bos bot cblx ce conv csc cscb cscw bok bol bom bos bot cblx ce conv cs csc
dac dbc dcbl dcsc ddf dln dnl dop dp dpro cscb cscw dac dbc dcbl dcsc ddf dln dnl dop
dsc dsm dsn dtt dwls dwrs dws f fll frm dp dpro dsc dsm dsn dtt dwls dwrs dws f
fs fso gcs hbc hbcm hbco hbh hbhh hbi hbj fll fpva frm fs fso gcs hbc hbcm hbco hbh
hbk hbm hbn hbp hbpd hbpu hbq hbs hbsc hbv hbhh hbi hbj hbk hbm hbn hbp hbpd hbpu hbq
hbw hent hic hicm hico hih hihh hii hij hik hbs hbsc hbv hbw hent hic hicm hico hih hihh
him hin hip hipd hipu hiq his hisc hiv hiw hii hij hik him hin hip hipd hipu hiq his
hsc html ibc icb icp iob isbc iscl kgb kgbd hisc hiv hiw hsc html ibc icb icp iob isbc
kgbi kis lal log lop lp lsl mem nib ohbr iscl kgb kgbd kgbi kis lal log lop lp lsl
okw ola olc oll olq opr opt osbc osbr otr mem nib ohbr okw ola olc oll olq opr opt
ple pod pvl q sac sbc sbl scbb schb scp osbc osbr otr ple pod pvl q sac sbc sbl
scsb sct se sfp sfs skp sob sobb sohb sop scbb schb scp scsb sct se sfp sfs skp sob
sosb sot ssc st sts t tac tbc toc tp sobb sohb sop sosb sot ssc st sts t tac
tqw trp ts tsc tso vmll w wn x xci tbc toc tp tqw trp ts tsc tso vmll w
xs wn x xci xs
Equivalently, the prefix 'no' or 'no-' on the corresponding long names may be Equivalently, the prefix 'no' or 'no-' on the corresponding long names may be
used. used.
=head1 LIMITATIONS =head1 LIMITATIONS
=over 4 =over 4
=item B<Parsing Limitations> =item B<Parsing Limitations>
skipping to change at line 4682 skipping to change at line 4757
=head1 SEE ALSO =head1 SEE ALSO
perlstyle(1), Perl::Tidy(3) perlstyle(1), Perl::Tidy(3)
=head1 INSTALLATION =head1 INSTALLATION
The perltidy binary uses the Perl::Tidy module and is installed when that module is installed. The module name is case-sensitive. For example, the basic comma nd for installing with cpanm is 'cpanm Perl::Tidy'. The perltidy binary uses the Perl::Tidy module and is installed when that module is installed. The module name is case-sensitive. For example, the basic comma nd for installing with cpanm is 'cpanm Perl::Tidy'.
=head1 VERSION =head1 VERSION
This man page documents perltidy version 20210402 This man page documents perltidy version 20210717
=head1 BUG REPORTS =head1 BUG REPORTS
A list of current bugs and issues can be found at the CPAN site L<https://rt.cpa n.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.cpa n.org/Public/Dist/Display.html?Name=Perl-Tidy>
To report a new bug or problem, use the link on this page. 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>. The source code repository is at L<https://github.com/perltidy/perltidy>.
=head1 COPYRIGHT =head1 COPYRIGHT
 End of changes. 34 change blocks. 
106 lines changed or deleted 187 lines changed or added

Home  |  About  |  Features  |  All  |  Newest  |  Dox  |  Diffs  |  RSS Feeds  |  Screenshots  |  Comments  |  Imprint  |  Privacy  |  HTTP(S)