From 895c3b9559b5cf745f3cfe57eeff038f58768457 Mon Sep 17 00:00:00 2001 From: Steve Hancock Date: Wed, 8 Sep 2021 07:45:17 -0700 Subject: [PATCH] bump version to 20210717.02 --- CHANGES.md | 2 +- MANIFEST | 1 + bin/perltidy | 2 +- lib/Perl/Tidy.pm | 2 +- lib/Perl/Tidy.pod | 2 +- lib/Perl/Tidy/Debugger.pm | 2 +- lib/Perl/Tidy/DevNull.pm | 2 +- lib/Perl/Tidy/Diagnostics.pm | 2 +- lib/Perl/Tidy/FileWriter.pm | 2 +- lib/Perl/Tidy/Formatter.pm | 2 +- lib/Perl/Tidy/HtmlWriter.pm | 2 +- lib/Perl/Tidy/IOScalar.pm | 2 +- lib/Perl/Tidy/IOScalarArray.pm | 2 +- lib/Perl/Tidy/IndentationItem.pm | 2 +- lib/Perl/Tidy/LineBuffer.pm | 2 +- lib/Perl/Tidy/LineSink.pm | 2 +- lib/Perl/Tidy/LineSource.pm | 2 +- lib/Perl/Tidy/Logger.pm | 2 +- lib/Perl/Tidy/Tokenizer.pm | 2 +- lib/Perl/Tidy/VerticalAligner.pm | 2 +- lib/Perl/Tidy/VerticalAligner/Alignment.pm | 2 +- lib/Perl/Tidy/VerticalAligner/Line.pm | 2 +- side-comm | 3827 -------------------- 23 files changed, 22 insertions(+), 3848 deletions(-) delete mode 100644 side-comm 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 ] 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 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) 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 = ) { - 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 = ) { - 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 , 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', like this: - - #< | _ | ] - | <''> - ] - }; - - #>>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. - - 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='#<{$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 = ) - { - $In .= $File; - $count++; - } - close(FILE); - } - - # perltidy -bli -bbvt=1 - if ( open( FILE, "< $File" ) ) - { while ( $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 - . 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 
 and
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 - - - To report a new bug or problem, use the link on this page. - - The source code repository is at . - -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) -- 2.39.5