From: Steve Hancock Date: Mon, 7 Feb 2022 18:50:02 +0000 (-0800) Subject: update docs X-Git-Tag: 20220217~9 X-Git-Url: https://git.donarmstrong.com/?a=commitdiff_plain;h=0d6c246d722649715ea5b21379363c3c9a1d034a;p=perltidy.git update docs --- diff --git a/CHANGES.md b/CHANGES.md index b497cf37..64a4bba8 100644 --- a/CHANGES.md +++ b/CHANGES.md @@ -4,33 +4,31 @@ - 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: { @@ -43,7 +41,7 @@ } - 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 @@ -52,7 +50,8 @@ - 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 @@ -63,19 +62,16 @@ 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 @@ -181,8 +177,8 @@ 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. @@ -249,14 +245,14 @@ 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: @@ -267,7 +263,7 @@ # perltidy -sfp myfun ( $aaa, $b, $cc ); mylongfun ( $a, $b, $c ); - + # perltidy -sfp -nfpva myfun ( $aaa, $b, $cc ); mylongfun ( $a, $b, $c ); @@ -362,9 +358,9 @@ ## 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 @@ -377,7 +373,7 @@ - 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 @@ -385,7 +381,7 @@ 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. diff --git a/bin/perltidy b/bin/perltidy index df7d6aee..bc593239 100755 --- a/bin/perltidy +++ b/bin/perltidy @@ -392,9 +392,9 @@ You do not need to include any sub aliases in these lists. Just include keyword =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 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, B or B. The string B 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 @@ -604,10 +604,11 @@ as 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 directives). -The possible values for B are : -(1) B if no encoding is used, or -(2) B or B or B, or -(3) if perltidy should guess between these two possibilities. +The possible values for B 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 causes the stream to be processed without special encoding assumptions. This is appropriate for files which are written in single-byte @@ -618,19 +619,20 @@ UTF-8. If the input stream cannot be decoded with this encoding then processing is not done. The value B 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 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. 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 which is encoded in UTF-8 you can use: perltidy -utf8 file.pl or + perltidy -guess file.pl or simply @@ -646,17 +648,18 @@ post-processing to handle decoding and encoding. =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 -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 +Perl::Tidy and calling programs, and in particular 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 +L and +L. If you only run the perltidy binary this flag has no effect. -If you use B with encoded files you should probably set this flag. +If you use B with encoded files and encounter irregularities such as +B messages you should set this flag. =item B<-gcs>, B<--use-unicode-gcstring> @@ -827,6 +830,8 @@ original flag for this is B<-lp>, but it has some limitations (explained below) 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 @@ -856,72 +861,95 @@ closing paren, see the next section. 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 characters if +=over 4 + +=item * + +Increase B<--maximum-line-length=n> above the default B 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 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 @@ -940,7 +968,7 @@ The same thing could alternatively be specified with which says to exclude lists within square-brackets and braces. So what remains is lists within parentheses. -A second B 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: @@ -1123,7 +1151,7 @@ has been set to), if possible. This is the default. For example: fixit($i); } -Use B<-nola> to not outdent labels. +Use B<-nola> to not outdent labels. To control line breaks after labels see L. =item B @@ -4361,7 +4389,7 @@ To exclude only the equals we could use: 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. diff --git a/lib/Perl/Tidy/Formatter.pm b/lib/Perl/Tidy/Formatter.pm index 13ffdabb..d780160b 100644 --- a/lib/Perl/Tidy/Formatter.pm +++ b/lib/Perl/Tidy/Formatter.pm @@ -2343,9 +2343,9 @@ EOM $rkeep_break_hash->{'('} = 1; $rkeep_break_hash->{'['} = 1; Warn(<