+++ /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