--- /dev/null
+PERLTIDY(1) User Contributed Perl Documentation PERLTIDY(1)
+
+N\bNA\bAM\bME\bE
+ perltidy - a perl script indenter and reformatter
+
+S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS
+ perltidy [ options ] file1 file2 file3 ...
+ (output goes to file1.tdy, file2.tdy, file3.tdy, ...)
+ perltidy [ options ] file1 -o outfile
+ perltidy [ options ] file1 -st >outfile
+ perltidy [ options ] <infile >outfile
+
+D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN
+ 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 -\b-h\bht\btm\bml\bl flag. Without this
+ flag, the output is passed through a formatter. The default formatting tries to follow the recommendations in
+ p\bpe\ber\brl\bls\bst\bty\byl\ble\be(1), but it can be controlled in detail with numerous input parameters, which are described in
+ "FORMATTING OPTIONS".
+
+ When the -\b-h\bht\btm\bml\bl flag is given, the output is passed through an HTML formatter which is described in "HTML
+ OPTIONS".
+
+E\bEX\bXA\bAM\bMP\bPL\bLE\bES\bS
+ perltidy somefile.pl
+
+ This will produce a file _\bs_\bo_\bm_\be_\bf_\bi_\bl_\be_\b._\bp_\bl_\b._\bt_\bd_\by containing the script reformatted using the default options, which
+ approximate the style suggested in p\bpe\ber\brl\bls\bst\bty\byl\ble\be(1). The source file _\bs_\bo_\bm_\be_\bf_\bi_\bl_\be_\b._\bp_\bl is unchanged.
+
+ perltidy *.pl
+
+ Execute perltidy on all _\b._\bp_\bl files in the current directory with the default options. The output will be in
+ files with an appended _\b._\bt_\bd_\by extension. For any file with an error, there will be a file with extension _\b._\bE_\bR_\bR.
+
+ perltidy -b file1.pl file2.pl
+
+ Modify _\bf_\bi_\bl_\be_\b1_\b._\bp_\bl and _\bf_\bi_\bl_\be_\b2_\b._\bp_\bl in place, and backup the originals to _\bf_\bi_\bl_\be_\b1_\b._\bp_\bl_\b._\bb_\ba_\bk and _\bf_\bi_\bl_\be_\b2_\b._\bp_\bl_\b._\bb_\ba_\bk. If
+ _\bf_\bi_\bl_\be_\b1_\b._\bp_\bl_\b._\bb_\ba_\bk and/or _\bf_\bi_\bl_\be_\b2_\b._\bp_\bl_\b._\bb_\ba_\bk already exist, they will be overwritten.
+
+ perltidy -b -bext='/' file1.pl file2.pl
+
+ Same as the previous example except that the backup files _\bf_\bi_\bl_\be_\b1_\b._\bp_\bl_\b._\bb_\ba_\bk and _\bf_\bi_\bl_\be_\b2_\b._\bp_\bl_\b._\bb_\ba_\bk will be deleted if there
+ are no errors.
+
+ perltidy -gnu somefile.pl
+
+ Execute perltidy on file _\bs_\bo_\bm_\be_\bf_\bi_\bl_\be_\b._\bp_\bl with a style which approximates the GNU Coding Standards for C programs.
+ The output will be _\bs_\bo_\bm_\be_\bf_\bi_\bl_\be_\b._\bp_\bl_\b._\bt_\bd_\by.
+
+ perltidy -i=3 somefile.pl
+
+ Execute perltidy on file _\bs_\bo_\bm_\be_\bf_\bi_\bl_\be_\b._\bp_\bl, with 3 columns for each level of indentation (-\b-i\bi=\b=3\b3) 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 _\bs_\bo_\bm_\be_\bf_\bi_\bl_\be_\b._\bp_\bl_\b._\bt_\bd_\by.
+
+ 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 _\bs_\bo_\bm_\be_\bf_\bi_\bl_\be_\b._\bp_\bl with all defaults except use "cuddled elses" (-\b-c\bce\be) and a maximum line
+ length of 72 columns (-\b-l\bl=\b=7\b72\b2) instead of the default 80 columns.
+
+ perltidy -g somefile.pl
+
+ Execute perltidy on file _\bs_\bo_\bm_\be_\bf_\bi_\bl_\be_\b._\bp_\bl and save a log file _\bs_\bo_\bm_\be_\bf_\bi_\bl_\be_\b._\bp_\bl_\b._\bL_\bO_\bG 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 _\bs_\bo_\bm_\be_\bf_\bi_\bl_\be_\b._\bp_\bl_\b._\bh_\bt_\bm_\bl containing the script with html markup. The output file will contain
+ an embedded style sheet in the <HEAD> section which may be edited to change the appearance.
+
+ perltidy -html -css=mystyle.css somefile.pl
+
+ This will produce a file _\bs_\bo_\bm_\be_\bf_\bi_\bl_\be_\b._\bp_\bl_\b._\bh_\bt_\bm_\bl containing the script with html markup. This output file will contain
+ a link to a separate style sheet file _\bm_\by_\bs_\bt_\by_\bl_\be_\b._\bc_\bs_\bs. If the file _\bm_\by_\bs_\bt_\by_\bl_\be_\b._\bc_\bs_\bs 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 _\bs_\bo_\bm_\be_\bf_\bi_\bl_\be_\b._\bp_\bl_\b._\bh_\bt_\bm_\bl. 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 _\bm_\by_\bs_\bt_\by_\bl_\be_\b._\bc_\bs_\bs 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
+ _\bm_\by_\bm_\bo_\bd_\bu_\bl_\be_\b._\bp_\bm_\b._\bh_\bt_\bm_\bl (the frame), _\bm_\by_\bm_\bo_\bd_\bu_\bl_\be_\b._\bp_\bm_\b._\bt_\bo_\bc_\b._\bh_\bt_\bm_\bl (the table of contents), and _\bm_\by_\bm_\bo_\bd_\bu_\bl_\be_\b._\bp_\bm_\b._\bs_\br_\bc_\b._\bh_\bt_\bm_\bl (the source
+ code).
+
+O\bOP\bPT\bTI\bIO\bON\bNS\bS -\b- O\bOV\bVE\bER\bRV\bVI\bIE\bEW\bW
+ 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 -\b-o\bol\blq\bq or
+ -\b--\b-o\bou\but\btd\bde\ben\bnt\bt-\b-l\blo\bon\bng\bg-\b-q\bqu\buo\bot\bte\bes\bs. The flag to skip this is -\b-n\bno\bol\blq\bq or -\b--\b-n\bno\boo\bou\but\btd\bde\ben\bnt\bt-\b-l\blo\bon\bng\bg-\b-q\bqu\buo\bot\bte\bes\bs or -\b--\b-n\bno\bo-\b-o\bou\but\btd\bde\ben\bnt\bt-\b-l\blo\bon\bng\bg-\b-q\bqu\buo\bot\bte\bes\bs.
+
+ Options may not be bundled together. In other words, options -\b-q\bq and -\b-g\bg may NOT be entered as -\b-q\bqg\bg.
+
+ Option names may be terminated early as long as they are uniquely identified. For example, instead of
+ -\b--\b-d\bdu\bum\bmp\bp-\b-t\bto\bok\bke\ben\bn-\b-t\bty\byp\bpe\bes\bs, it would be sufficient to enter -\b--\b-d\bdu\bum\bmp\bp-\b-t\bto\bok\bk, or even -\b--\b-d\bdu\bum\bmp\bp-\b-t\bt, to uniquely identify this
+ command.
+
+ I\bI/\b/O\bO c\bco\bon\bnt\btr\bro\bol\bl
+ The following parameters concern the files which are read and written.
+
+ -\b-h\bh, -\b--\b-h\bhe\bel\blp\bp
+ Show summary of usage and exit.
+
+ -\b-o\bo=filename, -\b--\b-o\bou\but\btf\bfi\bil\ble\be=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 -\b-s\bst\bt), the output will go to _\bf_\bi_\bl_\be_\bn_\ba_\bm_\be_\b._\bt_\bd_\by. [Note: -
+ does not redirect to standard output. Use -\b-s\bst\bt instead.]
+
+ -\b-s\bst\bt, -\b--\b-s\bst\bta\ban\bnd\bda\bar\brd\bd-\b-o\bou\but\btp\bpu\but\bt
+ 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, -\b-s\bst\bt, 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 -\b-n\bns\bst\bt or
+ -\b--\b-n\bno\bos\bst\bta\ban\bnd\bda\bar\brd\bd-\b-o\bou\but\btp\bpu\but\bt.
+
+ -\b-s\bse\be, -\b--\b-s\bst\bta\ban\bnd\bda\bar\brd\bd-\b-e\ber\brr\bro\bor\br-\b-o\bou\but\btp\bpu\but\bt
+ If perltidy detects an error when processing file _\bs_\bo_\bm_\be_\bf_\bi_\bl_\be_\b._\bp_\bl, its default behavior is to write error
+ messages to file _\bs_\bo_\bm_\be_\bf_\bi_\bl_\be_\b._\bp_\bl_\b._\bE_\bR_\bR. Use -\b-s\bse\be to cause all error messages to be sent to the standard error
+ output stream instead. This directive may be negated with -\b-n\bns\bse\be. Thus, you may place -\b-s\bse\be in a _\b._\bp_\be_\br_\bl_\bt_\bi_\bd_\by_\br_\bc
+ and override it when desired with -\b-n\bns\bse\be on the command line.
+
+ -\b-o\boe\bex\bxt\bt=ext, -\b--\b-o\bou\but\btp\bpu\but\bt-\b-f\bfi\bil\ble\be-\b-e\bex\bxt\bte\ben\bns\bsi\bio\bon\bn=ext
+ Change the extension of the output file to be _\be_\bx_\bt instead of the default _\bt_\bd_\by (or _\bh_\bt_\bm_\bl in case the --\b-h\bht\btm\bml\bl
+ option is used). See "Specifying File Extensions".
+
+ -\b-o\bop\bpa\bat\bth\bh=path, -\b--\b-o\bou\but\btp\bpu\but\bt-\b-p\bpa\bat\bth\bh=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 _\bp_\ba_\bt_\bh 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 _\b/_\bt_\bm_\bp_\b/_\bs_\bo_\bm_\be_\bf_\bi_\bl_\be_\b._\bp_\bl_\b._\bt_\bd_\by. Otherwise, _\bs_\bo_\bm_\be_\bf_\bi_\bl_\be_\b._\bp_\bl_\b._\bt_\bd_\by will appear in whatever directory contains
+ _\bs_\bo_\bm_\be_\bf_\bi_\bl_\be_\b._\bp_\bl.
+
+ 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 -\b-o\bo=\b=s\bs parameter.
+
+ -\b-b\bb, -\b--\b-b\bba\bac\bck\bku\bup\bp-\b-a\ban\bnd\bd-\b-m\bmo\bod\bdi\bif\bfy\by-\b-i\bin\bn-\b-p\bpl\bla\bac\bce\be
+ Modify the input file or files in-place and save the original with the extension _\b._\bb_\ba_\bk. Any existing _\b._\bb_\ba_\bk
+ file will be deleted. See next item for changing the default backup extension, and for eliminating the
+ backup file altogether.
+
+ A -\b-b\bb flag will be ignored if input is from standard input or goes to standard output, or if the -\b-h\bht\btm\bml\bl flag
+ is set.
+
+ In particular, if you want to use both the -\b-b\bb flag and the -\b-p\bpb\bbp\bp (--perl-best-practices) flag, then you must
+ put a -\b-n\bns\bst\bt flag after the -\b-p\bpb\bbp\bp flag because it contains a -\b-s\bst\bt flag as one of its components, which means
+ that output will go to the standard output stream.
+
+ -\b-b\bbe\bex\bxt\bt=ext, -\b--\b-b\bba\bac\bck\bku\bup\bp-\b-f\bfi\bil\ble\be-\b-e\bex\bxt\bte\ben\bns\bsi\bio\bon\bn=ext
+ This parameter serves two purposes: (1) to change the extension of the backup file to be something other
+ than the default _\b._\bb_\ba_\bk, and (2) to indicate that no backup file should be saved.
+
+ To change the default extension to something other than _\b._\bb_\ba_\bk 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, /\b/, 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
+
+ -\b-w\bw, -\b--\b-w\bwa\bar\brn\bni\bin\bng\bg-\b-o\bou\but\btp\bpu\but\bt
+ Setting -\b-w\bw 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, -\b-n\bnw\bw or -\b--\b-n\bno\bow\bwa\bar\brn\bni\bin\bng\bg-\b-o\bou\but\btp\bpu\but\bt, is not to include these warnings.
+
+ -\b-q\bq, -\b--\b-q\bqu\bui\bie\bet\bt
+ 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 -\b-q\bq flag, any error message may mess up your screen,
+ so be prepared to use your "undo" key.
+
+ -\b-l\blo\bog\bg, -\b--\b-l\blo\bog\bgf\bfi\bil\ble\be
+ Save the _\b._\bL_\bO_\bG file, which has many useful diagnostics. Perltidy always creates a _\b._\bL_\bO_\bG file, but by default
+ it is deleted unless a program bug is suspected. Setting the -\b-l\blo\bog\bg flag forces the log file to be saved.
+
+ -\b-g\bg=\b=n\bn, -\b--\b-l\blo\bog\bgf\bfi\bil\ble\be-\b-g\bga\bap\bp=\b=n\bn
+ 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 -\b-g\bg 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 -\b-g\bg also causes the logfile to be saved, so it is not necessary to also include -\b-l\blo\bog\bg.
+
+ If no -\b-g\bg 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 -\b-g\bg at all.
+
+ -\b-n\bnp\bpr\bro\bo -\b--\b-n\bno\bop\bpr\bro\bof\bfi\bil\ble\be
+ Ignore any _\b._\bp_\be_\br_\bl_\bt_\bi_\bd_\by_\br_\bc command file. Normally, perltidy looks first in your current directory for a
+ _\b._\bp_\be_\br_\bl_\bt_\bi_\bd_\by_\br_\bc 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
+ _\b._\bp_\be_\br_\bl_\bt_\bi_\bd_\by_\br_\bc file is found, it looks for one in your home directory.
+
+ If you set the -\b-n\bnp\bpr\bro\bo flag, perltidy will not look for this file.
+
+ -\b-p\bpr\bro\bo=\b=f\bfi\bil\ble\ben\bna\bam\bme\be or -\b--\b-p\bpr\bro\bof\bfi\bil\ble\be=\b=f\bfi\bil\ble\ben\bna\bam\bme\be
+ 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 _\bt_\be_\bs_\bt_\bc_\bf_\bg to be used instead of the default _\b._\bp_\be_\br_\bl_\bt_\bi_\bd_\by_\br_\bc.
+
+ 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.
+
+ -\b-o\bop\bpt\bt, -\b--\b-s\bsh\bho\bow\bw-\b-o\bop\bpt\bti\bio\bon\bns\bs
+ Write a list of all options used to the _\b._\bL_\bO_\bG file. Please see -\b--\b-d\bdu\bum\bmp\bp-\b-o\bop\bpt\bti\bio\bon\bns\bs for a simpler way to do this.
+
+ -\b-f\bf, -\b--\b-f\bfo\bor\brc\bce\be-\b-r\bre\bea\bad\bd-\b-b\bbi\bin\bna\bar\bry\by
+ 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.
+
+ -\b-a\bas\bst\bt, -\b--\b-a\bas\bss\bse\ber\brt\bt-\b-t\bti\bid\bdy\by
+ 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.
+
+ -\b-a\bas\bsu\bu, -\b--\b-a\bas\bss\bse\ber\brt\bt-\b-u\bun\bnt\bti\bid\bdy\by
+ 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.
+
+ -\b-s\bsa\bal\bl=\b=s\bs, -\b--\b-s\bsu\bub\bb-\b-a\bal\bli\bia\bas\bs-\b-l\bli\bis\bst\bt=\b=s\bs
+ This flag causes one or more words to be treated the same as if they were the keyword 'sub'. The string s\bs
+ 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.
+
+F\bFO\bOR\bRM\bMA\bAT\bTT\bTI\bIN\bNG\bG O\bOP\bPT\bTI\bIO\bON\bNS\bS
+ B\bBa\bas\bsi\bic\bc O\bOp\bpt\bti\bio\bon\bns\bs
+ -\b--\b-n\bno\bot\bti\bid\bdy\by
+ 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 _\b._\bp_\be_\br_\bl_\bt_\bi_\bd_\by_\br_\bc files to avoid unwanted code tidying. See also "Skipping Selected
+ Sections of Code" for a way to avoid tidying specific sections of code.
+
+ -\b-i\bi=\b=n\bn, -\b--\b-i\bin\bnd\bde\ben\bnt\bt-\b-c\bco\bol\blu\bum\bmn\bns\bs=\b=n\bn
+ Use n columns per indentation level (default n=4).
+
+ -\b-l\bl=\b=n\bn, -\b--\b-m\bma\bax\bxi\bim\bmu\bum\bm-\b-l\bli\bin\bne\be-\b-l\ble\ben\bng\bgt\bth\bh=\b=n\bn
+ 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 -\b-l\bl=\b=0\b0 is equivalent to setting -\b-l\bl=\b=(\b(a\ba v\bve\ber\bry\by l\bla\bar\brg\bge\be n\bnu\bum\bmb\bbe\ber\br)\b). But this is not recommended because, for
+ example, a very long list will be formatted in a single long line.
+
+ -\b-v\bvm\bml\bll\bl, -\b--\b-v\bva\bar\bri\bia\bab\bbl\ble\be-\b-m\bma\bax\bxi\bim\bmu\bum\bm-\b-l\bli\bin\bne\be-\b-l\ble\ben\bng\bgt\bth\bh
+ 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 -\b-v\bvm\bml\bll\bl flag, which basically tells perltidy to ignore
+ leading whitespace when measuring the line length.
+
+ To be precise, when the -\b-v\bvm\bml\bll\bl 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 (-\b-n\bnv\bvm\bml\bll\bl).
+
+ -\b-w\bwc\bc=\b=n\bn, -\b--\b-w\bwh\bhi\bit\bte\bes\bsp\bpa\bac\bce\be-\b-c\bcy\byc\bcl\ble\be=\b=n\bn
+ This flag also addresses problems with very deeply nested code and data structures. When the nesting depth
+ exceeds the value n\bn 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 (-\b-i\bi=\b=4\b4, the default), and one uses -\b-w\bwc\bc=\b=1\b15\b5, 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 -\b-v\bvm\bml\bll\bl and -\b-w\bwc\bc=\b=n\bn provides a solution to the problem of displaying arbitrarily deep data
+ structures and code in a finite window, although -\b-w\bwc\bc=\b=n\bn may of course be used without -\b-v\bvm\bml\bll\bl.
+
+ The default is not to use this, which can also be indicated using -\b-w\bwc\bc=\b=0\b0.
+
+ T\bTa\bab\bbs\bs
+ 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
+ -\b-f\bfw\bws\bs). If you have any tabs in your comments, quotes, or here-documents, they will remain.
+
+ -\b-e\bet\bt=\b=n\bn, -\b--\b-e\ben\bnt\bta\bab\bb-\b-l\ble\bea\bad\bdi\bin\bng\bg-\b-w\bwh\bhi\bit\bte\bes\bsp\bpa\bac\bce\be
+ This flag causes each n\bn initial space characters to be replaced by one tab character.
+
+ The value of the integer n\bn can be any value but can be coordinated with the number of spaces used for
+ intentation. For example, -\b-e\bet\bt=\b=4\b4 -\b-c\bci\bi=\b=4\b4 -\b-i\bi=\b=4\b4 will produce one tab for each indentation level and and one
+ for each continuation indentation level. You may want to coordinate the value of n\bn with what your
+ display software assumes for the spacing of a tab.
+
+ -\b-t\bt, -\b--\b-t\bta\bab\bbs\bs
+ 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 -\b-l\blp\bp option. This flag is retained for
+ backwards compatibility, but if you use tabs, the -\b-e\bet\bt=\b=n\bn flag is recommended.
+
+ -\b-d\bdt\bt=\b=n\bn, -\b--\b-d\bde\bef\bfa\bau\bul\blt\bt-\b-t\bta\bab\bbs\bsi\biz\bze\be=\b=n\bn
+ 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 n\bn corresponding to each leading tab of the input stream may be specified with -\b-d\bdt\bt=\b=n\bn. The
+ default is n\bn=\b=8\b8.
+
+ 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).
+
+ -\b-x\bxs\bs, -\b--\b-e\bex\bxt\bte\ben\bnd\bde\bed\bd-\b-s\bsy\byn\bnt\bta\bax\bx
+ 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 -\b--\b-n\bno\boo\bou\but\btd\bde\ben\bnt\bt-\b-l\bla\bab\bbe\bel\bls\bs flag to prevent lines such as 'default:' from being outdented.
+
+ This flag is enabled by default but it can be deactivated with -\b-n\bnx\bxs\bs. 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".
+
+ -\b-i\bio\bo, -\b--\b-i\bin\bnd\bde\ben\bnt\bt-\b-o\bon\bnl\bly\by
+ 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 -\b--\b-f\bfr\bre\bee\bez\bze\be-\b-n\bne\bew\bwl\bli\bin\bne\bes\bs and -\b--\b-f\bfr\bre\bee\bez\bze\be-\b-w\bwh\bhi\bit\bte\bes\bsp\bpa\bac\bce\be.
+
+ If you also want to keep your existing blank lines exactly as they are, you can add -\b--\b-f\bfr\bre\bee\bez\bze\be-\b-b\bbl\bla\ban\bnk\bk-\b-l\bli\bin\bne\bes\bs.
+
+ 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
+ -\b-n\bno\bol\bll\bl or -\b-l\bl=\b=0\b0.
+
+ 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.
+
+ -\b-e\ben\bnc\bc=\b=s\bs, -\b--\b-c\bch\bha\bar\bra\bac\bct\bte\ber\br-\b-e\ben\bnc\bco\bod\bdi\bin\bng\bg=\b=s\bs
+ 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 u\bus\bse\be u\but\btf\bf8\b8, 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 u\bus\bse\be u\but\btf\bf8\b8 directives).
+
+ The possible values for s\bs are (1) the name of an encoding recognized by the Encode.pm module, (2) n\bno\bon\bne\be if no
+ encoding is used, or (3) <guess> if perltidy should guess.
+
+ For example, the value u\but\btf\bf8\b8 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 n\bno\bon\bne\be 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 g\bgu\bue\bes\bss\bs 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 g\bgu\bue\bes\bss\bs.
+
+ The abbreviations -\b-u\but\btf\bf8\b8 or -\b-U\bUT\bTF\bF8\b8 are equivalent to -\b-e\ben\bnc\bc=\b=u\but\btf\bf8\b8, and the abbreviation -\b-g\bgu\bue\bes\bss\bs is equivalent to
+ <-enc=guess>. So to process a file named f\bfi\bil\ble\be.\b.p\bpl\bl which is encoded in UTF-8 you can use:
+
+ perltidy -utf8 file.pl
+
+ or
+ perltidy -guess file.pl
+
+ To process a file in e\beu\buc\bc-\b-j\bjp\bp 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 u\but\btf\bf8\b8,
+ even if the input encoding was not u\but\btf\bf8\b8.
+
+ -\b-g\bgc\bcs\bs, -\b--\b-u\bus\bse\be-\b-u\bun\bni\bic\bco\bod\bde\be-\b-g\bgc\bcs\bst\btr\bri\bin\bng\bg
+ This flag controls whether or not perltidy may use module Unicode::GCString to obtain accurate display
+ widths of wide characters. The default is -\b--\b-n\bno\bou\bus\bse\be-\b-u\bun\bni\bic\bco\bod\bde\be-\b-g\bgc\bcs\bst\btr\bri\bin\bng\bg.
+
+ 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.
+
+ -\b-o\bol\ble\be=\b=s\bs, -\b--\b-o\bou\but\btp\bpu\but\bt-\b-l\bli\bin\bne\be-\b-e\ben\bnd\bdi\bin\bng\bg=\b=s\bs
+ 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.
+
+ -\b-p\bpl\ble\be, -\b--\b-p\bpr\bre\bes\bse\ber\brv\bve\be-\b-l\bli\bin\bne\be-\b-e\ben\bnd\bdi\bin\bng\bgs\bs
+ This flag tells perltidy to write its output files with the same line endings as the input file, if
+ possible. It should work for d\bdo\bos\bs, u\bun\bni\bix\bx, and m\bma\bac\bc 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.
+
+ -\b-a\bat\btn\bnl\bl, -\b--\b-a\bad\bdd\bd-\b-t\bte\ber\brm\bmi\bin\bna\bal\bl-\b-n\bne\bew\bwl\bli\bin\bne\be
+ 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 -\b-n\bna\bat\btn\bnl\bl, 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.
+
+ -\b-i\bit\bt=\b=n\bn, -\b--\b-i\bit\bte\ber\bra\bat\bti\bio\bon\bns\bs=\b=n\bn
+ This flag causes perltidy to do n\bn 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 n\bn=\b=1\b1 should be satisfactory. However n\bn=\b=2\b2 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 n\bn
+ 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.
+
+ -\b-c\bco\bon\bnv\bv, -\b--\b-c\bco\bon\bnv\bve\ber\brg\bge\be
+ This flag is equivalent to -\b-i\bit\bt=\b=4\b4 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 -\b-n\bnc\bco\bon\bnv\bv (no convergence check). Using -\b-c\bco\bon\bnv\bv 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.
+
+ C\bCo\bod\bde\be I\bIn\bnd\bde\ben\bnt\bta\bat\bti\bio\bon\bn C\bCo\bon\bnt\btr\bro\bol\bl
+ -\b-c\bci\bi=\b=n\bn, -\b--\b-c\bco\bon\bnt\bti\bin\bnu\bua\bat\bti\bio\bon\bn-\b-i\bin\bnd\bde\ben\bnt\bta\bat\bti\bio\bon\bn=\b=n\bn
+ 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 -\b-c\bci\bi is also used by some commands when a small space is required. Examples are commands
+ for outdenting labels, -\b-o\bol\bla\ba, and control keywords, -\b-o\bok\bkw\bw.
+
+ When default values are not used, it is recommended that either
+
+ (1) the value n\bn given with -\b-c\bci\bi=\b=n\bn be no more than about one-half of the number of spaces assigned to a full
+ indentation level on the -\b-i\bi=\b=n\bn command, or
+
+ (2) the flag -\b-e\bex\bxt\bte\ben\bnd\bde\bed\bd-\b-c\bco\bon\bnt\bti\bin\bnu\bua\bat\bti\bio\bon\bn-\b-i\bin\bnd\bde\ben\bnt\bta\bat\bti\bio\bon\bn is used (see next section).
+
+ -\b-x\bxc\bci\bi, -\b--\b-e\bex\bxt\bte\ben\bnd\bde\bed\bd-\b-c\bco\bon\bnt\bti\bin\bnu\bua\bat\bti\bio\bon\bn-\b-i\bin\bnd\bde\ben\bnt\bta\bat\bti\bio\bon\bn
+ 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 -\b-c\bci\bi=\b=n\bn and -\b-i\bi=\b=n\bn use the same value of n\bn. There are no
+ significant disadvantages to using this flag, but to avoid disturbing existing formatting the default is not
+ to use it, -\b-n\bnx\bxc\bci\bi.
+
+ Please see the section "-\b-p\bpb\bbp\bp, -\b--\b-p\bpe\ber\brl\bl-\b-b\bbe\bes\bst\bt-\b-p\bpr\bra\bac\bct\bti\bic\bce\bes\bs" 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
+ )
+ )
+
+ -\b-s\bsi\bil\bl=\b=n\bn -\b--\b-s\bst\bta\bar\brt\bti\bin\bng\bg-\b-i\bin\bnd\bde\ben\bnt\bta\bat\bti\bio\bon\bn-\b-l\ble\bev\bve\bel\bl=\b=n\bn
+ 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 -\b-s\bsi\bil\bl=\b=n\bn, to
+ force the starting level to be n.
+
+ L\bLi\bis\bst\bt i\bin\bnd\bde\ben\bnt\bta\bat\bti\bio\bon\bn using -\b-l\blp\bp, -\b--\b-l\bli\bin\bne\be-\b-u\bup\bp-\b-p\bpa\bar\bre\ben\bnt\bth\bhe\bes\bse\bes\bs
+ By default, perltidy indents lists with 4 spaces, or whatever value is specified with -\b-i\bi=\b=n\bn. 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 -\b-l\blp\bp 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 -\b-l\bl=\b=n\bn ) 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 -\b-i\bi=\b=n\bn.
+
+ 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 -\b-l\blp\bp and will cause -\b-l\blp\bp to be deactivated. These include -\b-i\bio\bo, -\b-f\bfn\bnl\bl, -\b-n\bna\ban\bnl\bl, and -\b-n\bnd\bdn\bnl\bl. The
+ reason is that the -\b-l\blp\bp indentation style can require the careful coordination of an arbitrary number of
+ break points in hierarchical lists, and these flags may prevent that.
+
+ The -\b-l\blp\bp option may not be used together with the -\b-t\bt tabs option. It may, however, be used with the -\b-e\bet\bt=\b=n\bn
+ tab method.
+
+ -\b-l\blp\bpx\bxl\bl=\b=s\bs, -\b--\b-l\bli\bin\bne\be-\b-u\bup\bp-\b-p\bpa\bar\bre\ben\bnt\bth\bhe\bes\bse\bes\bs-\b-e\bex\bxc\bcl\blu\bus\bsi\bio\bon\bn-\b-l\bli\bis\bst\bt
+ This is an experimental parameter; the details might change as experience with it is gained.
+
+ The -\b-l\blp\bp 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 -\b-l\blp\bpx\bxl\bl=\b=s\bs flag is intended to help mitigate
+ this problem by providing control over the containers to which the -\b-l\blp\bp indentation style is applied. The
+ -\b-l\blp\bp flag by default is "greedy" and applies to as many containers as possible. This flag specifies a list
+ of things which should n\bno\bot\bt be use -\b-l\blp\bp 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 N\bNO\bOT\bT 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.
+
+ -\b-c\bct\bti\bi=\b=n\bn, -\b--\b-c\bcl\blo\bos\bsi\bin\bng\bg-\b-t\bto\bok\bke\ben\bn-\b-i\bin\bnd\bde\ben\bnt\bta\bat\bti\bio\bon\bn
+ The -\b-c\bct\bti\bi=\b=n\bn 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 -\b-c\bct\bti\bi=\b=1\b1 and -\b-c\bct\bti\bi=\b=2\b2 work well with the -\b-l\blp\bp 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 c\bct\bti\bi=\b=1\b1 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, -\b-c\bct\bti\bi=\b=n\bn is merely an abbreviation for -\b-c\bcp\bpi\bi=\b=n\bn -\b-c\bcs\bsb\bbi\bi=\b=n\bn -\b-c\bcb\bbi\bi=\b=n\bn, where: -\b-c\bcp\bpi\bi or -\b--\b-c\bcl\blo\bos\bsi\bin\bng\bg-\b-p\bpa\bar\bre\ben\bn-\b-i\bin\bnd\bde\ben\bnt\bta\bat\bti\bio\bon\bn
+ controls )\b)'s, -\b-c\bcs\bsb\bbi\bi or -\b--\b-c\bcl\blo\bos\bsi\bin\bng\bg-\b-s\bsq\bqu\bua\bar\bre\be-\b-b\bbr\bra\bac\bck\bke\bet\bt-\b-i\bin\bnd\bde\ben\bnt\bta\bat\bti\bio\bon\bn controls ]\b]'s, -\b-c\bcb\bbi\bi or
+ -\b--\b-c\bcl\blo\bos\bsi\bin\bng\bg-\b-b\bbr\bra\bac\bce\be-\b-i\bin\bnd\bde\ben\bnt\bta\bat\bti\bio\bon\bn controls non-block }\b}'s.
+
+ -\b-i\bic\bcp\bp, -\b--\b-i\bin\bnd\bde\ben\bnt\bt-\b-c\bcl\blo\bos\bsi\bin\bng\bg-\b-p\bpa\bar\bre\ben\bn
+ The -\b-i\bic\bcp\bp flag is equivalent to -\b-c\bct\bti\bi=\b=2\b2, described in the previous section. The -\b-n\bni\bic\bcp\bp flag is equivalent
+ -\b-c\bct\bti\bi=\b=0\b0. They are included for backwards compatibility.
+
+ -\b-i\bic\bcb\bb, -\b--\b-i\bin\bnd\bde\ben\bnt\bt-\b-c\bcl\blo\bos\bsi\bin\bng\bg-\b-b\bbr\bra\bac\bce\be
+ The -\b-i\bic\bcb\bb 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 -\b-n\bni\bic\bcb\bb.
+
+ -\b-n\bni\bib\bb, -\b--\b-n\bno\bon\bn-\b-i\bin\bnd\bde\ben\bnt\bti\bin\bng\bg-\b-b\bbr\bra\bac\bce\bes\bs
+ 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 #\b#<\b<<\b<<\b< 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 -\b-n\bnn\bni\bib\bb to deactivate it. To make it easy to remember, the default string is the same as the string
+ for starting a f\bfo\bor\brm\bma\bat\bt-\b-s\bsk\bki\bip\bpp\bpi\bin\bng\bg 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.
+
+ -\b-n\bni\bib\bbp\bp=\b=s\bs, -\b--\b-n\bno\bon\bn-\b-i\bin\bnd\bde\ben\bnt\bti\bin\bng\bg-\b-b\bbr\bra\bac\bce\be-\b-p\bpr\bre\bef\bfi\bix\bx=\b=s\bs
+ The -\b-n\bni\bib\bbp\bp=\b=s\bst\btr\bri\bin\bng\bg 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='#\+\+'
+
+ -\b-o\bol\blq\bq, -\b--\b-o\bou\but\btd\bde\ben\bnt\bt-\b-l\blo\bon\bng\bg-\b-q\bqu\buo\bot\bte\bes\bs
+ When -\b-o\bol\blq\bq is set, lines which is a quoted string longer than the value m\bma\bax\bxi\bim\bmu\bum\bm-\b-l\bli\bin\bne\be-\b-l\ble\ben\bng\bgt\bth\bh will have their
+ indentation removed to make them more readable. This is the default. To prevent such out-denting, use
+ -\b-n\bno\bol\blq\bq or -\b--\b-n\bno\boo\bou\but\btd\bde\ben\bnt\bt-\b-l\blo\bon\bng\bg-\b-l\bli\bin\bne\bes\bs.
+
+ -\b-o\bol\bll\bl, -\b--\b-o\bou\but\btd\bde\ben\bnt\bt-\b-l\blo\bon\bng\bg-\b-l\bli\bin\bne\bes\bs
+ This command is equivalent to -\b--\b-o\bou\but\btd\bde\ben\bnt\bt-\b-l\blo\bon\bng\bg-\b-q\bqu\buo\bot\bte\bes\bs and -\b--\b-o\bou\but\btd\bde\ben\bnt\bt-\b-l\blo\bon\bng\bg-\b-c\bco\bom\bmm\bme\ben\bnt\bts\bs, and it is included for
+ compatibility with previous versions of perltidy. The negation of this also works, -\b-n\bno\bol\bll\bl or
+ -\b--\b-n\bno\boo\bou\but\btd\bde\ben\bnt\bt-\b-l\blo\bon\bng\bg-\b-l\bli\bin\bne\bes\bs, and is equivalent to setting -\b-n\bno\bol\blq\bq and -\b-n\bno\bol\blc\bc.
+
+ O\bOu\but\btd\bde\ben\bnt\bti\bin\bng\bg L\bLa\bab\bbe\bel\bls\bs:\b: -\b-o\bol\bla\ba, -\b--\b-o\bou\but\btd\bde\ben\bnt\bt-\b-l\bla\bab\bbe\bel\bls\bs
+ This command will cause labels to be outdented by 2 spaces (or whatever -\b-c\bci\bi has been set to), if possible.
+ This is the default. For example:
+
+ my $i;
+ LOOP: while ( $i = <FOTOS> ) {
+ chomp($i);
+ next unless $i;
+ fixit($i);
+ }
+
+ Use -\b-n\bno\bol\bla\ba to not outdent labels.
+
+ O\bOu\but\btd\bde\ben\bnt\bti\bin\bng\bg K\bKe\bey\byw\bwo\bor\brd\bds\bs
+ -\b-o\bok\bkw\bw, -\b--\b-o\bou\but\btd\bde\ben\bnt\bt-\b-k\bke\bey\byw\bwo\bor\brd\bds\bs
+ The command -\b-o\bok\bkw\bw will cause certain leading control keywords to be outdented by 2 spaces (or whatever
+ -\b-c\bci\bi has been set to), if possible. By default, these keywords are "redo", "next", "last", "goto", and
+ "return". The intention is to make these control keywords easier to see. To change this list of
+ keywords being outdented, see the next section.
+
+ For example, using "perltidy -okw" on the previous example gives:
+
+ my $i;
+ LOOP: while ( $i = <FOTOS> ) {
+ chomp($i);
+ next unless $i;
+ fixit($i);
+ }
+
+ The default is not to do this.
+
+ S\bSp\bpe\bec\bci\bif\bfy\byi\bin\bng\bg O\bOu\but\btd\bde\ben\bnt\bte\bed\bd K\bKe\bey\byw\bwo\bor\brd\bds\bs:\b: -\b-o\bok\bkw\bwl\bl=\b=s\bst\btr\bri\bin\bng\bg, -\b--\b-o\bou\but\btd\bde\ben\bnt\bt-\b-k\bke\bey\byw\bwo\bor\brd\bd-\b-l\bli\bis\bst\bt=\b=s\bst\btr\bri\bin\bng\bg
+ This command can be used to change the keywords which are outdented with the -\b-o\bok\bkw\bw command. The
+ parameter s\bst\btr\bri\bin\bng\bg 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 -\b-o\bok\bkw\bw 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 -\b-o\bok\bkw\bwl\bl command in a _\b._\bp_\be_\br_\bl_\bt_\bi_\bd_\by_\br_\bc file.
+
+ W\bWh\bhi\bit\bte\bes\bsp\bpa\bac\bce\be C\bCo\bon\bnt\btr\bro\bol\bl
+ Whitespace refers to the blank space between variables, operators, and other code tokens.
+
+ -\b-f\bfw\bws\bs, -\b--\b-f\bfr\bre\bee\bez\bze\be-\b-w\bwh\bhi\bit\bte\bes\bsp\bpa\bac\bce\be
+ 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.
+
+ T\bTi\big\bgh\bht\btn\bne\bes\bss\bs o\bof\bf c\bcu\bur\brl\bly\by b\bbr\bra\bac\bce\bes\bs,\b, p\bpa\bar\bre\ben\bnt\bth\bhe\bes\bse\bes\bs,\b, a\ban\bnd\bd s\bsq\bqu\bua\bar\bre\be b\bbr\bra\bac\bck\bke\bet\bts\bs
+ 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 -\b-p\bpt\bt=\b=n\bn or -\b--\b-p\bpa\bar\bre\ben\bn-\b-t\bti\big\bgh\bht\btn\bne\bes\bss\bs=\b=n\bn 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 -\b-s\bsb\bbt\bt=\b=n\bn or -\b--\b-s\bsq\bqu\bua\bar\bre\be-\b-b\bbr\bra\bac\bck\bke\bet\bt-\b-t\bti\big\bgh\bht\btn\bne\bes\bss\bs=\b=n\bn 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 -\b-b\bbt\bt=\b=n\bn or -\b--\b-b\bbr\bra\bac\bce\be-\b-t\bti\big\bgh\bht\btn\bne\bes\bss\bs=\b=n\bn.
+
+ $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 -\b-b\bbb\bbt\bt=\b=n\bn or
+ -\b--\b-b\bbl\blo\boc\bck\bk-\b-b\bbr\bra\bac\bce\be-\b-t\bti\big\bgh\bht\btn\bne\bes\bss\bs=\b=n\bn as illustrated in the example below.
+
+ %bf = map { $_ => -M $_ } grep { /\.deb$/ } dirents '.'; # -bbt=0 (default)
+ %bf = map { $_ => -M $_ } grep {/\.deb$/} dirents '.'; # -bbt=1
+ %bf = map {$_ => -M $_} grep {/\.deb$/} dirents '.'; # -bbt=2
+
+ To simplify input in the case that all of the tightness flags have the same value <n>, the parameter
+ <-act=n> or -\b--\b-a\bal\bll\bl-\b-c\bco\bon\bnt\bta\bai\bin\bne\ber\brs\bs-\b-t\bti\big\bgh\bht\btn\bne\bes\bss\bs=\b=n\bn is an abbreviation for the combination <-pt=n -sbt=n -bt=n -bbt=n>.
+
+ -\b-t\bts\bso\bo, -\b--\b-t\bti\big\bgh\bht\bt-\b-s\bse\bec\bcr\bre\bet\bt-\b-o\bop\bpe\ber\bra\bat\bto\bor\brs\bs
+ The flag -\b-t\bts\bso\bo 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 0\b0 +\b+, which converts a string to a number, would be formatted without a space: 0\b0+\b+
+ when the -\b-t\bts\bso\bo flag is set. This flag is off by default.
+
+ -\b-s\bst\bts\bs, -\b--\b-s\bsp\bpa\bac\bce\be-\b-t\bte\ber\brm\bmi\bin\bna\bal\bl-\b-s\bse\bem\bmi\bic\bco\bol\blo\bon\bn
+ Some programmers prefer a space before all terminal semicolons. The default is for no such space, and is
+ indicated with -\b-n\bns\bst\bts\bs or -\b--\b-n\bno\bos\bsp\bpa\bac\bce\be-\b-t\bte\ber\brm\bmi\bin\bna\bal\bl-\b-s\bse\bem\bmi\bic\bco\bol\blo\bon\bn.
+
+ $i = 1 ; # -sts
+ $i = 1; # -nsts (default)
+
+ -\b-s\bsf\bfs\bs, -\b--\b-s\bsp\bpa\bac\bce\be-\b-f\bfo\bor\br-\b-s\bse\bem\bmi\bic\bco\bol\blo\bon\bn
+ Semicolons within f\bfo\bor\br 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 -\b-n\bns\bsf\bfs\bs or
+ -\b--\b-n\bno\bos\bsp\bpa\bac\bce\be-\b-f\bfo\bor\br-\b-s\bse\bem\bmi\bic\bco\bol\blo\bon\bn to deactivate it.
+
+ for ( @a = @$ap, $u = shift @a ; @a ; $u = $v ) { # -sfs (default)
+ for ( @a = @$ap, $u = shift @a; @a; $u = $v ) { # -nsfs
+
+ -\b-a\bas\bsc\bc, -\b--\b-a\bad\bdd\bd-\b-s\bse\bem\bmi\bic\bco\bol\blo\bon\bns\bs
+ Setting -\b-a\bas\bsc\bc 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 -\b-n\bna\bas\bsc\bc or
+ -\b--\b-n\bno\boa\bad\bdd\bd-\b-s\bse\bem\bmi\bic\bco\bol\blo\bon\bns\bs.
+
+ -\b-d\bds\bsm\bm, -\b--\b-d\bde\bel\ble\bet\bte\be-\b-s\bse\bem\bmi\bic\bco\bol\blo\bon\bns\bs
+ Setting -\b-d\bds\bsm\bm allows perltidy to delete extra semicolons which are simply empty statements. This is the
+ default, and may be deactivated with -\b-n\bnd\bds\bsm\bm or -\b--\b-n\bno\bod\bde\bel\ble\bet\bte\be-\b-s\bse\bem\bmi\bic\bco\bol\blo\bon\bns\bs. (Such semicolons are not deleted,
+ however, if they would promote a side comment to a block comment).
+
+ -\b-a\baw\bws\bs, -\b--\b-a\bad\bdd\bd-\b-w\bwh\bhi\bit\bte\bes\bsp\bpa\bac\bce\be
+ 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
+ -\b-n\bna\baw\bws\bs. (Use -\b-f\bfw\bws\bs to leave whitespace completely unchanged).
+
+ -\b-d\bdw\bws\bs, -\b--\b-d\bde\bel\ble\bet\bte\be-\b-o\bol\bld\bd-\b-w\bwh\bhi\bit\bte\bes\bsp\bpa\bac\bce\be
+ 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 -\b-n\bnd\bdw\bws\bs or -\b--\b-n\bno\bod\bde\bel\ble\bet\bte\be-\b-o\bol\bld\bd-\b-w\bwh\bhi\bit\bte\bes\bsp\bpa\bac\bce\be.
+
+ D\bDe\bet\bta\bai\bil\ble\bed\bd w\bwh\bhi\bit\bte\bes\bsp\bpa\bac\bce\be c\bco\bon\bnt\btr\bro\bol\bls\bs a\bar\bro\bou\bun\bnd\bd t\bto\bok\bke\ben\bns\bs
+ 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:
+
+ -\b-w\bwl\bls\bs=\b=s\bs or -\b--\b-w\bwa\ban\bnt\bt-\b-l\ble\bef\bft\bt-\b-s\bsp\bpa\bac\bce\be=\b=s\bs,
+
+ -\b-n\bnw\bwl\bls\bs=\b=s\bs or -\b--\b-n\bno\bow\bwa\ban\bnt\bt-\b-l\ble\bef\bft\bt-\b-s\bsp\bpa\bac\bce\be=\b=s\bs,
+
+ -\b-w\bwr\brs\bs=\b=s\bs or -\b--\b-w\bwa\ban\bnt\bt-\b-r\bri\big\bgh\bht\bt-\b-s\bsp\bpa\bac\bce\be=\b=s\bs,
+
+ -\b-n\bnw\bwr\brs\bs=\b=s\bs or -\b--\b-n\bno\bow\bwa\ban\bnt\bt-\b-r\bri\big\bgh\bht\bt-\b-s\bsp\bpa\bac\bce\be=\b=s\bs.
+
+ These parameters are each followed by a quoted string, s\bs, 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 =\b= +\b+ -\b- /\b/ *\b*. 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 -\b--\b-d\bdu\bum\bmp\bp-\b-t\bto\bok\bke\ben\bn-\b-t\bty\byp\bpe\bes\bs. Also try the -\b-D\bD flag on a short snippet of code and look at the
+ .DEBUG file to see the tokenization.
+
+ W\bWA\bAR\bRN\bNI\bIN\bNG\bG Be sure to put these tokens in quotes to avoid having them misinterpreted by your command shell.
+
+ N\bNo\bot\bte\be1\b1:\b: P\bPe\ber\brl\blt\bti\bid\bdy\by d\bdo\boe\bes\bs a\bal\blw\bwa\bay\bys\bs f\bfo\bol\bll\blo\bow\bw w\bwh\bhi\bit\bte\bes\bsp\bpa\bac\bce\be c\bco\bon\bnt\btr\bro\bol\bls\bs
+ 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 p\bpr\bri\bin\bnt\bt keyword as a special
+ type Z\bZ. 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 p\bpr\bri\bin\bnt\bt include p\bpr\bri\bin\bnt\btf\bf, s\bso\bor\brt\bt, e\bex\bxe\bec\bc, s\bsy\bys\bst\bte\bem\bm. 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 Z\bZ you can use p\bpe\ber\brl\blt\bti\bid\bdy\by -\b-D\bDE\bEB\bBU\bUG\bG. For the first line above the result is
+
+ 1: system($foo );
+ 1: kkkkkk{ZZZZb};
+
+ which shows that s\bsy\bys\bst\bte\bem\bm is type k\bk (keyword) and $foo is type Z\bZ.
+
+ N\bNo\bot\bte\be2\b2:\b: P\bPe\ber\brl\blt\bti\bid\bdy\by'\b's\bs w\bwh\bhi\bit\bte\bes\bsp\bpa\bac\bce\be r\bru\bul\ble\bes\bs a\bar\bre\be n\bno\bot\bt p\bpe\ber\brf\bfe\bec\bct\bt
+ 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.
+
+ S\bSp\bpa\bac\bce\be b\bbe\bet\btw\bwe\bee\ben\bn s\bsp\bpe\bec\bci\bif\bfi\bic\bc k\bke\bey\byw\bwo\bor\brd\bds\bs a\ban\bnd\bd o\bop\bpe\ben\bni\bin\bng\bg p\bpa\bar\bre\ben\bn
+ 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:
+
+ -\b-s\bsa\bak\bk=\b=s\bs or -\b--\b-s\bsp\bpa\bac\bce\be-\b-a\baf\bft\bte\ber\br-\b-k\bke\bey\byw\bwo\bor\brd\bd=\b=s\bs adds keywords.
+
+ -\b-n\bns\bsa\bak\bk=\b=s\bs or -\b--\b-n\bno\bos\bsp\bpa\bac\bce\be-\b-a\baf\bft\bte\ber\br-\b-k\bke\bey\byw\bwo\bor\brd\bd=\b=s\bs removes keywords.
+
+ where s\bs 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 -\b-n\bns\bsa\bak\bk=\b='\b'*\b*'\b' is equivalent to including all of the keywords in the above list.
+
+ When both -\b-n\bns\bsa\bak\bk=\b=s\bs and -\b-s\bsa\bak\bk=\b=s\bs commands are included, the -\b-n\bns\bsa\bak\bk=\b=s\bs command is executed first. For example, to
+ have space after only the keywords (my, local, our) you could use -\b-n\bns\bsa\bak\bk=\b="\b"*\b*"\b" -\b-s\bsa\bak\bk=\b="\b"m\bmy\by l\blo\boc\bca\bal\bl o\bou\bur\br"\b".
+
+ To put a space after all keywords, see the next item.
+
+ S\bSp\bpa\bac\bce\be b\bbe\bet\btw\bwe\bee\ben\bn a\bal\bll\bl k\bke\bey\byw\bwo\bor\brd\bds\bs a\ban\bnd\bd o\bop\bpe\ben\bni\bin\bng\bg p\bpa\bar\bre\ben\bns\bs
+ 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:
+
+ -\b-s\bsk\bkp\bp or -\b--\b-s\bsp\bpa\bac\bce\be-\b-k\bke\bey\byw\bwo\bor\brd\bd-\b-p\bpa\bar\bre\ben\bn
+
+ You may also want to use the flag -\b-s\bsf\bfp\bp (next item) too.
+
+ S\bSp\bpa\bac\bce\be b\bbe\bet\btw\bwe\bee\ben\bn a\bal\bll\bl f\bfu\bun\bnc\bct\bti\bio\bon\bn n\bna\bam\bme\bes\bs a\ban\bnd\bd o\bop\bpe\ben\bni\bin\bng\bg p\bpa\bar\bre\ben\bns\bs
+ 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:
+
+ -\b-s\bsf\bfp\bp or -\b--\b-s\bsp\bpa\bac\bce\be-\b-f\bfu\bun\bnc\bct\bti\bio\bon\bn-\b-p\bpa\bar\bre\ben\bn
+
+ myfunc( $a, $b, $c ); # default
+ myfunc ( $a, $b, $c ); # -sfp
+
+ You will probably also want to use the flag -\b-s\bsk\bkp\bp (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.
+
+ -\b-f\bfp\bpv\bva\ba or -\b--\b-f\bfu\bun\bnc\bct\bti\bio\bon\bn-\b-p\bpa\bar\bre\ben\bn-\b-v\bve\ber\brt\bti\bic\bca\bal\bl-\b-a\bal\bli\big\bgn\bnm\bme\ben\bnt\bt
+ A side-effect of using the -\b-s\bsf\bfp\bp 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 -\b-n\bnf\bfp\bpv\bva\ba:
+
+ # perltidy -sfp -nfpva
+ myfun ( $aaa, $b, $cc );
+ mylongfun ( $a, $b, $c );
+
+ -\b-s\bsp\bpp\bp=\b=n\bn or -\b--\b-s\bsp\bpa\bac\bce\be-\b-p\bpr\bro\bot\bto\bot\bty\byp\bpe\be-\b-p\bpa\bar\bre\ben\bn=\b=n\bn
+ 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 n\bn 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 -\b-s\bsp\bpp\bp=\b=1\b1, 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]
+
+ -\b-k\bkp\bpi\bit\bt=\b=n\bn or -\b--\b-k\bke\bey\byw\bwo\bor\brd\bd-\b-p\bpa\bar\bre\ben\bn-\b-i\bin\bnn\bne\ber\br-\b-t\bti\big\bgh\bht\btn\bne\bes\bss\bs=\b=n\bn
+ 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 n\bn 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 -\b-k\bkp\bpi\bit\btl\bl=\b=s\bs described in the next section.
+
+ -\b-k\bkp\bpi\bit\btl\bl=\b=s\bst\btr\bri\bin\bng\bg or -\b--\b-k\bke\bey\byw\bwo\bor\brd\bd-\b-p\bpa\bar\bre\ben\bn-\b-i\bin\bnn\bne\ber\br-\b-t\bti\big\bgh\bht\btn\bne\bes\bss\bs=\b=s\bst\btr\bri\bin\bng\bg
+ This command can be used to change the keywords to which the the -\b-k\bkp\bpi\bit\bt=\b=n\bn command applies. The parameter
+ s\bst\btr\bri\bin\bng\bg 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 -\b-k\bkp\bpi\bit\bt=\b=n\bn 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 -\b-k\bkp\bpi\bit\bt=\b=2\b2 flag.
+
+ -\b-l\blo\bop\bp or -\b--\b-l\blo\bog\bgi\bic\bca\bal\bl-\b-p\bpa\bad\bdd\bdi\bin\bng\bg
+ 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 -\b--\b-l\blo\bog\bgi\bic\bca\bal\bl-\b-p\bpa\bad\bdd\bdi\bin\bng\bg, which is set 'on' by default. If it is not
+ desired it can be turned off using -\b--\b-n\bno\bol\blo\bog\bgi\bic\bca\bal\bl-\b-p\bpa\bad\bdd\bdi\bin\bng\bg or -\b-n\bnl\blo\bop\bp. The above two examples become, with -\b-n\bnl\blo\bop\bp:
+
+ # 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;
+
+ T\bTr\bri\bim\bmm\bmi\bin\bng\bg w\bwh\bhi\bit\bte\bes\bsp\bpa\bac\bce\be a\bar\bro\bou\bun\bnd\bd "\b"q\bqw\bw"\b" q\bqu\buo\bot\bte\bes\bs
+ -\b-t\btq\bqw\bw or -\b--\b-t\btr\bri\bim\bm-\b-q\bqw\bw provide the default behavior of trimming spaces around multi-line "qw" quotes and
+ indenting them appropriately.
+
+ -\b-n\bnt\btq\bqw\bw or -\b--\b-n\bno\bot\btr\bri\bim\bm-\b-q\bqw\bw 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.
+
+ -\b-s\bsb\bbq\bq=\b=n\bn or -\b--\b-s\bsp\bpa\bac\bce\be-\b-b\bba\bac\bck\bks\bsl\bla\bas\bsh\bh-\b-q\bqu\buo\bot\bte\be=\b=n\bn
+ 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 n\bn 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 -\b-s\bsb\bbq\bq=\b=1\b1, meaning that a space will be used if there is one in the source code.
+
+ T\bTr\bri\bim\bmm\bmi\bin\bng\bg t\btr\bra\bai\bil\bli\bin\bng\bg w\bwh\bhi\bit\bte\bes\bsp\bpa\bac\bce\be f\bfr\bro\bom\bm l\bli\bin\bne\bes\bs o\bof\bf P\bPO\bOD\bD
+ -\b-t\btr\brp\bp or -\b--\b-t\btr\bri\bim\bm-\b-p\bpo\bod\bd will remove trailing whitespace from lines of POD. The default is not to do this.
+
+ C\bCo\bom\bmm\bme\ben\bnt\bt C\bCo\bon\bnt\btr\bro\bol\bls\bs
+ Perltidy has a number of ways to control the appearance of both block comments and side comments. The term
+ b\bbl\blo\boc\bck\bk c\bco\bom\bmm\bme\ben\bnt\bt here refers to a full-line comment, whereas s\bsi\bid\bde\be c\bco\bom\bmm\bme\ben\bnt\bt will refer to a comment which appears on
+ a line to the right of some code.
+
+ -\b-i\bib\bbc\bc, -\b--\b-i\bin\bnd\bde\ben\bnt\bt-\b-b\bbl\blo\boc\bck\bk-\b-c\bco\bom\bmm\bme\ben\bnt\bts\bs
+ 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 -\b-n\bni\bib\bbc\bc to keep block comments left-justified. Here is an
+ example:
+
+ # this comment is indented (-ibc, default)
+ if ($task) { yyy(); }
+
+ The alternative is -\b-n\bni\bib\bbc\bc:
+
+ # this comment is not indented (-nibc)
+ if ($task) { yyy(); }
+
+ See also the next item, -\b-i\bis\bsb\bbc\bc, as well as -\b-s\bsb\bbc\bc, for other ways to have some indented and some outdented
+ block comments.
+
+ -\b-i\bis\bsb\bbc\bc, -\b--\b-i\bin\bnd\bde\ben\bnt\bt-\b-s\bsp\bpa\bac\bce\bed\bd-\b-b\bbl\blo\boc\bck\bk-\b-c\bco\bom\bmm\bme\ben\bnt\bts\bs
+ If there is no leading space on the line, then the comment will not be indented, and otherwise it may be.
+
+ If both -\b-i\bib\bbc\bc and -\b-i\bis\bsb\bbc\bc are set, then -\b-i\bis\bsb\bbc\bc takes priority.
+
+ -\b-o\bol\blc\bc, -\b--\b-o\bou\but\btd\bde\ben\bnt\bt-\b-l\blo\bon\bng\bg-\b-c\bco\bom\bmm\bme\ben\bnt\bts\bs
+ When -\b-o\bol\blc\bc is set, lines which are full-line (block) comments longer than the value m\bma\bax\bxi\bim\bmu\bum\bm-\b-l\bli\bin\bne\be-\b-l\ble\ben\bng\bgt\bth\bh will
+ have their indentation removed. This is the default; use -\b-n\bno\bol\blc\bc to prevent outdenting.
+
+ -\b-m\bms\bsc\bc=\b=n\bn, -\b--\b-m\bmi\bin\bni\bim\bmu\bum\bm-\b-s\bsp\bpa\bac\bce\be-\b-t\bto\bo-\b-c\bco\bom\bmm\bme\ben\bnt\bt=\b=n\bn
+ 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.
+
+ -\b-f\bfp\bps\bsc\bc=\b=n\bn, -\b--\b-f\bfi\bix\bxe\bed\bd-\b-p\bpo\bos\bsi\bit\bti\bio\bon\bn-\b-s\bsi\bid\bde\be-\b-c\bco\bom\bmm\bme\ben\bnt\bt=\b=n\bn
+ This parameter tells perltidy to line up side comments in column number n\bn whenever possible. The default,
+ n=0, will not do this.
+
+ -\b-i\bis\bsc\bcl\bl, -\b--\b-i\big\bgn\bno\bor\bre\be-\b-s\bsi\bid\bde\be-\b-c\bco\bom\bmm\bme\ben\bnt\bt-\b-l\ble\ben\bng\bgt\bth\bhs\bs
+ This parameter causes perltidy to ignore the length of side comments when setting line breaks. The default,
+ -\b-n\bni\bis\bsc\bcl\bl, is to include the length of side comments when breaking lines to stay within the length prescribed
+ by the -\b-l\bl=\b=n\bn 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
+
+ -\b-h\bhs\bsc\bc, -\b--\b-h\bha\ban\bng\bgi\bin\bng\bg-\b-s\bsi\bid\bde\be-\b-c\bco\bom\bmm\bme\ben\bnt\bts\bs
+ 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 -\b-n\bnh\bhs\bsc\bc or -\b--\b-n\bno\boh\bha\ban\bng\bgi\bin\bng\bg-\b-s\bsi\bid\bde\be-\b-c\bco\bom\bmm\bme\ben\bnt\bts\bs. If block comments are preceded by a blank
+ line, or have no leading whitespace, they will not be mistaken as hanging side comments.
+
+ C\bCl\blo\bos\bsi\bin\bng\bg S\bSi\bid\bde\be C\bCo\bom\bmm\bme\ben\bnt\bts\bs
+ 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 -\b-c\bcs\bsc\bc (or
+ -\b--\b-c\bcl\blo\bos\bsi\bin\bng\bg-\b-s\bsi\bid\bde\be-\b-c\bco\bom\bmm\bme\ben\bnt\bts\bs) 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 -\b-c\bcs\bsc\bci\bi command, described below.
+
+ The command -\b-d\bdc\bcs\bsc\bc (or -\b--\b-d\bde\bel\ble\bet\bte\be-\b-c\bcl\blo\bos\bsi\bin\bng\bg-\b-s\bsi\bid\bde\be-\b-c\bco\bom\bmm\bme\ben\bnt\bts\bs) reverses this process and removes these comments.
+
+ Several commands are available to modify the behavior of these two basic commands, -\b-c\bcs\bsc\bc and -\b-d\bdc\bcs\bsc\bc:
+
+ -\b-c\bcs\bsc\bci\bi=\b=n\bn, or -\b--\b-c\bcl\blo\bos\bsi\bin\bng\bg-\b-s\bsi\bid\bde\be-\b-c\bco\bom\bmm\bme\ben\bnt\bt-\b-i\bin\bnt\bte\ber\brv\bva\bal\bl=\b=n\bn
+ 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.
+
+ -\b-c\bcs\bsc\bcp\bp=\b=s\bst\btr\bri\bin\bng\bg, or -\b--\b-c\bcl\blo\bos\bsi\bin\bng\bg-\b-s\bsi\bid\bde\be-\b-c\bco\bom\bmm\bme\ben\bnt\bt-\b-p\bpr\bre\bef\bfi\bix\bx=\b=s\bst\btr\bri\bin\bng\bg
+ 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.
+
+ -\b-c\bcs\bsc\bcl\bl=\b=s\bst\btr\bri\bin\bng\bg, or -\b--\b-c\bcl\blo\bos\bsi\bin\bng\bg-\b-s\bsi\bid\bde\be-\b-c\bco\bom\bmm\bme\ben\bnt\bt-\b-l\bli\bis\bst\bt
+ 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 -\b-c\bcs\bsc\bcl\bl
+ 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 -\b-c\bcs\bsc\bc or -\b-d\bdc\bcs\bsc\bc operation:
+
+ -cscl="sub : BEGIN END"
+
+ -\b-c\bcs\bsc\bct\bt=\b=n\bn, or -\b--\b-c\bcl\blo\bos\bsi\bin\bng\bg-\b-s\bsi\bid\bde\be-\b-c\bco\bom\bmm\bme\ben\bnt\bt-\b-m\bma\bax\bxi\bim\bmu\bum\bm-\b-t\bte\bex\bxt\bt=\b=n\bn
+ 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.
+
+ -\b-c\bcs\bsc\bcb\bb, or -\b--\b-c\bcl\blo\bos\bsi\bin\bng\bg-\b-s\bsi\bid\bde\be-\b-c\bco\bom\bmm\bme\ben\bnt\bts\bs-\b-b\bba\bal\bla\ban\bnc\bce\bed\bd
+ 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 -\b-c\bcs\bsc\bcb\bb 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 -\b-c\bcs\bsc\bcb\bb.
+
+ -\b-c\bcs\bsc\bce\be=\b=n\bn, or -\b--\b-c\bcl\blo\bos\bsi\bin\bng\bg-\b-s\bsi\bid\bde\be-\b-c\bco\bom\bmm\bme\ben\bnt\bt-\b-e\bel\bls\bse\be-\b-f\bfl\bla\bag\bg=\b=n\bn
+ The default, n\bn=\b=0\b0, places the text of the opening "if" statement after any terminal "else".
+
+ If n\bn=\b=2\b2 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 n\bn=\b=1\b1 is used, the results will be the same as n\bn=\b=2\b2 whenever the resulting line length is less than the
+ maximum allowed.
+
+ -\b-c\bcs\bsc\bcb\bb, or -\b--\b-c\bcl\blo\bos\bsi\bin\bng\bg-\b-s\bsi\bid\bde\be-\b-c\bco\bom\bmm\bme\ben\bnt\bts\bs-\b-b\bba\bal\bla\ban\bnc\bce\bed\bd
+ 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 -\b-c\bcs\bsc\bcb\bb 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 -\b-c\bcs\bsc\bcb\bb 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 -\b-c\bcs\bsc\bcb\bb.
+
+ -\b-c\bcs\bsc\bcw\bw, or -\b--\b-c\bcl\blo\bos\bsi\bin\bng\bg-\b-s\bsi\bid\bde\be-\b-c\bco\bom\bmm\bme\ben\bnt\bt-\b-w\bwa\bar\brn\bni\bin\bng\bgs\bs
+ 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 -\b-c\bcs\bsc\bc.
+
+ I\bIm\bmp\bpo\bor\brt\bta\ban\bnt\bt N\bNo\bot\bte\bes\bs o\bon\bn C\bCl\blo\bos\bsi\bin\bng\bg S\bSi\bid\bde\be C\bCo\bom\bmm\bme\ben\bnt\bts\bs:\b:
+
+ +\bo Closing side comments are only placed on lines terminated with a closing brace. Certain closing styles,
+ such as the use of cuddled elses (-\b-c\bce\be), preclude the generation of some closing side comments.
+
+ +\bo Please note that adding or deleting of closing side comments takes place only through the commands -\b-c\bcs\bsc\bc
+ or -\b-d\bdc\bcs\bsc\bc. The other commands, if used, merely modify the behavior of these two commands.
+
+ +\bo It is recommended that the -\b-c\bcs\bsc\bcw\bw flag be used along with -\b-c\bcs\bsc\bc 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.
+
+ +\bo Once you use -\b-c\bcs\bsc\bc, 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.
+
+ +\bo 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 -\b-c\bcs\bsc\bc. For example, you could simply change "## end" to be "## End", since the test is
+ case sensitive. You may also want to use the -\b-s\bss\bsc\bc flag to keep these modified closing side comments
+ spaced the same as actual closing side comments.
+
+ +\bo 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 -\b-d\bdc\bcs\bsc\bc.
+
+ S\bSt\bta\bat\bti\bic\bc B\bBl\blo\boc\bck\bk C\bCo\bom\bmm\bme\ben\bnt\bts\bs
+ 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.
+
+ -\b-s\bsb\bbc\bc, -\b--\b-s\bst\bta\bat\bti\bic\bc-\b-b\bbl\blo\boc\bck\bk-\b-c\bco\bom\bmm\bme\ben\bnt\bts\bs
+ When -\b-s\bsb\bbc\bc is used, a block comment with a special leading pattern, "##" by default, will be treated
+ specially.
+
+ Comments so identified are treated as follows:
+
+ +\bo If there is no leading space on the line, then the comment will not be indented, and otherwise it
+ may be,
+
+ +\bo no new blank line will be inserted before such a comment, and
+
+ +\bo 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 -\b-s\bsb\bbc\bc. This may be deactivated with -\b-n\bns\bsb\bbc\bc.
+
+ -\b-s\bsb\bbc\bcp\bp=\b=s\bst\btr\bri\bin\bng\bg, -\b--\b-s\bst\bta\bat\bti\bic\bc-\b-b\bbl\blo\boc\bck\bk-\b-c\bco\bom\bmm\bme\ben\bnt\bt-\b-p\bpr\bre\bef\bfi\bix\bx=\b=s\bst\btr\bri\bin\bng\bg
+ This parameter defines the prefix used to identify static block comments when the -\b-s\bsb\bbc\bc 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 -\b-s\bsb\bbc\bcp\bp merely defines the pattern used to identify static block comments; it will not be
+ used unless the switch -\b-s\bsb\bbc\bc 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 '#'.
+
+ -\b-o\bos\bsb\bbc\bc, -\b--\b-o\bou\but\btd\bde\ben\bnt\bt-\b-s\bst\bta\bat\bti\bic\bc-\b-b\bbl\blo\boc\bck\bk-\b-c\bco\bom\bmm\bme\ben\bnt\bts\bs
+ The command -\b-o\bos\bsb\bbc\bc will cause static block comments to be outdented by 2 spaces (or whatever -\b-c\bci\bi=\b=n\bn has
+ been set to), if possible.
+
+ S\bSt\bta\bat\bti\bic\bc S\bSi\bid\bde\be C\bCo\bom\bmm\bme\ben\bnt\bts\bs
+ 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.
+
+ -\b-s\bss\bsc\bc, -\b--\b-s\bst\bta\bat\bti\bic\bc-\b-s\bsi\bid\bde\be-\b-c\bco\bom\bmm\bme\ben\bnt\bts\bs
+ When -\b-s\bss\bsc\bc 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 -\b-n\bns\bss\bsc\bc.
+
+ -\b-s\bss\bsc\bcp\bp=\b=s\bst\btr\bri\bin\bng\bg, -\b--\b-s\bst\bta\bat\bti\bic\bc-\b-s\bsi\bid\bde\be-\b-c\bco\bom\bmm\bme\ben\bnt\bt-\b-p\bpr\bre\bef\bfi\bix\bx=\b=s\bst\btr\bri\bin\bng\bg
+ This parameter defines the prefix used to identify static side comments when the -\b-s\bss\bsc\bc parameter is set.
+ The default prefix is "##", corresponding to "-sscp=##".
+
+ Please note that -\b-s\bss\bsc\bcp\bp merely defines the pattern used to identify static side comments; it will not be
+ used unless the switch -\b-s\bss\bsc\bc 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.
+
+ S\bSk\bki\bip\bpp\bpi\bin\bng\bg S\bSe\bel\ble\bec\bct\bte\bed\bd S\bSe\bec\bct\bti\bio\bon\bns\bs o\bof\bf C\bCo\bod\bde\be
+ 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
+ -\b--\b-f\bfo\bor\brm\bma\bat\bt-\b-s\bsk\bki\bip\bpp\bpi\bin\bng\bg or -\b-f\bfs\bs, and the second option is called -\b--\b-c\bco\bod\bde\be-\b-s\bsk\bki\bip\bpp\bpi\bin\bng\bg or -\b-c\bcs\bs.
+
+ In both cases the lines of code will be output without any changes. The difference is that in -\b--\b-f\bfo\bor\brm\bma\bat\bt-\b-s\bsk\bki\bip\bpp\bpi\bin\bng\bg
+ perltidy will still parse the marked lines of code and check for errors, whereas in -\b--\b-c\bco\bod\bde\be-\b-s\bsk\bki\bip\bpp\bpi\bin\bng\bg 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. -\b--\b-f\bfo\bor\brm\bma\bat\bt-\b-s\bsk\bki\bip\bpp\bpi\bin\bng\bg
+ 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,);
+ #>>>
+
+ -\b--\b-c\bco\bod\bde\be-\b-s\bsk\bki\bip\bpp\bpi\bin\bng\bg uses starting and ending markers '#<<V' and '#>>V', like this:
+
+ #<<V code skipping: perltidy will pass this verbatim without error checking
+
+ token ident_digit {
+ [ [ <?word> | _ | <?digit> ] <?ident_digit>
+ | <''>
+ ]
+ };
+
+ #>>V
+
+ Additional text may appear on the special comment lines provided that it is separated from the marker by at
+ least one space, as in the above examples.
+
+ It is recommended to use -\b--\b-c\bco\bod\bde\be-\b-s\bsk\bki\bip\bpp\bpi\bin\bng\bg only if you need to hide a block of an extended syntax which would
+ produce errors if parsed by perltidy, and use -\b--\b-f\bfo\bor\brm\bma\bat\bt-\b-s\bsk\bki\bip\bpp\bpi\bin\bng\bg otherwise. This is because the
+ -\b--\b-f\bfo\bor\brm\bma\bat\bt-\b-s\bsk\bki\bip\bpp\bpi\bin\bng\bg option provides the benefits of error checking, and there are essentially no limitations on
+ which lines to which it can be applied. The -\b--\b-c\bco\bod\bde\be-\b-s\bsk\bki\bip\bpp\bpi\bin\bng\bg 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 -\b--\b-f\bfo\bor\brm\bma\bat\bt-\b-s\bsk\bki\bip\bpp\bpi\bin\bng\bg 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.
+
+ -\b-f\bfs\bs, -\b--\b-f\bfo\bor\brm\bma\bat\bt-\b-s\bsk\bki\bip\bpp\bpi\bin\bng\bg
+ 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 -\b-n\bnf\bfs\bs. This should not normally be necessary.
+
+ -\b-f\bfs\bsb\bb=\b=s\bst\btr\bri\bin\bng\bg, -\b--\b-f\bfo\bor\brm\bma\bat\bt-\b-s\bsk\bki\bip\bpp\bpi\bin\bng\bg-\b-b\bbe\beg\bgi\bin\bn=\b=s\bst\btr\bri\bin\bng\bg
+ 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 .\b.p\bpe\ber\brl\blt\bti\bid\bdy\byr\brc\bc 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 -\b-l\blo\bog\bg flag and examine the _\b._\bL_\bO_\bG file to see
+ if and where they are being detected.
+
+ The -\b-f\bfs\bsb\bb=\b=s\bst\btr\bri\bin\bng\bg 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 #*****
+
+ -\b-f\bfs\bse\be=\b=s\bst\btr\bri\bin\bng\bg, -\b--\b-f\bfo\bor\brm\bma\bat\bt-\b-s\bsk\bki\bip\bpp\bpi\bin\bng\bg-\b-e\ben\bnd\bd=\b=s\bst\btr\bri\bin\bng\bg
+ The -\b-f\bfs\bse\be=\b=s\bst\btr\bri\bin\bng\bg 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.
+
+ -\b-c\bcs\bs, -\b--\b-c\bco\bod\bde\be-\b-s\bsk\bki\bip\bpp\bpi\bin\bng\bg
+ As explained above, this flag, which is enabled by default, causes any code between special beginning and
+ ending comment markers to be directly passed to the output without any error checking or formatting.
+ Essentially, perltidy treats it as if it were a block of arbitrary text. The default beginning marker is
+ #<<V and the default ending marker is #>>V.
+
+ This feature can be disabled with -\b-n\bnc\bcs\bs. This should not normally be necessary.
+
+ -\b-c\bcs\bsb\bb=\b=s\bst\btr\bri\bin\bng\bg, -\b--\b-c\bco\bod\bde\be-\b-s\bsk\bki\bip\bpp\bpi\bin\bng\bg-\b-b\bbe\beg\bgi\bin\bn=\b=s\bst\btr\bri\bin\bng\bg
+ This may be used to change the beginning comment for a -\b--\b-c\bco\bod\bde\be-\b-s\bsk\bki\bip\bpp\bpi\bin\bng\bg section, and its use is similar to
+ the -\b-f\bfs\bsb\bb=\b=s\bst\btr\bri\bin\bng\bg. The default is equivalent to -csb='#<<V'.
+
+ -\b-c\bcs\bse\be=\b=s\bst\btr\bri\bin\bng\bg, -\b--\b-c\bco\bod\bde\be-\b-s\bsk\bki\bip\bpp\bpi\bin\bng\bg-\b-e\ben\bnd\bd=\b=s\bst\btr\bri\bin\bng\bg
+ This may be used to change the ending comment for a -\b--\b-c\bco\bod\bde\be-\b-s\bsk\bki\bip\bpp\bpi\bin\bng\bg section, and its use is similar to the
+ -\b-f\bfs\bse\be=\b=s\bst\btr\bri\bin\bng\bg. The default is equivalent to -cse='#>>V'.
+
+ L\bLi\bin\bne\be B\bBr\bre\bea\bak\bk C\bCo\bon\bnt\btr\bro\bol\bl
+ The parameters in this section control breaks after non-blank lines of code. Blank lines are controlled
+ separately by parameters in the section "Blank Line Control".
+
+ -\b-f\bfn\bnl\bl, -\b--\b-f\bfr\bre\bee\bez\bze\be-\b-n\bne\bew\bwl\bli\bin\bne\bes\bs
+ If you do not want any changes to the line breaks within lines of code in your script, set -\b-f\bfn\bnl\bl, and they
+ will remain fixed, and the rest of the commands in this section and sections "Controlling List Formatting",
+ "Retaining or Ignoring Existing Line Breaks". You may want to use -\b-n\bno\bol\bll\bl with this.
+
+ Note: If you also want to keep your blank lines exactly as they are, you can use the -\b-f\bfb\bbl\bl flag which is
+ described in the section "Blank Line Control".
+
+ -\b-c\bce\be, -\b--\b-c\bcu\bud\bdd\bdl\ble\bed\bd-\b-e\bel\bls\bse\be
+ Enable the "cuddled else" style, in which "else" and "elsif" are follow immediately after the curly brace
+ closing the previous block. The default is not to use cuddled elses, and is indicated with the flag -\b-n\bnc\bce\be or
+ -\b--\b-n\bno\boc\bcu\bud\bdd\bdl\ble\bed\bd-\b-e\bel\bls\bse\be. Here is a comparison of the alternatives:
+
+ # -ce
+ if ($task) {
+ yyy();
+ } else {
+ zzz();
+ }
+
+ # -nce (default)
+ if ($task) {
+ yyy();
+ }
+ else {
+ zzz();
+ }
+
+ In this example the keyword e\bel\bls\bse\be is placed on the same line which begins with the preceding closing block
+ brace and is followed by its own opening block brace on the same line. Other keywords and function names
+ which are formatted with this "cuddled" style are e\bel\bls\bsi\bif\bf, c\bco\bon\bnt\bti\bin\bnu\bue\be, c\bca\bat\btc\bch\bh, f\bfi\bin\bna\bal\bll\bly\by.
+
+ Other block types can be formatted by specifying their names on a separate parameter -\b-c\bcb\bbl\bl, described in a
+ later section.
+
+ Cuddling between a pair of code blocks requires that the closing brace of the first block start a new line.
+ If this block is entirely on one line in the input file, it is necessary to decide if it should be broken to
+ allow cuddling. This decision is controlled by the flag -\b-c\bcb\bbo\bo=\b=n\bn discussed below. The default and
+ recommended value of -\b-c\bcb\bbo\bo=\b=1\b1 bases this decision on the first block in the chain. If it spans multiple lines
+ then cuddling is made and continues along the chain, regardless of the sizes of subsequent blocks.
+ Otherwise, short lines remain intact.
+
+ So for example, the -\b-c\bce\be flag would not have any effect if the above snippet is rewritten as
+
+ if ($task) { yyy() }
+ else { zzz() }
+
+ If the first block spans multiple lines, then cuddling can be done and will continue for the subsequent
+ blocks in the chain, as illustrated in the previous snippet.
+
+ If there are blank lines between cuddled blocks they will be eliminated. If there are comments after the
+ closing brace where cuddling would occur then cuddling will be prevented. If this occurs, cuddling will
+ restart later in the chain if possible.
+
+ -\b-c\bcb\bb, -\b--\b-c\bcu\bud\bdd\bdl\ble\bed\bd-\b-b\bbl\blo\boc\bck\bks\bs
+ This flag is equivalent to -\b-c\bce\be.
+
+ -\b-c\bcb\bbl\bl, -\b--\b-c\bcu\bud\bdd\bdl\ble\bed\bd-\b-b\bbl\blo\boc\bck\bk-\b-l\bli\bis\bst\bt
+ The built-in default cuddled block types are e\bel\bls\bse\be,\b, e\bel\bls\bsi\bif\bf,\b, c\bco\bon\bnt\bti\bin\bnu\bue\be,\b, c\bca\bat\btc\bch\bh,\b, f\bfi\bin\bna\bal\bll\bly\by.
+
+ Additional block types to which the -\b-c\bcu\bud\bdd\bdl\ble\bed\bd-\b-b\bbl\blo\boc\bck\bks\bs style applies can be defined by this parameter. This
+ parameter is a character string, giving a list of block types separated by commas or spaces. For example,
+ to cuddle code blocks of type sort, map and grep, in addition to the default types, the string could be set
+ to
+
+ -cbl="sort map grep"
+
+ or equivalently
+
+ -cbl=sort,map,grep
+
+ Note however that these particular block types are typically short so there might not be much opportunity
+ for the cuddled format style.
+
+ Using commas avoids the need to protect spaces with quotes.
+
+ As a diagnostic check, the flag -\b--\b-d\bdu\bum\bmp\bp-\b-c\bcu\bud\bdd\bdl\ble\bed\bd-\b-b\bbl\blo\boc\bck\bk-\b-l\bli\bis\bst\bt or -\b-d\bdc\bcb\bbl\bl can be used to view the hash of values
+ that are generated by this flag.
+
+ Finally, note that the -\b-c\bcb\bbl\bl flag by itself merely specifies which blocks are formatted with the cuddled
+ format. It has no effect unless this formatting style is activated with -\b-c\bce\be.
+
+ -\b-c\bcb\bbl\blx\bx, -\b--\b-c\bcu\bud\bdd\bdl\ble\bed\bd-\b-b\bbl\blo\boc\bck\bk-\b-l\bli\bis\bst\bt-\b-e\bex\bxc\bcl\blu\bus\bsi\biv\bve\be
+ When cuddled else formatting is selected with -\b-c\bce\be, setting this flag causes perltidy to ignore its built-in
+ defaults and rely exclusively on the block types specified on the -\b-c\bcb\bbl\bl flag described in the previous
+ section. For example, to avoid using cuddled c\bca\bat\btc\bch\bh and f\bfi\bin\bna\bal\bll\bly\by, which among in the defaults, the following
+ set of parameters could be used:
+
+ perltidy -ce -cbl='else elsif continue' -cblx
+
+ -\b-c\bcb\bbo\bo=\b=n\bn, -\b--\b-c\bcu\bud\bdd\bdl\ble\bed\bd-\b-b\bbr\bre\bea\bak\bk-\b-o\bop\bpt\bti\bio\bon\bn=\b=n\bn
+ Cuddled formatting is only possible between a pair of code blocks if the closing brace of the first block
+ starts a new line. If a block is encountered which is entirely on a single line, and cuddled formatting is
+ selected, it is necessary to make a decision as to whether or not to "break" the block, meaning to cause it
+ to span multiple lines. This parameter controls that decision. The options are:
+
+ cbo=0 Never force a short block to break.
+ cbo=1 If the first of a pair of blocks is broken in the input file,
+ then break the second [DEFAULT].
+ cbo=2 Break open all blocks for maximal cuddled formatting.
+
+ The default and recommended value is c\bcb\bbo\bo=\b=1\b1. With this value, if the starting block of a chain spans
+ multiple lines, then a cascade of breaks will occur for remaining blocks causing the entire chain to be
+ cuddled.
+
+ The option c\bcb\bbo\bo=\b=0\b0 can produce erratic cuddling if there are numerous one-line blocks.
+
+ The option c\bcb\bbo\bo=\b=2\b2 produces maximal cuddling but will not allow any short blocks.
+
+ -\b-b\bbl\bl, -\b--\b-o\bop\bpe\ben\bni\bin\bng\bg-\b-b\bbr\bra\bac\bce\be-\b-o\bon\bn-\b-n\bne\bew\bw-\b-l\bli\bin\bne\be
+ Use the flag -\b-b\bbl\bl to place the opening brace on a new line:
+
+ if ( $input_file eq '-' ) # -bl
+ {
+ important_function();
+ }
+
+ This flag applies to all structural blocks, including named sub's (unless the -\b-s\bsb\bbl\bl flag is set -- see next
+ item).
+
+ The default style, -\b-n\bnb\bbl\bl, places an opening brace on the same line as the keyword introducing it. For
+ example,
+
+ if ( $input_file eq '-' ) { # -nbl (default)
+
+ -\b-s\bsb\bbl\bl, -\b--\b-o\bop\bpe\ben\bni\bin\bng\bg-\b-s\bsu\bub\bb-\b-b\bbr\bra\bac\bce\be-\b-o\bon\bn-\b-n\bne\bew\bw-\b-l\bli\bin\bne\be
+ The flag -\b-s\bsb\bbl\bl can be used to override the value of -\b-b\bbl\bl for the opening braces of named sub's. For example,
+
+ perltidy -sbl
+
+ produces this result:
+
+ sub message
+ {
+ if (!defined($_[0])) {
+ print("Hello, World\n");
+ }
+ else {
+ print($_[0], "\n");
+ }
+ }
+
+ This flag is negated with -\b-n\bns\bsb\bbl\bl. If -\b-s\bsb\bbl\bl is not specified, the value of -\b-b\bbl\bl is used.
+
+ -\b-a\bas\bsb\bbl\bl, -\b--\b-o\bop\bpe\ben\bni\bin\bng\bg-\b-a\ban\bno\bon\bny\bym\bmo\bou\bus\bs-\b-s\bsu\bub\bb-\b-b\bbr\bra\bac\bce\be-\b-o\bon\bn-\b-n\bne\bew\bw-\b-l\bli\bin\bne\be
+ The flag -\b-a\bas\bsb\bbl\bl is like the -\b-s\bsb\bbl\bl flag except that it applies to anonymous sub's instead of named subs. For
+ example
+
+ perltidy -asbl
+
+ produces this result:
+
+ $a = sub
+ {
+ if ( !defined( $_[0] ) ) {
+ print("Hello, World\n");
+ }
+ else {
+ print( $_[0], "\n" );
+ }
+ };
+
+ This flag is negated with -\b-n\bna\bas\bsb\bbl\bl, and the default is -\b-n\bna\bas\bsb\bbl\bl.
+
+ -\b-b\bbl\bli\bi, -\b--\b-b\bbr\bra\bac\bce\be-\b-l\ble\bef\bft\bt-\b-a\ban\bnd\bd-\b-i\bin\bnd\bde\ben\bnt\bt
+ The flag -\b-b\bbl\bli\bi is the same as -\b-b\bbl\bl but in addition it causes one unit of continuation indentation ( see -\b-c\bci\bi )
+ to be placed before an opening and closing block braces.
+
+ For example,
+
+ if ( $input_file eq '-' ) # -bli
+ {
+ important_function();
+ }
+
+ By default, this extra indentation occurs for blocks of type: i\bif\bf, e\bel\bls\bsi\bif\bf, e\bel\bls\bse\be, u\bun\bnl\ble\bes\bss\bs, f\bfo\bor\br, f\bfo\bor\bre\bea\bac\bch\bh, s\bsu\bub\bb,
+ w\bwh\bhi\bil\ble\be, u\bun\bnt\bti\bil\bl, and also with a preceding label. The next item shows how to change this.
+
+ -\b-b\bbl\bli\bil\bl=\b=s\bs, -\b--\b-b\bbr\bra\bac\bce\be-\b-l\ble\bef\bft\bt-\b-a\ban\bnd\bd-\b-i\bin\bnd\bde\ben\bnt\bt-\b-l\bli\bis\bst\bt=\b=s\bs
+ Use this parameter to change the types of block braces for which the -\b-b\bbl\bli\bi flag applies; see "Specifying
+ Block Types". For example, -\b-b\bbl\bli\bil\bl=\b='\b'i\bif\bf e\bel\bls\bsi\bif\bf e\bel\bls\bse\be'\b' would apply it to only "if/elsif/else" blocks.
+
+ -\b-b\bba\bar\br, -\b--\b-o\bop\bpe\ben\bni\bin\bng\bg-\b-b\bbr\bra\bac\bce\be-\b-a\bal\blw\bwa\bay\bys\bs-\b-o\bon\bn-\b-r\bri\big\bgh\bht\bt
+ The default style, -\b-n\bnb\bbl\bl places the opening code block brace on a new line if it does not fit on the same
+ line as the opening keyword, like this:
+
+ if ( $bigwasteofspace1 && $bigwasteofspace2
+ || $bigwasteofspace3 && $bigwasteofspace4 )
+ {
+ big_waste_of_time();
+ }
+
+ To force the opening brace to always be on the right, use the -\b-b\bba\bar\br flag. In this case, the above example
+ becomes
+
+ if ( $bigwasteofspace1 && $bigwasteofspace2
+ || $bigwasteofspace3 && $bigwasteofspace4 ) {
+ big_waste_of_time();
+ }
+
+ A conflict occurs if both -\b-b\bbl\bl and -\b-b\bba\bar\br are specified.
+
+ -\b-o\bot\btr\br, -\b--\b-o\bop\bpe\ben\bni\bin\bng\bg-\b-t\bto\bok\bke\ben\bn-\b-r\bri\big\bgh\bht\bt and related flags
+ The -\b-o\bot\btr\br flag is a hint that perltidy should not place a break between a comma and an opening token. For
+ example:
+
+ # default formatting
+ push @{ $self->{$module}{$key} },
+ {
+ accno => $ref->{accno},
+ description => $ref->{description}
+ };
+
+ # perltidy -otr
+ push @{ $self->{$module}{$key} }, {
+ accno => $ref->{accno},
+ description => $ref->{description}
+ };
+
+ The flag -\b-o\bot\btr\br 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
+
+ -\b-b\bbb\bbh\bhb\bb=\b=n\bn, -\b--\b-b\bbr\bre\bea\bak\bk-\b-b\bbe\bef\bfo\bor\bre\be-\b-h\bha\bas\bsh\bh-\b-b\bbr\bra\bac\bce\be=\b=n\bn 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 n\bn:
+
+ -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:
+
+ +\bo This parameter only applies if the opening brace is preceded by an '=' or '=>'.
+
+ +\bo 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.
+
+ +\bo For the n\bn=\b=2\b2 option, a list is considered 'complex' if it is part of a nested list structure which spans
+ multiple lines in the input file.
+
+ +\bo If multiple opening tokens have been 'welded' together with the -\b-w\bwn\bn parameter, then this parameter has
+ no effect.
+
+ +\bo The indentation of the braces will normally be one level of continuation indentation by default. This
+ can be changed with the parameter -\b-b\bbb\bbh\bhb\bbi\bi=\b=n\bn in the next section.
+
+ +\bo Similar flags for controlling parens and square brackets are given in the subsequent section.
+
+ -\b-b\bbb\bbh\bhb\bbi\bi=\b=n\bn, -\b--\b-b\bbr\bre\bea\bak\bk-\b-b\bbe\bef\bfo\bor\bre\be-\b-h\bha\bas\bsh\bh-\b-b\bbr\bra\bac\bce\be-\b-a\ban\bnd\bd-\b-i\bin\bnd\bde\ben\bnt\bt=\b=n\bn
+ This flag is a companion to -\b-b\bbb\bbh\bhb\bb=\b=n\bn 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 -\b-b\bbb\bbh\bhb\bb=\b=n\bn is also set.
+
+ -\b-b\bbb\bbs\bsb\bb=\b=n\bn, -\b--\b-b\bbr\bre\bea\bak\bk-\b-b\bbe\bef\bfo\bor\bre\be-\b-s\bsq\bqu\bua\bar\bre\be-\b-b\bbr\bra\bac\bck\bke\bet\bt=\b=n\bn
+ 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
+
+ -\b-b\bbb\bbs\bsb\bbi\bi=\b=n\bn, -\b--\b-b\bbr\bre\bea\bak\bk-\b-b\bbe\bef\bfo\bor\bre\be-\b-s\bsq\bqu\bua\bar\bre\be-\b-b\bbr\bra\bac\bck\bke\bet\bt-\b-a\ban\bnd\bd-\b-i\bin\bnd\bde\ben\bnt\bt=\b=n\bn
+ This flag is a companion to -\b-b\bbb\bbs\bsb\bb=\b=n\bn 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
+
+ -\b-b\bbb\bbp\bp=\b=n\bn, -\b--\b-b\bbr\bre\bea\bak\bk-\b-b\bbe\bef\bfo\bor\bre\be-\b-p\bpa\bar\bre\ben\bn=\b=n\bn
+ This flag is similar to -\b-b\bbb\bbh\bhb\bb=\b=n\bn, 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
+
+ -\b-b\bbb\bbp\bpi\bi=\b=n\bn, -\b--\b-b\bbr\bre\bea\bak\bk-\b-b\bbe\bef\bfo\bor\bre\be-\b-p\bpa\bar\bre\ben\bn-\b-a\ban\bnd\bd-\b-i\bin\bnd\bde\ben\bnt\bt=\b=n\bn
+ This flag is a companion to -\b-b\bbb\bbp\bp=\b=n\bn 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
+
+ -\b-w\bwn\bn, -\b--\b-w\bwe\bel\bld\bd-\b-n\bne\bes\bst\bte\bed\bd-\b-c\bco\bon\bnt\bta\bai\bin\bne\ber\brs\bs
+ The -\b-w\bwn\bn 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 -\b-c\bco\bon\bnv\bv 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 -\b-v\bvt\btc\bc=\b=n\bn flag
+ (described in the next section). For example, the same example adding -\b-v\bvt\btc\bc=\b=2\b2 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.
+
+ -\b-w\bwn\bnx\bxl\bl=\b=s\bs, -\b--\b-w\bwe\bel\bld\bd-\b-n\bne\bes\bst\bte\bed\bd-\b-e\bex\bxc\bcl\blu\bus\bsi\bio\bon\bn-\b-l\bli\bis\bst\bt
+ The -\b-w\bwn\bnx\bxl\bl=\b=s\bs flag provides some control over the types of containers which can be welded. The -\b-w\bwn\bn 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 n\bno\bot\bt
+ 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 N\bNO\bOT\bT 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 {{ ... }}
+
+ V\bVe\ber\brt\bti\bic\bca\bal\bl t\bti\big\bgh\bht\btn\bne\bes\bss\bs of non-block curly braces, parentheses, and square brackets.
+ These parameters control what shall be called vertical tightness. Here are the main points:
+
+ +\bo Opening tokens (except for block braces) are controlled by -\b-v\bvt\bt=\b=n\bn, or -\b--\b-v\bve\ber\brt\bti\bic\bca\bal\bl-\b-t\bti\big\bgh\bht\btn\bne\bes\bss\bs=\b=n\bn, 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
+
+ +\bo You must also use the -\b-l\blp\bp flag when you use the -\b-v\bvt\bt flag; the reason is explained below.
+
+ +\bo Closing tokens (except for block braces) are controlled by -\b-v\bvt\btc\bc=\b=n\bn, or -\b--\b-v\bve\ber\brt\bti\bic\bca\bal\bl-\b-t\bti\big\bgh\bht\btn\bne\bes\bss\bs-\b-c\bcl\blo\bos\bsi\bin\bng\bg=\b=n\bn,
+ 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 -\b-v\bvt\btc\bc=\b=1\b1 and -\b-v\bvt\btc\bc=\b=3\b3 are designed to maintain a reasonable balance between tightness and
+ readability in complex lists.
+
+ +\bo Different controls may be applied to different token types, and it is also possible to control block
+ braces; see below.
+
+ +\bo 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 -\b-l\blp\bp 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 -\b-v\bvt\btc\bc=\b=3\b3, the opening paren is preceded by an equals so the closing paren is placed on
+ a new line.
+
+ The difference between -\b-v\bvt\bt=\b=1\b1 and -\b-v\bvt\bt=\b=2\b2 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 -\b-v\bvt\bt=\b=1\b1, 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 -\b-v\bvt\bt=\b=2\b2 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 -\b-v\bvt\bt increases, but the indentation
+ remains unchanged. This is because perltidy implements the -\b-v\bvt\bt parameter by first formatting as if -\b-v\bvt\bt=\b=0\b0,
+ and then simply overwriting one output line on top of the next, if possible, to achieve the desired vertical
+ tightness. The -\b-l\blp\bp indentation style has been designed to allow this vertical collapse to occur, which is
+ why it is required for the -\b-v\bvt\bt parameter.
+
+ The -\b-v\bvt\bt=\b=n\bn and -\b-v\bvt\btc\bc=\b=n\bn 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 -\b-p\bpv\bvt\bt=\b=n\bn or -\b--\b-p\bpa\bar\bre\ben\bn-\b-v\bve\ber\brt\bti\bic\bca\bal\bl-\b-t\bti\big\bgh\bht\btn\bne\bes\bss\bs=\b=n\bn, and -\b-p\bpv\bvt\btc\bc=\b=n\bn or
+ -\b--\b-p\bpa\bar\bre\ben\bn-\b-v\bve\ber\brt\bti\bic\bca\bal\bl-\b-t\bti\big\bgh\bht\btn\bne\bes\bss\bs-\b-c\bcl\blo\bos\bsi\bin\bng\bg=\b=n\bn.
+
+ Likewise, the parameters for square brackets are -\b-s\bsb\bbv\bvt\bt=\b=n\bn or -\b--\b-s\bsq\bqu\bua\bar\bre\be-\b-b\bbr\bra\bac\bck\bke\bet\bt-\b-v\bve\ber\brt\bti\bic\bca\bal\bl-\b-t\bti\big\bgh\bht\btn\bne\bes\bss\bs=\b=n\bn, and
+ -\b-s\bsb\bbv\bvt\btc\bc=\b=n\bn or -\b--\b-s\bsq\bqu\bua\bar\bre\be-\b-b\bbr\bra\bac\bck\bke\bet\bt-\b-v\bve\ber\brt\bti\bic\bca\bal\bl-\b-t\bti\big\bgh\bht\btn\bne\bes\bss\bs-\b-c\bcl\blo\bos\bsi\bin\bng\bg=\b=n\bn.
+
+ Finally, the parameters for controlling non-code block braces are -\b-b\bbv\bvt\bt=\b=n\bn or -\b--\b-b\bbr\bra\bac\bce\be-\b-v\bve\ber\brt\bti\bic\bca\bal\bl-\b-t\bti\big\bgh\bht\btn\bne\bes\bss\bs=\b=n\bn,
+ and -\b-b\bbv\bvt\btc\bc=\b=n\bn or -\b--\b-b\bbr\bra\bac\bce\be-\b-v\bve\ber\brt\bti\bic\bca\bal\bl-\b-t\bti\big\bgh\bht\btn\bne\bes\bss\bs-\b-c\bcl\blo\bos\bsi\bin\bng\bg=\b=n\bn.
+
+ In fact, the parameter -\b-v\bvt\bt=\b=n\bn is actually just an abbreviation for -\b-p\bpv\bvt\bt=\b=n\bn -\b-b\bbv\bvt\bt=\b=n\bn s\bsb\bbv\bvt\bt=\b=n\bn, and likewise -\b-v\bvt\btc\bc=\b=n\bn
+ is an abbreviation for -\b-p\bpv\bvt\btc\bc=\b=n\bn -\b-b\bbv\bvt\btc\bc=\b=n\bn -\b-s\bsb\bbv\bvt\btc\bc=\b=n\bn.
+
+ -\b-b\bbb\bbv\bvt\bt=\b=n\bn or -\b--\b-b\bbl\blo\boc\bck\bk-\b-b\bbr\bra\bac\bce\be-\b-v\bve\ber\brt\bti\bic\bca\bal\bl-\b-t\bti\big\bgh\bht\btn\bne\bes\bss\bs=\b=n\bn
+ The -\b-b\bbb\bbv\bvt\bt=\b=n\bn flag is just like the -\b-v\bvt\bt=\b=n\bn 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 -\b-b\bbl\bl or -\b-b\bbl\bli\bi for this to work, because, as with other vertical tightness
+ controls, it is implemented by simply overwriting a line ending with an opening block brace with the
+ subsequent line. For example:
+
+ # perltidy -bli -bbvt=0
+ if ( open( FILE, "< $File" ) )
+ {
+ while ( $File = <FILE> )
+ {
+ $In .= $File;
+ $count++;
+ }
+ close(FILE);
+ }
+
+ # perltidy -bli -bbvt=1
+ if ( open( FILE, "< $File" ) )
+ { while ( $File = <FILE> )
+ { $In .= $File;
+ $count++;
+ }
+ close(FILE);
+ }
+
+ By default this applies to blocks associated with keywords i\bif\bf, e\bel\bls\bsi\bif\bf, e\bel\bls\bse\be, u\bun\bnl\ble\bes\bss\bs, f\bfo\bor\br, f\bfo\bor\bre\bea\bac\bch\bh, s\bsu\bub\bb,
+ w\bwh\bhi\bil\ble\be, u\bun\bnt\bti\bil\bl, and also with a preceding label. This can be changed with the parameter -\b-b\bbb\bbv\bvt\btl\bl=\b=s\bst\btr\bri\bin\bng\bg, or
+ -\b--\b-b\bbl\blo\boc\bck\bk-\b-b\bbr\bra\bac\bce\be-\b-v\bve\ber\brt\bti\bic\bca\bal\bl-\b-t\bti\big\bgh\bht\btn\bne\bes\bss\bs-\b-l\bli\bis\bst\bt=\b=s\bst\btr\bri\bin\bng\bg, where s\bst\btr\bri\bin\bng\bg 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 -\b-s\bsc\bcb\bbb\bb.
+
+ -\b-s\bso\bot\bt, -\b--\b-s\bst\bta\bac\bck\bk-\b-o\bop\bpe\ben\bni\bin\bng\bg-\b-t\bto\bok\bke\ben\bns\bs and related flags
+ The -\b-s\bso\bot\bt 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 -\b-s\bso\bot\bt is an abbreviation for -\b-s\bso\bop\bp -\b-s\bso\boh\bhb\bb -\b-s\bso\bos\bsb\bb.
+
+ The flag -\b-s\bso\bob\bbb\bb is an abbreviation for -\b-b\bbb\bbv\bvt\bt=\b=2\b2 -\b-b\bbb\bbv\bvt\btl\bl=\b='\b'*\b*'\b'. This will case a cascade of opening block braces
+ to appear on a single line, although this an uncommon occurrence except in test scripts.
+
+ -\b-s\bsc\bct\bt, -\b--\b-s\bst\bta\bac\bck\bk-\b-c\bcl\blo\bos\bsi\bin\bng\bg-\b-t\bto\bok\bke\ben\bns\bs and related flags
+ The -\b-s\bsc\bct\bt 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 -\b-s\bsc\bct\bt flag is somewhat similar to the -\b-v\bvt\btc\bc flags, and in some cases it can give a similar result. The
+ difference is that the -\b-v\bvt\btc\bc flags try to avoid lines with leading opening tokens by "hiding" them at the end
+ of a previous line, whereas the -\b-s\bsc\bct\bt 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 -\b-s\bsc\bct\bt is an abbreviation for stacking the non-block closing tokens, -\b-s\bsc\bcp\bp -\b-s\bsc\bch\bhb\bb -\b-s\bsc\bcs\bsb\bb.
+
+ Stacking of closing block braces, -\b-s\bsc\bcb\bbb\bb, 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 -\b-s\bsa\bac\bc or -\b--\b-s\bst\bta\bac\bck\bk-\b-a\bal\bll\bl-\b-c\bco\bon\bnt\bta\bai\bin\bne\ber\brs\bs is an abbreviation for -\b-s\bso\bot\bt -\b-s\bsc\bct\bt.
+
+ Please note that if both opening and closing tokens are to be stacked, then the newer flag
+ -\b-w\bwe\bel\bld\bd-\b-n\bne\bes\bst\bte\bed\bd-\b-c\bco\bon\bnt\bta\bai\bin\bne\ber\brs\bs 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 -\b-s\bso\bot\bt and -\b-s\bsc\bct\bt flags do.
+
+ -\b-d\bdn\bnl\bl, -\b--\b-d\bde\bel\ble\bet\bte\be-\b-o\bol\bld\bd-\b-n\bne\bew\bwl\bli\bin\bne\bes\bs
+ 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 -\b-n\bnd\bdn\bnl\bl or -\b--\b-n\bno\bod\bde\bel\ble\bet\bte\be-\b-o\bol\bld\bd-\b-n\bne\bew\bwl\bli\bin\bne\bes\bs to force perltidy to retain all old
+ line break points.
+
+ -\b-a\ban\bnl\bl, -\b--\b-a\bad\bdd\bd-\b-n\bne\bew\bwl\bli\bin\bne\bes\bs
+ By default, perltidy will add line breaks when necessary to create continuations of long lines and to
+ improve the script appearance. Use -\b-n\bna\ban\bnl\bl or -\b--\b-n\bno\boa\bad\bdd\bd-\b-n\bne\bew\bwl\bli\bin\bne\bes\bs to prevent any new line breaks.
+
+ This flag does not prevent perltidy from eliminating existing line breaks; see -\b--\b-f\bfr\bre\bee\bez\bze\be-\b-n\bne\bew\bwl\bli\bin\bne\bes\bs to
+ completely prevent changes to line break points.
+
+ C\bCo\bon\bnt\btr\bro\bol\bll\bli\bin\bng\bg w\bwh\bhe\bet\bth\bhe\ber\br p\bpe\ber\brl\blt\bti\bid\bdy\by b\bbr\bre\bea\bak\bks\bs b\bbe\bef\bfo\bor\bre\be o\bor\br a\baf\bft\bte\ber\br o\bop\bpe\ber\bra\bat\bto\bor\brs\bs
+ 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:
+
+ -\b-w\bwb\bba\ba=\b=s\bs or -\b--\b-w\bwa\ban\bnt\bt-\b-b\bbr\bre\bea\bak\bk-\b-a\baf\bft\bte\ber\br=\b=s\bs, and
+
+ -\b-w\bwb\bbb\bb=\b=s\bs or -\b--\b-w\bwa\ban\bnt\bt-\b-b\bbr\bre\bea\bak\bk-\b-b\bbe\bef\bfo\bor\bre\be=\b=s\bs.
+
+ These parameters are each followed by a quoted string, s\bs, 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 a\baf\bft\bte\ber\br these token types:
+ % + - * / x != == >= <= =~ !~ < > | &
+ = **= += *= &= <<= &&= -= /= |= >>= ||= //= .= %= ^= x=
+
+ And perltidy breaks b\bbe\bef\bfo\bor\bre\be 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 -\b--\b-d\bdu\bum\bmp\bp-\b-t\bto\bok\bke\ben\bn-\b-t\bty\byp\bpe\bes\bs for a
+ list). Also try the -\b-D\bD 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 b\bbl\bl provided for that purpose.
+
+ W\bWA\bAR\bRN\bNI\bIN\bNG\bG 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:
+
+ -\b-b\bba\baa\bao\bo or -\b--\b-b\bbr\bre\bea\bak\bk-\b-a\baf\bft\bte\ber\br-\b-a\bal\bll\bl-\b-o\bop\bpe\ber\bra\bat\bto\bor\brs\bs,
+
+ -\b-b\bbb\bba\bao\bo or -\b--\b-b\bbr\bre\bea\bak\bk-\b-b\bbe\bef\bfo\bor\bre\be-\b-a\bal\bll\bl-\b-o\bop\bpe\ber\bra\bat\bto\bor\brs\bs.
+
+ The -baao sets the default to be to break after all of the following operators:
+
+ % + - * / x != == >= <= =~ !~ < > | &
+ = **= += *= &= <<= &&= -= /= |= >>= ||= //= .= %= ^= x=
+ . : ? && || and or err xor
+
+ and the -\b-b\bbb\bba\bao\bo 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 -\b-w\bwb\bba\ba and -\b-w\bwb\bbb\bb flags. For example, to break before
+ all operators except an =\b= one could use --bbao -wba='=' rather than listing every single perl operator
+ except =\b= on a -wbb flag.
+
+ C\bCo\bon\bnt\btr\bro\bol\bll\bli\bin\bng\bg L\bLi\bis\bst\bt F\bFo\bor\brm\bma\bat\btt\bti\bin\bng\bg
+ 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".
+
+ -\b-b\bbo\boc\bc, -\b--\b-b\bbr\bre\bea\bak\bk-\b-a\bat\bt-\b-o\bol\bld\bd-\b-c\bco\bom\bmm\bma\ba-\b-b\bbr\bre\bea\bak\bkp\bpo\boi\bin\bnt\bts\bs
+ The -\b-b\bbo\boc\bc flag is another way to prevent comma-separated lists from being reformatted. Using -\b-b\bbo\boc\bc 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.
+
+ -\b-m\bmf\bft\bt=\b=n\bn, -\b--\b-m\bma\bax\bxi\bim\bmu\bum\bm-\b-f\bfi\bie\bel\bld\bds\bs-\b-p\bpe\ber\br-\b-t\bta\bab\bbl\ble\be=\b=n\bn
+ If the computed number of fields for any table exceeds n\bn, then it will be reduced to n\bn. The default value
+ for n\bn 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 -\b-b\bbo\boc\bc 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'
+ );
+
+ -\b-c\bca\bab\bb=\b=n\bn, -\b--\b-c\bco\bom\bmm\bma\ba-\b-a\bar\brr\bro\bow\bw-\b-b\bbr\bre\bea\bak\bkp\bpo\boi\bin\bnt\bts\bs=\b=n\bn
+ 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 -\b-b\bbo\boc\bc is used). The possible
+ values of n\bn 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 -\b-c\bca\bab\bb=\b=0\b0 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 -\b-c\bca\bab\bb=\b=2\b2 could be used.
+
+ The flag -\b-c\bca\bab\bb=\b=3\b3 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
+ );
+
+ R\bRe\bet\bta\bai\bin\bni\bin\bng\bg o\bor\br I\bIg\bgn\bno\bor\bri\bin\bng\bg E\bEx\bxi\bis\bst\bti\bin\bng\bg L\bLi\bin\bne\be B\bBr\bre\bea\bak\bks\bs
+ 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.
+
+ -\b-b\bbo\bol\bl, -\b--\b-b\bbr\bre\bea\bak\bk-\b-a\bat\bt-\b-o\bol\bld\bd-\b-l\blo\bog\bgi\bic\bca\bal\bl-\b-b\bbr\bre\bea\bak\bkp\bpo\boi\bin\bnt\bts\bs
+ 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 -\b-n\bnb\bbo\bol\bl.
+
+ 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('|');
+
+ -\b-b\bbo\bom\bm, -\b--\b-b\bbr\bre\bea\bak\bk-\b-a\bat\bt-\b-o\bol\bld\bd-\b-m\bme\bet\bth\bho\bod\bd-\b-b\bbr\bre\bea\bak\bkp\bpo\boi\bin\bnt\bts\bs
+ 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 -\b-b\bbo\bom\bm, 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 k\bke\bee\bep\bp 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 -\b-w\bwe\bel\bld\bd-\b-n\bne\bes\bst\bte\bed\bd-\b-c\bco\bon\bnt\bta\bai\bin\bne\ber\brs\bs flag in this case to keep nested braces and parens
+ together, as in the last line.
+
+ -\b-b\bbo\bos\bs, -\b--\b-b\bbr\bre\bea\bak\bk-\b-a\bat\bt-\b-o\bol\bld\bd-\b-s\bse\bem\bmi\bic\bco\bol\blo\bon\bn-\b-b\bbr\bre\bea\bak\bkp\bpo\boi\bin\bnt\bts\bs
+ 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 p\bpe\ber\brl\blt\bti\bid\bdy\by -\b-b\bbo\bos\bs keeps the isolated semicolon:
+
+ $z = sqrt( $x**2 + $y**2 )
+ ;
+
+ The default is not to do this, -\b-n\bnb\bbo\bos\bs.
+
+ -\b-b\bbo\bok\bk, -\b--\b-b\bbr\bre\bea\bak\bk-\b-a\bat\bt-\b-o\bol\bld\bd-\b-k\bke\bey\byw\bwo\bor\brd\bd-\b-b\bbr\bre\bea\bak\bkp\bpo\boi\bin\bnt\bts\bs
+ By default, perltidy will retain a breakpoint before keywords which may return lists, such as "sort" and
+ <map>. This allows chains of these operators to be displayed one per line. Use -\b-n\bnb\bbo\bok\bk to prevent retaining
+ these breakpoints.
+
+ -\b-b\bbo\bot\bt, -\b--\b-b\bbr\bre\bea\bak\bk-\b-a\bat\bt-\b-o\bol\bld\bd-\b-t\bte\ber\brn\bna\bar\bry\by-\b-b\bbr\bre\bea\bak\bkp\bpo\boi\bin\bnt\bts\bs
+ 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 -\b-n\bnb\bbo\bot\bt.
+
+ -\b-b\bbo\boa\ba, -\b--\b-b\bbr\bre\bea\bak\bk-\b-a\bat\bt-\b-o\bol\bld\bd-\b-a\bat\btt\btr\bri\bib\bbu\but\bte\be-\b-b\bbr\bre\bea\bak\bkp\bpo\boi\bin\bnt\bts\bs
+ 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 -\b-n\bnb\bbo\boa\ba.
+
+ K\bKe\bee\bep\bpi\bin\bng\bg o\bol\bld\bd b\bbr\bre\bea\bak\bkp\bpo\boi\bin\bnt\bts\bs a\bat\bt s\bsp\bpe\bec\bci\bif\bfi\bic\bc t\bto\bok\bke\ben\bn t\bty\byp\bpe\bes\bs
+ Two command line parameters provide detailed control over whether perltidy should keep an old line break
+ before or after a specific token type:
+
+ -\b-k\bkb\bbb\bb=\b=s\bs or -\b--\b-k\bke\bee\bep\bp-\b-o\bol\bld\bd-\b-b\bbr\bre\bea\bak\bkp\bpo\boi\bin\bnt\bts\bs-\b-b\bbe\bef\bfo\bor\bre\be=\b=s\bs, and
+
+ -\b-k\bkb\bba\ba=\b=s\bs or -\b--\b-k\bke\bee\bep\bp-\b-o\bol\bld\bd-\b-b\bbr\bre\bea\bak\bkp\bpo\boi\bin\bnt\bts\bs-\b-a\baf\bft\bte\ber\br=\b=s\bs
+
+ These parameters are each followed by a quoted string, s\bs, 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, @_ );
+ ...;
+ };
+
+ -\b-i\bio\bob\bb, -\b--\b-i\big\bgn\bno\bor\bre\be-\b-o\bol\bld\bd-\b-b\bbr\bre\bea\bak\bkp\bpo\boi\bin\bnt\bts\bs
+ 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.
+
+ -\b-k\bki\bis\bs, -\b--\b-k\bke\bee\bep\bp-\b-i\bin\bnt\bte\ber\bri\bio\bor\br-\b-s\bse\bem\bmi\bic\bco\bol\blo\bon\bns\bs
+ Use the -\b-k\bki\bis\bs 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 p\bpe\ber\brl\blt\bti\bid\bdy\by -\b-k\bki\bis\bs 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 m\bma\bax\bxi\bim\bmu\bum\bm-\b-l\bli\bin\bne\be-\b-l\ble\ben\bng\bgt\bth\bh and will be broken if this
+ maximum is exceeded.
+
+ B\bBl\bla\ban\bnk\bk L\bLi\bin\bne\be C\bCo\bon\bnt\btr\bro\bol\bl
+ 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.
+
+ -\b-f\bfb\bbl\bl, -\b--\b-f\bfr\bre\bee\bez\bze\be-\b-b\bbl\bla\ban\bnk\bk-\b-l\bli\bin\bne\bes\bs
+ Set -\b-f\bfb\bbl\bl 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 -\b-f\bfb\bbl\bl flag is equivalent to setting
+ -\b-m\bmb\bbl\bl=\b=0\b0 and -\b-k\bkb\bbl\bl=\b=2\b2).
+
+ -\b-b\bbb\bbc\bc, -\b--\b-b\bbl\bla\ban\bnk\bks\bs-\b-b\bbe\bef\bfo\bor\bre\be-\b-c\bco\bom\bmm\bme\ben\bnt\bts\bs
+ A blank line will be introduced before a full-line comment. This is the default. Use -\b-n\bnb\bbb\bbc\bc or
+ -\b--\b-n\bno\bob\bbl\bla\ban\bnk\bks\bs-\b-b\bbe\bef\bfo\bor\bre\be-\b-c\bco\bom\bmm\bme\ben\bnt\bts\bs to prevent such blank lines from being introduced.
+
+ -\b-b\bbl\blb\bbs\bs=\b=n\bn, -\b--\b-b\bbl\bla\ban\bnk\bk-\b-l\bli\bin\bne\bes\bs-\b-b\bbe\bef\bfo\bor\bre\be-\b-s\bsu\bub\bbs\bs=\b=n\bn
+ The parameter -\b-b\bbl\blb\bbs\bs=\b=n\bn requests that least n\bn 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>. B\bBE\bEG\bGI\bIN\bN and E\bEN\bND\bD blocks are included.
+
+ The requested number of blanks statement will be inserted regardless of the value of
+ -\b--\b-m\bma\bax\bxi\bim\bmu\bum\bm-\b-c\bco\bon\bns\bse\bec\bcu\but\bti\biv\bve\be-\b-b\bbl\bla\ban\bnk\bk-\b-l\bli\bin\bne\bes\bs=\b=n\bn (-\b-m\bmb\bbl\bl=\b=n\bn) with the exception that if -\b-m\bmb\bbl\bl=\b=0\b0 then no blanks will be
+ output.
+
+ This parameter interacts with the value k\bk of the parameter -\b--\b-m\bma\bax\bxi\bim\bmu\bum\bm-\b-c\bco\bon\bns\bse\bec\bcu\but\bti\biv\bve\be-\b-b\bbl\bla\ban\bnk\bk-\b-l\bli\bin\bne\bes\bs=\b=k\bk (-\b-m\bmb\bbl\bl=\b=k\bk) as
+ follows:
+
+ 1. If -\b-m\bmb\bbl\bl=\b=0\b0 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 n\bn then additional blanks will be inserted to
+ make the total n\bn regardless of the value of -\b-m\bmb\bbl\bl=\b=k\bk.
+
+ 3. If the number of old blank lines in the script equals or exceeds n\bn then this parameter has no effect,
+ however the total will not exceed value specified on the -\b-m\bmb\bbl\bl=\b=k\bk flag.
+
+ -\b-b\bbl\blb\bbp\bp=\b=n\bn, -\b--\b-b\bbl\bla\ban\bnk\bk-\b-l\bli\bin\bne\bes\bs-\b-b\bbe\bef\bfo\bor\bre\be-\b-p\bpa\bac\bck\bka\bag\bge\bes\bs=\b=n\bn
+ The parameter -\b-b\bbl\blb\bbp\bp=\b=n\bn requests that least n\bn blank lines precede a package which does not follow a comment.
+ The default is -\b-b\bbl\blb\bbp\bp=\b=1\b1.
+
+ This parameter interacts with the value k\bk of the parameter -\b--\b-m\bma\bax\bxi\bim\bmu\bum\bm-\b-c\bco\bon\bns\bse\bec\bcu\but\bti\biv\bve\be-\b-b\bbl\bla\ban\bnk\bk-\b-l\bli\bin\bne\bes\bs=\b=k\bk (-\b-m\bmb\bbl\bl=\b=k\bk) in
+ the same way as described for the previous item -\b-b\bbl\blb\bbs\bs=\b=n\bn.
+
+ -\b-b\bbb\bbs\bs, -\b--\b-b\bbl\bla\ban\bnk\bks\bs-\b-b\bbe\bef\bfo\bor\bre\be-\b-s\bsu\bub\bbs\bs
+ For compatibility with previous versions, -\b-b\bbb\bbs\bs or -\b--\b-b\bbl\bla\ban\bnk\bks\bs-\b-b\bbe\bef\bfo\bor\bre\be-\b-s\bsu\bub\bbs\bs is equivalent to _\b-_\bb_\bl_\bb_\bp_\b=_\b1 and _\b-_\bb_\bl_\bb_\bs_\b=_\b1.
+
+ Likewise, -\b-n\bnb\bbb\bbs\bs or -\b--\b-n\bno\bob\bbl\bla\ban\bnk\bks\bs-\b-b\bbe\bef\bfo\bor\bre\be-\b-s\bsu\bub\bbs\bs is equivalent to _\b-_\bb_\bl_\bb_\bp_\b=_\b0 and _\b-_\bb_\bl_\bb_\bs_\b=_\b0.
+
+ -\b-b\bbb\bbb\bb, -\b--\b-b\bbl\bla\ban\bnk\bks\bs-\b-b\bbe\bef\bfo\bor\bre\be-\b-b\bbl\blo\boc\bck\bks\bs
+ A blank line will be introduced before blocks of coding delimited by f\bfo\bor\br, f\bfo\bor\bre\bea\bac\bch\bh, w\bwh\bhi\bil\ble\be, u\bun\bnt\bti\bil\bl, and i\bif\bf,
+ u\bun\bnl\ble\bes\bss\bs, in the following circumstances:
+
+ +\bo The block is not preceded by a comment.
+
+ +\bo The block is not a one-line block.
+
+ +\bo The number of consecutive non-blank lines at the current indentation depth is at least -\b-l\blb\bbl\bl (see next
+ section).
+
+ This is the default. The intention of this option is to introduce some space within dense coding. This is
+ negated with -\b-n\bnb\bbb\bbb\bb or -\b--\b-n\bno\bob\bbl\bla\ban\bnk\bks\bs-\b-b\bbe\bef\bfo\bor\bre\be-\b-b\bbl\blo\boc\bck\bks\bs.
+
+ -\b-l\blb\bbl\bl=\b=n\bn -\b--\b-l\blo\bon\bng\bg-\b-b\bbl\blo\boc\bck\bk-\b-l\bli\bin\bne\be-\b-c\bco\bou\bun\bnt\bt=\b=n\bn
+ 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 0\b0 is equivalent to entering a very large number.
+
+ -\b-b\bbl\bla\bao\bo=\b=i\bi or -\b--\b-b\bbl\bla\ban\bnk\bk-\b-l\bli\bin\bne\bes\bs-\b-a\baf\bft\bte\ber\br-\b-o\bop\bpe\ben\bni\bin\bng\bg-\b-b\bbl\blo\boc\bck\bk=\b=i\bi
+ This control places a minimum of i\bi blank lines a\baf\bft\bte\ber\br a line which e\ben\bnd\bds\bs with an opening block brace of a
+ specified type. By default, this only applies to the block of a named s\bsu\bub\bb, but this can be changed (see
+ -\b-b\bbl\bla\bao\bol\bl below). The default is not to do this (i\bi=\b=0\b0).
+
+ Please see the note below on using the -\b-b\bbl\bla\bao\bo and -\b-b\bbl\blb\bbc\bc options.
+
+ -\b-b\bbl\blb\bbc\bc=\b=i\bi or -\b--\b-b\bbl\bla\ban\bnk\bk-\b-l\bli\bin\bne\bes\bs-\b-b\bbe\bef\bfo\bor\bre\be-\b-c\bcl\blo\bos\bsi\bin\bng\bg-\b-b\bbl\blo\boc\bck\bk=\b=i\bi
+ This control places a minimum of i\bi blank lines b\bbe\bef\bfo\bor\bre\be a line which b\bbe\beg\bgi\bin\bns\bs with a closing block brace of a
+ specified type. By default, this only applies to the block of a named s\bsu\bub\bb, but this can be changed (see
+ -\b-b\bbl\blb\bbc\bcl\bl below). The default is not to do this (i\bi=\b=0\b0).
+
+ -\b-b\bbl\bla\bao\bol\bl=\b=s\bs or -\b--\b-b\bbl\bla\ban\bnk\bk-\b-l\bli\bin\bne\bes\bs-\b-a\baf\bft\bte\ber\br-\b-o\bop\bpe\ben\bni\bin\bng\bg-\b-b\bbl\blo\boc\bck\bk-\b-l\bli\bis\bst\bt=\b=s\bs
+ The parameter s\bs is a list of block type keywords to which the flag -\b-b\bbl\bla\bao\bo should apply. The section
+ "Specifying Block Types" explains how to list block types.
+
+ -\b-b\bbl\blb\bbc\bcl\bl=\b=s\bs or -\b--\b-b\bbl\bla\ban\bnk\bk-\b-l\bli\bin\bne\bes\bs-\b-b\bbe\bef\bfo\bor\bre\be-\b-c\bcl\blo\bos\bsi\bin\bng\bg-\b-b\bbl\blo\boc\bck\bk-\b-l\bli\bis\bst\bt=\b=s\bs
+ This parameter is a list of block type keywords to which the flag -\b-b\bbl\blb\bbc\bc should apply. The section
+ "Specifying Block Types" explains how to list block types.
+
+ N\bNo\bot\bte\be o\bon\bn u\bus\bsi\bin\bng\bg t\bth\bhe\be -\b-b\bbl\bla\bao\bo and -\b-b\bbl\blb\bbc\bc 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 -\b-b\bbl\bla\bao\bo=\b=0\b0 and -\b-b\bbl\blb\bbc\bc=\b=0\b0 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 -\b-k\bkb\bbl\bl=\b=0\b0
+ 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.
+
+ -\b-m\bmb\bbl\bl=\b=n\bn -\b--\b-m\bma\bax\bxi\bim\bmu\bum\bm-\b-c\bco\bon\bns\bse\bec\bcu\but\bti\biv\bve\be-\b-b\bbl\bla\ban\bnk\bk-\b-l\bli\bin\bne\bes\bs=\b=n\bn
+ 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 -\b-b\bbl\blb\bbp\bp and -\b-b\bbl\blb\bbs\bs parameters. If n\bn=\b=0\b0 then no blank
+ lines will be output (unless all old blank lines are retained with the -\b-k\bkb\bbl\bl=\b=2\b2 flag of the next section).
+
+ This flag obviously does not apply to pod sections, here-documents, and quotes.
+
+ -\b-k\bkb\bbl\bl=\b=n\bn, -\b--\b-k\bke\bee\bep\bp-\b-o\bol\bld\bd-\b-b\bbl\bla\ban\bnk\bk-\b-l\bli\bin\bne\bes\bs=\b=n\bn
+ The -\b-k\bkb\bbl\bl=\b=n\bn flag gives you control over how your existing blank lines are treated.
+
+ The possible values of n\bn 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 n\bn=\b=1\b1.
+
+ -\b-s\bso\bob\bb, -\b--\b-s\bsw\bwa\bal\bll\blo\bow\bw-\b-o\bop\bpt\bti\bio\bon\bna\bal\bl-\b-b\bbl\bla\ban\bnk\bk-\b-l\bli\bin\bne\bes\bs
+ This is equivalent to k\bkb\bbl\bl=\b=0\b0 and is included for compatibility with previous versions.
+
+ -\b-n\bns\bso\bob\bb, -\b--\b-n\bno\bos\bsw\bwa\bal\bll\blo\bow\bw-\b-o\bop\bpt\bti\bio\bon\bna\bal\bl-\b-b\bbl\bla\ban\bnk\bk-\b-l\bli\bin\bne\bes\bs
+ This is equivalent to k\bkb\bbl\bl=\b=1\b1 and is included for compatibility with previous versions.
+
+ C\bCo\bon\bnt\btr\bro\bol\bls\bs f\bfo\bor\br b\bbl\bla\ban\bnk\bk l\bli\bin\bne\bes\bs a\bar\bro\bou\bun\bnd\bd l\bli\bin\bne\bes\bs o\bof\bf c\bco\bon\bns\bse\bec\bcu\but\bti\biv\bve\be k\bke\bey\byw\bwo\bor\brd\bds\bs
+
+ 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 k\bke\bey\byw\bwo\bor\brd\bd g\bgr\bro\bou\bup\bp b\bbl\bla\ban\bnk\bks\bs, and all
+ of the parameters begin with -\b--\b-k\bke\bey\byw\bwo\bor\brd\bd-\b-g\bgr\bro\bou\bup\bp-\b-b\bbl\bla\ban\bnk\bks\bs*\b*, or -\b-k\bkg\bgb\bb*\b* for short. The default settings do not employ
+ these controls but they can be enabled with the following parameters:
+
+ -\b-k\bkg\bgb\bbl\bl=\b=s\bs or -\b--\b-k\bke\bey\byw\bwo\bor\brd\bd-\b-g\bgr\bro\bou\bup\bp-\b-b\bbl\bla\ban\bnk\bks\bs-\b-l\bli\bis\bst\bt=\b=s\bs; s\bs is a quoted string of keywords
+
+ -\b-k\bkg\bgb\bbs\bs=\b=s\bs or -\b--\b-k\bke\bey\byw\bwo\bor\brd\bd-\b-g\bgr\bro\bou\bup\bp-\b-b\bbl\bla\ban\bnk\bks\bs-\b-s\bsi\biz\bze\be=\b=s\bs; s\bs gives the number of keywords required to form a group.
+
+ -\b-k\bkg\bgb\bbb\bb=\b=n\bn or -\b--\b-k\bke\bey\byw\bwo\bor\brd\bd-\b-g\bgr\bro\bou\bup\bp-\b-b\bbl\bla\ban\bnk\bks\bs-\b-b\bbe\bef\bfo\bor\bre\be=\b=n\bn; n\bn = (0, 1, or 2) controls a leading blank
+
+ -\b-k\bkg\bgb\bba\ba=\b=n\bn or -\b--\b-k\bke\bey\byw\bwo\bor\brd\bd-\b-g\bgr\bro\bou\bup\bp-\b-b\bbl\bla\ban\bnk\bks\bs-\b-a\baf\bft\bte\ber\br=\b=n\bn; n\bn = (0, 1, or 2) controls a trailing blank
+
+ -\b-k\bkg\bgb\bbi\bi or -\b--\b-k\bke\bey\byw\bwo\bor\brd\bd-\b-g\bgr\bro\bou\bup\bp-\b-b\bbl\bla\ban\bnk\bks\bs-\b-i\bin\bns\bsi\bid\bde\be is a switch for adding blanks between subgroups
+
+ -\b-k\bkg\bgb\bbd\bd or -\b--\b-k\bke\bey\byw\bwo\bor\brd\bd-\b-g\bgr\bro\bou\bup\bp-\b-b\bbl\bla\ban\bnk\bks\bs-\b-d\bde\bel\ble\bet\bte\be is a switch for removing initial blank lines between keywords
+
+ -\b-k\bkg\bgb\bbr\br=\b=n\bn or -\b--\b-k\bke\bey\byw\bwo\bor\brd\bd-\b-g\bgr\bro\bou\bup\bp-\b-b\bbl\bla\ban\bnk\bks\bs-\b-r\bre\bep\bpe\bea\bat\bt-\b-c\bco\bou\bun\bnt\bt=\b=n\bn can limit the number of times this logic is applied
+
+ In addition, the following abbreviations are available to for simplified usage:
+
+ -\b-k\bkg\bgb\bb or -\b--\b-k\bke\bey\byw\bwo\bor\brd\bd-\b-g\bgr\bro\bou\bup\bp-\b-b\bbl\bla\ban\bnk\bks\bs is short for -\b-k\bkg\bgb\bbb\bb=\b=2\b2 -\b-k\bkg\bgb\bba\ba=\b=2\b2 k\bkg\bgb\bbi\bi
+
+ -\b-n\bnk\bkg\bgb\bb or -\b--\b-n\bno\bok\bke\bey\byw\bwo\bor\brd\bd-\b-g\bgr\bro\bou\bup\bp-\b-b\bbl\bla\ban\bnk\bks\bs, is short for -\b-k\bkg\bgb\bbb\bb=\b=1\b1 -\b-k\bkg\bgb\bba\ba=\b=1\b1 n\bnk\bkg\bgb\bbi\bi
+
+ 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 p\bpe\ber\brl\blt\bti\bid\bdy\by -\b-k\bkg\bgb\bb 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 m\bmy\by and u\bus\bse\be sequences. What happened is that the default keyword
+ list includes m\bmy\by and u\bus\bse\be but not p\bpr\bri\bin\bnt\bt and r\bre\bet\btu\bur\brn\bn. So a continuous sequence of nine m\bmy\by and u\bus\bse\be 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 m\bmy\by 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 -\b-k\bkg\bgb\bb flag.
+ The individual controls are as follows.
+
+ -\b-k\bkg\bgb\bbl\bl=\b=s\bs or -\b--\b-k\bke\bey\byw\bwo\bor\brd\bd-\b-g\bgr\bro\bou\bup\bp-\b-b\bbl\bla\ban\bnk\bks\bs-\b-l\bli\bis\bst\bt=\b=s\bs, where s\bs 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 s\bs=\b="\b"u\bus\bse\be r\bre\beq\bqu\bui\bir\bre\be l\blo\boc\bca\bal\bl
+ o\bou\bur\br m\bmy\by"\b", 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 B\bBC\bC. To include static
+ block comments (which normally begin with '##'), include the symbol S\bSB\bBC\bC.
+
+ -\b-k\bkg\bgb\bbs\bs=\b=s\bs or -\b--\b-k\bke\bey\byw\bwo\bor\brd\bd-\b-g\bgr\bro\bou\bup\bp-\b-b\bbl\bla\ban\bnk\bks\bs-\b-s\bsi\biz\bze\be=\b=s\bs, where s\bs is a string describing the number of consecutive keyword
+ statements forming a group. If s\bs is an integer then it is the minimum number required for a group. A maximum
+ value may also be given with the format s\bs=\b=m\bmi\bin\bn.\b.m\bma\bax\bx, where m\bmi\bin\bn is the minimum number and m\bma\bax\bx 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 s\bs=\b=5\b5. 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)
+
+ -\b-k\bkg\bgb\bbb\bb=\b=n\bn or -\b--\b-k\bke\bey\byw\bwo\bor\brd\bd-\b-g\bgr\bro\bou\bup\bp-\b-b\bbl\bla\ban\bnk\bks\bs-\b-b\bbe\bef\bfo\bor\bre\be=\b=n\bn 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
+
+ -\b-k\bkg\bgb\bba\ba=\b=n\bn or -\b--\b-k\bke\bey\byw\bwo\bor\brd\bd-\b-g\bgr\bro\bou\bup\bp-\b-b\bbl\bla\ban\bnk\bks\bs-\b-a\baf\bft\bte\ber\br=\b=n\bn likewise specifies whether a blank should appear after the last line
+ of the group, using the same scheme (0=delete, 1=stable, 2=insert).
+
+ -\b-k\bkg\bgb\bbi\bi or -\b--\b-k\bke\bey\byw\bwo\bor\brd\bd-\b-g\bgr\bro\bou\bup\bp-\b-b\bbl\bla\ban\bnk\bks\bs-\b-i\bin\bns\bsi\bid\bde\be 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 -\b-k\bkg\bgb\bbs\bs=\b=s\bs) then this switch causes a blank line be inserted between
+ this subgroup and the others. In the example above this happened between the u\bus\bse\be and m\bmy\by statements.
+
+ -\b-k\bkg\bgb\bbd\bd or -\b--\b-k\bke\bey\byw\bwo\bor\brd\bd-\b-g\bgr\bro\bou\bup\bp-\b-b\bbl\bla\ban\bnk\bks\bs-\b-d\bde\bel\ble\bet\bte\be 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 -\b-k\bkg\bgb\bbd\bd is set. The default is not to do this, -\b-n\bnk\bkg\bgb\bbd\bd.
+
+ -\b-k\bkg\bgb\bbr\br=\b=n\bn or -\b--\b-k\bke\bey\byw\bwo\bor\brd\bd-\b-g\bgr\bro\bou\bup\bp-\b-b\bbl\bla\ban\bnk\bks\bs-\b-r\bre\bep\bpe\bea\bat\bt-\b-c\bco\bou\bun\bnt\bt=\b=n\bn specifies n\bn, the maximum number of times this logic will be
+ applied to any file. The special value n\bn=\b=0\b0 is the same as n=infinity which means it will be applied to an
+ entire script [Default]. A value n\bn=\b=1\b1 could be used to make it apply just one time for example. This might be
+ useful for adjusting just the u\bus\bse\be statements in the top part of a module for example.
+
+ -\b-k\bkg\bgb\bb or -\b--\b-k\bke\bey\byw\bwo\bor\brd\bd-\b-g\bgr\bro\bou\bup\bp-\b-b\bbl\bla\ban\bnk\bks\bs is an abbreviation equivalent to setting -\b-k\bkg\bgb\bbb\bb=\b=1\b1 -\b-k\bkg\bgb\bba\ba=\b=1\b1 -\b-k\bkg\bgb\bbi\bi. This turns on
+ keyword group formatting with a set of default values.
+
+ -\b-n\bnk\bkg\bgb\bb or -\b--\b-n\bno\bok\bke\bey\byw\bwo\bor\brd\bd-\b-g\bgr\bro\bou\bup\bp-\b-b\bbl\bla\ban\bnk\bks\bs is equivalent to -\b-k\bkg\bgb\bbb\bb=\b=0\b0 -\b-k\bkg\bgb\bba\ba n\bnk\bkg\bgb\bbi\bi. This flag turns off keyword group blank
+ lines and is the default setting.
+
+ Here are a few notes about the functioning of this technique.
+
+ +\bo 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 -\b-k\bkg\bgb\bbd\bd is an irreversible operation so it should be
+ applied with care. Existing blank lines may be serving an important role in controlling vertical alignment.
+
+ +\bo Conflicts which arise among these k\bkg\bgb\bb*\b* 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 -\b--\b-f\bfr\bre\bee\bez\bze\be-\b-b\bbl\bla\ban\bnk\bk-\b-l\bli\bin\bne\bes\bs, or -\b--\b-k\bke\bee\bep\bp-\b-o\bol\bld\bd-\b-b\bbl\bla\ban\bnk\bk-\b-l\bli\bin\bne\bes\bs=\b=2\b2, are set, then they have
+ priority over any blank line deletion implied by the -\b-k\bkg\bgb\bb flags of this section, so no blank lines will be
+ deleted.
+
+ For another example, if a keyword group ends at a s\bsu\bub\bb and the flag k\bkg\bgb\bba\ba=\b=0\b0 requests no blank line there, but
+ we also have -\b--\b-b\bbl\bla\ban\bnk\bk-\b-l\bli\bin\bne\bes\bs-\b-b\bbe\bef\bfo\bor\bre\be-\b-s\bsu\bub\bbs\bs=\b=2\b2, then two blank lines will still be introduced before the sub.
+
+ +\bo 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.
+
+ +\bo 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.
+
+ +\bo 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.
+
+ S\bSt\bty\byl\ble\bes\bs
+ A style refers to a convenient collection of existing parameters.
+
+ -\b-g\bgn\bnu\bu, -\b--\b-g\bgn\bnu\bu-\b-s\bst\bty\byl\ble\be
+ -\b-g\bgn\bnu\bu 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
+
+ -\b-p\bpb\bbp\bp, -\b--\b-p\bpe\ber\brl\bl-\b-b\bbe\bes\bst\bt-\b-p\bpr\bra\bac\bct\bti\bic\bce\bes\bs
+ -\b-p\bpb\bbp\bp is an abbreviation for the parameters in the book P\bPe\ber\brl\bl B\bBe\bes\bst\bt P\bPr\bra\bac\bct\bti\bic\bce\bes\bs 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 -\b-n\bns\bst\bt and/or -\b-n\bns\bse\be 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 -\b-c\bci\bi=\b=2\b2 be used instead, or the flag -\b-x\bxc\bci\bi 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 -\b-x\bxc\bci\bi flag was developed after the -\b-p\bpb\bbp\bp parameters were published so you need to include it separately.
+
+ O\bOn\bne\be-\b-l\bli\bin\bne\be b\bbl\blo\boc\bck\bks\bs
+ 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 -\b-n\bna\bas\bsc\bc 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
+ -\b-n\bno\boa\bad\bdd\bd-\b-n\bne\bew\bwl\bli\bin\bne\bes\bs 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.
+
+ -\b-o\bol\blb\bbs\bs=\b=n\bn, -\b--\b-o\bon\bne\be-\b-l\bli\bin\bne\be-\b-b\bbl\blo\boc\bck\bk-\b-s\bse\bem\bmi\bic\bco\bol\blo\bon\bns\bs=\b=n\bn
+ 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 n\bn=\b=2\b2 option has no effect if adding semicolons is prohibited with the -\b-n\bna\bas\bsc\bc flag. Also not
+ that while n\bn=\b=2\b2 adds missing semicolons to all one-line blocks, regardless of complexity, the n\bn=\b=0\b0 option only
+ removes ending semicolons which terminate one-line blocks containing just one semicolon. So these two
+ options are not exact inverses.
+
+ -\b-o\bol\blb\bbn\bn=\b=n\bn, -\b--\b-o\bon\bne\be-\b-l\bli\bin\bne\be-\b-b\bbl\blo\boc\bck\bk-\b-n\bne\bes\bst\bti\bin\bng\bg=\b=n\bn
+ 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 (-\b-o\bol\blb\bbn\bn=\b=0\b0) is
+
+ foreach (@list) {
+ if ( $_ eq $asked_for ) { last }
+ ++$found;
+ }
+
+ If the parameter -\b-o\bol\blb\bbn\bn=\b=1\b1 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.
+
+ C\bCo\bon\bnt\btr\bro\bol\bll\bli\bin\bng\bg V\bVe\ber\brt\bti\bic\bca\bal\bl A\bAl\bli\big\bgn\bnm\bme\ben\bnt\bt
+ 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 -\b-n\bno\bov\bva\bal\bli\big\bgn\bn, 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'
+ );
+
+ O\bOt\bth\bhe\ber\br C\bCo\bon\bnt\btr\bro\bol\bls\bs
+ D\bDe\bel\ble\bet\bti\bin\bng\bg s\bse\bel\ble\bec\bct\bte\bed\bd t\bte\bex\bxt\bt
+ Perltidy can selectively delete comments and/or pod documentation. The command -\b-d\bda\bac\bc or
+ -\b--\b-d\bde\bel\ble\bet\bte\be-\b-a\bal\bll\bl-\b-c\bco\bom\bmm\bme\ben\bnt\bts\bs will delete all comments a\ban\bnd\bd all pod documentation, leaving just code and any leading
+ system control lines.
+
+ The command -\b-d\bdp\bp or -\b--\b-d\bde\bel\ble\bet\bte\be-\b-p\bpo\bod\bd will remove all pod documentation (but not comments).
+
+ Two commands which remove comments (but not pod) are: -\b-d\bdb\bbc\bc or -\b--\b-d\bde\bel\ble\bet\bte\be-\b-b\bbl\blo\boc\bck\bk-\b-c\bco\bom\bmm\bme\ben\bnt\bts\bs and -\b-d\bds\bsc\bc or
+ -\b--\b-d\bde\bel\ble\bet\bte\be-\b-s\bsi\bid\bde\be-\b-c\bco\bom\bmm\bme\ben\bnt\bts\bs. (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 -\b-x\bx flag is used, any system commands before a leading
+ hash-bang will be retained (even if they are in the form of comments).
+
+ W\bWr\bri\bit\bti\bin\bng\bg s\bse\bel\ble\bec\bct\bte\bed\bd t\bte\bex\bxt\bt t\bto\bo a\ba f\bfi\bil\ble\be
+ When perltidy writes a formatted text file, it has the ability to also send selected text to a file with a
+ _\b._\bT_\bE_\bE extension. This text can include comments and pod documentation.
+
+ The command -\b-t\bta\bac\bc or -\b--\b-t\bte\bee\be-\b-a\bal\bll\bl-\b-c\bco\bom\bmm\bme\ben\bnt\bts\bs will write all comments a\ban\bnd\bd all pod documentation.
+
+ The command -\b-t\btp\bp or -\b--\b-t\bte\bee\be-\b-p\bpo\bod\bd will write all pod documentation (but not comments).
+
+ The commands which write comments (but not pod) are: -\b-t\btb\bbc\bc or -\b--\b-t\bte\bee\be-\b-b\bbl\blo\boc\bck\bk-\b-c\bco\bom\bmm\bme\ben\bnt\bts\bs and -\b-t\bts\bsc\bc or
+ -\b--\b-t\bte\bee\be-\b-s\bsi\bid\bde\be-\b-c\bco\bom\bmm\bme\ben\bnt\bts\bs. (Hanging side comments will be written with side comments here.)
+
+ The negatives of these commands also work, and are the defaults.
+
+ U\bUs\bsi\bin\bng\bg a\ba _\b.\b._\bp\bp_\be\be_\br\br_\bl\bl_\bt\bt_\bi\bi_\bd\bd_\by\by_\br\br_\bc\bc c\bco\bom\bmm\bma\ban\bnd\bd f\bfi\bil\ble\be
+ If you use perltidy frequently, you probably won't be happy until you create a _\b._\bp_\be_\br_\bl_\bt_\bi_\bd_\by_\br_\bc file to avoid
+ typing commonly-used parameters. Perltidy will first look in your current directory for a command file
+ named _\b._\bp_\be_\br_\bl_\bt_\bi_\bd_\by_\br_\bc. 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 P\bPE\bER\bRL\bLT\bTI\bID\bDY\bY. Then it will look for a _\b._\bp_\be_\br_\bl_\bt_\bi_\bd_\by_\br_\bc
+ file in the home directory, and then for a system-wide file _\b/_\bu_\bs_\br_\b/_\bl_\bo_\bc_\ba_\bl_\b/_\be_\bt_\bc_\b/_\bp_\be_\br_\bl_\bt_\bi_\bd_\by_\br_\bc, and then it will look
+ for _\b/_\be_\bt_\bc_\b/_\bp_\be_\br_\bl_\bt_\bi_\bd_\by_\br_\bc. 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 _\bC_\b:_\b\_\bD_\bo_\bc_\bu_\bm_\be_\bn_\bt_\bs _\ba_\bn_\bd _\bS_\be_\bt_\bt_\bi_\bn_\bg_\bs_\b\_\bA_\bl_\bl _\bU_\bs_\be_\br_\bs_\b\_\bp_\be_\br_\bl_\bt_\bi_\bd_\by_\b._\bi_\bn_\bi.
+
+ 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 _\b._\bp_\be_\br_\bl_\bt_\bi_\bd_\by_\br_\bc 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 _\b._\bp_\be_\br_\bl_\bt_\bi_\bd_\by_\br_\bc 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 _\b._\bp_\be_\br_\bl_\bt_\bi_\bd_\by_\br_\bc file:
+
+ +\bo A very helpful command is -\b--\b-d\bdu\bum\bmp\bp-\b-p\bpr\bro\bof\bfi\bil\ble\be or -\b-d\bdp\bpr\bro\bo. 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
+
+ +\bo It may be simplest to develop and test configuration files with alternative names, and invoke them with
+ -\b-p\bpr\bro\bo=\b=f\bfi\bil\ble\ben\bna\bam\bme\be on the command line. Then rename the desired file to _\b._\bp_\be_\br_\bl_\bt_\bi_\bd_\by_\br_\bc when finished.
+
+ +\bo The parameters in the _\b._\bp_\be_\br_\bl_\bt_\bi_\bd_\by_\br_\bc file can be switched off with the -\b-n\bnp\bpr\bro\bo option.
+
+ +\bo The commands -\b--\b-d\bdu\bum\bmp\bp-\b-o\bop\bpt\bti\bio\bon\bns\bs, -\b--\b-d\bdu\bum\bmp\bp-\b-d\bde\bef\bfa\bau\bul\blt\bts\bs, -\b--\b-d\bdu\bum\bmp\bp-\b-l\blo\bon\bng\bg-\b-n\bna\bam\bme\bes\bs, and -\b--\b-d\bdu\bum\bmp\bp-\b-s\bsh\bho\bor\brt\bt-\b-n\bna\bam\bme\bes\bs, all described
+ below, may all be helpful.
+
+ C\bCr\bre\bea\bat\bti\bin\bng\bg a\ba n\bne\bew\bw a\bab\bbb\bbr\bre\bev\bvi\bia\bat\bti\bio\bon\bn
+ A special notation is available for use in a _\b._\bp_\be_\br_\bl_\bt_\bi_\bd_\by_\br_\bc 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 n\bne\bew\bww\bwo\bor\brd\bd is the abbreviation, and o\bop\bpt\bt1\b1, etc, are existing parameters _\bo_\br _\bo_\bt_\bh_\be_\br _\ba_\bb_\bb_\br_\be_\bv_\bi_\ba_\bt_\bi_\bo_\bn_\bs. 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 _\b._\bp_\be_\br_\bl_\bt_\bi_\bd_\by_\br_\bc 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 _\b._\bp_\be_\br_\bl_\bt_\bi_\bd_\by_\br_\bc 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 -\b-x\bx or -\b--\b-l\blo\boo\bok\bk-\b-f\bfo\bor\br-\b-h\bha\bas\bsh\bh-\b-b\bba\ban\bng\bg
+ 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 -\b-x\bx 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.
+
+ M\bMa\bak\bki\bin\bng\bg a\ba f\bfi\bil\ble\be u\bun\bnr\bre\bea\bad\bda\bab\bbl\ble\be
+ The goal of perltidy is to improve the readability of files, but there are two commands which have the
+ opposite effect, -\b--\b-m\bma\ban\bng\bgl\ble\be and -\b--\b-e\bex\bxt\btr\bru\bud\bde\be. 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 -\b--\b-m\bma\ban\bng\bgl\ble\be puts the fewest possible line
+ breaks in a script while -\b--\b-e\bex\bxt\btr\bru\bud\bde\be 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 -\b--\b-m\bma\ban\bng\bgl\ble\be 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 -\b--\b-e\bex\bxt\btr\bru\bud\bde\be instead of -\b--\b-m\bma\ban\bng\bgl\ble\be to make the minimum number of one-line
+ blocks.
+
+ Another use for -\b--\b-m\bma\ban\bng\bgl\ble\be is to combine it with -\b-d\bda\bac\bc to reduce the file size of a perl script.
+
+ D\bDe\beb\bbu\bug\bgg\bgi\bin\bng\bg
+ The following flags are available for debugging:
+
+ -\b--\b-d\bdu\bum\bmp\bp-\b-c\bcu\bud\bdd\bdl\ble\bed\bd-\b-b\bbl\blo\boc\bck\bk-\b-l\bli\bis\bst\bt or -\b-d\bdc\bcb\bbl\bl will dump to standard output the internal hash of cuddled block types
+ created by a -\b-c\bcu\bud\bdd\bdl\ble\bed\bd-\b-b\bbl\blo\boc\bck\bk-\b-l\bli\bis\bst\bt input string.
+
+ -\b--\b-d\bdu\bum\bmp\bp-\b-d\bde\bef\bfa\bau\bul\blt\bts\bs or -\b-d\bdd\bdf\bf will write the default option set to standard output and quit
+
+ -\b--\b-d\bdu\bum\bmp\bp-\b-p\bpr\bro\bof\bfi\bil\ble\be or -\b-d\bdp\bpr\bro\bo will write the name of the current configuration file and its contents to standard
+ output and quit.
+
+ -\b--\b-d\bdu\bum\bmp\bp-\b-o\bop\bpt\bti\bio\bon\bns\bs or -\b-d\bdo\bop\bp will write current option set to standard output and quit.
+
+ -\b--\b-d\bdu\bum\bmp\bp-\b-l\blo\bon\bng\bg-\b-n\bna\bam\bme\bes\bs or -\b-d\bdl\bln\bn will write all command line long names (passed to Get_options) to standard output
+ and quit.
+
+ -\b--\b-d\bdu\bum\bmp\bp-\b-s\bsh\bho\bor\brt\bt-\b-n\bna\bam\bme\bes\bs or -\b-d\bds\bsn\bn will write all command line short names to standard output and quit.
+
+ -\b--\b-d\bdu\bum\bmp\bp-\b-t\bto\bok\bke\ben\bn-\b-t\bty\byp\bpe\bes\bs or -\b-d\bdt\btt\bt will write a list of all token types to standard output and quit.
+
+ -\b--\b-d\bdu\bum\bmp\bp-\b-w\bwa\ban\bnt\bt-\b-l\ble\bef\bft\bt-\b-s\bsp\bpa\bac\bce\be or -\b-d\bdw\bwl\bls\bs will write the hash %want_left_space to standard output and quit. See the
+ section on controlling whitespace around tokens.
+
+ -\b--\b-d\bdu\bum\bmp\bp-\b-w\bwa\ban\bnt\bt-\b-r\bri\big\bgh\bht\bt-\b-s\bsp\bpa\bac\bce\be or -\b-d\bdw\bwr\brs\bs will write the hash %want_right_space to standard output and quit. See
+ the section on controlling whitespace around tokens.
+
+ -\b--\b-n\bno\bo-\b-m\bme\bem\bmo\boi\biz\bze\be or -\b-n\bnm\bme\bem\bm 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 -\b-n\bnm\bme\bem\bm.
+
+ -\b--\b-n\bno\bo-\b-t\bti\bim\bme\bes\bst\bta\bam\bmp\bp or -\b-n\bnt\bts\bs 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 -\b-c\bcs\bsc\bcw\bw option is selected. The default is
+ to allow timestamps (-\b--\b-t\bti\bim\bme\bes\bst\bta\bam\bmp\bp or -\b-t\bts\bs).
+
+ -\b--\b-f\bfi\bil\ble\be-\b-s\bsi\biz\bze\be-\b-o\bor\brd\bde\ber\br or -\b-f\bfs\bso\bo 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.
+
+ -\b--\b-m\bma\bax\bxi\bim\bmu\bum\bm-\b-f\bfi\bil\ble\be-\b-s\bsi\biz\bze\be-\b-m\bmb\bb=\b=n\bn or -\b-m\bma\bax\bxf\bfs\bs=\b=n\bn 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 n\bn 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.
+
+ -\b--\b-m\bma\bax\bxi\bim\bmu\bum\bm-\b-l\ble\bev\bve\bel\bl-\b-e\ber\brr\bro\bor\brs\bs=\b=n\bn or -\b-m\bma\bax\bxl\ble\be=\b=n\bn specifies the maximum number of indentation level errors are allowed
+ before perltidy skips formatting and just outputs a file verbatim. The default is n\bn=\b=1\b1. 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 n\bn=\b=1\b10\b00\b0, or set n\bn=\b=-\b-1\b1.
+
+ For example, the following script has level error of 3 and will be output verbatim
+
+ Input and default output:
+ {{{
+
+ perltidy -maxle=100
+ {
+ {
+ {
+
+ -\b--\b-m\bma\bax\bxi\bim\bmu\bum\bm-\b-u\bun\bne\bex\bxp\bpe\bec\bct\bte\bed\bd-\b-e\ber\brr\bro\bor\brs\bs=\b=n\bn or -\b-m\bma\bax\bxu\bue\be=\b=n\bn 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 n\bn=\b=0\b0.
+
+ A recommended value is n\bn=\b=3\b3. However, the default is n\bn=\b=0\b0 (skip this check) to avoid causing problems with
+ scripts which have extended syntaxes.
+
+ -\b-D\bDE\bEB\bBU\bUG\bG will write a file with extension _\b._\bD_\bE_\bB_\bU_\bG for each input file showing the tokenization of all lines of
+ code.
+
+ W\bWo\bor\brk\bki\bin\bng\bg w\bwi\bit\bth\bh M\bMa\bak\bke\beM\bMa\bak\bke\ber\br,\b, A\bAu\but\bto\boL\bLo\boa\bad\bde\ber\br a\ban\bnd\bd S\bSe\bel\blf\bfL\bLo\boa\bad\bde\ber\br
+ The first $VERSION line of a file which might be eval'd by MakeMaker is passed through unchanged except for
+ indentation. Use -\b--\b-n\bno\bop\bpa\bas\bss\bs-\b-v\bve\ber\brs\bsi\bio\bon\bn-\b-l\bli\bin\bne\be, or -\b-n\bnp\bpv\bvl\bl, to deactivate this feature.
+
+ If the AutoLoader module is used, perltidy will continue formatting code after seeing an __END__ line. Use
+ -\b--\b-n\bno\bol\blo\boo\bok\bk-\b-f\bfo\bor\br-\b-a\bau\but\bto\bol\blo\boa\bad\bde\ber\br, or -\b-n\bnl\bla\bal\bl, to deactivate this feature.
+
+ Likewise, if the SelfLoader module is used, perltidy will continue formatting code after seeing a __DATA__
+ line. Use -\b--\b-n\bno\bol\blo\boo\bok\bk-\b-f\bfo\bor\br-\b-s\bse\bel\blf\bfl\blo\boa\bad\bde\ber\br, or -\b-n\bnl\bls\bsl\bl, to deactivate this feature.
+
+ W\bWo\bor\brk\bki\bin\bng\bg a\bar\bro\bou\bun\bnd\bd p\bpr\bro\bob\bbl\ble\bem\bms\bs w\bwi\bit\bth\bh o\bol\bld\bde\ber\br v\bve\ber\brs\bsi\bio\bon\bn o\bof\bf P\bPe\ber\brl\bl
+ 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.
+
+H\bHT\bTM\bML\bL O\bOP\bPT\bTI\bIO\bON\bNS\bS
+ The -\b-h\bht\btm\bml\bl master switch
+ The flag -\b-h\bht\btm\bml\bl causes perltidy to write an html file with extension _\b._\bh_\bt_\bm_\bl. So, for example, the following
+ command
+
+ perltidy -html somefile.pl
+
+ will produce a syntax-colored html file named _\bs_\bo_\bm_\be_\bf_\bi_\bl_\be_\b._\bp_\bl_\b._\bh_\bt_\bm_\bl which may be viewed with a browser.
+
+ P\bPl\ble\bea\bas\bse\be N\bNo\bot\bte\be: In this case, perltidy does not do any formatting to the input file, and it does not write a
+ formatted file with extension _\b._\bt_\bd_\by. This means that two perltidy runs are required to create a fully
+ reformatted, html copy of a script.
+
+ The -\b-p\bpr\bre\be flag for code snippets
+ When the -
\b-p
\bpr
\bre
\be flag is given, only the pre-formatted section, within the <PRE> and </PRE> tags, will be
+ output. This simplifies inclusion of the output in other files. The default is to output a complete web
+ page.
+
+ The -\b-n\bnn\bnn\bn flag for line numbering
+ When the -\b-n\bnn\bnn\bn flag is given, the output lines will be numbered.
+
+ The -\b-t\bto\boc\bc, or -\b--\b-h\bht\btm\bml\bl-\b-t\bta\bab\bbl\ble\be-\b-o\bof\bf-\b-c\bco\bon\bnt\bte\ben\bnt\bts\bs flag
+ By default, a table of contents to packages and subroutines will be written at the start of html output.
+ Use -\b-n\bnt\bto\boc\bc 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 -\b-p\bpo\bod\bd, or -\b--\b-p\bpo\bod\bd2\b2h\bht\btm\bml\bl 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 -\b-n\bnp\bpo\bod\bd, 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 -\b-f\bfr\brm\bm, or -\b--\b-f\bfr\bra\bam\bme\bes\bs flag
+ By default, a single html output file is produced. This can be changed with the -\b-f\bfr\brm\bm 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 _\bM_\by_\bM_\bo_\bd_\bu_\bl_\be_\b._\bp_\bm. 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 -\b-f\bfr\brm\bm option will be
+ ignored.
+
+ The -\b-t\bte\bex\bxt\bt=\b=s\bs, or -\b--\b-h\bht\btm\bml\bl-\b-t\bto\boc\bc-\b-e\bex\bxt\bte\ben\bns\bsi\bio\bon\bn 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 -\b-s\bse\bex\bxt\bt=\b=s\bs, or -\b--\b-h\bht\btm\bml\bl-\b-s\bsr\brc\bc-\b-e\bex\bxt\bte\ben\bns\bsi\bio\bon\bn 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 -\b-h\bhe\ben\bnt\bt, or -\b--\b-h\bht\btm\bml\bl-\b-e\ben\bnt\bti\bit\bti\bie\bes\bs 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.
+
+ S\bSt\bty\byl\ble\be S\bSh\bhe\bee\bet\bts\bs
+ 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 -\b-c\bcs\bss\bs=\b=f\bfi\bil\ble\ben\bna\bam\bme\be, where the external style sheet is _\bf_\bi_\bl_\be_\bn_\ba_\bm_\be. The external style sheet
+ _\bf_\bi_\bl_\be_\bn_\ba_\bm_\be 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 -\b-s\bss\bs, or -\b--\b-s\bst\bty\byl\ble\bes\bsh\bhe\bee\bet\bt, flag.
+ This is useful if the style sheet could not be written for some reason, such as if the -\b-p\bpr\bre\be flag was used.
+ Thus, for example,
+
+ perltidy -html -ss >mystyle.css
+
+ will write a style sheet with the default properties to file _\bm_\by_\bs_\bt_\by_\bl_\be_\b._\bc_\bs_\bs.
+
+ The use of style sheets is encouraged, but a web page without a style sheets can be created with the flag
+ -\b-n\bns\bss\bs. 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.
+
+ C\bCo\bon\bnt\btr\bro\bol\bll\bli\bin\bng\bg H\bHT\bTM\bML\bL p\bpr\bro\bop\bpe\ber\brt\bti\bie\bes\bs
+ 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,
+ -\b-h\bht\btm\bml\bl-\b-c\bco\bol\blo\bor\br-\b-x\bxx\bxx\bxx\bxx\bxx\bx=\b=n\bn, or more conveniently the short form, -\b-h\bhc\bcx\bx=\b=n\bn, where x\bxx\bxx\bxx\bxx\bxx\bx is one of the following
+ words, and x\bx 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 n\bn 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 _\bs_\bo_\bm_\be_\bf_\bi_\bl_\be_\b._\bp_\bl_\b._\bh_\bt_\bm_\bl 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 -\b--\b-h\bht\btm\bml\bl-\b-b\bbo\bol\bld\bd-\b-x\bxx\bxx\bxx\bxx\bxx\bx or -\b-h\bhb\bbx\bx, where x\bxx\bxx\bxx\bxx\bxx\bx or x\bx are the long or short names from the above
+ table. Conversely, to set a token type to NOT use bold, use -\b--\b-n\bno\boh\bht\btm\bml\bl-\b-b\bbo\bol\bld\bd-\b-x\bxx\bxx\bxx\bxx\bxx\bx or -\b-n\bnh\bhb\bbx\bx.
+
+ Likewise, to set a token type to use an italic font, use the flag -\b--\b-h\bht\btm\bml\bl-\b-i\bit\bta\bal\bli\bic\bc-\b-x\bxx\bxx\bxx\bxx\bxx\bx or -\b-h\bhi\bix\bx, where again
+ x\bxx\bxx\bxx\bxx\bxx\bx or x\bx are the long or short names from the above table. And to set a token type to NOT use italics,
+ use -\b--\b-n\bno\boh\bht\btm\bml\bl-\b-i\bit\bta\bal\bli\bic\bc-\b-x\bxx\bxx\bxx\bxx\bxx\bx or -\b-n\bnh\bhi\bix\bx.
+
+ 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 -\b--\b-h\bht\btm\bml\bl-\b-c\bco\bol\blo\bor\br-\b-b\bba\bac\bck\bkg\bgr\bro\bou\bun\bnd\bd=\b=n\bn, or -\b-h\bhc\bcb\bbg\bg=\b=n\bn for short, where n is a 6
+ character hex RGB value. The default color of text is the value given to p\bpu\bun\bnc\bct\btu\bua\bat\bti\bio\bon\bn, 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 _\b._\bp_\be_\br_\bl_\bt_\bi_\bd_\by_\br_\bc 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.
+
+S\bSO\bOM\bME\bE C\bCO\bOM\bMM\bMO\bON\bN I\bIN\bNP\bPU\bUT\bT C\bCO\bON\bNV\bVE\bEN\bNT\bTI\bIO\bON\bNS\bS
+ S\bSp\bpe\bec\bci\bif\bfy\byi\bin\bng\bg B\bBl\blo\boc\bck\bk T\bTy\byp\bpe\bes\bs
+ 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 i\bif\bf, e\bel\bls\bse\be, or
+ s\bsu\bub\bb. An exception is a labeled block, which has no keyword, and should be specified with just a colon. To
+ specify all blocks use '\b'*\b*'\b'.
+
+ The keyword s\bsu\bub\bb indicates a named sub. For anonymous subs, use the special keyword a\bas\bsu\bub\bb.
+
+ 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='*'
+
+ S\bSp\bpe\bec\bci\bif\bfy\byi\bin\bng\bg F\bFi\bil\ble\be E\bEx\bxt\bte\ben\bns\bsi\bio\bon\bns\bs
+ Several parameters allow default file extensions to be overridden. For example, a backup file extension may be
+ specified with -\b-b\bbe\bex\bxt\bt=\b=e\bex\bxt\bt, where e\bex\bxt\bt 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 _\bs_\bo_\bm_\be_\bf_\bi_\bl_\be_\b._\bp_\bl. For "-bext=old", a '.' is added to give _\bs_\bo_\bm_\be_\bf_\bi_\bl_\be_\b._\bp_\bl_\b._\bo_\bl_\bd. For
+ "-bext=.old", no additional '.' is added, so again the backup file is _\bs_\bo_\bm_\be_\bf_\bi_\bl_\be_\b._\bp_\bl_\b._\bo_\bl_\bd. For "-bext=~", then no
+ dot is added, and the backup file will be _\bs_\bo_\bm_\be_\bf_\bi_\bl_\be_\b._\bp_\bl_\b~ .
+
+S\bSW\bWI\bIT\bTC\bCH\bHE\bES\bS W\bWH\bHI\bIC\bCH\bH M\bMA\bAY\bY B\bBE\bE N\bNE\bEG\bGA\bAT\bTE\bED\bD
+ 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.
+
+L\bLI\bIM\bMI\bIT\bTA\bAT\bTI\bIO\bON\bNS\bS
+ P\bPa\bar\brs\bsi\bin\bng\bg L\bLi\bim\bmi\bit\bta\bat\bti\bio\bon\bns\bs
+ 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.
+
+ W\bWh\bha\bat\bt p\bpe\ber\brl\blt\bti\bid\bdy\by d\bdo\boe\bes\bs n\bno\bot\bt p\bpa\bar\brs\bse\be a\ban\bnd\bd f\bfo\bor\brm\bma\bat\bt
+ 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.
+
+F\bFI\bIL\bLE\bES\bS
+ T\bTe\bem\bmp\bpo\bor\bra\bar\bry\by f\bfi\bil\ble\bes\bs
+ 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 t\btm\bmp\bpn\bna\bam\bm(\b()\b) function. Otherwise the file _\bp_\be_\br_\bl_\bt_\bi_\bd_\by_\b._\bT_\bM_\bP will
+ be temporarily created in the current working directory.
+
+ S\bSp\bpe\bec\bci\bia\bal\bl f\bfi\bil\ble\bes\bs w\bwh\bhe\ben\bn s\bst\bta\ban\bnd\bda\bar\brd\bd i\bin\bnp\bpu\but\bt i\bis\bs u\bus\bse\bed\bd
+ When standard input is used, the log file, if saved, is _\bp_\be_\br_\bl_\bt_\bi_\bd_\by_\b._\bL_\bO_\bG, and any errors are written to
+ _\bp_\be_\br_\bl_\bt_\bi_\bd_\by_\b._\bE_\bR_\bR unless the -\b-s\bse\be flag is set. These are saved in the current working directory.
+
+ F\bFi\bil\ble\bes\bs o\bov\bve\ber\brw\bwr\bri\bit\btt\bte\ben\bn
+ The following file extensions are used by perltidy, and files with these extensions may be overwritten or
+ deleted: _\b._\bE_\bR_\bR, _\b._\bL_\bO_\bG, _\b._\bT_\bE_\bE, and/or _\b._\bt_\bd_\by, _\b._\bh_\bt_\bm_\bl, and _\b._\bb_\ba_\bk, depending on the run type and settings.
+
+ F\bFi\bil\ble\bes\bs e\bex\bxt\bte\ben\bns\bsi\bio\bon\bns\bs l\bli\bim\bmi\bit\bta\bat\bti\bio\bon\bns\bs
+ Perltidy does not operate on files for which the run could produce a file with a duplicated file extension.
+ These extensions include _\b._\bL_\bO_\bG, _\b._\bE_\bR_\bR, _\b._\bT_\bE_\bE, and perhaps _\b._\bt_\bd_\by and _\b._\bb_\ba_\bk, depending on the run type. The
+ purpose of this rule is to prevent generating confusing filenames such as _\bs_\bo_\bm_\be_\bf_\bi_\bl_\be_\b._\bt_\bd_\by_\b._\bt_\bd_\by_\b._\bt_\bd_\by.
+
+E\bER\bRR\bRO\bOR\bR H\bHA\bAN\bND\bDL\bLI\bIN\bNG\bG
+ 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.
+
+S\bSE\bEE\bE A\bAL\bLS\bSO\bO
+ p\bpe\ber\brl\bls\bst\bty\byl\ble\be(1), P\bPe\ber\brl\bl:\b::\b:T\bTi\bid\bdy\by(3)
+
+I\bIN\bNS\bST\bTA\bAL\bLL\bLA\bAT\bTI\bIO\bON\bN
+ 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'.
+
+V\bVE\bER\bRS\bSI\bIO\bON\bN
+ This man page documents perltidy version 20210717
+
+B\bBU\bUG\bG R\bRE\bEP\bPO\bOR\bRT\bTS\bS
+ A list of current bugs and issues can be found at the CPAN site
+ <https://rt.cpan.org/Public/Dist/Display.html?Name=Perl-Tidy>
+
+ To report a new bug or problem, use the link on this page.
+
+ The source code repository is at <https://github.com/perltidy/perltidy>.
+
+C\bCO\bOP\bPY\bYR\bRI\bIG\bGH\bHT\bT
+ Copyright (c) 2000-2021 by Steve Hancock
+
+L\bLI\bIC\bCE\bEN\bNS\bSE\bE
+ 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.
+
+D\bDI\bIS\bSC\bCL\bLA\bAI\bIM\bME\bER\bR
+ 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)
projects / perltidy.git / commitdiff