[header] categories=Styles|Basic Options|Code Indentation Control|Whitespace Control|Comment Controls|Skip Selected Codesections|Line Break Control|Controlling List Formatting|Retaining or Ignoring Existing Line Breaks|Blank Line Control|Other Controls cfgFileParameterEnding=cr configFilename=perltidy.cfg fileTypes=*.pl|*.pm indenterFileName=perltidy indenterName=Perltidy (Perl) inputFileName=indentinput inputFileParameter= manual=http://perltidy.sourceforge.net/perltidy.html outputFileName=indentoutput outputFileParameter="-o=" parameterOrder=pio showHelpParameter=-h stringparaminquotes=false useCfgFileParameter="-pro=" version=1.74 2010/12/17 [Iterations] CallName="--iterations=" Category=1 Description="This flag causes perltidy to do n complete iterations. For most purposes the default of n=1 should be satisfactory. However n=2 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. The run time will be approximately proportional to n, and it should seldom be necessary to use a value greater than n=2." EditorType=numeric Enabled=false MaxVal=10 MinVal=1 ValueDefault=1 [Add newlines] Category=6 Description="
By default, perltidy will add line breaks when necessary to create continuations of long lines and to improve the script appearance. Use -nanl or --noadd-newlines to prevent any new line breaks.
This flag does not prevent perltidy from eliminating existing line breaks; see --freeze-newlines to completely prevent changes to line break points.
Setting -asc allows perltidy to add any missing optional semicolon at the end of a line which is followed by a closing curly brace on the next line. This is the default, and may be deactivated with -nasc or --noadd-semicolons.
Setting this option allows perltidy to add certain whitespace improve code readability. This is the default. If you do not want any whitespace added, but are willing to have some whitespace deleted, use -naws. (Use -fws to leave whitespace completely unchanged).
And finally, curly braces which contain blocks of code are controlled by the parameter -bbt=n or --block-brace-tightness=n as illustrated in the example below.
\n %bf = map { $_ => -M $_ } grep { /deb$/ } dirents '.'; # -bbt=0 (default)\n %bf = map { $_ => -M $_ } grep {/deb$/} dirents '.'; # -bbt=1\n %bf = map {$_ => -M $_} grep {/deb$/} dirents '.'; # -bbt=2
The -bbvt=n flag is just like the -vt=n flag but applies to opening code block braces.
\n -bbvt=0 break after opening block brace (default). \n -bbvt=1 do not break unless this would produce more than one \n step in indentation in a line.\n -bbvt=2 do not break after opening block brace.
It is necessary to also use either -bl or -bli for this to work, because, as with other vertical tightness controls, it is implemented by simply overwriting a line ending with an opening block brace with the subsequent line. For example:
\n # perltidy -bli -bbvt=0\n if ( open( FILE, "< $File" ) )\n {\n while ( $File = <FILE> )\n {\n $In .= $File;\n $count++;\n }\n close(FILE);\n }
\n # perltidy -bli -bbvt=1\n if ( open( FILE, "< $File" ) )\n { while ( $File = <FILE> )\n { $In .= $File;\n $count++;\n }\n close(FILE);\n }
By default this applies to blocks associated with keywords if, elsif, else, unless, for, foreach, sub, while, until, and also with a preceding label. This can be changed with the parameter -bbvtl=string, or --block-brace-vertical-tightness-list=string, where string is a space-separated list of block types. For more information on the possible values of this string, see Specifying Block Types
For example, if we want to just apply this style to if
, elsif
, and else
blocks, we could use perltidy -bli -bbvt=1 -bbvtl='if elsif else'
.
There is no vertical tightness control for closing block braces; with the exception of one-line blocks, they will normally remain on a separate line.
The flag -bli is the same as -bl but in addition it causes one unit of continuation indentation ( see -ci ) to be placed before an opening and closing block braces.
For example,
\n if ( $input_file eq '-' ) # -bli\n {\n important_function();\n }
By default, this extra indentation occurs for blocks of type:if, elsif, else, unless, for, foreach, sub, while, until, and also with a preceding label. The next item shows how to change this.
Use this parameter to change the types of block braces for which the -bli flag applies; see Specifying Block Types. For example, -blil='if elsif else' would apply it to only if/elsif/else
blocks.
Curly braces which do not contain code blocks are controlled by the parameter -bt=n or --brace-tightness=n.
\n $obj->{ $parsed_sql->{ 'table' }[0] }; # -bt=0\n $obj->{ $parsed_sql->{'table'}[0] }; # -bt=1 (default)\n $obj->{$parsed_sql->{'table'}[0]}; # -bt=2
The -vt=n and -vtc=n parameters apply to each type of container token. If desired, vertical tightness controls can be applied independently to each of the closing container token types.
In fact, the parameter -vt=n is actually just an abbreviation for -pvt=n -bvt=n sbvt=n, and likewise -vtc=n is an abbreviation for -pvtc=n -bvtc=n sbvtc=n.
" EditorType=numeric Enabled=false MaxVal=2 MinVal=0 ValueDefault=0 [Brace vertical tightness closing] CallName="--brace-vertical-tightness-closing=" Category=6 Description="The -vt=n and -vtc=n parameters apply to each type of container token. If desired, vertical tightness controls can be applied independently to each of the closing container token types.
In fact, the parameter -vt=n is actually just an abbreviation for -pvt=n -bvt=n sbvt=n, and likewise -vtc=n is an abbreviation for -pvtc=n -bvtc=n sbvtc=n.
" EditorType=numeric Enabled=false MaxVal=2 MinVal=0 ValueDefault=0 [Break after all operators] Category=6 Description="The -baao sets the default to be to break after all of the following operators:
\n % + - * / x != == >= <= =~ !~ < > | & \n = **= += *= &= <<= &&= -= /= |= >>= ||= //= .= %= ^= x=\n . : ? && || and or err xor
and the -bbao flag sets the default to break before all of these operators. These can be used to define an initial break preference which can be fine-tuned with the -wba and -wbb flags. For example, to break before all operators except an = one could use --bbao -wba='=' rather than listing every single perl operator except = on a -wbb flag.
The -baao sets the default to be to break after all of the following operators:
\n % + - * / x != == >= <= =~ !~ < > | & \n = **= += *= &= <<= &&= -= /= |= >>= ||= //= .= %= ^= x=\n . : ? && || and or err xor
and the -bbao flag sets the default to break before all of these operators. These can be used to define an initial break preference which can be fine-tuned with the -wba and -wbb flags. For example, to break before all operators except an = one could use --bbao -wba='=' rather than listing every single perl operator except = on a -wbb flag.
perl -c -T
to check syntax of input and output. (To change the flags passed to perl, see the next item, -pscf). The results are written to the .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 --warning-output flag is given.
The default is 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." EditorType=boolean Enabled=false TrueFalse=--check-syntax| ValueDefault=0 [Closing Side Comment Else Flag] CallName="--closing-side-comment-else-flag=" Category=4 Description="
The default, n=0, places the text of the opening if
statement after any terminal else
.
If n=2 is used, then each elsif
is also given the text of the opening if
statement. Also, an else
will include the text of a preceding elsif
statement. Note that this may result some long closing side comments.
If n=1 is used, the results will be the same as n=2 whenever the resulting line length is less than the maximum allowed.
where n
is the minimum number of lines that a block must have in order for a closing side comment to be added. The default value is n=6
. To illustrate:
\n # perltidy -csci=2 -csc\n sub message {\n if ( !defined( $_[0] ) ) {\n print("Hello, World\n");\n } ## end if ( !defined( $_[0] ))\n else {\n print( $_[0], "\n" );\n } ## end else [ if ( !defined( $_[0] ))\n } ## end sub message
Now the if
and else
blocks are commented. However, now this has become very cluttered.
where string
is a list of block types to be tagged with closing side comments. By default, all code block types preceded by a keyword or label (such as if
, sub
, and so on) will be tagged. The -cscl command changes the default list to be any selected block types; see Specifying Block Types. For example, the following command requests that only sub
's, labels, BEGIN
, and END
blocks be affected by any -csc or -dcsc operation:
\n -cscl="sub : BEGIN END"
The text appended to certain block types, such as an if
block, is whatever lies between the keyword introducing the block, such as if
, and the opening brace. Since this might be too much text for a side comment, there needs to be a limit, and that is the purpose of this parameter. The default value is n=20
, meaning that no additional tokens will be appended to this text after its length reaches 20 characters. Omitted text is indicated with ...
. (Tokens, including sub names, are never truncated, however, so actual lengths may exceed this). To illustrate, in the above example, the appended text of the first block is ( !defined( $_[0] )...
. The existing limit of n=20
caused this text to be truncated, as indicated by the ...
.
As discussed in the previous item, when the closing-side-comment-maximum-text limit is exceeded the comment text must be truncated. Older versions of perltidy terminated with three dots, and this can still be achieved with -ncscb:
\n perltidy -csc -ncscb\n } ## end foreach my $foo (sort { $b cmp $a ...
However this causes a problem with editors editors which cannot recognize comments or are not configured to do so because they cannot "bounce" around in the text correctly. The -cscb flag has been added to help them by appending appropriate balancing structure:
\n perltidy -csc -cscb\n } ## end foreach my $foo (sort { $b cmp $a ... })
The default is -cscb.
" EditorType=boolean TrueFalse=--closing-side-comments-balanced|-ncscb ValueDefault=1 [Closing Side Comment Prefix] CallName="--closing-side-comment-prefix=" Category=4 Description="where string is the prefix used before the name of the block type. The default prefix, shown above, is ## end
. This string will be added to closing side comments, and it will also be used to recognize them in order to update, delete, and format them. Any comment identified as a closing side comment will be placed just a single space to the right of its closing brace.
This parameter is intended to help make the initial transition to the use of closing side comments. It causes two things to happen if a closing side comment replaces an existing, different closing side comment: first, an error message will be issued, and second, the original side comment will be placed alone on a new specially marked comment line for later attention.
The intent is to avoid clobbering existing hand-written side comments which happen to match the pattern of closing side comments. This flag should only be needed on the first run with -csc.
A closing side comment is a special comment which perltidy can automatically create and place after the closing brace of a code block. They can be useful for code maintenance and debugging. The command -csc (or --closing-side-comments) adds or updates closing side comments. For example, here is a small code snippet
\n sub message {\n if ( !defined( $_[0] ) ) {\n print("Hello, World\n");\n }\n else {\n print( $_[0], "\n" );\n }\n }
And here is the result of processing with perltidy -csc
:
\n sub message {\n if ( !defined( $_[0] ) ) {\n print("Hello, World\n");\n }\n else {\n print( $_[0], "\n" );\n }\n } ## end sub message
A closing side comment was added for sub message
in this case, but not for the if
and else
blocks, because they were below the 6 line cutoff limit for adding closing side comments. This limit may be changed with the -csci command, described below.
The command -dcsc (or --delete-closing-side-comments) reverses this process and removes these comments.
Several commands are available to modify the behavior of these two basic commands, -csc and -dcsc:
)
, ]
, or a non-block }
. Such a line receives:\n -cti = 0 no extra indentation (default)\n -cti = 1 extra indentation such that the closing token\n aligns with its opening token.\n -cti = 2 one extra indentation level if the line looks like:\n ); or ]; or };\n -cti = 3 one extra indentation level always
The flags -cti=1 and -cti=2 work well with the -lp flag (previous section).
\n # perltidy -lp -cti=1\n @month_of_year = (\n 'Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun',\n 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'\n );
\n # perltidy -lp -cti=2\n @month_of_year = (\n 'Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun',\n 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'\n );
These flags are merely hints to the formatter and they may not always be followed. In particular, if -lp is not being used, the indentation forcti=1 is constrained to be no more than one indentation level.
If desired, this control can be applied independently to each of theclosing container token types. In fact, -cti=n is merely anabbreviation for -cpi=n -csbi=n -cbi=n, where: -cpi or --closing-paren-indentation controls )'s,-csbi or --closing-square-bracket-indentation controls ]'s, -cbi or --closing-brace-indentation controls non-block }'s." EditorType=numeric Enabled=false MaxVal=1000 MinVal=0 ValueDefault=0 [Continuation indentation] CallName="--continuation-indentation=" Category=2 Description="Continuation indentation is extra indentation spaces applied whena long line is broken. The default is n=2, illustrated here:
my $level = # -ci=2 ( $max_index_to_go >= 0 ) ? $levels_to_go[0] : $last_output_level;
The same example, with n=0, is a little harder to read:
my $level = # -ci=0 ( $max_index_to_go >= 0 ) ? $levels_to_go[0] : $last_output_level;
The value given to -ci is also used by some commands when a small space is required. Examples are commands for outdenting labels, -ola, and control keywords, -okw.
When default values are not used, it is suggested that the value n given with -ci=n be no more than about one-half of the number of spaces assigned to a full indentation level on the -i=n command." EditorType=numeric Enabled=false MaxVal=1000 MinVal=0 ValueDefault=2 [Cuddled else] Category=6 Description="
Enable the ``cuddled else'' style, in which else
and elsif
are follow immediately after the curly brace closing the previous block. The default is not to use cuddled elses, and is indicated with the flag -nce or --nocuddled-else. Here is a comparison of the alternatives:
\n if ($task) {\n yyy();\n } else { # -ce\n zzz();\n }
\n if ($task) {\n yyy();\n }\n else { # -nce (default)\n zzz();\n }
By default, perltidy first deletes all old line break locations, and then it looks for good break points to match the desired line length. Use -ndnl or --nodelete-old-newlines to force perltidy to retain all old line break points.
Setting this option allows perltidy to remove some old whitespace between characters, if necessary. This is the default. If you do not want any old whitespace removed, use -ndws or --nodelete-old-whitespace.
Setting -dsm allows perltidy to delete extra semicolons which are simply empty statements. This is the default, and may be deactivated with -ndsm or --nodelete-semicolons. (Such semicolons are not deleted, however, if they would promote a side comment to a block comment).