1PERLTIDY(1) User Contributed Perl Documentation PERLTIDY(1)
2
6 perltidy - a perl script indenter and reformatter
7
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
16 Perltidy reads a perl script and writes an indented, reformatted
17 script.
18 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 A convenient aid to systematically defining a set of style parameters
24 can be found at http://perltidy.sourceforge.net/stylekey.html
25 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 When the -html flag is given, the output is passed through an HTML
34 formatter which is described in "HTML OPTIONS".
35
37 perltidy somefile.pl
38 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 perltidy *.pl
44 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 perltidy -b file1.pl file2.pl
51 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 perltidy -b -bext='/' file1.pl file2.pl
57 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 perltidy -gnu somefile.pl
62 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 perltidy -i=3 somefile.pl
68 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 perltidy -i=3 -et=8 somefile.pl
76 Same as the previous example, except that leading whitespace will be
78 entabbed with one tab character per 8 spaces.
79 perltidy -ce -l=72 somefile.pl
81 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 perltidy -g somefile.pl
87 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 perltidy -html somefile.pl
93 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 perltidy -html -css=mystyle.css somefile.pl
99 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 perltidy -html -pre somefile.pl
106 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 perltidy -html -ss >mystyle.css
112 Write a style sheet to mystyle.css and exit.
114 perltidy -html -frm mymodule.pm
116 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
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 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 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 Options may not be bundled together. In other words, options -q and -g
141 may NOT be entered as -qg.
142 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 I/O control
149 The following parameters concern the files which are read and written.
150 -h, --help
152 Show summary of usage and exit.
153 -o=filename, --outfile=filename
155 Name of the output file (only if a single input file is being
156 processed). If no output file is specified, and output is not
157 redirected to the standard output (see -st), the output will go to
158 filename.tdy. [Note: - does not redirect to standard output. Use
159 -st instead.]
160 -st, --standard-output
162 Perltidy must be able to operate on an arbitrarily large number of
163 files in a single run, with each output being directed to a
164 different output file. Obviously this would conflict with
165 outputting to the single standard output device, so a special flag,
166 -st, is required to request outputting to the standard output. For
167 example,
168 perltidy somefile.pl -st >somefile.new.pl
170 This option may only be used if there is just a single input file.
172 The default is -nst or --nostandard-output.
173 -se, --standard-error-output
175 If perltidy detects an error when processing file somefile.pl, its
176 default behavior is to write error messages to file
177 somefile.pl.ERR. Use -se to cause all error messages to be sent to
178 the standard error output stream instead. This directive may be
179 negated with -nse. Thus, you may place -se in a .perltidyrc and
180 override it when desired with -nse on the command line.
181 -oext=ext, --output-file-extension=ext
183 Change the extension of the output file to be ext instead of the
184 default tdy (or html in case the --html option is used). See
185 "Specifying File Extensions".
186 -opath=path, --output-path=path
188 When perltidy creates a filename for an output file, by default it
189 merely appends an extension to the path and basename of the input
190 file. This parameter causes the path to be changed to path
191 instead.
192 The path should end in a valid path separator character, but
194 perltidy will try to add one if it is missing.
195 For example
197 perltidy somefile.pl -opath=/tmp/
199 will produce /tmp/somefile.pl.tdy. Otherwise, somefile.pl.tdy will
201 appear in whatever directory contains somefile.pl.
202 If the path contains spaces, it should be placed in quotes.
204 This parameter will be ignored if output is being directed to
206 standard output, or if it is being specified explicitly with the
207 -o=s parameter.
208 -b, --backup-and-modify-in-place
210 Modify the input file or files in-place and save the original with
211 the extension .bak. Any existing .bak file will be deleted. See
212 next item for changing the default backup extension, and for
213 eliminating the backup file altogether.
214 A -b flag will be ignored if input is from standard input or goes
216 to standard output, or if the -html flag is set.
217 In particular, if you want to use both the -b flag and the -pbp
219 (--perl-best-practices) flag, then you must put a -nst flag after
220 the -pbp flag because it contains a -st flag as one of its
221 components, which means that output will go to the standard output
222 stream.
223 -bext=ext, --backup-file-extension=ext
225 This parameter serves two purposes: (1) to change the extension of
226 the backup file to be something other than the default .bak, and
227 (2) to indicate that no backup file should be saved.
228 To change the default extension to something other than .bak see
230 "Specifying File Extensions".
231 A backup file of the source is always written, but you can request
233 that it be deleted at the end of processing if there were no
234 errors. This is risky unless the source code is being maintained
235 with a source code control system.
236 To indicate that the backup should be deleted include one forward
238 slash, /, in the extension. If any text remains after the slash is
239 removed it will be used to define the backup file extension (which
240 is always created and only deleted if there were no errors).
241 Here are some examples:
243 Parameter Extension Backup File Treatment
245 <-bext=bak> F<.bak> Keep (same as the default behavior)
246 <-bext='/'> F<.bak> Delete if no errors
247 <-bext='/backup'> F<.backup> Delete if no errors
248 <-bext='original/'> F<.original> Delete if no errors
249 -w, --warning-output
251 Setting -w causes any non-critical warning messages to be reported
252 as errors. These include messages about possible pod problems,
253 possibly bad starting indentation level, and cautions about
254 indirect object usage. The default, -nw or --nowarning-output, is
255 not to include these warnings.
256 -q, --quiet
258 Deactivate error messages and syntax checking (for running under an
259 editor).
260 For example, if you use a vi-style editor, such as vim, you may
262 execute perltidy as a filter from within the editor using something
263 like
264 :n1,n2!perltidy -q
266 where "n1,n2" represents the selected text. Without the -q flag,
268 any error message may mess up your screen, so be prepared to use
269 your "undo" key.
270 -log, --logfile
272 Save the .LOG file, which has many useful diagnostics. Perltidy
273 always creates a .LOG file, but by default it is deleted unless a
274 program bug is suspected. Setting the -log flag forces the log
275 file to be saved.
276 -g=n, --logfile-gap=n
278 Set maximum interval between input code lines in the logfile. This
279 purpose of this flag is to assist in debugging nesting errors. The
280 value of "n" is optional. If you set the flag -g without the value
281 of "n", it will be taken to be 1, meaning that every line will be
282 written to the log file. This can be helpful if you are looking
283 for a brace, paren, or bracket nesting error.
284 Setting -g also causes the logfile to be saved, so it is not
286 necessary to also include -log.
287 If no -g flag is given, a value of 50 will be used, meaning that at
289 least every 50th line will be recorded in the logfile. This helps
290 prevent excessively long log files.
291 Setting a negative value of "n" is the same as not setting -g at
293 all.
294 -npro --noprofile
296 Ignore any .perltidyrc command file. Normally, perltidy looks
297 first in your current directory for a .perltidyrc file of
298 parameters. (The format is described below). If it finds one, it
299 applies those options to the initial default values, and then it
300 applies any that have been defined on the command line. If no
301 .perltidyrc file is found, it looks for one in your home directory.
302 If you set the -npro flag, perltidy will not look for this file.
304 -pro=filename or --profile=filename
306 To simplify testing and switching .perltidyrc files, this command
307 may be used to specify a configuration file which will override the
308 default name of .perltidyrc. There must not be a space on either
309 side of the '=' sign. For example, the line
310 perltidy -pro=testcfg
312 would cause file testcfg to be used instead of the default
314 .perltidyrc.
315 A pathname begins with three dots, e.g. ".../.perltidyrc",
317 indicates that the file should be searched for starting in the
318 current directory and working upwards. This makes it easier to have
319 multiple projects each with their own .perltidyrc in their root
320 directories.
321 -opt, --show-options
323 Write a list of all options used to the .LOG file. Please see
324 --dump-options for a simpler way to do this.
325 -f, --force-read-binary
327 Force perltidy to process binary files. To avoid producing
328 excessive error messages, perltidy skips files identified by the
329 system as non-text. However, valid perl scripts containing binary
330 data may sometimes be identified as non-text, and this flag forces
331 perltidy to process them.
332 -ast, --assert-tidy
334 This flag asserts that the input and output code streams are
335 identical, or in other words that the input code is already 'tidy'
336 according to the formatting parameters. If this is not the case,
337 an error message noting this is produced. This error message will
338 cause the process to return a non-zero exit code. The test for
339 this is made by comparing an MD5 hash value for the input and
340 output code streams. This flag has no other effect on the
341 functioning of perltidy. This might be useful for certain code
342 maintenance operations.
343 -asu, --assert-untidy
345 This flag asserts that the input and output code streams are
346 different, or in other words that the input code is 'untidy'
347 according to the formatting parameters. If this is not the case,
348 an error message noting this is produced. This flag has no other
349 effect on the functioning of perltidy.
350 -sal=s, --sub-alias-list=s
352 This flag causes one or more words to be treated the same as if
353 they were the keyword 'sub'. The string s contains one or more
354 alias words, separated by spaces or commas.
355 For example,
357 perltidy -sal='method fun _sub M4'
359 will cause the perltidy to treate the words 'method', 'fun', '_sub'
361 and 'M4' to be treated the same as if they were 'sub'. Note that
362 if the alias words are separated by spaces then the string of words
363 should be placed in quotes.
364 Note that several other parameters accept a list of keywords,
366 including 'sub' (see "Specifying Block Types"). You do not need to
367 include any sub aliases in these lists. Just include keyword 'sub'
368 if you wish, and all aliases are automatically included.
369
371 Basic Options
372 --notidy
373 This flag disables all formatting and causes the input to be copied
374 unchanged to the output except for possible changes in line ending
375 characters and any pre- and post-filters. This can be useful in
376 conjunction with a hierarchical set of .perltidyrc files to avoid
377 unwanted code tidying. See also "Skipping Selected Sections of
378 Code" for a way to avoid tidying specific sections of code.
379 -i=n, --indent-columns=n
381 Use n columns per indentation level (default n=4).
382 -l=n, --maximum-line-length=n
384 The default maximum line length is n=80 characters. Perltidy will
385 try to find line break points to keep lines below this length.
386 However, long quotes and side comments may cause lines to exceed
387 this length. Setting -l=0 is equivalent to setting -l=(a large
388 number).
389 -vmll, --variable-maximum-line-length
391 A problem arises using a fixed maximum line length with very deeply
392 nested code and data structures because eventually the amount of
393 leading whitespace used for indicating indentation takes up most or
394 all of the available line width, leaving little or no space for the
395 actual code or data. One solution is to use a vary long line
396 length. Another solution is to use the -vmll flag, which basically
397 tells perltidy to ignore leading whitespace when measuring the line
398 length.
399 To be precise, when the -vmll parameter is set, the maximum line
401 length of a line of code will be M+L*I, where
402 M is the value of --maximum-line-length=M (-l=M), default 80,
404 I is the value of --indent-columns=I (-i=I), default 4,
405 L is the indentation level of the line of code
406 When this flag is set, the choice of breakpoints for a block of
408 code should be essentially independent of its nesting depth.
409 However, the absolute line lengths, including leading whitespace,
410 can still be arbitrarily large. This problem can be avoided by
411 including the next parameter.
412 The default is not to do this (-nvmll).
414 -wc=n, --whitespace-cycle=n
416 This flag also addresses problems with very deeply nested code and
417 data structures. When the nesting depth exceeds the value n the
418 leading whitespace will be reduced and start at a depth of 1 again.
419 The result is that blocks of code will shift back to the left
420 rather than moving arbitrarily far to the right. This occurs
421 cyclically to any depth.
422 For example if one level of indentation equals 4 spaces (-i=4, the
424 default), and one uses -wc=15, then if the leading whitespace on a
425 line exceeds about 4*15=60 spaces it will be reduced back to 4*1=4
426 spaces and continue increasing from there. If the whitespace never
427 exceeds this limit the formatting remains unchanged.
428 The combination of -vmll and -wc=n provides a solution to the
430 problem of displaying arbitrarily deep data structures and code in
431 a finite window, although -wc=n may of course be used without
432 -vmll.
433 The default is not to use this, which can also be indicated using
435 -wc=0.
436 tabs
438 Using tab characters will almost certainly lead to future
439 portability and maintenance problems, so the default and
440 recommendation is not to use them. For those who prefer tabs,
441 however, there are two different options.
442 Except for possibly introducing tab indentation characters, as
444 outlined below, perltidy does not introduce any tab characters into
445 your file, and it removes any tabs from the code (unless requested
446 not to do so with -fws). If you have any tabs in your comments,
447 quotes, or here-documents, they will remain.
448 -et=n, --entab-leading-whitespace
450 This flag causes each n initial space characters to be replaced
451 by one tab character. Note that the integer n is completely
452 independent of the integer specified for indentation parameter,
453 -i=n.
454 -t, --tabs
456 This flag causes one leading tab character to be inserted for
457 each level of indentation. Certain other features are
458 incompatible with this option, and if these options are also
459 given, then a warning message will be issued and this flag will
460 be unset. One example is the -lp option.
461 -dt=n, --default-tabsize=n
463 If the first line of code passed to perltidy contains leading
464 tabs but no tab scheme is specified for the output stream then
465 perltidy must guess how many spaces correspond to each leading
466 tab. This number of spaces n corresponding to each leading tab
467 of the input stream may be specified with -dt=n. The default
468 is n=8.
469 This flag has no effect if a tab scheme is specified for the
471 output stream, because then the input stream is assumed to use
472 the same tab scheme and indentation spaces as for the output
473 stream (any other assumption would lead to unstable editing).
474 -syn, --check-syntax
476 This flag is now ignored for safety, but the following
477 documentation has been retained for reference.
478 This flag causes perltidy to run "perl -c -T" to check syntax of
480 input and output. (To change the flags passed to perl, see the
481 next item, -pscf). The results are written to the .LOG file, which
482 will be saved if an error is detected in the output script. The
483 output script is not checked if the input script has a syntax
484 error. Perltidy does its own checking, but this option employs
485 perl to get a "second opinion".
486 If perl reports errors in the input file, they will not be reported
488 in the error output unless the --warning-output flag is given.
489 The default is NOT to do this type of syntax checking (although
491 perltidy will still do as much self-checking as possible). The
492 reason is that it causes all code in BEGIN blocks to be executed,
493 for all modules being used, and this opens the door to security
494 issues and infinite loops when running perltidy.
495 -pscf=s, -perl-syntax-check-flags=s
497 When perl is invoked to check syntax, the normal flags are "-c -T".
498 In addition, if the -x flag is given to perltidy, then perl will
499 also be passed a -x flag. It should not normally be necessary to
500 change these flags, but it can be done with the -pscf=s flag. For
501 example, if the taint flag, "-T", is not wanted, the flag could be
502 set to be just -pscf=-c.
503 Perltidy will pass your string to perl with the exception that it
505 will add a -c and -x if appropriate. The .LOG file will show
506 exactly what flags were passed to perl.
507 -xs, --extended-syntax
509 A problem with formatting Perl code is that some modules can
510 introduce new syntax. This flag allows perltidy to handle certain
511 common extensions to the standard syntax without complaint.
512 For example, without this flag a structure such as the following
514 would generate a syntax error and the braces would not be balanced:
515 method deposit( Num $amount) {
517 $self->balance( $self->balance + $amount );
518 }
519 For one of the extensions, module Switch::Plain, colons are marked
521 as labels. If you use this module, you may want to also use the
522 --nooutdent-labels flag to prevent lines such as 'default:' from
523 being outdented.
524 This flag is enabled by default but it can be deactivated with
526 -nxs. Probably the only reason to deactivate this flag is to
527 generate more diagnostic messages when debugging a script.
528 -io, --indent-only
530 This flag is used to deactivate all whitespace and line break
531 changes within non-blank lines of code. When it is in effect, the
532 only change to the script will be to the indentation and to the
533 number of blank lines. And any flags controlling whitespace and
534 newlines will be ignored. You might want to use this if you are
535 perfectly happy with your whitespace and line breaks, and merely
536 want perltidy to handle the indentation. (This also speeds up
537 perltidy by well over a factor of two, so it might be useful when
538 perltidy is merely being used to help find a brace error in a large
539 script).
540 Setting this flag is equivalent to setting --freeze-newlines and
542 --freeze-whitespace.
543 If you also want to keep your existing blank lines exactly as they
545 are, you can add --freeze-blank-lines.
546 With this option perltidy is still free to modify the indenting
548 (and outdenting) of code and comments as it normally would. If you
549 also want to prevent long comment lines from being outdented, you
550 can add either -noll or -l=0.
551 Setting this flag will prevent perltidy from doing any special
553 operations on closing side comments. You may still delete all side
554 comments however when this flag is in effect.
555 -enc=s, --character-encoding=s
557 This flag indicates the character encoding, if any, of the input
558 data stream. Perltidy does not look for the encoding directives in
559 the soure stream, such as use utf8, and instead relies on this flag
560 to determine the encoding. (Note that perltidy often works on
561 snippets of code rather than complete files so it cannot rely on
562 use utf8 directives).
563 The possible values for s [22mare (1) the name of an encoding
565 recognized by the Encode.pm module, (2) none if no encoding is
566 used, or (3) <guess> if perltidy should guess.
567 For example, the value utf8 causes the stream to be read and
569 written as UTF-8. If the input stream cannot be decoded with a
570 specified encoding then processing is not done.
571 The value none causes the stream to be processed without special
573 encoding assumptions. This is appropriate for files which are
574 written in single-byte character encodings such as latin-1.
575 The value guess tells perltidy to guess between either utf8
577 encoding or no encoding (meaning one character per byte). The
578 guess uses the Encode::Guess module and this restricted range of
579 guesses covers the most common cases. Testing showed that
580 considering any greater number of encodings as guess suspects is
581 too risky.
582 The current default is guess.
584 The abbreviations -utf8 or -UTF8 are equivalent to -enc=utf8, and
586 the abbreviation -guess is equivalent to <-enc=guess>. So to
587 process a file named file.pl which is encoded in UTF-8 you can use:
588 perltidy -utf8 file.pl
590 or
592 perltidy -guess file.pl
593 To process a file in euc-jp you could use
595 perltidy -enc=euc-jp file.pl
597 A perltidy output file is unencoded if the input file is unencoded,
599 and otherwise it is encoded as utf8, even if the input encoding was
600 not utf8.
601 -gcs, --use-unicode-gcstring
603 This flag controls whether or not perltidy may use module
604 Unicode::GCString to obtain accurate display widths of wide
605 characters. The default is --nouse-unicode-gcstring.
606 If this flag is set, and text is encoded, perltidy will look for
608 the module Unicode::GCString and, if found, will use it to obtain
609 character display widths. This can improve displayed vertical
610 alignment for files with wide characters. It is a nice feature but
611 it is off by default to avoid conflicting formatting when there are
612 multiple developers. Perltidy installation does not require
613 Unicode::GCString, so users wanting to use this feature need set
614 this flag and also to install Unicode::GCString separately.
615 If this flag is set and perltidy does not find module
617 Unicode::GCString, a warning message will be produced and
618 processing will continue but without the potential benefit provided
619 by the module.
620 Also note that actual vertical alignment depends upon the fonts
622 used by the text display software, so vertical alignment may not be
623 optimal even when Unicode::GCString is used.
624 -ole=s, --output-line-ending=s
626 where s="win", "dos", "unix", or "mac". This flag tells perltidy
627 to output line endings for a specific system. Normally, perltidy
628 writes files with the line separator character of the host system.
629 The "win" and "dos" flags have an identical result.
630 -ple, --preserve-line-endings
632 This flag tells perltidy to write its output files with the same
633 line endings as the input file, if possible. It should work for
634 dos, unix, and mac line endings. It will only work if perltidy
635 input comes from a filename (rather than stdin, for example). If
636 perltidy has trouble determining the input file line ending, it
637 will revert to the default behavior of using the line ending of the
638 host system.
639 -it=n, --iterations=n
641 This flag causes perltidy to do n complete iterations. The reason
642 for this flag is that code beautification is an iterative process
643 and in some cases the output from perltidy can be different if it
644 is applied a second time. For most purposes the default of n=1
645 should be satisfactory. However n=2 can be useful when a major
646 style change is being made, or when code is being beautified on
647 check-in to a source code control system. It has been found to be
648 extremely rare for the output to change after 2 iterations. If a
649 value n is greater than 2 is input then a convergence test will be
650 used to stop the iterations as soon as possible, almost always
651 after 2 iterations. See the next item for a simplified iteration
652 control.
653 This flag has no effect when perltidy is used to generate html.
655 -conv, --converge
657 This flag is equivalent to -it=4 and is included to simplify
658 iteration control. For all practical purposes one either does or
659 does not want to be sure that the output is converged, and there is
660 no penalty to using a large iteration limit since perltidy will
661 check for convergence and stop iterating as soon as possible. The
662 default is -nconv (no convergence check). Using -conv will
663 approximately double run time since normally one extra iteration is
664 required to verify convergence.
665 Code Indentation Control
667 -ci=n, --continuation-indentation=n
668 Continuation indentation is extra indentation spaces applied when a
669 long line is broken. The default is n=2, illustrated here:
670 my $level = # -ci=2
672 ( $max_index_to_go >= 0 ) ? $levels_to_go[0] : $last_output_level;
673 The same example, with n=0, is a little harder to read:
675 my $level = # -ci=0
677 ( $max_index_to_go >= 0 ) ? $levels_to_go[0] : $last_output_level;
678 The value given to -ci is also used by some commands when a small
680 space is required. Examples are commands for outdenting labels,
681 -ola, and control keywords, -okw.
682 When default values are not used, it is highly recommended that the
684 value n given with -ci=n be no more than about one-half of the
685 number of spaces assigned to a full indentation level on the -i=n
686 command. The reason is that discontinuities in the definition and
687 control of continuation indentation arise in complex code, and this
688 rule helps to smooth out these discontinuities.
689 -sil=n --starting-indentation-level=n
691 By default, perltidy examines the input file and tries to determine
692 the starting indentation level. While it is often zero, it may not
693 be zero for a code snippet being sent from an editing session.
694 To guess the starting indentation level perltidy simply assumes
696 that indentation scheme used to create the code snippet is the same
697 as is being used for the current perltidy process. This is the
698 only sensible guess that can be made. It should be correct if this
699 is true, but otherwise it probably won't. For example, if the
700 input script was written with -i=2 and the current peltidy flags
701 have -i=4, the wrong initial indentation will be guessed for a code
702 snippet which has non-zero initial indentation. Likewise, if an
703 entabbing scheme is used in the input script and not in the current
704 process then the guessed indentation will be wrong.
705 If the default method does not work correctly, or you want to
707 change the starting level, use -sil=n, to force the starting level
708 to be n.
709 List indentation using -lp, --line-up-parentheses
711 By default, perltidy indents lists with 4 spaces, or whatever value
712 is specified with -i=n. Here is a small list formatted in this
713 way:
714 # perltidy (default)
716 @month_of_year = (
717 'Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun',
718 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'
719 );
720 Use the -lp flag to add extra indentation to cause the data to
722 begin past the opening parentheses of a sub call or list, or
723 opening square bracket of an anonymous array, or opening curly
724 brace of an anonymous hash. With this option, the above list would
725 become:
726 # perltidy -lp
728 @month_of_year = (
729 'Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun',
730 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'
731 );
732 If the available line length (see -l=n ) does not permit this much
734 space, perltidy will use less. For alternate placement of the
735 closing paren, see the next section.
736 This option has no effect on code BLOCKS, such as if/then/else
738 blocks, which always use whatever is specified with -i=n. Also,
739 the existence of line breaks and/or block comments between the
740 opening and closing parens may cause perltidy to temporarily revert
741 to its default method.
742 Note: The -lp option may not be used together with the -t tabs
744 option. It may, however, be used with the -et=n tab method.
745 In addition, any parameter which significantly restricts the
747 ability of perltidy to choose newlines will conflict with -lp and
748 will cause -lp to be deactivated. These include -io, -fnl, -nanl,
749 and -ndnl. The reason is that the -lp indentation style can
750 require the careful coordination of an arbitrary number of break
751 points in hierarchical lists, and these flags may prevent that.
752 -cti=n, --closing-token-indentation
754 The -cti=n flag controls the indentation of a line beginning with a
755 ")", "]", or a non-block "}". Such a line receives:
756 -cti = 0 no extra indentation (default)
758 -cti = 1 extra indentation such that the closing token
759 aligns with its opening token.
760 -cti = 2 one extra indentation level if the line looks like:
761 ); or ]; or };
762 -cti = 3 one extra indentation level always
763 The flags -cti=1 and -cti=2 work well with the -lp flag (previous
765 section).
766 # perltidy -lp -cti=1
768 @month_of_year = (
769 'Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun',
770 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'
771 );
772 # perltidy -lp -cti=2
774 @month_of_year = (
775 'Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun',
776 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'
777 );
778 These flags are merely hints to the formatter and they may not
780 always be followed. In particular, if -lp is not being used, the
781 indentation for cti=1 is constrained to be no more than one
782 indentation level.
783 If desired, this control can be applied independently to each of
785 the closing container token types. In fact, -cti=n is merely an
786 abbreviation for -cpi=n -csbi=n -cbi=n, where: -cpi or
787 --closing-paren-indentation controls )'s, -csbi or
788 --closing-square-bracket-indentation controls ]'s, -cbi or
789 --closing-brace-indentation controls non-block }'s.
790 -icp, --indent-closing-paren
792 The -icp flag is equivalent to -cti=2, described in the previous
793 section. The -nicp flag is equivalent -cti=0. They are included
794 for backwards compatibility.
795 -icb, --indent-closing-brace
797 The -icb option gives one extra level of indentation to a brace
798 which terminates a code block . For example,
799 if ($task) {
801 yyy();
802 } # -icb
803 else {
804 zzz();
805 }
806 The default is not to do this, indicated by -nicb.
808 -nib, --non-indenting-braces
810 Normally, lines of code contained within a pair of block braces
811 receive one additional level of indentation. This flag, which is
812 enabled by default, causes perltidy to look for opening block
813 braces which are followed by a special side comment. This special
814 side comment is #<<< by default. If found, the code between this
815 opening brace and its corresponding closing brace will not be given
816 the normal extra indentation level. For example:
817 { #<<< a closure to contain lexical vars
819 my $var; # this line does not get one level of indentation
821 ...
822 }
824 # this line does not 'see' $var;
826 This can be useful, for example, when combining code from different
828 files. Different sections of code can be placed within braces to
829 keep their lexical variables from being visible to the end of the
830 file. To keep the new braces from causing all of their contained
831 code to be indented if you run perltidy, and possibly introducing
832 new line breaks in long lines, you can mark the opening braces with
833 this special side comment.
834 Only the opening brace needs to be marked, since perltidy knows
836 where the closing brace is. Braces contained within marked braces
837 may also be marked as non-indenting.
838 If your code happens to have some opening braces followed by
840 '#<<<', and you don't want this behavior, you can use -nnib to
841 deactivate it. To make it easy to remember, the default string is
842 the same as the string for starting a format-skipping section.
843 There is no confusion because in that case it is for a block
844 comment rather than a side-comment.
845 The special side comment can be changed with the next parameter.
847 -nibp=s, --non-indenting-brace-prefix=s
849 The -nibp=string parameter may be used to change the marker for
850 non-indenting braces. The default is equivalent to -nibp='#<<<'.
851 The string that you enter must begin with a # and should be in
852 quotes as necessary to get past the command shell of your system.
853 This string is the leading text of a regex pattern that is
854 constructed by appending pre-pending a '^' and appending a'\s', so
855 you must also include backslashes for characters to be taken
856 literally rather than as patterns.
857 For example, to match the side comment '#++', the parameter would
859 be
860 -nibp='#\+\+'
862 -olq, --outdent-long-quotes
864 When -olq is set, lines which is a quoted string longer than the
865 value maximum-line-length will have their indentation removed to
866 make them more readable. This is the default. To prevent such
867 out-denting, use -nolq or --nooutdent-long-lines.
868 -oll, --outdent-long-lines
870 This command is equivalent to --outdent-long-quotes and
871 --outdent-long-comments, and it is included for compatibility with
872 previous versions of perltidy. The negation of this also works,
873 -noll or --nooutdent-long-lines, and is equivalent to setting -nolq
874 and -nolc.
875 Outdenting Labels: -ola, --outdent-labels
877 This command will cause labels to be outdented by 2 spaces (or
878 whatever -ci has been set to), if possible. This is the default.
879 For example:
880 my $i;
882 LOOP: while ( $i = <FOTOS> ) {
883 chomp($i);
884 next unless $i;
885 fixit($i);
886 }
887 Use -nola to not outdent labels.
889 Outdenting Keywords
891 -okw, --outdent-keywords
892 The command -okw will cause certain leading control keywords to
893 be outdented by 2 spaces (or whatever -ci has been set to), if
894 possible. By default, these keywords are "redo", "next",
895 "last", "goto", and "return". The intention is to make these
896 control keywords easier to see. To change this list of
897 keywords being outdented, see the next section.
898 For example, using "perltidy -okw" on the previous example
900 gives:
901 my $i;
903 LOOP: while ( $i = <FOTOS> ) {
904 chomp($i);
905 next unless $i;
906 fixit($i);
907 }
908 The default is not to do this.
910 Specifying Outdented Keywords: -okwl=string,
912 --outdent-keyword-list=string
913 This command can be used to change the keywords which are
914 outdented with the -okw command. The parameter string is a
915 required list of perl keywords, which should be placed in
916 quotes if there are more than one. By itself, it does not
917 cause any outdenting to occur, so the -okw command is still
918 required.
919 For example, the commands "-okwl="next last redo goto" -okw"
921 will cause those four keywords to be outdented. It is probably
922 simplest to place any -okwl command in a .perltidyrc file.
923 Whitespace Control
925 Whitespace refers to the blank space between variables, operators, and
926 other code tokens.
927 -fws, --freeze-whitespace
929 This flag causes your original whitespace to remain unchanged, and
930 causes the rest of the whitespace commands in this section, the
931 Code Indentation section, and the Comment Control section to be
932 ignored.
933 Tightness of curly braces, parentheses, and square brackets.
935 Here the term "tightness" will mean the closeness with which pairs
936 of enclosing tokens, such as parentheses, contain the quantities
937 within. A numerical value of 0, 1, or 2 defines the tightness,
938 with 0 being least tight and 2 being most tight. Spaces within
939 containers are always symmetric, so if there is a space after a "("
940 then there will be a space before the corresponding ")".
941 The -pt=n or --paren-tightness=n parameter controls the space
943 within parens. The example below shows the effect of the three
944 possible values, 0, 1, and 2:
945 if ( ( my $len_tab = length( $tabstr ) ) > 0 ) { # -pt=0
947 if ( ( my $len_tab = length($tabstr) ) > 0 ) { # -pt=1 (default)
948 if ((my $len_tab = length($tabstr)) > 0) { # -pt=2
949 When n is 0, there is always a space to the right of a '(' and to
951 the left of a ')'. For n=2 there is never a space. For n=1, the
952 default, there is a space unless the quantity within the parens is
953 a single token, such as an identifier or quoted string.
954 Likewise, the parameter -sbt=n or --square-bracket-tightness=n
956 controls the space within square brackets, as illustrated below.
957 $width = $col[ $j + $k ] - $col[ $j ]; # -sbt=0
959 $width = $col[ $j + $k ] - $col[$j]; # -sbt=1 (default)
960 $width = $col[$j + $k] - $col[$j]; # -sbt=2
961 Curly braces which do not contain code blocks are controlled by the
963 parameter -bt=n or --brace-tightness=n.
964 $obj->{ $parsed_sql->{ 'table' }[0] }; # -bt=0
966 $obj->{ $parsed_sql->{'table'}[0] }; # -bt=1 (default)
967 $obj->{$parsed_sql->{'table'}[0]}; # -bt=2
968 And finally, curly braces which contain blocks of code are
970 controlled by the parameter -bbt=n or --block-brace-tightness=n as
971 illustrated in the example below.
972 %bf = map { $_ => -M $_ } grep { /\.deb$/ } dirents '.'; # -bbt=0 (default)
974 %bf = map { $_ => -M $_ } grep {/\.deb$/} dirents '.'; # -bbt=1
975 %bf = map {$_ => -M $_} grep {/\.deb$/} dirents '.'; # -bbt=2
976 To simplify input in the case that all of the tightness flags have
978 the same value <n>, the parameter <-act=n> or
979 --all-containers-tightness=n is an abbreviation for the combination
980 <-pt=n -sbt=n -bt=n -bbt=n>.
981 -tso, --tight-secret-operators
983 The flag -tso causes certain perl token sequences (secret
984 operators) which might be considered to be a single operator to be
985 formatted "tightly" (without spaces). The operators currently
986 modified by this flag are:
987 0+ +0 ()x!! ~~<> ,=> =( )=
989 For example the sequence 0 +, which converts a string to a number,
991 would be formatted without a space: 0+ when the -tso flag is set.
992 This flag is off by default.
993 -sts, --space-terminal-semicolon
995 Some programmers prefer a space before all terminal semicolons.
996 The default is for no such space, and is indicated with -nsts or
997 --nospace-terminal-semicolon.
998 $i = 1 ; # -sts
1000 $i = 1; # -nsts (default)
1001 -sfs, --space-for-semicolon
1003 Semicolons within for loops may sometimes be hard to see,
1004 particularly when commas are also present. This option places
1005 spaces on both sides of these special semicolons, and is the
1006 default. Use -nsfs or --nospace-for-semicolon to deactivate it.
1007 for ( @a = @$ap, $u = shift @a ; @a ; $u = $v ) { # -sfs (default)
1009 for ( @a = @$ap, $u = shift @a; @a; $u = $v ) { # -nsfs
1010 -asc, --add-semicolons
1012 Setting -asc allows perltidy to add any missing optional semicolon
1013 at the end of a line which is followed by a closing curly brace on
1014 the next line. This is the default, and may be deactivated with
1015 -nasc or --noadd-semicolons.
1016 -dsm, --delete-semicolons
1018 Setting -dsm allows perltidy to delete extra semicolons which are
1019 simply empty statements. This is the default, and may be
1020 deactivated with -ndsm or --nodelete-semicolons. (Such semicolons
1021 are not deleted, however, if they would promote a side comment to a
1022 block comment).
1023 -aws, --add-whitespace
1025 Setting this option allows perltidy to add certain whitespace to
1026 improve code readability. This is the default. If you do not want
1027 any whitespace added, but are willing to have some whitespace
1028 deleted, use -naws. (Use -fws to leave whitespace completely
1029 unchanged).
1030 -dws, --delete-old-whitespace
1032 Setting this option allows perltidy to remove some old whitespace
1033 between characters, if necessary. This is the default. If you do
1034 not want any old whitespace removed, use -ndws or
1035 --nodelete-old-whitespace.
1036 Detailed whitespace controls around tokens
1038 For those who want more detailed control over the whitespace around
1039 tokens, there are four parameters which can directly modify the
1040 default whitespace rules built into perltidy for any token. They
1041 are:
1042 -wls=s or --want-left-space=s,
1044 -nwls=s or --nowant-left-space=s,
1046 -wrs=s or --want-right-space=s,
1048 -nwrs=s or --nowant-right-space=s.
1050 These parameters are each followed by a quoted string, s,
1052 containing a list of token types. No more than one of each of
1053 these parameters should be specified, because repeating a command-
1054 line parameter always overwrites the previous one before perltidy
1055 ever sees it.
1056 To illustrate how these are used, suppose it is desired that there
1058 be no space on either side of the token types = + - / *. The
1059 following two parameters would specify this desire:
1060 -nwls="= + - / *" -nwrs="= + - / *"
1062 (Note that the token types are in quotes, and that they are
1064 separated by spaces). With these modified whitespace rules, the
1065 following line of math:
1066 $root = -$b + sqrt( $b * $b - 4. * $a * $c ) / ( 2. * $a );
1068 becomes this:
1070 $root=-$b+sqrt( $b*$b-4.*$a*$c )/( 2.*$a );
1072 These parameters should be considered to be hints to perltidy
1074 rather than fixed rules, because perltidy must try to resolve
1075 conflicts that arise between them and all of the other rules that
1076 it uses. One conflict that can arise is if, between two tokens,
1077 the left token wants a space and the right one doesn't. In this
1078 case, the token not wanting a space takes priority.
1079 It is necessary to have a list of all token types in order to
1081 create this type of input. Such a list can be obtained by the
1082 command --dump-token-types. Also try the -D flag on a short
1083 snippet of code and look at the .DEBUG file to see the
1084 tokenization.
1085 WARNING Be sure to put these tokens in quotes to avoid having them
1087 misinterpreted by your command shell.
1088 Note1: Perltidy does always follow whitespace controls
1090 The various parameters controlling whitespace within a program are
1091 requests which perltidy follows as well as possible, but there are
1092 a number of situations where changing whitespace could change
1093 program behavior and is not done. Some of these are obvious; for
1094 example, we should not remove the space between the two plus
1095 symbols in '$x+ +$y' to avoid creating a '++' operator. Some are
1096 more subtle and involve the whitespace around bareword symbols and
1097 locations of possible filehandles. For example, consider the
1098 problem of formatting the following subroutine:
1099 sub print_div {
1101 my ($x,$y)=@_;
1102 print $x/$y;
1103 }
1104 Suppose the user requests that / signs have a space to the left but
1106 not to the right. Perltidy will refuse to do this, but if this were
1107 done the result would be
1108 sub print_div {
1110 my ($x,$y)=@_;
1111 print $x /$y;
1112 }
1113 If formatted in this way, the program will not run (at least with
1115 recent versions of perl) because the $x is taken to be a filehandle
1116 and / is assumed to start a quote. In a complex program, there
1117 might happen to be a / which terminates the multiline quote without
1118 a syntax error, allowing the program to run, but not as intended.
1119 Related issues arise with other binary operator symbols, such as +
1121 and -, and in older versions of perl there could be problems with
1122 ternary operators. So to avoid changing program behavior, perltidy
1123 has the simple rule that whitespace around possible filehandles is
1124 left unchanged. Likewise, whitespace around barewords is left
1125 unchanged. The reason is that if the barewords are defined in
1126 other modules, or in code that has not even been written yet,
1127 perltidy will not have seen their prototypes and must treat them
1128 cautiously.
1129 Note2: Perltidy's whitespace rules are not perfect
1131 Despite these precautions, it is still possible to introduce syntax
1132 errors with some asymmetric whitespace rules, particularly when
1133 call parameters are not placed in containg parens or braces. For
1134 example, the following two lines will be parsed by perl without a
1135 syntax error:
1136 # original programming, syntax ok
1138 my @newkeys = map $_-$nrecs+@data, @oldkeys;
1139 # perltidy default, syntax ok
1141 my @newkeys = map $_ - $nrecs + @data, @oldkeys;
1142 But the following will give a syntax error:
1144 # perltidy -nwrs='-'
1146 my @newkeys = map $_ -$nrecs + @data, @oldkeys;
1147 Space between specific keywords and opening paren
1149 When an opening paren follows a Perl keyword, no space is
1150 introduced after the keyword, unless it is (by default) one of
1151 these:
1152 my local our and or xor eq ne if else elsif until unless
1154 while for foreach return switch case given when
1155 These defaults can be modified with two commands:
1157 -sak=s or --space-after-keyword=s adds keywords.
1159 -nsak=s or --nospace-after-keyword=s removes keywords.
1161 where s is a list of keywords (in quotes if necessary). For
1163 example,
1164 my ( $a, $b, $c ) = @_; # default
1166 my( $a, $b, $c ) = @_; # -nsak="my local our"
1167 The abbreviation -nsak='*' is equivalent to including all of the
1169 keywords in the above list.
1170 When both -nsak=s and -sak=s commands are included, the -nsak=s
1172 command is executed first. For example, to have space after only
1173 the keywords (my, local, our) you could use -nsak="*" -sak="my
1174 local our".
1175 To put a space after all keywords, see the next item.
1177 Space between all keywords and opening parens
1179 When an opening paren follows a function or keyword, no space is
1180 introduced after the keyword except for the keywords noted in the
1181 previous item. To always put a space between a function or keyword
1182 and its opening paren, use the command:
1183 -skp or --space-keyword-paren
1185 You may also want to use the flag -sfp (next item) too.
1187 Space between all function names and opening parens
1189 When an opening paren follows a function the default and
1190 recommended formatting is not to introduce a space. To cause a
1191 space to be introduced use:
1192 -sfp or --space-function-paren
1194 myfunc( $a, $b, $c ); # default
1196 myfunc ( $a, $b, $c ); # -sfp
1197 You will probably also want to use the flag -skp (previous item)
1199 too.
1200 The reason this is not recommended is that spacing a function paren
1202 can make a program vulnerable to parsing problems by Perl. For
1203 example, the following two-line program will run as written but
1204 will have a syntax error if reformatted with -sfp:
1205 if ( -e filename() ) { print "exists\n"; }
1207 sub filename { return $0 }
1208 The syntax error can be removed if the line order is reversed, so
1210 that Perl parses 'sub filename' first.
1211 -spp=n or --space-prototype-paren=n
1213 This flag can be used to control whether a function prototype is
1214 preceded by a space. For example, the following prototype does not
1215 have a space.
1216 sub usage();
1218 This integer n may have the value 0, 1, or 2 as follows:
1220 -spp=0 means no space before the paren
1222 -spp=1 means follow the example of the source code [DEFAULT]
1223 -spp=2 means always put a space before the paren
1224 The default is -spp=1, meaning that a space will be used if and
1226 only if there is one in the source code. Given the above line of
1227 code, the result of applying the different options would be:
1228 sub usage(); # n=0 [no space]
1230 sub usage(); # n=1 [default; follows input]
1231 sub usage (); # n=2 [space]
1232 -kpit=n or --keyword-paren-inner-tightness=n
1234 The space inside of an opening paren, which itself follows a
1235 certain keyword, can be controlled by this parameter. The space on
1236 the inside of the corresponding closing paren will be treated in
1237 the same (balanced) manner. This parameter has precedence over any
1238 other paren spacing rules. The values of n are as follows:
1239 -kpit=0 means always put a space (not tight)
1241 -kpit=1 means ignore this parameter [default]
1242 -kpit=2 means never put a space (tight)
1243 To illustrate, the following snippet is shown formatted in three
1245 ways:
1246 if ( seek( DATA, 0, 0 ) ) { ... } # perltidy (default)
1248 if (seek(DATA, 0, 0)) { ... } # perltidy -pt=2
1249 if ( seek(DATA, 0, 0) ) { ... } # perltidy -pt=2 -kpit=0
1250 In the second case the -pt=2 parameter makes all of the parens
1252 tight. In the third case the -kpit=0 flag causes the space within
1253 the 'if' parens to have a space, since 'if' is one of the keywords
1254 to which the -kpit flag applies by default. The remaining parens
1255 are still tight because of the -pt=2 parameter.
1256 The set of keywords to which this parameter applies are by default
1258 are:
1259 if elsif unless while until for foreach
1261 These can be changed with the parameter -kpitl=s described in the
1263 next section.
1264 -kpitl=string or --keyword-paren-inner-tightness=string
1266 This command can be used to change the keywords to which the the
1267 -kpit=n command applies. The parameter string is a required list
1268 either keywords or functions, which should be placed in quotes if
1269 there are more than one. By itself, this parameter does not cause
1270 any change in spacing, so the -kpit=n command is still required.
1271 For example, the commands "-kpitl="if else while" -kpit=2" will
1273 cause the just the spaces inside parens following 'if', 'else',
1274 and 'while' keywords to follow the tightness value indicated by the
1275 -kpit=2 flag.
1276 -lop or --logical-padding
1278 In the following example some extra space has been inserted on the
1279 second line between the two open parens. This extra space is called
1280 "logical padding" and is intended to help align similar things
1281 vertically in some logical or ternary expressions.
1282 # perltidy [default formatting]
1284 $same =
1285 ( ( $aP eq $bP )
1286 && ( $aS eq $bS )
1287 && ( $aT eq $bT )
1288 && ( $a->{'title'} eq $b->{'title'} )
1289 && ( $a->{'href'} eq $b->{'href'} ) );
1290 Note that this is considered to be a different operation from
1292 "vertical alignment" because space at just one line is being
1293 adjusted, whereas in "vertical alignment" the spaces at all lines
1294 are being adjusted. So it sort of a local version of vertical
1295 alignment.
1296 Here is an example involving a ternary operator:
1298 # perltidy [default formatting]
1300 $bits =
1301 $top > 0xffff ? 32
1302 : $top > 0xff ? 16
1303 : $top > 1 ? 8
1304 : 1;
1305 This behavior is controlled with the flag --logical-padding, which
1307 is set 'on' by default. If it is not desired it can be turned off
1308 using --nological-padding or -nlop. The above two examples become,
1309 with -nlop:
1310 # perltidy -nlop
1312 $same =
1313 ( ( $aP eq $bP )
1314 && ( $aS eq $bS )
1315 && ( $aT eq $bT )
1316 && ( $a->{'title'} eq $b->{'title'} )
1317 && ( $a->{'href'} eq $b->{'href'} ) );
1318 # perltidy -nlop
1320 $bits =
1321 $top > 0xffff ? 32
1322 : $top > 0xff ? 16
1323 : $top > 1 ? 8
1324 : 1;
1325 Trimming whitespace around "qw" quotes
1327 -tqw or --trim-qw provide the default behavior of trimming spaces
1328 around multi-line "qw" quotes and indenting them appropriately.
1329 -ntqw or --notrim-qw cause leading and trailing whitespace around
1331 multi-line "qw" quotes to be left unchanged. This option will not
1332 normally be necessary, but was added for testing purposes, because
1333 in some versions of perl, trimming "qw" quotes changes the syntax
1334 tree.
1335 b<-sbq=n> or b<--space-backslash-quote=n>
1337 lines like
1338 $str1=\"string1";
1340 $str2=\'string2';
1341 can confuse syntax highlighters unless a space is included between
1343 the backslash and the single or double quotation mark.
1344 this can be controlled with the value of b<n> as follows:
1346 -sbq=0 means no space between the backslash and quote
1348 -sbq=1 means follow the example of the source code
1349 -sbq=2 means always put a space between the backslash and quote
1350 The default is -sbq=1, meaning that a space will be used if there
1352 is one in the source code.
1353 Trimming trailing whitespace from lines of POD
1355 -trp or --trim-pod will remove trailing whitespace from lines of
1356 POD. The default is not to do this.
1357 Comment Controls
1359 Perltidy has a number of ways to control the appearance of both block
1360 comments and side comments. The term block comment here refers to a
1361 full-line comment, whereas side comment will refer to a comment which
1362 appears on a line to the right of some code.
1363 -ibc, --indent-block-comments
1365 Block comments normally look best when they are indented to the
1366 same level as the code which follows them. This is the default
1367 behavior, but you may use -nibc to keep block comments left-
1368 justified. Here is an example:
1369 # this comment is indented (-ibc, default)
1371 if ($task) { yyy(); }
1372 The alternative is -nibc:
1374 # this comment is not indented (-nibc)
1376 if ($task) { yyy(); }
1377 See also the next item, -isbc, as well as -sbc, for other ways to
1379 have some indented and some outdented block comments.
1380 -isbc, --indent-spaced-block-comments
1382 If there is no leading space on the line, then the comment will not
1383 be indented, and otherwise it may be.
1384 If both -ibc and -isbc are set, then -isbc takes priority.
1386 -olc, --outdent-long-comments
1388 When -olc is set, lines which are full-line (block) comments longer
1389 than the value maximum-line-length will have their indentation
1390 removed. This is the default; use -nolc to prevent outdenting.
1391 -msc=n, --minimum-space-to-comment=n
1393 Side comments look best when lined up several spaces to the right
1394 of code. Perltidy will try to keep comments at least n spaces to
1395 the right. The default is n=4 spaces.
1396 -fpsc=n, --fixed-position-side-comment=n
1398 This parameter tells perltidy to line up side comments in column
1399 number n whenever possible. The default, n=0, will not do this.
1400 -iscl, --ignore-side-comment-lengths
1402 This parameter causes perltidy to ignore the length of side
1403 comments when setting line breaks. The default, -niscl, is to
1404 include the length of side comments when breaking lines to stay
1405 within the length prescribed by the -l=n maximum line length
1406 parameter. For example, the following long single line would
1407 remain intact with -l=80 and -iscl:
1408 perltidy -l=80 -iscl
1410 $vmsfile =~ s/;[\d\-]*$//; # Clip off version number; we can use a newer version as well
1411 whereas without the -iscl flag the line will be broken:
1413 perltidy -l=80
1415 $vmsfile =~ s/;[\d\-]*$//
1416 ; # Clip off version number; we can use a newer version as well
1417 -hsc, --hanging-side-comments
1419 By default, perltidy tries to identify and align "hanging side
1420 comments", which are something like this:
1421 my $IGNORE = 0; # This is a side comment
1423 # This is a hanging side comment
1424 # And so is this
1425 A comment is considered to be a hanging side comment if (1) it
1427 immediately follows a line with a side comment, or another hanging
1428 side comment, and (2) there is some leading whitespace on the line.
1429 To deactivate this feature, use -nhsc or --nohanging-side-comments.
1430 If block comments are preceded by a blank line, or have no leading
1431 whitespace, they will not be mistaken as hanging side comments.
1432 Closing Side Comments
1434 A closing side comment is a special comment which perltidy can
1435 automatically create and place after the closing brace of a code
1436 block. They can be useful for code maintenance and debugging. The
1437 command -csc (or --closing-side-comments) adds or updates closing
1438 side comments. For example, here is a small code snippet
1439 sub message {
1441 if ( !defined( $_[0] ) ) {
1442 print("Hello, World\n");
1443 }
1444 else {
1445 print( $_[0], "\n" );
1446 }
1447 }
1448 And here is the result of processing with "perltidy -csc":
1450 sub message {
1452 if ( !defined( $_[0] ) ) {
1453 print("Hello, World\n");
1454 }
1455 else {
1456 print( $_[0], "\n" );
1457 }
1458 } ## end sub message
1459 A closing side comment was added for "sub message" in this case,
1461 but not for the "if" and "else" blocks, because they were below the
1462 6 line cutoff limit for adding closing side comments. This limit
1463 may be changed with the -csci command, described below.
1464 The command -dcsc (or --delete-closing-side-comments) reverses this
1466 process and removes these comments.
1467 Several commands are available to modify the behavior of these two
1469 basic commands, -csc and -dcsc:
1470 -csci=n, or --closing-side-comment-interval=n
1472 where "n" is the minimum number of lines that a block must have
1473 in order for a closing side comment to be added. The default
1474 value is "n=6". To illustrate:
1475 # perltidy -csci=2 -csc
1477 sub message {
1478 if ( !defined( $_[0] ) ) {
1479 print("Hello, World\n");
1480 } ## end if ( !defined( $_[0] ))
1481 else {
1482 print( $_[0], "\n" );
1483 } ## end else [ if ( !defined( $_[0] ))
1484 } ## end sub message
1485 Now the "if" and "else" blocks are commented. However, now
1487 this has become very cluttered.
1488 -cscp=string, or --closing-side-comment-prefix=string
1490 where string is the prefix used before the name of the block
1491 type. The default prefix, shown above, is "## end". This
1492 string will be added to closing side comments, and it will also
1493 be used to recognize them in order to update, delete, and
1494 format them. Any comment identified as a closing side comment
1495 will be placed just a single space to the right of its closing
1496 brace.
1497 -cscl=string, or --closing-side-comment-list
1499 where "string" is a list of block types to be tagged with
1500 closing side comments. By default, all code block types
1501 preceded by a keyword or label (such as "if", "sub", and so on)
1502 will be tagged. The -cscl command changes the default list to
1503 be any selected block types; see "Specifying Block Types". For
1504 example, the following command requests that only "sub"'s,
1505 labels, "BEGIN", and "END" blocks be affected by any -csc or
1506 -dcsc operation:
1507 -cscl="sub : BEGIN END"
1509 -csct=n, or --closing-side-comment-maximum-text=n
1511 The text appended to certain block types, such as an "if"
1512 block, is whatever lies between the keyword introducing the
1513 block, such as "if", and the opening brace. Since this might
1514 be too much text for a side comment, there needs to be a limit,
1515 and that is the purpose of this parameter. The default value
1516 is "n=20", meaning that no additional tokens will be appended
1517 to this text after its length reaches 20 characters. Omitted
1518 text is indicated with "...". (Tokens, including sub names,
1519 are never truncated, however, so actual lengths may exceed
1520 this). To illustrate, in the above example, the appended text
1521 of the first block is " ( !defined( $_[0] )...". The existing
1522 limit of "n=20" caused this text to be truncated, as indicated
1523 by the "...". See the next flag for additional control of the
1524 abbreviated text.
1525 -cscb, or --closing-side-comments-balanced
1527 As discussed in the previous item, when the closing-side-
1528 comment-maximum-text limit is exceeded the comment text must be
1529 truncated. Older versions of perltidy terminated with three
1530 dots, and this can still be achieved with -ncscb:
1531 perltidy -csc -ncscb
1533 } ## end foreach my $foo (sort { $b cmp $a ...
1534 However this causes a problem with editors which cannot
1536 recognize comments or are not configured to do so because they
1537 cannot "bounce" around in the text correctly. The -cscb flag
1538 has been added to help them by appending appropriate balancing
1539 structure:
1540 perltidy -csc -cscb
1542 } ## end foreach my $foo (sort { $b cmp $a ... })
1543 The default is -cscb.
1545 -csce=n, or --closing-side-comment-else-flag=n
1547 The default, n=0, places the text of the opening "if" statement
1548 after any terminal "else".
1549 If n=2 is used, then each "elsif" is also given the text of the
1551 opening "if" statement. Also, an "else" will include the text
1552 of a preceding "elsif" statement. Note that this may result
1553 some long closing side comments.
1554 If n=1 is used, the results will be the same as n=2 whenever
1556 the resulting line length is less than the maximum allowed.
1557 -cscb, or --closing-side-comments-balanced
1559 When using closing-side-comments, and the closing-side-comment-
1560 maximum-text limit is exceeded, then the comment text must be
1561 abbreviated. It is terminated with three dots if the -cscb
1562 flag is negated:
1563 perltidy -csc -ncscb
1565 } ## end foreach my $foo (sort { $b cmp $a ...
1566 This causes a problem with older editors which do not recognize
1568 comments because they cannot "bounce" around in the text
1569 correctly. The -cscb flag tries to help them by appending
1570 appropriate terminal balancing structures:
1571 perltidy -csc -cscb
1573 } ## end foreach my $foo (sort { $b cmp $a ... })
1574 The default is -cscb.
1576 -cscw, or --closing-side-comment-warnings
1578 This parameter is intended to help make the initial transition
1579 to the use of closing side comments. It causes two things to
1580 happen if a closing side comment replaces an existing,
1581 different closing side comment: first, an error message will
1582 be issued, and second, the original side comment will be placed
1583 alone on a new specially marked comment line for later
1584 attention.
1585 The intent is to avoid clobbering existing hand-written side
1587 comments which happen to match the pattern of closing side
1588 comments. This flag should only be needed on the first run with
1589 -csc.
1590 Important Notes on Closing Side Comments:
1592 · Closing side comments are only placed on lines terminated with
1594 a closing brace. Certain closing styles, such as the use of
1595 cuddled elses (-ce), preclude the generation of some closing
1596 side comments.
1597 · Please note that adding or deleting of closing side comments
1599 takes place only through the commands -csc or -dcsc. The other
1600 commands, if used, merely modify the behavior of these two
1601 commands.
1602 · It is recommended that the -cscw flag be used along with -csc
1604 on the first use of perltidy on a given file. This will
1605 prevent loss of any existing side comment data which happens to
1606 have the csc prefix.
1607 · Once you use -csc, you should continue to use it so that any
1609 closing side comments remain correct as code changes.
1610 Otherwise, these comments will become incorrect as the code is
1611 updated.
1612 · If you edit the closing side comments generated by perltidy,
1614 you must also change the prefix to be different from the
1615 closing side comment prefix. Otherwise, your edits will be
1616 lost when you rerun perltidy with -csc. For example, you
1617 could simply change "## end" to be "## End", since the test is
1618 case sensitive. You may also want to use the -ssc flag to keep
1619 these modified closing side comments spaced the same as actual
1620 closing side comments.
1621 · Temporarily generating closing side comments is a useful
1623 technique for exploring and/or debugging a perl script,
1624 especially one written by someone else. You can always remove
1625 them with -dcsc.
1626 Static Block Comments
1628 Static block comments are block comments with a special leading
1629 pattern, "##" by default, which will be treated slightly
1630 differently from other block comments. They effectively behave as
1631 if they had glue along their left and top edges, because they stick
1632 to the left edge and previous line when there is no blank spaces in
1633 those places. This option is particularly useful for controlling
1634 how commented code is displayed.
1635 -sbc, --static-block-comments
1637 When -sbc is used, a block comment with a special leading
1638 pattern, "##" by default, will be treated specially.
1639 Comments so identified are treated as follows:
1641 · If there is no leading space on the line, then the comment
1643 will not be indented, and otherwise it may be,
1644 · no new blank line will be inserted before such a comment,
1646 and
1647 · such a comment will never become a hanging side comment.
1649 For example, assuming @month_of_year is left-adjusted:
1651 @month_of_year = ( # -sbc (default)
1653 'Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct',
1654 ## 'Dec', 'Nov'
1655 'Nov', 'Dec');
1656 Without this convention, the above code would become
1658 @month_of_year = ( # -nsbc
1660 'Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct',
1661 ## 'Dec', 'Nov'
1663 'Nov', 'Dec'
1664 );
1665 which is not as clear. The default is to use -sbc. This may
1667 be deactivated with -nsbc.
1668 -sbcp=string, --static-block-comment-prefix=string
1670 This parameter defines the prefix used to identify static block
1671 comments when the -sbc parameter is set. The default prefix is
1672 "##", corresponding to "-sbcp=##". The prefix is actually part
1673 of a perl pattern used to match lines and it must either begin
1674 with "#" or "^#". In the first case a prefix ^\s* will be
1675 added to match any leading whitespace, while in the second case
1676 the pattern will match only comments with no leading
1677 whitespace. For example, to identify all comments as static
1678 block comments, one would use "-sbcp=#". To identify all left-
1679 adjusted comments as static block comments, use "-sbcp='^#'".
1680 Please note that -sbcp merely defines the pattern used to
1682 identify static block comments; it will not be used unless the
1683 switch -sbc is set. Also, please be aware that since this
1684 string is used in a perl regular expression which identifies
1685 these comments, it must enable a valid regular expression to be
1686 formed.
1687 A pattern which can be useful is:
1689 -sbcp=^#{2,}[^\s#]
1691 This pattern requires a static block comment to have at least
1693 one character which is neither a # nor a space. It allows a
1694 line containing only '#' characters to be rejected as a static
1695 block comment. Such lines are often used at the start and end
1696 of header information in subroutines and should not be
1697 separated from the intervening comments, which typically begin
1698 with just a single '#'.
1699 -osbc, --outdent-static-block-comments
1701 The command -osbc will cause static block comments to be
1702 outdented by 2 spaces (or whatever -ci=n has been set to), if
1703 possible.
1704 Static Side Comments
1706 Static side comments are side comments with a special leading
1707 pattern. This option can be useful for controlling how commented
1708 code is displayed when it is a side comment.
1709 -ssc, --static-side-comments
1711 When -ssc is used, a side comment with a static leading
1712 pattern, which is "##" by default, will be spaced only a single
1713 space from previous character, and it will not be vertically
1714 aligned with other side comments.
1715 The default is -nssc.
1717 -sscp=string, --static-side-comment-prefix=string
1719 This parameter defines the prefix used to identify static side
1720 comments when the -ssc parameter is set. The default prefix is
1721 "##", corresponding to "-sscp=##".
1722 Please note that -sscp merely defines the pattern used to
1724 identify static side comments; it will not be used unless the
1725 switch -ssc is set. Also, note that this string is used in a
1726 perl regular expression which identifies these comments, so it
1727 must enable a valid regular expression to be formed.
1728 Skipping Selected Sections of Code
1730 Selected lines of code may be passed verbatim to the output without any
1731 formatting. This feature is enabled by default but can be disabled
1732 with the --noformat-skipping or -nfs flag. It should be used sparingly
1733 to avoid littering code with markers, but it might be helpful for
1734 working around occasional problems. For example it might be useful for
1735 keeping the indentation of old commented code unchanged, keeping
1736 indentation of long blocks of aligned comments unchanged, keeping
1737 certain list formatting unchanged, or working around a glitch in
1738 perltidy.
1739 -fs, --format-skipping
1741 This flag, which is enabled by default, causes any code between
1742 special beginning and ending comment markers to be passed to the
1743 output without formatting. The default beginning marker is #<<<
1744 and the default ending marker is #>>> but they may be changed (see
1745 next items below). Additional text may appear on these special
1746 comment lines provided that it is separated from the marker by at
1747 least one space. For example
1748 #<<< do not let perltidy touch this
1750 my @list = (1,
1751 1, 1,
1752 1, 2, 1,
1753 1, 3, 3, 1,
1754 1, 4, 6, 4, 1,);
1755 #>>>
1756 Format skipping begins when a format skipping comment is seen and
1758 continues until either a format-skipping end pattern is found or
1759 until the end of file.
1760 The comment markers may be placed at any location that a block
1762 comment may appear. If they do not appear to be working, use the
1763 -log flag and examine the .LOG file. Use -nfs to disable this
1764 feature.
1765 This method works for any code. For the specific case of a comma-
1767 separated list of values, as in this example, another possibility
1768 is to insert a blank or comment somewhere between the opening and
1769 closing parens. See the section "Controlling List Formatting".
1770 -fsb=string, --format-skipping-begin=string
1772 The -fsb=string parameter may be used to change the beginning
1773 marker for format skipping. The default is equivalent to
1774 -fsb='#<<<'. The string that you enter must begin with a # and
1775 should be in quotes as necessary to get past the command shell of
1776 your system. It is actually the leading text of a pattern that is
1777 constructed by appending a '\s', so you must also include
1778 backslashes for characters to be taken literally rather than as
1779 patterns.
1780 Some examples show how example strings become patterns:
1782 -fsb='#\{\{\{' becomes /^#\{\{\{\s/ which matches #{{{ but not #{{{{
1784 -fsb='#\*\*' becomes /^#\*\*\s/ which matches #** but not #***
1785 -fsb='#\*{2,}' becomes /^#\*{2,}\s/ which matches #** and #*****
1786 -fse=string, --format-skipping-end=string
1788 The -fsb=string is the corresponding parameter used to change the
1789 ending marker for format skipping. The default is equivalent to
1790 -fse='#<<<'.
1791 The beginning and ending strings may be the same, but it is
1793 preferable to make them different for clarity.
1794 Line Break Control
1796 The parameters in this section control breaks after non-blank lines of
1797 code. Blank lines are controlled separately by parameters in the
1798 section "Blank Line Control".
1799 -fnl, --freeze-newlines
1801 If you do not want any changes to the line breaks within lines of
1802 code in your script, set -fnl, and they will remain fixed, and the
1803 rest of the commands in this section and sections "Controlling List
1804 Formatting", "Retaining or Ignoring Existing Line Breaks". You may
1805 want to use -noll with this.
1806 Note: If you also want to keep your blank lines exactly as they
1808 are, you can use the -fbl flag which is described in the section
1809 "Blank Line Control".
1810 -ce, --cuddled-else
1812 Enable the "cuddled else" style, in which "else" and "elsif" are
1813 follow immediately after the curly brace closing the previous
1814 block. The default is not to use cuddled elses, and is indicated
1815 with the flag -nce or --nocuddled-else. Here is a comparison of
1816 the alternatives:
1817 # -ce
1819 if ($task) {
1820 yyy();
1821 } else {
1822 zzz();
1823 }
1824 # -nce (default)
1826 if ($task) {
1827 yyy();
1828 }
1829 else {
1830 zzz();
1831 }
1832 In this example the keyword else is placed on the same line which
1834 begins with the preceding closing block brace and is followed by
1835 its own opening block brace on the same line. Other keywords and
1836 function names which are formatted with this "cuddled" style are
1837 elsif, continue, catch, finally.
1838 Other block types can be formatted by specifying their names on a
1840 separate parameter -cbl, described in a later section.
1841 Cuddling between a pair of code blocks requires that the closing
1843 brace of the first block start a new line. If this block is
1844 entirely on one line in the input file, it is necessary to decide
1845 if it should be broken to allow cuddling. This decision is
1846 controlled by the flag -cbo=n discussed below. The default and
1847 recommended value of -cbo=1 bases this decision on the first block
1848 in the chain. If it spans multiple lines then cuddling is made and
1849 continues along the chain, regardless of the sizes of subsequent
1850 blocks. Otherwise, short lines remain intact.
1851 So for example, the -ce flag would not have any effect if the above
1853 snippet is rewritten as
1854 if ($task) { yyy() }
1856 else { zzz() }
1857 If the first block spans multiple lines, then cuddling can be done
1859 and will continue for the subsequent blocks in the chain, as
1860 illustrated in the previous snippet.
1861 If there are blank lines between cuddled blocks they will be
1863 eliminated. If there are comments after the closing brace where
1864 cuddling would occur then cuddling will be prevented. If this
1865 occurs, cuddling will restart later in the chain if possible.
1866 -cb, --cuddled-blocks
1868 This flag is equivalent to -ce.
1869 -cbl, --cuddled-block-list
1871 The built-in default cuddled block types are else, elsif, continue,
1872 catch, finally.
1873 Additional block types to which the -cuddled-blocks style applies
1875 can be defined by this parameter. This parameter is a character
1876 string, giving a list of block types separated by commas or spaces.
1877 For example, to cuddle code blocks of type sort, map and grep, in
1878 addition to the default types, the string could be set to
1879 -cbl="sort map grep"
1881 or equivalently
1883 -cbl=sort,map,grep
1885 Note however that these particular block types are typically short
1887 so there might not be much opportunity for the cuddled format
1888 style.
1889 Using commas avoids the need to protect spaces with quotes.
1891 As a diagnostic check, the flag --dump-cuddled-block-list or -dcbl
1893 can be used to view the hash of values that are generated by this
1894 flag.
1895 Finally, note that the -cbl flag by itself merely specifies which
1897 blocks are formatted with the cuddled format. It has no effect
1898 unless this formatting style is activated with -ce.
1899 -cblx, --cuddled-block-list-exclusive
1901 When cuddled else formatting is selected with -ce, setting this
1902 flag causes perltidy to ignore its built-in defaults and rely
1903 exclusively on the block types specified on the -cbl flag described
1904 in the previous section. For example, to avoid using cuddled catch
1905 and finally, which among in the defaults, the following set of
1906 parameters could be used:
1907 perltidy -ce -cbl='else elsif continue' -cblx
1909 -cbo=n, --cuddled-break-option=n
1911 Cuddled formatting is only possible between a pair of code blocks
1912 if the closing brace of the first block starts a new line. If a
1913 block is encountered which is entirely on a single line, and
1914 cuddled formatting is selected, it is necessary to make a decision
1915 as to whether or not to "break" the block, meaning to cause it to
1916 span multiple lines. This parameter controls that decision. The
1917 options are:
1918 cbo=0 Never force a short block to break.
1920 cbo=1 If the first of a pair of blocks is broken in the input file,
1921 then break the second [DEFAULT].
1922 cbo=2 Break open all blocks for maximal cuddled formatting.
1923 The default and recommended value is cbo=1. With this value, if
1925 the starting block of a chain spans multiple lines, then a cascade
1926 of breaks will occur for remaining blocks causing the entire chain
1927 to be cuddled.
1928 The option cbo=0 can produce erratic cuddling if there are numerous
1930 one-line blocks.
1931 The option cbo=2 produces maximal cuddling but will not allow any
1933 short blocks.
1934 -bl, --opening-brace-on-new-line
1936 Use the flag -bl to place the opening brace on a new line:
1937 if ( $input_file eq '-' ) # -bl
1939 {
1940 important_function();
1941 }
1942 This flag applies to all structural blocks, including named sub's
1944 (unless the -sbl flag is set -- see next item).
1945 The default style, -nbl, places an opening brace on the same line
1947 as the keyword introducing it. For example,
1948 if ( $input_file eq '-' ) { # -nbl (default)
1950 -sbl, --opening-sub-brace-on-new-line
1952 The flag -sbl can be used to override the value of -bl for the
1953 opening braces of named sub's. For example,
1954 perltidy -sbl
1956 produces this result:
1958 sub message
1960 {
1961 if (!defined($_[0])) {
1962 print("Hello, World\n");
1963 }
1964 else {
1965 print($_[0], "\n");
1966 }
1967 }
1968 This flag is negated with -nsbl. If -sbl is not specified, the
1970 value of -bl is used.
1971 -asbl, --opening-anonymous-sub-brace-on-new-line
1973 The flag -asbl is like the -sbl flag except that it applies to
1974 anonymous sub's instead of named subs. For example
1975 perltidy -asbl
1977 produces this result:
1979 $a = sub
1981 {
1982 if ( !defined( $_[0] ) ) {
1983 print("Hello, World\n");
1984 }
1985 else {
1986 print( $_[0], "\n" );
1987 }
1988 };
1989 This flag is negated with -nasbl, and the default is -nasbl.
1991 -bli, --brace-left-and-indent
1993 The flag -bli is the same as -bl but in addition it causes one unit
1994 of continuation indentation ( see -ci ) to be placed before an
1995 opening and closing block braces.
1996 For example,
1998 if ( $input_file eq '-' ) # -bli
2000 {
2001 important_function();
2002 }
2003 By default, this extra indentation occurs for blocks of type: if,
2005 elsif, else, unless, for, foreach, sub, while, until, and also with
2006 a preceding label. The next item shows how to change this.
2007 -blil=s, --brace-left-and-indent-list=s
2009 Use this parameter to change the types of block braces for which
2010 the -bli flag applies; see "Specifying Block Types". For example,
2011 -blil='if elsif else' would apply it to only "if/elsif/else"
2012 blocks.
2013 -bar, --opening-brace-always-on-right
2015 The default style, -nbl places the opening code block brace on a
2016 new line if it does not fit on the same line as the opening
2017 keyword, like this:
2018 if ( $bigwasteofspace1 && $bigwasteofspace2
2020 || $bigwasteofspace3 && $bigwasteofspace4 )
2021 {
2022 big_waste_of_time();
2023 }
2024 To force the opening brace to always be on the right, use the -bar
2026 flag. In this case, the above example becomes
2027 if ( $bigwasteofspace1 && $bigwasteofspace2
2029 || $bigwasteofspace3 && $bigwasteofspace4 ) {
2030 big_waste_of_time();
2031 }
2032 A conflict occurs if both -bl and -bar are specified.
2034 -otr, --opening-token-right and related flags
2036 The -otr flag is a hint that perltidy should not place a break
2037 between a comma and an opening token. For example:
2038 # default formatting
2040 push @{ $self->{$module}{$key} },
2041 {
2042 accno => $ref->{accno},
2043 description => $ref->{description}
2044 };
2045 # perltidy -otr
2047 push @{ $self->{$module}{$key} }, {
2048 accno => $ref->{accno},
2049 description => $ref->{description}
2050 };
2051 The flag -otr is actually an abbreviation for three other flags
2053 which can be used to control parens, hash braces, and square
2054 brackets separately if desired:
2055 -opr or --opening-paren-right
2057 -ohbr or --opening-hash-brace-right
2058 -osbr or --opening-square-bracket-right
2059 -bbhb=n, --break-before-hash-brace=n and related flags
2061 When a list of items spans multiple lines, the default formatting
2062 is to place the opening brace (or other container token) at the end
2063 of the starting line, like this:
2064 $romanNumerals = {
2066 one => 'I',
2067 two => 'II',
2068 three => 'III',
2069 four => 'IV',
2070 };
2071 This flag can change the default behavior to cause a line break to
2073 be placed before the opening brace according to the value given to
2074 the integer n:
2075 -bbhb=0 never break [default]
2077 -bbhb=1 stable: break if the input script had a break
2078 -bbhb=2 break if list is 'complex' (see note below)
2079 -bbhb=3 always break
2080 For example,
2082 # perltidy -bbhb=3
2084 $romanNumerals =
2085 {
2086 one => 'I',
2087 two => 'II',
2088 three => 'III',
2089 four => 'IV',
2090 };
2091 There are several points to note about this flag:
2093 · This parameter only applies if the opening brace is preceded by
2095 an '=' or '=>'.
2096 · This parameter only applies if the contents of the container
2098 looks like a list. The contents need to contain some commas or
2099 '=>'s at the next interior level to be considered a list.
2100 · For the n=2 option, a list is considered 'complex' if it is
2102 part of a nested list structure which spans multiple lines in
2103 the input file.
2104 · If multiple opening tokens have been 'welded' together with the
2106 -wn parameter, then this parameter has no effect.
2107 · The indentation of the braces will normally be one level of
2109 continuation indentation by default. This can be changed with
2110 the parameter -bbhbi=n in the next section.
2111 · Similar flags for controlling parens and square brackets are
2113 given in the subsequent section.
2114 -bbhbi=n, --break-before-hash-brace-and-indent=n
2116 This flag is a companion to -bbhb=n for controlling the indentation
2117 of an opening hash brace which is placed on a new line by that
2118 parameter. The indentation is as follows:
2119 -bbhbi=0 one continuation level [default]
2121 -bbhbi=1 outdent by one continuation level
2122 -bbhbi=2 indent one full indentation level
2123 For example:
2125 # perltidy -bbhb=3 -bbhbi=1
2127 $romanNumerals =
2128 {
2129 one => 'I',
2130 two => 'II',
2131 three => 'III',
2132 four => 'IV',
2133 };
2134 # perltidy -bbhb=3 -bbhbi=2
2136 $romanNumerals =
2137 {
2138 one => 'I',
2139 two => 'II',
2140 three => 'III',
2141 four => 'IV',
2142 };
2143 Note that this parameter has no effect unless -bbhb=n is also set.
2145 -bbsb=n, --break-before-square-bracket=n
2147 This flag is similar to the flag described above, except it applies
2148 to lists contained within square brackets.
2149 -bbsb=0 never break [default]
2151 -bbsb=1 stable: break if the input script had a break
2152 -bbsb=2 break if list is 'complex' (part of nested list structure)
2153 -bbsb=3 always break
2154 -bbsbi=n, --break-before-square-bracket-and-indent=n
2156 This flag is a companion to -bbsb=n for controlling the indentation
2157 of an opening square bracket which is placed on a new line by that
2158 parameter. The indentation is as follows:
2159 -bbsbi=0 one continuation level [default]
2161 -bbsbi=1 outdent by one continuation level
2162 -bbsbi=2 indent one full indentation level
2163 -bbp=n, --break-before-paren=n
2165 This flag is similar to -bbhb=n, described above, except it applies
2166 to lists contained within parens.
2167 -bbp=0 never break [default]
2169 -bbp=1 stable: break if the input script had a break
2170 -bpb=2 break if list is 'complex' (part of nested list structure)
2171 -bbp=3 always break
2172 -bbpi=n, --break-before-paren-and-indent=n
2174 This flag is a companion to -bbp=n for controlling the indentation
2175 of an opening paren which is placed on a new line by that
2176 parameter. The indentation is as follows:
2177 -bbpi=0 one continuation level [default]
2179 -bbpi=1 outdent by one continuation level
2180 -bbpi=2 indent one full indentation level
2181 -wn, --weld-nested-containers
2183 The -wn flag causes closely nested pairs of opening and closing
2184 container symbols (curly braces, brackets, or parens) to be
2185 "welded" together, meaning that they are treated as if combined
2186 into a single unit, with the indentation of the innermost code
2187 reduced to be as if there were just a single container symbol.
2188 For example:
2190 # default formatting
2192 do {
2193 {
2194 next if $x == $y;
2195 }
2196 } until $x++ > $z;
2197 # perltidy -wn
2199 do { {
2200 next if $x == $y;
2201 } } until $x++ > $z;
2202 When this flag is set perltidy makes a preliminary pass through the
2204 file and identifies all nested pairs of containers. To qualify as
2205 a nested pair, the closing container symbols must be immediately
2206 adjacent. The opening symbols must either be adjacent, or, if the
2207 outer opening symbol is an opening paren, they may be separated by
2208 any single non-container symbol or something that looks like a
2209 function evaluation.
2210 Any container symbol may serve as both the inner container of one
2212 pair and as the outer container of an adjacent pair. Consequently,
2213 any number of adjacent opening or closing symbols may join together
2214 in weld. For example, here are three levels of wrapped function
2215 calls:
2216 # default formatting
2218 my (@date_time) = Localtime(
2219 Date_to_Time(
2220 Add_Delta_DHMS(
2221 $year, $month, $day, $hour, $minute, $second,
2222 '0', $offset, '0', '0'
2223 )
2224 )
2225 );
2226 # perltidy -wn
2228 my (@date_time) = Localtime( Date_to_Time( Add_Delta_DHMS(
2229 $year, $month, $day, $hour, $minute, $second,
2230 '0', $offset, '0', '0'
2231 ) ) );
2232 Notice how the indentation of the inner lines are reduced by two
2234 levels in this case. This example also shows the typical result of
2235 this formatting, namely it is a sandwich consisting of an initial
2236 opening layer, a central section of any complexity forming the
2237 "meat" of the sandwich, and a final closing layer. This
2238 predictable structure helps keep the compacted structure readable.
2239 The inner sandwich layer is required to be at least one line thick.
2241 If this cannot be achieved, welding does not occur. This
2242 constraint can cause formatting to take a couple of iterations to
2243 stabilize when it is first applied to a script. The -conv flag can
2244 be used to insure that the final format is achieved in a single
2245 run.
2246 Here is an example illustrating a welded container within a welded
2248 containers:
2249 # default formatting
2251 $x->badd(
2252 bmul(
2253 $class->new(
2254 abs(
2255 $sx * int( $xr->numify() ) & $sy * int( $yr->numify() )
2256 )
2257 ),
2258 $m
2259 )
2260 );
2261 # perltidy -wn
2263 $x->badd( bmul(
2264 $class->new( abs(
2265 $sx * int( $xr->numify() ) & $sy * int( $yr->numify() )
2266 ) ),
2267 $m
2268 ) );
2269 This format option is quite general but there are some limitations.
2271 One limitation is that any line length limit still applies and can
2273 cause long welded sections to be broken into multiple lines.
2274 Another limitation is that an opening symbol which delimits quoted
2276 text cannot be included in a welded pair. This is because quote
2277 delimiters are treated specially in perltidy.
2278 Finally, the stacking of containers defined by this flag have
2280 priority over any other container stacking flags. This is because
2281 any welding is done first.
2282 Vertical tightness of non-block curly braces, parentheses, and square
2284 brackets.
2285 These parameters control what shall be called vertical tightness.
2286 Here are the main points:
2287 · Opening tokens (except for block braces) are controlled by
2289 -vt=n, or --vertical-tightness=n, where
2290 -vt=0 always break a line after opening token (default).
2292 -vt=1 do not break unless this would produce more than one
2293 step in indentation in a line.
2294 -vt=2 never break a line after opening token
2295 · You must also use the -lp flag when you use the -vt flag; the
2297 reason is explained below.
2298 · Closing tokens (except for block braces) are controlled by
2300 -vtc=n, or --vertical-tightness-closing=n, where
2301 -vtc=0 always break a line before a closing token (default),
2303 -vtc=1 do not break before a closing token which is followed
2304 by a semicolon or another closing token, and is not in
2305 a list environment.
2306 -vtc=2 never break before a closing token.
2307 The rules for -vtc=1 are designed to maintain a reasonable
2309 balance between tightness and readability in complex lists.
2310 · Different controls may be applied to different token types, and
2312 it is also possible to control block braces; see below.
2313 · Finally, please note that these vertical tightness flags are
2315 merely hints to the formatter, and it cannot always follow
2316 them. Things which make it difficult or impossible include
2317 comments, blank lines, blocks of code within a list, and
2318 possibly the lack of the -lp parameter. Also, these flags may
2319 be ignored for very small lists (2 or 3 lines in length).
2320 Here are some examples:
2322 # perltidy -lp -vt=0 -vtc=0
2324 %romanNumerals = (
2325 one => 'I',
2326 two => 'II',
2327 three => 'III',
2328 four => 'IV',
2329 );
2330 # perltidy -lp -vt=1 -vtc=0
2332 %romanNumerals = ( one => 'I',
2333 two => 'II',
2334 three => 'III',
2335 four => 'IV',
2336 );
2337 # perltidy -lp -vt=1 -vtc=1
2339 %romanNumerals = ( one => 'I',
2340 two => 'II',
2341 three => 'III',
2342 four => 'IV', );
2343 The difference between -vt=1 and -vt=2 is shown here:
2345 # perltidy -lp -vt=1
2347 $init->add(
2348 mysprintf( "(void)find_threadsv(%s);",
2349 cstring( $threadsv_names[ $op->targ ] )
2350 )
2351 );
2352 # perltidy -lp -vt=2
2354 $init->add( mysprintf( "(void)find_threadsv(%s);",
2355 cstring( $threadsv_names[ $op->targ ] )
2356 )
2357 );
2358 With -vt=1, the line ending in "add(" does not combine with the
2360 next line because the next line is not balanced. This can help
2361 with readability, but -vt=2 can be used to ignore this rule.
2362 The tightest, and least readable, code is produced with both
2364 "-vt=2" and "-vtc=2":
2365 # perltidy -lp -vt=2 -vtc=2
2367 $init->add( mysprintf( "(void)find_threadsv(%s);",
2368 cstring( $threadsv_names[ $op->targ ] ) ) );
2369 Notice how the code in all of these examples collapses vertically
2371 as -vt increases, but the indentation remains unchanged. This is
2372 because perltidy implements the -vt parameter by first formatting
2373 as if -vt=0, and then simply overwriting one output line on top of
2374 the next, if possible, to achieve the desired vertical tightness.
2375 The -lp indentation style has been designed to allow this vertical
2376 collapse to occur, which is why it is required for the -vt
2377 parameter.
2378 The -vt=n and -vtc=n parameters apply to each type of container
2380 token. If desired, vertical tightness controls can be applied
2381 independently to each of the closing container token types.
2382 The parameters for controlling parentheses are -pvt=n or
2384 --paren-vertical-tightness=n, and -pcvt=n or
2385 --paren-vertical-tightness-closing=n.
2386 Likewise, the parameters for square brackets are -sbvt=n or
2388 --square-bracket-vertical-tightness=n, and -sbcvt=n or
2389 --square-bracket-vertical-tightness-closing=n.
2390 Finally, the parameters for controlling non-code block braces are
2392 -bvt=n or --brace-vertical-tightness=n, and -bcvt=n or
2393 --brace-vertical-tightness-closing=n.
2394 In fact, the parameter -vt=n is actually just an abbreviation for
2396 -pvt=n -bvt=n sbvt=n, and likewise -vtc=n is an abbreviation for
2397 -pvtc=n -bvtc=n sbvtc=n.
2398 -bbvt=n or --block-brace-vertical-tightness=n
2400 The -bbvt=n flag is just like the -vt=n flag but applies to opening
2401 code block braces.
2402 -bbvt=0 break after opening block brace (default).
2404 -bbvt=1 do not break unless this would produce more than one
2405 step in indentation in a line.
2406 -bbvt=2 do not break after opening block brace.
2407 It is necessary to also use either -bl or -bli for this to work,
2409 because, as with other vertical tightness controls, it is
2410 implemented by simply overwriting a line ending with an opening
2411 block brace with the subsequent line. For example:
2412 # perltidy -bli -bbvt=0
2414 if ( open( FILE, "< $File" ) )
2415 {
2416 while ( $File = <FILE> )
2417 {
2418 $In .= $File;
2419 $count++;
2420 }
2421 close(FILE);
2422 }
2423 # perltidy -bli -bbvt=1
2425 if ( open( FILE, "< $File" ) )
2426 { while ( $File = <FILE> )
2427 { $In .= $File;
2428 $count++;
2429 }
2430 close(FILE);
2431 }
2432 By default this applies to blocks associated with keywords if,
2434 elsif, else, unless, for, foreach, sub, while, until, and also with
2435 a preceding label. This can be changed with the parameter
2436 -bbvtl=string, or --block-brace-vertical-tightness-list=string,
2437 where string is a space-separated list of block types. For more
2438 information on the possible values of this string, see "Specifying
2439 Block Types"
2440 For example, if we want to just apply this style to "if", "elsif",
2442 and "else" blocks, we could use "perltidy -bli -bbvt=1 -bbvtl='if
2443 elsif else'".
2444 There is no vertical tightness control for closing block braces;
2446 with one exception they will be placed on separate lines. The
2447 exception is that a cascade of closing block braces may be stacked
2448 on a single line. See -scbb.
2449 -sot, --stack-opening-tokens and related flags
2451 The -sot flag tells perltidy to "stack" opening tokens when
2452 possible to avoid lines with isolated opening tokens.
2453 For example:
2455 # default
2457 $opt_c = Text::CSV_XS->new(
2458 {
2459 binary => 1,
2460 sep_char => $opt_c,
2461 always_quote => 1,
2462 }
2463 );
2464 # -sot
2466 $opt_c = Text::CSV_XS->new( {
2467 binary => 1,
2468 sep_char => $opt_c,
2469 always_quote => 1,
2470 }
2471 );
2472 For detailed control of individual closing tokens the following
2474 controls can be used:
2475 -sop or --stack-opening-paren
2477 -sohb or --stack-opening-hash-brace
2478 -sosb or --stack-opening-square-bracket
2479 -sobb or --stack-opening-block-brace
2480 The flag -sot is an abbreviation for -sop -sohb -sosb.
2482 The flag -sobb is an abbreviation for -bbvt=2 -bbvtl='*'. This
2484 will case a cascade of opening block braces to appear on a single
2485 line, although this an uncommon occurrence except in test scripts.
2486 -sct, --stack-closing-tokens and related flags
2488 The -sct flag tells perltidy to "stack" closing tokens when
2489 possible to avoid lines with isolated closing tokens.
2490 For example:
2492 # default
2494 $opt_c = Text::CSV_XS->new(
2495 {
2496 binary => 1,
2497 sep_char => $opt_c,
2498 always_quote => 1,
2499 }
2500 );
2501 # -sct
2503 $opt_c = Text::CSV_XS->new(
2504 {
2505 binary => 1,
2506 sep_char => $opt_c,
2507 always_quote => 1,
2508 } );
2509 The -sct flag is somewhat similar to the -vtc flags, and in some
2511 cases it can give a similar result. The difference is that the
2512 -vtc flags try to avoid lines with leading opening tokens by
2513 "hiding" them at the end of a previous line, whereas the -sct flag
2514 merely tries to reduce the number of lines with isolated closing
2515 tokens by stacking them but does not try to hide them. For
2516 example:
2517 # -vtc=2
2519 $opt_c = Text::CSV_XS->new(
2520 {
2521 binary => 1,
2522 sep_char => $opt_c,
2523 always_quote => 1, } );
2524 For detailed control of the stacking of individual closing tokens
2526 the following controls can be used:
2527 -scp or --stack-closing-paren
2529 -schb or --stack-closing-hash-brace
2530 -scsb or --stack-closing-square-bracket
2531 -scbb or --stack-closing-block-brace
2532 The flag -sct is an abbreviation for stacking the non-block closing
2534 tokens, -scp -schb -scsb.
2535 Stacking of closing block braces, -scbb, causes a cascade of
2537 isolated closing block braces to be combined into a single line as
2538 in the following example:
2539 # -scbb:
2541 for $w1 (@w1) {
2542 for $w2 (@w2) {
2543 for $w3 (@w3) {
2544 for $w4 (@w4) {
2545 push( @lines, "$w1 $w2 $w3 $w4\n" );
2546 } } } }
2547 To simplify input even further for the case in which both opening
2549 and closing non-block containers are stacked, the flag -sac or
2550 --stack-all-containers is an abbreviation for -sot -sot.
2551 -dnl, --delete-old-newlines
2553 By default, perltidy first deletes all old line break locations,
2554 and then it looks for good break points to match the desired line
2555 length. Use -ndnl or --nodelete-old-newlines to force perltidy to
2556 retain all old line break points.
2557 -anl, --add-newlines
2559 By default, perltidy will add line breaks when necessary to create
2560 continuations of long lines and to improve the script appearance.
2561 Use -nanl or --noadd-newlines to prevent any new line breaks.
2562 This flag does not prevent perltidy from eliminating existing line
2564 breaks; see --freeze-newlines to completely prevent changes to line
2565 break points.
2566 Controlling whether perltidy breaks before or after operators
2568 Four command line parameters provide some control over whether a
2569 line break should be before or after specific token types. Two
2570 parameters give detailed control:
2571 -wba=s or --want-break-after=s, and
2573 -wbb=s or --want-break-before=s.
2575 These parameters are each followed by a quoted string, s,
2577 containing a list of token types (separated only by spaces). No
2578 more than one of each of these parameters should be specified,
2579 because repeating a command-line parameter always overwrites the
2580 previous one before perltidy ever sees it.
2581 By default, perltidy breaks after these token types:
2583 % + - * / x != == >= <= =~ !~ < > | &
2584 = **= += *= &= <<= &&= -= /= |= >>= ||= //= .= %= ^= x=
2585 And perltidy breaks before these token types by default:
2587 . << >> -> && || //
2588 To illustrate, to cause a break after a concatenation operator,
2590 '.', rather than before it, the command line would be
2591 -wba="."
2593 As another example, the following command would cause a break
2595 before math operators '+', '-', '/', and '*':
2596 -wbb="+ - / *"
2598 These commands should work well for most of the token types that
2600 perltidy uses (use --dump-token-types for a list). Also try the -D
2601 flag on a short snippet of code and look at the .DEBUG file to see
2602 the tokenization. However, for a few token types there may be
2603 conflicts with hardwired logic which cause unexpected results. One
2604 example is curly braces, which should be controlled with the
2605 parameter bl provided for that purpose.
2606 WARNING Be sure to put these tokens in quotes to avoid having them
2608 misinterpreted by your command shell.
2609 Two additional parameters are available which, though they provide
2611 no further capability, can simplify input are:
2612 -baao or --break-after-all-operators,
2614 -bbao or --break-before-all-operators.
2616 The -baao sets the default to be to break after all of the
2618 following operators:
2619 % + - * / x != == >= <= =~ !~ < > | &
2621 = **= += *= &= <<= &&= -= /= |= >>= ||= //= .= %= ^= x=
2622 . : ? && || and or err xor
2623 and the -bbao flag sets the default to break before all of these
2625 operators. These can be used to define an initial break preference
2626 which can be fine-tuned with the -wba and -wbb flags. For example,
2627 to break before all operators except an = one could use --bbao
2628 -wba='=' rather than listing every single perl operator except = on
2629 a -wbb flag.
2630 Controlling List Formatting
2632 Perltidy attempts to format lists of comma-separated values in tables
2633 which look good. Its default algorithms usually work well, but
2634 sometimes they don't. In this case, there are several methods
2635 available to control list formatting.
2636 A very simple way to prevent perltidy from changing the line breaks
2638 within a comma-separated list of values is to insert a blank line,
2639 comment, or side-comment anywhere between the opening and closing
2640 parens (or braces or brackets). This causes perltidy to skip over its
2641 list formatting logic. (The reason is that any of these items put a
2642 constraint on line breaks, and perltidy needs complete control over
2643 line breaks within a container to adjust a list layout). For example,
2644 let us consider
2645 my @list = (1,
2647 1, 1,
2648 1, 2, 1,
2649 1, 3, 3, 1,
2650 1, 4, 6, 4, 1,);
2651 The default formatting, which allows a maximum line length of 80, will
2653 flatten this down to one line:
2654 # perltidy (default)
2656 my @list = ( 1, 1, 1, 1, 2, 1, 1, 3, 3, 1, 1, 4, 6, 4, 1, );
2657 This formatting loses important information. If we place a side
2659 comment on one of the lines, for example, we get the following result
2660 with with default formatting parameters:
2661 my @list = (
2663 1, # a side comment, comment, or blank keeps list intact
2664 1, 1,
2665 1, 2, 1,
2666 1, 3, 3, 1,
2667 1, 4, 6, 4, 1,
2668 );
2669 We could achieve the same result with a blank line or full comment
2671 anywhere between the opening and closing parens.
2672 For another possibility see the -fs flag in "Skipping Selected Sections
2674 of Code".
2675 -boc, --break-at-old-comma-breakpoints
2677 The -boc flag is another way to prevent comma-separated lists from
2678 being reformatted. Using -boc on the above example, plus
2679 additional flags to retain the original style, yields
2680 # perltidy -boc -lp -pt=2 -vt=1 -vtc=1
2682 my @list = (1,
2683 1, 1,
2684 1, 2, 1,
2685 1, 3, 3, 1,
2686 1, 4, 6, 4, 1,);
2687 A disadvantage of this flag is that all tables in the file must
2689 already be nicely formatted.
2690 -mft=n, --maximum-fields-per-table=n
2692 If the computed number of fields for any table exceeds n, then it
2693 will be reduced to n. The default value for n is a large number,
2694 40. While this value should probably be left unchanged as a
2695 general rule, it might be used on a small section of code to force
2696 a list to have a particular number of fields per line, and then
2697 either the -boc flag could be used to retain this formatting, or a
2698 single comment could be introduced somewhere to freeze the
2699 formatting in future applications of perltidy.
2700 # perltidy -mft=2
2702 @month_of_year = (
2703 'Jan', 'Feb',
2704 'Mar', 'Apr',
2705 'May', 'Jun',
2706 'Jul', 'Aug',
2707 'Sep', 'Oct',
2708 'Nov', 'Dec'
2709 );
2710 -cab=n, --comma-arrow-breakpoints=n
2712 A comma which follows a comma arrow, '=>', is given special
2713 consideration. In a long list, it is common to break at all such
2714 commas. This parameter can be used to control how perltidy breaks
2715 at these commas. (However, it will have no effect if old comma
2716 breaks are being forced because -boc is used). The possible values
2717 of n are:
2718 n=0 break at all commas after =>
2720 n=1 stable: break at all commas after => if container is open,
2721 EXCEPT FOR one-line containers
2722 n=2 break at all commas after =>, BUT try to form the maximum
2723 maximum one-line container lengths
2724 n=3 do not treat commas after => specially at all
2725 n=4 break everything: like n=0 but ALSO break a short container with
2726 a => not followed by a comma when -vt=0 is used
2727 n=5 stable: like n=1 but ALSO break at open one-line containers when
2728 -vt=0 is used (default)
2729 For example, given the following single line, perltidy by default
2731 will not add any line breaks because it would break the existing
2732 one-line container:
2733 bless { B => $B, Root => $Root } => $package;
2735 Using -cab=0 will force a break after each comma-arrow item:
2737 # perltidy -cab=0:
2739 bless {
2740 B => $B,
2741 Root => $Root
2742 } => $package;
2743 If perltidy is subsequently run with this container broken, then by
2745 default it will break after each '=>' because the container is now
2746 broken. To reform a one-line container, the parameter -cab=2 could
2747 be used.
2748 The flag -cab=3 can be used to prevent these commas from being
2750 treated specially. In this case, an item such as "01" => 31 is
2751 treated as a single item in a table. The number of fields in this
2752 table will be determined by the same rules that are used for any
2753 other table. Here is an example.
2754 # perltidy -cab=3
2756 my %last_day = (
2757 "01" => 31, "02" => 29, "03" => 31, "04" => 30,
2758 "05" => 31, "06" => 30, "07" => 31, "08" => 31,
2759 "09" => 30, "10" => 31, "11" => 30, "12" => 31
2760 );
2761 Retaining or Ignoring Existing Line Breaks
2763 Several additional parameters are available for controlling the extent
2764 to which line breaks in the input script influence the output script.
2765 In most cases, the default parameter values are set so that, if a
2766 choice is possible, the output style follows the input style. For
2767 example, if a short logical container is broken in the input script,
2768 then the default behavior is for it to remain broken in the output
2769 script.
2770 Most of the parameters in this section would only be required for a
2772 one-time conversion of a script from short container lengths to longer
2773 container lengths. The opposite effect, of converting long container
2774 lengths to shorter lengths, can be obtained by temporarily using a
2775 short maximum line length.
2776 -bol, --break-at-old-logical-breakpoints
2778 By default, if a logical expression is broken at a "&&", "||",
2779 "and", or "or", then the container will remain broken. Also,
2780 breaks at internal keywords "if" and "unless" will normally be
2781 retained. To prevent this, and thus form longer lines, use -nbol.
2782 -bom, --break-at-old-method-breakpoints
2784 By default, a method call arrow "->" is considered a candidate for
2785 a breakpoint, but method chains will fill to the line width before
2786 a break is considered. With -bom, breaks before the arrow are
2787 preserved, so if you have preformatted a method chain:
2788 my $q = $rs
2790 ->related_resultset('CDs')
2791 ->related_resultset('Tracks')
2792 ->search({
2793 'track.id' => {-ident => 'none_search.id'},
2794 })->as_query;
2795 It will keep these breaks, rather than become this:
2797 my $q = $rs->related_resultset('CDs')->related_resultset('Tracks')->search({
2799 'track.id' => {-ident => 'none_search.id'},
2800 })->as_query;
2801 This flag will also look for and keep a 'cuddled' style of calls,
2803 in which lines begin with a closing paren followed by a call arrow,
2804 as in this example:
2805 my $q = $rs->related_resultset(
2807 'CDs'
2808 )->related_resultset(
2809 'Tracks'
2810 )->search( {
2811 'track.id' => { -ident => 'none_search.id' },
2812 } )->as_query;
2813 You may want to include the -weld-nested-containers flag in this
2815 case to keep nested braces and parens together, as in the last
2816 line.
2817 -bos, --break-at-old-semicolon-breakpoints
2819 Semicolons are normally placed at the end of a statement. This
2820 means that formatted lines do not normally begin with semicolons.
2821 If the input stream has some lines which begin with semicolons,
2822 these can be retained by setting this flag. For example, consider
2823 the following two-line input snippet:
2824 $z = sqrt($x**2 + $y**2)
2826 ;
2827 The default formatting will be:
2829 $z = sqrt( $x**2 + $y**2 );
2831 The result using perltidy -bos keeps the isolated semicolon:
2833 $z = sqrt( $x**2 + $y**2 )
2835 ;
2836 The default is not to do this, -nbos.
2838 -bok, --break-at-old-keyword-breakpoints
2840 By default, perltidy will retain a breakpoint before keywords which
2841 may return lists, such as "sort" and <map>. This allows chains of
2842 these operators to be displayed one per line. Use -nbok to prevent
2843 retaining these breakpoints.
2844 -bot, --break-at-old-ternary-breakpoints
2846 By default, if a conditional (ternary) operator is broken at a ":",
2847 then it will remain broken. To prevent this, and thereby form
2848 longer lines, use -nbot.
2849 -boa, --break-at-old-attribute-breakpoints
2851 By default, if an attribute list is broken at a ":" in the source
2852 file, then it will remain broken. For example, given the following
2853 code, the line breaks at the ':'s will be retained:
2854 my @field
2856 : field
2857 : Default(1)
2858 : Get('Name' => 'foo') : Set('Name');
2859 If the attributes are on a single line in the source code then they
2861 will remain on a single line if possible.
2862 To prevent this, and thereby always form longer lines, use -nboa.
2864 -iob, --ignore-old-breakpoints
2866 Use this flag to tell perltidy to ignore existing line breaks to
2867 the maximum extent possible. This will tend to produce the longest
2868 possible containers, regardless of type, which do not exceed the
2869 line length limit.
2870 -kis, --keep-interior-semicolons
2872 Use the -kis flag to prevent breaking at a semicolon if there was
2873 no break there in the input file. Normally perltidy places a
2874 newline after each semicolon which terminates a statement unless
2875 several statements are contained within a one-line brace block. To
2876 illustrate, consider the following input lines:
2877 dbmclose(%verb_delim); undef %verb_delim;
2879 dbmclose(%expanded); undef %expanded;
2880 The default is to break after each statement, giving
2882 dbmclose(%verb_delim);
2884 undef %verb_delim;
2885 dbmclose(%expanded);
2886 undef %expanded;
2887 With perltidy -kis the multiple statements are retained:
2889 dbmclose(%verb_delim); undef %verb_delim;
2891 dbmclose(%expanded); undef %expanded;
2892 The statements are still subject to the specified value of maximum-
2894 line-length and will be broken if this maximum is exceeded.
2895 Blank Line Control
2897 Blank lines can improve the readability of a script if they are
2898 carefully placed. Perltidy has several commands for controlling the
2899 insertion, retention, and removal of blank lines.
2900 -fbl, --freeze-blank-lines
2902 Set -fbl if you want to the blank lines in your script to remain
2903 exactly as they are. The rest of the parameters in this section
2904 may then be ignored. (Note: setting the -fbl flag is equivalent to
2905 setting -mbl=0 and -kbl=2).
2906 -bbc, --blanks-before-comments
2908 A blank line will be introduced before a full-line comment. This
2909 is the default. Use -nbbc or --noblanks-before-comments to
2910 prevent such blank lines from being introduced.
2911 -blbs=n, --blank-lines-before-subs=n
2913 The parameter -blbs=n requests that least n blank lines precede a
2914 sub definition which does not follow a comment and which is more
2915 than one-line long. The default is <-blbs=1>. BEGIN and END
2916 blocks are included.
2917 The requested number of blanks statement will be inserted
2919 regardless of the value of --maximum-consecutive-blank-lines=n
2920 (-mbl=n) with the exception that if -mbl=0 then no blanks will be
2921 output.
2922 This parameter interacts with the value k of the parameter
2924 --maximum-consecutive-blank-lines=k (-mbl=k) as follows:
2925 1. If -mbl=0 then no blanks will be output. This allows all blanks
2927 to be suppressed with a single parameter. Otherwise,
2928 2. If the number of old blank lines in the script is less than n
2930 then additional blanks will be inserted to make the total n
2931 regardless of the value of -mbl=k.
2932 3. If the number of old blank lines in the script equals or exceeds
2934 n then this parameter has no effect, however the total will not
2935 exceed value specified on the -mbl=k flag.
2936 -blbp=n, --blank-lines-before-packages=n
2938 The parameter -blbp=n requests that least n blank lines precede a
2939 package which does not follow a comment. The default is -blbp=1.
2940 This parameter interacts with the value k of the parameter
2942 --maximum-consecutive-blank-lines=k (-mbl=k) in the same way as
2943 described for the previous item -blbs=n.
2944 -bbs, --blanks-before-subs
2946 For compatibility with previous versions, -bbs or
2947 --blanks-before-subs is equivalent to -blbp=1 and -blbs=1.
2948 Likewise, -nbbs or --noblanks-before-subs is equivalent to -blbp=0
2950 and -blbs=0.
2951 -bbb, --blanks-before-blocks
2953 A blank line will be introduced before blocks of coding delimited
2954 by for, foreach, while, until, and if, unless, in the following
2955 circumstances:
2956 · The block is not preceded by a comment.
2958 · The block is not a one-line block.
2960 · The number of consecutive non-blank lines at the current
2962 indentation depth is at least -lbl (see next section).
2963 This is the default. The intention of this option is to introduce
2965 some space within dense coding. This is negated with -nbbb or
2966 --noblanks-before-blocks.
2967 -lbl=n --long-block-line-count=n
2969 This controls how often perltidy is allowed to add blank lines
2970 before certain block types (see previous section). The default is
2971 8. Entering a value of 0 is equivalent to entering a very large
2972 number.
2973 -blao=i or --blank-lines-after-opening-block=i
2975 This control places a minimum of i blank lines after a line which
2976 ends with an opening block brace of a specified type. By default,
2977 this only applies to the block of a named sub, but this can be
2978 changed (see -blaol below). The default is not to do this (i=0).
2979 Please see the note below on using the -blao and -blbc options.
2981 -blbc=i or --blank-lines-before-closing-block=i
2983 This control places a minimum of i blank lines before a line which
2984 begins with a closing block brace of a specified type. By default,
2985 this only applies to the block of a named sub, but this can be
2986 changed (see -blbcl below). The default is not to do this (i=0).
2987 -blaol=s or --blank-lines-after-opening-block-list=s
2989 The parameter s is a list of block type keywords to which the flag
2990 -blao should apply. The section "Specifying Block Types" explains
2991 how to list block types.
2992 -blbcl=s or --blank-lines-before-closing-block-list=s
2994 This parameter is a list of block type keywords to which the flag
2995 -blbc should apply. The section "Specifying Block Types" explains
2996 how to list block types.
2997 Note on using the -blao and -blbc options.
2999 These blank line controls introduce a certain minimum number of
3000 blank lines in the text, but the final number of blank lines may be
3001 greater, depending on values of the other blank line controls and
3002 the number of old blank lines. A consequence is that introducing
3003 blank lines with these and other controls cannot be exactly undone,
3004 so some experimentation with these controls is recommended before
3005 using them.
3006 For example, suppose that for some reason we decide to introduce
3008 one blank space at the beginning and ending of all blocks. We
3009 could do this using
3010 perltidy -blao=2 -blbc=2 -blaol='*' -blbcl='*' filename
3012 Now suppose the script continues to be developed, but at some later
3014 date we decide we don't want these spaces after all. we might
3015 expect that running with the flags -blao=0 and -blbc=0 will undo
3016 them. However, by default perltidy retains single blank lines, so
3017 the blank lines remain.
3018 We can easily fix this by telling perltidy to ignore old blank
3020 lines by including the added parameter -kbl=0 and rerunning. Then
3021 the unwanted blank lines will be gone. However, this will cause
3022 all old blank lines to be ignored, perhaps even some that were
3023 added by hand to improve formatting. So please be cautious when
3024 using these parameters.
3025 -mbl=n --maximum-consecutive-blank-lines=n
3027 This parameter specifies the maximum number of consecutive blank
3028 lines which will be output within code sections of a script. The
3029 default is n=1. If the input file has more than n consecutive
3030 blank lines, the number will be reduced to n except as noted above
3031 for the -blbp and -blbs parameters. If n=0 then no blank lines
3032 will be output (unless all old blank lines are retained with the
3033 -kbl=2 flag of the next section).
3034 This flag obviously does not apply to pod sections, here-documents,
3036 and quotes.
3037 -kbl=n, --keep-old-blank-lines=n
3039 The -kbl=n flag gives you control over how your existing blank
3040 lines are treated.
3041 The possible values of n are:
3043 n=0 ignore all old blank lines
3045 n=1 stable: keep old blanks, but limited by the value of the B<-mbl=n> flag
3046 n=2 keep all old blank lines, regardless of the value of the B<-mbl=n> flag
3047 The default is n=1.
3049 -sob, --swallow-optional-blank-lines
3051 This is equivalent to kbl=0 and is included for compatibility with
3052 previous versions.
3053 -nsob, --noswallow-optional-blank-lines
3055 This is equivalent to kbl=1 and is included for compatibility with
3056 previous versions.
3057 Controls for blank lines around lines of consecutive keywords
3059 The parameters in this section provide some control over the placement
3061 of blank lines within and around groups of statements beginning with
3062 selected keywords. These blank lines are called here keyword group
3063 blanks, and all of the parameters begin with --keyword-group-blanks*,
3064 or -kgb* for short. The default settings do not employ these controls
3065 but they can be enabled with the following parameters:
3066 -kgbl=s or --keyword-group-blanks-list=s; s is a quoted string of
3068 keywords
3069 -kgbs=s or --keyword-group-blanks-size=s; s gives the number of
3071 keywords required to form a group.
3072 -kgbb=n or --keyword-group-blanks-before=n; n = (0, 1, or 2) controls a
3074 leading blank
3075 -kgba=n or --keyword-group-blanks-after=n; n = (0, 1, or 2) controls a
3077 trailing blank
3078 -kgbi or --keyword-group-blanks-inside is a switch for adding blanks
3080 between subgroups
3081 -kgbd or --keyword-group-blanks-delete is a switch for removing initial
3083 blank lines between keywords
3084 -kgbr=n or --keyword-group-blanks-repeat-count=n can limit the number
3086 of times this logic is applied
3087 In addition, the following abbreviations are available to for
3089 simplified usage:
3090 -kgb or --keyword-group-blanks is short for -kgbb=2 -kgba=2 kgbi
3092 -nkgb or --nokeyword-group-blanks, is short for -kgbb=1 -kgba=1 nkgbi
3094 Before describing the meaning of the parameters in detail let us look
3096 at an example which is formatted with default parameter settings.
3097 print "Entering test 2\n";
3099 use Test;
3100 use Encode qw(from_to encode decode
3101 encode_utf8 decode_utf8
3102 find_encoding is_utf8);
3103 use charnames qw(greek);
3104 my @encodings = grep( /iso-?8859/, Encode::encodings() );
3105 my @character_set = ( '0' .. '9', 'A' .. 'Z', 'a' .. 'z' );
3106 my @source = qw(ascii iso8859-1 cp1250);
3107 my @destiny = qw(cp1047 cp37 posix-bc);
3108 my @ebcdic_sets = qw(cp1047 cp37 posix-bc);
3109 my $str = join( '', map( chr($_), 0x20 .. 0x7E ) );
3110 return unless ($str);
3111 using perltidy -kgb gives:
3113 print "Entering test 2\n";
3115 <----------this blank controlled by -kgbb
3116 use Test;
3117 use Encode qw(from_to encode decode
3118 encode_utf8 decode_utf8
3119 find_encoding is_utf8);
3120 use charnames qw(greek);
3121 <---------this blank controlled by -kgbi
3122 my @encodings = grep( /iso-?8859/, Encode::encodings() );
3123 my @character_set = ( '0' .. '9', 'A' .. 'Z', 'a' .. 'z' );
3124 my @source = qw(ascii iso8859-1 cp1250);
3125 my @destiny = qw(cp1047 cp37 posix-bc);
3126 my @ebcdic_sets = qw(cp1047 cp37 posix-bc);
3127 my $str = join( '', map( chr($_), 0x20 .. 0x7E ) );
3128 <----------this blank controlled by -kgba
3129 return unless ($str);
3130 Blank lines have been introduced around the my and use sequences. What
3132 happened is that the default keyword list includes my and use but not
3133 print and return. So a continuous sequence of nine my and use
3134 statements was located. This number exceeds the default threshold of
3135 five, so blanks were placed before and after the entire group. Then,
3136 since there was also a subsequence of six my lines, a blank line was
3137 introduced to separate them.
3138 Finer control over blank placement can be achieved by using the
3140 individual parameters rather than the -kgb flag. The individual
3141 controls are as follows.
3142 -kgbl=s or --keyword-group-blanks-list=s, where s is a quoted string,
3144 defines the set of keywords which will be formed into groups. The
3145 string is a space separated list of keywords. The default set is
3146 s="use require local our my", but any list of keywords may be used.
3147 Comment lines may also be included in a keyword group, even though they
3148 are not keywords. To include ordinary block comments, include the
3149 symbol BC. To include static block comments (which normally begin with
3150 '##'), include the symbol SBC.
3151 -kgbs=s or --keyword-group-blanks-size=s, where s is a string
3153 describing the number of consecutive keyword statements forming a
3154 group. If s is an integer then it is the minimum number required for a
3155 group. A maximum value may also be given with the format s=min.max,
3156 where min is the minimum number and max is the maximum number, and the
3157 min and max values are separated by one or more dots. No groups will
3158 be found if the maximum is less than the minimum. The maximum is
3159 unlimited if not given. The default is s=5. Some examples:
3160 s min max number for group
3162 3 3 unlimited 3 or more
3163 1.1 1 1 1
3164 1..3 1 3 1 to 3
3165 1.0 1 0 (no match)
3166 -kgbb=n or --keyword-group-blanks-before=n specifies whether a blank
3168 should appear before the first line of the group, as follows:
3169 n=0 => (delete) an existing blank line will be removed
3171 n=1 => (stable) no change to the input file is made [DEFAULT]
3172 n=2 => (insert) a blank line is introduced if possible
3173 -kgba=n or --keyword-group-blanks-after=n likewise specifies whether a
3175 blank should appear after the last line of the group, using the same
3176 scheme (0=delete, 1=stable, 2=insert).
3177 -kgbi or --keyword-group-blanks-inside controls the insertion of blank
3179 lines between the first and last statement of the entire group. If
3180 there is a continuous run of a single statement type with more than the
3181 minimum threshold number (as specified with -kgbs=s) then this switch
3182 causes a blank line be inserted between this subgroup and the others.
3183 In the example above this happened between the use and my statements.
3184 -kgbd or --keyword-group-blanks-delete controls the deletion of any
3186 blank lines that exist in the the group when it is first scanned. When
3187 statements are initially scanned, any existing blank lines are included
3188 in the collection. Any such orignial blank lines will be deleted
3189 before any other insertions are made when the parameter -kgbd is set.
3190 The default is not to do this, -nkgbd.
3191 -kgbr=n or --keyword-group-blanks-repeat-count=n specifies n, the
3193 maximum number of times this logic will be applied to any file. The
3194 special value n=0 is the same as n=infinity which means it will be
3195 applied to an entire script [Default]. A value n=1 could be used to
3196 make it apply just one time for example. This might be useful for
3197 adjusting just the use statements in the top part of a module for
3198 example.
3199 -kgb or --keyword-group-blanks is an abbreviation equivalent to setting
3201 -kgbb=1 -kgba=1 -kgbi. This turns on keyword group formatting with a
3202 set of default values.
3203 -nkgb or --nokeyword-group-blanks is equivalent to -kgbb=0 -kgba nkgbi.
3205 This flag turns off keyword group blank lines and is the default
3206 setting.
3207 Here are a few notes about the functioning of this technique.
3209 · These parameters are probably more useful as part of a major code
3211 reformatting operation rather than as a routine formatting
3212 operation.
3213 In particular, note that deleting old blank lines with -kgbd is an
3215 irreversible operation so it should be applied with care. Existing
3216 blank lines may be serving an important role in controlling
3217 vertical alignment.
3218 · Conflicts which arise among these kgb* parameters and other blank
3220 line controls are generally resolved by producing the maximum
3221 number of blank lines implied by any parameter.
3222 For example, if the flags --freeze-blank-lines, or
3224 --keep-old-blank-lines=2, are set, then they have priority over any
3225 blank line deletion implied by the -kgb flags of this section, so
3226 no blank lines will be deleted.
3227 For another example, if a keyword group ends at a sub and the flag
3229 kgba=0 requests no blank line there, but we also have
3230 --blank-lines-before-subs=2, then two blank lines will still be
3231 introduced before the sub.
3232 · The introduction of blank lines does not occur if it would conflict
3234 with other input controls or code validity. For example, a blank
3235 line will not be placed within a here-doc or within a section of
3236 code marked with format skipping comments. And in general, a blank
3237 line will only be introduced at the end of a group if the next
3238 statement is a line of code.
3239 · The count which is used to determine the group size is not the
3241 number of lines but rather the total number of keywords which are
3242 found. Individual statements with a certain leading keyword may
3243 continue on multiple lines, but if any of these lines is nested
3244 more than one level deep then that group will be ended.
3245 · The search for groups of lines with similar leading keywords is
3247 based on the input source, not the final formatted source.
3248 Consequently, if the source code is badly formatted, it would be
3249 best to make a first formatting pass without these options.
3250 Styles
3252 A style refers to a convenient collection of existing parameters.
3253 -gnu, --gnu-style
3255 -gnu gives an approximation to the GNU Coding Standards (which do
3256 not apply to perl) as they are sometimes implemented. At present,
3257 this style overrides the default style with the following
3258 parameters:
3259 -lp -bl -noll -pt=2 -bt=2 -sbt=2 -icp
3261 -pbp, --perl-best-practices
3263 -pbp is an abbreviation for the parameters in the book Perl Best
3264 Practices by Damian Conway:
3265 -l=78 -i=4 -ci=4 -st -se -vt=2 -cti=0 -pt=1 -bt=1 -sbt=1 -bbt=1 -nsfs -nolq
3267 -wbb="% + - * / x != == >= <= =~ !~ < > | & =
3268 **= += *= &= <<= &&= -= /= |= >>= ||= //= .= %= ^= x="
3269 Please note that this parameter set includes -st and -se flags,
3271 which make perltidy act as a filter on one file only. These can be
3272 overridden by placing -nst and/or -nse after the -pbp parameter.
3273 Also note that the value of continuation indentation, -ci=4, is
3275 equal to the value of the full indentation, -i=4. In some complex
3276 statements perltidy will produce nicer results with -ci=2. This can
3277 be implemented by including -ci=2 after the -pbp parameter. For
3278 example,
3279 # perltidy -pbp
3281 $self->{_text} = (
3282 !$section ? ''
3283 : $type eq 'item' ? "the $section entry"
3284 : "the section on $section"
3285 )
3286 . (
3287 $page
3288 ? ( $section ? ' in ' : '' ) . "the $page$page_ext manpage"
3289 : ' elsewhere in this document'
3290 );
3291 # perltidy -pbp -ci=2
3293 $self->{_text} = (
3294 !$section ? ''
3295 : $type eq 'item' ? "the $section entry"
3296 : "the section on $section"
3297 )
3298 . (
3299 $page
3300 ? ( $section ? ' in ' : '' ) . "the $page$page_ext manpage"
3301 : ' elsewhere in this document'
3302 );
3303 One-line blocks
3305 There are a few points to note regarding one-line blocks. A one-
3306 line block is something like this,
3307 if ($x > 0) { $y = 1 / $x }
3309 where the contents within the curly braces is short enough to fit
3311 on a single line.
3312 With few exceptions, perltidy retains existing one-line blocks, if
3314 it is possible within the line-length constraint, but it does not
3315 attempt to form new ones. In other words, perltidy will try to
3316 follow the one-line block style of the input file.
3317 If an existing one-line block is longer than the maximum line
3319 length, however, it will be broken into multiple lines. When this
3320 happens, perltidy checks for and adds any optional terminating
3321 semicolon (unless the -nasc option is used) if the block is a code
3322 block.
3323 The main exception is that perltidy will attempt to form new one-
3325 line blocks following the keywords "map", "eval", and "sort",
3326 because these code blocks are often small and most clearly
3327 displayed in a single line.
3328 One-line block rules can conflict with the cuddled-else option.
3330 When the cuddled-else option is used, perltidy retains existing
3331 one-line blocks, even if they do not obey cuddled-else formatting.
3332 Occasionally, when one-line blocks get broken because they exceed
3334 the available line length, the formatting will violate the
3335 requested brace style. If this happens, reformatting the script a
3336 second time should correct the problem.
3337 Sometimes it might be desirable to convert a script to have one-
3339 line blocks whenever possible. Although there is currently no flag
3340 for this, a simple workaround is to execute perltidy twice, once
3341 with the flag -noadd-newlines and then once again with normal
3342 parameters, like this:
3343 cat infile | perltidy -nanl | perltidy >outfile
3345 When executed on this snippet
3347 if ( $? == -1 ) {
3349 die "failed to execute: $!\n";
3350 }
3351 if ( $? == -1 ) {
3352 print "Had enough.\n";
3353 die "failed to execute: $!\n";
3354 }
3355 the result is
3357 if ( $? == -1 ) { die "failed to execute: $!\n"; }
3359 if ( $? == -1 ) {
3360 print "Had enough.\n";
3361 die "failed to execute: $!\n";
3362 }
3363 This shows that blocks with a single statement become one-line
3365 blocks.
3366 -olbs=n, --one-line-block-semicolons=n
3368 This flag controls the placement of semicolons at the end of one-
3369 line blocks. Semicolons are optional before a closing block brace,
3370 and frequently they are omitted at the end of a one-line block
3371 containing just a single statement. By default, perltidy follows
3372 the input file regarding these semicolons, but this behavior can be
3373 controlled by this flag. The values of n are:
3374 n=0 remove terminal semicolons in one-line blocks having a single statement
3376 n=1 stable; keep input file placement of terminal semicolons [DEFAULT ]
3377 n=2 add terminal semicolons in all one-line blocks
3378 Note that the n=2 option has no effect if adding semicolons is
3380 prohibited with the -nasc flag. Also not that while n=2 adds
3381 missing semicolons to all one-line blocks, regardless of
3382 complexity, the n=0 option only removes ending semicolons which
3383 terminate one-line blocks containing just one semicolon. So these
3384 two options are not exact inverses.
3385 -olbn=n, --one-line-block-nesting=n
3387 Nested one-line blocks are lines with code blocks which themselves
3388 contain code blocks. For example, the following line is a nested
3389 one-line block.
3390 foreach (@list) { if ($_ eq $asked_for) { last } ++$found }
3392 The default behavior is to break such lines into multiple lines,
3394 but this behavior can be controlled with this flag. The values of
3395 n are:
3396 n=0 break nested one-line blocks into multiple lines [DEFAULT]
3398 n=1 stable: keep existing nested-one line blocks intact
3399 For the above example, the default formatting (-olbn=0) is
3401 foreach (@list) {
3403 if ( $_ eq $asked_for ) { last }
3404 ++$found;
3405 }
3406 If the parameter -olbn=1 is given, then the line will be left
3408 intact if it is a single line in the source, or it will be broken
3409 into multiple lines if it is broken in multiple lines in the
3410 source.
3411 Controlling Vertical Alignment
3413 Vertical alignment refers to lining up certain symbols in a list of
3414 consecutive similar lines to improve readability. For example, the
3415 "fat commas" are aligned in the following statement:
3416 $data = $pkg->new(
3418 PeerAddr => join( ".", @port[ 0 .. 3 ] ),
3419 PeerPort => $port[4] * 256 + $port[5],
3420 Proto => 'tcp'
3421 );
3422 The only explicit control on vertical alignment is to turn it off using
3424 -novalign, a flag mainly intended for debugging. However, vertical
3425 alignment can be forced to stop and restart by selectively introducing
3426 blank lines. For example, a blank has been inserted in the following
3427 code to keep somewhat similar things aligned.
3428 %option_range = (
3430 'format' => [ 'tidy', 'html', 'user' ],
3431 'output-line-ending' => [ 'dos', 'win', 'mac', 'unix' ],
3432 'character-encoding' => [ 'none', 'utf8' ],
3433 'block-brace-tightness' => [ 0, 2 ],
3435 'brace-tightness' => [ 0, 2 ],
3436 'paren-tightness' => [ 0, 2 ],
3437 'square-bracket-tightness' => [ 0, 2 ],
3438 );
3439 Other Controls
3441 Deleting selected text
3442 Perltidy can selectively delete comments and/or pod documentation.
3443 The command -dac or --delete-all-comments will delete all comments
3444 and all pod documentation, leaving just code and any leading system
3445 control lines.
3446 The command -dp or --delete-pod will remove all pod documentation
3448 (but not comments).
3449 Two commands which remove comments (but not pod) are: -dbc or
3451 --delete-block-comments and -dsc or --delete-side-comments.
3452 (Hanging side comments will be deleted with side comments here.)
3453 The negatives of these commands also work, and are the defaults.
3455 When block comments are deleted, any leading 'hash-bang' will be
3456 retained. Also, if the -x flag is used, any system commands before
3457 a leading hash-bang will be retained (even if they are in the form
3458 of comments).
3459 Writing selected text to a file
3461 When perltidy writes a formatted text file, it has the ability to
3462 also send selected text to a file with a .TEE extension. This text
3463 can include comments and pod documentation.
3464 The command -tac or --tee-all-comments will write all comments and
3466 all pod documentation.
3467 The command -tp or --tee-pod will write all pod documentation (but
3469 not comments).
3470 The commands which write comments (but not pod) are: -tbc or
3472 --tee-block-comments and -tsc or --tee-side-comments. (Hanging
3473 side comments will be written with side comments here.)
3474 The negatives of these commands also work, and are the defaults.
3476 Using a .perltidyrc command file
3478 If you use perltidy frequently, you probably won't be happy until
3479 you create a .perltidyrc file to avoid typing commonly-used
3480 parameters. Perltidy will first look in your current directory for
3481 a command file named .perltidyrc. If it does not find one, it will
3482 continue looking for one in other standard locations.
3483 These other locations are system-dependent, and may be displayed
3485 with the command "perltidy -dpro". Under Unix systems, it will
3486 first look for an environment variable PERLTIDY. Then it will look
3487 for a .perltidyrc file in the home directory, and then for a
3488 system-wide file /usr/local/etc/perltidyrc, and then it will look
3489 for /etc/perltidyrc. Note that these last two system-wide files do
3490 not have a leading dot. Further system-dependent information will
3491 be found in the INSTALL file distributed with perltidy.
3492 Under Windows, perltidy will also search for a configuration file
3494 named perltidy.ini since Windows does not allow files with a
3495 leading period (.). Use "perltidy -dpro" to see the possible
3496 locations for your system. An example might be C:\Documents and
3497 Settings\All Users\perltidy.ini.
3498 Another option is the use of the PERLTIDY environment variable.
3500 The method for setting environment variables depends upon the
3501 version of Windows that you are using. Instructions for Windows 95
3502 and later versions can be found here:
3503 http://www.netmanage.com/000/20021101_005_tcm21-6336.pdf
3505 Under Windows NT / 2000 / XP the PERLTIDY environment variable can
3507 be placed in either the user section or the system section. The
3508 later makes the configuration file common to all users on the
3509 machine. Be sure to enter the full path of the configuration file
3510 in the value of the environment variable. Ex.
3511 PERLTIDY=C:\Documents and Settings\perltidy.ini
3512 The configuration file is free format, and simply a list of
3514 parameters, just as they would be entered on a command line. Any
3515 number of lines may be used, with any number of parameters per
3516 line, although it may be easiest to read with one parameter per
3517 line. Comment text begins with a #, and there must also be a space
3518 before the # for side comments. It is a good idea to put complex
3519 parameters in either single or double quotes.
3520 Here is an example of a .perltidyrc file:
3522 # This is a simple of a .perltidyrc configuration file
3524 # This implements a highly spaced style
3525 -se # errors to standard error output
3526 -w # show all warnings
3527 -bl # braces on new lines
3528 -pt=0 # parens not tight at all
3529 -bt=0 # braces not tight
3530 -sbt=0 # square brackets not tight
3531 The parameters in the .perltidyrc file are installed first, so any
3533 parameters given on the command line will have priority over them.
3534 To avoid confusion, perltidy ignores any command in the .perltidyrc
3536 file which would cause some kind of dump and an exit. These are:
3537 -h -v -ddf -dln -dop -dsn -dtt -dwls -dwrs -ss
3539 There are several options may be helpful in debugging a .perltidyrc
3541 file:
3542 · A very helpful command is --dump-profile or -dpro. It writes a
3544 list of all configuration filenames tested to standard output,
3545 and if a file is found, it dumps the content to standard output
3546 before exiting. So, to find out where perltidy looks for its
3547 configuration files, and which one if any it selects, just
3548 enter
3549 perltidy -dpro
3551 · It may be simplest to develop and test configuration files with
3553 alternative names, and invoke them with -pro=filename on the
3554 command line. Then rename the desired file to .perltidyrc when
3555 finished.
3556 · The parameters in the .perltidyrc file can be switched off with
3558 the -npro option.
3559 · The commands --dump-options, --dump-defaults,
3561 --dump-long-names, and --dump-short-names, all described below,
3562 may all be helpful.
3563 Creating a new abbreviation
3565 A special notation is available for use in a .perltidyrc file for
3566 creating an abbreviation for a group of options. This can be used
3567 to create a shorthand for one or more styles which are frequently,
3568 but not always, used. The notation is to group the options within
3569 curly braces which are preceded by the name of the alias (without
3570 leading dashes), like this:
3571 newword {
3573 -opt1
3574 -opt2
3575 }
3576 where newword is the abbreviation, and opt1, etc, are existing
3578 parameters or other abbreviations. The main syntax requirement is
3579 that the new abbreviation along with its opening curly brace must
3580 begin on a new line. Space before and after the curly braces is
3581 optional. For a specific example, the following line
3582 airy {-bl -pt=0 -bt=0 -sbt=0}
3584 could be placed in a .perltidyrc file, and then invoked at will
3586 with
3587 perltidy -airy somefile.pl
3589 (Either "-airy" or "--airy" may be used).
3591 Skipping leading non-perl commands with -x or --look-for-hash-bang
3593 If your script has leading lines of system commands or other text
3594 which are not valid perl code, and which are separated from the
3595 start of the perl code by a "hash-bang" line, ( a line of the form
3596 "#!...perl" ), you must use the -x flag to tell perltidy not to
3597 parse and format any lines before the "hash-bang" line. This
3598 option also invokes perl with a -x flag when checking the syntax.
3599 This option was originally added to allow perltidy to parse
3600 interactive VMS scripts, but it should be used for any script which
3601 is normally invoked with "perl -x".
3602 Please note: do not use this flag unless you are sure your script
3604 needs it. Parsing errors can occur if it does not have a hash-
3605 bang, or, for example, if the actual first hash-bang is in a here-
3606 doc. In that case a parsing error will occur because the
3607 tokenization will begin in the middle of the here-doc.
3608 Making a file unreadable
3610 The goal of perltidy is to improve the readability of files, but
3611 there are two commands which have the opposite effect, --mangle and
3612 --extrude. They are actually merely aliases for combinations of
3613 other parameters. Both of these strip all possible whitespace, but
3614 leave comments and pod documents, so that they are essentially
3615 reversible. The difference between these is that --mangle puts the
3616 fewest possible line breaks in a script while --extrude puts the
3617 maximum possible. Note that these options do not provided any
3618 meaningful obfuscation, because perltidy can be used to reformat
3619 the files. They were originally developed to help test the
3620 tokenization logic of perltidy, but they have other uses. One use
3621 for --mangle is the following:
3622 perltidy --mangle myfile.pl -st | perltidy -o myfile.pl.new
3624 This will form the maximum possible number of one-line blocks (see
3626 next section), and can sometimes help clean up a badly formatted
3627 script.
3628 A similar technique can be used with --extrude instead of --mangle
3630 to make the minimum number of one-line blocks.
3631 Another use for --mangle is to combine it with -dac to reduce the
3633 file size of a perl script.
3634 Debugging
3636 The following flags are available for debugging:
3637 --dump-cuddled-block-list or -dcbl will dump to standard output the
3639 internal hash of cuddled block types created by a
3640 -cuddled-block-list input string.
3641 --dump-defaults or -ddf will write the default option set to
3643 standard output and quit
3644 --dump-profile or -dpro will write the name of the current
3646 configuration file and its contents to standard output and quit.
3647 --dump-options or -dop will write current option set to standard
3649 output and quit.
3650 --dump-long-names or -dln will write all command line long names
3652 (passed to Get_options) to standard output and quit.
3653 --dump-short-names or -dsn will write all command line short names
3655 to standard output and quit.
3656 --dump-token-types or -dtt will write a list of all token types to
3658 standard output and quit.
3659 --dump-want-left-space or -dwls will write the hash
3661 %want_left_space to standard output and quit. See the section on
3662 controlling whitespace around tokens.
3663 --dump-want-right-space or -dwrs will write the hash
3665 %want_right_space to standard output and quit. See the section on
3666 controlling whitespace around tokens.
3667 --no-memoize or -nmem will turn of memoizing. Memoization can
3669 reduce run time when running perltidy repeatedly in a single
3670 process. It is on by default but can be deactivated for testing
3671 with -nmem.
3672 --no-timestamp or -nts will eliminate any time stamps in output
3674 files to prevent differences in dates from causing test
3675 installation scripts to fail. There are just a couple of places
3676 where timestamps normally occur. One is in the headers of html
3677 files, and another is when the -cscw option is selected. The
3678 default is to allow timestamps (--timestamp or -ts).
3679 --file-size-order or -fso will cause files to be processed in order
3681 of increasing size, when multiple files are being processed. This
3682 is useful during program development, when large numbers of files
3683 with varying sizes are processed, because it can reduce virtual
3684 memory usage.
3685 -DEBUG will write a file with extension .DEBUG for each input file
3687 showing the tokenization of all lines of code.
3688 Working with MakeMaker, AutoLoader and SelfLoader
3690 The first $VERSION line of a file which might be eval'd by
3691 MakeMaker is passed through unchanged except for indentation. Use
3692 --nopass-version-line, or -npvl, to deactivate this feature.
3693 If the AutoLoader module is used, perltidy will continue formatting
3695 code after seeing an __END__ line. Use --nolook-for-autoloader, or
3696 -nlal, to deactivate this feature.
3697 Likewise, if the SelfLoader module is used, perltidy will continue
3699 formatting code after seeing a __DATA__ line. Use
3700 --nolook-for-selfloader, or -nlsl, to deactivate this feature.
3701 Working around problems with older version of Perl
3703 Perltidy contains a number of rules which help avoid known
3704 subtleties and problems with older versions of perl, and these
3705 rules always take priority over whatever formatting flags have been
3706 set. For example, perltidy will usually avoid starting a new line
3707 with a bareword, because this might cause problems if "use strict"
3708 is active.
3709 There is no way to override these rules.
3711
3713 The -html master switch
3714 The flag -html causes perltidy to write an html file with extension
3715 .html. So, for example, the following command
3716 perltidy -html somefile.pl
3718 will produce a syntax-colored html file named somefile.pl.html
3720 which may be viewed with a browser.
3721 Please Note: In this case, perltidy does not do any formatting to
3723 the input file, and it does not write a formatted file with
3724 extension .tdy. This means that two perltidy runs are required to
3725 create a fully reformatted, html copy of a script.
3726 The -pre flag for code snippets
3728 When the -pre flag is given, only the pre-formatted section, within
3729 the <PRE> and </PRE> tags, will be output. This simplifies
3730 inclusion of the output in other files. The default is to output a
3731 complete web page.
3732 The -nnn flag for line numbering
3734 When the -nnn flag is given, the output lines will be numbered.
3735 The -toc, or --html-table-of-contents flag
3737 By default, a table of contents to packages and subroutines will be
3738 written at the start of html output. Use -ntoc to prevent this.
3739 This might be useful, for example, for a pod document which
3740 contains a number of unrelated code snippets. This flag only
3741 influences the code table of contents; it has no effect on any
3742 table of contents produced by pod2html (see next item).
3743 The -pod, or --pod2html flag
3745 There are two options for formatting pod documentation. The
3746 default is to pass the pod through the Pod::Html module (which
3747 forms the basis of the pod2html utility). Any code sections are
3748 formatted by perltidy, and the results then merged. Note: perltidy
3749 creates a temporary file when Pod::Html is used; see "FILES".
3750 Also, Pod::Html creates temporary files for its cache.
3751 NOTE: Perltidy counts the number of "=cut" lines, and either moves
3753 the pod text to the top of the html file if there is one "=cut", or
3754 leaves the pod text in its original order (interleaved with code)
3755 otherwise.
3756 Most of the flags accepted by pod2html may be included in the
3758 perltidy command line, and they will be passed to pod2html. In
3759 some cases, the flags have a prefix "pod" to emphasize that they
3760 are for the pod2html, and this prefix will be removed before they
3761 are passed to pod2html. The flags which have the additional "pod"
3762 prefix are:
3763 --[no]podheader --[no]podindex --[no]podrecurse --[no]podquiet
3765 --[no]podverbose --podflush
3766 The flags which are unchanged from their use in pod2html are:
3768 --backlink=s --cachedir=s --htmlroot=s --libpods=s --title=s
3770 --podpath=s --podroot=s
3771 where 's' is an appropriate character string. Not all of these
3773 flags are available in older versions of Pod::Html. See your
3774 Pod::Html documentation for more information.
3775 The alternative, indicated with -npod, is not to use Pod::Html, but
3777 rather to format pod text in italics (or whatever the stylesheet
3778 indicates), without special html markup. This is useful, for
3779 example, if pod is being used as an alternative way to write
3780 comments.
3781 The -frm, or --frames flag
3783 By default, a single html output file is produced. This can be
3784 changed with the -frm option, which creates a frame holding a table
3785 of contents in the left panel and the source code in the right
3786 side. This simplifies code browsing. Assume, for example, that the
3787 input file is MyModule.pm. Then, for default file extension
3788 choices, these three files will be created:
3789 MyModule.pm.html - the frame
3791 MyModule.pm.toc.html - the table of contents
3792 MyModule.pm.src.html - the formatted source code
3793 Obviously this file naming scheme requires that output be directed
3795 to a real file (as opposed to, say, standard output). If this is
3796 not the case, or if the file extension is unknown, the -frm option
3797 will be ignored.
3798 The -text=s, or --html-toc-extension flag
3800 Use this flag to specify the extra file extension of the table of
3801 contents file when html frames are used. The default is "toc".
3802 See "Specifying File Extensions".
3803 The -sext=s, or --html-src-extension flag
3805 Use this flag to specify the extra file extension of the content
3806 file when html frames are used. The default is "src". See
3807 "Specifying File Extensions".
3808 The -hent, or --html-entities flag
3810 This flag controls the use of Html::Entities for html formatting.
3811 By default, the module Html::Entities is used to encode special
3812 symbols. This may not be the right thing for some browser/language
3813 combinations. Use --nohtml-entities or -nhent to prevent this.
3814 Style Sheets
3816 Style sheets make it very convenient to control and adjust the
3817 appearance of html pages. The default behavior is to write a page
3818 of html with an embedded style sheet.
3819 An alternative to an embedded style sheet is to create a page with
3821 a link to an external style sheet. This is indicated with the
3822 -css=filename, where the external style sheet is filename. The
3823 external style sheet filename will be created if and only if it
3824 does not exist. This option is useful for controlling multiple
3825 pages from a single style sheet.
3826 To cause perltidy to write a style sheet to standard output and
3828 exit, use the -ss, or --stylesheet, flag. This is useful if the
3829 style sheet could not be written for some reason, such as if the
3830 -pre flag was used. Thus, for example,
3831 perltidy -html -ss >mystyle.css
3833 will write a style sheet with the default properties to file
3835 mystyle.css.
3836 The use of style sheets is encouraged, but a web page without a
3838 style sheets can be created with the flag -nss. Use this option if
3839 you must to be sure that older browsers (roughly speaking, versions
3840 prior to 4.0 of Netscape Navigator and Internet Explorer) can
3841 display the syntax-coloring of the html files.
3842 Controlling HTML properties
3844 Note: It is usually more convenient to accept the default
3845 properties and then edit the stylesheet which is produced.
3846 However, this section shows how to control the properties with
3847 flags to perltidy.
3848 Syntax colors may be changed from their default values by flags of
3850 the either the long form, -html-color-xxxxxx=n, or more
3851 conveniently the short form, -hcx=n, where xxxxxx is one of the
3852 following words, and x is the corresponding abbreviation:
3853 Token Type xxxxxx x
3855 ---------- -------- --
3856 comment comment c
3857 number numeric n
3858 identifier identifier i
3859 bareword, function bareword w
3860 keyword keyword k
3861 quite, pattern quote q
3862 here doc text here-doc-text h
3863 here doc target here-doc-target hh
3864 punctuation punctuation pu
3865 parentheses paren p
3866 structural braces structure s
3867 semicolon semicolon sc
3868 colon colon co
3869 comma comma cm
3870 label label j
3871 sub definition name subroutine m
3872 pod text pod-text pd
3873 A default set of colors has been defined, but they may be changed
3875 by providing values to any of the following parameters, where n is
3876 either a 6 digit hex RGB color value or an ascii name for a color,
3877 such as 'red'.
3878 To illustrate, the following command will produce an html file
3880 somefile.pl.html with "aqua" keywords:
3881 perltidy -html -hck=00ffff somefile.pl
3883 and this should be equivalent for most browsers:
3885 perltidy -html -hck=aqua somefile.pl
3887 Perltidy merely writes any non-hex names that it sees in the html
3889 file. The following 16 color names are defined in the HTML 3.2
3890 standard:
3891 black => 000000,
3893 silver => c0c0c0,
3894 gray => 808080,
3895 white => ffffff,
3896 maroon => 800000,
3897 red => ff0000,
3898 purple => 800080,
3899 fuchsia => ff00ff,
3900 green => 008000,
3901 lime => 00ff00,
3902 olive => 808000,
3903 yellow => ffff00
3904 navy => 000080,
3905 blue => 0000ff,
3906 teal => 008080,
3907 aqua => 00ffff,
3908 Many more names are supported in specific browsers, but it is
3910 safest to use the hex codes for other colors. Helpful color tables
3911 can be located with an internet search for "HTML color tables".
3912 Besides color, two other character attributes may be set: bold, and
3914 italics. To set a token type to use bold, use the flag
3915 --html-bold-xxxxxx or -hbx, where xxxxxx or x are the long or short
3916 names from the above table. Conversely, to set a token type to NOT
3917 use bold, use --nohtml-bold-xxxxxx or -nhbx.
3918 Likewise, to set a token type to use an italic font, use the flag
3920 --html-italic-xxxxxx or -hix, where again xxxxxx or x are the long
3921 or short names from the above table. And to set a token type to
3922 NOT use italics, use --nohtml-italic-xxxxxx or -nhix.
3923 For example, to use bold braces and lime color, non-bold, italics
3925 keywords the following command would be used:
3926 perltidy -html -hbs -hck=00FF00 -nhbk -hik somefile.pl
3928 The background color can be specified with
3930 --html-color-background=n, or -hcbg=n for short, where n is a 6
3931 character hex RGB value. The default color of text is the value
3932 given to punctuation, which is black as a default.
3933 Here are some notes and hints:
3935 1. If you find a preferred set of these parameters, you may want to
3937 create a .perltidyrc file containing them. See the perltidy man
3938 page for an explanation.
3939 2. Rather than specifying values for these parameters, it is
3941 probably easier to accept the defaults and then edit a style sheet.
3942 The style sheet contains comments which should make this easy.
3943 3. The syntax-colored html files can be very large, so it may be
3945 best to split large files into smaller pieces to improve download
3946 times.
3947
3949 Specifying Block Types
3950 Several parameters which refer to code block types may be customized by
3951 also specifying an associated list of block types. The type of a block
3952 is the name of the keyword which introduces that block, such as if,
3953 else, or sub. An exception is a labeled block, which has no keyword,
3954 and should be specified with just a colon. To specify all blocks use
3955 '*'.
3956 The keyword sub indicates a named sub. For anonymous subs, use the
3958 special keyword asub.
3959 For example, the following parameter specifies "sub", labels, "BEGIN",
3961 and "END" blocks:
3962 -cscl="sub : BEGIN END"
3964 (the meaning of the -cscl parameter is described above.) Note that
3966 quotes are required around the list of block types because of the
3967 spaces. For another example, the following list specifies all block
3968 types for vertical tightness:
3969 -bbvtl='*'
3971 Specifying File Extensions
3973 Several parameters allow default file extensions to be overridden. For
3974 example, a backup file extension may be specified with -bext=ext, where
3975 ext is some new extension. In order to provides the user some
3976 flexibility, the following convention is used in all cases to decide if
3977 a leading '.' should be used. If the extension "ext" begins with
3978 "A-Z", "a-z", or "0-9", then it will be appended to the filename with
3979 an intermediate '.' (or perhaps a '_' on VMS systems). Otherwise, it
3980 will be appended directly.
3981 For example, suppose the file is somefile.pl. For "-bext=old", a '.'
3983 is added to give somefile.pl.old. For "-bext=.old", no additional '.'
3984 is added, so again the backup file is somefile.pl.old. For "-bext=~",
3985 then no dot is added, and the backup file will be somefile.pl~ .
3986
3988 The following list shows all short parameter names which allow a prefix
3989 'n' to produce the negated form:
3990 D anl asc aws b bbb bbc bbs bl bli boc bok bol bot ce
3992 csc dac dbc dcsc ddf dln dnl dop dp dpro dsc dsm dsn dtt dwls
3993 dwrs dws f fll frm fs hsc html ibc icb icp iob isbc lal log
3994 lp lsl ohbr okw ola oll opr opt osbr otr ple pod pvl q
3995 sbc sbl schb scp scsb sct se sfp sfs skp sob sohb sop sosb sot
3996 ssc st sts syn t tac tbc toc tp tqw tsc w x bar kis
3997 Equivalently, the prefix 'no' or 'no-' on the corresponding long names
3999 may be used.
4000
4002 Parsing Limitations
4003 Perltidy should work properly on most perl scripts. It does a lot
4004 of self-checking, but still, it is possible that an error could be
4005 introduced and go undetected. Therefore, it is essential to make
4006 careful backups and to test reformatted scripts.
4007 The main current limitation is that perltidy does not scan modules
4009 included with 'use' statements. This makes it necessary to guess
4010 the context of any bare words introduced by such modules. Perltidy
4011 has good guessing algorithms, but they are not infallible. When it
4012 must guess, it leaves a message in the log file.
4013 If you encounter a bug, please report it.
4015 What perltidy does not parse and format
4017 Perltidy indents but does not reformat comments and "qw" quotes.
4018 Perltidy does not in any way modify the contents of here documents
4019 or quoted text, even if they contain source code. (You could,
4020 however, reformat them separately). Perltidy does not format
4021 'format' sections in any way. And, of course, it does not modify
4022 pod documents.
4023
4025 Temporary files
4026 Under the -html option with the default --pod2html flag, a
4027 temporary file is required to pass text to Pod::Html. Unix systems
4028 will try to use the POSIX tmpnam() function. Otherwise the file
4029 perltidy.TMP will be temporarily created in the current working
4030 directory.
4031 Special files when standard input is used
4033 When standard input is used, the log file, if saved, is
4034 perltidy.LOG, and any errors are written to perltidy.ERR unless the
4035 -se flag is set. These are saved in the current working directory.
4036 Files overwritten
4038 The following file extensions are used by perltidy, and files with
4039 these extensions may be overwritten or deleted: .ERR, .LOG, .TEE,
4040 and/or .tdy, .html, and .bak, depending on the run type and
4041 settings.
4042 Files extensions limitations
4044 Perltidy does not operate on files for which the run could produce
4045 a file with a duplicated file extension. These extensions include
4046 .LOG, .ERR, .TEE, and perhaps .tdy and .bak, depending on the run
4047 type. The purpose of this rule is to prevent generating confusing
4048 filenames such as somefile.tdy.tdy.tdy.
4049
4051 An exit value of 0, 1, or 2 is returned by perltidy to indicate the
4052 status of the result.
4053 A exit value of 0 indicates that perltidy ran to completion with no
4055 error messages.
4056 A non-zero exit value indicates some kind of problem was detected.
4058 An exit value of 1 indicates that perltidy terminated prematurely,
4060 usually due to some kind of errors in the input parameters. This can
4061 happen for example if a parameter is misspelled or given an invalid
4062 value. Error messages in the standard error output will indicate the
4063 cause of any problem. If perltidy terminates prematurely then no
4064 output files will be produced.
4065 An exit value of 2 indicates that perltidy was able to run to
4067 completion but there there are (1) warning messages in the standard
4068 error output related to parameter errors or problems and/or (2) warning
4069 messages in the perltidy error file(s) relating to possible syntax
4070 errors in one or more of the source script(s) being tidied. When
4071 multiple files are being processed, an error detected in any single
4072 file will produce this type of exit condition.
4073
4075 perlstyle(1), Perl::Tidy(3)
4076
4078 The perltidy binary uses the Perl::Tidy module and is installed when
4079 that module is installed. The module name is case-sensitive. For
4080 example, the basic command for installing with cpanm is 'cpanm
4081 Perl::Tidy'.
4082
4084 This man page documents perltidy version 20201001
4085
4087 A list of current bugs and issues can be found at the CPAN site
4088 <https://rt.cpan.org/Public/Dist/Display.html?Name=Perl-Tidy>
4089 To report a new bug or problem, use the link on this page.
4091 The source code repository is at
4093 <https://github.com/perltidy/perltidy>.
4094
4096 Copyright (c) 2000-2020 by Steve Hancock
4097
4099 This package is free software; you can redistribute it and/or modify it
4100 under the terms of the "GNU General Public License".
4101 Please refer to the file "COPYING" for details.
4103
4105 This package is distributed in the hope that it will be useful, but
4106 WITHOUT ANY WARRANTY; without even the implied warranty of
4107 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
4108 See the "GNU General Public License" for more details.
4110perl v5.32.0 2020-09-29 PERLTIDY(1)