use Perl::Tidy;
Perl::Tidy::perltidy();The call to perltidy returns a scalar $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 "ERROR HANDLING" section.
+The call to perltidy returns a scalar $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 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 filename, an ARRAY reference, a SCALAR reference, or an object with either a getline or print method, as appropriate.
@@ -101,36 +101,34 @@If the destination parameter is given, it will be used to define the file or memory location to receive output of perltidy.
-Important note if destination is a string or array reference. Perl strings 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 --encode-output-strings, or simply -eos, was added in versions of Perl::Tidy after 20220101 for this purpose. This flag should be added to the end of the argv paremeter (described below) if Perl::Tidy will be decoding utf8 text. The options are as follows.
+Important note if destination is a string or array reference. Perl strings 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 --encode-output-strings, or simply -eos, was added in Perl::Tidy version 20220217 for this purpose.
Use -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 -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.
Use -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.
- -The current default is -neos, but the default could change in a future version, so -neos should still be set, if appropriate, to allow for the possibility of a future change in the default.
+Use -neos if 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. If needed, this flag can be added to the end of the argv parameter passed to Perl::Tidy.
For example, to set -eos the following could be used
+For some background information see https://github.com/perltidy/perltidy/blob/master/docs/eos_flag.md.
+ +This change in default behavior was made over a period of time as follows:
- $argv .= " -eos" if ( $Perl::Tidy::VERSION > 20220101 );
+
+
+For versions before 20220217 the -eos flag was not available and the behavior was equivalent to -neos.
- $error_flag = Perl::Tidy::perltidy(
- argv => $argv,
- source => \$source,
- destination => \$destination,
- stderr => \$stderr,
- errorfile => \$errorfile
- );
In version 20220217 the -eos flag was added but the default remained -neos.
-The test on version allows older versions of Perl::Tidy to still be used.
+For versions after 20220217 the default was set to -eos.
-For some background information see https://github.com/perltidy/perltidy/issues/83 and https://github.com/houseabsolute/perl-code-tidyall/issues/84.
+In the present example, we are only looking for tokens of type i (identifiers), so the for loop skips past all other types. When an identifier is found, its actual text is checked to see if it is one being sought. If so, the above write_line prints the token and its line number.
-The 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 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 examples section of the source distribution has some examples of programs which use the formatter option.
For help with perltidy's peculiar way of breaking lines into tokens, you might run, from the command line,
perltidy -D filenamewhere filename is a short script of interest. This will produce filename.DEBUG with interleaved lines of text and their token types. The -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 write_debug_entry in Tidy.pm.
where filename is a short script of interest. This will produce filename.DEBUG with interleaved lines of text and their token types. The -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 sub Perl::Tidy::Debugger::write_debug_entry
This man page documents Perl::Tidy version 20220217
+This man page documents Perl::Tidy version 20220613
A list of current bugs and issues can be found at the CPAN site 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 https://github.com/perltidy/perltidy.
+To report a new bug or problem, use the "issues" link on this page.
+The perltidy(1) man page describes all of the features of perltidy. It can be found at http://perltidy.sourceforge.net.