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 (for running under an editor).
259 For example, if you use a vi-style editor, such as vim, you may
261 execute perltidy as a filter from within the editor using something
262 like
263 :n1,n2!perltidy -q
265 where "n1,n2" represents the selected text. Without the -q flag,
267 any error message may mess up your screen, so be prepared to use
268 your "undo" key.
269 -log, --logfile
271 Save the .LOG file, which has many useful diagnostics. Perltidy
272 always creates a .LOG file, but by default it is deleted unless a
273 program bug is suspected. Setting the -log flag forces the log
274 file to be saved.
275 -g=n, --logfile-gap=n
277 Set maximum interval between input code lines in the logfile. This
278 purpose of this flag is to assist in debugging nesting errors. The
279 value of "n" is optional. If you set the flag -g without the value
280 of "n", it will be taken to be 1, meaning that every line will be
281 written to the log file. This can be helpful if you are looking
282 for a brace, paren, or bracket nesting error.
283 Setting -g also causes the logfile to be saved, so it is not
285 necessary to also include -log.
286 If no -g flag is given, a value of 50 will be used, meaning that at
288 least every 50th line will be recorded in the logfile. This helps
289 prevent excessively long log files.
290 Setting a negative value of "n" is the same as not setting -g at
292 all.
293 -npro --noprofile
295 Ignore any .perltidyrc command file. Normally, perltidy looks
296 first in your current directory for a .perltidyrc file of
297 parameters. (The format is described below). If it finds one, it
298 applies those options to the initial default values, and then it
299 applies any that have been defined on the command line. If no
300 .perltidyrc file is found, it looks for one in your home directory.
301 If you set the -npro flag, perltidy will not look for this file.
303 -pro=filename or --profile=filename
305 To simplify testing and switching .perltidyrc files, this command
306 may be used to specify a configuration file which will override the
307 default name of .perltidyrc. There must not be a space on either
308 side of the '=' sign. For example, the line
309 perltidy -pro=testcfg
311 would cause file testcfg to be used instead of the default
313 .perltidyrc.
314 A pathname begins with three dots, e.g. ".../.perltidyrc",
316 indicates that the file should be searched for starting in the
317 current directory and working upwards. This makes it easier to have
318 multiple projects each with their own .perltidyrc in their root
319 directories.
320 -opt, --show-options
322 Write a list of all options used to the .LOG file. Please see
323 --dump-options for a simpler way to do this.
324 -f, --force-read-binary
326 Force perltidy to process binary files. To avoid producing
327 excessive error messages, perltidy skips files identified by the
328 system as non-text. However, valid perl scripts containing binary
329 data may sometimes be identified as non-text, and this flag forces
330 perltidy to process them.
331 -ast, --assert-tidy
333 This flag asserts that the input and output code streams are
334 identical, or in other words that the input code is already 'tidy'
335 according to the formatting parameters. If this is not the case,
336 an error message noting this is produced. This error message will
337 cause the process to return a non-zero exit code. The test for
338 this is made by comparing an MD5 hash value for the input and
339 output code streams. This flag has no other effect on the
340 functioning of perltidy. This might be useful for certain code
341 maintenance operations. Note: you will not see this message if you
342 have error messages turned off with the -quiet flag.
343 -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.
388 The default length of 80 comes from the past when this was the
390 standard CRT screen width. Many programmers prefer to increase
391 this to something like 120.
392 Setting -l=0 is equivalent to setting -l=(a very large number).
394 But this is not recommended because, for example, a very long list
395 will be formatted in a single long line.
396 -vmll, --variable-maximum-line-length
398 A problem arises using a fixed maximum line length with very deeply
399 nested code and data structures because eventually the amount of
400 leading whitespace used for indicating indentation takes up most or
401 all of the available line width, leaving little or no space for the
402 actual code or data. One solution is to use a vary long line
403 length. Another solution is to use the -vmll flag, which basically
404 tells perltidy to ignore leading whitespace when measuring the line
405 length.
406 To be precise, when the -vmll parameter is set, the maximum line
408 length of a line of code will be M+L*I, where
409 M is the value of --maximum-line-length=M (-l=M), default 80,
411 I is the value of --indent-columns=I (-i=I), default 4,
412 L is the indentation level of the line of code
413 When this flag is set, the choice of breakpoints for a block of
415 code should be essentially independent of its nesting depth.
416 However, the absolute line lengths, including leading whitespace,
417 can still be arbitrarily large. This problem can be avoided by
418 including the next parameter.
419 The default is not to do this (-nvmll).
421 -wc=n, --whitespace-cycle=n
423 This flag also addresses problems with very deeply nested code and
424 data structures. When the nesting depth exceeds the value n the
425 leading whitespace will be reduced and start at a depth of 1 again.
426 The result is that blocks of code will shift back to the left
427 rather than moving arbitrarily far to the right. This occurs
428 cyclically to any depth.
429 For example if one level of indentation equals 4 spaces (-i=4, the
431 default), and one uses -wc=15, then if the leading whitespace on a
432 line exceeds about 4*15=60 spaces it will be reduced back to 4*1=4
433 spaces and continue increasing from there. If the whitespace never
434 exceeds this limit the formatting remains unchanged.
435 The combination of -vmll and -wc=n provides a solution to the
437 problem of displaying arbitrarily deep data structures and code in
438 a finite window, although -wc=n may of course be used without
439 -vmll.
440 The default is not to use this, which can also be indicated using
442 -wc=0.
443 Tabs
445 Using tab characters will almost certainly lead to future
446 portability and maintenance problems, so the default and
447 recommendation is not to use them. For those who prefer tabs,
448 however, there are two different options.
449 Except for possibly introducing tab indentation characters, as
451 outlined below, perltidy does not introduce any tab characters into
452 your file, and it removes any tabs from the code (unless requested
453 not to do so with -fws). If you have any tabs in your comments,
454 quotes, or here-documents, they will remain.
455 -et=n, --entab-leading-whitespace
457 This flag causes each n initial space characters to be replaced
458 by one tab character.
459 The value of the integer n can be any value but can be
461 coordinated with the number of spaces used for intentation. For
462 example, -et=4 -ci=4 -i=4 will produce one tab for each
463 indentation level and and one for each continuation indentation
464 level. You may want to coordinate the value of n with what
465 your display software assumes for the spacing of a tab.
466 -t, --tabs
468 This flag causes one leading tab character to be inserted for
469 each level of indentation. Certain other features are
470 incompatible with this option, and if these options are also
471 given, then a warning message will be issued and this flag will
472 be unset. One example is the -lp option. This flag is retained
473 for backwards compatibility, but if you use tabs, the -et=n
474 flag is recommended.
475 -dt=n, --default-tabsize=n
477 If the first line of code passed to perltidy contains leading
478 tabs but no tab scheme is specified for the output stream then
479 perltidy must guess how many spaces correspond to each leading
480 tab. This number of spaces n corresponding to each leading tab
481 of the input stream may be specified with -dt=n. The default
482 is n=8.
483 This flag has no effect if a tab scheme is specified for the
485 output stream, because then the input stream is assumed to use
486 the same tab scheme and indentation spaces as for the output
487 stream (any other assumption would lead to unstable editing).
488 -xs, --extended-syntax
490 A problem with formatting Perl code is that some modules can
491 introduce new syntax. This flag allows perltidy to handle certain
492 common extensions to the standard syntax without complaint.
493 For example, without this flag a structure such as the following
495 would generate a syntax error and the braces would not be balanced:
496 method deposit( Num $amount) {
498 $self->balance( $self->balance + $amount );
499 }
500 For one of the extensions, module Switch::Plain, colons are marked
502 as labels. If you use this module, you may want to also use the
503 --nooutdent-labels flag to prevent lines such as 'default:' from
504 being outdented.
505 This flag is enabled by default but it can be deactivated with
507 -nxs. Probably the only reason to deactivate this flag is to
508 generate more diagnostic messages when debugging a script.
509 For another method of handling extended syntax see the section
511 "Skipping Selected Sections of Code".
512 -io, --indent-only
514 This flag is used to deactivate all whitespace and line break
515 changes within non-blank lines of code. When it is in effect, the
516 only change to the script will be to the indentation and to the
517 number of blank lines. And any flags controlling whitespace and
518 newlines will be ignored. You might want to use this if you are
519 perfectly happy with your whitespace and line breaks, and merely
520 want perltidy to handle the indentation. (This also speeds up
521 perltidy by well over a factor of two, so it might be useful when
522 perltidy is merely being used to help find a brace error in a large
523 script).
524 Setting this flag is equivalent to setting --freeze-newlines and
526 --freeze-whitespace.
527 If you also want to keep your existing blank lines exactly as they
529 are, you can add --freeze-blank-lines.
530 With this option perltidy is still free to modify the indenting
532 (and outdenting) of code and comments as it normally would. If you
533 also want to prevent long comment lines from being outdented, you
534 can add either -noll or -l=0.
535 Setting this flag will prevent perltidy from doing any special
537 operations on closing side comments. You may still delete all side
538 comments however when this flag is in effect.
539 -enc=s, --character-encoding=s
541 This flag indicates the character encoding, if any, of the input
542 data stream. Perltidy does not look for the encoding directives in
543 the soure stream, such as use utf8, and instead relies on this flag
544 to determine the encoding. (Note that perltidy often works on
545 snippets of code rather than complete files so it cannot rely on
546 use utf8 directives).
547 The possible values for s [22mare (1) the name of an encoding
549 recognized by the Encode.pm module, (2) none if no encoding is
550 used, or (3) <guess> if perltidy should guess.
551 For example, the value utf8 causes the stream to be read and
553 written as UTF-8. If the input stream cannot be decoded with a
554 specified encoding then processing is not done.
555 The value none causes the stream to be processed without special
557 encoding assumptions. This is appropriate for files which are
558 written in single-byte character encodings such as latin-1.
559 The value guess tells perltidy to guess between either utf8
561 encoding or no encoding (meaning one character per byte). The
562 guess uses the Encode::Guess module and this restricted range of
563 guesses covers the most common cases. Testing showed that
564 considering any greater number of encodings as guess suspects is
565 too risky.
566 The current default is guess.
568 The abbreviations -utf8 or -UTF8 are equivalent to -enc=utf8, and
570 the abbreviation -guess is equivalent to <-enc=guess>. So to
571 process a file named file.pl which is encoded in UTF-8 you can use:
572 perltidy -utf8 file.pl
574 or
576 perltidy -guess file.pl
577 To process a file in euc-jp you could use
579 perltidy -enc=euc-jp file.pl
581 A perltidy output file is unencoded if the input file is unencoded,
583 and otherwise it is encoded as utf8, even if the input encoding was
584 not utf8.
585 -gcs, --use-unicode-gcstring
587 This flag controls whether or not perltidy may use module
588 Unicode::GCString to obtain accurate display widths of wide
589 characters. The default is --nouse-unicode-gcstring.
590 If this flag is set, and text is encoded, perltidy will look for
592 the module Unicode::GCString and, if found, will use it to obtain
593 character display widths. This can improve displayed vertical
594 alignment for files with wide characters. It is a nice feature but
595 it is off by default to avoid conflicting formatting when there are
596 multiple developers. Perltidy installation does not require
597 Unicode::GCString, so users wanting to use this feature need set
598 this flag and also to install Unicode::GCString separately.
599 If this flag is set and perltidy does not find module
601 Unicode::GCString, a warning message will be produced and
602 processing will continue but without the potential benefit provided
603 by the module.
604 Also note that actual vertical alignment depends upon the fonts
606 used by the text display software, so vertical alignment may not be
607 optimal even when Unicode::GCString is used.
608 -ole=s, --output-line-ending=s
610 where s="win", "dos", "unix", or "mac". This flag tells perltidy
611 to output line endings for a specific system. Normally, perltidy
612 writes files with the line separator character of the host system.
613 The "win" and "dos" flags have an identical result.
614 -ple, --preserve-line-endings
616 This flag tells perltidy to write its output files with the same
617 line endings as the input file, if possible. It should work for
618 dos, unix, and mac line endings. It will only work if perltidy
619 input comes from a filename (rather than stdin, for example). If
620 perltidy has trouble determining the input file line ending, it
621 will revert to the default behavior of using the line ending of the
622 host system.
623 -atnl, --add-terminal-newline
625 This flag, which is enabled by default, allows perltidy to
626 terminate the last line of the output stream with a newline
627 character, regardless of whether or not the input stream was
628 terminated with a newline character. If this flag is negated, with
629 -natnl, then perltidy will add a terminal newline to the the output
630 stream only if the input stream is terminated with a newline.
631 Negating this flag may be useful for manipulating one-line scripts
633 intended for use on a command line.
634 -it=n, --iterations=n
636 This flag causes perltidy to do n complete iterations. The reason
637 for this flag is that code beautification is an iterative process
638 and in some cases the output from perltidy can be different if it
639 is applied a second time. For most purposes the default of n=1
640 should be satisfactory. However n=2 can be useful when a major
641 style change is being made, or when code is being beautified on
642 check-in to a source code control system. It has been found to be
643 extremely rare for the output to change after 2 iterations. If a
644 value n is greater than 2 is input then a convergence test will be
645 used to stop the iterations as soon as possible, almost always
646 after 2 iterations. See the next item for a simplified iteration
647 control.
648 This flag has no effect when perltidy is used to generate html.
650 -conv, --converge
652 This flag is equivalent to -it=4 and is included to simplify
653 iteration control. For all practical purposes one either does or
654 does not want to be sure that the output is converged, and there is
655 no penalty to using a large iteration limit since perltidy will
656 check for convergence and stop iterating as soon as possible. The
657 default is -nconv (no convergence check). Using -conv will
658 approximately double run time since typically one extra iteration
659 is required to verify convergence. No extra iterations are
660 required if no new line breaks are made, and two extra iterations
661 are occasionally needed when reformatting complex code structures,
662 such as deeply nested ternary statements.
663 Code Indentation Control
665 -ci=n, --continuation-indentation=n
666 Continuation indentation is extra indentation spaces applied when a
667 long line is broken. The default is n=2, illustrated here:
668 my $level = # -ci=2
670 ( $max_index_to_go >= 0 ) ? $levels_to_go[0] : $last_output_level;
671 The same example, with n=0, is a little harder to read:
673 my $level = # -ci=0
675 ( $max_index_to_go >= 0 ) ? $levels_to_go[0] : $last_output_level;
676 The value given to -ci is also used by some commands when a small
678 space is required. Examples are commands for outdenting labels,
679 -ola, and control keywords, -okw.
680 When default values are not used, it is recommended that either
682 (1) the value n given with -ci=n be no more than about one-half of
684 the number of spaces assigned to a full indentation level on the
685 -i=n command, or
686 (2) the flag -extended-continuation-indentation is used (see next
688 section).
689 -xci, --extended-continuation-indentation
691 This flag allows perltidy to use some improvements which have been
692 made to its indentation model. One of the things it does is
693 "extend" continuation indentation deeper into structures, hence the
694 name. The improved indentation is particularly noticeable when the
695 flags -ci=n and -i=n use the same value of n. There are no
696 significant disadvantages to using this flag, but to avoid
697 disturbing existing formatting the default is not to use it, -nxci.
698 Please see the section "-pbp, --perl-best-practices" for an example
700 of how this flag can improve the formatting of ternary statements.
701 It can also improve indentation of some multi-line qw lists as
702 shown below.
703 # perltidy
705 foreach $color (
706 qw(
707 AntiqueWhite3 Bisque1 Bisque2 Bisque3 Bisque4
708 SlateBlue3 RoyalBlue1 SteelBlue2 DeepSkyBlue3
709 ),
710 qw(
711 LightBlue1 DarkSlateGray1 Aquamarine2 DarkSeaGreen2
712 SeaGreen1 Yellow1 IndianRed1 IndianRed2 Tan1 Tan4
713 )
714 )
715 # perltidy -xci
717 foreach $color (
718 qw(
719 AntiqueWhite3 Bisque1 Bisque2 Bisque3 Bisque4
720 SlateBlue3 RoyalBlue1 SteelBlue2 DeepSkyBlue3
721 ),
722 qw(
723 LightBlue1 DarkSlateGray1 Aquamarine2 DarkSeaGreen2
724 SeaGreen1 Yellow1 IndianRed1 IndianRed2 Tan1 Tan4
725 )
726 )
727 -sil=n --starting-indentation-level=n
729 By default, perltidy examines the input file and tries to determine
730 the starting indentation level. While it is often zero, it may not
731 be zero for a code snippet being sent from an editing session.
732 To guess the starting indentation level perltidy simply assumes
734 that indentation scheme used to create the code snippet is the same
735 as is being used for the current perltidy process. This is the
736 only sensible guess that can be made. It should be correct if this
737 is true, but otherwise it probably won't. For example, if the
738 input script was written with -i=2 and the current peltidy flags
739 have -i=4, the wrong initial indentation will be guessed for a code
740 snippet which has non-zero initial indentation. Likewise, if an
741 entabbing scheme is used in the input script and not in the current
742 process then the guessed indentation will be wrong.
743 If the default method does not work correctly, or you want to
745 change the starting level, use -sil=n, to force the starting level
746 to be n.
747 List indentation using -lp, --line-up-parentheses
749 By default, perltidy indents lists with 4 spaces, or whatever value
750 is specified with -i=n. Here is a small list formatted in this
751 way:
752 # perltidy (default)
754 @month_of_year = (
755 'Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun',
756 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'
757 );
758 Use the -lp flag to add extra indentation to cause the data to
760 begin past the opening parentheses of a sub call or list, or
761 opening square bracket of an anonymous array, or opening curly
762 brace of an anonymous hash. With this option, the above list would
763 become:
764 # perltidy -lp
766 @month_of_year = (
767 'Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun',
768 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'
769 );
770 If the available line length (see -l=n ) does not permit this much
772 space, perltidy will use less. For alternate placement of the
773 closing paren, see the next section.
774 This option has no effect on code BLOCKS, such as if/then/else
776 blocks, which always use whatever is specified with -i=n.
777 In situations where perltidy does not have complete freedom to
779 choose line breaks it may temporarily revert to its default
780 indentation method. This can occur for example if there are blank
781 lines, block comments, multi-line quotes, or side comments between
782 the opening and closing parens, braces, or brackets.
783 In addition, any parameter which significantly restricts the
785 ability of perltidy to choose newlines will conflict with -lp and
786 will cause -lp to be deactivated. These include -io, -fnl, -nanl,
787 and -ndnl. The reason is that the -lp indentation style can
788 require the careful coordination of an arbitrary number of break
789 points in hierarchical lists, and these flags may prevent that.
790 The -lp option may not be used together with the -t tabs option.
792 It may, however, be used with the -et=n tab method.
793 -lpxl=s, --line-up-parentheses-exclusion-list
795 This is an experimental parameter; the details might change as
796 experience with it is gained.
797 The -lp indentation style works well for some types of coding but
799 can produce very long lines when variables have long names and/or
800 containers are very deeply nested. The -lpxl=s flag is intended to
801 help mitigate this problem by providing control over the containers
802 to which the -lp indentation style is applied. The -lp flag by
803 default is "greedy" and applies to as many containers as possible.
804 This flag specifies a list of things which should not be use -lp
805 indentation.
806 This list is a string with space-separated items. Each item
808 consists of up to three pieces of information in this order: (1) an
809 optional letter code (2) a required container type, and (3) an
810 optional numeric code.
811 The only required piece of information is a container type, which
813 is one of '(', '[', or '{'. For example the string
814 -lpxl='[ {'
816 means do NOT include use -lp formatting within square-bracets or
818 braces. The only unspecified container is '(', so this string
819 means that only the contents within parens will use -lp
820 indentation.
821 An optional numeric code may follow any of the container types to
823 further refine the selection based on container contents. The
824 numeric codes are:
825 '0' or blank: no check on contents
827 '1' reject -lp unless the contents is a simple list without sublists
828 '2' reject -lp unless the contents is a simple list without sublists, without
829 code blocks, and without ternary operators
830 For example,
832 -lpxl = '[ { (2'
834 means only apply -lp to parenthesized lists which do not contain
836 any sublists, code blocks or ternary expressions.
837 A third optional item of information which can be given for parens
839 is an alphanumeric letter which is used to limit the selection
840 further depending on the type of token immediately before the
841 paren. The possible letters are currently 'k', 'K', 'f', 'F', 'w',
842 and 'W', with these meanings:
843 'k' matches if the previous nonblank token is a perl builtin keyword (such as 'if', 'while'),
845 'K' matches if 'k' does not, meaning that the previous token is not a keyword.
846 'f' matches if the previous token is a function other than a keyword.
847 'F' matches if 'f' does not.
848 'w' matches if either 'k' or 'f' match.
849 'W' matches if 'w' does not.
850 For example,
852 -lpxl = '[ { F(2'
854 means only apply -lp to parenthesized lists which follow a function
856 call and which do not contain any sublists, code blocks or ternary
857 expressions. The logic of writing these codes is somewhat counter-
858 intuitive because they describe what is not getting the -lp
859 indentation. So the 'F' indicates that non-function calls are not
860 getting -lp, or in other words that function calls are getting the
861 -lp indentation.
862 -cti=n, --closing-token-indentation
864 The -cti=n flag controls the indentation of a line beginning with a
865 ")", "]", or a non-block "}". Such a line receives:
866 -cti = 0 no extra indentation (default)
868 -cti = 1 extra indentation such that the closing token
869 aligns with its opening token.
870 -cti = 2 one extra indentation level if the line looks like:
871 ); or ]; or };
872 -cti = 3 one extra indentation level always
873 The flags -cti=1 and -cti=2 work well with the -lp flag (previous
875 section).
876 # perltidy -lp -cti=1
878 @month_of_year = (
879 'Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun',
880 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'
881 );
882 # perltidy -lp -cti=2
884 @month_of_year = (
885 'Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun',
886 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'
887 );
888 These flags are merely hints to the formatter and they may not
890 always be followed. In particular, if -lp is not being used, the
891 indentation for cti=1 is constrained to be no more than one
892 indentation level.
893 If desired, this control can be applied independently to each of
895 the closing container token types. In fact, -cti=n is merely an
896 abbreviation for -cpi=n -csbi=n -cbi=n, where: -cpi or
897 --closing-paren-indentation controls )'s, -csbi or
898 --closing-square-bracket-indentation controls ]'s, -cbi or
899 --closing-brace-indentation controls non-block }'s.
900 -icp, --indent-closing-paren
902 The -icp flag is equivalent to -cti=2, described in the previous
903 section. The -nicp flag is equivalent -cti=0. They are included
904 for backwards compatibility.
905 -icb, --indent-closing-brace
907 The -icb option gives one extra level of indentation to a brace
908 which terminates a code block . For example,
909 if ($task) {
911 yyy();
912 } # -icb
913 else {
914 zzz();
915 }
916 The default is not to do this, indicated by -nicb.
918 -nib, --non-indenting-braces
920 Normally, lines of code contained within a pair of block braces
921 receive one additional level of indentation. This flag, which is
922 enabled by default, causes perltidy to look for opening block
923 braces which are followed by a special side comment. This special
924 side comment is #<<< by default. If found, the code between this
925 opening brace and its corresponding closing brace will not be given
926 the normal extra indentation level. For example:
927 { #<<< a closure to contain lexical vars
929 my $var; # this line does not get one level of indentation
931 ...
932 }
934 # this line does not 'see' $var;
936 This can be useful, for example, when combining code from different
938 files. Different sections of code can be placed within braces to
939 keep their lexical variables from being visible to the end of the
940 file. To keep the new braces from causing all of their contained
941 code to be indented if you run perltidy, and possibly introducing
942 new line breaks in long lines, you can mark the opening braces with
943 this special side comment.
944 Only the opening brace needs to be marked, since perltidy knows
946 where the closing brace is. Braces contained within marked braces
947 may also be marked as non-indenting.
948 If your code happens to have some opening braces followed by
950 '#<<<', and you don't want this behavior, you can use -nnib to
951 deactivate it. To make it easy to remember, the default string is
952 the same as the string for starting a format-skipping section.
953 There is no confusion because in that case it is for a block
954 comment rather than a side-comment.
955 The special side comment can be changed with the next parameter.
957 -nibp=s, --non-indenting-brace-prefix=s
959 The -nibp=string parameter may be used to change the marker for
960 non-indenting braces. The default is equivalent to -nibp='#<<<'.
961 The string that you enter must begin with a # and should be in
962 quotes as necessary to get past the command shell of your system.
963 This string is the leading text of a regex pattern that is
964 constructed by appending pre-pending a '^' and appending a'\s', so
965 you must also include backslashes for characters to be taken
966 literally rather than as patterns.
967 For example, to match the side comment '#++', the parameter would
969 be
970 -nibp='#\+\+'
972 -olq, --outdent-long-quotes
974 When -olq is set, lines which is a quoted string longer than the
975 value maximum-line-length will have their indentation removed to
976 make them more readable. This is the default. To prevent such
977 out-denting, use -nolq or --nooutdent-long-lines.
978 -oll, --outdent-long-lines
980 This command is equivalent to --outdent-long-quotes and
981 --outdent-long-comments, and it is included for compatibility with
982 previous versions of perltidy. The negation of this also works,
983 -noll or --nooutdent-long-lines, and is equivalent to setting -nolq
984 and -nolc.
985 Outdenting Labels: -ola, --outdent-labels
987 This command will cause labels to be outdented by 2 spaces (or
988 whatever -ci has been set to), if possible. This is the default.
989 For example:
990 my $i;
992 LOOP: while ( $i = <FOTOS> ) {
993 chomp($i);
994 next unless $i;
995 fixit($i);
996 }
997 Use -nola to not outdent labels.
999 Outdenting Keywords
1001 -okw, --outdent-keywords
1002 The command -okw will cause certain leading control keywords to
1003 be outdented by 2 spaces (or whatever -ci has been set to), if
1004 possible. By default, these keywords are "redo", "next",
1005 "last", "goto", and "return". The intention is to make these
1006 control keywords easier to see. To change this list of
1007 keywords being outdented, see the next section.
1008 For example, using "perltidy -okw" on the previous example
1010 gives:
1011 my $i;
1013 LOOP: while ( $i = <FOTOS> ) {
1014 chomp($i);
1015 next unless $i;
1016 fixit($i);
1017 }
1018 The default is not to do this.
1020 Specifying Outdented Keywords: -okwl=string,
1022 --outdent-keyword-list=string
1023 This command can be used to change the keywords which are
1024 outdented with the -okw command. The parameter string is a
1025 required list of perl keywords, which should be placed in
1026 quotes if there are more than one. By itself, it does not
1027 cause any outdenting to occur, so the -okw command is still
1028 required.
1029 For example, the commands "-okwl="next last redo goto" -okw"
1031 will cause those four keywords to be outdented. It is probably
1032 simplest to place any -okwl command in a .perltidyrc file.
1033 Whitespace Control
1035 Whitespace refers to the blank space between variables, operators, and
1036 other code tokens.
1037 -fws, --freeze-whitespace
1039 This flag causes your original whitespace to remain unchanged, and
1040 causes the rest of the whitespace commands in this section, the
1041 Code Indentation section, and the Comment Control section to be
1042 ignored.
1043 Tightness of curly braces, parentheses, and square brackets
1045 Here the term "tightness" will mean the closeness with which pairs
1046 of enclosing tokens, such as parentheses, contain the quantities
1047 within. A numerical value of 0, 1, or 2 defines the tightness,
1048 with 0 being least tight and 2 being most tight. Spaces within
1049 containers are always symmetric, so if there is a space after a "("
1050 then there will be a space before the corresponding ")".
1051 The -pt=n or --paren-tightness=n parameter controls the space
1053 within parens. The example below shows the effect of the three
1054 possible values, 0, 1, and 2:
1055 if ( ( my $len_tab = length( $tabstr ) ) > 0 ) { # -pt=0
1057 if ( ( my $len_tab = length($tabstr) ) > 0 ) { # -pt=1 (default)
1058 if ((my $len_tab = length($tabstr)) > 0) { # -pt=2
1059 When n is 0, there is always a space to the right of a '(' and to
1061 the left of a ')'. For n=2 there is never a space. For n=1, the
1062 default, there is a space unless the quantity within the parens is
1063 a single token, such as an identifier or quoted string.
1064 Likewise, the parameter -sbt=n or --square-bracket-tightness=n
1066 controls the space within square brackets, as illustrated below.
1067 $width = $col[ $j + $k ] - $col[ $j ]; # -sbt=0
1069 $width = $col[ $j + $k ] - $col[$j]; # -sbt=1 (default)
1070 $width = $col[$j + $k] - $col[$j]; # -sbt=2
1071 Curly braces which do not contain code blocks are controlled by the
1073 parameter -bt=n or --brace-tightness=n.
1074 $obj->{ $parsed_sql->{ 'table' }[0] }; # -bt=0
1076 $obj->{ $parsed_sql->{'table'}[0] }; # -bt=1 (default)
1077 $obj->{$parsed_sql->{'table'}[0]}; # -bt=2
1078 And finally, curly braces which contain blocks of code are
1080 controlled by the parameter -bbt=n or --block-brace-tightness=n as
1081 illustrated in the example below.
1082 %bf = map { $_ => -M $_ } grep { /\.deb$/ } dirents '.'; # -bbt=0 (default)
1084 %bf = map { $_ => -M $_ } grep {/\.deb$/} dirents '.'; # -bbt=1
1085 %bf = map {$_ => -M $_} grep {/\.deb$/} dirents '.'; # -bbt=2
1086 To simplify input in the case that all of the tightness flags have
1088 the same value <n>, the parameter <-act=n> or
1089 --all-containers-tightness=n is an abbreviation for the combination
1090 <-pt=n -sbt=n -bt=n -bbt=n>.
1091 -tso, --tight-secret-operators
1093 The flag -tso causes certain perl token sequences (secret
1094 operators) which might be considered to be a single operator to be
1095 formatted "tightly" (without spaces). The operators currently
1096 modified by this flag are:
1097 0+ +0 ()x!! ~~<> ,=> =( )=
1099 For example the sequence 0 +, which converts a string to a number,
1101 would be formatted without a space: 0+ when the -tso flag is set.
1102 This flag is off by default.
1103 -sts, --space-terminal-semicolon
1105 Some programmers prefer a space before all terminal semicolons.
1106 The default is for no such space, and is indicated with -nsts or
1107 --nospace-terminal-semicolon.
1108 $i = 1 ; # -sts
1110 $i = 1; # -nsts (default)
1111 -sfs, --space-for-semicolon
1113 Semicolons within for loops may sometimes be hard to see,
1114 particularly when commas are also present. This option places
1115 spaces on both sides of these special semicolons, and is the
1116 default. Use -nsfs or --nospace-for-semicolon to deactivate it.
1117 for ( @a = @$ap, $u = shift @a ; @a ; $u = $v ) { # -sfs (default)
1119 for ( @a = @$ap, $u = shift @a; @a; $u = $v ) { # -nsfs
1120 -asc, --add-semicolons
1122 Setting -asc allows perltidy to add any missing optional semicolon
1123 at the end of a line which is followed by a closing curly brace on
1124 the next line. This is the default, and may be deactivated with
1125 -nasc or --noadd-semicolons.
1126 -dsm, --delete-semicolons
1128 Setting -dsm allows perltidy to delete extra semicolons which are
1129 simply empty statements. This is the default, and may be
1130 deactivated with -ndsm or --nodelete-semicolons. (Such semicolons
1131 are not deleted, however, if they would promote a side comment to a
1132 block comment).
1133 -aws, --add-whitespace
1135 Setting this option allows perltidy to add certain whitespace to
1136 improve code readability. This is the default. If you do not want
1137 any whitespace added, but are willing to have some whitespace
1138 deleted, use -naws. (Use -fws to leave whitespace completely
1139 unchanged).
1140 -dws, --delete-old-whitespace
1142 Setting this option allows perltidy to remove some old whitespace
1143 between characters, if necessary. This is the default. If you do
1144 not want any old whitespace removed, use -ndws or
1145 --nodelete-old-whitespace.
1146 Detailed whitespace controls around tokens
1148 For those who want more detailed control over the whitespace around
1149 tokens, there are four parameters which can directly modify the
1150 default whitespace rules built into perltidy for any token. They
1151 are:
1152 -wls=s or --want-left-space=s,
1154 -nwls=s or --nowant-left-space=s,
1156 -wrs=s or --want-right-space=s,
1158 -nwrs=s or --nowant-right-space=s.
1160 These parameters are each followed by a quoted string, s,
1162 containing a list of token types. No more than one of each of
1163 these parameters should be specified, because repeating a command-
1164 line parameter always overwrites the previous one before perltidy
1165 ever sees it.
1166 To illustrate how these are used, suppose it is desired that there
1168 be no space on either side of the token types = + - / *. The
1169 following two parameters would specify this desire:
1170 -nwls="= + - / *" -nwrs="= + - / *"
1172 (Note that the token types are in quotes, and that they are
1174 separated by spaces). With these modified whitespace rules, the
1175 following line of math:
1176 $root = -$b + sqrt( $b * $b - 4. * $a * $c ) / ( 2. * $a );
1178 becomes this:
1180 $root=-$b+sqrt( $b*$b-4.*$a*$c )/( 2.*$a );
1182 These parameters should be considered to be hints to perltidy
1184 rather than fixed rules, because perltidy must try to resolve
1185 conflicts that arise between them and all of the other rules that
1186 it uses. One conflict that can arise is if, between two tokens,
1187 the left token wants a space and the right one doesn't. In this
1188 case, the token not wanting a space takes priority.
1189 It is necessary to have a list of all token types in order to
1191 create this type of input. Such a list can be obtained by the
1192 command --dump-token-types. Also try the -D flag on a short
1193 snippet of code and look at the .DEBUG file to see the
1194 tokenization.
1195 WARNING Be sure to put these tokens in quotes to avoid having them
1197 misinterpreted by your command shell.
1198 Note1: Perltidy does always follow whitespace controls
1200 The various parameters controlling whitespace within a program are
1201 requests which perltidy follows as well as possible, but there are
1202 a number of situations where changing whitespace could change
1203 program behavior and is not done. Some of these are obvious; for
1204 example, we should not remove the space between the two plus
1205 symbols in '$x+ +$y' to avoid creating a '++' operator. Some are
1206 more subtle and involve the whitespace around bareword symbols and
1207 locations of possible filehandles. For example, consider the
1208 problem of formatting the following subroutine:
1209 sub print_div {
1211 my ($x,$y)=@_;
1212 print $x/$y;
1213 }
1214 Suppose the user requests that / signs have a space to the left but
1216 not to the right. Perltidy will refuse to do this, but if this were
1217 done the result would be
1218 sub print_div {
1220 my ($x,$y)=@_;
1221 print $x /$y;
1222 }
1223 If formatted in this way, the program will not run (at least with
1225 recent versions of perl) because the $x is taken to be a filehandle
1226 and / is assumed to start a quote. In a complex program, there
1227 might happen to be a / which terminates the multiline quote without
1228 a syntax error, allowing the program to run, but not as intended.
1229 Related issues arise with other binary operator symbols, such as +
1231 and -, and in older versions of perl there could be problems with
1232 ternary operators. So to avoid changing program behavior, perltidy
1233 has the simple rule that whitespace around possible filehandles is
1234 left unchanged. Likewise, whitespace around barewords is left
1235 unchanged. The reason is that if the barewords are defined in
1236 other modules, or in code that has not even been written yet,
1237 perltidy will not have seen their prototypes and must treat them
1238 cautiously.
1239 In perltidy this is implemented in the tokenizer by marking token
1241 following a print keyword as a special type Z. When formatting is
1242 being done, whitespace following this token type is generally left
1243 unchanged as a precaution against changing program behavior. This
1244 is excessively conservative but simple and easy to implement.
1245 Keywords which are treated similarly to print include printf, sort,
1246 exec, system. Changes in spacing around parameters following these
1247 keywords may have to be made manually. For example, the space, or
1248 lack of space, after the parameter $foo in the following line will
1249 be unchanged in formatting.
1250 system($foo );
1252 system($foo);
1253 To find if a token is of type Z you can use perltidy -DEBUG. For
1255 the first line above the result is
1256 1: system($foo );
1258 1: kkkkkk{ZZZZb};
1259 which shows that system is type k (keyword) and $foo is type Z.
1261 Note2: Perltidy's whitespace rules are not perfect
1263 Despite these precautions, it is still possible to introduce syntax
1264 errors with some asymmetric whitespace rules, particularly when
1265 call parameters are not placed in containing parens or braces. For
1266 example, the following two lines will be parsed by perl without a
1267 syntax error:
1268 # original programming, syntax ok
1270 my @newkeys = map $_-$nrecs+@data, @oldkeys;
1271 # perltidy default, syntax ok
1273 my @newkeys = map $_ - $nrecs + @data, @oldkeys;
1274 But the following will give a syntax error:
1276 # perltidy -nwrs='-'
1278 my @newkeys = map $_ -$nrecs + @data, @oldkeys;
1279 For another example, the following two lines will be parsed without
1281 syntax error:
1282 # original programming, syntax ok
1284 for my $severity ( reverse $SEVERITY_LOWEST+1 .. $SEVERITY_HIGHEST ) { ... }
1285 # perltidy default, syntax ok
1287 for my $severity ( reverse $SEVERITY_LOWEST + 1 .. $SEVERITY_HIGHEST ) { ... }
1288 But the following will give a syntax error:
1290 # perltidy -nwrs='+', syntax error:
1292 for my $severity ( reverse $SEVERITY_LOWEST +1 .. $SEVERITY_HIGHEST ) { ... }
1293 To avoid subtle parsing problems like this, it is best to avoid
1295 spacing a binary operator asymetrically with a space on the left
1296 but not on the right.
1297 Space between specific keywords and opening paren
1299 When an opening paren follows a Perl keyword, no space is
1300 introduced after the keyword, unless it is (by default) one of
1301 these:
1302 my local our and or xor eq ne if else elsif until unless
1304 while for foreach return switch case given when
1305 These defaults can be modified with two commands:
1307 -sak=s or --space-after-keyword=s adds keywords.
1309 -nsak=s or --nospace-after-keyword=s removes keywords.
1311 where s is a list of keywords (in quotes if necessary). For
1313 example,
1314 my ( $a, $b, $c ) = @_; # default
1316 my( $a, $b, $c ) = @_; # -nsak="my local our"
1317 The abbreviation -nsak='*' is equivalent to including all of the
1319 keywords in the above list.
1320 When both -nsak=s and -sak=s commands are included, the -nsak=s
1322 command is executed first. For example, to have space after only
1323 the keywords (my, local, our) you could use -nsak="*" -sak="my
1324 local our".
1325 To put a space after all keywords, see the next item.
1327 Space between all keywords and opening parens
1329 When an opening paren follows a function or keyword, no space is
1330 introduced after the keyword except for the keywords noted in the
1331 previous item. To always put a space between a function or keyword
1332 and its opening paren, use the command:
1333 -skp or --space-keyword-paren
1335 You may also want to use the flag -sfp (next item) too.
1337 Space between all function names and opening parens
1339 When an opening paren follows a function the default and
1340 recommended formatting is not to introduce a space. To cause a
1341 space to be introduced use:
1342 -sfp or --space-function-paren
1344 myfunc( $a, $b, $c ); # default
1346 myfunc ( $a, $b, $c ); # -sfp
1347 You will probably also want to use the flag -skp (previous item)
1349 too.
1350 The reason this is not recommended is that spacing a function paren
1352 can make a program vulnerable to parsing problems by Perl. For
1353 example, the following two-line program will run as written but
1354 will have a syntax error if reformatted with -sfp:
1355 if ( -e filename() ) { print "I'm here\n"; }
1357 sub filename { return $0 }
1358 In this particular case the syntax error can be removed if the line
1360 order is reversed, so that Perl parses 'sub filename' first.
1361 -fpva or --function-paren-vertical-alignment
1363 A side-effect of using the -sfp flag is that the parens may become
1364 vertically aligned. For example,
1365 # perltidy -sfp
1367 myfun ( $aaa, $b, $cc );
1368 mylongfun ( $a, $b, $c );
1369 This is the default behavior. To prevent this alignment use
1371 -nfpva:
1372 # perltidy -sfp -nfpva
1374 myfun ( $aaa, $b, $cc );
1375 mylongfun ( $a, $b, $c );
1376 -spp=n or --space-prototype-paren=n
1378 This flag can be used to control whether a function prototype is
1379 preceded by a space. For example, the following prototype does not
1380 have a space.
1381 sub usage();
1383 This integer n may have the value 0, 1, or 2 as follows:
1385 -spp=0 means no space before the paren
1387 -spp=1 means follow the example of the source code [DEFAULT]
1388 -spp=2 means always put a space before the paren
1389 The default is -spp=1, meaning that a space will be used if and
1391 only if there is one in the source code. Given the above line of
1392 code, the result of applying the different options would be:
1393 sub usage(); # n=0 [no space]
1395 sub usage(); # n=1 [default; follows input]
1396 sub usage (); # n=2 [space]
1397 -kpit=n or --keyword-paren-inner-tightness=n
1399 The space inside of an opening paren, which itself follows a
1400 certain keyword, can be controlled by this parameter. The space on
1401 the inside of the corresponding closing paren will be treated in
1402 the same (balanced) manner. This parameter has precedence over any
1403 other paren spacing rules. The values of n are as follows:
1404 -kpit=0 means always put a space (not tight)
1406 -kpit=1 means ignore this parameter [default]
1407 -kpit=2 means never put a space (tight)
1408 To illustrate, the following snippet is shown formatted in three
1410 ways:
1411 if ( seek( DATA, 0, 0 ) ) { ... } # perltidy (default)
1413 if (seek(DATA, 0, 0)) { ... } # perltidy -pt=2
1414 if ( seek(DATA, 0, 0) ) { ... } # perltidy -pt=2 -kpit=0
1415 In the second case the -pt=2 parameter makes all of the parens
1417 tight. In the third case the -kpit=0 flag causes the space within
1418 the 'if' parens to have a space, since 'if' is one of the keywords
1419 to which the -kpit flag applies by default. The remaining parens
1420 are still tight because of the -pt=2 parameter.
1421 The set of keywords to which this parameter applies are by default
1423 are:
1424 if elsif unless while until for foreach
1426 These can be changed with the parameter -kpitl=s described in the
1428 next section.
1429 -kpitl=string or --keyword-paren-inner-tightness=string
1431 This command can be used to change the keywords to which the the
1432 -kpit=n command applies. The parameter string is a required list
1433 either keywords or functions, which should be placed in quotes if
1434 there are more than one. By itself, this parameter does not cause
1435 any change in spacing, so the -kpit=n command is still required.
1436 For example, the commands "-kpitl="if else while" -kpit=2" will
1438 cause the just the spaces inside parens following 'if', 'else',
1439 and 'while' keywords to follow the tightness value indicated by the
1440 -kpit=2 flag.
1441 -lop or --logical-padding
1443 In the following example some extra space has been inserted on the
1444 second line between the two open parens. This extra space is called
1445 "logical padding" and is intended to help align similar things
1446 vertically in some logical or ternary expressions.
1447 # perltidy [default formatting]
1449 $same =
1450 ( ( $aP eq $bP )
1451 && ( $aS eq $bS )
1452 && ( $aT eq $bT )
1453 && ( $a->{'title'} eq $b->{'title'} )
1454 && ( $a->{'href'} eq $b->{'href'} ) );
1455 Note that this is considered to be a different operation from
1457 "vertical alignment" because space at just one line is being
1458 adjusted, whereas in "vertical alignment" the spaces at all lines
1459 are being adjusted. So it sort of a local version of vertical
1460 alignment.
1461 Here is an example involving a ternary operator:
1463 # perltidy [default formatting]
1465 $bits =
1466 $top > 0xffff ? 32
1467 : $top > 0xff ? 16
1468 : $top > 1 ? 8
1469 : 1;
1470 This behavior is controlled with the flag --logical-padding, which
1472 is set 'on' by default. If it is not desired it can be turned off
1473 using --nological-padding or -nlop. The above two examples become,
1474 with -nlop:
1475 # perltidy -nlop
1477 $same =
1478 ( ( $aP eq $bP )
1479 && ( $aS eq $bS )
1480 && ( $aT eq $bT )
1481 && ( $a->{'title'} eq $b->{'title'} )
1482 && ( $a->{'href'} eq $b->{'href'} ) );
1483 # perltidy -nlop
1485 $bits =
1486 $top > 0xffff ? 32
1487 : $top > 0xff ? 16
1488 : $top > 1 ? 8
1489 : 1;
1490 Trimming whitespace around "qw" quotes
1492 -tqw or --trim-qw provide the default behavior of trimming spaces
1493 around multi-line "qw" quotes and indenting them appropriately.
1494 -ntqw or --notrim-qw cause leading and trailing whitespace around
1496 multi-line "qw" quotes to be left unchanged. This option will not
1497 normally be necessary, but was added for testing purposes, because
1498 in some versions of perl, trimming "qw" quotes changes the syntax
1499 tree.
1500 -sbq=n or --space-backslash-quote=n
1502 lines like
1503 $str1=\"string1";
1505 $str2=\'string2';
1506 can confuse syntax highlighters unless a space is included between
1508 the backslash and the single or double quotation mark.
1509 this can be controlled with the value of n as follows:
1511 -sbq=0 means no space between the backslash and quote
1513 -sbq=1 means follow the example of the source code
1514 -sbq=2 means always put a space between the backslash and quote
1515 The default is -sbq=1, meaning that a space will be used if there
1517 is one in the source code.
1518 Trimming trailing whitespace from lines of POD
1520 -trp or --trim-pod will remove trailing whitespace from lines of
1521 POD. The default is not to do this.
1522 Comment Controls
1524 Perltidy has a number of ways to control the appearance of both block
1525 comments and side comments. The term block comment here refers to a
1526 full-line comment, whereas side comment will refer to a comment which
1527 appears on a line to the right of some code.
1528 -ibc, --indent-block-comments
1530 Block comments normally look best when they are indented to the
1531 same level as the code which follows them. This is the default
1532 behavior, but you may use -nibc to keep block comments left-
1533 justified. Here is an example:
1534 # this comment is indented (-ibc, default)
1536 if ($task) { yyy(); }
1537 The alternative is -nibc:
1539 # this comment is not indented (-nibc)
1541 if ($task) { yyy(); }
1542 See also the next item, -isbc, as well as -sbc, for other ways to
1544 have some indented and some outdented block comments.
1545 -isbc, --indent-spaced-block-comments
1547 If there is no leading space on the line, then the comment will not
1548 be indented, and otherwise it may be.
1549 If both -ibc and -isbc are set, then -isbc takes priority.
1551 -olc, --outdent-long-comments
1553 When -olc is set, lines which are full-line (block) comments longer
1554 than the value maximum-line-length will have their indentation
1555 removed. This is the default; use -nolc to prevent outdenting.
1556 -msc=n, --minimum-space-to-comment=n
1558 Side comments look best when lined up several spaces to the right
1559 of code. Perltidy will try to keep comments at least n spaces to
1560 the right. The default is n=4 spaces.
1561 -fpsc=n, --fixed-position-side-comment=n
1563 This parameter tells perltidy to line up side comments in column
1564 number n whenever possible. The default, n=0, will not do this.
1565 -iscl, --ignore-side-comment-lengths
1567 This parameter causes perltidy to ignore the length of side
1568 comments when setting line breaks. The default, -niscl, is to
1569 include the length of side comments when breaking lines to stay
1570 within the length prescribed by the -l=n maximum line length
1571 parameter. For example, the following long single line would
1572 remain intact with -l=80 and -iscl:
1573 perltidy -l=80 -iscl
1575 $vmsfile =~ s/;[\d\-]*$//; # Clip off version number; we can use a newer version as well
1576 whereas without the -iscl flag the line will be broken:
1578 perltidy -l=80
1580 $vmsfile =~ s/;[\d\-]*$//
1581 ; # Clip off version number; we can use a newer version as well
1582 -hsc, --hanging-side-comments
1584 By default, perltidy tries to identify and align "hanging side
1585 comments", which are something like this:
1586 my $IGNORE = 0; # This is a side comment
1588 # This is a hanging side comment
1589 # And so is this
1590 A comment is considered to be a hanging side comment if (1) it
1592 immediately follows a line with a side comment, or another hanging
1593 side comment, and (2) there is some leading whitespace on the line.
1594 To deactivate this feature, use -nhsc or --nohanging-side-comments.
1595 If block comments are preceded by a blank line, or have no leading
1596 whitespace, they will not be mistaken as hanging side comments.
1597 Closing Side Comments
1599 A closing side comment is a special comment which perltidy can
1600 automatically create and place after the closing brace of a code
1601 block. They can be useful for code maintenance and debugging. The
1602 command -csc (or --closing-side-comments) adds or updates closing
1603 side comments. For example, here is a small code snippet
1604 sub message {
1606 if ( !defined( $_[0] ) ) {
1607 print("Hello, World\n");
1608 }
1609 else {
1610 print( $_[0], "\n" );
1611 }
1612 }
1613 And here is the result of processing with "perltidy -csc":
1615 sub message {
1617 if ( !defined( $_[0] ) ) {
1618 print("Hello, World\n");
1619 }
1620 else {
1621 print( $_[0], "\n" );
1622 }
1623 } ## end sub message
1624 A closing side comment was added for "sub message" in this case,
1626 but not for the "if" and "else" blocks, because they were below the
1627 6 line cutoff limit for adding closing side comments. This limit
1628 may be changed with the -csci command, described below.
1629 The command -dcsc (or --delete-closing-side-comments) reverses this
1631 process and removes these comments.
1632 Several commands are available to modify the behavior of these two
1634 basic commands, -csc and -dcsc:
1635 -csci=n, or --closing-side-comment-interval=n
1637 where "n" is the minimum number of lines that a block must have
1638 in order for a closing side comment to be added. The default
1639 value is "n=6". To illustrate:
1640 # perltidy -csci=2 -csc
1642 sub message {
1643 if ( !defined( $_[0] ) ) {
1644 print("Hello, World\n");
1645 } ## end if ( !defined( $_[0] ))
1646 else {
1647 print( $_[0], "\n" );
1648 } ## end else [ if ( !defined( $_[0] ))
1649 } ## end sub message
1650 Now the "if" and "else" blocks are commented. However, now
1652 this has become very cluttered.
1653 -cscp=string, or --closing-side-comment-prefix=string
1655 where string is the prefix used before the name of the block
1656 type. The default prefix, shown above, is "## end". This
1657 string will be added to closing side comments, and it will also
1658 be used to recognize them in order to update, delete, and
1659 format them. Any comment identified as a closing side comment
1660 will be placed just a single space to the right of its closing
1661 brace.
1662 -cscl=string, or --closing-side-comment-list
1664 where "string" is a list of block types to be tagged with
1665 closing side comments. By default, all code block types
1666 preceded by a keyword or label (such as "if", "sub", and so on)
1667 will be tagged. The -cscl command changes the default list to
1668 be any selected block types; see "Specifying Block Types". For
1669 example, the following command requests that only "sub"'s,
1670 labels, "BEGIN", and "END" blocks be affected by any -csc or
1671 -dcsc operation:
1672 -cscl="sub : BEGIN END"
1674 -csct=n, or --closing-side-comment-maximum-text=n
1676 The text appended to certain block types, such as an "if"
1677 block, is whatever lies between the keyword introducing the
1678 block, such as "if", and the opening brace. Since this might
1679 be too much text for a side comment, there needs to be a limit,
1680 and that is the purpose of this parameter. The default value
1681 is "n=20", meaning that no additional tokens will be appended
1682 to this text after its length reaches 20 characters. Omitted
1683 text is indicated with "...". (Tokens, including sub names,
1684 are never truncated, however, so actual lengths may exceed
1685 this). To illustrate, in the above example, the appended text
1686 of the first block is " ( !defined( $_[0] )...". The existing
1687 limit of "n=20" caused this text to be truncated, as indicated
1688 by the "...". See the next flag for additional control of the
1689 abbreviated text.
1690 -cscb, or --closing-side-comments-balanced
1692 As discussed in the previous item, when the closing-side-
1693 comment-maximum-text limit is exceeded the comment text must be
1694 truncated. Older versions of perltidy terminated with three
1695 dots, and this can still be achieved with -ncscb:
1696 perltidy -csc -ncscb
1698 } ## end foreach my $foo (sort { $b cmp $a ...
1699 However this causes a problem with editors which cannot
1701 recognize comments or are not configured to do so because they
1702 cannot "bounce" around in the text correctly. The -cscb flag
1703 has been added to help them by appending appropriate balancing
1704 structure:
1705 perltidy -csc -cscb
1707 } ## end foreach my $foo (sort { $b cmp $a ... })
1708 The default is -cscb.
1710 -csce=n, or --closing-side-comment-else-flag=n
1712 The default, n=0, places the text of the opening "if" statement
1713 after any terminal "else".
1714 If n=2 is used, then each "elsif" is also given the text of the
1716 opening "if" statement. Also, an "else" will include the text
1717 of a preceding "elsif" statement. Note that this may result
1718 some long closing side comments.
1719 If n=1 is used, the results will be the same as n=2 whenever
1721 the resulting line length is less than the maximum allowed.
1722 -cscb, or --closing-side-comments-balanced
1724 When using closing-side-comments, and the closing-side-comment-
1725 maximum-text limit is exceeded, then the comment text must be
1726 abbreviated. It is terminated with three dots if the -cscb
1727 flag is negated:
1728 perltidy -csc -ncscb
1730 } ## end foreach my $foo (sort { $b cmp $a ...
1731 This causes a problem with older editors which do not recognize
1733 comments because they cannot "bounce" around in the text
1734 correctly. The -cscb flag tries to help them by appending
1735 appropriate terminal balancing structures:
1736 perltidy -csc -cscb
1738 } ## end foreach my $foo (sort { $b cmp $a ... })
1739 The default is -cscb.
1741 -cscw, or --closing-side-comment-warnings
1743 This parameter is intended to help make the initial transition
1744 to the use of closing side comments. It causes two things to
1745 happen if a closing side comment replaces an existing,
1746 different closing side comment: first, an error message will
1747 be issued, and second, the original side comment will be placed
1748 alone on a new specially marked comment line for later
1749 attention.
1750 The intent is to avoid clobbering existing hand-written side
1752 comments which happen to match the pattern of closing side
1753 comments. This flag should only be needed on the first run with
1754 -csc.
1755 Important Notes on Closing Side Comments:
1757 • Closing side comments are only placed on lines terminated with
1759 a closing brace. Certain closing styles, such as the use of
1760 cuddled elses (-ce), preclude the generation of some closing
1761 side comments.
1762 • Please note that adding or deleting of closing side comments
1764 takes place only through the commands -csc or -dcsc. The other
1765 commands, if used, merely modify the behavior of these two
1766 commands.
1767 • It is recommended that the -cscw flag be used along with -csc
1769 on the first use of perltidy on a given file. This will
1770 prevent loss of any existing side comment data which happens to
1771 have the csc prefix.
1772 • Once you use -csc, you should continue to use it so that any
1774 closing side comments remain correct as code changes.
1775 Otherwise, these comments will become incorrect as the code is
1776 updated.
1777 • If you edit the closing side comments generated by perltidy,
1779 you must also change the prefix to be different from the
1780 closing side comment prefix. Otherwise, your edits will be
1781 lost when you rerun perltidy with -csc. For example, you
1782 could simply change "## end" to be "## End", since the test is
1783 case sensitive. You may also want to use the -ssc flag to keep
1784 these modified closing side comments spaced the same as actual
1785 closing side comments.
1786 • Temporarily generating closing side comments is a useful
1788 technique for exploring and/or debugging a perl script,
1789 especially one written by someone else. You can always remove
1790 them with -dcsc.
1791 Static Block Comments
1793 Static block comments are block comments with a special leading
1794 pattern, "##" by default, which will be treated slightly
1795 differently from other block comments. They effectively behave as
1796 if they had glue along their left and top edges, because they stick
1797 to the left edge and previous line when there is no blank spaces in
1798 those places. This option is particularly useful for controlling
1799 how commented code is displayed.
1800 -sbc, --static-block-comments
1802 When -sbc is used, a block comment with a special leading
1803 pattern, "##" by default, will be treated specially.
1804 Comments so identified are treated as follows:
1806 • If there is no leading space on the line, then the comment
1808 will not be indented, and otherwise it may be,
1809 • no new blank line will be inserted before such a comment,
1811 and
1812 • such a comment will never become a hanging side comment.
1814 For example, assuming @month_of_year is left-adjusted:
1816 @month_of_year = ( # -sbc (default)
1818 'Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct',
1819 ## 'Dec', 'Nov'
1820 'Nov', 'Dec');
1821 Without this convention, the above code would become
1823 @month_of_year = ( # -nsbc
1825 'Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct',
1826 ## 'Dec', 'Nov'
1828 'Nov', 'Dec'
1829 );
1830 which is not as clear. The default is to use -sbc. This may
1832 be deactivated with -nsbc.
1833 -sbcp=string, --static-block-comment-prefix=string
1835 This parameter defines the prefix used to identify static block
1836 comments when the -sbc parameter is set. The default prefix is
1837 "##", corresponding to "-sbcp=##". The prefix is actually part
1838 of a perl pattern used to match lines and it must either begin
1839 with "#" or "^#". In the first case a prefix ^\s* will be
1840 added to match any leading whitespace, while in the second case
1841 the pattern will match only comments with no leading
1842 whitespace. For example, to identify all comments as static
1843 block comments, one would use "-sbcp=#". To identify all left-
1844 adjusted comments as static block comments, use "-sbcp='^#'".
1845 Please note that -sbcp merely defines the pattern used to
1847 identify static block comments; it will not be used unless the
1848 switch -sbc is set. Also, please be aware that since this
1849 string is used in a perl regular expression which identifies
1850 these comments, it must enable a valid regular expression to be
1851 formed.
1852 A pattern which can be useful is:
1854 -sbcp=^#{2,}[^\s#]
1856 This pattern requires a static block comment to have at least
1858 one character which is neither a # nor a space. It allows a
1859 line containing only '#' characters to be rejected as a static
1860 block comment. Such lines are often used at the start and end
1861 of header information in subroutines and should not be
1862 separated from the intervening comments, which typically begin
1863 with just a single '#'.
1864 -osbc, --outdent-static-block-comments
1866 The command -osbc will cause static block comments to be
1867 outdented by 2 spaces (or whatever -ci=n has been set to), if
1868 possible.
1869 Static Side Comments
1871 Static side comments are side comments with a special leading
1872 pattern. This option can be useful for controlling how commented
1873 code is displayed when it is a side comment.
1874 -ssc, --static-side-comments
1876 When -ssc is used, a side comment with a static leading
1877 pattern, which is "##" by default, will be spaced only a single
1878 space from previous character, and it will not be vertically
1879 aligned with other side comments.
1880 The default is -nssc.
1882 -sscp=string, --static-side-comment-prefix=string
1884 This parameter defines the prefix used to identify static side
1885 comments when the -ssc parameter is set. The default prefix is
1886 "##", corresponding to "-sscp=##".
1887 Please note that -sscp merely defines the pattern used to
1889 identify static side comments; it will not be used unless the
1890 switch -ssc is set. Also, note that this string is used in a
1891 perl regular expression which identifies these comments, so it
1892 must enable a valid regular expression to be formed.
1893 Skipping Selected Sections of Code
1895 Selected lines of code may be passed verbatim to the output without any
1896 formatting by marking the starting and ending lines with special
1897 comments. There are two options for doing this. The first option is
1898 called --format-skipping or -fs, and the second option is called
1899 --code-skipping or -cs.
1900 In both cases the lines of code will be output without any changes.
1902 The difference is that in --format-skipping perltidy will still parse
1903 the marked lines of code and check for errors, whereas in
1904 --code-skipping perltidy will simply pass the lines to the output
1905 without any checking.
1906 Both of these features are enabled by default and are invoked with
1908 special comment markers. --format-skipping uses starting and ending
1909 markers '#<<<' and '#>>>', like this:
1910 #<<< format skipping: do not let perltidy change my nice formatting
1912 my @list = (1,
1913 1, 1,
1914 1, 2, 1,
1915 1, 3, 3, 1,
1916 1, 4, 6, 4, 1,);
1917 #>>>
1918 --code-skipping uses starting and ending markers '#<<V' and '#>>V',
1920 like this:
1921 #<<V code skipping: perltidy will pass this verbatim without error checking
1923 token ident_digit {
1925 [ [ <?word> | _ | <?digit> ] <?ident_digit>
1926 | <''>
1927 ]
1928 };
1929 #>>V
1931 Additional text may appear on the special comment lines provided that
1933 it is separated from the marker by at least one space, as in the above
1934 examples.
1935 It is recommended to use --code-skipping only if you need to hide a
1937 block of an extended syntax which would produce errors if parsed by
1938 perltidy, and use --format-skipping otherwise. This is because the
1939 --format-skipping option provides the benefits of error checking, and
1940 there are essentially no limitations on which lines to which it can be
1941 applied. The --code-skipping option, on the other hand, does not do
1942 error checking and its use is more restrictive because the code which
1943 remains, after skipping the marked lines, must be syntactically correct
1944 code with balanced containers.
1945 These features should be used sparingly to avoid littering code with
1947 markers, but they can be helpful for working around occasional
1948 problems.
1949 Note that it may be possible to avoid the use of --format-skipping for
1951 the specific case of a comma-separated list of values, as in the above
1952 example, by simply inserting a blank or comment somewhere between the
1953 opening and closing parens. See the section "Controlling List
1954 Formatting".
1955 The following sections describe the available controls for these
1957 options. They should not normally be needed.
1958 -fs, --format-skipping
1960 As explained above, this flag, which is enabled by default, causes
1961 any code between special beginning and ending comment markers to be
1962 passed to the output without formatting. The code between the
1963 comments is still checked for errors however. The default
1964 beginning marker is #<<< and the default ending marker is #>>>.
1965 Format skipping begins when a format skipping beginning comment is
1967 seen and continues until a format-skipping ending comment is found.
1968 This feature can be disabled with -nfs. This should not normally
1970 be necessary.
1971 -fsb=string, --format-skipping-begin=string
1973 This and the next parameter allow the special beginning and ending
1974 comments to be changed. However, it is recommended that they only
1975 be changed if there is a conflict between the default values and
1976 some other use. If they are used, it is recommended that they only
1977 be entered in a .perltidyrc file, rather than on a command line.
1978 This is because properly escaping these parameters on a command
1979 line can be difficult.
1980 If changed comment markers do not appear to be working, use the
1982 -log flag and examine the .LOG file to see if and where they are
1983 being detected.
1984 The -fsb=string parameter may be used to change the beginning
1986 marker for format skipping. The default is equivalent to
1987 -fsb='#<<<'. The string that you enter must begin with a # and
1988 should be in quotes as necessary to get past the command shell of
1989 your system. It is actually the leading text of a pattern that is
1990 constructed by appending a '\s', so you must also include
1991 backslashes for characters to be taken literally rather than as
1992 patterns.
1993 Some examples show how example strings become patterns:
1995 -fsb='#\{\{\{' becomes /^#\{\{\{\s/ which matches #{{{ but not #{{{{
1997 -fsb='#\*\*' becomes /^#\*\*\s/ which matches #** but not #***
1998 -fsb='#\*{2,}' becomes /^#\*{2,}\s/ which matches #** and #*****
1999 -fse=string, --format-skipping-end=string
2001 The -fse=string is the corresponding parameter used to change the
2002 ending marker for format skipping. The default is equivalent to
2003 -fse='#<<<'.
2004 The beginning and ending strings may be the same, but it is
2006 preferable to make them different for clarity.
2007 -cs, --code-skipping
2009 As explained above, this flag, which is enabled by default, causes
2010 any code between special beginning and ending comment markers to be
2011 directly passed to the output without any error checking or
2012 formatting. Essentially, perltidy treats it as if it were a block
2013 of arbitrary text. The default beginning marker is #<<V and the
2014 default ending marker is #>>V.
2015 This feature can be disabled with -ncs. This should not normally
2017 be necessary.
2018 -csb=string, --code-skipping-begin=string
2020 This may be used to change the beginning comment for a
2021 --code-skipping section, and its use is similar to the -fsb=string.
2022 The default is equivalent to -csb='#<<V'.
2023 -cse=string, --code-skipping-end=string
2025 This may be used to change the ending comment for a --code-skipping
2026 section, and its use is similar to the -fse=string. The default is
2027 equivalent to -cse='#>>V'.
2028 Line Break Control
2030 The parameters in this section control breaks after non-blank lines of
2031 code. Blank lines are controlled separately by parameters in the
2032 section "Blank Line Control".
2033 -fnl, --freeze-newlines
2035 If you do not want any changes to the line breaks within lines of
2036 code in your script, set -fnl, and they will remain fixed, and the
2037 rest of the commands in this section and sections "Controlling List
2038 Formatting", "Retaining or Ignoring Existing Line Breaks". You may
2039 want to use -noll with this.
2040 Note: If you also want to keep your blank lines exactly as they
2042 are, you can use the -fbl flag which is described in the section
2043 "Blank Line Control".
2044 -ce, --cuddled-else
2046 Enable the "cuddled else" style, in which "else" and "elsif" are
2047 follow immediately after the curly brace closing the previous
2048 block. The default is not to use cuddled elses, and is indicated
2049 with the flag -nce or --nocuddled-else. Here is a comparison of
2050 the alternatives:
2051 # -ce
2053 if ($task) {
2054 yyy();
2055 } else {
2056 zzz();
2057 }
2058 # -nce (default)
2060 if ($task) {
2061 yyy();
2062 }
2063 else {
2064 zzz();
2065 }
2066 In this example the keyword else is placed on the same line which
2068 begins with the preceding closing block brace and is followed by
2069 its own opening block brace on the same line. Other keywords and
2070 function names which are formatted with this "cuddled" style are
2071 elsif, continue, catch, finally.
2072 Other block types can be formatted by specifying their names on a
2074 separate parameter -cbl, described in a later section.
2075 Cuddling between a pair of code blocks requires that the closing
2077 brace of the first block start a new line. If this block is
2078 entirely on one line in the input file, it is necessary to decide
2079 if it should be broken to allow cuddling. This decision is
2080 controlled by the flag -cbo=n discussed below. The default and
2081 recommended value of -cbo=1 bases this decision on the first block
2082 in the chain. If it spans multiple lines then cuddling is made and
2083 continues along the chain, regardless of the sizes of subsequent
2084 blocks. Otherwise, short lines remain intact.
2085 So for example, the -ce flag would not have any effect if the above
2087 snippet is rewritten as
2088 if ($task) { yyy() }
2090 else { zzz() }
2091 If the first block spans multiple lines, then cuddling can be done
2093 and will continue for the subsequent blocks in the chain, as
2094 illustrated in the previous snippet.
2095 If there are blank lines between cuddled blocks they will be
2097 eliminated. If there are comments after the closing brace where
2098 cuddling would occur then cuddling will be prevented. If this
2099 occurs, cuddling will restart later in the chain if possible.
2100 -cb, --cuddled-blocks
2102 This flag is equivalent to -ce.
2103 -cbl, --cuddled-block-list
2105 The built-in default cuddled block types are else, elsif, continue,
2106 catch, finally.
2107 Additional block types to which the -cuddled-blocks style applies
2109 can be defined by this parameter. This parameter is a character
2110 string, giving a list of block types separated by commas or spaces.
2111 For example, to cuddle code blocks of type sort, map and grep, in
2112 addition to the default types, the string could be set to
2113 -cbl="sort map grep"
2115 or equivalently
2117 -cbl=sort,map,grep
2119 Note however that these particular block types are typically short
2121 so there might not be much opportunity for the cuddled format
2122 style.
2123 Using commas avoids the need to protect spaces with quotes.
2125 As a diagnostic check, the flag --dump-cuddled-block-list or -dcbl
2127 can be used to view the hash of values that are generated by this
2128 flag.
2129 Finally, note that the -cbl flag by itself merely specifies which
2131 blocks are formatted with the cuddled format. It has no effect
2132 unless this formatting style is activated with -ce.
2133 -cblx, --cuddled-block-list-exclusive
2135 When cuddled else formatting is selected with -ce, setting this
2136 flag causes perltidy to ignore its built-in defaults and rely
2137 exclusively on the block types specified on the -cbl flag described
2138 in the previous section. For example, to avoid using cuddled catch
2139 and finally, which among in the defaults, the following set of
2140 parameters could be used:
2141 perltidy -ce -cbl='else elsif continue' -cblx
2143 -cbo=n, --cuddled-break-option=n
2145 Cuddled formatting is only possible between a pair of code blocks
2146 if the closing brace of the first block starts a new line. If a
2147 block is encountered which is entirely on a single line, and
2148 cuddled formatting is selected, it is necessary to make a decision
2149 as to whether or not to "break" the block, meaning to cause it to
2150 span multiple lines. This parameter controls that decision. The
2151 options are:
2152 cbo=0 Never force a short block to break.
2154 cbo=1 If the first of a pair of blocks is broken in the input file,
2155 then break the second [DEFAULT].
2156 cbo=2 Break open all blocks for maximal cuddled formatting.
2157 The default and recommended value is cbo=1. With this value, if
2159 the starting block of a chain spans multiple lines, then a cascade
2160 of breaks will occur for remaining blocks causing the entire chain
2161 to be cuddled.
2162 The option cbo=0 can produce erratic cuddling if there are numerous
2164 one-line blocks.
2165 The option cbo=2 produces maximal cuddling but will not allow any
2167 short blocks.
2168 -bl, --opening-brace-on-new-line
2170 Use the flag -bl to place the opening brace on a new line:
2171 if ( $input_file eq '-' ) # -bl
2173 {
2174 important_function();
2175 }
2176 This flag applies to all structural blocks, including named sub's
2178 (unless the -sbl flag is set -- see next item).
2179 The default style, -nbl, places an opening brace on the same line
2181 as the keyword introducing it. For example,
2182 if ( $input_file eq '-' ) { # -nbl (default)
2184 -sbl, --opening-sub-brace-on-new-line
2186 The flag -sbl can be used to override the value of -bl for the
2187 opening braces of named sub's. For example,
2188 perltidy -sbl
2190 produces this result:
2192 sub message
2194 {
2195 if (!defined($_[0])) {
2196 print("Hello, World\n");
2197 }
2198 else {
2199 print($_[0], "\n");
2200 }
2201 }
2202 This flag is negated with -nsbl. If -sbl is not specified, the
2204 value of -bl is used.
2205 -asbl, --opening-anonymous-sub-brace-on-new-line
2207 The flag -asbl is like the -sbl flag except that it applies to
2208 anonymous sub's instead of named subs. For example
2209 perltidy -asbl
2211 produces this result:
2213 $a = sub
2215 {
2216 if ( !defined( $_[0] ) ) {
2217 print("Hello, World\n");
2218 }
2219 else {
2220 print( $_[0], "\n" );
2221 }
2222 };
2223 This flag is negated with -nasbl, and the default is -nasbl.
2225 -bli, --brace-left-and-indent
2227 The flag -bli is the same as -bl but in addition it causes one unit
2228 of continuation indentation ( see -ci ) to be placed before an
2229 opening and closing block braces.
2230 For example,
2232 if ( $input_file eq '-' ) # -bli
2234 {
2235 important_function();
2236 }
2237 By default, this extra indentation occurs for blocks of type: if,
2239 elsif, else, unless, for, foreach, sub, while, until, and also with
2240 a preceding label. The next item shows how to change this.
2241 -blil=s, --brace-left-and-indent-list=s
2243 Use this parameter to change the types of block braces for which
2244 the -bli flag applies; see "Specifying Block Types". For example,
2245 -blil='if elsif else' would apply it to only "if/elsif/else"
2246 blocks.
2247 -bar, --opening-brace-always-on-right
2249 The default style, -nbl places the opening code block brace on a
2250 new line if it does not fit on the same line as the opening
2251 keyword, like this:
2252 if ( $bigwasteofspace1 && $bigwasteofspace2
2254 || $bigwasteofspace3 && $bigwasteofspace4 )
2255 {
2256 big_waste_of_time();
2257 }
2258 To force the opening brace to always be on the right, use the -bar
2260 flag. In this case, the above example becomes
2261 if ( $bigwasteofspace1 && $bigwasteofspace2
2263 || $bigwasteofspace3 && $bigwasteofspace4 ) {
2264 big_waste_of_time();
2265 }
2266 A conflict occurs if both -bl and -bar are specified.
2268 -otr, --opening-token-right and related flags
2270 The -otr flag is a hint that perltidy should not place a break
2271 between a comma and an opening token. For example:
2272 # default formatting
2274 push @{ $self->{$module}{$key} },
2275 {
2276 accno => $ref->{accno},
2277 description => $ref->{description}
2278 };
2279 # perltidy -otr
2281 push @{ $self->{$module}{$key} }, {
2282 accno => $ref->{accno},
2283 description => $ref->{description}
2284 };
2285 The flag -otr is actually an abbreviation for three other flags
2287 which can be used to control parens, hash braces, and square
2288 brackets separately if desired:
2289 -opr or --opening-paren-right
2291 -ohbr or --opening-hash-brace-right
2292 -osbr or --opening-square-bracket-right
2293 -bbhb=n, --break-before-hash-brace=n and related flags
2295 When a list of items spans multiple lines, the default formatting
2296 is to place the opening brace (or other container token) at the end
2297 of the starting line, like this:
2298 $romanNumerals = {
2300 one => 'I',
2301 two => 'II',
2302 three => 'III',
2303 four => 'IV',
2304 };
2305 This flag can change the default behavior to cause a line break to
2307 be placed before the opening brace according to the value given to
2308 the integer n:
2309 -bbhb=0 never break [default]
2311 -bbhb=1 stable: break if the input script had a break
2312 -bbhb=2 break if list is 'complex' (see note below)
2313 -bbhb=3 always break
2314 For example,
2316 # perltidy -bbhb=3
2318 $romanNumerals =
2319 {
2320 one => 'I',
2321 two => 'II',
2322 three => 'III',
2323 four => 'IV',
2324 };
2325 There are several points to note about this flag:
2327 • This parameter only applies if the opening brace is preceded by
2329 an '=' or '=>'.
2330 • This parameter only applies if the contents of the container
2332 looks like a list. The contents need to contain some commas or
2333 '=>'s at the next interior level to be considered a list.
2334 • For the n=2 option, a list is considered 'complex' if it is
2336 part of a nested list structure which spans multiple lines in
2337 the input file.
2338 • If multiple opening tokens have been 'welded' together with the
2340 -wn parameter, then this parameter has no effect.
2341 • The indentation of the braces will normally be one level of
2343 continuation indentation by default. This can be changed with
2344 the parameter -bbhbi=n in the next section.
2345 • Similar flags for controlling parens and square brackets are
2347 given in the subsequent section.
2348 -bbhbi=n, --break-before-hash-brace-and-indent=n
2350 This flag is a companion to -bbhb=n for controlling the indentation
2351 of an opening hash brace which is placed on a new line by that
2352 parameter. The indentation is as follows:
2353 -bbhbi=0 one continuation level [default]
2355 -bbhbi=1 outdent by one continuation level
2356 -bbhbi=2 indent one full indentation level
2357 For example:
2359 # perltidy -bbhb=3 -bbhbi=1
2361 $romanNumerals =
2362 {
2363 one => 'I',
2364 two => 'II',
2365 three => 'III',
2366 four => 'IV',
2367 };
2368 # perltidy -bbhb=3 -bbhbi=2
2370 $romanNumerals =
2371 {
2372 one => 'I',
2373 two => 'II',
2374 three => 'III',
2375 four => 'IV',
2376 };
2377 Note that this parameter has no effect unless -bbhb=n is also set.
2379 -bbsb=n, --break-before-square-bracket=n
2381 This flag is similar to the flag described above, except it applies
2382 to lists contained within square brackets.
2383 -bbsb=0 never break [default]
2385 -bbsb=1 stable: break if the input script had a break
2386 -bbsb=2 break if list is 'complex' (part of nested list structure)
2387 -bbsb=3 always break
2388 -bbsbi=n, --break-before-square-bracket-and-indent=n
2390 This flag is a companion to -bbsb=n for controlling the indentation
2391 of an opening square bracket which is placed on a new line by that
2392 parameter. The indentation is as follows:
2393 -bbsbi=0 one continuation level [default]
2395 -bbsbi=1 outdent by one continuation level
2396 -bbsbi=2 indent one full indentation level
2397 -bbp=n, --break-before-paren=n
2399 This flag is similar to -bbhb=n, described above, except it applies
2400 to lists contained within parens.
2401 -bbp=0 never break [default]
2403 -bbp=1 stable: break if the input script had a break
2404 -bpb=2 break if list is 'complex' (part of nested list structure)
2405 -bbp=3 always break
2406 -bbpi=n, --break-before-paren-and-indent=n
2408 This flag is a companion to -bbp=n for controlling the indentation
2409 of an opening paren which is placed on a new line by that
2410 parameter. The indentation is as follows:
2411 -bbpi=0 one continuation level [default]
2413 -bbpi=1 outdent by one continuation level
2414 -bbpi=2 indent one full indentation level
2415 -wn, --weld-nested-containers
2417 The -wn flag causes closely nested pairs of opening and closing
2418 container symbols (curly braces, brackets, or parens) to be
2419 "welded" together, meaning that they are treated as if combined
2420 into a single unit, with the indentation of the innermost code
2421 reduced to be as if there were just a single container symbol.
2422 For example:
2424 # default formatting
2426 do {
2427 {
2428 next if $x == $y;
2429 }
2430 } until $x++ > $z;
2431 # perltidy -wn
2433 do { {
2434 next if $x == $y;
2435 } } until $x++ > $z;
2436 When this flag is set perltidy makes a preliminary pass through the
2438 file and identifies all nested pairs of containers. To qualify as
2439 a nested pair, the closing container symbols must be immediately
2440 adjacent and the opening symbols must either (1) be adjacent as in
2441 the above example, or (2) have an anonymous sub declaration
2442 following an outer opening container symbol which is not a code
2443 block brace, or (3) have an outer opening paren separated from the
2444 inner opening symbol by any single non-container symbol or
2445 something that looks like a function evaluation, as illustrated in
2446 the next examples.
2447 Any container symbol may serve as both the inner container of one
2449 pair and as the outer container of an adjacent pair. Consequently,
2450 any number of adjacent opening or closing symbols may join together
2451 in weld. For example, here are three levels of wrapped function
2452 calls:
2453 # default formatting
2455 my (@date_time) = Localtime(
2456 Date_to_Time(
2457 Add_Delta_DHMS(
2458 $year, $month, $day, $hour, $minute, $second,
2459 '0', $offset, '0', '0'
2460 )
2461 )
2462 );
2463 # perltidy -wn
2465 my (@date_time) = Localtime( Date_to_Time( Add_Delta_DHMS(
2466 $year, $month, $day, $hour, $minute, $second,
2467 '0', $offset, '0', '0'
2468 ) ) );
2469 Notice how the indentation of the inner lines are reduced by two
2471 levels in this case. This example also shows the typical result of
2472 this formatting, namely it is a sandwich consisting of an initial
2473 opening layer, a central section of any complexity forming the
2474 "meat" of the sandwich, and a final closing layer. This
2475 predictable structure helps keep the compacted structure readable.
2476 The inner sandwich layer is required to be at least one line thick.
2478 If this cannot be achieved, welding does not occur. This
2479 constraint can cause formatting to take a couple of iterations to
2480 stabilize when it is first applied to a script. The -conv flag can
2481 be used to insure that the final format is achieved in a single
2482 run.
2483 Here is an example illustrating a welded container within a welded
2485 containers:
2486 # default formatting
2488 $x->badd(
2489 bmul(
2490 $class->new(
2491 abs(
2492 $sx * int( $xr->numify() ) & $sy * int( $yr->numify() )
2493 )
2494 ),
2495 $m
2496 )
2497 );
2498 # perltidy -wn
2500 $x->badd( bmul(
2501 $class->new( abs(
2502 $sx * int( $xr->numify() ) & $sy * int( $yr->numify() )
2503 ) ),
2504 $m
2505 ) );
2506 The welded closing tokens are by default on a separate line but
2508 this can be modified with the -vtc=n flag (described in the next
2509 section). For example, the same example adding -vtc=2 is
2510 # perltidy -wn -vtc=2
2512 $x->badd( bmul(
2513 $class->new( abs(
2514 $sx * int( $xr->numify() ) & $sy * int( $yr->numify() ) ) ),
2515 $m ) );
2516 This format option is quite general but there are some limitations.
2518 One limitation is that any line length limit still applies and can
2520 cause long welded sections to be broken into multiple lines.
2521 Another limitation is that an opening symbol which delimits quoted
2523 text cannot be included in a welded pair. This is because quote
2524 delimiters are treated specially in perltidy.
2525 Finally, the stacking of containers defined by this flag have
2527 priority over any other container stacking flags. This is because
2528 any welding is done first.
2529 -wnxl=s, --weld-nested-exclusion-list
2531 The -wnxl=s flag provides some control over the types of containers
2532 which can be welded. The -wn flag by default is "greedy" in
2533 welding adjacent containers. If it welds more types of containers
2534 than desired, this flag provides a capability to reduce the amount
2535 of welding by specifying a list of things which should not be
2536 welded.
2537 The logic in perltidy to apply this is straightforward. As each
2539 container token is being considered for joining a weld, any
2540 exclusion rules are consulted and used to reject the weld if
2541 necessary.
2542 This list is a string with space-separated items. Each item
2544 consists of up to three pieces of information: (1) an optional
2545 position, (2) an optional preceding type, and (3) a container type.
2546 The only required piece of information is a container type, which
2548 is one of '(', '[', '{' or 'q'. The first three of these are
2549 container tokens and the last represents a quoted list. For
2550 example the string
2551 -wnxl='[ { q'
2553 means do NOT include square-bracets, braces, or quotes in any
2555 welds. The only unspecified container is '(', so this string means
2556 that only welds involving parens will be made.
2557 To illustrate, following welded snippet consists of a chain of
2559 three welded containers with types '(' '[' and 'q':
2560 # perltidy -wn
2562 skip_symbols( [ qw(
2563 Perl_dump_fds
2564 Perl_ErrorNo
2565 Perl_GetVars
2566 PL_sys_intern
2567 ) ] );
2568 Even though the qw term uses parens as the quote delimiter, it has
2570 a special type 'q' here. If it appears in a weld it always appears
2571 at the end of the welded chain.
2572 Any of the container types '[', '{', and '(' may be prefixed with a
2574 position indicator which is either '^', to indicate the first token
2575 of a welded sequence, or '.', to indicate an interior token of a
2576 welded sequence. (Since a quoted string 'q' always ends a chain it
2577 does need a position indicator).
2578 For example, if we do not want a sequence of welded containers to
2580 start with a square bracket we could use
2581 -wnxl='^['
2583 In the above snippet, there is a square bracket but it does not
2585 start the chain, so the formatting would be unchanged if it were
2586 formatted with this restriction.
2587 A third optional item of information which can be given is an
2589 alphanumeric letter which is used to limit the selection further
2590 depending on the type of token immediately before the container.
2591 If given, it goes just before the container symbol. The possible
2592 letters are currently 'k', 'K', 'f', 'F', 'w', and 'W', with these
2593 meanings:
2594 'k' matches if the previous nonblank token is a perl builtin keyword (such as 'if', 'while'),
2596 'K' matches if 'k' does not, meaning that the previous token is not a keyword.
2597 'f' matches if the previous token is a function other than a keyword.
2598 'F' matches if 'f' does not.
2599 'w' matches if either 'k' or 'f' match.
2600 'W' matches if 'w' does not.
2601 For example, compare
2603 # perltidy -wn
2605 if ( defined( $_Cgi_Query{
2606 $Config{'methods'}{'authentication'}{'remote'}{'cgi'}{'username'}
2607 } ) )
2608 with
2610 # perltidy -wn -wnxl='^K( {'
2612 if ( defined(
2613 $_Cgi_Query{ $Config{'methods'}{'authentication'}{'remote'}{'cgi'}
2614 {'username'} }
2615 ) )
2616 The first case does maximum welding. In the second case the leading
2618 paren is retained by the rule (it would have been rejected if
2619 preceded by a non-keyword) but the curly brace is rejected by the
2620 rule.
2621 Here are some additional example strings and their meanings:
2623 '^(' - the weld must not start with a paren
2625 '.(' - the second and later tokens may not be parens
2626 '.w(' - the second and later tokens may not keyword or function call parens
2627 '(' - no parens in a weld
2628 '^K(' - exclude a leading paren preceded by a non-keyword
2629 '.k(' - exclude a secondary paren preceded by a keyword
2630 '[ {' - exclude all brackets and braces
2631 '[ ( ^K{' - exclude everything except nested structures like do {{ ... }}
2632 Vertical tightness of non-block curly braces, parentheses, and square
2634 brackets.
2635 These parameters control what shall be called vertical tightness.
2636 Here are the main points:
2637 • Opening tokens (except for block braces) are controlled by
2639 -vt=n, or --vertical-tightness=n, where
2640 -vt=0 always break a line after opening token (default).
2642 -vt=1 do not break unless this would produce more than one
2643 step in indentation in a line.
2644 -vt=2 never break a line after opening token
2645 • You must also use the -lp flag when you use the -vt flag; the
2647 reason is explained below.
2648 • Closing tokens (except for block braces) are controlled by
2650 -vtc=n, or --vertical-tightness-closing=n, where
2651 -vtc=0 always break a line before a closing token (default),
2653 -vtc=1 do not break before a closing token which is followed
2654 by a semicolon or another closing token, and is not in
2655 a list environment.
2656 -vtc=2 never break before a closing token.
2657 -vtc=3 Like -vtc=1 except always break before a closing token
2658 if the corresponding opening token follows an = or =>.
2659 The rules for -vtc=1 and -vtc=3 are designed to maintain a
2661 reasonable balance between tightness and readability in complex
2662 lists.
2663 • Different controls may be applied to different token types, and
2665 it is also possible to control block braces; see below.
2666 • Finally, please note that these vertical tightness flags are
2668 merely hints to the formatter, and it cannot always follow
2669 them. Things which make it difficult or impossible include
2670 comments, blank lines, blocks of code within a list, and
2671 possibly the lack of the -lp parameter. Also, these flags may
2672 be ignored for very small lists (2 or 3 lines in length).
2673 Here are some examples:
2675 # perltidy -lp -vt=0 -vtc=0
2677 %romanNumerals = (
2678 one => 'I',
2679 two => 'II',
2680 three => 'III',
2681 four => 'IV',
2682 );
2683 # perltidy -lp -vt=1 -vtc=0
2685 %romanNumerals = ( one => 'I',
2686 two => 'II',
2687 three => 'III',
2688 four => 'IV',
2689 );
2690 # perltidy -lp -vt=1 -vtc=1
2692 %romanNumerals = ( one => 'I',
2693 two => 'II',
2694 three => 'III',
2695 four => 'IV', );
2696 # perltidy -vtc=3
2698 my_function(
2699 one => 'I',
2700 two => 'II',
2701 three => 'III',
2702 four => 'IV', );
2703 # perltidy -vtc=3
2705 %romanNumerals = (
2706 one => 'I',
2707 two => 'II',
2708 three => 'III',
2709 four => 'IV',
2710 );
2711 In the last example for -vtc=3, the opening paren is preceded by an
2713 equals so the closing paren is placed on a new line.
2714 The difference between -vt=1 and -vt=2 is shown here:
2716 # perltidy -lp -vt=1
2718 $init->add(
2719 mysprintf( "(void)find_threadsv(%s);",
2720 cstring( $threadsv_names[ $op->targ ] )
2721 )
2722 );
2723 # perltidy -lp -vt=2
2725 $init->add( mysprintf( "(void)find_threadsv(%s);",
2726 cstring( $threadsv_names[ $op->targ ] )
2727 )
2728 );
2729 With -vt=1, the line ending in "add(" does not combine with the
2731 next line because the next line is not balanced. This can help
2732 with readability, but -vt=2 can be used to ignore this rule.
2733 The tightest, and least readable, code is produced with both
2735 "-vt=2" and "-vtc=2":
2736 # perltidy -lp -vt=2 -vtc=2
2738 $init->add( mysprintf( "(void)find_threadsv(%s);",
2739 cstring( $threadsv_names[ $op->targ ] ) ) );
2740 Notice how the code in all of these examples collapses vertically
2742 as -vt increases, but the indentation remains unchanged. This is
2743 because perltidy implements the -vt parameter by first formatting
2744 as if -vt=0, and then simply overwriting one output line on top of
2745 the next, if possible, to achieve the desired vertical tightness.
2746 The -lp indentation style has been designed to allow this vertical
2747 collapse to occur, which is why it is required for the -vt
2748 parameter.
2749 The -vt=n and -vtc=n parameters apply to each type of container
2751 token. If desired, vertical tightness controls can be applied
2752 independently to each of the closing container token types.
2753 The parameters for controlling parentheses are -pvt=n or
2755 --paren-vertical-tightness=n, and -pvtc=n or
2756 --paren-vertical-tightness-closing=n.
2757 Likewise, the parameters for square brackets are -sbvt=n or
2759 --square-bracket-vertical-tightness=n, and -sbvtc=n or
2760 --square-bracket-vertical-tightness-closing=n.
2761 Finally, the parameters for controlling non-code block braces are
2763 -bvt=n or --brace-vertical-tightness=n, and -bvtc=n or
2764 --brace-vertical-tightness-closing=n.
2765 In fact, the parameter -vt=n is actually just an abbreviation for
2767 -pvt=n -bvt=n sbvt=n, and likewise -vtc=n is an abbreviation for
2768 -pvtc=n -bvtc=n -sbvtc=n.
2769 -bbvt=n or --block-brace-vertical-tightness=n
2771 The -bbvt=n flag is just like the -vt=n flag but applies to opening
2772 code block braces.
2773 -bbvt=0 break after opening block brace (default).
2775 -bbvt=1 do not break unless this would produce more than one
2776 step in indentation in a line.
2777 -bbvt=2 do not break after opening block brace.
2778 It is necessary to also use either -bl or -bli for this to work,
2780 because, as with other vertical tightness controls, it is
2781 implemented by simply overwriting a line ending with an opening
2782 block brace with the subsequent line. For example:
2783 # perltidy -bli -bbvt=0
2785 if ( open( FILE, "< $File" ) )
2786 {
2787 while ( $File = <FILE> )
2788 {
2789 $In .= $File;
2790 $count++;
2791 }
2792 close(FILE);
2793 }
2794 # perltidy -bli -bbvt=1
2796 if ( open( FILE, "< $File" ) )
2797 { while ( $File = <FILE> )
2798 { $In .= $File;
2799 $count++;
2800 }
2801 close(FILE);
2802 }
2803 By default this applies to blocks associated with keywords if,
2805 elsif, else, unless, for, foreach, sub, while, until, and also with
2806 a preceding label. This can be changed with the parameter
2807 -bbvtl=string, or --block-brace-vertical-tightness-list=string,
2808 where string is a space-separated list of block types. For more
2809 information on the possible values of this string, see "Specifying
2810 Block Types"
2811 For example, if we want to just apply this style to "if", "elsif",
2813 and "else" blocks, we could use "perltidy -bli -bbvt=1 -bbvtl='if
2814 elsif else'".
2815 There is no vertical tightness control for closing block braces;
2817 with one exception they will be placed on separate lines. The
2818 exception is that a cascade of closing block braces may be stacked
2819 on a single line. See -scbb.
2820 -sot, --stack-opening-tokens and related flags
2822 The -sot flag tells perltidy to "stack" opening tokens when
2823 possible to avoid lines with isolated opening tokens.
2824 For example:
2826 # default
2828 $opt_c = Text::CSV_XS->new(
2829 {
2830 binary => 1,
2831 sep_char => $opt_c,
2832 always_quote => 1,
2833 }
2834 );
2835 # -sot
2837 $opt_c = Text::CSV_XS->new( {
2838 binary => 1,
2839 sep_char => $opt_c,
2840 always_quote => 1,
2841 }
2842 );
2843 For detailed control of individual closing tokens the following
2845 controls can be used:
2846 -sop or --stack-opening-paren
2848 -sohb or --stack-opening-hash-brace
2849 -sosb or --stack-opening-square-bracket
2850 -sobb or --stack-opening-block-brace
2851 The flag -sot is an abbreviation for -sop -sohb -sosb.
2853 The flag -sobb is an abbreviation for -bbvt=2 -bbvtl='*'. This
2855 will case a cascade of opening block braces to appear on a single
2856 line, although this an uncommon occurrence except in test scripts.
2857 -sct, --stack-closing-tokens and related flags
2859 The -sct flag tells perltidy to "stack" closing tokens when
2860 possible to avoid lines with isolated closing tokens.
2861 For example:
2863 # default
2865 $opt_c = Text::CSV_XS->new(
2866 {
2867 binary => 1,
2868 sep_char => $opt_c,
2869 always_quote => 1,
2870 }
2871 );
2872 # -sct
2874 $opt_c = Text::CSV_XS->new(
2875 {
2876 binary => 1,
2877 sep_char => $opt_c,
2878 always_quote => 1,
2879 } );
2880 The -sct flag is somewhat similar to the -vtc flags, and in some
2882 cases it can give a similar result. The difference is that the
2883 -vtc flags try to avoid lines with leading opening tokens by
2884 "hiding" them at the end of a previous line, whereas the -sct flag
2885 merely tries to reduce the number of lines with isolated closing
2886 tokens by stacking them but does not try to hide them. For
2887 example:
2888 # -vtc=2
2890 $opt_c = Text::CSV_XS->new(
2891 {
2892 binary => 1,
2893 sep_char => $opt_c,
2894 always_quote => 1, } );
2895 For detailed control of the stacking of individual closing tokens
2897 the following controls can be used:
2898 -scp or --stack-closing-paren
2900 -schb or --stack-closing-hash-brace
2901 -scsb or --stack-closing-square-bracket
2902 -scbb or --stack-closing-block-brace
2903 The flag -sct is an abbreviation for stacking the non-block closing
2905 tokens, -scp -schb -scsb.
2906 Stacking of closing block braces, -scbb, causes a cascade of
2908 isolated closing block braces to be combined into a single line as
2909 in the following example:
2910 # -scbb:
2912 for $w1 (@w1) {
2913 for $w2 (@w2) {
2914 for $w3 (@w3) {
2915 for $w4 (@w4) {
2916 push( @lines, "$w1 $w2 $w3 $w4\n" );
2917 } } } }
2918 To simplify input even further for the case in which both opening
2920 and closing non-block containers are stacked, the flag -sac or
2921 --stack-all-containers is an abbreviation for -sot -sct.
2922 Please note that if both opening and closing tokens are to be
2924 stacked, then the newer flag -weld-nested-containers may be
2925 preferable because it insures that stacking is always done
2926 symmetrically. It also removes an extra level of unnecessary
2927 indentation within welded containers. It is able to do this
2928 because it works on formatting globally rather than locally, as the
2929 -sot and -sct flags do.
2930 -dnl, --delete-old-newlines
2932 By default, perltidy first deletes all old line break locations,
2933 and then it looks for good break points to match the desired line
2934 length. Use -ndnl or --nodelete-old-newlines to force perltidy to
2935 retain all old line break points.
2936 -anl, --add-newlines
2938 By default, perltidy will add line breaks when necessary to create
2939 continuations of long lines and to improve the script appearance.
2940 Use -nanl or --noadd-newlines to prevent any new line breaks.
2941 This flag does not prevent perltidy from eliminating existing line
2943 breaks; see --freeze-newlines to completely prevent changes to line
2944 break points.
2945 Controlling whether perltidy breaks before or after operators
2947 Four command line parameters provide some control over whether a
2948 line break should be before or after specific token types. Two
2949 parameters give detailed control:
2950 -wba=s or --want-break-after=s, and
2952 -wbb=s or --want-break-before=s.
2954 These parameters are each followed by a quoted string, s,
2956 containing a list of token types (separated only by spaces). No
2957 more than one of each of these parameters should be specified,
2958 because repeating a command-line parameter always overwrites the
2959 previous one before perltidy ever sees it.
2960 By default, perltidy breaks after these token types:
2962 % + - * / x != == >= <= =~ !~ < > | &
2963 = **= += *= &= <<= &&= -= /= |= >>= ||= //= .= %= ^= x=
2964 And perltidy breaks before these token types by default:
2966 . << >> -> && || //
2967 To illustrate, to cause a break after a concatenation operator,
2969 '.', rather than before it, the command line would be
2970 -wba="."
2972 As another example, the following command would cause a break
2974 before math operators '+', '-', '/', and '*':
2975 -wbb="+ - / *"
2977 These commands should work well for most of the token types that
2979 perltidy uses (use --dump-token-types for a list). Also try the -D
2980 flag on a short snippet of code and look at the .DEBUG file to see
2981 the tokenization. However, for a few token types there may be
2982 conflicts with hardwired logic which cause unexpected results. One
2983 example is curly braces, which should be controlled with the
2984 parameter bl provided for that purpose.
2985 WARNING Be sure to put these tokens in quotes to avoid having them
2987 misinterpreted by your command shell.
2988 Two additional parameters are available which, though they provide
2990 no further capability, can simplify input are:
2991 -baao or --break-after-all-operators,
2993 -bbao or --break-before-all-operators.
2995 The -baao sets the default to be to break after all of the
2997 following operators:
2998 % + - * / x != == >= <= =~ !~ < > | &
3000 = **= += *= &= <<= &&= -= /= |= >>= ||= //= .= %= ^= x=
3001 . : ? && || and or err xor
3002 and the -bbao flag sets the default to break before all of these
3004 operators. These can be used to define an initial break preference
3005 which can be fine-tuned with the -wba and -wbb flags. For example,
3006 to break before all operators except an = one could use --bbao
3007 -wba='=' rather than listing every single perl operator except = on
3008 a -wbb flag.
3009 Controlling List Formatting
3011 Perltidy attempts to format lists of comma-separated values in tables
3012 which look good. Its default algorithms usually work well, but
3013 sometimes they don't. In this case, there are several methods
3014 available to control list formatting.
3015 A very simple way to prevent perltidy from changing the line breaks
3017 within a comma-separated list of values is to insert a blank line,
3018 comment, or side-comment anywhere between the opening and closing
3019 parens (or braces or brackets). This causes perltidy to skip over its
3020 list formatting logic. (The reason is that any of these items put a
3021 constraint on line breaks, and perltidy needs complete control over
3022 line breaks within a container to adjust a list layout). For example,
3023 let us consider
3024 my @list = (1,
3026 1, 1,
3027 1, 2, 1,
3028 1, 3, 3, 1,
3029 1, 4, 6, 4, 1,);
3030 The default formatting, which allows a maximum line length of 80, will
3032 flatten this down to one line:
3033 # perltidy (default)
3035 my @list = ( 1, 1, 1, 1, 2, 1, 1, 3, 3, 1, 1, 4, 6, 4, 1, );
3036 This formatting loses important information. If we place a side
3038 comment on one of the lines, for example, we get the following result
3039 with with default formatting parameters:
3040 my @list = (
3042 1, # a side comment, comment, or blank keeps list intact
3043 1, 1,
3044 1, 2, 1,
3045 1, 3, 3, 1,
3046 1, 4, 6, 4, 1,
3047 );
3048 We could achieve the same result with a blank line or full comment
3050 anywhere between the opening and closing parens.
3051 For another possibility see the -fs flag in "Skipping Selected Sections
3053 of Code".
3054 -boc, --break-at-old-comma-breakpoints
3056 The -boc flag is another way to prevent comma-separated lists from
3057 being reformatted. Using -boc on the above example, plus
3058 additional flags to retain the original style, yields
3059 # perltidy -boc -lp -pt=2 -vt=1 -vtc=1
3061 my @list = (1,
3062 1, 1,
3063 1, 2, 1,
3064 1, 3, 3, 1,
3065 1, 4, 6, 4, 1,);
3066 A disadvantage of this flag is that all tables in the file must
3068 already be nicely formatted.
3069 -mft=n, --maximum-fields-per-table=n
3071 If the computed number of fields for any table exceeds n, then it
3072 will be reduced to n. The default value for n is a large number,
3073 40. While this value should probably be left unchanged as a
3074 general rule, it might be used on a small section of code to force
3075 a list to have a particular number of fields per line, and then
3076 either the -boc flag could be used to retain this formatting, or a
3077 single comment could be introduced somewhere to freeze the
3078 formatting in future applications of perltidy.
3079 # perltidy -mft=2
3081 @month_of_year = (
3082 'Jan', 'Feb',
3083 'Mar', 'Apr',
3084 'May', 'Jun',
3085 'Jul', 'Aug',
3086 'Sep', 'Oct',
3087 'Nov', 'Dec'
3088 );
3089 -cab=n, --comma-arrow-breakpoints=n
3091 A comma which follows a comma arrow, '=>', is given special
3092 consideration. In a long list, it is common to break at all such
3093 commas. This parameter can be used to control how perltidy breaks
3094 at these commas. (However, it will have no effect if old comma
3095 breaks are being forced because -boc is used). The possible values
3096 of n are:
3097 n=0 break at all commas after =>
3099 n=1 stable: break at all commas after => if container is open,
3100 EXCEPT FOR one-line containers
3101 n=2 break at all commas after =>, BUT try to form the maximum
3102 one-line container lengths
3103 n=3 do not treat commas after => specially at all
3104 n=4 break everything: like n=0 but ALSO break a short container with
3105 a => not followed by a comma when -vt=0 is used
3106 n=5 stable: like n=1 but ALSO break at open one-line containers when
3107 -vt=0 is used (default)
3108 For example, given the following single line, perltidy by default
3110 will not add any line breaks because it would break the existing
3111 one-line container:
3112 bless { B => $B, Root => $Root } => $package;
3114 Using -cab=0 will force a break after each comma-arrow item:
3116 # perltidy -cab=0:
3118 bless {
3119 B => $B,
3120 Root => $Root
3121 } => $package;
3122 If perltidy is subsequently run with this container broken, then by
3124 default it will break after each '=>' because the container is now
3125 broken. To reform a one-line container, the parameter -cab=2 could
3126 be used.
3127 The flag -cab=3 can be used to prevent these commas from being
3129 treated specially. In this case, an item such as "01" => 31 is
3130 treated as a single item in a table. The number of fields in this
3131 table will be determined by the same rules that are used for any
3132 other table. Here is an example.
3133 # perltidy -cab=3
3135 my %last_day = (
3136 "01" => 31, "02" => 29, "03" => 31, "04" => 30,
3137 "05" => 31, "06" => 30, "07" => 31, "08" => 31,
3138 "09" => 30, "10" => 31, "11" => 30, "12" => 31
3139 );
3140 Retaining or Ignoring Existing Line Breaks
3142 Several additional parameters are available for controlling the extent
3143 to which line breaks in the input script influence the output script.
3144 In most cases, the default parameter values are set so that, if a
3145 choice is possible, the output style follows the input style. For
3146 example, if a short logical container is broken in the input script,
3147 then the default behavior is for it to remain broken in the output
3148 script.
3149 Most of the parameters in this section would only be required for a
3151 one-time conversion of a script from short container lengths to longer
3152 container lengths. The opposite effect, of converting long container
3153 lengths to shorter lengths, can be obtained by temporarily using a
3154 short maximum line length.
3155 -bol, --break-at-old-logical-breakpoints
3157 By default, if a logical expression is broken at a "&&", "||",
3158 "and", or "or", then the container will remain broken. Also,
3159 breaks at internal keywords "if" and "unless" will normally be
3160 retained. To prevent this, and thus form longer lines, use -nbol.
3161 Please note that this flag does not duplicate old logical
3163 breakpoints. They are merely used as a hint with this flag that a
3164 statement should remain broken. Without this flag, perltidy will
3165 normally try to combine relatively short expressions into a single
3166 line.
3167 For example, given this snippet:
3169 return unless $cmd = $cmd || ($dot
3171 && $Last_Shell) || &prompt('|');
3172 # perltidy -bol [default]
3174 return
3175 unless $cmd = $cmd
3176 || ( $dot
3177 && $Last_Shell )
3178 || &prompt('|');
3179 # perltidy -nbol
3181 return unless $cmd = $cmd || ( $dot && $Last_Shell ) || &prompt('|');
3182 -bom, --break-at-old-method-breakpoints
3184 By default, a method call arrow "->" is considered a candidate for
3185 a breakpoint, but method chains will fill to the line width before
3186 a break is considered. With -bom, breaks before the arrow are
3187 preserved, so if you have preformatted a method chain:
3188 my $q = $rs
3190 ->related_resultset('CDs')
3191 ->related_resultset('Tracks')
3192 ->search({
3193 'track.id' => {-ident => 'none_search.id'},
3194 })->as_query;
3195 It will keep these breaks, rather than become this:
3197 my $q = $rs->related_resultset('CDs')->related_resultset('Tracks')->search({
3199 'track.id' => {-ident => 'none_search.id'},
3200 })->as_query;
3201 This flag will also look for and keep a 'cuddled' style of calls,
3203 in which lines begin with a closing paren followed by a call arrow,
3204 as in this example:
3205 # perltidy -bom -wn
3207 my $q = $rs->related_resultset(
3208 'CDs'
3209 )->related_resultset(
3210 'Tracks'
3211 )->search( {
3212 'track.id' => { -ident => 'none_search.id' },
3213 } )->as_query;
3214 You may want to include the -weld-nested-containers flag in this
3216 case to keep nested braces and parens together, as in the last
3217 line.
3218 -bos, --break-at-old-semicolon-breakpoints
3220 Semicolons are normally placed at the end of a statement. This
3221 means that formatted lines do not normally begin with semicolons.
3222 If the input stream has some lines which begin with semicolons,
3223 these can be retained by setting this flag. For example, consider
3224 the following two-line input snippet:
3225 $z = sqrt($x**2 + $y**2)
3227 ;
3228 The default formatting will be:
3230 $z = sqrt( $x**2 + $y**2 );
3232 The result using perltidy -bos keeps the isolated semicolon:
3234 $z = sqrt( $x**2 + $y**2 )
3236 ;
3237 The default is not to do this, -nbos.
3239 -bok, --break-at-old-keyword-breakpoints
3241 By default, perltidy will retain a breakpoint before keywords which
3242 may return lists, such as "sort" and <map>. This allows chains of
3243 these operators to be displayed one per line. Use -nbok to prevent
3244 retaining these breakpoints.
3245 -bot, --break-at-old-ternary-breakpoints
3247 By default, if a conditional (ternary) operator is broken at a ":",
3248 then it will remain broken. To prevent this, and thereby form
3249 longer lines, use -nbot.
3250 -boa, --break-at-old-attribute-breakpoints
3252 By default, if an attribute list is broken at a ":" in the source
3253 file, then it will remain broken. For example, given the following
3254 code, the line breaks at the ':'s will be retained:
3255 my @field
3257 : field
3258 : Default(1)
3259 : Get('Name' => 'foo') : Set('Name');
3260 If the attributes are on a single line in the source code then they
3262 will remain on a single line if possible.
3263 To prevent this, and thereby always form longer lines, use -nboa.
3265 Keeping old breakpoints at specific token types
3267 Two command line parameters provide detailed control over whether
3268 perltidy should keep an old line break before or after a specific
3269 token type:
3270 -kbb=s or --keep-old-breakpoints-before=s, and
3272 -kba=s or --keep-old-breakpoints-after=s
3274 These parameters are each followed by a quoted string, s,
3276 containing a list of token types (separated only by spaces). No
3277 more than one of each of these parameters should be specified,
3278 because repeating a command-line parameter always overwrites the
3279 previous one before perltidy ever sees it.
3280 For example, -kbb='=>' means that if an input line begins with a
3282 '=>' then the output script should also have a line break before
3283 that token.
3284 For example, given the script:
3286 method 'foo'
3288 => [ Int, Int ]
3289 => sub {
3290 my ( $self, $x, $y ) = ( shift, @_ );
3291 ...;
3292 };
3293 # perltidy [default]
3295 method 'foo' => [ Int, Int ] => sub {
3296 my ( $self, $x, $y ) = ( shift, @_ );
3297 ...;
3298 };
3299 # perltidy -kbb='=>'
3301 method 'foo'
3302 => [ Int, Int ]
3303 => sub {
3304 my ( $self, $x, $y ) = ( shift, @_ );
3305 ...;
3306 };
3307 -iob, --ignore-old-breakpoints
3309 Use this flag to tell perltidy to ignore existing line breaks to
3310 the maximum extent possible. This will tend to produce the longest
3311 possible containers, regardless of type, which do not exceed the
3312 line length limit. But please note that this parameter has priority
3313 over all other parameters requesting that certain old breakpoints
3314 be kept.
3315 -kis, --keep-interior-semicolons
3317 Use the -kis flag to prevent breaking at a semicolon if there was
3318 no break there in the input file. Normally perltidy places a
3319 newline after each semicolon which terminates a statement unless
3320 several statements are contained within a one-line brace block. To
3321 illustrate, consider the following input lines:
3322 dbmclose(%verb_delim); undef %verb_delim;
3324 dbmclose(%expanded); undef %expanded;
3325 The default is to break after each statement, giving
3327 dbmclose(%verb_delim);
3329 undef %verb_delim;
3330 dbmclose(%expanded);
3331 undef %expanded;
3332 With perltidy -kis the multiple statements are retained:
3334 dbmclose(%verb_delim); undef %verb_delim;
3336 dbmclose(%expanded); undef %expanded;
3337 The statements are still subject to the specified value of maximum-
3339 line-length and will be broken if this maximum is exceeded.
3340 Blank Line Control
3342 Blank lines can improve the readability of a script if they are
3343 carefully placed. Perltidy has several commands for controlling the
3344 insertion, retention, and removal of blank lines.
3345 -fbl, --freeze-blank-lines
3347 Set -fbl if you want to the blank lines in your script to remain
3348 exactly as they are. The rest of the parameters in this section
3349 may then be ignored. (Note: setting the -fbl flag is equivalent to
3350 setting -mbl=0 and -kbl=2).
3351 -bbc, --blanks-before-comments
3353 A blank line will be introduced before a full-line comment. This
3354 is the default. Use -nbbc or --noblanks-before-comments to
3355 prevent such blank lines from being introduced.
3356 -blbs=n, --blank-lines-before-subs=n
3358 The parameter -blbs=n requests that least n blank lines precede a
3359 sub definition which does not follow a comment and which is more
3360 than one-line long. The default is <-blbs=1>. BEGIN and END
3361 blocks are included.
3362 The requested number of blanks statement will be inserted
3364 regardless of the value of --maximum-consecutive-blank-lines=n
3365 (-mbl=n) with the exception that if -mbl=0 then no blanks will be
3366 output.
3367 This parameter interacts with the value k of the parameter
3369 --maximum-consecutive-blank-lines=k (-mbl=k) as follows:
3370 1. If -mbl=0 then no blanks will be output. This allows all blanks
3372 to be suppressed with a single parameter. Otherwise,
3373 2. If the number of old blank lines in the script is less than n
3375 then additional blanks will be inserted to make the total n
3376 regardless of the value of -mbl=k.
3377 3. If the number of old blank lines in the script equals or exceeds
3379 n then this parameter has no effect, however the total will not
3380 exceed value specified on the -mbl=k flag.
3381 -blbp=n, --blank-lines-before-packages=n
3383 The parameter -blbp=n requests that least n blank lines precede a
3384 package which does not follow a comment. The default is -blbp=1.
3385 This parameter interacts with the value k of the parameter
3387 --maximum-consecutive-blank-lines=k (-mbl=k) in the same way as
3388 described for the previous item -blbs=n.
3389 -bbs, --blanks-before-subs
3391 For compatibility with previous versions, -bbs or
3392 --blanks-before-subs is equivalent to -blbp=1 and -blbs=1.
3393 Likewise, -nbbs or --noblanks-before-subs is equivalent to -blbp=0
3395 and -blbs=0.
3396 -bbb, --blanks-before-blocks
3398 A blank line will be introduced before blocks of coding delimited
3399 by for, foreach, while, until, and if, unless, in the following
3400 circumstances:
3401 • The block is not preceded by a comment.
3403 • The block is not a one-line block.
3405 • The number of consecutive non-blank lines at the current
3407 indentation depth is at least -lbl (see next section).
3408 This is the default. The intention of this option is to introduce
3410 some space within dense coding. This is negated with -nbbb or
3411 --noblanks-before-blocks.
3412 -lbl=n --long-block-line-count=n
3414 This controls how often perltidy is allowed to add blank lines
3415 before certain block types (see previous section). The default is
3416 8. Entering a value of 0 is equivalent to entering a very large
3417 number.
3418 -blao=i or --blank-lines-after-opening-block=i
3420 This control places a minimum of i blank lines after a line which
3421 ends with an opening block brace of a specified type. By default,
3422 this only applies to the block of a named sub, but this can be
3423 changed (see -blaol below). The default is not to do this (i=0).
3424 Please see the note below on using the -blao and -blbc options.
3426 -blbc=i or --blank-lines-before-closing-block=i
3428 This control places a minimum of i blank lines before a line which
3429 begins with a closing block brace of a specified type. By default,
3430 this only applies to the block of a named sub, but this can be
3431 changed (see -blbcl below). The default is not to do this (i=0).
3432 -blaol=s or --blank-lines-after-opening-block-list=s
3434 The parameter s is a list of block type keywords to which the flag
3435 -blao should apply. The section "Specifying Block Types" explains
3436 how to list block types.
3437 -blbcl=s or --blank-lines-before-closing-block-list=s
3439 This parameter is a list of block type keywords to which the flag
3440 -blbc should apply. The section "Specifying Block Types" explains
3441 how to list block types.
3442 Note on using the -blao and -blbc options.
3444 These blank line controls introduce a certain minimum number of
3445 blank lines in the text, but the final number of blank lines may be
3446 greater, depending on values of the other blank line controls and
3447 the number of old blank lines. A consequence is that introducing
3448 blank lines with these and other controls cannot be exactly undone,
3449 so some experimentation with these controls is recommended before
3450 using them.
3451 For example, suppose that for some reason we decide to introduce
3453 one blank space at the beginning and ending of all blocks. We
3454 could do this using
3455 perltidy -blao=2 -blbc=2 -blaol='*' -blbcl='*' filename
3457 Now suppose the script continues to be developed, but at some later
3459 date we decide we don't want these spaces after all. We might
3460 expect that running with the flags -blao=0 and -blbc=0 will undo
3461 them. However, by default perltidy retains single blank lines, so
3462 the blank lines remain.
3463 We can easily fix this by telling perltidy to ignore old blank
3465 lines by including the added parameter -kbl=0 and rerunning. Then
3466 the unwanted blank lines will be gone. However, this will cause
3467 all old blank lines to be ignored, perhaps even some that were
3468 added by hand to improve formatting. So please be cautious when
3469 using these parameters.
3470 -mbl=n --maximum-consecutive-blank-lines=n
3472 This parameter specifies the maximum number of consecutive blank
3473 lines which will be output within code sections of a script. The
3474 default is n=1. If the input file has more than n consecutive
3475 blank lines, the number will be reduced to n except as noted above
3476 for the -blbp and -blbs parameters. If n=0 then no blank lines
3477 will be output (unless all old blank lines are retained with the
3478 -kbl=2 flag of the next section).
3479 This flag obviously does not apply to pod sections, here-documents,
3481 and quotes.
3482 -kbl=n, --keep-old-blank-lines=n
3484 The -kbl=n flag gives you control over how your existing blank
3485 lines are treated.
3486 The possible values of n are:
3488 n=0 ignore all old blank lines
3490 n=1 stable: keep old blanks, but limited by the value of the B<-mbl=n> flag
3491 n=2 keep all old blank lines, regardless of the value of the B<-mbl=n> flag
3492 The default is n=1.
3494 -sob, --swallow-optional-blank-lines
3496 This is equivalent to kbl=0 and is included for compatibility with
3497 previous versions.
3498 -nsob, --noswallow-optional-blank-lines
3500 This is equivalent to kbl=1 and is included for compatibility with
3501 previous versions.
3502 Controls for blank lines around lines of consecutive keywords
3504 The parameters in this section provide some control over the placement
3506 of blank lines within and around groups of statements beginning with
3507 selected keywords. These blank lines are called here keyword group
3508 blanks, and all of the parameters begin with --keyword-group-blanks*,
3509 or -kgb* for short. The default settings do not employ these controls
3510 but they can be enabled with the following parameters:
3511 -kgbl=s or --keyword-group-blanks-list=s; s is a quoted string of
3513 keywords
3514 -kgbs=s or --keyword-group-blanks-size=s; s gives the number of
3516 keywords required to form a group.
3517 -kgbb=n or --keyword-group-blanks-before=n; n = (0, 1, or 2) controls a
3519 leading blank
3520 -kgba=n or --keyword-group-blanks-after=n; n = (0, 1, or 2) controls a
3522 trailing blank
3523 -kgbi or --keyword-group-blanks-inside is a switch for adding blanks
3525 between subgroups
3526 -kgbd or --keyword-group-blanks-delete is a switch for removing initial
3528 blank lines between keywords
3529 -kgbr=n or --keyword-group-blanks-repeat-count=n can limit the number
3531 of times this logic is applied
3532 In addition, the following abbreviations are available to for
3534 simplified usage:
3535 -kgb or --keyword-group-blanks is short for -kgbb=2 -kgba=2 kgbi
3537 -nkgb or --nokeyword-group-blanks, is short for -kgbb=1 -kgba=1 nkgbi
3539 Before describing the meaning of the parameters in detail let us look
3541 at an example which is formatted with default parameter settings.
3542 print "Entering test 2\n";
3544 use Test;
3545 use Encode qw(from_to encode decode
3546 encode_utf8 decode_utf8
3547 find_encoding is_utf8);
3548 use charnames qw(greek);
3549 my @encodings = grep( /iso-?8859/, Encode::encodings() );
3550 my @character_set = ( '0' .. '9', 'A' .. 'Z', 'a' .. 'z' );
3551 my @source = qw(ascii iso8859-1 cp1250);
3552 my @destiny = qw(cp1047 cp37 posix-bc);
3553 my @ebcdic_sets = qw(cp1047 cp37 posix-bc);
3554 my $str = join( '', map( chr($_), 0x20 .. 0x7E ) );
3555 return unless ($str);
3556 using perltidy -kgb gives:
3558 print "Entering test 2\n";
3560 <----------this blank controlled by -kgbb
3561 use Test;
3562 use Encode qw(from_to encode decode
3563 encode_utf8 decode_utf8
3564 find_encoding is_utf8);
3565 use charnames qw(greek);
3566 <---------this blank controlled by -kgbi
3567 my @encodings = grep( /iso-?8859/, Encode::encodings() );
3568 my @character_set = ( '0' .. '9', 'A' .. 'Z', 'a' .. 'z' );
3569 my @source = qw(ascii iso8859-1 cp1250);
3570 my @destiny = qw(cp1047 cp37 posix-bc);
3571 my @ebcdic_sets = qw(cp1047 cp37 posix-bc);
3572 my $str = join( '', map( chr($_), 0x20 .. 0x7E ) );
3573 <----------this blank controlled by -kgba
3574 return unless ($str);
3575 Blank lines have been introduced around the my and use sequences. What
3577 happened is that the default keyword list includes my and use but not
3578 print and return. So a continuous sequence of nine my and use
3579 statements was located. This number exceeds the default threshold of
3580 five, so blanks were placed before and after the entire group. Then,
3581 since there was also a subsequence of six my lines, a blank line was
3582 introduced to separate them.
3583 Finer control over blank placement can be achieved by using the
3585 individual parameters rather than the -kgb flag. The individual
3586 controls are as follows.
3587 -kgbl=s or --keyword-group-blanks-list=s, where s is a quoted string,
3589 defines the set of keywords which will be formed into groups. The
3590 string is a space separated list of keywords. The default set is
3591 s="use require local our my", but any list of keywords may be used.
3592 Comment lines may also be included in a keyword group, even though they
3593 are not keywords. To include ordinary block comments, include the
3594 symbol BC. To include static block comments (which normally begin with
3595 '##'), include the symbol SBC.
3596 -kgbs=s or --keyword-group-blanks-size=s, where s is a string
3598 describing the number of consecutive keyword statements forming a
3599 group. If s is an integer then it is the minimum number required for a
3600 group. A maximum value may also be given with the format s=min.max,
3601 where min is the minimum number and max is the maximum number, and the
3602 min and max values are separated by one or more dots. No groups will
3603 be found if the maximum is less than the minimum. The maximum is
3604 unlimited if not given. The default is s=5. Some examples:
3605 s min max number for group
3607 3 3 unlimited 3 or more
3608 1.1 1 1 1
3609 1..3 1 3 1 to 3
3610 1.0 1 0 (no match)
3611 -kgbb=n or --keyword-group-blanks-before=n specifies whether a blank
3613 should appear before the first line of the group, as follows:
3614 n=0 => (delete) an existing blank line will be removed
3616 n=1 => (stable) no change to the input file is made [DEFAULT]
3617 n=2 => (insert) a blank line is introduced if possible
3618 -kgba=n or --keyword-group-blanks-after=n likewise specifies whether a
3620 blank should appear after the last line of the group, using the same
3621 scheme (0=delete, 1=stable, 2=insert).
3622 -kgbi or --keyword-group-blanks-inside controls the insertion of blank
3624 lines between the first and last statement of the entire group. If
3625 there is a continuous run of a single statement type with more than the
3626 minimum threshold number (as specified with -kgbs=s) then this switch
3627 causes a blank line be inserted between this subgroup and the others.
3628 In the example above this happened between the use and my statements.
3629 -kgbd or --keyword-group-blanks-delete controls the deletion of any
3631 blank lines that exist in the the group when it is first scanned. When
3632 statements are initially scanned, any existing blank lines are included
3633 in the collection. Any such orignial blank lines will be deleted
3634 before any other insertions are made when the parameter -kgbd is set.
3635 The default is not to do this, -nkgbd.
3636 -kgbr=n or --keyword-group-blanks-repeat-count=n specifies n, the
3638 maximum number of times this logic will be applied to any file. The
3639 special value n=0 is the same as n=infinity which means it will be
3640 applied to an entire script [Default]. A value n=1 could be used to
3641 make it apply just one time for example. This might be useful for
3642 adjusting just the use statements in the top part of a module for
3643 example.
3644 -kgb or --keyword-group-blanks is an abbreviation equivalent to setting
3646 -kgbb=1 -kgba=1 -kgbi. This turns on keyword group formatting with a
3647 set of default values.
3648 -nkgb or --nokeyword-group-blanks is equivalent to -kgbb=0 -kgba nkgbi.
3650 This flag turns off keyword group blank lines and is the default
3651 setting.
3652 Here are a few notes about the functioning of this technique.
3654 • These parameters are probably more useful as part of a major code
3656 reformatting operation rather than as a routine formatting
3657 operation.
3658 In particular, note that deleting old blank lines with -kgbd is an
3660 irreversible operation so it should be applied with care. Existing
3661 blank lines may be serving an important role in controlling
3662 vertical alignment.
3663 • Conflicts which arise among these kgb* parameters and other blank
3665 line controls are generally resolved by producing the maximum
3666 number of blank lines implied by any parameter.
3667 For example, if the flags --freeze-blank-lines, or
3669 --keep-old-blank-lines=2, are set, then they have priority over any
3670 blank line deletion implied by the -kgb flags of this section, so
3671 no blank lines will be deleted.
3672 For another example, if a keyword group ends at a sub and the flag
3674 kgba=0 requests no blank line there, but we also have
3675 --blank-lines-before-subs=2, then two blank lines will still be
3676 introduced before the sub.
3677 • The introduction of blank lines does not occur if it would conflict
3679 with other input controls or code validity. For example, a blank
3680 line will not be placed within a here-doc or within a section of
3681 code marked with format skipping comments. And in general, a blank
3682 line will only be introduced at the end of a group if the next
3683 statement is a line of code.
3684 • The count which is used to determine the group size is not the
3686 number of lines but rather the total number of keywords which are
3687 found. Individual statements with a certain leading keyword may
3688 continue on multiple lines, but if any of these lines is nested
3689 more than one level deep then that group will be ended.
3690 • The search for groups of lines with similar leading keywords is
3692 based on the input source, not the final formatted source.
3693 Consequently, if the source code is badly formatted, it would be
3694 best to make a first formatting pass without these options.
3695 Styles
3697 A style refers to a convenient collection of existing parameters.
3698 -gnu, --gnu-style
3700 -gnu gives an approximation to the GNU Coding Standards (which do
3701 not apply to perl) as they are sometimes implemented. At present,
3702 this style overrides the default style with the following
3703 parameters:
3704 -lp -bl -noll -pt=2 -bt=2 -sbt=2 -icp
3706 -pbp, --perl-best-practices
3708 -pbp is an abbreviation for the parameters in the book Perl Best
3709 Practices by Damian Conway:
3710 -l=78 -i=4 -ci=4 -st -se -vt=2 -cti=0 -pt=1 -bt=1 -sbt=1 -bbt=1 -nsfs -nolq
3712 -wbb="% + - * / x != == >= <= =~ !~ < > | & =
3713 **= += *= &= <<= &&= -= /= |= >>= ||= //= .= %= ^= x="
3714 Please note that this parameter set includes -st and -se flags,
3716 which make perltidy act as a filter on one file only. These can be
3717 overridden by placing -nst and/or -nse after the -pbp parameter.
3718 Also note that the value of continuation indentation, -ci=4, is
3720 equal to the value of the full indentation, -i=4. It is
3721 recommended that the either (1) the parameter -ci=2 be used
3722 instead, or the flag -xci be set. This will help show structure,
3723 particularly when there are ternary statements. The following
3724 snippet illustrates these options.
3725 # perltidy -pbp
3727 $self->{_text} = (
3728 !$section ? ''
3729 : $type eq 'item' ? "the $section entry"
3730 : "the section on $section"
3731 )
3732 . (
3733 $page
3734 ? ( $section ? ' in ' : '' ) . "the $page$page_ext manpage"
3735 : ' elsewhere in this document'
3736 );
3737 # perltidy -pbp -ci=2
3739 $self->{_text} = (
3740 !$section ? ''
3741 : $type eq 'item' ? "the $section entry"
3742 : "the section on $section"
3743 )
3744 . (
3745 $page
3746 ? ( $section ? ' in ' : '' ) . "the $page$page_ext manpage"
3747 : ' elsewhere in this document'
3748 );
3749 # perltidy -pbp -xci
3751 $self->{_text} = (
3752 !$section ? ''
3753 : $type eq 'item' ? "the $section entry"
3754 : "the section on $section"
3755 )
3756 . ( $page
3757 ? ( $section ? ' in ' : '' ) . "the $page$page_ext manpage"
3758 : ' elsewhere in this document'
3759 );
3760 The -xci flag was developed after the -pbp parameters were
3762 published so you need to include it separately.
3763 One-line blocks
3765 There are a few points to note regarding one-line blocks. A one-
3766 line block is something like this,
3767 where the contents within the curly braces is short enough to fit
3769 on a single line.
3770 With few exceptions, perltidy retains existing one-line blocks, if
3772 it is possible within the line-length constraint, but it does not
3773 attempt to form new ones. In other words, perltidy will try to
3774 follow the one-line block style of the input file.
3775 If an existing one-line block is longer than the maximum line
3777 length, however, it will be broken into multiple lines. When this
3778 happens, perltidy checks for and adds any optional terminating
3779 semicolon (unless the -nasc option is used) if the block is a code
3780 block.
3781 The main exception is that perltidy will attempt to form new one-
3783 line blocks following the keywords "map", "eval", and "sort",
3784 because these code blocks are often small and most clearly
3785 displayed in a single line.
3786 One-line block rules can conflict with the cuddled-else option.
3788 When the cuddled-else option is used, perltidy retains existing
3789 one-line blocks, even if they do not obey cuddled-else formatting.
3790 Occasionally, when one-line blocks get broken because they exceed
3792 the available line length, the formatting will violate the
3793 requested brace style. If this happens, reformatting the script a
3794 second time should correct the problem.
3795 Sometimes it might be desirable to convert a script to have one-
3797 line blocks whenever possible. Although there is currently no flag
3798 for this, a simple workaround is to execute perltidy twice, once
3799 with the flag -noadd-newlines and then once again with normal
3800 parameters, like this:
3801 cat infile | perltidy -nanl | perltidy >outfile
3803 When executed on this snippet
3805 if ( $? == -1 ) {
3807 die "failed to execute: $!\n";
3808 }
3809 if ( $? == -1 ) {
3810 print "Had enough.\n";
3811 die "failed to execute: $!\n";
3812 }
3813 the result is
3815 if ( $? == -1 ) { die "failed to execute: $!\n"; }
3817 if ( $? == -1 ) {
3818 print "Had enough.\n";
3819 die "failed to execute: $!\n";
3820 }
3821 This shows that blocks with a single statement become one-line
3823 blocks.
3824 -olbs=n, --one-line-block-semicolons=n
3826 This flag controls the placement of semicolons at the end of one-
3827 line blocks. Semicolons are optional before a closing block brace,
3828 and frequently they are omitted at the end of a one-line block
3829 containing just a single statement. By default, perltidy follows
3830 the input file regarding these semicolons, but this behavior can be
3831 controlled by this flag. The values of n are:
3832 n=0 remove terminal semicolons in one-line blocks having a single statement
3834 n=1 stable; keep input file placement of terminal semicolons [DEFAULT ]
3835 n=2 add terminal semicolons in all one-line blocks
3836 Note that the n=2 option has no effect if adding semicolons is
3838 prohibited with the -nasc flag. Also not that while n=2 adds
3839 missing semicolons to all one-line blocks, regardless of
3840 complexity, the n=0 option only removes ending semicolons which
3841 terminate one-line blocks containing just one semicolon. So these
3842 two options are not exact inverses.
3843 -olbn=n, --one-line-block-nesting=n
3845 Nested one-line blocks are lines with code blocks which themselves
3846 contain code blocks. For example, the following line is a nested
3847 one-line block.
3848 foreach (@list) { if ($_ eq $asked_for) { last } ++$found }
3850 The default behavior is to break such lines into multiple lines,
3852 but this behavior can be controlled with this flag. The values of
3853 n are:
3854 n=0 break nested one-line blocks into multiple lines [DEFAULT]
3856 n=1 stable: keep existing nested-one line blocks intact
3857 For the above example, the default formatting (-olbn=0) is
3859 foreach (@list) {
3861 if ( $_ eq $asked_for ) { last }
3862 ++$found;
3863 }
3864 If the parameter -olbn=1 is given, then the line will be left
3866 intact if it is a single line in the source, or it will be broken
3867 into multiple lines if it is broken in multiple lines in the
3868 source.
3869 Controlling Vertical Alignment
3871 Vertical alignment refers to lining up certain symbols in a list of
3872 consecutive similar lines to improve readability. For example, the
3873 "fat commas" are aligned in the following statement:
3874 $data = $pkg->new(
3876 PeerAddr => join( ".", @port[ 0 .. 3 ] ),
3877 PeerPort => $port[4] * 256 + $port[5],
3878 Proto => 'tcp'
3879 );
3880 Vertical alignment can be completely turned off using -novalign, a flag
3882 mainly intended for debugging. However, vertical alignment can be
3883 forced to stop and restart by selectively introducing blank lines. For
3884 example, a blank has been inserted in the following code to keep
3885 somewhat similar things aligned.
3886 %option_range = (
3888 'format' => [ 'tidy', 'html', 'user' ],
3889 'output-line-ending' => [ 'dos', 'win', 'mac', 'unix' ],
3890 'character-encoding' => [ 'none', 'utf8' ],
3891 'block-brace-tightness' => [ 0, 2 ],
3893 'brace-tightness' => [ 0, 2 ],
3894 'paren-tightness' => [ 0, 2 ],
3895 'square-bracket-tightness' => [ 0, 2 ],
3896 );
3897 Vertical alignment is implemented by locally increasing an existing
3899 blank space to produce alignment with an adjacent line. It cannot
3900 occur if there is no blank space to increase. So if a particular space
3901 is removed by one of the existing controls then vertical alignment
3902 cannot occur. Likewise, if a space is added with one of the controls,
3903 then vertical alignment might occur.
3904 For example,
3906 # perltidy -nwls='=>'
3908 $data = $pkg->new(
3909 PeerAddr=> join( ".", @port[ 0 .. 3 ] ),
3910 PeerPort=> $port[4] * 256 + $port[5],
3911 Proto=> 'tcp'
3912 );
3913 Other Controls
3915 Deleting selected text
3916 Perltidy can selectively delete comments and/or pod documentation.
3917 The command -dac or --delete-all-comments will delete all comments
3918 and all pod documentation, leaving just code and any leading system
3919 control lines.
3920 The command -dp or --delete-pod will remove all pod documentation
3922 (but not comments).
3923 Two commands which remove comments (but not pod) are: -dbc or
3925 --delete-block-comments and -dsc or --delete-side-comments.
3926 (Hanging side comments will be deleted with side comments here.)
3927 The negatives of these commands also work, and are the defaults.
3929 When block comments are deleted, any leading 'hash-bang' will be
3930 retained. Also, if the -x flag is used, any system commands before
3931 a leading hash-bang will be retained (even if they are in the form
3932 of comments).
3933 Writing selected text to a file
3935 When perltidy writes a formatted text file, it has the ability to
3936 also send selected text to a file with a .TEE extension. This text
3937 can include comments and pod documentation.
3938 The command -tac or --tee-all-comments will write all comments and
3940 all pod documentation.
3941 The command -tp or --tee-pod will write all pod documentation (but
3943 not comments).
3944 The commands which write comments (but not pod) are: -tbc or
3946 --tee-block-comments and -tsc or --tee-side-comments. (Hanging
3947 side comments will be written with side comments here.)
3948 The negatives of these commands also work, and are the defaults.
3950 Using a .perltidyrc command file
3952 If you use perltidy frequently, you probably won't be happy until
3953 you create a .perltidyrc file to avoid typing commonly-used
3954 parameters. Perltidy will first look in your current directory for
3955 a command file named .perltidyrc. If it does not find one, it will
3956 continue looking for one in other standard locations.
3957 These other locations are system-dependent, and may be displayed
3959 with the command "perltidy -dpro". Under Unix systems, it will
3960 first look for an environment variable PERLTIDY. Then it will look
3961 for a .perltidyrc file in the home directory, and then for a
3962 system-wide file /usr/local/etc/perltidyrc, and then it will look
3963 for /etc/perltidyrc. Note that these last two system-wide files do
3964 not have a leading dot. Further system-dependent information will
3965 be found in the INSTALL file distributed with perltidy.
3966 Under Windows, perltidy will also search for a configuration file
3968 named perltidy.ini since Windows does not allow files with a
3969 leading period (.). Use "perltidy -dpro" to see the possible
3970 locations for your system. An example might be C:\Documents and
3971 Settings\All Users\perltidy.ini.
3972 Another option is the use of the PERLTIDY environment variable.
3974 The method for setting environment variables depends upon the
3975 version of Windows that you are using. Instructions for Windows 95
3976 and later versions can be found here:
3977 http://www.netmanage.com/000/20021101_005_tcm21-6336.pdf
3979 Under Windows NT / 2000 / XP the PERLTIDY environment variable can
3981 be placed in either the user section or the system section. The
3982 later makes the configuration file common to all users on the
3983 machine. Be sure to enter the full path of the configuration file
3984 in the value of the environment variable. Ex.
3985 PERLTIDY=C:\Documents and Settings\perltidy.ini
3986 The configuration file is free format, and simply a list of
3988 parameters, just as they would be entered on a command line. Any
3989 number of lines may be used, with any number of parameters per
3990 line, although it may be easiest to read with one parameter per
3991 line. Comment text begins with a #, and there must also be a space
3992 before the # for side comments. It is a good idea to put complex
3993 parameters in either single or double quotes.
3994 Here is an example of a .perltidyrc file:
3996 # This is a simple of a .perltidyrc configuration file
3998 # This implements a highly spaced style
3999 -se # errors to standard error output
4000 -w # show all warnings
4001 -bl # braces on new lines
4002 -pt=0 # parens not tight at all
4003 -bt=0 # braces not tight
4004 -sbt=0 # square brackets not tight
4005 The parameters in the .perltidyrc file are installed first, so any
4007 parameters given on the command line will have priority over them.
4008 To avoid confusion, perltidy ignores any command in the .perltidyrc
4010 file which would cause some kind of dump and an exit. These are:
4011 -h -v -ddf -dln -dop -dsn -dtt -dwls -dwrs -ss
4013 There are several options may be helpful in debugging a .perltidyrc
4015 file:
4016 • A very helpful command is --dump-profile or -dpro. It writes a
4018 list of all configuration filenames tested to standard output,
4019 and if a file is found, it dumps the content to standard output
4020 before exiting. So, to find out where perltidy looks for its
4021 configuration files, and which one if any it selects, just
4022 enter
4023 perltidy -dpro
4025 • It may be simplest to develop and test configuration files with
4027 alternative names, and invoke them with -pro=filename on the
4028 command line. Then rename the desired file to .perltidyrc when
4029 finished.
4030 • The parameters in the .perltidyrc file can be switched off with
4032 the -npro option.
4033 • The commands --dump-options, --dump-defaults,
4035 --dump-long-names, and --dump-short-names, all described below,
4036 may all be helpful.
4037 Creating a new abbreviation
4039 A special notation is available for use in a .perltidyrc file for
4040 creating an abbreviation for a group of options. This can be used
4041 to create a shorthand for one or more styles which are frequently,
4042 but not always, used. The notation is to group the options within
4043 curly braces which are preceded by the name of the alias (without
4044 leading dashes), like this:
4045 newword {
4047 -opt1
4048 -opt2
4049 }
4050 where newword is the abbreviation, and opt1, etc, are existing
4052 parameters or other abbreviations. The main syntax requirement is
4053 that the new abbreviation along with its opening curly brace must
4054 begin on a new line. Space before and after the curly braces is
4055 optional.
4056 For a specific example, the following line
4058 oneliner { --maximum-line-length=0 --noadd-newlines --noadd-terminal-newline}
4060 or equivalently with abbreviations
4062 oneliner { -l=0 -nanl -natnl }
4064 could be placed in a .perltidyrc file to temporarily override the
4066 maximum line length with a large value, to temporarily prevent new
4067 line breaks from being added, and to prevent an extra newline
4068 character from being added the file. All other settings in the
4069 .perltidyrc file still apply. Thus it provides a way to format a
4070 long 'one liner' when perltidy is invoked with
4071 perltidy --oneliner ...
4073 (Either "-oneliner" or "--oneliner" may be used).
4075 Skipping leading non-perl commands with -x or --look-for-hash-bang
4077 If your script has leading lines of system commands or other text
4078 which are not valid perl code, and which are separated from the
4079 start of the perl code by a "hash-bang" line, ( a line of the form
4080 "#!...perl" ), you must use the -x flag to tell perltidy not to
4081 parse and format any lines before the "hash-bang" line. This
4082 option also invokes perl with a -x flag when checking the syntax.
4083 This option was originally added to allow perltidy to parse
4084 interactive VMS scripts, but it should be used for any script which
4085 is normally invoked with "perl -x".
4086 Please note: do not use this flag unless you are sure your script
4088 needs it. Parsing errors can occur if it does not have a hash-
4089 bang, or, for example, if the actual first hash-bang is in a here-
4090 doc. In that case a parsing error will occur because the
4091 tokenization will begin in the middle of the here-doc.
4092 Making a file unreadable
4094 The goal of perltidy is to improve the readability of files, but
4095 there are two commands which have the opposite effect, --mangle and
4096 --extrude. They are actually merely aliases for combinations of
4097 other parameters. Both of these strip all possible whitespace, but
4098 leave comments and pod documents, so that they are essentially
4099 reversible. The difference between these is that --mangle puts the
4100 fewest possible line breaks in a script while --extrude puts the
4101 maximum possible. Note that these options do not provided any
4102 meaningful obfuscation, because perltidy can be used to reformat
4103 the files. They were originally developed to help test the
4104 tokenization logic of perltidy, but they have other uses. One use
4105 for --mangle is the following:
4106 perltidy --mangle myfile.pl -st | perltidy -o myfile.pl.new
4108 This will form the maximum possible number of one-line blocks (see
4110 next section), and can sometimes help clean up a badly formatted
4111 script.
4112 A similar technique can be used with --extrude instead of --mangle
4114 to make the minimum number of one-line blocks.
4115 Another use for --mangle is to combine it with -dac to reduce the
4117 file size of a perl script.
4118 Debugging
4120 The following flags are available for debugging:
4121 --dump-cuddled-block-list or -dcbl will dump to standard output the
4123 internal hash of cuddled block types created by a
4124 -cuddled-block-list input string.
4125 --dump-defaults or -ddf will write the default option set to
4127 standard output and quit
4128 --dump-profile or -dpro will write the name of the current
4130 configuration file and its contents to standard output and quit.
4131 --dump-options or -dop will write current option set to standard
4133 output and quit.
4134 --dump-long-names or -dln will write all command line long names
4136 (passed to Get_options) to standard output and quit.
4137 --dump-short-names or -dsn will write all command line short names
4139 to standard output and quit.
4140 --dump-token-types or -dtt will write a list of all token types to
4142 standard output and quit.
4143 --dump-want-left-space or -dwls will write the hash
4145 %want_left_space to standard output and quit. See the section on
4146 controlling whitespace around tokens.
4147 --dump-want-right-space or -dwrs will write the hash
4149 %want_right_space to standard output and quit. See the section on
4150 controlling whitespace around tokens.
4151 --no-memoize or -nmem will turn of memoizing. Memoization can
4153 reduce run time when running perltidy repeatedly in a single
4154 process. It is on by default but can be deactivated for testing
4155 with -nmem.
4156 --no-timestamp or -nts will eliminate any time stamps in output
4158 files to prevent differences in dates from causing test
4159 installation scripts to fail. There are just a couple of places
4160 where timestamps normally occur. One is in the headers of html
4161 files, and another is when the -cscw option is selected. The
4162 default is to allow timestamps (--timestamp or -ts).
4163 --file-size-order or -fso will cause files to be processed in order
4165 of increasing size, when multiple files are being processed. This
4166 is useful during program development, when large numbers of files
4167 with varying sizes are processed, because it can reduce virtual
4168 memory usage.
4169 --maximum-file-size-mb=n or -maxfs=n specifies the maximum file
4171 size in megabytes that perltidy will attempt to format. This
4172 parameter is provided to avoid causing system problems by
4173 accidentally attempting to format an extremely large data file.
4174 Most perl scripts are less than about 2 MB in size. The integer n
4175 has a default value of 10, so perltidy will skip formatting files
4176 which have a size greater than 10 MB. The command to increase the
4177 limit to 20 MB for example would be
4178 perltidy -maxfs=20
4180 This only applies to files specified by filename on the command
4182 line.
4183 --maximum-level-errors=n or -maxle=n specifies the maximum number
4185 of indentation level errors are allowed before perltidy skips
4186 formatting and just outputs a file verbatim. The default is n=1.
4187 This means that if the final indentation of a script differs from
4188 the starting indentation by more than 1 levels, the file will be
4189 output verbatim. To avoid formatting if there are any indentation
4190 level errors use -maxle=0. To skip this check you can either set n
4191 equal to a large number, such as n=100, or set n=-1.
4192 For example, the following script has level error of 3 and will be
4194 output verbatim
4195 Input and default output:
4197 {{{
4198 perltidy -maxle=100
4201 {
4202 {
4203 {
4204 --maximum-unexpected-errors=n or -maxue=n specifies the maximum
4206 number of unexpected tokenization errors are allowed before
4207 formatting is skipped and a script is output verbatim. The
4208 intention is to avoid accidentally formatting a non-perl script,
4209 such as an html file for example. This check can be turned off by
4210 setting n=0.
4211 A recommended value is n=3. However, the default is n=0 (skip this
4213 check) to avoid causing problems with scripts which have extended
4214 syntaxes.
4215 -DEBUG will write a file with extension .DEBUG for each input file
4217 showing the tokenization of all lines of code.
4218 Working with MakeMaker, AutoLoader and SelfLoader
4220 The first $VERSION line of a file which might be eval'd by
4221 MakeMaker is passed through unchanged except for indentation. Use
4222 --nopass-version-line, or -npvl, to deactivate this feature.
4223 If the AutoLoader module is used, perltidy will continue formatting
4225 code after seeing an __END__ line. Use --nolook-for-autoloader, or
4226 -nlal, to deactivate this feature.
4227 Likewise, if the SelfLoader module is used, perltidy will continue
4229 formatting code after seeing a __DATA__ line. Use
4230 --nolook-for-selfloader, or -nlsl, to deactivate this feature.
4231 Working around problems with older version of Perl
4233 Perltidy contains a number of rules which help avoid known
4234 subtleties and problems with older versions of perl, and these
4235 rules always take priority over whatever formatting flags have been
4236 set. For example, perltidy will usually avoid starting a new line
4237 with a bareword, because this might cause problems if "use strict"
4238 is active.
4239 There is no way to override these rules.
4241
4243 The -html master switch
4244 The flag -html causes perltidy to write an html file with extension
4245 .html. So, for example, the following command
4246 perltidy -html somefile.pl
4248 will produce a syntax-colored html file named somefile.pl.html
4250 which may be viewed with a browser.
4251 Please Note: In this case, perltidy does not do any formatting to
4253 the input file, and it does not write a formatted file with
4254 extension .tdy. This means that two perltidy runs are required to
4255 create a fully reformatted, html copy of a script.
4256 The -pre flag for code snippets
4258 When the -pre flag is given, only the pre-formatted section, within
4259 the <PRE> and </PRE> tags, will be output. This simplifies
4260 inclusion of the output in other files. The default is to output a
4261 complete web page.
4262 The -nnn flag for line numbering
4264 When the -nnn flag is given, the output lines will be numbered.
4265 The -toc, or --html-table-of-contents flag
4267 By default, a table of contents to packages and subroutines will be
4268 written at the start of html output. Use -ntoc to prevent this.
4269 This might be useful, for example, for a pod document which
4270 contains a number of unrelated code snippets. This flag only
4271 influences the code table of contents; it has no effect on any
4272 table of contents produced by pod2html (see next item).
4273 The -pod, or --pod2html flag
4275 There are two options for formatting pod documentation. The
4276 default is to pass the pod through the Pod::Html module (which
4277 forms the basis of the pod2html utility). Any code sections are
4278 formatted by perltidy, and the results then merged. Note: perltidy
4279 creates a temporary file when Pod::Html is used; see "FILES".
4280 Also, Pod::Html creates temporary files for its cache.
4281 NOTE: Perltidy counts the number of "=cut" lines, and either moves
4283 the pod text to the top of the html file if there is one "=cut", or
4284 leaves the pod text in its original order (interleaved with code)
4285 otherwise.
4286 Most of the flags accepted by pod2html may be included in the
4288 perltidy command line, and they will be passed to pod2html. In
4289 some cases, the flags have a prefix "pod" to emphasize that they
4290 are for the pod2html, and this prefix will be removed before they
4291 are passed to pod2html. The flags which have the additional "pod"
4292 prefix are:
4293 --[no]podheader --[no]podindex --[no]podrecurse --[no]podquiet
4295 --[no]podverbose --podflush
4296 The flags which are unchanged from their use in pod2html are:
4298 --backlink=s --cachedir=s --htmlroot=s --libpods=s --title=s
4300 --podpath=s --podroot=s
4301 where 's' is an appropriate character string. Not all of these
4303 flags are available in older versions of Pod::Html. See your
4304 Pod::Html documentation for more information.
4305 The alternative, indicated with -npod, is not to use Pod::Html, but
4307 rather to format pod text in italics (or whatever the stylesheet
4308 indicates), without special html markup. This is useful, for
4309 example, if pod is being used as an alternative way to write
4310 comments.
4311 The -frm, or --frames flag
4313 By default, a single html output file is produced. This can be
4314 changed with the -frm option, which creates a frame holding a table
4315 of contents in the left panel and the source code in the right
4316 side. This simplifies code browsing. Assume, for example, that the
4317 input file is MyModule.pm. Then, for default file extension
4318 choices, these three files will be created:
4319 MyModule.pm.html - the frame
4321 MyModule.pm.toc.html - the table of contents
4322 MyModule.pm.src.html - the formatted source code
4323 Obviously this file naming scheme requires that output be directed
4325 to a real file (as opposed to, say, standard output). If this is
4326 not the case, or if the file extension is unknown, the -frm option
4327 will be ignored.
4328 The -text=s, or --html-toc-extension flag
4330 Use this flag to specify the extra file extension of the table of
4331 contents file when html frames are used. The default is "toc".
4332 See "Specifying File Extensions".
4333 The -sext=s, or --html-src-extension flag
4335 Use this flag to specify the extra file extension of the content
4336 file when html frames are used. The default is "src". See
4337 "Specifying File Extensions".
4338 The -hent, or --html-entities flag
4340 This flag controls the use of Html::Entities for html formatting.
4341 By default, the module Html::Entities is used to encode special
4342 symbols. This may not be the right thing for some browser/language
4343 combinations. Use --nohtml-entities or -nhent to prevent this.
4344 Style Sheets
4346 Style sheets make it very convenient to control and adjust the
4347 appearance of html pages. The default behavior is to write a page
4348 of html with an embedded style sheet.
4349 An alternative to an embedded style sheet is to create a page with
4351 a link to an external style sheet. This is indicated with the
4352 -css=filename, where the external style sheet is filename. The
4353 external style sheet filename will be created if and only if it
4354 does not exist. This option is useful for controlling multiple
4355 pages from a single style sheet.
4356 To cause perltidy to write a style sheet to standard output and
4358 exit, use the -ss, or --stylesheet, flag. This is useful if the
4359 style sheet could not be written for some reason, such as if the
4360 -pre flag was used. Thus, for example,
4361 perltidy -html -ss >mystyle.css
4363 will write a style sheet with the default properties to file
4365 mystyle.css.
4366 The use of style sheets is encouraged, but a web page without a
4368 style sheets can be created with the flag -nss. Use this option if
4369 you must to be sure that older browsers (roughly speaking, versions
4370 prior to 4.0 of Netscape Navigator and Internet Explorer) can
4371 display the syntax-coloring of the html files.
4372 Controlling HTML properties
4374 Note: It is usually more convenient to accept the default
4375 properties and then edit the stylesheet which is produced.
4376 However, this section shows how to control the properties with
4377 flags to perltidy.
4378 Syntax colors may be changed from their default values by flags of
4380 the either the long form, -html-color-xxxxxx=n, or more
4381 conveniently the short form, -hcx=n, where xxxxxx is one of the
4382 following words, and x is the corresponding abbreviation:
4383 Token Type xxxxxx x
4385 ---------- -------- --
4386 comment comment c
4387 number numeric n
4388 identifier identifier i
4389 bareword, function bareword w
4390 keyword keyword k
4391 quite, pattern quote q
4392 here doc text here-doc-text h
4393 here doc target here-doc-target hh
4394 punctuation punctuation pu
4395 parentheses paren p
4396 structural braces structure s
4397 semicolon semicolon sc
4398 colon colon co
4399 comma comma cm
4400 label label j
4401 sub definition name subroutine m
4402 pod text pod-text pd
4403 A default set of colors has been defined, but they may be changed
4405 by providing values to any of the following parameters, where n is
4406 either a 6 digit hex RGB color value or an ascii name for a color,
4407 such as 'red'.
4408 To illustrate, the following command will produce an html file
4410 somefile.pl.html with "aqua" keywords:
4411 perltidy -html -hck=00ffff somefile.pl
4413 and this should be equivalent for most browsers:
4415 perltidy -html -hck=aqua somefile.pl
4417 Perltidy merely writes any non-hex names that it sees in the html
4419 file. The following 16 color names are defined in the HTML 3.2
4420 standard:
4421 black => 000000,
4423 silver => c0c0c0,
4424 gray => 808080,
4425 white => ffffff,
4426 maroon => 800000,
4427 red => ff0000,
4428 purple => 800080,
4429 fuchsia => ff00ff,
4430 green => 008000,
4431 lime => 00ff00,
4432 olive => 808000,
4433 yellow => ffff00
4434 navy => 000080,
4435 blue => 0000ff,
4436 teal => 008080,
4437 aqua => 00ffff,
4438 Many more names are supported in specific browsers, but it is
4440 safest to use the hex codes for other colors. Helpful color tables
4441 can be located with an internet search for "HTML color tables".
4442 Besides color, two other character attributes may be set: bold, and
4444 italics. To set a token type to use bold, use the flag
4445 --html-bold-xxxxxx or -hbx, where xxxxxx or x are the long or short
4446 names from the above table. Conversely, to set a token type to NOT
4447 use bold, use --nohtml-bold-xxxxxx or -nhbx.
4448 Likewise, to set a token type to use an italic font, use the flag
4450 --html-italic-xxxxxx or -hix, where again xxxxxx or x are the long
4451 or short names from the above table. And to set a token type to
4452 NOT use italics, use --nohtml-italic-xxxxxx or -nhix.
4453 For example, to use bold braces and lime color, non-bold, italics
4455 keywords the following command would be used:
4456 perltidy -html -hbs -hck=00FF00 -nhbk -hik somefile.pl
4458 The background color can be specified with
4460 --html-color-background=n, or -hcbg=n for short, where n is a 6
4461 character hex RGB value. The default color of text is the value
4462 given to punctuation, which is black as a default.
4463 Here are some notes and hints:
4465 1. If you find a preferred set of these parameters, you may want to
4467 create a .perltidyrc file containing them. See the perltidy man
4468 page for an explanation.
4469 2. Rather than specifying values for these parameters, it is
4471 probably easier to accept the defaults and then edit a style sheet.
4472 The style sheet contains comments which should make this easy.
4473 3. The syntax-colored html files can be very large, so it may be
4475 best to split large files into smaller pieces to improve download
4476 times.
4477
4479 Specifying Block Types
4480 Several parameters which refer to code block types may be customized by
4481 also specifying an associated list of block types. The type of a block
4482 is the name of the keyword which introduces that block, such as if,
4483 else, or sub. An exception is a labeled block, which has no keyword,
4484 and should be specified with just a colon. To specify all blocks use
4485 '*'.
4486 The keyword sub indicates a named sub. For anonymous subs, use the
4488 special keyword asub.
4489 For example, the following parameter specifies "sub", labels, "BEGIN",
4491 and "END" blocks:
4492 -cscl="sub : BEGIN END"
4494 (the meaning of the -cscl parameter is described above.) Note that
4496 quotes are required around the list of block types because of the
4497 spaces. For another example, the following list specifies all block
4498 types for vertical tightness:
4499 -bbvtl='*'
4501 Specifying File Extensions
4503 Several parameters allow default file extensions to be overridden. For
4504 example, a backup file extension may be specified with -bext=ext, where
4505 ext is some new extension. In order to provides the user some
4506 flexibility, the following convention is used in all cases to decide if
4507 a leading '.' should be used. If the extension "ext" begins with
4508 "A-Z", "a-z", or "0-9", then it will be appended to the filename with
4509 an intermediate '.' (or perhaps a '_' on VMS systems). Otherwise, it
4510 will be appended directly.
4511 For example, suppose the file is somefile.pl. For "-bext=old", a '.'
4513 is added to give somefile.pl.old. For "-bext=.old", no additional '.'
4514 is added, so again the backup file is somefile.pl.old. For "-bext=~",
4515 then no dot is added, and the backup file will be somefile.pl~ .
4516
4518 The following list shows all short parameter names which allow a prefix
4519 'n' to produce the negated form:
4520 D anl asbl asc ast asu atnl aws b baa
4522 baao bar bbao bbb bbc bbs bl bli boa boc
4523 bok bol bom bos bot cblx ce conv cs csc
4524 cscb cscw dac dbc dcbl dcsc ddf dln dnl dop
4525 dp dpro dsc dsm dsn dtt dwls dwrs dws f
4526 fll fpva frm fs fso gcs hbc hbcm hbco hbh
4527 hbhh hbi hbj hbk hbm hbn hbp hbpd hbpu hbq
4528 hbs hbsc hbv hbw hent hic hicm hico hih hihh
4529 hii hij hik him hin hip hipd hipu hiq his
4530 hisc hiv hiw hsc html ibc icb icp iob isbc
4531 iscl kgb kgbd kgbi kis lal log lop lp lsl
4532 mem nib ohbr okw ola olc oll olq opr opt
4533 osbc osbr otr ple pod pvl q sac sbc sbl
4534 scbb schb scp scsb sct se sfp sfs skp sob
4535 sobb sohb sop sosb sot ssc st sts t tac
4536 tbc toc tp tqw trp ts tsc tso vmll w
4537 wn x xci xs
4538 Equivalently, the prefix 'no' or 'no-' on the corresponding long names
4540 may be used.
4541
4543 Parsing Limitations
4544 Perltidy should work properly on most perl scripts. It does a lot
4545 of self-checking, but still, it is possible that an error could be
4546 introduced and go undetected. Therefore, it is essential to make
4547 careful backups and to test reformatted scripts.
4548 The main current limitation is that perltidy does not scan modules
4550 included with 'use' statements. This makes it necessary to guess
4551 the context of any bare words introduced by such modules. Perltidy
4552 has good guessing algorithms, but they are not infallible. When it
4553 must guess, it leaves a message in the log file.
4554 If you encounter a bug, please report it.
4556 What perltidy does not parse and format
4558 Perltidy indents but does not reformat comments and "qw" quotes.
4559 Perltidy does not in any way modify the contents of here documents
4560 or quoted text, even if they contain source code. (You could,
4561 however, reformat them separately). Perltidy does not format
4562 'format' sections in any way. And, of course, it does not modify
4563 pod documents.
4564
4566 Temporary files
4567 Under the -html option with the default --pod2html flag, a
4568 temporary file is required to pass text to Pod::Html. Unix systems
4569 will try to use the POSIX tmpnam() function. Otherwise the file
4570 perltidy.TMP will be temporarily created in the current working
4571 directory.
4572 Special files when standard input is used
4574 When standard input is used, the log file, if saved, is
4575 perltidy.LOG, and any errors are written to perltidy.ERR unless the
4576 -se flag is set. These are saved in the current working directory.
4577 Files overwritten
4579 The following file extensions are used by perltidy, and files with
4580 these extensions may be overwritten or deleted: .ERR, .LOG, .TEE,
4581 and/or .tdy, .html, and .bak, depending on the run type and
4582 settings.
4583 Files extensions limitations
4585 Perltidy does not operate on files for which the run could produce
4586 a file with a duplicated file extension. These extensions include
4587 .LOG, .ERR, .TEE, and perhaps .tdy and .bak, depending on the run
4588 type. The purpose of this rule is to prevent generating confusing
4589 filenames such as somefile.tdy.tdy.tdy.
4590
4592 An exit value of 0, 1, or 2 is returned by perltidy to indicate the
4593 status of the result.
4594 A exit value of 0 indicates that perltidy ran to completion with no
4596 error messages.
4597 A non-zero exit value indicates some kind of problem was detected.
4599 An exit value of 1 indicates that perltidy terminated prematurely,
4601 usually due to some kind of errors in the input parameters. This can
4602 happen for example if a parameter is misspelled or given an invalid
4603 value. Error messages in the standard error output will indicate the
4604 cause of any problem. If perltidy terminates prematurely then no
4605 output files will be produced.
4606 An exit value of 2 indicates that perltidy was able to run to
4608 completion but there there are (1) warning messages in the standard
4609 error output related to parameter errors or problems and/or (2) warning
4610 messages in the perltidy error file(s) relating to possible syntax
4611 errors in one or more of the source script(s) being tidied. When
4612 multiple files are being processed, an error detected in any single
4613 file will produce this type of exit condition.
4614
4616 perlstyle(1), Perl::Tidy(3)
4617
4619 The perltidy binary uses the Perl::Tidy module and is installed when
4620 that module is installed. The module name is case-sensitive. For
4621 example, the basic command for installing with cpanm is 'cpanm
4622 Perl::Tidy'.
4623
4625 This man page documents perltidy version 20210717
4626
4628 A list of current bugs and issues can be found at the CPAN site
4629 <https://rt.cpan.org/Public/Dist/Display.html?Name=Perl-Tidy>
4630 To report a new bug or problem, use the link on this page.
4632 The source code repository is at
4634 <https://github.com/perltidy/perltidy>.
4635
4637 Copyright (c) 2000-2021 by Steve Hancock
4638
4640 This package is free software; you can redistribute it and/or modify it
4641 under the terms of the "GNU General Public License".
4642 Please refer to the file "COPYING" for details.
4644
4646 This package is distributed in the hope that it will be useful, but
4647 WITHOUT ANY WARRANTY; without even the implied warranty of
4648 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
4649 See the "GNU General Public License" for more details.
4651perl v5.34.0 2021-07-23 PERLTIDY(1)