# Perltidy Change Log
-## 2021 10 29.06
+## 2022 02 15
- A new flag, --encode-output-strings, or -eos, has been added to resolve
issue git #83. This issue involves the interface between Perl::Tidy and
calling programs, and Code::TidyAll (tidyall) in particular. The problem
is that perltidy by default returns decoded character strings, but
- tidyall expects encoded strings. Tidyall users who process encoded (utf8)
- files should update to this version of Perl::Tidy and use -eos for tidyall.
- Note that if you run the 'perltidy' binary this flag has no effect. See:
+ tidyall expects encoded strings. This flag provides a fix for that.
+
+ So, tidyall users who process encoded (utf8) files should update to this
+ version of Perl::Tidy and use -eos for tidyall. For further info see:
+
https://github.com/houseabsolute/perl-code-tidyall/issues/84, and
https://github.com/perltidy/perltidy/issues/83
+ If there are other applications having utf8 problems at the interface
+ with Perl::Tidy, this flag probably may need to be set.
+
- The possible values of the string 's' for the flag '--character-encoding=s'
have been limited to 'utf8' (or UTF-8), 'none', or 'guess'. Previously an
arbitrary encoding could also be specified, but as a result of discussions
- regarding git #83 it became clear that this could lead to problems
+ regarding git #83 it became clear that this could cause trouble
since the output encoding was still restricted to UTF-8. Users
who need to work in other encodings can write a short program calling
Perl::Tidy with pre- and post-processing to handle encoding/decoding.
$xx = 1.234;
}
- - Fix issue git #82, an error handling something like ${bareword} in a possible
- indirect object location. Perl allows this, now perltidy does too.
+ - Fix issue git #82, an error handling something like ${bareword} in a
+ possible indirect object location. Perl allows this, now perltidy does too.
- The flags -kbb=s or --keep-old-breakpoints-before=s, and its counterpart
-kba=s or --keep-old-breakpoints-after=s have expanded functionality
- Two new flags have been added to provide finer vertical alignment control,
--valign-exclusion-list=s (-vxl=s) and --valign-inclusion-list=s (-vil=s).
- This has been requested several times, most recently in git #79, and we finally
- got it done.
+ This has been requested several times, most recently in git #79, and it
+ finally got done. For example, -vil='=>' means just align on '=>'.
- A new flag -gal=s, --grep-alias-list=s, has been added as suggested in
git #77. This allows code blocks passed to list operator functions to
- A new flag -xlp has been added which can be set to avoid most of the
limitations of the -lp flag regarding side comments, blank lines, and
code blocks. See the man pages for more info. This fixes git #64 and git #74.
+ The older -lp flag still works.
- A new flag -lpil=s, --line-up-parentheses-inclusion-list=s, has been added
as an alternative to -lpxl=s, --line-up-parentheses-exclusion-list=s.
and limitations. The new coding allows the -lp indentation style to
mix smoothly with the standard indentation in a single file. Some problems
where -lp and -xci flags were not working well together have been fixed, such
- as happened in issue rt140025.
+ as happened in issue rt140025. As a result of these updates some minor
+ changes in existing code using the -lp style may occur.
+
+ - This version of perltidy was stress-tested for many cpu hours with
+ random input parameters. No failures to converge, internal fault checks,
+ undefined variable references or other irregularities were seen.
+
+ - Numerous minor fixes have been made, mostly very rare formatting
+ instabilities found in random testing.
## 2021 10 29
without parens around the call args. Some examples:
# OLD
- mkTextConfig $c, $x, $y, -anchor => 'se', $color;
+ mkTextConfi2022 Helen Hancockg $c, $x, $y, -anchor => 'se', $color;
mkTextConfig $c, $x + 30, $y, -anchor => 's', $color;
mkTextConfig $c, $x + 60, $y, -anchor => 'sw', $color;
mkTextConfig $c, $x, $y + 30, -anchor => 'e', $color;
<h1>Perltidy Change Log</h1>
-<h2>2021 10 29.05</h2>
+<h2>2022 02 15</h2>
-<pre><code>- Two new flags have been added to provide finer vertical alignment control,
+<pre><code>- A new flag, --encode-output-strings, or -eos, has been added to resolve
+ issue git #83. This issue involves the interface between Perl::Tidy and
+ calling programs, and Code::TidyAll (tidyall) in particular. The problem
+ is that perltidy by default returns decoded character strings, but
+ tidyall expects encoded strings. This flag provides a fix for that.
+
+ So, tidyall users who process encoded (utf8) files should update to this
+ version of Perl::Tidy and use -eos for tidyall. For further info see:
+
+ https://github.com/houseabsolute/perl-code-tidyall/issues/84, and
+ https://github.com/perltidy/perltidy/issues/83
+
+ If there are other applications having utf8 problems at the interface
+ with Perl::Tidy, this flag probably may need to be set.
+
+- The possible values of the string 's' for the flag '--character-encoding=s'
+ have been limited to 'utf8' (or UTF-8), 'none', or 'guess'. Previously an
+ arbitrary encoding could also be specified, but as a result of discussions
+ regarding git #83 it became clear that this could cause trouble
+ since the output encoding was still restricted to UTF-8. Users
+ who need to work in other encodings can write a short program calling
+ Perl::Tidy with pre- and post-processing to handle encoding/decoding.
+
+- A new flag --break-after-labels=i, or -bal=i, was added for git #86. This
+ controls line breaks after labels, to provide a uniform style, as follows:
+
+ -bal=0 follows the input line breaks [DEFAULT]
+ -bal=1 always break after a label
+ -bal=2 never break after a label
+
+ For example:
+
+ # perltidy -bal=1
+ INIT:
+ {
+ $xx = 1.234;
+ }
+
+ # perltidy -bal=2
+ INIT: {
+ $xx = 1.234;
+ }
+
+- Fix issue git #82, an error handling something like ${bareword} in a
+ possible indirect object location. Perl allows this, now perltidy does too.
+
+- The flags -kbb=s or --keep-old-breakpoints-before=s, and its counterpart
+ -kba=s or --keep-old-breakpoints-after=s have expanded functionality
+ for the container tokens: { [ ( } ] ). The updated man pages have
+ details.
+
+- Two new flags have been added to provide finer vertical alignment control,
--valign-exclusion-list=s (-vxl=s) and --valign-inclusion-list=s (-vil=s).
- This has been requested several times, recently in git #79.
+ This has been requested several times, most recently in git #79, and it
+ finally got done. For example, -vil='=>' means just align on '=>'.
- A new flag -gal=s, --grep-alias-list=s, has been added as suggested in
git #77. This allows code blocks passed to list operator functions to
- A new flag -xlp has been added which can be set to avoid most of the
limitations of the -lp flag regarding side comments, blank lines, and
- code blocks. This is off by default to avoid changing existing coding,
- so this flag has to be set to turn this feature on. [Documentation still
- needs to be written]. It will be included in the next release to CPAN,
- but some details regarding how it handles very long lines may change before
- the final release to CPAN. This fixes issues git #64 and git #74.
+ code blocks. See the man pages for more info. This fixes git #64 and git #74.
+ The older -lp flag still works.
+
+- A new flag -lpil=s, --line-up-parentheses-inclusion-list=s, has been added
+ as an alternative to -lpxl=s, --line-up-parentheses-exclusion-list=s.
+ It supplies equivalent information but is much easier to describe and use.
+ It works for both the older -lp version and the newer -xlp.
-- The coding for the -lp flag has been rewritten to avoid some problems
+- The coding for the older -lp flag has been updated to avoid some problems
and limitations. The new coding allows the -lp indentation style to
mix smoothly with the standard indentation in a single file. Some problems
where -lp and -xci flags were not working well together have been fixed, such
- as happened in issue rt140025.
+ as happened in issue rt140025. As a result of these updates some minor
+ changes in existing code using the -lp style may occur.
+
+- This version of perltidy was stress-tested for many cpu hours with
+ random input parameters. No failures to converge, internal fault checks,
+ undefined variable references or other irregularities were seen.
+
+- Numerous minor fixes have been made, mostly very rare formatting
+ instabilities found in random testing.
</code></pre>
<h2>2021 10 29</h2>
without parens around the call args. Some examples:
# OLD
- mkTextConfig $c, $x, $y, -anchor => 'se', $color;
+ mkTextConfi2022 Helen Hancockg $c, $x, $y, -anchor => 'se', $color;
mkTextConfig $c, $x + 30, $y, -anchor => 's', $color;
mkTextConfig $c, $x + 60, $y, -anchor => 'sw', $color;
mkTextConfig $c, $x, $y + 30, -anchor => 'e', $color;
comment '#<<V' which is not terminated with a closing comment '#>>V'. This
makes code-skipping and format-skipping behave in a similar way: an
opening comment without a corresponding closing comment will cause
- the rest of a file to be skipped. If there is a question about which lines
- are skipped, a .LOG file can be produced with the -g flag and it will have
+ the rest of a file to be skipped. If there is a question about which lines
+ are skipped, a .LOG file can be produced with the -g flag and it will have
this information.
- Removed the limit on -ci=n when -xci is set, reference: rt #136415.
flags and the --line-up-parens flag.
- Fixed issue git #54 regarding irregular application of the --break-before-paren
-and similar --break-before-xxx flags, in which lists without commas were not
+and similar --break-before-xxx flags, in which lists without commas were not
being formatted according to these flags.
-- Fixed issue git #53. A flag was added to turn off alignment of spaced function
+- Fixed issue git #53. A flag was added to turn off alignment of spaced function
parens. If the --space-function-paren, -sfp flag is set, a side-effect is that the
spaced function parens may get vertically aligned. This can be undesirable,
so a new parameter '--function-paren-vertical-alignment', or '-fpva', has been
-added to turn this vertical alignment off. The default is '-fpva', so that
+added to turn this vertical alignment off. The default is '-fpva', so that
existing formatting is not changed. Use '-nfpva' to turn off unwanted
vertical alignment. To illustrate the possibilities:
<h2>2020 12 01</h2>
-<pre><code>- This release is being made primarily to make available a several new formatting
- parameters, in particular -xci, -kbb=s, -kba=s, and -wnxl=s. No significant
- bugs have been found since the previous release, but numerous minor issues have
+<pre><code>- This release is being made primarily to make available a several new formatting
+ parameters, in particular -xci, -kbb=s, -kba=s, and -wnxl=s. No significant
+ bugs have been found since the previous release, but numerous minor issues have
been found and fixed as listed below.
- This version is about 20% faster than the previous version due to optimizations
- Fixed issue git #45, -vtc=n flag was ignored when -wn was set.
-- implement request RT #133649, delete-old-newlines selectively. Two parameters,
+- implement request RT #133649, delete-old-newlines selectively. Two parameters,
-kbb=s or --keep-old-breakpoints-before=s, and
-kba=s or --keep-old-breakpoints-after=s
<dt id="gal-s---grep-alias-list-s"><b>-gal=s</b>, <b>--grep-alias-list=s</b></dt>
<dd>
-<p>This flag causes a code block following a specified word to be formatted as if it followed the keyword 'grep' (or 'map' or 'sort'). The string <b>s</b> contains one or more such alias words, separated by spaces or commas.</p>
+<p>This flag allows a code block following an external 'list operator' function to be formatted as if it followed one of the builtin keywords <b>grep</b>, <b>map</b> or <b>sort</b>. The string <b>s</b> contains the names of one or more such list operators, separated by spaces or commas.</p>
-<p>This allows code block arguments to external list operator functions to be formatted in the same way as code blocks which follow the perl builtin keywords 'grep', 'map', and 'sort'. By 'list operator' is meant a function which is invoked in the form</p>
+<p>By 'list operator' is meant a function which is invoked in the form</p>
<pre><code> word {BLOCK} @list</code></pre>
<dt id="vmll---variable-maximum-line-length"><b>-vmll</b>, <b>--variable-maximum-line-length</b></dt>
<dd>
-<p>A problem arises using a fixed maximum line length with very deeply nested code and data structures because eventually the amount of leading whitespace used for indicating indentation takes up most or all of the available line width, leaving little or no space for the actual code or data. One solution is to use a vary long line length. Another solution is to use the <b>-vmll</b> flag, which basically tells perltidy to ignore leading whitespace when measuring the line length.</p>
+<p>A problem arises using a fixed maximum line length with very deeply nested code and data structures because eventually the amount of leading whitespace used for indicating indentation takes up most or all of the available line width, leaving little or no space for the actual code or data. One solution is to use a very long line length. Another solution is to use the <b>-vmll</b> flag, which basically tells perltidy to ignore leading whitespace when measuring the line length.</p>
<p>To be precise, when the <b>-vmll</b> parameter is set, the maximum line length of a line of code will be M+L*I, where</p>
<dt id="enc-s---character-encoding-s"><b>-enc=s</b>, <b>--character-encoding=s</b></dt>
<dd>
-<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>This flag indicates if the input data stream use a character encoding. 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 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 possible values for <b>s</b> are:</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>
+<pre><code> -enc=none if no encoding is used, or
+ -enc=utf8 for encoding in utf8
+ -enc=guess if perltidy should guess between these two possibilities.</code></pre>
<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 value <b>utf8</b> causes the stream to be read and written as UTF-8. If the input stream cannot be decoded with this encoding then processing is not done.</p>
+
+<p>The value <b>guess</b> tells perltidy to guess between either utf8 encoding or no encoding (meaning one character per byte). The <b>guess</b> option uses the Encode::Guess module which has been found to be reliable at detecting if a file is encoded in utf8 or not.</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>
+<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 <b>-enc=guess</b>. 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>or</p>
+
+<pre><code> perltidy -guess file.pl</code></pre>
+
+<p>or simply</p>
+
+<pre><code> perltidy file.pl</code></pre>
+
+<p>since <b>-guess</b> is the default.</p>
-<p>To process a file in <b>euc-jp</b> you could use</p>
+<p>To process files with an encoding other than UTF-8, it would be necessary to write a short program which calls the Perl::Tidy module with some pre- and post-processing to handle decoding and encoding.</p>
-<pre><code> perltidy -enc=euc-jp file.pl</code></pre>
+</dd>
+<dt id="eos-s---encode-output-strings-s"><b>-eos=s</b>, <b>--encode-output-strings=s</b></dt>
+<dd>
+
+<p>This flag has been added to resolve an issue involving the interface between Perl::Tidy and calling programs, and in particular <b>Code::TidyAll (tidyall)</b>. By default Perl::Tidy returns unencoded strings to the calling program, but some programs expect encoded strings. Setting this flag causes Perl::Tidy to return encoded output strings which it decoded. For some background information see <a href="https://github.com/perltidy/perltidy/issues/83">https://github.com/perltidy/perltidy/issues/83</a> and <a href="https://github.com/houseabsolute/perl-code-tidyall/issues/84">https://github.com/houseabsolute/perl-code-tidyall/issues/84</a>.</p>
-<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>
+<p>If you only run the perltidy binary this flag has no effect.</p>
+
+<p>If you use <b>tidyall</b> with encoded files and encounter irregularities such as <b>wide character</b> messages you should set this flag.</p>
</dd>
<dt id="gcs---use-unicode-gcstring"><b>-gcs</b>, <b>--use-unicode-gcstring</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"><b>List indentation</b> using <b>-lp</b>, <b>--line-up-parentheses</b></dt>
+<dt id="List-indentation-using---line-up-parentheses--lp-or---extended--line-up-parentheses--xlp"><b>List indentation</b> using <b>--line-up-parentheses</b>, <b>-lp</b> or <b>--extended--line-up-parentheses</b> , <b>-xlp</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>These flags provide an alternative indentation method for list data. The original flag for this is <b>-lp</b>, but it has some limitations (explained below) which are avoided with the newer <b>-xlp</b> flag. So <b>-xlp</b> is probably the better choice for new work, but the <b>-lp</b> flag is retained to minimize changes to existing formatting. If you enter both <b>-lp</b> and <b>-xlp</b>, then <b>-xlp</b> will be used.</p>
+
+<p>In the default indentation method 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>
<pre><code> # perltidy (default)
@month_of_year = (
'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'
);</code></pre>
-<p>Use the <b>-lp</b> flag to add extra indentation to cause the data to begin past the opening parentheses of a sub call or list, or opening square bracket of an anonymous array, or opening curly brace of an anonymous hash. With this option, the above list would become:</p>
+<p>The <b>-lp</b> or <b>-xlp</b> flags add extra indentation to cause the data to begin past the opening parentheses of a sub call or list, or opening square bracket of an anonymous array, or opening curly brace of an anonymous hash. With this option, the above list would become:</p>
-<pre><code> # perltidy -lp
+<pre><code> # perltidy -lp or -xlp
@month_of_year = (
'Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun',
'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'
<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>.</p>
+<p>These flags have no effect on code BLOCKS, such as if/then/else blocks, which always use whatever is specified with <b>-i=n</b>.</p>
+
+<p>Some limitiations on these flags are:</p>
+
+<ul>
+
+<li><p>A limitation on <b>-lp</b>, but not <b>-xlp</b>, occurs in situations where perltidy does not have complete freedom to choose line breaks. Then 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. It will also occur if a multi-line anonymous sub occurs within a container since that will impose specific line breaks (such as line breaks after statements).</p>
+
+</li>
+<li><p>For both the <b>-lp</b> and <b>-xlp</b> flags, any parameter which significantly restricts the ability of perltidy to choose newlines will conflict with these flags and will cause them to be deactivated. These include <b>-io</b>, <b>-fnl</b>, <b>-nanl</b>, and <b>-ndnl</b>.</p>
+
+</li>
+<li><p>The <b>-lp</b> and <b>-xlp</b> options may not be used together with the <b>-t</b> tabs option. They may, however, be used with the <b>-et=n</b> tab method</p>
+
+</li>
+</ul>
+
+<p>There are some potential disadvantages of this indentation method compared to the default method that should be noted:</p>
+
+<ul>
+
+<li><p>The available line length can quickly be used up if variable names are long. This can cause deeply nested code to quickly reach the line length limit, and become badly formatted, much sooner than would occur with the default indentation method.</p>
+
+</li>
+<li><p>Since the indentation depends on the lengths of variable names, small changes in variable names can cause changes in indentation over many lines in a file. This means that minor name changes can produce significant file differences. This can be annoying and does not occur with the default indentation method.</p>
+
+</li>
+</ul>
+
+<p>Some things that can be done to minimize these problems are:</p>
+
+<ul>
-<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. It will also occur if a multi-line anonymous sub occurs within a container since that will impose specific line breaks (such as line breaks after statements).</p>
+<li><p>Increase <b>--maximum-line-length=n</b> above the default <b>n=80</b> characters if necessary.</p>
+
+</li>
+<li><p>If you use <b>-xlp</b> then long side comments can limit the indentation over multiple lines. Consider adding the flag <b>--ignore-side-comment-lengths</b> to prevent this, or minimizing the use of side comments.</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>
+</li>
+<li><p>Apply this style in a limited way. By default, it applies to all list containers (not just lists in parentheses). The next section describes how to limit this style to, for example, just function calls. The default indentation method will be applied elsewhere.</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>
+</li>
+</ul>
</dd>
-<dt id="lpxl-s---line-up-parentheses-exclusion-list"><b>-lpxl=s</b>, <b>--line-up-parentheses-exclusion-list</b></dt>
+<dt id="lpil-s---line-up-parentheses-inclusion-list-and--lpxl-s---line-up-parentheses-exclusion-list"><b>-lpil=s</b>, <b>--line-up-parentheses-inclusion-list</b> and <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 following discussion is written for <b>-lp</b> but applies equally to the newer <b>-xlp</b> version. By default, the <b>-lp</b> flag applies to as many containers as possible. The set of containers to which the <b>-lp</b> style applies can be reduced by either one of these two flags:</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>Use <b>-lpil=s</b> to specify the containers to which <b>-lp</b> applies, or</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>
+<p>use <b>-lpxl=s</b> to specify the containers to which <b>-lp</b> does NOT apply.</p>
-<pre><code> -lpxl='[ {'</code></pre>
+<p>Only one of these two flags may be used. Both flags can achieve the same result, but the <b>-lpil=s</b> flag is much easier to describe and use and is recommended. The <b>-lpxl=s</b> flag was the original implementation and is only retained for backwards compatibility.</p>
-<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>This list <b>s</b> for these parametes 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>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>
+<p>The only required piece of information is a container type, which is one of '(', '[', or '{'. For example the string</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>
+<pre><code> -lpil='('</code></pre>
-<p>For example,</p>
+<p>means use -lp formatting only on lists within parentheses, not lists in square-bracets or braces. The same thing could alternatively be specified with</p>
-<pre><code> -lpxl = '[ { (2'</code></pre>
+<pre><code> -lpxl = '[ {'</code></pre>
-<p>means only apply -lp to parenthesized lists which do not contain any sublists, code blocks or ternary expressions.</p>
+<p>which says to exclude lists within square-brackets and braces. So what remains is lists within parentheses.</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>
+<p>A second optional item of information which can be given for parentheses 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 for matching whatever precedes an opening paren:</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.
'w' matches if either 'k' or 'f' match.
'W' matches if 'w' does not.</code></pre>
+<p>For example:</p>
+
+<pre><code> -lpil = 'f('</code></pre>
+
+<p>means only apply -lp to function calls, and</p>
+
+<pre><code> -lpil = 'w('</code></pre>
+
+<p>means only apply -lp to parenthesized lists which follow a function or a keyword.</p>
+
+<p>This last example could alternatively be written using the <b>-lpxl=s</b> flag as</p>
+
+<pre><code> -lpxl = '[ { W('</code></pre>
+
+<p>which says exclude <b>-lp</b> for lists within square-brackets, braces, and parens NOT preceded by a keyword or function. Clearly, the <b>-lpil=s</b> method is easier to understand.</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 is made
+ '1' exclude B<-lp> unless the contents is a simple list without sublists
+ '2' exclude B<-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 = '[ { F(2'</code></pre>
+<pre><code> -lpil = '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>
+<p>means only apply -lp to function call lists which do not contain any sublists, code blocks or ternary expressions.</p>
</dd>
<dt id="cti-n---closing-token-indentation"><b>-cti=n</b>, <b>--closing-token-indentation</b></dt>
fixit($i);
}</code></pre>
-<p>Use <b>-nola</b> to not outdent labels.</p>
+<p>Use <b>-nola</b> to not outdent labels. To control line breaks after labels see <a href="#bal-n---break-after-labels-n">"bal=n, --break-after-labels=n"</a>.</p>
</dd>
<dt id="Outdenting-Keywords"><b>Outdenting Keywords</b></dt>
<p>and the <b>-bbao</b> flag sets the default to break before all of these operators. These can be used to define an initial break preference which can be fine-tuned with the <b>-wba</b> and <b>-wbb</b> flags. For example, to break before all operators except an <b>=</b> one could use --bbao -wba='=' rather than listing every single perl operator except <b>=</b> on a -wbb flag.</p>
+</dd>
+<dt id="bal-n---break-after-labels-n"><b>bal=n, --break-after-labels=n</b></dt>
+<dd>
+
+<p>This flag controls whether or not a line break occurs after a label. There are three possible valuse for <b>n</b>:</p>
+
+<pre><code> -bal=0 break if there is a break in the input [DEFAULt]
+ -bal=1 always break after a label
+ -bal=2 never break after a label</code></pre>
+
+<p>For example,</p>
+
+<pre><code> # perltidy -bal=1
+ RETURN:
+ return;
+
+ # perltidy -bal=2
+ RETURN: return;</code></pre>
+
</dd>
</dl>
<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>It is possible to override the choice of line breaks made by perltidy, and force it to follow certain line breaks in the input stream, with these two parameters:</p>
<p><b>-kbb=s</b> or <b>--keep-old-breakpoints-before=s</b>, and</p>
...;
};</code></pre>
+<p>For the container tokens '{', '[' and '(' and, their closing counterparts, use the token symbol. Thus, the command to keep a break after all opening parens is:</p>
+
+<pre><code> perltidy -kba='('</code></pre>
+
+<p>It is possible to be more specific in matching parentheses by preceding them with a letter. The possible letters are 'k', 'K', 'f', 'F', 'w', and 'W', with these meanings (these are the same as used in the <b>--weld-nested-exclusion-list</b> and <b>--line-up-parentheses-exclusion-list</b> parameters):</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>So for example the the following parameter will keep breaks after opening function call parens:</p>
+
+<pre><code> perltidy -kba='f('</code></pre>
+
+<p><b>NOTE</b>: To match all opening curly braces, and no other opening tokens, please prefix the brace it with an asterisk, like this: '*{'. Otherwise a warning message will occur. This is necessary to avoid problems while the input scheme is being updated and generalized. A single bare curly brace previously matched all container tokens, and tentatively still does. Likewise, to match all closing curly braces, and no other closing tokens, use '*}'.</p>
+
</dd>
<dt id="iob---ignore-old-breakpoints"><b>-iob</b>, <b>--ignore-old-breakpoints</b></dt>
<dd>
<pre><code> -lp -bl -noll -pt=2 -bt=2 -sbt=2 -icp</code></pre>
+<p>To use this style with <b>-xlp</b> instead of <b>-lp</b> use <b>-gnu -xlp</b>.</p>
+
</dd>
<dt id="pbp---perl-best-practices"><b>-pbp</b>, <b>--perl-best-practices</b></dt>
<dd>
<pre><code> --valign-exclusion-list='= if'</code></pre>
-<p>If it is simpler to specify only the token types which are to be aligned, then use the special symbol <b>*</b> for this exclusion list and include the types which are to be aligned in the list of <b>--valign-inclusion-list</b> (this works because <b>*</b> is not one of the alignment tokens). For example, the following parameters enable alignment only at commas and 'fat commas':</p>
+<p>If it is simpler to specify only the token types which are to be aligned, then include the types which are to be aligned in the list of <b>--valign-inclusion-list</b>. You may leave the <b>valign-exclusion-list</b> undefined, or use the special symbol <b>*</b> for the exclusion list. For example, the following parameters enable alignment only at commas and 'fat commas':</p>
-<pre><code> --valign-exclusion-list='*'
- --valign-inclusion-list=', =>'</code></pre>
+<pre><code> --valign-inclusion-list=', =>'
+ --valign-exclusion-list='*' ( this is optional and may be omitted )</code></pre>
-<p>These parameter lists should consist of space-separated tokens from the above list of possible alignment tokens. If an unrecognized parameter appears, it is simply ignored. And if a parameter is entered in both lists by mistake then the exclusion list has priority.</p>
+<p>These parameter lists should consist of space-separated tokens from the above list of possible alignment tokens, or a '*'. If an unrecognized token appears, it is simply ignored. And if a specific token is entered in both lists by mistake then the exclusion list has priority.</p>
<p>The default values of these parameters enable all alignments and are equivalent to</p>
$co_prompt = ($color) ? 'bold green' : ''; # prompt
$co_unused = ($color) ? 'on_green' : 'reverse'; # unused</code></pre>
-<p>To exclude all alignments except the equals we could use:</p>
+<p>To exclude all alignments except the equals (i.e., include only equals) we could use:</p>
-<pre><code> # perltidy -vxl='*' -vil='='
+<pre><code> # perltidy -vil='='
$co_description = ($color) ? 'bold cyan' : ''; # description
$co_prompt = ($color) ? 'bold green' : ''; # prompt
$co_unused = ($color) ? 'on_green' : 'reverse'; # unused</code></pre>
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 vbc vc
- vmll vsc w wn x xci xs</code></pre>
+ dp dpro dsc dsm dsn dtt dwls dwrs dws eos
+ 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 vbc
+ vc vmll vsc w wn x xci xlp xs</code></pre>
<p>Equivalently, the prefix 'no' or 'no-' on the corresponding long names may be used.</p>
<h1 id="VERSION">VERSION</h1>
-<p>This man page documents perltidy version 20211029.05</p>
+<p>This man page documents perltidy version 20220215</p>
<h1 id="BUG-REPORTS">BUG REPORTS</h1>
<h1 id="COPYRIGHT">COPYRIGHT</h1>
-<p>Copyright (c) 2000-2021 by Steve Hancock</p>
+<p>Copyright (c) 2000-2022 by Steve Hancock</p>
<h1 id="LICENSE">LICENSE</h1>
projects / perltidy.git / commitdiff