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