appear. If they do not appear to be working, use the -log flag and examine the
F<.LOG> file. Use B<-nfs> to disable this feature.
+This method works for any code. For the specific case of a comma-separated list
+of values, as in this example, another possibility is to insert a blank or
+comment somewhere between the opening and closing parens. See the section
+L<Controlling List Formatting>.
+
=item B<-fsb=string>, B<--format-skipping-begin=string>
The B<-fsb=string> parameter may be used to change the beginning marker for
=head2 Controlling List Formatting
-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.
-
-=over 4
-
-=item B<-boc>, B<--break-at-old-comma-breakpoints>
+Perltidy attempts to format lists of comma-separated values in tables
+which look good. Its default algorithms usually work well, but sometimes
+parameters available to control list formatting. In this case, there
+are several methods available to control list formatting.
-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:
+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
my @list = (1,
1, 1,
1, 3, 3, 1,
1, 4, 6, 4, 1,);
-The default formatting will flatten this down to one line:
+The default formatting, which allows a maximum line length of 80,
+will flatten this down to one line:
# perltidy (default)
my @list = ( 1, 1, 1, 1, 2, 1, 1, 3, 3, 1, 1, 4, 6, 4, 1, );
-which hides the structure. Using B<-boc>, plus additional flags
-to retain the original style, yields
+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:
+
+ 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,
+ );
+
+We could achieve the same result with a blank line or full comment
+anywhere between the opening and closing parens.
+
+For another possibility see
+the -fs flag in L<Skipping Selected Sections of Code>.
+
+=over 4
+
+=item B<-boc>, B<--break-at-old-comma-breakpoints>
+
+The B<-boc> flag is another way to prevent comma-separated lists from being
+reformatted. Using B<-boc> on the above example, plus additional flags to retain
+the original style, yields
# perltidy -boc -lp -pt=2 -vt=1 -vtc=1
my @list = (1,
1, 4, 6, 4, 1,);
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 L<Skipping Selected Sections of Code>.
+must already be nicely formatted.
+
=item B<-mft=n>, B<--maximum-fields-per-table=n>
<h2>2020 01 10.01</h2>
-<pre><code>- Added a parameter --logical-padding or -lop to allow logical padding
+<pre><code>- Fixed minor problem where trailing 'unless' clauses were not
+ getting vertically aligned.
+
+- Added a parameter --logical-padding or -lop to allow logical padding
to be turned off. Requested by git #29. This flag is on by default.
The man pages have examples.
in RT#131644. This flag will keep lines beginning with a semicolon.
- Added --use-unicode-gcstring to control use of Unicode::GCString for
- evaluating character widths of encoded data. By default, for encoded files
- perltidy will now look for Unicode::GCString and, if found, will use it
+ evaluating character widths of encoded data. The default is
+ not to use this (--nouse-unicode-gcstring). If this flag is set,
+ perltidy will look for Unicode::GCString and, if found, will use it
to evaluate character display widths. This can improve displayed
- vertical alignment for files with wide characters. This flag is mainly intended
- for testing, but can also prevent the use of this module in the event that some
- unforseen issue arises. Perltidy installation does not require
- Unicode::GCString, so users wanting to use this feature need to install it
- separately.
+ 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.
- Added --character-encoding=guess or -guess to have perltidy guess
if a file (or other input stream) is encoded as -utf8 or some
which is included in standard perl distributions, and only tries to
guess if a file is utf8 or not, never any other encoding. If the guess is
utf8, and if the file successfully decodes as utf8, then it the encoding
- is assumed to be utf8. Otherwise, no encoding is assumed.
- I have done extensive testing and have not detected any problems with
- this guess method. If you do not want to use this new default guess mode,
- or have a problem with it, you can set --character-encoding=none
- (the previous default) or --character-encoding=utf8 (if you deal
- with utf8 files).
+ is assumed to be utf8. Otherwise, no encoding is assumed. I have done
+ extensive testing and have not detected any problems with this
+ rather conservative guess method, so I think it is a good default.
+ If you do not want to use this new default guess mode, or have a
+ problem with it, you can set --character-encoding=none (the previous
+ default) or --character-encoding=utf8 (if you deal with utf8 files).
- Specific encodings of input files other than utf8 may now be given, for
example --character-encoding=euc-jp.
<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. It has no effect if that module is not installed on a system. If text is encoded then perltidy will by default use the module Unicode::GCString to determine the horizontal widths of the text, provided Unicode::GCString is available. This is needed to produce formatted text with good vertical alignment when there are wide characters. If the module is not available on the system, or if the flag <b>--nouse-unicode-gcstring</b> or <b>ngcs</b> has been set, then this module will not be used and characters will have an assumed display width of 1. In this case, vertical alignment may be poor if code contains a mixture of wide and normal characters. The default setting is <b>--use-unicode-gcstring</b>. This flag is mainly intended for testing, and as a workaround in case a problem arises with the Unicode::GCString module.</p>
+<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>Perltidy installation does not require Unicode::GCString, so users wanting to use this feature need to install it separately.</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>
<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>This method works for any code. For the specific case of a comma-separated list of values, as in this example, another possibility is to insert a blank or comment somewhere between the opening and closing parens. See the section <a href="#Controlling-List-Formatting">"Controlling List Formatting"</a>.</p>
+
</dd>
<dt id="fsb-string---format-skipping-begin-string"><b>-fsb=string</b>, <b>--format-skipping-begin=string</b></dt>
<dd>
<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 parameters available to control list formatting. 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>
projects / perltidy.git / commitdiff