<pre><code> use Perl::Tidy;
Perl::Tidy::perltidy();</code></pre>
-<p>The call to <b>perltidy</b> returns a scalar <b>$error_flag</b> 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 <a href="#ERROR-HANDLING">"ERROR HANDLING"</a> section.</p>
+<p>The call to <b>perltidy</b> returns a scalar <b>$error_flag</b> 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 <a href="#ERROR-HANDLING">ERROR HANDLING</a> section.</p>
<p>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 <b>getline</b> or <b>print</b> method, as appropriate.</p>
<p>If the <b>destination</b> parameter is given, it will be used to define the file or memory location to receive output of perltidy.</p>
-<p><b>Important note if destination is a string or array reference</b>. 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 <b>--encode-output-strings</b>, or simply <b>-eos</b>, was added in versions of Perl::Tidy after 20220101 for this purpose. This flag should be added to the end of the <b>argv</b> paremeter (described below) if Perl::Tidy will be decoding utf8 text. The options are as follows.</p>
+<p><b>Important note if destination is a string or array reference</b>. 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 <b>--encode-output-strings</b>, or simply <b>-eos</b>, was added in Perl::Tidy version 20220217 for this purpose.</p>
<ul>
-<li><p>Use <b>-eos</b> 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.</p>
+<li><p>Use <b>-eos</b> 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.</p>
</li>
-<li><p>Use <b>-neos</b> 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.</p>
-
-</li>
-<li><p>The current default is <b>-neos</b>, but <b>the default could change in a future version</b>, so <b>-neos</b> should still be set, if appropriate, to allow for the possibility of a future change in the default.</p>
+<li><p>Use <b>-neos</b> 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 <b>argv</b> parameter passed to Perl::Tidy.</p>
</li>
</ul>
-<p>For example, to set <b>-eos</b> the following could be used</p>
+<p>For some background information see <a href="https://github.com/perltidy/perltidy/blob/master/docs/eos_flag.md">https://github.com/perltidy/perltidy/blob/master/docs/eos_flag.md</a>.</p>
+
+<p>This change in default behavior was made over a period of time as follows:</p>
-<pre><code> $argv .= " -eos" if ( $Perl::Tidy::VERSION > 20220101 );
+<ul>
+
+<li><p>For versions before 20220217 the <b>-eos</b> flag was not available and the behavior was equivalent to <b>-neos</b>.</p>
- $error_flag = Perl::Tidy::perltidy(
- argv => $argv,
- source => \$source,
- destination => \$destination,
- stderr => \$stderr,
- errorfile => \$errorfile
- );</code></pre>
+</li>
+<li><p>In version 20220217 the <b>-eos</b> flag was added but the default remained <b>-neos</b>.</p>
-<p>The test on version allows older versions of Perl::Tidy to still be used.</p>
+</li>
+<li><p>For versions after 20220217 the default was set to <b>-eos</b>.</p>
-<p>For some background information see <a href="https://github.com/perltidy/perltidy/issues/83">https://github.com/perltidy/perltidy/issues/83</a> and <a href="https://github.com/houseabsolute/perl-code-tidyall/issues/84">https://github.com/houseabsolute/perl-code-tidyall/issues/84</a>.</p>
+</li>
+</ul>
</dd>
<dt id="stderr"><b>stderr</b></dt>
<p>In the present example, we are only looking for tokens of type <b>i</b> (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.</p>
-<p>The <b>formatter</b> 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</b> 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.</p>
+<p>The <b>examples</b> section of the source distribution has some examples of programs which use the <b>formatter</b> option.</p>
<p>For help with perltidy's peculiar way of breaking lines into tokens, you might run, from the command line,</p>
<pre><code> perltidy -D filename</code></pre>
-<p>where <i>filename</i> is a short script of interest. This will produce <i>filename.DEBUG</i> with interleaved lines of text and their token types. The <b>-D</b> flag has been in perltidy from the beginning for this purpose. If you want to see the code which creates this file, it is <code>write_debug_entry</code> in Tidy.pm.</p>
+<p>where <i>filename</i> is a short script of interest. This will produce <i>filename.DEBUG</i> with interleaved lines of text and their token types. The <b>-D</b> flag has been in perltidy from the beginning for this purpose. If you want to see the code which creates this file, it is <code>sub Perl::Tidy::Debugger::write_debug_entry</code></p>
<h1 id="EXPORT">EXPORT</h1>
<h1 id="VERSION">VERSION</h1>
-<p>This man page documents Perl::Tidy version 20220217</p>
+<p>This man page documents Perl::Tidy version 20220613</p>
<h1 id="LICENSE">LICENSE</h1>
<h1 id="BUG-REPORTS">BUG REPORTS</h1>
-<p>A list of current bugs and issues can be found at the CPAN site <a href="https://rt.cpan.org/Public/Dist/Display.html?Name=Perl-Tidy">https://rt.cpan.org/Public/Dist/Display.html?Name=Perl-Tidy</a></p>
-
-<p>To report a new bug or problem, use the link on this page.</p>
-
<p>The source code repository is at <a href="https://github.com/perltidy/perltidy">https://github.com/perltidy/perltidy</a>.</p>
+<p>To report a new bug or problem, use the "issues" link on this page.</p>
+
<h1 id="SEE-ALSO">SEE ALSO</h1>
<p>The perltidy(1) man page describes all of the features of perltidy. It can be found at http://perltidy.sourceforge.net.</p>
projects / perltidy.git / blobdiff