# HG changeset patch # User thomas_-_s # Date 1324993494 0 # Node ID a0f609a86954bd1cb5d068372fbcb78e7e12ac23 # Parent f55b7f34a3e1ea297a4bba43f15f0aed380a0801 Updated the perltidy config file to suit for version 1.74 of perltidy. git-svn-id: svn://svn.code.sf.net/p/universalindent/code/trunk@1055 59b1889a-e5ac-428c-b0c7-476e01d41282 diff -r f55b7f34a3e1 -r a0f609a86954 indenters/uigui_perltidy.ini --- a/indenters/uigui_perltidy.ini Tue Dec 27 13:28:58 2011 +0000 +++ b/indenters/uigui_perltidy.ini Tue Dec 27 13:44:54 2011 +0000 @@ -1,1006 +1,1040 @@ -[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=2007-12-05 - -[Add newlines] -Category=6 -Description="

By default, perltidy will add line breaks when necessary to create continuations of long lines and to improve the script appearance. Use -nanl or --noadd-newlines to prevent any new line breaks.

This flag does not prevent perltidy from eliminating existing line breaks; see --freeze-newlines to completely prevent changes to line break points.

" -EditorType=boolean -TrueFalse=-anl|-nanl -ValueDefault=0 - -[Add semicolons] -Category=3 -Description="

Setting -asc allows perltidy to add any missing optional semicolon at the end of a line which is followed by a closing curly brace on the next line. This is the default, and may be deactivated with -nasc or --noadd-semicolons.

" -EditorType=boolean -TrueFalse=--add-semicolons| -ValueDefault=0 - -[Add whitespace] -Category=3 -Description="

Setting this option allows perltidy to add certain whitespace improve code readability. This is the default. If you do not want any whitespace added, but are willing to have some whitespace deleted, use -naws. (Use -fws to leave whitespace completely unchanged).

" -EditorType=boolean -TrueFalse=--add-whitespace| -ValueDefault=0 - -[Block brace tightness] -CallName="--block-brace-tightness=" -Category=3 -Description="

And finally, curly braces which contain blocks of code are controlled by the parameter -bbt=n or --block-brace-tightness=n as illustrated in the example below.

\n %bf = map { $_ => -M $_ } grep { /deb$/ } dirents '.'; # -bbt=0 (default)\n %bf = map { $_ => -M $_ } grep {/deb$/} dirents '.';   # -bbt=1\n %bf = map {$_ => -M $_} grep {/deb$/} dirents '.';     # -bbt=2

" -EditorType=numeric -Enabled=false -MaxVal=2 -MinVal=0 -ValueDefault=1 - -[Block brace vertical tightness] -CallName="--block-brace-vertical-tightness=" -Category=6 -Description="

The -bbvt=n flag is just like the -vt=n flag but applies to opening code block braces.

\n -bbvt=0 break after opening block brace (default). \n -bbvt=1 do not break unless this would produce more than one \n         step in indentation in a line.\n -bbvt=2 do not break after opening block brace.

It is necessary to also use either -bl or -bli for this to work, because, as with other vertical tightness controls, it is implemented by simply overwriting a line ending with an opening block brace with the subsequent line. For example:

\n    # perltidy -bli -bbvt=0\n    if ( open( FILE, "< $File" ) )\n      {\n        while ( $File = <FILE> )\n          {\n            $In .= $File;\n            $count++;\n          }\n        close(FILE);\n      }

\n    # perltidy -bli -bbvt=1\n    if ( open( FILE, "< $File" ) )\n      { while ( $File = <FILE> )\n          { $In .= $File;\n            $count++;\n          }\n        close(FILE);\n      }

By default this applies to blocks associated with keywords if, elsif, else, unless, for, foreach, sub, while, until, and also with a preceding label. This can be changed with the parameter -bbvtl=string, or --block-brace-vertical-tightness-list=string, where string is a space-separated list of block types. For more information on the possible values of this string, see Specifying Block Types

For example, if we want to just apply this style to if, elsif, and else blocks, we could use perltidy -bli -bbvt=1 -bbvtl='if elsif else'.

There is no vertical tightness control for closing block braces; with the exception of one-line blocks, they will normally remain on a separate line.

" -EditorType=numeric -Enabled=false -MaxVal=2 -MinVal=0 -ValueDefault=0 - -[Brace left and indent] -Category=6 -Description="

The flag -bli is the same as -bl but in addition it causes one unit of continuation indentation ( see -ci ) to be placed before an opening and closing block braces.

For example,

\n        if ( $input_file eq '-' )    # -bli\n          {\n            important_function();\n          }

By default, this extra indentation occurs for blocks of type:if, elsif, else, unless, for, foreach, sub, while, until, and also with a preceding label. The next item shows how to change this.

" -EditorType=boolean -TrueFalse=-bli| -ValueDefault=0 - -[Brace left and indent list] -CallName="--brace-left-and-indent-list=" -Category=6 -Description="

Use this parameter to change the types of block braces for which the -bli flag applies; see Specifying Block Types. For example, -blil='if elsif else' would apply it to only if/elsif/else blocks.

" -EditorType=string -Enabled=false -ValueDefault= - -[Brace tightness] -CallName="--brace-tightness=" -Category=3 -Description="

Curly braces which do not contain code blocks are controlled by the parameter -bt=n or --brace-tightness=n.

\n $obj->{ $parsed_sql->{ 'table' }[0] };    # -bt=0\n $obj->{ $parsed_sql->{'table'}[0] };      # -bt=1 (default)\n $obj->{$parsed_sql->{'table'}[0]};        # -bt=2

" -EditorType=numeric -Enabled=false -MaxVal=2 -MinVal=0 -ValueDefault=1 - -[Brace vertical tightness] -CallName="--brace-vertical-tightness=" -Category=6 -Description="

The -vt=n and -vtc=n parameters apply to each type of container token. If desired, vertical tightness controls can be applied independently to each of the closing container token types.

In fact, the parameter -vt=n is actually just an abbreviation for -pvt=n -bvt=n sbvt=n, and likewise -vtc=n is an abbreviation for -pvtc=n -bvtc=n sbvtc=n.

" -EditorType=numeric -Enabled=false -MaxVal=2 -MinVal=0 -ValueDefault=0 - -[Brace vertical tightness closing] -CallName="--brace-vertical-tightness-closing=" -Category=6 -Description="

The -vt=n and -vtc=n parameters apply to each type of container token. If desired, vertical tightness controls can be applied independently to each of the closing container token types.

In fact, the parameter -vt=n is actually just an abbreviation for -pvt=n -bvt=n sbvt=n, and likewise -vtc=n is an abbreviation for -pvtc=n -bvtc=n sbvtc=n.

" -EditorType=numeric -Enabled=false -MaxVal=2 -MinVal=0 -ValueDefault=0 - -[Break after all operators] -Category=6 -Description="

The -baao sets the default to be to break after all of the following operators:

\n    % + - * / x != == >= <= =~ !~ < > | & \n    = **= += *= &= <<= &&= -= /= |= >>= ||= //= .= %= ^= x=\n    . : ? && || and or err xor

and the -bbao flag sets the default to break before all of these operators. These can be used to define an initial break preference which can be fine-tuned with the -wba and -wbb flags. For example, to break before all operators except an = one could use --bbao -wba='=' rather than listing every single perl operator except = on a -wbb flag.

" -EditorType=boolean -TrueFalse=-baao| -ValueDefault=0 - -[Break before all operators] -Category=6 -Description="

The -baao sets the default to be to break after all of the following operators:

\n    % + - * / x != == >= <= =~ !~ < > | & \n    = **= += *= &= <<= &&= -= /= |= >>= ||= //= .= %= ^= x=\n    . : ? && || and or err xor

" -EditorType=boolean -TrueFalse=-bbao| -ValueDefault=0 - -[Check syntax] -Category=1 -Description="This flag causes perltidy to run perl -c -T to check syntax of input and output. (To change the flags passed to perl, see the next item, -pscf). The results are written to the .LOG file, which will be saved if an error is detected in the output script. The output script is not checked if the input script has a syntax error. Perltidy does its own checking, but this option employs perl to get a ``second opinion''.

If perl reports errors in the input file, they will not be reported in the error output unless the --warning-output flag is given.

The default is not to do this type of syntax checking (although perltidy will still do as much self-checking as possible). The reason is that it causes all code in BEGIN blocks to be executed, for all modules being used, and this opens the door to security issues and infinite loops when running perltidy." -EditorType=boolean -Enabled=false -TrueFalse=--check-syntax| -ValueDefault=0 - -[Closing Side Comment Else Flag] -CallName="--closing-side-comment-else-flag=" -Category=4 -Description="

The default, n=0, places the text of the opening if statement after any terminal else.

If n=2 is used, then each elsif is also given the text of the opening if statement. Also, an else will include the text of a preceding elsif statement. Note that this may result some long closing side comments.

If n=1 is used, the results will be the same as n=2 whenever the resulting line length is less than the maximum allowed.

" -EditorType=numeric -Enabled=false -MaxVal=1000 -MinVal=0 -ValueDefault=0 - -[Closing Side Comment Interval] -CallName="--closing-side-comment-interval=" -Category=4 -Description="

where n is the minimum number of lines that a block must have in order for a closing side comment to be added. The default value is n=6. To illustrate:

\n        # perltidy -csci=2 -csc\n        sub message {\n            if ( !defined( $_[0] ) ) {\n                print("Hello, World\n");\n            } ## end if ( !defined( $_[0] ))\n            else {\n                print( $_[0], "\n" );\n            } ## end else [ if ( !defined( $_[0] ))\n        } ## end sub message

Now the if and else blocks are commented. However, now this has become very cluttered.

" -EditorType=numeric -Enabled=false -MaxVal=1000 -MinVal=0 -ValueDefault=6 - -[Closing Side Comment List] -CallName="--closing-side-comment-list=" -Category=4 -Description="

where string is a list of block types to be tagged with closing side comments. By default, all code block types preceded by a keyword or label (such as if, sub, and so on) will be tagged. The -cscl command changes the default list to be any selected block types; see Specifying Block Types. For example, the following command requests that only sub's, labels, BEGIN, and END blocks be affected by any -csc or -dcsc operation:

\n   -cscl="sub : BEGIN END"

" -EditorType=string -Enabled=false -ValueDefault= - -[Closing Side Comment Maximum Text] -CallName="--closing-side-comment-maximum-text=" -Category=4 -Description="

The text appended to certain block types, such as an if block, is whatever lies between the keyword introducing the block, such as if, and the opening brace. Since this might be too much text for a side comment, there needs to be a limit, and that is the purpose of this parameter. The default value is n=20, meaning that no additional tokens will be appended to this text after its length reaches 20 characters. Omitted text is indicated with .... (Tokens, including sub names, are never truncated, however, so actual lengths may exceed this). To illustrate, in the above example, the appended text of the first block is ( !defined( $_[0] ).... The existing limit of n=20 caused this text to be truncated, as indicated by the ....

" -EditorType=numeric -Enabled=false -MaxVal=1000 -MinVal=0 -ValueDefault=20 - -[Closing Side Comment Prefix] -CallName="--closing-side-comment-prefix=" -Category=4 -Description="

where string is the prefix used before the name of the block type. The default prefix, shown above, is ## end. This string will be added to closing side comments, and it will also be used to recognize them in order to update, delete, and format them. Any comment identified as a closing side comment will be placed just a single space to the right of its closing brace.

" -EditorType=string -Enabled=false -ValueDefault=## end - -[Closing Side Comment Warnings] -Category=4 -Description="

This parameter is intended to help make the initial transition to the use of closing side comments. It causes two things to happen if a closing side comment replaces an existing, different closing side comment: first, an error message will be issued, and second, the original side comment will be placed alone on a new specially marked comment line for later attention.

The intent is to avoid clobbering existing hand-written side comments which happen to match the pattern of closing side comments. This flag should only be needed on the first run with -csc.

" -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="

A closing side comment is a special comment which perltidy can automatically create and place after the closing brace of a code block. They can be useful for code maintenance and debugging. The command -csc (or --closing-side-comments) adds or updates closing side comments. For example, here is a small code snippet

\n        sub message {\n            if ( !defined( $_[0] ) ) {\n                print("Hello, World\n");\n            }\n            else {\n                print( $_[0], "\n" );\n            }\n        }

And here is the result of processing with perltidy -csc:

\n        sub message {\n            if ( !defined( $_[0] ) ) {\n                print("Hello, World\n");\n            }\n            else {\n                print( $_[0], "\n" );\n            }\n        } ## end sub message

A closing side comment was added for sub message in this case, but not for the if and else blocks, because they were below the 6 line cutoff limit for adding closing side comments. This limit may be changed with the -csci command, described below.

The command -dcsc (or --delete-closing-side-comments) reverses this process and removes these comments.

Several commands are available to modify the behavior of these two basic commands, -csc and -dcsc:

" -EditorType=multiple -Enabled=false -ValueDefault=0 - -[Closing token indentation] -CallName="--closing-token-indentation=" -Category=2 -Description="The -cti=n flag controls the indentation of a line beginning with a ), ], or a non-block }. Such a line receives:

\n -cti = 0 no extra indentation (default)\n -cti = 1 extra indentation such that the closing token\n        aligns with its opening token.\n -cti = 2 one extra indentation level if the line looks like:\n        );  or  ];  or  };\n -cti = 3 one extra indentation level always

The flags -cti=1 and -cti=2 work well with the -lp flag (previous section).

\n    # perltidy -lp -cti=1\n    @month_of_year = (\n                       'Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun',\n                       'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'\n                     );

\n    # perltidy -lp -cti=2\n    @month_of_year = (\n                       'Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun',\n                       'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'\n                       );

These flags are merely hints to the formatter and they may not always be followed. In particular, if -lp is not being used, the indentation forcti=1 is constrained to be no more than one indentation level.

If desired, this control can be applied independently to each of theclosing container token types. In fact, -cti=n is merely anabbreviation for -cpi=n -csbi=n -cbi=n, where: -cpi or --closing-paren-indentation controls )'s,-csbi or --closing-square-bracket-indentation controls ]'s, -cbi or --closing-brace-indentation controls non-block }'s." -EditorType=numeric -Enabled=false -MaxVal=1000 -MinVal=0 -ValueDefault=0 - -[Continuation indentation] -CallName="--continuation-indentation=" -Category=2 -Description="Continuation indentation is extra indentation spaces applied whena long line is broken. The default is n=2, illustrated here:

 my $level =   # -ci=2   ( $max_index_to_go >= 0 ) ? $levels_to_go[0] : $last_output_level;

The same example, with n=0, is a little harder to read:

 my $level =   # -ci=0 ( $max_index_to_go >= 0 ) ? $levels_to_go[0] : $last_output_level;

The value given to -ci is also used by some commands when a small space is required. Examples are commands for outdenting labels, -ola, and control keywords, -okw.

When default values are not used, it is suggested that the value n given with -ci=n be no more than about one-half of the number of spaces assigned to a full indentation level on the -i=n command." -EditorType=numeric -Enabled=false -MaxVal=1000 -MinVal=0 -ValueDefault=2 - -[Cuddled else] -Category=6 -Description="

Enable the ``cuddled else'' style, in which else and elsif are follow immediately after the curly brace closing the previous block. The default is not to use cuddled elses, and is indicated with the flag -nce or --nocuddled-else. Here is a comparison of the alternatives:

\n  if ($task) {\n      yyy();\n  } else {    # -ce\n      zzz();\n  }

\n  if ($task) {\n        yyy();\n  }\n  else {    # -nce  (default)\n        zzz();\n  }

" -EditorType=boolean -TrueFalse=-ce|-nce -ValueDefault=0 - -[Delete old newlines] -Category=6 -Description="

By default, perltidy first deletes all old line break locations, and then it looks for good break points to match the desired line length. Use -ndnl or --nodelete-old-newlines to force perltidy to retain all old line break points.

" -EditorType=boolean -TrueFalse=-dnl|-ndnl -ValueDefault=0 - -[Delete old whitespace] -Category=3 -Description="

Setting this option allows perltidy to remove some old whitespace between characters, if necessary. This is the default. If you do not want any old whitespace removed, use -ndws or --nodelete-old-whitespace.

" -EditorType=boolean -TrueFalse=--delete-old-whitespace| -ValueDefault=0 - -[Delete semicolons] -Category=3 -Description="

Setting -dsm allows perltidy to delete extra semicolons which are simply empty statements. This is the default, and may be deactivated with -ndsm or --nodelete-semicolons. (Such semicolons are not deleted, however, if they would promote a side comment to a block comment).

" -EditorType=boolean -TrueFalse=--delete-semicolons| -ValueDefault=0 - -[Entab leading whitespace] -CallName="--entab-leading-whitespace=" -Category=1 -Description="This flag causes each n initial space characters to be replaced by one tab character. Note that the integer n is completely independent of the integer specified for indentation parameter, -i=n." -EditorType=numeric -Enabled=false -MaxVal=1000 -MinVal=0 -ValueDefault=4 - -[Feeze newlines] -Category=6 -Description="

If you do not want any changes to the line breaks in your script, set -fnl, and they will remain fixed, and the rest of the commands in this section and sections Controlling List Formatting, Retaining or Ignoring Existing Line Breaks, and Blank Line Control will be ignored. You may want to use -noll with this.

" -EditorType=boolean -TrueFalse=-fnl| -ValueDefault=0 - -[Fixed position side comment] -CallName="--fixed-position-side-comment=" -Category=4 -Description="

This parameter tells perltidy to line up side comments in column number n whenever possible. The default, n=0, is not do do this.

" -EditorType=numeric -Enabled=false -MaxVal=1000 -MinVal=0 -ValueDefault=0 - -[Format skipping] -Category=5 -Description="

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 --noformat-skipping or -nfs flag. It should be used sparingly to avoid littering code with markers, but it might be helpful for working around occasional problems. For example it might be useful for keeping the indentation of old commented code unchanged, keeping indentation of long blocks of aligned comments unchanged, keeping certain list formatting unchanged, or working around a glitch in perltidy.

-fs, --format-skipping

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

\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 #>>>

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 .LOG file. Use -nfs to disable this feature.

The -fsb=string parameter may be used to change the beginning marker for format skipping. The default is equivalent to -fsb='#<<<'. The string that you enter must begin with a # and should be in quotes as necessary to get past 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.

Some examples show how example strings become patterns:

\n -fsb='#' becomes /^#/  which matches  #{{{ but not #{{{{\n -fsb='#'   becomes /^#/    which matches  #** but not #***\n -fsb='#{2,}' becomes /^#{2,}/  which matches  #** and #*****

The -fsb=string is the corresponding parameter used to change the ending marker for format skipping. The default is equivalent to -fse='#<<<'.

-gnu 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:

\n    -lp -bl -noll -pt=2 -bt=2 -sbt=2 -icp

By default, perltidy tries to identify and align ``hanging side comments'', which are something like this:

\n        my $IGNORE = 0;    # This is a side comment\n                           # This is a hanging side comment\n                           # And so is this

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 -nhsc or --nohanging-side-comments. If block comments are preceded by a blank line, or have no leading whitespace, they will not be mistaken as hanging side comments.

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 -nibc to keep block comments left-justified. Here is an example:

\n             # this comment is indented      (-ibc, default)\n             if ($task) { yyy(); }

The alternative is -nibc:

\n # this comment is not indented              (-nibc)\n             if ($task) { yyy(); }

See also the next item, -isbc, as well as -sbc, for other ways to have some indented and some outdented block comments.

-icb

\n        if ($task) {\n            yyy();\n            }    # -icb\n        else {\n            zzz();\n            }

The default is not to do this, indicated by -nicb." -EditorType=boolean -TrueFalse=--indent-closing-brace| -ValueDefault=0 - -[Indent closing paren] -Category=2 -Description="The -icp flag is equivalent to-cti=2, described in the previous section. The -nicp flag is equivalent -cti=0. They are included for backwards compatability." -EditorType=boolean -TrueFalse=--indent-closing-paren| -ValueDefault=0 - -[Indent columns] -CallName="--indent-columns=" -Category=1 -Description="Use n columns per indentation level (default n=4)." -EditorType=numeric -Enabled=false -MaxVal=1000 -MinVal=0 -ValueDefault=4 - -[Indent only] -Category=1 -Description="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).

Setting this flag is equivalent to setting --freeze-newlines and--freeze-whitespace." -EditorType=boolean -Enabled=false -TrueFalse=--indent-only| -ValueDefault=0 - -[Indent spaced block comments] -Category=4 -Description="

If there is no leading space on the line, then the comment will not be indented, and otherwise it may be.

If both -ibc and -isbc are set, then -isbc takes priority.

-i=n

\n    # perltidy (default)\n    @month_of_year = (\n        'Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun',\n        'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'\n    );

Use the -lp 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:

\n    # perltidy -lp\n    @month_of_year = (\n                       'Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun',\n                       'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'\n    );

If the available line length (see -l=n ) does not permit this much space, perltidy will use less. For alternate placement of the closing paren, see the next section.

This option has no effect on code BLOCKS, such as if/then/else blocks, which always use whatever is specified with -i=n. Also, the existence of line breaks and/or block comments between the opening and closing parens may cause perltidy to temporarily revert to its default method.

Note: The -lp option may not be used together with the -t tabs option. It may, however, be used with the -et=n tab method.

In addition, any parameter which significantly restricts the ability of perltidy to choose newlines will conflict with -lp and will cause -lp to be deactivated. These include -io, -fnl, -nanl, and -ndnl. The reason is that the -lp indentation style can require the careful coordination of an arbitrary number of break points in hierarchical lists, and these flags may prevent that." -EditorType=boolean -TrueFalse=--line-up-parentheses| -ValueDefault=0 - -[Maximum line length] -CallName="--maximum-line-length=" -Category=1 -Description="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 -l=0 is equivalent to setting -l=(a large number)." -EditorType=numeric -Enabled=false -MaxVal=1000 -MinVal=0 -ValueDefault=80 - -[Minimum space to comment] -CallName="--minimum-space-to-comment=" -Category=4 -Description="

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.

When an opening paren follows a Perl keyword, no space is introduced after the keyword, unless it is (by default) one of these:

\n   my local our and or eq ne if else elsif until unless \n   while for foreach return switch case given when

These defaults can be modified with two commands:

-sak=s or --space-after-keyword=s adds keywords.

-nsak=s or --nospace-after-keyword=s removes keywords.

where s is a list of keywords (in quotes if necessary). For example,

\n  my ( $a, $b, $c ) = @_;    # default\n  my( $a, $b, $c ) = @_;     # -nsak="my local our"

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:

-wls=s or --want-left-space=s,

-nwls=s or --nowant-left-space=s,

-wrs=s or --want-right-space=s,

-nwrs=s or --nowant-right-space=s.

These parameters are each followed by a quoted string, s, 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.

To illustrate how these are used, suppose it is desired that there be no space on either side of the token types = + - / *. The following two parameters would specify this desire:

\n  -nwls="= + - / *"    -nwrs="= + - / *"

(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:

\n  $root = -$b + sqrt( $b * $b - 4. * $a * $c ) / ( 2. * $a );

becomes this:

\n  $root=-$b+sqrt( $b*$b-4.*$a*$c )/( 2.*$a );

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.

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 --dump-token-types. Also try the -D flag on a short snippet of code and look at the .DEBUG file to see the tokenization.

WARNING Be sure to put these tokens in quotes to avoid having them misinterpreted by your command shell.

-wls=s or --want-left-space=s,

-nwls=s or --nowant-left-space=s,

-wrs=s or --want-right-space=s,

-nwrs=s or --nowant-right-space=s.

To illustrate how these are used, suppose it is desired that there be no space on either side of the token types = + - / *. The following two parameters would specify this desire:

\n  -nwls="= + - / *"    -nwrs="= + - / *"

(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:

\n  $root = -$b + sqrt( $b * $b - 4. * $a * $c ) / ( 2. * $a );

becomes this:

\n  $root=-$b+sqrt( $b*$b-4.*$a*$c )/( 2.*$a );

WARNING Be sure to put these tokens in quotes to avoid having them misinterpreted by your command shell.

The default style, -nbl 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:

\n        if ( $bigwasteofspace1 && $bigwasteofspace2\n          || $bigwasteofspace3 && $bigwasteofspace4 )\n        {\n            big_waste_of_time();\n        }

To force the opening brace to always be on the right, use the -bar flag. In this case, the above example becomes

\n        if ( $bigwasteofspace1 && $bigwasteofspace2\n          || $bigwasteofspace3 && $bigwasteofspace4 ) {\n            big_waste_of_time();\n        }

A conflict occurs if both -bl and -bar are specified.

Use the flag -bl to place the opening brace on a new line:

\n  if ( $input_file eq '-' )    # -bl \n  {                          \n      important_function();\n  }

This flag applies to all structural blocks, including sub's (unless the -sbl flag is set -- see next item).

The default style, -nbl, places an opening brace on the same line as the keyword introducing it. For example,

\n  if ( $input_file eq '-' ) {   # -nbl (default)

The -otr flag is a hint that perltidy should not place a break between a comma and an opening token. For example:

\n    # default formatting\n    push @{ $self->{$module}{$key} },\n      {\n        accno       => $ref->{accno},\n        description => $ref->{description}\n      };

\n    # perltidy -otr\n    push @{ $self->{$module}{$key} }, {\n        accno       => $ref->{accno},\n        description => $ref->{description}\n      };

The flag -otr is actually a synonym for three other flags which can be used to control parens, hash braces, and square brackets separately if desired:

\n  -opr  or --opening-paren-right\n  -ohbr or --opening-hash-brace-right\n  -osbr or --opening-square-bracket-right

The -otr flag is a hint that perltidy should not place a break between a comma and an opening token. For example:

\n    # default formatting\n    push @{ $self->{$module}{$key} },\n      {\n        accno       => $ref->{accno},\n        description => $ref->{description}\n      };

\n    # perltidy -otr\n    push @{ $self->{$module}{$key} }, {\n        accno       => $ref->{accno},\n        description => $ref->{description}\n      };

The flag -otr is actually a synonym for three other flags which can be used to control parens, hash braces, and square brackets separately if desired:

\n  -opr  or --opening-paren-right\n  -ohbr or --opening-hash-brace-right\n  -osbr or --opening-square-bracket-right

The -otr flag is a hint that perltidy should not place a break between a comma and an opening token. For example:

\n    # default formatting\n    push @{ $self->{$module}{$key} },\n      {\n        accno       => $ref->{accno},\n        description => $ref->{description}\n      };

\n    # perltidy -otr\n    push @{ $self->{$module}{$key} }, {\n        accno       => $ref->{accno},\n        description => $ref->{description}\n      };

The flag -otr is actually a synonym for three other flags which can be used to control parens, hash braces, and square brackets separately if desired:

\n  -opr  or --opening-paren-right\n  -ohbr or --opening-hash-brace-right\n  -osbr or --opening-square-bracket-right

The flag -sbl can be used to override the value of -bl for opening sub braces. For example,

\n perltidy -sbl

produces this result:

\n sub message\n {\n    if (!defined($_[0])) {\n        print("Hello, World\n");\n    }\n    else {\n        print($_[0], "\n");\n    }\n }

This flag is negated with -nsbl. If -sbl is not specified, the value of -bl is used.

The -otr flag is a hint that perltidy should not place a break between a comma and an opening token. For example:

\n    # default formatting\n    push @{ $self->{$module}{$key} },\n      {\n        accno       => $ref->{accno},\n        description => $ref->{description}\n      };

\n    # perltidy -otr\n    push @{ $self->{$module}{$key} }, {\n        accno       => $ref->{accno},\n        description => $ref->{description}\n      };

The flag -otr is actually a synonym for three other flags which can be used to control parens, hash braces, and square brackets separately if desired:

\n  -opr  or --opening-paren-right\n  -ohbr or --opening-hash-brace-right\n  -osbr or --opening-square-bracket-right

-okwstring-okw

For example, the commands -okwl="next last redo goto" -okw will cause those four keywords to be outdented. It is probably simplest to place any -okwl command in a .perltidyrc file." -EditorType=string -Enabled=false -ValueDefault= - -[Outdent long comments] -Category=4 -Description="

When -olc is set, lines which are full-line (block) comments longer than the value maximum-line-length will have their indentation removed. This is the default; use -nolc to prevent outdenting.

--outdent-long-quotes--outdent-long-comments-noll--nooutdent-long-lines-nolq-nolc-olqmaximum-line-length-nolq--nooutdent-long-lines-okw-ciredonextlastgotoreturn

For example, using perltidy -okw on the previous example gives:

\n        my $i;\n      LOOP: while ( $i = <FOTOS> ) {\n            chomp($i);\n          next unless $i;\n            fixit($i);\n        }

The default is not to do this." -EditorType=boolean -TrueFalse=--outdent-keywords| -ValueDefault=0 - -[Outdenting Labels] -Category=2 -Description="This command will cause labels to be outdented by 2 spaces (or whatever -ci has been set to), if possible. This is the default. For example:

\n        my $i;\n      LOOP: while ( $i = <FOTOS> ) {\n            chomp($i);\n            next unless $i;\n            fixit($i);\n        }

Use -nola to not outdent labels." -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="where s=win, dos, unix, or mac. 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 win and dos flags have an identical result." -EditorType=multiple -Enabled=false -ValueDefault=1 - -[Paren tightness] -CallName="--paren-tightness=" -Category=3 -Description="

The -pt=n or --paren-tightness=n parameter controls the space within parens. The example below shows the effect of the three possible values, 0, 1, and 2:

\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

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." -EditorType=numeric -Enabled=false -MaxVal=2 -MinVal=0 -ValueDefault=1 - -[Paren vertical tightness] -CallName="--paren-vertical-tightness=" -Category=6 -Description="

The -vt=n and -vtc=n parameters apply to each type of container token. If desired, vertical tightness controls can be applied independently to each of the closing container token types.

In fact, the parameter -vt=n is actually just an abbreviation for -pvt=n -bvt=n sbvt=n, and likewise -vtc=n is an abbreviation for -pvtc=n -bvtc=n sbvtc=n.

" -EditorType=numeric -Enabled=false -MaxVal=2 -MinVal=0 -ValueDefault=0 - -[Paren vertical tightness closing] -CallName="--paren-vertical-tightness-closing=" -Category=6 -Description="

The -vt=n and -vtc=n parameters apply to each type of container token. If desired, vertical tightness controls can be applied independently to each of the closing container token types.

In fact, the parameter -vt=n is actually just an abbreviation for -pvt=n -bvt=n sbvt=n, and likewise -vtc=n is an abbreviation for -pvtc=n -bvtc=n sbvtc=n.

" -EditorType=numeric -Enabled=false -MaxVal=2 -MinVal=0 -ValueDefault=0 - -[Perl best practices] -Category=0 -Description="

-pbp is an abbreviation for the parameters in the book Perl Best Practices by Damian Conway:

\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="

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.

-c -T-x-x-pscf=s-T-pscf=-c

Perltidy will pass your string to perl with the exception that it willadd a -c and -x if appropriate. The .LOG file will show exactly what flags were passed to perl." -EditorType=string -Enabled=false -ValueDefault= - -[Preserve line endings] -Category=1 -Description="This flag tells perltidy to write its output files with the same line endings as the input file, if possible. It should work for dos, unix, and mac 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." -EditorType=boolean -Enabled=false -TrueFalse=--preserve-line-endings| -ValueDefault=0 - -[Space after keyword] -CallName="--space-after-keyword=" -Category=3 -Description="

When an opening paren follows a Perl keyword, no space is introduced after the keyword, unless it is (by default) one of these:

\n   my local our and or eq ne if else elsif until unless \n   while for foreach return switch case given when

These defaults can be modified with two commands:

-sak=s or --space-after-keyword=s adds keywords.

-nsak=s or --nospace-after-keyword=s removes keywords.

where s is a list of keywords (in quotes if necessary). For example,

\n  my ( $a, $b, $c ) = @_;    # default\n  my( $a, $b, $c ) = @_;     # -nsak="my local our"

Semicolons within for 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 -nsfs or --nospace-for-semicolon to deactivate it.

\n for ( @a = @$ap, $u = shift @a ; @a ; $u = $v ) {  # -sfs (default)\n for ( @a = @$ap, $u = shift @a; @a; $u = $v ) {    # -nsfs

When an opening paren follows a function the default is not to introduce a space. To cause a space to be introduced use:

-sfp or --space-function-paren

\n  myfunc( $a, $b, $c );    # default \n  myfunc ( $a, $b, $c );   # -sfp

You will probably also want to use the flag -skp (previous item) too.

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:

-skp or --space-keyword-paren

You will probably also want to use the flag -sfp (next item) too.

Some programmers prefer a space before all terminal semicolons. The default is for no such space, and is indicated with -nsts or --nospace-terminal-semicolon.

\n        $i = 1 ;     #  -sts\n        $i = 1;      #  -nsts   (default)

Likewise, the parameter -sbt=n or --square-bracket-tightness=n controls the space within square brackets, as illustrated below.

\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

The -vt=n and -vtc=n parameters apply to each type of container token. If desired, vertical tightness controls can be applied independently to each of the closing container token types.

In fact, the parameter -vt=n is actually just an abbreviation for -pvt=n -bvt=n sbvt=n, and likewise -vtc=n is an abbreviation for -pvtc=n -bvtc=n sbvtc=n.

The -vt=n and -vtc=n parameters apply to each type of container token. If desired, vertical tightness controls can be applied independently to each of the closing container token types.

In fact, the parameter -vt=n is actually just an abbreviation for -pvt=n -bvt=n sbvt=n, and likewise -vtc=n is an abbreviation for -pvtc=n -bvtc=n sbvtc=n.

The -sct flag tells perltidy to ``stack'' closing tokens when possible to avoid lines with isolated closing tokens.

For example:

\n    # default\n    $opt_c = Text::CSV_XS->new(\n        {\n            binary       => 1,\n            sep_char     => $opt_c,\n            always_quote => 1,\n        }\n    );

\n    # -sct\n    $opt_c = Text::CSV_XS->new(\n        {\n            binary       => 1,\n            sep_char     => $opt_c,\n            always_quote => 1,\n        } );

The -sct flag is somewhat similar to the -vtc flags, and in some cases it can give a similar result. The difference is that the -vtc flags try to avoid lines with leading opening tokens by ``hiding'' them at the end of a previous line, whereas the -sct 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:

\n    # -vtc=2\n    $opt_c = Text::CSV_XS->new(\n        {\n            binary       => 1,\n            sep_char     => $opt_c,\n            always_quote => 1, } );

The flag -sct is a synonym for -scp -schb -scsb.

The -sct flag tells perltidy to ``stack'' closing tokens when possible to avoid lines with isolated closing tokens.

For example:

\n    # default\n    $opt_c = Text::CSV_XS->new(\n        {\n            binary       => 1,\n            sep_char     => $opt_c,\n            always_quote => 1,\n        }\n    );

\n    # -sct\n    $opt_c = Text::CSV_XS->new(\n        {\n            binary       => 1,\n            sep_char     => $opt_c,\n            always_quote => 1,\n        } );

\n    # -vtc=2\n    $opt_c = Text::CSV_XS->new(\n        {\n            binary       => 1,\n            sep_char     => $opt_c,\n            always_quote => 1, } );

The flag -sct is a synonym for -scp -schb -scsb.

The -sct flag tells perltidy to ``stack'' closing tokens when possible to avoid lines with isolated closing tokens.

For example:

\n    # default\n    $opt_c = Text::CSV_XS->new(\n        {\n            binary       => 1,\n            sep_char     => $opt_c,\n            always_quote => 1,\n        }\n    );

\n    # -sct\n    $opt_c = Text::CSV_XS->new(\n        {\n            binary       => 1,\n            sep_char     => $opt_c,\n            always_quote => 1,\n        } );

\n    # -vtc=2\n    $opt_c = Text::CSV_XS->new(\n        {\n            binary       => 1,\n            sep_char     => $opt_c,\n            always_quote => 1, } );

The flag -sct is a synonym for -scp -schb -scsb.

The -sct flag tells perltidy to ``stack'' closing tokens when possible to avoid lines with isolated closing tokens.

For example:

\n    # default\n    $opt_c = Text::CSV_XS->new(\n        {\n            binary       => 1,\n            sep_char     => $opt_c,\n            always_quote => 1,\n        }\n    );

\n    # -sct\n    $opt_c = Text::CSV_XS->new(\n        {\n            binary       => 1,\n            sep_char     => $opt_c,\n            always_quote => 1,\n        } );

\n    # -vtc=2\n    $opt_c = Text::CSV_XS->new(\n        {\n            binary       => 1,\n            sep_char     => $opt_c,\n            always_quote => 1, } );

For detailed control of the stacking of individual closing tokens the following controls can be used:

\n  -scp  or --stack-closing-paren\n  -schb or --stack-closing-hash-brace\n  -scsb or --stack-closing-square-bracket

The flag -sct is a synonym for -scp -schb -scsb.

The -sot flag tells perltidy to ``stack'' opening tokens when possible to avoid lines with isolated opening tokens.

For example:

\n    # default\n    $opt_c = Text::CSV_XS->new(\n        {\n            binary       => 1,\n            sep_char     => $opt_c,\n            always_quote => 1,\n        }\n    );

\n    # -sot\n    $opt_c = Text::CSV_XS->new( {\n            binary       => 1,\n            sep_char     => $opt_c,\n            always_quote => 1,\n        }\n    );

For detailed control of individual closing tokens the following controls can be used:

\n  -sop  or --stack-opening-paren\n  -sohb or --stack-opening-hash-brace\n  -sosb or --stack-opening-square-bracket

The flag -sot is a synonym for -sop -sohb -sosb.

The -sot flag tells perltidy to ``stack'' opening tokens when possible to avoid lines with isolated opening tokens.

For example:

\n    # default\n    $opt_c = Text::CSV_XS->new(\n        {\n            binary       => 1,\n            sep_char     => $opt_c,\n            always_quote => 1,\n        }\n    );

\n    # -sot\n    $opt_c = Text::CSV_XS->new( {\n            binary       => 1,\n            sep_char     => $opt_c,\n            always_quote => 1,\n        }\n    );

The flag -sot is a synonym for -sop -sohb -sosb.

The -sot flag tells perltidy to ``stack'' opening tokens when possible to avoid lines with isolated opening tokens.

For example:

\n    # default\n    $opt_c = Text::CSV_XS->new(\n        {\n            binary       => 1,\n            sep_char     => $opt_c,\n            always_quote => 1,\n        }\n    );

\n    # -sot\n    $opt_c = Text::CSV_XS->new( {\n            binary       => 1,\n            sep_char     => $opt_c,\n            always_quote => 1,\n        }\n    );

For detailed control of individual closing tokens the following controls can be used:

\n  -sop  or --stack-opening-paren\n  -sohb or --stack-opening-hash-brace\n  -sosb or --stack-opening-square-bracket

The flag -sot is a synonym for -sop -sohb -sosb.

The -sot flag tells perltidy to ``stack'' opening tokens when possible to avoid lines with isolated opening tokens.

For example:

\n    # default\n    $opt_c = Text::CSV_XS->new(\n        {\n            binary       => 1,\n            sep_char     => $opt_c,\n            always_quote => 1,\n        }\n    );

\n    # -sot\n    $opt_c = Text::CSV_XS->new( {\n            binary       => 1,\n            sep_char     => $opt_c,\n            always_quote => 1,\n        }\n    );

For detailed control of individual closing tokens the following controls can be used:

\n  -sop  or --stack-opening-paren\n  -sohb or --stack-opening-hash-brace\n  -sosb or --stack-opening-square-bracket

The flag -sot is a synonym for -sop -sohb -sosb.

-sil=n

The command -osbc will will cause static block comments to be outdented by 2 spaces (or whatever -ci=n has been set to), if possible.

This parameter defines the prefix used to identify static block comments when the -sbc parameter is set. The default prefix is ##, corresponding to -sbcp=##. The prefix is actually part of a perl pattern used to match lines and it must either begin with # or ^#. 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 -sbcp=#. To identify all left-adjusted comments as static block comments, use -sbcp='^#'.

Please note that -sbcp merely defines the pattern used to identify static block comments; it will not be used unless the switch -sbc 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.

A pattern which can be useful is:

\n    -sbcp=^#{2,}[^#]

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 '#'.

Static block comments are block comments with a special leading pattern, ## 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.

-sbc, --static-block-comments: When -sbc is used, a block comment with a special leading pattern, ## by default, will be treated specially.; Comments so identified are treated as follows:; This parameter defines the prefix used to identify static side comments when the -ssc parameter is set. The default prefix is ##, corresponding to -sscp=##.; Please note that -sscp merely defines the pattern used to identify static side comments; it will not be used unless the switch -ssc 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.; 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.