From: Steve Hancock Date: Sun, 6 Feb 2022 02:14:43 +0000 (-0800) Subject: update docs X-Git-Tag: 20220217~11 X-Git-Url: https://git.donarmstrong.com/?a=commitdiff_plain;h=81be8ae05bda6532e2c112ccda34d91f62e0ec21;p=perltidy.git update docs --- diff --git a/CHANGES.md b/CHANGES.md index b11ed093..b497cf37 100644 --- a/CHANGES.md +++ b/CHANGES.md @@ -2,6 +2,25 @@ ## 2021 10 29.06 + - 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. + + - 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 + 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: @@ -26,23 +45,6 @@ - Fix issue git #82, an error handling something like ${bareword} in a possible indirect object location. - - 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 - 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, --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. If you use tidyall and have - encoded files you may want to set this flag. The crux of the matter is - that by default perltidy returns unencoded strings to the calling program. - Some programs need encoded strings, and setting this flag causes encoding. - If you use tidyall with encoded files (like utf8) you should probably - set this flag. If you run the perltidy binary this flag has no effect. - - 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 diff --git a/lib/Perl/Tidy.pm b/lib/Perl/Tidy.pm index 33018ee9..b0c98424 100644 --- a/lib/Perl/Tidy.pm +++ b/lib/Perl/Tidy.pm @@ -1677,10 +1677,13 @@ EOM # output to a string or array ref. We use the -eos flag to decide # if we should encode. - # [DEFAULT]: encoding is done by the program which writes to the - # file system. In this case, we do not encode string output. + # [DEFAULT]: perltidy does not return encoded string output. This + # is a result of the code evolution but not very convenient for most + # applications. It would be hard to change without breaking some + # programs. - # [WITH -eos flag]: encoding is done by the program which decodes. + # [WITH -eos flag]: If perltidy decodes a string, regardless of + # source, it encodes before returning. if ( $rOpts->{'encode-output-strings'} && $decoded_input_as ) { my $encoded_buffer; diff --git a/lib/Perl/Tidy.pod b/lib/Perl/Tidy.pod index 081d3c95..f42ba127 100644 --- a/lib/Perl/Tidy.pod +++ b/lib/Perl/Tidy.pod @@ -88,13 +88,14 @@ characters, then by default it will NOT be encoded by Perl::Tidy. This default is not always convenient, particularly if the calling program did not do the decoding, and can be changed by including the B<-eos> or -B<--encode-output-strings> flag described in the B manual. When this -flag is set, and if Perl::Tidy decoded a string, then it will encode the string -before returning. For some background information see the discussion at github -for perltidy issue git #83 at +B<--encode-output-strings> flag described in the B manual. This can +either be set by the user or by the calling program in the B parameter +described below. When this flag is set, and if Perl::Tidy decoded a string, +then it will encode the string before returning. For some background +information see the discussion at github for perltidy issue git #83 at L. -This B<-eos> parameter was added after perltidy version 20211029.05. +This B<-eos> parameter is available in perltidy version 20211029.06 and later. =item stderr