.\" ========================================================================
.\"
.IX Title "PERLTIDY 1"
-.TH PERLTIDY 1 "2007-04-24" "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"
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
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
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
.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
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
.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
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
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
\& 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 bar
+\& 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
\&\fIperlstyle\fR\|(1), \fIPerl::Tidy\fR\|(3)
.SH "VERSION"
.IX Header "VERSION"
-This man page documents perltidy version 20070424.
+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
projects / perltidy.git / blobdiff