From: Steve Hancock <perltidy@users.sourceforge.net>
Date: Wed, 8 Sep 2021 14:45:17 +0000 (-0700)
Subject: bump version to 20210717.02
X-Git-Tag: 20210717.02^0
X-Git-Url: https://git.donarmstrong.com/?a=commitdiff_plain;h=895c3b9559b5cf745f3cfe57eeff038f58768457;p=perltidy.git
bump version to 20210717.02
---
diff --git a/CHANGES.md b/CHANGES.md
index 5f6f0af6..7c961d06 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -1,6 +1,6 @@
# Perltidy Change Log
-## 2021 07 17.01
+## 2021 07 17.02
- Fixed problem where a blank line following a closing code-skipping
comment, '#>>V', can be lost. A workaround for the previous version
diff --git a/MANIFEST b/MANIFEST
index b4d99fd4..e190c918 100644
--- a/MANIFEST
+++ b/MANIFEST
@@ -1,3 +1,4 @@
+.github/workflows/perltest.yml
.pre-commit-hooks.yaml
bin/perltidy
BUGS.md
diff --git a/bin/perltidy b/bin/perltidy
index 866cec05..7041cf67 100755
--- a/bin/perltidy
+++ b/bin/perltidy
@@ -4788,7 +4788,7 @@ The perltidy binary uses the Perl::Tidy module and is installed when that module
=head1 VERSION
-This man page documents perltidy version 20210717.01
+This man page documents perltidy version 20210717.02
=head1 BUG REPORTS
diff --git a/lib/Perl/Tidy.pm b/lib/Perl/Tidy.pm
index f69f5369..b1fadb17 100644
--- a/lib/Perl/Tidy.pm
+++ b/lib/Perl/Tidy.pm
@@ -110,7 +110,7 @@ BEGIN {
# Release version must be bumped, and it is probably past time for a
# release anyway.
- $VERSION = '20210717.01';
+ $VERSION = '20210717.02';
}
sub DESTROY {
diff --git a/lib/Perl/Tidy.pod b/lib/Perl/Tidy.pod
index d653d6d2..b44dacf0 100644
--- a/lib/Perl/Tidy.pod
+++ b/lib/Perl/Tidy.pod
@@ -432,7 +432,7 @@ The module 'Perl::Tidy' comes with a binary 'perltidy' which is installed when t
=head1 VERSION
-This man page documents Perl::Tidy version 20210717.01
+This man page documents Perl::Tidy version 20210717.02
=head1 LICENSE
diff --git a/lib/Perl/Tidy/Debugger.pm b/lib/Perl/Tidy/Debugger.pm
index 25206d6f..9a11f6c1 100644
--- a/lib/Perl/Tidy/Debugger.pm
+++ b/lib/Perl/Tidy/Debugger.pm
@@ -7,7 +7,7 @@
package Perl::Tidy::Debugger;
use strict;
use warnings;
-our $VERSION = '20210717.01';
+our $VERSION = '20210717.02';
sub new {
diff --git a/lib/Perl/Tidy/DevNull.pm b/lib/Perl/Tidy/DevNull.pm
index 59075261..4f003c5e 100644
--- a/lib/Perl/Tidy/DevNull.pm
+++ b/lib/Perl/Tidy/DevNull.pm
@@ -7,7 +7,7 @@
package Perl::Tidy::DevNull;
use strict;
use warnings;
-our $VERSION = '20210717.01';
+our $VERSION = '20210717.02';
sub new { my $self = shift; return bless {}, $self }
sub print { return }
sub close { return }
diff --git a/lib/Perl/Tidy/Diagnostics.pm b/lib/Perl/Tidy/Diagnostics.pm
index 5424e8e8..13db3ba2 100644
--- a/lib/Perl/Tidy/Diagnostics.pm
+++ b/lib/Perl/Tidy/Diagnostics.pm
@@ -20,7 +20,7 @@
package Perl::Tidy::Diagnostics;
use strict;
use warnings;
-our $VERSION = '20210717.01';
+our $VERSION = '20210717.02';
sub AUTOLOAD {
diff --git a/lib/Perl/Tidy/FileWriter.pm b/lib/Perl/Tidy/FileWriter.pm
index c31f2bf3..89d226f3 100644
--- a/lib/Perl/Tidy/FileWriter.pm
+++ b/lib/Perl/Tidy/FileWriter.pm
@@ -7,7 +7,7 @@
package Perl::Tidy::FileWriter;
use strict;
use warnings;
-our $VERSION = '20210717.01';
+our $VERSION = '20210717.02';
use constant DEVEL_MODE => 0;
diff --git a/lib/Perl/Tidy/Formatter.pm b/lib/Perl/Tidy/Formatter.pm
index 77fc7fba..1ef1650f 100644
--- a/lib/Perl/Tidy/Formatter.pm
+++ b/lib/Perl/Tidy/Formatter.pm
@@ -49,7 +49,7 @@ use constant DEVEL_MODE => 0;
{ #<<< A non-indenting brace to contain all lexical variables
use Carp;
-our $VERSION = '20210717.01';
+our $VERSION = '20210717.02';
# The Tokenizer will be loaded with the Formatter
##use Perl::Tidy::Tokenizer; # for is_keyword()
diff --git a/lib/Perl/Tidy/HtmlWriter.pm b/lib/Perl/Tidy/HtmlWriter.pm
index c5239c2e..9ff2f57a 100644
--- a/lib/Perl/Tidy/HtmlWriter.pm
+++ b/lib/Perl/Tidy/HtmlWriter.pm
@@ -7,7 +7,7 @@
package Perl::Tidy::HtmlWriter;
use strict;
use warnings;
-our $VERSION = '20210717.01';
+our $VERSION = '20210717.02';
use File::Basename;
diff --git a/lib/Perl/Tidy/IOScalar.pm b/lib/Perl/Tidy/IOScalar.pm
index 34103722..b4e7a266 100644
--- a/lib/Perl/Tidy/IOScalar.pm
+++ b/lib/Perl/Tidy/IOScalar.pm
@@ -10,7 +10,7 @@ package Perl::Tidy::IOScalar;
use strict;
use warnings;
use Carp;
-our $VERSION = '20210717.01';
+our $VERSION = '20210717.02';
sub AUTOLOAD {
diff --git a/lib/Perl/Tidy/IOScalarArray.pm b/lib/Perl/Tidy/IOScalarArray.pm
index d9f16b3d..7644d562 100644
--- a/lib/Perl/Tidy/IOScalarArray.pm
+++ b/lib/Perl/Tidy/IOScalarArray.pm
@@ -14,7 +14,7 @@ package Perl::Tidy::IOScalarArray;
use strict;
use warnings;
use Carp;
-our $VERSION = '20210717.01';
+our $VERSION = '20210717.02';
sub AUTOLOAD {
diff --git a/lib/Perl/Tidy/IndentationItem.pm b/lib/Perl/Tidy/IndentationItem.pm
index dffdf19e..547a0d1f 100644
--- a/lib/Perl/Tidy/IndentationItem.pm
+++ b/lib/Perl/Tidy/IndentationItem.pm
@@ -8,7 +8,7 @@
package Perl::Tidy::IndentationItem;
use strict;
use warnings;
-our $VERSION = '20210717.01';
+our $VERSION = '20210717.02';
BEGIN {
diff --git a/lib/Perl/Tidy/LineBuffer.pm b/lib/Perl/Tidy/LineBuffer.pm
index 42a674b3..e2fae0bd 100644
--- a/lib/Perl/Tidy/LineBuffer.pm
+++ b/lib/Perl/Tidy/LineBuffer.pm
@@ -12,7 +12,7 @@
package Perl::Tidy::LineBuffer;
use strict;
use warnings;
-our $VERSION = '20210717.01';
+our $VERSION = '20210717.02';
sub AUTOLOAD {
diff --git a/lib/Perl/Tidy/LineSink.pm b/lib/Perl/Tidy/LineSink.pm
index 20430286..2361d021 100644
--- a/lib/Perl/Tidy/LineSink.pm
+++ b/lib/Perl/Tidy/LineSink.pm
@@ -8,7 +8,7 @@
package Perl::Tidy::LineSink;
use strict;
use warnings;
-our $VERSION = '20210717.01';
+our $VERSION = '20210717.02';
sub AUTOLOAD {
diff --git a/lib/Perl/Tidy/LineSource.pm b/lib/Perl/Tidy/LineSource.pm
index c232282d..7f7950a6 100644
--- a/lib/Perl/Tidy/LineSource.pm
+++ b/lib/Perl/Tidy/LineSource.pm
@@ -8,7 +8,7 @@
package Perl::Tidy::LineSource;
use strict;
use warnings;
-our $VERSION = '20210717.01';
+our $VERSION = '20210717.02';
sub AUTOLOAD {
diff --git a/lib/Perl/Tidy/Logger.pm b/lib/Perl/Tidy/Logger.pm
index 89ee5197..668b661c 100644
--- a/lib/Perl/Tidy/Logger.pm
+++ b/lib/Perl/Tidy/Logger.pm
@@ -7,7 +7,7 @@
package Perl::Tidy::Logger;
use strict;
use warnings;
-our $VERSION = '20210717.01';
+our $VERSION = '20210717.02';
sub AUTOLOAD {
diff --git a/lib/Perl/Tidy/Tokenizer.pm b/lib/Perl/Tidy/Tokenizer.pm
index f0c71648..07cf9bdf 100644
--- a/lib/Perl/Tidy/Tokenizer.pm
+++ b/lib/Perl/Tidy/Tokenizer.pm
@@ -21,7 +21,7 @@
package Perl::Tidy::Tokenizer;
use strict;
use warnings;
-our $VERSION = '20210717.01';
+our $VERSION = '20210717.02';
# this can be turned on for extra checking during development
use constant DEVEL_MODE => 0;
diff --git a/lib/Perl/Tidy/VerticalAligner.pm b/lib/Perl/Tidy/VerticalAligner.pm
index be6e5a25..ade5229f 100644
--- a/lib/Perl/Tidy/VerticalAligner.pm
+++ b/lib/Perl/Tidy/VerticalAligner.pm
@@ -1,7 +1,7 @@
package Perl::Tidy::VerticalAligner;
use strict;
use warnings;
-our $VERSION = '20210717.01';
+our $VERSION = '20210717.02';
use Perl::Tidy::VerticalAligner::Alignment;
use Perl::Tidy::VerticalAligner::Line;
diff --git a/lib/Perl/Tidy/VerticalAligner/Alignment.pm b/lib/Perl/Tidy/VerticalAligner/Alignment.pm
index aee1609c..c077d4c1 100644
--- a/lib/Perl/Tidy/VerticalAligner/Alignment.pm
+++ b/lib/Perl/Tidy/VerticalAligner/Alignment.pm
@@ -10,7 +10,7 @@ use warnings;
{ #<<< A non-indenting brace
-our $VERSION = '20210717.01';
+our $VERSION = '20210717.02';
# _column_ # the current column number
# _saved_column_ # a place for temporary storage
diff --git a/lib/Perl/Tidy/VerticalAligner/Line.pm b/lib/Perl/Tidy/VerticalAligner/Line.pm
index 824ba8c5..aef9e6de 100644
--- a/lib/Perl/Tidy/VerticalAligner/Line.pm
+++ b/lib/Perl/Tidy/VerticalAligner/Line.pm
@@ -8,7 +8,7 @@
package Perl::Tidy::VerticalAligner::Line;
use strict;
use warnings;
-our $VERSION = '20210717.01';
+our $VERSION = '20210717.02';
BEGIN {
my $i = 0;
diff --git a/side-comm b/side-comm
deleted file mode 100644
index 0ff46c97..00000000
--- a/side-comm
+++ /dev/null
@@ -1,3827 +0,0 @@
-PERLTIDY(1) User Contributed Perl Documentation PERLTIDY(1)
-
-NNAAMMEE
- perltidy - a perl script indenter and reformatter
-
-SSYYNNOOPPSSIISS
- perltidy [ options ] file1 file2 file3 ...
- (output goes to file1.tdy, file2.tdy, file3.tdy, ...)
- perltidy [ options ] file1 -o outfile
- perltidy [ options ] file1 -st >outfile
- perltidy [ options ] <infile >outfile
-
-DDEESSCCRRIIPPTTIIOONN
- Perltidy reads a perl script and writes an indented, reformatted script.
-
- Many users will find enough information in "EXAMPLES" to get started. New users may benefit from the short
- tutorial which can be found at http://perltidy.sourceforge.net/tutorial.html
-
- A convenient aid to systematically defining a set of style parameters can be found at
- http://perltidy.sourceforge.net/stylekey.html
-
- Perltidy can produce output on either of two modes, depending on the existence of an --hhttmmll flag. Without this
- flag, the output is passed through a formatter. The default formatting tries to follow the recommendations in
- ppeerrllssttyyllee(1), but it can be controlled in detail with numerous input parameters, which are described in
- "FORMATTING OPTIONS".
-
- When the --hhttmmll flag is given, the output is passed through an HTML formatter which is described in "HTML
- OPTIONS".
-
-EEXXAAMMPPLLEESS
- perltidy somefile.pl
-
- This will produce a file _s_o_m_e_f_i_l_e_._p_l_._t_d_y containing the script reformatted using the default options, which
- approximate the style suggested in ppeerrllssttyyllee(1). The source file _s_o_m_e_f_i_l_e_._p_l is unchanged.
-
- perltidy *.pl
-
- Execute perltidy on all _._p_l files in the current directory with the default options. The output will be in
- files with an appended _._t_d_y extension. For any file with an error, there will be a file with extension _._E_R_R.
-
- perltidy -b file1.pl file2.pl
-
- Modify _f_i_l_e_1_._p_l and _f_i_l_e_2_._p_l in place, and backup the originals to _f_i_l_e_1_._p_l_._b_a_k and _f_i_l_e_2_._p_l_._b_a_k. If
- _f_i_l_e_1_._p_l_._b_a_k and/or _f_i_l_e_2_._p_l_._b_a_k already exist, they will be overwritten.
-
- perltidy -b -bext='/' file1.pl file2.pl
-
- Same as the previous example except that the backup files _f_i_l_e_1_._p_l_._b_a_k and _f_i_l_e_2_._p_l_._b_a_k will be deleted if there
- are no errors.
-
- perltidy -gnu somefile.pl
-
- Execute perltidy on file _s_o_m_e_f_i_l_e_._p_l with a style which approximates the GNU Coding Standards for C programs.
- The output will be _s_o_m_e_f_i_l_e_._p_l_._t_d_y.
-
- perltidy -i=3 somefile.pl
-
- Execute perltidy on file _s_o_m_e_f_i_l_e_._p_l, with 3 columns for each level of indentation (--ii==33) instead of the default
- 4 columns. There will not be any tabs in the reformatted script, except for any which already exist in
- comments, pod documents, quotes, and here documents. Output will be _s_o_m_e_f_i_l_e_._p_l_._t_d_y.
-
- perltidy -i=3 -et=8 somefile.pl
-
- Same as the previous example, except that leading whitespace will be entabbed with one tab character per 8
- spaces.
-
- perltidy -ce -l=72 somefile.pl
-
- Execute perltidy on file _s_o_m_e_f_i_l_e_._p_l with all defaults except use "cuddled elses" (--ccee) and a maximum line
- length of 72 columns (--ll==7722) instead of the default 80 columns.
-
- perltidy -g somefile.pl
-
- Execute perltidy on file _s_o_m_e_f_i_l_e_._p_l and save a log file _s_o_m_e_f_i_l_e_._p_l_._L_O_G which shows the nesting of braces,
- parentheses, and square brackets at the start of every line.
-
- perltidy -html somefile.pl
-
- This will produce a file _s_o_m_e_f_i_l_e_._p_l_._h_t_m_l containing the script with html markup. The output file will contain
- an embedded style sheet in the <HEAD> section which may be edited to change the appearance.
-
- perltidy -html -css=mystyle.css somefile.pl
-
- This will produce a file _s_o_m_e_f_i_l_e_._p_l_._h_t_m_l containing the script with html markup. This output file will contain
- a link to a separate style sheet file _m_y_s_t_y_l_e_._c_s_s. If the file _m_y_s_t_y_l_e_._c_s_s does not exist, it will be created.
- If it exists, it will not be overwritten.
-
- perltidy -html -pre somefile.pl
-
- Write an html snippet with only the PRE section to _s_o_m_e_f_i_l_e_._p_l_._h_t_m_l. This is useful when code snippets are
- being formatted for inclusion in a larger web page. No style sheet will be written in this case.
-
- perltidy -html -ss >mystyle.css
-
- Write a style sheet to _m_y_s_t_y_l_e_._c_s_s and exit.
-
- perltidy -html -frm mymodule.pm
-
- Write html with a frame holding a table of contents and the source code. The output files will be
- _m_y_m_o_d_u_l_e_._p_m_._h_t_m_l (the frame), _m_y_m_o_d_u_l_e_._p_m_._t_o_c_._h_t_m_l (the table of contents), and _m_y_m_o_d_u_l_e_._p_m_._s_r_c_._h_t_m_l (the source
- code).
-
-OOPPTTIIOONNSS -- OOVVEERRVVIIEEWW
- The entire command line is scanned for options, and they are processed before any files are processed. As a
- result, it does not matter whether flags are before or after any filenames. However, the relative order of
- parameters is important, with later parameters overriding the values of earlier parameters.
-
- For each parameter, there is a long name and a short name. The short names are convenient for keyboard input,
- while the long names are self-documenting and therefore useful in scripts. It is customary to use two leading
- dashes for long names, but one may be used.
-
- Most parameters which serve as on/off flags can be negated with a leading "n" (for the short name) or a leading
- "no" or "no-" (for the long name). For example, the flag to outdent long quotes is --oollqq or
- ----oouuttddeenntt--lloonngg--qquuootteess. The flag to skip this is --nnoollqq or ----nnoooouuttddeenntt--lloonngg--qquuootteess or ----nnoo--oouuttddeenntt--lloonngg--qquuootteess.
-
- Options may not be bundled together. In other words, options --qq and --gg may NOT be entered as --qqgg.
-
- Option names may be terminated early as long as they are uniquely identified. For example, instead of
- ----dduummpp--ttookkeenn--ttyyppeess, it would be sufficient to enter ----dduummpp--ttookk, or even ----dduummpp--tt, to uniquely identify this
- command.
-
- II//OO ccoonnttrrooll
- The following parameters concern the files which are read and written.
-
- --hh, ----hheellpp
- Show summary of usage and exit.
-
- --oo=filename, ----oouuttffiillee=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 (see --sstt), the output will go to _f_i_l_e_n_a_m_e_._t_d_y. [Note: -
- does not redirect to standard output. Use --sstt instead.]
-
- --sstt, ----ssttaannddaarrdd--oouuttppuutt
- 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
- standard output device, so a special flag, --sstt, is required to request outputting to the standard output.
- For example,
-
- perltidy somefile.pl -st >somefile.new.pl
-
- This option may only be used if there is just a single input file. The default is --nnsstt or
- ----nnoossttaannddaarrdd--oouuttppuutt.
-
- --ssee, ----ssttaannddaarrdd--eerrrroorr--oouuttppuutt
- If perltidy detects an error when processing file _s_o_m_e_f_i_l_e_._p_l, its default behavior is to write error
- messages to file _s_o_m_e_f_i_l_e_._p_l_._E_R_R. Use --ssee to cause all error messages to be sent to the standard error
- output stream instead. This directive may be negated with --nnssee. Thus, you may place --ssee in a _._p_e_r_l_t_i_d_y_r_c
- and override it when desired with --nnssee on the command line.
-
- --ooeexxtt=ext, ----oouuttppuutt--ffiillee--eexxtteennssiioonn=ext
- Change the extension of the output file to be _e_x_t instead of the default _t_d_y (or _h_t_m_l in case the ---hhttmmll
- option is used). See "Specifying File Extensions".
-
- --ooppaatthh=path, ----oouuttppuutt--ppaatthh=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 _p_a_t_h instead.
-
- The path should end in a valid path separator character, but perltidy will try to add one if it is missing.
-
- For example
-
- perltidy somefile.pl -opath=/tmp/
-
- will produce _/_t_m_p_/_s_o_m_e_f_i_l_e_._p_l_._t_d_y. Otherwise, _s_o_m_e_f_i_l_e_._p_l_._t_d_y will appear in whatever directory contains
- _s_o_m_e_f_i_l_e_._p_l.
-
- If the path contains spaces, it should be placed in quotes.
-
- This parameter will be ignored if output is being directed to standard output, or if it is being specified
- explicitly with the --oo==ss parameter.
-
- --bb, ----bbaacckkuupp--aanndd--mmooddiiffyy--iinn--ppllaaccee
- Modify the input file or files in-place and save the original with the extension _._b_a_k. Any existing _._b_a_k
- file will be deleted. See next item for changing the default backup extension, and for eliminating the
- backup file altogether.
-
- A --bb flag will be ignored if input is from standard input or goes to standard output, or if the --hhttmmll flag
- is set.
-
- In particular, if you want to use both the --bb flag and the --ppbbpp (--perl-best-practices) flag, then you must
- put a --nnsstt flag after the --ppbbpp flag because it contains a --sstt flag as one of its components, which means
- that output will go to the standard output stream.
-
- --bbeexxtt=ext, ----bbaacckkuupp--ffiillee--eexxtteennssiioonn=ext
- This parameter serves two purposes: (1) to change the extension of the backup file to be something other
- than the default _._b_a_k, and (2) to indicate that no backup file should be saved.
-
- To change the default extension to something other than _._b_a_k see "Specifying File Extensions".
-
- 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.
-
- To indicate that the backup should be deleted include one forward slash, //, 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).
-
- Here are some examples:
-
- Parameter Extension Backup File Treatment
- <-bext=bak> F<.bak> Keep (same as the default behavior)
- <-bext='/'> F<.bak> Delete if no errors
- <-bext='/backup'> F<.backup> Delete if no errors
- <-bext='original/'> F<.original> Delete if no errors
-
- --ww, ----wwaarrnniinngg--oouuttppuutt
- Setting --ww 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, --nnww or ----nnoowwaarrnniinngg--oouuttppuutt, is not to include these warnings.
-
- --qq, ----qquuiieett
- Deactivate error messages (for running under an editor).
-
- For example, if you use a vi-style editor, such as vim, you may execute perltidy as a filter from within the
- editor using something like
-
- :n1,n2!perltidy -q
-
- where "n1,n2" represents the selected text. Without the --qq flag, any error message may mess up your screen,
- so be prepared to use your "undo" key.
-
- --lloogg, ----llooggffiillee
- Save the _._L_O_G file, which has many useful diagnostics. Perltidy always creates a _._L_O_G file, but by default
- it is deleted unless a program bug is suspected. Setting the --lloogg flag forces the log file to be saved.
-
- --gg==nn, ----llooggffiillee--ggaapp==nn
- Set maximum interval between input code lines in the logfile. This purpose of this flag is to assist in
- debugging nesting errors. The value of "n" is optional. If you set the flag --gg without the value of "n",
- it will be taken to be 1, meaning that every line will be written to the log file. This can be helpful if
- you are looking for a brace, paren, or bracket nesting error.
-
- Setting --gg also causes the logfile to be saved, so it is not necessary to also include --lloogg.
-
- If no --gg flag is given, a value of 50 will be used, meaning that at least every 50th line will be recorded
- in the logfile. This helps prevent excessively long log files.
-
- Setting a negative value of "n" is the same as not setting --gg at all.
-
- --nnpprroo ----nnoopprrooffiillee
- Ignore any _._p_e_r_l_t_i_d_y_r_c command file. Normally, perltidy looks first in your current directory for a
- _._p_e_r_l_t_i_d_y_r_c file of parameters. (The format is described below). If it finds one, it applies those options
- to the initial default values, and then it applies any that have been defined on the command line. If no
- _._p_e_r_l_t_i_d_y_r_c file is found, it looks for one in your home directory.
-
- If you set the --nnpprroo flag, perltidy will not look for this file.
-
- --pprroo==ffiilleennaammee or ----pprrooffiillee==ffiilleennaammee
- 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
- '=' sign. For example, the line
-
- perltidy -pro=testcfg
-
- would cause file _t_e_s_t_c_f_g to be used instead of the default _._p_e_r_l_t_i_d_y_r_c.
-
- A pathname begins with three dots, e.g. ".../.perltidyrc", 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.
-
- --oopptt, ----sshhooww--ooppttiioonnss
- Write a list of all options used to the _._L_O_G file. Please see ----dduummpp--ooppttiioonnss for a simpler way to do this.
-
- --ff, ----ffoorrccee--rreeaadd--bbiinnaarryy
- 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.
-
- --aasstt, ----aasssseerrtt--ttiiddyy
- 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.
- Note: you will not see this message if you have error messages turned off with the -quiet flag.
-
- --aassuu, ----aasssseerrtt--uunnttiiddyy
- 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.
-
- --ssaall==ss, ----ssuubb--aalliiaass--lliisstt==ss
- This flag causes one or more words to be treated the same as if they were the keyword 'sub'. The string ss
- contains one or more alias words, separated by spaces or commas.
-
- For example,
-
- perltidy -sal='method fun _sub M4'
-
- 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.
-
- Note that several other parameters accept a list of keywords, including 'sub' (see "Specifying Block
- Types"). You do not need to include any sub aliases in these lists. Just include keyword 'sub' if you wish,
- and all aliases are automatically included.
-
-FFOORRMMAATTTTIINNGG OOPPTTIIOONNSS
- BBaassiicc OOppttiioonnss
- ----nnoottiiddyy
- 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 _._p_e_r_l_t_i_d_y_r_c files to avoid unwanted code tidying. See also "Skipping Selected
- Sections of Code" for a way to avoid tidying specific sections of code.
-
- --ii==nn, ----iinnddeenntt--ccoolluummnnss==nn
- Use n columns per indentation level (default n=4).
-
- --ll==nn, ----mmaaxxiimmuumm--lliinnee--lleennggtthh==nn
- The default maximum line length is n=80 characters. Perltidy will try to find line break points to keep
- lines below this length. However, long quotes and side comments may cause lines to exceed this length.
-
- The default length of 80 comes from the past when this was the standard CRT screen width. Many programmers
- prefer to increase this to something like 120.
-
- Setting --ll==00 is equivalent to setting --ll==((aa vveerryy llaarrggee nnuummbbeerr)). But this is not recommended because, for
- example, a very long list will be formatted in a single long line.
-
- --vvmmllll, ----vvaarriiaabbllee--mmaaxxiimmuumm--lliinnee--lleennggtthh
- A problem arises using a fixed maximum line length with very deeply nested code and data structures because
- eventually the amount of leading whitespace used for indicating indentation takes up most or all of the
- available line width, leaving little or no space for the actual code or data. One solution is to use a vary
- long line length. Another solution is to use the --vvmmllll flag, which basically tells perltidy to ignore
- leading whitespace when measuring the line length.
-
- To be precise, when the --vvmmllll parameter is set, the maximum line length of a line of code will be M+L*I,
- where
-
- M is the value of --maximum-line-length=M (-l=M), default 80,
- I is the value of --indent-columns=I (-i=I), default 4,
- L is the indentation level of the line of code
-
- When this flag is set, the choice of breakpoints for a block of code should be essentially independent of
- its nesting depth. However, the absolute line lengths, including leading whitespace, can still be
- arbitrarily large. This problem can be avoided by including the next parameter.
-
- The default is not to do this (--nnvvmmllll).
-
- --wwcc==nn, ----wwhhiitteessppaaccee--ccyyccllee==nn
- This flag also addresses problems with very deeply nested code and data structures. When the nesting depth
- exceeds the value nn the leading whitespace will be reduced and start at a depth of 1 again. The result is
- that blocks of code will shift back to the left rather than moving arbitrarily far to the right. This
- occurs cyclically to any depth.
-
- For example if one level of indentation equals 4 spaces (--ii==44, the default), and one uses --wwcc==1155, then if
- the leading whitespace on a line exceeds about 4*15=60 spaces it will be reduced back to 4*1=4 spaces and
- continue increasing from there. If the whitespace never exceeds this limit the formatting remains
- unchanged.
-
- The combination of --vvmmllll and --wwcc==nn provides a solution to the problem of displaying arbitrarily deep data
- structures and code in a finite window, although --wwcc==nn may of course be used without --vvmmllll.
-
- The default is not to use this, which can also be indicated using --wwcc==00.
-
- TTaabbss
- Using tab characters will almost certainly lead to future portability and maintenance problems, so the
- default and recommendation is not to use them. For those who prefer tabs, however, there are two different
- options.
-
- Except for possibly introducing tab indentation characters, as outlined below, perltidy does not introduce
- any tab characters into your file, and it removes any tabs from the code (unless requested not to do so with
- --ffwwss). If you have any tabs in your comments, quotes, or here-documents, they will remain.
-
- --eett==nn, ----eennttaabb--lleeaaddiinngg--wwhhiitteessppaaccee
- This flag causes each nn initial space characters to be replaced by one tab character.
-
- The value of the integer nn can be any value but can be coordinated with the number of spaces used for
- intentation. For example, --eett==44 --ccii==44 --ii==44 will produce one tab for each indentation level and and one
- for each continuation indentation level. You may want to coordinate the value of nn with what your
- display software assumes for the spacing of a tab.
-
- --tt, ----ttaabbss
- 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 --llpp option. This flag is retained for
- backwards compatibility, but if you use tabs, the --eett==nn flag is recommended.
-
- --ddtt==nn, ----ddeeffaauulltt--ttaabbssiizzee==nn
- 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 nn corresponding to each leading tab of the input stream may be specified with --ddtt==nn. The
- default is nn==88.
-
- This flag has no effect if a tab scheme is specified for the output stream, because then the input
- stream is assumed to use the same tab scheme and indentation spaces as for the output stream (any other
- assumption would lead to unstable editing).
-
- --xxss, ----eexxtteennddeedd--ssyynnttaaxx
- 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.
-
- For example, without this flag a structure such as the following would generate a syntax error and the
- braces would not be balanced:
-
- method deposit( Num $amount) {
- $self->balance( $self->balance + $amount );
- }
-
- For one of the extensions, module Switch::Plain, colons are marked as labels. If you use this module, you
- may want to also use the ----nnoooouuttddeenntt--llaabbeellss flag to prevent lines such as 'default:' from being outdented.
-
- This flag is enabled by default but it can be deactivated with --nnxxss. Probably the only reason to deactivate
- this flag is to generate more diagnostic messages when debugging a script.
-
- For another method of handling extended syntax see the section "Skipping Selected Sections of Code".
-
- --iioo, ----iinnddeenntt--oonnllyy
- 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 to the indentation and to the number of blank lines.
- And any flags controlling whitespace and newlines will be ignored. You might want to use this if you are
- perfectly happy with your whitespace and line breaks, and merely want perltidy to handle the indentation.
- (This also speeds up perltidy by well over a factor of two, so it might be useful when perltidy is merely
- being used to help find a brace error in a large script).
-
- Setting this flag is equivalent to setting ----ffrreeeezzee--nneewwlliinneess and ----ffrreeeezzee--wwhhiitteessppaaccee.
-
- If you also want to keep your existing blank lines exactly as they are, you can add ----ffrreeeezzee--bbllaannkk--lliinneess.
-
- With this option perltidy is still free to modify the indenting (and outdenting) of code and comments as it
- normally would. If you also want to prevent long comment lines from being outdented, you can add either
- --nnoollll or --ll==00.
-
- Setting this flag will prevent perltidy from doing any special operations on closing side comments. You may
- still delete all side comments however when this flag is in effect.
-
- --eenncc==ss, ----cchhaarraacctteerr--eennccooddiinngg==ss
- This flag indicates the character encoding, if any, of the input data stream. Perltidy does not look for
- the encoding directives in the soure stream, such as uussee uuttff88, and instead relies on this flag to determine
- the encoding. (Note that perltidy often works on snippets of code rather than complete files so it cannot
- rely on uussee uuttff88 directives).
-
- The possible values for ss are (1) the name of an encoding recognized by the Encode.pm module, (2) nnoonnee if no
- encoding is used, or (3) <guess> if perltidy should guess.
-
- For example, the value uuttff88 causes the stream to be read and written as UTF-8. If the input stream cannot
- be decoded with a specified encoding then processing is not done.
-
- The value nnoonnee causes the stream to be processed without special encoding assumptions. This is appropriate
- for files which are written in single-byte character encodings such as latin-1.
-
- The value gguueessss tells perltidy to guess between either utf8 encoding or no encoding (meaning one character
- per byte). The guess uses the Encode::Guess module and this restricted range of guesses covers the most
- common cases. Testing showed that considering any greater number of encodings as guess suspects is too
- risky.
-
- The current default is gguueessss.
-
- The abbreviations --uuttff88 or --UUTTFF88 are equivalent to --eenncc==uuttff88, and the abbreviation --gguueessss is equivalent to
- <-enc=guess>. So to process a file named ffiillee..ppll which is encoded in UTF-8 you can use:
-
- perltidy -utf8 file.pl
-
- or
- perltidy -guess file.pl
-
- To process a file in eeuucc--jjpp you could use
-
- perltidy -enc=euc-jp file.pl
-
- A perltidy output file is unencoded if the input file is unencoded, and otherwise it is encoded as uuttff88,
- even if the input encoding was not uuttff88.
-
- --ggccss, ----uussee--uunniiccooddee--ggccssttrriinngg
- This flag controls whether or not perltidy may use module Unicode::GCString to obtain accurate display
- widths of wide characters. The default is ----nnoouussee--uunniiccooddee--ggccssttrriinngg.
-
- If this flag is set, and text is encoded, perltidy will look for the module Unicode::GCString and, if found,
- will use it to obtain character display widths. This can improve displayed vertical alignment for files
- with wide characters. It is a nice feature but it is off by default to avoid conflicting formatting when
- there are multiple developers. Perltidy installation does not require Unicode::GCString, so users wanting
- to use this feature need set this flag and also to install Unicode::GCString separately.
-
- If this flag is set and perltidy does not find module Unicode::GCString, a warning message will be produced
- and processing will continue but without the potential benefit provided by the module.
-
- Also note that actual vertical alignment depends upon the fonts used by the text display software, so
- vertical alignment may not be optimal even when Unicode::GCString is used.
-
- --oollee==ss, ----oouuttppuutt--lliinnee--eennddiinngg==ss
- where s="win", "dos", "unix", or "mac". 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 "win"
- and "dos" flags have an identical result.
-
- --ppllee, ----pprreesseerrvvee--lliinnee--eennddiinnggss
- This flag tells perltidy to write its output files with the same line endings as the input file, if
- possible. It should work for ddooss, uunniixx, and mmaacc line endings. It will only work if perltidy 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.
-
- --aattnnll, ----aadddd--tteerrmmiinnaall--nneewwlliinnee
- This flag, which is enabled by default, allows perltidy to terminate the last line of the output stream with
- a newline character, regardless of whether or not the input stream was terminated with a newline character.
- If this flag is negated, with --nnaattnnll, then perltidy will add a terminal newline to the the output stream
- only if the input stream is terminated with a newline.
-
- Negating this flag may be useful for manipulating one-line scripts intended for use on a command line.
-
- --iitt==nn, ----iitteerraattiioonnss==nn
- This flag causes perltidy to do nn 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 nn==11 should be satisfactory. However nn==22 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 nn
- 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. See the next item for a simplified iteration control.
-
- This flag has no effect when perltidy is used to generate html.
-
- --ccoonnvv, ----ccoonnvveerrggee
- This flag is equivalent to --iitt==44 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 iteration limit since perltidy will check for convergence and stop iterating as soon as possible. The
- default is --nnccoonnvv (no convergence check). Using --ccoonnvv will approximately double run time since typically
- one extra iteration is required to verify convergence. No extra iterations are required if no new line
- breaks are made, and two extra iterations are occasionally needed when reformatting complex code structures,
- such as deeply nested ternary statements.
-
- CCooddee IInnddeennttaattiioonn CCoonnttrrooll
- --ccii==nn, ----ccoonnttiinnuuaattiioonn--iinnddeennttaattiioonn==nn
- Continuation indentation is extra indentation spaces applied when a long line is broken. The default is
- n=2, illustrated here:
-
- my $level = # -ci=2
- ( $max_index_to_go >= 0 ) ? $levels_to_go[0] : $last_output_level;
-
- The same example, with n=0, is a little harder to read:
-
- my $level = # -ci=0
- ( $max_index_to_go >= 0 ) ? $levels_to_go[0] : $last_output_level;
-
- The value given to --ccii is also used by some commands when a small space is required. Examples are commands
- for outdenting labels, --oollaa, and control keywords, --ookkww.
-
- When default values are not used, it is recommended that either
-
- (1) the value nn given with --ccii==nn be no more than about one-half of the number of spaces assigned to a full
- indentation level on the --ii==nn command, or
-
- (2) the flag --eexxtteennddeedd--ccoonnttiinnuuaattiioonn--iinnddeennttaattiioonn is used (see next section).
-
- --xxccii, ----eexxtteennddeedd--ccoonnttiinnuuaattiioonn--iinnddeennttaattiioonn
- This flag allows perltidy to use some improvements which have been made to its indentation model. One of the
- things it does is "extend" continuation indentation deeper into structures, hence the name. The improved
- indentation is particularly noticeable when the flags --ccii==nn and --ii==nn use the same value of nn. There are no
- significant disadvantages to using this flag, but to avoid disturbing existing formatting the default is not
- to use it, --nnxxccii.
-
- Please see the section "--ppbbpp, ----ppeerrll--bbeesstt--pprraaccttiicceess" for an example of how this flag can improve the
- formatting of ternary statements. It can also improve indentation of some multi-line qw lists as shown
- below.
-
- # perltidy
- foreach $color (
- qw(
- AntiqueWhite3 Bisque1 Bisque2 Bisque3 Bisque4
- SlateBlue3 RoyalBlue1 SteelBlue2 DeepSkyBlue3
- ),
- qw(
- LightBlue1 DarkSlateGray1 Aquamarine2 DarkSeaGreen2
- SeaGreen1 Yellow1 IndianRed1 IndianRed2 Tan1 Tan4
- )
- )
-
- # perltidy -xci
- foreach $color (
- qw(
- AntiqueWhite3 Bisque1 Bisque2 Bisque3 Bisque4
- SlateBlue3 RoyalBlue1 SteelBlue2 DeepSkyBlue3
- ),
- qw(
- LightBlue1 DarkSlateGray1 Aquamarine2 DarkSeaGreen2
- SeaGreen1 Yellow1 IndianRed1 IndianRed2 Tan1 Tan4
- )
- )
-
- --ssiill==nn ----ssttaarrttiinngg--iinnddeennttaattiioonn--lleevveell==nn
- 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.
-
- 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.
-
- If the default method does not work correctly, or you want to change the starting level, use --ssiill==nn, to
- force the starting level to be n.
-
- LLiisstt iinnddeennttaattiioonn using --llpp, ----lliinnee--uupp--ppaarreenntthheesseess
- By default, perltidy indents lists with 4 spaces, or whatever value is specified with --ii==nn. Here is a small
- list formatted in this way:
-
- # perltidy (default)
- @month_of_year = (
- 'Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun',
- 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'
- );
-
- Use the --llpp flag to add extra indentation to cause the data to begin past the opening parentheses of a sub
- call or list, or opening square bracket of an anonymous array, or opening curly brace of an anonymous hash.
- With this option, the above list would become:
-
- # perltidy -lp
- @month_of_year = (
- 'Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun',
- 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'
- );
-
- If the available line length (see --ll==nn ) does not permit this much space, perltidy will use less. For
- alternate placement of the closing paren, see the next section.
-
- This option has no effect on code BLOCKS, such as if/then/else blocks, which always use whatever is
- specified with --ii==nn.
-
- In situations where perltidy does not have complete freedom to choose line breaks it may temporarily revert
- to its default indentation method. This can occur for example if there are blank lines, block comments,
- multi-line quotes, or side comments between the opening and closing parens, braces, or brackets.
-
- In addition, any parameter which significantly restricts the ability of perltidy to choose newlines will
- conflict with --llpp and will cause --llpp to be deactivated. These include --iioo, --ffnnll, --nnaannll, and --nnddnnll. The
- reason is that the --llpp indentation style can require the careful coordination of an arbitrary number of
- break points in hierarchical lists, and these flags may prevent that.
-
- The --llpp option may not be used together with the --tt tabs option. It may, however, be used with the --eett==nn
- tab method.
-
- --llppxxll==ss, ----lliinnee--uupp--ppaarreenntthheesseess--eexxcclluussiioonn--lliisstt
- This is an experimental parameter; the details might change as experience with it is gained.
-
- The --llpp indentation style works well for some types of coding but can produce very long lines when variables
- have long names and/or containers are very deeply nested. The --llppxxll==ss flag is intended to help mitigate
- this problem by providing control over the containers to which the --llpp indentation style is applied. The
- --llpp flag by default is "greedy" and applies to as many containers as possible. This flag specifies a list
- of things which should nnoott be use --llpp indentation.
-
- This list is a string with space-separated items. Each item consists of up to three pieces of information
- in this order: (1) an optional letter code (2) a required container type, and (3) an optional numeric code.
-
- The only required piece of information is a container type, which is one of '(', '[', or '{'. For example
- the string
-
- -lpxl='[ {'
-
- means do NNOOTT include use -lp formatting within square-bracets or braces. The only unspecified container is
- '(', so this string means that only the contents within parens will use -lp indentation.
-
- An optional numeric code may follow any of the container types to further refine the selection based on
- container contents. The numeric codes are:
-
- '0' or blank: no check on contents
- '1' reject -lp unless the contents is a simple list without sublists
- '2' reject -lp unless the contents is a simple list without sublists, without
- code blocks, and without ternary operators
-
- For example,
-
- -lpxl = '[ { (2'
-
- means only apply -lp to parenthesized lists which do not contain any sublists, code blocks or ternary
- expressions.
-
- A third optional item of information which can be given for parens is an alphanumeric letter which is used
- to limit the selection further depending on the type of token immediately before the paren. The possible
- letters are currently 'k', 'K', 'f', 'F', 'w', and 'W', with these meanings:
-
- 'k' matches if the previous nonblank token is a perl builtin keyword (such as 'if', 'while'),
- 'K' matches if 'k' does not, meaning that the previous token is not a keyword.
- 'f' matches if the previous token is a function other than a keyword.
- 'F' matches if 'f' does not.
- 'w' matches if either 'k' or 'f' match.
- 'W' matches if 'w' does not.
-
- For example,
-
- -lpxl = '[ { F(2'
-
- means only apply -lp to parenthesized lists which follow a function call and which do not contain any
- sublists, code blocks or ternary expressions. The logic of writing these codes is somewhat counter-
- intuitive because they describe what is not getting the -lp indentation. So the 'F' indicates that non-
- function calls are not getting -lp, or in other words that function calls are getting the -lp indentation.
-
- --ccttii==nn, ----cclloossiinngg--ttookkeenn--iinnddeennttaattiioonn
- The --ccttii==nn flag controls the indentation of a line beginning with a ")", "]", or a non-block "}". Such a
- line receives:
-
- -cti = 0 no extra indentation (default)
- -cti = 1 extra indentation such that the closing token
- aligns with its opening token.
- -cti = 2 one extra indentation level if the line looks like:
- ); or ]; or };
- -cti = 3 one extra indentation level always
-
- The flags --ccttii==11 and --ccttii==22 work well with the --llpp flag (previous section).
-
- # perltidy -lp -cti=1
- @month_of_year = (
- 'Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun',
- 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'
- );
-
- # perltidy -lp -cti=2
- @month_of_year = (
- 'Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun',
- 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'
- );
-
- These flags are merely hints to the formatter and they may not always be followed. In particular, if -lp is
- not being used, the indentation for ccttii==11 is constrained to be no more than one indentation level.
-
- If desired, this control can be applied independently to each of the closing container token types. In
- fact, --ccttii==nn is merely an abbreviation for --ccppii==nn --ccssbbii==nn --ccbbii==nn, where: --ccppii or ----cclloossiinngg--ppaarreenn--iinnddeennttaattiioonn
- controls ))'s, --ccssbbii or ----cclloossiinngg--ssqquuaarree--bbrraacckkeett--iinnddeennttaattiioonn controls ]]'s, --ccbbii or
- ----cclloossiinngg--bbrraaccee--iinnddeennttaattiioonn controls non-block }}'s.
-
- --iiccpp, ----iinnddeenntt--cclloossiinngg--ppaarreenn
- The --iiccpp flag is equivalent to --ccttii==22, described in the previous section. The --nniiccpp flag is equivalent
- --ccttii==00. They are included for backwards compatibility.
-
- --iiccbb, ----iinnddeenntt--cclloossiinngg--bbrraaccee
- The --iiccbb option gives one extra level of indentation to a brace which terminates a code block . For
- example,
-
- if ($task) {
- yyy();
- } # -icb
- else {
- zzz();
- }
-
- The default is not to do this, indicated by --nniiccbb.
-
- --nniibb, ----nnoonn--iinnddeennttiinngg--bbrraacceess
- Normally, lines of code contained within a pair of block braces receive one additional level of indentation.
- This flag, which is enabled by default, causes perltidy to look for opening block braces which are followed
- by a special side comment. This special side comment is ##<<<<<< by default. If found, the code between this
- opening brace and its corresponding closing brace will not be given the normal extra indentation level. For
- example:
-
- { #<<< a closure to contain lexical vars
-
- my $var; # this line does not get one level of indentation
- ...
-
- }
-
- # this line does not 'see' $var;
-
- This can be useful, for example, when combining code from different files. Different sections of code can
- be placed within braces to keep their lexical variables from being visible to the end of the file. To keep
- the new braces from causing all of their contained code to be indented if you run perltidy, and possibly
- introducing new line breaks in long lines, you can mark the opening braces with this special side comment.
-
- Only the opening brace needs to be marked, since perltidy knows where the closing brace is. Braces
- contained within marked braces may also be marked as non-indenting.
-
- If your code happens to have some opening braces followed by '#<<<', and you don't want this behavior, you
- can use --nnnniibb to deactivate it. To make it easy to remember, the default string is the same as the string
- for starting a ffoorrmmaatt--sskkiippppiinngg section. There is no confusion because in that case it is for a block comment
- rather than a side-comment.
-
- The special side comment can be changed with the next parameter.
-
- --nniibbpp==ss, ----nnoonn--iinnddeennttiinngg--bbrraaccee--pprreeffiixx==ss
- The --nniibbpp==ssttrriinngg parameter may be used to change the marker for non-indenting braces. The default is
- equivalent to -nibp='#<<<'. The string that you enter must begin with a # and should be in quotes as
- necessary to get past the command shell of your system. This string is the leading text of a regex pattern
- that is constructed by appending pre-pending a '^' and appending a'\s', so you must also include backslashes
- for characters to be taken literally rather than as patterns.
-
- For example, to match the side comment '#++', the parameter would be
-
- -nibp='#\+\+'
-
- --oollqq, ----oouuttddeenntt--lloonngg--qquuootteess
- When --oollqq is set, lines which is a quoted string longer than the value mmaaxxiimmuumm--lliinnee--lleennggtthh will have their
- indentation removed to make them more readable. This is the default. To prevent such out-denting, use
- --nnoollqq or ----nnoooouuttddeenntt--lloonngg--lliinneess.
-
- --oollll, ----oouuttddeenntt--lloonngg--lliinneess
- This command is equivalent to ----oouuttddeenntt--lloonngg--qquuootteess and ----oouuttddeenntt--lloonngg--ccoommmmeennttss, and it is included for
- compatibility with previous versions of perltidy. The negation of this also works, --nnoollll or
- ----nnoooouuttddeenntt--lloonngg--lliinneess, and is equivalent to setting --nnoollqq and --nnoollcc.
-
- OOuuttddeennttiinngg LLaabbeellss:: --oollaa, ----oouuttddeenntt--llaabbeellss
- This command will cause labels to be outdented by 2 spaces (or whatever --ccii has been set to), if possible.
- This is the default. For example:
-
- my $i;
- LOOP: while ( $i = <FOTOS> ) {
- chomp($i);
- next unless $i;
- fixit($i);
- }
-
- Use --nnoollaa to not outdent labels.
-
- OOuuttddeennttiinngg KKeeyywwoorrddss
- --ookkww, ----oouuttddeenntt--kkeeyywwoorrddss
- The command --ookkww will cause certain leading control keywords to be outdented by 2 spaces (or whatever
- --ccii has been set to), if possible. By default, these keywords are "redo", "next", "last", "goto", and
- "return". The intention is to make these control keywords easier to see. To change this list of
- keywords being outdented, see the next section.
-
- For example, using "perltidy -okw" on the previous example gives:
-
- my $i;
- LOOP: while ( $i = <FOTOS> ) {
- chomp($i);
- next unless $i;
- fixit($i);
- }
-
- The default is not to do this.
-
- SSppeecciiffyyiinngg OOuuttddeenntteedd KKeeyywwoorrddss:: --ookkwwll==ssttrriinngg, ----oouuttddeenntt--kkeeyywwoorrdd--lliisstt==ssttrriinngg
- This command can be used to change the keywords which are outdented with the --ookkww command. The
- parameter ssttrriinngg is a required list of perl keywords, which should be placed in quotes if there are more
- than one. By itself, it does not cause any outdenting to occur, so the --ookkww command is still required.
-
- For example, the commands "-okwl="next last redo goto" -okw" will cause those four keywords to be
- outdented. It is probably simplest to place any --ookkwwll command in a _._p_e_r_l_t_i_d_y_r_c file.
-
- WWhhiitteessppaaccee CCoonnttrrooll
- Whitespace refers to the blank space between variables, operators, and other code tokens.
-
- --ffwwss, ----ffrreeeezzee--wwhhiitteessppaaccee
- 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 the Comment Control section to be ignored.
-
- TTiigghhttnneessss ooff ccuurrllyy bbrraacceess,, ppaarreenntthheesseess,, aanndd ssqquuaarree bbrraacckkeettss
- Here the term "tightness" will mean the closeness with which pairs of enclosing tokens, such as parentheses,
- contain the quantities within. A numerical value of 0, 1, or 2 defines the tightness, with 0 being least
- tight and 2 being most tight. Spaces within containers are always symmetric, so if there is a space after a
- "(" then there will be a space before the corresponding ")".
-
- The --pptt==nn or ----ppaarreenn--ttiigghhttnneessss==nn parameter controls the space within parens. The example below shows the
- effect of the three possible values, 0, 1, and 2:
-
- if ( ( my $len_tab = length( $tabstr ) ) > 0 ) { # -pt=0
- if ( ( my $len_tab = length($tabstr) ) > 0 ) { # -pt=1 (default)
- if ((my $len_tab = length($tabstr)) > 0) { # -pt=2
-
- When n is 0, there is always a space to the right of a '(' and to the left of a ')'. For n=2 there is never
- a space. For n=1, the default, there is a space unless the quantity within the parens is a single token,
- such as an identifier or quoted string.
-
- Likewise, the parameter --ssbbtt==nn or ----ssqquuaarree--bbrraacckkeett--ttiigghhttnneessss==nn controls the space within square brackets, as
- illustrated below.
-
- $width = $col[ $j + $k ] - $col[ $j ]; # -sbt=0
- $width = $col[ $j + $k ] - $col[$j]; # -sbt=1 (default)
- $width = $col[$j + $k] - $col[$j]; # -sbt=2
-
- Curly braces which do not contain code blocks are controlled by the parameter --bbtt==nn or ----bbrraaccee--ttiigghhttnneessss==nn.
-
- $obj->{ $parsed_sql->{ 'table' }[0] }; # -bt=0
- $obj->{ $parsed_sql->{'table'}[0] }; # -bt=1 (default)
- $obj->{$parsed_sql->{'table'}[0]}; # -bt=2
-
- And finally, curly braces which contain blocks of code are controlled by the parameter --bbbbtt==nn or
- ----bblloocckk--bbrraaccee--ttiigghhttnneessss==nn as illustrated in the example below.
-
- %bf = map { $_ => -M $_ } grep { /\.deb$/ } dirents '.'; # -bbt=0 (default)
- %bf = map { $_ => -M $_ } grep {/\.deb$/} dirents '.'; # -bbt=1
- %bf = map {$_ => -M $_} grep {/\.deb$/} dirents '.'; # -bbt=2
-
- To simplify input in the case that all of the tightness flags have the same value <n>, the parameter
- <-act=n> or ----aallll--ccoonnttaaiinneerrss--ttiigghhttnneessss==nn is an abbreviation for the combination <-pt=n -sbt=n -bt=n -bbt=n>.
-
- --ttssoo, ----ttiigghhtt--sseeccrreett--ooppeerraattoorrss
- The flag --ttssoo causes certain perl token sequences (secret operators) which might be considered to be a
- single operator to be formatted "tightly" (without spaces). The operators currently modified by this flag
- are:
-
- 0+ +0 ()x!! ~~<> ,=> =( )=
-
- For example the sequence 00 ++, which converts a string to a number, would be formatted without a space: 00++
- when the --ttssoo flag is set. This flag is off by default.
-
- --ssttss, ----ssppaaccee--tteerrmmiinnaall--sseemmiiccoolloonn
- Some programmers prefer a space before all terminal semicolons. The default is for no such space, and is
- indicated with --nnssttss or ----nnoossppaaccee--tteerrmmiinnaall--sseemmiiccoolloonn.
-
- $i = 1 ; # -sts
- $i = 1; # -nsts (default)
-
- --ssffss, ----ssppaaccee--ffoorr--sseemmiiccoolloonn
- Semicolons within ffoorr 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 --nnssffss or
- ----nnoossppaaccee--ffoorr--sseemmiiccoolloonn to deactivate it.
-
- for ( @a = @$ap, $u = shift @a ; @a ; $u = $v ) { # -sfs (default)
- for ( @a = @$ap, $u = shift @a; @a; $u = $v ) { # -nsfs
-
- --aasscc, ----aadddd--sseemmiiccoolloonnss
- Setting --aasscc 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 --nnaasscc or
- ----nnooaadddd--sseemmiiccoolloonnss.
-
- --ddssmm, ----ddeelleettee--sseemmiiccoolloonnss
- Setting --ddssmm allows perltidy to delete extra semicolons which are simply empty statements. This is the
- default, and may be deactivated with --nnddssmm or ----nnooddeelleettee--sseemmiiccoolloonnss. (Such semicolons are not deleted,
- however, if they would promote a side comment to a block comment).
-
- --aawwss, ----aadddd--wwhhiitteessppaaccee
- Setting this option allows perltidy to add certain whitespace to improve code readability. This is the
- default. If you do not want any whitespace added, but are willing to have some whitespace deleted, use
- --nnaawwss. (Use --ffwwss to leave whitespace completely unchanged).
-
- --ddwwss, ----ddeelleettee--oolldd--wwhhiitteessppaaccee
- 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 --nnddwwss or ----nnooddeelleettee--oolldd--wwhhiitteessppaaccee.
-
- DDeettaaiilleedd wwhhiitteessppaaccee ccoonnttrroollss aarroouunndd ttookkeennss
- For those who want more detailed control over the whitespace around tokens, there are four parameters which
- can directly modify the default whitespace rules built into perltidy for any token. They are:
-
- --wwllss==ss or ----wwaanntt--lleefftt--ssppaaccee==ss,
-
- --nnwwllss==ss or ----nnoowwaanntt--lleefftt--ssppaaccee==ss,
-
- --wwrrss==ss or ----wwaanntt--rriigghhtt--ssppaaccee==ss,
-
- --nnwwrrss==ss or ----nnoowwaanntt--rriigghhtt--ssppaaccee==ss.
-
- These parameters are each followed by a quoted string, ss, containing a list of token types. No more than
- one of each of these parameters should be specified, because repeating a command-line parameter always
- overwrites the previous one before perltidy ever sees it.
-
- To illustrate how these are used, suppose it is desired that there be no space on either side of the token
- types == ++ -- // **. The following two parameters would specify this desire:
-
- -nwls="= + - / *" -nwrs="= + - / *"
-
- (Note that the token types are in quotes, and that they are separated by spaces). With these modified
- whitespace rules, the following line of math:
-
- $root = -$b + sqrt( $b * $b - 4. * $a * $c ) / ( 2. * $a );
-
- becomes this:
-
- $root=-$b+sqrt( $b*$b-4.*$a*$c )/( 2.*$a );
-
- These parameters should be considered to be hints to perltidy rather than fixed rules, because perltidy must
- try to resolve conflicts that arise between them and all of the other rules that it uses. One conflict that
- can arise is if, between two tokens, the left token wants a space and the right one doesn't. In this case,
- the token not wanting a space takes priority.
-
- 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 ----dduummpp--ttookkeenn--ttyyppeess. Also try the --DD flag on a short snippet of code and look at the
- .DEBUG file to see the tokenization.
-
- WWAARRNNIINNGG Be sure to put these tokens in quotes to avoid having them misinterpreted by your command shell.
-
- NNoottee11:: PPeerrllttiiddyy ddooeess aallwwaayyss ffoollllooww wwhhiitteessppaaccee ccoonnttrroollss
- The various parameters controlling whitespace within a program are requests which perltidy follows as well
- as possible, but there are a number of situations where changing whitespace could change program behavior
- and is not done. Some of these are obvious; for example, we should not remove the space between the two
- plus symbols in '$x+ +$y' to avoid creating a '++' operator. Some are more subtle and involve the whitespace
- around bareword symbols and locations of possible filehandles. For example, consider the problem of
- formatting the following subroutine:
-
- sub print_div {
- my ($x,$y)=@_;
- print $x/$y;
- }
-
- Suppose the user requests that / signs have a space to the left but not to the right. Perltidy will refuse
- to do this, but if this were done the result would be
-
- sub print_div {
- my ($x,$y)=@_;
- print $x /$y;
- }
-
- If formatted in this way, the program will not run (at least with recent versions of perl) because the $x is
- taken to be a filehandle and / is assumed to start a quote. In a complex program, there might happen to be a
- / which terminates the multiline quote without a syntax error, allowing the program to run, but not as
- intended.
-
- Related issues arise with other binary operator symbols, such as + and -, and in older versions of perl
- there could be problems with ternary operators. So to avoid changing program behavior, perltidy has the
- simple rule that whitespace around possible filehandles is left unchanged. Likewise, whitespace around
- barewords is left unchanged. The reason is that if the barewords are defined in other modules, or in code
- that has not even been written yet, perltidy will not have seen their prototypes and must treat them
- cautiously.
-
- In perltidy this is implemented in the tokenizer by marking token following a pprriinntt keyword as a special
- type ZZ. When formatting is being done, whitespace following this token type is generally left unchanged as
- a precaution against changing program behavior. This is excessively conservative but simple and easy to
- implement. Keywords which are treated similarly to pprriinntt include pprriinnttff, ssoorrtt, eexxeecc, ssyysstteemm. Changes in
- spacing around parameters following these keywords may have to be made manually. For example, the space, or
- lack of space, after the parameter $foo in the following line will be unchanged in formatting.
-
- system($foo );
- system($foo);
-
- To find if a token is of type ZZ you can use ppeerrllttiiddyy --DDEEBBUUGG. For the first line above the result is
-
- 1: system($foo );
- 1: kkkkkk{ZZZZb};
-
- which shows that ssyysstteemm is type kk (keyword) and $foo is type ZZ.
-
- NNoottee22:: PPeerrllttiiddyy''ss wwhhiitteessppaaccee rruulleess aarree nnoott ppeerrffeecctt
- Despite these precautions, it is still possible to introduce syntax errors with some asymmetric whitespace
- rules, particularly when call parameters are not placed in containing parens or braces. For example, the
- following two lines will be parsed by perl without a syntax error:
-
- # original programming, syntax ok
- my @newkeys = map $_-$nrecs+@data, @oldkeys;
-
- # perltidy default, syntax ok
- my @newkeys = map $_ - $nrecs + @data, @oldkeys;
-
- But the following will give a syntax error:
-
- # perltidy -nwrs='-'
- my @newkeys = map $_ -$nrecs + @data, @oldkeys;
-
- For another example, the following two lines will be parsed without syntax error:
-
- # original programming, syntax ok
- for my $severity ( reverse $SEVERITY_LOWEST+1 .. $SEVERITY_HIGHEST ) { ... }
-
- # perltidy default, syntax ok
- for my $severity ( reverse $SEVERITY_LOWEST + 1 .. $SEVERITY_HIGHEST ) { ... }
-
- But the following will give a syntax error:
-
- # perltidy -nwrs='+', syntax error:
- for my $severity ( reverse $SEVERITY_LOWEST +1 .. $SEVERITY_HIGHEST ) { ... }
-
- To avoid subtle parsing problems like this, it is best to avoid spacing a binary operator asymetrically with
- a space on the left but not on the right.
-
- SSppaaccee bbeettwweeeenn ssppeecciiffiicc kkeeyywwoorrddss aanndd ooppeenniinngg ppaarreenn
- When an opening paren follows a Perl keyword, no space is introduced after the keyword, unless it is (by
- default) one of these:
-
- my local our and or xor eq ne if else elsif until unless
- while for foreach return switch case given when
-
- These defaults can be modified with two commands:
-
- --ssaakk==ss or ----ssppaaccee--aafftteerr--kkeeyywwoorrdd==ss adds keywords.
-
- --nnssaakk==ss or ----nnoossppaaccee--aafftteerr--kkeeyywwoorrdd==ss removes keywords.
-
- where ss is a list of keywords (in quotes if necessary). For example,
-
- my ( $a, $b, $c ) = @_; # default
- my( $a, $b, $c ) = @_; # -nsak="my local our"
-
- The abbreviation --nnssaakk==''**'' is equivalent to including all of the keywords in the above list.
-
- When both --nnssaakk==ss and --ssaakk==ss commands are included, the --nnssaakk==ss command is executed first. For example, to
- have space after only the keywords (my, local, our) you could use --nnssaakk==""**"" --ssaakk==""mmyy llooccaall oouurr"".
-
- To put a space after all keywords, see the next item.
-
- SSppaaccee bbeettwweeeenn aallll kkeeyywwoorrddss aanndd ooppeenniinngg ppaarreennss
- When an opening paren follows a function or keyword, no space is introduced after the keyword except for the
- keywords noted in the previous item. To always put a space between a function or keyword and its opening
- paren, use the command:
-
- --sskkpp or ----ssppaaccee--kkeeyywwoorrdd--ppaarreenn
-
- You may also want to use the flag --ssffpp (next item) too.
-
- SSppaaccee bbeettwweeeenn aallll ffuunnccttiioonn nnaammeess aanndd ooppeenniinngg ppaarreennss
- When an opening paren follows a function the default and recommended formatting is not to introduce a space.
- To cause a space to be introduced use:
-
- --ssffpp or ----ssppaaccee--ffuunnccttiioonn--ppaarreenn
-
- myfunc( $a, $b, $c ); # default
- myfunc ( $a, $b, $c ); # -sfp
-
- You will probably also want to use the flag --sskkpp (previous item) too.
-
- The reason this is not recommended is that spacing a function paren can make a program vulnerable to parsing
- problems by Perl. For example, the following two-line program will run as written but will have a syntax
- error if reformatted with -sfp:
-
- if ( -e filename() ) { print "I'm here\n"; }
- sub filename { return $0 }
-
- In this particular case the syntax error can be removed if the line order is reversed, so that Perl parses
- 'sub filename' first.
-
- --ffppvvaa or ----ffuunnccttiioonn--ppaarreenn--vveerrttiiccaall--aalliiggnnmmeenntt
- A side-effect of using the --ssffpp flag is that the parens may become vertically aligned. For example,
-
- # perltidy -sfp
- myfun ( $aaa, $b, $cc );
- mylongfun ( $a, $b, $c );
-
- This is the default behavior. To prevent this alignment use --nnffppvvaa:
-
- # perltidy -sfp -nfpva
- myfun ( $aaa, $b, $cc );
- mylongfun ( $a, $b, $c );
-
- --sspppp==nn or ----ssppaaccee--pprroottoottyyppee--ppaarreenn==nn
- 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.
-
- sub usage();
-
- This integer nn may have the value 0, 1, or 2 as follows:
-
- -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
-
- The default is --sspppp==11, 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:
-
- sub usage(); # n=0 [no space]
- sub usage(); # n=1 [default; follows input]
- sub usage (); # n=2 [space]
-
- --kkppiitt==nn or ----kkeeyywwoorrdd--ppaarreenn--iinnnneerr--ttiigghhttnneessss==nn
- The space inside of an opening paren, which itself follows a certain keyword, can be controlled by this
- parameter. The space on the inside of the corresponding closing paren will be treated in the same
- (balanced) manner. This parameter has precedence over any other paren spacing rules. The values of nn are
- as follows:
-
- -kpit=0 means always put a space (not tight)
- -kpit=1 means ignore this parameter [default]
- -kpit=2 means never put a space (tight)
-
- To illustrate, the following snippet is shown formatted in three ways:
-
- if ( seek( DATA, 0, 0 ) ) { ... } # perltidy (default)
- if (seek(DATA, 0, 0)) { ... } # perltidy -pt=2
- if ( seek(DATA, 0, 0) ) { ... } # perltidy -pt=2 -kpit=0
-
- In the second case the -pt=2 parameter makes all of the parens tight. In the third case the -kpit=0 flag
- causes the space within the 'if' parens to have a space, since 'if' is one of the keywords to which the
- -kpit flag applies by default. The remaining parens are still tight because of the -pt=2 parameter.
-
- The set of keywords to which this parameter applies are by default are:
-
- if elsif unless while until for foreach
-
- These can be changed with the parameter --kkppiittll==ss described in the next section.
-
- --kkppiittll==ssttrriinngg or ----kkeeyywwoorrdd--ppaarreenn--iinnnneerr--ttiigghhttnneessss==ssttrriinngg
- This command can be used to change the keywords to which the the --kkppiitt==nn command applies. The parameter
- ssttrriinngg is a required list either keywords or functions, which should be placed in quotes if there are more
- than one. By itself, this parameter does not cause any change in spacing, so the --kkppiitt==nn command is still
- required.
-
- For example, the commands "-kpitl="if else while" -kpit=2" will cause the just the spaces inside parens
- following 'if', 'else', and 'while' keywords to follow the tightness value indicated by the --kkppiitt==22 flag.
-
- --lloopp or ----llooggiiccaall--ppaaddddiinngg
- In the following example some extra space has been inserted on the second line between the two open parens.
- This extra space is called "logical padding" and is intended to help align similar things vertically in some
- logical or ternary expressions.
-
- # perltidy [default formatting]
- $same =
- ( ( $aP eq $bP )
- && ( $aS eq $bS )
- && ( $aT eq $bT )
- && ( $a->{'title'} eq $b->{'title'} )
- && ( $a->{'href'} eq $b->{'href'} ) );
-
- Note that this is considered to be a different operation from "vertical alignment" because space at just one
- line is being adjusted, whereas in "vertical alignment" the spaces at all lines are being adjusted. So it
- sort of a local version of vertical alignment.
-
- Here is an example involving a ternary operator:
-
- # perltidy [default formatting]
- $bits =
- $top > 0xffff ? 32
- : $top > 0xff ? 16
- : $top > 1 ? 8
- : 1;
-
- This behavior is controlled with the flag ----llooggiiccaall--ppaaddddiinngg, which is set 'on' by default. If it is not
- desired it can be turned off using ----nnoollooggiiccaall--ppaaddddiinngg or --nnlloopp. The above two examples become, with --nnlloopp:
-
- # perltidy -nlop
- $same =
- ( ( $aP eq $bP )
- && ( $aS eq $bS )
- && ( $aT eq $bT )
- && ( $a->{'title'} eq $b->{'title'} )
- && ( $a->{'href'} eq $b->{'href'} ) );
-
- # perltidy -nlop
- $bits =
- $top > 0xffff ? 32
- : $top > 0xff ? 16
- : $top > 1 ? 8
- : 1;
-
- TTrriimmmmiinngg wwhhiitteessppaaccee aarroouunndd ""qqww"" qquuootteess
- --ttqqww or ----ttrriimm--qqww provide the default behavior of trimming spaces around multi-line "qw" quotes and
- indenting them appropriately.
-
- --nnttqqww or ----nnoottrriimm--qqww cause leading and trailing whitespace around multi-line "qw" 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 "qw" quotes changes the syntax tree.
-
- --ssbbqq==nn or ----ssppaaccee--bbaacckkssllaasshh--qquuoottee==nn
- lines like
-
- $str1=\"string1";
- $str2=\'string2';
-
- can confuse syntax highlighters unless a space is included between the backslash and the single or double
- quotation mark.
-
- this can be controlled with the value of nn as follows:
-
- -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
-
- The default is --ssbbqq==11, meaning that a space will be used if there is one in the source code.
-
- TTrriimmmmiinngg ttrraaiilliinngg wwhhiitteessppaaccee ffrroomm lliinneess ooff PPOODD
- --ttrrpp or ----ttrriimm--ppoodd will remove trailing whitespace from lines of POD. The default is not to do this.
-
- CCoommmmeenntt CCoonnttrroollss
- Perltidy has a number of ways to control the appearance of both block comments and side comments. The term
- bblloocckk ccoommmmeenntt here refers to a full-line comment, whereas ssiiddee ccoommmmeenntt will refer to a comment which appears on
- a line to the right of some code.
-
- --iibbcc, ----iinnddeenntt--bblloocckk--ccoommmmeennttss
- 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 --nniibbcc to keep block comments left-justified. Here is an
- example:
-
- # this comment is indented (-ibc, default)
- if ($task) { yyy(); }
-
- The alternative is --nniibbcc:
-
- # this comment is not indented (-nibc)
- if ($task) { yyy(); }
-
- See also the next item, --iissbbcc, as well as --ssbbcc, for other ways to have some indented and some outdented
- block comments.
-
- --iissbbcc, ----iinnddeenntt--ssppaacceedd--bblloocckk--ccoommmmeennttss
- If there is no leading space on the line, then the comment will not be indented, and otherwise it may be.
-
- If both --iibbcc and --iissbbcc are set, then --iissbbcc takes priority.
-
- --oollcc, ----oouuttddeenntt--lloonngg--ccoommmmeennttss
- When --oollcc is set, lines which are full-line (block) comments longer than the value mmaaxxiimmuumm--lliinnee--lleennggtthh will
- have their indentation removed. This is the default; use --nnoollcc to prevent outdenting.
-
- --mmsscc==nn, ----mmiinniimmuumm--ssppaaccee--ttoo--ccoommmmeenntt==nn
- 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.
-
- --ffppsscc==nn, ----ffiixxeedd--ppoossiittiioonn--ssiiddee--ccoommmmeenntt==nn
- This parameter tells perltidy to line up side comments in column number nn whenever possible. The default,
- n=0, will not do this.
-
- --iissccll, ----iiggnnoorree--ssiiddee--ccoommmmeenntt--lleennggtthhss
- This parameter causes perltidy to ignore the length of side comments when setting line breaks. The default,
- --nniissccll, is to include the length of side comments when breaking lines to stay within the length prescribed
- by the --ll==nn maximum line length parameter. For example, the following long single line would remain intact
- with -l=80 and -iscl:
-
- perltidy -l=80 -iscl
- $vmsfile =~ s/;[\d\-]*$//; # Clip off version number; we can use a newer version as well
-
- whereas without the -iscl flag the line will be broken:
-
- perltidy -l=80
- $vmsfile =~ s/;[\d\-]*$//
- ; # Clip off version number; we can use a newer version as well
-
- --hhsscc, ----hhaannggiinngg--ssiiddee--ccoommmmeennttss
- By default, perltidy tries to identify and align "hanging side comments", which are something like this:
-
- my $IGNORE = 0; # This is a side comment
- # This is a hanging side comment
- # And so is this
-
- A comment is considered to be a hanging side comment if (1) it immediately follows a line with a side
- comment, or another hanging side comment, and (2) there is some leading whitespace on the line. To
- deactivate this feature, use --nnhhsscc or ----nnoohhaannggiinngg--ssiiddee--ccoommmmeennttss. If block comments are preceded by a blank
- line, or have no leading whitespace, they will not be mistaken as hanging side comments.
-
- CClloossiinngg SSiiddee CCoommmmeennttss
- A closing side comment is a special comment which perltidy can automatically create and place after the
- closing brace of a code block. They can be useful for code maintenance and debugging. The command --ccsscc (or
- ----cclloossiinngg--ssiiddee--ccoommmmeennttss) adds or updates closing side comments. For example, here is a small code snippet
-
- sub message {
- if ( !defined( $_[0] ) ) {
- print("Hello, World\n");
- }
- else {
- print( $_[0], "\n" );
- }
- }
-
- And here is the result of processing with "perltidy -csc":
-
- sub message {
- if ( !defined( $_[0] ) ) {
- print("Hello, World\n");
- }
- else {
- print( $_[0], "\n" );
- }
- } ## end sub message
-
- A closing side comment was added for "sub message" in this case, but not for the "if" and "else" blocks,
- because they were below the 6 line cutoff limit for adding closing side comments. This limit may be changed
- with the --ccssccii command, described below.
-
- The command --ddccsscc (or ----ddeelleettee--cclloossiinngg--ssiiddee--ccoommmmeennttss) reverses this process and removes these comments.
-
- Several commands are available to modify the behavior of these two basic commands, --ccsscc and --ddccsscc:
-
- --ccssccii==nn, or ----cclloossiinngg--ssiiddee--ccoommmmeenntt--iinntteerrvvaall==nn
- where "n" is the minimum number of lines that a block must have in order for a closing side comment to
- be added. The default value is "n=6". To illustrate:
-
- # perltidy -csci=2 -csc
- sub message {
- if ( !defined( $_[0] ) ) {
- print("Hello, World\n");
- } ## end if ( !defined( $_[0] ))
- else {
- print( $_[0], "\n" );
- } ## end else [ if ( !defined( $_[0] ))
- } ## end sub message
-
- Now the "if" and "else" blocks are commented. However, now this has become very cluttered.
-
- --ccssccpp==ssttrriinngg, or ----cclloossiinngg--ssiiddee--ccoommmmeenntt--pprreeffiixx==ssttrriinngg
- where string is the prefix used before the name of the block type. The default prefix, shown above, is
- "## end". This string will be added to closing side comments, and it will also be used to recognize
- them in 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.
-
- --ccssccll==ssttrriinngg, or ----cclloossiinngg--ssiiddee--ccoommmmeenntt--lliisstt
- where "string" 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 "if", "sub", and so on) will be tagged. The --ccssccll
- command changes the default list to be any selected block types; see "Specifying Block Types". For
- example, the following command requests that only "sub"'s, labels, "BEGIN", and "END" blocks be affected
- by any --ccsscc or --ddccsscc operation:
-
- -cscl="sub : BEGIN END"
-
- --ccsscctt==nn, or ----cclloossiinngg--ssiiddee--ccoommmmeenntt--mmaaxxiimmuumm--tteexxtt==nn
- The text appended to certain block types, such as an "if" block, is whatever lies between the keyword
- introducing the block, such as "if", and the opening brace. Since this might be too much text for a
- side comment, there needs to be a limit, and that is the purpose of this parameter. The default value
- is "n=20", meaning that no additional tokens will be appended to this text after its length reaches 20
- characters. Omitted text is indicated with "...". (Tokens, including sub names, are never truncated,
- however, so actual lengths may exceed this). To illustrate, in the above example, the appended text of
- the first block is " ( !defined( $_[0] )...". The existing limit of "n=20" caused this text to be
- truncated, as indicated by the "...". See the next flag for additional control of the abbreviated text.
-
- --ccssccbb, or ----cclloossiinngg--ssiiddee--ccoommmmeennttss--bbaallaanncceedd
- As discussed in the previous item, when the closing-side-comment-maximum-text limit is exceeded the
- comment text must be truncated. Older versions of perltidy terminated with three dots, and this can
- still be achieved with -ncscb:
-
- perltidy -csc -ncscb
- } ## end foreach my $foo (sort { $b cmp $a ...
-
- However this causes a problem with editors which cannot recognize comments or are not configured to do
- so because they cannot "bounce" around in the text correctly. The --ccssccbb flag has been added to help
- them by appending appropriate balancing structure:
-
- perltidy -csc -cscb
- } ## end foreach my $foo (sort { $b cmp $a ... })
-
- The default is --ccssccbb.
-
- --ccssccee==nn, or ----cclloossiinngg--ssiiddee--ccoommmmeenntt--eellssee--ffllaagg==nn
- The default, nn==00, places the text of the opening "if" statement after any terminal "else".
-
- If nn==22 is used, then each "elsif" is also given the text of the opening "if" statement. Also, an "else"
- will include the text of a preceding "elsif" statement. Note that this may result some long closing
- side comments.
-
- If nn==11 is used, the results will be the same as nn==22 whenever the resulting line length is less than the
- maximum allowed.
-
- --ccssccbb, or ----cclloossiinngg--ssiiddee--ccoommmmeennttss--bbaallaanncceedd
- 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 --ccssccbb flag is negated:
-
- perltidy -csc -ncscb
- } ## end foreach my $foo (sort { $b cmp $a ...
-
- This causes a problem with older editors which do not recognize comments because they cannot "bounce"
- around in the text correctly. The --ccssccbb flag tries to help them by appending appropriate terminal
- balancing structures:
-
- perltidy -csc -cscb
- } ## end foreach my $foo (sort { $b cmp $a ... })
-
- The default is --ccssccbb.
-
- --ccssccww, or ----cclloossiinngg--ssiiddee--ccoommmmeenntt--wwaarrnniinnggss
- This parameter is intended to help make the initial transition to the use of closing side comments. It
- causes two things to happen if a closing side comment replaces an existing, different closing side
- comment: first, an error message will be issued, and second, the original side comment will be placed
- alone on a new specially marked comment line for later attention.
-
- The intent is to avoid clobbering existing hand-written side comments which happen to match the pattern
- of closing side comments. This flag should only be needed on the first run with --ccsscc.
-
- IImmppoorrttaanntt NNootteess oonn CClloossiinngg SSiiddee CCoommmmeennttss::
-
- +o Closing side comments are only placed on lines terminated with a closing brace. Certain closing styles,
- such as the use of cuddled elses (--ccee), preclude the generation of some closing side comments.
-
- +o Please note that adding or deleting of closing side comments takes place only through the commands --ccsscc
- or --ddccsscc. The other commands, if used, merely modify the behavior of these two commands.
-
- +o It is recommended that the --ccssccww flag be used along with --ccsscc on the first use of perltidy on a given
- file. This will prevent loss of any existing side comment data which happens to have the csc prefix.
-
- +o Once you use --ccsscc, you should continue to use it so that any closing side comments remain correct as
- code changes. Otherwise, these comments will become incorrect as the code is updated.
-
- +o If you edit the closing side comments generated by perltidy, you must also change the prefix to be
- different from the closing side comment prefix. Otherwise, your edits will be lost when you rerun
- perltidy with --ccsscc. For example, you could simply change "## end" to be "## End", since the test is
- case sensitive. You may also want to use the --sssscc flag to keep these modified closing side comments
- spaced the same as actual closing side comments.
-
- +o Temporarily generating closing side comments is a useful technique for exploring and/or debugging a perl
- script, especially one written by someone else. You can always remove them with --ddccsscc.
-
- SSttaattiicc BBlloocckk CCoommmmeennttss
- Static block comments are block comments with a special leading pattern, "##" by default, which will be
- treated slightly differently from other block comments. They effectively behave as if they had glue along
- their left and top edges, because they stick to the left edge and previous line when there is no blank
- spaces in those places. This option is particularly useful for controlling how commented code is displayed.
-
- --ssbbcc, ----ssttaattiicc--bblloocckk--ccoommmmeennttss
- When --ssbbcc is used, a block comment with a special leading pattern, "##" by default, will be treated
- specially.
-
- Comments so identified are treated as follows:
-
- +o If there is no leading space on the line, then the comment will not be indented, and otherwise it
- may be,
-
- +o no new blank line will be inserted before such a comment, and
-
- +o such a comment will never become a hanging side comment.
-
- For example, assuming @month_of_year is left-adjusted:
-
- @month_of_year = ( # -sbc (default)
- 'Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct',
- ## 'Dec', 'Nov'
- 'Nov', 'Dec');
-
- Without this convention, the above code would become
-
- @month_of_year = ( # -nsbc
- 'Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct',
-
- ## 'Dec', 'Nov'
- 'Nov', 'Dec'
- );
-
- which is not as clear. The default is to use --ssbbcc. This may be deactivated with --nnssbbcc.
-
- --ssbbccpp==ssttrriinngg, ----ssttaattiicc--bblloocckk--ccoommmmeenntt--pprreeffiixx==ssttrriinngg
- This parameter defines the prefix used to identify static block comments when the --ssbbcc parameter is set.
- The default prefix is "##", corresponding to "-sbcp=##". The prefix is actually part of a perl pattern
- used to match lines and it must either begin with "#" or "^#". In the first case a prefix ^\s* will be
- added to match any leading whitespace, while in the second case the pattern will match only comments
- with no leading whitespace. For example, to identify all comments as static block comments, one would
- use "-sbcp=#". To identify all left-adjusted comments as static block comments, use "-sbcp='^#'".
-
- Please note that --ssbbccpp merely defines the pattern used to identify static block comments; it will not be
- used unless the switch --ssbbcc 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.
-
- A pattern which can be useful is:
-
- -sbcp=^#{2,}[^\s#]
-
- 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 '#'.
-
- --oossbbcc, ----oouuttddeenntt--ssttaattiicc--bblloocckk--ccoommmmeennttss
- The command --oossbbcc will cause static block comments to be outdented by 2 spaces (or whatever --ccii==nn has
- been set to), if possible.
-
- SSttaattiicc SSiiddee CCoommmmeennttss
- Static side comments are side comments with a special leading pattern. This option can be useful for
- controlling how commented code is displayed when it is a side comment.
-
- --sssscc, ----ssttaattiicc--ssiiddee--ccoommmmeennttss
- When --sssscc is used, a side comment with a static leading pattern, which is "##" by default, will be
- spaced only a single space from previous character, and it will not be vertically aligned with other
- side comments.
-
- The default is --nnsssscc.
-
- --ssssccpp==ssttrriinngg, ----ssttaattiicc--ssiiddee--ccoommmmeenntt--pprreeffiixx==ssttrriinngg
- This parameter defines the prefix used to identify static side comments when the --sssscc parameter is set.
- The default prefix is "##", corresponding to "-sscp=##".
-
- Please note that --ssssccpp merely defines the pattern used to identify static side comments; it will not be
- used unless the switch --sssscc is set. Also, note that this string is used in a perl regular expression
- which identifies these comments, so it must enable a valid regular expression to be formed.
-
- SSkkiippppiinngg SSeelleecctteedd SSeeccttiioonnss ooff CCooddee
- Selected lines of code may be passed verbatim to the output without any formatting by marking the starting and
- ending lines with special comments. There are two options for doing this. The first option is called
- ----ffoorrmmaatt--sskkiippppiinngg or --ffss, and the second option is called ----ccooddee--sskkiippppiinngg or --ccss.
-
- In both cases the lines of code will be output without any changes. The difference is that in ----ffoorrmmaatt--sskkiippppiinngg
- perltidy will still parse the marked lines of code and check for errors, whereas in ----ccooddee--sskkiippppiinngg perltidy
- will simply pass the lines to the output without any checking.
-
- Both of these features are enabled by default and are invoked with special comment markers. ----ffoorrmmaatt--sskkiippppiinngg
- uses starting and ending markers '#<<<' and '#>>>', like this:
-
- #<<< format skipping: do not let perltidy change my nice formatting
- my @list = (1,
- 1, 1,
- 1, 2, 1,
- 1, 3, 3, 1,
- 1, 4, 6, 4, 1,);
- #>>>
-
- ----ccooddee--sskkiippppiinngg uses starting and ending markers '#<<V' and '#>>V', like this:
-
- #<<V code skipping: perltidy will pass this verbatim without error checking
-
- token ident_digit {
- [ [ <?word> | _ | <?digit> ] <?ident_digit>
- | <''>
- ]
- };
-
- #>>V
-
- Additional text may appear on the special comment lines provided that it is separated from the marker by at
- least one space, as in the above examples.
-
- It is recommended to use ----ccooddee--sskkiippppiinngg only if you need to hide a block of an extended syntax which would
- produce errors if parsed by perltidy, and use ----ffoorrmmaatt--sskkiippppiinngg otherwise. This is because the
- ----ffoorrmmaatt--sskkiippppiinngg option provides the benefits of error checking, and there are essentially no limitations on
- which lines to which it can be applied. The ----ccooddee--sskkiippppiinngg option, on the other hand, does not do error
- checking and its use is more restrictive because the code which remains, after skipping the marked lines, must
- be syntactically correct code with balanced containers.
-
- These features should be used sparingly to avoid littering code with markers, but they can be helpful for
- working around occasional problems.
-
- Note that it may be possible to avoid the use of ----ffoorrmmaatt--sskkiippppiinngg for the specific case of a comma-separated
- list of values, as in the above example, by simply inserting a blank or comment somewhere between the opening
- and closing parens. See the section "Controlling List Formatting".
-
- The following sections describe the available controls for these options. They should not normally be needed.
-
- --ffss, ----ffoorrmmaatt--sskkiippppiinngg
- As explained above, 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 code between the comments is
- still checked for errors however. The default beginning marker is #<<< and the default ending marker is
- #>>>.
-
- Format skipping begins when a format skipping beginning comment is seen and continues until a format-
- skipping ending comment is found.
-
- This feature can be disabled with --nnffss. This should not normally be necessary.
-
- --ffssbb==ssttrriinngg, ----ffoorrmmaatt--sskkiippppiinngg--bbeeggiinn==ssttrriinngg
- This and the next parameter allow the special beginning and ending comments to be changed. However, it is
- recommended that they only be changed if there is a conflict between the default values and some other use.
- If they are used, it is recommended that they only be entered in a ..ppeerrllttiiddyyrrcc file, rather than on a
- command line. This is because properly escaping these parameters on a command line can be difficult.
-
- If changed comment markers do not appear to be working, use the --lloogg flag and examine the _._L_O_G file to see
- if and where they are being detected.
-
- The --ffssbb==ssttrriinngg 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 the command shell of your system. It is actually the leading text of a pattern that
- is constructed by appending a '\s', so you must also include backslashes for characters to be taken
- literally rather than as patterns.
-
- Some examples show how example strings become patterns:
-
- -fsb='#\{\{\{' becomes /^#\{\{\{\s/ which matches #{{{ but not #{{{{
- -fsb='#\*\*' becomes /^#\*\*\s/ which matches #** but not #***
- -fsb='#\*{2,}' becomes /^#\*{2,}\s/ which matches #** and #*****
-
- --ffssee==ssttrriinngg, ----ffoorrmmaatt--sskkiippppiinngg--eenndd==ssttrriinngg
- The --ffssee==ssttrriinngg is the corresponding parameter used to change the ending marker for format skipping. The
- default is equivalent to -fse='#<<<'.
-
- The beginning and ending strings may be the same, but it is preferable to make them different for clarity.
-
- --ccss, ----ccooddee--sskkiippppiinngg
- As explained above, this flag, which is enabled by default, causes any code between special beginning and
- ending comment markers to be directly passed to the output without any error checking or formatting.
- Essentially, perltidy treats it as if it were a block of arbitrary text. The default beginning marker is
- #<<V and the default ending marker is #>>V.
-
- This feature can be disabled with --nnccss. This should not normally be necessary.
-
- --ccssbb==ssttrriinngg, ----ccooddee--sskkiippppiinngg--bbeeggiinn==ssttrriinngg
- This may be used to change the beginning comment for a ----ccooddee--sskkiippppiinngg section, and its use is similar to
- the --ffssbb==ssttrriinngg. The default is equivalent to -csb='#<<V'.
-
- --ccssee==ssttrriinngg, ----ccooddee--sskkiippppiinngg--eenndd==ssttrriinngg
- This may be used to change the ending comment for a ----ccooddee--sskkiippppiinngg section, and its use is similar to the
- --ffssee==ssttrriinngg. The default is equivalent to -cse='#>>V'.
-
- LLiinnee BBrreeaakk CCoonnttrrooll
- The parameters in this section control breaks after non-blank lines of code. Blank lines are controlled
- separately by parameters in the section "Blank Line Control".
-
- --ffnnll, ----ffrreeeezzee--nneewwlliinneess
- If you do not want any changes to the line breaks within lines of code in your script, set --ffnnll, and they
- will remain fixed, and the rest of the commands in this section and sections "Controlling List Formatting",
- "Retaining or Ignoring Existing Line Breaks". You may want to use --nnoollll with this.
-
- Note: If you also want to keep your blank lines exactly as they are, you can use the --ffbbll flag which is
- described in the section "Blank Line Control".
-
- --ccee, ----ccuuddddlleedd--eellssee
- Enable the "cuddled else" style, in which "else" and "elsif" 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 --nnccee or
- ----nnooccuuddddlleedd--eellssee. Here is a comparison of the alternatives:
-
- # -ce
- if ($task) {
- yyy();
- } else {
- zzz();
- }
-
- # -nce (default)
- if ($task) {
- yyy();
- }
- else {
- zzz();
- }
-
- In this example the keyword eellssee is placed on the same line which begins with the preceding closing block
- brace and is followed by its own opening block brace on the same line. Other keywords and function names
- which are formatted with this "cuddled" style are eellssiiff, ccoonnttiinnuuee, ccaattcchh, ffiinnaallllyy.
-
- Other block types can be formatted by specifying their names on a separate parameter --ccbbll, described in a
- later section.
-
- 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 --ccbboo==nn discussed below. The default and
- recommended value of --ccbboo==11 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.
-
- So for example, the --ccee flag would not have any effect if the above snippet is rewritten as
-
- if ($task) { yyy() }
- else { zzz() }
-
- 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.
-
- 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.
-
- --ccbb, ----ccuuddddlleedd--bblloocckkss
- This flag is equivalent to --ccee.
-
- --ccbbll, ----ccuuddddlleedd--bblloocckk--lliisstt
- The built-in default cuddled block types are eellssee,, eellssiiff,, ccoonnttiinnuuee,, ccaattcchh,, ffiinnaallllyy.
-
- Additional block types to which the --ccuuddddlleedd--bblloocckkss style applies can be defined by this parameter. This
- parameter is a character string, giving a list of block types separated by commas or spaces. For example,
- to cuddle code blocks of type sort, map and grep, in addition to the default types, the string could be set
- to
-
- -cbl="sort map grep"
-
- or equivalently
-
- -cbl=sort,map,grep
-
- Note however that these particular block types are typically short so there might not be much opportunity
- for the cuddled format style.
-
- Using commas avoids the need to protect spaces with quotes.
-
- As a diagnostic check, the flag ----dduummpp--ccuuddddlleedd--bblloocckk--lliisstt or --ddccbbll can be used to view the hash of values
- that are generated by this flag.
-
- Finally, note that the --ccbbll flag by itself merely specifies which blocks are formatted with the cuddled
- format. It has no effect unless this formatting style is activated with --ccee.
-
- --ccbbllxx, ----ccuuddddlleedd--bblloocckk--lliisstt--eexxcclluussiivvee
- When cuddled else formatting is selected with --ccee, setting this flag causes perltidy to ignore its built-in
- defaults and rely exclusively on the block types specified on the --ccbbll flag described in the previous
- section. For example, to avoid using cuddled ccaattcchh and ffiinnaallllyy, which among in the defaults, the following
- set of parameters could be used:
-
- perltidy -ce -cbl='else elsif continue' -cblx
-
- --ccbboo==nn, ----ccuuddddlleedd--bbrreeaakk--ooppttiioonn==nn
- 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 "break" the block, meaning to cause it
- to span multiple lines. This parameter controls that decision. The options are:
-
- 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 [DEFAULT].
- cbo=2 Break open all blocks for maximal cuddled formatting.
-
- The default and recommended value is ccbboo==11. 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.
-
- The option ccbboo==00 can produce erratic cuddling if there are numerous one-line blocks.
-
- The option ccbboo==22 produces maximal cuddling but will not allow any short blocks.
-
- --bbll, ----ooppeenniinngg--bbrraaccee--oonn--nneeww--lliinnee
- Use the flag --bbll to place the opening brace on a new line:
-
- if ( $input_file eq '-' ) # -bl
- {
- important_function();
- }
-
- This flag applies to all structural blocks, including named sub's (unless the --ssbbll flag is set -- see next
- item).
-
- The default style, --nnbbll, places an opening brace on the same line as the keyword introducing it. For
- example,
-
- if ( $input_file eq '-' ) { # -nbl (default)
-
- --ssbbll, ----ooppeenniinngg--ssuubb--bbrraaccee--oonn--nneeww--lliinnee
- The flag --ssbbll can be used to override the value of --bbll for the opening braces of named sub's. For example,
-
- perltidy -sbl
-
- produces this result:
-
- sub message
- {
- if (!defined($_[0])) {
- print("Hello, World\n");
- }
- else {
- print($_[0], "\n");
- }
- }
-
- This flag is negated with --nnssbbll. If --ssbbll is not specified, the value of --bbll is used.
-
- --aassbbll, ----ooppeenniinngg--aannoonnyymmoouuss--ssuubb--bbrraaccee--oonn--nneeww--lliinnee
- The flag --aassbbll is like the --ssbbll flag except that it applies to anonymous sub's instead of named subs. For
- example
-
- perltidy -asbl
-
- produces this result:
-
- $a = sub
- {
- if ( !defined( $_[0] ) ) {
- print("Hello, World\n");
- }
- else {
- print( $_[0], "\n" );
- }
- };
-
- This flag is negated with --nnaassbbll, and the default is --nnaassbbll.
-
- --bbllii, ----bbrraaccee--lleefftt--aanndd--iinnddeenntt
- The flag --bbllii is the same as --bbll but in addition it causes one unit of continuation indentation ( see --ccii )
- to be placed before an opening and closing block braces.
-
- For example,
-
- if ( $input_file eq '-' ) # -bli
- {
- important_function();
- }
-
- By default, this extra indentation occurs for blocks of type: iiff, eellssiiff, eellssee, uunnlleessss, ffoorr, ffoorreeaacchh, ssuubb,
- wwhhiillee, uunnttiill, and also with a preceding label. The next item shows how to change this.
-
- --bblliill==ss, ----bbrraaccee--lleefftt--aanndd--iinnddeenntt--lliisstt==ss
- Use this parameter to change the types of block braces for which the --bbllii flag applies; see "Specifying
- Block Types". For example, --bblliill==''iiff eellssiiff eellssee'' would apply it to only "if/elsif/else" blocks.
-
- --bbaarr, ----ooppeenniinngg--bbrraaccee--aallwwaayyss--oonn--rriigghhtt
- The default style, --nnbbll 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:
-
- if ( $bigwasteofspace1 && $bigwasteofspace2
- || $bigwasteofspace3 && $bigwasteofspace4 )
- {
- big_waste_of_time();
- }
-
- To force the opening brace to always be on the right, use the --bbaarr flag. In this case, the above example
- becomes
-
- if ( $bigwasteofspace1 && $bigwasteofspace2
- || $bigwasteofspace3 && $bigwasteofspace4 ) {
- big_waste_of_time();
- }
-
- A conflict occurs if both --bbll and --bbaarr are specified.
-
- --oottrr, ----ooppeenniinngg--ttookkeenn--rriigghhtt and related flags
- The --oottrr flag is a hint that perltidy should not place a break between a comma and an opening token. For
- example:
-
- # default formatting
- push @{ $self->{$module}{$key} },
- {
- accno => $ref->{accno},
- description => $ref->{description}
- };
-
- # perltidy -otr
- push @{ $self->{$module}{$key} }, {
- accno => $ref->{accno},
- description => $ref->{description}
- };
-
- The flag --oottrr is actually an abbreviation for three other flags which can be used to control parens, hash
- braces, and square brackets separately if desired:
-
- -opr or --opening-paren-right
- -ohbr or --opening-hash-brace-right
- -osbr or --opening-square-bracket-right
-
- --bbbbhhbb==nn, ----bbrreeaakk--bbeeffoorree--hhaasshh--bbrraaccee==nn and related flags
- When a list of items spans multiple lines, the default formatting is to place the opening brace (or other
- container token) at the end of the starting line, like this:
-
- $romanNumerals = {
- one => 'I',
- two => 'II',
- three => 'III',
- four => 'IV',
- };
-
- This flag can change the default behavior to cause a line break to be placed before the opening brace
- according to the value given to the integer nn:
-
- -bbhb=0 never break [default]
- -bbhb=1 stable: break if the input script had a break
- -bbhb=2 break if list is 'complex' (see note below)
- -bbhb=3 always break
-
- For example,
-
- # perltidy -bbhb=3
- $romanNumerals =
- {
- one => 'I',
- two => 'II',
- three => 'III',
- four => 'IV',
- };
-
- There are several points to note about this flag:
-
- +o This parameter only applies if the opening brace is preceded by an '=' or '=>'.
-
- +o This parameter only applies if the contents of the container looks like a list. The contents need to
- contain some commas or '=>'s at the next interior level to be considered a list.
-
- +o For the nn==22 option, a list is considered 'complex' if it is part of a nested list structure which spans
- multiple lines in the input file.
-
- +o If multiple opening tokens have been 'welded' together with the --wwnn parameter, then this parameter has
- no effect.
-
- +o The indentation of the braces will normally be one level of continuation indentation by default. This
- can be changed with the parameter --bbbbhhbbii==nn in the next section.
-
- +o Similar flags for controlling parens and square brackets are given in the subsequent section.
-
- --bbbbhhbbii==nn, ----bbrreeaakk--bbeeffoorree--hhaasshh--bbrraaccee--aanndd--iinnddeenntt==nn
- This flag is a companion to --bbbbhhbb==nn for controlling the indentation of an opening hash brace which is placed
- on a new line by that parameter. The indentation is as follows:
-
- -bbhbi=0 one continuation level [default]
- -bbhbi=1 outdent by one continuation level
- -bbhbi=2 indent one full indentation level
-
- For example:
-
- # perltidy -bbhb=3 -bbhbi=1
- $romanNumerals =
- {
- one => 'I',
- two => 'II',
- three => 'III',
- four => 'IV',
- };
-
- # perltidy -bbhb=3 -bbhbi=2
- $romanNumerals =
- {
- one => 'I',
- two => 'II',
- three => 'III',
- four => 'IV',
- };
-
- Note that this parameter has no effect unless --bbbbhhbb==nn is also set.
-
- --bbbbssbb==nn, ----bbrreeaakk--bbeeffoorree--ssqquuaarree--bbrraacckkeett==nn
- This flag is similar to the flag described above, except it applies to lists contained within square
- brackets.
-
- -bbsb=0 never break [default]
- -bbsb=1 stable: break if the input script had a break
- -bbsb=2 break if list is 'complex' (part of nested list structure)
- -bbsb=3 always break
-
- --bbbbssbbii==nn, ----bbrreeaakk--bbeeffoorree--ssqquuaarree--bbrraacckkeett--aanndd--iinnddeenntt==nn
- This flag is a companion to --bbbbssbb==nn for controlling the indentation of an opening square bracket which is
- placed on a new line by that parameter. The indentation is as follows:
-
- -bbsbi=0 one continuation level [default]
- -bbsbi=1 outdent by one continuation level
- -bbsbi=2 indent one full indentation level
-
- --bbbbpp==nn, ----bbrreeaakk--bbeeffoorree--ppaarreenn==nn
- This flag is similar to --bbbbhhbb==nn, described above, except it applies to lists contained within parens.
-
- -bbp=0 never break [default]
- -bbp=1 stable: break if the input script had a break
- -bpb=2 break if list is 'complex' (part of nested list structure)
- -bbp=3 always break
-
- --bbbbppii==nn, ----bbrreeaakk--bbeeffoorree--ppaarreenn--aanndd--iinnddeenntt==nn
- This flag is a companion to --bbbbpp==nn for controlling the indentation of an opening paren which is placed on a
- new line by that parameter. The indentation is as follows:
-
- -bbpi=0 one continuation level [default]
- -bbpi=1 outdent by one continuation level
- -bbpi=2 indent one full indentation level
-
- --wwnn, ----wweelldd--nneesstteedd--ccoonnttaaiinneerrss
- The --wwnn flag causes closely nested pairs of opening and closing container symbols (curly braces, brackets,
- or parens) to be "welded" 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.
-
- For example:
-
- # default formatting
- do {
- {
- next if $x == $y;
- }
- } until $x++ > $z;
-
- # perltidy -wn
- do { {
- next if $x == $y;
- } } until $x++ > $z;
-
- 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 and the
- opening symbols must either (1) be adjacent as in the above example, or (2) have an anonymous sub
- declaration following an outer opening container symbol which is not a code block brace, or (3) have an
- outer opening paren separated from the inner opening symbol by any single non-container symbol or something
- that looks like a function evaluation, as illustrated in the next examples.
-
- 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:
-
- # default formatting
- my (@date_time) = Localtime(
- Date_to_Time(
- Add_Delta_DHMS(
- $year, $month, $day, $hour, $minute, $second,
- '0', $offset, '0', '0'
- )
- )
- );
-
- # perltidy -wn
- my (@date_time) = Localtime( Date_to_Time( Add_Delta_DHMS(
- $year, $month, $day, $hour, $minute, $second,
- '0', $offset, '0', '0'
- ) ) );
-
- 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 "meat" of the sandwich, and a final closing layer. This
- predictable structure helps keep the compacted structure readable.
-
- 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 --ccoonnvv flag can be used to insure that the final format is achieved in a
- single run.
-
- Here is an example illustrating a welded container within a welded containers:
-
- # 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
- ) );
-
- The welded closing tokens are by default on a separate line but this can be modified with the --vvttcc==nn flag
- (described in the next section). For example, the same example adding --vvttcc==22 is
-
- # perltidy -wn -vtc=2
- $x->badd( bmul(
- $class->new( abs(
- $sx * int( $xr->numify() ) & $sy * int( $yr->numify() ) ) ),
- $m ) );
-
- This format option is quite general but there are some limitations.
-
- One limitation is that any line length limit still applies and can cause long welded sections to be broken
- into multiple lines.
-
- 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.
-
- 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.
-
- --wwnnxxll==ss, ----wweelldd--nneesstteedd--eexxcclluussiioonn--lliisstt
- The --wwnnxxll==ss flag provides some control over the types of containers which can be welded. The --wwnn flag by
- default is "greedy" in welding adjacent containers. If it welds more types of containers than desired, this
- flag provides a capability to reduce the amount of welding by specifying a list of things which should nnoott
- be welded.
-
- The logic in perltidy to apply this is straightforward. As each container token is being considered for
- joining a weld, any exclusion rules are consulted and used to reject the weld if necessary.
-
- This list is a string with space-separated items. Each item consists of up to three pieces of information:
- (1) an optional position, (2) an optional preceding type, and (3) a container type.
-
- The only required piece of information is a container type, which is one of '(', '[', '{' or 'q'. The first
- three of these are container tokens and the last represents a quoted list. For example the string
-
- -wnxl='[ { q'
-
- means do NNOOTT include square-bracets, braces, or quotes in any welds. The only unspecified container is '(',
- so this string means that only welds involving parens will be made.
-
- To illustrate, following welded snippet consists of a chain of three welded containers with types '(' '['
- and 'q':
-
- # perltidy -wn
- skip_symbols( [ qw(
- Perl_dump_fds
- Perl_ErrorNo
- Perl_GetVars
- PL_sys_intern
- ) ] );
-
- Even though the qw term uses parens as the quote delimiter, it has a special type 'q' here. If it appears in
- a weld it always appears at the end of the welded chain.
-
- Any of the container types '[', '{', and '(' may be prefixed with a position indicator which is either '^',
- to indicate the first token of a welded sequence, or '.', to indicate an interior token of a welded
- sequence. (Since a quoted string 'q' always ends a chain it does need a position indicator).
-
- For example, if we do not want a sequence of welded containers to start with a square bracket we could use
-
- -wnxl='^['
-
- In the above snippet, there is a square bracket but it does not start the chain, so the formatting would be
- unchanged if it were formatted with this restriction.
-
- A third optional item of information which can be given is an alphanumeric letter which is used to limit the
- selection further depending on the type of token immediately before the container. If given, it goes just
- before the container symbol. The possible letters are currently 'k', 'K', 'f', 'F', 'w', and 'W', with
- these meanings:
-
- 'k' matches if the previous nonblank token is a perl builtin keyword (such as 'if', 'while'),
- 'K' matches if 'k' does not, meaning that the previous token is not a keyword.
- 'f' matches if the previous token is a function other than a keyword.
- 'F' matches if 'f' does not.
- 'w' matches if either 'k' or 'f' match.
- 'W' matches if 'w' does not.
-
- For example, compare
-
- # perltidy -wn
- if ( defined( $_Cgi_Query{
- $Config{'methods'}{'authentication'}{'remote'}{'cgi'}{'username'}
- } ) )
-
- with
-
- # perltidy -wn -wnxl='^K( {'
- if ( defined(
- $_Cgi_Query{ $Config{'methods'}{'authentication'}{'remote'}{'cgi'}
- {'username'} }
- ) )
-
- The first case does maximum welding. In the second case the leading paren is retained by the rule (it would
- have been rejected if preceded by a non-keyword) but the curly brace is rejected by the rule.
-
- Here are some additional example strings and their meanings:
-
- '^(' - the weld must not start with a paren
- '.(' - the second and later tokens may not be parens
- '.w(' - the second and later tokens may not keyword or function call parens
- '(' - no parens in a weld
- '^K(' - exclude a leading paren preceded by a non-keyword
- '.k(' - exclude a secondary paren preceded by a keyword
- '[ {' - exclude all brackets and braces
- '[ ( ^K{' - exclude everything except nested structures like do {{ ... }}
-
- VVeerrttiiccaall ttiigghhttnneessss of non-block curly braces, parentheses, and square brackets.
- These parameters control what shall be called vertical tightness. Here are the main points:
-
- +o Opening tokens (except for block braces) are controlled by --vvtt==nn, or ----vveerrttiiccaall--ttiigghhttnneessss==nn, where
-
- -vt=0 always break a line after opening token (default).
- -vt=1 do not break unless this would produce more than one
- step in indentation in a line.
- -vt=2 never break a line after opening token
-
- +o You must also use the --llpp flag when you use the --vvtt flag; the reason is explained below.
-
- +o Closing tokens (except for block braces) are controlled by --vvttcc==nn, or ----vveerrttiiccaall--ttiigghhttnneessss--cclloossiinngg==nn,
- where
-
- -vtc=0 always break a line before a closing token (default),
- -vtc=1 do not break before a closing token which is followed
- by a semicolon or another closing token, and is not in
- a list environment.
- -vtc=2 never break before a closing token.
- -vtc=3 Like -vtc=1 except always break before a closing token
- if the corresponding opening token follows an = or =>.
-
- The rules for --vvttcc==11 and --vvttcc==33 are designed to maintain a reasonable balance between tightness and
- readability in complex lists.
-
- +o Different controls may be applied to different token types, and it is also possible to control block
- braces; see below.
-
- +o Finally, please note that these vertical tightness flags are merely hints to the formatter, and it
- cannot always follow them. Things which make it difficult or impossible include comments, blank lines,
- blocks of code within a list, and possibly the lack of the --llpp parameter. Also, these flags may be
- ignored for very small lists (2 or 3 lines in length).
-
- Here are some examples:
-
- # perltidy -lp -vt=0 -vtc=0
- %romanNumerals = (
- one => 'I',
- two => 'II',
- three => 'III',
- four => 'IV',
- );
-
- # perltidy -lp -vt=1 -vtc=0
- %romanNumerals = ( one => 'I',
- two => 'II',
- three => 'III',
- four => 'IV',
- );
-
- # perltidy -lp -vt=1 -vtc=1
- %romanNumerals = ( one => 'I',
- two => 'II',
- three => 'III',
- four => 'IV', );
-
- # perltidy -vtc=3
- my_function(
- one => 'I',
- two => 'II',
- three => 'III',
- four => 'IV', );
-
- # perltidy -vtc=3
- %romanNumerals = (
- one => 'I',
- two => 'II',
- three => 'III',
- four => 'IV',
- );
-
- In the last example for --vvttcc==33, the opening paren is preceded by an equals so the closing paren is placed on
- a new line.
-
- The difference between --vvtt==11 and --vvtt==22 is shown here:
-
- # perltidy -lp -vt=1
- $init->add(
- mysprintf( "(void)find_threadsv(%s);",
- cstring( $threadsv_names[ $op->targ ] )
- )
- );
-
- # perltidy -lp -vt=2
- $init->add( mysprintf( "(void)find_threadsv(%s);",
- cstring( $threadsv_names[ $op->targ ] )
- )
- );
-
- With --vvtt==11, the line ending in "add(" does not combine with the next line because the next line is not
- balanced. This can help with readability, but --vvtt==22 can be used to ignore this rule.
-
- The tightest, and least readable, code is produced with both "-vt=2" and "-vtc=2":
-
- # perltidy -lp -vt=2 -vtc=2
- $init->add( mysprintf( "(void)find_threadsv(%s);",
- cstring( $threadsv_names[ $op->targ ] ) ) );
-
- Notice how the code in all of these examples collapses vertically as --vvtt increases, but the indentation
- remains unchanged. This is because perltidy implements the --vvtt parameter by first formatting as if --vvtt==00,
- and then simply overwriting one output line on top of the next, if possible, to achieve the desired vertical
- tightness. The --llpp indentation style has been designed to allow this vertical collapse to occur, which is
- why it is required for the --vvtt parameter.
-
- The --vvtt==nn and --vvttcc==nn parameters apply to each type of container token. If desired, vertical tightness
- controls can be applied independently to each of the closing container token types.
-
- The parameters for controlling parentheses are --ppvvtt==nn or ----ppaarreenn--vveerrttiiccaall--ttiigghhttnneessss==nn, and --ppvvttcc==nn or
- ----ppaarreenn--vveerrttiiccaall--ttiigghhttnneessss--cclloossiinngg==nn.
-
- Likewise, the parameters for square brackets are --ssbbvvtt==nn or ----ssqquuaarree--bbrraacckkeett--vveerrttiiccaall--ttiigghhttnneessss==nn, and
- --ssbbvvttcc==nn or ----ssqquuaarree--bbrraacckkeett--vveerrttiiccaall--ttiigghhttnneessss--cclloossiinngg==nn.
-
- Finally, the parameters for controlling non-code block braces are --bbvvtt==nn or ----bbrraaccee--vveerrttiiccaall--ttiigghhttnneessss==nn,
- and --bbvvttcc==nn or ----bbrraaccee--vveerrttiiccaall--ttiigghhttnneessss--cclloossiinngg==nn.
-
- In fact, the parameter --vvtt==nn is actually just an abbreviation for --ppvvtt==nn --bbvvtt==nn ssbbvvtt==nn, and likewise --vvttcc==nn
- is an abbreviation for --ppvvttcc==nn --bbvvttcc==nn --ssbbvvttcc==nn.
-
- --bbbbvvtt==nn or ----bblloocckk--bbrraaccee--vveerrttiiccaall--ttiigghhttnneessss==nn
- The --bbbbvvtt==nn flag is just like the --vvtt==nn flag but applies to opening code block braces.
-
- -bbvt=0 break after opening block brace (default).
- -bbvt=1 do not break unless this would produce more than one
- step in indentation in a line.
- -bbvt=2 do not break after opening block brace.
-
- It is necessary to also use either --bbll or --bbllii for this to work, because, as with other vertical tightness
- controls, it is implemented by simply overwriting a line ending with an opening block brace with the
- subsequent line. For example:
-
- # perltidy -bli -bbvt=0
- if ( open( FILE, "< $File" ) )
- {
- while ( $File = <FILE> )
- {
- $In .= $File;
- $count++;
- }
- close(FILE);
- }
-
- # perltidy -bli -bbvt=1
- if ( open( FILE, "< $File" ) )
- { while ( $File = <FILE> )
- { $In .= $File;
- $count++;
- }
- close(FILE);
- }
-
- By default this applies to blocks associated with keywords iiff, eellssiiff, eellssee, uunnlleessss, ffoorr, ffoorreeaacchh, ssuubb,
- wwhhiillee, uunnttiill, and also with a preceding label. This can be changed with the parameter --bbbbvvttll==ssttrriinngg, or
- ----bblloocckk--bbrraaccee--vveerrttiiccaall--ttiigghhttnneessss--lliisstt==ssttrriinngg, where ssttrriinngg is a space-separated list of block types. For
- more information on the possible values of this string, see "Specifying Block Types"
-
- For example, if we want to just apply this style to "if", "elsif", and "else" blocks, we could use "perltidy
- -bli -bbvt=1 -bbvtl='if elsif else'".
-
- There is no vertical tightness control for closing block braces; with one exception they will be placed on
- separate lines. The exception is that a cascade of closing block braces may be stacked on a single line.
- See --ssccbbbb.
-
- --ssoott, ----ssttaacckk--ooppeenniinngg--ttookkeennss and related flags
- The --ssoott flag tells perltidy to "stack" opening tokens when possible to avoid lines with isolated opening
- tokens.
-
- For example:
-
- # default
- $opt_c = Text::CSV_XS->new(
- {
- binary => 1,
- sep_char => $opt_c,
- always_quote => 1,
- }
- );
-
- # -sot
- $opt_c = Text::CSV_XS->new( {
- binary => 1,
- sep_char => $opt_c,
- always_quote => 1,
- }
- );
-
- For detailed control of individual closing tokens the following controls can be used:
-
- -sop or --stack-opening-paren
- -sohb or --stack-opening-hash-brace
- -sosb or --stack-opening-square-bracket
- -sobb or --stack-opening-block-brace
-
- The flag --ssoott is an abbreviation for --ssoopp --ssoohhbb --ssoossbb.
-
- The flag --ssoobbbb is an abbreviation for --bbbbvvtt==22 --bbbbvvttll==''**''. This will case a cascade of opening block braces
- to appear on a single line, although this an uncommon occurrence except in test scripts.
-
- --sscctt, ----ssttaacckk--cclloossiinngg--ttookkeennss and related flags
- The --sscctt flag tells perltidy to "stack" closing tokens when possible to avoid lines with isolated closing
- tokens.
-
- For example:
-
- # default
- $opt_c = Text::CSV_XS->new(
- {
- binary => 1,
- sep_char => $opt_c,
- always_quote => 1,
- }
- );
-
- # -sct
- $opt_c = Text::CSV_XS->new(
- {
- binary => 1,
- sep_char => $opt_c,
- always_quote => 1,
- } );
-
- The --sscctt flag is somewhat similar to the --vvttcc flags, and in some cases it can give a similar result. The
- difference is that the --vvttcc flags try to avoid lines with leading opening tokens by "hiding" them at the end
- of a previous line, whereas the --sscctt flag merely tries to reduce the number of lines with isolated closing
- tokens by stacking them but does not try to hide them. For example:
-
- # -vtc=2
- $opt_c = Text::CSV_XS->new(
- {
- binary => 1,
- sep_char => $opt_c,
- always_quote => 1, } );
-
- For detailed control of the stacking of individual closing tokens the following controls can be used:
-
- -scp or --stack-closing-paren
- -schb or --stack-closing-hash-brace
- -scsb or --stack-closing-square-bracket
- -scbb or --stack-closing-block-brace
-
- The flag --sscctt is an abbreviation for stacking the non-block closing tokens, --ssccpp --sscchhbb --ssccssbb.
-
- Stacking of closing block braces, --ssccbbbb, causes a cascade of isolated closing block braces to be combined
- into a single line as in the following example:
-
- # -scbb:
- for $w1 (@w1) {
- for $w2 (@w2) {
- for $w3 (@w3) {
- for $w4 (@w4) {
- push( @lines, "$w1 $w2 $w3 $w4\n" );
- } } } }
-
- To simplify input even further for the case in which both opening and closing non-block containers are
- stacked, the flag --ssaacc or ----ssttaacckk--aallll--ccoonnttaaiinneerrss is an abbreviation for --ssoott --sscctt.
-
- Please note that if both opening and closing tokens are to be stacked, then the newer flag
- --wweelldd--nneesstteedd--ccoonnttaaiinneerrss may be preferable because it insures that stacking is always done symmetrically. It
- also removes an extra level of unnecessary indentation within welded containers. It is able to do this
- because it works on formatting globally rather than locally, as the --ssoott and --sscctt flags do.
-
- --ddnnll, ----ddeelleettee--oolldd--nneewwlliinneess
- 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 --nnddnnll or ----nnooddeelleettee--oolldd--nneewwlliinneess to force perltidy to retain all old
- line break points.
-
- --aannll, ----aadddd--nneewwlliinneess
- By default, perltidy will add line breaks when necessary to create continuations of long lines and to
- improve the script appearance. Use --nnaannll or ----nnooaadddd--nneewwlliinneess to prevent any new line breaks.
-
- This flag does not prevent perltidy from eliminating existing line breaks; see ----ffrreeeezzee--nneewwlliinneess to
- completely prevent changes to line break points.
-
- CCoonnttrroolllliinngg wwhheetthheerr ppeerrllttiiddyy bbrreeaakkss bbeeffoorree oorr aafftteerr ooppeerraattoorrss
- 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:
-
- --wwbbaa==ss or ----wwaanntt--bbrreeaakk--aafftteerr==ss, and
-
- --wwbbbb==ss or ----wwaanntt--bbrreeaakk--bbeeffoorree==ss.
-
- These parameters are each followed by a quoted string, ss, containing a list of token types (separated only
- by spaces). No more than one of each of these parameters should be specified, because repeating a command-
- line parameter always overwrites the previous one before perltidy ever sees it.
-
- By default, perltidy breaks aafftteerr these token types:
- % + - * / x != == >= <= =~ !~ < > | &
- = **= += *= &= <<= &&= -= /= |= >>= ||= //= .= %= ^= x=
-
- And perltidy breaks bbeeffoorree these token types by default:
- . << >> -> && || //
-
- To illustrate, to cause a break after a concatenation operator, '.', rather than before it, the command line
- would be
-
- -wba="."
-
- As another example, the following command would cause a break before math operators '+', '-', '/', and '*':
-
- -wbb="+ - / *"
-
- These commands should work well for most of the token types that perltidy uses (use ----dduummpp--ttookkeenn--ttyyppeess for a
- list). Also try the --DD 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 with the parameter bbll provided for that purpose.
-
- WWAARRNNIINNGG Be sure to put these tokens in quotes to avoid having them misinterpreted by your command shell.
-
- Two additional parameters are available which, though they provide no further capability, can simplify input
- are:
-
- --bbaaaaoo or ----bbrreeaakk--aafftteerr--aallll--ooppeerraattoorrss,
-
- --bbbbaaoo or ----bbrreeaakk--bbeeffoorree--aallll--ooppeerraattoorrss.
-
- The -baao sets the default to be to break after all of the following operators:
-
- % + - * / x != == >= <= =~ !~ < > | &
- = **= += *= &= <<= &&= -= /= |= >>= ||= //= .= %= ^= x=
- . : ? && || and or err xor
-
- and the --bbbbaaoo 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 --wwbbaa and --wwbbbb flags. For example, to break before
- all operators except an == one could use --bbao -wba='=' rather than listing every single perl operator
- except == on a -wbb flag.
-
- CCoonnttrroolllliinngg LLiisstt FFoorrmmaattttiinngg
- Perltidy attempts to format lists of comma-separated values in tables which look good. Its default algorithms
- usually work well, but sometimes they don't. In this case, there are several methods available to control list
- formatting.
-
- A very simple way to prevent perltidy from changing the line breaks within a comma-separated list of values is
- to insert a blank line, comment, or side-comment anywhere between the opening and closing parens (or braces or
- brackets). This causes perltidy to skip over its list formatting logic. (The reason is that any of these
- items put a constraint on line breaks, and perltidy needs complete control over line breaks within a container
- to adjust a list layout). For example, let us consider
-
- my @list = (1,
- 1, 1,
- 1, 2, 1,
- 1, 3, 3, 1,
- 1, 4, 6, 4, 1,);
-
- The default formatting, which allows a maximum line length of 80, will flatten this down to one line:
-
- # perltidy (default)
- my @list = ( 1, 1, 1, 1, 2, 1, 1, 3, 3, 1, 1, 4, 6, 4, 1, );
-
- This formatting loses important information. If we place a side comment on one of the lines, for example, we
- get the following result with with default formatting parameters:
-
- my @list = (
- 1, # a side comment, comment, or blank keeps list intact
- 1, 1,
- 1, 2, 1,
- 1, 3, 3, 1,
- 1, 4, 6, 4, 1,
- );
-
- We could achieve the same result with a blank line or full comment anywhere between the opening and closing
- parens.
-
- For another possibility see the -fs flag in "Skipping Selected Sections of Code".
-
- --bboocc, ----bbrreeaakk--aatt--oolldd--ccoommmmaa--bbrreeaakkppooiinnttss
- The --bboocc flag is another way to prevent comma-separated lists from being reformatted. Using --bboocc on the
- above example, plus additional flags to retain the original style, yields
-
- # perltidy -boc -lp -pt=2 -vt=1 -vtc=1
- my @list = (1,
- 1, 1,
- 1, 2, 1,
- 1, 3, 3, 1,
- 1, 4, 6, 4, 1,);
-
- A disadvantage of this flag is that all tables in the file must already be nicely formatted.
-
- --mmfftt==nn, ----mmaaxxiimmuumm--ffiieellddss--ppeerr--ttaabbllee==nn
- If the computed number of fields for any table exceeds nn, then it will be reduced to nn. The default value
- for nn is a large number, 40. While this value should probably be left unchanged as a general rule, it might
- be used on a small section of code to force a list to have a particular number of fields per line, and then
- either the --bboocc flag could be used to retain this formatting, or a single comment could be introduced
- somewhere to freeze the formatting in future applications of perltidy.
-
- # perltidy -mft=2
- @month_of_year = (
- 'Jan', 'Feb',
- 'Mar', 'Apr',
- 'May', 'Jun',
- 'Jul', 'Aug',
- 'Sep', 'Oct',
- 'Nov', 'Dec'
- );
-
- --ccaabb==nn, ----ccoommmmaa--aarrrrooww--bbrreeaakkppooiinnttss==nn
- 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 these commas.
- (However, it will have no effect if old comma breaks are being forced because --bboocc is used). The possible
- values of nn are:
-
- n=0 break at all commas after =>
- n=1 stable: break at all commas after => if container is open,
- EXCEPT FOR one-line containers
- n=2 break at all commas after =>, BUT try to form the maximum
- one-line container lengths
- n=3 do not treat commas after => specially at all
- n=4 break everything: like n=0 but ALSO break a short container with
- a => not followed by a comma when -vt=0 is used
- n=5 stable: like n=1 but ALSO break at open one-line containers when
- -vt=0 is used (default)
-
- For example, given the following single line, perltidy by default will not add any line breaks because it
- would break the existing one-line container:
-
- bless { B => $B, Root => $Root } => $package;
-
- Using --ccaabb==00 will force a break after each comma-arrow item:
-
- # perltidy -cab=0:
- bless {
- B => $B,
- Root => $Root
- } => $package;
-
- If perltidy is subsequently run with this container broken, then by default it will break after each '=>'
- because the container is now broken. To reform a one-line container, the parameter --ccaabb==22 could be used.
-
- The flag --ccaabb==33 can be used to prevent these commas from being treated specially. In this case, an item
- such as "01" => 31 is treated as a single item in a table. The number of fields in this table will be
- determined by the same rules that are used for any other table. Here is an example.
-
- # perltidy -cab=3
- my %last_day = (
- "01" => 31, "02" => 29, "03" => 31, "04" => 30,
- "05" => 31, "06" => 30, "07" => 31, "08" => 31,
- "09" => 30, "10" => 31, "11" => 30, "12" => 31
- );
-
- RReettaaiinniinngg oorr IIggnnoorriinngg EExxiissttiinngg LLiinnee BBrreeaakkss
- Several additional parameters are available for controlling the extent to which line breaks in the input script
- influence the output script. In most cases, the default parameter values are set so that, if a choice is
- possible, the output style follows the input style. For example, if a short logical container is broken in the
- input script, then the default behavior is for it to remain broken in the output script.
-
- Most of the parameters in this section would only be required for a one-time conversion of a script from short
- container lengths to longer container lengths. The opposite effect, of converting long container lengths to
- shorter lengths, can be obtained by temporarily using a short maximum line length.
-
- --bbooll, ----bbrreeaakk--aatt--oolldd--llooggiiccaall--bbrreeaakkppooiinnttss
- By default, if a logical expression is broken at a "&&", "||", "and", or "or", then the container will
- remain broken. Also, breaks at internal keywords "if" and "unless" will normally be retained. To prevent
- this, and thus form longer lines, use --nnbbooll.
-
- Please note that this flag does not duplicate old logical breakpoints. They are merely used as a hint with
- this flag that a statement should remain broken. Without this flag, perltidy will normally try to combine
- relatively short expressions into a single line.
-
- For example, given this snippet:
-
- return unless $cmd = $cmd || ($dot
- && $Last_Shell) || &prompt('|');
-
- # perltidy -bol [default]
- return
- unless $cmd = $cmd
- || ( $dot
- && $Last_Shell )
- || &prompt('|');
-
- # perltidy -nbol
- return unless $cmd = $cmd || ( $dot && $Last_Shell ) || &prompt('|');
-
- --bboomm, ----bbrreeaakk--aatt--oolldd--mmeetthhoodd--bbrreeaakkppooiinnttss
- By default, a method call arrow "->" is considered a candidate for a breakpoint, but method chains will fill
- to the line width before a break is considered. With --bboomm, breaks before the arrow are preserved, so if you
- have preformatted a method chain:
-
- my $q = $rs
- ->related_resultset('CDs')
- ->related_resultset('Tracks')
- ->search({
- 'track.id' => {-ident => 'none_search.id'},
- })->as_query;
-
- It will kkeeeepp these breaks, rather than become this:
-
- my $q = $rs->related_resultset('CDs')->related_resultset('Tracks')->search({
- 'track.id' => {-ident => 'none_search.id'},
- })->as_query;
-
- This flag will also look for and keep a 'cuddled' style of calls, in which lines begin with a closing paren
- followed by a call arrow, as in this example:
-
- # perltidy -bom -wn
- my $q = $rs->related_resultset(
- 'CDs'
- )->related_resultset(
- 'Tracks'
- )->search( {
- 'track.id' => { -ident => 'none_search.id' },
- } )->as_query;
-
- You may want to include the --wweelldd--nneesstteedd--ccoonnttaaiinneerrss flag in this case to keep nested braces and parens
- together, as in the last line.
-
- --bbooss, ----bbrreeaakk--aatt--oolldd--sseemmiiccoolloonn--bbrreeaakkppooiinnttss
- Semicolons are normally placed at the end of a statement. This means that formatted lines do not normally
- begin with semicolons. If the input stream has some lines which begin with semicolons, these can be
- retained by setting this flag. For example, consider the following two-line input snippet:
-
- $z = sqrt($x**2 + $y**2)
- ;
-
- The default formatting will be:
-
- $z = sqrt( $x**2 + $y**2 );
-
- The result using ppeerrllttiiddyy --bbooss keeps the isolated semicolon:
-
- $z = sqrt( $x**2 + $y**2 )
- ;
-
- The default is not to do this, --nnbbooss.
-
- --bbookk, ----bbrreeaakk--aatt--oolldd--kkeeyywwoorrdd--bbrreeaakkppooiinnttss
- By default, perltidy will retain a breakpoint before keywords which may return lists, such as "sort" and
- <map>. This allows chains of these operators to be displayed one per line. Use --nnbbookk to prevent retaining
- these breakpoints.
-
- --bboott, ----bbrreeaakk--aatt--oolldd--tteerrnnaarryy--bbrreeaakkppooiinnttss
- By default, if a conditional (ternary) operator is broken at a ":", then it will remain broken. To prevent
- this, and thereby form longer lines, use --nnbboott.
-
- --bbooaa, ----bbrreeaakk--aatt--oolldd--aattttrriibbuuttee--bbrreeaakkppooiinnttss
- By default, if an attribute list is broken at a ":" in the source file, then it will remain broken. For
- example, given the following code, the line breaks at the ':'s will be retained:
-
- my @field
- : field
- : Default(1)
- : Get('Name' => 'foo') : Set('Name');
-
- If the attributes are on a single line in the source code then they will remain on a single line if
- possible.
-
- To prevent this, and thereby always form longer lines, use --nnbbooaa.
-
- KKeeeeppiinngg oolldd bbrreeaakkppooiinnttss aatt ssppeecciiffiicc ttookkeenn ttyyppeess
- Two command line parameters provide detailed control over whether perltidy should keep an old line break
- before or after a specific token type:
-
- --kkbbbb==ss or ----kkeeeepp--oolldd--bbrreeaakkppooiinnttss--bbeeffoorree==ss, and
-
- --kkbbaa==ss or ----kkeeeepp--oolldd--bbrreeaakkppooiinnttss--aafftteerr==ss
-
- These parameters are each followed by a quoted string, ss, containing a list of token types (separated only
- by spaces). No more than one of each of these parameters should be specified, because repeating a command-
- line parameter always overwrites the previous one before perltidy ever sees it.
-
- For example, -kbb='=>' means that if an input line begins with a '=>' then the output script should also
- have a line break before that token.
-
- For example, given the script:
-
- method 'foo'
- => [ Int, Int ]
- => sub {
- my ( $self, $x, $y ) = ( shift, @_ );
- ...;
- };
-
- # perltidy [default]
- method 'foo' => [ Int, Int ] => sub {
- my ( $self, $x, $y ) = ( shift, @_ );
- ...;
- };
-
- # perltidy -kbb='=>'
- method 'foo'
- => [ Int, Int ]
- => sub {
- my ( $self, $x, $y ) = ( shift, @_ );
- ...;
- };
-
- --iioobb, ----iiggnnoorree--oolldd--bbrreeaakkppooiinnttss
- 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. But please note that this parameter has priority over all other parameters requesting that certain
- old breakpoints be kept.
-
- --kkiiss, ----kkeeeepp--iinntteerriioorr--sseemmiiccoolloonnss
- Use the --kkiiss 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:
-
- dbmclose(%verb_delim); undef %verb_delim;
- dbmclose(%expanded); undef %expanded;
-
- The default is to break after each statement, giving
-
- dbmclose(%verb_delim);
- undef %verb_delim;
- dbmclose(%expanded);
- undef %expanded;
-
- With ppeerrllttiiddyy --kkiiss the multiple statements are retained:
-
- dbmclose(%verb_delim); undef %verb_delim;
- dbmclose(%expanded); undef %expanded;
-
- The statements are still subject to the specified value of mmaaxxiimmuumm--lliinnee--lleennggtthh and will be broken if this
- maximum is exceeded.
-
- BBllaannkk LLiinnee CCoonnttrrooll
- Blank lines can improve the readability of a script if they are carefully placed. Perltidy has several commands
- for controlling the insertion, retention, and removal of blank lines.
-
- --ffbbll, ----ffrreeeezzee--bbllaannkk--lliinneess
- Set --ffbbll 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 --ffbbll flag is equivalent to setting
- --mmbbll==00 and --kkbbll==22).
-
- --bbbbcc, ----bbllaannkkss--bbeeffoorree--ccoommmmeennttss
- A blank line will be introduced before a full-line comment. This is the default. Use --nnbbbbcc or
- ----nnoobbllaannkkss--bbeeffoorree--ccoommmmeennttss to prevent such blank lines from being introduced.
-
- --bbllbbss==nn, ----bbllaannkk--lliinneess--bbeeffoorree--ssuubbss==nn
- The parameter --bbllbbss==nn requests that least nn 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>. BBEEGGIINN and EENNDD blocks are included.
-
- The requested number of blanks statement will be inserted regardless of the value of
- ----mmaaxxiimmuumm--ccoonnsseeccuuttiivvee--bbllaannkk--lliinneess==nn (--mmbbll==nn) with the exception that if --mmbbll==00 then no blanks will be
- output.
-
- This parameter interacts with the value kk of the parameter ----mmaaxxiimmuumm--ccoonnsseeccuuttiivvee--bbllaannkk--lliinneess==kk (--mmbbll==kk) as
- follows:
-
- 1. If --mmbbll==00 then no blanks will be output. This allows all blanks to be suppressed with a single
- parameter. Otherwise,
-
- 2. If the number of old blank lines in the script is less than nn then additional blanks will be inserted to
- make the total nn regardless of the value of --mmbbll==kk.
-
- 3. If the number of old blank lines in the script equals or exceeds nn then this parameter has no effect,
- however the total will not exceed value specified on the --mmbbll==kk flag.
-
- --bbllbbpp==nn, ----bbllaannkk--lliinneess--bbeeffoorree--ppaacckkaaggeess==nn
- The parameter --bbllbbpp==nn requests that least nn blank lines precede a package which does not follow a comment.
- The default is --bbllbbpp==11.
-
- This parameter interacts with the value kk of the parameter ----mmaaxxiimmuumm--ccoonnsseeccuuttiivvee--bbllaannkk--lliinneess==kk (--mmbbll==kk) in
- the same way as described for the previous item --bbllbbss==nn.
-
- --bbbbss, ----bbllaannkkss--bbeeffoorree--ssuubbss
- For compatibility with previous versions, --bbbbss or ----bbllaannkkss--bbeeffoorree--ssuubbss is equivalent to _-_b_l_b_p_=_1 and _-_b_l_b_s_=_1.
-
- Likewise, --nnbbbbss or ----nnoobbllaannkkss--bbeeffoorree--ssuubbss is equivalent to _-_b_l_b_p_=_0 and _-_b_l_b_s_=_0.
-
- --bbbbbb, ----bbllaannkkss--bbeeffoorree--bblloocckkss
- A blank line will be introduced before blocks of coding delimited by ffoorr, ffoorreeaacchh, wwhhiillee, uunnttiill, and iiff,
- uunnlleessss, in the following circumstances:
-
- +o The block is not preceded by a comment.
-
- +o The block is not a one-line block.
-
- +o The number of consecutive non-blank lines at the current indentation depth is at least --llbbll (see next
- section).
-
- This is the default. The intention of this option is to introduce some space within dense coding. This is
- negated with --nnbbbbbb or ----nnoobbllaannkkss--bbeeffoorree--bblloocckkss.
-
- --llbbll==nn ----lloonngg--bblloocckk--lliinnee--ccoouunntt==nn
- This controls how often perltidy is allowed to add blank lines before certain block types (see previous
- section). The default is 8. Entering a value of 00 is equivalent to entering a very large number.
-
- --bbllaaoo==ii or ----bbllaannkk--lliinneess--aafftteerr--ooppeenniinngg--bblloocckk==ii
- This control places a minimum of ii blank lines aafftteerr a line which eennddss with an opening block brace of a
- specified type. By default, this only applies to the block of a named ssuubb, but this can be changed (see
- --bbllaaooll below). The default is not to do this (ii==00).
-
- Please see the note below on using the --bbllaaoo and --bbllbbcc options.
-
- --bbllbbcc==ii or ----bbllaannkk--lliinneess--bbeeffoorree--cclloossiinngg--bblloocckk==ii
- This control places a minimum of ii blank lines bbeeffoorree a line which bbeeggiinnss with a closing block brace of a
- specified type. By default, this only applies to the block of a named ssuubb, but this can be changed (see
- --bbllbbccll below). The default is not to do this (ii==00).
-
- --bbllaaooll==ss or ----bbllaannkk--lliinneess--aafftteerr--ooppeenniinngg--bblloocckk--lliisstt==ss
- The parameter ss is a list of block type keywords to which the flag --bbllaaoo should apply. The section
- "Specifying Block Types" explains how to list block types.
-
- --bbllbbccll==ss or ----bbllaannkk--lliinneess--bbeeffoorree--cclloossiinngg--bblloocckk--lliisstt==ss
- This parameter is a list of block type keywords to which the flag --bbllbbcc should apply. The section
- "Specifying Block Types" explains how to list block types.
-
- NNoottee oonn uussiinngg tthhee --bbllaaoo and --bbllbbcc options.
- These blank line controls introduce a certain minimum number of blank lines in the text, but the final
- number of blank lines may be greater, depending on values of the other blank line controls and the number of
- old blank lines. A consequence is that introducing blank lines with these and other controls cannot be
- exactly undone, so some experimentation with these controls is recommended before using them.
-
- For example, suppose that for some reason we decide to introduce one blank space at the beginning and ending
- of all blocks. We could do this using
-
- perltidy -blao=2 -blbc=2 -blaol='*' -blbcl='*' filename
-
- Now suppose the script continues to be developed, but at some later date we decide we don't want these
- spaces after all. We might expect that running with the flags --bbllaaoo==00 and --bbllbbcc==00 will undo them. However,
- by default perltidy retains single blank lines, so the blank lines remain.
-
- We can easily fix this by telling perltidy to ignore old blank lines by including the added parameter --kkbbll==00
- and rerunning. Then the unwanted blank lines will be gone. However, this will cause all old blank lines to
- be ignored, perhaps even some that were added by hand to improve formatting. So please be cautious when
- using these parameters.
-
- --mmbbll==nn ----mmaaxxiimmuumm--ccoonnsseeccuuttiivvee--bbllaannkk--lliinneess==nn
- 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 --bbllbbpp and --bbllbbss parameters. If nn==00 then no blank
- lines will be output (unless all old blank lines are retained with the --kkbbll==22 flag of the next section).
-
- This flag obviously does not apply to pod sections, here-documents, and quotes.
-
- --kkbbll==nn, ----kkeeeepp--oolldd--bbllaannkk--lliinneess==nn
- The --kkbbll==nn flag gives you control over how your existing blank lines are treated.
-
- The possible values of nn are:
-
- n=0 ignore all old blank lines
- n=1 stable: keep old blanks, but limited by the value of the B<-mbl=n> flag
- n=2 keep all old blank lines, regardless of the value of the B<-mbl=n> flag
-
- The default is nn==11.
-
- --ssoobb, ----sswwaallllooww--ooppttiioonnaall--bbllaannkk--lliinneess
- This is equivalent to kkbbll==00 and is included for compatibility with previous versions.
-
- --nnssoobb, ----nnoosswwaallllooww--ooppttiioonnaall--bbllaannkk--lliinneess
- This is equivalent to kkbbll==11 and is included for compatibility with previous versions.
-
- CCoonnttrroollss ffoorr bbllaannkk lliinneess aarroouunndd lliinneess ooff ccoonnsseeccuuttiivvee kkeeyywwoorrddss
-
- The parameters in this section provide some control over the placement of blank lines within and around groups
- of statements beginning with selected keywords. These blank lines are called here kkeeyywwoorrdd ggrroouupp bbllaannkkss, and all
- of the parameters begin with ----kkeeyywwoorrdd--ggrroouupp--bbllaannkkss**, or --kkggbb** for short. The default settings do not employ
- these controls but they can be enabled with the following parameters:
-
- --kkggbbll==ss or ----kkeeyywwoorrdd--ggrroouupp--bbllaannkkss--lliisstt==ss; ss is a quoted string of keywords
-
- --kkggbbss==ss or ----kkeeyywwoorrdd--ggrroouupp--bbllaannkkss--ssiizzee==ss; ss gives the number of keywords required to form a group.
-
- --kkggbbbb==nn or ----kkeeyywwoorrdd--ggrroouupp--bbllaannkkss--bbeeffoorree==nn; nn = (0, 1, or 2) controls a leading blank
-
- --kkggbbaa==nn or ----kkeeyywwoorrdd--ggrroouupp--bbllaannkkss--aafftteerr==nn; nn = (0, 1, or 2) controls a trailing blank
-
- --kkggbbii or ----kkeeyywwoorrdd--ggrroouupp--bbllaannkkss--iinnssiiddee is a switch for adding blanks between subgroups
-
- --kkggbbdd or ----kkeeyywwoorrdd--ggrroouupp--bbllaannkkss--ddeelleettee is a switch for removing initial blank lines between keywords
-
- --kkggbbrr==nn or ----kkeeyywwoorrdd--ggrroouupp--bbllaannkkss--rreeppeeaatt--ccoouunntt==nn can limit the number of times this logic is applied
-
- In addition, the following abbreviations are available to for simplified usage:
-
- --kkggbb or ----kkeeyywwoorrdd--ggrroouupp--bbllaannkkss is short for --kkggbbbb==22 --kkggbbaa==22 kkggbbii
-
- --nnkkggbb or ----nnookkeeyywwoorrdd--ggrroouupp--bbllaannkkss, is short for --kkggbbbb==11 --kkggbbaa==11 nnkkggbbii
-
- Before describing the meaning of the parameters in detail let us look at an example which is formatted with
- default parameter settings.
-
- print "Entering test 2\n";
- use Test;
- use Encode qw(from_to encode decode
- encode_utf8 decode_utf8
- find_encoding is_utf8);
- use charnames qw(greek);
- my @encodings = grep( /iso-?8859/, Encode::encodings() );
- my @character_set = ( '0' .. '9', 'A' .. 'Z', 'a' .. 'z' );
- my @source = qw(ascii iso8859-1 cp1250);
- my @destiny = qw(cp1047 cp37 posix-bc);
- my @ebcdic_sets = qw(cp1047 cp37 posix-bc);
- my $str = join( '', map( chr($_), 0x20 .. 0x7E ) );
- return unless ($str);
-
- using ppeerrllttiiddyy --kkggbb gives:
-
- print "Entering test 2\n";
- <----------this blank controlled by -kgbb
- use Test;
- use Encode qw(from_to encode decode
- encode_utf8 decode_utf8
- find_encoding is_utf8);
- use charnames qw(greek);
- <---------this blank controlled by -kgbi
- my @encodings = grep( /iso-?8859/, Encode::encodings() );
- my @character_set = ( '0' .. '9', 'A' .. 'Z', 'a' .. 'z' );
- my @source = qw(ascii iso8859-1 cp1250);
- my @destiny = qw(cp1047 cp37 posix-bc);
- my @ebcdic_sets = qw(cp1047 cp37 posix-bc);
- my $str = join( '', map( chr($_), 0x20 .. 0x7E ) );
- <----------this blank controlled by -kgba
- return unless ($str);
-
- Blank lines have been introduced around the mmyy and uussee sequences. What happened is that the default keyword
- list includes mmyy and uussee but not pprriinntt and rreettuurrnn. So a continuous sequence of nine mmyy and uussee statements was
- located. This number exceeds the default threshold of five, so blanks were placed before and after the entire
- group. Then, since there was also a subsequence of six mmyy lines, a blank line was introduced to separate them.
-
- Finer control over blank placement can be achieved by using the individual parameters rather than the --kkggbb flag.
- The individual controls are as follows.
-
- --kkggbbll==ss or ----kkeeyywwoorrdd--ggrroouupp--bbllaannkkss--lliisstt==ss, where ss is a quoted string, defines the set of keywords which will be
- formed into groups. The string is a space separated list of keywords. The default set is ss==""uussee rreeqquuiirree llooccaall
- oouurr mmyy"", but any list of keywords may be used. Comment lines may also be included in a keyword group, even
- though they are not keywords. To include ordinary block comments, include the symbol BBCC. To include static
- block comments (which normally begin with '##'), include the symbol SSBBCC.
-
- --kkggbbss==ss or ----kkeeyywwoorrdd--ggrroouupp--bbllaannkkss--ssiizzee==ss, where ss is a string describing the number of consecutive keyword
- statements forming a group. If ss is an integer then it is the minimum number required for a group. A maximum
- value may also be given with the format ss==mmiinn..mmaaxx, where mmiinn is the minimum number and mmaaxx is the maximum
- number, and the min and max values are separated by one or more dots. No groups will be found if the maximum is
- less than the minimum. The maximum is unlimited if not given. The default is ss==55. Some examples:
-
- s min max number for group
- 3 3 unlimited 3 or more
- 1.1 1 1 1
- 1..3 1 3 1 to 3
- 1.0 1 0 (no match)
-
- --kkggbbbb==nn or ----kkeeyywwoorrdd--ggrroouupp--bbllaannkkss--bbeeffoorree==nn specifies whether a blank should appear before the first line of the
- group, as follows:
-
- n=0 => (delete) an existing blank line will be removed
- n=1 => (stable) no change to the input file is made [DEFAULT]
- n=2 => (insert) a blank line is introduced if possible
-
- --kkggbbaa==nn or ----kkeeyywwoorrdd--ggrroouupp--bbllaannkkss--aafftteerr==nn likewise specifies whether a blank should appear after the last line
- of the group, using the same scheme (0=delete, 1=stable, 2=insert).
-
- --kkggbbii or ----kkeeyywwoorrdd--ggrroouupp--bbllaannkkss--iinnssiiddee controls the insertion of blank lines between the first and last
- statement of the entire group. If there is a continuous run of a single statement type with more than the
- minimum threshold number (as specified with --kkggbbss==ss) then this switch causes a blank line be inserted between
- this subgroup and the others. In the example above this happened between the uussee and mmyy statements.
-
- --kkggbbdd or ----kkeeyywwoorrdd--ggrroouupp--bbllaannkkss--ddeelleettee controls the deletion of any blank lines that exist in the the group when
- it is first scanned. When statements are initially scanned, any existing blank lines are included in the
- collection. Any such orignial blank lines will be deleted before any other insertions are made when the
- parameter --kkggbbdd is set. The default is not to do this, --nnkkggbbdd.
-
- --kkggbbrr==nn or ----kkeeyywwoorrdd--ggrroouupp--bbllaannkkss--rreeppeeaatt--ccoouunntt==nn specifies nn, the maximum number of times this logic will be
- applied to any file. The special value nn==00 is the same as n=infinity which means it will be applied to an
- entire script [Default]. A value nn==11 could be used to make it apply just one time for example. This might be
- useful for adjusting just the uussee statements in the top part of a module for example.
-
- --kkggbb or ----kkeeyywwoorrdd--ggrroouupp--bbllaannkkss is an abbreviation equivalent to setting --kkggbbbb==11 --kkggbbaa==11 --kkggbbii. This turns on
- keyword group formatting with a set of default values.
-
- --nnkkggbb or ----nnookkeeyywwoorrdd--ggrroouupp--bbllaannkkss is equivalent to --kkggbbbb==00 --kkggbbaa nnkkggbbii. This flag turns off keyword group blank
- lines and is the default setting.
-
- Here are a few notes about the functioning of this technique.
-
- +o These parameters are probably more useful as part of a major code reformatting operation rather than as a
- routine formatting operation.
-
- In particular, note that deleting old blank lines with --kkggbbdd is an irreversible operation so it should be
- applied with care. Existing blank lines may be serving an important role in controlling vertical alignment.
-
- +o Conflicts which arise among these kkggbb** parameters and other blank line controls are generally resolved by
- producing the maximum number of blank lines implied by any parameter.
-
- For example, if the flags ----ffrreeeezzee--bbllaannkk--lliinneess, or ----kkeeeepp--oolldd--bbllaannkk--lliinneess==22, are set, then they have
- priority over any blank line deletion implied by the --kkggbb flags of this section, so no blank lines will be
- deleted.
-
- For another example, if a keyword group ends at a ssuubb and the flag kkggbbaa==00 requests no blank line there, but
- we also have ----bbllaannkk--lliinneess--bbeeffoorree--ssuubbss==22, then two blank lines will still be introduced before the sub.
-
- +o The introduction of blank lines does not occur if it would conflict with other input controls or code
- validity. For example, a blank line will not be placed within a here-doc or within a section of code marked
- with format skipping comments. And in general, a blank line will only be introduced at the end of a group
- if the next statement is a line of code.
-
- +o The count which is used to determine the group size is not the number of lines but rather the total number
- of keywords which are found. Individual statements with a certain leading keyword may continue on multiple
- lines, but if any of these lines is nested more than one level deep then that group will be ended.
-
- +o The search for groups of lines with similar leading keywords is based on the input source, not the final
- formatted source. Consequently, if the source code is badly formatted, it would be best to make a first
- formatting pass without these options.
-
- SSttyylleess
- A style refers to a convenient collection of existing parameters.
-
- --ggnnuu, ----ggnnuu--ssttyyllee
- --ggnnuu gives an approximation to the GNU Coding Standards (which do not apply to perl) as they are sometimes
- implemented. At present, this style overrides the default style with the following parameters:
-
- -lp -bl -noll -pt=2 -bt=2 -sbt=2 -icp
-
- --ppbbpp, ----ppeerrll--bbeesstt--pprraaccttiicceess
- --ppbbpp is an abbreviation for the parameters in the book PPeerrll BBeesstt PPrraaccttiicceess by Damian Conway:
-
- -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="
-
- Please note that this parameter set includes -st and -se flags, which make perltidy act as a filter on one
- file only. These can be overridden by placing --nnsstt and/or --nnssee after the -pbp parameter.
-
- Also note that the value of continuation indentation, -ci=4, is equal to the value of the full indentation,
- -i=4. It is recommended that the either (1) the parameter --ccii==22 be used instead, or the flag --xxccii be set.
- This will help show structure, particularly when there are ternary statements. The following snippet
- illustrates these options.
-
- # perltidy -pbp
- $self->{_text} = (
- !$section ? ''
- : $type eq 'item' ? "the $section entry"
- : "the section on $section"
- )
- . (
- $page
- ? ( $section ? ' in ' : '' ) . "the $page$page_ext manpage"
- : ' elsewhere in this document'
- );
-
- # perltidy -pbp -ci=2
- $self->{_text} = (
- !$section ? ''
- : $type eq 'item' ? "the $section entry"
- : "the section on $section"
- )
- . (
- $page
- ? ( $section ? ' in ' : '' ) . "the $page$page_ext manpage"
- : ' elsewhere in this document'
- );
-
- # perltidy -pbp -xci
- $self->{_text} = (
- !$section ? ''
- : $type eq 'item' ? "the $section entry"
- : "the section on $section"
- )
- . ( $page
- ? ( $section ? ' in ' : '' ) . "the $page$page_ext manpage"
- : ' elsewhere in this document'
- );
-
- The --xxccii flag was developed after the --ppbbpp parameters were published so you need to include it separately.
-
- OOnnee--lliinnee bblloocckkss
- There are a few points to note regarding one-line blocks. A one-line block is something like this,
-
- where the contents within the curly braces is short enough to fit on a single line.
-
- With few exceptions, perltidy retains existing one-line blocks, if it is possible within the line-length
- constraint, but it does not attempt to form new ones. In other words, perltidy will try to follow the one-
- line block style of the input file.
-
- If an existing one-line block is longer than the maximum line length, however, it will be broken into
- multiple lines. When this happens, perltidy checks for and adds any optional terminating semicolon (unless
- the --nnaasscc option is used) if the block is a code block.
-
- The main exception is that perltidy will attempt to form new one-line blocks following the keywords "map",
- "eval", and "sort", because these code blocks are often small and most clearly displayed in a single line.
-
- One-line block rules can conflict with the cuddled-else option. When the cuddled-else option is used,
- perltidy retains existing one-line blocks, even if they do not obey cuddled-else formatting.
-
- Occasionally, when one-line blocks get broken because they exceed the available line length, the formatting
- will violate the requested brace style. If this happens, reformatting the script a second time should
- correct the problem.
-
- Sometimes it might be desirable to convert a script to have one-line blocks whenever possible. Although
- there is currently no flag for this, a simple workaround is to execute perltidy twice, once with the flag
- --nnooaadddd--nneewwlliinneess and then once again with normal parameters, like this:
-
- cat infile | perltidy -nanl | perltidy >outfile
-
- When executed on this snippet
-
- if ( $? == -1 ) {
- die "failed to execute: $!\n";
- }
- if ( $? == -1 ) {
- print "Had enough.\n";
- die "failed to execute: $!\n";
- }
-
- the result is
-
- if ( $? == -1 ) { die "failed to execute: $!\n"; }
- if ( $? == -1 ) {
- print "Had enough.\n";
- die "failed to execute: $!\n";
- }
-
- This shows that blocks with a single statement become one-line blocks.
-
- --oollbbss==nn, ----oonnee--lliinnee--bblloocckk--sseemmiiccoolloonnss==nn
- This flag controls the placement of semicolons at the end of one-line blocks. Semicolons are optional
- before a closing block brace, and frequently they are omitted at the end of a one-line block containing just
- a single statement. By default, perltidy follows the input file regarding these semicolons, but this
- behavior can be controlled by this flag. The values of n are:
-
- n=0 remove terminal semicolons in one-line blocks having a single statement
- n=1 stable; keep input file placement of terminal semicolons [DEFAULT ]
- n=2 add terminal semicolons in all one-line blocks
-
- Note that the nn==22 option has no effect if adding semicolons is prohibited with the --nnaasscc flag. Also not
- that while nn==22 adds missing semicolons to all one-line blocks, regardless of complexity, the nn==00 option only
- removes ending semicolons which terminate one-line blocks containing just one semicolon. So these two
- options are not exact inverses.
-
- --oollbbnn==nn, ----oonnee--lliinnee--bblloocckk--nneessttiinngg==nn
- 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.
-
- foreach (@list) { if ($_ eq $asked_for) { last } ++$found }
-
- 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:
-
- n=0 break nested one-line blocks into multiple lines [DEFAULT]
- n=1 stable: keep existing nested-one line blocks intact
-
- For the above example, the default formatting (--oollbbnn==00) is
-
- foreach (@list) {
- if ( $_ eq $asked_for ) { last }
- ++$found;
- }
-
- If the parameter --oollbbnn==11 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.
-
- CCoonnttrroolllliinngg VVeerrttiiccaall AAlliiggnnmmeenntt
- Vertical alignment refers to lining up certain symbols in a list of consecutive similar lines to improve
- readability. For example, the "fat commas" are aligned in the following statement:
-
- $data = $pkg->new(
- PeerAddr => join( ".", @port[ 0 .. 3 ] ),
- PeerPort => $port[4] * 256 + $port[5],
- Proto => 'tcp'
- );
-
- Vertical alignment can be completely turned off using --nnoovvaalliiggnn, 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.
-
- %option_range = (
- 'format' => [ 'tidy', 'html', 'user' ],
- 'output-line-ending' => [ 'dos', 'win', 'mac', 'unix' ],
- 'character-encoding' => [ 'none', 'utf8' ],
-
- 'block-brace-tightness' => [ 0, 2 ],
- 'brace-tightness' => [ 0, 2 ],
- 'paren-tightness' => [ 0, 2 ],
- 'square-bracket-tightness' => [ 0, 2 ],
- );
-
- Vertical alignment is implemented by locally increasing an existing blank space to produce alignment with an
- adjacent line. It cannot occur if there is no blank space to increase. So if a particular space is removed by
- one of the existing controls then vertical alignment cannot occur. Likewise, if a space is added with one of the
- controls, then vertical alignment might occur.
-
- For example,
-
- # perltidy -nwls='=>'
- $data = $pkg->new(
- PeerAddr=> join( ".", @port[ 0 .. 3 ] ),
- PeerPort=> $port[4] * 256 + $port[5],
- Proto=> 'tcp'
- );
-
- OOtthheerr CCoonnttrroollss
- DDeelleettiinngg sseelleecctteedd tteexxtt
- Perltidy can selectively delete comments and/or pod documentation. The command --ddaacc or
- ----ddeelleettee--aallll--ccoommmmeennttss will delete all comments aanndd all pod documentation, leaving just code and any leading
- system control lines.
-
- The command --ddpp or ----ddeelleettee--ppoodd will remove all pod documentation (but not comments).
-
- Two commands which remove comments (but not pod) are: --ddbbcc or ----ddeelleettee--bblloocckk--ccoommmmeennttss and --ddsscc or
- ----ddeelleettee--ssiiddee--ccoommmmeennttss. (Hanging side comments will be deleted with side comments here.)
-
- The negatives of these commands also work, and are the defaults. When block comments are deleted, any
- leading 'hash-bang' will be retained. Also, if the --xx flag is used, any system commands before a leading
- hash-bang will be retained (even if they are in the form of comments).
-
- WWrriittiinngg sseelleecctteedd tteexxtt ttoo aa ffiillee
- When perltidy writes a formatted text file, it has the ability to also send selected text to a file with a
- _._T_E_E extension. This text can include comments and pod documentation.
-
- The command --ttaacc or ----tteeee--aallll--ccoommmmeennttss will write all comments aanndd all pod documentation.
-
- The command --ttpp or ----tteeee--ppoodd will write all pod documentation (but not comments).
-
- The commands which write comments (but not pod) are: --ttbbcc or ----tteeee--bblloocckk--ccoommmmeennttss and --ttsscc or
- ----tteeee--ssiiddee--ccoommmmeennttss. (Hanging side comments will be written with side comments here.)
-
- The negatives of these commands also work, and are the defaults.
-
- UUssiinngg aa _.._pp_ee_rr_ll_tt_ii_dd_yy_rr_cc ccoommmmaanndd ffiillee
- If you use perltidy frequently, you probably won't be happy until you create a _._p_e_r_l_t_i_d_y_r_c file to avoid
- typing commonly-used parameters. Perltidy will first look in your current directory for a command file
- named _._p_e_r_l_t_i_d_y_r_c. If it does not find one, it will continue looking for one in other standard locations.
-
- These other locations are system-dependent, and may be displayed with the command "perltidy -dpro". Under
- Unix systems, it will first look for an environment variable PPEERRLLTTIIDDYY. Then it will look for a _._p_e_r_l_t_i_d_y_r_c
- file in the home directory, and then for a system-wide file _/_u_s_r_/_l_o_c_a_l_/_e_t_c_/_p_e_r_l_t_i_d_y_r_c, and then it will look
- for _/_e_t_c_/_p_e_r_l_t_i_d_y_r_c. Note that these last two system-wide files do not have a leading dot. Further system-
- dependent information will be found in the INSTALL file distributed with perltidy.
-
- Under Windows, perltidy will also search for a configuration file named perltidy.ini since Windows does not
- allow files with a leading period (.). Use "perltidy -dpro" to see the possible locations for your system.
- An example might be _C_:_\_D_o_c_u_m_e_n_t_s _a_n_d _S_e_t_t_i_n_g_s_\_A_l_l _U_s_e_r_s_\_p_e_r_l_t_i_d_y_._i_n_i.
-
- Another option is the use of the PERLTIDY environment variable. The method for setting environment
- variables depends upon the version of Windows that you are using. Instructions for Windows 95 and later
- versions can be found here:
-
- http://www.netmanage.com/000/20021101_005_tcm21-6336.pdf
-
- Under Windows NT / 2000 / XP the PERLTIDY 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. Ex.
- PERLTIDY=C:\Documents and Settings\perltidy.ini
-
- The configuration 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. 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.
-
- Here is an example of a _._p_e_r_l_t_i_d_y_r_c file:
-
- # This is a simple of a .perltidyrc configuration file
- # This implements a highly spaced style
- -se # errors to standard error output
- -w # show all warnings
- -bl # braces on new lines
- -pt=0 # parens not tight at all
- -bt=0 # braces not tight
- -sbt=0 # square brackets not tight
-
- The parameters in the _._p_e_r_l_t_i_d_y_r_c file are installed first, so any parameters given on the command line will
- have priority over them.
-
- To avoid confusion, perltidy ignores any command in the .perltidyrc file which would cause some kind of dump
- and an exit. These are:
-
- -h -v -ddf -dln -dop -dsn -dtt -dwls -dwrs -ss
-
- There are several options may be helpful in debugging a _._p_e_r_l_t_i_d_y_r_c file:
-
- +o A very helpful command is ----dduummpp--pprrooffiillee or --ddpprroo. It writes a list of all configuration filenames
- tested to standard output, and if a file is found, it dumps the content to standard output before
- exiting. So, to find out where perltidy looks for its configuration files, and which one if any it
- selects, just enter
-
- perltidy -dpro
-
- +o It may be simplest to develop and test configuration files with alternative names, and invoke them with
- --pprroo==ffiilleennaammee on the command line. Then rename the desired file to _._p_e_r_l_t_i_d_y_r_c when finished.
-
- +o The parameters in the _._p_e_r_l_t_i_d_y_r_c file can be switched off with the --nnpprroo option.
-
- +o The commands ----dduummpp--ooppttiioonnss, ----dduummpp--ddeeffaauullttss, ----dduummpp--lloonngg--nnaammeess, and ----dduummpp--sshhoorrtt--nnaammeess, all described
- below, may all be helpful.
-
- CCrreeaattiinngg aa nneeww aabbbbrreevviiaattiioonn
- A special notation is available for use in a _._p_e_r_l_t_i_d_y_r_c file for creating an abbreviation for a group of
- options. This can be used to create a shorthand for one or more styles which are frequently, but not
- always, used. The notation is to group the options within curly braces which are preceded by the name of
- the alias (without leading dashes), like this:
-
- newword {
- -opt1
- -opt2
- }
-
- where nneewwwwoorrdd is the abbreviation, and oopptt11, etc, are existing parameters _o_r _o_t_h_e_r _a_b_b_r_e_v_i_a_t_i_o_n_s. The main
- syntax requirement is that the new abbreviation along with its opening curly brace must begin on a new line.
- Space before and after the curly braces is optional.
-
- For a specific example, the following line
-
- oneliner { --maximum-line-length=0 --noadd-newlines --noadd-terminal-newline}
-
- or equivalently with abbreviations
-
- oneliner { -l=0 -nanl -natnl }
-
- could be placed in a _._p_e_r_l_t_i_d_y_r_c file to temporarily override the maximum line length with a large value, to
- temporarily prevent new line breaks from being added, and to prevent an extra newline character from being
- added the file. All other settings in the _._p_e_r_l_t_i_d_y_r_c file still apply. Thus it provides a way to format a
- long 'one liner' when perltidy is invoked with
-
- perltidy --oneliner ...
-
- (Either "-oneliner" or "--oneliner" may be used).
-
- Skipping leading non-perl commands with --xx or ----llooookk--ffoorr--hhaasshh--bbaanngg
- If your script has leading lines of system commands or other text which are not valid perl code, and which
- are separated from the start of the perl code by a "hash-bang" line, ( a line of the form "#!...perl" ), you
- must use the --xx flag to tell perltidy not to parse and format any lines before the "hash-bang" line. This
- option also invokes perl with a -x flag when checking the syntax. This option was originally added to allow
- perltidy to parse interactive VMS scripts, but it should be used for any script which is normally invoked
- with "perl -x".
-
- Please note: do not use this flag unless you are sure your script needs it. Parsing errors can occur if it
- does not have a hash-bang, or, for example, if the actual first hash-bang is in a here-doc. In that case a
- parsing error will occur because the tokenization will begin in the middle of the here-doc.
-
- MMaakkiinngg aa ffiillee uunnrreeaaddaabbllee
- The goal of perltidy is to improve the readability of files, but there are two commands which have the
- opposite effect, ----mmaannggllee and ----eexxttrruuddee. They are actually merely aliases for combinations of other
- parameters. Both of these strip all possible whitespace, but leave comments and pod documents, so that they
- are essentially reversible. The difference between these is that ----mmaannggllee puts the fewest possible line
- breaks in a script while ----eexxttrruuddee puts the maximum possible. Note that these options do not provided any
- meaningful obfuscation, because perltidy can be used to reformat the files. They were originally developed
- to help test the tokenization logic of perltidy, but they have other uses. One use for ----mmaannggllee is the
- following:
-
- perltidy --mangle myfile.pl -st | perltidy -o myfile.pl.new
-
- This will form the maximum possible number of one-line blocks (see next section), and can sometimes help
- clean up a badly formatted script.
-
- A similar technique can be used with ----eexxttrruuddee instead of ----mmaannggllee to make the minimum number of one-line
- blocks.
-
- Another use for ----mmaannggllee is to combine it with --ddaacc to reduce the file size of a perl script.
-
- DDeebbuuggggiinngg
- The following flags are available for debugging:
-
- ----dduummpp--ccuuddddlleedd--bblloocckk--lliisstt or --ddccbbll will dump to standard output the internal hash of cuddled block types
- created by a --ccuuddddlleedd--bblloocckk--lliisstt input string.
-
- ----dduummpp--ddeeffaauullttss or --ddddff will write the default option set to standard output and quit
-
- ----dduummpp--pprrooffiillee or --ddpprroo will write the name of the current configuration file and its contents to standard
- output and quit.
-
- ----dduummpp--ooppttiioonnss or --ddoopp will write current option set to standard output and quit.
-
- ----dduummpp--lloonngg--nnaammeess or --ddllnn will write all command line long names (passed to Get_options) to standard output
- and quit.
-
- ----dduummpp--sshhoorrtt--nnaammeess or --ddssnn will write all command line short names to standard output and quit.
-
- ----dduummpp--ttookkeenn--ttyyppeess or --ddtttt will write a list of all token types to standard output and quit.
-
- ----dduummpp--wwaanntt--lleefftt--ssppaaccee or --ddwwllss will write the hash %want_left_space to standard output and quit. See the
- section on controlling whitespace around tokens.
-
- ----dduummpp--wwaanntt--rriigghhtt--ssppaaccee or --ddwwrrss will write the hash %want_right_space to standard output and quit. See
- the section on controlling whitespace around tokens.
-
- ----nnoo--mmeemmooiizzee or --nnmmeemm will turn of memoizing. Memoization can reduce run time when running perltidy
- repeatedly in a single process. It is on by default but can be deactivated for testing with --nnmmeemm.
-
- ----nnoo--ttiimmeessttaammpp or --nnttss will eliminate any time stamps in output files to prevent differences in dates from
- causing test installation scripts to fail. There are just a couple of places where timestamps normally
- occur. One is in the headers of html files, and another is when the --ccssccww option is selected. The default is
- to allow timestamps (----ttiimmeessttaammpp or --ttss).
-
- ----ffiillee--ssiizzee--oorrddeerr or --ffssoo 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.
-
- ----mmaaxxiimmuumm--ffiillee--ssiizzee--mmbb==nn or --mmaaxxffss==nn specifies the maximum file size in megabytes that perltidy will attempt
- to format. This parameter is provided to avoid causing system problems by accidentally attempting to format
- an extremely large data file. Most perl scripts are less than about 2 MB in size. The integer nn has a
- default value of 10, so perltidy will skip formatting files which have a size greater than 10 MB. The
- command to increase the limit to 20 MB for example would be
-
- perltidy -maxfs=20
-
- This only applies to files specified by filename on the command line.
-
- ----mmaaxxiimmuumm--lleevveell--eerrrroorrss==nn or --mmaaxxllee==nn specifies the maximum number of indentation level errors are allowed
- before perltidy skips formatting and just outputs a file verbatim. The default is nn==11. This means that if
- the final indentation of a script differs from the starting indentation by more than 1 levels, the file will
- be output verbatim. To avoid formatting if there are any indentation level errors use -maxle=0. To skip
- this check you can either set n equal to a large number, such as nn==110000, or set nn==--11.
-
- For example, the following script has level error of 3 and will be output verbatim
-
- Input and default output:
- {{{
-
- perltidy -maxle=100
- {
- {
- {
-
- ----mmaaxxiimmuumm--uunneexxppeecctteedd--eerrrroorrss==nn or --mmaaxxuuee==nn specifies the maximum number of unexpected tokenization errors are
- allowed before formatting is skipped and a script is output verbatim. The intention is to avoid
- accidentally formatting a non-perl script, such as an html file for example. This check can be turned off
- by setting nn==00.
-
- A recommended value is nn==33. However, the default is nn==00 (skip this check) to avoid causing problems with
- scripts which have extended syntaxes.
-
- --DDEEBBUUGG will write a file with extension _._D_E_B_U_G for each input file showing the tokenization of all lines of
- code.
-
- WWoorrkkiinngg wwiitthh MMaakkeeMMaakkeerr,, AAuuttooLLooaaddeerr aanndd SSeellffLLooaaddeerr
- The first $VERSION line of a file which might be eval'd by MakeMaker is passed through unchanged except for
- indentation. Use ----nnooppaassss--vveerrssiioonn--lliinnee, or --nnppvvll, to deactivate this feature.
-
- If the AutoLoader module is used, perltidy will continue formatting code after seeing an __END__ line. Use
- ----nnoollooookk--ffoorr--aauuttoollooaaddeerr, or --nnllaall, to deactivate this feature.
-
- Likewise, if the SelfLoader module is used, perltidy will continue formatting code after seeing a __DATA__
- line. Use ----nnoollooookk--ffoorr--sseellffllooaaddeerr, or --nnllssll, to deactivate this feature.
-
- WWoorrkkiinngg aarroouunndd pprroobblleemmss wwiitthh oollddeerr vveerrssiioonn ooff PPeerrll
- Perltidy contains a number of rules which help avoid known subtleties and problems with older versions of
- perl, and these rules always take priority over whatever formatting flags have been set. For example,
- perltidy will usually avoid starting a new line with a bareword, because this might cause problems if "use
- strict" is active.
-
- There is no way to override these rules.
-
-HHTTMMLL OOPPTTIIOONNSS
- The --hhttmmll master switch
- The flag --hhttmmll causes perltidy to write an html file with extension _._h_t_m_l. So, for example, the following
- command
-
- perltidy -html somefile.pl
-
- will produce a syntax-colored html file named _s_o_m_e_f_i_l_e_._p_l_._h_t_m_l which may be viewed with a browser.
-
- PPlleeaassee NNoottee: In this case, perltidy does not do any formatting to the input file, and it does not write a
- formatted file with extension _._t_d_y. This means that two perltidy runs are required to create a fully
- reformatted, html copy of a script.
-
- The --pprree flag for code snippets
- When the --pprree flag is given, only the pre-formatted section, within the <PRE> and </PRE> tags, will be
- output. This simplifies inclusion of the output in other files. The default is to output a complete web
- page.
-
- The --nnnnnn flag for line numbering
- When the --nnnnnn flag is given, the output lines will be numbered.
-
- The --ttoocc, or ----hhttmmll--ttaabbllee--ooff--ccoonntteennttss flag
- By default, a table of contents to packages and subroutines will be written at the start of html output.
- Use --nnttoocc to prevent this. This might be useful, for example, for a pod document which contains a number of
- unrelated code snippets. This flag only influences the code table of contents; it has no effect on any
- table of contents produced by pod2html (see next item).
-
- The --ppoodd, or ----ppoodd22hhttmmll flag
- There are two options for formatting pod documentation. The default is 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
- "FILES". Also, Pod::Html creates temporary files for its cache.
-
- NOTE: Perltidy counts the number of "=cut" lines, and either moves the pod text to the top of the html file
- if there is one "=cut", or leaves the pod text in its original order (interleaved with code) otherwise.
-
- Most of the flags accepted by pod2html may be included in the perltidy command line, and they will be passed
- to pod2html. In some cases, the flags have a prefix "pod" to emphasize that they are for the pod2html, and
- this prefix will be removed before they are passed to pod2html. The flags which have the additional "pod"
- prefix are:
-
- --[no]podheader --[no]podindex --[no]podrecurse --[no]podquiet
- --[no]podverbose --podflush
-
- The flags which are unchanged from their use in pod2html are:
-
- --backlink=s --cachedir=s --htmlroot=s --libpods=s --title=s
- --podpath=s --podroot=s
-
- where 's' is an appropriate character string. Not all of these flags are available in older versions of
- Pod::Html. See your Pod::Html documentation for more information.
-
- The alternative, indicated with --nnppoodd, is not to use Pod::Html, but rather to format pod text in italics (or
- whatever the stylesheet indicates), without special html markup. This is useful, for example, if pod is
- being used as an alternative way to write comments.
-
- The --ffrrmm, or ----ffrraammeess flag
- By default, a single html output file is produced. This can be changed with the --ffrrmm option, which creates
- a frame holding a table of contents in the left panel and the source code in the right side. This simplifies
- code browsing. Assume, for example, that the input file is _M_y_M_o_d_u_l_e_._p_m. Then, for default file extension
- choices, these three files will be created:
-
- MyModule.pm.html - the frame
- MyModule.pm.toc.html - the table of contents
- MyModule.pm.src.html - the formatted source code
-
- Obviously this file naming scheme requires that output be directed to a real file (as opposed to, say,
- standard output). If this is not the case, or if the file extension is unknown, the --ffrrmm option will be
- ignored.
-
- The --tteexxtt==ss, or ----hhttmmll--ttoocc--eexxtteennssiioonn flag
- Use this flag to specify the extra file extension of the table of contents file when html frames are used.
- The default is "toc". See "Specifying File Extensions".
-
- The --sseexxtt==ss, or ----hhttmmll--ssrrcc--eexxtteennssiioonn flag
- Use this flag to specify the extra file extension of the content file when html frames are used. The
- default is "src". See "Specifying File Extensions".
-
- The --hheenntt, or ----hhttmmll--eennttiittiieess flag
- This flag controls the use of Html::Entities for html formatting. By default, the module Html::Entities is
- used to encode special symbols. This may not be the right thing for some browser/language combinations.
- Use --nohtml-entities or -nhent to prevent this.
-
- SSttyyllee SShheeeettss
- Style sheets make it very convenient to control and adjust the appearance of html pages. The default
- behavior is to write a page of html with an embedded style sheet.
-
- An alternative to an embedded style sheet is to create a page with a link to an external style sheet. This
- is indicated with the --ccssss==ffiilleennaammee, where the external style sheet is _f_i_l_e_n_a_m_e. The external style sheet
- _f_i_l_e_n_a_m_e will be created if and only if it does not exist. This option is useful for controlling multiple
- pages from a single style sheet.
-
- To cause perltidy to write a style sheet to standard output and exit, use the --ssss, or ----ssttyylleesshheeeett, flag.
- This is useful if the style sheet could not be written for some reason, such as if the --pprree flag was used.
- Thus, for example,
-
- perltidy -html -ss >mystyle.css
-
- will write a style sheet with the default properties to file _m_y_s_t_y_l_e_._c_s_s.
-
- The use of style sheets is encouraged, but a web page without a style sheets can be created with the flag
- --nnssss. Use this option if you must to be sure that older browsers (roughly speaking, versions prior to 4.0
- of Netscape Navigator and Internet Explorer) can display the syntax-coloring of the html files.
-
- CCoonnttrroolllliinngg HHTTMMLL pprrooppeerrttiieess
- Note: It is usually more convenient to accept the default properties and then edit the stylesheet which is
- produced. However, this section shows how to control the properties with flags to perltidy.
-
- Syntax colors may be changed from their default values by flags of the either the long form,
- --hhttmmll--ccoolloorr--xxxxxxxxxxxx==nn, or more conveniently the short form, --hhccxx==nn, where xxxxxxxxxxxx is one of the following
- words, and xx is the corresponding abbreviation:
-
- Token Type xxxxxx x
- ---------- -------- --
- comment comment c
- number numeric n
- identifier identifier i
- bareword, function bareword w
- keyword keyword k
- quite, pattern quote q
- here doc text here-doc-text h
- here doc target here-doc-target hh
- punctuation punctuation pu
- parentheses paren p
- structural braces structure s
- semicolon semicolon sc
- colon colon co
- comma comma cm
- label label j
- sub definition name subroutine m
- pod text pod-text pd
-
- A default set of colors has been defined, but they may be changed by providing values to any of the
- following parameters, where nn is either a 6 digit hex RGB color value or an ascii name for a color, such as
- 'red'.
-
- To illustrate, the following command will produce an html file _s_o_m_e_f_i_l_e_._p_l_._h_t_m_l with "aqua" keywords:
-
- perltidy -html -hck=00ffff somefile.pl
-
- and this should be equivalent for most browsers:
-
- perltidy -html -hck=aqua somefile.pl
-
- Perltidy merely writes any non-hex names that it sees in the html file. The following 16 color names are
- defined in the HTML 3.2 standard:
-
- black => 000000,
- silver => c0c0c0,
- gray => 808080,
- white => ffffff,
- maroon => 800000,
- red => ff0000,
- purple => 800080,
- fuchsia => ff00ff,
- green => 008000,
- lime => 00ff00,
- olive => 808000,
- yellow => ffff00
- navy => 000080,
- blue => 0000ff,
- teal => 008080,
- aqua => 00ffff,
-
- Many more names are supported in specific browsers, but it is safest to use the hex codes for other colors.
- Helpful color tables can be located with an internet search for "HTML color tables".
-
- Besides color, two other character attributes may be set: bold, and italics. To set a token type to use
- bold, use the flag ----hhttmmll--bboolldd--xxxxxxxxxxxx or --hhbbxx, where xxxxxxxxxxxx or xx are the long or short names from the above
- table. Conversely, to set a token type to NOT use bold, use ----nnoohhttmmll--bboolldd--xxxxxxxxxxxx or --nnhhbbxx.
-
- Likewise, to set a token type to use an italic font, use the flag ----hhttmmll--iittaalliicc--xxxxxxxxxxxx or --hhiixx, where again
- xxxxxxxxxxxx or xx are the long or short names from the above table. And to set a token type to NOT use italics,
- use ----nnoohhttmmll--iittaalliicc--xxxxxxxxxxxx or --nnhhiixx.
-
- For example, to use bold braces and lime color, non-bold, italics keywords the following command would be
- used:
-
- perltidy -html -hbs -hck=00FF00 -nhbk -hik somefile.pl
-
- The background color can be specified with ----hhttmmll--ccoolloorr--bbaacckkggrroouunndd==nn, or --hhccbbgg==nn for short, where n is a 6
- character hex RGB value. The default color of text is the value given to ppuunnccttuuaattiioonn, which is black as a
- default.
-
- Here are some notes and hints:
-
- 1. If you find a preferred set of these parameters, you may want to create a _._p_e_r_l_t_i_d_y_r_c file containing
- them. See the perltidy man page for an explanation.
-
- 2. Rather than specifying values for these parameters, it is probably easier to accept the defaults and then
- edit a style sheet. The style sheet contains comments which should make this easy.
-
- 3. The syntax-colored html files can be very large, so it may be best to split large files into smaller
- pieces to improve download times.
-
-SSOOMMEE CCOOMMMMOONN IINNPPUUTT CCOONNVVEENNTTIIOONNSS
- SSppeecciiffyyiinngg BBlloocckk TTyyppeess
- Several parameters which refer to code block types may be customized by also specifying an associated list of
- block types. The type of a block is the name of the keyword which introduces that block, such as iiff, eellssee, or
- ssuubb. An exception is a labeled block, which has no keyword, and should be specified with just a colon. To
- specify all blocks use ''**''.
-
- The keyword ssuubb indicates a named sub. For anonymous subs, use the special keyword aassuubb.
-
- For example, the following parameter specifies "sub", labels, "BEGIN", and "END" blocks:
-
- -cscl="sub : BEGIN END"
-
- (the meaning of the -cscl parameter is described above.) Note that quotes are required around the list of block
- types because of the spaces. For another example, the following list specifies all block types for vertical
- tightness:
-
- -bbvtl='*'
-
- SSppeecciiffyyiinngg FFiillee EExxtteennssiioonnss
- Several parameters allow default file extensions to be overridden. For example, a backup file extension may be
- specified with --bbeexxtt==eexxtt, where eexxtt 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 "ext"
- begins with "A-Z", "a-z", or "0-9", then it will be appended to the filename with an intermediate '.' (or
- perhaps a '_' on VMS systems). Otherwise, it will be appended directly.
-
- For example, suppose the file is _s_o_m_e_f_i_l_e_._p_l. For "-bext=old", a '.' is added to give _s_o_m_e_f_i_l_e_._p_l_._o_l_d. For
- "-bext=.old", no additional '.' is added, so again the backup file is _s_o_m_e_f_i_l_e_._p_l_._o_l_d. For "-bext=~", then no
- dot is added, and the backup file will be _s_o_m_e_f_i_l_e_._p_l_~ .
-
-SSWWIITTCCHHEESS WWHHIICCHH MMAAYY BBEE NNEEGGAATTEEDD
- The following list shows all short parameter names which allow a prefix 'n' to produce the negated form:
-
- D anl asbl asc ast asu atnl aws b baa
- baao bar bbao bbb bbc bbs bl bli boa boc
- bok bol bom bos bot cblx ce conv cs csc
- cscb cscw dac dbc dcbl dcsc ddf dln dnl dop
- dp dpro dsc dsm dsn dtt dwls dwrs dws f
- fll fpva frm fs fso gcs hbc hbcm hbco hbh
- hbhh hbi hbj hbk hbm hbn hbp hbpd hbpu hbq
- hbs hbsc hbv hbw hent hic hicm hico hih hihh
- hii hij hik him hin hip hipd hipu hiq his
- hisc hiv hiw hsc html ibc icb icp iob isbc
- iscl kgb kgbd kgbi kis lal log lop lp lsl
- mem nib ohbr okw ola olc oll olq opr opt
- osbc osbr otr ple pod pvl q sac sbc sbl
- scbb schb scp scsb sct se sfp sfs skp sob
- sobb sohb sop sosb sot ssc st sts t tac
- tbc toc tp tqw trp ts tsc tso vmll w
- wn x xci xs
-
- Equivalently, the prefix 'no' or 'no-' on the corresponding long names may be used.
-
-LLIIMMIITTAATTIIOONNSS
- PPaarrssiinngg LLiimmiittaattiioonnss
- Perltidy should work properly on most perl scripts. It does a lot of self-checking, but still, it is
- possible that an error could be introduced and go undetected. Therefore, it is essential to make careful
- backups and to test reformatted scripts.
-
- The main current limitation is that perltidy does not scan modules included with 'use' statements. This
- makes it necessary to guess the context of any bare words introduced by such modules. Perltidy has good
- guessing algorithms, but they are not infallible. When it must guess, it leaves a message in the log file.
-
- If you encounter a bug, please report it.
-
- WWhhaatt ppeerrllttiiddyy ddooeess nnoott ppaarrssee aanndd ffoorrmmaatt
- Perltidy indents but does not reformat comments and "qw" quotes. Perltidy does not in any way modify the
- contents of here documents or quoted text, even if they contain source code. (You could, however, reformat
- them separately). Perltidy does not format 'format' sections in any way. And, of course, it does not
- modify pod documents.
-
-FFIILLEESS
- TTeemmppoorraarryy ffiilleess
- Under the -html option with the default --pod2html flag, a temporary file is required to pass text to
- Pod::Html. Unix systems will try to use the POSIX ttmmppnnaamm(()) function. Otherwise the file _p_e_r_l_t_i_d_y_._T_M_P will
- be temporarily created in the current working directory.
-
- SSppeecciiaall ffiilleess wwhheenn ssttaannddaarrdd iinnppuutt iiss uusseedd
- When standard input is used, the log file, if saved, is _p_e_r_l_t_i_d_y_._L_O_G, and any errors are written to
- _p_e_r_l_t_i_d_y_._E_R_R unless the --ssee flag is set. These are saved in the current working directory.
-
- FFiilleess oovveerrwwrriitttteenn
- The following file extensions are used by perltidy, and files with these extensions may be overwritten or
- deleted: _._E_R_R, _._L_O_G, _._T_E_E, and/or _._t_d_y, _._h_t_m_l, and _._b_a_k, depending on the run type and settings.
-
- FFiilleess eexxtteennssiioonnss lliimmiittaattiioonnss
- Perltidy does not operate on files for which the run could produce a file with a duplicated file extension.
- These extensions include _._L_O_G, _._E_R_R, _._T_E_E, and perhaps _._t_d_y and _._b_a_k, depending on the run type. The
- purpose of this rule is to prevent generating confusing filenames such as _s_o_m_e_f_i_l_e_._t_d_y_._t_d_y_._t_d_y.
-
-EERRRROORR HHAANNDDLLIINNGG
- An exit value of 0, 1, or 2 is returned by perltidy to indicate the status of the result.
-
- A exit value of 0 indicates that perltidy ran to completion with no error messages.
-
- A non-zero exit value indicates some kind of problem was detected.
-
- 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.
-
- 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.
-
-SSEEEE AALLSSOO
- ppeerrllssttyyllee(1), PPeerrll::::TTiiddyy(3)
-
-IINNSSTTAALLLLAATTIIOONN
- 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'.
-
-VVEERRSSIIOONN
- This man page documents perltidy version 20210717
-
-BBUUGG RREEPPOORRTTSS
- A list of current bugs and issues can be found at the CPAN site
- <https://rt.cpan.org/Public/Dist/Display.html?Name=Perl-Tidy>
-
- To report a new bug or problem, use the link on this page.
-
- The source code repository is at <https://github.com/perltidy/perltidy>.
-
-CCOOPPYYRRIIGGHHTT
- Copyright (c) 2000-2021 by Steve Hancock
-
-LLIICCEENNSSEE
- This package is free software; you can redistribute it and/or modify it under the terms of the "GNU General
- Public License".
-
- Please refer to the file "COPYING" for details.
-
-DDIISSCCLLAAIIMMEERR
- This package is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the
- implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
-
- See the "GNU General Public License" for more details.
-
-perl v5.22.1 2021-07-15 PERLTIDY(1)