-.\" Automatically generated by Pod::Man 2.25 (Pod::Simple 3.16)
+.\" Automatically generated by Pod::Man 2.28 (Pod::Simple 3.29)
.\"
.\" Standard preamble:
.\" ========================================================================
. ds PI \(*p
. ds L" ``
. ds R" ''
+. ds C`
+. ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD. Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
-.ie \nF \{\
-. de IX
-. tm Index:\\$1\t\\n%\t"\\$2"
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
..
-. nr % 0
-. rr F
-.\}
-.el \{\
-. de IX
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{
+. if \nF \{
+. de IX
+. tm Index:\\$1\t\\n%\t"\\$2"
..
+. if !\nF==2 \{
+. nr % 0
+. nr F 2
+. \}
+. \}
.\}
+.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear. Run. Save yourself. No user-serviceable parts.
.\" ========================================================================
.\"
.IX Title "PERLTIDY 1"
-.TH PERLTIDY 1 "2017-05-21" "perl v5.14.2" "User Contributed Perl Documentation"
+.TH PERLTIDY 1 "2018-02-20" "perl v5.22.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
.IX Header "DESCRIPTION"
Perltidy reads a perl script and writes an indented, reformatted script.
.PP
-Many users will find enough information in \*(L"\s-1EXAMPLES\s0\*(R" to get
+Many users will find enough information in \*(L"\s-1EXAMPLES\*(R"\s0 to get
started. New users may benefit from the short tutorial
which can be found at
http://perltidy.sourceforge.net/tutorial.html
existence of an \fB\-html\fR flag. Without this flag, the output is passed
through a formatter. The default formatting tries to follow the
recommendations in \fIperlstyle\fR\|(1), but it can be controlled in detail with
-numerous input parameters, which are described in \*(L"\s-1FORMATTING\s0
-\&\s-1OPTIONS\s0\*(R".
+numerous input parameters, which are described in \*(L"\s-1FORMATTING
+OPTIONS\*(R"\s0.
.PP
When the \fB\-html\fR flag is given, the output is passed through an \s-1HTML\s0
-formatter which is described in \*(L"\s-1HTML\s0 \s-1OPTIONS\s0\*(R".
+formatter which is described in \*(L"\s-1HTML OPTIONS\*(R"\s0.
.SH "EXAMPLES"
.IX Header "EXAMPLES"
.Vb 1
.IX Subsection "I/O control"
The following parameters concern the files which are read and written.
.IP "\fB\-h\fR, \fB\-\-help\fR" 4
-.IX Item "-h, --help"
+.IX Item "-h, --help"
Show summary of usage and exit.
.IP "\fB\-o\fR=filename, \fB\-\-outfile\fR=filename" 4
-.IX Item "-o=filename, --outfile=filename"
+.IX Item "-o=filename, --outfile=filename"
Name of the output file (only if a single input file is being
processed). If no output file is specified, and output is not
redirected to the standard output, the output will go to \fIfilename.tdy\fR.
.IP "\fB\-st\fR, \fB\-\-standard\-output\fR" 4
-.IX Item "-st, --standard-output"
+.IX Item "-st, --standard-output"
Perltidy must be able to operate on an arbitrarily large number of files
in a single run, with each output being directed to a different output
file. Obviously this would conflict with outputting to the single
This option may only be used if there is just a single input file.
The default is \fB\-nst\fR or \fB\-\-nostandard\-output\fR.
.IP "\fB\-se\fR, \fB\-\-standard\-error\-output\fR" 4
-.IX Item "-se, --standard-error-output"
+.IX Item "-se, --standard-error-output"
If perltidy detects an error when processing file \fIsomefile.pl\fR, its
default behavior is to write error messages to file \fIsomefile.pl.ERR\fR.
Use \fB\-se\fR to cause all error messages to be sent to the standard error
Thus, you may place \fB\-se\fR in a \fI.perltidyrc\fR and override it when
desired with \fB\-nse\fR on the command line.
.IP "\fB\-oext\fR=ext, \fB\-\-output\-file\-extension\fR=ext" 4
-.IX Item "-oext=ext, --output-file-extension=ext"
+.IX Item "-oext=ext, --output-file-extension=ext"
Change the extension of the output file to be \fIext\fR instead of the
default \fItdy\fR (or \fIhtml\fR in case the \-\fB\-html\fR option is used).
See \*(L"Specifying File Extensions\*(R".
.IP "\fB\-opath\fR=path, \fB\-\-output\-path\fR=path" 4
-.IX Item "-opath=path, --output-path=path"
+.IX Item "-opath=path, --output-path=path"
When perltidy creates a filename for an output file, by default it merely
appends an extension to the path and basename of the input file. This
parameter causes the path to be changed to \fIpath\fR instead.
This parameter will be ignored if output is being directed to standard output,
or if it is being specified explicitly with the \fB\-o=s\fR parameter.
.IP "\fB\-b\fR, \fB\-\-backup\-and\-modify\-in\-place\fR" 4
-.IX Item "-b, --backup-and-modify-in-place"
+.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, and for eliminating the
\&\fB\-pbp\fR flag because it contains a \fB\-st\fR flag as one of its components,
which means that output will go to the standard output stream.
.IP "\fB\-bext\fR=ext, \fB\-\-backup\-file\-extension\fR=ext" 4
-.IX Item "-bext=ext, --backup-file-extension=ext"
+.IX Item "-bext=ext, --backup-file-extension=ext"
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.
\& <\-bext=\*(Aqoriginal/\*(Aq> F<.original> Delete if no errors
.Ve
.IP "\fB\-w\fR, \fB\-\-warning\-output\fR" 4
-.IX Item "-w, --warning-output"
+.IX Item "-w, --warning-output"
Setting \fB\-w\fR causes any non-critical warning
messages to be reported as errors. These include messages
about possible pod problems, possibly bad starting indentation level,
and cautions about indirect object usage. The default, \fB\-nw\fR or
\&\fB\-\-nowarning\-output\fR, is not to include these warnings.
.IP "\fB\-q\fR, \fB\-\-quiet\fR" 4
-.IX Item "-q, --quiet"
+.IX Item "-q, --quiet"
Deactivate error messages and syntax checking (for running under
an editor).
.Sp
any error message may mess up your screen, so be prepared to use your
\&\*(L"undo\*(R" key.
.IP "\fB\-log\fR, \fB\-\-logfile\fR" 4
-.IX Item "-log, --logfile"
+.IX Item "-log, --logfile"
Save the \fI.LOG\fR file, which has many useful diagnostics. Perltidy always
creates a \fI.LOG\fR file, but by default it is deleted unless a program bug is
suspected. Setting the \fB\-log\fR flag forces the log file to be saved.
.Sp
Setting a negative value of \f(CW\*(C`n\*(C'\fR is the same as not setting \fB\-g\fR at all.
.IP "\fB\-npro\fR \fB\-\-noprofile\fR" 4
-.IX Item "-npro --noprofile"
+.IX Item "-npro --noprofile"
Ignore any \fI.perltidyrc\fR command file. Normally, perltidy looks first in
your current directory for a \fI.perltidyrc\fR file of parameters. (The format
is described below). If it finds one, it applies those options to the
.Sp
If you set the \fB\-npro\fR flag, perltidy will not look for this file.
.IP "\fB\-pro=filename\fR or \fB\-\-profile=filename\fR" 4
-.IX Item "-pro=filename or --profile=filename"
+.IX Item "-pro=filename or --profile=filename"
To simplify testing and switching .perltidyrc files, this command may be
used to specify a configuration file which will override the default
name of .perltidyrc. There must not be a space on either side of the
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"
+.IX Item "-opt, --show-options"
Write a list of all options used to the \fI.LOG\fR file.
Please see \fB\-\-dump\-options\fR for a simpler way to do this.
.IP "\fB\-f\fR, \fB\-\-force\-read\-binary\fR" 4
-.IX Item "-f, --force-read-binary"
+.IX Item "-f, --force-read-binary"
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
\&\*(L"Skipping Selected Sections of Code\*(R" for a way to avoid tidying specific
sections of code.
.IP "\fB\-i=n\fR, \fB\-\-indent\-columns=n\fR" 4
-.IX Item "-i=n, --indent-columns=n"
+.IX Item "-i=n, --indent-columns=n"
Use n columns per indentation level (default n=4).
.IP "\fB\-l=n\fR, \fB\-\-maximum\-line\-length=n\fR" 4
.IX Item "-l=n, --maximum-line-length=n"
here-documents, they will remain.
.RS 4
.IP "\fB\-et=n\fR, \fB\-\-entab\-leading\-whitespace\fR" 4
-.IX Item "-et=n, --entab-leading-whitespace"
+.IX Item "-et=n, --entab-leading-whitespace"
This flag causes each \fBn\fR initial space characters to be replaced by
one tab character. Note that the integer \fBn\fR is completely independent
of the integer specified for indentation parameter, \fB\-i=n\fR.
.IP "\fB\-t\fR, \fB\-\-tabs\fR" 4
-.IX Item "-t, --tabs"
+.IX Item "-t, --tabs"
This flag causes one leading tab character to be inserted for each level
of indentation. Certain other features are incompatible with this
option, and if these options are also given, then a warning message will
be issued and this flag will be unset. One example is the \fB\-lp\fR
option.
.IP "\fB\-dt=n\fR, \fB\-\-default\-tabsize=n\fR" 4
-.IX Item "-dt=n, --default-tabsize=n"
+.IX Item "-dt=n, --default-tabsize=n"
If the first line of code passed to perltidy contains leading tabs but no
tab scheme is specified for the output stream then perltidy must guess how many
spaces correspond to each leading tab. This number of spaces \fBn\fR
.RS 4
.RE
.IP "\fB\-syn\fR, \fB\-\-check\-syntax\fR" 4
-.IX Item "-syn, --check-syntax"
+.IX Item "-syn, --check-syntax"
+This flag is now ignored for safety, but the following documentation
+has been retained for reference.
+.Sp
This flag causes perltidy to run \f(CW\*(C`perl \-c \-T\*(C'\fR to check syntax of input
and output. (To change the flags passed to perl, see the next
item, \fB\-pscf\fR). The results are written to the \fI.LOG\fR file, which
add a \fB\-c\fR and \fB\-x\fR if appropriate. The \fI.LOG\fR file will show
exactly what flags were passed to perl.
.IP "\fB\-xs\fR, \fB\-\-extended\-syntax\fR" 4
-.IX Item "-xs, --extended-syntax"
+.IX Item "-xs, --extended-syntax"
A problem with formatting Perl code is that some modules can introduce new
syntax. This flag allows perltidy to handle certain common extensions
to the standard syntax without complaint.
Probably the only reason to deactivate this flag is to generate more diagnostic
messages when debugging a script.
.IP "\fB\-io\fR, \fB\-\-indent\-only\fR" 4
-.IX Item "-io, --indent-only"
+.IX Item "-io, --indent-only"
This flag is used to deactivate all whitespace and line break changes
within non-blank lines of code.
When it is in effect, the only change to the script will be
closing side comments. You may still delete all side comments however when
this flag is in effect.
.IP "\fB\-enc=s\fR, \fB\-\-character\-encoding=s\fR" 4
-.IX Item "-enc=s, --character-encoding=s"
+.IX Item "-enc=s, --character-encoding=s"
where \fBs\fR=\fBnone\fR or \fButf8\fR. This flag tells perltidy the character encoding
of both the input and output character streams. The value \fButf8\fR causes the
-stream to be read and written as \s-1UTF\-8\s0. The value \fBnone\fR causes the stream to
+stream to be read and written as \s-1UTF\-8. \s0 The value \fBnone\fR causes the stream to
be processed without special encoding assumptions. At present there is no
automatic detection of character encoding (even if there is a \f(CW\*(Aquse utf8\*(Aq\fR
-statement in your code) so this flag must be set for streams encoded in \s-1UTF\-8\s0.
+statement in your code) so this flag must be set for streams encoded in \s-1UTF\-8.\s0
Incorrectly setting this parameter can cause data corruption, so please
carefully check the output.
.Sp
\& perltidy \-utf8 file.pl
.Ve
.IP "\fB\-ole=s\fR, \fB\-\-output\-line\-ending=s\fR" 4
-.IX Item "-ole=s, --output-line-ending=s"
+.IX Item "-ole=s, --output-line-ending=s"
where s=\f(CW\*(C`win\*(C'\fR, \f(CW\*(C`dos\*(C'\fR, \f(CW\*(C`unix\*(C'\fR, or \f(CW\*(C`mac\*(C'\fR. This flag tells perltidy
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.
.IP "\fB\-ple\fR, \fB\-\-preserve\-line\-endings\fR" 4
-.IX Item "-ple, --preserve-line-endings"
+.IX Item "-ple, --preserve-line-endings"
This flag tells perltidy to write its output files with the same line
endings as the input file, if possible. It should work for
\&\fBdos\fR, \fBunix\fR, and \fBmac\fR line endings. It will only work if perltidy
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"
+.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.
.Sp
This flag has no effect when perltidy is used to generate html.
.IP "\fB\-conv\fR, \fB\-\-converge\fR" 4
-.IX Item "-conv, --converge"
+.IX Item "-conv, --converge"
This flag is equivalent to \fB\-it=4\fR and is included to simplify iteration
control. For all practical purposes one either does or does not want to be
sure that the output is converged, and there is no penalty to using a large
space, perltidy will use less. For alternate placement of the
closing paren, see the next section.
.Sp
-This option has no effect on code \s-1BLOCKS\s0, such as if/then/else blocks,
+This option has no effect on code \s-1BLOCKS,\s0 such as if/then/else blocks,
which always use whatever is specified with \fB\-i=n\fR. Also, the
existence of line breaks and/or block comments between the opening and
closing parens may cause perltidy to temporarily revert to its default
versions of perltidy. The negation of this also works, \fB\-noll\fR or
\&\fB\-\-nooutdent\-long\-lines\fR, and is equivalent to setting \fB\-nolq\fR and \fB\-nolc\fR.
.IP "Outdenting Labels: \fB\-ola\fR, \fB\-\-outdent\-labels\fR" 4
-.IX Item "Outdenting Labels: -ola, --outdent-labels"
+.IX Item "Outdenting Labels: -ola, --outdent-labels"
This command will cause labels to be outdented by 2 spaces (or whatever \fB\-ci\fR
has been set to), if possible. This is the default. For example:
.Sp
.RS 4
.PD 0
.IP "\fB\-okw\fR, \fB\-\-outdent\-keywords\fR" 4
-.IX Item "-okw, --outdent-keywords"
+.IX Item "-okw, --outdent-keywords"
.PD
The command \fB\-okw\fR will cause certain leading control keywords to
be outdented by 2 spaces (or whatever \fB\-ci\fR has been set to), if
.Sp
The default is not to do this.
.IP "Specifying Outdented Keywords: \fB\-okwl=string\fR, \fB\-\-outdent\-keyword\-list=string\fR" 4
-.IX Item "Specifying Outdented Keywords: -okwl=string, --outdent-keyword-list=string"
+.IX Item "Specifying Outdented Keywords: -okwl=string, --outdent-keyword-list=string"
This command can be used to change the keywords which are outdented with
the \fB\-okw\fR command. The parameter \fBstring\fR is a required list of perl
keywords, which should be placed in quotes if there are more than one.
Whitespace refers to the blank space between variables, operators,
and other code tokens.
.IP "\fB\-fws\fR, \fB\-\-freeze\-whitespace\fR" 4
-.IX Item "-fws, --freeze-whitespace"
+.IX Item "-fws, --freeze-whitespace"
This flag causes your original whitespace to remain unchanged, and
causes the rest of the whitespace commands in this section, the
Code Indentation section, and
value <n>, the parameter <\-act=n> or \fB\-\-all\-containers\-tightness=n\fR is an
abbreviation for the combination <\-pt=n \-sbt=n \-bt=n \-bbt=n>.
.IP "\fB\-tso\fR, \fB\-\-tight\-secret\-operators\fR" 4
-.IX Item "-tso, --tight-secret-operators"
+.IX Item "-tso, --tight-secret-operators"
The flag \fB\-tso\fR causes certain perl token sequences (secret operators)
which might be considered to be a single operator to be formatted \*(L"tightly\*(R"
(without spaces). The operators currently modified by this flag are:
would be formatted without a space: \fB0+\fR when the \fB\-tso\fR flag is set. This
flag is off by default.
.IP "\fB\-sts\fR, \fB\-\-space\-terminal\-semicolon\fR" 4
-.IX Item "-sts, --space-terminal-semicolon"
+.IX Item "-sts, --space-terminal-semicolon"
Some programmers prefer a space before all terminal semicolons. The
default is for no such space, and is indicated with \fB\-nsts\fR or
\&\fB\-\-nospace\-terminal\-semicolon\fR.
\& $i = 1; # \-nsts (default)
.Ve
.IP "\fB\-sfs\fR, \fB\-\-space\-for\-semicolon\fR" 4
-.IX Item "-sfs, --space-for-semicolon"
+.IX Item "-sfs, --space-for-semicolon"
Semicolons within \fBfor\fR loops may sometimes be hard to see,
particularly when commas are also present. This option places spaces on
both sides of these special semicolons, and is the default. Use
\& for ( @a = @$ap, $u = shift @a; @a; $u = $v ) { # \-nsfs
.Ve
.IP "\fB\-asc\fR, \fB\-\-add\-semicolons\fR" 4
-.IX Item "-asc, --add-semicolons"
+.IX Item "-asc, --add-semicolons"
Setting \fB\-asc\fR allows perltidy to add any missing optional semicolon at the end
of a line which is followed by a closing curly brace on the next line. This
is the default, and may be deactivated with \fB\-nasc\fR or \fB\-\-noadd\-semicolons\fR.
.IP "\fB\-dsm\fR, \fB\-\-delete\-semicolons\fR" 4
-.IX Item "-dsm, --delete-semicolons"
+.IX Item "-dsm, --delete-semicolons"
Setting \fB\-dsm\fR allows perltidy to delete extra semicolons which are
simply empty statements. This is the default, and may be deactivated
with \fB\-ndsm\fR or \fB\-\-nodelete\-semicolons\fR. (Such semicolons are not
deleted, however, if they would promote a side comment to a block
comment).
.IP "\fB\-aws\fR, \fB\-\-add\-whitespace\fR" 4
-.IX Item "-aws, --add-whitespace"
+.IX Item "-aws, --add-whitespace"
Setting this option allows perltidy to add certain whitespace improve
code readability. This is the default. If you do not want any
whitespace added, but are willing to have some whitespace deleted, use
\&\fB\-naws\fR. (Use \fB\-fws\fR to leave whitespace completely unchanged).
.IP "\fB\-dws\fR, \fB\-\-delete\-old\-whitespace\fR" 4
-.IX Item "-dws, --delete-old-whitespace"
+.IX Item "-dws, --delete-old-whitespace"
Setting this option allows perltidy to remove some old whitespace
between characters, if necessary. This is the default. If you
do not want any old whitespace removed, use \fB\-ndws\fR or
multi-line \f(CW\*(C`qw\*(C'\fR quotes to be left unchanged. This option will not
normally be necessary, but was added for testing purposes, because in
some versions of perl, trimming \f(CW\*(C`qw\*(C'\fR quotes changes the syntax tree.
+.IP "\fB\-sbq=n\fR or \fB\-\-space\-backslash\-quote=n\fR" 4
+.IX Item "-sbq=n or --space-backslash-quote=n"
+Lines like
+.Sp
+.Vb 2
+\& $str1=\e"string1";
+\& $str2=\e\*(Aqstring2\*(Aq;
+.Ve
+.Sp
+can confuse syntax highlighters unless a space is included between the backslash and the single or double quotation mark.
+.Sp
+This can be controlled with the value of \fBn\fR as follows:
+.Sp
+.Vb 3
+\& \-sbq=0 means no space between the backslash and quote
+\& \-sbq=1 means follow the example of the source code
+\& \-sbq=2 means always put a space between the backslash and quote
+.Ve
+.Sp
+The default is \fB\-sbq=1\fR, meaning that a space will be used 0if there is one in the source code.
.IP "Trimming trailing whitespace from lines of \s-1POD\s0" 4
.IX Item "Trimming trailing whitespace from lines of POD"
-\&\fB\-trp\fR or \fB\-\-trim\-pod\fR will remove trailing whitespace from lines of \s-1POD\s0.
+\&\fB\-trp\fR or \fB\-\-trim\-pod\fR will remove trailing whitespace from lines of \s-1POD.\s0
The default is not to do this.
.SS "Comment Controls"
.IX Subsection "Comment Controls"
comment, whereas \fBside comment\fR will refer to a comment which appears on a
line to the right of some code.
.IP "\fB\-ibc\fR, \fB\-\-indent\-block\-comments\fR" 4
-.IX Item "-ibc, --indent-block-comments"
+.IX Item "-ibc, --indent-block-comments"
Block comments normally look best when they are indented to the same
level as the code which follows them. This is the default behavior, but
you may use \fB\-nibc\fR to keep block comments left-justified. Here is an
See also the next item, \fB\-isbc\fR, as well as \fB\-sbc\fR, for other ways to
have some indented and some outdented block comments.
.IP "\fB\-isbc\fR, \fB\-\-indent\-spaced\-block\-comments\fR" 4
-.IX Item "-isbc, --indent-spaced-block-comments"
+.IX Item "-isbc, --indent-spaced-block-comments"
If there is no leading space on the line, then the comment will not be
indented, and otherwise it may be.
.Sp
than the value \fBmaximum-line-length\fR will have their indentation
removed. This is the default; use \fB\-nolc\fR to prevent outdenting.
.IP "\fB\-msc=n\fR, \fB\-\-minimum\-space\-to\-comment=n\fR" 4
-.IX Item "-msc=n, --minimum-space-to-comment=n"
+.IX Item "-msc=n, --minimum-space-to-comment=n"
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"
+.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, will not do this.
.IP "\fB\-iscl\fR, \fB\-\-ignore\-side\-comment\-lengths\fR" 4
-.IX Item "-iscl, --ignore-side-comment-lengths"
+.IX Item "-iscl, --ignore-side-comment-lengths"
This parameter causes perltidy to ignore the length of side comments when
setting line breaks. The default, \fB\-niscl\fR, is to include the length of
side comments when breaking lines to stay within the length prescribed
order to update, delete, and format them. Any comment identified as a
closing side comment will be placed just a single space to the right of
its closing brace.
-.IP "\fB\-cscl=string\fR, or \fB\-\-closing\-side\-comment\-list\-string\fR" 4
-.IX Item "-cscl=string, or --closing-side-comment-list-string"
+.IP "\fB\-cscl=string\fR, or \fB\-\-closing\-side\-comment\-list\fR" 4
+.IX Item "-cscl=string, or --closing-side-comment-list"
where \f(CW\*(C`string\*(C'\fR is a list of block types to be tagged with closing side
comments. By default, all code block types preceded by a keyword or
label (such as \f(CW\*(C`if\*(C'\fR, \f(CW\*(C`sub\*(C'\fR, and so on) will be tagged. The \fB\-cscl\fR
.Sp
If \fBn=1\fR is used, the results will be the same as \fBn=2\fR whenever the
resulting line length is less than the maximum allowed.
-=item \fB\-cscb\fR, or \fB\-\-closing\-side\-comments\-balanced\fR
-.Sp
+.IP "\fB\-cscb\fR, or \fB\-\-closing\-side\-comments\-balanced\fR" 4
+.IX Item "-cscb, or --closing-side-comments-balanced"
When using closing-side-comments, and the closing-side-comment-maximum-text
limit is exceeded, then the comment text must be abbreviated.
It is terminated with three dots if the \fB\-cscb\fR flag is negated:
long blocks of aligned comments unchanged, keeping certain list
formatting unchanged, or working around a glitch in perltidy.
.IP "\fB\-fs\fR, \fB\-\-format\-skipping\fR" 4
-.IX Item "-fs, --format-skipping"
+.IX Item "-fs, --format-skipping"
This flag, which is enabled by default, causes any code between
special beginning and ending comment markers to be passed to the
output without formatting. The default beginning marker is #<<<
appear. If they do not appear to be working, use the \-log flag and examine the
\&\fI.LOG\fR file. Use \fB\-nfs\fR to disable this feature.
.IP "\fB\-fsb=string\fR, \fB\-\-format\-skipping\-begin=string\fR" 4
-.IX Item "-fsb=string, --format-skipping-begin=string"
+.IX Item "-fsb=string, --format-skipping-begin=string"
The \fB\-fsb=string\fR parameter may be used to change the beginning marker for
format skipping. The default is equivalent to \-fsb='#<<<'. The string that
you enter must begin with a # and should be in quotes as necessary to get past
\& \-fsb=\*(Aq#\e*{2,}\*(Aq becomes /^#\e*{2,}\es/ which matches #** and #*****
.Ve
.IP "\fB\-fse=string\fR, \fB\-\-format\-skipping\-end=string\fR" 4
-.IX Item "-fse=string, --format-skipping-end=string"
+.IX Item "-fse=string, --format-skipping-end=string"
The \fB\-fsb=string\fR is the corresponding parameter used to change the
ending marker for format skipping. The default is equivalent to
\&\-fse='#<<<'.
separately by parameters in the section \*(L"Blank Line
Control\*(R".
.IP "\fB\-fnl\fR, \fB\-\-freeze\-newlines\fR" 4
-.IX Item "-fnl, --freeze-newlines"
+.IX Item "-fnl, --freeze-newlines"
If you do not want any changes to the line breaks within
lines of code in your script, set
\&\fB\-fnl\fR, and they will remain fixed, and the rest of the commands in
as they are, you can use the \fB\-fbl\fR flag which is described
in the section \*(L"Blank Line Control\*(R".
.IP "\fB\-ce\fR, \fB\-\-cuddled\-else\fR" 4
-.IX Item "-ce, --cuddled-else"
+.IX Item "-ce, --cuddled-else"
Enable the \*(L"cuddled else\*(R" style, in which \f(CW\*(C`else\*(C'\fR and \f(CW\*(C`elsif\*(C'\fR are
follow immediately after the curly brace closing the previous block.
The default is not to use cuddled elses, and is indicated with the flag
\& zzz();
\& }
.Ve
+.IP "\fB\-cb\fR, \fB\-\-cuddled\-blocks\fR" 4
+.IX Item "-cb, --cuddled-blocks"
+This flag enables the \*(L"cuddled else\*(R" format style on a chain of specified block
+types. The default is to apply it to a chain consisting of try-catch-finally
+blocks, but it can apply to any desired chain of blocks by specifying their
+names on a separate parameter \fB\-cbl\fR, described in the next section.
+.Sp
+.Vb 9
+\& # perltidy \-cb:
+\& try {
+\& throw Error::Simple( "ok 2\en", 2 );
+\& } catch Error::Simple with {
+\& my $err = shift;
+\& print "$err";
+\& } finally {
+\& print "ok 3\en";
+\& };
+.Ve
+.Sp
+Cuddling between a pair of code blocks requires that the closing brace of the
+first block start a new line. If this block is entirely on one line in the
+input file, it is necessary to decide if it should be broken to allow cuddling.
+This decision is controlled by the flag \fB\-cbo=n\fR discussed below. The default
+and recommended value of \fB\-cbo=1\fR bases this decision on the first block in
+the chain. If it spans multiple lines then cuddling is made and continues
+along the chain, regardless of the sizes of subsequent blocks. Otherwise, short
+lines remain intact.
+.Sp
+So for example, the \fB\-cb\fR flag would not have any effect if the above snippet
+is rewritten as
+.Sp
+.Vb 3
+\& try { throw Error::Simple( "ok 2\en", 2 ); }
+\& catch Error::Simple with { my $err = shift; print "$err"; }
+\& finally { print "ok 3\en"; };
+.Ve
+.Sp
+If the first block spans multiple lines, then cuddling can be done and will
+continue for the subsequent blocks in the chain, as illustrated in the previous
+snippet.
+.Sp
+If there are blank lines between cuddled blocks they will be eliminated. If
+there are comments after the closing brace where cuddling would occur then
+cuddling will be prevented. If this occurs, cuddling will restart later in the
+chain if possible.
+.Sp
+The default for this parameter is \fB\-\-nocuddled\-blocks\fR
+.IP "\fB\-cbl\fR, \fB\-\-cuddled\-block\-list\fR" 4
+.IX Item "-cbl, --cuddled-block-list"
+The block types to which the \fB\-cuddled\-blocks\fR style applies is defined by
+this parameter. This parameter is a character string, giving a list of
+block types separated by dashes.
+.Sp
+The default value for this string is
+.Sp
+.Vb 1
+\& \-cbl="try\-catch\-finally"
+.Ve
+.Sp
+This string will cause cuddled formatting to be applied to every block in a chain
+starting with a \*(L"try\*(R" and followed by any number of \*(L"catch\*(R" and \*(L"finally\*(R"
+blocks.
+.Sp
+In general, a string describing a chain of blocks has the form
+.Sp
+.Vb 1
+\& \-cbl="word1\-word2\-word3\-...\-wordn"
+.Ve
+.Sp
+In this case, a chain begins when an opening block brace preceded by word1 in
+the list is encountered. The chain continues if the closing block brace is
+followed immediately by any of word2, word3, etc.
+.Sp
+If the leading word, word1, might be repeated later in a chain then it should
+also be included amoung the secondary words.
+.Sp
+Multiple chain types may be specified by separating the strings with commas or
+spaces. So for example if we have two chains of code blocks, f1\-f2\-f3 and g1\-g2\-g3\-g4,
+they could be specified as
+.Sp
+.Vb 3
+\& \-cbl="f1\-f2\-f3 g1\-g2\-g3\-g4"
+\&or
+\& \-cbl=f1\-f2\-f3,g1\-g2\-g3\-g4
+.Ve
+.Sp
+Spaces are easier to read but commas may avoid quotation difficulties when
+entering data in a command shell.
+.Sp
+To define secondary words that apply to all block types, other than those explicitly specified,
+the leading word can be omitted. For example, the built-in cuddled-else format specified by
+the \fB\-ce\fR flag can be approximately specified by
+.Sp
+.Vb 3
+\& \-cbl="if\-else\-elsif unless\-else\-elsif \-continue"
+\&or
+\& \-cbl=if\-else\-elsif,unless\-else\-elsif,\-continue
+.Ve
+.Sp
+The final string \-continue allows cuddling the optional continue block
+which may follow may other block types.
+.Sp
+As a diagnostic check, the flag \fB\-\-dump\-cuddled\-block\-list\fR or \fB\-dcbl\fR can be
+used to view the hash of values this flag creates.
+.Sp
+Finally, note that the \fB\-cbl\fR flag by itself merely specifies which blocks are formatted
+with the cuddled format. It has no effect unless this formatting style is activated with
+\&\fB\-cb\fR.
+.IP "\fB\-cbo=n\fR, \fB\-\-cuddled\-break\-option=n\fR" 4
+.IX Item "-cbo=n, --cuddled-break-option=n"
+Cuddled formatting is only possible between a pair of code blocks if the
+closing brace of the first block starts a new line. If a block is encountered
+which is entirely on a single line, and cuddled formatting is selected, it is
+necessary to make a decision as to whether or not to \*(L"break\*(R" the block, meaning
+to cause it to span multiple lines. This parameter controls that decision. The
+options are:
+.Sp
+.Vb 4
+\& cbo=0 Never force a short block to break.
+\& cbo=1 If the first of a pair of blocks is broken in the input file,
+\& then break the second.
+\& cbo=2 Break open all blocks for maximal cuddled formatting.
+.Ve
+.Sp
+The default and recommended value is \fBcbo=1\fR. With this value, if the starting
+block of a chain spans multiple lines, then a cascade of breaks will occur for
+remaining blocks causing the entire chain to be cuddled.
+.Sp
+The option \fBcbo=0\fR can produce erratic cuddling if there are numerous one-line
+blocks.
+.Sp
+The option \fBcbo=2\fR produces maximal cuddling but will not allow any short blocks.
+.Sp
+Note: at present, this option currently only applies to blocks controlled by
+the \fB\-cb\fR flag. Cuddling under the \fB\-ce\fR flag corresponds approximately to
+\&\fB\-cbo=1\fR but cannot currently be changed.
.IP "\fB\-bl\fR, \fB\-\-opening\-brace\-on\-new\-line\fR" 4
-.IX Item "-bl, --opening-brace-on-new-line"
+.IX Item "-bl, --opening-brace-on-new-line"
Use the flag \fB\-bl\fR to place the opening brace on a new line:
.Sp
.Vb 4
\& if ( $input_file eq \*(Aq\-\*(Aq ) { # \-nbl (default)
.Ve
.IP "\fB\-sbl\fR, \fB\-\-opening\-sub\-brace\-on\-new\-line\fR" 4
-.IX Item "-sbl, --opening-sub-brace-on-new-line"
+.IX Item "-sbl, --opening-sub-brace-on-new-line"
The flag \fB\-sbl\fR can be used to override the value of \fB\-bl\fR for
the opening braces of named sub's. For example,
.Sp
This flag is negated with \fB\-nsbl\fR. If \fB\-sbl\fR is not specified,
the value of \fB\-bl\fR is used.
.IP "\fB\-asbl\fR, \fB\-\-opening\-anonymous\-sub\-brace\-on\-new\-line\fR" 4
-.IX Item "-asbl, --opening-anonymous-sub-brace-on-new-line"
+.IX Item "-asbl, --opening-anonymous-sub-brace-on-new-line"
The flag \fB\-asbl\fR is like the \fB\-sbl\fR flag except that it applies
to anonymous sub's instead of named subs. For example
.Sp
.Sp
This flag is negated with \fB\-nasbl\fR, and the default is \fB\-nasbl\fR.
.IP "\fB\-bli\fR, \fB\-\-brace\-left\-and\-indent\fR" 4
-.IX Item "-bli, --brace-left-and-indent"
+.IX Item "-bli, --brace-left-and-indent"
The flag \fB\-bli\fR is the same as \fB\-bl\fR but in addition it causes one
unit of continuation indentation ( see \fB\-ci\fR ) to be placed before
an opening and closing block braces.
\&\fBwhile\fR, \fBuntil\fR, and also with a preceding label. The next item
shows how to change this.
.IP "\fB\-blil=s\fR, \fB\-\-brace\-left\-and\-indent\-list=s\fR" 4
-.IX Item "-blil=s, --brace-left-and-indent-list=s"
+.IX Item "-blil=s, --brace-left-and-indent-list=s"
Use this parameter to change the types of block braces for which the
\&\fB\-bli\fR flag applies; see \*(L"Specifying Block Types\*(R". For example,
\&\fB\-blil='if elsif else'\fR would apply it to only \f(CW\*(C`if/elsif/else\*(C'\fR blocks.
.IP "\fB\-bar\fR, \fB\-\-opening\-brace\-always\-on\-right\fR" 4
-.IX Item "-bar, --opening-brace-always-on-right"
+.IX Item "-bar, --opening-brace-always-on-right"
The default style, \fB\-nbl\fR places the opening code block brace on a new
line if it does not fit on the same line as the opening keyword, like
this:
.Sp
A conflict occurs if both \fB\-bl\fR and \fB\-bar\fR are specified.
.IP "\fB\-otr\fR, \fB\-\-opening\-token\-right\fR and related flags" 4
-.IX Item "-otr, --opening-token-right and related flags"
+.IX Item "-otr, --opening-token-right and related flags"
The \fB\-otr\fR flag is a hint that perltidy should not place a break between a
comma and an opening token. For example:
.Sp
\& \-ohbr or \-\-opening\-hash\-brace\-right
\& \-osbr or \-\-opening\-square\-bracket\-right
.Ve
-.IP "Vertical tightness of non-block curly braces, parentheses, and square brackets." 4
+.IP "\fB\-wn\fR, \fB\-\-weld\-nested\-containers\fR" 4
+.IX Item "-wn, --weld-nested-containers"
+The \fB\-wn\fR flag causes closely nested pairs of opening and closing container
+symbols (curly braces, brackets, or parens) to be \*(L"welded\*(R" together, meaning
+that they are treated as if combined into a single unit, with the indentation
+of the innermost code reduced to be as if there were just a single container
+symbol.
+.Sp
+For example:
+.Sp
+.Vb 6
+\& # default formatting
+\& do {
+\& {
+\& next if $x == $y;
+\& }
+\& } until $x++ > $z;
+\&
+\& # perltidy \-wn
+\& do { {
+\& next if $x == $y;
+\& } } until $x++ > $z;
+.Ve
+.Sp
+When this flag is set perltidy makes a preliminary pass through the file and
+identifies all nested pairs of containers. To qualify as a nested pair, the
+closing container symbols must be immediately adjacent. The opening symbols
+must either be adjacent, or, if the outer opening symbol is an opening
+paren, they may be separated by any single non-container symbol or something
+that looks like a function evaluation.
+.Sp
+Any container symbol may serve as both the inner container of one pair and as
+the outer container of an adjacent pair. Consequently, any number of adjacent
+opening or closing symbols may join together in weld. For example, here are
+three levels of wrapped function calls:
+.Sp
+.Vb 9
+\& # default formatting
+\& my (@date_time) = Localtime(
+\& Date_to_Time(
+\& Add_Delta_DHMS(
+\& $year, $month, $day, $hour, $minute, $second,
+\& \*(Aq0\*(Aq, $offset, \*(Aq0\*(Aq, \*(Aq0\*(Aq
+\& )
+\& )
+\& );
+\&
+\& # perltidy \-wn
+\& my (@date_time) = Localtime( Date_to_Time( Add_Delta_DHMS(
+\& $year, $month, $day, $hour, $minute, $second,
+\& \*(Aq0\*(Aq, $offset, \*(Aq0\*(Aq, \*(Aq0\*(Aq
+\& ) ) );
+.Ve
+.Sp
+Notice how the indentation of the inner lines are reduced by two levels in this
+case. This example also shows the typical result of this formatting, namely it
+is a sandwich consisting of an initial opening layer, a central section of any
+complexity forming the \*(L"meat\*(R" of the sandwich, and a final closing layer. This
+predictable structure helps keep the compacted structure readable.
+.Sp
+The inner sandwich layer is required to be at least one line thick. If this
+cannot be achieved, welding does not occur. This constraint can cause
+formatting to take a couple of iterations to stabilize when it is first applied
+to a script. The \fB\-conv\fR flag can be used to insure that the final format is
+achieved in a single run.
+.Sp
+Here is an example illustrating a welded container within a welded containers:
+.Sp
+.Vb 11
+\& # default formatting
+\& $x\->badd(
+\& bmul(
+\& $class\->new(
+\& abs(
+\& $sx * int( $xr\->numify() ) & $sy * int( $yr\->numify() )
+\& )
+\& ),
+\& $m
+\& )
+\& );
+\&
+\& # perltidy \-wn
+\& $x\->badd( bmul(
+\& $class\->new( abs(
+\& $sx * int( $xr\->numify() ) & $sy * int( $yr\->numify() )
+\& ) ),
+\& $m
+\& ) );
+.Ve
+.Sp
+This format option is quite general but there are some limitations.
+.Sp
+One limitiation is that any line length limit still applies and can cause long
+welded sections to be broken into multiple lines.
+.Sp
+Another limitation is that an opening symbol which delimits quoted text cannot
+be included in a welded pair. This is because quote delimiters are treated
+specially in perltidy.
+.Sp
+Finally, the stacking of containers defined by this flag have priority over
+any other container stacking flags. This is because any welding is done first.
+.IP "\fBVertical tightness\fR of non-block curly braces, parentheses, and square brackets." 4
.IX Item "Vertical tightness of non-block curly braces, parentheses, and square brackets."
These parameters control what shall be called vertical tightness. Here are the
main points:
The exception is that a cascade of closing block braces may
be stacked on a single line. See \fB\-scbb\fR.
.IP "\fB\-sot\fR, \fB\-\-stack\-opening\-tokens\fR and related flags" 4
-.IX Item "-sot, --stack-opening-tokens and related flags"
+.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
will case a cascade of opening block braces to appear on a single line,
although this an uncommon occurrence except in test scripts.
.IP "\fB\-sct\fR, \fB\-\-stack\-closing\-tokens\fR and related flags" 4
-.IX Item "-sct, --stack-closing-tokens and related flags"
+.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
non-block containers are stacked, the flag \fB\-sac\fR or \fB\-\-stack\-all\-containers\fR
is an abbreviation for \fB\-sot \-sot\fR.
.IP "\fB\-dnl\fR, \fB\-\-delete\-old\-newlines\fR" 4
-.IX Item "-dnl, --delete-old-newlines"
+.IX Item "-dnl, --delete-old-newlines"
By default, perltidy first deletes all old line break locations, and then it
looks for good break points to match the desired line length. Use \fB\-ndnl\fR
or \fB\-\-nodelete\-old\-newlines\fR to force perltidy to retain all old line break
points.
.IP "\fB\-anl\fR, \fB\-\-add\-newlines\fR" 4
-.IX Item "-anl, --add-newlines"
+.IX Item "-anl, --add-newlines"
By default, perltidy will add line breaks when necessary to create
continuations of long lines and to improve the script appearance. Use
\&\fB\-nanl\fR or \fB\-\-noadd\-newlines\fR to prevent any new line breaks.
have been improving with each release, but several parameters are
available to control list formatting.
.IP "\fB\-boc\fR, \fB\-\-break\-at\-old\-comma\-breakpoints\fR" 4
-.IX Item "-boc, --break-at-old-comma-breakpoints"
+.IX Item "-boc, --break-at-old-comma-breakpoints"
This flag tells perltidy to try to break at all old commas. This is not
the default. Normally, perltidy makes a best guess at list formatting,
and seldom uses old comma breakpoints. Usually this works well,
must already be nicely formatted. For another possibility see
the \-fs flag in \*(L"Skipping Selected Sections of Code\*(R".
.IP "\fB\-mft=n\fR, \fB\-\-maximum\-fields\-per\-table=n\fR" 4
-.IX Item "-mft=n, --maximum-fields-per-table=n"
+.IX Item "-mft=n, --maximum-fields-per-table=n"
If the computed number of fields for any table exceeds \fBn\fR, then it
will be reduced to \fBn\fR. The default value for \fBn\fR is a large number,
40. While this value should probably be left unchanged as a general
\& );
.Ve
.IP "\fB\-cab=n\fR, \fB\-\-comma\-arrow\-breakpoints=n\fR" 4
-.IX Item "-cab=n, --comma-arrow-breakpoints=n"
+.IX Item "-cab=n, --comma-arrow-breakpoints=n"
A comma which follows a comma arrow, '=>', is given special
consideration. In a long list, it is common to break at all such
commas. This parameter can be used to control how perltidy breaks at
lengths to shorter lengths, can be obtained by temporarily using a short
maximum line length.
.IP "\fB\-bol\fR, \fB\-\-break\-at\-old\-logical\-breakpoints\fR" 4
-.IX Item "-bol, --break-at-old-logical-breakpoints"
+.IX Item "-bol, --break-at-old-logical-breakpoints"
By default, if a logical expression is broken at a \f(CW\*(C`&&\*(C'\fR, \f(CW\*(C`||\*(C'\fR, \f(CW\*(C`and\*(C'\fR,
or \f(CW\*(C`or\*(C'\fR, then the container will remain broken. Also, breaks
at internal keywords \f(CW\*(C`if\*(C'\fR and \f(CW\*(C`unless\*(C'\fR will normally be retained.
To prevent this, and thus form longer lines, use \fB\-nbol\fR.
.IP "\fB\-bok\fR, \fB\-\-break\-at\-old\-keyword\-breakpoints\fR" 4
-.IX Item "-bok, --break-at-old-keyword-breakpoints"
+.IX Item "-bok, --break-at-old-keyword-breakpoints"
By default, perltidy will retain a breakpoint before keywords which may
return lists, such as \f(CW\*(C`sort\*(C'\fR and <map>. This allows chains of these
operators to be displayed one per line. Use \fB\-nbok\fR to prevent
retaining these breakpoints.
.IP "\fB\-bot\fR, \fB\-\-break\-at\-old\-ternary\-breakpoints\fR" 4
-.IX Item "-bot, --break-at-old-ternary-breakpoints"
+.IX Item "-bot, --break-at-old-ternary-breakpoints"
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"
+.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
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"
+.IX Item "-iob, --ignore-old-breakpoints"
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"
+.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
placed. Perltidy has several commands for controlling the insertion,
retention, and removal of blank lines.
.IP "\fB\-fbl\fR, \fB\-\-freeze\-blank\-lines\fR" 4
-.IX Item "-fbl, --freeze-blank-lines"
+.IX Item "-fbl, --freeze-blank-lines"
Set \fB\-fbl\fR if you want to the blank lines in your script to
remain exactly as they are. The rest of the parameters in
this section may then be ignored. (Note: setting the \fB\-fbl\fR flag
is equivalent to setting \fB\-mbl=0\fR and \fB\-kbl=2\fR).
.IP "\fB\-bbc\fR, \fB\-\-blanks\-before\-comments\fR" 4
-.IX Item "-bbc, --blanks-before-comments"
+.IX Item "-bbc, --blanks-before-comments"
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"
+.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.
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"
+.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 \fB\-blbp=1\fR.
.Sp
\&\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"
+.IX Item "-bbs, --blanks-before-subs"
For compatibility 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"
+.IX Item "-bbb, --blanks-before-blocks"
A blank line will be introduced before blocks of coding delimited by
\&\fBfor\fR, \fBforeach\fR, \fBwhile\fR, \fBuntil\fR, and \fBif\fR, \fBunless\fR, in the following
circumstances:
This flag obviously does not apply to pod sections,
here-documents, and quotes.
.IP "\fB\-kbl=n\fR, \fB\-\-keep\-old\-blank\-lines=n\fR" 4
-.IX Item "-kbl=n, --keep-old-blank-lines=n"
+.IX Item "-kbl=n, --keep-old-blank-lines=n"
The \fB\-kbl=n\fR flag gives you control over how your existing blank lines are
treated.
.Sp
.Sp
The default is \fBn=1\fR.
.IP "\fB\-sob\fR, \fB\-\-swallow\-optional\-blank\-lines\fR" 4
-.IX Item "-sob, --swallow-optional-blank-lines"
+.IX Item "-sob, --swallow-optional-blank-lines"
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"
+.IX Item "-nsob, --noswallow-optional-blank-lines"
This is equivalent to \fBkbl=1\fR and is included for compatibility with
previous versions.
.SS "Styles"
\& : \*(Aq elsewhere in this document\*(Aq
\& );
.Ve
+.SS "Controlling Vertical Alignment"
+.IX Subsection "Controlling Vertical Alignment"
+Vertical alignment refers to lining up certain symbols in list of consecutive
+similar lines to improve readability. For example, the \*(L"fat commas\*(R" are
+aligned in the following statement:
+.PP
+.Vb 5
+\& $data = $pkg\->new(
+\& PeerAddr => join( ".", @port[ 0 .. 3 ] ),
+\& PeerPort => $port[4] * 256 + $port[5],
+\& Proto => \*(Aqtcp\*(Aq
+\& );
+.Ve
+.PP
+The only explicit control on vertical alignment is to turn it off using
+\&\fB\-novalign\fR, a flag mainly intended for debugging. However, vertical
+alignment can be forced to stop and restart by selectively introducing blank
+lines. For example, a blank has been inserted in the following code
+to keep somewhat similar things aligned.
+.PP
+.Vb 4
+\& %option_range = (
+\& \*(Aqformat\*(Aq => [ \*(Aqtidy\*(Aq, \*(Aqhtml\*(Aq, \*(Aquser\*(Aq ],
+\& \*(Aqoutput\-line\-ending\*(Aq => [ \*(Aqdos\*(Aq, \*(Aqwin\*(Aq, \*(Aqmac\*(Aq, \*(Aqunix\*(Aq ],
+\& \*(Aqcharacter\-encoding\*(Aq => [ \*(Aqnone\*(Aq, \*(Aqutf8\*(Aq ],
+\&
+\& \*(Aqblock\-brace\-tightness\*(Aq => [ 0, 2 ],
+\& \*(Aqbrace\-tightness\*(Aq => [ 0, 2 ],
+\& \*(Aqparen\-tightness\*(Aq => [ 0, 2 ],
+\& \*(Aqsquare\-bracket\-tightness\*(Aq => [ 0, 2 ],
+\& );
+.Ve
.SS "Other Controls"
.IX Subsection "Other Controls"
.IP "Deleting selected text" 4
.Sp
http://www.netmanage.com/000/20021101_005_tcm21\-6336.pdf
.Sp
-Under Windows \s-1NT\s0 / 2000 / \s-1XP\s0 the \s-1PERLTIDY\s0 environment variable can be placed in
+Under Windows \s-1NT / 2000 / XP\s0 the \s-1PERLTIDY\s0 environment variable can be placed in
either the user section or the system section. The later makes the
configuration file common to all users on the machine. Be sure to enter the
full path of the configuration file in the value of the environment variable.
.IX Item "Debugging"
The following flags are available for debugging:
.Sp
+\&\fB\-\-dump\-cuddled\-block\-list\fR or \fB\-dcbl\fR will dump to standard output the
+internal hash of cuddled block types created by a \fB\-cuddled\-block\-list\fR input
+string.
+.Sp
\&\fB\-\-dump\-defaults\fR or \fB\-ddf\fR will write the default option set to standard output and quit
.Sp
\&\fB\-\-dump\-profile\fR or \fB\-dpro\fR will write the name of the current
single process. It is on by default but can be deactivated for
testing with \fB\-nmem\fR.
.Sp
+\&\fB\-\-file\-size\-order\fR or \fB\-fso\fR will cause files to be processed in order of
+increasing size, when multiple files are being processed. This is useful
+during program development, when large numbers of files with varying sizes are
+processed, because it can reduce virtual memory usage.
+.Sp
\&\fB\-DEBUG\fR will write a file with extension \fI.DEBUG\fR for each input file
showing the tokenization of all lines of code.
.IP "Working with MakeMaker, AutoLoader and SelfLoader" 4
to pass the pod through the Pod::Html module (which forms the basis of
the pod2html utility). Any code sections are formatted by perltidy, and
the results then merged. Note: perltidy creates a temporary file when
-Pod::Html is used; see \*(L"\s-1FILES\s0\*(R". Also, Pod::Html creates temporary
+Pod::Html is used; see \*(L"\s-1FILES\*(R"\s0. Also, Pod::Html creates temporary
files for its cache.
.Sp
\&\s-1NOTE:\s0 Perltidy counts the number of \f(CW\*(C`=cut\*(C'\fR lines, and either moves the
.Ve
.Sp
Perltidy merely writes any non-hex names that it sees in the html file.
-The following 16 color names are defined in the \s-1HTML\s0 3.2 standard:
+The following 16 color names are defined in the \s-1HTML 3.2\s0 standard:
.Sp
.Vb 10
\& black => 000000,
\&\fIperlstyle\fR\|(1), \fIPerl::Tidy\fR\|(3)
.SH "VERSION"
.IX Header "VERSION"
-This man page documents perltidy version 20170521.
+This man page documents perltidy version 20180220.
.SH "BUG REPORTS"
.IX Header "BUG REPORTS"
A list of current bugs and issues can be found at the \s-1CPAN\s0 site
To report a new bug or problem, use the link on this page.
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
-Copyright (c) 2000\-2017 by Steve Hancock
+Copyright (c) 2000\-2018 by Steve Hancock
.SH "LICENSE"
.IX Header "LICENSE"
This package is free software; you can redistribute it and/or modify it
under the terms of the \*(L"\s-1GNU\s0 General Public License\*(R".
.PP
-Please refer to the file \*(L"\s-1COPYING\s0\*(R" for details.
+Please refer to the file \*(L"\s-1COPYING\*(R"\s0 for details.
.SH "DISCLAIMER"
.IX Header "DISCLAIMER"
This package is distributed in the hope that it will be useful,
-but \s-1WITHOUT\s0 \s-1ANY\s0 \s-1WARRANTY\s0; without even the implied warranty of
-\&\s-1MERCHANTABILITY\s0 or \s-1FITNESS\s0 \s-1FOR\s0 A \s-1PARTICULAR\s0 \s-1PURPOSE\s0.
+but \s-1WITHOUT ANY WARRANTY\s0; without even the implied warranty of
+\&\s-1MERCHANTABILITY\s0 or \s-1FITNESS FOR A PARTICULAR PURPOSE.\s0
.PP
See the \*(L"\s-1GNU\s0 General Public License\*(R" for more details.
projects / perltidy.git / blobdiff