- 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 'tidyall' in particular. The crux of the matter is
- that perltidy by default returns decoded character strings to the calling
- program. This is a result of its evolution over time, and it is not the best
- default, but it is difficult to change without breaking existing programs.
- Programs or users who require encoded character strings can set this flag.
- In particular, tidyall users who process encoded (utf8) files should
- probably set -eos to avoid problems. If you run the 'perltidy' binary
- this flag has no effect.
+ 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:
+ https://github.com/houseabsolute/perl-code-tidyall/issues/84, and
+ https://github.com/perltidy/perltidy/issues/83
- 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 was a bad idea and could lead
- to problems since the output encoding was still restricted to UTF-8. Users
+ regarding git #83 it became clear that this could lead to problems
+ 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 as requested
- in git #86. This controls line breaks after labels, as follows:
+ - 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:
{
}
- Fix issue git #82, an error handling something like ${bareword} in a possible
- indirect object location.
+ 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, recently in git #79.
+ This has been requested several times, most recently in git #79, and we finally
+ got it done.
- 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
They can be changed with the flag -gaxl=s, -grep-alias-exclusion-list=s
- - 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 easier to describe and use.
-
- 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 coding for the -lp flag has been rewritten to avoid some problems
+ - 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 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
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:
# perltidy -sfp
myfun ( $aaa, $b, $cc );
mylongfun ( $a, $b, $c );
-
+
# perltidy -sfp -nfpva
myfun ( $aaa, $b, $cc );
mylongfun ( $a, $b, $c );
## 2020 12 01
- - 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
+ - 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
were added to request that old breakpoints be kept before or after
selected token types. For example, -kbb='=>' means that newlines before
fat commas should be kept.
-
+
- Fix git #44, fix exit status for assert-tidy/untidy. The exit status was
always 0 for --assert-tidy if the user had turned off all error messages with
the -quiet flag. This has been fixed.
=item B<-gal=s>, B<--grep-alias-list=s>
-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> contains one or more such alias words, separated by spaces or commas.
+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<map> or B<sort>. The string B<s> contains the names of one or more such list operators, separated by spaces or commas.
-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
+By 'list operator' is meant a function which is invoked in the form
word {BLOCK} @list
(Note that perltidy often works on snippets of code rather than complete files
so it cannot rely on B<use utf8> directives).
-The possible values for B<s> are :
-(1) B<none> if no encoding is used, or
-(2) B<utf8> or B<UTF8> or B<UTF-8>, or
-(3) <guess> if perltidy should guess between these two possibilities.
+The possible values for B<s> are:
+
+ -enc=none if no encoding is used, or
+ -enc=utf8 for encoding in utf8
+ -enc=guess if perltidy should guess between these two possibilities.
The value B<none> causes the stream to be processed without special encoding
assumptions. This is appropriate for files which are written in single-byte
processing is not done.
The value B<guess> tells perltidy to guess between either utf8 encoding or no
-encoding (meaning one character per byte). The 'guess' option uses the
-Encode::Guess module which has been found to be quite reliable at detecting
+encoding (meaning one character per byte). The B<guess> option uses the
+Encode::Guess module which has been found to be reliable at detecting
if a file is encoded in utf8 or not.
The current default is B<guess>.
The abbreviations B<-utf8> or B<-UTF8> are equivalent to B<-enc=utf8>, and the
-abbreviation B<-guess> is equivalent to <-enc=guess>. So to process a file
+abbreviation B<-guess> is equivalent to B<-enc=guess>. So to process a file
named B<file.pl> which is encoded in UTF-8 you can use:
perltidy -utf8 file.pl
or
+
perltidy -guess file.pl
or simply
=item B<-eos=s>, B<--encode-output-strings=s>
This flag has been added to resolve an issue involving the interface between
-Perl::Tidy and calling programs, and in particular the widely used B<tidyall>
-program. The crux of the matter is that, as a result of its historical
-evolution, by default perltidy returns unencoded strings to the calling
-program. Some programs need encoded strings, and setting this flag causes
-Perl::Tidy to encode output strings, but only if it decoded them. For some
-background information see the discussion at github for perltidy issue git #83 at
-L<https://github.com/perltidy/perltidy/issues/83>
+Perl::Tidy and calling programs, and in particular B<Code::TidyAll (tidyall)>.
+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
+L<https://github.com/perltidy/perltidy/issues/83> and
+L<https://github.com/houseabsolute/perl-code-tidyall/issues/84>.
If you only run the perltidy binary this flag has no effect.
-If you use B<tidyall> with encoded files you should probably set this flag.
+If you use B<tidyall> with encoded files and encounter irregularities such as
+B<wide character> messages you should set this flag.
=item B<-gcs>, B<--use-unicode-gcstring>
which are avoided with the newer B<-xlp> flag. So B<-xlp> is probably the better
choice for new work, but the B<-lp> flag is retained to minimize changes to
existing formatting.
+If you enter both B<-lp> and B<-xlp>, then B<-xlp> will be used.
+
In the default indentation method perltidy indents lists with 4 spaces, or
whatever value is specified with B<-i=n>. Here is a small list formatted in
These flags have no effect on code BLOCKS, such as if/then/else blocks,
which always use whatever is specified with B<-i=n>.
+Some limitiations on these flags are:
+
+=over 4
+
+=item *
+
A limitation on B<-lp>, but not B<-xlp>, occurs in situations where perltidy
-does not have complete freedom to choose line breaks it may temporarily revert
+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).
+=item *
+
For both the B<-lp> and B<-xlp> 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<-fnl>,
B<-nanl>, and B<-ndnl>.
+=item *
+
The B<-lp> and B<-xlp> options may not be used together with the B<-t> tabs option.
They may, however, be used with the B<-et=n> tab method
-If you enter both B<-lp> and B<-xlp>, then B<-xlp> will be used.
+=back
There are some potential disadvantages of this indentation method compared to
the default method that should be noted:
-(1) The available line length can quickly be used up if variable names are
+=over 4
+
+=item *
+
+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.
-(2) Since the indentation depends on the lengths of variable names, small
+=item *
+
+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.
+=back
+
Some things that can be done to minimize these problems are:
-(1) Increase B<--maximum-line-length=n> above the default B<n=80> characters if
+=over 4
+
+=item *
+
+Increase B<--maximum-line-length=n> above the default B<n=80> characters if
necessary.
-(2) If you use B<-xlp> then long side comments can limit the indentation over
+=item *
+
+If you use B<-xlp> then long side comments can limit the indentation over
multiple lines. Consider adding the flag B<--ignore-side-comment-lengths> to
prevent this, or minimizing the use of side comments.
-(3) Apply this style in a limited way. By default, it applies to all list
+=item *
+
+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.
+=back
+
=item B<-lpil=s>, B<--line-up-parentheses-inclusion-list> and B<-lpxl=s>, B<--line-up-parentheses-exclusion-list>
-These parameters can be used to restrict the application of the B<-lp> or B<-xlp> styles.
The following discussion is written for B<-lp> but applies equally to the newer B<-xlp> version.
+By default, the B<-lp> flag applies to as many containers as possible.
+The set of containers to which the B<-lp> style applies can be reduced by
+either one of these two flags:
-The B<-lp> 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. One solution to this problem is to limit the application
-of this style to just certain containers. By default, the B<-lp> flag applies
-to as many containers as possible. The set of containers to which it applies
-can be reduced by either one of these two flags:
-
-The B<-lpil=s> flag to specifies the containers to which B<-lp> applies.
+Use B<-lpil=s> to specify the containers to which B<-lp> applies, or
-The B<-lpxl=s> flag to specifies the containers to which B<-lp> does NOT apply.
+use B<-lpxl=s> to specify the containers to which B<-lp> does NOT apply.
Only one of these two flags may be used. Both flags can achieve the same
result, but the B<-lpil=s> flag is much easier to describe and use and is
recommended. The B<-lpxl=s> flag was the original implementation and is
-retained for backwards compatibility.
+only retained for backwards compatibility.
This list B<s> 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
which says to exclude lists within square-brackets and braces. So what remains is lists within parentheses.
-A second B<optional> item of information which can be given for parentheses is an alphanumeric
+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:
fixit($i);
}
-Use B<-nola> to not outdent labels.
+Use B<-nola> to not outdent labels. To control line breaks after labels see L<bal=n, --break-after-labels=n>.
=item B<Outdenting Keywords>
Notice in this last example that although only the equals alignment was
excluded, the ternary alignments were also lost. This happens because the
vertical aligner sweeps from left-to-right and usually stops if an important
-alignment cannot be made for some reason.
+alignment cannot be made for some reason.
But also notice that side comments remain aligned because their alignment is
controlled separately with the parameter B<--valign-side_comments> described above.
projects / perltidy.git / commitdiff