X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=docs%2Fperltidy.1;h=3244abd0aa9562a62c42c7cc3c4efccdfd4f214f;hb=4695b0259a32c6fc3c11de5662ed41cfa1d10dd9;hp=2a37636af7ce58d1a84904a9bf7a714ccc57ddaa;hpb=7272c75ca797879bc1a6bb26ad0f82b89255104a;p=perltidy.git diff --git a/docs/perltidy.1 b/docs/perltidy.1 index 2a37636..3244abd 100644 --- a/docs/perltidy.1 +++ b/docs/perltidy.1 @@ -129,7 +129,7 @@ .\" ======================================================================== .\" .IX Title "PERLTIDY 1" -.TH PERLTIDY 1 "2006-07-19" "perl v5.8.8" "User Contributed Perl Documentation" +.TH PERLTIDY 1 "2007-12-05" "perl v5.8.8" "User Contributed Perl Documentation" .SH "NAME" perltidy \- a perl script indenter and reformatter .SH "SYNOPSIS" @@ -529,8 +529,6 @@ where s=\f(CW\*(C`win\*(C'\fR, \f(CW\*(C`dos\*(C'\fR, \f(CW\*(C`unix\*(C'\fR, or to output line endings for a specific system. Normally, perltidy writes files with the line separator character of the host system. The \f(CW\*(C`win\*(C'\fR and \f(CW\*(C`dos\*(C'\fR flags have an identical result. -\&\fB\s-1NOTE\s0\fR: This only works under unix-like systems and is ignored under -other systems. .IP "\fB\-ple\fR, \fB\-\-preserve\-line\-endings\fR" 4 .IX Item "-ple, --preserve-line-endings" This flag tells perltidy to write its output files with the same line @@ -539,8 +537,6 @@ endings as the input file, if possible. It should work for input comes from a filename (rather than stdin, for example). If perltidy has trouble determining the input file line ending, it will revert to the default behavior of using the line ending of the host system. -\&\fB\s-1NOTE\s0\fR: This only works under unix-like systems and is ignored under -other systems. .Sh "Code Indentation Control" .IX Subsection "Code Indentation Control" .IP "\fB\-ci=n\fR, \fB\-\-continuation\-indentation=n\fR" 4 @@ -904,7 +900,7 @@ a space takes priority. .Sp It is necessary to have a list of all token types in order to create this type of input. Such a list can be obtained by the command -\&\fB\-\-dump\-token\-types\fR. Also try the \-D flag on a short snippet of code +\&\fB\-\-dump\-token\-types\fR. Also try the \fB\-D\fR flag on a short snippet of code and look at the .DEBUG file to see the tokenization. .Sp \&\fB\s-1WARNING\s0\fR Be sure to put these tokens in quotes to avoid having them @@ -1009,6 +1005,10 @@ removed. This is the default; use \fB\-nolc\fR to prevent outdenting. Side comments look best when lined up several spaces to the right of code. Perltidy will try to keep comments at least n spaces to the right. The default is n=4 spaces. +.IP "\fB\-fpsc=n\fR, \fB\-\-fixed\-position\-side\-comment=n\fR" 4 +.IX Item "-fpsc=n, --fixed-position-side-comment=n" +This parameter tells perltidy to line up side comments in column number \fBn\fR +whenever possible. The default, n=0, is not do do this. .IP "\fB\-hsc\fR, \fB\-\-hanging\-side\-comments\fR" 4 .IX Item "-hsc, --hanging-side-comments" By default, perltidy tries to identify and align \*(L"hanging side @@ -1254,6 +1254,19 @@ block comments; it will not be used unless the switch \fB\-sbc\fR is set. Also, please be aware that since this string is used in a perl regular expression which identifies these comments, it must enable a valid regular expression to be formed. +.Sp +A pattern which can be useful is: +.Sp +.Vb 1 +\& \-sbcp=^#{2,}[^\es#] +.Ve +.Sp +This pattern requires a static block comment to have at least one character +which is neither a # nor a space. It allows a line containing only '#' +characters to be rejected as a static block comment. Such lines are often used +at the start and end of header information in subroutines and should not be +separated from the intervening comments, which typically begin with just a +single '#'. .IP "\fB\-osbc\fR, \fB\-\-outdent\-static\-block\-comments\fR" 4 .IX Item "-osbc, --outdent-static-block-comments" The command \fB\-osbc\fR will will cause static block comments to be outdented by 2 @@ -1692,8 +1705,8 @@ For example, if we want to just apply this style to \f(CW\*(C`if\*(C'\fR, There is no vertical tightness control for closing block braces; with the exception of one-line blocks, they will normally remain on a separate line. -.IP "\fB\-sot\fR, \fB\-\-stack\-opening\-token\fR and related flags" 4 -.IX Item "-sot, --stack-opening-token and related flags" +.IP "\fB\-sot\fR, \fB\-\-stack\-opening\-tokens\fR and related flags" 4 +.IX Item "-sot, --stack-opening-tokens and related flags" The \fB\-sot\fR flag tells perltidy to \*(L"stack\*(R" opening tokens when possible to avoid lines with isolated opening tokens. .Sp @@ -1730,8 +1743,8 @@ controls can be used: .Ve .Sp The flag \fB\-sot\fR is a synonym for \fB\-sop \-sohb \-sosb\fR. -.IP "\fB\-sct\fR, \fB\-\-stack\-closing\-token\fR and related flags" 4 -.IX Item "-sct, --stack-closing-token and related flags" +.IP "\fB\-sct\fR, \fB\-\-stack\-closing\-tokens\fR and related flags" 4 +.IX Item "-sct, --stack-closing-tokens and related flags" The \fB\-sct\fR flag tells perltidy to \*(L"stack\*(R" closing tokens when possible to avoid lines with isolated closing tokens. .Sp @@ -1801,8 +1814,9 @@ breaks; see \fB\-\-freeze\-newlines\fR to completely prevent changes to line break points. .IP "Controlling whether perltidy breaks before or after operators" 4 .IX Item "Controlling whether perltidy breaks before or after operators" -Two command line parameters provide some control over whether +Four command line parameters provide some control over whether a line break should be before or after specific token types. +Two parameters give detailed control: .Sp \&\fB\-wba=s\fR or \fB\-\-want\-break\-after=s\fR, and .Sp @@ -1815,11 +1829,11 @@ command-line parameter always overwrites the previous one before perltidy ever sees it. .Sp By default, perltidy breaks \fBafter\fR these token types: - % + \- * / x != == >= <= =~ !~ < > | & >= < - = **= += *= &= <<= &&= \-= /= |= >>= ||= .= %= ^= x= + % + \- * / x != == >= <= =~ !~ < > | & + = **= += *= &= <<= &&= \-= /= |= >>= ||= //= .= %= ^= x= .Sp And perltidy breaks \fBbefore\fR these token types by default: - . << >> \-> && || + . << >> \-> && || // .Sp To illustrate, to cause a break after a concatenation operator, \f(CW'.'\fR, rather than before it, the command line would be @@ -1836,7 +1850,7 @@ math operators \f(CW'+'\fR, \f(CW'\-'\fR, \f(CW'/'\fR, and \f(CW'*'\fR: .Ve .Sp These commands should work well for most of the token types that perltidy uses -(use \fB\-\-dump\-token\-types\fR for a list). Also try the \-D flag on a short +(use \fB\-\-dump\-token\-types\fR for a list). Also try the \fB\-D\fR flag on a short snippet of code and look at the .DEBUG file to see the tokenization. However, for a few token types there may be conflicts with hardwired logic which cause unexpected results. One example is curly braces, which should be controlled @@ -1844,6 +1858,27 @@ with the parameter \fBbl\fR provided for that purpose. .Sp \&\fB\s-1WARNING\s0\fR Be sure to put these tokens in quotes to avoid having them misinterpreted by your command shell. +.Sp +Two additional parameters are available which, though they provide no further +capability, can simplify input are: +.Sp +\&\fB\-baao\fR or \fB\-\-break\-after\-all\-operators\fR, +.Sp +\&\fB\-bbao\fR or \fB\-\-break\-before\-all\-operators\fR. +.Sp +The \-baao sets the default to be to break after all of the following operators: +.Sp +.Vb 3 +\& % + \- * / x != == >= <= =~ !~ < > | & +\& = **= += *= &= <<= &&= \-= /= |= >>= ||= //= .= %= ^= x= +\& . : ? && || and or err xor +.Ve +.Sp +and the \fB\-bbao\fR flag sets the default to break before all of these operators. +These can be used to define an initial break preference which can be fine-tuned +with the \fB\-wba\fR and \fB\-wbb\fR flags. For example, to break before all operators +except an \fB=\fR one could use \-\-bbao \-wba='=' rather than listing every +single perl operator except \fB=\fR on a \-wbb flag. .Sh "Controlling List Formatting" .IX Subsection "Controlling List Formatting" Perltidy attempts to place comma-separated arrays of values in tables @@ -2000,6 +2035,39 @@ Use this flag to tell perltidy to ignore existing line breaks to the maximum extent possible. This will tend to produce the longest possible containers, regardless of type, which do not exceed the line length limit. +.IP "\fB\-kis\fR, \fB\-\-keep\-interior\-semicolons\fR" 4 +.IX Item "-kis, --keep-interior-semicolons" +Use the \fB\-kis\fR flag to prevent breaking at a semicolon if +there was no break there in the input file. Normally +perltidy places a newline after each semicolon which +terminates a statement unless several statements are +contained within a one-line brace block. To illustrate, +consider the following input lines: +.Sp +.Vb 2 +\& dbmclose(%verb_delim); undef %verb_delim; +\& dbmclose(%expanded); undef %expanded; +.Ve +.Sp +The default is to break after each statement, giving +.Sp +.Vb 4 +\& dbmclose(%verb_delim); +\& undef %verb_delim; +\& dbmclose(%expanded); +\& undef %expanded; +.Ve +.Sp +With \fBperltidy \-kis\fR the multiple statements are retained: +.Sp +.Vb 2 +\& dbmclose(%verb_delim); undef %verb_delim; +\& dbmclose(%expanded); undef %expanded; +.Ve +.Sp +The statements are still subject to the specified value +of \fBmaximum-line-length\fR and will be broken if this +maximum is exceeed. .Sh "Blank Line Control" .IX Subsection "Blank Line Control" Blank lines can improve the readability of a script if they are carefully @@ -2079,8 +2147,8 @@ by Damian Conway: .Sp .Vb 3 \& \-l=78 \-i=4 \-ci=4 \-st \-se \-vt=2 \-cti=0 \-pt=1 \-bt=1 \-sbt=1 \-bbt=1 \-nsfs \-nolq -\& \-wbb="% + \- * / x != == >= <= =~ !~ < > | & >= < = -\& **= += *= &= <<= &&= \-= /= |= >>= ||= .= %= ^= x=" +\& \-wbb="% + \- * / x != == >= <= =~ !~ < > | & = +\& **= += *= &= <<= &&= \-= /= |= >>= ||= //= .= %= ^= x=" .Ve .Sp Note that the \-st and \-se flags make perltidy act as a filter on one file only. @@ -2131,7 +2199,8 @@ named \fI.perltidyrc\fR. If it does not find one, it will continue looking for one in other standard locations. .Sp These other locations are system\-dependent, and may be displayed with -the command \f(CW\*(C`perltidy \-dpro\*(C'\fR. Under Unix systems, it will look for a +the command \f(CW\*(C`perltidy \-dpro\*(C'\fR. Under Unix systems, it will first look +for an environment variable \fB\s-1PERLTIDY\s0\fR. Then it will look for a \&\fI.perltidyrc\fR file in the home directory, and then for a system-wide file \fI/usr/local/etc/perltidyrc\fR, and then it will look for \&\fI/etc/perltidyrc\fR. Note that these last two system-wide files do not @@ -2649,7 +2718,7 @@ The following list shows all short parameter names which allow a prefix \& dwrs dws f fll frm fs hsc html ibc icb icp iob isbc lal log \& lp lsl ohbr okw ola oll opr opt osbr otr ple ple pod pvl q \& sbc sbl schb scp scsb sct se sfp sfs skp sob sohb sop sosb sot -\& ssc st sts syn t tac tbc toc tp tqw tsc w x +\& ssc st sts syn t tac tbc toc tp tqw tsc w x bar kis .Ve .PP Equivalently, the prefix 'no' or 'no\-' on the corresponding long names may be @@ -2708,7 +2777,7 @@ purpose of this rule is to prevent generating confusing filenames such as \&\fIperlstyle\fR\|(1), \fIPerl::Tidy\fR\|(3) .SH "VERSION" .IX Header "VERSION" -This man page documents perltidy version 20060719. +This man page documents perltidy version 20071205. .SH "CREDITS" .IX Header "CREDITS" Michael Cartmell supplied code for adaptation to \s-1VMS\s0 and helped with