From: Steve Hancock Date: Fri, 27 May 2022 13:33:50 +0000 (-0700) Subject: update docs and fix spelling X-Git-Tag: 20220613~12 X-Git-Url: https://git.donarmstrong.com/?a=commitdiff_plain;h=f4547c5d4caf92a78114286ff2a236f3b897baf5;p=perltidy.git update docs and fix spelling --- diff --git a/bin/perltidy b/bin/perltidy index e6c1418e..62a7c629 100755 --- a/bin/perltidy +++ b/bin/perltidy @@ -384,14 +384,14 @@ For example, perltidy -sal='method fun _sub M4' -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. +will cause the perltidy to treat the words 'method', 'fun', '_sub' and 'M4' 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. Note that several other parameters accept a list of keywords, including 'sub' (see L<"Specifying Block Types">). 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. =item B<-gal=s>, B<--grep-alias-list=s> -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 flag allows a code block following an external 'list operator' function to be formatted as if it followed one of the built-in keywords B, B or B. The string B contains the names of one or more such list operators, separated by spaces or commas. By 'list operator' is meant a function which is invoked in the form @@ -518,7 +518,7 @@ Before starting to use tabs, it is essential to first get the indentation controls set as desired without tabs, particularly the two parameters B<--indent-columns=n> (or B<-i=n>) and B<--continuation-indentation=n> (or B<-ci=n>). The value of the integer 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> will +number of spaces used for indentation. For example, B<-et=4 -ci=4 -i=4> 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 with what your display software assumes for the spacing of a tab. @@ -603,7 +603,7 @@ this flag is in effect. =item B<-enc=s>, B<--character-encoding=s> 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 +Perltidy does not look for the encoding directives in the source stream, such 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). @@ -651,21 +651,34 @@ 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 +This flag was added to resolve an issue involving the interface between 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 B binary this flag has no effect. +If you only run the B binary this flag has no effect. If you run a +program which calls the Perl::Tidy module and receives a string in return, then +the meaning of the flag is as follows: -If you use B with encoded files and encounter irregularities such as -B messages you should set this flag. +=over 4 + +=item * + +The setting B<-eos> means Perl::Tidy should encode any string which it decodes. +This is the default because it makes perltidy behave well as a filter, +and is the correct setting for most programs. + +=item * + +The setting B<-neos> means that a string should remain decoded if it was +decoded by Perl::Tidy. This is only appropriate if the calling program will +handle any needed encoding before outputting the string. -Additional information can be found in the man pages for the B module. +=back + +The default was changed from B<-neos> to B<-eos> in versions after 20220217. +If this change causes a program to start running incorrectly on encoded files, +an emergency fix might be to set B<-neos>. Additional information can be found +in the man pages for the B module and also in +L. =item B<-gcs>, B<--use-unicode-gcstring> @@ -820,7 +833,7 @@ To guess the starting indentation level perltidy simply assumes that indentation scheme used to create the code snippet is the same as is being used for the current perltidy process. This is the only sensible guess that can be made. It should be correct if this is true, but otherwise it probably won't. -For example, if the input script was written with -i=2 and the current peltidy +For example, if the input script was written with -i=2 and the current perltidy flags have -i=4, the wrong initial indentation will be guessed for a code snippet which has non-zero initial indentation. Likewise, if an entabbing scheme is used in the input script and not in the current process then the @@ -867,7 +880,7 @@ 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: +Some limitations on these flags are: =over 4 @@ -957,7 +970,7 @@ 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 only retained for backwards compatibility. -This list B for these parametes is a string with space-separated items. +This list B for these parameters 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. @@ -967,7 +980,7 @@ The only required piece of information is a container type, which is one of -lpil='(' -means use -lp formatting only on lists within parentheses, not lists in square-bracets or braces. +means use -lp formatting only on lists within parentheses, not lists in square-brackets or braces. The same thing could alternatively be specified with -lpxl = '[ {' @@ -979,7 +992,7 @@ 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: - 'k' matches if the previous nonblank token is a perl builtin keyword (such as 'if', 'while'), + 'k' matches if the previous nonblank token is a perl built-in 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. @@ -1443,7 +1456,7 @@ But the following will give a syntax error: for my $severity ( reverse $SEVERITY_LOWEST +1 .. $SEVERITY_HIGHEST ) { ... } 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. +binary operator asymmetrically with a space on the left but not on the right. =item B @@ -2851,7 +2864,7 @@ 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: - 'k' matches if the previous nonblank token is a perl builtin keyword (such as 'if', 'while'), + 'k' matches if the previous nonblank token is a perl built-in 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. @@ -3281,9 +3294,9 @@ single perl operator except B<=> on a -wbb flag. =item B This flag controls whether or not a line break occurs after a label. There -are three possible valuse for B: +are three possible values for B: - -bal=0 break if there is a break in the input [DEFAULt] + -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 @@ -3619,7 +3632,7 @@ these meanings (these are the same as used in the B<--weld-nested-exclusion-list> and B<--line-up-parentheses-exclusion-list> parameters): - 'k' matches if the previous nonblank token is a perl builtin keyword (such as 'if', 'while'), + 'k' matches if the previous nonblank token is a perl built-in 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. @@ -4012,7 +4025,7 @@ B and B statements. B<-kgbd> or B<--keyword-group-blanks-delete> controls the deletion of any blank lines that exist in the the group when it is first scanned. When statements are initially scanned, any existing blank lines are included in the -collection. Any such orignial blank lines will be deleted before any other +collection. Any such original blank lines will be deleted before any other insertions are made when the parameter B<-kgbd> is set. The default is not to do this, B<-nkgbd>. @@ -4309,7 +4322,7 @@ For example, =item B -The default is to use vertical alignment, but bertical alignment can be +The default is to use vertical alignment, but vertical alignment can be completely turned of with the B<-novalign> flag. A lower level of control of vertical alignment is possible with three parameters @@ -4329,7 +4342,7 @@ below. =item B The B<-vsc> flag enables alignment of side comments and is enabled by default. If side -comment aligment is disabled with B<-nvsc> they will appear at a fixed space from the +comment alignment is disabled with B<-nvsc> they will appear at a fixed space from the preceding code token. The default is B<-vsc> =item B @@ -4350,14 +4363,18 @@ of the tokens ',', '=', and '=>', but many other alignments are possible and are { ( ? : , ; => && || ~~ !~~ =~ !~ // <=> -> q if unless and or err for foreach while until -The 'q' in this list refers to a qw quote. These alignments are all enabled by default, but they can be selectively disabled by including one or more of these tokens in the space-separated list B. +These alignment types correspond to perl symbols, operators and keywords except +for 'q', which refers to the special case of alignment in a 'use' statement of +qw quotes and empty parens. + +They are all enabled by default, but they can be selectively disabled by including one or more of these tokens in the space-separated list B. For example, the following would prevent alignment at B<=> and B: --valign-exclusion-list='= if' 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>. -You may leave the B undefined, or use the special symbol B<*> for the exclusion list. +In that case you may leave the B undefined, or use the special symbol B<*> for the exclusion list. For example, the following parameters enable alignment only at commas and 'fat commas': --valign-inclusion-list=', =>' @@ -4466,7 +4483,7 @@ F. Note that these last two system-wide files do not have a leading dot. Further system-dependent information will be found in the INSTALL file distributed with perltidy. -Under Windows, perltidy will also search for a configuration file named perltidy.ini since Windows does not allow files with a leading period (.). +Under Windows, perltidy will also search for a configuration file named F since Windows does not allow files with a leading period (.). Use C to see the possible locations for your system. An example might be F. diff --git a/lib/Perl/Tidy.pod b/lib/Perl/Tidy.pod index 4dd8bc69..06e7d83e 100644 --- a/lib/Perl/Tidy.pod +++ b/lib/Perl/Tidy.pod @@ -89,49 +89,47 @@ of characters which are decoded as utf8 by Perl::Tidy can be returned in either of two possible states, decoded or encoded, and it is important that the calling program and Perl::Tidy are in agreement regarding the state to be returned. A flag B<--encode-output-strings>, or simply B<-eos>, was added in -versions of Perl::Tidy after 20220101 for this purpose. This flag should be -added to the end of the B parameter (described below) if Perl::Tidy -will be decoding utf8 text. The options are as follows. +Perl::Tidy version 20220217 for this purpose. =over 4 =item * -Use B<-eos> if Perl::Tidy should encode any string which it decodes. -This is probably most convenient for most programs. -But do not use this setting if the calling program will -encode the data too, because double encoding will corrupt data. +Use B<-eos> if Perl::Tidy should encode any string which it decodes. This is +the current default because it makes perltidy behave well as a filter, and is +the correct setting for most programs. But do not use this setting if the +calling program will encode the data too, because double encoding will corrupt +data. =item * Use B<-neos> if a string should remain decoded if it was decoded by Perl::Tidy. -This is appropriate if -the calling program will handle any needed encoding before outputting the string. +This is only appropriate if the calling program will handle any needed encoding +before outputting the string. If needed, this flag can be added to the end of +the B parameter passed to Perl::Tidy. -=item * +=back -The current default is B<-neos>, but B, so B<-neos> should still be set, if appropriate, to allow for the -possibility of a future change in the default. +For some background information see +L. -=back +This change in default behavior was made over a period of time as follows: -For example, to set B<-eos> the following could be used +=over 4 - $argv .= " -eos" if ( $Perl::Tidy::VERSION > 20220101 ); +=item * - $error_flag = Perl::Tidy::perltidy( - argv => $argv, - source => \$source, - destination => \$destination, - stderr => \$stderr, - errorfile => \$errorfile - ); +For versions before 20220217 the B<-eos> flag was not available and the behavior was equivalent to B<-neos>. -The test on version allows older versions of Perl::Tidy to still be used. +=item * -For some background information see -L +In version 20220217 the B<-eos> flag was added but the default remained B<-neos>. + +=item * + +For versions after 20220217 the default was set to B<-eos>. + +=back =item B