You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
1041 lines
104 KiB
1041 lines
104 KiB
2 years ago
|
[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="<html>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.</html>"
|
||
|
|
EditorType=numeric
|
||
|
|
Enabled=false
|
||
|
|
MaxVal=10
|
||
|
|
MinVal=1
|
||
|
|
ValueDefault=1
|
||
|
|
|
||
|
|
[Add newlines]
|
||
|
|
Category=6
|
||
|
|
Description="<html><dd><p>By default, perltidy will add line breaks when necessary to create continuations of long lines and to improve the script appearance. Use <strong>-nanl</strong> or <strong>--noadd-newlines</strong> to prevent any new line breaks.</p></dd><dd><p>This flag does not prevent perltidy from eliminating existing line breaks; see <strong>--freeze-newlines</strong> to completely prevent changes to line break points.</p></dd></html>"
|
||
|
|
EditorType=boolean
|
||
|
|
TrueFalse=-anl|-nanl
|
||
|
|
ValueDefault=0
|
||
|
|
|
||
|
|
[Add semicolons]
|
||
|
|
Category=3
|
||
|
|
Description="<html><dd><p>Setting <strong>-asc</strong> 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 <strong>-nasc</strong> or <strong>--noadd-semicolons</strong>.</p></dd></html>"
|
||
|
|
EditorType=boolean
|
||
|
|
TrueFalse=--add-semicolons|
|
||
|
|
ValueDefault=0
|
||
|
|
|
||
|
|
[Add whitespace]
|
||
|
|
Category=3
|
||
|
|
Description="<html><dd><p>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 <strong>-naws</strong>. (Use <strong>-fws</strong> to leave whitespace completely unchanged).</p></dd></html>"
|
||
|
|
EditorType=boolean
|
||
|
|
TrueFalse=--add-whitespace|
|
||
|
|
ValueDefault=0
|
||
|
|
|
||
|
|
[Block brace tightness]
|
||
|
|
CallName="--block-brace-tightness="
|
||
|
|
Category=3
|
||
|
|
Description="<html><p>And finally, curly braces which contain blocks of code are controlled by the parameter <strong>-bbt=n</strong> or <strong>--block-brace-tightness=n</strong> as illustrated in the example below.</p></dd><dd><pre>\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</pre></dd></html>"
|
||
|
|
EditorType=numeric
|
||
|
|
Enabled=false
|
||
|
|
MaxVal=2
|
||
|
|
MinVal=0
|
||
|
|
ValueDefault=1
|
||
|
|
|
||
|
|
[Block brace vertical tightness]
|
||
|
|
CallName="--block-brace-vertical-tightness="
|
||
|
|
Category=6
|
||
|
|
Description="<html><dd><p>The <strong>-bbvt=n</strong> flag is just like the <strong>-vt=n</strong> flag but applies to opening code block braces.</p></dd><dd><pre>\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.</pre></dd><dd><p>It is necessary to also use either <strong>-bl</strong> or <strong>-bli</strong> 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:</p></dd><dd><pre>\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 }</pre></dd><dd><pre>\n # perltidy -bli -bbvt=1\n if ( open( FILE, "< $File" ) )\n { while ( $File = <FILE> )\n { $In .= $File;\n $count++;\n }\n close(FILE);\n }</pre></dd><dd><p>By default this applies to blocks associated with keywords <strong>if</strong>, <strong>elsif</strong>, <strong>else</strong>, <strong>unless</strong>, <strong>for</strong>, <strong>foreach</strong>, <strong>sub</strong>, <strong>while</strong>, <strong>until</strong>, and also with a preceding label. This can be changed with the parameter <strong>-bbvtl=string</strong>, or <strong>--block-brace-vertical-tightness-list=string</strong>, where <strong>string</strong> is a space-separated list of block types. For more information on the possible values of this string, see <a href=#specifying_block_types>Specifying Block Types</a></p></dd><dd><p>For example, if we want to just apply this style to <code>if</code>, <code>elsif</code>, and <code>else</code> blocks, we could use <code>perltidy -bli -bbvt=1 -bbvtl='if elsif else'</code>.</p></dd><dd><p>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.</p></dd></html>"
|
||
|
|
EditorType=numeric
|
||
|
|
Enabled=false
|
||
|
|
MaxVal=2
|
||
|
|
MinVal=0
|
||
|
|
ValueDefault=0
|
||
|
|
|
||
|
|
[Brace left and indent]
|
||
|
|
Category=6
|
||
|
|
Description="<html><dd><p>The flag <strong>-bli</strong> is the same as <strong>-bl</strong> but in addition it causes one unit of continuation indentation ( see <strong>-ci</strong> ) to be placed before an opening and closing block braces.</p></dd><dd><p>For example,</p></dd><dd><pre>\n if ( $input_file eq '-' ) # -bli\n {\n important_function();\n }</pre></dd><dd><p>By default, this extra indentation occurs for blocks of type:<strong>if</strong>, <strong>elsif</strong>, <strong>else</strong>, <strong>unless</strong>, <strong>for</strong>, <strong>foreach</strong>, <strong>sub</strong>, <strong>while</strong>, <strong>until</strong>, and also with a preceding label. The next item shows how to change this.</p></dd></html>"
|
||
|
|
EditorType=boolean
|
||
|
|
TrueFalse=-bli|
|
||
|
|
ValueDefault=0
|
||
|
|
|
||
|
|
[Brace left and indent list]
|
||
|
|
CallName="--brace-left-and-indent-list="
|
||
|
|
Category=6
|
||
|
|
Description="<html><dd><p>Use this parameter to change the types of block braces for which the <strong>-bli</strong> flag applies; see <a href=#specifying_block_types>Specifying Block Types</a>. For example, <strong>-blil='if elsif else'</strong> would apply it to only <code>if/elsif/else</code> blocks.</p></dd></html>"
|
||
|
|
EditorType=string
|
||
|
|
Enabled=false
|
||
|
|
ValueDefault=
|
||
|
|
|
||
|
|
[Brace tightness]
|
||
|
|
CallName="--brace-tightness="
|
||
|
|
Category=3
|
||
|
|
Description="<html><p>Curly braces which do not contain code blocks are controlled by the parameter <strong>-bt=n</strong> or <strong>--brace-tightness=n</strong>.</p></dd><dd><pre>\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</pre></dd></html>"
|
||
|
|
EditorType=numeric
|
||
|
|
Enabled=false
|
||
|
|
MaxVal=2
|
||
|
|
MinVal=0
|
||
|
|
ValueDefault=1
|
||
|
|
|
||
|
|
[Brace vertical tightness]
|
||
|
|
CallName="--brace-vertical-tightness="
|
||
|
|
Category=6
|
||
|
|
Description="<html><p>The <strong>-vt=n</strong> and <strong>-vtc=n</strong> 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.</p><p>In fact, the parameter <strong>-vt=n</strong> is actually just an abbreviation for <strong>-pvt=n -bvt=n sbvt=n</strong>, and likewise <strong>-vtc=n</strong> is an abbreviation for <strong>-pvtc=n -bvtc=n sbvtc=n</strong>.</p></html>"
|
||
|
|
EditorType=numeric
|
||
|
|
Enabled=false
|
||
|
|
MaxVal=2
|
||
|
|
MinVal=0
|
||
|
|
ValueDefault=0
|
||
|
|
|
||
|
|
[Brace vertical tightness closing]
|
||
|
|
CallName="--brace-vertical-tightness-closing="
|
||
|
|
Category=6
|
||
|
|
Description="<html><p>The <strong>-vt=n</strong> and <strong>-vtc=n</strong> 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.</p><p>In fact, the parameter <strong>-vt=n</strong> is actually just an abbreviation for <strong>-pvt=n -bvt=n sbvt=n</strong>, and likewise <strong>-vtc=n</strong> is an abbreviation for <strong>-pvtc=n -bvtc=n sbvtc=n</strong>.</p></html>"
|
||
|
|
EditorType=numeric
|
||
|
|
Enabled=false
|
||
|
|
MaxVal=2
|
||
|
|
MinVal=0
|
||
|
|
ValueDefault=0
|
||
|
|
|
||
|
|
[Break after all operators]
|
||
|
|
Category=6
|
||
|
|
Description="<html><dd><p>The -baao sets the default to be to break after all of the following operators:</p></dd><dd><pre>\n % + - * / x != == >= <= =~ !~ < > | & \n = **= += *= &= <<= &&= -= /= |= >>= ||= //= .= %= ^= x=\n . : ? && || and or err xor</pre></dd><dd><p>and the <strong>-bbao</strong> 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 <strong>-wba</strong> and <strong>-wbb</strong> flags. For example, to break before all operators except an <strong>=</strong> one could use --bbao -wba='=' rather than listing every single perl operator except <strong>=</strong> on a -wbb flag.</p></dd></html>"
|
||
|
|
EditorType=boolean
|
||
|
|
TrueFalse=-baao|
|
||
|
|
ValueDefault=0
|
||
|
|
|
||
|
|
[Break before all operators]
|
||
|
|
Category=6
|
||
|
|
Description="<html><dd><p>The -baao sets the default to be to break after all of the following operators:</p></dd><dd><pre>\n % + - * / x != == >= <= =~ !~ < > | & \n = **= += *= &= <<= &&= -= /= |= >>= ||= //= .= %= ^= x=\n . : ? && || and or err xor</pre></dd><dd><p>and the <strong>-bbao</strong> 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 <strong>-wba</strong> and <strong>-wbb</strong> flags. For example, to break before all operators except an <strong>=</strong> one could use --bbao -wba='=' rather than listing every single perl operator except <strong>=</strong> on a -wbb flag.</p></dd></html>"
|
||
|
|
EditorType=boolean
|
||
|
|
TrueFalse=-bbao|
|
||
|
|
ValueDefault=0
|
||
|
|
|
||
|
|
[Check syntax]
|
||
|
|
Category=1
|
||
|
|
Description="<html>This flag causes perltidy to run <code>perl -c -T</code> to check syntax of input and output. (To change the flags passed to perl, see the next item, <strong>-pscf</strong>). The results are written to the <em>.LOG</em> 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''.</p></dd><dd><p>If perl reports errors in the input file, they will not be reported in the error output unless the <strong>--warning-output</strong> flag is given.</p></dd><dd><p>The default is <strong>not</strong> 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.</html>"
|
||
|
|
EditorType=boolean
|
||
|
|
Enabled=false
|
||
|
|
TrueFalse=--check-syntax|
|
||
|
|
ValueDefault=0
|
||
|
|
|
||
|
|
[Closing Side Comment Else Flag]
|
||
|
|
CallName="--closing-side-comment-else-flag="
|
||
|
|
Category=4
|
||
|
|
Description="<html><dd><p>The default, <strong>n=0</strong>, places the text of the opening <code>if</code> statement after any terminal <code>else</code>.</p></dd><dd><p>If <strong>n=2</strong> is used, then each <code>elsif</code> is also given the text of the opening <code>if</code> statement. Also, an <code>else</code> will include the text of a preceding <code>elsif</code> statement. Note that this may result some long closing side comments.</p></dd><dd><p>If <strong>n=1</strong> is used, the results will be the same as <strong>n=2</strong> whenever the resulting line length is less than the maximum allowed.</p></dd></html>"
|
||
|
|
EditorType=numeric
|
||
|
|
Enabled=false
|
||
|
|
MaxVal=1000
|
||
|
|
MinVal=0
|
||
|
|
ValueDefault=0
|
||
|
|
|
||
|
|
[Closing Side Comment Interval]
|
||
|
|
CallName="--closing-side-comment-interval="
|
||
|
|
Category=4
|
||
|
|
Description="<html><dd><p>where <code>n</code> 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 <code>n=6</code>. To illustrate:</p></dd><dd><pre>\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</pre></dd><dd><p>Now the <code>if</code> and <code>else</code> blocks are commented. However, now this has become very cluttered.</p></dd></html>"
|
||
|
|
EditorType=numeric
|
||
|
|
Enabled=false
|
||
|
|
MaxVal=1000
|
||
|
|
MinVal=0
|
||
|
|
ValueDefault=6
|
||
|
|
|
||
|
|
[Closing Side Comment List]
|
||
|
|
CallName="--closing-side-comment-list="
|
||
|
|
Category=4
|
||
|
|
Description="<html><dd><p>where <code>string</code> 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 <code>if</code>, <code>sub</code>, and so on) will be tagged. The <strong>-cscl</strong> command changes the default list to be any selected block types; see <a href=#specifying_block_types>Specifying Block Types</a>. For example, the following command requests that only <code>sub</code>'s, labels, <code>BEGIN</code>, and <code>END</code> blocks be affected by any <strong>-csc</strong> or <strong>-dcsc</strong> operation:</p></dd><dd><pre>\n -cscl="sub : BEGIN END"</pre></dd></html>"
|
||
|
|
EditorType=string
|
||
|
|
Enabled=false
|
||
|
|
ValueDefault=
|
||
|
|
|
||
|
|
[Closing Side Comment Maximum Text]
|
||
|
|
CallName="--closing-side-comment-maximum-text="
|
||
|
|
Category=4
|
||
|
|
Description="<html><dd><p>The text appended to certain block types, such as an <code>if</code> block, is whatever lies between the keyword introducing the block, such as <code>if</code>, 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 <code>n=20</code>, meaning that no additional tokens will be appended to this text after its length reaches 20 characters. Omitted text is indicated with <code>...</code>. (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 <code> ( !defined( $_[0] )...</code>. The existing limit of <code>n=20</code> caused this text to be truncated, as indicated by the <code>...</code>.</p></dd></html>"
|
||
|
|
EditorType=numeric
|
||
|
|
Enabled=false
|
||
|
|
MaxVal=1000
|
||
|
|
MinVal=0
|
||
|
|
ValueDefault=20
|
||
|
|
|
||
|
|
[Closing Side Comments Balanced]
|
||
|
|
Category=4
|
||
|
|
Description="<html><p>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:</p><pre>\n perltidy -csc -ncscb\n } ## end foreach my $foo (sort { $b cmp $a ...</pre><p>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 <strong>-cscb</strong> flag has been added to help them by appending appropriate balancing structure:</p><pre>\n perltidy -csc -cscb\n } ## end foreach my $foo (sort { $b cmp $a ... })</pre><p>The default is <strong>-cscb</strong>.</p></html>"
|
||
|
|
EditorType=boolean
|
||
|
|
TrueFalse=--closing-side-comments-balanced|-ncscb
|
||
|
|
ValueDefault=1
|
||
|
|
|
||
|
|
[Closing Side Comment Prefix]
|
||
|
|
CallName="--closing-side-comment-prefix="
|
||
|
|
Category=4
|
||
|
|
Description="<html><dd><p>where string is the prefix used before the name of the block type. The default prefix, shown above, is <code>## end</code>. 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.</p></dd></html>"
|
||
|
|
EditorType=string
|
||
|
|
Enabled=false
|
||
|
|
ValueDefault=## end
|
||
|
|
|
||
|
|
[Closing Side Comment Warnings]
|
||
|
|
Category=4
|
||
|
|
Description="<html><dd><p>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.</p></dd><dd><p>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 <strong>-csc</strong>.</p></dd></html>"
|
||
|
|
EditorType=boolean
|
||
|
|
TrueFalse=--closing-side-comment-warnings|
|
||
|
|
ValueDefault=0
|
||
|
|
|
||
|
|
[Closing Side Comments]
|
||
|
|
Category=4
|
||
|
|
Choices=-csc|-dcsc
|
||
|
|
ChoicesReadable=Add Closing Side Comments|Delete Closing Side Comments
|
||
|
|
Description="<html><dd><p>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 <strong>-csc</strong> (or <strong>--closing-side-comments</strong>) adds or updates closing side comments. For example, here is a small code snippet</p></dd><dd><pre>\n sub message {\n if ( !defined( $_[0] ) ) {\n print("Hello, World\n");\n }\n else {\n print( $_[0], "\n" );\n }\n }</pre></dd><dd><p>And here is the result of processing with <code>perltidy -csc</code>:</p></dd><dd><pre>\n sub message {\n if ( !defined( $_[0] ) ) {\n print("Hello, World\n");\n }\n else {\n print( $_[0], "\n" );\n }\n } ## end sub message</pre></dd><dd><p>A closing side comment was added for <code>sub message</code> in this case, but not for the <code>if</code> and <code>else</code> blocks, because they were below the 6 line cutoff limit for adding closing side comments. This limit may be changed with the <strong>-csci</strong> command, described below.</p></dd><dd><p>The command <strong>-dcsc</strong> (or <strong>--delete-closing-side-comments</strong>) reverses this process and removes these comments.</p></dd><dd><p>Several commands are available to modify the behavior of these two basic commands, <strong>-csc</strong> and <strong>-dcsc</strong>:</p></dd></html>"
|
||
|
|
EditorType=multiple
|
||
|
|
Enabled=false
|
||
|
|
ValueDefault=0
|
||
|
|
|
||
|
|
[Closing token indentation]
|
||
|
|
CallName="--closing-token-indentation="
|
||
|
|
Category=2
|
||
|
|
Description="<html>The <strong>-cti=n</strong> flag controls the indentation of a line beginning with a <code>)</code>, <code>]</code>, or a non-block <code>}</code>. Such a line receives:</p></dd><dd><pre>\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</pre></dd><dd><p>The flags <strong>-cti=1</strong> and <strong>-cti=2</strong> work well with the <strong>-lp</strong> flag (previous section).</p></dd><dd><pre>\n # perltidy -lp -cti=1\n @month_of_year = (\n 'Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun',\n 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'\n );</pre></dd><dd><pre>\n # perltidy -lp -cti=2\n @month_of_year = (\n 'Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun',\n 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'\n );</pre></dd><dd><p>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 for<strong>cti=1</strong> is constrained to be no more than one indentation level.</p></dd><dd><p>If desired, this control can be applied independently to each of theclosing container token types. In fact, <strong>-cti=n</strong> is merely anabbreviation for <strong>-cpi=n -csbi=n -cbi=n</strong>, where: <strong>-cpi</strong> or <strong>--closing-paren-indentation</strong> controls <strong>)</strong>'s,<strong>-csbi</strong> or <strong>--closing-square-bracket-indentation</strong> controls <strong>]</strong>'s, <strong>-cbi</strong> or <strong>--closing-brace-indentation</strong> controls non-block <strong>}</strong>'s.</html>"
|
||
|
|
EditorType=numeric
|
||
|
|
Enabled=false
|
||
|
|
MaxVal=1000
|
||
|
|
MinVal=0
|
||
|
|
ValueDefault=0
|
||
|
|
|
||
|
|
[Continuation indentation]
|
||
|
|
CallName="--continuation-indentation="
|
||
|
|
Category=2
|
||
|
|
Description="<html>Continuation indentation is extra indentation spaces applied whena long line is broken. The default is n=2, illustrated here:</p></dd><dd><pre> my $level = # -ci=2 ( $max_index_to_go >= 0 ) ? $levels_to_go[0] : $last_output_level;</pre></dd><dd><p>The same example, with n=0, is a little harder to read:</p></dd><dd><pre> my $level = # -ci=0 ( $max_index_to_go >= 0 ) ? $levels_to_go[0] : $last_output_level;</pre></dd><dd><p>The value given to <strong>-ci</strong> is also used by some commands when a small space is required. Examples are commands for outdenting labels, <strong>-ola</strong>, and control keywords, <strong>-okw</strong>.</p></dd><dd><p>When default values are not used, it is suggested that the value <strong>n</strong> given with <strong>-ci=n</strong> be no more than about one-half of the number of spaces assigned to a full indentation level on the <strong>-i=n</strong> command.</html>"
|
||
|
|
EditorType=numeric
|
||
|
|
Enabled=false
|
||
|
|
MaxVal=1000
|
||
|
|
MinVal=0
|
||
|
|
ValueDefault=2
|
||
|
|
|
||
|
|
[Cuddled else]
|
||
|
|
Category=6
|
||
|
|
Description="<html><dd><p>Enable the ``cuddled else'' style, in which <code>else</code> and <code>elsif</code> 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 <strong>-nce</strong> or <strong>--nocuddled-else</strong>. Here is a comparison of the alternatives:</p></dd><dd><pre>\n if ($task) {\n yyy();\n } else { # -ce\n zzz();\n }</pre></dd><dd><pre>\n if ($task) {\n yyy();\n }\n else { # -nce (default)\n zzz();\n }</pre></dd></html>"
|
||
|
|
EditorType=boolean
|
||
|
|
TrueFalse=-ce|-nce
|
||
|
|
ValueDefault=0
|
||
|
|
|
||
|
|
[Delete old newlines]
|
||
|
|
Category=6
|
||
|
|
Description="<html><dd><p>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 <strong>-ndnl</strong> or <strong>--nodelete-old-newlines</strong> to force perltidy to retain all old line break points.</p></dd></html>"
|
||
|
|
EditorType=boolean
|
||
|
|
TrueFalse=-dnl|-ndnl
|
||
|
|
ValueDefault=0
|
||
|
|
|
||
|
|
[Delete old whitespace]
|
||
|
|
Category=3
|
||
|
|
Description="<html><dd><p>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 <strong>-ndws</strong> or <strong>--nodelete-old-whitespace</strong>.</p></dd></html>"
|
||
|
|
EditorType=boolean
|
||
|
|
TrueFalse=--delete-old-whitespace|
|
||
|
|
ValueDefault=0
|
||
|
|
|
||
|
|
[Delete semicolons]
|
||
|
|
Category=3
|
||
|
|
Description="<html><dd><p>Setting <strong>-dsm</strong> allows perltidy to delete extra semicolons which are simply empty statements. This is the default, and may be deactivated with <strong>-ndsm</strong> or <strong>--nodelete-semicolons</strong>. (Such semicolons are not deleted, however, if they would promote a side comment to a block comment).</p></dd></html>"
|
||
|
|
EditorType=boolean
|
||
|
|
TrueFalse=--delete-semicolons|
|
||
|
|
ValueDefault=0
|
||
|
|
|
||
|
|
[Entab leading whitespace]
|
||
|
|
CallName="--entab-leading-whitespace="
|
||
|
|
Category=1
|
||
|
|
Description="This flag causes each <strong>n</strong> initial space characters to be replaced by one tab character. Note that the integer <strong>n</strong> is completely independent of the integer specified for indentation parameter, <strong>-i=n</strong>.</html>"
|
||
|
|
EditorType=numeric
|
||
|
|
Enabled=false
|
||
|
|
MaxVal=1000
|
||
|
|
MinVal=0
|
||
|
|
ValueDefault=4
|
||
|
|
|
||
|
|
[Feeze newlines]
|
||
|
|
Category=6
|
||
|
|
Description="<html><dd><p>If you do not want any changes to the line breaks in your script, set <strong>-fnl</strong>, and they will remain fixed, and the rest of the commands in this section and sections <a href=#controlling_list_formatting>Controlling List Formatting</a>, <a href=#retaining_or_ignoring_existing_line_breaks>Retaining or Ignoring Existing Line Breaks</a>, and <a href=#blank_line_control>Blank Line Control</a> will be ignored. You may want to use <strong>-noll</strong> with this.</p></dd></html>"
|
||
|
|
EditorType=boolean
|
||
|
|
TrueFalse=-fnl|
|
||
|
|
ValueDefault=0
|
||
|
|
|
||
|
|
[Fixed position side comment]
|
||
|
|
CallName="--fixed-position-side-comment="
|
||
|
|
Category=4
|
||
|
|
Description="<html><dd><p>This parameter tells perltidy to line up side comments in column number <strong>n</strong> whenever possible. The default, n=0, is not do do this.</p></dd></html>"
|
||
|
|
EditorType=numeric
|
||
|
|
Enabled=false
|
||
|
|
MaxVal=1000
|
||
|
|
MinVal=0
|
||
|
|
ValueDefault=0
|
||
|
|
|
||
|
|
[Format skipping]
|
||
|
|
Category=5
|
||
|
|
Description="<html><p>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 <strong>--noformat-skipping</strong> or <strong>-nfs</strong> 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.</p><dl><dt><strong><a name=item__2dfs_2c__2d_2dformat_2dskipping><strong>-fs</strong>, <strong>--format-skipping</strong></a></strong><dd><p>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</p></dd><dd><pre>\n #<<< do not let perltidy touch this\n my @list = (1,\n 1, 1,\n 1, 2, 1,\n 1, 3, 3, 1,\n 1, 4, 6, 4, 1,);\n #>>></pre></dd><dd><p>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 <em>.LOG</em> file. Use <strong>-nfs</strong> to disable this feature.</p></dd></html>"
|
||
|
|
EditorType=boolean
|
||
|
|
TrueFalse=-fs|-nfs
|
||
|
|
ValueDefault=1
|
||
|
|
|
||
|
|
[Format skipping begin]
|
||
|
|
CallName="--format-skipping-begin="
|
||
|
|
Category=5
|
||
|
|
Description="<html><dd><p>The <strong>-fsb=string</strong> 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 the command shell of your system. It is actually the leading text of a pattern that is constructed by appending a '', so you must also include backslashes for characters to be taken literally rather than as patterns.</p></dd><dd><p>Some examples show how example strings become patterns:</p></dd><dd><pre>\n -fsb='#' becomes /^#/ which matches #{{{ but not #{{{{\n -fsb='#' becomes /^#/ which matches #** but not #***\n -fsb='#{2,}' becomes /^#{2,}/ which matches #** and #*****</pre></dd></html>"
|
||
|
|
EditorType=string
|
||
|
|
Enabled=false
|
||
|
|
ValueDefault=#<<<
|
||
|
|
|
||
|
|
[Format skipping end]
|
||
|
|
CallName="--format-skipping-end="
|
||
|
|
Category=5
|
||
|
|
Description="<html><dd><p>The <strong>-fsb=string</strong> is the corresponding parameter used to change the ending marker for format skipping. The default is equivalent to -fse='#<<<'.</p></dd></html>"
|
||
|
|
EditorType=string
|
||
|
|
Enabled=false
|
||
|
|
ValueDefault=#<<<
|
||
|
|
|
||
|
|
[Freeze whitespace]
|
||
|
|
Category=3
|
||
|
|
Description="<html>This flag causes your original whitespace to remain unchanged, and causes the rest of the whitespace commands in this section, the Code Indentation section, and the Comment Control section to be ignored.</html>"
|
||
|
|
EditorType=boolean
|
||
|
|
TrueFalse=--freeze-whitespace|
|
||
|
|
ValueDefault=0
|
||
|
|
|
||
|
|
[Gnu style]
|
||
|
|
Category=0
|
||
|
|
Description="<html><dd><p><strong>-gnu</strong> gives an approximation to the GNU Coding Standards (which do not apply to perl) as they are sometimes implemented. At present, this style overrides the default style with the following parameters:</p></dd><dd><pre>\n -lp -bl -noll -pt=2 -bt=2 -sbt=2 -icp</pre></dd></html>"
|
||
|
|
EditorType=boolean
|
||
|
|
Enabled=false
|
||
|
|
TrueFalse=--gnu-style|
|
||
|
|
ValueDefault=0
|
||
|
|
|
||
|
|
[Hanging side comments]
|
||
|
|
Category=4
|
||
|
|
Description="<html><dd><p>By default, perltidy tries to identify and align ``hanging side comments'', which are something like this:</p></dd><dd><pre>\n my $IGNORE = 0; # This is a side comment\n # This is a hanging side comment\n # And so is this</pre></dd><dd><p>A comment is considered to be a hanging side comment if (1) it immediately follows a line with a side comment, or another hanging side comment, and (2) there is some leading whitespace on the line. To deactivate this feature, use <strong>-nhsc</strong> or <strong>--nohanging-side-comments</strong>. If block comments are preceded by a blank line, or have no leading whitespace, they will not be mistaken as hanging side comments.</p></dd></html>"
|
||
|
|
EditorType=boolean
|
||
|
|
TrueFalse=-hsc|-nhsc
|
||
|
|
ValueDefault=0
|
||
|
|
|
||
|
|
[Indent block comments]
|
||
|
|
Category=4
|
||
|
|
Description="<html><p>Block comments normally look best when they are indented to the same level as the code which follows them. This is the default behavior, but you may use <strong>-nibc</strong> to keep block comments left-justified. Here is an example:</p></dd><dd><pre>\n # this comment is indented (-ibc, default)\n if ($task) { yyy(); }</pre></dd><dd><p>The alternative is <strong>-nibc</strong>:</p></dd><dd><pre>\n # this comment is not indented (-nibc)\n if ($task) { yyy(); }</pre></dd><dd><p>See also the next item, <strong>-isbc</strong>, as well as <strong>-sbc</strong>, for other ways to have some indented and some outdented block comments.</p></dd></html>"
|
||
|
|
EditorType=boolean
|
||
|
|
TrueFalse=-ibc|-nibc
|
||
|
|
ValueDefault=1
|
||
|
|
|
||
|
|
[Indent closing brace]
|
||
|
|
Category=2
|
||
|
|
Description="<html>The <strong>-icb</strong> option gives one extra level of indentation to a brace which terminates a code block . For example,</p></dd><dd><pre>\n if ($task) {\n yyy();\n } # -icb\n else {\n zzz();\n }</pre></dd><dd><p>The default is not to do this, indicated by <strong>-nicb</strong>.</html>"
|
||
|
|
EditorType=boolean
|
||
|
|
TrueFalse=--indent-closing-brace|
|
||
|
|
ValueDefault=0
|
||
|
|
|
||
|
|
[Indent closing paren]
|
||
|
|
Category=2
|
||
|
|
Description="<html>The <strong>-icp</strong> flag is equivalent to<strong>-cti=2</strong>, described in the previous section. The <strong>-nicp</strong> flag is equivalent <strong>-cti=0</strong>. They are included for backwards compatability.</html>"
|
||
|
|
EditorType=boolean
|
||
|
|
TrueFalse=--indent-closing-paren|
|
||
|
|
ValueDefault=0
|
||
|
|
|
||
|
|
[Indent columns]
|
||
|
|
CallName="--indent-columns="
|
||
|
|
Category=1
|
||
|
|
Description="<html>Use n columns per indentation level (default n=4).</html>"
|
||
|
|
EditorType=numeric
|
||
|
|
Enabled=false
|
||
|
|
MaxVal=1000
|
||
|
|
MinVal=0
|
||
|
|
ValueDefault=4
|
||
|
|
|
||
|
|
[Indent only]
|
||
|
|
Category=1
|
||
|
|
Description="<html>This flag is used to deactivate all formatting and line break changes. When it is in effect, the only change to the script will be indentation. And any flags controlling whitespace and newlines will be ignored. You might want to use this if you are perfectly happy with your whitespace 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 useful when perltidy is merely being used to help find a brace error in a large script).</p></dd><dd><p>Setting this flag is equivalent to setting <strong>--freeze-newlines</strong> and<strong>--freeze-whitespace</strong>.</html>"
|
||
|
|
EditorType=boolean
|
||
|
|
Enabled=false
|
||
|
|
TrueFalse=--indent-only|
|
||
|
|
ValueDefault=0
|
||
|
|
|
||
|
|
[Indent spaced block comments]
|
||
|
|
Category=4
|
||
|
|
Description="<html><dd><p>If there is no leading space on the line, then the comment will not be indented, and otherwise it may be.</p></dd><dd><p>If both <strong>-ibc</strong> and <strong>-isbc</strong> are set, then <strong>-isbc</strong> takes priority.</p></dd></html>"
|
||
|
|
EditorType=boolean
|
||
|
|
TrueFalse=-isbc|
|
||
|
|
ValueDefault=0
|
||
|
|
|
||
|
|
[List indentation]
|
||
|
|
Category=2
|
||
|
|
Description="<html>By default, perltidy indents lists with 4 spaces, or whatever value is specified with <strong>-i=n</strong>. Here is a small list formatted in this way:</p></dd><dd><pre>\n # perltidy (default)\n @month_of_year = (\n 'Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun',\n 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'\n );</pre></dd><dd><p>Use the <strong>-lp</strong> flag to add extra indentation to cause the data to begin past the opening parentheses of a sub call or list, or opening square bracket of an anonymous array, or opening curly brace of an anonymous hash. With this option, the above list would become:</p></dd><dd><pre>\n # perltidy -lp\n @month_of_year = (\n 'Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun',\n 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'\n );</pre></dd><dd><p>If the available line length (see <strong>-l=n</strong> ) does not permit this much space, perltidy will use less. For alternate placement of the closing paren, see the next section.</p></dd><dd><p>This option has no effect on code BLOCKS, such as if/then/else blocks, which always use whatever is specified with <strong>-i=n</strong>. 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.</p></dd><dd><p>Note: The <strong>-lp</strong> option may not be used together with the <strong>-t</strong> tabs option. It may, however, be used with the <strong>-et=n</strong> tab method.</p></dd><dd><p>In addition, any parameter which significantly restricts the ability of perltidy to choose newlines will conflict with <strong>-lp</strong> and will cause <strong>-lp</strong> to be deactivated. These include <strong>-io</strong>, <strong>-fnl</strong>, <strong>-nanl</strong>, and <strong>-ndnl</strong>. The reason is that the <strong>-lp</strong> indentation style can require the careful coordination of an arbitrary number of break points in hierarchical lists, and these flags may prevent that.</html>"
|
||
|
|
EditorType=boolean
|
||
|
|
TrueFalse=--line-up-parentheses|
|
||
|
|
ValueDefault=0
|
||
|
|
|
||
|
|
[Maximum line length]
|
||
|
|
CallName="--maximum-line-length="
|
||
|
|
Category=1
|
||
|
|
Description="<html>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 <strong>-l=0</strong> is equivalent to setting <strong>-l=(a large number)</strong>.</html>"
|
||
|
|
EditorType=numeric
|
||
|
|
Enabled=false
|
||
|
|
MaxVal=1000
|
||
|
|
MinVal=0
|
||
|
|
ValueDefault=80
|
||
|
|
|
||
|
|
[Minimum space to comment]
|
||
|
|
CallName="--minimum-space-to-comment="
|
||
|
|
Category=4
|
||
|
|
Description="<html><dd><p>Side comments look best when lined up several spaces to the right of code. Perltidy will try to keep comments at least n spaces to the right. The default is n=4 spaces.</p></dd></html>"
|
||
|
|
EditorType=numeric
|
||
|
|
Enabled=false
|
||
|
|
MaxVal=1000
|
||
|
|
MinVal=0
|
||
|
|
ValueDefault=4
|
||
|
|
|
||
|
|
[Nospace after keyword]
|
||
|
|
CallName="--nospace-after-keyword="
|
||
|
|
Category=3
|
||
|
|
Description="<html><dd><p>When an opening paren follows a Perl keyword, no space is introduced after the keyword, unless it is (by default) one of these:</p></dd><dd><pre>\n my local our and or eq ne if else elsif until unless \n while for foreach return switch case given when</pre></dd><dd><p>These defaults can be modified with two commands:</p></dd><dd><p><strong>-sak=s</strong> or <strong>--space-after-keyword=s</strong> adds keywords.</p></dd><dd><p><strong>-nsak=s</strong> or <strong>--nospace-after-keyword=s</strong> removes keywords.</p></dd><dd><p>where <strong>s</strong> is a list of keywords (in quotes if necessary). For example,</p></dd><dd><pre>\n my ( $a, $b, $c ) = @_; # default\n my( $a, $b, $c ) = @_; # -nsak="my local our"</pre></dd></html>"
|
||
|
|
EditorType=string
|
||
|
|
Enabled=false
|
||
|
|
ValueDefault=
|
||
|
|
|
||
|
|
[Nowant left space]
|
||
|
|
CallName="--nowant-left-space="
|
||
|
|
Category=3
|
||
|
|
Description="<html><dd><p>For those who want more detailed control over the whitespace around tokens, there are four parameters which can directly modify the default whitespace rules built into perltidy for any token. They are:</p></dd><dd><p><strong>-wls=s</strong> or <strong>--want-left-space=s</strong>,</p></dd><dd><p><strong>-nwls=s</strong> or <strong>--nowant-left-space=s</strong>,</p></dd><dd><p><strong>-wrs=s</strong> or <strong>--want-right-space=s</strong>,</p></dd><dd><p><strong>-nwrs=s</strong> or <strong>--nowant-right-space=s</strong>.</p></dd><dd><p>These parameters are each followed by a quoted string, <strong>s</strong>, containing a list of token types. 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.</p></dd><dd><p>To illustrate how these are used, suppose it is desired that there be no space on either side of the token types <strong>= + - / *</strong>. The following two parameters would specify this desire:</p></dd><dd><pre>\n -nwls="= + - / *" -nwrs="= + - / *"</pre></dd><dd><p>(Note that the token types are in quotes, and that they are separated by spaces). With these modified whitespace rules, the following line of math:</p></dd><dd><pre>\n $root = -$b + sqrt( $b * $b - 4. * $a * $c ) / ( 2. * $a );</pre></dd><dd><p>becomes this:</p></dd><dd><pre>\n $root=-$b+sqrt( $b*$b-4.*$a*$c )/( 2.*$a );</pre></dd><dd><p>These parameters should be considered to be hints to perltidy rather than fixed rules, because perltidy must try to resolve conflicts that arise between them and all of the other rules that it uses. One conflict that can arise is if, between two tokens, the left token wants a space and the right one doesn't. In this case, the token not wanting a space takes priority.</p></dd><dd><p>It is necessary to have a list of all token types in order to create this type of input. Such a list can be obtained by the command <strong>--dump-token-types</strong>. Also try the <strong>-D</strong> flag on a short snippet of code and look at the .DEBUG file to see the tokenization.</p></dd><dd><p><strong>WARNING</strong> Be sure to put these tokens in quotes to avoid having them misinterpreted by your command shell.</p></dd></html>"
|
||
|
|
EditorType=string
|
||
|
|
Enabled=false
|
||
|
|
ValueDefault=
|
||
|
|
|
||
|
|
[Nowant right space]
|
||
|
|
CallName="--nowant-right-space="
|
||
|
|
Category=3
|
||
|
|
Description="<html><dd><p>For those who want more detailed control over the whitespace around tokens, there are four parameters which can directly modify the default whitespace rules built into perltidy for any token. They are:</p></dd><dd><p><strong>-wls=s</strong> or <strong>--want-left-space=s</strong>,</p></dd><dd><p><strong>-nwls=s</strong> or <strong>--nowant-left-space=s</strong>,</p></dd><dd><p><strong>-wrs=s</strong> or <strong>--want-right-space=s</strong>,</p></dd><dd><p><strong>-nwrs=s</strong> or <strong>--nowant-right-space=s</strong>.</p></dd><dd><p>These parameters are each followed by a quoted string, <strong>s</strong>, containing a list of token types. 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.</p></dd><dd><p>To illustrate how these are used, suppose it is desired that there be no space on either side of the token types <strong>= + - / *</strong>. The following two parameters would specify this desire:</p></dd><dd><pre>\n -nwls="= + - / *" -nwrs="= + - / *"</pre></dd><dd><p>(Note that the token types are in quotes, and that they are separated by spaces). With these modified whitespace rules, the following line of math:</p></dd><dd><pre>\n $root = -$b + sqrt( $b * $b - 4. * $a * $c ) / ( 2. * $a );</pre></dd><dd><p>becomes this:</p></dd><dd><pre>\n $root=-$b+sqrt( $b*$b-4.*$a*$c )/( 2.*$a );</pre></dd><dd><p>These parameters should be considered to be hints to perltidy rather than fixed rules, because perltidy must try to resolve conflicts that arise between them and all of the other rules that it uses. One conflict that can arise is if, between two tokens, the left token wants a space and the right one doesn't. In this case, the token not wanting a space takes priority.</p></dd><dd><p>It is necessary to have a list of all token types in order to create this type of input. Such a list can be obtained by the command <strong>--dump-token-types</strong>. Also try the <strong>-D</strong> flag on a short snippet of code and look at the .DEBUG file to see the tokenization.</p></dd><dd><p><strong>WARNING</strong> Be sure to put these tokens in quotes to avoid having them misinterpreted by your command shell.</p></dd></html>"
|
||
|
|
EditorType=string
|
||
|
|
Enabled=false
|
||
|
|
ValueDefault=
|
||
|
|
|
||
|
|
[Opening brace always on right]
|
||
|
|
Category=6
|
||
|
|
Description="<html><dd><p>The default style, <strong>-nbl</strong> places the opening code block brace on a new line if it does not fit on the same line as the opening keyword, like this:</p></dd><dd><pre>\n if ( $bigwasteofspace1 && $bigwasteofspace2\n || $bigwasteofspace3 && $bigwasteofspace4 )\n {\n big_waste_of_time();\n }</pre></dd><dd><p>To force the opening brace to always be on the right, use the <strong>-bar</strong> flag. In this case, the above example becomes</p></dd><dd><pre>\n if ( $bigwasteofspace1 && $bigwasteofspace2\n || $bigwasteofspace3 && $bigwasteofspace4 ) {\n big_waste_of_time();\n }</pre></dd><dd><p>A conflict occurs if both <strong>-bl</strong> and <strong>-bar</strong> are specified.</p></dd></html>"
|
||
|
|
EditorType=boolean
|
||
|
|
TrueFalse=-bar|
|
||
|
|
ValueDefault=0
|
||
|
|
|
||
|
|
[Opening brace on new line]
|
||
|
|
Category=6
|
||
|
|
Description="<html><dd><p>Use the flag <strong>-bl</strong> to place the opening brace on a new line:</p></dd><dd><pre>\n if ( $input_file eq '-' ) # -bl \n { \n important_function();\n }</pre></dd><dd><p>This flag applies to all structural blocks, including sub's (unless the <strong>-sbl</strong> flag is set -- see next item).</p></dd><dd><p>The default style, <strong>-nbl</strong>, places an opening brace on the same line as the keyword introducing it. For example,</p></dd><dd><pre>\n if ( $input_file eq '-' ) { # -nbl (default)</pre></dd></html>"
|
||
|
|
EditorType=boolean
|
||
|
|
TrueFalse=-bl|-nbl
|
||
|
|
ValueDefault=0
|
||
|
|
|
||
|
|
[Opening hash brace right]
|
||
|
|
Category=6
|
||
|
|
Description="<html><dd><p>The <strong>-otr</strong> flag is a hint that perltidy should not place a break between a comma and an opening token. For example:</p></dd><dd><pre>\n # default formatting\n push @{ $self->{$module}{$key} },\n {\n accno => $ref->{accno},\n description => $ref->{description}\n };</pre></dd><dd><pre>\n # perltidy -otr\n push @{ $self->{$module}{$key} }, {\n accno => $ref->{accno},\n description => $ref->{description}\n };</pre></dd><dd><p>The flag <strong>-otr</strong> is actually a synonym for three other flags which can be used to control parens, hash braces, and square brackets separately if desired:</p></dd><dd><pre>\n -opr or --opening-paren-right\n -ohbr or --opening-hash-brace-right\n -osbr or --opening-square-bracket-right</pre></dd></html>"
|
||
|
|
EditorType=boolean
|
||
|
|
TrueFalse=-ohbr|
|
||
|
|
ValueDefault=0
|
||
|
|
|
||
|
|
[Opening paren right]
|
||
|
|
Category=6
|
||
|
|
Description="<html><dd><p>The <strong>-otr</strong> flag is a hint that perltidy should not place a break between a comma and an opening token. For example:</p></dd><dd><pre>\n # default formatting\n push @{ $self->{$module}{$key} },\n {\n accno => $ref->{accno},\n description => $ref->{description}\n };</pre></dd><dd><pre>\n # perltidy -otr\n push @{ $self->{$module}{$key} }, {\n accno => $ref->{accno},\n description => $ref->{description}\n };</pre></dd><dd><p>The flag <strong>-otr</strong> is actually a synonym for three other flags which can be used to control parens, hash braces, and square brackets separately if desired:</p></dd><dd><pre>\n -opr or --opening-paren-right\n -ohbr or --opening-hash-brace-right\n -osbr or --opening-square-bracket-right</pre></dd></html>"
|
||
|
|
EditorType=boolean
|
||
|
|
TrueFalse=-opr|
|
||
|
|
ValueDefault=0
|
||
|
|
|
||
|
|
[Opening square bracket right]
|
||
|
|
Category=6
|
||
|
|
Description="<html><dd><p>The <strong>-otr</strong> flag is a hint that perltidy should not place a break between a comma and an opening token. For example:</p></dd><dd><pre>\n # default formatting\n push @{ $self->{$module}{$key} },\n {\n accno => $ref->{accno},\n description => $ref->{description}\n };</pre></dd><dd><pre>\n # perltidy -otr\n push @{ $self->{$module}{$key} }, {\n accno => $ref->{accno},\n description => $ref->{description}\n };</pre></dd><dd><p>The flag <strong>-otr</strong> is actually a synonym for three other flags which can be used to control parens, hash braces, and square brackets separately if desired:</p></dd><dd><pre>\n -opr or --opening-paren-right\n -ohbr or --opening-hash-brace-right\n -osbr or --opening-square-bracket-right</pre></dd></html>"
|
||
|
|
EditorType=boolean
|
||
|
|
TrueFalse=-osbr|
|
||
|
|
ValueDefault=0
|
||
|
|
|
||
|
|
[Opening sub brace on new line]
|
||
|
|
Category=6
|
||
|
|
Description="<html><dd><p>The flag <strong>-sbl</strong> can be used to override the value of <strong>-bl</strong> for opening sub braces. For example,</p></dd><dd><pre>\n perltidy -sbl</pre></dd><dd><p>produces this result:</p></dd><dd><pre>\n sub message\n {\n if (!defined($_[0])) {\n print("Hello, World\n");\n }\n else {\n print($_[0], "\n");\n }\n }</pre></dd><dd><p>This flag is negated with <strong>-nsbl</strong>. If <strong>-sbl</strong> is not specified, the value of <strong>-bl</strong> is used.</p></dd></html>"
|
||
|
|
EditorType=boolean
|
||
|
|
TrueFalse=-sbl|-nsbl
|
||
|
|
ValueDefault=0
|
||
|
|
|
||
|
|
[Opening anonymous sub brace on new line]
|
||
|
|
Category=6
|
||
|
|
Description="<html><p>The flag <strong>-asbl</strong> is like the <strong>-sbl</strong> flag except that it applies to anonymous sub's instead of named subs. For example</p><pre>\n perltidy -asbl</pre><p>produces this result:</p><pre>\n $a = sub\n {\n if ( !defined( $_[0] ) ) {\n print("Hello, World\n");\n }\n else {\n print( $_[0], "\n" );\n }\n };</pre><p>This flag is negated with <strong>-nasbl</strong>, and the default is <strong>-nasbl</strong>.</p></html>"
|
||
|
|
EditorType=boolean
|
||
|
|
TrueFalse=-asbl|-nasbl
|
||
|
|
ValueDefault=0
|
||
|
|
|
||
|
|
[Opening token right]
|
||
|
|
Category=6
|
||
|
|
Description="<html><dd><p>The <strong>-otr</strong> flag is a hint that perltidy should not place a break between a comma and an opening token. For example:</p></dd><dd><pre>\n # default formatting\n push @{ $self->{$module}{$key} },\n {\n accno => $ref->{accno},\n description => $ref->{description}\n };</pre></dd><dd><pre>\n # perltidy -otr\n push @{ $self->{$module}{$key} }, {\n accno => $ref->{accno},\n description => $ref->{description}\n };</pre></dd><dd><p>The flag <strong>-otr</strong> is actually a synonym for three other flags which can be used to control parens, hash braces, and square brackets separately if desired:</p></dd><dd><pre>\n -opr or --opening-paren-right\n -ohbr or --opening-hash-brace-right\n -osbr or --opening-square-bracket-right</pre></dd></html>"
|
||
|
|
EditorType=boolean
|
||
|
|
TrueFalse=-otr|
|
||
|
|
ValueDefault=0
|
||
|
|
|
||
|
|
[Outdent keyword list]
|
||
|
|
CallName="--outdent-keyword-list="
|
||
|
|
Category=2
|
||
|
|
Description="<html>This command can be used to change the keywords which are outdented with the <strong>-okw</strong> command. The parameter <strong>string</strong> is a required list of perl keywords, which should be placed in quotes if there are more than one. By itself, it does not cause any outdenting to occur, so the <strong>-okw</strong> command is still required.</p></dd><dd><p>For example, the commands <code>-okwl="next last redo goto" -okw</code> will cause those four keywords to be outdented. It is probably simplest to place any <strong>-okwl</strong> command in a <em>.perltidyrc</em> file.</html>"
|
||
|
|
EditorType=string
|
||
|
|
Enabled=false
|
||
|
|
ValueDefault=
|
||
|
|
|
||
|
|
[Outdent long comments]
|
||
|
|
Category=4
|
||
|
|
Description="<html><dd><p>When <strong>-olc</strong> is set, lines which are full-line (block) comments longer than the value <strong>maximum-line-length</strong> will have their indentation removed. This is the default; use <strong>-nolc</strong> to prevent outdenting.</p></dd></html>"
|
||
|
|
EditorType=boolean
|
||
|
|
TrueFalse=-olc|-nolc
|
||
|
|
ValueDefault=1
|
||
|
|
|
||
|
|
[Outdent long lines]
|
||
|
|
Category=2
|
||
|
|
Description="<html>This command is equivalent to <strong>--outdent-long-quotes</strong> and <strong>--outdent-long-comments</strong>, and it is included for compatibility with previous versions of perltidy. The negation of this also works, <strong>-noll</strong> or <strong>--nooutdent-long-lines</strong>, and is equivalent to setting <strong>-nolq</strong> and <strong>-nolc</strong>.</html>"
|
||
|
|
EditorType=boolean
|
||
|
|
TrueFalse=--outdent-long-lines|
|
||
|
|
ValueDefault=0
|
||
|
|
|
||
|
|
[Outdent long quotes]
|
||
|
|
Category=2
|
||
|
|
Description="<html>When <strong>-olq</strong> is set, lines which is a quoted string longer than the value <strong>maximum-line-length</strong> will have their indentation removed to make them more readable. This is the default. To prevent such out-denting, use <strong>-nolq</strong> or <strong>--nooutdent-long-lines</strong>.</html>"
|
||
|
|
EditorType=boolean
|
||
|
|
TrueFalse=--outdent-long-quotes|
|
||
|
|
ValueDefault=0
|
||
|
|
|
||
|
|
[Outdenting Keywords]
|
||
|
|
Category=2
|
||
|
|
Description="<html>The command <strong>-okw</strong> will will cause certain leading control keywords to be outdented by 2 spaces (or whatever <strong>-ci</strong> has been set to), if possible. By default, these keywords are <code>redo</code>, <code>next</code>, <code>last</code>, <code>goto</code>, and <code>return</code>. The intention is to make these control keywords easier to see. To change this list of keywords being outdented, see the next section.</p></dd><dd><p>For example, using <code>perltidy -okw</code> on the previous example gives:</p></dd><dd><pre>\n my $i;\n LOOP: while ( $i = <FOTOS> ) {\n chomp($i);\n next unless $i;\n fixit($i);\n }</pre></dd><dd><p>The default is not to do this.</html>"
|
||
|
|
EditorType=boolean
|
||
|
|
TrueFalse=--outdent-keywords|
|
||
|
|
ValueDefault=0
|
||
|
|
|
||
|
|
[Outdenting Labels]
|
||
|
|
Category=2
|
||
|
|
Description="<html>This command will cause labels to be outdented by 2 spaces (or whatever <strong>-ci</strong> has been set to), if possible. This is the default. For example:</p></dd><dd><pre>\n my $i;\n LOOP: while ( $i = <FOTOS> ) {\n chomp($i);\n next unless $i;\n fixit($i);\n }</pre></dd><dd><p>Use <strong>-nola</strong> to not outdent labels.</html>"
|
||
|
|
EditorType=boolean
|
||
|
|
TrueFalse=--outdent-labels|
|
||
|
|
ValueDefault=0
|
||
|
|
|
||
|
|
[Output line ending]
|
||
|
|
Category=1
|
||
|
|
Choices="--output-line-ending=win|--output-line-ending=dos|--output-line-ending=unix|--output-line-ending=mac"
|
||
|
|
ChoicesReadable=Output line ending Windows|Output line ending Dos|Output line ending Unix|Output line ending Mac
|
||
|
|
Description="<html>where s=<code>win</code>, <code>dos</code>, <code>unix</code>, or <code>mac</code>. This flag tells perltidy to output line endings for a specific system. Normally, perltidy writes files with the line separator character of the host system. The <code>win</code> and <code>dos</code> flags have an identical result.</html>"
|
||
|
|
EditorType=multiple
|
||
|
|
Enabled=false
|
||
|
|
ValueDefault=1
|
||
|
|
|
||
|
|
[Paren tightness]
|
||
|
|
CallName="--paren-tightness="
|
||
|
|
Category=3
|
||
|
|
Description="<html><p>The <strong>-pt=n</strong> or <strong>--paren-tightness=n</strong> parameter controls the space within parens. The example below shows the effect of the three possible values, 0, 1, and 2:</p></dd><dd><pre>\n if ( ( my $len_tab = length( $tabstr ) ) > 0 ) { # -pt=0\n if ( ( my $len_tab = length($tabstr) ) > 0 ) { # -pt=1 (default)\n if ((my $len_tab = length($tabstr)) > 0) { # -pt=2</pre></dd><dd><p>When n is 0, there is always a space to the right of a '(' and to the left of a ')'. For n=2 there is never a space. For n=1, the default, there is a space unless the quantity within the parens is a single token, such as an identifier or quoted string.</html>"
|
||
|
|
EditorType=numeric
|
||
|
|
Enabled=false
|
||
|
|
MaxVal=2
|
||
|
|
MinVal=0
|
||
|
|
ValueDefault=1
|
||
|
|
|
||
|
|
[Paren vertical tightness]
|
||
|
|
CallName="--paren-vertical-tightness="
|
||
|
|
Category=6
|
||
|
|
Description="<html><p>The <strong>-vt=n</strong> and <strong>-vtc=n</strong> 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.</p><p>In fact, the parameter <strong>-vt=n</strong> is actually just an abbreviation for <strong>-pvt=n -bvt=n sbvt=n</strong>, and likewise <strong>-vtc=n</strong> is an abbreviation for <strong>-pvtc=n -bvtc=n sbvtc=n</strong>.</p></html>"
|
||
|
|
EditorType=numeric
|
||
|
|
Enabled=false
|
||
|
|
MaxVal=2
|
||
|
|
MinVal=0
|
||
|
|
ValueDefault=0
|
||
|
|
|
||
|
|
[Paren vertical tightness closing]
|
||
|
|
CallName="--paren-vertical-tightness-closing="
|
||
|
|
Category=6
|
||
|
|
Description="<html><p>The <strong>-vt=n</strong> and <strong>-vtc=n</strong> 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.</p><p>In fact, the parameter <strong>-vt=n</strong> is actually just an abbreviation for <strong>-pvt=n -bvt=n sbvt=n</strong>, and likewise <strong>-vtc=n</strong> is an abbreviation for <strong>-pvtc=n -bvtc=n sbvtc=n</strong>.</p></html>"
|
||
|
|
EditorType=numeric
|
||
|
|
Enabled=false
|
||
|
|
MaxVal=2
|
||
|
|
MinVal=0
|
||
|
|
ValueDefault=0
|
||
|
|
|
||
|
|
[Perl best practices]
|
||
|
|
Category=0
|
||
|
|
Description="<html><dd><p><strong>-pbp</strong> is an abbreviation for the parameters in the book <strong>Perl Best Practices</strong> by Damian Conway:</p></dd><dd><pre>\n -l=78 -i=4 -ci=4 -st -se -vt=2 -cti=0 -pt=1 -bt=1 -sbt=1 -bbt=1 -nsfs -nolq\n -wbb="% + - * / x != == >= <= =~ !~ < > | & = \n **= += *= &= <<= &&= -= /= |= >>= ||= //= .= %= ^= x="</pre></dd><dd><p>Note that the -st and -se flags make perltidy act as a filter on one file only. These can be overridden with -nst and -nse if necessary.</p></dd></html>"
|
||
|
|
EditorType=boolean
|
||
|
|
Enabled=false
|
||
|
|
TrueFalse=--perl-best-practices --nostandard-output|
|
||
|
|
ValueDefault=0
|
||
|
|
|
||
|
|
[Perl syntax check flags]
|
||
|
|
CallName="--perl-syntax-check-flags="
|
||
|
|
Category=1
|
||
|
|
Description="<html>When perl is invoked to check syntax, the normal flags are <code>-c -T</code>. In addition, if the <strong>-x</strong> flag is given to perltidy, then perl will also be passed a <strong>-x</strong> flag. It should not normally be necessary to change these flags, but it can be done with the <strong>-pscf=s</strong> flag. For example, if the taint flag, <code>-T</code>, is not wanted, the flag could be set to be just <strong>-pscf=-c</strong>.</p></dd><dd><p>Perltidy will pass your string to perl with the exception that it willadd a <strong>-c</strong> and <strong>-x</strong> if appropriate. The <em>.LOG</em> file will show exactly what flags were passed to perl.</html>"
|
||
|
|
EditorType=string
|
||
|
|
Enabled=false
|
||
|
|
ValueDefault=
|
||
|
|
|
||
|
|
[Preserve line endings]
|
||
|
|
Category=1
|
||
|
|
Description="<html>This flag tells perltidy to write its output files with the same line endings as the input file, if possible. It should work for <strong>dos</strong>, <strong>unix</strong>, and <strong>mac</strong> line endings. It will only work if perltidy input comes from a filename (rather than stdin, for example). If 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.</html>"
|
||
|
|
EditorType=boolean
|
||
|
|
Enabled=false
|
||
|
|
TrueFalse=--preserve-line-endings|
|
||
|
|
ValueDefault=0
|
||
|
|
|
||
|
|
[Space after keyword]
|
||
|
|
CallName="--space-after-keyword="
|
||
|
|
Category=3
|
||
|
|
Description="<html><dd><p>When an opening paren follows a Perl keyword, no space is introduced after the keyword, unless it is (by default) one of these:</p></dd><dd><pre>\n my local our and or eq ne if else elsif until unless \n while for foreach return switch case given when</pre></dd><dd><p>These defaults can be modified with two commands:</p></dd><dd><p><strong>-sak=s</strong> or <strong>--space-after-keyword=s</strong> adds keywords.</p></dd><dd><p><strong>-nsak=s</strong> or <strong>--nospace-after-keyword=s</strong> removes keywords.</p></dd><dd><p>where <strong>s</strong> is a list of keywords (in quotes if necessary). For example,</p></dd><dd><pre>\n my ( $a, $b, $c ) = @_; # default\n my( $a, $b, $c ) = @_; # -nsak="my local our"</pre></dd></html>"
|
||
|
|
EditorType=string
|
||
|
|
Enabled=false
|
||
|
|
ValueDefault=
|
||
|
|
|
||
|
|
[Space for semicolon]
|
||
|
|
Category=3
|
||
|
|
Description="<html><dd><p>Semicolons within <strong>for</strong> loops may sometimes be hard to see, particularly when commas are also present. This option places spaces on both sides of these special semicolons, and is the default. Use <strong>-nsfs</strong> or <strong>--nospace-for-semicolon</strong> to deactivate it.</p></dd><dd><pre>\n for ( @a = @$ap, $u = shift @a ; @a ; $u = $v ) { # -sfs (default)\n for ( @a = @$ap, $u = shift @a; @a; $u = $v ) { # -nsfs</pre></dd></html>"
|
||
|
|
EditorType=boolean
|
||
|
|
TrueFalse=--space-for-semicolon|
|
||
|
|
ValueDefault=0
|
||
|
|
|
||
|
|
[Space function paren]
|
||
|
|
Category=3
|
||
|
|
Description="<html><dd><p>When an opening paren follows a function the default is not to introduce a space. To cause a space to be introduced use:</p></dd><dd><p><strong>-sfp</strong> or <strong>--space-function-paren</strong></p></dd><dd><pre>\n myfunc( $a, $b, $c ); # default \n myfunc ( $a, $b, $c ); # -sfp</pre></dd><dd><p>You will probably also want to use the flag <strong>-skp</strong> (previous item) too.</p></dd></html>"
|
||
|
|
EditorType=boolean
|
||
|
|
TrueFalse=--space-function-paren|
|
||
|
|
ValueDefault=0
|
||
|
|
|
||
|
|
[Space keyword paren]
|
||
|
|
Category=3
|
||
|
|
Description="<html><dd><p>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 always put a space between a function or keyword and its opening paren, use the command:</p></dd><dd><p><strong>-skp</strong> or <strong>--space-keyword-paren</strong></p></dd><dd><p>You will probably also want to use the flag <strong>-sfp</strong> (next item) too.</p></dd></html>"
|
||
|
|
EditorType=boolean
|
||
|
|
TrueFalse=--space-keyword-paren|
|
||
|
|
ValueDefault=0
|
||
|
|
|
||
|
|
[Space terminal semicolon]
|
||
|
|
Category=3
|
||
|
|
Description="<html><p>Some programmers prefer a space before all terminal semicolons. The default is for no such space, and is indicated with <strong>-nsts</strong> or <strong>--nospace-terminal-semicolon</strong>.</p></dd><dd><pre>\n $i = 1 ; # -sts\n $i = 1; # -nsts (default)</pre></dd></html>"
|
||
|
|
EditorType=boolean
|
||
|
|
TrueFalse=--space-terminal-semicolon|
|
||
|
|
ValueDefault=0
|
||
|
|
|
||
|
|
[Square bracket tightness]
|
||
|
|
CallName="--square-bracket-tightness="
|
||
|
|
Category=3
|
||
|
|
Description="<html><p>Likewise, the parameter <strong>-sbt=n</strong> or <strong>--square-bracket-tightness=n</strong> controls the space within square brackets, as illustrated below.</p></dd><dd><pre>\n $width = $col[ $j + $k ] - $col[ $j ]; # -sbt=0\n $width = $col[ $j + $k ] - $col[$j]; # -sbt=1 (default)\n $width = $col[$j + $k] - $col[$j]; # -sbt=2</pre></dd></html>"
|
||
|
|
EditorType=numeric
|
||
|
|
Enabled=false
|
||
|
|
MaxVal=2
|
||
|
|
MinVal=0
|
||
|
|
ValueDefault=1
|
||
|
|
|
||
|
|
[Square bracket vertical tightness]
|
||
|
|
CallName="--square-bracket-vertical-tightness="
|
||
|
|
Category=6
|
||
|
|
Description="<html><p>The <strong>-vt=n</strong> and <strong>-vtc=n</strong> 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.</p><p>In fact, the parameter <strong>-vt=n</strong> is actually just an abbreviation for <strong>-pvt=n -bvt=n sbvt=n</strong>, and likewise <strong>-vtc=n</strong> is an abbreviation for <strong>-pvtc=n -bvtc=n sbvtc=n</strong>.</p></html>"
|
||
|
|
EditorType=numeric
|
||
|
|
Enabled=false
|
||
|
|
MaxVal=2
|
||
|
|
MinVal=0
|
||
|
|
ValueDefault=0
|
||
|
|
|
||
|
|
[Square bracket vertical tightness closing]
|
||
|
|
CallName="--square-bracket-vertical-tightness-closing="
|
||
|
|
Category=6
|
||
|
|
Description="<html><p>The <strong>-vt=n</strong> and <strong>-vtc=n</strong> 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.</p><p>In fact, the parameter <strong>-vt=n</strong> is actually just an abbreviation for <strong>-pvt=n -bvt=n sbvt=n</strong>, and likewise <strong>-vtc=n</strong> is an abbreviation for <strong>-pvtc=n -bvtc=n sbvtc=n</strong>.</p></html>"
|
||
|
|
EditorType=numeric
|
||
|
|
Enabled=false
|
||
|
|
MaxVal=2
|
||
|
|
MinVal=0
|
||
|
|
ValueDefault=0
|
||
|
|
|
||
|
|
[Stack closing hash brace]
|
||
|
|
Category=6
|
||
|
|
Description="<html><dd><p>The <strong>-sct</strong> flag tells perltidy to ``stack'' closing tokens when possible to avoid lines with isolated closing tokens.</p></dd><dd><p>For example:</p></dd><dd><pre>\n # default\n $opt_c = Text::CSV_XS->new(\n {\n binary => 1,\n sep_char => $opt_c,\n always_quote => 1,\n }\n );</pre></dd><dd><pre>\n # -sct\n $opt_c = Text::CSV_XS->new(\n {\n binary => 1,\n sep_char => $opt_c,\n always_quote => 1,\n } );</pre></dd><dd><p>The <strong>-sct</strong> flag is somewhat similar to the <strong>-vtc</strong> flags, and in some cases it can give a similar result. The difference is that the <strong>-vtc</strong> flags try to avoid lines with leading opening tokens by ``hiding'' them at the end of a previous line, whereas the <strong>-sct</strong> flag merely tries to reduce the number of lines with isolated closing tokens by stacking them but does not try to hide them. For example:</p></dd><dd><pre>\n # -vtc=2\n $opt_c = Text::CSV_XS->new(\n {\n binary => 1,\n sep_char => $opt_c,\n always_quote => 1, } );</pre></dd><dd><p>The flag <strong>-sct</strong> is a synonym for <strong>-scp -schb -scsb</strong>.</p></dd></html>"
|
||
|
|
EditorType=boolean
|
||
|
|
TrueFalse=-schb|
|
||
|
|
ValueDefault=0
|
||
|
|
|
||
|
|
[Stack closing paren]
|
||
|
|
Category=6
|
||
|
|
Description="<html><dd><p>The <strong>-sct</strong> flag tells perltidy to ``stack'' closing tokens when possible to avoid lines with isolated closing tokens.</p></dd><dd><p>For example:</p></dd><dd><pre>\n # default\n $opt_c = Text::CSV_XS->new(\n {\n binary => 1,\n sep_char => $opt_c,\n always_quote => 1,\n }\n );</pre></dd><dd><pre>\n # -sct\n $opt_c = Text::CSV_XS->new(\n {\n binary => 1,\n sep_char => $opt_c,\n always_quote => 1,\n } );</pre></dd><dd><p>The <strong>-sct</strong> flag is somewhat similar to the <strong>-vtc</strong> flags, and in some cases it can give a similar result. The difference is that the <strong>-vtc</strong> flags try to avoid lines with leading opening tokens by ``hiding'' them at the end of a previous line, whereas the <strong>-sct</strong> flag merely tries to reduce the number of lines with isolated closing tokens by stacking them but does not try to hide them. For example:</p></dd><dd><pre>\n # -vtc=2\n $opt_c = Text::CSV_XS->new(\n {\n binary => 1,\n sep_char => $opt_c,\n always_quote => 1, } );</pre></dd><dd><p>The flag <strong>-sct</strong> is a synonym for <strong>-scp -schb -scsb</strong>.</p></dd></html>"
|
||
|
|
EditorType=boolean
|
||
|
|
TrueFalse=-scp|
|
||
|
|
ValueDefault=0
|
||
|
|
|
||
|
|
[Stack closing square bracket]
|
||
|
|
Category=6
|
||
|
|
Description="<html><dd><p>The <strong>-sct</strong> flag tells perltidy to ``stack'' closing tokens when possible to avoid lines with isolated closing tokens.</p></dd><dd><p>For example:</p></dd><dd><pre>\n # default\n $opt_c = Text::CSV_XS->new(\n {\n binary => 1,\n sep_char => $opt_c,\n always_quote => 1,\n }\n );</pre></dd><dd><pre>\n # -sct\n $opt_c = Text::CSV_XS->new(\n {\n binary => 1,\n sep_char => $opt_c,\n always_quote => 1,\n } );</pre></dd><dd><p>The <strong>-sct</strong> flag is somewhat similar to the <strong>-vtc</strong> flags, and in some cases it can give a similar result. The difference is that the <strong>-vtc</strong> flags try to avoid lines with leading opening tokens by ``hiding'' them at the end of a previous line, whereas the <strong>-sct</strong> flag merely tries to reduce the number of lines with isolated closing tokens by stacking them but does not try to hide them. For example:</p></dd><dd><pre>\n # -vtc=2\n $opt_c = Text::CSV_XS->new(\n {\n binary => 1,\n sep_char => $opt_c,\n always_quote => 1, } );</pre></dd><dd><p>The flag <strong>-sct</strong> is a synonym for <strong>-scp -schb -scsb</strong>.</p></dd></html>"
|
||
|
|
EditorType=boolean
|
||
|
|
TrueFalse=-scsb|
|
||
|
|
ValueDefault=0
|
||
|
|
|
||
|
|
[Stack closing tokens]
|
||
|
|
Category=6
|
||
|
|
Description="<html><dd><p>The <strong>-sct</strong> flag tells perltidy to ``stack'' closing tokens when possible to avoid lines with isolated closing tokens.</p></dd><dd><p>For example:</p></dd><dd><pre>\n # default\n $opt_c = Text::CSV_XS->new(\n {\n binary => 1,\n sep_char => $opt_c,\n always_quote => 1,\n }\n );</pre></dd><dd><pre>\n # -sct\n $opt_c = Text::CSV_XS->new(\n {\n binary => 1,\n sep_char => $opt_c,\n always_quote => 1,\n } );</pre></dd><dd><p>The <strong>-sct</strong> flag is somewhat similar to the <strong>-vtc</strong> flags, and in some cases it can give a similar result. The difference is that the <strong>-vtc</strong> flags try to avoid lines with leading opening tokens by ``hiding'' them at the end of a previous line, whereas the <strong>-sct</strong> flag merely tries to reduce the number of lines with isolated closing tokens by stacking them but does not try to hide them. For example:</p></dd><dd><pre>\n # -vtc=2\n $opt_c = Text::CSV_XS->new(\n {\n binary => 1,\n sep_char => $opt_c,\n always_quote => 1, } );</pre></dd><dd><p>For detailed control of the stacking of individual closing tokens the following controls can be used:</p></dd><dd><pre>\n -scp or --stack-closing-paren\n -schb or --stack-closing-hash-brace\n -scsb or --stack-closing-square-bracket</pre></dd><dd><p>The flag <strong>-sct</strong> is a synonym for <strong>-scp -schb -scsb</strong>.</p></dd></html>"
|
||
|
|
EditorType=boolean
|
||
|
|
TrueFalse=-sct|
|
||
|
|
ValueDefault=0
|
||
|
|
|
||
|
|
[Stack opening hash brace]
|
||
|
|
Category=6
|
||
|
|
Description="<html><dd><p>The <strong>-sot</strong> flag tells perltidy to ``stack'' opening tokens when possible to avoid lines with isolated opening tokens.</p></dd><dd><p>For example:</p></dd><dd><pre>\n # default\n $opt_c = Text::CSV_XS->new(\n {\n binary => 1,\n sep_char => $opt_c,\n always_quote => 1,\n }\n );</pre></dd><dd><pre>\n # -sot\n $opt_c = Text::CSV_XS->new( {\n binary => 1,\n sep_char => $opt_c,\n always_quote => 1,\n }\n );</pre></dd><dd><p>For detailed control of individual closing tokens the following controls can be used:</p></dd><dd><pre>\n -sop or --stack-opening-paren\n -sohb or --stack-opening-hash-brace\n -sosb or --stack-opening-square-bracket</pre></dd><dd><p>The flag <strong>-sot</strong> is a synonym for <strong>-sop -sohb -sosb</strong>.</p></dd></html>"
|
||
|
|
EditorType=boolean
|
||
|
|
TrueFalse=-sohb|
|
||
|
|
ValueDefault=0
|
||
|
|
|
||
|
|
[Stack opening paren]
|
||
|
|
Category=6
|
||
|
|
Description="<html><dd><p>The <strong>-sot</strong> flag tells perltidy to ``stack'' opening tokens when possible to avoid lines with isolated opening tokens.</p></dd><dd><p>For example:</p></dd><dd><pre>\n # default\n $opt_c = Text::CSV_XS->new(\n {\n binary => 1,\n sep_char => $opt_c,\n always_quote => 1,\n }\n );</pre></dd><dd><pre>\n # -sot\n $opt_c = Text::CSV_XS->new( {\n binary => 1,\n sep_char => $opt_c,\n always_quote => 1,\n }\n );</pre></dd><dd><p>The flag <strong>-sot</strong> is a synonym for <strong>-sop -sohb -sosb</strong>.</p></dd></html>"
|
||
|
|
EditorType=boolean
|
||
|
|
TrueFalse=-sop|
|
||
|
|
ValueDefault=0
|
||
|
|
|
||
|
|
[Stack opening square bracket]
|
||
|
|
Category=6
|
||
|
|
Description="<html><dd><p>The <strong>-sot</strong> flag tells perltidy to ``stack'' opening tokens when possible to avoid lines with isolated opening tokens.</p></dd><dd><p>For example:</p></dd><dd><pre>\n # default\n $opt_c = Text::CSV_XS->new(\n {\n binary => 1,\n sep_char => $opt_c,\n always_quote => 1,\n }\n );</pre></dd><dd><pre>\n # -sot\n $opt_c = Text::CSV_XS->new( {\n binary => 1,\n sep_char => $opt_c,\n always_quote => 1,\n }\n );</pre></dd><dd><p>For detailed control of individual closing tokens the following controls can be used:</p></dd><dd><pre>\n -sop or --stack-opening-paren\n -sohb or --stack-opening-hash-brace\n -sosb or --stack-opening-square-bracket</pre></dd><dd><p>The flag <strong>-sot</strong> is a synonym for <strong>-sop -sohb -sosb</strong>.</p></dd></html>"
|
||
|
|
EditorType=boolean
|
||
|
|
TrueFalse=-sosb|
|
||
|
|
ValueDefault=0
|
||
|
|
|
||
|
|
[Stack opening tokens]
|
||
|
|
Category=6
|
||
|
|
Description="<html><dd><p>The <strong>-sot</strong> flag tells perltidy to ``stack'' opening tokens when possible to avoid lines with isolated opening tokens.</p></dd><dd><p>For example:</p></dd><dd><pre>\n # default\n $opt_c = Text::CSV_XS->new(\n {\n binary => 1,\n sep_char => $opt_c,\n always_quote => 1,\n }\n );</pre></dd><dd><pre>\n # -sot\n $opt_c = Text::CSV_XS->new( {\n binary => 1,\n sep_char => $opt_c,\n always_quote => 1,\n }\n );</pre></dd><dd><p>For detailed control of individual closing tokens the following controls can be used:</p></dd><dd><pre>\n -sop or --stack-opening-paren\n -sohb or --stack-opening-hash-brace\n -sosb or --stack-opening-square-bracket</pre></dd><dd><p>The flag <strong>-sot</strong> is a synonym for <strong>-sop -sohb -sosb</strong>.</p></dd></html>"
|
||
|
|
EditorType=boolean
|
||
|
|
TrueFalse=-sot|
|
||
|
|
ValueDefault=0
|
||
|
|
|
||
|
|
[Starting indentation level]
|
||
|
|
CallName="--starting-indentation-level="
|
||
|
|
Category=2
|
||
|
|
Description="<html>By default, perltidy examines the input file and tries to determine the starting indentation level. While it is often zero, it may not be zero for a code snippet being sent from an editing session. If the default method does not work correctly, or you want to change the starting level, use <strong>-sil=n</strong>, to force the starting level to be n.</html>"
|
||
|
|
EditorType=numeric
|
||
|
|
Enabled=false
|
||
|
|
MaxVal=1000
|
||
|
|
MinVal=0
|
||
|
|
ValueDefault=0
|
||
|
|
|
||
|
|
[Static Block Comment Outdent]
|
||
|
|
Category=4
|
||
|
|
Description="<html><dd><p>The command <strong>-osbc</strong> will will cause static block comments to be outdented by 2 spaces (or whatever <strong>-ci=n</strong> has been set to), if possible.</p></dd></html>"
|
||
|
|
EditorType=boolean
|
||
|
|
TrueFalse=-osbc|
|
||
|
|
ValueDefault=0
|
||
|
|
|
||
|
|
[Static Block Comment Prefix]
|
||
|
|
CallName="--static-block-comment-prefix="
|
||
|
|
Category=4
|
||
|
|
Description="<html><dd><p>This parameter defines the prefix used to identify static block comments when the <strong>-sbc</strong> parameter is set. The default prefix is <code>##</code>, corresponding to <code>-sbcp=##</code>. The prefix is actually part of a perl pattern used to match lines and it must either begin with <code>#</code> or <code>^#</code>. In the first case a prefix ^* will be added to match any leading whitespace, while in the second case the pattern will match only comments with no leading whitespace. For example, to identify all comments as static block comments, one would use <code>-sbcp=#</code>. To identify all left-adjusted comments as static block comments, use <code>-sbcp='^#'</code>.</p></dd><dd><p>Please note that <strong>-sbcp</strong> merely defines the pattern used to identify static block comments; it will not be used unless the switch <strong>-sbc</strong> is set. Also, please be aware that since this string is used in a perl regular expression which identifies these comments, it must enable a valid regular expression to be formed.</p></dd><dd><p>A pattern which can be useful is:</p></dd><dd><pre>\n -sbcp=^#{2,}[^#]</pre></dd><dd><p>This pattern requires a static block comment to have at least one character which is neither a # nor a space. It allows a line containing only '#' characters to be rejected as a static block comment. Such lines are often used at the start and end of header information in subroutines and should not be separated from the intervening comments, which typically begin with just a single '#'.</p></dd></html>"
|
||
|
|
EditorType=string
|
||
|
|
Enabled=false
|
||
|
|
ValueDefault=##
|
||
|
|
|
||
|
|
[Static Block Comments]
|
||
|
|
Category=4
|
||
|
|
Description="<html><dd><p>Static block comments are block comments with a special leading pattern, <code>##</code> by default, which will be treated slightly differently from other block comments. They effectively behave as if they had glue along their left and top edges, because they stick to the left edge and previous line when there is no blank spaces in those places. This option is particularly useful for controlling how commented code is displayed.</p></dd><dl><dt><strong><a name=item__2dsbc_2c__2d_2dstatic_2dblock_2dcomments><strong>-sbc</strong>, <strong>--static-block-comments</strong></a></strong><dd><p>When <strong>-sbc</strong> is used, a block comment with a special leading pattern, <code>##</code> by default, will be treated specially.</p></dd><dd><p>Comments so identified are treated as follows:</p></dd><ul><li><p>If there is no leading space on the line, then the comment will not be indented, and otherwise it may be,</p></li><li><p>no new blank line will be inserted before such a comment, and</p></li><li><p>such a comment will never become a hanging side comment.</p></li></ul><p>For example, assuming <code>@month_of_year</code> is left-adjusted:</p><pre>\n @month_of_year = ( # -sbc (default)\n 'Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct',\n ## 'Dec', 'Nov'\n 'Nov', 'Dec');</pre><p>Without this convention, the above code would become</p><pre>\n @month_of_year = ( # -nsbc\n 'Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct',\n \n ## 'Dec', 'Nov'\n 'Nov', 'Dec'\n );</pre> <p>which is not as clear. The default is to use <strong>-sbc</strong>. This may be deactivated with <strong>-nsbc</strong>.</p></html>"
|
||
|
|
EditorType=boolean
|
||
|
|
TrueFalse=-sbc|-nsbc
|
||
|
|
ValueDefault=1
|
||
|
|
|
||
|
|
[Static Side Comment Prefix]
|
||
|
|
CallName="--static-side-comment-prefix="
|
||
|
|
Category=4
|
||
|
|
Description="<html><dd><p>This parameter defines the prefix used to identify static side comments when the <strong>-ssc</strong> parameter is set. The default prefix is <code>##</code>, corresponding to <code>-sscp=##</code>.</p></dd><dd><p>Please note that <strong>-sscp</strong> merely defines the pattern used to identify static side comments; it will not be used unless the switch <strong>-ssc</strong> is set. Also, note that this string is used in a perl regular expression which identifies these comments, so it must enable a valid regular expression to be formed.</p></dd></html>"
|
||
|
|
EditorType=string
|
||
|
|
Enabled=false
|
||
|
|
ValueDefault=##
|
||
|
|
|
||
|
|
[Static Side Comments]
|
||
|
|
Category=4
|
||
|
|
Description="<html><dd><p>Static side comments are side comments with a special leading pattern. This option can be useful for controlling how commented code is displayed when it is a side comment.</p></dd><dl><dt><strong><a name=item__2dssc_2c__2d_2dstatic_2dside_2dcomments><strong>-ssc</strong>, <strong>--static-side-comments</strong></a></strong><dd><p>When <strong>-ssc</strong> is used, a side comment with a static leading pattern, which is <code>##</code> by default, will be be spaced only a single space from previous character, and it will not be vertically aligned with other side comments.</p></dd><dd><p>The default is <strong>-nssc</strong>.</p></dd></html>"
|
||
|
|
EditorType=boolean
|
||
|
|
TrueFalse=-ssc|-nssc
|
||
|
|
ValueDefault=0
|
||
|
|
|
||
|
|
[Tabs]
|
||
|
|
Category=1
|
||
|
|
Description="<html>This flag causes one leading tab character to be inserted for each level 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 <strong>-lp</strong> option.</html>"
|
||
|
|
EditorType=boolean
|
||
|
|
TrueFalse=--tabs|
|
||
|
|
ValueDefault=0
|
||
|
|
|
||
|
|
[Trimming whitespace around qw quotes]
|
||
|
|
Category=3
|
||
|
|
Choices=--trim-qw|--notrim-qw
|
||
|
|
ChoicesReadable=Trim whitespace|Do not trim whitespace
|
||
|
|
Description="<html><dd><p><strong>-tqw</strong> or <strong>--trim-qw</strong> provide the default behavior of trimming spaces around multi-line <code>qw</code> quotes and indenting them appropriately.</p></dd><dd><p><strong>-ntqw</strong> or <strong>--notrim-qw</strong> cause leading and trailing whitespace around multi-line <code>qw</code> quotes to be left unchanged. This option will not normally be necessary, but was added for testing purposes, because in some versions of perl, trimming <code>qw</code> quotes changes the syntax tree.</p></dd></html>"
|
||
|
|
EditorType=multiple
|
||
|
|
Enabled=false
|
||
|
|
ValueDefault=0
|
||
|
|
|
||
|
|
[Vertical tightness]
|
||
|
|
CallName="--vertical-tightness="
|
||
|
|
Category=6
|
||
|
|
Description="<html><p>Opening tokens (except for block braces) are controlled by <strong>-vt=n</strong>, or <strong>--vertical-tightness=n</strong>, where</p><pre>\n -vt=0 always break a line after opening token (default). \n -vt=1 do not break unless this would produce more than one \n step in indentation in a line.\n -vt=2 never break a line after opening token</pre><p>You must also use the <strong>-lp</strong> flag when you use the <strong>-vt</strong> flag; the reason is explained below.</p></html>"
|
||
|
|
EditorType=numeric
|
||
|
|
Enabled=false
|
||
|
|
MaxVal=2
|
||
|
|
MinVal=0
|
||
|
|
ValueDefault=0
|
||
|
|
|
||
|
|
[Vertical tightness closing]
|
||
|
|
CallName="--vertical-tightness-closing="
|
||
|
|
Category=6
|
||
|
|
Description="<html><p>Closing tokens (except for block braces) are controlled by <strong>-vtc=n</strong>, or <strong>--vertical-tightness-closing=n</strong>, where</p><pre>\n -vtc=0 always break a line before a closing token (default), \n -vtc=1 do not break before a closing token which is followed \n by a semicolon or another closing token, and is not in \n a list environment.\n -vtc=2 never break before a closing token.</pre><p>The rules for <strong>-vtc=1</strong> are designed to maintain a reasonable balance between tightness and readability in complex lists.</p></html>"
|
||
|
|
EditorType=numeric
|
||
|
|
Enabled=false
|
||
|
|
MaxVal=2
|
||
|
|
MinVal=0
|
||
|
|
ValueDefault=0
|
||
|
|
|
||
|
|
[Want break after]
|
||
|
|
CallName="--want-break-after="
|
||
|
|
Category=6
|
||
|
|
Description="<html><dd><p>These parameters are each followed by a quoted string, <strong>s</strong>, 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.</p></dd><dd><p>By default, perltidy breaks <strong>after</strong> these token types: % + - * / x != == >= <= =~ !~ < > | & = **= += *= &= <<= &&= -= /= |= >>= ||= //= .= %= ^= x=</p></dd><dd><p>And perltidy breaks <strong>before</strong> these token types by default: . << >> -> && || //</p></dd><dd><p>To illustrate, to cause a break after a concatenation operator, <code>'.'</code>, rather than before it, the command line would be</p></dd><dd><pre>\n -wba="."</pre></dd><dd><p>As another example, the following command would cause a break before math operators <code>'+'</code>, <code>'-'</code>, <code>'/'</code>, and <code>'*'</code>:</p></dd><dd><pre>\n -wbb="+ - / *"</pre></dd><dd><p>These commands should work well for most of the token types that perltidy uses (use <strong>--dump-token-types</strong> for a list). Also try the <strong>-D</strong> flag on a short snippet of code and look at the .DEBUG file to see the tokenization. However, for a few token types there may be conflicts with hardwired logic which cause unexpected results. One example is curly braces, which should be controlled with the parameter <strong>bl</strong> provided for that purpose.</p></dd></html>"
|
||
|
|
EditorType=string
|
||
|
|
Enabled=false
|
||
|
|
ValueDefault=
|
||
|
|
|
||
|
|
[Want break before]
|
||
|
|
CallName="--want-break-before="
|
||
|
|
Category=6
|
||
|
|
Description="<html><dd><p>These parameters are each followed by a quoted string, <strong>s</strong>, 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.</p></dd><dd><p>By default, perltidy breaks <strong>after</strong> these token types: % + - * / x != == >= <= =~ !~ < > | & = **= += *= &= <<= &&= -= /= |= >>= ||= //= .= %= ^= x=</p></dd><dd><p>And perltidy breaks <strong>before</strong> these token types by default: . << >> -> && || //</p></dd><dd><p>To illustrate, to cause a break after a concatenation operator, <code>'.'</code>, rather than before it, the command line would be</p></dd><dd><pre>\n -wba="."</pre></dd><dd><p>As another example, the following command would cause a break before math operators <code>'+'</code>, <code>'-'</code>, <code>'/'</code>, and <code>'*'</code>:</p></dd><dd><pre>\n -wbb="+ - / *"</pre></dd><dd><p>These commands should work well for most of the token types that perltidy uses (use <strong>--dump-token-types</strong> for a list). Also try the <strong>-D</strong> flag on a short snippet of code and look at the .DEBUG file to see the tokenization. However, for a few token types there may be conflicts with hardwired logic which cause unexpected results. One example is curly braces, which should be controlled with the parameter <strong>bl</strong> provided for that purpose.</p></dd></html>"
|
||
|
|
EditorType=string
|
||
|
|
Enabled=false
|
||
|
|
ValueDefault=
|
||
|
|
|
||
|
|
[Want left space]
|
||
|
|
CallName="--want-left-space="
|
||
|
|
Category=3
|
||
|
|
Description="<html><dd><p>For those who want more detailed control over the whitespace around tokens, there are four parameters which can directly modify the default whitespace rules built into perltidy for any token. They are:</p></dd><dd><p><strong>-wls=s</strong> or <strong>--want-left-space=s</strong>,</p></dd><dd><p><strong>-nwls=s</strong> or <strong>--nowant-left-space=s</strong>,</p></dd><dd><p><strong>-wrs=s</strong> or <strong>--want-right-space=s</strong>,</p></dd><dd><p><strong>-nwrs=s</strong> or <strong>--nowant-right-space=s</strong>.</p></dd><dd><p>These parameters are each followed by a quoted string, <strong>s</strong>, containing a list of token types. 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.</p></dd><dd><p>To illustrate how these are used, suppose it is desired that there be no space on either side of the token types <strong>= + - / *</strong>. The following two parameters would specify this desire:</p></dd><dd><pre>\n -nwls="= + - / *" -nwrs="= + - / *"</pre></dd><dd><p>(Note that the token types are in quotes, and that they are separated by spaces). With these modified whitespace rules, the following line of math:</p></dd><dd><pre>\n $root = -$b + sqrt( $b * $b - 4. * $a * $c ) / ( 2. * $a );</pre></dd><dd><p>becomes this:</p></dd><dd><pre>\n $root=-$b+sqrt( $b*$b-4.*$a*$c )/( 2.*$a );</pre></dd><dd><p>These parameters should be considered to be hints to perltidy rather than fixed rules, because perltidy must try to resolve conflicts that arise between them and all of the other rules that it uses. One conflict that can arise is if, between two tokens, the left token wants a space and the right one doesn't. In this case, the token not wanting a space takes priority.</p></dd><dd><p>It is necessary to have a list of all token types in order to create this type of input. Such a list can be obtained by the command <strong>--dump-token-types</strong>. Also try the <strong>-D</strong> flag on a short snippet of code and look at the .DEBUG file to see the tokenization.</p></dd><dd><p><strong>WARNING</strong> Be sure to put these tokens in quotes to avoid having them misinterpreted by your command shell.</p></dd></html>"
|
||
|
|
EditorType=string
|
||
|
|
Enabled=false
|
||
|
|
ValueDefault=
|
||
|
|
|
||
|
|
[Want right space]
|
||
|
|
CallName="--want-right-space="
|
||
|
|
Category=3
|
||
|
|
Description="<html><dd><p>For those who want more detailed control over the whitespace around tokens, there are four parameters which can directly modify the default whitespace rules built into perltidy for any token. They are:</p></dd><dd><p><strong>-wls=s</strong> or <strong>--want-left-space=s</strong>,</p></dd><dd><p><strong>-nwls=s</strong> or <strong>--nowant-left-space=s</strong>,</p></dd><dd><p><strong>-wrs=s</strong> or <strong>--want-right-space=s</strong>,</p></dd><dd><p><strong>-nwrs=s</strong> or <strong>--nowant-right-space=s</strong>.</p></dd><dd><p>These parameters are each followed by a quoted string, <strong>s</strong>, containing a list of token types. 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.</p></dd><dd><p>To illustrate how these are used, suppose it is desired that there be no space on either side of the token types <strong>= + - / *</strong>. The following two parameters would specify this desire:</p></dd><dd><pre>\n -nwls="= + - / *" -nwrs="= + - / *"</pre></dd><dd><p>(Note that the token types are in quotes, and that they are separated by spaces). With these modified whitespace rules, the following line of math:</p></dd><dd><pre>\n $root = -$b + sqrt( $b * $b - 4. * $a * $c ) / ( 2. * $a );</pre></dd><dd><p>becomes this:</p></dd><dd><pre>\n $root=-$b+sqrt( $b*$b-4.*$a*$c )/( 2.*$a );</pre></dd><dd><p>These parameters should be considered to be hints to perltidy rather than fixed rules, because perltidy must try to resolve conflicts that arise between them and all of the other rules that it uses. One conflict that can arise is if, between two tokens, the left token wants a space and the right one doesn't. In this case, the token not wanting a space takes priority.</p></dd><dd><p>It is necessary to have a list of all token types in order to create this type of input. Such a list can be obtained by the command <strong>--dump-token-types</strong>. Also try the <strong>-D</strong> flag on a short snippet of code and look at the .DEBUG file to see the tokenization.</p></dd><dd><p><strong>WARNING</strong> Be sure to put these tokens in quotes to avoid having them misinterpreted by your command shell.</p></dd></html>"
|
||
|
|
EditorType=string
|
||
|
|
Enabled=false
|
||
|
|
ValueDefault=
|
||
|
|
|
||
|
|
[Break at old comma breakpoints]
|
||
|
|
Category=7
|
||
|
|
Description="<html><dd><p>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:</p></dd><dd><pre>\n my @list = (1,\n 1, 1,\n 1, 2, 1,\n 1, 3, 3, 1,\n 1, 4, 6, 4, 1,);</pre></dd><dd><p>The default formatting will flatten this down to one line:</p></dd><dd><pre>\n # perltidy (default)\n my @list = ( 1, 1, 1, 1, 2, 1, 1, 3, 3, 1, 1, 4, 6, 4, 1, );</pre></dd><dd><p>which hides the structure. Using <strong>-boc</strong>, plus additional flags to retain the original style, yields</p></dd><dd><pre>\n # perltidy -boc -lp -pt=2 -vt=1 -vtc=1\n my @list = (1,\n 1, 1,\n 1, 2, 1,\n 1, 3, 3, 1,\n 1, 4, 6, 4, 1,);</pre></dd><dd><p>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 Skipping Selected Sections of Code.</p></dd></html>"
|
||
|
|
EditorType=boolean
|
||
|
|
TrueFalse=--break-at-old-comma-breakpoints|
|
||
|
|
ValueDefault=0
|
||
|
|
|
||
|
|
[Maximum fields per table]
|
||
|
|
CallName="--maximum-fields-per-table="
|
||
|
|
Category=7
|
||
|
|
Description="<html><dd><p>If the computed number of fields for any table exceeds <strong>n</strong>, then it will be reduced to <strong>n</strong>. The default value for <strong>n</strong> is a large number, 40. While this value should probably be left unchanged as a general rule, it might be used on a small section of code to force a list to have a particular number of fields per line, and then either the <strong>-boc</strong> flag could be used to retain this formatting, or a single comment could be introduced somewhere to freeze the formatting in future applications of perltidy.</p></dd><dd><pre>\n # perltidy -mft=2\n @month_of_year = ( \n 'Jan', 'Feb',\n 'Mar', 'Apr',\n 'May', 'Jun',\n 'Jul', 'Aug',\n 'Sep', 'Oct',\n 'Nov', 'Dec'\n );</pre></dd></html>"
|
||
|
|
EditorType=numeric
|
||
|
|
Enabled=false
|
||
|
|
MaxVal=9999
|
||
|
|
MinVal=0
|
||
|
|
ValueDefault=40
|
||
|
|
|
||
|
|
[Comma arrow breakpoints]
|
||
|
|
CallName="--comma-arrow-breakpoints="
|
||
|
|
Category=7
|
||
|
|
Description="<html><dd><p>A comma which follows a comma arrow, '=>', requires special consideration. In a long list, it is common to break at all such commas. This parameter can be used to control how perltidy breaks at these commas. (However, it will have no effect if old comma breaks are being forced because <strong>-boc</strong> is used). The possible values of <strong>n</strong> are:</p></dd><dd><pre>\n n=0 break at all commas after => \n n=1 stable: break at all commas after => unless this would break\n an existing one-line container (default)\n n=2 break at all commas after =>, but try to form the maximum\n maximum one-line container lengths\n n=3 do not treat commas after => specially at all</pre></dd><dd><p>For example, given the following single line, perltidy by default will not add any line breaks because it would break the existing one-line container:</p></dd><dd><pre>\n bless { B => $B, Root => $Root } => $package;</pre></dd><dd><p>Using <strong>-cab=0</strong> will force a break after each comma-arrow item:</p></dd><dd><pre>\n # perltidy -cab=0:\n bless {\n B => $B,\n Root => $Root\n } => $package;</pre></dd><dd><p>If perltidy is subsequently run with this container broken, then by default it will break after each '=>' because the container is now broken. To reform a one-line container, the parameter <strong>-cab=2</strong> would be needed.</p></dd><dd><p>The flag <strong>-cab=3</strong> can be used to prevent these commas from being treated specially. In this case, an item such as ``01'' => 31 is 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.</p></dd><dd><pre>\n # perltidy -cab=3\n my %last_day = (\n "01" => 31, "02" => 29, "03" => 31, "04" => 30,\n "05" => 31, "06" => 30, "07" => 31, "08" => 31,\n "09" => 30, "10" => 31, "11" => 30, "12" => 31\n );</pre></dd></html>"
|
||
|
|
EditorType=numeric
|
||
|
|
Enabled=false
|
||
|
|
MaxVal=3
|
||
|
|
MinVal=0
|
||
|
|
ValueDefault=3
|
||
|
|
|
||
|
|
[Break at old logical breakpoints]
|
||
|
|
Category=8
|
||
|
|
Description="<html><p>By default, if a logical expression is broken at a <code>&&</code>, <code>||</code>, <code>and</code>, or <code>or</code>, then the container will remain broken. Also, breaks at internal keywords <code>if</code> and <code>unless</code> will normally be retained. To prevent this, and thus form longer lines, use <strong>-nbol</strong>.</p></html>"
|
||
|
|
EditorType=boolean
|
||
|
|
TrueFalse=--break-at-old-logical-breakpoints|
|
||
|
|
ValueDefault=0
|
||
|
|
|
||
|
|
[Break at old keyword breakpoints]
|
||
|
|
Category=8
|
||
|
|
Description="<html><p>By default, perltidy will retain a breakpoint before keywords which may return lists, such as <code>sort</code> and <map>. This allows chains of these operators to be displayed one per line. Use <strong>-nbok</strong> to prevent retaining these breakpoints.</p></html>"
|
||
|
|
EditorType=boolean
|
||
|
|
TrueFalse=--break-at-old-keyword-breakpoints|
|
||
|
|
ValueDefault=0
|
||
|
|
|
||
|
|
[Break at old ternary breakpoints]
|
||
|
|
Category=8
|
||
|
|
Description="<html><p>By default, if a conditional (ternary) operator is broken at a <code>:</code>, then it will remain broken. To prevent this, and thereby form longer lines, use <strong>-nbot</strong>.</p></html>"
|
||
|
|
EditorType=boolean
|
||
|
|
TrueFalse=--break-at-old-ternary-breakpoints|
|
||
|
|
ValueDefault=0
|
||
|
|
|
||
|
|
[Ignore old breakpoints]
|
||
|
|
Category=8
|
||
|
|
Description="<html><p>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.</p></html>"
|
||
|
|
EditorType=boolean
|
||
|
|
TrueFalse=--ignore-old-breakpoints|
|
||
|
|
ValueDefault=0
|
||
|
|
|
||
|
|
[Keep interior semicolons]
|
||
|
|
Category=8
|
||
|
|
Description="<html><dd><p>Use the <strong>-kis</strong> flag to prevent breaking at a semicolon if there was no break there in the input file. Normally perltidy places a newline after each semicolon which terminates a statement unless several statements are contained within a one-line brace block. To illustrate, consider the following input lines:</p></dd><dd><pre>\n dbmclose(%verb_delim); undef %verb_delim;\n dbmclose(%expanded); undef %expanded;</pre></dd><dd><p>The default is to break after each statement, giving</p></dd><dd><pre>\n dbmclose(%verb_delim);\n undef %verb_delim;\n dbmclose(%expanded);\n undef %expanded;</pre></dd><dd><p>With <strong>perltidy -kis</strong> the multiple statements are retained:</p></dd><dd><pre>\n dbmclose(%verb_delim); undef %verb_delim;\n dbmclose(%expanded); undef %expanded;</pre></dd><dd><p>The statements are still subject to the specified value of <strong>maximum-line-length</strong> and will be broken if this maximum is exceeed.</p></dd></html>"
|
||
|
|
EditorType=boolean
|
||
|
|
TrueFalse=--keep-interior-semicolons|
|
||
|
|
ValueDefault=0
|
||
|
|
|
||
|
|
[Blanks before comments]
|
||
|
|
Category=9
|
||
|
|
Description="<html><p>A blank line will be introduced before a full-line comment. This is the default. Use <strong>-nbbc</strong> or <strong>--noblanks-before-comments</strong> to prevent such blank lines from being introduced.</p></html>"
|
||
|
|
EditorType=boolean
|
||
|
|
TrueFalse=--blanks-before-comments|
|
||
|
|
ValueDefault=0
|
||
|
|
|
||
|
|
[Blanks before subs]
|
||
|
|
Category=9
|
||
|
|
Description="<html><p>A blank line will be introduced before a <strong>sub</strong> definition, unless it is a one-liner or preceded by a comment. A blank line will also be introduced before a <strong>package</strong> statement and a <strong>BEGIN</strong> and <strong>END</strong> block. This is the default. The intention is to help display the structure of a program by setting off certain key sections of code. This is negated with <strong>-nbbs</strong> or <strong>--noblanks-before-subs</strong>.</p></html>"
|
||
|
|
EditorType=boolean
|
||
|
|
TrueFalse=--blanks-before-subs|
|
||
|
|
ValueDefault=0
|
||
|
|
|
||
|
|
[Blanks before blocks]
|
||
|
|
Category=9
|
||
|
|
Description="<html><dd><p>A blank line will be introduced before blocks of coding delimited by <strong>for</strong>, <strong>foreach</strong>, <strong>while</strong>, <strong>until</strong>, and <strong>if</strong>, <strong>unless</strong>, in the following circumstances:</p></dd><ul><li><p>The block is not preceded by a comment.</p></li><li><p>The block is not a one-line block.</p></li><li><p>The number of consecutive non-blank lines at the current indentation depth is at least <strong>-lbl</strong> (see next section).</p></li></ul><p>This is the default. The intention of this option is to introduce some space within dense coding. This is negated with <strong>-nbbb</strong> or <strong>--noblanks-before-blocks</strong>.</p></html>"
|
||
|
|
EditorType=boolean
|
||
|
|
TrueFalse=--blanks-before-blocks|
|
||
|
|
ValueDefault=0
|
||
|
|
|
||
|
|
[Long block line count]
|
||
|
|
CallName="--long-block-line-count="
|
||
|
|
Category=9
|
||
|
|
Description="<html><p>This controls how often perltidy is allowed to add blank lines before certain block types (see previous section). The default is 8. Entering a value of <strong>0</strong> is equivalent to entering a very large number.</p></html>"
|
||
|
|
EditorType=numeric
|
||
|
|
Enabled=false
|
||
|
|
MaxVal=9999
|
||
|
|
MinVal=0
|
||
|
|
ValueDefault=8
|
||
|
|
|
||
|
|
[Maximum consecutive blank lines]
|
||
|
|
CallName="--maximum-consecutive-blank-lines="
|
||
|
|
Category=9
|
||
|
|
Description="<html><p>This parameter specifies the maximum number of consecutive blank lines in the output script. The default is n=1. If the input file has more than n consecutive blank lines, the number will be reduced to n. (This obviously does not apply to pod sections, here-documents, and quotes).</p></html>"
|
||
|
|
EditorType=numeric
|
||
|
|
Enabled=false
|
||
|
|
MaxVal=9999
|
||
|
|
MinVal=0
|
||
|
|
ValueDefault=1
|
||
|
|
|
||
|
|
[Keep old blank lines]
|
||
|
|
CallName="--keep-old-blank-lines="
|
||
|
|
Category=9
|
||
|
|
Description="<html><p>The <strong>-kbl=n</strong> flag gives you control over how your existing blank lines are treated.</p><p>The possible values of <strong>n</strong> are:</p><pre>\n n=0 ignore all old blank lines\n n=1 stable: keep old blanks, but limited by the value of the B<-mbl=n> flag\n n=2 keep all old blank lines, regardless of the value of the B<-mbl=n> flag</pre><p>The default is <strong>n=1</strong>.</p></html>"
|
||
|
|
EditorType=numeric
|
||
|
|
Enabled=false
|
||
|
|
MaxVal=9999
|
||
|
|
MinVal=0
|
||
|
|
ValueDefault=1
|
||
|
|
|
||
|
|
[Swallow optional blank lines]
|
||
|
|
Category=9
|
||
|
|
Description="<html><p>All blank lines not required by the above flags, <strong>-bbb</strong>, <strong>-bbs</strong>, and <strong>-bbc</strong>, will be deleted. (But essential blank lines above pod documents will be retained). This is NOT the default.</p></html>"
|
||
|
|
EditorType=boolean
|
||
|
|
TrueFalse=--swallow-optional-blank-lines|
|
||
|
|
ValueDefault=0
|
||
|
|
|
||
|
|
[Noswallow optional blank lines]
|
||
|
|
Category=9
|
||
|
|
Description="<html><p>Retain blank lines, including those which do not corresponding to flags <strong>-bbb</strong>, <strong>-bbs</strong>, and <strong>-bbc</strong>. This is the default. The number of blanks retained is subject to the limit imposed by <strong>--maximum-consecutive-blank-lines</strong>, however.</p></html>"
|
||
|
|
EditorType=boolean
|
||
|
|
TrueFalse=--noswallow-optional-blank-lines|
|
||
|
|
ValueDefault=0
|
||
|
|
|
||
|
|
[Delete all comments]
|
||
|
|
Category=10
|
||
|
|
Description="<html><p>Perltidy can selectively delete comments and/or pod documentation. The command <strong>-dac</strong> or <strong>--delete-all-comments</strong> will delete all comments <strong>and</strong> all pod documentation, leaving just code and any leading system control lines.</p></html>"
|
||
|
|
EditorType=boolean
|
||
|
|
TrueFalse=--delete-all-comments|
|
||
|
|
ValueDefault=0
|
||
|
|
|
||
|
|
[Delete pod]
|
||
|
|
Category=10
|
||
|
|
Description="<html><p>The command <strong>-dp</strong> or <strong>--delete-pod</strong> will remove all pod documentation (but not comments).</p></html>"
|
||
|
|
EditorType=boolean
|
||
|
|
TrueFalse=--delete-pod|
|
||
|
|
ValueDefault=0
|
||
|
|
|
||
|
|
[Delete block comments]
|
||
|
|
Category=10
|
||
|
|
Description="<html><p>Two commands which remove comments (but not pod) are: <strong>-dbc</strong> or <strong>--delete-block-comments</strong> and <strong>-dsc</strong> or <strong>--delete-side-comments</strong>. (Hanging side comments will be deleted with block comments here.)</p></html>"
|
||
|
|
EditorType=boolean
|
||
|
|
TrueFalse=--delete-block-comments|
|
||
|
|
ValueDefault=0
|
||
|
|
|
||
|
|
[Delete side comments]
|
||
|
|
Category=10
|
||
|
|
Description="<html><p>Two commands which remove comments (but not pod) are: <strong>-dbc</strong> or <strong>--delete-block-comments</strong> and <strong>-dsc</strong> or <strong>--delete-side-comments</strong>. (Hanging side comments will be deleted with block comments here.)</p></html>"
|
||
|
|
EditorType=boolean
|
||
|
|
TrueFalse=--delete-side-comments|
|
||
|
|
ValueDefault=0
|
||
|
|
|
||
|
|
[Tee all comments]
|
||
|
|
Category=10
|
||
|
|
Description="<html><p>When perltidy writes a formatted text file, it has the ability to also send selected text to a file with a <em>.TEE</em> extension. This text can include comments and pod documentation.</p><p>The command <strong>-tac</strong> or <strong>--tee-all-comments</strong> will write all comments <strong>and</strong> all pod documentation.</p></html>"
|
||
|
|
EditorType=boolean
|
||
|
|
TrueFalse=--tee-all-comments|
|
||
|
|
ValueDefault=0
|
||
|
|
|
||
|
|
[Tee pod]
|
||
|
|
Category=10
|
||
|
|
Description="<html><p>When perltidy writes a formatted text file, it has the ability to also send selected text to a file with a <em>.TEE</em> extension. This text can include comments and pod documentation.</p><p>The command <strong>-tp</strong> or <strong>--tee-pod</strong> will write all pod documentation (but not comments).</p></html>"
|
||
|
|
EditorType=boolean
|
||
|
|
TrueFalse=--tee-pod|
|
||
|
|
ValueDefault=0
|
||
|
|
|
||
|
|
[Tee block comments]
|
||
|
|
Category=10
|
||
|
|
Description="<html><p>When perltidy writes a formatted text file, it has the ability to also send selected text to a file with a <em>.TEE</em> extension. This text can include comments and pod documentation.</p><p>The commands which write comments (but not pod) are: <strong>-tbc</strong> or <strong>--tee-block-comments</strong> and <strong>-tsc</strong> or <strong>--tee-side-comments</strong>. (Hanging side comments will be written with block comments here.)</p></html>"
|
||
|
|
EditorType=boolean
|
||
|
|
TrueFalse=--tee-block-comments|
|
||
|
|
ValueDefault=0
|
||
|
|
|
||
|
|
[Tee side comments]
|
||
|
|
Category=10
|
||
|
|
Description="<html><p>When perltidy writes a formatted text file, it has the ability to also send selected text to a file with a <em>.TEE</em> extension. This text can include comments and pod documentation.</p><p>The commands which write comments (but not pod) are: <strong>-tbc</strong> or <strong>--tee-block-comments</strong> and <strong>-tsc</strong> or <strong>--tee-side-comments</strong>. (Hanging side comments will be written with block comments here.)</p></html>"
|
||
|
|
EditorType=boolean
|
||
|
|
TrueFalse=--tee-side-comments|
|
||
|
|
ValueDefault=0
|
||
|
|
|
||
|
|
[Look for hash bang]
|
||
|
|
Category=10
|
||
|
|
Description="<html><p>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 perl code by a ``hash-bang'' line, ( a line of the form <code>#!...perl</code> ), you must use the <strong>-x</strong> flag to tell perltidy not to parse and format any 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 allow perltidy to parse interactive VMS scripts, but it should be used for any script which is normally invoked with <code>perl -x</code>.</p></html>"
|
||
|
|
EditorType=boolean
|
||
|
|
TrueFalse=--look-for-hash-bang|
|
||
|
|
ValueDefault=0
|
||
|
|
|
||
|
|
[Making a file unreadable]
|
||
|
|
Category=10
|
||
|
|
Choices=--mangle|--extrude
|
||
|
|
ChoicesReadable=Mangle|Extrude
|
||
|
|
Description="<html><dd><p>The goal of perltidy is to improve the readability of files, but there are two commands which have the opposite effect, <strong>--mangle</strong> and <strong>--extrude</strong>. They are actually merely aliases for combinations of other parameters. Both of these strip all possible whitespace, but leave comments and pod documents, so that they are essentially reversible. The difference between these is that <strong>--mangle</strong> puts the fewest possible line breaks in a script while <strong>--extrude</strong> puts the maximum possible. Note that these options do not provided any meaningful obfuscation, because perltidy can be used to reformat the files. They were originally developed to help test the tokenization logic of perltidy, but they have other uses. One use for <strong>--mangle</strong> is the following:</p></dd><dd><pre>\n perltidy --mangle myfile.pl -st | perltidy -o myfile.pl.new</pre></dd><dd><p>This will form the maximum possible number of one-line blocks (see next section), and can sometimes help clean up a badly formatted script.</p></dd><dd><p>A similar technique can be used with <strong>--extrude</strong> instead of <strong>--mangle</strong> to make the minimum number of one-line blocks.</p></dd><dd><p>Another use for <strong>--mangle</strong> is to combine it with <strong>-dac</strong> to reduce the file size of a perl script.</p></dd></html>"
|
||
|
|
EditorType=multiple
|
||
|
|
Enabled=false
|
||
|
|
ValueDefault=0
|
||
|
|
|
||
|
|
[MakeMaker]
|
||
|
|
Category=10
|
||
|
|
Description="<html><p>The first $VERSION line of a file which might be eval'd by MakeMaker is passed through unchanged except for indentation. Use --nopass-version-line, or -npvl, to deactivate this feature.</p></html>"
|
||
|
|
EditorType=boolean
|
||
|
|
TrueFalse=--nopass-version-line|
|
||
|
|
ValueDefault=0
|
||
|
|
|
||
|
|
[AutoLoader]
|
||
|
|
Category=10
|
||
|
|
Description="<html><p>If the AutoLoader module is used, perltidy will continue formatting code after seeing an __END__ line. Use --nolook-for-autoloader, or -nlal, to deactivate this feature.</p></html>"
|
||
|
|
EditorType=boolean
|
||
|
|
TrueFalse=--nolook-for-autoloader|
|
||
|
|
ValueDefault=0
|
||
|
|
|
||
|
|
[SelfLoader]
|
||
|
|
Category=10
|
||
|
|
Description="<html><p>Likewise, if the SelfLoader module is used, perltidy will continue formatting code after seeing a __DATA__ line. Use --nolook-for-selfloader, or -nlsl, to deactivate this feature.</p></html>"
|
||
|
|
EditorType=boolean
|
||
|
|
TrueFalse=--nolook-for-selfloader|
|
||
|
|
ValueDefault=0
|