-.\" Automatically generated by Pod::Man 2.1801 (Pod::Simple 3.05)
+.\" Automatically generated by Pod::Man 2.22 (Pod::Simple 3.07)
.\"
.\" Standard preamble:
.\" ========================================================================
.\" ========================================================================
.\"
.IX Title "PERLTIDY 1"
-.TH PERLTIDY 1 "2009-06-16" "perl v5.10.0" "User Contributed Perl Documentation"
+.TH PERLTIDY 1 "2012-06-29" "perl v5.10.1" "User Contributed Perl Documentation"
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.PP
This will produce a file \fIsomefile.pl.tdy\fR containing the script reformatted
using the default options, which approximate the style suggested in
-\&\fIperlstyle\fR\|(1). Perltidy never changes the input file.
+\&\fIperlstyle\fR\|(1). The source file \fIsomefile.pl\fR is unchanged.
.PP
.Vb 1
\& perltidy *.pl
.IP "\fB\-b\fR, \fB\-\-backup\-and\-modify\-in\-place\fR" 4
.IX Item "-b, --backup-and-modify-in-place"
Modify the input file or files in-place and save the original with the
-extension \fI.bak\fR. Any existing \fI.bak\fR file will be deleted. See next item
-for changing the default backup extension.
+extension \fI.bak\fR. Any existing \fI.bak\fR file will be deleted. See next
+item for changing the default backup extension, and for eliminating the
+backup file altogether.
.Sp
A \fB\-b\fR flag will be ignored if input is from standard input, or
if the \fB\-html\fR flag is set.
.IP "\fB\-bext\fR=ext, \fB\-\-backup\-file\-extension\fR=ext" 4
.IX Item "-bext=ext, --backup-file-extension=ext"
-Change the extension of the backup file to be something other than the
-default \fI.bak\fR. See \*(L"Specifying File Extensions\*(R".
+This parameter serves two purposes: (1) to change the extension of the backup
+file to be something other than the default \fI.bak\fR, and (2) to indicate
+that no backup file should be saved.
+.Sp
+To change the default extension to something other than \fI.bak\fR see
+\&\*(L"Specifying File Extensions\*(R".
+.Sp
+A backup file of the source is always written, but you can request that it
+be deleted at the end of processing if there were no errors. This is risky
+unless the source code is being maintained with a source code control
+system.
+.Sp
+To indicate that the backup should be deleted include one forward slash,
+\&\fB/\fR, in the extension. If any text remains after the slash is removed
+it will be used to define the backup file extension (which is always
+created and only deleted if there were no errors).
+.Sp
+Here are some examples:
+.Sp
+.Vb 5
+\& Parameter Extension Backup File Treatment
+\& <\-bext=bak> F<.bak> Keep (same as the default behavior)
+\& <\-bext=\*(Aq/\*(Aq> F<.bak> Delete if no errors
+\& <\-bext=\*(Aq/backup\*(Aq> F<.backup> Delete if no errors
+\& <\-bext=\*(Aqoriginal/\*(Aq> F<.original> Delete if no errors
+.Ve
.IP "\fB\-w\fR, \fB\-\-warning\-output\fR" 4
.IX Item "-w, --warning-output"
Setting \fB\-w\fR causes any non-critical warning
.Sp
would cause file \fItestcfg\fR to be used instead of the
default \fI.perltidyrc\fR.
+.Sp
+A pathname begins with three dots, e.g. \*(L".../.perltidyrc\*(R", indicates that
+the file should be searched for starting in the current directory and
+working upwards. This makes it easier to have multiple projects each with
+their own .perltidyrc in their root directories.
.IP "\fB\-opt\fR, \fB\-\-show\-options\fR" 4
.IX Item "-opt, --show-options"
Write a list of all options used to the \fI.LOG\fR file.
.IX Header "FORMATTING OPTIONS"
.SS "Basic Options"
.IX Subsection "Basic Options"
+.IP "\fB\-\-notidy\fR" 4
+.IX Item "--notidy"
+This flag disables all formatting and causes the input to be copied unchanged
+to the output except for possible changes in line ending characters and any
+pre\- and post-filters. This can be useful in conjunction with a hierarchical
+set of \fI.perltidyrc\fR files to avoid unwanted code tidying. See also
+\&\*(L"Skipping Selected Sections of Code\*(R" for a way to avoid tidying specific
+sections of code.
.IP "\fB\-l=n\fR, \fB\-\-maximum\-line\-length=n\fR" 4
.IX Item "-l=n, --maximum-line-length=n"
The default maximum line length is n=80 characters. Perltidy will try
If perl reports errors in the input file, they will not be reported in
the error output unless the \fB\-\-warning\-output\fR flag is given.
.Sp
-The default is \fBnot\fR to do this type of syntax checking (although
+The default is \fB\s-1NOT\s0\fR to do this type of syntax checking (although
perltidy will still do as much self-checking as possible). The reason
is that it causes all code in \s-1BEGIN\s0 blocks to be executed, for all
modules being used, and this opens the door to security issues and
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.
+.IP "\fB\-it=n\fR, \fB\-\-iterations=n\fR" 4
+.IX Item "-it=n, --iterations=n"
+This flag causes perltidy to do \fBn\fR complete iterations. The reason for this
+flag is that code beautification is an iterative process and in some
+cases the output from perltidy can be different if it is applied a second time.
+For most purposes the default of \fBn=1\fR should be satisfactory. However \fBn=2\fR
+can be useful when a major style change is being made, or when code is being
+beautified on check-in to a source code control system. It has been found to
+be extremely rare for the output to change after 2 iterations. If a value
+\&\fBn\fR is greater than 2 is input then a convergence test will be used to stop
+the iterations as soon as possible, almost always after 2 iterations.
+.Sp
+This flag has no effect when perltidy is used to generate html.
.SS "Code Indentation Control"
.IX Subsection "Code Indentation Control"
.IP "\fB\-ci=n\fR, \fB\-\-continuation\-indentation=n\fR" 4
.IX Item "-sil=n --starting-indentation-level=n"
By default, perltidy examines the input file and tries to determine the
starting indentation level. While it is often zero, it may not be
-zero for a code snippet being sent from an editing session. If the
-default method does not work correctly, or you want to change the
+zero for a code snippet being sent from an editing session.
+.Sp
+To guess the starting indentation level perltidy simply assumes that
+indentation scheme used to create the code snippet is the same as is being used
+for the current perltidy process. This is the only sensible guess that can be
+made. It should be correct if this is true, but otherwise it probably won't.
+For example, if the input script was written with \-i=2 and the current peltidy
+flags have \-i=4, the wrong initial indentation will be guessed for a code
+snippet which has non-zero initial indentation. Likewise, if an entabbing
+scheme is used in the input script and not in the current process then the
+guessed indentation will be wrong.
+.Sp
+If the default method does not work correctly, or you want to change the
starting level, use \fB\-sil=n\fR, to force the starting level to be n.
.IP "List indentation using \fB\-lp\fR, \fB\-\-line\-up\-parentheses\fR" 4
.IX Item "List indentation using -lp, --line-up-parentheses"
.IX Item "-icp, --indent-closing-paren"
The \fB\-icp\fR flag is equivalent to
\&\fB\-cti=2\fR, described in the previous section. The \fB\-nicp\fR flag is
-equivalent \fB\-cti=0\fR. They are included for backwards compatability.
+equivalent \fB\-cti=0\fR. They are included for backwards compatibility.
.IP "\fB\-icb\fR, \fB\-\-indent\-closing\-brace\fR" 4
.IX Item "-icb, --indent-closing-brace"
The \fB\-icb\fR option gives one extra level of indentation to a brace which
\& my( $a, $b, $c ) = @_; # \-nsak="my local our"
.Ve
.Sp
+The abbreviation \fB\-nsak='*'\fR is equivalent to including all of the
+keywords in the above list.
+.Sp
+When both \fB\-nsak=s\fR and \fB\-sak=s\fR commands are included, the \fB\-nsak=s\fR
+command is executed first. For example, to have space after only the
+keywords (my, local, our) you could use \fB\-nsak=\*(L"*\*(R" \-sak=\*(L"my local our\*(R"\fR.
+.Sp
To put a space after all keywords, see the next item.
.IP "Space between all keywords and opening parens" 4
.IX Item "Space between all keywords and opening parens"
By default, if a conditional (ternary) operator is broken at a \f(CW\*(C`:\*(C'\fR,
then it will remain broken. To prevent this, and thereby
form longer lines, use \fB\-nbot\fR.
+.IP "\fB\-boa\fR, \fB\-\-break\-at\-old\-attribute\-breakpoints\fR" 4
+.IX Item "-boa, --break-at-old-attribute-breakpoints"
+By default, if an attribute list is broken at a \f(CW\*(C`:\*(C'\fR in the source file, then
+it will remain broken. For example, given the following code, the line breaks
+at the ':'s will be retained:
+.Sp
+.Vb 4
+\& my @field
+\& : field
+\& : Default(1)
+\& : Get(\*(AqName\*(Aq => \*(Aqfoo\*(Aq) : Set(\*(AqName\*(Aq);
+.Ve
+.Sp
+If the attributes are on a single line in the source code then they will remain
+on a single line if possible.
+.Sp
+To prevent this, and thereby always form longer lines, use \fB\-nboa\fR.
.IP "\fB\-iob\fR, \fB\-\-ignore\-old\-breakpoints\fR" 4
.IX Item "-iob, --ignore-old-breakpoints"
Use this flag to tell perltidy to ignore existing line breaks to the
A blank line will be introduced before a full-line comment. This is the
default. Use \fB\-nbbc\fR or \fB\-\-noblanks\-before\-comments\fR to prevent
such blank lines from being introduced.
+.IP "\fB\-blbs=n\fR, \fB\-\-blank\-lines\-before\-subs=n\fR" 4
+.IX Item "-blbs=n, --blank-lines-before-subs=n"
+The parameter \fB\-blbs=n\fR requests that least \fBn\fR blank lines precede a sub
+definition which does not follow a comment and which is more than one-line
+long. The default is <\-blbs=1>. \fB\s-1BEGIN\s0\fR and \fB\s-1END\s0\fR blocks are included.
+.Sp
+The requested number of blanks statement will be inserted regardless of of the
+value of \fB\-\-maximum\-consecutive\-blank\-lines=n\fR (\fB\-mbl=n\fR) with the exception
+that if \fB\-mbl=0\fR then no blanks will be output.
+.Sp
+This parameter interacts with the value \fBk\fR of the parameter \fB\-\-maximum\-consecutive\-blank\-lines=k\fR (\fB\-mbl=k\fR) as follows:
+.Sp
+1. If \fB\-mbl=0\fR then no blanks will be output. This allows all blanks to be suppressed with a single parameter. Otherwise,
+.Sp
+2. If the number of old blank lines in the script is less than \fBn\fR then
+additional blanks will be inserted to make the total \fBn\fR regardless of the
+value of \fB\-mbl=k\fR.
+.Sp
+3. If the number of old blank lines in the script equals or exceeds \fBn\fR then
+this parameter has no effect, however the total will not exceed
+value specified on the \fB\-mbl=k\fR flag.
+.IP "\fB\-blbp=n\fR, \fB\-\-blank\-lines\-before\-packages=n\fR" 4
+.IX Item "-blbp=n, --blank-lines-before-packages=n"
+The parameter \fB\-blbp=n\fR requests that least \fBn\fR blank lines precede a package
+which does not follow a comment. The default is <\-blbp=1>.
+.Sp
+This parameter interacts with the value \fBk\fR of the parameter
+\&\fB\-\-maximum\-consecutive\-blank\-lines=k\fR (\fB\-mbl=k\fR) in the same way as described
+for the previous item \fB\-blbs=n\fR.
.IP "\fB\-bbs\fR, \fB\-\-blanks\-before\-subs\fR" 4
.IX Item "-bbs, --blanks-before-subs"
-A blank line will be introduced before a \fBsub\fR definition, unless it is a
-one-liner or preceded by a comment. A blank line will also be introduced
-before a \fBpackage\fR statement and a \fB\s-1BEGIN\s0\fR and \fB\s-1END\s0\fR block. This is the
-default. The intention is to help display the structure of a program by
-setting off certain key sections of code. This is negated with \fB\-nbbs\fR or
-\&\fB\-\-noblanks\-before\-subs\fR.
+For compatability with previous versions, \fB\-bbs\fR or \fB\-\-blanks\-before\-subs\fR
+is equivalent to \fI\-blbp=1\fR and \fI\-blbs=1\fR.
+.Sp
+Likewise, \fB\-nbbs\fR or \fB\-\-noblanks\-before\-subs\fR
+is equivalent to \fI\-blbp=0\fR and \fI\-blbs=0\fR.
.IP "\fB\-bbb\fR, \fB\-\-blanks\-before\-blocks\fR" 4
.IX Item "-bbb, --blanks-before-blocks"
A blank line will be introduced before blocks of coding delimited by
a value of \fB0\fR is equivalent to entering a very large number.
.IP "\fB\-mbl=n\fR \fB\-\-maximum\-consecutive\-blank\-lines=n\fR" 4
.IX Item "-mbl=n --maximum-consecutive-blank-lines=n"
-This parameter specifies the maximum number of consecutive
-blank lines which will be output within code sections of a
-script. The default is n=1. If the input file has more
-than n consecutive blank lines, the number will be reduced
-to n. If \fBn=0\fR then no blank lines will be output (unless
-all old blank lines are retained with the \fB\-kbl=2\fR flag of
-the next section).
+This parameter specifies the maximum number of consecutive blank lines which
+will be output within code sections of a script. The default is n=1. If the
+input file has more than n consecutive blank lines, the number will be reduced
+to n except as noted above for the \fB\-blbp\fR and \fB\-blbs\fR parameters. If \fBn=0\fR
+then no blank lines will be output (unless all old blank lines are retained
+with the \fB\-kbl=2\fR flag of the next section).
.Sp
This flag obviously does not apply to pod sections,
here-documents, and quotes.
The default is \fBn=1\fR.
.IP "\fB\-sob\fR, \fB\-\-swallow\-optional\-blank\-lines\fR" 4
.IX Item "-sob, --swallow-optional-blank-lines"
-This is equivalent to \fBkbl=0\fR and is included for compatability with
+This is equivalent to \fBkbl=0\fR and is included for compatibility with
previous versions.
.IP "\fB\-nsob\fR, \fB\-\-noswallow\-optional\-blank\-lines\fR" 4
.IX Item "-nsob, --noswallow-optional-blank-lines"
-This is equivalent to \fBkbl=1\fR and is included for compatability with
+This is equivalent to \fBkbl=1\fR and is included for compatibility with
previous versions.
.SS "Styles"
.IX Subsection "Styles"
The configuation file is free format, and simply a list of parameters, just as
they would be entered on a command line. Any number of lines may be used, with
any number of parameters per line, although it may be easiest to read with one
-parameter per line. Blank lines are ignored, and text after a '#' is ignored
-to the end of a line.
+parameter per line. Comment text begins with a #, and there must
+also be a space before the # for side comments. It is a good idea to
+put complex parameters in either single or double quotes.
.Sp
Here is an example of a \fI.perltidyrc\fR file:
.Sp
\&\fIperlstyle\fR\|(1), \fIPerl::Tidy\fR\|(3)
.SH "VERSION"
.IX Header "VERSION"
-This man page documents perltidy version 20090616.
+This man page documents perltidy version 20120701.
.SH "CREDITS"
.IX Header "CREDITS"
Michael Cartmell supplied code for adaptation to \s-1VMS\s0 and helped with
.Ve
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
-Copyright (c) 2000\-2008 by Steve Hancock
+Copyright (c) 2000\-2010 by Steve Hancock
.SH "LICENSE"
.IX Header "LICENSE"
This package is free software; you can redistribute it and/or modify it
projects / perltidy.git / blobdiff