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, the output will go to
158           filename.tdy.
159
160       -st,    --standard-output
161           Perltidy must be able to operate on an arbitrarily large number of
162           files in a single run, with each output being directed to a
163           different output file.  Obviously this would conflict with
164           outputting to the single standard output device, so a special flag,
165           -st, is required to request outputting to the standard output.  For
166           example,
167
168             perltidy somefile.pl -st >somefile.new.pl
169
170           This option may only be used if there is just a single input file.
171           The default is -nst or --nostandard-output.
172
173       -se,    --standard-error-output
174           If perltidy detects an error when processing file somefile.pl, its
175           default behavior is to write error messages to file
176           somefile.pl.ERR.  Use -se to cause all error messages to be sent to
177           the standard error output stream instead.  This directive may be
178           negated with -nse.  Thus, you may place -se in a .perltidyrc and
179           override it when desired with -nse on the command line.
180
181       -oext=ext,    --output-file-extension=ext
182           Change the extension of the output file to be ext instead of the
183           default tdy (or html in case the --html option is used).  See
184           "Specifying File Extensions".
185
186       -opath=path,    --output-path=path
187           When perltidy creates a filename for an output file, by default it
188           merely appends an extension to the path and basename of the input
189           file.  This parameter causes the path to be changed to path
190           instead.
191
192           The path should end in a valid path separator character, but
193           perltidy will try to add one if it is missing.
194
195           For example
196
197            perltidy somefile.pl -opath=/tmp/
198
199           will produce /tmp/somefile.pl.tdy.  Otherwise, somefile.pl.tdy will
200           appear in whatever directory contains somefile.pl.
201
202           If the path contains spaces, it should be placed in quotes.
203
204           This parameter will be ignored if output is being directed to
205           standard output, or if it is being specified explicitly with the
206           -o=s parameter.
207
208       -b,    --backup-and-modify-in-place
209           Modify the input file or files in-place and save the original with
210           the extension .bak.  Any existing .bak file will be deleted.  See
211           next item for changing the default backup extension, and for
212           eliminating the backup file altogether.
213
214           A -b flag will be ignored if input is from standard input or goes
215           to standard output, or if the -html flag is set.
216
217           In particular, if you want to use both the -b flag and the -pbp
218           (--perl-best-practices) flag, then you must put a -nst flag after
219           the -pbp flag because it contains a -st flag as one of its
220           components, which means that output will go to the standard output
221           stream.
222
223       -bext=ext,    --backup-file-extension=ext
224           This parameter serves two purposes: (1) to change the extension of
225           the backup file to be something other than the default .bak, and
226           (2) to indicate that no backup file should be saved.
227
228           To change the default extension to something other than .bak see
229           "Specifying File Extensions".
230
231           A backup file of the source is always written, but you can request
232           that it be deleted at the end of processing if there were no
233           errors.  This is risky unless the source code is being maintained
234           with a source code control system.
235
236           To indicate that the backup should be deleted include one forward
237           slash, /, in the extension.  If any text remains after the slash is
238           removed it will be used to define the backup file extension (which
239           is always created and only deleted if there were no errors).
240
241           Here are some examples:
242
243             Parameter           Extension          Backup File Treatment
244             <-bext=bak>         F<.bak>            Keep (same as the default behavior)
245             <-bext='/'>         F<.bak>            Delete if no errors
246             <-bext='/backup'>   F<.backup>         Delete if no errors
247             <-bext='original/'> F<.original>       Delete if no errors
248
249       -w,    --warning-output
250           Setting -w causes any non-critical warning messages to be reported
251           as errors.  These include messages about possible pod problems,
252           possibly bad starting indentation level, and cautions about
253           indirect object usage.  The default, -nw or --nowarning-output, is
254           not to include these warnings.
255
256       -q,    --quiet
257           Deactivate error messages and syntax checking (for running under an
258           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

FORMATTING OPTIONS

333   Basic Options
334       --notidy
335           This flag disables all formatting and causes the input to be copied
336           unchanged to the output except for possible changes in line ending
337           characters and any pre- and post-filters.  This can be useful in
338           conjunction with a hierarchical set of .perltidyrc files to avoid
339           unwanted code tidying.  See also "Skipping Selected Sections of
340           Code" for a way to avoid tidying specific sections of code.
341
342       -i=n,  --indent-columns=n
343           Use n columns per indentation level (default n=4).
344
345       -l=n, --maximum-line-length=n
346           The default maximum line length is n=80 characters.  Perltidy will
347           try to find line break points to keep lines below this length.
348           However, long quotes and side comments may cause lines to exceed
349           this length.  Setting -l=0 is equivalent to setting -l=(a large
350           number).
351
352       -vmll, --variable-maximum-line-length
353           A problem arises using a fixed maximum line length with very deeply
354           nested code and data structures because eventually the amount of
355           leading whitespace used for indicating indentation takes up most or
356           all of the available line width, leaving little or no space for the
357           actual code or data.  One solution is to use a vary long line
358           length.  Another solution is to use the -vmll flag, which basically
359           tells perltidy to ignore leading whitespace when measuring the line
360           length.
361
362           To be precise, when the -vmll parameter is set, the maximum line
363           length of a line of code will be M+L*I, where
364
365                 M is the value of --maximum-line-length=M (-l=M), default 80,
366                 I is the value of --indent-columns=I (-i=I), default 4,
367                 L is the indentation level of the line of code
368
369           When this flag is set, the choice of breakpoints for a block of
370           code should be essentially independent of its nesting depth.
371           However, the absolute line lengths, including leading whitespace,
372           can still be arbitrarily large.  This problem can be avoided by
373           including the next parameter.
374
375           The default is not to do this (-nvmll).
376
377       -wc=n, --whitespace-cycle=n
378           This flag also addresses problems with very deeply nested code and
379           data structures.  When the nesting depth exceeds the value n the
380           leading whitespace will be reduced and start at a depth of 1 again.
381           The result is that blocks of code will shift back to the left
382           rather than moving arbitrarily far to the right.  This occurs
383           cyclically to any depth.
384
385           For example if one level of indentation equals 4 spaces (-i=4, the
386           default), and one uses -wc=15, then if the leading whitespace on a
387           line exceeds about 4*15=60 spaces it will be reduced back to 4*1=4
388           spaces and continue increasing from there.  If the whitespace never
389           exceeds this limit the formatting remains unchanged.
390
391           The combination of -vmll and -wc=n provides a solution to the
392           problem of displaying arbitrarily deep data structures and code in
393           a finite window, although -wc=n may of course be used without
394           -vmll.
395
396           The default is not to use this, which can also be indicated using
397           -wc=0.
398
399       tabs
400           Using tab characters will almost certainly lead to future
401           portability and maintenance problems, so the default and
402           recommendation is not to use them.  For those who prefer tabs,
403           however, there are two different options.
404
405           Except for possibly introducing tab indentation characters, as
406           outlined below, perltidy does not introduce any tab characters into
407           your file, and it removes any tabs from the code (unless requested
408           not to do so with -fws).  If you have any tabs in your comments,
409           quotes, or here-documents, they will remain.
410
411           -et=n,   --entab-leading-whitespace
412               This flag causes each n initial space characters to be replaced
413               by one tab character.  Note that the integer n is completely
414               independent of the integer specified for indentation parameter,
415               -i=n.
416
417           -t,   --tabs
418               This flag causes one leading tab character to be inserted for
419               each level of indentation.  Certain other features are
420               incompatible with this option, and if these options are also
421               given, then a warning message will be issued and this flag will
422               be unset.  One example is the -lp option.
423
424           -dt=n,   --default-tabsize=n
425               If the first line of code passed to perltidy contains leading
426               tabs but no tab scheme is specified for the output stream then
427               perltidy must guess how many spaces correspond to each leading
428               tab.  This number of spaces n corresponding to each leading tab
429               of the input stream may be specified with -dt=n.  The default
430               is n=8.
431
432               This flag has no effect if a tab scheme is specified for the
433               output stream, because then the input stream is assumed to use
434               the same tab scheme and indentation spaces as for the output
435               stream (any other assumption would lead to unstable editing).
436
437       -syn,   --check-syntax
438           This flag is now ignored for safety, but the following
439           documentation has been retained for reference.
440
441           This flag causes perltidy to run "perl -c -T" to check syntax of
442           input and output.  (To change the flags passed to perl, see the
443           next item, -pscf).  The results are written to the .LOG file, which
444           will be saved if an error is detected in the output script.  The
445           output script is not checked if the input script has a syntax
446           error.  Perltidy does its own checking, but this option employs
447           perl to get a "second opinion".
448
449           If perl reports errors in the input file, they will not be reported
450           in the error output unless the --warning-output flag is given.
451
452           The default is NOT to do this type of syntax checking (although
453           perltidy will still do as much self-checking as possible).  The
454           reason is that it causes all code in BEGIN blocks to be executed,
455           for all modules being used, and this opens the door to security
456           issues and infinite loops when running perltidy.
457
458       -pscf=s, -perl-syntax-check-flags=s
459           When perl is invoked to check syntax, the normal flags are "-c -T".
460           In addition, if the -x flag is given to perltidy, then perl will
461           also be passed a -x flag.  It should not normally be necessary to
462           change these flags, but it can be done with the -pscf=s flag.  For
463           example, if the taint flag, "-T", is not wanted, the flag could be
464           set to be just -pscf=-c.
465
466           Perltidy will pass your string to perl with the exception that it
467           will add a -c and -x if appropriate.  The .LOG file will show
468           exactly what flags were passed to perl.
469
470       -xs,   --extended-syntax
471           A problem with formatting Perl code is that some modules can
472           introduce new syntax.  This flag allows perltidy to handle certain
473           common extensions to the standard syntax without complaint.
474
475           For example, without this flag a structure such as the following
476           would generate a syntax error and the braces would not be balanced:
477
478               method deposit( Num $amount) {
479                   $self->balance( $self->balance + $amount );
480               }
481
482           This flag is enabled by default but it can be deactivated with
483           -nxs.  Probably the only reason to deactivate this flag is to
484           generate more diagnostic messages when debugging a script.
485
486       -io,   --indent-only
487           This flag is used to deactivate all whitespace and line break
488           changes within non-blank lines of code.  When it is in effect, the
489           only change to the script will be to the indentation and to the
490           number of blank lines.  And any flags controlling whitespace and
491           newlines will be ignored.  You might want to use this if you are
492           perfectly happy with your whitespace and line breaks, and merely
493           want perltidy to handle the indentation.  (This also speeds up
494           perltidy by well over a factor of two, so it might be useful when
495           perltidy is merely being used to help find a brace error in a large
496           script).
497
498           Setting this flag is equivalent to setting --freeze-newlines and
499           --freeze-whitespace.
500
501           If you also want to keep your existing blank lines exactly as they
502           are, you can add --freeze-blank-lines.
503
504           With this option perltidy is still free to modify the indenting
505           (and outdenting) of code and comments as it normally would.  If you
506           also want to prevent long comment lines from being outdented, you
507           can add either -noll or -l=0.
508
509           Setting this flag will prevent perltidy from doing any special
510           operations on closing side comments.  You may still delete all side
511           comments however when this flag is in effect.
512
513       -enc=s,  --character-encoding=s
514           where s=none or utf8.  This flag tells perltidy the character
515           encoding of both the input and output character streams.  The value
516           utf8 causes the stream to be read and written as UTF-8.  The value
517           none causes the stream to be processed without special encoding
518           assumptions.  At present there is no automatic detection of
519           character encoding (even if there is a 'use utf8' statement in your
520           code) so this flag must be set for streams encoded in UTF-8.
521           Incorrectly setting this parameter can cause data corruption, so
522           please carefully check the output.
523
524           The default is none.
525
526           The abbreviations -utf8 or -UTF8 are equivalent to -enc=utf8.  So
527           to process a file named file.pl which is encoded in UTF-8 you can
528           use:
529
530              perltidy -utf8 file.pl
531
532       -ole=s,  --output-line-ending=s
533           where s="win", "dos", "unix", or "mac".  This flag tells perltidy
534           to output line endings for a specific system.  Normally, perltidy
535           writes files with the line separator character of the host system.
536           The "win" and "dos" flags have an identical result.
537
538       -ple,  --preserve-line-endings
539           This flag tells perltidy to write its output files with the same
540           line endings as the input file, if possible.  It should work for
541           dos, unix, and mac line endings.  It will only work if perltidy
542           input comes from a filename (rather than stdin, for example).  If
543           perltidy has trouble determining the input file line ending, it
544           will revert to the default behavior of using the line ending of the
545           host system.
546
547       -it=n,   --iterations=n
548           This flag causes perltidy to do n complete iterations.  The reason
549           for this flag is that code beautification is an iterative process
550           and in some cases the output from perltidy can be different if it
551           is applied a second time.  For most purposes the default of n=1
552           should be satisfactory.  However n=2 can be useful when a major
553           style change is being made, or when code is being beautified on
554           check-in to a source code control system.  It has been found to be
555           extremely rare for the output to change after 2 iterations.  If a
556           value n is greater than 2 is input then a convergence test will be
557           used to stop the iterations as soon as possible, almost always
558           after 2 iterations.  See the next item for a simplified iteration
559           control.
560
561           This flag has no effect when perltidy is used to generate html.
562
563       -conv,   --converge
564           This flag is equivalent to -it=4 and is included to simplify
565           iteration control.  For all practical purposes one either does or
566           does not want to be sure that the output is converged, and there is
567           no penalty to using a large iteration limit since perltidy will
568           check for convergence and stop iterating as soon as possible.  The
569           default is -nconv (no convergence check).  Using -conv will
570           approximately double run time since normally one extra iteration is
571           required to verify convergence.
572
573   Code Indentation Control
574       -ci=n, --continuation-indentation=n
575           Continuation indentation is extra indentation spaces applied when a
576           long line is broken.  The default is n=2, illustrated here:
577
578            my $level =   # -ci=2
579              ( $max_index_to_go >= 0 ) ? $levels_to_go[0] : $last_output_level;
580
581           The same example, with n=0, is a little harder to read:
582
583            my $level =   # -ci=0
584            ( $max_index_to_go >= 0 ) ? $levels_to_go[0] : $last_output_level;
585
586           The value given to -ci is also used by some commands when a small
587           space is required.  Examples are commands for outdenting labels,
588           -ola, and control keywords, -okw.
589
590           When default values are not used, it is suggested that the value n
591           given with -ci=n be no more than about one-half of the number of
592           spaces assigned to a full indentation level on the -i=n command.
593
594       -sil=n --starting-indentation-level=n
595           By default, perltidy examines the input file and tries to determine
596           the starting indentation level.  While it is often zero, it may not
597           be zero for a code snippet being sent from an editing session.
598
599           To guess the starting indentation level perltidy simply assumes
600           that indentation scheme used to create the code snippet is the same
601           as is being used for the current perltidy process.  This is the
602           only sensible guess that can be made.  It should be correct if this
603           is true, but otherwise it probably won't.  For example, if the
604           input script was written with -i=2 and the current peltidy flags
605           have -i=4, the wrong initial indentation will be guessed for a code
606           snippet which has non-zero initial indentation. Likewise, if an
607           entabbing scheme is used in the input script and not in the current
608           process then the guessed indentation will be wrong.
609
610           If the default method does not work correctly, or you want to
611           change the starting level, use -sil=n, to force the starting level
612           to be n.
613
614       List indentation using -lp, --line-up-parentheses
615           By default, perltidy indents lists with 4 spaces, or whatever value
616           is specified with -i=n.  Here is a small list formatted in this
617           way:
618
619               # perltidy (default)
620               @month_of_year = (
621                   'Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun',
622                   'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'
623               );
624
625           Use the -lp flag to add extra indentation to cause the data to
626           begin past the opening parentheses of a sub call or list, or
627           opening square bracket of an anonymous array, or opening curly
628           brace of an anonymous hash.  With this option, the above list would
629           become:
630
631               # perltidy -lp
632               @month_of_year = (
633                                  'Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun',
634                                  'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'
635               );
636
637           If the available line length (see -l=n ) does not permit this much
638           space, perltidy will use less.   For alternate placement of the
639           closing paren, see the next section.
640
641           This option has no effect on code BLOCKS, such as if/then/else
642           blocks, which always use whatever is specified with -i=n.  Also,
643           the existence of line breaks and/or block comments between the
644           opening and closing parens may cause perltidy to temporarily revert
645           to its default method.
646
647           Note: The -lp option may not be used together with the -t tabs
648           option.  It may, however, be used with the -et=n tab method.
649
650           In addition, any parameter which significantly restricts the
651           ability of perltidy to choose newlines will conflict with -lp and
652           will cause -lp to be deactivated.  These include -io, -fnl, -nanl,
653           and -ndnl.  The reason is that the -lp indentation style can
654           require the careful coordination of an arbitrary number of break
655           points in hierarchical lists, and these flags may prevent that.
656
657       -cti=n, --closing-token-indentation
658           The -cti=n flag controls the indentation of a line beginning with a
659           ")", "]", or a non-block "}".  Such a line receives:
660
661            -cti = 0 no extra indentation (default)
662            -cti = 1 extra indentation such that the closing token
663                   aligns with its opening token.
664            -cti = 2 one extra indentation level if the line looks like:
665                   );  or  ];  or  };
666            -cti = 3 one extra indentation level always
667
668           The flags -cti=1 and -cti=2 work well with the -lp flag (previous
669           section).
670
671               # perltidy -lp -cti=1
672               @month_of_year = (
673                                  'Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun',
674                                  'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'
675                                );
676
677               # perltidy -lp -cti=2
678               @month_of_year = (
679                                  'Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun',
680                                  'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'
681                                  );
682
683           These flags are merely hints to the formatter and they may not
684           always be followed.  In particular, if -lp is not being used, the
685           indentation for cti=1 is constrained to be no more than one
686           indentation level.
687
688           If desired, this control can be applied independently to each of
689           the closing container token types.  In fact, -cti=n is merely an
690           abbreviation for -cpi=n -csbi=n -cbi=n, where: -cpi or
691           --closing-paren-indentation controls )'s, -csbi or
692           --closing-square-bracket-indentation controls ]'s, -cbi or
693           --closing-brace-indentation controls non-block }'s.
694
695       -icp, --indent-closing-paren
696           The -icp flag is equivalent to -cti=2, described in the previous
697           section.  The -nicp flag is equivalent -cti=0.  They are included
698           for backwards compatibility.
699
700       -icb, --indent-closing-brace
701           The -icb option gives one extra level of indentation to a brace
702           which terminates a code block .  For example,
703
704                   if ($task) {
705                       yyy();
706                       }    # -icb
707                   else {
708                       zzz();
709                       }
710
711           The default is not to do this, indicated by -nicb.
712
713       -olq, --outdent-long-quotes
714           When -olq is set, lines which is a quoted string longer than the
715           value maximum-line-length will have their indentation removed to
716           make them more readable.  This is the default.  To prevent such
717           out-denting, use -nolq or --nooutdent-long-lines.
718
719       -oll, --outdent-long-lines
720           This command is equivalent to --outdent-long-quotes and
721           --outdent-long-comments, and it is included for compatibility with
722           previous versions of perltidy.  The negation of this also works,
723           -noll or --nooutdent-long-lines, and is equivalent to setting -nolq
724           and -nolc.
725
726       Outdenting Labels: -ola,  --outdent-labels
727           This command will cause labels to be outdented by 2 spaces (or
728           whatever -ci has been set to), if possible.  This is the default.
729           For example:
730
731                   my $i;
732                 LOOP: while ( $i = <FOTOS> ) {
733                       chomp($i);
734                       next unless $i;
735                       fixit($i);
736                   }
737
738           Use -nola to not outdent labels.
739
740       Outdenting Keywords
741           -okw,  --outdent-keywords
742               The command -okw will cause certain leading control keywords to
743               be outdented by 2 spaces (or whatever -ci has been set to), if
744               possible.  By default, these keywords are "redo", "next",
745               "last", "goto", and "return".  The intention is to make these
746               control keywords easier to see.  To change this list of
747               keywords being outdented, see the next section.
748
749               For example, using "perltidy -okw" on the previous example
750               gives:
751
752                       my $i;
753                     LOOP: while ( $i = <FOTOS> ) {
754                           chomp($i);
755                         next unless $i;
756                           fixit($i);
757                       }
758
759               The default is not to do this.
760
761           Specifying Outdented Keywords: -okwl=string,
762           --outdent-keyword-list=string
763               This command can be used to change the keywords which are
764               outdented with the -okw command.  The parameter string is a
765               required list of perl keywords, which should be placed in
766               quotes if there are more than one.  By itself, it does not
767               cause any outdenting to occur, so the -okw command is still
768               required.
769
770               For example, the commands "-okwl="next last redo goto" -okw"
771               will cause those four keywords to be outdented.  It is probably
772               simplest to place any -okwl command in a .perltidyrc file.
773
774   Whitespace Control
775       Whitespace refers to the blank space between variables, operators, and
776       other code tokens.
777
778       -fws,  --freeze-whitespace
779           This flag causes your original whitespace to remain unchanged, and
780           causes the rest of the whitespace commands in this section, the
781           Code Indentation section, and the Comment Control section to be
782           ignored.
783
784       Tightness of curly braces, parentheses, and square brackets.
785           Here the term "tightness" will mean the closeness with which pairs
786           of enclosing tokens, such as parentheses, contain the quantities
787           within.  A numerical value of 0, 1, or 2 defines the tightness,
788           with 0 being least tight and 2 being most tight.  Spaces within
789           containers are always symmetric, so if there is a space after a "("
790           then there will be a space before the corresponding ")".
791
792           The -pt=n or --paren-tightness=n parameter controls the space
793           within parens.  The example below shows the effect of the three
794           possible values, 0, 1, and 2:
795
796            if ( ( my $len_tab = length( $tabstr ) ) > 0 ) {  # -pt=0
797            if ( ( my $len_tab = length($tabstr) ) > 0 ) {    # -pt=1 (default)
798            if ((my $len_tab = length($tabstr)) > 0) {        # -pt=2
799
800           When n is 0, there is always a space to the right of a '(' and to
801           the left of a ')'.  For n=2 there is never a space.  For n=1, the
802           default, there is a space unless the quantity within the parens is
803           a single token, such as an identifier or quoted string.
804
805           Likewise, the parameter -sbt=n or --square-bracket-tightness=n
806           controls the space within square brackets, as illustrated below.
807
808            $width = $col[ $j + $k ] - $col[ $j ];  # -sbt=0
809            $width = $col[ $j + $k ] - $col[$j];    # -sbt=1 (default)
810            $width = $col[$j + $k] - $col[$j];      # -sbt=2
811
812           Curly braces which do not contain code blocks are controlled by the
813           parameter -bt=n or --brace-tightness=n.
814
815            $obj->{ $parsed_sql->{ 'table' }[0] };    # -bt=0
816            $obj->{ $parsed_sql->{'table'}[0] };      # -bt=1 (default)
817            $obj->{$parsed_sql->{'table'}[0]};        # -bt=2
818
819           And finally, curly braces which contain blocks of code are
820           controlled by the parameter -bbt=n or --block-brace-tightness=n as
821           illustrated in the example below.
822
823            %bf = map { $_ => -M $_ } grep { /\.deb$/ } dirents '.'; # -bbt=0 (default)
824            %bf = map { $_ => -M $_ } grep {/\.deb$/} dirents '.';   # -bbt=1
825            %bf = map {$_ => -M $_} grep {/\.deb$/} dirents '.';     # -bbt=2
826
827           To simplify input in the case that all of the tightness flags have
828           the same value <n>, the parameter <-act=n> or
829           --all-containers-tightness=n is an abbreviation for the combination
830           <-pt=n -sbt=n -bt=n -bbt=n>.
831
832       -tso,   --tight-secret-operators
833           The flag -tso causes certain perl token sequences (secret
834           operators) which might be considered to be a single operator to be
835           formatted "tightly" (without spaces).  The operators currently
836           modified by this flag are:
837
838                0+  +0  ()x!! ~~<>  ,=>   =( )=
839
840           For example the sequence 0 +,  which converts a string to a number,
841           would be formatted without a space: 0+ when the -tso flag is set.
842           This flag is off by default.
843
844       -sts,   --space-terminal-semicolon
845           Some programmers prefer a space before all terminal semicolons.
846           The default is for no such space, and is indicated with -nsts or
847           --nospace-terminal-semicolon.
848
849                   $i = 1 ;     #  -sts
850                   $i = 1;      #  -nsts   (default)
851
852       -sfs,   --space-for-semicolon
853           Semicolons within for loops may sometimes be hard to see,
854           particularly when commas are also present.  This option places
855           spaces on both sides of these special semicolons, and is the
856           default.  Use -nsfs or --nospace-for-semicolon to deactivate it.
857
858            for ( @a = @$ap, $u = shift @a ; @a ; $u = $v ) {  # -sfs (default)
859            for ( @a = @$ap, $u = shift @a; @a; $u = $v ) {    # -nsfs
860
861       -asc,  --add-semicolons
862           Setting -asc allows perltidy to add any missing optional semicolon
863           at the end of a line which is followed by a closing curly brace on
864           the next line.  This is the default, and may be deactivated with
865           -nasc or --noadd-semicolons.
866
867       -dsm,  --delete-semicolons
868           Setting -dsm allows perltidy to delete extra semicolons which are
869           simply empty statements.  This is the default, and may be
870           deactivated with -ndsm or --nodelete-semicolons.  (Such semicolons
871           are not deleted, however, if they would promote a side comment to a
872           block comment).
873
874       -aws,  --add-whitespace
875           Setting this option allows perltidy to add certain whitespace
876           improve code readability.  This is the default. If you do not want
877           any whitespace added, but are willing to have some whitespace
878           deleted, use -naws.  (Use -fws to leave whitespace completely
879           unchanged).
880
881       -dws,  --delete-old-whitespace
882           Setting this option allows perltidy to remove some old whitespace
883           between characters, if necessary.  This is the default.  If you do
884           not want any old whitespace removed, use -ndws or
885           --nodelete-old-whitespace.
886
887       Detailed whitespace controls around tokens
888           For those who want more detailed control over the whitespace around
889           tokens, there are four parameters which can directly modify the
890           default whitespace rules built into perltidy for any token.  They
891           are:
892
893           -wls=s or --want-left-space=s,
894
895           -nwls=s or --nowant-left-space=s,
896
897           -wrs=s or --want-right-space=s,
898
899           -nwrs=s or --nowant-right-space=s.
900
901           These parameters are each followed by a quoted string, s,
902           containing a list of token types.  No more than one of each of
903           these parameters should be specified, because repeating a command-
904           line parameter always overwrites the previous one before perltidy
905           ever sees it.
906
907           To illustrate how these are used, suppose it is desired that there
908           be no space on either side of the token types = + - / *.  The
909           following two parameters would specify this desire:
910
911             -nwls="= + - / *"    -nwrs="= + - / *"
912
913           (Note that the token types are in quotes, and that they are
914           separated by spaces).  With these modified whitespace rules, the
915           following line of math:
916
917             $root = -$b + sqrt( $b * $b - 4. * $a * $c ) / ( 2. * $a );
918
919           becomes this:
920
921             $root=-$b+sqrt( $b*$b-4.*$a*$c )/( 2.*$a );
922
923           These parameters should be considered to be hints to perltidy
924           rather than fixed rules, because perltidy must try to resolve
925           conflicts that arise between them and all of the other rules that
926           it uses.  One conflict that can arise is if, between two tokens,
927           the left token wants a space and the right one doesn't.  In this
928           case, the token not wanting a space takes priority.
929
930           It is necessary to have a list of all token types in order to
931           create this type of input.  Such a list can be obtained by the
932           command --dump-token-types.  Also try the -D flag on a short
933           snippet of code and look at the .DEBUG file to see the
934           tokenization.
935
936           WARNING Be sure to put these tokens in quotes to avoid having them
937           misinterpreted by your command shell.
938
939       Space between specific keywords and opening paren
940           When an opening paren follows a Perl keyword, no space is
941           introduced after the keyword, unless it is (by default) one of
942           these:
943
944              my local our and or eq ne if else elsif until unless
945              while for foreach return switch case given when
946
947           These defaults can be modified with two commands:
948
949           -sak=s  or --space-after-keyword=s  adds keywords.
950
951           -nsak=s  or --nospace-after-keyword=s  removes keywords.
952
953           where s is a list of keywords (in quotes if necessary).  For
954           example,
955
956             my ( $a, $b, $c ) = @_;    # default
957             my( $a, $b, $c ) = @_;     # -nsak="my local our"
958
959           The abbreviation -nsak='*' is equivalent to including all of the
960           keywords in the above list.
961
962           When both -nsak=s and -sak=s commands are included, the -nsak=s
963           command is executed first.  For example, to have space after only
964           the keywords (my, local, our) you could use -nsak="*" -sak="my
965           local our".
966
967           To put a space after all keywords, see the next item.
968
969       Space between all keywords and opening parens
970           When an opening paren follows a function or keyword, no space is
971           introduced after the keyword except for the keywords noted in the
972           previous item.  To always put a space between a function or keyword
973           and its opening paren, use the command:
974
975           -skp  or --space-keyword-paren
976
977           You will probably also want to use the flag -sfp (next item) too.
978
979       Space between all function names and opening parens
980           When an opening paren follows a function the default is not to
981           introduce a space.  To cause a space to be introduced use:
982
983           -sfp  or --space-function-paren
984
985             myfunc( $a, $b, $c );    # default
986             myfunc ( $a, $b, $c );   # -sfp
987
988           You will probably also want to use the flag -skp (previous item)
989           too.
990
991       Trimming whitespace around "qw" quotes
992           -tqw or --trim-qw provide the default behavior of trimming spaces
993           around multi-line "qw" quotes and indenting them appropriately.
994
995           -ntqw or --notrim-qw cause leading and trailing whitespace around
996           multi-line "qw" quotes to be left unchanged.  This option will not
997           normally be necessary, but was added for testing purposes, because
998           in some versions of perl, trimming "qw" quotes changes the syntax
999           tree.
1000
1001       -sbq=n  or --space-backslash-quote=n
1002           Lines like
1003
1004                  $str1=\"string1";
1005                  $str2=\'string2';
1006
1007           can confuse syntax highlighters unless a space is included between
1008           the backslash and the single or double quotation mark.
1009
1010           This can be controlled with the value of n as follows:
1011
1012               -sbq=0 means no space between the backslash and quote
1013               -sbq=1 means follow the example of the source code
1014               -sbq=2 means always put a space between the backslash and quote
1015
1016           The default is -sbq=1, meaning that a space will be used 0if there
1017           is one in the source code.
1018
1019       Trimming trailing whitespace from lines of POD
1020           -trp or --trim-pod will remove trailing whitespace from lines of
1021           POD.  The default is not to do this.
1022
1023   Comment Controls
1024       Perltidy has a number of ways to control the appearance of both block
1025       comments and side comments.  The term block comment here refers to a
1026       full-line comment, whereas side comment will refer to a comment which
1027       appears on a line to the right of some code.
1028
1029       -ibc,  --indent-block-comments
1030           Block comments normally look best when they are indented to the
1031           same level as the code which follows them.  This is the default
1032           behavior, but you may use -nibc to keep block comments left-
1033           justified.  Here is an example:
1034
1035                        # this comment is indented      (-ibc, default)
1036                        if ($task) { yyy(); }
1037
1038           The alternative is -nibc:
1039
1040            # this comment is not indented              (-nibc)
1041                        if ($task) { yyy(); }
1042
1043           See also the next item, -isbc, as well as -sbc, for other ways to
1044           have some indented and some outdented block comments.
1045
1046       -isbc,  --indent-spaced-block-comments
1047           If there is no leading space on the line, then the comment will not
1048           be indented, and otherwise it may be.
1049
1050           If both -ibc and -isbc are set, then -isbc takes priority.
1051
1052       -olc, --outdent-long-comments
1053           When -olc is set, lines which are full-line (block) comments longer
1054           than the value maximum-line-length will have their indentation
1055           removed.  This is the default; use -nolc to prevent outdenting.
1056
1057       -msc=n,  --minimum-space-to-comment=n
1058           Side comments look best when lined up several spaces to the right
1059           of code.  Perltidy will try to keep comments at least n spaces to
1060           the right.  The default is n=4 spaces.
1061
1062       -fpsc=n,  --fixed-position-side-comment=n
1063           This parameter tells perltidy to line up side comments in column
1064           number n whenever possible.  The default, n=0, will not do this.
1065
1066       -iscl,  --ignore-side-comment-lengths
1067           This parameter causes perltidy to ignore the length of side
1068           comments when setting line breaks.  The default, -niscl, is to
1069           include the length of side comments when breaking lines to stay
1070           within the length prescribed by the -l=n maximum line length
1071           parameter.  For example, the following long single line would
1072           remain intact with -l=80 and -iscl:
1073
1074                perltidy -l=80 -iscl
1075                   $vmsfile =~ s/;[\d\-]*$//; # Clip off version number; we can use a newer version as well
1076
1077           whereas without the -iscl flag the line will be broken:
1078
1079                perltidy -l=80
1080                   $vmsfile =~ s/;[\d\-]*$//
1081                     ;    # Clip off version number; we can use a newer version as well
1082
1083       -hsc, --hanging-side-comments
1084           By default, perltidy tries to identify and align "hanging side
1085           comments", which are something like this:
1086
1087                   my $IGNORE = 0;    # This is a side comment
1088                                      # This is a hanging side comment
1089                                      # And so is this
1090
1091           A comment is considered to be a hanging side comment if (1) it
1092           immediately follows a line with a side comment, or another hanging
1093           side comment, and (2) there is some leading whitespace on the line.
1094           To deactivate this feature, use -nhsc or --nohanging-side-comments.
1095           If block comments are preceded by a blank line, or have no leading
1096           whitespace, they will not be mistaken as hanging side comments.
1097
1098       Closing Side Comments
1099           A closing side comment is a special comment which perltidy can
1100           automatically create and place after the closing brace of a code
1101           block.  They can be useful for code maintenance and debugging.  The
1102           command -csc (or --closing-side-comments) adds or updates closing
1103           side comments.  For example, here is a small code snippet
1104
1105                   sub message {
1106                       if ( !defined( $_[0] ) ) {
1107                           print("Hello, World\n");
1108                       }
1109                       else {
1110                           print( $_[0], "\n" );
1111                       }
1112                   }
1113
1114           And here is the result of processing with "perltidy -csc":
1115
1116                   sub message {
1117                       if ( !defined( $_[0] ) ) {
1118                           print("Hello, World\n");
1119                       }
1120                       else {
1121                           print( $_[0], "\n" );
1122                       }
1123                   } ## end sub message
1124
1125           A closing side comment was added for "sub message" in this case,
1126           but not for the "if" and "else" blocks, because they were below the
1127           6 line cutoff limit for adding closing side comments.  This limit
1128           may be changed with the -csci command, described below.
1129
1130           The command -dcsc (or --delete-closing-side-comments) reverses this
1131           process and removes these comments.
1132
1133           Several commands are available to modify the behavior of these two
1134           basic commands, -csc and -dcsc:
1135
1136           -csci=n, or --closing-side-comment-interval=n
1137               where "n" is the minimum number of lines that a block must have
1138               in order for a closing side comment to be added.  The default
1139               value is "n=6".  To illustrate:
1140
1141                       # perltidy -csci=2 -csc
1142                       sub message {
1143                           if ( !defined( $_[0] ) ) {
1144                               print("Hello, World\n");
1145                           } ## end if ( !defined( $_[0] ))
1146                           else {
1147                               print( $_[0], "\n" );
1148                           } ## end else [ if ( !defined( $_[0] ))
1149                       } ## end sub message
1150
1151               Now the "if" and "else" blocks are commented.  However, now
1152               this has become very cluttered.
1153
1154           -cscp=string, or --closing-side-comment-prefix=string
1155               where string is the prefix used before the name of the block
1156               type.  The default prefix, shown above, is "## end".  This
1157               string will be added to closing side comments, and it will also
1158               be used to recognize them in order to update, delete, and
1159               format them.  Any comment identified as a closing side comment
1160               will be placed just a single space to the right of its closing
1161               brace.
1162
1163           -cscl=string, or --closing-side-comment-list
1164               where "string" is a list of block types to be tagged with
1165               closing side comments.  By default, all code block types
1166               preceded by a keyword or label (such as "if", "sub", and so on)
1167               will be tagged.  The -cscl command changes the default list to
1168               be any selected block types; see "Specifying Block Types".  For
1169               example, the following command requests that only "sub"'s,
1170               labels, "BEGIN", and "END" blocks be affected by any -csc or
1171               -dcsc operation:
1172
1173                  -cscl="sub : BEGIN END"
1174
1175           -csct=n, or --closing-side-comment-maximum-text=n
1176               The text appended to certain block types, such as an "if"
1177               block, is whatever lies between the keyword introducing the
1178               block, such as "if", and the opening brace.  Since this might
1179               be too much text for a side comment, there needs to be a limit,
1180               and that is the purpose of this parameter.  The default value
1181               is "n=20", meaning that no additional tokens will be appended
1182               to this text after its length reaches 20 characters.  Omitted
1183               text is indicated with "...".  (Tokens, including sub names,
1184               are never truncated, however, so actual lengths may exceed
1185               this).  To illustrate, in the above example, the appended text
1186               of the first block is " ( !defined( $_[0] )...".  The existing
1187               limit of "n=20" caused this text to be truncated, as indicated
1188               by the "...".  See the next flag for additional control of the
1189               abbreviated text.
1190
1191           -cscb, or --closing-side-comments-balanced
1192               As discussed in the previous item, when the closing-side-
1193               comment-maximum-text limit is exceeded the comment text must be
1194               truncated.  Older versions of perltidy terminated with three
1195               dots, and this can still be achieved with -ncscb:
1196
1197                 perltidy -csc -ncscb
1198                 } ## end foreach my $foo (sort { $b cmp $a ...
1199
1200               However this causes a problem with editors which cannot
1201               recognize comments or are not configured to do so because they
1202               cannot "bounce" around in the text correctly.  The -cscb flag
1203               has been added to help them by appending appropriate balancing
1204               structure:
1205
1206                 perltidy -csc -cscb
1207                 } ## end foreach my $foo (sort { $b cmp $a ... })
1208
1209               The default is -cscb.
1210
1211           -csce=n, or --closing-side-comment-else-flag=n
1212               The default, n=0, places the text of the opening "if" statement
1213               after any terminal "else".
1214
1215               If n=2 is used, then each "elsif" is also given the text of the
1216               opening "if" statement.  Also, an "else" will include the text
1217               of a preceding "elsif" statement.  Note that this may result
1218               some long closing side comments.
1219
1220               If n=1 is used, the results will be the same as n=2 whenever
1221               the resulting line length is less than the maximum allowed.
1222
1223           -cscb, or --closing-side-comments-balanced
1224               When using closing-side-comments, and the closing-side-comment-
1225               maximum-text limit is exceeded, then the comment text must be
1226               abbreviated.  It is terminated with three dots if the -cscb
1227               flag is negated:
1228
1229                 perltidy -csc -ncscb
1230                 } ## end foreach my $foo (sort { $b cmp $a ...
1231
1232               This causes a problem with older editors which do not recognize
1233               comments because they cannot "bounce" around in the text
1234               correctly.  The -cscb flag tries to help them by appending
1235               appropriate terminal balancing structures:
1236
1237                 perltidy -csc -cscb
1238                 } ## end foreach my $foo (sort { $b cmp $a ... })
1239
1240               The default is -cscb.
1241
1242           -cscw, or --closing-side-comment-warnings
1243               This parameter is intended to help make the initial transition
1244               to the use of closing side comments.  It causes two things to
1245               happen if a closing side comment replaces an existing,
1246               different closing side comment:  first, an error message will
1247               be issued, and second, the original side comment will be placed
1248               alone on a new specially marked comment line for later
1249               attention.
1250
1251               The intent is to avoid clobbering existing hand-written side
1252               comments which happen to match the pattern of closing side
1253               comments. This flag should only be needed on the first run with
1254               -csc.
1255
1256           Important Notes on Closing Side Comments:
1257
1258           ·   Closing side comments are only placed on lines terminated with
1259               a closing brace.  Certain closing styles, such as the use of
1260               cuddled elses (-ce), preclude the generation of some closing
1261               side comments.
1262
1263           ·   Please note that adding or deleting of closing side comments
1264               takes place only through the commands -csc or -dcsc.  The other
1265               commands, if used, merely modify the behavior of these two
1266               commands.
1267
1268           ·   It is recommended that the -cscw flag be used along with -csc
1269               on the first use of perltidy on a given file.  This will
1270               prevent loss of any existing side comment data which happens to
1271               have the csc prefix.
1272
1273           ·   Once you use -csc, you should continue to use it so that any
1274               closing side comments remain correct as code changes.
1275               Otherwise, these comments will become incorrect as the code is
1276               updated.
1277
1278           ·   If you edit the closing side comments generated by perltidy,
1279               you must also change the prefix to be different from the
1280               closing side comment prefix.  Otherwise, your edits will be
1281               lost when you rerun perltidy with -csc.   For example, you
1282               could simply change "## end" to be "## End", since the test is
1283               case sensitive.  You may also want to use the -ssc flag to keep
1284               these modified closing side comments spaced the same as actual
1285               closing side comments.
1286
1287           ·   Temporarily generating closing side comments is a useful
1288               technique for exploring and/or debugging a perl script,
1289               especially one written by someone else.  You can always remove
1290               them with -dcsc.
1291
1292       Static Block Comments
1293           Static block comments are block comments with a special leading
1294           pattern, "##" by default, which will be treated slightly
1295           differently from other block comments.  They effectively behave as
1296           if they had glue along their left and top edges, because they stick
1297           to the left edge and previous line when there is no blank spaces in
1298           those places.  This option is particularly useful for controlling
1299           how commented code is displayed.
1300
1301           -sbc, --static-block-comments
1302               When -sbc is used, a block comment with a special leading
1303               pattern, "##" by default, will be treated specially.
1304
1305               Comments so identified  are treated as follows:
1306
1307               ·   If there is no leading space on the line, then the comment
1308                   will not be indented, and otherwise it may be,
1309
1310               ·   no new blank line will be inserted before such a comment,
1311                   and
1312
1313               ·   such a comment will never become a hanging side comment.
1314
1315               For example, assuming @month_of_year is left-adjusted:
1316
1317                   @month_of_year = (    # -sbc (default)
1318                       'Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct',
1319                   ##  'Dec', 'Nov'
1320                       'Nov', 'Dec');
1321
1322               Without this convention, the above code would become
1323
1324                   @month_of_year = (   # -nsbc
1325                       'Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct',
1326
1327                       ##  'Dec', 'Nov'
1328                       'Nov', 'Dec'
1329                   );
1330
1331               which is not as clear.  The default is to use -sbc.  This may
1332               be deactivated with -nsbc.
1333
1334           -sbcp=string, --static-block-comment-prefix=string
1335               This parameter defines the prefix used to identify static block
1336               comments when the -sbc parameter is set.  The default prefix is
1337               "##", corresponding to "-sbcp=##".  The prefix is actually part
1338               of a perl pattern used to match lines and it must either begin
1339               with "#" or "^#".  In the first case a prefix ^\s* will be
1340               added to match any leading whitespace, while in the second case
1341               the pattern will match only comments with no leading
1342               whitespace.  For example, to identify all comments as static
1343               block comments, one would use "-sbcp=#".  To identify all left-
1344               adjusted comments as static block comments, use "-sbcp='^#'".
1345
1346               Please note that -sbcp merely defines the pattern used to
1347               identify static block comments; it will not be used unless the
1348               switch -sbc is set.  Also, please be aware that since this
1349               string is used in a perl regular expression which identifies
1350               these comments, it must enable a valid regular expression to be
1351               formed.
1352
1353               A pattern which can be useful is:
1354
1355                   -sbcp=^#{2,}[^\s#]
1356
1357               This pattern requires a static block comment to have at least
1358               one character which is neither a # nor a space.  It allows a
1359               line containing only '#' characters to be rejected as a static
1360               block comment.  Such lines are often used at the start and end
1361               of header information in subroutines and should not be
1362               separated from the intervening comments, which typically begin
1363               with just a single '#'.
1364
1365           -osbc, --outdent-static-block-comments
1366               The command -osbc will cause static block comments to be
1367               outdented by 2 spaces (or whatever -ci=n has been set to), if
1368               possible.
1369
1370       Static Side Comments
1371           Static side comments are side comments with a special leading
1372           pattern.  This option can be useful for controlling how commented
1373           code is displayed when it is a side comment.
1374
1375           -ssc, --static-side-comments
1376               When -ssc is used, a side comment with a static leading
1377               pattern, which is "##" by default, will be spaced only a single
1378               space from previous character, and it will not be vertically
1379               aligned with other side comments.
1380
1381               The default is -nssc.
1382
1383           -sscp=string, --static-side-comment-prefix=string
1384               This parameter defines the prefix used to identify static side
1385               comments when the -ssc parameter is set.  The default prefix is
1386               "##", corresponding to "-sscp=##".
1387
1388               Please note that -sscp merely defines the pattern used to
1389               identify static side comments; it will not be used unless the
1390               switch -ssc is set.  Also, note that this string is used in a
1391               perl regular expression which identifies these comments, so it
1392               must enable a valid regular expression to be formed.
1393
1394   Skipping Selected Sections of Code
1395       Selected lines of code may be passed verbatim to the output without any
1396       formatting.  This feature is enabled by default but can be disabled
1397       with the --noformat-skipping or -nfs flag.  It should be used sparingly
1398       to avoid littering code with markers, but it might be helpful for
1399       working around occasional problems.  For example it might be useful for
1400       keeping the indentation of old commented code unchanged, keeping
1401       indentation of long blocks of aligned comments unchanged, keeping
1402       certain list formatting unchanged, or working around a glitch in
1403       perltidy.
1404
1405       -fs,  --format-skipping
1406           This flag, which is enabled by default, causes any code between
1407           special beginning and ending comment markers to be passed to the
1408           output without formatting.  The default beginning marker is #<<<
1409           and the default ending marker is #>>> but they may be changed (see
1410           next items below).  Additional text may appear on these special
1411           comment lines provided that it is separated from the marker by at
1412           least one space.  For example
1413
1414            #<<<  do not let perltidy touch this
1415               my @list = (1,
1416                           1, 1,
1417                           1, 2, 1,
1418                           1, 3, 3, 1,
1419                           1, 4, 6, 4, 1,);
1420            #>>>
1421
1422           The comment markers may be placed at any location that a block
1423           comment may appear.  If they do not appear to be working, use the
1424           -log flag and examine the .LOG file.  Use -nfs to disable this
1425           feature.
1426
1427       -fsb=string,  --format-skipping-begin=string
1428           The -fsb=string parameter may be used to change the beginning
1429           marker for format skipping.  The default is equivalent to
1430           -fsb='#<<<'.  The string that you enter must begin with a # and
1431           should be in quotes as necessary to get past the command shell of
1432           your system.  It is actually the leading text of a pattern that is
1433           constructed by appending a '\s', so you must also include
1434           backslashes for characters to be taken literally rather than as
1435           patterns.
1436
1437           Some examples show how example strings become patterns:
1438
1439            -fsb='#\{\{\{' becomes /^#\{\{\{\s/  which matches  #{{{ but not #{{{{
1440            -fsb='#\*\*'   becomes /^#\*\*\s/    which matches  #** but not #***
1441            -fsb='#\*{2,}' becomes /^#\*{2,}\s/  which matches  #** and #*****
1442
1443       -fse=string,  --format-skipping-end=string
1444           The -fsb=string is the corresponding parameter used to change the
1445           ending marker for format skipping.  The default is equivalent to
1446           -fse='#<<<'.
1447
1448   Line Break Control
1449       The parameters in this section control breaks after non-blank lines of
1450       code.  Blank lines are controlled separately by parameters in the
1451       section "Blank Line Control".
1452
1453       -fnl,  --freeze-newlines
1454           If you do not want any changes to the line breaks within lines of
1455           code in your script, set -fnl, and they will remain fixed, and the
1456           rest of the commands in this section and sections "Controlling List
1457           Formatting", "Retaining or Ignoring Existing Line Breaks".  You may
1458           want to use -noll with this.
1459
1460           Note: If you also want to keep your blank lines exactly as they
1461           are, you can use the -fbl flag which is described in the section
1462           "Blank Line Control".
1463
1464       -ce,   --cuddled-else
1465           Enable the "cuddled else" style, in which "else" and "elsif" are
1466           follow immediately after the curly brace closing the previous
1467           block.  The default is not to use cuddled elses, and is indicated
1468           with the flag -nce or --nocuddled-else.  Here is a comparison of
1469           the alternatives:
1470
1471             # -ce
1472             if ($task) {
1473                 yyy();
1474             } else {
1475                 zzz();
1476             }
1477
1478             # -nce (default)
1479             if ($task) {
1480                   yyy();
1481             }
1482             else {
1483                   zzz();
1484             }
1485
1486           In this example the keyword else is placed on the same line which
1487           begins with the preceding closing block brace and is followed by
1488           its own opening block brace on the same line.  Other keywords and
1489           function names which are formatted with this "cuddled" style are
1490           elsif, continue, catch, finally.
1491
1492           Other block types can be formatted by specifying their names on a
1493           separate parameter -cbl, described in a later section.
1494
1495           Cuddling between a pair of code blocks requires that the closing
1496           brace of the first block start a new line.  If this block is
1497           entirely on one line in the input file, it is necessary to decide
1498           if it should be broken to allow cuddling.  This decision is
1499           controlled by the flag -cbo=n discussed below.  The default and
1500           recommended value of -cbo=1 bases this decision on the first block
1501           in the chain.  If it spans multiple lines then cuddling is made and
1502           continues along the chain, regardless of the sizes of subsequent
1503           blocks. Otherwise, short lines remain intact.
1504
1505           So for example, the -ce flag would not have any effect if the above
1506           snippet is rewritten as
1507
1508             if ($task) { yyy() }
1509             else {    zzz() }
1510
1511           If the first block spans multiple lines, then cuddling can be done
1512           and will continue for the subsequent blocks in the chain, as
1513           illustrated in the previous snippet.
1514
1515           If there are blank lines between cuddled blocks they will be
1516           eliminated.  If there are comments after the closing brace where
1517           cuddling would occur then cuddling will be prevented.  If this
1518           occurs, cuddling will restart later in the chain if possible.
1519
1520       -cb,   --cuddled-blocks
1521           This flag is equivalent to -ce.
1522
1523       -cbl,    --cuddled-block-list
1524           The built-in default cuddled block types are else, elsif, continue,
1525           catch, finally.
1526
1527           Additional block types to which the -cuddled-blocks style applies
1528           can be defined by this parameter.  This parameter is a character
1529           string, giving a list of block types separated by commas or spaces.
1530           For example, to cuddle code blocks of type sort, map and grep, in
1531           addition to the default types, the string could be set to
1532
1533             -cbl="sort map grep"
1534
1535           or equivalently
1536
1537             -cbl=sort,map,grep
1538
1539           Note however that these particular block types are typically short
1540           so there might not be much opportunity for the cuddled format
1541           style.
1542
1543           Using commas avoids the need to protect spaces with quotes.
1544
1545           As a diagnostic check, the flag --dump-cuddled-block-list or -dcbl
1546           can be used to view the hash of values that are generated by this
1547           flag.
1548
1549           Finally, note that the -cbl flag by itself merely specifies which
1550           blocks are formatted with the cuddled format. It has no effect
1551           unless this formatting style is activated with -ce.
1552
1553       -cblx,    --cuddled-block-list-exclusive
1554           When cuddled else formatting is selected with -ce, setting this
1555           flag causes perltidy to ignore its built-in defaults and rely
1556           exclusively on the block types specified on the -cbl flag described
1557           in the previous section.  For example, to avoid using cuddled catch
1558           and finally, which among in the defaults, the following set of
1559           parameters could be used:
1560
1561             perltidy -ce -cbl='else elsif continue' -cblx
1562
1563       -cbo=n,   --cuddled-break-option=n
1564           Cuddled formatting is only possible between a pair of code blocks
1565           if the closing brace of the first block starts a new line. If a
1566           block is encountered which is entirely on a single line, and
1567           cuddled formatting is selected, it is necessary to make a decision
1568           as to whether or not to "break" the block, meaning to cause it to
1569           span multiple lines.  This parameter controls that decision. The
1570           options are:
1571
1572              cbo=0  Never force a short block to break.
1573              cbo=1  If the first of a pair of blocks is broken in the input file,
1574                     then break the second [DEFAULT].
1575              cbo=2  Break open all blocks for maximal cuddled formatting.
1576
1577           The default and recommended value is cbo=1.  With this value, if
1578           the starting block of a chain spans multiple lines, then a cascade
1579           of breaks will occur for remaining blocks causing the entire chain
1580           to be cuddled.
1581
1582           The option cbo=0 can produce erratic cuddling if there are numerous
1583           one-line blocks.
1584
1585           The option cbo=2 produces maximal cuddling but will not allow any
1586           short blocks.
1587
1588       -bl,    --opening-brace-on-new-line
1589           Use the flag -bl to place the opening brace on a new line:
1590
1591             if ( $input_file eq '-' )    # -bl
1592             {
1593                 important_function();
1594             }
1595
1596           This flag applies to all structural blocks, including named sub's
1597           (unless the -sbl flag is set -- see next item).
1598
1599           The default style, -nbl, places an opening brace on the same line
1600           as the keyword introducing it.  For example,
1601
1602             if ( $input_file eq '-' ) {   # -nbl (default)
1603
1604       -sbl,    --opening-sub-brace-on-new-line
1605           The flag -sbl can be used to override the value of -bl for the
1606           opening braces of named sub's.  For example,
1607
1608            perltidy -sbl
1609
1610           produces this result:
1611
1612            sub message
1613            {
1614               if (!defined($_[0])) {
1615                   print("Hello, World\n");
1616               }
1617               else {
1618                   print($_[0], "\n");
1619               }
1620            }
1621
1622           This flag is negated with -nsbl.  If -sbl is not specified, the
1623           value of -bl is used.
1624
1625       -asbl,    --opening-anonymous-sub-brace-on-new-line
1626           The flag -asbl is like the -sbl flag except that it applies to
1627           anonymous sub's instead of named subs. For example
1628
1629            perltidy -asbl
1630
1631           produces this result:
1632
1633            $a = sub
1634            {
1635                if ( !defined( $_[0] ) ) {
1636                    print("Hello, World\n");
1637                }
1638                else {
1639                    print( $_[0], "\n" );
1640                }
1641            };
1642
1643           This flag is negated with -nasbl, and the default is -nasbl.
1644
1645       -bli,    --brace-left-and-indent
1646           The flag -bli is the same as -bl but in addition it causes one unit
1647           of continuation indentation ( see -ci ) to be placed before an
1648           opening and closing block braces.
1649
1650           For example,
1651
1652                   if ( $input_file eq '-' )    # -bli
1653                     {
1654                       important_function();
1655                     }
1656
1657           By default, this extra indentation occurs for blocks of type: if,
1658           elsif, else, unless, for, foreach, sub, while, until, and also with
1659           a preceding label.  The next item shows how to change this.
1660
1661       -blil=s,    --brace-left-and-indent-list=s
1662           Use this parameter to change the types of block braces for which
1663           the -bli flag applies; see "Specifying Block Types".  For example,
1664           -blil='if elsif else' would apply it to only "if/elsif/else"
1665           blocks.
1666
1667       -bar,    --opening-brace-always-on-right
1668           The default style, -nbl places the opening code block brace on a
1669           new line if it does not fit on the same line as the opening
1670           keyword, like this:
1671
1672                   if ( $bigwasteofspace1 && $bigwasteofspace2
1673                     || $bigwasteofspace3 && $bigwasteofspace4 )
1674                   {
1675                       big_waste_of_time();
1676                   }
1677
1678           To force the opening brace to always be on the right, use the -bar
1679           flag.  In this case, the above example becomes
1680
1681                   if ( $bigwasteofspace1 && $bigwasteofspace2
1682                     || $bigwasteofspace3 && $bigwasteofspace4 ) {
1683                       big_waste_of_time();
1684                   }
1685
1686           A conflict occurs if both -bl and -bar are specified.
1687
1688       -otr,  --opening-token-right and related flags
1689           The -otr flag is a hint that perltidy should not place a break
1690           between a comma and an opening token.  For example:
1691
1692               # default formatting
1693               push @{ $self->{$module}{$key} },
1694                 {
1695                   accno       => $ref->{accno},
1696                   description => $ref->{description}
1697                 };
1698
1699               # perltidy -otr
1700               push @{ $self->{$module}{$key} }, {
1701                   accno       => $ref->{accno},
1702                   description => $ref->{description}
1703                 };
1704
1705           The flag -otr is actually an abbreviation for three other flags
1706           which can be used to control parens, hash braces, and square
1707           brackets separately if desired:
1708
1709             -opr  or --opening-paren-right
1710             -ohbr or --opening-hash-brace-right
1711             -osbr or --opening-square-bracket-right
1712
1713       -wn,  --weld-nested-containers
1714           The -wn flag causes closely nested pairs of opening and closing
1715           container symbols (curly braces, brackets, or parens) to be
1716           "welded" together, meaning that they are treated as if combined
1717           into a single unit, with the indentation of the innermost code
1718           reduced to be as if there were just a single container symbol.
1719
1720           For example:
1721
1722                   # default formatting
1723                   do {
1724                       {
1725                           next if $x == $y;
1726                       }
1727                   } until $x++ > $z;
1728
1729                   # perltidy -wn
1730                   do { {
1731                       next if $x == $y;
1732                   } } until $x++ > $z;
1733
1734           When this flag is set perltidy makes a preliminary pass through the
1735           file and identifies all nested pairs of containers.  To qualify as
1736           a nested pair, the closing container symbols must be immediately
1737           adjacent. The opening symbols must either be adjacent, or, if the
1738           outer opening symbol is an opening paren, they may be separated by
1739           any single non-container symbol or something that looks like a
1740           function evaluation.
1741
1742           Any container symbol may serve as both the inner container of one
1743           pair and as the outer container of an adjacent pair. Consequently,
1744           any number of adjacent opening or closing symbols may join together
1745           in weld.  For example, here are three levels of wrapped function
1746           calls:
1747
1748                   # default formatting
1749                   my (@date_time) = Localtime(
1750                       Date_to_Time(
1751                           Add_Delta_DHMS(
1752                               $year, $month,  $day, $hour, $minute, $second,
1753                               '0',   $offset, '0',  '0'
1754                           )
1755                       )
1756                   );
1757
1758                   # perltidy -wn
1759                   my (@date_time) = Localtime( Date_to_Time( Add_Delta_DHMS(
1760                       $year, $month,  $day, $hour, $minute, $second,
1761                       '0',   $offset, '0',  '0'
1762                   ) ) );
1763
1764           Notice how the indentation of the inner lines are reduced by two
1765           levels in this case.  This example also shows the typical result of
1766           this formatting, namely it is a sandwich consisting of an initial
1767           opening layer, a central section of any complexity forming the
1768           "meat" of the sandwich, and a final closing layer.  This
1769           predictable structure helps keep the compacted structure readable.
1770
1771           The inner sandwich layer is required to be at least one line thick.
1772           If this cannot be achieved, welding does not occur.  This
1773           constraint can cause formatting to take a couple of iterations to
1774           stabilize when it is first applied to a script. The -conv flag can
1775           be used to insure that the final format is achieved in a single
1776           run.
1777
1778           Here is an example illustrating a welded container within a welded
1779           containers:
1780
1781                   # default formatting
1782                   $x->badd(
1783                       bmul(
1784                           $class->new(
1785                               abs(
1786                                   $sx * int( $xr->numify() ) & $sy * int( $yr->numify() )
1787                               )
1788                           ),
1789                           $m
1790                       )
1791                   );
1792
1793                   # perltidy -wn
1794                   $x->badd( bmul(
1795                       $class->new( abs(
1796                           $sx * int( $xr->numify() ) & $sy * int( $yr->numify() )
1797                       ) ),
1798                       $m
1799                   ) );
1800
1801           This format option is quite general but there are some limitations.
1802
1803           One limitiation is that any line length limit still applies and can
1804           cause long welded sections to be broken into multiple lines.
1805
1806           Another limitation is that an opening symbol which delimits quoted
1807           text cannot be included in a welded pair.  This is because quote
1808           delimiters are treated specially in perltidy.
1809
1810           Finally, the stacking of containers defined by this flag have
1811           priority over any other container stacking flags.  This is because
1812           any welding is done first.
1813
1814       Vertical tightness of non-block curly braces, parentheses, and square
1815       brackets.
1816           These parameters control what shall be called vertical tightness.
1817           Here are the main points:
1818
1819           ·   Opening tokens (except for block braces) are controlled by
1820               -vt=n, or --vertical-tightness=n, where
1821
1822                -vt=0 always break a line after opening token (default).
1823                -vt=1 do not break unless this would produce more than one
1824                        step in indentation in a line.
1825                -vt=2 never break a line after opening token
1826
1827           ·   You must also use the -lp flag when you use the -vt flag; the
1828               reason is explained below.
1829
1830           ·   Closing tokens (except for block braces) are controlled by
1831               -vtc=n, or --vertical-tightness-closing=n, where
1832
1833                -vtc=0 always break a line before a closing token (default),
1834                -vtc=1 do not break before a closing token which is followed
1835                       by a semicolon or another closing token, and is not in
1836                       a list environment.
1837                -vtc=2 never break before a closing token.
1838
1839               The rules for -vtc=1 are designed to maintain a reasonable
1840               balance between tightness and readability in complex lists.
1841
1842           ·   Different controls may be applied to different token types, and
1843               it is also possible to control block braces; see below.
1844
1845           ·   Finally, please note that these vertical tightness flags are
1846               merely hints to the formatter, and it cannot always follow
1847               them.  Things which make it difficult or impossible include
1848               comments, blank lines, blocks of code within a list, and
1849               possibly the lack of the -lp parameter.  Also, these flags may
1850               be ignored for very small lists (2 or 3 lines in length).
1851
1852           Here are some examples:
1853
1854               # perltidy -lp -vt=0 -vtc=0
1855               %romanNumerals = (
1856                                  one   => 'I',
1857                                  two   => 'II',
1858                                  three => 'III',
1859                                  four  => 'IV',
1860               );
1861
1862               # perltidy -lp -vt=1 -vtc=0
1863               %romanNumerals = ( one   => 'I',
1864                                  two   => 'II',
1865                                  three => 'III',
1866                                  four  => 'IV',
1867               );
1868
1869               # perltidy -lp -vt=1 -vtc=1
1870               %romanNumerals = ( one   => 'I',
1871                                  two   => 'II',
1872                                  three => 'III',
1873                                  four  => 'IV', );
1874
1875           The difference between -vt=1 and -vt=2 is shown here:
1876
1877               # perltidy -lp -vt=1
1878               $init->add(
1879                           mysprintf( "(void)find_threadsv(%s);",
1880                                      cstring( $threadsv_names[ $op->targ ] )
1881                           )
1882               );
1883
1884               # perltidy -lp -vt=2
1885               $init->add( mysprintf( "(void)find_threadsv(%s);",
1886                                      cstring( $threadsv_names[ $op->targ ] )
1887                           )
1888               );
1889
1890           With -vt=1, the line ending in "add(" does not combine with the
1891           next line because the next line is not balanced.  This can help
1892           with readability, but -vt=2 can be used to ignore this rule.
1893
1894           The tightest, and least readable, code is produced with both
1895           "-vt=2" and "-vtc=2":
1896
1897               # perltidy -lp -vt=2 -vtc=2
1898               $init->add( mysprintf( "(void)find_threadsv(%s);",
1899                                      cstring( $threadsv_names[ $op->targ ] ) ) );
1900
1901           Notice how the code in all of these examples collapses vertically
1902           as -vt increases, but the indentation remains unchanged.  This is
1903           because perltidy implements the -vt parameter by first formatting
1904           as if -vt=0, and then simply overwriting one output line on top of
1905           the next, if possible, to achieve the desired vertical tightness.
1906           The -lp indentation style has been designed to allow this vertical
1907           collapse to occur, which is why it is required for the -vt
1908           parameter.
1909
1910           The -vt=n and -vtc=n parameters apply to each type of container
1911           token.  If desired, vertical tightness controls can be applied
1912           independently to each of the closing container token types.
1913
1914           The parameters for controlling parentheses are -pvt=n or
1915           --paren-vertical-tightness=n, and -pcvt=n or
1916           --paren-vertical-tightness-closing=n.
1917
1918           Likewise, the parameters for square brackets are -sbvt=n or
1919           --square-bracket-vertical-tightness=n, and -sbcvt=n or
1920           --square-bracket-vertical-tightness-closing=n.
1921
1922           Finally, the parameters for controlling non-code block braces are
1923           -bvt=n or --brace-vertical-tightness=n, and -bcvt=n or
1924           --brace-vertical-tightness-closing=n.
1925
1926           In fact, the parameter -vt=n is actually just an abbreviation for
1927           -pvt=n -bvt=n sbvt=n, and likewise -vtc=n is an abbreviation for
1928           -pvtc=n -bvtc=n sbvtc=n.
1929
1930       -bbvt=n or --block-brace-vertical-tightness=n
1931           The -bbvt=n flag is just like the -vt=n flag but applies to opening
1932           code block braces.
1933
1934            -bbvt=0 break after opening block brace (default).
1935            -bbvt=1 do not break unless this would produce more than one
1936                    step in indentation in a line.
1937            -bbvt=2 do not break after opening block brace.
1938
1939           It is necessary to also use either -bl or -bli for this to work,
1940           because, as with other vertical tightness controls, it is
1941           implemented by simply overwriting a line ending with an opening
1942           block brace with the subsequent line.  For example:
1943
1944               # perltidy -bli -bbvt=0
1945               if ( open( FILE, "< $File" ) )
1946                 {
1947                   while ( $File = <FILE> )
1948                     {
1949                       $In .= $File;
1950                       $count++;
1951                     }
1952                   close(FILE);
1953                 }
1954
1955               # perltidy -bli -bbvt=1
1956               if ( open( FILE, "< $File" ) )
1957                 { while ( $File = <FILE> )
1958                     { $In .= $File;
1959                       $count++;
1960                     }
1961                   close(FILE);
1962                 }
1963
1964           By default this applies to blocks associated with keywords if,
1965           elsif, else, unless, for, foreach, sub, while, until, and also with
1966           a preceding label.  This can be changed with the parameter
1967           -bbvtl=string, or --block-brace-vertical-tightness-list=string,
1968           where string is a space-separated list of block types.  For more
1969           information on the possible values of this string, see "Specifying
1970           Block Types"
1971
1972           For example, if we want to just apply this style to "if", "elsif",
1973           and "else" blocks, we could use "perltidy -bli -bbvt=1 -bbvtl='if
1974           elsif else'".
1975
1976           There is no vertical tightness control for closing block braces;
1977           with one exception they will be placed on separate lines.  The
1978           exception is that a cascade of closing block braces may be stacked
1979           on a single line.  See -scbb.
1980
1981       -sot,  --stack-opening-tokens and related flags
1982           The -sot flag tells perltidy to "stack" opening tokens when
1983           possible to avoid lines with isolated opening tokens.
1984
1985           For example:
1986
1987               # default
1988               $opt_c = Text::CSV_XS->new(
1989                   {
1990                       binary       => 1,
1991                       sep_char     => $opt_c,
1992                       always_quote => 1,
1993                   }
1994               );
1995
1996               # -sot
1997               $opt_c = Text::CSV_XS->new( {
1998                       binary       => 1,
1999                       sep_char     => $opt_c,
2000                       always_quote => 1,
2001                   }
2002               );
2003
2004           For detailed control of individual closing tokens the following
2005           controls can be used:
2006
2007             -sop  or --stack-opening-paren
2008             -sohb or --stack-opening-hash-brace
2009             -sosb or --stack-opening-square-bracket
2010             -sobb or --stack-opening-block-brace
2011
2012           The flag -sot is an abbreviation for -sop -sohb -sosb.
2013
2014           The flag -sobb is a abbreviation for -bbvt=2 -bbvtl='*'.  This will
2015           case a cascade of opening block braces to appear on a single line,
2016           although this an uncommon occurrence except in test scripts.
2017
2018       -sct,  --stack-closing-tokens and related flags
2019           The -sct flag tells perltidy to "stack" closing tokens when
2020           possible to avoid lines with isolated closing tokens.
2021
2022           For example:
2023
2024               # default
2025               $opt_c = Text::CSV_XS->new(
2026                   {
2027                       binary       => 1,
2028                       sep_char     => $opt_c,
2029                       always_quote => 1,
2030                   }
2031               );
2032
2033               # -sct
2034               $opt_c = Text::CSV_XS->new(
2035                   {
2036                       binary       => 1,
2037                       sep_char     => $opt_c,
2038                       always_quote => 1,
2039                   } );
2040
2041           The -sct flag is somewhat similar to the -vtc flags, and in some
2042           cases it can give a similar result.  The difference is that the
2043           -vtc flags try to avoid lines with leading opening tokens by
2044           "hiding" them at the end of a previous line, whereas the -sct flag
2045           merely tries to reduce the number of lines with isolated closing
2046           tokens by stacking them but does not try to hide them.  For
2047           example:
2048
2049               # -vtc=2
2050               $opt_c = Text::CSV_XS->new(
2051                   {
2052                       binary       => 1,
2053                       sep_char     => $opt_c,
2054                       always_quote => 1, } );
2055
2056           For detailed control of the stacking of individual closing tokens
2057           the following controls can be used:
2058
2059             -scp  or --stack-closing-paren
2060             -schb or --stack-closing-hash-brace
2061             -scsb or --stack-closing-square-bracket
2062             -scbb or --stack-closing-block-brace
2063
2064           The flag -sct is an abbreviation for stacking the non-block closing
2065           tokens, -scp -schb -scsb.
2066
2067           Stacking of closing block braces, -scbb, causes a cascade of
2068           isolated closing block braces to be combined into a single line as
2069           in the following example:
2070
2071               # -scbb:
2072               for $w1 (@w1) {
2073                   for $w2 (@w2) {
2074                       for $w3 (@w3) {
2075                           for $w4 (@w4) {
2076                               push( @lines, "$w1 $w2 $w3 $w4\n" );
2077                           } } } }
2078
2079           To simplify input even further for the case in which both opening
2080           and closing non-block containers are stacked, the flag -sac or
2081           --stack-all-containers is an abbreviation for -sot -sot.
2082
2083       -dnl,  --delete-old-newlines
2084           By default, perltidy first deletes all old line break locations,
2085           and then it looks for good break points to match the desired line
2086           length.  Use -ndnl or  --nodelete-old-newlines to force perltidy to
2087           retain all old line break points.
2088
2089       -anl,  --add-newlines
2090           By default, perltidy will add line breaks when necessary to create
2091           continuations of long lines and to improve the script appearance.
2092           Use -nanl or --noadd-newlines to prevent any new line breaks.
2093
2094           This flag does not prevent perltidy from eliminating existing line
2095           breaks; see --freeze-newlines to completely prevent changes to line
2096           break points.
2097
2098       Controlling whether perltidy breaks before or after operators
2099           Four command line parameters provide some control over whether a
2100           line break should be before or after specific token types.  Two
2101           parameters give detailed control:
2102
2103           -wba=s or --want-break-after=s, and
2104
2105           -wbb=s or --want-break-before=s.
2106
2107           These parameters are each followed by a quoted string, s,
2108           containing a list of token types (separated only by spaces).  No
2109           more than one of each of these parameters should be specified,
2110           because repeating a command-line parameter always overwrites the
2111           previous one before perltidy ever sees it.
2112
2113           By default, perltidy breaks after these token types:
2114             % + - * / x != == >= <= =~ !~ < >  | &
2115             = **= += *= &= <<= &&= -= /= |= >>= ||= //= .= %= ^= x=
2116
2117           And perltidy breaks before these token types by default:
2118             . << >> -> && || //
2119
2120           To illustrate, to cause a break after a concatenation operator,
2121           '.', rather than before it, the command line would be
2122
2123             -wba="."
2124
2125           As another example, the following command would cause a break
2126           before math operators '+', '-', '/', and '*':
2127
2128             -wbb="+ - / *"
2129
2130           These commands should work well for most of the token types that
2131           perltidy uses (use --dump-token-types for a list).  Also try the -D
2132           flag on a short snippet of code and look at the .DEBUG file to see
2133           the tokenization.  However, for a few token types there may be
2134           conflicts with hardwired logic which cause unexpected results.  One
2135           example is curly braces, which should be controlled with the
2136           parameter bl provided for that purpose.
2137
2138           WARNING Be sure to put these tokens in quotes to avoid having them
2139           misinterpreted by your command shell.
2140
2141           Two additional parameters are available which, though they provide
2142           no further capability, can simplify input are:
2143
2144           -baao or --break-after-all-operators,
2145
2146           -bbao or --break-before-all-operators.
2147
2148           The -baao sets the default to be to break after all of the
2149           following operators:
2150
2151               % + - * / x != == >= <= =~ !~ < > | &
2152               = **= += *= &= <<= &&= -= /= |= >>= ||= //= .= %= ^= x=
2153               . : ? && || and or err xor
2154
2155           and the -bbao flag sets the default to break before all of these
2156           operators.  These can be used to define an initial break preference
2157           which can be fine-tuned with the -wba and -wbb flags.  For example,
2158           to break before all operators except an = one could use --bbao
2159           -wba='=' rather than listing every single perl operator except = on
2160           a -wbb flag.
2161
2162   Controlling List Formatting
2163       Perltidy attempts to place comma-separated arrays of values in tables
2164       which look good.  Its default algorithms usually work well, and they
2165       have been improving with each release, but several parameters are
2166       available to control list formatting.
2167
2168       -boc,  --break-at-old-comma-breakpoints
2169           This flag tells perltidy to try to break at all old commas.  This
2170           is not the default.  Normally, perltidy makes a best guess at list
2171           formatting, and seldom uses old comma breakpoints.  Usually this
2172           works well, but consider:
2173
2174               my @list = (1,
2175                           1, 1,
2176                           1, 2, 1,
2177                           1, 3, 3, 1,
2178                           1, 4, 6, 4, 1,);
2179
2180           The default formatting will flatten this down to one line:
2181
2182               # perltidy (default)
2183               my @list = ( 1, 1, 1, 1, 2, 1, 1, 3, 3, 1, 1, 4, 6, 4, 1, );
2184
2185           which hides the structure. Using -boc, plus additional flags to
2186           retain the original style, yields
2187
2188               # perltidy -boc -lp -pt=2 -vt=1 -vtc=1
2189               my @list = (1,
2190                           1, 1,
2191                           1, 2, 1,
2192                           1, 3, 3, 1,
2193                           1, 4, 6, 4, 1,);
2194
2195           A disadvantage of this flag is that all tables in the file must
2196           already be nicely formatted.  For another possibility see the -fs
2197           flag in "Skipping Selected Sections of Code".
2198
2199       -mft=n,  --maximum-fields-per-table=n
2200           If the computed number of fields for any table exceeds n, then it
2201           will be reduced to n.  The default value for n is a large number,
2202           40.  While this value should probably be left unchanged as a
2203           general rule, it might be used on a small section of code to force
2204           a list to have a particular number of fields per line, and then
2205           either the -boc flag could be used to retain this formatting, or a
2206           single comment could be introduced somewhere to freeze the
2207           formatting in future applications of perltidy.
2208
2209               # perltidy -mft=2
2210               @month_of_year = (
2211                   'Jan', 'Feb',
2212                   'Mar', 'Apr',
2213                   'May', 'Jun',
2214                   'Jul', 'Aug',
2215                   'Sep', 'Oct',
2216                   'Nov', 'Dec'
2217               );
2218
2219       -cab=n,  --comma-arrow-breakpoints=n
2220           A comma which follows a comma arrow, '=>', is given special
2221           consideration.  In a long list, it is common to break at all such
2222           commas.  This parameter can be used to control how perltidy breaks
2223           at these commas.  (However, it will have no effect if old comma
2224           breaks are being forced because -boc is used).  The possible values
2225           of n are:
2226
2227            n=0 break at all commas after =>
2228            n=1 stable: break at all commas after => if container is open,
2229                EXCEPT FOR one-line containers
2230            n=2 break at all commas after =>, BUT try to form the maximum
2231                maximum one-line container lengths
2232            n=3 do not treat commas after => specially at all
2233            n=4 break everything: like n=0 but ALSO break a short container with
2234                a => not followed by a comma when -vt=0 is used
2235            n=5 stable: like n=1 but ALSO break at open one-line containers when
2236                -vt=0 is used (default)
2237
2238           For example, given the following single line, perltidy by default
2239           will not add any line breaks because it would break the existing
2240           one-line container:
2241
2242               bless { B => $B, Root => $Root } => $package;
2243
2244           Using -cab=0 will force a break after each comma-arrow item:
2245
2246               # perltidy -cab=0:
2247               bless {
2248                   B    => $B,
2249                   Root => $Root
2250               } => $package;
2251
2252           If perltidy is subsequently run with this container broken, then by
2253           default it will break after each '=>' because the container is now
2254           broken.  To reform a one-line container, the parameter -cab=2 could
2255           be used.
2256
2257           The flag -cab=3 can be used to prevent these commas from being
2258           treated specially.  In this case, an item such as "01" => 31 is
2259           treated as a single item in a table.  The number of fields in this
2260           table will be determined by the same rules that are used for any
2261           other table.  Here is an example.
2262
2263               # perltidy -cab=3
2264               my %last_day = (
2265                   "01" => 31, "02" => 29, "03" => 31, "04" => 30,
2266                   "05" => 31, "06" => 30, "07" => 31, "08" => 31,
2267                   "09" => 30, "10" => 31, "11" => 30, "12" => 31
2268               );
2269
2270   Retaining or Ignoring Existing Line Breaks
2271       Several additional parameters are available for controlling the extent
2272       to which line breaks in the input script influence the output script.
2273       In most cases, the default parameter values are set so that, if a
2274       choice is possible, the output style follows the input style.  For
2275       example, if a short logical container is broken in the input script,
2276       then the default behavior is for it to remain broken in the output
2277       script.
2278
2279       Most of the parameters in this section would only be required for a
2280       one-time conversion of a script from short container lengths to longer
2281       container lengths.  The opposite effect, of converting long container
2282       lengths to shorter lengths, can be obtained by temporarily using a
2283       short maximum line length.
2284
2285       -bol,  --break-at-old-logical-breakpoints
2286           By default, if a logical expression is broken at a "&&", "||",
2287           "and", or "or", then the container will remain broken.  Also,
2288           breaks at internal keywords "if" and "unless" will normally be
2289           retained.  To prevent this, and thus form longer lines, use -nbol.
2290
2291       -bok,  --break-at-old-keyword-breakpoints
2292           By default, perltidy will retain a breakpoint before keywords which
2293           may return lists, such as "sort" and <map>.  This allows chains of
2294           these operators to be displayed one per line.  Use -nbok to prevent
2295           retaining these breakpoints.
2296
2297       -bot,  --break-at-old-ternary-breakpoints
2298           By default, if a conditional (ternary) operator is broken at a ":",
2299           then it will remain broken.  To prevent this, and thereby form
2300           longer lines, use -nbot.
2301
2302       -boa,  --break-at-old-attribute-breakpoints
2303           By default, if an attribute list is broken at a ":" in the source
2304           file, then it will remain broken.  For example, given the following
2305           code, the line breaks at the ':'s will be retained:
2306
2307                               my @field
2308                                 : field
2309                                 : Default(1)
2310                                 : Get('Name' => 'foo') : Set('Name');
2311
2312           If the attributes are on a single line in the source code then they
2313           will remain on a single line if possible.
2314
2315           To prevent this, and thereby always form longer lines, use -nboa.
2316
2317       -iob,  --ignore-old-breakpoints
2318           Use this flag to tell perltidy to ignore existing line breaks to
2319           the maximum extent possible.  This will tend to produce the longest
2320           possible containers, regardless of type, which do not exceed the
2321           line length limit.
2322
2323       -kis,  --keep-interior-semicolons
2324           Use the -kis flag to prevent breaking at a semicolon if there was
2325           no break there in the input file.  Normally perltidy places a
2326           newline after each semicolon which terminates a statement unless
2327           several statements are contained within a one-line brace block.  To
2328           illustrate, consider the following input lines:
2329
2330               dbmclose(%verb_delim); undef %verb_delim;
2331               dbmclose(%expanded); undef %expanded;
2332
2333           The default is to break after each statement, giving
2334
2335               dbmclose(%verb_delim);
2336               undef %verb_delim;
2337               dbmclose(%expanded);
2338               undef %expanded;
2339
2340           With perltidy -kis the multiple statements are retained:
2341
2342               dbmclose(%verb_delim); undef %verb_delim;
2343               dbmclose(%expanded);   undef %expanded;
2344
2345           The statements are still subject to the specified value of maximum-
2346           line-length and will be broken if this maximum is exceeded.
2347
2348   Blank Line Control
2349       Blank lines can improve the readability of a script if they are
2350       carefully placed.  Perltidy has several commands for controlling the
2351       insertion, retention, and removal of blank lines.
2352
2353       -fbl,  --freeze-blank-lines
2354           Set -fbl if you want to the blank lines in your script to remain
2355           exactly as they are.  The rest of the parameters in this section
2356           may then be ignored.  (Note: setting the -fbl flag is equivalent to
2357           setting -mbl=0 and -kbl=2).
2358
2359       -bbc,  --blanks-before-comments
2360           A blank line will be introduced before a full-line comment.  This
2361           is the default.  Use -nbbc or  --noblanks-before-comments to
2362           prevent such blank lines from being introduced.
2363
2364       -blbs=n,  --blank-lines-before-subs=n
2365           The parameter -blbs=n requests that least n blank lines precede a
2366           sub definition which does not follow a comment and which is more
2367           than one-line long.  The default is <-blbs=1>.  BEGIN and END
2368           blocks are included.
2369
2370           The requested number of blanks statement will be inserted
2371           regardless of the value of --maximum-consecutive-blank-lines=n
2372           (-mbl=n) with the exception that if -mbl=0 then no blanks will be
2373           output.
2374
2375           This parameter interacts with the value k of the parameter
2376           --maximum-consecutive-blank-lines=k (-mbl=k) as follows:
2377
2378           1. If -mbl=0 then no blanks will be output.  This allows all blanks
2379           to be suppressed with a single parameter.  Otherwise,
2380
2381           2. If the number of old blank lines in the script is less than n
2382           then additional blanks will be inserted to make the total n
2383           regardless of the value of -mbl=k.
2384
2385           3. If the number of old blank lines in the script equals or exceeds
2386           n then this parameter has no effect, however the total will not
2387           exceed value specified on the -mbl=k flag.
2388
2389       -blbp=n,  --blank-lines-before-packages=n
2390           The parameter -blbp=n requests that least n blank lines precede a
2391           package which does not follow a comment.  The default is -blbp=1.
2392
2393           This parameter interacts with the value k of the parameter
2394           --maximum-consecutive-blank-lines=k (-mbl=k) in the same way as
2395           described for the previous item -blbs=n.
2396
2397       -bbs,  --blanks-before-subs
2398           For compatibility with previous versions, -bbs or
2399           --blanks-before-subs is equivalent to -blbp=1 and -blbs=1.
2400
2401           Likewise, -nbbs or --noblanks-before-subs is equivalent to -blbp=0
2402           and -blbs=0.
2403
2404       -bbb,  --blanks-before-blocks
2405           A blank line will be introduced before blocks of coding delimited
2406           by for, foreach, while, until, and if, unless, in the following
2407           circumstances:
2408
2409           ·   The block is not preceded by a comment.
2410
2411           ·   The block is not a one-line block.
2412
2413           ·   The number of consecutive non-blank lines at the current
2414               indentation depth is at least -lbl (see next section).
2415
2416           This is the default.  The intention of this option is to introduce
2417           some space within dense coding.  This is negated with -nbbb or
2418           --noblanks-before-blocks.
2419
2420       -lbl=n --long-block-line-count=n
2421           This controls how often perltidy is allowed to add blank lines
2422           before certain block types (see previous section).  The default is
2423           8.  Entering a value of 0 is equivalent to entering a very large
2424           number.
2425
2426       -blao=i or --blank-lines-after-opening-block=i
2427           This control places a minimum of i blank lines after a line which
2428           ends with an opening block brace of a specified type.  By default,
2429           this only applies to the block of a named sub, but this can be
2430           changed (see -blaol below).  The default is not to do this (i=0).
2431
2432           Please see the note below on using the -blao and -blbc options.
2433
2434       -blbc=i or --blank-lines-before-closing-block=i
2435           This control places a minimum of i blank lines before a line which
2436           begins with a closing block brace of a specified type.  By default,
2437           this only applies to the block of a named sub, but this can be
2438           changed (see -blbcl below).  The default is not to do this (i=0).
2439
2440       -blaol=s or --blank-lines-after-opening-block-list=s
2441           The parameter s is a list of block type keywords to which the flag
2442           -blao should apply.  The section "Specifying Block Types" explains
2443           how to list block types.
2444
2445       -blbcl=s or --blank-lines-before-closing-block-list=s
2446           This parameter is a list of block type keywords to which the flag
2447           -blbc should apply.  The section "Specifying Block Types" explains
2448           how to list block types.
2449
2450       Note on using the -blao and -blbc options.
2451           These blank line controls introduce a certain minimum number of
2452           blank lines in the text, but the final number of blank lines may be
2453           greater, depending on values of the other blank line controls and
2454           the number of old blank lines.  A consequence is that introducing
2455           blank lines with these and other controls cannot be exactly undone,
2456           so some experimentation with these controls is recommended before
2457           using them.
2458
2459           For example, suppose that for some reason we decide to introduce
2460           one blank space at the beginning and ending of all blocks.  We
2461           could do this using
2462
2463             perltidy -blao=2 -blbc=2 -blaol='*' -blbcl='*' filename
2464
2465           Now suppose the script continues to be developed, but at some later
2466           date we decide we don't want these spaces after all. we might
2467           expect that running with the flags -blao=0 and -blbc=0 will undo
2468           them.  However, by default perltidy retains single blank lines, so
2469           the blank lines remain.
2470
2471           We can easily fix this by telling perltidy to ignore old blank
2472           lines by including the added parameter -kbl=0 and rerunning. Then
2473           the unwanted blank lines will be gone.  However, this will cause
2474           all old blank lines to be ignored, perhaps even some that were
2475           added by hand to improve formatting. So please be cautious when
2476           using these parameters.
2477
2478       -mbl=n --maximum-consecutive-blank-lines=n
2479           This parameter specifies the maximum number of consecutive blank
2480           lines which will be output within code sections of a script.  The
2481           default is n=1.  If the input file has more than n consecutive
2482           blank lines, the number will be reduced to n except as noted above
2483           for the -blbp and -blbs parameters.  If n=0 then no blank lines
2484           will be output (unless all old blank lines are retained with the
2485           -kbl=2 flag of the next section).
2486
2487           This flag obviously does not apply to pod sections, here-documents,
2488           and quotes.
2489
2490       -kbl=n,  --keep-old-blank-lines=n
2491           The -kbl=n flag gives you control over how your existing blank
2492           lines are treated.
2493
2494           The possible values of n are:
2495
2496            n=0 ignore all old blank lines
2497            n=1 stable: keep old blanks, but limited by the value of the B<-mbl=n> flag
2498            n=2 keep all old blank lines, regardless of the value of the B<-mbl=n> flag
2499
2500           The default is n=1.
2501
2502       -sob,  --swallow-optional-blank-lines
2503           This is equivalent to kbl=0 and is included for compatibility with
2504           previous versions.
2505
2506       -nsob,  --noswallow-optional-blank-lines
2507           This is equivalent to kbl=1 and is included for compatibility with
2508           previous versions.
2509
2510   Styles
2511       A style refers to a convenient collection of existing parameters.
2512
2513       -gnu, --gnu-style
2514           -gnu gives an approximation to the GNU Coding Standards (which do
2515           not apply to perl) as they are sometimes implemented.  At present,
2516           this style overrides the default style with the following
2517           parameters:
2518
2519               -lp -bl -noll -pt=2 -bt=2 -sbt=2 -icp
2520
2521       -pbp, --perl-best-practices
2522           -pbp is an abbreviation for the parameters in the book Perl Best
2523           Practices by Damian Conway:
2524
2525               -l=78 -i=4 -ci=4 -st -se -vt=2 -cti=0 -pt=1 -bt=1 -sbt=1 -bbt=1 -nsfs -nolq
2526               -wbb="% + - * / x != == >= <= =~ !~ < > | & =
2527                     **= += *= &= <<= &&= -= /= |= >>= ||= //= .= %= ^= x="
2528
2529           Please note that this parameter set includes -st and -se flags,
2530           which make perltidy act as a filter on one file only.  These can be
2531           overridden by placing -nst and/or -nse after the -pbp parameter.
2532
2533           Also note that the value of continuation indentation, -ci=4, is
2534           equal to the value of the full indentation, -i=4.  In some complex
2535           statements perltidy will produce nicer results with -ci=2. This can
2536           be implemented by including -ci=2 after the -pbp parameter.  For
2537           example,
2538
2539               # perltidy -pbp
2540               $self->{_text} = (
2541                    !$section        ? ''
2542                   : $type eq 'item' ? "the $section entry"
2543                   :                   "the section on $section"
2544                   )
2545                   . (
2546                   $page
2547                   ? ( $section ? ' in ' : '' ) . "the $page$page_ext manpage"
2548                   : ' elsewhere in this document'
2549                   );
2550
2551               # perltidy -pbp -ci=2
2552               $self->{_text} = (
2553                    !$section        ? ''
2554                   : $type eq 'item' ? "the $section entry"
2555                   :                   "the section on $section"
2556                 )
2557                 . (
2558                   $page
2559                   ? ( $section ? ' in ' : '' ) . "the $page$page_ext manpage"
2560                   : ' elsewhere in this document'
2561                 );
2562
2563   Controlling Vertical Alignment
2564       Vertical alignment refers to lining up certain symbols in list of
2565       consecutive similar lines to improve readability.  For example, the
2566       "fat commas" are aligned in the following statement:
2567
2568               $data = $pkg->new(
2569                   PeerAddr => join( ".", @port[ 0 .. 3 ] ),
2570                   PeerPort => $port[4] * 256 + $port[5],
2571                   Proto    => 'tcp'
2572               );
2573
2574       The only explicit control on vertical alignment is to turn it off using
2575       -novalign, a flag mainly intended for debugging.  However, vertical
2576       alignment can be forced to stop and restart by selectively introducing
2577       blank lines.  For example, a blank has been inserted in the following
2578       code to keep somewhat similar things aligned.
2579
2580           %option_range = (
2581               'format'             => [ 'tidy', 'html', 'user' ],
2582               'output-line-ending' => [ 'dos',  'win',  'mac', 'unix' ],
2583               'character-encoding' => [ 'none', 'utf8' ],
2584
2585               'block-brace-tightness'    => [ 0, 2 ],
2586               'brace-tightness'          => [ 0, 2 ],
2587               'paren-tightness'          => [ 0, 2 ],
2588               'square-bracket-tightness' => [ 0, 2 ],
2589           );
2590
2591   Other Controls
2592       Deleting selected text
2593           Perltidy can selectively delete comments and/or pod documentation.
2594           The command -dac or  --delete-all-comments will delete all comments
2595           and all pod documentation, leaving just code and any leading system
2596           control lines.
2597
2598           The command -dp or --delete-pod will remove all pod documentation
2599           (but not comments).
2600
2601           Two commands which remove comments (but not pod) are: -dbc or
2602           --delete-block-comments and -dsc or  --delete-side-comments.
2603           (Hanging side comments will be deleted with block comments here.)
2604
2605           The negatives of these commands also work, and are the defaults.
2606           When block comments are deleted, any leading 'hash-bang' will be
2607           retained.  Also, if the -x flag is used, any system commands before
2608           a leading hash-bang will be retained (even if they are in the form
2609           of comments).
2610
2611       Writing selected text to a file
2612           When perltidy writes a formatted text file, it has the ability to
2613           also send selected text to a file with a .TEE extension.  This text
2614           can include comments and pod documentation.
2615
2616           The command -tac or  --tee-all-comments will write all comments and
2617           all pod documentation.
2618
2619           The command -tp or --tee-pod will write all pod documentation (but
2620           not comments).
2621
2622           The commands which write comments (but not pod) are: -tbc or
2623           --tee-block-comments and -tsc or  --tee-side-comments.  (Hanging
2624           side comments will be written with block comments here.)
2625
2626           The negatives of these commands also work, and are the defaults.
2627
2628       Using a .perltidyrc command file
2629           If you use perltidy frequently, you probably won't be happy until
2630           you create a .perltidyrc file to avoid typing commonly-used
2631           parameters.  Perltidy will first look in your current directory for
2632           a command file named .perltidyrc.  If it does not find one, it will
2633           continue looking for one in other standard locations.
2634
2635           These other locations are system-dependent, and may be displayed
2636           with the command "perltidy -dpro".  Under Unix systems, it will
2637           first look for an environment variable PERLTIDY.  Then it will look
2638           for a .perltidyrc file in the home directory, and then for a
2639           system-wide file /usr/local/etc/perltidyrc, and then it will look
2640           for /etc/perltidyrc.  Note that these last two system-wide files do
2641           not have a leading dot.  Further system-dependent information will
2642           be found in the INSTALL file distributed with perltidy.
2643
2644           Under Windows, perltidy will also search for a configuration file
2645           named perltidy.ini since Windows does not allow files with a
2646           leading period (.).  Use "perltidy -dpro" to see the possible
2647           locations for your system.  An example might be C:\Documents and
2648           Settings\All Users\perltidy.ini.
2649
2650           Another option is the use of the PERLTIDY environment variable.
2651           The method for setting environment variables depends upon the
2652           version of Windows that you are using.  Instructions for Windows 95
2653           and later versions can be found here:
2654
2655           http://www.netmanage.com/000/20021101_005_tcm21-6336.pdf
2656
2657           Under Windows NT / 2000 / XP the PERLTIDY environment variable can
2658           be placed in either the user section or the system section.  The
2659           later makes the configuration file common to all users on the
2660           machine.  Be sure to enter the full path of the configuration file
2661           in the value of the environment variable.  Ex.
2662           PERLTIDY=C:\Documents and Settings\perltidy.ini
2663
2664           The configuration file is free format, and simply a list of
2665           parameters, just as they would be entered on a command line.  Any
2666           number of lines may be used, with any number of parameters per
2667           line, although it may be easiest to read with one parameter per
2668           line.  Comment text begins with a #, and there must also be a space
2669           before the # for side comments.  It is a good idea to put complex
2670           parameters in either single or double quotes.
2671
2672           Here is an example of a .perltidyrc file:
2673
2674             # This is a simple of a .perltidyrc configuration file
2675             # This implements a highly spaced style
2676             -se    # errors to standard error output
2677             -w     # show all warnings
2678             -bl    # braces on new lines
2679             -pt=0  # parens not tight at all
2680             -bt=0  # braces not tight
2681             -sbt=0 # square brackets not tight
2682
2683           The parameters in the .perltidyrc file are installed first, so any
2684           parameters given on the command line will have priority over them.
2685
2686           To avoid confusion, perltidy ignores any command in the .perltidyrc
2687           file which would cause some kind of dump and an exit.  These are:
2688
2689            -h -v -ddf -dln -dop -dsn -dtt -dwls -dwrs -ss
2690
2691           There are several options may be helpful in debugging a .perltidyrc
2692           file:
2693
2694           ·   A very helpful command is --dump-profile or -dpro.  It writes a
2695               list of all configuration filenames tested to standard output,
2696               and if a file is found, it dumps the content to standard output
2697               before exiting.  So, to find out where perltidy looks for its
2698               configuration files, and which one if any it selects, just
2699               enter
2700
2701                 perltidy -dpro
2702
2703           ·   It may be simplest to develop and test configuration files with
2704               alternative names, and invoke them with -pro=filename on the
2705               command line.  Then rename the desired file to .perltidyrc when
2706               finished.
2707
2708           ·   The parameters in the .perltidyrc file can be switched off with
2709               the -npro option.
2710
2711           ·   The commands --dump-options, --dump-defaults,
2712               --dump-long-names, and --dump-short-names, all described below,
2713               may all be helpful.
2714
2715       Creating a new abbreviation
2716           A special notation is available for use in a .perltidyrc file for
2717           creating an abbreviation for a group of options.  This can be used
2718           to create a shorthand for one or more styles which are frequently,
2719           but not always, used.  The notation is to group the options within
2720           curly braces which are preceded by the name of the alias (without
2721           leading dashes), like this:
2722
2723                   newword {
2724                   -opt1
2725                   -opt2
2726                   }
2727
2728           where newword is the abbreviation, and opt1, etc, are existing
2729           parameters or other abbreviations.  The main syntax requirement is
2730           that the new abbreviation along with its opening curly brace must
2731           begin on a new line.  Space before and after the curly braces is
2732           optional.  For a specific example, the following line
2733
2734                   airy {-bl -pt=0 -bt=0 -sbt=0}
2735
2736           could be placed in a .perltidyrc file, and then invoked at will
2737           with
2738
2739                   perltidy -airy somefile.pl
2740
2741           (Either "-airy" or "--airy" may be used).
2742
2743       Skipping leading non-perl commands with -x or --look-for-hash-bang
2744           If your script has leading lines of system commands or other text
2745           which are not valid perl code, and which are separated from the
2746           start of the perl code by a "hash-bang" line, ( a line of the form
2747           "#!...perl" ), you must use the -x flag to tell perltidy not to
2748           parse and format any lines before the "hash-bang" line.  This
2749           option also invokes perl with a -x flag when checking the syntax.
2750           This option was originally added to allow perltidy to parse
2751           interactive VMS scripts, but it should be used for any script which
2752           is normally invoked with "perl -x".
2753
2754       Making a file unreadable
2755           The goal of perltidy is to improve the readability of files, but
2756           there are two commands which have the opposite effect, --mangle and
2757           --extrude.  They are actually merely aliases for combinations of
2758           other parameters.  Both of these strip all possible whitespace, but
2759           leave comments and pod documents, so that they are essentially
2760           reversible.  The difference between these is that --mangle puts the
2761           fewest possible line breaks in a script while --extrude puts the
2762           maximum possible.  Note that these options do not provided any
2763           meaningful obfuscation, because perltidy can be used to reformat
2764           the files.  They were originally developed to help test the
2765           tokenization logic of perltidy, but they have other uses.  One use
2766           for --mangle is the following:
2767
2768             perltidy --mangle myfile.pl -st | perltidy -o myfile.pl.new
2769
2770           This will form the maximum possible number of one-line blocks (see
2771           next section), and can sometimes help clean up a badly formatted
2772           script.
2773
2774           A similar technique can be used with --extrude instead of --mangle
2775           to make the minimum number of one-line blocks.
2776
2777           Another use for --mangle is to combine it with -dac to reduce the
2778           file size of a perl script.
2779
2780       One-line blocks
2781           There are a few points to note regarding one-line blocks.  A one-
2782           line block is something like this,
2783
2784                   if ($x > 0) { $y = 1 / $x }
2785
2786           where the contents within the curly braces is short enough to fit
2787           on a single line.
2788
2789           With few exceptions, perltidy retains existing one-line blocks, if
2790           it is possible within the line-length constraint, but it does not
2791           attempt to form new ones.  In other words, perltidy will try to
2792           follow the one-line block style of the input file.
2793
2794           If an existing one-line block is longer than the maximum line
2795           length, however, it will be broken into multiple lines.  When this
2796           happens, perltidy checks for and adds any optional terminating
2797           semicolon (unless the -nasc option is used) if the block is a code
2798           block.
2799
2800           The main exception is that perltidy will attempt to form new one-
2801           line blocks following the keywords "map", "eval", and "sort",
2802           because these code blocks are often small and most clearly
2803           displayed in a single line.
2804
2805           One-line block rules can conflict with the cuddled-else option.
2806           When the cuddled-else option is used, perltidy retains existing
2807           one-line blocks, even if they do not obey cuddled-else formatting.
2808
2809           Occasionally, when one-line blocks get broken because they exceed
2810           the available line length, the formatting will violate the
2811           requested brace style.  If this happens, reformatting the script a
2812           second time should correct the problem.
2813
2814       Debugging
2815           The following flags are available for debugging:
2816
2817           --dump-cuddled-block-list or -dcbl will dump to standard output the
2818           internal hash of cuddled block types created by a
2819           -cuddled-block-list input string.
2820
2821           --dump-defaults or -ddf will write the default option set to
2822           standard output and quit
2823
2824           --dump-profile or -dpro  will write the name of the current
2825           configuration file and its contents to standard output and quit.
2826
2827           --dump-options or -dop  will write current option set to standard
2828           output and quit.
2829
2830           --dump-long-names or -dln  will write all command line long names
2831           (passed to Get_options) to standard output and quit.
2832
2833           --dump-short-names  or -dsn will write all command line short names
2834           to standard output and quit.
2835
2836           --dump-token-types or -dtt  will write a list of all token types to
2837           standard output and quit.
2838
2839           --dump-want-left-space or -dwls  will write the hash
2840           %want_left_space to standard output and quit.  See the section on
2841           controlling whitespace around tokens.
2842
2843           --dump-want-right-space or -dwrs  will write the hash
2844           %want_right_space to standard output and quit.  See the section on
2845           controlling whitespace around tokens.
2846
2847           --no-memoize or -nmem  will turn of memoizing.  Memoization can
2848           reduce run time when running perltidy repeatedly in a single
2849           process.  It is on by default but can be deactivated for testing
2850           with -nmem.
2851
2852           --no-timestamp or -nts will eliminate any time stamps in output
2853           files to prevent differences in dates from causing test
2854           installation scripts to fail. There are just a couple of places
2855           where timestamps normally occur. One is in the headers of html
2856           files, and another is when the -cscw option is selected. The
2857           default is to allow timestamps (--timestamp or -ts).
2858
2859           --file-size-order or -fso will cause files to be processed in order
2860           of increasing size, when multiple files are being processed.  This
2861           is useful during program development, when large numbers of files
2862           with varying sizes are processed, because it can reduce virtual
2863           memory usage.
2864
2865           -DEBUG  will write a file with extension .DEBUG for each input file
2866           showing the tokenization of all lines of code.
2867
2868       Working with MakeMaker, AutoLoader and SelfLoader
2869           The first $VERSION line of a file which might be eval'd by
2870           MakeMaker is passed through unchanged except for indentation.  Use
2871           --nopass-version-line, or -npvl, to deactivate this feature.
2872
2873           If the AutoLoader module is used, perltidy will continue formatting
2874           code after seeing an __END__ line.  Use --nolook-for-autoloader, or
2875           -nlal, to deactivate this feature.
2876
2877           Likewise, if the SelfLoader module is used, perltidy will continue
2878           formatting code after seeing a __DATA__ line.  Use
2879           --nolook-for-selfloader, or -nlsl, to deactivate this feature.
2880
2881       Working around problems with older version of Perl
2882           Perltidy contains a number of rules which help avoid known
2883           subtleties and problems with older versions of perl, and these
2884           rules always take priority over whatever formatting flags have been
2885           set.  For example, perltidy will usually avoid starting a new line
2886           with a bareword, because this might cause problems if "use strict"
2887           is active.
2888
2889           There is no way to override these rules.
2890

HTML OPTIONS

2892       The -html master switch
2893           The flag -html causes perltidy to write an html file with extension
2894           .html.  So, for example, the following command
2895
2896                   perltidy -html somefile.pl
2897
2898           will produce a syntax-colored html file named somefile.pl.html
2899           which may be viewed with a browser.
2900
2901           Please Note: In this case, perltidy does not do any formatting to
2902           the input file, and it does not write a formatted file with
2903           extension .tdy.  This means that two perltidy runs are required to
2904           create a fully reformatted, html copy of a script.
2905
2906       The -pre flag for code snippets
2907           When the -pre flag is given, only the pre-formatted section, within
2908           the <PRE> and </PRE> tags, will be output.  This simplifies
2909           inclusion of the output in other files.  The default is to output a
2910           complete web page.
2911
2912       The -nnn flag for line numbering
2913           When the -nnn flag is given, the output lines will be numbered.
2914
2915       The -toc, or --html-table-of-contents flag
2916           By default, a table of contents to packages and subroutines will be
2917           written at the start of html output.  Use -ntoc to prevent this.
2918           This might be useful, for example, for a pod document which
2919           contains a number of unrelated code snippets.  This flag only
2920           influences the code table of contents; it has no effect on any
2921           table of contents produced by pod2html (see next item).
2922
2923       The -pod, or --pod2html flag
2924           There are two options for formatting pod documentation.  The
2925           default is to pass the pod through the Pod::Html module (which
2926           forms the basis of the pod2html utility).  Any code sections are
2927           formatted by perltidy, and the results then merged.  Note: perltidy
2928           creates a temporary file when Pod::Html is used; see "FILES".
2929           Also, Pod::Html creates temporary files for its cache.
2930
2931           NOTE: Perltidy counts the number of "=cut" lines, and either moves
2932           the pod text to the top of the html file if there is one "=cut", or
2933           leaves the pod text in its original order (interleaved with code)
2934           otherwise.
2935
2936           Most of the flags accepted by pod2html may be included in the
2937           perltidy command line, and they will be passed to pod2html.  In
2938           some cases, the flags have a prefix "pod" to emphasize that they
2939           are for the pod2html, and this prefix will be removed before they
2940           are passed to pod2html.  The flags which have the additional "pod"
2941           prefix are:
2942
2943              --[no]podheader --[no]podindex --[no]podrecurse --[no]podquiet
2944              --[no]podverbose --podflush
2945
2946           The flags which are unchanged from their use in pod2html are:
2947
2948              --backlink=s --cachedir=s --htmlroot=s --libpods=s --title=s
2949              --podpath=s --podroot=s
2950
2951           where 's' is an appropriate character string.  Not all of these
2952           flags are available in older versions of Pod::Html.  See your
2953           Pod::Html documentation for more information.
2954
2955           The alternative, indicated with -npod, is not to use Pod::Html, but
2956           rather to format pod text in italics (or whatever the stylesheet
2957           indicates), without special html markup.  This is useful, for
2958           example, if pod is being used as an alternative way to write
2959           comments.
2960
2961       The -frm, or --frames flag
2962           By default, a single html output file is produced.  This can be
2963           changed with the -frm option, which creates a frame holding a table
2964           of contents in the left panel and the source code in the right
2965           side. This simplifies code browsing.  Assume, for example, that the
2966           input file is MyModule.pm.  Then, for default file extension
2967           choices, these three files will be created:
2968
2969            MyModule.pm.html      - the frame
2970            MyModule.pm.toc.html  - the table of contents
2971            MyModule.pm.src.html  - the formatted source code
2972
2973           Obviously this file naming scheme requires that output be directed
2974           to a real file (as opposed to, say, standard output).  If this is
2975           not the case, or if the file extension is unknown, the -frm option
2976           will be ignored.
2977
2978       The -text=s, or --html-toc-extension flag
2979           Use this flag to specify the extra file extension of the table of
2980           contents file when html frames are used.  The default is "toc".
2981           See "Specifying File Extensions".
2982
2983       The -sext=s, or --html-src-extension flag
2984           Use this flag to specify the extra file extension of the content
2985           file when html frames are used.  The default is "src".  See
2986           "Specifying File Extensions".
2987
2988       The -hent, or --html-entities flag
2989           This flag controls the use of Html::Entities for html formatting.
2990           By default, the module Html::Entities is used to encode special
2991           symbols.  This may not be the right thing for some browser/language
2992           combinations.  Use --nohtml-entities or -nhent to prevent this.
2993
2994       Style Sheets
2995           Style sheets make it very convenient to control and adjust the
2996           appearance of html pages.  The default behavior is to write a page
2997           of html with an embedded style sheet.
2998
2999           An alternative to an embedded style sheet is to create a page with
3000           a link to an external style sheet.  This is indicated with the
3001           -css=filename,  where the external style sheet is filename.  The
3002           external style sheet filename will be created if and only if it
3003           does not exist.  This option is useful for controlling multiple
3004           pages from a single style sheet.
3005
3006           To cause perltidy to write a style sheet to standard output and
3007           exit, use the -ss, or --stylesheet, flag.  This is useful if the
3008           style sheet could not be written for some reason, such as if the
3009           -pre flag was used.  Thus, for example,
3010
3011             perltidy -html -ss >mystyle.css
3012
3013           will write a style sheet with the default properties to file
3014           mystyle.css.
3015
3016           The use of style sheets is encouraged, but a web page without a
3017           style sheets can be created with the flag -nss.  Use this option if
3018           you must to be sure that older browsers (roughly speaking, versions
3019           prior to 4.0 of Netscape Navigator and Internet Explorer) can
3020           display the syntax-coloring of the html files.
3021
3022       Controlling HTML properties
3023           Note: It is usually more convenient to accept the default
3024           properties and then edit the stylesheet which is produced.
3025           However, this section shows how to control the properties with
3026           flags to perltidy.
3027
3028           Syntax colors may be changed from their default values by flags of
3029           the either the long form, -html-color-xxxxxx=n, or more
3030           conveniently the short form, -hcx=n, where xxxxxx is one of the
3031           following words, and x is the corresponding abbreviation:
3032
3033                 Token Type             xxxxxx           x
3034                 ----------             --------         --
3035                 comment                comment          c
3036                 number                 numeric          n
3037                 identifier             identifier       i
3038                 bareword, function     bareword         w
3039                 keyword                keyword          k
3040                 quite, pattern         quote            q
3041                 here doc text          here-doc-text    h
3042                 here doc target        here-doc-target  hh
3043                 punctuation            punctuation      pu
3044                 parentheses            paren            p
3045                 structural braces      structure        s
3046                 semicolon              semicolon        sc
3047                 colon                  colon            co
3048                 comma                  comma            cm
3049                 label                  label            j
3050                 sub definition name    subroutine       m
3051                 pod text               pod-text         pd
3052
3053           A default set of colors has been defined, but they may be changed
3054           by providing values to any of the following parameters, where n is
3055           either a 6 digit hex RGB color value or an ascii name for a color,
3056           such as 'red'.
3057
3058           To illustrate, the following command will produce an html file
3059           somefile.pl.html with "aqua" keywords:
3060
3061                   perltidy -html -hck=00ffff somefile.pl
3062
3063           and this should be equivalent for most browsers:
3064
3065                   perltidy -html -hck=aqua somefile.pl
3066
3067           Perltidy merely writes any non-hex names that it sees in the html
3068           file.  The following 16 color names are defined in the HTML 3.2
3069           standard:
3070
3071                   black   => 000000,
3072                   silver  => c0c0c0,
3073                   gray    => 808080,
3074                   white   => ffffff,
3075                   maroon  => 800000,
3076                   red     => ff0000,
3077                   purple  => 800080,
3078                   fuchsia => ff00ff,
3079                   green   => 008000,
3080                   lime    => 00ff00,
3081                   olive   => 808000,
3082                   yellow  => ffff00
3083                   navy    => 000080,
3084                   blue    => 0000ff,
3085                   teal    => 008080,
3086                   aqua    => 00ffff,
3087
3088           Many more names are supported in specific browsers, but it is
3089           safest to use the hex codes for other colors.  Helpful color tables
3090           can be located with an internet search for "HTML color tables".
3091
3092           Besides color, two other character attributes may be set: bold, and
3093           italics.  To set a token type to use bold, use the flag
3094           --html-bold-xxxxxx or -hbx, where xxxxxx or x are the long or short
3095           names from the above table.  Conversely, to set a token type to NOT
3096           use bold, use --nohtml-bold-xxxxxx or -nhbx.
3097
3098           Likewise, to set a token type to use an italic font, use the flag
3099           --html-italic-xxxxxx or -hix, where again xxxxxx or x are the long
3100           or short names from the above table.  And to set a token type to
3101           NOT use italics, use --nohtml-italic-xxxxxx or -nhix.
3102
3103           For example, to use bold braces and lime color, non-bold, italics
3104           keywords the following command would be used:
3105
3106                   perltidy -html -hbs -hck=00FF00 -nhbk -hik somefile.pl
3107
3108           The background color can be specified with
3109           --html-color-background=n, or -hcbg=n for short, where n is a 6
3110           character hex RGB value.  The default color of text is the value
3111           given to punctuation, which is black as a default.
3112
3113           Here are some notes and hints:
3114
3115           1. If you find a preferred set of these parameters, you may want to
3116           create a .perltidyrc file containing them.  See the perltidy man
3117           page for an explanation.
3118
3119           2. Rather than specifying values for these parameters, it is
3120           probably easier to accept the defaults and then edit a style sheet.
3121           The style sheet contains comments which should make this easy.
3122
3123           3. The syntax-colored html files can be very large, so it may be
3124           best to split large files into smaller pieces to improve download
3125           times.
3126

SOME COMMON INPUT CONVENTIONS

3128   Specifying Block Types
3129       Several parameters which refer to code block types may be customized by
3130       also specifying an associated list of block types.  The type of a block
3131       is the name of the keyword which introduces that block, such as if,
3132       else, or sub.  An exception is a labeled block, which has no keyword,
3133       and should be specified with just a colon.  To specify all blocks use
3134       '*'.
3135
3136       The keyword sub indicates a named sub.  For anonymous subs, use the
3137       special keyword asub.
3138
3139       For example, the following parameter specifies "sub", labels, "BEGIN",
3140       and "END" blocks:
3141
3142          -cscl="sub : BEGIN END"
3143
3144       (the meaning of the -cscl parameter is described above.)  Note that
3145       quotes are required around the list of block types because of the
3146       spaces.  For another example, the following list specifies all block
3147       types for vertical tightness:
3148
3149          -bbvtl='*'
3150
3151   Specifying File Extensions
3152       Several parameters allow default file extensions to be overridden.  For
3153       example, a backup file extension may be specified with -bext=ext, where
3154       ext is some new extension.  In order to provides the user some
3155       flexibility, the following convention is used in all cases to decide if
3156       a leading '.' should be used.  If the extension "ext" begins with
3157       "A-Z", "a-z", or "0-9", then it will be appended to the filename with
3158       an intermediate '.' (or perhaps an '_' on VMS systems).  Otherwise, it
3159       will be appended directly.
3160
3161       For example, suppose the file is somefile.pl.  For "-bext=old", a '.'
3162       is added to give somefile.pl.old.  For "-bext=.old", no additional '.'
3163       is added, so again the backup file is somefile.pl.old.  For "-bext=~",
3164       then no dot is added, and the backup file will be somefile.pl~  .
3165

SWITCHES WHICH MAY BE NEGATED

3167       The following list shows all short parameter names which allow a prefix
3168       'n' to produce the negated form:
3169
3170        D    anl asc  aws  b    bbb bbc bbs  bl   bli  boc bok  bol  bot  ce
3171        csc  dac dbc  dcsc ddf  dln dnl dop  dp   dpro dsc dsm  dsn  dtt  dwls
3172        dwrs dws f    fll  frm  fs  hsc html ibc  icb  icp iob  isbc lal  log
3173        lp   lsl ohbr okw  ola  oll opr opt  osbr otr  ple  pod  pvl  q
3174        sbc  sbl schb scp  scsb sct se  sfp  sfs  skp  sob sohb sop  sosb sot
3175        ssc  st  sts  syn  t    tac tbc toc  tp   tqw  tsc w    x    bar  kis
3176
3177       Equivalently, the prefix 'no' or 'no-' on the corresponding long names
3178       may be used.
3179

LIMITATIONS

3181       Parsing Limitations
3182           Perltidy should work properly on most perl scripts.  It does a lot
3183           of self-checking, but still, it is possible that an error could be
3184           introduced and go undetected.  Therefore, it is essential to make
3185           careful backups and to test reformatted scripts.
3186
3187           The main current limitation is that perltidy does not scan modules
3188           included with 'use' statements.  This makes it necessary to guess
3189           the context of any bare words introduced by such modules.  Perltidy
3190           has good guessing algorithms, but they are not infallible.  When it
3191           must guess, it leaves a message in the log file.
3192
3193           If you encounter a bug, please report it.
3194
3195       What perltidy does not parse and format
3196           Perltidy indents but does not reformat comments and "qw" quotes.
3197           Perltidy does not in any way modify the contents of here documents
3198           or quoted text, even if they contain source code.  (You could,
3199           however, reformat them separately).  Perltidy does not format
3200           'format' sections in any way.  And, of course, it does not modify
3201           pod documents.
3202

FILES

3204       Temporary files
3205           Under the -html option with the default --pod2html flag, a
3206           temporary file is required to pass text to Pod::Html.  Unix systems
3207           will try to use the POSIX tmpnam() function.  Otherwise the file
3208           perltidy.TMP will be temporarily created in the current working
3209           directory.
3210
3211       Special files when standard input is used
3212           When standard input is used, the log file, if saved, is
3213           perltidy.LOG, and any errors are written to perltidy.ERR unless the
3214           -se flag is set.  These are saved in the current working directory.
3215
3216       Files overwritten
3217           The following file extensions are used by perltidy, and files with
3218           these extensions may be overwritten or deleted: .ERR, .LOG, .TEE,
3219           and/or .tdy, .html, and .bak, depending on the run type and
3220           settings.
3221
3222       Files extensions limitations
3223           Perltidy does not operate on files for which the run could produce
3224           a file with a duplicated file extension.  These extensions include
3225           .LOG, .ERR, .TEE, and perhaps .tdy and .bak, depending on the run
3226           type.  The purpose of this rule is to prevent generating confusing
3227           filenames such as somefile.tdy.tdy.tdy.
3228

SEE ALSO

3230       perlstyle(1), Perl::Tidy(3)
3231

VERSION

3233       This man page documents perltidy version 20181120
3234

BUG REPORTS

3236       A list of current bugs and issues can be found at the CPAN site
3237       <https://rt.cpan.org/Public/Dist/Display.html?Name=Perl-Tidy>
3238
3239       To report a new bug or problem, use the link on this page.
3240
3241       The source code repository is at
3242       <https://github.com/perltidy/perltidy>.
3243
3245       Copyright (c) 2000-2018 by Steve Hancock
3246

LICENSE

3248       This package is free software; you can redistribute it and/or modify it
3249       under the terms of the "GNU General Public License".
3250
3251       Please refer to the file "COPYING" for details.
3252

DISCLAIMER

3254       This package is distributed in the hope that it will be useful, but
3255       WITHOUT ANY WARRANTY; without even the implied warranty of
3256       MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
3257
3258       See the "GNU General Public License" for more details.
3259
3260
3261
3262perl v5.28.1                      2018-11-19                       PERLTIDY(1)
Impressum