+
=head1 NAME
Perl::Tidy - Parses and beautifies perl source
The call to B<perltidy> returns a scalar B<$error_flag> which is TRUE if an
error caused premature termination, and FALSE if the process ran to normal
-completion. Additional discuss of errors is contained below in the L<ERROR
-HANDLING> section.
+completion. Additional discuss of errors is contained below in the
+L<ERROR HANDLING|"ERROR HANDLING"> section.
The module accepts input and output streams by a variety of methods.
The following list of parameters may be any of the following: a
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<argv> paremeter (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<argv> parameter passed to Perl::Tidy.
-=item *
+=back
-The current default is B<-neos>, but B<the default could change in a future
-version>, 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<https://github.com/perltidy/perltidy/blob/master/docs/eos_flag.md>.
-=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<https://github.com/perltidy/perltidy/issues/83> and
-L<https://github.com/houseabsolute/perl-code-tidyall/issues/84>.
+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<stderr>
being sought. If so, the above write_line prints the token and its
line number.
-The B<formatter> feature is relatively new in perltidy, and further
-documentation needs to be written to complete its description. However,
-several example programs have been written and can be found in the
-B<examples> section of the source distribution. Probably the best way
-to get started is to find one of the examples which most closely matches
-your application and start modifying it.
+The B<examples> section of the source distribution has some examples of programs which use the B<formatter> option.
For help with perltidy's peculiar way of breaking lines into tokens, you
might run, from the command line,
F<filename.DEBUG> with interleaved lines of text and their token types.
The B<-D> flag has been in perltidy from the beginning for this purpose.
If you want to see the code which creates this file, it is
-C<write_debug_entry> in Tidy.pm.
+C<sub Perl::Tidy::Debugger::write_debug_entry>
=head1 EXPORT
=head1 VERSION
-This man page documents Perl::Tidy version 20220217
+This man page documents Perl::Tidy version 20220613
=head1 LICENSE
=head1 BUG REPORTS
-A list of current bugs and issues can be found at the CPAN site L<https://rt.cpan.org/Public/Dist/Display.html?Name=Perl-Tidy>
-
-To report a new bug or problem, use the link on this page.
-
The source code repository is at L<https://github.com/perltidy/perltidy>.
+To report a new bug or problem, use the "issues" link on this page.
+
=head1 SEE ALSO
The perltidy(1) man page describes all of the features of perltidy. It
projects / perltidy.git / blobdiff