1PERLTIDY(1)           User Contributed Perl Documentation          PERLTIDY(1)
2
3
4

NAME

6       perltidy - a perl script indenter and reformatter
7

SYNOPSIS

9           perltidy [ options ] file1 file2 file3 ...
10                   (output goes to file1.tdy, file2.tdy, file3.tdy, ...)
11           perltidy [ options ] file1 -o outfile
12           perltidy [ options ] file1 -st >outfile
13           perltidy [ options ] <infile >outfile
14

DESCRIPTION

16       Perltidy reads a perl script and writes an indented, reformatted
17       script.
18
19       Many users will find enough information in "EXAMPLES" to get started.
20       New users may benefit from the short tutorial which can be found at
21       http://perltidy.sourceforge.net/tutorial.html
22
23       A convenient aid to systematically defining a set of style parameters
24       can be found at http://perltidy.sourceforge.net/stylekey.html
25
26       Perltidy can produce output on either of two modes, depending on the
27       existence of an -html flag.  Without this flag, the output is passed
28       through a formatter.  The default formatting tries to follow the
29       recommendations in perlstyle(1), but it can be controlled in detail
30       with numerous input parameters, which are described in "FORMATTING
31       OPTIONS".
32
33       When the -html flag is given, the output is passed through an HTML
34       formatter which is described in "HTML OPTIONS".
35

EXAMPLES

37         perltidy somefile.pl
38
39       This will produce a file somefile.pl.tdy containing the script
40       reformatted using the default options, which approximate the style
41       suggested in perlstyle(1).  The source file somefile.pl is unchanged.
42
43         perltidy *.pl
44
45       Execute perltidy on all .pl files in the current directory with the
46       default options.  The output will be in files with an appended .tdy
47       extension.  For any file with an error, there will be a file with
48       extension .ERR.
49
50         perltidy -b file1.pl file2.pl
51
52       Modify file1.pl and file2.pl in place, and backup the originals to
53       file1.pl.bak and file2.pl.bak.  If file1.pl.bak and/or file2.pl.bak
54       already exist, they will be overwritten.
55
56         perltidy -b -bext='/' file1.pl file2.pl
57
58       Same as the previous example except that the backup files file1.pl.bak
59       and file2.pl.bak will be deleted if there are no errors.
60
61         perltidy -gnu somefile.pl
62
63       Execute perltidy on file somefile.pl with a style which approximates
64       the GNU Coding Standards for C programs.  The output will be
65       somefile.pl.tdy.
66
67         perltidy -i=3 somefile.pl
68
69       Execute perltidy on file somefile.pl, with 3 columns for each level of
70       indentation (-i=3) instead of the default 4 columns.  There will not be
71       any tabs in the reformatted script, except for any which already exist
72       in comments, pod documents, quotes, and here documents.  Output will be
73       somefile.pl.tdy.
74
75         perltidy -i=3 -et=8 somefile.pl
76
77       Same as the previous example, except that leading whitespace will be
78       entabbed with one tab character per 8 spaces.
79
80         perltidy -ce -l=72 somefile.pl
81
82       Execute perltidy on file somefile.pl with all defaults except use
83       "cuddled elses" (-ce) and a maximum line length of 72 columns (-l=72)
84       instead of the default 80 columns.
85
86         perltidy -g somefile.pl
87
88       Execute perltidy on file somefile.pl and save a log file
89       somefile.pl.LOG which shows the nesting of braces, parentheses, and
90       square brackets at the start of every line.
91
92         perltidy -html somefile.pl
93
94       This will produce a file somefile.pl.html containing the script with
95       html markup.  The output file will contain an embedded style sheet in
96       the <HEAD> section which may be edited to change the appearance.
97
98         perltidy -html -css=mystyle.css somefile.pl
99
100       This will produce a file somefile.pl.html containing the script with
101       html markup.  This output file will contain a link to a separate style
102       sheet file mystyle.css.  If the file mystyle.css does not exist, it
103       will be created.  If it exists, it will not be overwritten.
104
105         perltidy -html -pre somefile.pl
106
107       Write an html snippet with only the PRE section to somefile.pl.html.
108       This is useful when code snippets are being formatted for inclusion in
109       a larger web page.  No style sheet will be written in this case.
110
111         perltidy -html -ss >mystyle.css
112
113       Write a style sheet to mystyle.css and exit.
114
115         perltidy -html -frm mymodule.pm
116
117       Write html with a frame holding a table of contents and the source
118       code.  The output files will be mymodule.pm.html (the frame),
119       mymodule.pm.toc.html (the table of contents), and mymodule.pm.src.html
120       (the source code).
121

OPTIONS - OVERVIEW

123       The entire command line is scanned for options, and they are processed
124       before any files are processed.  As a result, it does not matter
125       whether flags are before or after any filenames.  However, the relative
126       order of parameters is important, with later parameters overriding the
127       values of earlier parameters.
128
129       For each parameter, there is a long name and a short name.  The short
130       names are convenient for keyboard input, while the long names are self-
131       documenting and therefore useful in scripts.  It is customary to use
132       two leading dashes for long names, but one may be used.
133
134       Most parameters which serve as on/off flags can be negated with a
135       leading "n" (for the short name) or a leading "no" or "no-" (for the
136       long name).  For example, the flag to outdent long quotes is -olq or
137       --outdent-long-quotes.  The flag to skip this is -nolq or
138       --nooutdent-long-quotes or --no-outdent-long-quotes.
139
140       Options may not be bundled together.  In other words, options -q and -g
141       may NOT be entered as -qg.
142
143       Option names may be terminated early as long as they are uniquely
144       identified.  For example, instead of --dump-token-types, it would be
145       sufficient to enter --dump-tok, or even --dump-t, to uniquely identify
146       this command.
147
148   I/O control
149       The following parameters concern the files which are read and written.
150
151       -h,    --help
152           Show summary of usage and exit.
153
154       -o=filename,    --outfile=filename
155           Name of the output file (only if a single input file is being
156           processed).  If no output file is specified, and output is not
157           redirected to the standard output (see -st), the output will go to
158           filename.tdy. [Note: - does not redirect to standard output. Use
159           -st instead.]
160
161       -st,    --standard-output
162           Perltidy must be able to operate on an arbitrarily large number of
163           files in a single run, with each output being directed to a
164           different output file.  Obviously this would conflict with
165           outputting to the single standard output device, so a special flag,
166           -st, is required to request outputting to the standard output.  For
167           example,
168
169             perltidy somefile.pl -st >somefile.new.pl
170
171           This option may only be used if there is just a single input file.
172           The default is -nst or --nostandard-output.
173
174       -se,    --standard-error-output
175           If perltidy detects an error when processing file somefile.pl, its
176           default behavior is to write error messages to file
177           somefile.pl.ERR.  Use -se to cause all error messages to be sent to
178           the standard error output stream instead.  This directive may be
179           negated with -nse.  Thus, you may place -se in a .perltidyrc and
180           override it when desired with -nse on the command line.
181
182       -oext=ext,    --output-file-extension=ext
183           Change the extension of the output file to be ext instead of the
184           default tdy (or html in case the --html option is used).  See
185           "Specifying File Extensions".
186
187       -opath=path,    --output-path=path
188           When perltidy creates a filename for an output file, by default it
189           merely appends an extension to the path and basename of the input
190           file.  This parameter causes the path to be changed to path
191           instead.
192
193           The path should end in a valid path separator character, but
194           perltidy will try to add one if it is missing.
195
196           For example
197
198            perltidy somefile.pl -opath=/tmp/
199
200           will produce /tmp/somefile.pl.tdy.  Otherwise, somefile.pl.tdy will
201           appear in whatever directory contains somefile.pl.
202
203           If the path contains spaces, it should be placed in quotes.
204
205           This parameter will be ignored if output is being directed to
206           standard output, or if it is being specified explicitly with the
207           -o=s parameter.
208
209       -b,    --backup-and-modify-in-place
210           Modify the input file or files in-place and save the original with
211           the extension .bak.  Any existing .bak file will be deleted.  See
212           next item for changing the default backup extension, and for
213           eliminating the backup file altogether.
214
215           A -b flag will be ignored if input is from standard input or goes
216           to standard output, or if the -html flag is set.
217
218           In particular, if you want to use both the -b flag and the -pbp
219           (--perl-best-practices) flag, then you must put a -nst flag after
220           the -pbp flag because it contains a -st flag as one of its
221           components, which means that output will go to the standard output
222           stream.
223
224       -bext=ext,    --backup-file-extension=ext
225           This parameter serves two purposes: (1) to change the extension of
226           the backup file to be something other than the default .bak, and
227           (2) to indicate that no backup file should be saved.
228
229           To change the default extension to something other than .bak see
230           "Specifying File Extensions".
231
232           A backup file of the source is always written, but you can request
233           that it be deleted at the end of processing if there were no
234           errors.  This is risky unless the source code is being maintained
235           with a source code control system.
236
237           To indicate that the backup should be deleted include one forward
238           slash, /, in the extension.  If any text remains after the slash is
239           removed it will be used to define the backup file extension (which
240           is always created and only deleted if there were no errors).
241
242           Here are some examples:
243
244             Parameter           Extension          Backup File Treatment
245             <-bext=bak>         F<.bak>            Keep (same as the default behavior)
246             <-bext='/'>         F<.bak>            Delete if no errors
247             <-bext='/backup'>   F<.backup>         Delete if no errors
248             <-bext='original/'> F<.original>       Delete if no errors
249
250       -w,    --warning-output
251           Setting -w causes any non-critical warning messages to be reported
252           as errors.  These include messages about possible pod problems,
253           possibly bad starting indentation level, and cautions about
254           indirect object usage.  The default, -nw or --nowarning-output, is
255           not to include these warnings.
256
257       -q,    --quiet
258           Deactivate error messages (for running under an editor).
259
260           For example, if you use a vi-style editor, such as vim, you may
261           execute perltidy as a filter from within the editor using something
262           like
263
264            :n1,n2!perltidy -q
265
266           where "n1,n2" represents the selected text.  Without the -q flag,
267           any error message may mess up your screen, so be prepared to use
268           your "undo" key.
269
270       -log,    --logfile
271           Save the .LOG file, which has many useful diagnostics.  Perltidy
272           always creates a .LOG file, but by default it is deleted unless a
273           program bug is suspected.  Setting the -log flag forces the log
274           file to be saved.
275
276       -g=n, --logfile-gap=n
277           Set maximum interval between input code lines in the logfile.  This
278           purpose of this flag is to assist in debugging nesting errors.  The
279           value of "n" is optional.  If you set the flag -g without the value
280           of "n", it will be taken to be 1, meaning that every line will be
281           written to the log file.  This can be helpful if you are looking
282           for a brace, paren, or bracket nesting error.
283
284           Setting -g also causes the logfile to be saved, so it is not
285           necessary to also include -log.
286
287           If no -g flag is given, a value of 50 will be used, meaning that at
288           least every 50th line will be recorded in the logfile.  This helps
289           prevent excessively long log files.
290
291           Setting a negative value of "n" is the same as not setting -g at
292           all.
293
294       -npro  --noprofile
295           Ignore any .perltidyrc command file.  Normally, perltidy looks
296           first in your current directory for a .perltidyrc file of
297           parameters.  (The format is described below).  If it finds one, it
298           applies those options to the initial default values, and then it
299           applies any that have been defined on the command line.  If no
300           .perltidyrc file is found, it looks for one in your home directory.
301
302           If you set the -npro flag, perltidy will not look for this file.
303
304       -pro=filename or  --profile=filename
305           To simplify testing and switching .perltidyrc files, this command
306           may be used to specify a configuration file which will override the
307           default name of .perltidyrc.  There must not be a space on either
308           side of the '=' sign.  For example, the line
309
310              perltidy -pro=testcfg
311
312           would cause file testcfg to be used instead of the default
313           .perltidyrc.
314
315           A pathname begins with three dots, e.g. ".../.perltidyrc",
316           indicates that the file should be searched for starting in the
317           current directory and working upwards. This makes it easier to have
318           multiple projects each with their own .perltidyrc in their root
319           directories.
320
321       -opt,   --show-options
322           Write a list of all options used to the .LOG file.  Please see
323           --dump-options for a simpler way to do this.
324
325       -f,   --force-read-binary
326           Force perltidy to process binary files.  To avoid producing
327           excessive error messages, perltidy skips files identified by the
328           system as non-text.  However, valid perl scripts containing binary
329           data may sometimes be identified as non-text, and this flag forces
330           perltidy to process them.
331
332       -ast,   --assert-tidy
333           This flag asserts that the input and output code streams are
334           identical, or in other words that the input code is already 'tidy'
335           according to the formatting parameters.  If this is not the case,
336           an error message noting this is produced.  This error message will
337           cause the process to return a non-zero exit code.  The test for
338           this is made by comparing an MD5 hash value for the input and
339           output code streams. This flag has no other effect on the
340           functioning of perltidy.  This might be useful for certain code
341           maintenance operations.  Note: you will not see this message if you
342           have error messages turned off with the -quiet flag.
343
344       -asu,   --assert-untidy
345           This flag asserts that the input and output code streams are
346           different, or in other words that the input code is 'untidy'
347           according to the formatting parameters.  If this is not the case,
348           an error message noting this is produced.  This flag has no other
349           effect on the functioning of perltidy.
350
351       -sal=s,   --sub-alias-list=s
352           This flag causes one or more words to be treated the same as if
353           they were the keyword 'sub'.  The string s contains one or more
354           alias words, separated by spaces or commas.
355
356           For example,
357
358                   perltidy -sal='method fun _sub M4'
359
360           will cause the perltidy to treate the words 'method', 'fun', '_sub'
361           and 'M4' to be treated the same as if they were 'sub'.  Note that
362           if the alias words are separated by spaces then the string of words
363           should be placed in quotes.
364
365           Note that several other parameters accept a list of keywords,
366           including 'sub' (see "Specifying Block Types").  You do not need to
367           include any sub aliases in these lists. Just include keyword 'sub'
368           if you wish, and all aliases are automatically included.
369

FORMATTING OPTIONS

371   Basic Options
372       --notidy
373           This flag disables all formatting and causes the input to be copied
374           unchanged to the output except for possible changes in line ending
375           characters and any pre- and post-filters.  This can be useful in
376           conjunction with a hierarchical set of .perltidyrc files to avoid
377           unwanted code tidying.  See also "Skipping Selected Sections of
378           Code" for a way to avoid tidying specific sections of code.
379
380       -i=n,  --indent-columns=n
381           Use n columns per indentation level (default n=4).
382
383       -l=n, --maximum-line-length=n
384           The default maximum line length is n=80 characters.  Perltidy will
385           try to find line break points to keep lines below this length.
386           However, long quotes and side comments may cause lines to exceed
387           this length.
388
389           The default length of 80 comes from the past when this was the
390           standard CRT screen width.  Many programmers prefer to increase
391           this to something like 120.
392
393           Setting -l=0 is equivalent to setting -l=(a very large number).
394           But this is not recommended because, for example, a very long list
395           will be formatted in a single long line.
396
397       -vmll, --variable-maximum-line-length
398           A problem arises using a fixed maximum line length with very deeply
399           nested code and data structures because eventually the amount of
400           leading whitespace used for indicating indentation takes up most or
401           all of the available line width, leaving little or no space for the
402           actual code or data.  One solution is to use a vary long line
403           length.  Another solution is to use the -vmll flag, which basically
404           tells perltidy to ignore leading whitespace when measuring the line
405           length.
406
407           To be precise, when the -vmll parameter is set, the maximum line
408           length of a line of code will be M+L*I, where
409
410                 M is the value of --maximum-line-length=M (-l=M), default 80,
411                 I is the value of --indent-columns=I (-i=I), default 4,
412                 L is the indentation level of the line of code
413
414           When this flag is set, the choice of breakpoints for a block of
415           code should be essentially independent of its nesting depth.
416           However, the absolute line lengths, including leading whitespace,
417           can still be arbitrarily large.  This problem can be avoided by
418           including the next parameter.
419
420           The default is not to do this (-nvmll).
421
422       -wc=n, --whitespace-cycle=n
423           This flag also addresses problems with very deeply nested code and
424           data structures.  When the nesting depth exceeds the value n the
425           leading whitespace will be reduced and start at a depth of 1 again.
426           The result is that blocks of code will shift back to the left
427           rather than moving arbitrarily far to the right.  This occurs
428           cyclically to any depth.
429
430           For example if one level of indentation equals 4 spaces (-i=4, the
431           default), and one uses -wc=15, then if the leading whitespace on a
432           line exceeds about 4*15=60 spaces it will be reduced back to 4*1=4
433           spaces and continue increasing from there.  If the whitespace never
434           exceeds this limit the formatting remains unchanged.
435
436           The combination of -vmll and -wc=n provides a solution to the
437           problem of displaying arbitrarily deep data structures and code in
438           a finite window, although -wc=n may of course be used without
439           -vmll.
440
441           The default is not to use this, which can also be indicated using
442           -wc=0.
443
444       Tabs
445           Using tab characters will almost certainly lead to future
446           portability and maintenance problems, so the default and
447           recommendation is not to use them.  For those who prefer tabs,
448           however, there are two different options.
449
450           Except for possibly introducing tab indentation characters, as
451           outlined below, perltidy does not introduce any tab characters into
452           your file, and it removes any tabs from the code (unless requested
453           not to do so with -fws).  If you have any tabs in your comments,
454           quotes, or here-documents, they will remain.
455
456           -et=n,   --entab-leading-whitespace
457               This flag causes each n initial space characters to be replaced
458               by one tab character.
459
460               The value of the integer n can be any value but can be
461               coordinated with the number of spaces used for intentation. For
462               example, -et=4 -ci=4 -i=4 will produce one tab for each
463               indentation level and and one for each continuation indentation
464               level.  You may want to coordinate the value of n with what
465               your display software assumes for the spacing of a tab.
466
467           -t,   --tabs
468               This flag causes one leading tab character to be inserted for
469               each level of indentation.  Certain other features are
470               incompatible with this option, and if these options are also
471               given, then a warning message will be issued and this flag will
472               be unset.  One example is the -lp option. This flag is retained
473               for backwards compatability, but if you use tabs, the -et=n
474               flag is recommended.
475
476           -dt=n,   --default-tabsize=n
477               If the first line of code passed to perltidy contains leading
478               tabs but no tab scheme is specified for the output stream then
479               perltidy must guess how many spaces correspond to each leading
480               tab.  This number of spaces n corresponding to each leading tab
481               of the input stream may be specified with -dt=n.  The default
482               is n=8.
483
484               This flag has no effect if a tab scheme is specified for the
485               output stream, because then the input stream is assumed to use
486               the same tab scheme and indentation spaces as for the output
487               stream (any other assumption would lead to unstable editing).
488
489       -syn,   --check-syntax
490           This flag is now ignored for safety, but the following
491           documentation has been retained for reference.
492
493           This flag causes perltidy to run "perl -c -T" to check syntax of
494           input and output.  (To change the flags passed to perl, see the
495           next item, -pscf).  The results are written to the .LOG file, which
496           will be saved if an error is detected in the output script.  The
497           output script is not checked if the input script has a syntax
498           error.  Perltidy does its own checking, but this option employs
499           perl to get a "second opinion".
500
501           If perl reports errors in the input file, they will not be reported
502           in the error output unless the --warning-output flag is given.
503
504           The default is NOT to do this type of syntax checking (although
505           perltidy will still do as much self-checking as possible).  The
506           reason is that it causes all code in BEGIN blocks to be executed,
507           for all modules being used, and this opens the door to security
508           issues and infinite loops when running perltidy.
509
510       -pscf=s, -perl-syntax-check-flags=s
511           When perl is invoked to check syntax, the normal flags are "-c -T".
512           In addition, if the -x flag is given to perltidy, then perl will
513           also be passed a -x flag.  It should not normally be necessary to
514           change these flags, but it can be done with the -pscf=s flag.  For
515           example, if the taint flag, "-T", is not wanted, the flag could be
516           set to be just -pscf=-c.
517
518           Perltidy will pass your string to perl with the exception that it
519           will add a -c and -x if appropriate.  The .LOG file will show
520           exactly what flags were passed to perl.
521
522       -xs,   --extended-syntax
523           A problem with formatting Perl code is that some modules can
524           introduce new syntax.  This flag allows perltidy to handle certain
525           common extensions to the standard syntax without complaint.
526
527           For example, without this flag a structure such as the following
528           would generate a syntax error and the braces would not be balanced:
529
530               method deposit( Num $amount) {
531                   $self->balance( $self->balance + $amount );
532               }
533
534           For one of the extensions, module Switch::Plain, colons are marked
535           as labels.  If you use this module, you may want to also use the
536           --nooutdent-labels flag to prevent lines such as 'default:' from
537           being outdented.
538
539           This flag is enabled by default but it can be deactivated with
540           -nxs.  Probably the only reason to deactivate this flag is to
541           generate more diagnostic messages when debugging a script.
542
543       -io,   --indent-only
544           This flag is used to deactivate all whitespace and line break
545           changes within non-blank lines of code.  When it is in effect, the
546           only change to the script will be to the indentation and to the
547           number of blank lines.  And any flags controlling whitespace and
548           newlines will be ignored.  You might want to use this if you are
549           perfectly happy with your whitespace and line breaks, and merely
550           want perltidy to handle the indentation.  (This also speeds up
551           perltidy by well over a factor of two, so it might be useful when
552           perltidy is merely being used to help find a brace error in a large
553           script).
554
555           Setting this flag is equivalent to setting --freeze-newlines and
556           --freeze-whitespace.
557
558           If you also want to keep your existing blank lines exactly as they
559           are, you can add --freeze-blank-lines.
560
561           With this option perltidy is still free to modify the indenting
562           (and outdenting) of code and comments as it normally would.  If you
563           also want to prevent long comment lines from being outdented, you
564           can add either -noll or -l=0.
565
566           Setting this flag will prevent perltidy from doing any special
567           operations on closing side comments.  You may still delete all side
568           comments however when this flag is in effect.
569
570       -enc=s,  --character-encoding=s
571           This flag indicates the character encoding, if any, of the input
572           data stream.  Perltidy does not look for the encoding directives in
573           the soure stream, such as use utf8, and instead relies on this flag
574           to determine the encoding.  (Note that perltidy often works on
575           snippets of code rather than complete files so it cannot rely on
576           use utf8 directives).
577
578           The possible values for s are (1) the name of an encoding
579           recognized by the Encode.pm module, (2) none if no encoding is
580           used, or (3) <guess> if perltidy should guess.
581
582           For example, the value utf8 causes the stream to be read and
583           written as UTF-8.  If the input stream cannot be decoded with a
584           specified encoding then processing is not done.
585
586           The value none causes the stream to be processed without special
587           encoding assumptions.  This is appropriate for files which are
588           written in single-byte character encodings such as latin-1.
589
590           The value guess tells perltidy to guess between either utf8
591           encoding or no encoding (meaning one character per byte).  The
592           guess uses the Encode::Guess module and this restricted range of
593           guesses covers the most common cases.  Testing showed that
594           considering any greater number of encodings as guess suspects is
595           too risky.
596
597           The current default is guess.
598
599           The abbreviations -utf8 or -UTF8 are equivalent to -enc=utf8, and
600           the abbreviation -guess is equivalent to <-enc=guess>.  So to
601           process a file named file.pl which is encoded in UTF-8 you can use:
602
603              perltidy -utf8 file.pl
604
605           or
606              perltidy -guess file.pl
607
608           To process a file in euc-jp you could use
609
610              perltidy -enc=euc-jp file.pl
611
612           A perltidy output file is unencoded if the input file is unencoded,
613           and otherwise it is encoded as utf8, even if the input encoding was
614           not utf8.
615
616       -gcs,  --use-unicode-gcstring
617           This flag controls whether or not perltidy may use module
618           Unicode::GCString to obtain accurate display widths of wide
619           characters.  The default is --nouse-unicode-gcstring.
620
621           If this flag is set, and text is encoded, perltidy will look for
622           the module Unicode::GCString and, if found, will use it to obtain
623           character display widths.  This can improve displayed vertical
624           alignment for files with wide characters.  It is a nice feature but
625           it is off by default to avoid conflicting formatting when there are
626           multiple developers.  Perltidy installation does not require
627           Unicode::GCString, so users wanting to use this feature need set
628           this flag and also to install Unicode::GCString separately.
629
630           If this flag is set and perltidy does not find module
631           Unicode::GCString, a warning message will be produced and
632           processing will continue but without the potential benefit provided
633           by the module.
634
635           Also note that actual vertical alignment depends upon the fonts
636           used by the text display software, so vertical alignment may not be
637           optimal even when Unicode::GCString is used.
638
639       -ole=s,  --output-line-ending=s
640           where s="win", "dos", "unix", or "mac".  This flag tells perltidy
641           to output line endings for a specific system.  Normally, perltidy
642           writes files with the line separator character of the host system.
643           The "win" and "dos" flags have an identical result.
644
645       -ple,  --preserve-line-endings
646           This flag tells perltidy to write its output files with the same
647           line endings as the input file, if possible.  It should work for
648           dos, unix, and mac line endings.  It will only work if perltidy
649           input comes from a filename (rather than stdin, for example).  If
650           perltidy has trouble determining the input file line ending, it
651           will revert to the default behavior of using the line ending of the
652           host system.
653
654       -it=n,   --iterations=n
655           This flag causes perltidy to do n complete iterations.  The reason
656           for this flag is that code beautification is an iterative process
657           and in some cases the output from perltidy can be different if it
658           is applied a second time.  For most purposes the default of n=1
659           should be satisfactory.  However n=2 can be useful when a major
660           style change is being made, or when code is being beautified on
661           check-in to a source code control system.  It has been found to be
662           extremely rare for the output to change after 2 iterations.  If a
663           value n is greater than 2 is input then a convergence test will be
664           used to stop the iterations as soon as possible, almost always
665           after 2 iterations.  See the next item for a simplified iteration
666           control.
667
668           This flag has no effect when perltidy is used to generate html.
669
670       -conv,   --converge
671           This flag is equivalent to -it=4 and is included to simplify
672           iteration control.  For all practical purposes one either does or
673           does not want to be sure that the output is converged, and there is
674           no penalty to using a large iteration limit since perltidy will
675           check for convergence and stop iterating as soon as possible.  The
676           default is -nconv (no convergence check).  Using -conv will
677           approximately double run time since typically one extra iteration
678           is required to verify convergence.  No extra iterations are
679           required if no new line breaks are made, and two extra iterations
680           are occasionally needed when reformatting complex code structures,
681           such as deeply nested ternary statements.
682
683   Code Indentation Control
684       -ci=n, --continuation-indentation=n
685           Continuation indentation is extra indentation spaces applied when a
686           long line is broken.  The default is n=2, illustrated here:
687
688            my $level =   # -ci=2
689              ( $max_index_to_go >= 0 ) ? $levels_to_go[0] : $last_output_level;
690
691           The same example, with n=0, is a little harder to read:
692
693            my $level =   # -ci=0
694            ( $max_index_to_go >= 0 ) ? $levels_to_go[0] : $last_output_level;
695
696           The value given to -ci is also used by some commands when a small
697           space is required.  Examples are commands for outdenting labels,
698           -ola, and control keywords, -okw.
699
700           When default values are not used, it is recommended that either
701
702           (1) the value n given with -ci=n be no more than about one-half of
703           the number of spaces assigned to a full indentation level on the
704           -i=n command, or
705
706           (2) the flag -extended-continuation-indentation is used (see next
707           section).
708
709       -xci, --extended-continuation-indentation
710           This flag allows perltidy to use some improvements which have been
711           made to its indentation model. One of the things it does is
712           "extend" continuation indentation deeper into structures, hence the
713           name.  The improved indentation is particularly noticable when the
714           flags -ci=n and -i=n use the same value of n. There are no
715           significant disadvantages to using this flag, but to avoid
716           disturbing existing formatting the default is not to use it, -nxci.
717
718           Please see the section "-pbp, --perl-best-practices" for an example
719           of how this flag can improve the formatting of ternary statements.
720           It can also improve indentation of some multi-line qw lists as
721           shown below.
722
723                       # perltidy
724                       foreach $color (
725                           qw(
726                           AntiqueWhite3 Bisque1 Bisque2 Bisque3 Bisque4
727                           SlateBlue3 RoyalBlue1 SteelBlue2 DeepSkyBlue3
728                           ),
729                           qw(
730                           LightBlue1 DarkSlateGray1 Aquamarine2 DarkSeaGreen2
731                           SeaGreen1 Yellow1 IndianRed1 IndianRed2 Tan1 Tan4
732                           )
733                         )
734
735                       # perltidy -xci
736                       foreach $color (
737                           qw(
738                               AntiqueWhite3 Bisque1 Bisque2 Bisque3 Bisque4
739                               SlateBlue3 RoyalBlue1 SteelBlue2 DeepSkyBlue3
740                           ),
741                           qw(
742                               LightBlue1 DarkSlateGray1 Aquamarine2 DarkSeaGreen2
743                               SeaGreen1 Yellow1 IndianRed1 IndianRed2 Tan1 Tan4
744                           )
745                         )
746
747       -sil=n --starting-indentation-level=n
748           By default, perltidy examines the input file and tries to determine
749           the starting indentation level.  While it is often zero, it may not
750           be zero for a code snippet being sent from an editing session.
751
752           To guess the starting indentation level perltidy simply assumes
753           that indentation scheme used to create the code snippet is the same
754           as is being used for the current perltidy process.  This is the
755           only sensible guess that can be made.  It should be correct if this
756           is true, but otherwise it probably won't.  For example, if the
757           input script was written with -i=2 and the current peltidy flags
758           have -i=4, the wrong initial indentation will be guessed for a code
759           snippet which has non-zero initial indentation. Likewise, if an
760           entabbing scheme is used in the input script and not in the current
761           process then the guessed indentation will be wrong.
762
763           If the default method does not work correctly, or you want to
764           change the starting level, use -sil=n, to force the starting level
765           to be n.
766
767       List indentation using -lp, --line-up-parentheses
768           By default, perltidy indents lists with 4 spaces, or whatever value
769           is specified with -i=n.  Here is a small list formatted in this
770           way:
771
772               # perltidy (default)
773               @month_of_year = (
774                   'Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun',
775                   'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'
776               );
777
778           Use the -lp flag to add extra indentation to cause the data to
779           begin past the opening parentheses of a sub call or list, or
780           opening square bracket of an anonymous array, or opening curly
781           brace of an anonymous hash.  With this option, the above list would
782           become:
783
784               # perltidy -lp
785               @month_of_year = (
786                                  'Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun',
787                                  'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'
788               );
789
790           If the available line length (see -l=n ) does not permit this much
791           space, perltidy will use less.   For alternate placement of the
792           closing paren, see the next section.
793
794           This option has no effect on code BLOCKS, such as if/then/else
795           blocks, which always use whatever is specified with -i=n.  Also,
796           the existence of line breaks and/or block comments between the
797           opening and closing parens may cause perltidy to temporarily revert
798           to its default method.
799
800           Note: The -lp option may not be used together with the -t tabs
801           option.  It may, however, be used with the -et=n tab method.
802
803           In addition, any parameter which significantly restricts the
804           ability of perltidy to choose newlines will conflict with -lp and
805           will cause -lp to be deactivated.  These include -io, -fnl, -nanl,
806           and -ndnl.  The reason is that the -lp indentation style can
807           require the careful coordination of an arbitrary number of break
808           points in hierarchical lists, and these flags may prevent that.
809
810       -lpxl=s,  --line-up-parentheses-exclusion-list
811           This is an experimental parameter; the details might change as
812           experience with it is gained.
813
814           The -lp indentation style works well for some types of coding but
815           can produce very long lines when variables have long names and/or
816           containers are very deeply nested.  The -lpxl=s flag is intended to
817           help mitigate this problem by providing control over the containers
818           to which the -lp indentation style is applied.  The -lp flag by
819           default is "greedy" and applies to as many containers as possible.
820           This flag specifies a list of things which should not be use -lp
821           indentation.
822
823           This list is a string with space-separated items.  Each item
824           consists of up to three pieces of information in this order: (1) an
825           optional letter code (2) a required container type, and (3) an
826           optional numeric code.
827
828           The only required piece of information is a container type, which
829           is one of '(', '[', or '{'.  For example the string
830
831             -lpxl='[ {'
832
833           means do NOT include use -lp formatting within square-bracets or
834           braces.  The only unspecified container is '(', so this string
835           means that only the contens within parens will use -lp indentation.
836
837           An optional numeric code may follow any of the container types to
838           further refine the selection based on container contents.  The
839           numeric codes are:
840
841             '0' or blank: no check on contents
842             '1' reject -lp unless the contents is a simple list without sublists
843             '2' reject -lp unless the contents is a simple list without sublists, without
844                 code blocks, and without ternary operators
845
846           For example,
847
848             -lpxl = '[ { (2'
849
850           means only apply -lp to parenthesized lists which do not contain
851           any sublists, code blocks or ternary expressions.
852
853           A third optional item of information which can be given for parens
854           is an alphanumeric letter which is used to limit the selection
855           further depending on the type of token immediately before the
856           paren.  The possible letters are currently 'k', 'K', 'f', 'F', 'w',
857           and 'W', with these meanings:
858
859            'k' matches if the previous nonblank token is a perl builtin keyword (such as 'if', 'while'),
860            'K' matches if 'k' does not, meaning that the previous token is not a keyword.
861            'f' matches if the previous token is a function other than a keyword.
862            'F' matches if 'f' does not.
863            'w' matches if either 'k' or 'f' match.
864            'W' matches if 'w' does not.
865
866           For example,
867
868             -lpxl = '[ { F(2'
869
870           means only apply -lp to parenthesized lists which follow a function
871           call and which do not contain any sublists, code blocks or ternary
872           expressions.  The logic of writing these codes is somewhat counter-
873           intuitive because they describe what is not getting the -lp
874           indentation.  So the 'F' indicates that non-function calls are not
875           getting -lp, or in other words that function calls are getting the
876           -lp indentation.
877
878       -cti=n, --closing-token-indentation
879           The -cti=n flag controls the indentation of a line beginning with a
880           ")", "]", or a non-block "}".  Such a line receives:
881
882            -cti = 0 no extra indentation (default)
883            -cti = 1 extra indentation such that the closing token
884                   aligns with its opening token.
885            -cti = 2 one extra indentation level if the line looks like:
886                   );  or  ];  or  };
887            -cti = 3 one extra indentation level always
888
889           The flags -cti=1 and -cti=2 work well with the -lp flag (previous
890           section).
891
892               # perltidy -lp -cti=1
893               @month_of_year = (
894                                  'Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun',
895                                  'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'
896                                );
897
898               # perltidy -lp -cti=2
899               @month_of_year = (
900                                  'Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun',
901                                  'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'
902                                  );
903
904           These flags are merely hints to the formatter and they may not
905           always be followed.  In particular, if -lp is not being used, the
906           indentation for cti=1 is constrained to be no more than one
907           indentation level.
908
909           If desired, this control can be applied independently to each of
910           the closing container token types.  In fact, -cti=n is merely an
911           abbreviation for -cpi=n -csbi=n -cbi=n, where: -cpi or
912           --closing-paren-indentation controls )'s, -csbi or
913           --closing-square-bracket-indentation controls ]'s, -cbi or
914           --closing-brace-indentation controls non-block }'s.
915
916       -icp, --indent-closing-paren
917           The -icp flag is equivalent to -cti=2, described in the previous
918           section.  The -nicp flag is equivalent -cti=0.  They are included
919           for backwards compatibility.
920
921       -icb, --indent-closing-brace
922           The -icb option gives one extra level of indentation to a brace
923           which terminates a code block .  For example,
924
925                   if ($task) {
926                       yyy();
927                       }    # -icb
928                   else {
929                       zzz();
930                       }
931
932           The default is not to do this, indicated by -nicb.
933
934       -nib, --non-indenting-braces
935           Normally, lines of code contained within a pair of block braces
936           receive one additional level of indentation.  This flag, which is
937           enabled by default, causes perltidy to look for opening block
938           braces which are followed by a special side comment. This special
939           side comment is #<<< by default.  If found, the code between this
940           opening brace and its corresponding closing brace will not be given
941           the normal extra indentation level.  For example:
942
943                       { #<<<   a closure to contain lexical vars
944
945                       my $var;  # this line does not get one level of indentation
946                       ...
947
948                       }
949
950                       # this line does not 'see' $var;
951
952           This can be useful, for example, when combining code from different
953           files.  Different sections of code can be placed within braces to
954           keep their lexical variables from being visible to the end of the
955           file.  To keep the new braces from causing all of their contained
956           code to be indented if you run perltidy, and possibly introducing
957           new line breaks in long lines, you can mark the opening braces with
958           this special side comment.
959
960           Only the opening brace needs to be marked, since perltidy knows
961           where the closing brace is.  Braces contained within marked braces
962           may also be marked as non-indenting.
963
964           If your code happens to have some opening braces followed by
965           '#<<<', and you don't want this behavior, you can use -nnib to
966           deactivate it.  To make it easy to remember, the default string is
967           the same as the string for starting a format-skipping section.
968           There is no confusion because in that case it is for a block
969           comment rather than a side-comment.
970
971           The special side comment can be changed with the next parameter.
972
973       -nibp=s, --non-indenting-brace-prefix=s
974           The -nibp=string parameter may be used to change the marker for
975           non-indenting braces.  The default is equivalent to -nibp='#<<<'.
976           The string that you enter must begin with a # and should be in
977           quotes as necessary to get past the command shell of your system.
978           This string is the leading text of a regex pattern that is
979           constructed by appending pre-pending a '^' and appending a'\s', so
980           you must also include backslashes for characters to be taken
981           literally rather than as patterns.
982
983           For example, to match the side comment '#++', the parameter would
984           be
985
986             -nibp='#\+\+'
987
988       -olq, --outdent-long-quotes
989           When -olq is set, lines which is a quoted string longer than the
990           value maximum-line-length will have their indentation removed to
991           make them more readable.  This is the default.  To prevent such
992           out-denting, use -nolq or --nooutdent-long-lines.
993
994       -oll, --outdent-long-lines
995           This command is equivalent to --outdent-long-quotes and
996           --outdent-long-comments, and it is included for compatibility with
997           previous versions of perltidy.  The negation of this also works,
998           -noll or --nooutdent-long-lines, and is equivalent to setting -nolq
999           and -nolc.
1000
1001       Outdenting Labels: -ola,  --outdent-labels
1002           This command will cause labels to be outdented by 2 spaces (or
1003           whatever -ci has been set to), if possible.  This is the default.
1004           For example:
1005
1006                   my $i;
1007                 LOOP: while ( $i = <FOTOS> ) {
1008                       chomp($i);
1009                       next unless $i;
1010                       fixit($i);
1011                   }
1012
1013           Use -nola to not outdent labels.
1014
1015       Outdenting Keywords
1016           -okw,  --outdent-keywords
1017               The command -okw will cause certain leading control keywords to
1018               be outdented by 2 spaces (or whatever -ci has been set to), if
1019               possible.  By default, these keywords are "redo", "next",
1020               "last", "goto", and "return".  The intention is to make these
1021               control keywords easier to see.  To change this list of
1022               keywords being outdented, see the next section.
1023
1024               For example, using "perltidy -okw" on the previous example
1025               gives:
1026
1027                       my $i;
1028                     LOOP: while ( $i = <FOTOS> ) {
1029                           chomp($i);
1030                         next unless $i;
1031                           fixit($i);
1032                       }
1033
1034               The default is not to do this.
1035
1036           Specifying Outdented Keywords: -okwl=string,
1037           --outdent-keyword-list=string
1038               This command can be used to change the keywords which are
1039               outdented with the -okw command.  The parameter string is a
1040               required list of perl keywords, which should be placed in
1041               quotes if there are more than one.  By itself, it does not
1042               cause any outdenting to occur, so the -okw command is still
1043               required.
1044
1045               For example, the commands "-okwl="next last redo goto" -okw"
1046               will cause those four keywords to be outdented.  It is probably
1047               simplest to place any -okwl command in a .perltidyrc file.
1048
1049   Whitespace Control
1050       Whitespace refers to the blank space between variables, operators, and
1051       other code tokens.
1052
1053       -fws,  --freeze-whitespace
1054           This flag causes your original whitespace to remain unchanged, and
1055           causes the rest of the whitespace commands in this section, the
1056           Code Indentation section, and the Comment Control section to be
1057           ignored.
1058
1059       Tightness of curly braces, parentheses, and square brackets
1060           Here the term "tightness" will mean the closeness with which pairs
1061           of enclosing tokens, such as parentheses, contain the quantities
1062           within.  A numerical value of 0, 1, or 2 defines the tightness,
1063           with 0 being least tight and 2 being most tight.  Spaces within
1064           containers are always symmetric, so if there is a space after a "("
1065           then there will be a space before the corresponding ")".
1066
1067           The -pt=n or --paren-tightness=n parameter controls the space
1068           within parens.  The example below shows the effect of the three
1069           possible values, 0, 1, and 2:
1070
1071            if ( ( my $len_tab = length( $tabstr ) ) > 0 ) {  # -pt=0
1072            if ( ( my $len_tab = length($tabstr) ) > 0 ) {    # -pt=1 (default)
1073            if ((my $len_tab = length($tabstr)) > 0) {        # -pt=2
1074
1075           When n is 0, there is always a space to the right of a '(' and to
1076           the left of a ')'.  For n=2 there is never a space.  For n=1, the
1077           default, there is a space unless the quantity within the parens is
1078           a single token, such as an identifier or quoted string.
1079
1080           Likewise, the parameter -sbt=n or --square-bracket-tightness=n
1081           controls the space within square brackets, as illustrated below.
1082
1083            $width = $col[ $j + $k ] - $col[ $j ];  # -sbt=0
1084            $width = $col[ $j + $k ] - $col[$j];    # -sbt=1 (default)
1085            $width = $col[$j + $k] - $col[$j];      # -sbt=2
1086
1087           Curly braces which do not contain code blocks are controlled by the
1088           parameter -bt=n or --brace-tightness=n.
1089
1090            $obj->{ $parsed_sql->{ 'table' }[0] };    # -bt=0
1091            $obj->{ $parsed_sql->{'table'}[0] };      # -bt=1 (default)
1092            $obj->{$parsed_sql->{'table'}[0]};        # -bt=2
1093
1094           And finally, curly braces which contain blocks of code are
1095           controlled by the parameter -bbt=n or --block-brace-tightness=n as
1096           illustrated in the example below.
1097
1098            %bf = map { $_ => -M $_ } grep { /\.deb$/ } dirents '.'; # -bbt=0 (default)
1099            %bf = map { $_ => -M $_ } grep {/\.deb$/} dirents '.';   # -bbt=1
1100            %bf = map {$_ => -M $_} grep {/\.deb$/} dirents '.';     # -bbt=2
1101
1102           To simplify input in the case that all of the tightness flags have
1103           the same value <n>, the parameter <-act=n> or
1104           --all-containers-tightness=n is an abbreviation for the combination
1105           <-pt=n -sbt=n -bt=n -bbt=n>.
1106
1107       -tso,   --tight-secret-operators
1108           The flag -tso causes certain perl token sequences (secret
1109           operators) which might be considered to be a single operator to be
1110           formatted "tightly" (without spaces).  The operators currently
1111           modified by this flag are:
1112
1113                0+  +0  ()x!! ~~<>  ,=>   =( )=
1114
1115           For example the sequence 0 +,  which converts a string to a number,
1116           would be formatted without a space: 0+ when the -tso flag is set.
1117           This flag is off by default.
1118
1119       -sts,   --space-terminal-semicolon
1120           Some programmers prefer a space before all terminal semicolons.
1121           The default is for no such space, and is indicated with -nsts or
1122           --nospace-terminal-semicolon.
1123
1124                   $i = 1 ;     #  -sts
1125                   $i = 1;      #  -nsts   (default)
1126
1127       -sfs,   --space-for-semicolon
1128           Semicolons within for loops may sometimes be hard to see,
1129           particularly when commas are also present.  This option places
1130           spaces on both sides of these special semicolons, and is the
1131           default.  Use -nsfs or --nospace-for-semicolon to deactivate it.
1132
1133            for ( @a = @$ap, $u = shift @a ; @a ; $u = $v ) {  # -sfs (default)
1134            for ( @a = @$ap, $u = shift @a; @a; $u = $v ) {    # -nsfs
1135
1136       -asc,  --add-semicolons
1137           Setting -asc allows perltidy to add any missing optional semicolon
1138           at the end of a line which is followed by a closing curly brace on
1139           the next line.  This is the default, and may be deactivated with
1140           -nasc or --noadd-semicolons.
1141
1142       -dsm,  --delete-semicolons
1143           Setting -dsm allows perltidy to delete extra semicolons which are
1144           simply empty statements.  This is the default, and may be
1145           deactivated with -ndsm or --nodelete-semicolons.  (Such semicolons
1146           are not deleted, however, if they would promote a side comment to a
1147           block comment).
1148
1149       -aws,  --add-whitespace
1150           Setting this option allows perltidy to add certain whitespace to
1151           improve code readability.  This is the default. If you do not want
1152           any whitespace added, but are willing to have some whitespace
1153           deleted, use -naws.  (Use -fws to leave whitespace completely
1154           unchanged).
1155
1156       -dws,  --delete-old-whitespace
1157           Setting this option allows perltidy to remove some old whitespace
1158           between characters, if necessary.  This is the default.  If you do
1159           not want any old whitespace removed, use -ndws or
1160           --nodelete-old-whitespace.
1161
1162       Detailed whitespace controls around tokens
1163           For those who want more detailed control over the whitespace around
1164           tokens, there are four parameters which can directly modify the
1165           default whitespace rules built into perltidy for any token.  They
1166           are:
1167
1168           -wls=s or --want-left-space=s,
1169
1170           -nwls=s or --nowant-left-space=s,
1171
1172           -wrs=s or --want-right-space=s,
1173
1174           -nwrs=s or --nowant-right-space=s.
1175
1176           These parameters are each followed by a quoted string, s,
1177           containing a list of token types.  No more than one of each of
1178           these parameters should be specified, because repeating a command-
1179           line parameter always overwrites the previous one before perltidy
1180           ever sees it.
1181
1182           To illustrate how these are used, suppose it is desired that there
1183           be no space on either side of the token types = + - / *.  The
1184           following two parameters would specify this desire:
1185
1186             -nwls="= + - / *"    -nwrs="= + - / *"
1187
1188           (Note that the token types are in quotes, and that they are
1189           separated by spaces).  With these modified whitespace rules, the
1190           following line of math:
1191
1192             $root = -$b + sqrt( $b * $b - 4. * $a * $c ) / ( 2. * $a );
1193
1194           becomes this:
1195
1196             $root=-$b+sqrt( $b*$b-4.*$a*$c )/( 2.*$a );
1197
1198           These parameters should be considered to be hints to perltidy
1199           rather than fixed rules, because perltidy must try to resolve
1200           conflicts that arise between them and all of the other rules that
1201           it uses.  One conflict that can arise is if, between two tokens,
1202           the left token wants a space and the right one doesn't.  In this
1203           case, the token not wanting a space takes priority.
1204
1205           It is necessary to have a list of all token types in order to
1206           create this type of input.  Such a list can be obtained by the
1207           command --dump-token-types.  Also try the -D flag on a short
1208           snippet of code and look at the .DEBUG file to see the
1209           tokenization.
1210
1211           WARNING Be sure to put these tokens in quotes to avoid having them
1212           misinterpreted by your command shell.
1213
1214       Note1: Perltidy does always follow whitespace controls
1215           The various parameters controlling whitespace within a program are
1216           requests which perltidy follows as well as possible, but there are
1217           a number of situations where changing whitespace could change
1218           program behavior and is not done.  Some of these are obvious; for
1219           example, we should not remove the space between the two plus
1220           symbols in '$x+ +$y' to avoid creating a '++' operator. Some are
1221           more subtle and involve the whitespace around bareword symbols and
1222           locations of possible filehandles.  For example, consider the
1223           problem of formatting the following subroutine:
1224
1225              sub print_div {
1226                 my ($x,$y)=@_;
1227                 print $x/$y;
1228              }
1229
1230           Suppose the user requests that / signs have a space to the left but
1231           not to the right. Perltidy will refuse to do this, but if this were
1232           done the result would be
1233
1234              sub print_div {
1235                  my ($x,$y)=@_;
1236                  print $x /$y;
1237              }
1238
1239           If formatted in this way, the program will not run (at least with
1240           recent versions of perl) because the $x is taken to be a filehandle
1241           and / is assumed to start a quote. In a complex program, there
1242           might happen to be a / which terminates the multiline quote without
1243           a syntax error, allowing the program to run, but not as intended.
1244
1245           Related issues arise with other binary operator symbols, such as +
1246           and -, and in older versions of perl there could be problems with
1247           ternary operators.  So to avoid changing program behavior, perltidy
1248           has the simple rule that whitespace around possible filehandles is
1249           left unchanged.  Likewise, whitespace around barewords is left
1250           unchanged.  The reason is that if the barewords are defined in
1251           other modules, or in code that has not even been written yet,
1252           perltidy will not have seen their prototypes and must treat them
1253           cautiously.
1254
1255           In perltidy this is implemented in the tokenizer by marking token
1256           following a print keyword as a special type Z.  When formatting is
1257           being done, whitespace following this token type is generally left
1258           unchanged as a precaution against changing program behavior.  This
1259           is excessively conservative but simple and easy to implement.
1260           Keywords which are treated similarly to print include printf, sort,
1261           exec, system.  Changes in spacing around parameters following these
1262           keywords may have to be made manually.  For example, the space, or
1263           lack of space, after the parameter $foo in the following line will
1264           be unchanged in formatting.
1265
1266              system($foo );
1267              system($foo);
1268
1269           To find if a token is of type Z you can use perltidy -DEBUG. For
1270           the first line above the result is
1271
1272              1: system($foo );
1273              1: kkkkkk{ZZZZb};
1274
1275           which shows that system is type k (keyword) and $foo is type Z.
1276
1277       Note2: Perltidy's whitespace rules are not perfect
1278           Despite these precautions, it is still possible to introduce syntax
1279           errors with some asymmetric whitespace rules, particularly when
1280           call parameters are not placed in containg parens or braces.  For
1281           example, the following two lines will be parsed by perl without a
1282           syntax error:
1283
1284             # original programming, syntax ok
1285             my @newkeys = map $_-$nrecs+@data, @oldkeys;
1286
1287             # perltidy default, syntax ok
1288             my @newkeys = map $_ - $nrecs + @data, @oldkeys;
1289
1290           But the following will give a syntax error:
1291
1292             # perltidy -nwrs='-'
1293             my @newkeys = map $_ -$nrecs + @data, @oldkeys;
1294
1295           For another example, the following two lines will be parsed without
1296           syntax error:
1297
1298             # original programming, syntax ok
1299             for my $severity ( reverse $SEVERITY_LOWEST+1 .. $SEVERITY_HIGHEST ) { ...  }
1300
1301             # perltidy default, syntax ok
1302             for my $severity ( reverse $SEVERITY_LOWEST + 1 .. $SEVERITY_HIGHEST ) { ... }
1303
1304           But the following will give a syntax error:
1305
1306             # perltidy -nwrs='+', syntax error:
1307             for my $severity ( reverse $SEVERITY_LOWEST +1 .. $SEVERITY_HIGHEST ) { ... }
1308
1309           To avoid subtle parsing problems like this, it is best to avoid
1310           spacing a binary operator asymetrically with a space on the left
1311           but not on the right.
1312
1313       Space between specific keywords and opening paren
1314           When an opening paren follows a Perl keyword, no space is
1315           introduced after the keyword, unless it is (by default) one of
1316           these:
1317
1318              my local our and or xor eq ne if else elsif until unless
1319              while for foreach return switch case given when
1320
1321           These defaults can be modified with two commands:
1322
1323           -sak=s  or --space-after-keyword=s  adds keywords.
1324
1325           -nsak=s  or --nospace-after-keyword=s  removes keywords.
1326
1327           where s is a list of keywords (in quotes if necessary).  For
1328           example,
1329
1330             my ( $a, $b, $c ) = @_;    # default
1331             my( $a, $b, $c ) = @_;     # -nsak="my local our"
1332
1333           The abbreviation -nsak='*' is equivalent to including all of the
1334           keywords in the above list.
1335
1336           When both -nsak=s and -sak=s commands are included, the -nsak=s
1337           command is executed first.  For example, to have space after only
1338           the keywords (my, local, our) you could use -nsak="*" -sak="my
1339           local our".
1340
1341           To put a space after all keywords, see the next item.
1342
1343       Space between all keywords and opening parens
1344           When an opening paren follows a function or keyword, no space is
1345           introduced after the keyword except for the keywords noted in the
1346           previous item.  To always put a space between a function or keyword
1347           and its opening paren, use the command:
1348
1349           -skp  or --space-keyword-paren
1350
1351           You may also want to use the flag -sfp (next item) too.
1352
1353       Space between all function names and opening parens
1354           When an opening paren follows a function the default and
1355           recommended formatting is not to introduce a space.  To cause a
1356           space to be introduced use:
1357
1358           -sfp  or --space-function-paren
1359
1360             myfunc( $a, $b, $c );    # default
1361             myfunc ( $a, $b, $c );   # -sfp
1362
1363           You will probably also want to use the flag -skp (previous item)
1364           too.
1365
1366           The reason this is not recommended is that spacing a function paren
1367           can make a program vulnerable to parsing problems by Perl.  For
1368           example, the following two-line program will run as written but
1369           will have a syntax error if reformatted with -sfp:
1370
1371             if ( -e filename() ) { print "I'm here\n"; }
1372             sub filename { return $0 }
1373
1374           In this particular case the syntax error can be removed if the line
1375           order is reversed, so that Perl parses 'sub filename' first.
1376
1377       -fpva  or --function-paren-vertical-alignment
1378           A side-effect of using the -sfp flag is that the parens may become
1379           vertically aligned. For example,
1380
1381               # perltidy -sfp
1382               myfun     ( $aaa, $b, $cc );
1383               mylongfun ( $a, $b, $c );
1384
1385           This is the default behavior.  To prevent this alignment use
1386           -nfpva:
1387
1388               # perltidy -sfp -nfpva
1389               myfun ( $aaa, $b, $cc );
1390               mylongfun ( $a, $b, $c );
1391
1392       -spp=n  or --space-prototype-paren=n
1393           This flag can be used to control whether a function prototype is
1394           preceded by a space.  For example, the following prototype does not
1395           have a space.
1396
1397                 sub usage();
1398
1399           This integer n may have the value 0, 1, or 2 as follows:
1400
1401               -spp=0 means no space before the paren
1402               -spp=1 means follow the example of the source code [DEFAULT]
1403               -spp=2 means always put a space before the paren
1404
1405           The default is -spp=1, meaning that a space will be used if and
1406           only if there is one in the source code.  Given the above line of
1407           code, the result of applying the different options would be:
1408
1409                   sub usage();    # n=0 [no space]
1410                   sub usage();    # n=1 [default; follows input]
1411                   sub usage ();   # n=2 [space]
1412
1413       -kpit=n or --keyword-paren-inner-tightness=n
1414           The space inside of an opening paren, which itself follows a
1415           certain keyword, can be controlled by this parameter.  The space on
1416           the inside of the corresponding closing paren will be treated in
1417           the same (balanced) manner.  This parameter has precedence over any
1418           other paren spacing rules.  The values of n are as follows:
1419
1420              -kpit=0 means always put a space (not tight)
1421              -kpit=1 means ignore this parameter [default]
1422              -kpit=2 means never put a space (tight)
1423
1424           To illustrate, the following snippet is shown formatted in three
1425           ways:
1426
1427               if ( seek( DATA, 0, 0 ) ) { ... }    # perltidy (default)
1428               if (seek(DATA, 0, 0)) { ... }        # perltidy -pt=2
1429               if ( seek(DATA, 0, 0) ) { ... }      # perltidy -pt=2 -kpit=0
1430
1431           In the second case the -pt=2 parameter makes all of the parens
1432           tight. In the third case the -kpit=0 flag causes the space within
1433           the 'if' parens to have a space, since 'if' is one of the keywords
1434           to which the -kpit flag applies by default.  The remaining parens
1435           are still tight because of the -pt=2 parameter.
1436
1437           The set of keywords to which this parameter applies are by default
1438           are:
1439
1440              if elsif unless while until for foreach
1441
1442           These can be changed with the parameter -kpitl=s described in the
1443           next section.
1444
1445       -kpitl=string or --keyword-paren-inner-tightness=string
1446           This command can be used to change the keywords to which the the
1447           -kpit=n command applies.  The parameter string is a required list
1448           either keywords or functions, which should be placed in quotes if
1449           there are more than one.  By itself, this parameter does not cause
1450           any change in spacing, so the -kpit=n command is still required.
1451
1452           For example, the commands "-kpitl="if else while" -kpit=2" will
1453           cause the just the spaces inside parens following  'if', 'else',
1454           and 'while' keywords to follow the tightness value indicated by the
1455           -kpit=2 flag.
1456
1457       -lop  or --logical-padding
1458           In the following example some extra space has been inserted on the
1459           second line between the two open parens. This extra space is called
1460           "logical padding" and is intended to help align similar things
1461           vertically in some logical or ternary expressions.
1462
1463               # perltidy [default formatting]
1464               $same =
1465                 (      ( $aP eq $bP )
1466                     && ( $aS eq $bS )
1467                     && ( $aT eq $bT )
1468                     && ( $a->{'title'} eq $b->{'title'} )
1469                     && ( $a->{'href'} eq $b->{'href'} ) );
1470
1471           Note that this is considered to be a different operation from
1472           "vertical alignment" because space at just one line is being
1473           adjusted, whereas in "vertical alignment" the spaces at all lines
1474           are being adjusted. So it sort of a local version of vertical
1475           alignment.
1476
1477           Here is an example involving a ternary operator:
1478
1479               # perltidy [default formatting]
1480               $bits =
1481                   $top > 0xffff ? 32
1482                 : $top > 0xff   ? 16
1483                 : $top > 1      ? 8
1484                 :                 1;
1485
1486           This behavior is controlled with the flag --logical-padding, which
1487           is set 'on' by default.  If it is not desired it can be turned off
1488           using --nological-padding or -nlop.  The above two examples become,
1489           with -nlop:
1490
1491               # perltidy -nlop
1492               $same =
1493                 ( ( $aP eq $bP )
1494                     && ( $aS eq $bS )
1495                     && ( $aT eq $bT )
1496                     && ( $a->{'title'} eq $b->{'title'} )
1497                     && ( $a->{'href'} eq $b->{'href'} ) );
1498
1499               # perltidy -nlop
1500               $bits =
1501                 $top > 0xffff ? 32
1502                 : $top > 0xff ? 16
1503                 : $top > 1    ? 8
1504                 :               1;
1505
1506       Trimming whitespace around "qw" quotes
1507           -tqw or --trim-qw provide the default behavior of trimming spaces
1508           around multi-line "qw" quotes and indenting them appropriately.
1509
1510           -ntqw or --notrim-qw cause leading and trailing whitespace around
1511           multi-line "qw" quotes to be left unchanged.  This option will not
1512           normally be necessary, but was added for testing purposes, because
1513           in some versions of perl, trimming "qw" quotes changes the syntax
1514           tree.
1515
1516       -sbq=n  or --space-backslash-quote=n
1517           lines like
1518
1519                  $str1=\"string1";
1520                  $str2=\'string2';
1521
1522           can confuse syntax highlighters unless a space is included between
1523           the backslash and the single or double quotation mark.
1524
1525           this can be controlled with the value of n as follows:
1526
1527               -sbq=0 means no space between the backslash and quote
1528               -sbq=1 means follow the example of the source code
1529               -sbq=2 means always put a space between the backslash and quote
1530
1531           The default is -sbq=1, meaning that a space will be used if there
1532           is one in the source code.
1533
1534       Trimming trailing whitespace from lines of POD
1535           -trp or --trim-pod will remove trailing whitespace from lines of
1536           POD.  The default is not to do this.
1537
1538   Comment Controls
1539       Perltidy has a number of ways to control the appearance of both block
1540       comments and side comments.  The term block comment here refers to a
1541       full-line comment, whereas side comment will refer to a comment which
1542       appears on a line to the right of some code.
1543
1544       -ibc,  --indent-block-comments
1545           Block comments normally look best when they are indented to the
1546           same level as the code which follows them.  This is the default
1547           behavior, but you may use -nibc to keep block comments left-
1548           justified.  Here is an example:
1549
1550                        # this comment is indented      (-ibc, default)
1551                        if ($task) { yyy(); }
1552
1553           The alternative is -nibc:
1554
1555            # this comment is not indented              (-nibc)
1556                        if ($task) { yyy(); }
1557
1558           See also the next item, -isbc, as well as -sbc, for other ways to
1559           have some indented and some outdented block comments.
1560
1561       -isbc,  --indent-spaced-block-comments
1562           If there is no leading space on the line, then the comment will not
1563           be indented, and otherwise it may be.
1564
1565           If both -ibc and -isbc are set, then -isbc takes priority.
1566
1567       -olc, --outdent-long-comments
1568           When -olc is set, lines which are full-line (block) comments longer
1569           than the value maximum-line-length will have their indentation
1570           removed.  This is the default; use -nolc to prevent outdenting.
1571
1572       -msc=n,  --minimum-space-to-comment=n
1573           Side comments look best when lined up several spaces to the right
1574           of code.  Perltidy will try to keep comments at least n spaces to
1575           the right.  The default is n=4 spaces.
1576
1577       -fpsc=n,  --fixed-position-side-comment=n
1578           This parameter tells perltidy to line up side comments in column
1579           number n whenever possible.  The default, n=0, will not do this.
1580
1581       -iscl,  --ignore-side-comment-lengths
1582           This parameter causes perltidy to ignore the length of side
1583           comments when setting line breaks.  The default, -niscl, is to
1584           include the length of side comments when breaking lines to stay
1585           within the length prescribed by the -l=n maximum line length
1586           parameter.  For example, the following long single line would
1587           remain intact with -l=80 and -iscl:
1588
1589                perltidy -l=80 -iscl
1590                   $vmsfile =~ s/;[\d\-]*$//; # Clip off version number; we can use a newer version as well
1591
1592           whereas without the -iscl flag the line will be broken:
1593
1594                perltidy -l=80
1595                   $vmsfile =~ s/;[\d\-]*$//
1596                     ;    # Clip off version number; we can use a newer version as well
1597
1598       -hsc, --hanging-side-comments
1599           By default, perltidy tries to identify and align "hanging side
1600           comments", which are something like this:
1601
1602                   my $IGNORE = 0;    # This is a side comment
1603                                      # This is a hanging side comment
1604                                      # And so is this
1605
1606           A comment is considered to be a hanging side comment if (1) it
1607           immediately follows a line with a side comment, or another hanging
1608           side comment, and (2) there is some leading whitespace on the line.
1609           To deactivate this feature, use -nhsc or --nohanging-side-comments.
1610           If block comments are preceded by a blank line, or have no leading
1611           whitespace, they will not be mistaken as hanging side comments.
1612
1613       Closing Side Comments
1614           A closing side comment is a special comment which perltidy can
1615           automatically create and place after the closing brace of a code
1616           block.  They can be useful for code maintenance and debugging.  The
1617           command -csc (or --closing-side-comments) adds or updates closing
1618           side comments.  For example, here is a small code snippet
1619
1620                   sub message {
1621                       if ( !defined( $_[0] ) ) {
1622                           print("Hello, World\n");
1623                       }
1624                       else {
1625                           print( $_[0], "\n" );
1626                       }
1627                   }
1628
1629           And here is the result of processing with "perltidy -csc":
1630
1631                   sub message {
1632                       if ( !defined( $_[0] ) ) {
1633                           print("Hello, World\n");
1634                       }
1635                       else {
1636                           print( $_[0], "\n" );
1637                       }
1638                   } ## end sub message
1639
1640           A closing side comment was added for "sub message" in this case,
1641           but not for the "if" and "else" blocks, because they were below the
1642           6 line cutoff limit for adding closing side comments.  This limit
1643           may be changed with the -csci command, described below.
1644
1645           The command -dcsc (or --delete-closing-side-comments) reverses this
1646           process and removes these comments.
1647
1648           Several commands are available to modify the behavior of these two
1649           basic commands, -csc and -dcsc:
1650
1651           -csci=n, or --closing-side-comment-interval=n
1652               where "n" is the minimum number of lines that a block must have
1653               in order for a closing side comment to be added.  The default
1654               value is "n=6".  To illustrate:
1655
1656                       # perltidy -csci=2 -csc
1657                       sub message {
1658                           if ( !defined( $_[0] ) ) {
1659                               print("Hello, World\n");
1660                           } ## end if ( !defined( $_[0] ))
1661                           else {
1662                               print( $_[0], "\n" );
1663                           } ## end else [ if ( !defined( $_[0] ))
1664                       } ## end sub message
1665
1666               Now the "if" and "else" blocks are commented.  However, now
1667               this has become very cluttered.
1668
1669           -cscp=string, or --closing-side-comment-prefix=string
1670               where string is the prefix used before the name of the block
1671               type.  The default prefix, shown above, is "## end".  This
1672               string will be added to closing side comments, and it will also
1673               be used to recognize them in order to update, delete, and
1674               format them.  Any comment identified as a closing side comment
1675               will be placed just a single space to the right of its closing
1676               brace.
1677
1678           -cscl=string, or --closing-side-comment-list
1679               where "string" is a list of block types to be tagged with
1680               closing side comments.  By default, all code block types
1681               preceded by a keyword or label (such as "if", "sub", and so on)
1682               will be tagged.  The -cscl command changes the default list to
1683               be any selected block types; see "Specifying Block Types".  For
1684               example, the following command requests that only "sub"'s,
1685               labels, "BEGIN", and "END" blocks be affected by any -csc or
1686               -dcsc operation:
1687
1688                  -cscl="sub : BEGIN END"
1689
1690           -csct=n, or --closing-side-comment-maximum-text=n
1691               The text appended to certain block types, such as an "if"
1692               block, is whatever lies between the keyword introducing the
1693               block, such as "if", and the opening brace.  Since this might
1694               be too much text for a side comment, there needs to be a limit,
1695               and that is the purpose of this parameter.  The default value
1696               is "n=20", meaning that no additional tokens will be appended
1697               to this text after its length reaches 20 characters.  Omitted
1698               text is indicated with "...".  (Tokens, including sub names,
1699               are never truncated, however, so actual lengths may exceed
1700               this).  To illustrate, in the above example, the appended text
1701               of the first block is " ( !defined( $_[0] )...".  The existing
1702               limit of "n=20" caused this text to be truncated, as indicated
1703               by the "...".  See the next flag for additional control of the
1704               abbreviated text.
1705
1706           -cscb, or --closing-side-comments-balanced
1707               As discussed in the previous item, when the closing-side-
1708               comment-maximum-text limit is exceeded the comment text must be
1709               truncated.  Older versions of perltidy terminated with three
1710               dots, and this can still be achieved with -ncscb:
1711
1712                 perltidy -csc -ncscb
1713                 } ## end foreach my $foo (sort { $b cmp $a ...
1714
1715               However this causes a problem with editors which cannot
1716               recognize comments or are not configured to do so because they
1717               cannot "bounce" around in the text correctly.  The -cscb flag
1718               has been added to help them by appending appropriate balancing
1719               structure:
1720
1721                 perltidy -csc -cscb
1722                 } ## end foreach my $foo (sort { $b cmp $a ... })
1723
1724               The default is -cscb.
1725
1726           -csce=n, or --closing-side-comment-else-flag=n
1727               The default, n=0, places the text of the opening "if" statement
1728               after any terminal "else".
1729
1730               If n=2 is used, then each "elsif" is also given the text of the
1731               opening "if" statement.  Also, an "else" will include the text
1732               of a preceding "elsif" statement.  Note that this may result
1733               some long closing side comments.
1734
1735               If n=1 is used, the results will be the same as n=2 whenever
1736               the resulting line length is less than the maximum allowed.
1737
1738           -cscb, or --closing-side-comments-balanced
1739               When using closing-side-comments, and the closing-side-comment-
1740               maximum-text limit is exceeded, then the comment text must be
1741               abbreviated.  It is terminated with three dots if the -cscb
1742               flag is negated:
1743
1744                 perltidy -csc -ncscb
1745                 } ## end foreach my $foo (sort { $b cmp $a ...
1746
1747               This causes a problem with older editors which do not recognize
1748               comments because they cannot "bounce" around in the text
1749               correctly.  The -cscb flag tries to help them by appending
1750               appropriate terminal balancing structures:
1751
1752                 perltidy -csc -cscb
1753                 } ## end foreach my $foo (sort { $b cmp $a ... })
1754
1755               The default is -cscb.
1756
1757           -cscw, or --closing-side-comment-warnings
1758               This parameter is intended to help make the initial transition
1759               to the use of closing side comments.  It causes two things to
1760               happen if a closing side comment replaces an existing,
1761               different closing side comment:  first, an error message will
1762               be issued, and second, the original side comment will be placed
1763               alone on a new specially marked comment line for later
1764               attention.
1765
1766               The intent is to avoid clobbering existing hand-written side
1767               comments which happen to match the pattern of closing side
1768               comments. This flag should only be needed on the first run with
1769               -csc.
1770
1771           Important Notes on Closing Side Comments:
1772
1773           •   Closing side comments are only placed on lines terminated with
1774               a closing brace.  Certain closing styles, such as the use of
1775               cuddled elses (-ce), preclude the generation of some closing
1776               side comments.
1777
1778           •   Please note that adding or deleting of closing side comments
1779               takes place only through the commands -csc or -dcsc.  The other
1780               commands, if used, merely modify the behavior of these two
1781               commands.
1782
1783           •   It is recommended that the -cscw flag be used along with -csc
1784               on the first use of perltidy on a given file.  This will
1785               prevent loss of any existing side comment data which happens to
1786               have the csc prefix.
1787
1788           •   Once you use -csc, you should continue to use it so that any
1789               closing side comments remain correct as code changes.
1790               Otherwise, these comments will become incorrect as the code is
1791               updated.
1792
1793           •   If you edit the closing side comments generated by perltidy,
1794               you must also change the prefix to be different from the
1795               closing side comment prefix.  Otherwise, your edits will be
1796               lost when you rerun perltidy with -csc.   For example, you
1797               could simply change "## end" to be "## End", since the test is
1798               case sensitive.  You may also want to use the -ssc flag to keep
1799               these modified closing side comments spaced the same as actual
1800               closing side comments.
1801
1802           •   Temporarily generating closing side comments is a useful
1803               technique for exploring and/or debugging a perl script,
1804               especially one written by someone else.  You can always remove
1805               them with -dcsc.
1806
1807       Static Block Comments
1808           Static block comments are block comments with a special leading
1809           pattern, "##" by default, which will be treated slightly
1810           differently from other block comments.  They effectively behave as
1811           if they had glue along their left and top edges, because they stick
1812           to the left edge and previous line when there is no blank spaces in
1813           those places.  This option is particularly useful for controlling
1814           how commented code is displayed.
1815
1816           -sbc, --static-block-comments
1817               When -sbc is used, a block comment with a special leading
1818               pattern, "##" by default, will be treated specially.
1819
1820               Comments so identified  are treated as follows:
1821
1822               •   If there is no leading space on the line, then the comment
1823                   will not be indented, and otherwise it may be,
1824
1825               •   no new blank line will be inserted before such a comment,
1826                   and
1827
1828               •   such a comment will never become a hanging side comment.
1829
1830               For example, assuming @month_of_year is left-adjusted:
1831
1832                   @month_of_year = (    # -sbc (default)
1833                       'Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct',
1834                   ##  'Dec', 'Nov'
1835                       'Nov', 'Dec');
1836
1837               Without this convention, the above code would become
1838
1839                   @month_of_year = (   # -nsbc
1840                       'Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct',
1841
1842                       ##  'Dec', 'Nov'
1843                       'Nov', 'Dec'
1844                   );
1845
1846               which is not as clear.  The default is to use -sbc.  This may
1847               be deactivated with -nsbc.
1848
1849           -sbcp=string, --static-block-comment-prefix=string
1850               This parameter defines the prefix used to identify static block
1851               comments when the -sbc parameter is set.  The default prefix is
1852               "##", corresponding to "-sbcp=##".  The prefix is actually part
1853               of a perl pattern used to match lines and it must either begin
1854               with "#" or "^#".  In the first case a prefix ^\s* will be
1855               added to match any leading whitespace, while in the second case
1856               the pattern will match only comments with no leading
1857               whitespace.  For example, to identify all comments as static
1858               block comments, one would use "-sbcp=#".  To identify all left-
1859               adjusted comments as static block comments, use "-sbcp='^#'".
1860
1861               Please note that -sbcp merely defines the pattern used to
1862               identify static block comments; it will not be used unless the
1863               switch -sbc is set.  Also, please be aware that since this
1864               string is used in a perl regular expression which identifies
1865               these comments, it must enable a valid regular expression to be
1866               formed.
1867
1868               A pattern which can be useful is:
1869
1870                   -sbcp=^#{2,}[^\s#]
1871
1872               This pattern requires a static block comment to have at least
1873               one character which is neither a # nor a space.  It allows a
1874               line containing only '#' characters to be rejected as a static
1875               block comment.  Such lines are often used at the start and end
1876               of header information in subroutines and should not be
1877               separated from the intervening comments, which typically begin
1878               with just a single '#'.
1879
1880           -osbc, --outdent-static-block-comments
1881               The command -osbc will cause static block comments to be
1882               outdented by 2 spaces (or whatever -ci=n has been set to), if
1883               possible.
1884
1885       Static Side Comments
1886           Static side comments are side comments with a special leading
1887           pattern.  This option can be useful for controlling how commented
1888           code is displayed when it is a side comment.
1889
1890           -ssc, --static-side-comments
1891               When -ssc is used, a side comment with a static leading
1892               pattern, which is "##" by default, will be spaced only a single
1893               space from previous character, and it will not be vertically
1894               aligned with other side comments.
1895
1896               The default is -nssc.
1897
1898           -sscp=string, --static-side-comment-prefix=string
1899               This parameter defines the prefix used to identify static side
1900               comments when the -ssc parameter is set.  The default prefix is
1901               "##", corresponding to "-sscp=##".
1902
1903               Please note that -sscp merely defines the pattern used to
1904               identify static side comments; it will not be used unless the
1905               switch -ssc is set.  Also, note that this string is used in a
1906               perl regular expression which identifies these comments, so it
1907               must enable a valid regular expression to be formed.
1908
1909   Skipping Selected Sections of Code
1910       Selected lines of code may be passed verbatim to the output without any
1911       formatting.  This feature is enabled by default but can be disabled
1912       with the --noformat-skipping or -nfs flag.  It should be used sparingly
1913       to avoid littering code with markers, but it might be helpful for
1914       working around occasional problems.  For example it might be useful for
1915       keeping the indentation of old commented code unchanged, keeping
1916       indentation of long blocks of aligned comments unchanged, keeping
1917       certain list formatting unchanged, or working around a glitch in
1918       perltidy.
1919
1920       -fs,  --format-skipping
1921           This flag, which is enabled by default, causes any code between
1922           special beginning and ending comment markers to be passed to the
1923           output without formatting.  The default beginning marker is #<<<
1924           and the default ending marker is #>>> but they may be changed (see
1925           next items below).  Additional text may appear on these special
1926           comment lines provided that it is separated from the marker by at
1927           least one space.  For example
1928
1929            #<<<  do not let perltidy touch this
1930               my @list = (1,
1931                           1, 1,
1932                           1, 2, 1,
1933                           1, 3, 3, 1,
1934                           1, 4, 6, 4, 1,);
1935            #>>>
1936
1937           Format skipping begins when a format skipping comment is seen and
1938           continues until either a format-skipping end pattern is found or
1939           until the end of file.
1940
1941           The comment markers may be placed at any location that a block
1942           comment may appear.  If they do not appear to be working, use the
1943           -log flag and examine the .LOG file.  Use -nfs to disable this
1944           feature.
1945
1946           This method works for any code. For the specific case of a comma-
1947           separated list of values, as in this example, another possibility
1948           is to insert a blank or comment somewhere between the opening and
1949           closing parens.  See the section "Controlling List Formatting".
1950
1951       -fsb=string,  --format-skipping-begin=string
1952           The -fsb=string parameter may be used to change the beginning
1953           marker for format skipping.  The default is equivalent to
1954           -fsb='#<<<'.  The string that you enter must begin with a # and
1955           should be in quotes as necessary to get past the command shell of
1956           your system.  It is actually the leading text of a pattern that is
1957           constructed by appending a '\s', so you must also include
1958           backslashes for characters to be taken literally rather than as
1959           patterns.
1960
1961           Some examples show how example strings become patterns:
1962
1963            -fsb='#\{\{\{' becomes /^#\{\{\{\s/  which matches  #{{{ but not #{{{{
1964            -fsb='#\*\*'   becomes /^#\*\*\s/    which matches  #** but not #***
1965            -fsb='#\*{2,}' becomes /^#\*{2,}\s/  which matches  #** and #*****
1966
1967       -fse=string,  --format-skipping-end=string
1968           The -fse=string is the corresponding parameter used to change the
1969           ending marker for format skipping.  The default is equivalent to
1970           -fse='#<<<'.
1971
1972           The beginning and ending strings may be the same, but it is
1973           preferable to make them different for clarity.
1974
1975   Line Break Control
1976       The parameters in this section control breaks after non-blank lines of
1977       code.  Blank lines are controlled separately by parameters in the
1978       section "Blank Line Control".
1979
1980       -fnl,  --freeze-newlines
1981           If you do not want any changes to the line breaks within lines of
1982           code in your script, set -fnl, and they will remain fixed, and the
1983           rest of the commands in this section and sections "Controlling List
1984           Formatting", "Retaining or Ignoring Existing Line Breaks".  You may
1985           want to use -noll with this.
1986
1987           Note: If you also want to keep your blank lines exactly as they
1988           are, you can use the -fbl flag which is described in the section
1989           "Blank Line Control".
1990
1991       -ce,   --cuddled-else
1992           Enable the "cuddled else" style, in which "else" and "elsif" are
1993           follow immediately after the curly brace closing the previous
1994           block.  The default is not to use cuddled elses, and is indicated
1995           with the flag -nce or --nocuddled-else.  Here is a comparison of
1996           the alternatives:
1997
1998             # -ce
1999             if ($task) {
2000                 yyy();
2001             } else {
2002                 zzz();
2003             }
2004
2005             # -nce (default)
2006             if ($task) {
2007                   yyy();
2008             }
2009             else {
2010                   zzz();
2011             }
2012
2013           In this example the keyword else is placed on the same line which
2014           begins with the preceding closing block brace and is followed by
2015           its own opening block brace on the same line.  Other keywords and
2016           function names which are formatted with this "cuddled" style are
2017           elsif, continue, catch, finally.
2018
2019           Other block types can be formatted by specifying their names on a
2020           separate parameter -cbl, described in a later section.
2021
2022           Cuddling between a pair of code blocks requires that the closing
2023           brace of the first block start a new line.  If this block is
2024           entirely on one line in the input file, it is necessary to decide
2025           if it should be broken to allow cuddling.  This decision is
2026           controlled by the flag -cbo=n discussed below.  The default and
2027           recommended value of -cbo=1 bases this decision on the first block
2028           in the chain.  If it spans multiple lines then cuddling is made and
2029           continues along the chain, regardless of the sizes of subsequent
2030           blocks. Otherwise, short lines remain intact.
2031
2032           So for example, the -ce flag would not have any effect if the above
2033           snippet is rewritten as
2034
2035             if ($task) { yyy() }
2036             else {    zzz() }
2037
2038           If the first block spans multiple lines, then cuddling can be done
2039           and will continue for the subsequent blocks in the chain, as
2040           illustrated in the previous snippet.
2041
2042           If there are blank lines between cuddled blocks they will be
2043           eliminated.  If there are comments after the closing brace where
2044           cuddling would occur then cuddling will be prevented.  If this
2045           occurs, cuddling will restart later in the chain if possible.
2046
2047       -cb,   --cuddled-blocks
2048           This flag is equivalent to -ce.
2049
2050       -cbl,    --cuddled-block-list
2051           The built-in default cuddled block types are else, elsif, continue,
2052           catch, finally.
2053
2054           Additional block types to which the -cuddled-blocks style applies
2055           can be defined by this parameter.  This parameter is a character
2056           string, giving a list of block types separated by commas or spaces.
2057           For example, to cuddle code blocks of type sort, map and grep, in
2058           addition to the default types, the string could be set to
2059
2060             -cbl="sort map grep"
2061
2062           or equivalently
2063
2064             -cbl=sort,map,grep
2065
2066           Note however that these particular block types are typically short
2067           so there might not be much opportunity for the cuddled format
2068           style.
2069
2070           Using commas avoids the need to protect spaces with quotes.
2071
2072           As a diagnostic check, the flag --dump-cuddled-block-list or -dcbl
2073           can be used to view the hash of values that are generated by this
2074           flag.
2075
2076           Finally, note that the -cbl flag by itself merely specifies which
2077           blocks are formatted with the cuddled format. It has no effect
2078           unless this formatting style is activated with -ce.
2079
2080       -cblx,    --cuddled-block-list-exclusive
2081           When cuddled else formatting is selected with -ce, setting this
2082           flag causes perltidy to ignore its built-in defaults and rely
2083           exclusively on the block types specified on the -cbl flag described
2084           in the previous section.  For example, to avoid using cuddled catch
2085           and finally, which among in the defaults, the following set of
2086           parameters could be used:
2087
2088             perltidy -ce -cbl='else elsif continue' -cblx
2089
2090       -cbo=n,   --cuddled-break-option=n
2091           Cuddled formatting is only possible between a pair of code blocks
2092           if the closing brace of the first block starts a new line. If a
2093           block is encountered which is entirely on a single line, and
2094           cuddled formatting is selected, it is necessary to make a decision
2095           as to whether or not to "break" the block, meaning to cause it to
2096           span multiple lines.  This parameter controls that decision. The
2097           options are:
2098
2099              cbo=0  Never force a short block to break.
2100              cbo=1  If the first of a pair of blocks is broken in the input file,
2101                     then break the second [DEFAULT].
2102              cbo=2  Break open all blocks for maximal cuddled formatting.
2103
2104           The default and recommended value is cbo=1.  With this value, if
2105           the starting block of a chain spans multiple lines, then a cascade
2106           of breaks will occur for remaining blocks causing the entire chain
2107           to be cuddled.
2108
2109           The option cbo=0 can produce erratic cuddling if there are numerous
2110           one-line blocks.
2111
2112           The option cbo=2 produces maximal cuddling but will not allow any
2113           short blocks.
2114
2115       -bl,    --opening-brace-on-new-line
2116           Use the flag -bl to place the opening brace on a new line:
2117
2118             if ( $input_file eq '-' )    # -bl
2119             {
2120                 important_function();
2121             }
2122
2123           This flag applies to all structural blocks, including named sub's
2124           (unless the -sbl flag is set -- see next item).
2125
2126           The default style, -nbl, places an opening brace on the same line
2127           as the keyword introducing it.  For example,
2128
2129             if ( $input_file eq '-' ) {   # -nbl (default)
2130
2131       -sbl,    --opening-sub-brace-on-new-line
2132           The flag -sbl can be used to override the value of -bl for the
2133           opening braces of named sub's.  For example,
2134
2135            perltidy -sbl
2136
2137           produces this result:
2138
2139            sub message
2140            {
2141               if (!defined($_[0])) {
2142                   print("Hello, World\n");
2143               }
2144               else {
2145                   print($_[0], "\n");
2146               }
2147            }
2148
2149           This flag is negated with -nsbl.  If -sbl is not specified, the
2150           value of -bl is used.
2151
2152       -asbl,    --opening-anonymous-sub-brace-on-new-line
2153           The flag -asbl is like the -sbl flag except that it applies to
2154           anonymous sub's instead of named subs. For example
2155
2156            perltidy -asbl
2157
2158           produces this result:
2159
2160            $a = sub
2161            {
2162                if ( !defined( $_[0] ) ) {
2163                    print("Hello, World\n");
2164                }
2165                else {
2166                    print( $_[0], "\n" );
2167                }
2168            };
2169
2170           This flag is negated with -nasbl, and the default is -nasbl.
2171
2172       -bli,    --brace-left-and-indent
2173           The flag -bli is the same as -bl but in addition it causes one unit
2174           of continuation indentation ( see -ci ) to be placed before an
2175           opening and closing block braces.
2176
2177           For example,
2178
2179                   if ( $input_file eq '-' )    # -bli
2180                     {
2181                       important_function();
2182                     }
2183
2184           By default, this extra indentation occurs for blocks of type: if,
2185           elsif, else, unless, for, foreach, sub, while, until, and also with
2186           a preceding label.  The next item shows how to change this.
2187
2188       -blil=s,    --brace-left-and-indent-list=s
2189           Use this parameter to change the types of block braces for which
2190           the -bli flag applies; see "Specifying Block Types".  For example,
2191           -blil='if elsif else' would apply it to only "if/elsif/else"
2192           blocks.
2193
2194       -bar,    --opening-brace-always-on-right
2195           The default style, -nbl places the opening code block brace on a
2196           new line if it does not fit on the same line as the opening
2197           keyword, like this:
2198
2199                   if ( $bigwasteofspace1 && $bigwasteofspace2
2200                     || $bigwasteofspace3 && $bigwasteofspace4 )
2201                   {
2202                       big_waste_of_time();
2203                   }
2204
2205           To force the opening brace to always be on the right, use the -bar
2206           flag.  In this case, the above example becomes
2207
2208                   if ( $bigwasteofspace1 && $bigwasteofspace2
2209                     || $bigwasteofspace3 && $bigwasteofspace4 ) {
2210                       big_waste_of_time();
2211                   }
2212
2213           A conflict occurs if both -bl and -bar are specified.
2214
2215       -otr,  --opening-token-right and related flags
2216           The -otr flag is a hint that perltidy should not place a break
2217           between a comma and an opening token.  For example:
2218
2219               # default formatting
2220               push @{ $self->{$module}{$key} },
2221                 {
2222                   accno       => $ref->{accno},
2223                   description => $ref->{description}
2224                 };
2225
2226               # perltidy -otr
2227               push @{ $self->{$module}{$key} }, {
2228                   accno       => $ref->{accno},
2229                   description => $ref->{description}
2230                 };
2231
2232           The flag -otr is actually an abbreviation for three other flags
2233           which can be used to control parens, hash braces, and square
2234           brackets separately if desired:
2235
2236             -opr  or --opening-paren-right
2237             -ohbr or --opening-hash-brace-right
2238             -osbr or --opening-square-bracket-right
2239
2240       -bbhb=n,  --break-before-hash-brace=n and related flags
2241           When a list of items spans multiple lines, the default formatting
2242           is to place the opening brace (or other container token) at the end
2243           of the starting line, like this:
2244
2245               $romanNumerals = {
2246                   one   => 'I',
2247                   two   => 'II',
2248                   three => 'III',
2249                   four  => 'IV',
2250               };
2251
2252           This flag can change the default behavior to cause a line break to
2253           be placed before the opening brace according to the value given to
2254           the integer n:
2255
2256             -bbhb=0 never break [default]
2257             -bbhb=1 stable: break if the input script had a break
2258             -bbhb=2 break if list is 'complex' (see note below)
2259             -bbhb=3 always break
2260
2261           For example,
2262
2263               # perltidy -bbhb=3
2264               $romanNumerals =
2265                 {
2266                   one   => 'I',
2267                   two   => 'II',
2268                   three => 'III',
2269                   four  => 'IV',
2270                 };
2271
2272           There are several points to note about this flag:
2273
2274           •   This parameter only applies if the opening brace is preceded by
2275               an '=' or '=>'.
2276
2277           •   This parameter only applies if the contents of the container
2278               looks like a list.  The contents need to contain some commas or
2279               '=>'s at the next interior level to be considered a list.
2280
2281           •   For the n=2 option, a list is considered 'complex' if it is
2282               part of a nested list structure which spans multiple lines in
2283               the input file.
2284
2285           •   If multiple opening tokens have been 'welded' together with the
2286               -wn parameter, then this parameter has no effect.
2287
2288           •   The indentation of the braces will normally be one level of
2289               continuation indentation by default.  This can be changed with
2290               the parameter -bbhbi=n in the next section.
2291
2292           •   Similar flags for controlling parens and square brackets are
2293               given in the subsequent section.
2294
2295       -bbhbi=n,  --break-before-hash-brace-and-indent=n
2296           This flag is a companion to -bbhb=n for controlling the indentation
2297           of an opening hash brace which is placed on a new line by that
2298           parameter.  The indentation is as follows:
2299
2300             -bbhbi=0 one continuation level [default]
2301             -bbhbi=1 outdent by one continuation level
2302             -bbhbi=2 indent one full indentation level
2303
2304           For example:
2305
2306               # perltidy -bbhb=3 -bbhbi=1
2307               $romanNumerals =
2308               {
2309                   one   => 'I',
2310                   two   => 'II',
2311                   three => 'III',
2312                   four  => 'IV',
2313               };
2314
2315               # perltidy -bbhb=3 -bbhbi=2
2316               $romanNumerals =
2317                   {
2318                   one   => 'I',
2319                   two   => 'II',
2320                   three => 'III',
2321                   four  => 'IV',
2322                   };
2323
2324           Note that this parameter has no effect unless -bbhb=n is also set.
2325
2326       -bbsb=n,  --break-before-square-bracket=n
2327           This flag is similar to the flag described above, except it applies
2328           to lists contained within square brackets.
2329
2330             -bbsb=0 never break [default]
2331             -bbsb=1 stable: break if the input script had a break
2332             -bbsb=2 break if list is 'complex' (part of nested list structure)
2333             -bbsb=3 always break
2334
2335       -bbsbi=n,  --break-before-square-bracket-and-indent=n
2336           This flag is a companion to -bbsb=n for controlling the indentation
2337           of an opening square bracket which is placed on a new line by that
2338           parameter.  The indentation is as follows:
2339
2340             -bbsbi=0 one continuation level [default]
2341             -bbsbi=1 outdent by one continuation level
2342             -bbsbi=2 indent one full indentation level
2343
2344       -bbp=n,  --break-before-paren=n
2345           This flag is similar to -bbhb=n, described above, except it applies
2346           to lists contained within parens.
2347
2348             -bbp=0 never break [default]
2349             -bbp=1 stable: break if the input script had a break
2350             -bpb=2 break if list is 'complex' (part of nested list structure)
2351             -bbp=3 always break
2352
2353       -bbpi=n,  --break-before-paren-and-indent=n
2354           This flag is a companion to -bbp=n for controlling the indentation
2355           of an opening paren which is placed on a new line by that
2356           parameter.  The indentation is as follows:
2357
2358             -bbpi=0 one continuation level [default]
2359             -bbpi=1 outdent by one continuation level
2360             -bbpi=2 indent one full indentation level
2361
2362       -wn,  --weld-nested-containers
2363           The -wn flag causes closely nested pairs of opening and closing
2364           container symbols (curly braces, brackets, or parens) to be
2365           "welded" together, meaning that they are treated as if combined
2366           into a single unit, with the indentation of the innermost code
2367           reduced to be as if there were just a single container symbol.
2368
2369           For example:
2370
2371                   # default formatting
2372                   do {
2373                       {
2374                           next if $x == $y;
2375                       }
2376                   } until $x++ > $z;
2377
2378                   # perltidy -wn
2379                   do { {
2380                       next if $x == $y;
2381                   } } until $x++ > $z;
2382
2383           When this flag is set perltidy makes a preliminary pass through the
2384           file and identifies all nested pairs of containers.  To qualify as
2385           a nested pair, the closing container symbols must be immediately
2386           adjacent and the opening symbols must either (1) be adjacent as in
2387           the above example, or (2) have an anonymous sub declaration
2388           following an outer opening container symbol which is not a code
2389           block brace, or (3) have an outer opening paren separated from the
2390           inner opening symbol by any single non-container symbol or
2391           something that looks like a function evaluation, as illustrated in
2392           the next examples.
2393
2394           Any container symbol may serve as both the inner container of one
2395           pair and as the outer container of an adjacent pair. Consequently,
2396           any number of adjacent opening or closing symbols may join together
2397           in weld.  For example, here are three levels of wrapped function
2398           calls:
2399
2400                   # default formatting
2401                   my (@date_time) = Localtime(
2402                       Date_to_Time(
2403                           Add_Delta_DHMS(
2404                               $year, $month,  $day, $hour, $minute, $second,
2405                               '0',   $offset, '0',  '0'
2406                           )
2407                       )
2408                   );
2409
2410                   # perltidy -wn
2411                   my (@date_time) = Localtime( Date_to_Time( Add_Delta_DHMS(
2412                       $year, $month,  $day, $hour, $minute, $second,
2413                       '0',   $offset, '0',  '0'
2414                   ) ) );
2415
2416           Notice how the indentation of the inner lines are reduced by two
2417           levels in this case.  This example also shows the typical result of
2418           this formatting, namely it is a sandwich consisting of an initial
2419           opening layer, a central section of any complexity forming the
2420           "meat" of the sandwich, and a final closing layer.  This
2421           predictable structure helps keep the compacted structure readable.
2422
2423           The inner sandwich layer is required to be at least one line thick.
2424           If this cannot be achieved, welding does not occur.  This
2425           constraint can cause formatting to take a couple of iterations to
2426           stabilize when it is first applied to a script. The -conv flag can
2427           be used to insure that the final format is achieved in a single
2428           run.
2429
2430           Here is an example illustrating a welded container within a welded
2431           containers:
2432
2433                   # default formatting
2434                   $x->badd(
2435                       bmul(
2436                           $class->new(
2437                               abs(
2438                                   $sx * int( $xr->numify() ) & $sy * int( $yr->numify() )
2439                               )
2440                           ),
2441                           $m
2442                       )
2443                   );
2444
2445                   # perltidy -wn
2446                   $x->badd( bmul(
2447                       $class->new( abs(
2448                           $sx * int( $xr->numify() ) & $sy * int( $yr->numify() )
2449                       ) ),
2450                       $m
2451                   ) );
2452
2453           The welded closing tokens are by default on a separate line but
2454           this can be modified with the -vtc=n flag (described in the next
2455           section).  For example, the same example adding -vtc=2 is
2456
2457                   # perltidy -wn -vtc=2
2458                   $x->badd( bmul(
2459                       $class->new( abs(
2460                           $sx * int( $xr->numify() ) & $sy * int( $yr->numify() ) ) ),
2461                       $m ) );
2462
2463           This format option is quite general but there are some limitations.
2464
2465           One limitation is that any line length limit still applies and can
2466           cause long welded sections to be broken into multiple lines.
2467
2468           Another limitation is that an opening symbol which delimits quoted
2469           text cannot be included in a welded pair.  This is because quote
2470           delimiters are treated specially in perltidy.
2471
2472           Finally, the stacking of containers defined by this flag have
2473           priority over any other container stacking flags.  This is because
2474           any welding is done first.
2475
2476       -wnxl=s,  --weld-nested-exclusion-list
2477           The -wnxl=s flag provides some control over the types of containers
2478           which can be welded.  The -wn flag by default is "greedy" in
2479           welding adjacent containers.  If it welds more types of containers
2480           than desired, this flag provides a capability to reduce the amount
2481           of welding by specifying a list of things which should not be
2482           welded.
2483
2484           The logic in perltidy to apply this is straightforward.  As each
2485           container token is being considered for joining a weld, any
2486           exclusion rules are consulted and used to reject the weld if
2487           necessary.
2488
2489           This list is a string with space-separated items.  Each item
2490           consists of up to three pieces of information: (1) an optional
2491           position, (2) an optional preceding type, and (3) a container type.
2492
2493           The only required piece of information is a container type, which
2494           is one of '(', '[', '{' or 'q'.  The first three of these are
2495           container tokens and the last represents a quoted list.  For
2496           example the string
2497
2498             -wnxl='[ { q'
2499
2500           means do NOT include square-bracets, braces, or quotes in any
2501           welds.  The only unspecified container is '(', so this string means
2502           that only welds involving parens will be made.
2503
2504           To illustrate, following welded snippet consists of a chain of
2505           three welded containers with types '(' '[' and 'q':
2506
2507               # perltidy -wn
2508               skip_symbols( [ qw(
2509                   Perl_dump_fds
2510                   Perl_ErrorNo
2511                   Perl_GetVars
2512                   PL_sys_intern
2513               ) ] );
2514
2515           Even though the qw term uses parens as the quote delimiter, it has
2516           a special type 'q' here. If it appears in a weld it always appears
2517           at the end of the welded chain.
2518
2519           Any of the container types '[', '{', and '(' may be prefixed with a
2520           position indicator which is either '^', to indicate the first token
2521           of a welded sequence, or '.', to indicate an interior token of a
2522           welded sequence.  (Since a quoted string 'q' always ends a chain it
2523           does need a position indicator).
2524
2525           For example, if we do not want a sequence of welded containers to
2526           start with a square bracket we could use
2527
2528             -wnxl='^['
2529
2530           In the above snippet, there is a square bracket but it does not
2531           start the chain, so the formatting would be unchanged if it were
2532           formatted with this restriction.
2533
2534           A third optional item of information which can be given is an
2535           alphanumeric letter which is used to limit the selection further
2536           depending on the type of token immediately before the container.
2537           If given, it goes just before the container symbol.  The possible
2538           letters are currently 'k', 'K', 'f', 'F', 'w', and 'W', with these
2539           meanings:
2540
2541            'k' matches if the previous nonblank token is a perl builtin keyword (such as 'if', 'while'),
2542            'K' matches if 'k' does not, meaning that the previous token is not a keyword.
2543            'f' matches if the previous token is a function other than a keyword.
2544            'F' matches if 'f' does not.
2545            'w' matches if either 'k' or 'f' match.
2546            'W' matches if 'w' does not.
2547
2548           For example, compare
2549
2550                   # perltidy -wn
2551                   if ( defined( $_Cgi_Query{
2552                       $Config{'methods'}{'authentication'}{'remote'}{'cgi'}{'username'}
2553                   } ) )
2554
2555           with
2556
2557                   # perltidy -wn -wnxl='^K( {'
2558                   if ( defined(
2559                       $_Cgi_Query{ $Config{'methods'}{'authentication'}{'remote'}{'cgi'}
2560                             {'username'} }
2561                   ) )
2562
2563           The first case does maximum welding. In the second case the leading
2564           paren is retained by the rule (it would have been rejected if
2565           preceded by a non-keyword) but the curly brace is rejected by the
2566           rule.
2567
2568           Here are some additional example strings and their meanings:
2569
2570               '^('   - the weld must not start with a paren
2571               '.('   - the second and later tokens may not be parens
2572               '('    - no parens in a weld
2573               '^K('  - exclude a leading paren preceded by a non-keyword
2574               '.k('  - exclude a secondary paren preceded by a keyword
2575               '[ {'  - exclude all brackets and braces
2576
2577       Vertical tightness of non-block curly braces, parentheses, and square
2578       brackets.
2579           These parameters control what shall be called vertical tightness.
2580           Here are the main points:
2581
2582           •   Opening tokens (except for block braces) are controlled by
2583               -vt=n, or --vertical-tightness=n, where
2584
2585                -vt=0 always break a line after opening token (default).
2586                -vt=1 do not break unless this would produce more than one
2587                        step in indentation in a line.
2588                -vt=2 never break a line after opening token
2589
2590           •   You must also use the -lp flag when you use the -vt flag; the
2591               reason is explained below.
2592
2593           •   Closing tokens (except for block braces) are controlled by
2594               -vtc=n, or --vertical-tightness-closing=n, where
2595
2596                -vtc=0 always break a line before a closing token (default),
2597                -vtc=1 do not break before a closing token which is followed
2598                       by a semicolon or another closing token, and is not in
2599                       a list environment.
2600                -vtc=2 never break before a closing token.
2601
2602               The rules for -vtc=1 are designed to maintain a reasonable
2603               balance between tightness and readability in complex lists.
2604
2605           •   Different controls may be applied to different token types, and
2606               it is also possible to control block braces; see below.
2607
2608           •   Finally, please note that these vertical tightness flags are
2609               merely hints to the formatter, and it cannot always follow
2610               them.  Things which make it difficult or impossible include
2611               comments, blank lines, blocks of code within a list, and
2612               possibly the lack of the -lp parameter.  Also, these flags may
2613               be ignored for very small lists (2 or 3 lines in length).
2614
2615           Here are some examples:
2616
2617               # perltidy -lp -vt=0 -vtc=0
2618               %romanNumerals = (
2619                                  one   => 'I',
2620                                  two   => 'II',
2621                                  three => 'III',
2622                                  four  => 'IV',
2623               );
2624
2625               # perltidy -lp -vt=1 -vtc=0
2626               %romanNumerals = ( one   => 'I',
2627                                  two   => 'II',
2628                                  three => 'III',
2629                                  four  => 'IV',
2630               );
2631
2632               # perltidy -lp -vt=1 -vtc=1
2633               %romanNumerals = ( one   => 'I',
2634                                  two   => 'II',
2635                                  three => 'III',
2636                                  four  => 'IV', );
2637
2638           The difference between -vt=1 and -vt=2 is shown here:
2639
2640               # perltidy -lp -vt=1
2641               $init->add(
2642                           mysprintf( "(void)find_threadsv(%s);",
2643                                      cstring( $threadsv_names[ $op->targ ] )
2644                           )
2645               );
2646
2647               # perltidy -lp -vt=2
2648               $init->add( mysprintf( "(void)find_threadsv(%s);",
2649                                      cstring( $threadsv_names[ $op->targ ] )
2650                           )
2651               );
2652
2653           With -vt=1, the line ending in "add(" does not combine with the
2654           next line because the next line is not balanced.  This can help
2655           with readability, but -vt=2 can be used to ignore this rule.
2656
2657           The tightest, and least readable, code is produced with both
2658           "-vt=2" and "-vtc=2":
2659
2660               # perltidy -lp -vt=2 -vtc=2
2661               $init->add( mysprintf( "(void)find_threadsv(%s);",
2662                                      cstring( $threadsv_names[ $op->targ ] ) ) );
2663
2664           Notice how the code in all of these examples collapses vertically
2665           as -vt increases, but the indentation remains unchanged.  This is
2666           because perltidy implements the -vt parameter by first formatting
2667           as if -vt=0, and then simply overwriting one output line on top of
2668           the next, if possible, to achieve the desired vertical tightness.
2669           The -lp indentation style has been designed to allow this vertical
2670           collapse to occur, which is why it is required for the -vt
2671           parameter.
2672
2673           The -vt=n and -vtc=n parameters apply to each type of container
2674           token.  If desired, vertical tightness controls can be applied
2675           independently to each of the closing container token types.
2676
2677           The parameters for controlling parentheses are -pvt=n or
2678           --paren-vertical-tightness=n, and -pcvt=n or
2679           --paren-vertical-tightness-closing=n.
2680
2681           Likewise, the parameters for square brackets are -sbvt=n or
2682           --square-bracket-vertical-tightness=n, and -sbcvt=n or
2683           --square-bracket-vertical-tightness-closing=n.
2684
2685           Finally, the parameters for controlling non-code block braces are
2686           -bvt=n or --brace-vertical-tightness=n, and -bcvt=n or
2687           --brace-vertical-tightness-closing=n.
2688
2689           In fact, the parameter -vt=n is actually just an abbreviation for
2690           -pvt=n -bvt=n sbvt=n, and likewise -vtc=n is an abbreviation for
2691           -pvtc=n -bvtc=n sbvtc=n.
2692
2693       -bbvt=n or --block-brace-vertical-tightness=n
2694           The -bbvt=n flag is just like the -vt=n flag but applies to opening
2695           code block braces.
2696
2697            -bbvt=0 break after opening block brace (default).
2698            -bbvt=1 do not break unless this would produce more than one
2699                    step in indentation in a line.
2700            -bbvt=2 do not break after opening block brace.
2701
2702           It is necessary to also use either -bl or -bli for this to work,
2703           because, as with other vertical tightness controls, it is
2704           implemented by simply overwriting a line ending with an opening
2705           block brace with the subsequent line.  For example:
2706
2707               # perltidy -bli -bbvt=0
2708               if ( open( FILE, "< $File" ) )
2709                 {
2710                   while ( $File = <FILE> )
2711                     {
2712                       $In .= $File;
2713                       $count++;
2714                     }
2715                   close(FILE);
2716                 }
2717
2718               # perltidy -bli -bbvt=1
2719               if ( open( FILE, "< $File" ) )
2720                 { while ( $File = <FILE> )
2721                     { $In .= $File;
2722                       $count++;
2723                     }
2724                   close(FILE);
2725                 }
2726
2727           By default this applies to blocks associated with keywords if,
2728           elsif, else, unless, for, foreach, sub, while, until, and also with
2729           a preceding label.  This can be changed with the parameter
2730           -bbvtl=string, or --block-brace-vertical-tightness-list=string,
2731           where string is a space-separated list of block types.  For more
2732           information on the possible values of this string, see "Specifying
2733           Block Types"
2734
2735           For example, if we want to just apply this style to "if", "elsif",
2736           and "else" blocks, we could use "perltidy -bli -bbvt=1 -bbvtl='if
2737           elsif else'".
2738
2739           There is no vertical tightness control for closing block braces;
2740           with one exception they will be placed on separate lines.  The
2741           exception is that a cascade of closing block braces may be stacked
2742           on a single line.  See -scbb.
2743
2744       -sot,  --stack-opening-tokens and related flags
2745           The -sot flag tells perltidy to "stack" opening tokens when
2746           possible to avoid lines with isolated opening tokens.
2747
2748           For example:
2749
2750               # default
2751               $opt_c = Text::CSV_XS->new(
2752                   {
2753                       binary       => 1,
2754                       sep_char     => $opt_c,
2755                       always_quote => 1,
2756                   }
2757               );
2758
2759               # -sot
2760               $opt_c = Text::CSV_XS->new( {
2761                       binary       => 1,
2762                       sep_char     => $opt_c,
2763                       always_quote => 1,
2764                   }
2765               );
2766
2767           For detailed control of individual closing tokens the following
2768           controls can be used:
2769
2770             -sop  or --stack-opening-paren
2771             -sohb or --stack-opening-hash-brace
2772             -sosb or --stack-opening-square-bracket
2773             -sobb or --stack-opening-block-brace
2774
2775           The flag -sot is an abbreviation for -sop -sohb -sosb.
2776
2777           The flag -sobb is an abbreviation for -bbvt=2 -bbvtl='*'.  This
2778           will case a cascade of opening block braces to appear on a single
2779           line, although this an uncommon occurrence except in test scripts.
2780
2781       -sct,  --stack-closing-tokens and related flags
2782           The -sct flag tells perltidy to "stack" closing tokens when
2783           possible to avoid lines with isolated closing tokens.
2784
2785           For example:
2786
2787               # default
2788               $opt_c = Text::CSV_XS->new(
2789                   {
2790                       binary       => 1,
2791                       sep_char     => $opt_c,
2792                       always_quote => 1,
2793                   }
2794               );
2795
2796               # -sct
2797               $opt_c = Text::CSV_XS->new(
2798                   {
2799                       binary       => 1,
2800                       sep_char     => $opt_c,
2801                       always_quote => 1,
2802                   } );
2803
2804           The -sct flag is somewhat similar to the -vtc flags, and in some
2805           cases it can give a similar result.  The difference is that the
2806           -vtc flags try to avoid lines with leading opening tokens by
2807           "hiding" them at the end of a previous line, whereas the -sct flag
2808           merely tries to reduce the number of lines with isolated closing
2809           tokens by stacking them but does not try to hide them.  For
2810           example:
2811
2812               # -vtc=2
2813               $opt_c = Text::CSV_XS->new(
2814                   {
2815                       binary       => 1,
2816                       sep_char     => $opt_c,
2817                       always_quote => 1, } );
2818
2819           For detailed control of the stacking of individual closing tokens
2820           the following controls can be used:
2821
2822             -scp  or --stack-closing-paren
2823             -schb or --stack-closing-hash-brace
2824             -scsb or --stack-closing-square-bracket
2825             -scbb or --stack-closing-block-brace
2826
2827           The flag -sct is an abbreviation for stacking the non-block closing
2828           tokens, -scp -schb -scsb.
2829
2830           Stacking of closing block braces, -scbb, causes a cascade of
2831           isolated closing block braces to be combined into a single line as
2832           in the following example:
2833
2834               # -scbb:
2835               for $w1 (@w1) {
2836                   for $w2 (@w2) {
2837                       for $w3 (@w3) {
2838                           for $w4 (@w4) {
2839                               push( @lines, "$w1 $w2 $w3 $w4\n" );
2840                           } } } }
2841
2842           To simplify input even further for the case in which both opening
2843           and closing non-block containers are stacked, the flag -sac or
2844           --stack-all-containers is an abbreviation for -sot -sct.
2845
2846           Please note that if both opening and closing tokens are to be
2847           stacked, then the newer flag -weld-nested-containers may be
2848           preferable because it insures that stacking is always done
2849           symmetrically.  It also removes an extra level of unnecessary
2850           indentation within welded containers.  It is able to do this
2851           because it works on formatting globally rather than locally, as the
2852           -sot and -sct flags do.
2853
2854       -dnl,  --delete-old-newlines
2855           By default, perltidy first deletes all old line break locations,
2856           and then it looks for good break points to match the desired line
2857           length.  Use -ndnl or  --nodelete-old-newlines to force perltidy to
2858           retain all old line break points.
2859
2860       -anl,  --add-newlines
2861           By default, perltidy will add line breaks when necessary to create
2862           continuations of long lines and to improve the script appearance.
2863           Use -nanl or --noadd-newlines to prevent any new line breaks.
2864
2865           This flag does not prevent perltidy from eliminating existing line
2866           breaks; see --freeze-newlines to completely prevent changes to line
2867           break points.
2868
2869       Controlling whether perltidy breaks before or after operators
2870           Four command line parameters provide some control over whether a
2871           line break should be before or after specific token types.  Two
2872           parameters give detailed control:
2873
2874           -wba=s or --want-break-after=s, and
2875
2876           -wbb=s or --want-break-before=s.
2877
2878           These parameters are each followed by a quoted string, s,
2879           containing a list of token types (separated only by spaces).  No
2880           more than one of each of these parameters should be specified,
2881           because repeating a command-line parameter always overwrites the
2882           previous one before perltidy ever sees it.
2883
2884           By default, perltidy breaks after these token types:
2885             % + - * / x != == >= <= =~ !~ < >  | &
2886             = **= += *= &= <<= &&= -= /= |= >>= ||= //= .= %= ^= x=
2887
2888           And perltidy breaks before these token types by default:
2889             . << >> -> && || //
2890
2891           To illustrate, to cause a break after a concatenation operator,
2892           '.', rather than before it, the command line would be
2893
2894             -wba="."
2895
2896           As another example, the following command would cause a break
2897           before math operators '+', '-', '/', and '*':
2898
2899             -wbb="+ - / *"
2900
2901           These commands should work well for most of the token types that
2902           perltidy uses (use --dump-token-types for a list).  Also try the -D
2903           flag on a short snippet of code and look at the .DEBUG file to see
2904           the tokenization.  However, for a few token types there may be
2905           conflicts with hardwired logic which cause unexpected results.  One
2906           example is curly braces, which should be controlled with the
2907           parameter bl provided for that purpose.
2908
2909           WARNING Be sure to put these tokens in quotes to avoid having them
2910           misinterpreted by your command shell.
2911
2912           Two additional parameters are available which, though they provide
2913           no further capability, can simplify input are:
2914
2915           -baao or --break-after-all-operators,
2916
2917           -bbao or --break-before-all-operators.
2918
2919           The -baao sets the default to be to break after all of the
2920           following operators:
2921
2922               % + - * / x != == >= <= =~ !~ < > | &
2923               = **= += *= &= <<= &&= -= /= |= >>= ||= //= .= %= ^= x=
2924               . : ? && || and or err xor
2925
2926           and the -bbao flag sets the default to break before all of these
2927           operators.  These can be used to define an initial break preference
2928           which can be fine-tuned with the -wba and -wbb flags.  For example,
2929           to break before all operators except an = one could use --bbao
2930           -wba='=' rather than listing every single perl operator except = on
2931           a -wbb flag.
2932
2933   Controlling List Formatting
2934       Perltidy attempts to format lists of comma-separated values in tables
2935       which look good.  Its default algorithms usually work well, but
2936       sometimes they don't.  In this case, there are several methods
2937       available to control list formatting.
2938
2939       A very simple way to prevent perltidy from changing the line breaks
2940       within a comma-separated list of values is to insert a blank line,
2941       comment, or side-comment anywhere between the opening and closing
2942       parens (or braces or brackets).   This causes perltidy to skip over its
2943       list formatting logic.  (The reason is that any of these items put a
2944       constraint on line breaks, and perltidy needs complete control over
2945       line breaks within a container to adjust a list layout).  For example,
2946       let us consider
2947
2948           my @list = (1,
2949                       1, 1,
2950                       1, 2, 1,
2951                       1, 3, 3, 1,
2952                       1, 4, 6, 4, 1,);
2953
2954       The default formatting, which allows a maximum line length of 80, will
2955       flatten this down to one line:
2956
2957           # perltidy (default)
2958           my @list = ( 1, 1, 1, 1, 2, 1, 1, 3, 3, 1, 1, 4, 6, 4, 1, );
2959
2960       This formatting loses important information.  If we place a side
2961       comment on one of the lines, for example, we get the following result
2962       with with default formatting parameters:
2963
2964           my @list = (
2965               1,    # a side comment, comment, or blank keeps list intact
2966               1, 1,
2967               1, 2, 1,
2968               1, 3, 3, 1,
2969               1, 4, 6, 4, 1,
2970           );
2971
2972       We could achieve the same result with a blank line or full comment
2973       anywhere between the opening and closing parens.
2974
2975       For another possibility see the -fs flag in "Skipping Selected Sections
2976       of Code".
2977
2978       -boc,  --break-at-old-comma-breakpoints
2979           The -boc flag is another way to prevent comma-separated lists from
2980           being reformatted.  Using -boc on the above example, plus
2981           additional flags to retain the original style, yields
2982
2983               # perltidy -boc -lp -pt=2 -vt=1 -vtc=1
2984               my @list = (1,
2985                           1, 1,
2986                           1, 2, 1,
2987                           1, 3, 3, 1,
2988                           1, 4, 6, 4, 1,);
2989
2990           A disadvantage of this flag is that all tables in the file must
2991           already be nicely formatted.
2992
2993       -mft=n,  --maximum-fields-per-table=n
2994           If the computed number of fields for any table exceeds n, then it
2995           will be reduced to n.  The default value for n is a large number,
2996           40.  While this value should probably be left unchanged as a
2997           general rule, it might be used on a small section of code to force
2998           a list to have a particular number of fields per line, and then
2999           either the -boc flag could be used to retain this formatting, or a
3000           single comment could be introduced somewhere to freeze the
3001           formatting in future applications of perltidy.
3002
3003               # perltidy -mft=2
3004               @month_of_year = (
3005                   'Jan', 'Feb',
3006                   'Mar', 'Apr',
3007                   'May', 'Jun',
3008                   'Jul', 'Aug',
3009                   'Sep', 'Oct',
3010                   'Nov', 'Dec'
3011               );
3012
3013       -cab=n,  --comma-arrow-breakpoints=n
3014           A comma which follows a comma arrow, '=>', is given special
3015           consideration.  In a long list, it is common to break at all such
3016           commas.  This parameter can be used to control how perltidy breaks
3017           at these commas.  (However, it will have no effect if old comma
3018           breaks are being forced because -boc is used).  The possible values
3019           of n are:
3020
3021            n=0 break at all commas after =>
3022            n=1 stable: break at all commas after => if container is open,
3023                EXCEPT FOR one-line containers
3024            n=2 break at all commas after =>, BUT try to form the maximum
3025                one-line container lengths
3026            n=3 do not treat commas after => specially at all
3027            n=4 break everything: like n=0 but ALSO break a short container with
3028                a => not followed by a comma when -vt=0 is used
3029            n=5 stable: like n=1 but ALSO break at open one-line containers when
3030                -vt=0 is used (default)
3031
3032           For example, given the following single line, perltidy by default
3033           will not add any line breaks because it would break the existing
3034           one-line container:
3035
3036               bless { B => $B, Root => $Root } => $package;
3037
3038           Using -cab=0 will force a break after each comma-arrow item:
3039
3040               # perltidy -cab=0:
3041               bless {
3042                   B    => $B,
3043                   Root => $Root
3044               } => $package;
3045
3046           If perltidy is subsequently run with this container broken, then by
3047           default it will break after each '=>' because the container is now
3048           broken.  To reform a one-line container, the parameter -cab=2 could
3049           be used.
3050
3051           The flag -cab=3 can be used to prevent these commas from being
3052           treated specially.  In this case, an item such as "01" => 31 is
3053           treated as a single item in a table.  The number of fields in this
3054           table will be determined by the same rules that are used for any
3055           other table.  Here is an example.
3056
3057               # perltidy -cab=3
3058               my %last_day = (
3059                   "01" => 31, "02" => 29, "03" => 31, "04" => 30,
3060                   "05" => 31, "06" => 30, "07" => 31, "08" => 31,
3061                   "09" => 30, "10" => 31, "11" => 30, "12" => 31
3062               );
3063
3064   Retaining or Ignoring Existing Line Breaks
3065       Several additional parameters are available for controlling the extent
3066       to which line breaks in the input script influence the output script.
3067       In most cases, the default parameter values are set so that, if a
3068       choice is possible, the output style follows the input style.  For
3069       example, if a short logical container is broken in the input script,
3070       then the default behavior is for it to remain broken in the output
3071       script.
3072
3073       Most of the parameters in this section would only be required for a
3074       one-time conversion of a script from short container lengths to longer
3075       container lengths.  The opposite effect, of converting long container
3076       lengths to shorter lengths, can be obtained by temporarily using a
3077       short maximum line length.
3078
3079       -bol,  --break-at-old-logical-breakpoints
3080           By default, if a logical expression is broken at a "&&", "||",
3081           "and", or "or", then the container will remain broken.  Also,
3082           breaks at internal keywords "if" and "unless" will normally be
3083           retained.  To prevent this, and thus form longer lines, use -nbol.
3084
3085           Please note that this flag does not duplicate old logical
3086           breakpoints.  They are merely used as a hint with this flag that a
3087           statement should remain broken.  Without this flag, perltidy will
3088           normally try to combine relatively short expressions into a single
3089           line.
3090
3091           For example, given this snippet:
3092
3093               return unless $cmd = $cmd || ($dot
3094                   && $Last_Shell) || &prompt('|');
3095
3096               # perltidy -bol [default]
3097               return
3098                 unless $cmd = $cmd
3099                 || ( $dot
3100                   && $Last_Shell )
3101                 || &prompt('|');
3102
3103               # perltidy -nbol
3104               return unless $cmd = $cmd || ( $dot && $Last_Shell ) || &prompt('|');
3105
3106       -bom,  --break-at-old-method-breakpoints
3107           By default, a method call arrow "->" is considered a candidate for
3108           a breakpoint, but method chains will fill to the line width before
3109           a break is considered.  With -bom, breaks before the arrow are
3110           preserved, so if you have preformatted a method chain:
3111
3112             my $q = $rs
3113               ->related_resultset('CDs')
3114               ->related_resultset('Tracks')
3115               ->search({
3116                 'track.id' => {-ident => 'none_search.id'},
3117               })->as_query;
3118
3119           It will keep these breaks, rather than become this:
3120
3121             my $q = $rs->related_resultset('CDs')->related_resultset('Tracks')->search({
3122                 'track.id' => {-ident => 'none_search.id'},
3123               })->as_query;
3124
3125           This flag will also look for and keep a 'cuddled' style of calls,
3126           in which lines begin with a closing paren followed by a call arrow,
3127           as in this example:
3128
3129             my $q = $rs->related_resultset(
3130                 'CDs'
3131             )->related_resultset(
3132                 'Tracks'
3133             )->search( {
3134                 'track.id' => { -ident => 'none_search.id' },
3135             } )->as_query;
3136
3137           You may want to include the -weld-nested-containers flag in this
3138           case to keep nested braces and parens together, as in the last
3139           line.
3140
3141       -bos,  --break-at-old-semicolon-breakpoints
3142           Semicolons are normally placed at the end of a statement.  This
3143           means that formatted lines do not normally begin with semicolons.
3144           If the input stream has some lines which begin with semicolons,
3145           these can be retained by setting this flag.  For example, consider
3146           the following two-line input snippet:
3147
3148             $z = sqrt($x**2 + $y**2)
3149             ;
3150
3151           The default formatting will be:
3152
3153             $z = sqrt( $x**2 + $y**2 );
3154
3155           The result using perltidy -bos keeps the isolated semicolon:
3156
3157             $z = sqrt( $x**2 + $y**2 )
3158               ;
3159
3160           The default is not to do this, -nbos.
3161
3162       -bok,  --break-at-old-keyword-breakpoints
3163           By default, perltidy will retain a breakpoint before keywords which
3164           may return lists, such as "sort" and <map>.  This allows chains of
3165           these operators to be displayed one per line.  Use -nbok to prevent
3166           retaining these breakpoints.
3167
3168       -bot,  --break-at-old-ternary-breakpoints
3169           By default, if a conditional (ternary) operator is broken at a ":",
3170           then it will remain broken.  To prevent this, and thereby form
3171           longer lines, use -nbot.
3172
3173       -boa,  --break-at-old-attribute-breakpoints
3174           By default, if an attribute list is broken at a ":" in the source
3175           file, then it will remain broken.  For example, given the following
3176           code, the line breaks at the ':'s will be retained:
3177
3178                               my @field
3179                                 : field
3180                                 : Default(1)
3181                                 : Get('Name' => 'foo') : Set('Name');
3182
3183           If the attributes are on a single line in the source code then they
3184           will remain on a single line if possible.
3185
3186           To prevent this, and thereby always form longer lines, use -nboa.
3187
3188       Keeping old breakpoints at specific token types
3189           Two command line parameters provide detailed control over whether
3190           perltidy should keep an old line break before or after a specific
3191           token type:
3192
3193           -kbb=s or --keep-old-breakpoints-before=s, and
3194
3195           -kba=s or --keep-old-breakpoints-after=s
3196
3197           These parameters are each followed by a quoted string, s,
3198           containing a list of token types (separated only by spaces).  No
3199           more than one of each of these parameters should be specified,
3200           because repeating a command-line parameter always overwrites the
3201           previous one before perltidy ever sees it.
3202
3203           For example, -kbb='=>' means that if an input line begins with a
3204           '=>' then the output script should also have a line break before
3205           that token.
3206
3207           For example, given the script:
3208
3209               method 'foo'
3210                 => [ Int, Int ]
3211                 => sub {
3212                   my ( $self, $x, $y ) = ( shift, @_ );
3213                   ...;
3214                 };
3215
3216               # perltidy [default]
3217               method 'foo' => [ Int, Int ] => sub {
3218                   my ( $self, $x, $y ) = ( shift, @_ );
3219                   ...;
3220               };
3221
3222               # perltidy -kbb='=>'
3223               method 'foo'
3224                 => [ Int, Int ]
3225                 => sub {
3226                   my ( $self, $x, $y ) = ( shift, @_ );
3227                   ...;
3228                 };
3229
3230       -iob,  --ignore-old-breakpoints
3231           Use this flag to tell perltidy to ignore existing line breaks to
3232           the maximum extent possible.  This will tend to produce the longest
3233           possible containers, regardless of type, which do not exceed the
3234           line length limit. But please note that this parameter has priority
3235           over all other parameters requesting that certain old breakpoints
3236           be kept.
3237
3238       -kis,  --keep-interior-semicolons
3239           Use the -kis flag to prevent breaking at a semicolon if there was
3240           no break there in the input file.  Normally perltidy places a
3241           newline after each semicolon which terminates a statement unless
3242           several statements are contained within a one-line brace block.  To
3243           illustrate, consider the following input lines:
3244
3245               dbmclose(%verb_delim); undef %verb_delim;
3246               dbmclose(%expanded); undef %expanded;
3247
3248           The default is to break after each statement, giving
3249
3250               dbmclose(%verb_delim);
3251               undef %verb_delim;
3252               dbmclose(%expanded);
3253               undef %expanded;
3254
3255           With perltidy -kis the multiple statements are retained:
3256
3257               dbmclose(%verb_delim); undef %verb_delim;
3258               dbmclose(%expanded);   undef %expanded;
3259
3260           The statements are still subject to the specified value of maximum-
3261           line-length and will be broken if this maximum is exceeded.
3262
3263   Blank Line Control
3264       Blank lines can improve the readability of a script if they are
3265       carefully placed.  Perltidy has several commands for controlling the
3266       insertion, retention, and removal of blank lines.
3267
3268       -fbl,  --freeze-blank-lines
3269           Set -fbl if you want to the blank lines in your script to remain
3270           exactly as they are.  The rest of the parameters in this section
3271           may then be ignored.  (Note: setting the -fbl flag is equivalent to
3272           setting -mbl=0 and -kbl=2).
3273
3274       -bbc,  --blanks-before-comments
3275           A blank line will be introduced before a full-line comment.  This
3276           is the default.  Use -nbbc or  --noblanks-before-comments to
3277           prevent such blank lines from being introduced.
3278
3279       -blbs=n,  --blank-lines-before-subs=n
3280           The parameter -blbs=n requests that least n blank lines precede a
3281           sub definition which does not follow a comment and which is more
3282           than one-line long.  The default is <-blbs=1>.  BEGIN and END
3283           blocks are included.
3284
3285           The requested number of blanks statement will be inserted
3286           regardless of the value of --maximum-consecutive-blank-lines=n
3287           (-mbl=n) with the exception that if -mbl=0 then no blanks will be
3288           output.
3289
3290           This parameter interacts with the value k of the parameter
3291           --maximum-consecutive-blank-lines=k (-mbl=k) as follows:
3292
3293           1. If -mbl=0 then no blanks will be output.  This allows all blanks
3294           to be suppressed with a single parameter.  Otherwise,
3295
3296           2. If the number of old blank lines in the script is less than n
3297           then additional blanks will be inserted to make the total n
3298           regardless of the value of -mbl=k.
3299
3300           3. If the number of old blank lines in the script equals or exceeds
3301           n then this parameter has no effect, however the total will not
3302           exceed value specified on the -mbl=k flag.
3303
3304       -blbp=n,  --blank-lines-before-packages=n
3305           The parameter -blbp=n requests that least n blank lines precede a
3306           package which does not follow a comment.  The default is -blbp=1.
3307
3308           This parameter interacts with the value k of the parameter
3309           --maximum-consecutive-blank-lines=k (-mbl=k) in the same way as
3310           described for the previous item -blbs=n.
3311
3312       -bbs,  --blanks-before-subs
3313           For compatibility with previous versions, -bbs or
3314           --blanks-before-subs is equivalent to -blbp=1 and -blbs=1.
3315
3316           Likewise, -nbbs or --noblanks-before-subs is equivalent to -blbp=0
3317           and -blbs=0.
3318
3319       -bbb,  --blanks-before-blocks
3320           A blank line will be introduced before blocks of coding delimited
3321           by for, foreach, while, until, and if, unless, in the following
3322           circumstances:
3323
3324           •   The block is not preceded by a comment.
3325
3326           •   The block is not a one-line block.
3327
3328           •   The number of consecutive non-blank lines at the current
3329               indentation depth is at least -lbl (see next section).
3330
3331           This is the default.  The intention of this option is to introduce
3332           some space within dense coding.  This is negated with -nbbb or
3333           --noblanks-before-blocks.
3334
3335       -lbl=n --long-block-line-count=n
3336           This controls how often perltidy is allowed to add blank lines
3337           before certain block types (see previous section).  The default is
3338           8.  Entering a value of 0 is equivalent to entering a very large
3339           number.
3340
3341       -blao=i or --blank-lines-after-opening-block=i
3342           This control places a minimum of i blank lines after a line which
3343           ends with an opening block brace of a specified type.  By default,
3344           this only applies to the block of a named sub, but this can be
3345           changed (see -blaol below).  The default is not to do this (i=0).
3346
3347           Please see the note below on using the -blao and -blbc options.
3348
3349       -blbc=i or --blank-lines-before-closing-block=i
3350           This control places a minimum of i blank lines before a line which
3351           begins with a closing block brace of a specified type.  By default,
3352           this only applies to the block of a named sub, but this can be
3353           changed (see -blbcl below).  The default is not to do this (i=0).
3354
3355       -blaol=s or --blank-lines-after-opening-block-list=s
3356           The parameter s is a list of block type keywords to which the flag
3357           -blao should apply.  The section "Specifying Block Types" explains
3358           how to list block types.
3359
3360       -blbcl=s or --blank-lines-before-closing-block-list=s
3361           This parameter is a list of block type keywords to which the flag
3362           -blbc should apply.  The section "Specifying Block Types" explains
3363           how to list block types.
3364
3365       Note on using the -blao and -blbc options.
3366           These blank line controls introduce a certain minimum number of
3367           blank lines in the text, but the final number of blank lines may be
3368           greater, depending on values of the other blank line controls and
3369           the number of old blank lines.  A consequence is that introducing
3370           blank lines with these and other controls cannot be exactly undone,
3371           so some experimentation with these controls is recommended before
3372           using them.
3373
3374           For example, suppose that for some reason we decide to introduce
3375           one blank space at the beginning and ending of all blocks.  We
3376           could do this using
3377
3378             perltidy -blao=2 -blbc=2 -blaol='*' -blbcl='*' filename
3379
3380           Now suppose the script continues to be developed, but at some later
3381           date we decide we don't want these spaces after all. we might
3382           expect that running with the flags -blao=0 and -blbc=0 will undo
3383           them.  However, by default perltidy retains single blank lines, so
3384           the blank lines remain.
3385
3386           We can easily fix this by telling perltidy to ignore old blank
3387           lines by including the added parameter -kbl=0 and rerunning. Then
3388           the unwanted blank lines will be gone.  However, this will cause
3389           all old blank lines to be ignored, perhaps even some that were
3390           added by hand to improve formatting. So please be cautious when
3391           using these parameters.
3392
3393       -mbl=n --maximum-consecutive-blank-lines=n
3394           This parameter specifies the maximum number of consecutive blank
3395           lines which will be output within code sections of a script.  The
3396           default is n=1.  If the input file has more than n consecutive
3397           blank lines, the number will be reduced to n except as noted above
3398           for the -blbp and -blbs parameters.  If n=0 then no blank lines
3399           will be output (unless all old blank lines are retained with the
3400           -kbl=2 flag of the next section).
3401
3402           This flag obviously does not apply to pod sections, here-documents,
3403           and quotes.
3404
3405       -kbl=n,  --keep-old-blank-lines=n
3406           The -kbl=n flag gives you control over how your existing blank
3407           lines are treated.
3408
3409           The possible values of n are:
3410
3411            n=0 ignore all old blank lines
3412            n=1 stable: keep old blanks, but limited by the value of the B<-mbl=n> flag
3413            n=2 keep all old blank lines, regardless of the value of the B<-mbl=n> flag
3414
3415           The default is n=1.
3416
3417       -sob,  --swallow-optional-blank-lines
3418           This is equivalent to kbl=0 and is included for compatibility with
3419           previous versions.
3420
3421       -nsob,  --noswallow-optional-blank-lines
3422           This is equivalent to kbl=1 and is included for compatibility with
3423           previous versions.
3424
3425       Controls for blank lines around lines of consecutive keywords
3426
3427       The parameters in this section provide some control over the placement
3428       of blank lines within and around groups of statements beginning with
3429       selected keywords.  These blank lines are called here keyword group
3430       blanks, and all of the parameters begin with --keyword-group-blanks*,
3431       or -kgb* for short.  The default settings do not employ these controls
3432       but they can be enabled with the following parameters:
3433
3434       -kgbl=s or --keyword-group-blanks-list=s; s is a quoted string of
3435       keywords
3436
3437       -kgbs=s or --keyword-group-blanks-size=s; s gives the number of
3438       keywords required to form a group.
3439
3440       -kgbb=n or --keyword-group-blanks-before=n; n = (0, 1, or 2) controls a
3441       leading blank
3442
3443       -kgba=n or --keyword-group-blanks-after=n; n = (0, 1, or 2) controls a
3444       trailing blank
3445
3446       -kgbi or --keyword-group-blanks-inside is a switch for adding blanks
3447       between subgroups
3448
3449       -kgbd or --keyword-group-blanks-delete is a switch for removing initial
3450       blank lines between keywords
3451
3452       -kgbr=n or --keyword-group-blanks-repeat-count=n can limit the number
3453       of times this logic is applied
3454
3455       In addition, the following abbreviations are available to for
3456       simplified usage:
3457
3458       -kgb or --keyword-group-blanks is short for -kgbb=2 -kgba=2 kgbi
3459
3460       -nkgb or --nokeyword-group-blanks, is short for -kgbb=1 -kgba=1 nkgbi
3461
3462       Before describing the meaning of the parameters in detail let us look
3463       at an example which is formatted with default parameter settings.
3464
3465               print "Entering test 2\n";
3466               use Test;
3467               use Encode qw(from_to encode decode
3468                 encode_utf8 decode_utf8
3469                 find_encoding is_utf8);
3470               use charnames qw(greek);
3471               my @encodings     = grep( /iso-?8859/, Encode::encodings() );
3472               my @character_set = ( '0' .. '9', 'A' .. 'Z', 'a' .. 'z' );
3473               my @source        = qw(ascii iso8859-1 cp1250);
3474               my @destiny       = qw(cp1047 cp37 posix-bc);
3475               my @ebcdic_sets   = qw(cp1047 cp37 posix-bc);
3476               my $str           = join( '', map( chr($_), 0x20 .. 0x7E ) );
3477               return unless ($str);
3478
3479       using perltidy -kgb gives:
3480
3481               print "Entering test 2\n";
3482                                             <----------this blank controlled by -kgbb
3483               use Test;
3484               use Encode qw(from_to encode decode
3485                 encode_utf8 decode_utf8
3486                 find_encoding is_utf8);
3487               use charnames qw(greek);
3488                                             <---------this blank controlled by -kgbi
3489               my @encodings     = grep( /iso-?8859/, Encode::encodings() );
3490               my @character_set = ( '0' .. '9', 'A' .. 'Z', 'a' .. 'z' );
3491               my @source        = qw(ascii iso8859-1 cp1250);
3492               my @destiny       = qw(cp1047 cp37 posix-bc);
3493               my @ebcdic_sets   = qw(cp1047 cp37 posix-bc);
3494               my $str           = join( '', map( chr($_), 0x20 .. 0x7E ) );
3495                                             <----------this blank controlled by -kgba
3496               return unless ($str);
3497
3498       Blank lines have been introduced around the my and use sequences.  What
3499       happened is that the default keyword list includes my and use but not
3500       print and return.  So a continuous sequence of nine my and use
3501       statements was located.  This number exceeds the default threshold of
3502       five, so blanks were placed before and after the entire group.  Then,
3503       since there was also a subsequence of six my lines, a blank line was
3504       introduced to separate them.
3505
3506       Finer control over blank placement can be achieved by using the
3507       individual parameters rather than the -kgb flag.  The individual
3508       controls are as follows.
3509
3510       -kgbl=s or --keyword-group-blanks-list=s, where s is a quoted string,
3511       defines the set of keywords which will be formed into groups.  The
3512       string is a space separated list of keywords.  The default set is
3513       s="use require local our my", but any list of keywords may be used.
3514       Comment lines may also be included in a keyword group, even though they
3515       are not keywords.  To include ordinary block comments, include the
3516       symbol BC. To include static block comments (which normally begin with
3517       '##'), include the symbol SBC.
3518
3519       -kgbs=s or --keyword-group-blanks-size=s, where s is a string
3520       describing the number of consecutive keyword statements forming a
3521       group.  If s is an integer then it is the minimum number required for a
3522       group.  A maximum value may also be given with the format s=min.max,
3523       where min is the minimum number and max is the maximum number, and the
3524       min and max values are separated by one or more dots.  No groups will
3525       be found if the maximum is less than the minimum.  The maximum is
3526       unlimited if not given.  The default is s=5.  Some examples:
3527
3528           s      min   max         number for group
3529           3      3     unlimited   3 or more
3530           1.1    1     1           1
3531           1..3   1     3           1 to 3
3532           1.0    1     0           (no match)
3533
3534       -kgbb=n or --keyword-group-blanks-before=n specifies whether a blank
3535       should appear before the first line of the group, as follows:
3536
3537          n=0 => (delete) an existing blank line will be removed
3538          n=1 => (stable) no change to the input file is made  [DEFAULT]
3539          n=2 => (insert) a blank line is introduced if possible
3540
3541       -kgba=n or --keyword-group-blanks-after=n likewise specifies whether a
3542       blank should appear after the last line of the group, using the same
3543       scheme (0=delete, 1=stable, 2=insert).
3544
3545       -kgbi or --keyword-group-blanks-inside controls the insertion of blank
3546       lines between the first and last statement of the entire group.  If
3547       there is a continuous run of a single statement type with more than the
3548       minimum threshold number (as specified with -kgbs=s) then this switch
3549       causes a blank line be inserted between this subgroup and the others.
3550       In the example above this happened between the use and my statements.
3551
3552       -kgbd or --keyword-group-blanks-delete controls the deletion of any
3553       blank lines that exist in the the group when it is first scanned.  When
3554       statements are initially scanned, any existing blank lines are included
3555       in the collection.  Any such orignial blank lines will be deleted
3556       before any other insertions are made when the parameter -kgbd is set.
3557       The default is not to do this, -nkgbd.
3558
3559       -kgbr=n or --keyword-group-blanks-repeat-count=n specifies n, the
3560       maximum number of times this logic will be applied to any file.  The
3561       special value n=0 is the same as n=infinity which means it will be
3562       applied to an entire script [Default].  A value n=1 could be used to
3563       make it apply just one time for example.  This might be useful for
3564       adjusting just the use statements in the top part of a module for
3565       example.
3566
3567       -kgb or --keyword-group-blanks is an abbreviation equivalent to setting
3568       -kgbb=1 -kgba=1 -kgbi.  This turns on keyword group formatting with a
3569       set of default values.
3570
3571       -nkgb or --nokeyword-group-blanks is equivalent to -kgbb=0 -kgba nkgbi.
3572       This flag turns off keyword group blank lines and is the default
3573       setting.
3574
3575       Here are a few notes about the functioning of this technique.
3576
3577       •   These parameters are probably more useful as part of a major code
3578           reformatting operation rather than as a routine formatting
3579           operation.
3580
3581           In particular, note that deleting old blank lines with -kgbd is an
3582           irreversible operation so it should be applied with care.  Existing
3583           blank lines may be serving an important role in controlling
3584           vertical alignment.
3585
3586       •   Conflicts which arise among these kgb* parameters and other blank
3587           line controls are generally resolved by producing the maximum
3588           number of blank lines implied by any parameter.
3589
3590           For example, if the flags --freeze-blank-lines, or
3591           --keep-old-blank-lines=2, are set, then they have priority over any
3592           blank line deletion implied by the -kgb flags of this section, so
3593           no blank lines will be deleted.
3594
3595           For another example, if a keyword group ends at a sub and the flag
3596           kgba=0 requests no blank line there, but we also have
3597           --blank-lines-before-subs=2, then two blank lines will still be
3598           introduced before the sub.
3599
3600       •   The introduction of blank lines does not occur if it would conflict
3601           with other input controls or code validity. For example, a blank
3602           line will not be placed within a here-doc or within a section of
3603           code marked with format skipping comments.  And in general, a blank
3604           line will only be introduced at the end of a group if the next
3605           statement is a line of code.
3606
3607       •   The count which is used to determine the group size is not the
3608           number of lines but rather the total number of keywords which are
3609           found.  Individual statements with a certain leading keyword may
3610           continue on multiple lines, but if any of these lines is nested
3611           more than one level deep then that group will be ended.
3612
3613       •   The search for groups of lines with similar leading keywords is
3614           based on the input source, not the final formatted source.
3615           Consequently, if the source code is badly formatted, it would be
3616           best to make a first formatting pass without these options.
3617
3618   Styles
3619       A style refers to a convenient collection of existing parameters.
3620
3621       -gnu, --gnu-style
3622           -gnu gives an approximation to the GNU Coding Standards (which do
3623           not apply to perl) as they are sometimes implemented.  At present,
3624           this style overrides the default style with the following
3625           parameters:
3626
3627               -lp -bl -noll -pt=2 -bt=2 -sbt=2 -icp
3628
3629       -pbp, --perl-best-practices
3630           -pbp is an abbreviation for the parameters in the book Perl Best
3631           Practices by Damian Conway:
3632
3633               -l=78 -i=4 -ci=4 -st -se -vt=2 -cti=0 -pt=1 -bt=1 -sbt=1 -bbt=1 -nsfs -nolq
3634               -wbb="% + - * / x != == >= <= =~ !~ < > | & =
3635                     **= += *= &= <<= &&= -= /= |= >>= ||= //= .= %= ^= x="
3636
3637           Please note that this parameter set includes -st and -se flags,
3638           which make perltidy act as a filter on one file only.  These can be
3639           overridden by placing -nst and/or -nse after the -pbp parameter.
3640
3641           Also note that the value of continuation indentation, -ci=4, is
3642           equal to the value of the full indentation, -i=4.  It is
3643           recommended that the either (1) the parameter -ci=2 be used
3644           instead, or the flag -xci be set.  This will help show structure,
3645           particularly when there are ternary statements. The following
3646           snippet illustrates these options.
3647
3648               # perltidy -pbp
3649               $self->{_text} = (
3650                    !$section        ? ''
3651                   : $type eq 'item' ? "the $section entry"
3652                   :                   "the section on $section"
3653                   )
3654                   . (
3655                   $page
3656                   ? ( $section ? ' in ' : '' ) . "the $page$page_ext manpage"
3657                   : ' elsewhere in this document'
3658                   );
3659
3660               # perltidy -pbp -ci=2
3661               $self->{_text} = (
3662                    !$section        ? ''
3663                   : $type eq 'item' ? "the $section entry"
3664                   :                   "the section on $section"
3665                 )
3666                 . (
3667                   $page
3668                   ? ( $section ? ' in ' : '' ) . "the $page$page_ext manpage"
3669                   : ' elsewhere in this document'
3670                 );
3671
3672               # perltidy -pbp -xci
3673               $self->{_text} = (
3674                    !$section        ? ''
3675                   : $type eq 'item' ? "the $section entry"
3676                   :                   "the section on $section"
3677                   )
3678                   . ( $page
3679                       ? ( $section ? ' in ' : '' ) . "the $page$page_ext manpage"
3680                       : ' elsewhere in this document'
3681                   );
3682
3683           The -xci flag was developed after the -pbp parameters were
3684           published so you need to include it separately.
3685
3686       One-line blocks
3687           There are a few points to note regarding one-line blocks.  A one-
3688           line block is something like this,
3689
3690           where the contents within the curly braces is short enough to fit
3691           on a single line.
3692
3693           With few exceptions, perltidy retains existing one-line blocks, if
3694           it is possible within the line-length constraint, but it does not
3695           attempt to form new ones.  In other words, perltidy will try to
3696           follow the one-line block style of the input file.
3697
3698           If an existing one-line block is longer than the maximum line
3699           length, however, it will be broken into multiple lines.  When this
3700           happens, perltidy checks for and adds any optional terminating
3701           semicolon (unless the -nasc option is used) if the block is a code
3702           block.
3703
3704           The main exception is that perltidy will attempt to form new one-
3705           line blocks following the keywords "map", "eval", and "sort",
3706           because these code blocks are often small and most clearly
3707           displayed in a single line.
3708
3709           One-line block rules can conflict with the cuddled-else option.
3710           When the cuddled-else option is used, perltidy retains existing
3711           one-line blocks, even if they do not obey cuddled-else formatting.
3712
3713           Occasionally, when one-line blocks get broken because they exceed
3714           the available line length, the formatting will violate the
3715           requested brace style.  If this happens, reformatting the script a
3716           second time should correct the problem.
3717
3718           Sometimes it might be desirable to convert a script to have one-
3719           line blocks whenever possible.  Although there is currently no flag
3720           for this, a simple workaround is to execute perltidy twice, once
3721           with the flag -noadd-newlines and then once again with normal
3722           parameters, like this:
3723
3724                cat infile | perltidy -nanl | perltidy >outfile
3725
3726           When executed on this snippet
3727
3728               if ( $? == -1 ) {
3729                   die "failed to execute: $!\n";
3730               }
3731               if ( $? == -1 ) {
3732                   print "Had enough.\n";
3733                   die "failed to execute: $!\n";
3734               }
3735
3736           the result is
3737
3738               if ( $? == -1 ) { die "failed to execute: $!\n"; }
3739               if ( $? == -1 ) {
3740                   print "Had enough.\n";
3741                   die "failed to execute: $!\n";
3742               }
3743
3744           This shows that blocks with a single statement become one-line
3745           blocks.
3746
3747       -olbs=n, --one-line-block-semicolons=n
3748           This flag controls the placement of semicolons at the end of one-
3749           line blocks.  Semicolons are optional before a closing block brace,
3750           and frequently they are omitted at the end of a one-line block
3751           containing just a single statement.  By default, perltidy follows
3752           the input file regarding these semicolons, but this behavior can be
3753           controlled by this flag.  The values of n are:
3754
3755             n=0 remove terminal semicolons in one-line blocks having a single statement
3756             n=1 stable; keep input file placement of terminal semicolons [DEFAULT ]
3757             n=2 add terminal semicolons in all one-line blocks
3758
3759           Note that the n=2 option has no effect if adding semicolons is
3760           prohibited with the -nasc flag.  Also not that while n=2 adds
3761           missing semicolons to all one-line blocks, regardless of
3762           complexity, the n=0 option only removes ending semicolons which
3763           terminate one-line blocks containing just one semicolon.  So these
3764           two options are not exact inverses.
3765
3766       -olbn=n, --one-line-block-nesting=n
3767           Nested one-line blocks are lines with code blocks which themselves
3768           contain code blocks.  For example, the following line is a nested
3769           one-line block.
3770
3771                    foreach (@list) { if ($_ eq $asked_for) { last } ++$found }
3772
3773           The default behavior is to break such lines into multiple lines,
3774           but this behavior can be controlled with this flag.  The values of
3775           n are:
3776
3777             n=0 break nested one-line blocks into multiple lines [DEFAULT]
3778             n=1 stable: keep existing nested-one line blocks intact
3779
3780           For the above example, the default formatting (-olbn=0) is
3781
3782               foreach (@list) {
3783                   if ( $_ eq $asked_for ) { last }
3784                   ++$found;
3785               }
3786
3787           If the parameter -olbn=1 is given, then the line will be left
3788           intact if it is a single line in the source, or it will be broken
3789           into multiple lines if it is broken in multiple lines in the
3790           source.
3791
3792   Controlling Vertical Alignment
3793       Vertical alignment refers to lining up certain symbols in a list of
3794       consecutive similar lines to improve readability.  For example, the
3795       "fat commas" are aligned in the following statement:
3796
3797               $data = $pkg->new(
3798                   PeerAddr => join( ".", @port[ 0 .. 3 ] ),
3799                   PeerPort => $port[4] * 256 + $port[5],
3800                   Proto    => 'tcp'
3801               );
3802
3803       Vertical alignment can be completely turned off using -novalign, a flag
3804       mainly intended for debugging.  However, vertical alignment can be
3805       forced to stop and restart by selectively introducing blank lines.  For
3806       example, a blank has been inserted in the following code to keep
3807       somewhat similar things aligned.
3808
3809           %option_range = (
3810               'format'             => [ 'tidy', 'html', 'user' ],
3811               'output-line-ending' => [ 'dos',  'win',  'mac', 'unix' ],
3812               'character-encoding' => [ 'none', 'utf8' ],
3813
3814               'block-brace-tightness'    => [ 0, 2 ],
3815               'brace-tightness'          => [ 0, 2 ],
3816               'paren-tightness'          => [ 0, 2 ],
3817               'square-bracket-tightness' => [ 0, 2 ],
3818           );
3819
3820       Vertical alignment is implemented by locally increasing an existing
3821       blank space to produce alignment with an adjacent line.  It cannot
3822       occur if there is no blank space to increase.  So if a particular space
3823       is removed by one of the existing controls then vertical alignment
3824       cannot occur. Likewise, if a space is added with one of the controls,
3825       then vertical alignment might occur.
3826
3827       For example,
3828
3829               # perltidy -nwls='=>'
3830               $data = $pkg->new(
3831                   PeerAddr=> join( ".", @port[ 0 .. 3 ] ),
3832                   PeerPort=> $port[4] * 256 + $port[5],
3833                   Proto=> 'tcp'
3834               );
3835
3836   Other Controls
3837       Deleting selected text
3838           Perltidy can selectively delete comments and/or pod documentation.
3839           The command -dac or  --delete-all-comments will delete all comments
3840           and all pod documentation, leaving just code and any leading system
3841           control lines.
3842
3843           The command -dp or --delete-pod will remove all pod documentation
3844           (but not comments).
3845
3846           Two commands which remove comments (but not pod) are: -dbc or
3847           --delete-block-comments and -dsc or  --delete-side-comments.
3848           (Hanging side comments will be deleted with side comments here.)
3849
3850           The negatives of these commands also work, and are the defaults.
3851           When block comments are deleted, any leading 'hash-bang' will be
3852           retained.  Also, if the -x flag is used, any system commands before
3853           a leading hash-bang will be retained (even if they are in the form
3854           of comments).
3855
3856       Writing selected text to a file
3857           When perltidy writes a formatted text file, it has the ability to
3858           also send selected text to a file with a .TEE extension.  This text
3859           can include comments and pod documentation.
3860
3861           The command -tac or  --tee-all-comments will write all comments and
3862           all pod documentation.
3863
3864           The command -tp or --tee-pod will write all pod documentation (but
3865           not comments).
3866
3867           The commands which write comments (but not pod) are: -tbc or
3868           --tee-block-comments and -tsc or  --tee-side-comments.  (Hanging
3869           side comments will be written with side comments here.)
3870
3871           The negatives of these commands also work, and are the defaults.
3872
3873       Using a .perltidyrc command file
3874           If you use perltidy frequently, you probably won't be happy until
3875           you create a .perltidyrc file to avoid typing commonly-used
3876           parameters.  Perltidy will first look in your current directory for
3877           a command file named .perltidyrc.  If it does not find one, it will
3878           continue looking for one in other standard locations.
3879
3880           These other locations are system-dependent, and may be displayed
3881           with the command "perltidy -dpro".  Under Unix systems, it will
3882           first look for an environment variable PERLTIDY.  Then it will look
3883           for a .perltidyrc file in the home directory, and then for a
3884           system-wide file /usr/local/etc/perltidyrc, and then it will look
3885           for /etc/perltidyrc.  Note that these last two system-wide files do
3886           not have a leading dot.  Further system-dependent information will
3887           be found in the INSTALL file distributed with perltidy.
3888
3889           Under Windows, perltidy will also search for a configuration file
3890           named perltidy.ini since Windows does not allow files with a
3891           leading period (.).  Use "perltidy -dpro" to see the possible
3892           locations for your system.  An example might be C:\Documents and
3893           Settings\All Users\perltidy.ini.
3894
3895           Another option is the use of the PERLTIDY environment variable.
3896           The method for setting environment variables depends upon the
3897           version of Windows that you are using.  Instructions for Windows 95
3898           and later versions can be found here:
3899
3900           http://www.netmanage.com/000/20021101_005_tcm21-6336.pdf
3901
3902           Under Windows NT / 2000 / XP the PERLTIDY environment variable can
3903           be placed in either the user section or the system section.  The
3904           later makes the configuration file common to all users on the
3905           machine.  Be sure to enter the full path of the configuration file
3906           in the value of the environment variable.  Ex.
3907           PERLTIDY=C:\Documents and Settings\perltidy.ini
3908
3909           The configuration file is free format, and simply a list of
3910           parameters, just as they would be entered on a command line.  Any
3911           number of lines may be used, with any number of parameters per
3912           line, although it may be easiest to read with one parameter per
3913           line.  Comment text begins with a #, and there must also be a space
3914           before the # for side comments.  It is a good idea to put complex
3915           parameters in either single or double quotes.
3916
3917           Here is an example of a .perltidyrc file:
3918
3919             # This is a simple of a .perltidyrc configuration file
3920             # This implements a highly spaced style
3921             -se    # errors to standard error output
3922             -w     # show all warnings
3923             -bl    # braces on new lines
3924             -pt=0  # parens not tight at all
3925             -bt=0  # braces not tight
3926             -sbt=0 # square brackets not tight
3927
3928           The parameters in the .perltidyrc file are installed first, so any
3929           parameters given on the command line will have priority over them.
3930
3931           To avoid confusion, perltidy ignores any command in the .perltidyrc
3932           file which would cause some kind of dump and an exit.  These are:
3933
3934            -h -v -ddf -dln -dop -dsn -dtt -dwls -dwrs -ss
3935
3936           There are several options may be helpful in debugging a .perltidyrc
3937           file:
3938
3939           •   A very helpful command is --dump-profile or -dpro.  It writes a
3940               list of all configuration filenames tested to standard output,
3941               and if a file is found, it dumps the content to standard output
3942               before exiting.  So, to find out where perltidy looks for its
3943               configuration files, and which one if any it selects, just
3944               enter
3945
3946                 perltidy -dpro
3947
3948           •   It may be simplest to develop and test configuration files with
3949               alternative names, and invoke them with -pro=filename on the
3950               command line.  Then rename the desired file to .perltidyrc when
3951               finished.
3952
3953           •   The parameters in the .perltidyrc file can be switched off with
3954               the -npro option.
3955
3956           •   The commands --dump-options, --dump-defaults,
3957               --dump-long-names, and --dump-short-names, all described below,
3958               may all be helpful.
3959
3960       Creating a new abbreviation
3961           A special notation is available for use in a .perltidyrc file for
3962           creating an abbreviation for a group of options.  This can be used
3963           to create a shorthand for one or more styles which are frequently,
3964           but not always, used.  The notation is to group the options within
3965           curly braces which are preceded by the name of the alias (without
3966           leading dashes), like this:
3967
3968                   newword {
3969                   -opt1
3970                   -opt2
3971                   }
3972
3973           where newword is the abbreviation, and opt1, etc, are existing
3974           parameters or other abbreviations.  The main syntax requirement is
3975           that the new abbreviation along with its opening curly brace must
3976           begin on a new line.  Space before and after the curly braces is
3977           optional.  For a specific example, the following line
3978
3979                   airy {-bl -pt=0 -bt=0 -sbt=0}
3980
3981           could be placed in a .perltidyrc file, and then invoked at will
3982           with
3983
3984                   perltidy -airy somefile.pl
3985
3986           (Either "-airy" or "--airy" may be used).
3987
3988       Skipping leading non-perl commands with -x or --look-for-hash-bang
3989           If your script has leading lines of system commands or other text
3990           which are not valid perl code, and which are separated from the
3991           start of the perl code by a "hash-bang" line, ( a line of the form
3992           "#!...perl" ), you must use the -x flag to tell perltidy not to
3993           parse and format any lines before the "hash-bang" line.  This
3994           option also invokes perl with a -x flag when checking the syntax.
3995           This option was originally added to allow perltidy to parse
3996           interactive VMS scripts, but it should be used for any script which
3997           is normally invoked with "perl -x".
3998
3999           Please note: do not use this flag unless you are sure your script
4000           needs it.  Parsing errors can occur if it does not have a hash-
4001           bang, or, for example, if the actual first hash-bang is in a here-
4002           doc. In that case a parsing error will occur because the
4003           tokenization will begin in the middle of the here-doc.
4004
4005       Making a file unreadable
4006           The goal of perltidy is to improve the readability of files, but
4007           there are two commands which have the opposite effect, --mangle and
4008           --extrude.  They are actually merely aliases for combinations of
4009           other parameters.  Both of these strip all possible whitespace, but
4010           leave comments and pod documents, so that they are essentially
4011           reversible.  The difference between these is that --mangle puts the
4012           fewest possible line breaks in a script while --extrude puts the
4013           maximum possible.  Note that these options do not provided any
4014           meaningful obfuscation, because perltidy can be used to reformat
4015           the files.  They were originally developed to help test the
4016           tokenization logic of perltidy, but they have other uses.  One use
4017           for --mangle is the following:
4018
4019             perltidy --mangle myfile.pl -st | perltidy -o myfile.pl.new
4020
4021           This will form the maximum possible number of one-line blocks (see
4022           next section), and can sometimes help clean up a badly formatted
4023           script.
4024
4025           A similar technique can be used with --extrude instead of --mangle
4026           to make the minimum number of one-line blocks.
4027
4028           Another use for --mangle is to combine it with -dac to reduce the
4029           file size of a perl script.
4030
4031       Debugging
4032           The following flags are available for debugging:
4033
4034           --dump-cuddled-block-list or -dcbl will dump to standard output the
4035           internal hash of cuddled block types created by a
4036           -cuddled-block-list input string.
4037
4038           --dump-defaults or -ddf will write the default option set to
4039           standard output and quit
4040
4041           --dump-profile or -dpro  will write the name of the current
4042           configuration file and its contents to standard output and quit.
4043
4044           --dump-options or -dop  will write current option set to standard
4045           output and quit.
4046
4047           --dump-long-names or -dln  will write all command line long names
4048           (passed to Get_options) to standard output and quit.
4049
4050           --dump-short-names  or -dsn will write all command line short names
4051           to standard output and quit.
4052
4053           --dump-token-types or -dtt  will write a list of all token types to
4054           standard output and quit.
4055
4056           --dump-want-left-space or -dwls  will write the hash
4057           %want_left_space to standard output and quit.  See the section on
4058           controlling whitespace around tokens.
4059
4060           --dump-want-right-space or -dwrs  will write the hash
4061           %want_right_space to standard output and quit.  See the section on
4062           controlling whitespace around tokens.
4063
4064           --no-memoize or -nmem  will turn of memoizing.  Memoization can
4065           reduce run time when running perltidy repeatedly in a single
4066           process.  It is on by default but can be deactivated for testing
4067           with -nmem.
4068
4069           --no-timestamp or -nts will eliminate any time stamps in output
4070           files to prevent differences in dates from causing test
4071           installation scripts to fail. There are just a couple of places
4072           where timestamps normally occur. One is in the headers of html
4073           files, and another is when the -cscw option is selected. The
4074           default is to allow timestamps (--timestamp or -ts).
4075
4076           --file-size-order or -fso will cause files to be processed in order
4077           of increasing size, when multiple files are being processed.  This
4078           is useful during program development, when large numbers of files
4079           with varying sizes are processed, because it can reduce virtual
4080           memory usage.
4081
4082           --maximum-file-size-mb=n or -maxfs=n specifies the maximum file
4083           size in megabytes that perltidy will attempt to format. This
4084           parameter is provided to avoid causing system problems by
4085           accidentally attempting to format an extremely large data file.
4086           Most perl scripts are less than about 2 MB in size. The integer n
4087           has a default value of 10, so perltidy will skip formatting files
4088           which have a size greater than 10 MB.  The command to increase the
4089           limit to 20 MB for example would be
4090
4091             perltidy -maxfs=20
4092
4093           This only applies to files specified by filename on the command
4094           line.
4095
4096           --maximum-level-errors=n or -maxle=n specifies the maximum number
4097           of indentation level errors are allowed before perltidy skips
4098           formatting and just outputs a file verbatim.  The default is n=1.
4099           This means that if the final indentation of a script differs from
4100           the starting indentation by more than 1 levels, the file will be
4101           output verbatim.  To avoid formatting if there are any indentation
4102           level errors use -maxle=0. To skip this check you can either set n
4103           equal to a large number, such as n=100, or set n=-1.
4104
4105           For example, the following script has level error of 3 and will be
4106           output verbatim
4107
4108               Input and default output:
4109               {{{
4110
4111
4112               perltidy -maxle=100
4113               {
4114                   {
4115                       {
4116
4117           --maximum-unexpected-errors=n or -maxue=n specifies the maximum
4118           number of unexpected tokenization errors are allowed before
4119           formatting is skipped and a script is output verbatim.  The
4120           intention is to avoid accidentally formatting a non-perl script,
4121           such as an html file for example.  This check can be turned off by
4122           setting n=0.
4123
4124           A recommended value is n=3.  However, the default is n=0 (skip this
4125           check) to avoid causing problems with scripts which have extended
4126           syntaxes.
4127
4128           -DEBUG  will write a file with extension .DEBUG for each input file
4129           showing the tokenization of all lines of code.
4130
4131       Working with MakeMaker, AutoLoader and SelfLoader
4132           The first $VERSION line of a file which might be eval'd by
4133           MakeMaker is passed through unchanged except for indentation.  Use
4134           --nopass-version-line, or -npvl, to deactivate this feature.
4135
4136           If the AutoLoader module is used, perltidy will continue formatting
4137           code after seeing an __END__ line.  Use --nolook-for-autoloader, or
4138           -nlal, to deactivate this feature.
4139
4140           Likewise, if the SelfLoader module is used, perltidy will continue
4141           formatting code after seeing a __DATA__ line.  Use
4142           --nolook-for-selfloader, or -nlsl, to deactivate this feature.
4143
4144       Working around problems with older version of Perl
4145           Perltidy contains a number of rules which help avoid known
4146           subtleties and problems with older versions of perl, and these
4147           rules always take priority over whatever formatting flags have been
4148           set.  For example, perltidy will usually avoid starting a new line
4149           with a bareword, because this might cause problems if "use strict"
4150           is active.
4151
4152           There is no way to override these rules.
4153

HTML OPTIONS

4155       The -html master switch
4156           The flag -html causes perltidy to write an html file with extension
4157           .html.  So, for example, the following command
4158
4159                   perltidy -html somefile.pl
4160
4161           will produce a syntax-colored html file named somefile.pl.html
4162           which may be viewed with a browser.
4163
4164           Please Note: In this case, perltidy does not do any formatting to
4165           the input file, and it does not write a formatted file with
4166           extension .tdy.  This means that two perltidy runs are required to
4167           create a fully reformatted, html copy of a script.
4168
4169       The -pre flag for code snippets
4170           When the -pre flag is given, only the pre-formatted section, within
4171           the <PRE> and </PRE> tags, will be output.  This simplifies
4172           inclusion of the output in other files.  The default is to output a
4173           complete web page.
4174
4175       The -nnn flag for line numbering
4176           When the -nnn flag is given, the output lines will be numbered.
4177
4178       The -toc, or --html-table-of-contents flag
4179           By default, a table of contents to packages and subroutines will be
4180           written at the start of html output.  Use -ntoc to prevent this.
4181           This might be useful, for example, for a pod document which
4182           contains a number of unrelated code snippets.  This flag only
4183           influences the code table of contents; it has no effect on any
4184           table of contents produced by pod2html (see next item).
4185
4186       The -pod, or --pod2html flag
4187           There are two options for formatting pod documentation.  The
4188           default is to pass the pod through the Pod::Html module (which
4189           forms the basis of the pod2html utility).  Any code sections are
4190           formatted by perltidy, and the results then merged.  Note: perltidy
4191           creates a temporary file when Pod::Html is used; see "FILES".
4192           Also, Pod::Html creates temporary files for its cache.
4193
4194           NOTE: Perltidy counts the number of "=cut" lines, and either moves
4195           the pod text to the top of the html file if there is one "=cut", or
4196           leaves the pod text in its original order (interleaved with code)
4197           otherwise.
4198
4199           Most of the flags accepted by pod2html may be included in the
4200           perltidy command line, and they will be passed to pod2html.  In
4201           some cases, the flags have a prefix "pod" to emphasize that they
4202           are for the pod2html, and this prefix will be removed before they
4203           are passed to pod2html.  The flags which have the additional "pod"
4204           prefix are:
4205
4206              --[no]podheader --[no]podindex --[no]podrecurse --[no]podquiet
4207              --[no]podverbose --podflush
4208
4209           The flags which are unchanged from their use in pod2html are:
4210
4211              --backlink=s --cachedir=s --htmlroot=s --libpods=s --title=s
4212              --podpath=s --podroot=s
4213
4214           where 's' is an appropriate character string.  Not all of these
4215           flags are available in older versions of Pod::Html.  See your
4216           Pod::Html documentation for more information.
4217
4218           The alternative, indicated with -npod, is not to use Pod::Html, but
4219           rather to format pod text in italics (or whatever the stylesheet
4220           indicates), without special html markup.  This is useful, for
4221           example, if pod is being used as an alternative way to write
4222           comments.
4223
4224       The -frm, or --frames flag
4225           By default, a single html output file is produced.  This can be
4226           changed with the -frm option, which creates a frame holding a table
4227           of contents in the left panel and the source code in the right
4228           side. This simplifies code browsing.  Assume, for example, that the
4229           input file is MyModule.pm.  Then, for default file extension
4230           choices, these three files will be created:
4231
4232            MyModule.pm.html      - the frame
4233            MyModule.pm.toc.html  - the table of contents
4234            MyModule.pm.src.html  - the formatted source code
4235
4236           Obviously this file naming scheme requires that output be directed
4237           to a real file (as opposed to, say, standard output).  If this is
4238           not the case, or if the file extension is unknown, the -frm option
4239           will be ignored.
4240
4241       The -text=s, or --html-toc-extension flag
4242           Use this flag to specify the extra file extension of the table of
4243           contents file when html frames are used.  The default is "toc".
4244           See "Specifying File Extensions".
4245
4246       The -sext=s, or --html-src-extension flag
4247           Use this flag to specify the extra file extension of the content
4248           file when html frames are used.  The default is "src".  See
4249           "Specifying File Extensions".
4250
4251       The -hent, or --html-entities flag
4252           This flag controls the use of Html::Entities for html formatting.
4253           By default, the module Html::Entities is used to encode special
4254           symbols.  This may not be the right thing for some browser/language
4255           combinations.  Use --nohtml-entities or -nhent to prevent this.
4256
4257       Style Sheets
4258           Style sheets make it very convenient to control and adjust the
4259           appearance of html pages.  The default behavior is to write a page
4260           of html with an embedded style sheet.
4261
4262           An alternative to an embedded style sheet is to create a page with
4263           a link to an external style sheet.  This is indicated with the
4264           -css=filename,  where the external style sheet is filename.  The
4265           external style sheet filename will be created if and only if it
4266           does not exist.  This option is useful for controlling multiple
4267           pages from a single style sheet.
4268
4269           To cause perltidy to write a style sheet to standard output and
4270           exit, use the -ss, or --stylesheet, flag.  This is useful if the
4271           style sheet could not be written for some reason, such as if the
4272           -pre flag was used.  Thus, for example,
4273
4274             perltidy -html -ss >mystyle.css
4275
4276           will write a style sheet with the default properties to file
4277           mystyle.css.
4278
4279           The use of style sheets is encouraged, but a web page without a
4280           style sheets can be created with the flag -nss.  Use this option if
4281           you must to be sure that older browsers (roughly speaking, versions
4282           prior to 4.0 of Netscape Navigator and Internet Explorer) can
4283           display the syntax-coloring of the html files.
4284
4285       Controlling HTML properties
4286           Note: It is usually more convenient to accept the default
4287           properties and then edit the stylesheet which is produced.
4288           However, this section shows how to control the properties with
4289           flags to perltidy.
4290
4291           Syntax colors may be changed from their default values by flags of
4292           the either the long form, -html-color-xxxxxx=n, or more
4293           conveniently the short form, -hcx=n, where xxxxxx is one of the
4294           following words, and x is the corresponding abbreviation:
4295
4296                 Token Type             xxxxxx           x
4297                 ----------             --------         --
4298                 comment                comment          c
4299                 number                 numeric          n
4300                 identifier             identifier       i
4301                 bareword, function     bareword         w
4302                 keyword                keyword          k
4303                 quite, pattern         quote            q
4304                 here doc text          here-doc-text    h
4305                 here doc target        here-doc-target  hh
4306                 punctuation            punctuation      pu
4307                 parentheses            paren            p
4308                 structural braces      structure        s
4309                 semicolon              semicolon        sc
4310                 colon                  colon            co
4311                 comma                  comma            cm
4312                 label                  label            j
4313                 sub definition name    subroutine       m
4314                 pod text               pod-text         pd
4315
4316           A default set of colors has been defined, but they may be changed
4317           by providing values to any of the following parameters, where n is
4318           either a 6 digit hex RGB color value or an ascii name for a color,
4319           such as 'red'.
4320
4321           To illustrate, the following command will produce an html file
4322           somefile.pl.html with "aqua" keywords:
4323
4324                   perltidy -html -hck=00ffff somefile.pl
4325
4326           and this should be equivalent for most browsers:
4327
4328                   perltidy -html -hck=aqua somefile.pl
4329
4330           Perltidy merely writes any non-hex names that it sees in the html
4331           file.  The following 16 color names are defined in the HTML 3.2
4332           standard:
4333
4334                   black   => 000000,
4335                   silver  => c0c0c0,
4336                   gray    => 808080,
4337                   white   => ffffff,
4338                   maroon  => 800000,
4339                   red     => ff0000,
4340                   purple  => 800080,
4341                   fuchsia => ff00ff,
4342                   green   => 008000,
4343                   lime    => 00ff00,
4344                   olive   => 808000,
4345                   yellow  => ffff00
4346                   navy    => 000080,
4347                   blue    => 0000ff,
4348                   teal    => 008080,
4349                   aqua    => 00ffff,
4350
4351           Many more names are supported in specific browsers, but it is
4352           safest to use the hex codes for other colors.  Helpful color tables
4353           can be located with an internet search for "HTML color tables".
4354
4355           Besides color, two other character attributes may be set: bold, and
4356           italics.  To set a token type to use bold, use the flag
4357           --html-bold-xxxxxx or -hbx, where xxxxxx or x are the long or short
4358           names from the above table.  Conversely, to set a token type to NOT
4359           use bold, use --nohtml-bold-xxxxxx or -nhbx.
4360
4361           Likewise, to set a token type to use an italic font, use the flag
4362           --html-italic-xxxxxx or -hix, where again xxxxxx or x are the long
4363           or short names from the above table.  And to set a token type to
4364           NOT use italics, use --nohtml-italic-xxxxxx or -nhix.
4365
4366           For example, to use bold braces and lime color, non-bold, italics
4367           keywords the following command would be used:
4368
4369                   perltidy -html -hbs -hck=00FF00 -nhbk -hik somefile.pl
4370
4371           The background color can be specified with
4372           --html-color-background=n, or -hcbg=n for short, where n is a 6
4373           character hex RGB value.  The default color of text is the value
4374           given to punctuation, which is black as a default.
4375
4376           Here are some notes and hints:
4377
4378           1. If you find a preferred set of these parameters, you may want to
4379           create a .perltidyrc file containing them.  See the perltidy man
4380           page for an explanation.
4381
4382           2. Rather than specifying values for these parameters, it is
4383           probably easier to accept the defaults and then edit a style sheet.
4384           The style sheet contains comments which should make this easy.
4385
4386           3. The syntax-colored html files can be very large, so it may be
4387           best to split large files into smaller pieces to improve download
4388           times.
4389

SOME COMMON INPUT CONVENTIONS

4391   Specifying Block Types
4392       Several parameters which refer to code block types may be customized by
4393       also specifying an associated list of block types.  The type of a block
4394       is the name of the keyword which introduces that block, such as if,
4395       else, or sub.  An exception is a labeled block, which has no keyword,
4396       and should be specified with just a colon.  To specify all blocks use
4397       '*'.
4398
4399       The keyword sub indicates a named sub.  For anonymous subs, use the
4400       special keyword asub.
4401
4402       For example, the following parameter specifies "sub", labels, "BEGIN",
4403       and "END" blocks:
4404
4405          -cscl="sub : BEGIN END"
4406
4407       (the meaning of the -cscl parameter is described above.)  Note that
4408       quotes are required around the list of block types because of the
4409       spaces.  For another example, the following list specifies all block
4410       types for vertical tightness:
4411
4412          -bbvtl='*'
4413
4414   Specifying File Extensions
4415       Several parameters allow default file extensions to be overridden.  For
4416       example, a backup file extension may be specified with -bext=ext, where
4417       ext is some new extension.  In order to provides the user some
4418       flexibility, the following convention is used in all cases to decide if
4419       a leading '.' should be used.  If the extension "ext" begins with
4420       "A-Z", "a-z", or "0-9", then it will be appended to the filename with
4421       an intermediate '.' (or perhaps a '_' on VMS systems).  Otherwise, it
4422       will be appended directly.
4423
4424       For example, suppose the file is somefile.pl.  For "-bext=old", a '.'
4425       is added to give somefile.pl.old.  For "-bext=.old", no additional '.'
4426       is added, so again the backup file is somefile.pl.old.  For "-bext=~",
4427       then no dot is added, and the backup file will be somefile.pl~  .
4428

SWITCHES WHICH MAY BE NEGATED

4430       The following list shows all short parameter names which allow a prefix
4431       'n' to produce the negated form:
4432
4433        D      anl    asbl   asc    ast    asu    aws    b      baa    baao
4434        bar    bbao   bbb    bbc    bbs    bl     bli    boa    boc    bok
4435        bol    bom    bos    bot    cblx   ce     conv   csc    cscb   cscw
4436        dac    dbc    dcbl   dcsc   ddf    dln    dnl    dop    dp     dpro
4437        dsc    dsm    dsn    dtt    dwls   dwrs   dws    f      fll    frm
4438        fs     fso    gcs    hbc    hbcm   hbco   hbh    hbhh   hbi    hbj
4439        hbk    hbm    hbn    hbp    hbpd   hbpu   hbq    hbs    hbsc   hbv
4440        hbw    hent   hic    hicm   hico   hih    hihh   hii    hij    hik
4441        him    hin    hip    hipd   hipu   hiq    his    hisc   hiv    hiw
4442        hsc    html   ibc    icb    icp    iob    isbc   iscl   kgb    kgbd
4443        kgbi   kis    lal    log    lop    lp     lsl    mem    nib    ohbr
4444        okw    ola    olc    oll    olq    opr    opt    osbc   osbr   otr
4445        ple    pod    pvl    q      sac    sbc    sbl    scbb   schb   scp
4446        scsb   sct    se     sfp    sfs    skp    sob    sobb   sohb   sop
4447        sosb   sot    ssc    st     sts    t      tac    tbc    toc    tp
4448        tqw    trp    ts     tsc    tso    vmll   w      wn     x      xci
4449        xs
4450
4451       Equivalently, the prefix 'no' or 'no-' on the corresponding long names
4452       may be used.
4453

LIMITATIONS

4455       Parsing Limitations
4456           Perltidy should work properly on most perl scripts.  It does a lot
4457           of self-checking, but still, it is possible that an error could be
4458           introduced and go undetected.  Therefore, it is essential to make
4459           careful backups and to test reformatted scripts.
4460
4461           The main current limitation is that perltidy does not scan modules
4462           included with 'use' statements.  This makes it necessary to guess
4463           the context of any bare words introduced by such modules.  Perltidy
4464           has good guessing algorithms, but they are not infallible.  When it
4465           must guess, it leaves a message in the log file.
4466
4467           If you encounter a bug, please report it.
4468
4469       What perltidy does not parse and format
4470           Perltidy indents but does not reformat comments and "qw" quotes.
4471           Perltidy does not in any way modify the contents of here documents
4472           or quoted text, even if they contain source code.  (You could,
4473           however, reformat them separately).  Perltidy does not format
4474           'format' sections in any way.  And, of course, it does not modify
4475           pod documents.
4476

FILES

4478       Temporary files
4479           Under the -html option with the default --pod2html flag, a
4480           temporary file is required to pass text to Pod::Html.  Unix systems
4481           will try to use the POSIX tmpnam() function.  Otherwise the file
4482           perltidy.TMP will be temporarily created in the current working
4483           directory.
4484
4485       Special files when standard input is used
4486           When standard input is used, the log file, if saved, is
4487           perltidy.LOG, and any errors are written to perltidy.ERR unless the
4488           -se flag is set.  These are saved in the current working directory.
4489
4490       Files overwritten
4491           The following file extensions are used by perltidy, and files with
4492           these extensions may be overwritten or deleted: .ERR, .LOG, .TEE,
4493           and/or .tdy, .html, and .bak, depending on the run type and
4494           settings.
4495
4496       Files extensions limitations
4497           Perltidy does not operate on files for which the run could produce
4498           a file with a duplicated file extension.  These extensions include
4499           .LOG, .ERR, .TEE, and perhaps .tdy and .bak, depending on the run
4500           type.  The purpose of this rule is to prevent generating confusing
4501           filenames such as somefile.tdy.tdy.tdy.
4502

ERROR HANDLING

4504       An exit value of 0, 1, or 2 is returned by perltidy to indicate the
4505       status of the result.
4506
4507       A exit value of 0 indicates that perltidy ran to completion with no
4508       error messages.
4509
4510       A non-zero exit value indicates some kind of problem was detected.
4511
4512       An exit value of 1 indicates that perltidy terminated prematurely,
4513       usually due to some kind of errors in the input parameters.  This can
4514       happen for example if a parameter is misspelled or given an invalid
4515       value.  Error messages in the standard error output will indicate the
4516       cause of any problem.  If perltidy terminates prematurely then no
4517       output files will be produced.
4518
4519       An exit value of 2 indicates that perltidy was able to run to
4520       completion but there there are (1) warning messages in the standard
4521       error output related to parameter errors or problems and/or (2) warning
4522       messages in the perltidy error file(s) relating to possible syntax
4523       errors in one or more of the source script(s) being tidied.  When
4524       multiple files are being processed, an error detected in any single
4525       file will produce this type of exit condition.
4526

SEE ALSO

4528       perlstyle(1), Perl::Tidy(3)
4529

INSTALLATION

4531       The perltidy binary uses the Perl::Tidy module and is installed when
4532       that module is installed.  The module name is case-sensitive.  For
4533       example, the basic command for installing with cpanm is 'cpanm
4534       Perl::Tidy'.
4535

VERSION

4537       This man page documents perltidy version 20210402
4538

BUG REPORTS

4540       A list of current bugs and issues can be found at the CPAN site
4541       <https://rt.cpan.org/Public/Dist/Display.html?Name=Perl-Tidy>
4542
4543       To report a new bug or problem, use the link on this page.
4544
4545       The source code repository is at
4546       <https://github.com/perltidy/perltidy>.
4547
4549       Copyright (c) 2000-2021 by Steve Hancock
4550

LICENSE

4552       This package is free software; you can redistribute it and/or modify it
4553       under the terms of the "GNU General Public License".
4554
4555       Please refer to the file "COPYING" for details.
4556

DISCLAIMER

4558       This package is distributed in the hope that it will be useful, but
4559       WITHOUT ANY WARRANTY; without even the implied warranty of
4560       MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
4561
4562       See the "GNU General Public License" for more details.
4563
4564
4565
4566perl v5.32.1                      2021-04-01                       PERLTIDY(1)
Impressum