to add one if it is missing.
For example
-
+
perltidy somefile.pl -opath=/tmp/
will produce F</tmp/somefile.pl.tdy>. Otherwise, F<somefile.pl.tdy> will
=item B<-q>, B<--quiet>
-Deactivate error messages and syntax checking (for running under
-an editor).
+Deactivate error messages (for running under an editor).
For example, if you use a vi-style editor, such as vim, you may execute
perltidy as a filter from within the editor using something like
The test for this is made by comparing an MD5 hash value for the input and
output code streams. This flag has no other effect on the functioning of
perltidy. This might be useful for certain code maintenance operations.
+Note: you will not see this message if you have error messages turned off with the
+-quiet flag.
=item B<-asu>, B<--assert-untidy>
will cause the perltidy to treate the words 'method', 'fun', '_sub' and 'M4' to be treated the same as if they were 'sub'. Note that if the alias words are separated by spaces then the string of words should be placed in quotes.
+Note that several other parameters accept a list of keywords, including 'sub' (see L<Specifying Block Types>).
+You do not need to include any sub aliases in these lists. Just include keyword 'sub' if you wish, and all aliases are automatically included.
=back
The default maximum line length is n=80 characters. Perltidy will try
to find line break points to keep lines below this length. However, long
quotes and side comments may cause lines to exceed this length.
-Setting B<-l=0> is equivalent to setting B<-l=(a large number)>.
+
+The default length of 80 comes from the past when this was the standard CRT
+screen width. Many programmers prefer to increase this to something like 120.
+
+Setting B<-l=0> is equivalent to setting B<-l=(a very large number)>. But this is
+not recommended because, for example, a very long list will be formatted in a
+single long line.
=item B<-vmll>, B<--variable-maximum-line-length>
The default is not to use this, which can also be indicated using B<-wc=0>.
-=item tabs
+=item B<Tabs>
Using tab characters will almost certainly lead to future portability
and maintenance problems, so the default and recommendation is not to
=item B<-et=n>, B<--entab-leading-whitespace>
This flag causes each B<n> initial space characters to be replaced by
-one tab character. Note that the integer B<n> is completely independent
-of the integer specified for indentation parameter, B<-i=n>.
+one tab character.
+
+The value of the integer B<n> can be any value but can be coordinated with the
+number of spaces used for intentation. For example, B<-et=4 -ci=4 -i=4> will
+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
+display software assumes for the spacing of a tab.
=item B<-t>, B<--tabs>
of indentation. Certain other features are incompatible with this
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>
-option.
+option. This flag is retained for backwards compatibility, but
+if you use tabs, the B<-et=n> flag is recommended.
=item B<-dt=n>, B<--default-tabsize=n>
=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>
A problem with formatting Perl code is that some modules can introduce new
$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.
+For another method of handling extended syntax see the section L<Skipping Selected Sections of Code>.
=item B<-io>, B<--indent-only>
=item B<-enc=s>, B<--character-encoding=s>
-where B<s>=B<none> or B<utf8>. This flag tells perltidy the character encoding
-of both the input and output character streams. The value B<utf8> causes the
-stream to be read and written as UTF-8. The value B<none> causes the stream to
-be processed without special encoding assumptions. At present there is no
-automatic detection of character encoding (even if there is a C<'use utf8'>
-statement in your code) so this flag must be set for streams encoded in UTF-8.
-Incorrectly setting this parameter can cause data corruption, so please
-carefully check the output.
+This flag indicates the character encoding, if any, of the input data stream.
+Perltidy does not look for the encoding directives in the soure stream, such
+as B<use utf8>, and instead relies on this flag to determine the encoding.
+(Note that perltidy often works on snippets of code rather than complete files
+so it cannot rely on B<use utf8> directives).
+
+The possible values for B<s> are (1) the name of an encoding recognized by the
+Encode.pm module, (2) B<none> if no encoding is used, or (3) <guess> if
+perltidy should guess.
+
+For example, the value B<utf8> causes the stream to be read and written as
+UTF-8. If the input stream cannot be decoded with a specified encoding then
+processing is not done.
-The default is B<none>.
+The value B<none> causes the stream to be processed without special encoding
+assumptions. This is appropriate for files which are written in single-byte
+character encodings such as latin-1.
-The abbreviations B<-utf8> or B<-UTF8> are equivalent to B<-enc=utf8>.
-So to process a file named B<file.pl> which is encoded in UTF-8 you can use:
+The value B<guess> tells perltidy to guess between either utf8 encoding or no
+encoding (meaning one character per byte). The guess uses the Encode::Guess
+module and this restricted range of guesses covers the most common cases.
+Testing showed that considering any greater number of encodings as guess
+suspects is too risky.
+
+The current default is B<guess>.
+
+The abbreviations B<-utf8> or B<-UTF8> are equivalent to B<-enc=utf8>, and the
+abbreviation B<-guess> is equivalent to <-enc=guess>. So to process a file
+named B<file.pl> which is encoded in UTF-8 you can use:
perltidy -utf8 file.pl
+or
+ perltidy -guess file.pl
+
+To process a file in B<euc-jp> you could use
+
+ perltidy -enc=euc-jp file.pl
+
+A perltidy output file is unencoded if the input file is unencoded, and
+otherwise it is encoded as B<utf8>, even if the input encoding was not
+B<utf8>.
+
+=item B<-gcs>, B<--use-unicode-gcstring>
+
+This flag controls whether or not perltidy may use module Unicode::GCString to
+obtain accurate display widths of wide characters. The default
+is B<--nouse-unicode-gcstring>.
+
+If this flag is set, and text is encoded, perltidy will look for the module
+Unicode::GCString and, if found, will use it to obtain character display
+widths. This can improve displayed vertical alignment for files with wide
+characters. It is a nice feature but it is off by default to avoid conflicting
+formatting when there are multiple developers. Perltidy installation does not
+require Unicode::GCString, so users wanting to use this feature need set this
+flag and also to install Unicode::GCString separately.
+
+If this flag is set and perltidy does not find module Unicode::GCString,
+a warning message will be produced and processing will continue but without
+the potential benefit provided by the module.
+
+Also note that actual vertical alignment depends upon the fonts used by the
+text display software, so vertical alignment may not be optimal even when
+Unicode::GCString is used.
+
=item B<-ole=s>, B<--output-line-ending=s>
where s=C<win>, C<dos>, C<unix>, or C<mac>. This flag tells perltidy
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.
+=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>
This flag causes perltidy to do B<n> complete iterations. The reason for this
sure that the output is converged, and there is no penalty to using a large
iteration limit since perltidy will check for convergence and stop iterating as
soon as possible. The default is B<-nconv> (no convergence check). Using
-B<-conv> will approximately double run time since normally one extra iteration
-is required to verify convergence.
+B<-conv> will approximately double run time since typically one extra iteration
+is required to verify convergence. No extra iterations are required if no new
+line breaks are made, and two extra iterations are occasionally needed when
+reformatting complex code structures, such as deeply nested ternary statements.
=back
space is required. Examples are commands for outdenting labels,
B<-ola>, and control keywords, B<-okw>.
-When default values are not used, it is suggested that 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.
+When default values are not used, it is recommended that either
+
+(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
+
+(2) the flag B<-extended-continuation-indentation> is used (see next section).
+
+=item B<-xci>, B<--extended-continuation-indentation>
+
+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 deeper into structures, hence the name. The improved indentation
+is particularly noticeable when the flags B<-ci=n> and B<-i=n> use the same value of
+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>.
+
+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
+improve indentation of some multi-line qw lists as shown below.
+
+ # perltidy
+ foreach $color (
+ qw(
+ AntiqueWhite3 Bisque1 Bisque2 Bisque3 Bisque4
+ SlateBlue3 RoyalBlue1 SteelBlue2 DeepSkyBlue3
+ ),
+ qw(
+ LightBlue1 DarkSlateGray1 Aquamarine2 DarkSeaGreen2
+ SeaGreen1 Yellow1 IndianRed1 IndianRed2 Tan1 Tan4
+ )
+ )
+
+ # perltidy -xci
+ foreach $color (
+ qw(
+ AntiqueWhite3 Bisque1 Bisque2 Bisque3 Bisque4
+ SlateBlue3 RoyalBlue1 SteelBlue2 DeepSkyBlue3
+ ),
+ qw(
+ LightBlue1 DarkSlateGray1 Aquamarine2 DarkSeaGreen2
+ SeaGreen1 Yellow1 IndianRed1 IndianRed2 Tan1 Tan4
+ )
+ )
=item B<-sil=n> B<--starting-indentation-level=n>
If the default method does not work correctly, or you want to change the
starting level, use B<-sil=n>, to force the starting level to be n.
-=item List indentation using B<-lp>, B<--line-up-parentheses>
+=item B<List indentation> using B<-lp>, B<--line-up-parentheses>
By default, perltidy indents lists with 4 spaces, or whatever value
is specified with B<-i=n>. Here is a small list formatted in this way:
closing paren, see the next section.
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
-existence of line breaks and/or block comments between the opening and
-closing parens may cause perltidy to temporarily revert to its default
-method.
+which always use whatever is specified with B<-i=n>.
-Note: 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.
+In situations where perltidy does not have complete freedom to choose line
+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
perltidy to choose newlines will conflict with B<-lp> and will cause
the careful coordination of an arbitrary number of break points in
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>
+
+This is an experimental parameter; the details might change as experience
+with it is gained.
+
+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
+very deeply nested. The B<-lpxl=s> flag is intended to help mitigate this problem by
+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
+containers as possible. This flag specifies a list of things which should
+B<not> be use B<-lp> indentation.
+
+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
+required container type, and (3) an optional numeric code.
+
+The only required piece of information is a container type, which is one of
+'(', '[', or '{'. For example the string
+
+ -lpxl='[ {'
+
+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 contents within parens will use -lp indentation.
+
+An optional numeric code may follow any of the container types to further refine the selection based
+on container contents. The numeric codes are:
+
+ '0' or blank: no check on contents
+ '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
+ code blocks, and without ternary operators
+
+For example,
+
+ -lpxl = '[ { (2'
+
+means only apply -lp to parenthesized lists which do not contain any sublists,
+code blocks or ternary expressions.
+
+A third optional item of information which can be given for parens is an alphanumeric
+letter which is used to limit the selection further depending on the type of
+token immediately before the paren. The possible letters are currently 'k',
+'K', 'f', 'F', 'w', and 'W', with these meanings:
+
+ 'k' matches if the previous nonblank token is a perl builtin keyword (such as 'if', 'while'),
+ 'K' matches if 'k' does not, meaning that the previous token is not a keyword.
+ 'f' matches if the previous token is a function other than a keyword.
+ 'F' matches if 'f' does not.
+ 'w' matches if either 'k' or 'f' match.
+ 'W' matches if 'w' does not.
+
+For example,
+
+ -lpxl = '[ { F(2'
+
+means only apply -lp to parenthesized lists which follow a function call and
+which do not contain any sublists, code blocks or ternary expressions. The logic
+of writing these codes is somewhat counter-intuitive because they describe what is not
+getting the -lp indentation. So the 'F' indicates that non-function calls are
+not getting -lp, or in other words that function calls are getting the -lp indentation.
+
=item B<-cti=n>, B<--closing-token-indentation>
The B<-cti=n> flag controls the indentation of a line beginning with
The flags B<-cti=1> and B<-cti=2> work well with the B<-lp> flag (previous
section).
-
+
# perltidy -lp -cti=1
@month_of_year = (
'Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun',
The default is not to do this, indicated by B<-nicb>.
+
+=item B<-nib>, B<--non-indenting-braces>
+
+Normally, lines of code contained within a pair of block braces receive one
+additional level of indentation. This flag, which is enabled by default,
+causes perltidy to look for
+opening block braces which are followed by a special side comment. This special
+side comment is B<#<<<> by default. If found, the code between this opening brace and its
+corresponding closing brace will not be given the normal extra indentation
+level. For example:
+
+ { #<<< a closure to contain lexical vars
+
+ my $var; # this line does not get one level of indentation
+ ...
+
+ }
+
+ # this line does not 'see' $var;
+
+This can be useful, for example, when combining code from different files.
+Different sections of code can be placed within braces to keep their lexical
+variables from being visible to the end of the file. To keep the new braces
+from causing all of their contained code to be indented if you run perltidy,
+and possibly introducing new line breaks in long lines, you can mark the
+opening braces with this special side comment.
+
+Only the opening brace needs to be marked, since perltidy knows where the
+closing brace is. Braces contained within marked braces may also be marked
+as non-indenting.
+
+If your code happens to have some opening braces followed by '#<<<', and you
+don't want this behavior, you can use B<-nnib> to deactivate it. To make it
+easy to remember, the default string is the same as the string for starting a
+B<format-skipping> section. There is no confusion because in that case it is
+for a block comment rather than a side-comment.
+
+The special side comment can be changed with the next parameter.
+
+
+=item B<-nibp=s>, B<--non-indenting-brace-prefix=s>
+
+The B<-nibp=string> parameter may be used to change the marker for
+non-indenting braces. The default is equivalent to -nibp='#<<<'. The string
+that you enter must begin with a # and should be in quotes as necessary to get
+past the command shell of your system. This string is the leading text of a
+regex pattern that is constructed by appending pre-pending a '^' and appending
+a'\s', so you must also include backslashes for characters to be taken
+literally rather than as patterns.
+
+For example, to match the side comment '#++', the parameter would be
+
+ -nibp='#\+\+'
+
+
=item B<-olq>, B<--outdent-long-quotes>
When B<-olq> is set, lines which is a quoted string longer than the
versions of perltidy. The negation of this also works, B<-noll> or
B<--nooutdent-long-lines>, and is equivalent to setting B<-nolq> and B<-nolc>.
-=item Outdenting Labels: B<-ola>, B<--outdent-labels>
+=item B<Outdenting Labels:> B<-ola>, B<--outdent-labels>
This command will cause labels to be outdented by 2 spaces (or whatever B<-ci>
has been set to), if possible. This is the default. For example:
Use B<-nola> to not outdent labels.
-=item Outdenting Keywords
+=item B<Outdenting Keywords>
=over 4
The default is not to do this.
-=item Specifying Outdented Keywords: B<-okwl=string>, B<--outdent-keyword-list=string>
+=item B<Specifying Outdented Keywords:> B<-okwl=string>, B<--outdent-keyword-list=string>
This command can be used to change the keywords which are outdented with
the B<-okw> command. The parameter B<string> is a required list of perl
Code Indentation section, and
the Comment Control section to be ignored.
-=item Tightness of curly braces, parentheses, and square brackets.
+=item B<Tightness of curly braces, parentheses, and square brackets>
Here the term "tightness" will mean the closeness with which
pairs of enclosing tokens, such as parentheses, contain the quantities
=item B<-aws>, B<--add-whitespace>
-Setting this option allows perltidy to add certain whitespace improve
+Setting this option allows perltidy to add certain whitespace to improve
code readability. This is the default. If you do not want any
whitespace added, but are willing to have some whitespace deleted, use
B<-naws>. (Use B<-fws> to leave whitespace completely unchanged).
do not want any old whitespace removed, use B<-ndws> or
B<--nodelete-old-whitespace>.
-=item Detailed whitespace controls around tokens
+=item B<Detailed whitespace controls around tokens>
For those who want more detailed control over the whitespace around
tokens, there are four parameters which can directly modify the default
B<WARNING> Be sure to put these tokens in quotes to avoid having them
misinterpreted by your command shell.
-=item Space between specific keywords and opening paren
+=item B<Note1: Perltidy does always follow whitespace controls>
+
+The various parameters controlling whitespace within a program are requests which perltidy follows as well as possible, but there are a number of situations where changing whitespace could change program behavior and is not done. Some of these are obvious; for example, we should not remove the space between the two plus symbols in '$x+ +$y' to avoid creating a '++' operator. Some are more subtle and involve the whitespace around bareword symbols and locations of possible filehandles. For example, consider the problem of formatting the following subroutine:
+
+ sub print_div {
+ my ($x,$y)=@_;
+ print $x/$y;
+ }
+
+Suppose the user requests that / signs have a space to the left but not to the right. Perltidy will refuse to do this, but if this were done the result would be
+
+ sub print_div {
+ my ($x,$y)=@_;
+ print $x /$y;
+ }
+
+If formatted in this way, the program will not run (at least with recent versions of perl) because the $x is taken to be a filehandle and / is assumed to start a quote. In a complex program, there might happen to be a / which terminates the multiline quote without a syntax error, allowing the program to run, but not as intended.
+
+Related issues arise with other binary operator symbols, such as + and -, and in older versions of perl there could be problems with ternary operators. So to avoid changing program behavior, perltidy has the simple rule that whitespace around possible filehandles is left unchanged. Likewise, whitespace around barewords is left unchanged. The reason is that if the barewords are defined in other modules, or in code that has not even been written yet, perltidy will not have seen their prototypes and must treat them cautiously.
+
+In perltidy this is implemented in the tokenizer by marking token following a
+B<print> keyword as a special type B<Z>. When formatting is being done,
+whitespace following this token type is generally left unchanged as a precaution
+against changing program behavior. This is excessively conservative but simple
+and easy to implement. Keywords which are treated similarly to B<print> include
+B<printf>, B<sort>, B<exec>, B<system>. Changes in spacing around parameters
+following these keywords may have to be made manually. For example, the space,
+or lack of space, after the parameter $foo in the following line will be
+unchanged in formatting.
+
+ system($foo );
+ system($foo);
+
+To find if a token is of type B<Z> you can use B<perltidy -DEBUG>. For the
+first line above the result is
+
+ 1: system($foo );
+ 1: kkkkkk{ZZZZb};
+
+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>
+
+Despite these precautions, it is still possible to introduce syntax errors with
+some asymmetric whitespace rules, particularly when call parameters are not
+placed in containing parens or braces. For example, the following two lines will
+be parsed by perl without a syntax error:
+
+ # original programming, syntax ok
+ my @newkeys = map $_-$nrecs+@data, @oldkeys;
+
+ # perltidy default, syntax ok
+ my @newkeys = map $_ - $nrecs + @data, @oldkeys;
+
+But the following will give a syntax error:
+
+ # perltidy -nwrs='-'
+ my @newkeys = map $_ -$nrecs + @data, @oldkeys;
+
+For another example, the following two lines will be parsed without syntax error:
+
+ # original programming, syntax ok
+ for my $severity ( reverse $SEVERITY_LOWEST+1 .. $SEVERITY_HIGHEST ) { ... }
+
+ # perltidy default, syntax ok
+ for my $severity ( reverse $SEVERITY_LOWEST + 1 .. $SEVERITY_HIGHEST ) { ... }
+
+But the following will give a syntax error:
+
+ # perltidy -nwrs='+', syntax error:
+ for my $severity ( reverse $SEVERITY_LOWEST +1 .. $SEVERITY_HIGHEST ) { ... }
+
+To avoid subtle parsing problems like this, it is best to avoid spacing a
+binary operator asymetrically with a space on the left but not on the right.
+
+=item B<Space between specific keywords and opening paren>
When an opening paren follows a Perl keyword, no space is introduced after the
keyword, unless it is (by default) one of these:
- my local our and or eq ne if else elsif until unless
+ my local our and or xor eq ne if else elsif until unless
while for foreach return switch case given when
These defaults can be modified with two commands:
To put a space after all keywords, see the next item.
-=item Space between all keywords and opening parens
+=item B<Space between all keywords and opening parens>
When an opening paren follows a function or keyword, no space is introduced
after the keyword except for the keywords noted in the previous item. To
B<-skp> or B<--space-keyword-paren>
-You will probably also want to use the flag B<-sfp> (next item) too.
+You may also want to use the flag B<-sfp> (next item) too.
-=item Space between all function names and opening parens
+=item B<Space between all function names and opening parens>
-When an opening paren follows a function the default is not to introduce
-a space. To cause a space to be introduced use:
+When an opening paren follows a function the default and recommended formatting
+is not to introduce a space. To cause a space to be introduced use:
B<-sfp> or B<--space-function-paren>
You will probably also want to use the flag B<-skp> (previous item) too.
+The reason this is not recommended is that spacing a function paren can make a
+program vulnerable to parsing problems by Perl. For example, the following
+two-line program will run as written but will have a syntax error if
+reformatted with -sfp:
+
+ if ( -e filename() ) { print "I'm here\n"; }
+ sub filename { return $0 }
+
+In this particular case the syntax error can be removed if the line order is
+reversed, so that Perl parses 'sub filename' first.
+
+=item B<-fpva> or B<--function-paren-vertical-alignment>
+
+A side-effect of using the B<-sfp> flag is that the parens may become vertically
+aligned. For example,
+
+ # perltidy -sfp
+ myfun ( $aaa, $b, $cc );
+ mylongfun ( $a, $b, $c );
+
+This is the default behavior. To prevent this alignment use B<-nfpva>:
+
+ # perltidy -sfp -nfpva
+ myfun ( $aaa, $b, $cc );
+ mylongfun ( $a, $b, $c );
+
=item B<-spp=n> or B<--space-prototype-paren=n>
This flag can be used to control whether a function prototype is preceded by a space. For example, the following prototype does not have a space.
sub usage(); # n=1 [default; follows input]
sub usage (); # n=2 [space]
-=item Trimming whitespace around C<qw> quotes
+=item B<-kpit=n> or B<--keyword-paren-inner-tightness=n>
+
+The space inside of an opening paren, which itself follows a certain keyword,
+can be controlled by this parameter. The space on the inside of the
+corresponding closing paren will be treated in the same (balanced) manner.
+This parameter has precedence over any other paren spacing rules. The values
+of B<n> are as follows:
+
+ -kpit=0 means always put a space (not tight)
+ -kpit=1 means ignore this parameter [default]
+ -kpit=2 means never put a space (tight)
+
+To illustrate, the following snippet is shown formatted in three ways:
+
+ if ( seek( DATA, 0, 0 ) ) { ... } # perltidy (default)
+ if (seek(DATA, 0, 0)) { ... } # perltidy -pt=2
+ if ( seek(DATA, 0, 0) ) { ... } # perltidy -pt=2 -kpit=0
+
+In the second case the -pt=2 parameter makes all of the parens tight. In the
+third case the -kpit=0 flag causes the space within the 'if' parens to have a
+space, since 'if' is one of the keywords to which the -kpit flag applies by
+default. The remaining parens are still tight because of the -pt=2 parameter.
+
+The set of keywords to which this parameter applies are by default are:
+
+ if elsif unless while until for foreach
+
+These can be changed with the parameter B<-kpitl=s> described in the next section.
+
+
+=item B<-kpitl=string> or B<--keyword-paren-inner-tightness=string>
+
+This command can be used to change the keywords to which the the B<-kpit=n>
+command applies. The parameter B<string> is a required list either keywords or
+functions, which should be placed in quotes if there are more than one. By
+itself, this parameter does not cause any change in spacing, so the B<-kpit=n>
+command is still required.
+
+For example, the commands C<-kpitl="if else while" -kpit=2> will cause the just
+the spaces inside parens following 'if', 'else', and 'while' keywords to
+follow the tightness value indicated by the B<-kpit=2> flag.
+
+=item B<-lop> or B<--logical-padding>
+
+In the following example some extra space has been inserted on the second
+line between the two open parens. This extra space is called "logical padding"
+and is intended to help align similar things vertically in some logical
+or ternary expressions.
+
+ # perltidy [default formatting]
+ $same =
+ ( ( $aP eq $bP )
+ && ( $aS eq $bS )
+ && ( $aT eq $bT )
+ && ( $a->{'title'} eq $b->{'title'} )
+ && ( $a->{'href'} eq $b->{'href'} ) );
+
+Note that this is considered to be a different operation from "vertical
+alignment" because space at just one line is being adjusted, whereas in
+"vertical alignment" the spaces at all lines are being adjusted. So it sort of
+a local version of vertical alignment.
+
+Here is an example involving a ternary operator:
+
+ # perltidy [default formatting]
+ $bits =
+ $top > 0xffff ? 32
+ : $top > 0xff ? 16
+ : $top > 1 ? 8
+ : 1;
+
+This behavior is controlled with the flag B<--logical-padding>, which is set
+'on' by default. If it is not desired it can be turned off using
+B<--nological-padding> or B<-nlop>. The above two examples become, with
+B<-nlop>:
+
+ # perltidy -nlop
+ $same =
+ ( ( $aP eq $bP )
+ && ( $aS eq $bS )
+ && ( $aT eq $bT )
+ && ( $a->{'title'} eq $b->{'title'} )
+ && ( $a->{'href'} eq $b->{'href'} ) );
+
+ # perltidy -nlop
+ $bits =
+ $top > 0xffff ? 32
+ : $top > 0xff ? 16
+ : $top > 1 ? 8
+ : 1;
+
+
+=item B<Trimming whitespace around C<qw> quotes>
B<-tqw> or B<--trim-qw> provide the default behavior of trimming
spaces around multi-line C<qw> quotes and indenting them appropriately.
=item B<-sbq=n> or B<--space-backslash-quote=n>
-Lines like
+lines like
$str1=\"string1";
$str2=\'string2';
can confuse syntax highlighters unless a space is included between the backslash and the single or double quotation mark.
-This can be controlled with the value of B<n> as follows:
+this can be controlled with the value of B<n> as follows:
-sbq=0 means no space between the backslash and quote
-sbq=1 means follow the example of the source code
-sbq=2 means always put a space between the backslash and quote
-The default is B<-sbq=1>, meaning that a space will be used 0if there is one in the source code.
+The default is B<-sbq=1>, meaning that a space will be used if there is one in the source code.
-=item Trimming trailing whitespace from lines of POD
+=item B<Trimming trailing whitespace from lines of POD>
B<-trp> or B<--trim-pod> will remove trailing whitespace from lines of POD.
The default is not to do this.
If block comments are preceded by a blank line, or have no leading
whitespace, they will not be mistaken as hanging side comments.
-=item Closing Side Comments
+=item B<Closing Side Comments>
A closing side comment is a special comment which perltidy can
automatically create and place after the closing brace of a code block.
=back
-=item Static Block Comments
+=item B<Static Block Comments>
Static block comments are block comments with a special leading pattern,
C<##> by default, which will be treated slightly differently from other
=back
-=item Static Side Comments
+=item B<Static Side Comments>
Static side comments are side comments with a special leading pattern.
This option can be useful for controlling how commented code is displayed
=back
-
=back
=head2 Skipping Selected Sections of Code
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
-the B<--noformat-skipping> or B<-nfs> flag. It should be used sparingly to
-avoid littering code with markers, but it might be helpful for working
-around occasional problems. For example it might be useful for keeping
-the indentation of old commented code unchanged, keeping indentation of
-long blocks of aligned comments unchanged, keeping certain list
-formatting unchanged, or working around a glitch in perltidy.
-
-=over 4
+formatting by marking the starting and ending lines with special comments.
+There are two options for doing this. The first option is called
+B<--format-skipping> or B<-fs>, and the second option is called
+B<--code-skipping> or B<-cs>.
-=item B<-fs>, B<--format-skipping>
+In both cases the lines of code will be output without any changes.
+The difference is that in B<--format-skipping>
+perltidy will still parse the marked lines of code and check for errors,
+whereas in B<--code-skipping> perltidy will simply pass the lines to the output without any checking.
-This flag, which is enabled by default, causes any code between
-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
+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:
- #<<< do not let perltidy touch this
+ #<<< format skipping: do not let perltidy change my nice formatting
my @list = (1,
1, 1,
1, 2, 1,
1, 4, 6, 4, 1,);
#>>>
-The comment markers may be placed at any location that a block comment may
-appear. If they do not appear to be working, use the -log flag and examine the
-F<.LOG> file. Use B<-nfs> to disable this feature.
+B<--code-skipping> uses starting and ending markers '#<<V' and '#>>V', like
+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>
+
+As explained above, this flag, which is enabled by default, causes any code
+between special beginning and ending comment markers to be passed to the output
+without formatting. The code between the comments is still checked for errors
+however. The default beginning marker is #<<< and the default ending marker is
+#>>>.
+
+Format skipping begins when a format skipping beginning comment is seen and
+continues until a format-skipping ending comment is found.
+
+This feature can be disabled with B<-nfs>. This should not normally be necessary.
=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
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
=item B<-fse=string>, B<--format-skipping-end=string>
-The B<-fsb=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
-fse='#<<<'.
+The beginning and ending strings may be the same, but it is preferable
+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> section, 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
=head2 Line Break Control
block types separated by commas or spaces. For example, to cuddle code blocks
of type sort, map and grep, in addition to the default types, the string could
be set to
-
+
-cbl="sort map grep"
or equivalently
-ohbr or --opening-hash-brace-right
-osbr or --opening-square-bracket-right
+=item B<-bbhb=n>, B<--break-before-hash-brace=n> and related flags
+
+When a list of items spans multiple lines, the default formatting is to place
+the opening brace (or other container token) at the end of the starting line,
+like this:
+
+ $romanNumerals = {
+ one => 'I',
+ two => 'II',
+ three => 'III',
+ four => 'IV',
+ };
+
+This flag can change the default behavior to cause a line break to be placed
+before the opening brace according to the value given to the integer B<n>:
+
+ -bbhb=0 never break [default]
+ -bbhb=1 stable: break if the input script had a break
+ -bbhb=2 break if list is 'complex' (see note below)
+ -bbhb=3 always break
+
+For example,
+
+ # perltidy -bbhb=3
+ $romanNumerals =
+ {
+ one => 'I',
+ two => 'II',
+ three => 'III',
+ four => 'IV',
+ };
+
+There are several points to note about this flag:
+
+=over 4
+
+=item *
+
+This parameter only applies if the opening brace is preceded by an '='
+or '=>'.
+
+=item *
+
+This parameter only applies if the contents of the container looks like a list.
+The contents need to contain some commas or '=>'s at the next interior level to
+be considered a list.
+
+=item *
+
+For the B<n=2> option, a list is considered 'complex' if it is part of a nested list
+structure which spans multiple lines in the input file.
+
+=item *
+
+If multiple opening tokens have been 'welded' together with the B<-wn> parameter, then
+this parameter has no effect.
+
+=item *
+
+The indentation of the braces will normally be one level of continuation
+indentation by default. This can be changed with the parameter
+B<-bbhbi=n> in the next section.
+
+=item *
+
+Similar flags for controlling parens and square brackets are given in the subsequent section.
+
+=back
+
+=item B<-bbhbi=n>, B<--break-before-hash-brace-and-indent=n>
+
+This flag is a companion to B<-bbhb=n> for controlling the indentation of an opening hash brace
+which is placed on a new line by that parameter. The indentation is as follows:
+
+ -bbhbi=0 one continuation level [default]
+ -bbhbi=1 outdent by one continuation level
+ -bbhbi=2 indent one full indentation level
+
+For example:
+
+ # perltidy -bbhb=3 -bbhbi=1
+ $romanNumerals =
+ {
+ one => 'I',
+ two => 'II',
+ three => 'III',
+ four => 'IV',
+ };
+
+ # perltidy -bbhb=3 -bbhbi=2
+ $romanNumerals =
+ {
+ one => 'I',
+ two => 'II',
+ three => 'III',
+ four => 'IV',
+ };
+
+Note that this parameter has no effect unless B<-bbhb=n> is also set.
+
+=item B<-bbsb=n>, B<--break-before-square-bracket=n>
+
+This flag is similar to the flag described above, except it applies to lists contained within square brackets.
+
+ -bbsb=0 never break [default]
+ -bbsb=1 stable: break if the input script had a break
+ -bbsb=2 break if list is 'complex' (part of nested list structure)
+ -bbsb=3 always break
+
+=item B<-bbsbi=n>, B<--break-before-square-bracket-and-indent=n>
+
+This flag is a companion to B<-bbsb=n> for controlling the indentation of an opening square bracket
+which is placed on a new line by that parameter. The indentation is as follows:
+
+ -bbsbi=0 one continuation level [default]
+ -bbsbi=1 outdent by one continuation level
+ -bbsbi=2 indent one full indentation level
+
+=item B<-bbp=n>, B<--break-before-paren=n>
+
+This flag is similar to B<-bbhb=n>, described above, except it applies to lists contained within parens.
+
+ -bbp=0 never break [default]
+ -bbp=1 stable: break if the input script had a break
+ -bpb=2 break if list is 'complex' (part of nested list structure)
+ -bbp=3 always break
+
+=item B<-bbpi=n>, B<--break-before-paren-and-indent=n>
+
+This flag is a companion to B<-bbp=n> for controlling the indentation of an opening paren
+which is placed on a new line by that parameter. The indentation is as follows:
+
+ -bbpi=0 one continuation level [default]
+ -bbpi=1 outdent by one continuation level
+ -bbpi=2 indent one full indentation level
+
=item B<-wn>, B<--weld-nested-containers>
The B<-wn> flag causes closely nested pairs of opening and closing container
When this flag is set perltidy makes a preliminary pass through the file and
identifies all nested pairs of containers. To qualify as a nested pair, the
-closing container symbols must be immediately adjacent. The opening symbols
-must either be adjacent, or, if the outer opening symbol is an opening
-paren, they may be separated by any single non-container symbol or something
-that looks like a function evaluation.
+closing container symbols must be immediately adjacent and the opening symbols
+must either (1) be adjacent as in the above example, or (2) have an anonymous
+sub declaration following an outer opening container symbol which is not a
+code block brace, or (3) have an outer opening paren separated from the inner
+opening symbol by any single non-container symbol or something that looks like
+a function evaluation, as illustrated in the next examples.
Any container symbol may serve as both the inner container of one pair and as
the outer container of an adjacent pair. Consequently, any number of adjacent
$m
) );
+The welded closing tokens are by default on a separate line but this can be
+modified with the B<-vtc=n> flag (described in the next section). For example,
+the same example adding B<-vtc=2> is
+
+ # perltidy -wn -vtc=2
+ $x->badd( bmul(
+ $class->new( abs(
+ $sx * int( $xr->numify() ) & $sy * int( $yr->numify() ) ) ),
+ $m ) );
+
This format option is quite general but there are some limitations.
One limitation is that any line length limit still applies and can cause long
Finally, the stacking of containers defined by this flag have priority over
any other container stacking flags. This is because any welding is done first.
+=item B<-wnxl=s>, B<--weld-nested-exclusion-list>
+
+The B<-wnxl=s> flag provides some control over the types of containers which
+can be welded. The B<-wn> flag by default is "greedy" in welding adjacent
+containers. If it welds more types of containers than desired, this flag
+provides a capability to reduce the amount of welding by specifying a list
+of things which should B<not> be welded.
+
+The logic in perltidy to apply this is straightforward. As each container
+token is being considered for joining a weld, any exclusion rules are consulted
+and used to reject the weld if necessary.
+
+This list is a string with space-separated items. Each item consists of up to
+three pieces of information: (1) an optional position, (2) an optional
+preceding type, and (3) a container type.
+
+The only required piece of information is a container type, which is one of
+'(', '[', '{' or 'q'. The first three of these are container tokens and the
+last represents a quoted list. For example the string
+
+ -wnxl='[ { q'
+
+means do B<NOT> include square-bracets, braces, or quotes in any welds. The only unspecified
+container is '(', so this string means that only welds involving parens will be made.
+
+To illustrate, following welded snippet consists of a chain of three welded
+containers with types '(' '[' and 'q':
+
+ # perltidy -wn
+ skip_symbols( [ qw(
+ Perl_dump_fds
+ Perl_ErrorNo
+ Perl_GetVars
+ PL_sys_intern
+ ) ] );
+
+Even though the qw term uses parens as the quote delimiter, it has a special
+type 'q' here. If it appears in a weld it always appears at the end of the
+welded chain.
+
+Any of the container types '[', '{', and '(' may be prefixed with a position
+indicator which is either '^', to indicate the first token of a welded
+sequence, or '.', to indicate an interior token of a welded sequence. (Since
+a quoted string 'q' always ends a chain it does need a position indicator).
+
+For example, if we do not want a sequence of welded containers to start with a
+square bracket we could use
+
+ -wnxl='^['
+
+In the above snippet, there is a square bracket but it does not start the chain,
+so the formatting would be unchanged if it were formatted with this restriction.
+
+A third optional item of information which can be given is an alphanumeric
+letter which is used to limit the selection further depending on the type of
+token immediately before the container. If given, it goes just before the
+container symbol. The possible letters are currently 'k', 'K', 'f', 'F',
+'w', and 'W', with these meanings:
+
+ 'k' matches if the previous nonblank token is a perl builtin keyword (such as 'if', 'while'),
+ 'K' matches if 'k' does not, meaning that the previous token is not a keyword.
+ 'f' matches if the previous token is a function other than a keyword.
+ 'F' matches if 'f' does not.
+ 'w' matches if either 'k' or 'f' match.
+ 'W' matches if 'w' does not.
+
+For example, compare
+
+ # perltidy -wn
+ if ( defined( $_Cgi_Query{
+ $Config{'methods'}{'authentication'}{'remote'}{'cgi'}{'username'}
+ } ) )
+
+with
+
+ # perltidy -wn -wnxl='^K( {'
+ if ( defined(
+ $_Cgi_Query{ $Config{'methods'}{'authentication'}{'remote'}{'cgi'}
+ {'username'} }
+ ) )
+
+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)
+but the curly brace is rejected by the rule.
+
+Here are some additional example strings and their meanings:
+
+ '^(' - the weld must not start with a paren
+ '.(' - 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
+ '^K(' - exclude a leading paren preceded by a non-keyword
+ '.k(' - exclude a secondary paren preceded by a keyword
+ '[ {' - 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 brackets.
by a semicolon or another closing token, and is not in
a list environment.
-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
-between tightness and readability in complex lists.
+The rules for B<-vtc=1> and B<-vtc=3> are designed to maintain a reasonable
+balance between tightness and readability in complex lists.
=item *
three => 'III',
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:
# perltidy -lp -vt=1
independently to each of the closing container token types.
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>.
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>.
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>.
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
-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>
To simplify input even further for the case in which both opening and closing
non-block containers are stacked, the flag B<-sac> or B<--stack-all-containers>
-is an abbreviation for B<-sot -sot>.
+is an abbreviation for B<-sot -sct>.
+
+Please note that if both opening and closing tokens are to be stacked, then the
+newer flag B<-weld-nested-containers> may be preferable because it insures that
+stacking is always done symmetrically. It also removes an extra level of
+unnecessary indentation within welded containers. It is able to do this
+because it works on formatting globally rather than locally, as the B<-sot> and
+B<-sct> flags do.
=item B<-dnl>, B<--delete-old-newlines>
breaks; see B<--freeze-newlines> to completely prevent changes to line
break points.
-=item Controlling whether perltidy breaks before or after operators
+=item B<Controlling whether perltidy breaks before or after operators>
Four command line parameters provide some control over whether
a line break should be before or after specific token types.
=head2 Controlling List Formatting
-Perltidy attempts to place comma-separated arrays of values in tables
-which look good. Its default algorithms usually work well, and they
-have been improving with each release, but several parameters are
-available to control list formatting.
-
-=over 4
-
-=item B<-boc>, B<--break-at-old-comma-breakpoints>
+Perltidy attempts to format lists of comma-separated values in tables which
+look good. Its default algorithms usually work well, but sometimes they don't.
+In this case, there are several methods available to control list formatting.
-This flag tells perltidy to try to break at all old commas. This is not
-the default. Normally, perltidy makes a best guess at list formatting,
-and seldom uses old comma breakpoints. Usually this works well,
-but consider:
+A very simple way to prevent perltidy from changing the line breaks
+within a comma-separated list of values is to insert a blank line,
+comment, or side-comment anywhere between the opening and closing
+parens (or braces or brackets). This causes perltidy to skip
+over its list formatting logic. (The reason is that any of
+these items put a constraint on line breaks, and perltidy
+needs complete control over line breaks within a container to
+adjust a list layout). For example, let us consider
my @list = (1,
1, 1,
1, 3, 3, 1,
1, 4, 6, 4, 1,);
-The default formatting will flatten this down to one line:
+The default formatting, which allows a maximum line length of 80,
+will flatten this down to one line:
# perltidy (default)
my @list = ( 1, 1, 1, 1, 2, 1, 1, 3, 3, 1, 1, 4, 6, 4, 1, );
-which hides the structure. Using B<-boc>, plus additional flags
-to retain the original style, yields
+This formatting loses important information. If we place a side comment on one
+of the lines, for example, we get the following result with with default formatting
+parameters:
+
+ my @list = (
+ 1, # a side comment, comment, or blank keeps list intact
+ 1, 1,
+ 1, 2, 1,
+ 1, 3, 3, 1,
+ 1, 4, 6, 4, 1,
+ );
+
+We could achieve the same result with a blank line or full comment
+anywhere between the opening and closing parens.
+
+For another possibility see
+the -fs flag in L<Skipping Selected Sections of Code>.
+
+=over 4
+
+=item B<-boc>, B<--break-at-old-comma-breakpoints>
+
+The B<-boc> flag is another way to prevent comma-separated lists from being
+reformatted. Using B<-boc> on the above example, plus additional flags to retain
+the original style, yields
# perltidy -boc -lp -pt=2 -vt=1 -vtc=1
my @list = (1,
1, 4, 6, 4, 1,);
A disadvantage of this flag is that all tables in the file
-must already be nicely formatted. For another possibility see
-the -fs flag in L<Skipping Selected Sections of Code>.
+must already be nicely formatted.
+
=item B<-mft=n>, B<--maximum-fields-per-table=n>
n=1 stable: break at all commas after => if container is open,
EXCEPT FOR one-line containers
n=2 break at all commas after =>, BUT try to form the maximum
- maximum one-line container lengths
+ one-line container lengths
n=3 do not treat commas after => specially at all
n=4 break everything: like n=0 but ALSO break a short container with
a => not followed by a comma when -vt=0 is used
treated as a single item in a table. The number of fields in this table
will be determined by the same rules that are used for any other table.
Here is an example.
-
+
# perltidy -cab=3
my %last_day = (
"01" => 31, "02" => 29, "03" => 31, "04" => 30,
at internal keywords C<if> and C<unless> will normally be retained.
To prevent this, and thus form longer lines, use B<-nbol>.
+Please note that this flag does not duplicate old logical breakpoints. They
+are merely used as a hint with this flag that a statement should remain
+broken. Without this flag, perltidy will normally try to combine relatively
+short expressions into a single line.
+
+For example, given this snippet:
+
+ return unless $cmd = $cmd || ($dot
+ && $Last_Shell) || &prompt('|');
+
+ # perltidy -bol [default]
+ return
+ unless $cmd = $cmd
+ || ( $dot
+ && $Last_Shell )
+ || &prompt('|');
+
+ # perltidy -nbol
+ return unless $cmd = $cmd || ( $dot && $Last_Shell ) || &prompt('|');
+
=item B<-bom>, B<--break-at-old-method-breakpoints>
By default, a method call arrow C<-E<gt>> is considered a candidate for
in which lines begin with a closing paren followed by a call arrow,
as in this example:
+ # perltidy -bom -wn
my $q = $rs->related_resultset(
'CDs'
)->related_resultset(
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<-bos>, B<--break-at-old-semicolon-breakpoints>
+
+Semicolons are normally placed at the end of a statement. This means that formatted lines do not normally begin with semicolons. If the input stream has some lines which begin with semicolons, these can be retained by setting this flag. For example, consider
+the following two-line input snippet:
+
+ $z = sqrt($x**2 + $y**2)
+ ;
+
+The default formatting will be:
+
+ $z = sqrt( $x**2 + $y**2 );
+
+The result using B<perltidy -bos> keeps the isolated semicolon:
+
+ $z = sqrt( $x**2 + $y**2 )
+ ;
+
+The default is not to do this, B<-nbos>.
+
=item B<-bok>, B<--break-at-old-keyword-breakpoints>
By default, if an attribute list is broken at a C<:> in the source file, then
it will remain broken. For example, given the following code, the line breaks
at the ':'s will be retained:
-
+
my @field
: field
: Default(1)
To prevent this, and thereby always form longer lines, use B<-nboa>.
+=item B<Keeping old breakpoints at specific token types>
+
+Two command line parameters provide detailed control over whether
+perltidy should keep an old line break before or after a specific
+token type:
+
+B<-kbb=s> or B<--keep-old-breakpoints-before=s>, and
+
+B<-kba=s> or B<--keep-old-breakpoints-after=s>
+
+These parameters are each followed by a quoted string, B<s>, containing
+a list of token types (separated only by spaces). No more than one of each
+of these parameters should be specified, because repeating a
+command-line parameter always overwrites the previous one before
+perltidy ever sees it.
+
+For example, -kbb='=>' means that if an input line begins with a '=>' then the
+output script should also have a line break before that token.
+
+For example, given the script:
+
+ method 'foo'
+ => [ Int, Int ]
+ => sub {
+ my ( $self, $x, $y ) = ( shift, @_ );
+ ...;
+ };
+
+ # perltidy [default]
+ method 'foo' => [ Int, Int ] => sub {
+ my ( $self, $x, $y ) = ( shift, @_ );
+ ...;
+ };
+
+ # perltidy -kbb='=>'
+ method 'foo'
+ => [ Int, Int ]
+ => sub {
+ my ( $self, $x, $y ) = ( shift, @_ );
+ ...;
+ };
+
=item B<-iob>, B<--ignore-old-breakpoints>
Use this flag to tell perltidy to ignore existing line breaks to the
maximum extent possible. This will tend to produce the longest possible
containers, regardless of type, which do not exceed the line length
-limit.
+limit. But please note that this parameter has priority over all
+other parameters requesting that certain old breakpoints be kept.
=item B<-kis>, B<--keep-interior-semicolons>
should apply. The section L<"Specifying Block Types"> explains how to list
block types.
-=item Note on using the B<-blao> and B<-blbc> options.
+=item B<Note on using the> B<-blao> and B<-blbc> options.
These blank line controls introduce a certain minimum number of blank lines in
the text, but the final number of blank lines may be greater, depending on
perltidy -blao=2 -blbc=2 -blaol='*' -blbcl='*' filename
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
perltidy retains single blank lines, so the blank lines remain.
B<-nst> and/or B<-nse> after the -pbp parameter.
Also note that the value of continuation indentation, -ci=4, is equal to the
-value of the full indentation, -i=4. In some complex statements perltidy will
-produce nicer results with -ci=2. This can be implemented by including -ci=2
-after the -pbp parameter. For example,
+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.
# perltidy -pbp
$self->{_text} = (
: ' elsewhere in this document'
);
+ # perltidy -pbp -xci
+ $self->{_text} = (
+ !$section ? ''
+ : $type eq 'item' ? "the $section entry"
+ : "the section on $section"
+ )
+ . ( $page
+ ? ( $section ? ' in ' : '' ) . "the $page$page_ext manpage"
+ : ' elsewhere in this document'
+ );
+
+The B<-xci> flag was developed after the B<-pbp> parameters were published so you need
+to include it separately.
-=item One-line blocks
+=item B<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.
=head2 Controlling Vertical Alignment
-Vertical alignment refers to lining up certain symbols in list of consecutive
+Vertical alignment refers to lining up certain symbols in a list of consecutive
similar lines to improve readability. For example, the "fat commas" are
aligned in the following statement:
Proto => 'tcp'
);
-The only explicit control on vertical alignment is to turn it off using
-B<-novalign>, a flag mainly intended for debugging. However, vertical
-alignment can be forced to stop and restart by selectively introducing blank
-lines. For example, a blank has been inserted in the following code
-to keep somewhat similar things aligned.
+Vertical alignment can be completely turned off using B<-novalign>, a flag
+mainly intended for debugging. However, vertical alignment can be forced to
+stop and restart by selectively introducing blank lines. For example, a blank
+has been inserted in the following code to keep somewhat similar things
+aligned.
%option_range = (
'format' => [ 'tidy', 'html', 'user' ],
'square-bracket-tightness' => [ 0, 2 ],
);
+Vertical alignment is implemented by locally increasing an existing blank space
+to produce alignment with an adjacent line. It cannot occur if there is no
+blank space to increase. So if a particular space is removed by one of the
+existing controls then vertical alignment cannot occur. Likewise, if a space is
+added with one of the controls, then vertical alignment might occur.
+
+For example,
+
+ # perltidy -nwls='=>'
+ $data = $pkg->new(
+ PeerAddr=> join( ".", @port[ 0 .. 3 ] ),
+ PeerPort=> $port[4] * 256 + $port[5],
+ Proto=> 'tcp'
+ );
=head2 Other Controls
=over 4
-=item Deleting selected text
+=item B<Deleting selected text>
Perltidy can selectively delete comments and/or pod documentation. The
command B<-dac> or B<--delete-all-comments> will delete all comments
Two commands which remove comments (but not pod) are: B<-dbc> or
B<--delete-block-comments> and B<-dsc> or B<--delete-side-comments>.
-(Hanging side comments will be deleted with block comments here.)
+(Hanging side comments will be deleted with side comments here.)
The negatives of these commands also work, and are the defaults. When
block comments are deleted, any leading 'hash-bang' will be retained.
Also, if the B<-x> flag is used, any system commands before a leading
hash-bang will be retained (even if they are in the form of comments).
-=item Writing selected text to a file
+=item B<Writing selected text to a file>
When perltidy writes a formatted text file, it has the ability to also
send selected text to a file with a F<.TEE> extension. This text can
The commands which write comments (but not pod) are: B<-tbc> or
B<--tee-block-comments> and B<-tsc> or B<--tee-side-comments>.
-(Hanging side comments will be written with block comments here.)
+(Hanging side comments will be written with side comments here.)
The negatives of these commands also work, and are the defaults.
-=item Using a F<.perltidyrc> command file
+=item B<Using a F<.perltidyrc> command file>
If you use perltidy frequently, you probably won't be happy until you
create a F<.perltidyrc> file to avoid typing commonly-used parameters.
=back
-=item Creating a new abbreviation
+=item B<Creating a new abbreviation>
A special notation is available for use in a F<.perltidyrc> file
for creating an abbreviation for a group
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.
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-newline}
+
+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>
allow perltidy to parse interactive VMS scripts, but it should be used
for any script which is normally invoked with C<perl -x>.
-=item Making a file unreadable
+Please note: do not use this flag unless you are sure your script needs it.
+Parsing errors can occur if it does not have a hash-bang, or, for example, if
+the actual first hash-bang is in a here-doc. In that case a parsing error will
+occur because the tokenization will begin in the middle of the here-doc.
+
+=item B<Making a file unreadable>
The goal of perltidy is to improve the readability of files, but there
are two commands which have the opposite effect, B<--mangle> and
Another use for B<--mangle> is to combine it with B<-dac> to reduce
the file size of a perl script.
-=item Debugging
+=item B<Debugging>
The following flags are available for debugging:
during program development, when large numbers of files with varying sizes are
processed, because it can reduce virtual memory usage.
+B<--maximum-file-size-mb=n> or B<-maxfs=n> specifies the maximum file size in
+megabytes that perltidy will attempt to format. This parameter is provided to
+avoid causing system problems by accidentally attempting to format an extremely
+large data file. Most perl scripts are less than about 2 MB in size. The
+integer B<n> has a default value of 10, so perltidy will skip formatting files
+which have a size greater than 10 MB. The command to increase the limit to 20
+MB for example would be
+
+ perltidy -maxfs=20
+
+This only applies to files specified by filename on the command line.
+
+B<--maximum-level-errors=n> or B<-maxle=n> specifies the maximum number of
+indentation level errors are allowed before perltidy skips formatting and just
+outputs a file verbatim. The default is B<n=1>. This means that if the final
+indentation of a script differs from the starting indentation by more than 1
+levels, the file will be output verbatim. To avoid formatting if there are any
+indentation level errors use -maxle=0. To skip this check you can either set n
+equal to a large number, such as B<n=100>, or set B<n=-1>.
+
+For example, the following script has level error of 3 and will be output verbatim
+
+ Input and default output:
+ {{{
+
+
+ perltidy -maxle=100
+ {
+ {
+ {
+
+B<--maximum-unexpected-errors=n> or B<-maxue=n> specifies the maximum number of
+unexpected tokenization errors are allowed before formatting is skipped and a
+script is output verbatim. The intention is to avoid accidentally formatting
+a non-perl script, such as an html file for example. This check can be turned
+off by setting B<n=0>.
+
+A recommended value is B<n=3>. However, the default is B<n=0> (skip this check)
+to avoid causing problems with scripts which have extended syntaxes.
+
B<-DEBUG> will write a file with extension F<.DEBUG> for each input file
showing the tokenization of all lines of code.
-=item Working with MakeMaker, AutoLoader and SelfLoader
+=item B<Working with MakeMaker, AutoLoader and SelfLoader>
The first $VERSION line of a file which might be eval'd by MakeMaker
is passed through unchanged except for indentation.
code after seeing a __DATA__ line.
Use B<--nolook-for-selfloader>, or B<-nlsl>, to deactivate this feature.
-=item Working around problems with older version of Perl
+=item B<Working around problems with older version of Perl>
Perltidy contains a number of rules which help avoid known subtleties
and problems with older versions of perl, and these rules always
This may not be the right thing for some browser/language
combinations. Use --nohtml-entities or -nhent to prevent this.
-=item Style Sheets
+=item B<Style Sheets>
Style sheets make it very convenient to control and adjust the
appearance of html pages. The default behavior is to write a page of
use the B<-ss>, or B<--stylesheet>, flag. This is useful if the style
sheet could not be written for some reason, such as if the B<-pre> flag
was used. Thus, for example,
-
+
perltidy -html -ss >mystyle.css
will write a style sheet with the default properties to file
4.0 of Netscape Navigator and Internet Explorer) can display the
syntax-coloring of the html files.
-=item Controlling HTML properties
+=item B<Controlling HTML properties>
Note: It is usually more convenient to accept the default properties
and then edit the stylesheet which is produced. However, this section
The following list shows all short parameter names which allow a prefix
'n' to produce the negated form:
- D anl asc aws b bbb bbc bbs bl bli boc bok bol bot ce
- csc dac dbc dcsc ddf dln dnl dop dp dpro dsc dsm dsn dtt dwls
- dwrs dws f fll frm fs hsc html ibc icb icp iob isbc lal log
- lp lsl ohbr okw ola oll opr opt osbr otr ple pod pvl q
- sbc sbl schb scp scsb sct se sfp sfs skp sob sohb sop sosb sot
- ssc st sts syn t tac tbc toc tp tqw tsc w x bar kis
+ D anl asbl asc ast asu atnl aws b baa
+ baao bar bbao bbb bbc bbs bl bli boa boc
+ bok bol bom bos bot cblx ce conv cs csc
+ cscb cscw dac dbc dcbl dcsc ddf dln dnl dop
+ dp dpro dsc dsm dsn dtt dwls dwrs dws f
+ fll fpva frm fs fso gcs hbc hbcm hbco hbh
+ hbhh hbi hbj hbk hbm hbn hbp hbpd hbpu hbq
+ hbs hbsc hbv hbw hent hic hicm hico hih hihh
+ hii hij hik him hin hip hipd hipu hiq his
+ hisc hiv hiw hsc html ibc icb icp iob isbc
+ iscl kgb kgbd kgbi kis lal log lop lp lsl
+ mem nib ohbr okw ola olc oll olq opr opt
+ osbc osbr otr ple pod pvl q sac sbc sbl
+ scbb schb scp scsb sct se sfp sfs skp sob
+ sobb sohb sop sosb sot ssc st sts t tac
+ tbc toc tp tqw trp ts tsc tso vmll w
+ wn x xci xs
Equivalently, the prefix 'no' or 'no-' on the corresponding long names may be
used.
=over 4
-=item Parsing Limitations
+=item B<Parsing Limitations>
Perltidy should work properly on most perl scripts. It does a lot of
self-checking, but still, it is possible that an error could be
If you encounter a bug, please report it.
-=item What perltidy does not parse and format
+=item B<What perltidy does not parse and format>
Perltidy indents but does not reformat comments and C<qw> quotes.
Perltidy does not in any way modify the contents of here documents or
=over 4
-=item Temporary files
+=item B<Temporary files>
Under the -html option with the default --pod2html flag, a temporary file is
required to pass text to Pod::Html. Unix systems will try to use the POSIX
tmpnam() function. Otherwise the file F<perltidy.TMP> will be temporarily
created in the current working directory.
-=item Special files when standard input is used
+=item B<Special files when standard input is used>
When standard input is used, the log file, if saved, is F<perltidy.LOG>,
and any errors are written to F<perltidy.ERR> unless the B<-se> flag is
set. These are saved in the current working directory.
-=item Files overwritten
+=item B<Files overwritten>
The following file extensions are used by perltidy, and files with these
extensions may be overwritten or deleted: F<.ERR>, F<.LOG>, F<.TEE>,
and/or F<.tdy>, F<.html>, and F<.bak>, depending on the run type and
settings.
-=item Files extensions limitations
+=item B<Files extensions limitations>
Perltidy does not operate on files for which the run could produce a file with
a duplicated file extension. These extensions include F<.LOG>, F<.ERR>,
=head1 VERSION
-This man page documents perltidy version 20200110
+This man page documents perltidy version 20210717
=head1 BUG REPORTS
=head1 COPYRIGHT
-Copyright (c) 2000-2020 by Steve Hancock
+Copyright (c) 2000-2021 by Steve Hancock
=head1 LICENSE
projects / perltidy.git / blobdiff