<li><a href="#SWITCHES-WHICH-MAY-BE-NEGATED">SWITCHES WHICH MAY BE NEGATED</a></li>
<li><a href="#LIMITATIONS">LIMITATIONS</a></li>
<li><a href="#FILES">FILES</a></li>
+ <li><a href="#ERROR-HANDLING">ERROR HANDLING</a></li>
<li><a href="#SEE-ALSO">SEE ALSO</a></li>
+ <li><a href="#INSTALLATION">INSTALLATION</a></li>
<li><a href="#VERSION">VERSION</a></li>
<li><a href="#BUG-REPORTS">BUG REPORTS</a></li>
<li><a href="#COPYRIGHT">COPYRIGHT</a></li>
<p>Force perltidy to process binary files. To avoid producing excessive error messages, perltidy skips files identified by the system as non-text. However, valid perl scripts containing binary data may sometimes be identified as non-text, and this flag forces perltidy to process them.</p>
+</dd>
+<dt id="ast---assert-tidy"><b>-ast</b>, <b>--assert-tidy</b></dt>
+<dd>
+
+<p>This flag asserts that the input and output code streams are identical, or in other words that the input code is already 'tidy' according to the formatting parameters. If this is not the case, an error message noting this is produced. This error message will cause the process to return a non-zero exit code. The test for this is made by comparing an MD5 hash value for the input and output code streams. This flag has no other effect on the functioning of perltidy. This might be useful for certain code maintenance operations.</p>
+
+</dd>
+<dt id="asu---assert-untidy"><b>-asu</b>, <b>--assert-untidy</b></dt>
+<dd>
+
+<p>This flag asserts that the input and output code streams are different, or in other words that the input code is 'untidy' according to the formatting parameters. If this is not the case, an error message noting this is produced. This flag has no other effect on the functioning of perltidy.</p>
+
+</dd>
+<dt id="sal-s---sub-alias-list-s"><b>-sal=s</b>, <b>--sub-alias-list=s</b></dt>
+<dd>
+
+<p>This flag causes one or more words to be treated the same as if they were the keyword 'sub'. The string <b>s</b> contains one or more alias words, separated by spaces or commas.</p>
+
+<p>For example,</p>
+
+<pre><code> perltidy -sal='method fun _sub M4' </code></pre>
+
+<p>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.</p>
+
</dd>
</dl>
<p>You will probably also want to use the flag <b>-skp</b> (previous item) too.</p>
+</dd>
+<dt id="spp-n-or---space-prototype-paren-n"><b>-spp=n</b> or <b>--space-prototype-paren=n</b></dt>
+<dd>
+
+<p>This flag can be used to control whether a function prototype is preceded by a space. For example, the following prototype does not have a space.</p>
+
+<pre><code> sub usage();</code></pre>
+
+<p>This integer <b>n</b> may have the value 0, 1, or 2 as follows:</p>
+
+<pre><code> -spp=0 means no space before the paren
+ -spp=1 means follow the example of the source code [DEFAULT]
+ -spp=2 means always put a space before the paren</code></pre>
+
+<p>The default is <b>-spp=1</b>, meaning that a space will be used if and only if there is one in the source code. Given the above line of code, the result of applying the different options would be:</p>
+
+<pre><code> sub usage(); # n=0 [no space]
+ sub usage(); # n=1 [default; follows input]
+ sub usage (); # n=2 [space]</code></pre>
+
</dd>
<dt id="Trimming-whitespace-around-qw-quotes">Trimming whitespace around <code>qw</code> quotes</dt>
<dd>
<p>Note that the <b>n=2</b> option has no effect if adding semicolons is prohibited with the <b>-nasc</b> flag. Also not that while <b>n=2</b> adds missing semicolons to all one-line blocks, regardless of complexity, the <b>n=0</b> option only removes ending semicolons which terminate one-line blocks containing just one semicolon. So these two options are not exact inverses.</p>
+</dd>
+<dt id="olbn-n---one-line-block-nesting-n"><b>-olbn=n</b>, <b>--one-line-block-nesting=n</b></dt>
+<dd>
+
+<p>Nested one-line blocks are lines with code blocks which themselves contain code blocks. For example, the following line is a nested one-line block.</p>
+
+<pre><code> foreach (@list) { if ($_ eq $asked_for) { last } ++$found }</code></pre>
+
+<p>The default behavior is to break such lines into multiple lines, but this behavior can be controlled with this flag. The values of n are:</p>
+
+<pre><code> n=0 break nested one-line blocks into multiple lines [DEFAULT]
+ n=1 stable: keep existing nested-one line blocks intact</code></pre>
+
+<p>For the above example, the default formatting (<b>-olbn=0</b>) is</p>
+
+<pre><code> foreach (@list) {
+ if ( $_ eq $asked_for ) { last }
+ ++$found;
+ }</code></pre>
+
+<p>If the parameter <b>-olbn=1</b> is given, then the line will be left intact if it is a single line in the source, or it will be broken into multiple lines if it is broken in multiple lines in the source.</p>
+
</dd>
</dl>
<h2 id="Specifying-File-Extensions">Specifying File Extensions</h2>
-<p>Several parameters allow default file extensions to be overridden. For example, a backup file extension may be specified with <b>-bext=ext</b>, where <b>ext</b> is some new extension. In order to provides the user some flexibility, the following convention is used in all cases to decide if a leading '.' should be used. If the extension <code>ext</code> begins with <code>A-Z</code>, <code>a-z</code>, or <code>0-9</code>, then it will be appended to the filename with an intermediate '.' (or perhaps an '_' on VMS systems). Otherwise, it will be appended directly.</p>
+<p>Several parameters allow default file extensions to be overridden. For example, a backup file extension may be specified with <b>-bext=ext</b>, where <b>ext</b> is some new extension. In order to provides the user some flexibility, the following convention is used in all cases to decide if a leading '.' should be used. If the extension <code>ext</code> begins with <code>A-Z</code>, <code>a-z</code>, or <code>0-9</code>, then it will be appended to the filename with an intermediate '.' (or perhaps a '_' on VMS systems). Otherwise, it will be appended directly.</p>
<p>For example, suppose the file is <i>somefile.pl</i>. For <code>-bext=old</code>, a '.' is added to give <i>somefile.pl.old</i>. For <code>-bext=.old</code>, no additional '.' is added, so again the backup file is <i>somefile.pl.old</i>. For <code>-bext=~</code>, then no dot is added, and the backup file will be <i>somefile.pl~</i> .</p>
</dd>
</dl>
+<h1 id="ERROR-HANDLING">ERROR HANDLING</h1>
+
+<p>An exit value of 0, 1, or 2 is returned by perltidy to indicate the status of the result.</p>
+
+<p>A exit value of 0 indicates that perltidy ran to completion with no error messages.</p>
+
+<p>A non-zero exit value indicates some kind of problem was detected.</p>
+
+<p>An exit value of 1 indicates that perltidy terminated prematurely, usually due to some kind of errors in the input parameters. This can happen for example if a parameter is misspelled or given an invalid value. Error messages in the standard error output will indicate the cause of any problem. If perltidy terminates prematurely then no output files will be produced.</p>
+
+<p>An exit value of 2 indicates that perltidy was able to run to completion but there there are (1) warning messages in the standard error output related to parameter errors or problems and/or (2) warning messages in the perltidy error file(s) relating to possible syntax errors in one or more of the source script(s) being tidied. When multiple files are being processed, an error detected in any single file will produce this type of exit condition.</p>
+
<h1 id="SEE-ALSO">SEE ALSO</h1>
<p>perlstyle(1), Perl::Tidy(3)</p>
+<h1 id="INSTALLATION">INSTALLATION</h1>
+
+<p>The perltidy binary uses the Perl::Tidy module and is installed when that module is installed. The module name is case-sensitive. For example, the basic command for installing with cpanm is 'cpanm Perl::Tidy'.</p>
+
<h1 id="VERSION">VERSION</h1>
-<p>This man page documents perltidy version 20190601</p>
+<p>This man page documents perltidy version 20200110</p>
<h1 id="BUG-REPORTS">BUG REPORTS</h1>
<h1 id="COPYRIGHT">COPYRIGHT</h1>
-<p>Copyright (c) 2000-2018 by Steve Hancock</p>
+<p>Copyright (c) 2000-2020 by Steve Hancock</p>
<h1 id="LICENSE">LICENSE</h1>
projects / perltidy.git / blobdiff