From: Steve Hancock Date: Wed, 8 Sep 2021 14:27:59 +0000 (-0700) Subject: make -novalign apply to all side comments X-Git-Tag: 20210717.02~1 X-Git-Url: https://git.donarmstrong.com/?a=commitdiff_plain;h=cabe3fcd393ec151113770ffbd5dfd74eaf27af9;p=perltidy.git make -novalign apply to all side comments --- diff --git a/lib/Perl/Tidy/VerticalAligner.pm b/lib/Perl/Tidy/VerticalAligner.pm index 3c453227..be6e5a25 100644 --- a/lib/Perl/Tidy/VerticalAligner.pm +++ b/lib/Perl/Tidy/VerticalAligner.pm @@ -4280,7 +4280,7 @@ sub is_good_side_comment_column { my $short_diff = SC_LONG_LINE_DIFF / ( 1 + $alev_diff * $num5 ); goto FORGET - if ( $line_diff > $short_diff ); + if ( $line_diff > $short_diff ) || !$self->[_rOpts_valign_]; # RULE3: Forget a side comment if this line is at lower level and # ends a block diff --git a/side-comm b/side-comm new file mode 100644 index 00000000..0ff46c97 --- /dev/null +++ b/side-comm @@ -0,0 +1,3827 @@ +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)