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. The formatting process involves converting the script into a
18 string of tokens, removing any non-essential whitespace, and then
19 rewriting the string of tokens with whitespace using whatever rules are
20 specified, or defaults. This happens in a series of operations which
21 can be controlled with the parameters described in this document.
22 Perltidy is a commandline frontend to the module Perl::Tidy. For
24 documentation describing how to call the Perl::Tidy module from other
25 applications see the separate documentation for Perl::Tidy. It is the
26 file Perl::Tidy.pod in the source distribution.
27 Many users will find enough information in "EXAMPLES" to get started.
29 New users may benefit from the short tutorial which can be found at
30 http://perltidy.sourceforge.net/tutorial.html
31 A convenient aid to systematically defining a set of style parameters
33 can be found at http://perltidy.sourceforge.net/stylekey.html
34 Perltidy can produce output on either of two modes, depending on the
36 existence of an -html flag. Without this flag, the output is passed
37 through a formatter. The default formatting tries to follow the
38 recommendations in perlstyle(1), but it can be controlled in detail
39 with numerous input parameters, which are described in "FORMATTING
40 OPTIONS".
41 When the -html flag is given, the output is passed through an HTML
43 formatter which is described in "HTML OPTIONS".
44
46 perltidy somefile.pl
47 This will produce a file somefile.pl.tdy containing the script
49 reformatted using the default options, which approximate the style
50 suggested in perlstyle(1). The source file somefile.pl is unchanged.
51 perltidy *.pl
53 Execute perltidy on all .pl files in the current directory with the
55 default options. The output will be in files with an appended .tdy
56 extension. For any file with an error, there will be a file with
57 extension .ERR.
58 perltidy -b file1.pl file2.pl
60 Modify file1.pl and file2.pl in place, and backup the originals to
62 file1.pl.bak and file2.pl.bak. If file1.pl.bak and/or file2.pl.bak
63 already exist, they will be overwritten.
64 perltidy -b -bext='/' file1.pl file2.pl
66 Same as the previous example except that the backup files file1.pl.bak
68 and file2.pl.bak will be deleted if there are no errors.
69 perltidy -gnu somefile.pl
71 Execute perltidy on file somefile.pl with a style which approximates
73 the GNU Coding Standards for C programs. The output will be
74 somefile.pl.tdy.
75 perltidy -i=3 somefile.pl
77 Execute perltidy on file somefile.pl, with 3 columns for each level of
79 indentation (-i=3) instead of the default 4 columns. There will not be
80 any tabs in the reformatted script, except for any which already exist
81 in comments, pod documents, quotes, and here documents. Output will be
82 somefile.pl.tdy.
83 perltidy -i=3 -et=8 somefile.pl
85 Same as the previous example, except that leading whitespace will be
87 entabbed with one tab character per 8 spaces.
88 perltidy -ce -l=72 somefile.pl
90 Execute perltidy on file somefile.pl with all defaults except use
92 "cuddled elses" (-ce) and a maximum line length of 72 columns (-l=72)
93 instead of the default 80 columns.
94 perltidy -g somefile.pl
96 Execute perltidy on file somefile.pl and save a log file
98 somefile.pl.LOG which shows the nesting of braces, parentheses, and
99 square brackets at the start of every line.
100 perltidy -html somefile.pl
102 This will produce a file somefile.pl.html containing the script with
104 html markup. The output file will contain an embedded style sheet in
105 the <HEAD> section which may be edited to change the appearance.
106 perltidy -html -css=mystyle.css somefile.pl
108 This will produce a file somefile.pl.html containing the script with
110 html markup. This output file will contain a link to a separate style
111 sheet file mystyle.css. If the file mystyle.css does not exist, it
112 will be created. If it exists, it will not be overwritten.
113 perltidy -html -pre somefile.pl
115 Write an html snippet with only the PRE section to somefile.pl.html.
117 This is useful when code snippets are being formatted for inclusion in
118 a larger web page. No style sheet will be written in this case.
119 perltidy -html -ss >mystyle.css
121 Write a style sheet to mystyle.css and exit.
123 perltidy -html -frm mymodule.pm
125 Write html with a frame holding a table of contents and the source
127 code. The output files will be mymodule.pm.html (the frame),
128 mymodule.pm.toc.html (the table of contents), and mymodule.pm.src.html
129 (the source code).
130
132 The entire command line is scanned for options, and they are processed
133 before any files are processed. As a result, it does not matter
134 whether flags are before or after any filenames. However, the relative
135 order of parameters is important, with later parameters overriding the
136 values of earlier parameters.
137 For each parameter, there is a long name and a short name. The short
139 names are convenient for keyboard input, while the long names are self-
140 documenting and therefore useful in scripts. It is customary to use
141 two leading dashes for long names, but one may be used.
142 Most parameters which serve as on/off flags can be negated with a
144 leading "n" (for the short name) or a leading "no" or "no-" (for the
145 long name). For example, the flag to outdent long quotes is -olq or
146 --outdent-long-quotes. The flag to skip this is -nolq or
147 --nooutdent-long-quotes or --no-outdent-long-quotes.
148 Options may not be bundled together. In other words, options -q and -g
150 may NOT be entered as -qg.
151 Option names may be terminated early as long as they are uniquely
153 identified. For example, instead of --dump-token-types, it would be
154 sufficient to enter --dump-tok, or even --dump-t, to uniquely identify
155 this command.
156 I/O Control
158 The following parameters concern the files which are read and written.
159 -h, --help
161 Show summary of usage and exit.
162 -o=filename, --outfile=filename
164 Name of the output file (only if a single input file is being
165 processed). If no output file is specified, and output is not
166 redirected to the standard output (see -st), the output will go to
167 filename.tdy. [Note: - does not redirect to standard output. Use
168 -st instead.]
169 -st, --standard-output
171 Perltidy must be able to operate on an arbitrarily large number of
172 files in a single run, with each output being directed to a
173 different output file. Obviously this would conflict with
174 outputting to the single standard output device, so a special flag,
175 -st, is required to request outputting to the standard output. For
176 example,
177 perltidy somefile.pl -st >somefile.new.pl
179 This option may only be used if there is just a single input file.
181 The default is -nst or --nostandard-output.
182 -se, --standard-error-output
184 If perltidy detects an error when processing file somefile.pl, its
185 default behavior is to write error messages to file
186 somefile.pl.ERR. Use -se to cause all error messages to be sent to
187 the standard error output stream instead. This directive may be
188 negated with -nse. Thus, you may place -se in a .perltidyrc and
189 override it when desired with -nse on the command line.
190 -oext=ext, --output-file-extension=ext
192 Change the extension of the output file to be ext instead of the
193 default tdy (or html in case the --html option is used). See
194 "Specifying File Extensions".
195 -opath=path, --output-path=path
197 When perltidy creates a filename for an output file, by default it
198 merely appends an extension to the path and basename of the input
199 file. This parameter causes the path to be changed to path
200 instead.
201 The path should end in a valid path separator character, but
203 perltidy will try to add one if it is missing.
204 For example
206 perltidy somefile.pl -opath=/tmp/
208 will produce /tmp/somefile.pl.tdy. Otherwise, somefile.pl.tdy will
210 appear in whatever directory contains somefile.pl.
211 If the path contains spaces, it should be placed in quotes.
213 This parameter will be ignored if output is being directed to
215 standard output, or if it is being specified explicitly with the
216 -o=s parameter.
217 -b, --backup-and-modify-in-place
219 Modify the input file or files in-place and save the original with
220 the extension .bak. Any existing .bak file will be deleted. See
221 next item for changing the default backup extension, and for
222 eliminating the backup file altogether.
223 Please Note: Writing back to the input file increases the risk of
225 data loss or corruption in the event of a software or hardware
226 malfunction. Before using the -b parameter please be sure to have
227 backups and verify that it works correctly in your environment and
228 operating system.
229 A -b flag will be ignored if input is from standard input or goes
231 to standard output, or if the -html flag is set.
232 In particular, if you want to use both the -b flag and the -pbp
234 (--perl-best-practices) flag, then you must put a -nst flag after
235 the -pbp flag because it contains a -st flag as one of its
236 components, which means that output will go to the standard output
237 stream.
238 -bext=ext, --backup-file-extension=ext
240 This parameter serves two purposes: (1) to change the extension of
241 the backup file to be something other than the default .bak, and
242 (2) to indicate that no backup file should be saved.
243 To change the default extension to something other than .bak see
245 "Specifying File Extensions".
246 A backup file of the source is always written, but you can request
248 that it be deleted at the end of processing if there were no
249 errors. This is risky unless the source code is being maintained
250 with a source code control system.
251 To indicate that the backup should be deleted include one forward
253 slash, /, in the extension. If any text remains after the slash is
254 removed it will be used to define the backup file extension (which
255 is always created and only deleted if there were no errors).
256 Here are some examples:
258 Parameter Extension Backup File Treatment
260 <-bext=bak> F<.bak> Keep (same as the default behavior)
261 <-bext='/'> F<.bak> Delete if no errors
262 <-bext='/backup'> F<.backup> Delete if no errors
263 <-bext='original/'> F<.original> Delete if no errors
264 -bm=s, --backup-method=s
266 This parameter should not normally be used but is available in the
267 event that problems arise as a transition is made from an older
268 implementation of the backup logic to a newer implementation. The
269 newer implementation is the default and is specified with
270 -bm='copy'. The older implementation is specified with -bm='move'.
271 The difference is that the older implementation made the backup by
272 moving the input file to the backup file, and the newer
273 implementation makes the backup by copying the input file. The
274 newer implementation preserves the file system inode value. This
275 may avoid problems with other software running simultaneously.
276 This change was made as part of issue git #103 at github.
277 -w, --warning-output
279 Setting -w causes any non-critical warning messages to be reported
280 as errors. These include messages about possible pod problems,
281 possibly bad starting indentation level, and cautions about
282 indirect object usage. The default, -nw or --nowarning-output, is
283 not to include these warnings.
284 -q, --quiet
286 Deactivate error messages (for running under an editor).
287 For example, if you use a vi-style editor, such as vim, you may
289 execute perltidy as a filter from within the editor using something
290 like
291 :n1,n2!perltidy -q
293 where "n1,n2" represents the selected text. Without the -q flag,
295 any error message may mess up your screen, so be prepared to use
296 your "undo" key.
297 -log, --logfile
299 Save the .LOG file, which has many useful diagnostics. Perltidy
300 always creates a .LOG file, but by default it is deleted unless a
301 program bug is suspected. Setting the -log flag forces the log
302 file to be saved.
303 -g=n, --logfile-gap=n
305 Set maximum interval between input code lines in the logfile. This
306 purpose of this flag is to assist in debugging nesting errors. The
307 value of "n" is optional. If you set the flag -g without the value
308 of "n", it will be taken to be 1, meaning that every line will be
309 written to the log file. This can be helpful if you are looking
310 for a brace, paren, or bracket nesting error.
311 Setting -g also causes the logfile to be saved, so it is not
313 necessary to also include -log.
314 If no -g flag is given, a value of 50 will be used, meaning that at
316 least every 50th line will be recorded in the logfile. This helps
317 prevent excessively long log files.
318 Setting a negative value of "n" is the same as not setting -g at
320 all.
321 -npro --noprofile
323 Ignore any .perltidyrc command file. Normally, perltidy looks
324 first in your current directory for a .perltidyrc file of
325 parameters. (The format is described below). If it finds one, it
326 applies those options to the initial default values, and then it
327 applies any that have been defined on the command line. If no
328 .perltidyrc file is found, it looks for one in your home directory.
329 If you set the -npro flag, perltidy will not look for this file.
331 -pro=filename or --profile=filename
333 To simplify testing and switching .perltidyrc files, this command
334 may be used to specify a configuration file which will override the
335 default name of .perltidyrc. There must not be a space on either
336 side of the '=' sign. For example, the line
337 perltidy -pro=testcfg
339 would cause file testcfg to be used instead of the default
341 .perltidyrc.
342 A pathname begins with three dots, e.g. ".../.perltidyrc",
344 indicates that the file should be searched for starting in the
345 current directory and working upwards. This makes it easier to have
346 multiple projects each with their own .perltidyrc in their root
347 directories.
348 -opt, --show-options
350 Write a list of all options used to the .LOG file. Please see
351 --dump-options for a simpler way to do this.
352 -f, --force-read-binary
354 Force perltidy to process binary files. To avoid producing
355 excessive error messages, perltidy skips files identified by the
356 system as non-text. However, valid perl scripts containing binary
357 data may sometimes be identified as non-text, and this flag forces
358 perltidy to process them.
359 -ast, --assert-tidy
361 This flag asserts that the input and output code streams are
362 identical, or in other words that the input code is already 'tidy'
363 according to the formatting parameters. If this is not the case,
364 an error message noting this is produced. This error message will
365 cause the process to return a non-zero exit code. The test for
366 this is made by comparing an MD5 hash value for the input and
367 output code streams. This flag has no other effect on the
368 functioning of perltidy. This might be useful for certain code
369 maintenance operations. Note: you will not see this message if you
370 have error messages turned off with the -quiet flag.
371 -asu, --assert-untidy
373 This flag asserts that the input and output code streams are
374 different, or in other words that the input code is 'untidy'
375 according to the formatting parameters. If this is not the case,
376 an error message noting this is produced. This flag has no other
377 effect on the functioning of perltidy.
378
380 Basic Options
381 --notidy
382 This flag disables all formatting and causes the input to be copied
383 unchanged to the output except for possible changes in line ending
384 characters and any pre- and post-filters. This can be useful in
385 conjunction with a hierarchical set of .perltidyrc files to avoid
386 unwanted code tidying. See also "Skipping Selected Sections of
387 Code" for a way to avoid tidying specific sections of code.
388 -i=n, --indent-columns=n
390 Use n columns per indentation level (default n=4).
391 -l=n, --maximum-line-length=n
393 The default maximum line length is n=80 characters. Perltidy will
394 try to find line break points to keep lines below this length.
395 However, long quotes and side comments may cause lines to exceed
396 this length.
397 The default length of 80 comes from the past when this was the
399 standard CRT screen width. Many programmers prefer to increase
400 this to something like 120.
401 Setting -l=0 is equivalent to setting -l=(a very large number).
403 But this is not recommended because, for example, a very long list
404 will be formatted in a single long line.
405 -vmll, --variable-maximum-line-length
407 A problem arises using a fixed maximum line length with very deeply
408 nested code and data structures because eventually the amount of
409 leading whitespace used for indicating indentation takes up most or
410 all of the available line width, leaving little or no space for the
411 actual code or data. One solution is to use a very long line
412 length. Another solution is to use the -vmll flag, which basically
413 tells perltidy to ignore leading whitespace when measuring the line
414 length.
415 To be precise, when the -vmll parameter is set, the maximum line
417 length of a line of code will be M+L*I, where
418 M is the value of --maximum-line-length=M (-l=M), default 80,
420 I is the value of --indent-columns=I (-i=I), default 4,
421 L is the indentation level of the line of code
422 When this flag is set, the choice of breakpoints for a block of
424 code should be essentially independent of its nesting depth.
425 However, the absolute line lengths, including leading whitespace,
426 can still be arbitrarily large. This problem can be avoided by
427 including the next parameter.
428 The default is not to do this (-nvmll).
430 -wc=n, --whitespace-cycle=n
432 This flag also addresses problems with very deeply nested code and
433 data structures. When the nesting depth exceeds the value n the
434 leading whitespace will be reduced and start at a depth of 1 again.
435 The result is that blocks of code will shift back to the left
436 rather than moving arbitrarily far to the right. This occurs
437 cyclically to any depth.
438 For example if one level of indentation equals 4 spaces (-i=4, the
440 default), and one uses -wc=15, then if the leading whitespace on a
441 line exceeds about 4*15=60 spaces it will be reduced back to 4*1=4
442 spaces and continue increasing from there. If the whitespace never
443 exceeds this limit the formatting remains unchanged.
444 The combination of -vmll and -wc=n provides a solution to the
446 problem of displaying arbitrarily deep data structures and code in
447 a finite window, although -wc=n may of course be used without
448 -vmll.
449 The default is not to use this, which can also be indicated using
451 -wc=0.
452 Tabs
454 Using tab characters will almost certainly lead to future
455 portability and maintenance problems, so the default and
456 recommendation is not to use them. For those who prefer tabs,
457 however, there are two different options.
458 Except for possibly introducing tab indentation characters, as
460 outlined below, perltidy does not introduce any tab characters into
461 your file, and it removes any tabs from the code (unless requested
462 not to do so with -fws). If you have any tabs in your comments,
463 quotes, or here-documents, they will remain.
464 -et=n, --entab-leading-whitespace
466 This flag causes each n leading space characters produced by
467 the formatting process to be replaced by one tab character.
468 The formatting process itself works with space characters. The
469 -et=n parameter is applied as a last step, after formatting is
470 complete, to convert leading spaces into tabs. Before starting
471 to use tabs, it is essential to first get the indentation
472 controls set as desired without tabs, particularly the two
473 parameters --indent-columns=n (or -i=n) and
474 --continuation-indentation=n (or -ci=n).
475 The value of the integer n can be any value but can be
477 coordinated with the number of spaces used for indentation. For
478 example, -et=4 -ci=4 -i=4 will produce one tab for each
479 indentation level and and one for each continuation indentation
480 level. You may want to coordinate the value of n with what
481 your display software assumes for the spacing of a tab.
482 -t, --tabs
484 This flag causes one leading tab character to be inserted for
485 each level of indentation. Certain other features are
486 incompatible with this option, and if these options are also
487 given, then a warning message will be issued and this flag will
488 be unset. One example is the -lp option. This flag is retained
489 for backwards compatibility, but if you use tabs, the -et=n
490 flag is recommended. If both -t and -et=n are set, the -et=n
491 is used.
492 -dt=n, --default-tabsize=n
494 If the first line of code passed to perltidy contains leading
495 tabs but no tab scheme is specified for the output stream then
496 perltidy must guess how many spaces correspond to each leading
497 tab. This number of spaces n corresponding to each leading tab
498 of the input stream may be specified with -dt=n. The default
499 is n=8.
500 This flag has no effect if a tab scheme is specified for the
502 output stream, because then the input stream is assumed to use
503 the same tab scheme and indentation spaces as for the output
504 stream (any other assumption would lead to unstable editing).
505 -io, --indent-only
507 This flag is used to deactivate all whitespace and line break
508 changes within non-blank lines of code. When it is in effect, the
509 only change to the script will be to the indentation and to the
510 number of blank lines. And any flags controlling whitespace and
511 newlines will be ignored. You might want to use this if you are
512 perfectly happy with your whitespace and line breaks, and merely
513 want perltidy to handle the indentation. (This also speeds up
514 perltidy by well over a factor of two, so it might be useful when
515 perltidy is merely being used to help find a brace error in a large
516 script).
517 Setting this flag is equivalent to setting --freeze-newlines and
519 --freeze-whitespace.
520 If you also want to keep your existing blank lines exactly as they
522 are, you can add --freeze-blank-lines.
523 With this option perltidy is still free to modify the indenting
525 (and outdenting) of code and comments as it normally would. If you
526 also want to prevent long comment lines from being outdented, you
527 can add either -noll or -l=0.
528 Setting this flag will prevent perltidy from doing any special
530 operations on closing side comments. You may still delete all side
531 comments however when this flag is in effect.
532 -enc=s, --character-encoding=s
534 This flag indicates if the input data stream use a character
535 encoding. Perltidy does not look for the encoding directives in
536 the source stream, such as use utf8, and instead relies on this
537 flag to determine the encoding. (Note that perltidy often works on
538 snippets of code rather than complete files so it cannot rely on
539 use utf8 directives).
540 The possible values for s are:
542 -enc=none if no encoding is used, or
544 -enc=utf8 for encoding in utf8
545 -enc=guess if perltidy should guess between these two possibilities.
546 The value none causes the stream to be processed without special
548 encoding assumptions. This is appropriate for files which are
549 written in single-byte character encodings such as latin-1.
550 The value utf8 causes the stream to be read and written as UTF-8.
552 If the input stream cannot be decoded with this encoding then
553 processing is not done.
554 The value guess tells perltidy to guess between either utf8
556 encoding or no encoding (meaning one character per byte). The
557 guess option uses the Encode::Guess module which has been found to
558 be reliable at detecting if a file is encoded in utf8 or not.
559 The current default is guess.
561 The abbreviations -utf8 or -UTF8 are equivalent to -enc=utf8, and
563 the abbreviation -guess is equivalent to -enc=guess. So to process
564 a file named file.pl which is encoded in UTF-8 you can use:
565 perltidy -utf8 file.pl
567 or
569 perltidy -guess file.pl
571 or simply
573 perltidy file.pl
575 since -guess is the default.
577 To process files with an encoding other than UTF-8, it would be
579 necessary to write a short program which calls the Perl::Tidy
580 module with some pre- and post-processing to handle decoding and
581 encoding.
582 -eos=s, --encode-output-strings=s
584 This flag was added to resolve an issue involving the interface
585 between Perl::Tidy and calling programs, and in particular
586 Code::TidyAll (tidyall).
587 If you only run the perltidy binary this flag has no effect. If
589 you run a program which calls the Perl::Tidy module and receives a
590 string in return, then the meaning of the flag is as follows:
591 • The setting -eos means Perl::Tidy should encode any string
593 which it decodes. This is the default because it makes
594 perltidy behave well as a filter, and is the correct setting
595 for most programs.
596 • The setting -neos means that a string should remain decoded if
598 it was decoded by Perl::Tidy. This is only appropriate if the
599 calling program will handle any needed encoding before
600 outputting the string.
601 The default was changed from -neos to -eos in versions after
603 20220217. If this change causes a program to start running
604 incorrectly on encoded files, an emergency fix might be to set
605 -neos. Additional information can be found in the man pages for
606 the Perl::Tidy module and also in
607 <https://github.com/perltidy/perltidy/blob/master/docs/eos_flag.md>.
608 -gcs, --use-unicode-gcstring
610 This flag controls whether or not perltidy may use module
611 Unicode::GCString to obtain accurate display widths of wide
612 characters. The default is --nouse-unicode-gcstring.
613 If this flag is set, and text is encoded, perltidy will look for
615 the module Unicode::GCString and, if found, will use it to obtain
616 character display widths. This can improve displayed vertical
617 alignment for files with wide characters. It is a nice feature but
618 it is off by default to avoid conflicting formatting when there are
619 multiple developers. Perltidy installation does not require
620 Unicode::GCString, so users wanting to use this feature need set
621 this flag and also to install Unicode::GCString separately.
622 If this flag is set and perltidy does not find module
624 Unicode::GCString, a warning message will be produced and
625 processing will continue but without the potential benefit provided
626 by the module.
627 Also note that actual vertical alignment depends upon the fonts
629 used by the text display software, so vertical alignment may not be
630 optimal even when Unicode::GCString is used.
631 -ole=s, --output-line-ending=s
633 where s="win", "dos", "unix", or "mac". This flag tells perltidy
634 to output line endings for a specific system. Normally, perltidy
635 writes files with the line separator character of the host system.
636 The "win" and "dos" flags have an identical result.
637 -ple, --preserve-line-endings
639 This flag tells perltidy to write its output files with the same
640 line endings as the input file, if possible. It should work for
641 dos, unix, and mac line endings. It will only work if perltidy
642 input comes from a filename (rather than stdin, for example). If
643 perltidy has trouble determining the input file line ending, it
644 will revert to the default behavior of using the line ending of the
645 host system.
646 -atnl, --add-terminal-newline
648 This flag, which is enabled by default, allows perltidy to
649 terminate the last line of the output stream with a newline
650 character, regardless of whether or not the input stream was
651 terminated with a newline character. If this flag is negated, with
652 -natnl, then perltidy will add a terminal newline to the the output
653 stream only if the input stream is terminated with a newline.
654 Negating this flag may be useful for manipulating one-line scripts
656 intended for use on a command line.
657 -it=n, --iterations=n
659 This flag causes perltidy to do n complete iterations. The reason
660 for this flag is that code beautification is an iterative process
661 and in some cases the output from perltidy can be different if it
662 is applied a second time. For most purposes the default of n=1
663 should be satisfactory. However n=2 can be useful when a major
664 style change is being made, or when code is being beautified on
665 check-in to a source code control system. It has been found to be
666 extremely rare for the output to change after 2 iterations. If a
667 value n is greater than 2 is input then a convergence test will be
668 used to stop the iterations as soon as possible, almost always
669 after 2 iterations. See the next item for a simplified iteration
670 control.
671 This flag has no effect when perltidy is used to generate html.
673 -conv, --converge
675 This flag is equivalent to -it=4 and is included to simplify
676 iteration control. For all practical purposes one either does or
677 does not want to be sure that the output is converged, and there is
678 no penalty to using a large iteration limit since perltidy will
679 check for convergence and stop iterating as soon as possible. The
680 default is -nconv (no convergence check). Using -conv will
681 approximately double run time since typically one extra iteration
682 is required to verify convergence. No extra iterations are
683 required if no new line breaks are made, and two extra iterations
684 are occasionally needed when reformatting complex code structures,
685 such as deeply nested ternary statements.
686 Code Indentation Control
688 -ci=n, --continuation-indentation=n
689 Continuation indentation is extra indentation spaces applied when a
690 long line is broken. The default is n=2, illustrated here:
691 my $level = # -ci=2
693 ( $max_index_to_go >= 0 ) ? $levels_to_go[0] : $last_output_level;
694 The same example, with n=0, is a little harder to read:
696 my $level = # -ci=0
698 ( $max_index_to_go >= 0 ) ? $levels_to_go[0] : $last_output_level;
699 The value given to -ci is also used by some commands when a small
701 space is required. Examples are commands for outdenting labels,
702 -ola, and control keywords, -okw.
703 When default values are not used, it is recommended that either
705 (1) the value n given with -ci=n be no more than about one-half of
707 the number of spaces assigned to a full indentation level on the
708 -i=n command, or
709 (2) the flag -extended-continuation-indentation is used (see next
711 section).
712 -xci, --extended-continuation-indentation
714 This flag allows perltidy to use some improvements which have been
715 made to its indentation model. One of the things it does is
716 "extend" continuation indentation deeper into structures, hence the
717 name. The improved indentation is particularly noticeable when the
718 flags -ci=n and -i=n use the same value of n. There are no
719 significant disadvantages to using this flag, but to avoid
720 disturbing existing formatting the default is not to use it, -nxci.
721 Please see the section "-pbp, --perl-best-practices" for an example
723 of how this flag can improve the formatting of ternary statements.
724 It can also improve indentation of some multi-line qw lists as
725 shown below.
726 # perltidy
728 foreach $color (
729 qw(
730 AntiqueWhite3 Bisque1 Bisque2 Bisque3 Bisque4
731 SlateBlue3 RoyalBlue1 SteelBlue2 DeepSkyBlue3
732 ),
733 qw(
734 LightBlue1 DarkSlateGray1 Aquamarine2 DarkSeaGreen2
735 SeaGreen1 Yellow1 IndianRed1 IndianRed2 Tan1 Tan4
736 )
737 )
738 # perltidy -xci
740 foreach $color (
741 qw(
742 AntiqueWhite3 Bisque1 Bisque2 Bisque3 Bisque4
743 SlateBlue3 RoyalBlue1 SteelBlue2 DeepSkyBlue3
744 ),
745 qw(
746 LightBlue1 DarkSlateGray1 Aquamarine2 DarkSeaGreen2
747 SeaGreen1 Yellow1 IndianRed1 IndianRed2 Tan1 Tan4
748 )
749 )
750 -sil=n --starting-indentation-level=n
752 By default, perltidy examines the input file and tries to determine
753 the starting indentation level. While it is often zero, it may not
754 be zero for a code snippet being sent from an editing session.
755 To guess the starting indentation level perltidy simply assumes
757 that indentation scheme used to create the code snippet is the same
758 as is being used for the current perltidy process. This is the
759 only sensible guess that can be made. It should be correct if this
760 is true, but otherwise it probably won't. For example, if the
761 input script was written with -i=2 and the current perltidy flags
762 have -i=4, the wrong initial indentation will be guessed for a code
763 snippet which has non-zero initial indentation. Likewise, if an
764 entabbing scheme is used in the input script and not in the current
765 process then the guessed indentation will be wrong.
766 If the default method does not work correctly, or you want to
768 change the starting level, use -sil=n, to force the starting level
769 to be n.
770 List indentation using --line-up-parentheses, -lp or
772 --extended--line-up-parentheses , -xlp
773 These flags provide an alternative indentation method for list
774 data. The original flag for this is -lp, but it has some
775 limitations (explained below) which are avoided with the newer -xlp
776 flag. So -xlp is probably the better choice for new work, but the
777 -lp flag is retained to minimize changes to existing formatting.
778 If you enter both -lp and -xlp, then -xlp will be used.
779 In the default indentation method perltidy indents lists with 4
781 spaces, or whatever value is specified with -i=n. Here is a small
782 list formatted in this way:
783 # perltidy (default)
785 @month_of_year = (
786 'Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun',
787 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'
788 );
789 The -lp or -xlp flags add extra indentation to cause the data to
791 begin past the opening parentheses of a sub call or list, or
792 opening square bracket of an anonymous array, or opening curly
793 brace of an anonymous hash. With this option, the above list would
794 become:
795 # perltidy -lp or -xlp
797 @month_of_year = (
798 'Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun',
799 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'
800 );
801 If the available line length (see -l=n ) does not permit this much
803 space, perltidy will use less. For alternate placement of the
804 closing paren, see the next section.
805 These flags have no effect on code BLOCKS, such as if/then/else
807 blocks, which always use whatever is specified with -i=n.
808 Some limitations on these flags are:
810 • A limitation on -lp, but not -xlp, occurs in situations where
812 perltidy does not have complete freedom to choose line breaks.
813 Then it may temporarily revert to its default indentation
814 method. This can occur for example if there are blank lines,
815 block comments, multi-line quotes, or side comments between the
816 opening and closing parens, braces, or brackets. It will also
817 occur if a multi-line anonymous sub occurs within a container
818 since that will impose specific line breaks (such as line
819 breaks after statements).
820 • For both the -lp and -xlp flags, any parameter which
822 significantly restricts the ability of perltidy to choose
823 newlines will conflict with these flags and will cause them to
824 be deactivated. These include -io, -fnl, -nanl, and -ndnl.
825 • The -lp and -xlp options may not be used together with the -t
827 tabs option. They may, however, be used with the -et=n tab
828 method
829 There are some potential disadvantages of this indentation method
831 compared to the default method that should be noted:
832 • The available line length can quickly be used up if variable
834 names are long. This can cause deeply nested code to quickly
835 reach the line length limit, and become badly formatted, much
836 sooner than would occur with the default indentation method.
837 • Since the indentation depends on the lengths of variable names,
839 small changes in variable names can cause changes in
840 indentation over many lines in a file. This means that minor
841 name changes can produce significant file differences. This
842 can be annoying and does not occur with the default indentation
843 method.
844 Some things that can be done to minimize these problems are:
846 • Increase --maximum-line-length=n above the default n=80
848 characters if necessary.
849 • If you use -xlp then long side comments can limit the
851 indentation over multiple lines. Consider adding the flag
852 --ignore-side-comment-lengths to prevent this, or minimizing
853 the use of side comments.
854 • Apply this style in a limited way. By default, it applies to
856 all list containers (not just lists in parentheses). The next
857 section describes how to limit this style to, for example, just
858 function calls. The default indentation method will be applied
859 elsewhere.
860 -lpil=s, --line-up-parentheses-inclusion-list and -lpxl=s,
862 --line-up-parentheses-exclusion-list
863 The following discussion is written for -lp but applies equally to
864 the newer -xlp version. By default, the -lp flag applies to as
865 many containers as possible. The set of containers to which the
866 -lp style applies can be reduced by either one of these two flags:
867 Use -lpil=s to specify the containers to which -lp applies, or
869 use -lpxl=s to specify the containers to which -lp does NOT apply.
871 Only one of these two flags may be used. Both flags can achieve
873 the same result, but the -lpil=s flag is much easier to describe
874 and use and is recommended. The -lpxl=s flag was the original
875 implementation and is only retained for backwards compatibility.
876 This list s for these parameters is a string with space-separated
878 items. Each item consists of up to three pieces of information in
879 this order: (1) an optional letter code (2) a required container
880 type, and (3) an optional numeric code.
881 The only required piece of information is a container type, which
883 is one of '(', '[', or '{'. For example the string
884 -lpil='('
886 means use -lp formatting only on lists within parentheses, not
888 lists in square-brackets or braces. The same thing could
889 alternatively be specified with
890 -lpxl = '[ {'
892 which says to exclude lists within square-brackets and braces. So
894 what remains is lists within parentheses.
895 A second optional item of information which can be given for
897 parentheses is an alphanumeric letter which is used to limit the
898 selection further depending on the type of token immediately before
899 the paren. The possible letters are currently 'k', 'K', 'f', 'F',
900 'w', and 'W', with these meanings for matching whatever precedes an
901 opening paren:
902 'k' matches if the previous nonblank token is a perl built-in keyword (such as 'if', 'while'),
904 'K' matches if 'k' does not, meaning that the previous token is not a keyword.
905 'f' matches if the previous token is a function other than a keyword.
906 'F' matches if 'f' does not.
907 'w' matches if either 'k' or 'f' match.
908 'W' matches if 'w' does not.
909 For example:
911 -lpil = 'f('
913 means only apply -lp to function calls, and
915 -lpil = 'w('
917 means only apply -lp to parenthesized lists which follow a function
919 or a keyword.
920 This last example could alternatively be written using the -lpxl=s
922 flag as
923 -lpxl = '[ { W('
925 which says exclude -lp for lists within square-brackets, braces,
927 and parens NOT preceded by a keyword or function. Clearly, the
928 -lpil=s method is easier to understand.
929 An optional numeric code may follow any of the container types to
931 further refine the selection based on container contents. The
932 numeric codes are:
933 '0' or blank: no check on contents is made
935 '1' exclude B<-lp> unless the contents is a simple list without sublists
936 '2' exclude B<-lp> unless the contents is a simple list without sublists, without
937 code blocks, and without ternary operators
938 For example,
940 -lpil = 'f(2'
942 means only apply -lp to function call lists which do not contain
944 any sublists, code blocks or ternary expressions.
945 -cti=n, --closing-token-indentation
947 The -cti=n flag controls the indentation of a line beginning with a
948 ")", "]", or a non-block "}". Such a line receives:
949 -cti = 0 no extra indentation (default)
951 -cti = 1 extra indentation such that the closing token
952 aligns with its opening token.
953 -cti = 2 one extra indentation level if the line looks like:
954 ); or ]; or };
955 -cti = 3 one extra indentation level always
956 The flags -cti=1 and -cti=2 work well with the -lp flag (previous
958 section).
959 # perltidy -lp -cti=1
961 @month_of_year = (
962 'Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun',
963 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'
964 );
965 # perltidy -lp -cti=2
967 @month_of_year = (
968 'Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun',
969 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'
970 );
971 These flags are merely hints to the formatter and they may not
973 always be followed. In particular, if -lp is not being used, the
974 indentation for cti=1 is constrained to be no more than one
975 indentation level.
976 If desired, this control can be applied independently to each of
978 the closing container token types. In fact, -cti=n is merely an
979 abbreviation for -cpi=n -csbi=n -cbi=n, where: -cpi or
980 --closing-paren-indentation controls )'s, -csbi or
981 --closing-square-bracket-indentation controls ]'s, -cbi or
982 --closing-brace-indentation controls non-block }'s.
983 -icp, --indent-closing-paren
985 The -icp flag is equivalent to -cti=2, described in the previous
986 section. The -nicp flag is equivalent -cti=0. They are included
987 for backwards compatibility.
988 -icb, --indent-closing-brace
990 The -icb option gives one extra level of indentation to a brace
991 which terminates a code block . For example,
992 if ($task) {
994 yyy();
995 } # -icb
996 else {
997 zzz();
998 }
999 The default is not to do this, indicated by -nicb.
1001 -nib, --non-indenting-braces
1003 Normally, lines of code contained within a pair of block braces
1004 receive one additional level of indentation. This flag, which is
1005 enabled by default, causes perltidy to look for opening block
1006 braces which are followed by a special side comment. This special
1007 side comment is #<<< by default. If found, the code between this
1008 opening brace and its corresponding closing brace will not be given
1009 the normal extra indentation level. For example:
1010 { #<<< a closure to contain lexical vars
1012 my $var; # this line does not get one level of indentation
1014 ...
1015 }
1017 # this line does not 'see' $var;
1019 This can be useful, for example, when combining code from different
1021 files. Different sections of code can be placed within braces to
1022 keep their lexical variables from being visible to the end of the
1023 file. To keep the new braces from causing all of their contained
1024 code to be indented if you run perltidy, and possibly introducing
1025 new line breaks in long lines, you can mark the opening braces with
1026 this special side comment.
1027 Only the opening brace needs to be marked, since perltidy knows
1029 where the closing brace is. Braces contained within marked braces
1030 may also be marked as non-indenting.
1031 If your code happens to have some opening braces followed by
1033 '#<<<', and you don't want this behavior, you can use -nnib to
1034 deactivate it. To make it easy to remember, the default string is
1035 the same as the string for starting a format-skipping section.
1036 There is no confusion because in that case it is for a block
1037 comment rather than a side-comment.
1038 The special side comment can be changed with the next parameter.
1040 -nibp=s, --non-indenting-brace-prefix=s
1042 The -nibp=string parameter may be used to change the marker for
1043 non-indenting braces. The default is equivalent to -nibp='#<<<'.
1044 The string that you enter must begin with a # and should be in
1045 quotes as necessary to get past the command shell of your system.
1046 This string is the leading text of a regex pattern that is
1047 constructed by appending pre-pending a '^' and appending a'\s', so
1048 you must also include backslashes for characters to be taken
1049 literally rather than as patterns.
1050 For example, to match the side comment '#++', the parameter would
1052 be
1053 -nibp='#\+\+'
1055 -olq, --outdent-long-quotes
1057 When -olq is set, lines which is a quoted string longer than the
1058 value maximum-line-length will have their indentation removed to
1059 make them more readable. This is the default. To prevent such
1060 out-denting, use -nolq or --nooutdent-long-lines.
1061 -oll, --outdent-long-lines
1063 This command is equivalent to --outdent-long-quotes and
1064 --outdent-long-comments, and it is included for compatibility with
1065 previous versions of perltidy. The negation of this also works,
1066 -noll or --nooutdent-long-lines, and is equivalent to setting -nolq
1067 and -nolc.
1068 Outdenting Labels: -ola, --outdent-labels
1070 This command will cause labels to be outdented by 2 spaces (or
1071 whatever -ci has been set to), if possible. This is the default.
1072 For example:
1073 my $i;
1075 LOOP: while ( $i = <FOTOS> ) {
1076 chomp($i);
1077 next unless $i;
1078 fixit($i);
1079 }
1080 Use -nola to not outdent labels. To control line breaks after
1082 labels see "-bal=n, --break-after-labels=n".
1083 Outdenting Keywords
1085 -okw, --outdent-keywords
1086 The command -okw will cause certain leading control keywords to
1087 be outdented by 2 spaces (or whatever -ci has been set to), if
1088 possible. By default, these keywords are "redo", "next",
1089 "last", "goto", and "return". The intention is to make these
1090 control keywords easier to see. To change this list of
1091 keywords being outdented, see the next section.
1092 For example, using "perltidy -okw" on the previous example
1094 gives:
1095 my $i;
1097 LOOP: while ( $i = <FOTOS> ) {
1098 chomp($i);
1099 next unless $i;
1100 fixit($i);
1101 }
1102 The default is not to do this.
1104 Specifying Outdented Keywords: -okwl=string,
1106 --outdent-keyword-list=string
1107 This command can be used to change the keywords which are
1108 outdented with the -okw command. The parameter string is a
1109 required list of perl keywords, which should be placed in
1110 quotes if there are more than one. By itself, it does not
1111 cause any outdenting to occur, so the -okw command is still
1112 required.
1113 For example, the commands "-okwl="next last redo goto" -okw"
1115 will cause those four keywords to be outdented. It is probably
1116 simplest to place any -okwl command in a .perltidyrc file.
1117 Whitespace Control
1119 Whitespace refers to the blank space between variables, operators, and
1120 other code tokens.
1121 -fws, --freeze-whitespace
1123 This flag causes your original whitespace to remain unchanged, and
1124 causes the rest of the whitespace commands in this section, the
1125 Code Indentation section, and the Comment Control section to be
1126 ignored.
1127 Tightness of curly braces, parentheses, and square brackets
1129 Here the term "tightness" will mean the closeness with which pairs
1130 of enclosing tokens, such as parentheses, contain the quantities
1131 within. A numerical value of 0, 1, or 2 defines the tightness,
1132 with 0 being least tight and 2 being most tight. Spaces within
1133 containers are always symmetric, so if there is a space after a "("
1134 then there will be a space before the corresponding ")".
1135 The -pt=n or --paren-tightness=n parameter controls the space
1137 within parens. The example below shows the effect of the three
1138 possible values, 0, 1, and 2:
1139 if ( ( my $len_tab = length( $tabstr ) ) > 0 ) { # -pt=0
1141 if ( ( my $len_tab = length($tabstr) ) > 0 ) { # -pt=1 (default)
1142 if ((my $len_tab = length($tabstr)) > 0) { # -pt=2
1143 When n is 0, there is always a space to the right of a '(' and to
1145 the left of a ')'. For n=2 there is never a space. For n=1, the
1146 default, there is a space unless the quantity within the parens is
1147 a single token, such as an identifier or quoted string.
1148 Likewise, the parameter -sbt=n or --square-bracket-tightness=n
1150 controls the space within square brackets, as illustrated below.
1151 $width = $col[ $j + $k ] - $col[ $j ]; # -sbt=0
1153 $width = $col[ $j + $k ] - $col[$j]; # -sbt=1 (default)
1154 $width = $col[$j + $k] - $col[$j]; # -sbt=2
1155 Curly braces which do not contain code blocks are controlled by the
1157 parameter -bt=n or --brace-tightness=n.
1158 $obj->{ $parsed_sql->{ 'table' }[0] }; # -bt=0
1160 $obj->{ $parsed_sql->{'table'}[0] }; # -bt=1 (default)
1161 $obj->{$parsed_sql->{'table'}[0]}; # -bt=2
1162 And finally, curly braces which contain blocks of code are
1164 controlled by the parameter -bbt=n or --block-brace-tightness=n as
1165 illustrated in the example below.
1166 %bf = map { $_ => -M $_ } grep { /\.deb$/ } dirents '.'; # -bbt=0 (default)
1168 %bf = map { $_ => -M $_ } grep {/\.deb$/} dirents '.'; # -bbt=1
1169 %bf = map {$_ => -M $_} grep {/\.deb$/} dirents '.'; # -bbt=2
1170 To simplify input in the case that all of the tightness flags have
1172 the same value <n>, the parameter <-act=n> or
1173 --all-containers-tightness=n is an abbreviation for the combination
1174 <-pt=n -sbt=n -bt=n -bbt=n>.
1175 -tso, --tight-secret-operators
1177 The flag -tso causes certain perl token sequences (secret
1178 operators) which might be considered to be a single operator to be
1179 formatted "tightly" (without spaces). The operators currently
1180 modified by this flag are:
1181 0+ +0 ()x!! ~~<> ,=> =( )=
1183 For example the sequence 0 +, which converts a string to a number,
1185 would be formatted without a space: 0+ when the -tso flag is set.
1186 This flag is off by default.
1187 -sts, --space-terminal-semicolon
1189 Some programmers prefer a space before all terminal semicolons.
1190 The default is for no such space, and is indicated with -nsts or
1191 --nospace-terminal-semicolon.
1192 $i = 1 ; # -sts
1194 $i = 1; # -nsts (default)
1195 -sfs, --space-for-semicolon
1197 Semicolons within for loops may sometimes be hard to see,
1198 particularly when commas are also present. This option places
1199 spaces on both sides of these special semicolons, and is the
1200 default. Use -nsfs or --nospace-for-semicolon to deactivate it.
1201 for ( @a = @$ap, $u = shift @a ; @a ; $u = $v ) { # -sfs (default)
1203 for ( @a = @$ap, $u = shift @a; @a; $u = $v ) { # -nsfs
1204 -asc, --add-semicolons
1206 Setting -asc allows perltidy to add any missing optional semicolon
1207 at the end of a line which is followed by a closing curly brace on
1208 the next line. This is the default, and may be deactivated with
1209 -nasc or --noadd-semicolons.
1210 -dsm, --delete-semicolons
1212 Setting -dsm allows perltidy to delete extra semicolons which are
1213 simply empty statements. This is the default, and may be
1214 deactivated with -ndsm or --nodelete-semicolons. (Such semicolons
1215 are not deleted, however, if they would promote a side comment to a
1216 block comment).
1217 -aws, --add-whitespace
1219 Setting this option allows perltidy to add certain whitespace to
1220 improve code readability. This is the default. If you do not want
1221 any whitespace added, but are willing to have some whitespace
1222 deleted, use -naws. (Use -fws to leave whitespace completely
1223 unchanged).
1224 -dws, --delete-old-whitespace
1226 Setting this option allows perltidy to remove some old whitespace
1227 between characters, if necessary. This is the default. If you do
1228 not want any old whitespace removed, use -ndws or
1229 --nodelete-old-whitespace.
1230 Detailed whitespace controls around tokens
1232 For those who want more detailed control over the whitespace around
1233 tokens, there are four parameters which can directly modify the
1234 default whitespace rules built into perltidy for any token. They
1235 are:
1236 -wls=s or --want-left-space=s,
1238 -nwls=s or --nowant-left-space=s,
1240 -wrs=s or --want-right-space=s,
1242 -nwrs=s or --nowant-right-space=s.
1244 These parameters are each followed by a quoted string, s,
1246 containing a list of token types. No more than one of each of
1247 these parameters should be specified, because repeating a command-
1248 line parameter always overwrites the previous one before perltidy
1249 ever sees it.
1250 To illustrate how these are used, suppose it is desired that there
1252 be no space on either side of the token types = + - / *. The
1253 following two parameters would specify this desire:
1254 -nwls="= + - / *" -nwrs="= + - / *"
1256 (Note that the token types are in quotes, and that they are
1258 separated by spaces). With these modified whitespace rules, the
1259 following line of math:
1260 $root = -$b + sqrt( $b * $b - 4. * $a * $c ) / ( 2. * $a );
1262 becomes this:
1264 $root=-$b+sqrt( $b*$b-4.*$a*$c )/( 2.*$a );
1266 These parameters should be considered to be hints to perltidy
1268 rather than fixed rules, because perltidy must try to resolve
1269 conflicts that arise between them and all of the other rules that
1270 it uses. One conflict that can arise is if, between two tokens,
1271 the left token wants a space and the right one doesn't. In this
1272 case, the token not wanting a space takes priority.
1273 It is necessary to have a list of all token types in order to
1275 create this type of input. Such a list can be obtained by the
1276 command --dump-token-types. Also try the -D flag on a short
1277 snippet of code and look at the .DEBUG file to see the
1278 tokenization.
1279 WARNING Be sure to put these tokens in quotes to avoid having them
1281 misinterpreted by your command shell.
1282 Note1: Perltidy does always follow whitespace controls
1284 The various parameters controlling whitespace within a program are
1285 requests which perltidy follows as well as possible, but there are
1286 a number of situations where changing whitespace could change
1287 program behavior and is not done. Some of these are obvious; for
1288 example, we should not remove the space between the two plus
1289 symbols in '$x+ +$y' to avoid creating a '++' operator. Some are
1290 more subtle and involve the whitespace around bareword symbols and
1291 locations of possible filehandles. For example, consider the
1292 problem of formatting the following subroutine:
1293 sub print_div {
1295 my ($x,$y)=@_;
1296 print $x/$y;
1297 }
1298 Suppose the user requests that / signs have a space to the left but
1300 not to the right. Perltidy will refuse to do this, but if this were
1301 done the result would be
1302 sub print_div {
1304 my ($x,$y)=@_;
1305 print $x /$y;
1306 }
1307 If formatted in this way, the program will not run (at least with
1309 recent versions of perl) because the $x is taken to be a filehandle
1310 and / is assumed to start a quote. In a complex program, there
1311 might happen to be a / which terminates the multiline quote without
1312 a syntax error, allowing the program to run, but not as intended.
1313 Related issues arise with other binary operator symbols, such as +
1315 and -, and in older versions of perl there could be problems with
1316 ternary operators. So to avoid changing program behavior, perltidy
1317 has the simple rule that whitespace around possible filehandles is
1318 left unchanged. Likewise, whitespace around barewords is left
1319 unchanged. The reason is that if the barewords are defined in
1320 other modules, or in code that has not even been written yet,
1321 perltidy will not have seen their prototypes and must treat them
1322 cautiously.
1323 In perltidy this is implemented in the tokenizer by marking token
1325 following a print keyword as a special type Z. When formatting is
1326 being done, whitespace following this token type is generally left
1327 unchanged as a precaution against changing program behavior. This
1328 is excessively conservative but simple and easy to implement.
1329 Keywords which are treated similarly to print include printf, sort,
1330 exec, system. Changes in spacing around parameters following these
1331 keywords may have to be made manually. For example, the space, or
1332 lack of space, after the parameter $foo in the following line will
1333 be unchanged in formatting.
1334 system($foo );
1336 system($foo);
1337 To find if a token is of type Z you can use perltidy -DEBUG. For
1339 the first line above the result is
1340 1: system($foo );
1342 1: kkkkkk{ZZZZb};
1343 which shows that system is type k (keyword) and $foo is type Z.
1345 Note2: Perltidy's whitespace rules are not perfect
1347 Despite these precautions, it is still possible to introduce syntax
1348 errors with some asymmetric whitespace rules, particularly when
1349 call parameters are not placed in containing parens or braces. For
1350 example, the following two lines will be parsed by perl without a
1351 syntax error:
1352 # original programming, syntax ok
1354 my @newkeys = map $_-$nrecs+@data, @oldkeys;
1355 # perltidy default, syntax ok
1357 my @newkeys = map $_ - $nrecs + @data, @oldkeys;
1358 But the following will give a syntax error:
1360 # perltidy -nwrs='-'
1362 my @newkeys = map $_ -$nrecs + @data, @oldkeys;
1363 For another example, the following two lines will be parsed without
1365 syntax error:
1366 # original programming, syntax ok
1368 for my $severity ( reverse $SEVERITY_LOWEST+1 .. $SEVERITY_HIGHEST ) { ... }
1369 # perltidy default, syntax ok
1371 for my $severity ( reverse $SEVERITY_LOWEST + 1 .. $SEVERITY_HIGHEST ) { ... }
1372 But the following will give a syntax error:
1374 # perltidy -nwrs='+', syntax error:
1376 for my $severity ( reverse $SEVERITY_LOWEST +1 .. $SEVERITY_HIGHEST ) { ... }
1377 To avoid subtle parsing problems like this, it is best to avoid
1379 spacing a binary operator asymmetrically with a space on the left
1380 but not on the right.
1381 Space between specific keywords and opening paren
1383 When an opening paren follows a Perl keyword, no space is
1384 introduced after the keyword, unless it is (by default) one of
1385 these:
1386 my local our and or xor eq ne if else elsif until unless
1388 while for foreach return switch case given when
1389 These defaults can be modified with two commands:
1391 -sak=s or --space-after-keyword=s adds keywords.
1393 -nsak=s or --nospace-after-keyword=s removes keywords.
1395 where s is a list of keywords (in quotes if necessary). For
1397 example,
1398 my ( $a, $b, $c ) = @_; # default
1400 my( $a, $b, $c ) = @_; # -nsak="my local our"
1401 The abbreviation -nsak='*' is equivalent to including all of the
1403 keywords in the above list.
1404 When both -nsak=s and -sak=s commands are included, the -nsak=s
1406 command is executed first. For example, to have space after only
1407 the keywords (my, local, our) you could use -nsak="*" -sak="my
1408 local our".
1409 To put a space after all keywords, see the next item.
1411 Space between all keywords and opening parens
1413 When an opening paren follows a function or keyword, no space is
1414 introduced after the keyword except for the keywords noted in the
1415 previous item. To always put a space between a function or keyword
1416 and its opening paren, use the command:
1417 -skp or --space-keyword-paren
1419 You may also want to use the flag -sfp (next item) too.
1421 Space between all function names and opening parens
1423 When an opening paren follows a function the default and
1424 recommended formatting is not to introduce a space. To cause a
1425 space to be introduced use:
1426 -sfp or --space-function-paren
1428 myfunc( $a, $b, $c ); # default
1430 myfunc ( $a, $b, $c ); # -sfp
1431 You will probably also want to use the flag -skp (previous item)
1433 too.
1434 The parameter is not recommended because spacing a function paren
1436 can make a program vulnerable to parsing problems by Perl. For
1437 example, the following two-line program will run as written but
1438 will have a syntax error if reformatted with -sfp:
1439 if ( -e filename() ) { print "I'm here\n"; }
1441 sub filename { return $0 }
1442 In this particular case the syntax error can be removed if the line
1444 order is reversed, so that Perl parses 'sub filename' first.
1445 -fpva or --function-paren-vertical-alignment
1447 A side-effect of using the -sfp flag is that the parens may become
1448 vertically aligned. For example,
1449 # perltidy -sfp
1451 myfun ( $aaa, $b, $cc );
1452 mylongfun ( $a, $b, $c );
1453 This is the default behavior. To prevent this alignment use
1455 -nfpva:
1456 # perltidy -sfp -nfpva
1458 myfun ( $aaa, $b, $cc );
1459 mylongfun ( $a, $b, $c );
1460 -spp=n or --space-prototype-paren=n
1462 This flag can be used to control whether a function prototype is
1463 preceded by a space. For example, the following prototype does not
1464 have a space.
1465 sub usage();
1467 This integer n may have the value 0, 1, or 2 as follows:
1469 -spp=0 means no space before the paren
1471 -spp=1 means follow the example of the source code [DEFAULT]
1472 -spp=2 means always put a space before the paren
1473 The default is -spp=1, meaning that a space will be used if and
1475 only if there is one in the source code. Given the above line of
1476 code, the result of applying the different options would be:
1477 sub usage(); # n=0 [no space]
1479 sub usage(); # n=1 [default; follows input]
1480 sub usage (); # n=2 [space]
1481 -kpit=n or --keyword-paren-inner-tightness=n
1483 The space inside of an opening paren, which itself follows a
1484 certain keyword, can be controlled by this parameter. The space on
1485 the inside of the corresponding closing paren will be treated in
1486 the same (balanced) manner. This parameter has precedence over any
1487 other paren spacing rules. The values of n are as follows:
1488 -kpit=0 means always put a space (not tight)
1490 -kpit=1 means ignore this parameter [default]
1491 -kpit=2 means never put a space (tight)
1492 To illustrate, the following snippet is shown formatted in three
1494 ways:
1495 if ( seek( DATA, 0, 0 ) ) { ... } # perltidy (default)
1497 if (seek(DATA, 0, 0)) { ... } # perltidy -pt=2
1498 if ( seek(DATA, 0, 0) ) { ... } # perltidy -pt=2 -kpit=0
1499 In the second case the -pt=2 parameter makes all of the parens
1501 tight. In the third case the -kpit=0 flag causes the space within
1502 the 'if' parens to have a space, since 'if' is one of the keywords
1503 to which the -kpit flag applies by default. The remaining parens
1504 are still tight because of the -pt=2 parameter.
1505 The set of keywords to which this parameter applies are by default
1507 are:
1508 if elsif unless while until for foreach
1510 These can be changed with the parameter -kpitl=s described in the
1512 next section.
1513 -kpitl=string or --keyword-paren-inner-tightness=string
1515 This command can be used to change the keywords to which the the
1516 -kpit=n command applies. The parameter string is a required list
1517 either keywords or functions, which should be placed in quotes if
1518 there are more than one. By itself, this parameter does not cause
1519 any change in spacing, so the -kpit=n command is still required.
1520 For example, the commands "-kpitl="if else while" -kpit=2" will
1522 cause the just the spaces inside parens following 'if', 'else',
1523 and 'while' keywords to follow the tightness value indicated by the
1524 -kpit=2 flag.
1525 -lop or --logical-padding
1527 In the following example some extra space has been inserted on the
1528 second line between the two open parens. This extra space is called
1529 "logical padding" and is intended to help align similar things
1530 vertically in some logical or ternary expressions.
1531 # perltidy [default formatting]
1533 $same =
1534 ( ( $aP eq $bP )
1535 && ( $aS eq $bS )
1536 && ( $aT eq $bT )
1537 && ( $a->{'title'} eq $b->{'title'} )
1538 && ( $a->{'href'} eq $b->{'href'} ) );
1539 Note that this is considered to be a different operation from
1541 "vertical alignment" because space at just one line is being
1542 adjusted, whereas in "vertical alignment" the spaces at all lines
1543 are being adjusted. So it sort of a local version of vertical
1544 alignment.
1545 Here is an example involving a ternary operator:
1547 # perltidy [default formatting]
1549 $bits =
1550 $top > 0xffff ? 32
1551 : $top > 0xff ? 16
1552 : $top > 1 ? 8
1553 : 1;
1554 This behavior is controlled with the flag --logical-padding, which
1556 is set 'on' by default. If it is not desired it can be turned off
1557 using --nological-padding or -nlop. The above two examples become,
1558 with -nlop:
1559 # perltidy -nlop
1561 $same =
1562 ( ( $aP eq $bP )
1563 && ( $aS eq $bS )
1564 && ( $aT eq $bT )
1565 && ( $a->{'title'} eq $b->{'title'} )
1566 && ( $a->{'href'} eq $b->{'href'} ) );
1567 # perltidy -nlop
1569 $bits =
1570 $top > 0xffff ? 32
1571 : $top > 0xff ? 16
1572 : $top > 1 ? 8
1573 : 1;
1574 Trimming whitespace around "qw" quotes
1576 -tqw or --trim-qw provide the default behavior of trimming spaces
1577 around multi-line "qw" quotes and indenting them appropriately.
1578 -ntqw or --notrim-qw cause leading and trailing whitespace around
1580 multi-line "qw" quotes to be left unchanged. This option will not
1581 normally be necessary, but was added for testing purposes, because
1582 in some versions of perl, trimming "qw" quotes changes the syntax
1583 tree.
1584 -sbq=n or --space-backslash-quote=n
1586 lines like
1587 $str1=\"string1";
1589 $str2=\'string2';
1590 can confuse syntax highlighters unless a space is included between
1592 the backslash and the single or double quotation mark.
1593 this can be controlled with the value of n as follows:
1595 -sbq=0 means no space between the backslash and quote
1597 -sbq=1 means follow the example of the source code
1598 -sbq=2 means always put a space between the backslash and quote
1599 The default is -sbq=1, meaning that a space will be used if there
1601 is one in the source code.
1602 Trimming trailing whitespace from lines of POD
1604 -trp or --trim-pod will remove trailing whitespace from lines of
1605 POD. The default is not to do this.
1606 Comment Controls
1608 Perltidy has a number of ways to control the appearance of both block
1609 comments and side comments. The term block comment here refers to a
1610 full-line comment, whereas side comment will refer to a comment which
1611 appears on a line to the right of some code.
1612 -ibc, --indent-block-comments
1614 Block comments normally look best when they are indented to the
1615 same level as the code which follows them. This is the default
1616 behavior, but you may use -nibc to keep block comments left-
1617 justified. Here is an example:
1618 # this comment is indented (-ibc, default)
1620 if ($task) { yyy(); }
1621 The alternative is -nibc:
1623 # this comment is not indented (-nibc)
1625 if ($task) { yyy(); }
1626 See also the next item, -isbc, as well as -sbc, for other ways to
1628 have some indented and some outdented block comments.
1629 -isbc, --indent-spaced-block-comments
1631 If there is no leading space on the line, then the comment will not
1632 be indented, and otherwise it may be.
1633 If both -ibc and -isbc are set, then -isbc takes priority.
1635 -olc, --outdent-long-comments
1637 When -olc is set, lines which are full-line (block) comments longer
1638 than the value maximum-line-length will have their indentation
1639 removed. This is the default; use -nolc to prevent outdenting.
1640 -msc=n, --minimum-space-to-comment=n
1642 Side comments look best when lined up several spaces to the right
1643 of code. Perltidy will try to keep comments at least n spaces to
1644 the right. The default is n=4 spaces.
1645 -fpsc=n, --fixed-position-side-comment=n
1647 This parameter tells perltidy to line up side comments in column
1648 number n whenever possible. The default, n=0, will not do this.
1649 -iscl, --ignore-side-comment-lengths
1651 This parameter causes perltidy to ignore the length of side
1652 comments when setting line breaks. The default, -niscl, is to
1653 include the length of side comments when breaking lines to stay
1654 within the length prescribed by the -l=n maximum line length
1655 parameter. For example, the following long single line would
1656 remain intact with -l=80 and -iscl:
1657 perltidy -l=80 -iscl
1659 $vmsfile =~ s/;[\d\-]*$//; # Clip off version number; we can use a newer version as well
1660 whereas without the -iscl flag the line will be broken:
1662 perltidy -l=80
1664 $vmsfile =~ s/;[\d\-]*$//
1665 ; # Clip off version number; we can use a newer version as well
1666 -hsc, --hanging-side-comments
1668 By default, perltidy tries to identify and align "hanging side
1669 comments", which are something like this:
1670 my $IGNORE = 0; # This is a side comment
1672 # This is a hanging side comment
1673 # And so is this
1674 A comment is considered to be a hanging side comment if (1) it
1676 immediately follows a line with a side comment, or another hanging
1677 side comment, and (2) there is some leading whitespace on the line.
1678 To deactivate this feature, use -nhsc or --nohanging-side-comments.
1679 If block comments are preceded by a blank line, or have no leading
1680 whitespace, they will not be mistaken as hanging side comments.
1681 Closing Side Comments
1683 A closing side comment is a special comment which perltidy can
1684 automatically create and place after the closing brace of a code
1685 block. They can be useful for code maintenance and debugging. The
1686 command -csc (or --closing-side-comments) adds or updates closing
1687 side comments. For example, here is a small code snippet
1688 sub message {
1690 if ( !defined( $_[0] ) ) {
1691 print("Hello, World\n");
1692 }
1693 else {
1694 print( $_[0], "\n" );
1695 }
1696 }
1697 And here is the result of processing with "perltidy -csc":
1699 sub message {
1701 if ( !defined( $_[0] ) ) {
1702 print("Hello, World\n");
1703 }
1704 else {
1705 print( $_[0], "\n" );
1706 }
1707 } ## end sub message
1708 A closing side comment was added for "sub message" in this case,
1710 but not for the "if" and "else" blocks, because they were below the
1711 6 line cutoff limit for adding closing side comments. This limit
1712 may be changed with the -csci command, described below.
1713 The command -dcsc (or --delete-closing-side-comments) reverses this
1715 process and removes these comments.
1716 Several commands are available to modify the behavior of these two
1718 basic commands, -csc and -dcsc:
1719 -csci=n, or --closing-side-comment-interval=n
1721 where "n" is the minimum number of lines that a block must have
1722 in order for a closing side comment to be added. The default
1723 value is "n=6". To illustrate:
1724 # perltidy -csci=2 -csc
1726 sub message {
1727 if ( !defined( $_[0] ) ) {
1728 print("Hello, World\n");
1729 } ## end if ( !defined( $_[0] ))
1730 else {
1731 print( $_[0], "\n" );
1732 } ## end else [ if ( !defined( $_[0] ))
1733 } ## end sub message
1734 Now the "if" and "else" blocks are commented. However, now
1736 this has become very cluttered.
1737 -cscp=string, or --closing-side-comment-prefix=string
1739 where string is the prefix used before the name of the block
1740 type. The default prefix, shown above, is "## end". This
1741 string will be added to closing side comments, and it will also
1742 be used to recognize them in order to update, delete, and
1743 format them. Any comment identified as a closing side comment
1744 will be placed just a single space to the right of its closing
1745 brace.
1746 -cscl=string, or --closing-side-comment-list
1748 where "string" is a list of block types to be tagged with
1749 closing side comments. By default, all code block types
1750 preceded by a keyword or label (such as "if", "sub", and so on)
1751 will be tagged. The -cscl command changes the default list to
1752 be any selected block types; see "Specifying Block Types". For
1753 example, the following command requests that only "sub"'s,
1754 labels, "BEGIN", and "END" blocks be affected by any -csc or
1755 -dcsc operation:
1756 -cscl="sub : BEGIN END"
1758 -csct=n, or --closing-side-comment-maximum-text=n
1760 The text appended to certain block types, such as an "if"
1761 block, is whatever lies between the keyword introducing the
1762 block, such as "if", and the opening brace. Since this might
1763 be too much text for a side comment, there needs to be a limit,
1764 and that is the purpose of this parameter. The default value
1765 is "n=20", meaning that no additional tokens will be appended
1766 to this text after its length reaches 20 characters. Omitted
1767 text is indicated with "...". (Tokens, including sub names,
1768 are never truncated, however, so actual lengths may exceed
1769 this). To illustrate, in the above example, the appended text
1770 of the first block is " ( !defined( $_[0] )...". The existing
1771 limit of "n=20" caused this text to be truncated, as indicated
1772 by the "...". See the next flag for additional control of the
1773 abbreviated text.
1774 -cscb, or --closing-side-comments-balanced
1776 As discussed in the previous item, when the closing-side-
1777 comment-maximum-text limit is exceeded the comment text must be
1778 truncated. Older versions of perltidy terminated with three
1779 dots, and this can still be achieved with -ncscb:
1780 perltidy -csc -ncscb
1782 } ## end foreach my $foo (sort { $b cmp $a ...
1783 However this causes a problem with editors which cannot
1785 recognize comments or are not configured to do so because they
1786 cannot "bounce" around in the text correctly. The -cscb flag
1787 has been added to help them by appending appropriate balancing
1788 structure:
1789 perltidy -csc -cscb
1791 } ## end foreach my $foo (sort { $b cmp $a ... })
1792 The default is -cscb.
1794 -csce=n, or --closing-side-comment-else-flag=n
1796 The default, n=0, places the text of the opening "if" statement
1797 after any terminal "else".
1798 If n=2 is used, then each "elsif" is also given the text of the
1800 opening "if" statement. Also, an "else" will include the text
1801 of a preceding "elsif" statement. Note that this may result
1802 some long closing side comments.
1803 If n=1 is used, the results will be the same as n=2 whenever
1805 the resulting line length is less than the maximum allowed.
1806 -cscb, or --closing-side-comments-balanced
1808 When using closing-side-comments, and the closing-side-comment-
1809 maximum-text limit is exceeded, then the comment text must be
1810 abbreviated. It is terminated with three dots if the -cscb
1811 flag is negated:
1812 perltidy -csc -ncscb
1814 } ## end foreach my $foo (sort { $b cmp $a ...
1815 This causes a problem with older editors which do not recognize
1817 comments because they cannot "bounce" around in the text
1818 correctly. The -cscb flag tries to help them by appending
1819 appropriate terminal balancing structures:
1820 perltidy -csc -cscb
1822 } ## end foreach my $foo (sort { $b cmp $a ... })
1823 The default is -cscb.
1825 -cscw, or --closing-side-comment-warnings
1827 This parameter is intended to help make the initial transition
1828 to the use of closing side comments. It causes two things to
1829 happen if a closing side comment replaces an existing,
1830 different closing side comment: first, an error message will
1831 be issued, and second, the original side comment will be placed
1832 alone on a new specially marked comment line for later
1833 attention.
1834 The intent is to avoid clobbering existing hand-written side
1836 comments which happen to match the pattern of closing side
1837 comments. This flag should only be needed on the first run with
1838 -csc.
1839 Important Notes on Closing Side Comments:
1841 • Closing side comments are only placed on lines terminated with
1843 a closing brace. Certain closing styles, such as the use of
1844 cuddled elses (-ce), preclude the generation of some closing
1845 side comments.
1846 • Please note that adding or deleting of closing side comments
1848 takes place only through the commands -csc or -dcsc. The other
1849 commands, if used, merely modify the behavior of these two
1850 commands.
1851 • It is recommended that the -cscw flag be used along with -csc
1853 on the first use of perltidy on a given file. This will
1854 prevent loss of any existing side comment data which happens to
1855 have the csc prefix.
1856 • Once you use -csc, you should continue to use it so that any
1858 closing side comments remain correct as code changes.
1859 Otherwise, these comments will become incorrect as the code is
1860 updated.
1861 • If you edit the closing side comments generated by perltidy,
1863 you must also change the prefix to be different from the
1864 closing side comment prefix. Otherwise, your edits will be
1865 lost when you rerun perltidy with -csc. For example, you
1866 could simply change "## end" to be "## End", since the test is
1867 case sensitive. You may also want to use the -ssc flag to keep
1868 these modified closing side comments spaced the same as actual
1869 closing side comments.
1870 • Temporarily generating closing side comments is a useful
1872 technique for exploring and/or debugging a perl script,
1873 especially one written by someone else. You can always remove
1874 them with -dcsc.
1875 Static Block Comments
1877 Static block comments are block comments with a special leading
1878 pattern, "##" by default, which will be treated slightly
1879 differently from other block comments. They effectively behave as
1880 if they had glue along their left and top edges, because they stick
1881 to the left edge and previous line when there is no blank spaces in
1882 those places. This option is particularly useful for controlling
1883 how commented code is displayed.
1884 -sbc, --static-block-comments
1886 When -sbc is used, a block comment with a special leading
1887 pattern, "##" by default, will be treated specially.
1888 Comments so identified are treated as follows:
1890 • If there is no leading space on the line, then the comment
1892 will not be indented, and otherwise it may be,
1893 • no new blank line will be inserted before such a comment,
1895 and
1896 • such a comment will never become a hanging side comment.
1898 For example, assuming @month_of_year is left-adjusted:
1900 @month_of_year = ( # -sbc (default)
1902 'Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct',
1903 ## 'Dec', 'Nov'
1904 'Nov', 'Dec');
1905 Without this convention, the above code would become
1907 @month_of_year = ( # -nsbc
1909 'Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct',
1910 ## 'Dec', 'Nov'
1912 'Nov', 'Dec'
1913 );
1914 which is not as clear. The default is to use -sbc. This may
1916 be deactivated with -nsbc.
1917 -sbcp=string, --static-block-comment-prefix=string
1919 This parameter defines the prefix used to identify static block
1920 comments when the -sbc parameter is set. The default prefix is
1921 "##", corresponding to "-sbcp=##". The prefix is actually part
1922 of a perl pattern used to match lines and it must either begin
1923 with "#" or "^#". In the first case a prefix ^\s* will be
1924 added to match any leading whitespace, while in the second case
1925 the pattern will match only comments with no leading
1926 whitespace. For example, to identify all comments as static
1927 block comments, one would use "-sbcp=#". To identify all left-
1928 adjusted comments as static block comments, use "-sbcp='^#'".
1929 Please note that -sbcp merely defines the pattern used to
1931 identify static block comments; it will not be used unless the
1932 switch -sbc is set. Also, please be aware that since this
1933 string is used in a perl regular expression which identifies
1934 these comments, it must enable a valid regular expression to be
1935 formed.
1936 A pattern which can be useful is:
1938 -sbcp=^#{2,}[^\s#]
1940 This pattern requires a static block comment to have at least
1942 one character which is neither a # nor a space. It allows a
1943 line containing only '#' characters to be rejected as a static
1944 block comment. Such lines are often used at the start and end
1945 of header information in subroutines and should not be
1946 separated from the intervening comments, which typically begin
1947 with just a single '#'.
1948 -osbc, --outdent-static-block-comments
1950 The command -osbc will cause static block comments to be
1951 outdented by 2 spaces (or whatever -ci=n has been set to), if
1952 possible.
1953 Static Side Comments
1955 Static side comments are side comments with a special leading
1956 pattern. This option can be useful for controlling how commented
1957 code is displayed when it is a side comment.
1958 -ssc, --static-side-comments
1960 When -ssc is used, a side comment with a static leading
1961 pattern, which is "##" by default, will be spaced only a single
1962 space from previous character, and it will not be vertically
1963 aligned with other side comments.
1964 The default is -nssc.
1966 -sscp=string, --static-side-comment-prefix=string
1968 This parameter defines the prefix used to identify static side
1969 comments when the -ssc parameter is set. The default prefix is
1970 "##", corresponding to "-sscp=##".
1971 Please note that -sscp merely defines the pattern used to
1973 identify static side comments; it will not be used unless the
1974 switch -ssc is set. Also, note that this string is used in a
1975 perl regular expression which identifies these comments, so it
1976 must enable a valid regular expression to be formed.
1977 Skipping Selected Sections of Code
1979 Selected lines of code may be passed verbatim to the output without any
1980 formatting by marking the starting and ending lines with special
1981 comments. There are two options for doing this. The first option is
1982 called --format-skipping or -fs, and the second option is called
1983 --code-skipping or -cs.
1984 In both cases the lines of code will be output without any changes.
1986 The difference is that in --format-skipping perltidy will still parse
1987 the marked lines of code and check for errors, whereas in
1988 --code-skipping perltidy will simply pass the lines to the output
1989 without any checking.
1990 Both of these features are enabled by default and are invoked with
1992 special comment markers. --format-skipping uses starting and ending
1993 markers '#<<<' and '#>>>', like this:
1994 #<<< format skipping: do not let perltidy change my nice formatting
1996 my @list = (1,
1997 1, 1,
1998 1, 2, 1,
1999 1, 3, 3, 1,
2000 1, 4, 6, 4, 1,);
2001 #>>>
2002 --code-skipping uses starting and ending markers '#<<V' and '#>>V',
2004 like this:
2005 #<<V code skipping: perltidy will pass this verbatim without error checking
2007 token ident_digit {
2009 [ [ <?word> | _ | <?digit> ] <?ident_digit>
2010 | <''>
2011 ]
2012 };
2013 #>>V
2015 Additional text may appear on the special comment lines provided that
2017 it is separated from the marker by at least one space, as in the above
2018 examples.
2019 Any number of code-skipping or format-skipping sections may appear in a
2021 file. If an opening code-skipping or format-skipping comment is not
2022 followed by a corresponding closing comment, then skipping continues to
2023 the end of the file. If a closing code-skipping or format-skipping
2024 comment appears in a file but does not follow a corresponding opening
2025 comment, then it is treated as an ordinary comment without any special
2026 meaning.
2027 It is recommended to use --code-skipping only if you need to hide a
2029 block of an extended syntax which would produce errors if parsed by
2030 perltidy, and use --format-skipping otherwise. This is because the
2031 --format-skipping option provides the benefits of error checking, and
2032 there are essentially no limitations on which lines to which it can be
2033 applied. The --code-skipping option, on the other hand, does not do
2034 error checking and its use is more restrictive because the code which
2035 remains, after skipping the marked lines, must be syntactically correct
2036 code with balanced containers.
2037 These features should be used sparingly to avoid littering code with
2039 markers, but they can be helpful for working around occasional
2040 problems.
2041 Note that it may be possible to avoid the use of --format-skipping for
2043 the specific case of a comma-separated list of values, as in the above
2044 example, by simply inserting a blank or comment somewhere between the
2045 opening and closing parens. See the section "Controlling List
2046 Formatting".
2047 The following sections describe the available controls for these
2049 options. They should not normally be needed.
2050 -fs, --format-skipping
2052 As explained above, this flag, which is enabled by default, causes
2053 any code between special beginning and ending comment markers to be
2054 passed to the output without formatting. The code between the
2055 comments is still checked for errors however. The default
2056 beginning marker is #<<< and the default ending marker is #>>>.
2057 Format skipping begins when a format skipping beginning comment is
2059 seen and continues until a format-skipping ending comment is found.
2060 This feature can be disabled with -nfs. This should not normally
2062 be necessary.
2063 -fsb=string, --format-skipping-begin=string
2065 This and the next parameter allow the special beginning and ending
2066 comments to be changed. However, it is recommended that they only
2067 be changed if there is a conflict between the default values and
2068 some other use. If they are used, it is recommended that they only
2069 be entered in a .perltidyrc file, rather than on a command line.
2070 This is because properly escaping these parameters on a command
2071 line can be difficult.
2072 If changed comment markers do not appear to be working, use the
2074 -log flag and examine the .LOG file to see if and where they are
2075 being detected.
2076 The -fsb=string parameter may be used to change the beginning
2078 marker for format skipping. The default is equivalent to
2079 -fsb='#<<<'. The string that you enter must begin with a # and
2080 should be in quotes as necessary to get past the command shell of
2081 your system. It is actually the leading text of a pattern that is
2082 constructed by appending a '\s', so you must also include
2083 backslashes for characters to be taken literally rather than as
2084 patterns.
2085 Some examples show how example strings become patterns:
2087 -fsb='#\{\{\{' becomes /^#\{\{\{\s/ which matches #{{{ but not #{{{{
2089 -fsb='#\*\*' becomes /^#\*\*\s/ which matches #** but not #***
2090 -fsb='#\*{2,}' becomes /^#\*{2,}\s/ which matches #** and #*****
2091 -fse=string, --format-skipping-end=string
2093 The -fse=string is the corresponding parameter used to change the
2094 ending marker for format skipping. The default is equivalent to
2095 -fse='#<<<'.
2096 The beginning and ending strings may be the same, but it is
2098 preferable to make them different for clarity.
2099 -cs, --code-skipping
2101 As explained above, this flag, which is enabled by default, causes
2102 any code between special beginning and ending comment markers to be
2103 directly passed to the output without any error checking or
2104 formatting. Essentially, perltidy treats it as if it were a block
2105 of arbitrary text. The default beginning marker is #<<V and the
2106 default ending marker is #>>V.
2107 This feature can be disabled with -ncs. This should not normally
2109 be necessary.
2110 -csb=string, --code-skipping-begin=string
2112 This may be used to change the beginning comment for a
2113 --code-skipping section, and its use is similar to the -fsb=string.
2114 The default is equivalent to -csb='#<<V'.
2115 -cse=string, --code-skipping-end=string
2117 This may be used to change the ending comment for a --code-skipping
2118 section, and its use is similar to the -fse=string. The default is
2119 equivalent to -cse='#>>V'.
2120 Line Break Control
2122 The parameters in this and the next sections control breaks after non-
2123 blank lines of code. Blank lines are controlled separately by
2124 parameters in the section "Blank Line Control".
2125 -dnl, --delete-old-newlines
2127 By default, perltidy first deletes all old line break locations,
2128 and then it looks for good break points to match the desired line
2129 length. Use -ndnl or --nodelete-old-newlines to force perltidy to
2130 retain all old line break points.
2131 -anl, --add-newlines
2133 By default, perltidy will add line breaks when necessary to create
2134 continuations of long lines and to improve the script appearance.
2135 Use -nanl or --noadd-newlines to prevent any new line breaks.
2136 This flag does not prevent perltidy from eliminating existing line
2138 breaks; see --freeze-newlines to completely prevent changes to line
2139 break points.
2140 -fnl, --freeze-newlines
2142 If you do not want any changes to the line breaks within lines of
2143 code in your script, set -fnl, and they will remain fixed, and the
2144 rest of the commands in this section and sections "Controlling List
2145 Formatting", "Retaining or Ignoring Existing Line Breaks". You may
2146 want to use -noll with this.
2147 Note: If you also want to keep your blank lines exactly as they
2149 are, you can use the -fbl flag which is described in the section
2150 "Blank Line Control".
2151 Controlling Breaks at Braces, Parens, and Square Brackets
2153 -ce, --cuddled-else
2154 Enable the "cuddled else" style, in which "else" and "elsif" are
2155 follow immediately after the curly brace closing the previous
2156 block. The default is not to use cuddled elses, and is indicated
2157 with the flag -nce or --nocuddled-else. Here is a comparison of
2158 the alternatives:
2159 # -ce
2161 if ($task) {
2162 yyy();
2163 } else {
2164 zzz();
2165 }
2166 # -nce (default)
2168 if ($task) {
2169 yyy();
2170 }
2171 else {
2172 zzz();
2173 }
2174 In this example the keyword else is placed on the same line which
2176 begins with the preceding closing block brace and is followed by
2177 its own opening block brace on the same line. Other keywords and
2178 function names which are formatted with this "cuddled" style are
2179 elsif, continue, catch, finally.
2180 Other block types can be formatted by specifying their names on a
2182 separate parameter -cbl, described in a later section.
2183 Cuddling between a pair of code blocks requires that the closing
2185 brace of the first block start a new line. If this block is
2186 entirely on one line in the input file, it is necessary to decide
2187 if it should be broken to allow cuddling. This decision is
2188 controlled by the flag -cbo=n discussed below. The default and
2189 recommended value of -cbo=1 bases this decision on the first block
2190 in the chain. If it spans multiple lines then cuddling is made and
2191 continues along the chain, regardless of the sizes of subsequent
2192 blocks. Otherwise, short lines remain intact.
2193 So for example, the -ce flag would not have any effect if the above
2195 snippet is rewritten as
2196 if ($task) { yyy() }
2198 else { zzz() }
2199 If the first block spans multiple lines, then cuddling can be done
2201 and will continue for the subsequent blocks in the chain, as
2202 illustrated in the previous snippet.
2203 If there are blank lines between cuddled blocks they will be
2205 eliminated. If there are comments after the closing brace where
2206 cuddling would occur then cuddling will be prevented. If this
2207 occurs, cuddling will restart later in the chain if possible.
2208 -cb, --cuddled-blocks
2210 This flag is equivalent to -ce.
2211 -cbl, --cuddled-block-list
2213 The built-in default cuddled block types are else, elsif, continue,
2214 catch, finally.
2215 Additional block types to which the -cuddled-blocks style applies
2217 can be defined by this parameter. This parameter is a character
2218 string, giving a list of block types separated by commas or spaces.
2219 For example, to cuddle code blocks of type sort, map and grep, in
2220 addition to the default types, the string could be set to
2221 -cbl="sort map grep"
2223 or equivalently
2225 -cbl=sort,map,grep
2227 Note however that these particular block types are typically short
2229 so there might not be much opportunity for the cuddled format
2230 style.
2231 Using commas avoids the need to protect spaces with quotes.
2233 As a diagnostic check, the flag --dump-cuddled-block-list or -dcbl
2235 can be used to view the hash of values that are generated by this
2236 flag.
2237 Finally, note that the -cbl flag by itself merely specifies which
2239 blocks are formatted with the cuddled format. It has no effect
2240 unless this formatting style is activated with -ce.
2241 -cblx, --cuddled-block-list-exclusive
2243 When cuddled else formatting is selected with -ce, setting this
2244 flag causes perltidy to ignore its built-in defaults and rely
2245 exclusively on the block types specified on the -cbl flag described
2246 in the previous section. For example, to avoid using cuddled catch
2247 and finally, which are among the defaults, the following set of
2248 parameters could be used:
2249 perltidy -ce -cbl='else elsif continue' -cblx
2251 -cbo=n, --cuddled-break-option=n
2253 Cuddled formatting is only possible between a pair of code blocks
2254 if the closing brace of the first block starts a new line. If a
2255 block is encountered which is entirely on a single line, and
2256 cuddled formatting is selected, it is necessary to make a decision
2257 as to whether or not to "break" the block, meaning to cause it to
2258 span multiple lines. This parameter controls that decision. The
2259 options are:
2260 cbo=0 Never force a short block to break.
2262 cbo=1 If the first of a pair of blocks is broken in the input file,
2263 then break the second [DEFAULT].
2264 cbo=2 Break open all blocks for maximal cuddled formatting.
2265 The default and recommended value is cbo=1. With this value, if
2267 the starting block of a chain spans multiple lines, then a cascade
2268 of breaks will occur for remaining blocks causing the entire chain
2269 to be cuddled.
2270 The option cbo=0 can produce erratic cuddling if there are numerous
2272 one-line blocks.
2273 The option cbo=2 produces maximal cuddling but will not allow any
2275 short blocks.
2276 -bl, --opening-brace-on-new-line, or --brace-left
2278 Use the flag -bl to place an opening block brace on a new line:
2279 if ( $input_file eq '-' )
2281 {
2282 ...
2283 }
2284 By default it applies to all structural blocks except sort map grep
2286 eval and anonymous subs.
2287 The default is -nbl which places an opening brace on the same line
2289 as the keyword introducing it if possible. For example,
2290 # default
2292 if ( $input_file eq '-' ) {
2293 ...
2294 }
2295 When -bl is set, the blocks to which this applies can be controlled
2297 with the parameters --brace-left-list and
2298 -brace-left-exclusion-list described in the next sections.
2299 -bll=s, --brace-left-list=s
2301 Use this parameter to change the types of block braces for which
2302 the -bl flag applies; see "Specifying Block Types". For example,
2303 -bll='if elsif else sub' would apply it to only "if/elsif/else" and
2304 named sub blocks. The default is all blocks, -bll='*'.
2305 -blxl=s, --brace-left-exclusion-list=s
2307 Use this parameter to exclude types of block braces for which the
2308 -bl flag applies; see "Specifying Block Types". For example, the
2309 default settings -bll='*' and -blxl='sort map grep eval asub' mean
2310 all blocks except sort map grep eval and anonymous sub blocks.
2311 Note that the lists -bll=s and -blxl=s control the behavior of the
2313 -bl flag but have no effect unless the -bl flag is set.
2314 -sbl, --opening-sub-brace-on-new-line
2316 The flag -sbl provides a shortcut way to turn on -bl just for named
2317 subs. The same effect can be achieved by turning on -bl with the
2318 block list set as -bll='sub'.
2319 For example,
2321 perltidy -sbl
2323 produces this result:
2325 sub message
2327 {
2328 if (!defined($_[0])) {
2329 print("Hello, World\n");
2330 }
2331 else {
2332 print($_[0], "\n");
2333 }
2334 }
2335 This flag is negated with -nsbl, which is the default.
2337 -asbl, --opening-anonymous-sub-brace-on-new-line
2339 The flag -asbl is like the -sbl flag except that it applies to
2340 anonymous sub's instead of named subs. For example
2341 perltidy -asbl
2343 produces this result:
2345 $a = sub
2347 {
2348 if ( !defined( $_[0] ) ) {
2349 print("Hello, World\n");
2350 }
2351 else {
2352 print( $_[0], "\n" );
2353 }
2354 };
2355 This flag is negated with -nasbl, and the default is -nasbl.
2357 -bli, --brace-left-and-indent
2359 The flag -bli is similar to the -bl flag but in addition it causes
2360 one unit of continuation indentation ( see -ci ) to be placed
2361 before an opening and closing block braces.
2362 For example, perltidy -bli gives
2364 if ( $input_file eq '-' )
2366 {
2367 important_function();
2368 }
2369 By default, this extra indentation occurs for block types: if,
2371 elsif, else, unless, while, for, foreach, do, and also named subs
2372 and blocks preceded by a label. The next item shows how to change
2373 this.
2374 Note: The -bli flag is similar to the -bl flag, with the difference
2376 being that braces get indented. But these two flags are
2377 implemented independently, and have different default settings for
2378 historical reasons. If desired, a mixture of effects can be
2379 achieved if desired by turning them both on with different -list
2380 settings. In the event that both settings are selected for a
2381 certain block type, the -bli style has priority.
2382 -blil=s, --brace-left-and-indent-list=s
2384 Use this parameter to change the types of block braces for which
2385 the -bli flag applies; see "Specifying Block Types".
2386 The default is -blil='if else elsif unless while for foreach do :
2388 sub'.
2389 -blixl=s, --brace-left-and-indent-exclusion-list=s
2391 Use this parameter to exclude types of block braces for which the
2392 -bli flag applies; see "Specifying Block Types".
2393 This might be useful in conjunction with selecting all blocks
2395 -blil='*'. The default setting is -blixl=' ', which does not
2396 exclude any blocks.
2397 Note that the two parameters -blil and -blixl control the behavior
2399 of the -bli flag but have no effect unless the -bli flag is set.
2400 -bar, --opening-brace-always-on-right
2402 The default style, -nbl places the opening code block brace on a
2403 new line if it does not fit on the same line as the opening
2404 keyword, like this:
2405 if ( $bigwasteofspace1 && $bigwasteofspace2
2407 || $bigwasteofspace3 && $bigwasteofspace4 )
2408 {
2409 big_waste_of_time();
2410 }
2411 To force the opening brace to always be on the right, use the -bar
2413 flag. In this case, the above example becomes
2414 if ( $bigwasteofspace1 && $bigwasteofspace2
2416 || $bigwasteofspace3 && $bigwasteofspace4 ) {
2417 big_waste_of_time();
2418 }
2419 A conflict occurs if both -bl and -bar are specified.
2421 -otr, --opening-token-right and related flags
2423 The -otr flag is a hint that perltidy should not place a break
2424 between a comma and an opening token. For example:
2425 # default formatting
2427 push @{ $self->{$module}{$key} },
2428 {
2429 accno => $ref->{accno},
2430 description => $ref->{description}
2431 };
2432 # perltidy -otr
2434 push @{ $self->{$module}{$key} }, {
2435 accno => $ref->{accno},
2436 description => $ref->{description}
2437 };
2438 The flag -otr is actually an abbreviation for three other flags
2440 which can be used to control parens, hash braces, and square
2441 brackets separately if desired:
2442 -opr or --opening-paren-right
2444 -ohbr or --opening-hash-brace-right
2445 -osbr or --opening-square-bracket-right
2446 -bbhb=n, --break-before-hash-brace=n and related flags
2448 When a list of items spans multiple lines, the default formatting
2449 is to place the opening brace (or other container token) at the end
2450 of the starting line, like this:
2451 $romanNumerals = {
2453 one => 'I',
2454 two => 'II',
2455 three => 'III',
2456 four => 'IV',
2457 };
2458 This flag can change the default behavior to cause a line break to
2460 be placed before the opening brace according to the value given to
2461 the integer n:
2462 -bbhb=0 never break [default]
2464 -bbhb=1 stable: break if the input script had a break
2465 -bbhb=2 break if list is 'complex' (see note below)
2466 -bbhb=3 always break
2467 For example,
2469 # perltidy -bbhb=3
2471 $romanNumerals =
2472 {
2473 one => 'I',
2474 two => 'II',
2475 three => 'III',
2476 four => 'IV',
2477 };
2478 There are several points to note about this flag:
2480 • This parameter only applies if the opening brace is preceded by
2482 an '=' or '=>'.
2483 • This parameter only applies if the contents of the container
2485 looks like a list. The contents need to contain some commas or
2486 '=>'s at the next interior level to be considered a list.
2487 • For the n=2 option, a list is considered 'complex' if it is
2489 part of a nested list structure which spans multiple lines in
2490 the input file.
2491 • If multiple opening tokens have been 'welded' together with the
2493 -wn parameter, then this parameter has no effect.
2494 • The indentation of the braces will normally be one level of
2496 continuation indentation by default. This can be changed with
2497 the parameter -bbhbi=n in the next section.
2498 • Similar flags for controlling parens and square brackets are
2500 given in the subsequent section.
2501 -bbhbi=n, --break-before-hash-brace-and-indent=n
2503 This flag is a companion to -bbhb=n for controlling the indentation
2504 of an opening hash brace which is placed on a new line by that
2505 parameter. The indentation is as follows:
2506 -bbhbi=0 one continuation level [default]
2508 -bbhbi=1 outdent by one continuation level
2509 -bbhbi=2 indent one full indentation level
2510 For example:
2512 # perltidy -bbhb=3 -bbhbi=1
2514 $romanNumerals =
2515 {
2516 one => 'I',
2517 two => 'II',
2518 three => 'III',
2519 four => 'IV',
2520 };
2521 # perltidy -bbhb=3 -bbhbi=2
2523 $romanNumerals =
2524 {
2525 one => 'I',
2526 two => 'II',
2527 three => 'III',
2528 four => 'IV',
2529 };
2530 Note that this parameter has no effect unless -bbhb=n is also set.
2532 -bbsb=n, --break-before-square-bracket=n
2534 This flag is similar to the flag described above, except it applies
2535 to lists contained within square brackets.
2536 -bbsb=0 never break [default]
2538 -bbsb=1 stable: break if the input script had a break
2539 -bbsb=2 break if list is 'complex' (part of nested list structure)
2540 -bbsb=3 always break
2541 -bbsbi=n, --break-before-square-bracket-and-indent=n
2543 This flag is a companion to -bbsb=n for controlling the indentation
2544 of an opening square bracket which is placed on a new line by that
2545 parameter. The indentation is as follows:
2546 -bbsbi=0 one continuation level [default]
2548 -bbsbi=1 outdent by one continuation level
2549 -bbsbi=2 indent one full indentation level
2550 -bbp=n, --break-before-paren=n
2552 This flag is similar to -bbhb=n, described above, except it applies
2553 to lists contained within parens.
2554 -bbp=0 never break [default]
2556 -bbp=1 stable: break if the input script had a break
2557 -bpb=2 break if list is 'complex' (part of nested list structure)
2558 -bbp=3 always break
2559 -bbpi=n, --break-before-paren-and-indent=n
2561 This flag is a companion to -bbp=n for controlling the indentation
2562 of an opening paren which is placed on a new line by that
2563 parameter. The indentation is as follows:
2564 -bbpi=0 one continuation level [default]
2566 -bbpi=1 outdent by one continuation level
2567 -bbpi=2 indent one full indentation level
2568 Welding
2570 -wn, --weld-nested-containers
2571 The -wn flag causes closely nested pairs of opening and closing
2572 container symbols (curly braces, brackets, or parens) to be
2573 "welded" together, meaning that they are treated as if combined
2574 into a single unit, with the indentation of the innermost code
2575 reduced to be as if there were just a single container symbol.
2576 For example:
2578 # default formatting
2580 do {
2581 {
2582 next if $x == $y;
2583 }
2584 } until $x++ > $z;
2585 # perltidy -wn
2587 do { {
2588 next if $x == $y;
2589 } } until $x++ > $z;
2590 When this flag is set perltidy makes a preliminary pass through the
2592 file and identifies all nested pairs of containers. To qualify as
2593 a nested pair, the closing container symbols must be immediately
2594 adjacent and the opening symbols must either (1) be adjacent as in
2595 the above example, or (2) have an anonymous sub declaration
2596 following an outer opening container symbol which is not a code
2597 block brace, or (3) have an outer opening paren separated from the
2598 inner opening symbol by any single non-container symbol or
2599 something that looks like a function evaluation, as illustrated in
2600 the next examples. An additional option (4) which can be turned on
2601 with the flag --weld-fat-comma is when the opening container
2602 symbols are separated by a hash key and fat comma (=>).
2603 Any container symbol may serve as both the inner container of one
2605 pair and as the outer container of an adjacent pair. Consequently,
2606 any number of adjacent opening or closing symbols may join together
2607 in weld. For example, here are three levels of wrapped function
2608 calls:
2609 # default formatting
2611 my (@date_time) = Localtime(
2612 Date_to_Time(
2613 Add_Delta_DHMS(
2614 $year, $month, $day, $hour, $minute, $second,
2615 '0', $offset, '0', '0'
2616 )
2617 )
2618 );
2619 # perltidy -wn
2621 my (@date_time) = Localtime( Date_to_Time( Add_Delta_DHMS(
2622 $year, $month, $day, $hour, $minute, $second,
2623 '0', $offset, '0', '0'
2624 ) ) );
2625 Notice how the indentation of the inner lines are reduced by two
2627 levels in this case. This example also shows the typical result of
2628 this formatting, namely it is a sandwich consisting of an initial
2629 opening layer, a central section of any complexity forming the
2630 "meat" of the sandwich, and a final closing layer. This
2631 predictable structure helps keep the compacted structure readable.
2632 The inner sandwich layer is required to be at least one line thick.
2634 If this cannot be achieved, welding does not occur. This
2635 constraint can cause formatting to take a couple of iterations to
2636 stabilize when it is first applied to a script. The -conv flag can
2637 be used to insure that the final format is achieved in a single
2638 run.
2639 Here is an example illustrating a welded container within a welded
2641 containers:
2642 # default formatting
2644 $x->badd(
2645 bmul(
2646 $class->new(
2647 abs(
2648 $sx * int( $xr->numify() ) & $sy * int( $yr->numify() )
2649 )
2650 ),
2651 $m
2652 )
2653 );
2654 # perltidy -wn
2656 $x->badd( bmul(
2657 $class->new( abs(
2658 $sx * int( $xr->numify() ) & $sy * int( $yr->numify() )
2659 ) ),
2660 $m
2661 ) );
2662 The welded closing tokens are by default on a separate line but
2664 this can be modified with the -vtc=n flag (described in the next
2665 section). For example, the same example adding -vtc=2 is
2666 # perltidy -wn -vtc=2
2668 $x->badd( bmul(
2669 $class->new( abs(
2670 $sx * int( $xr->numify() ) & $sy * int( $yr->numify() ) ) ),
2671 $m ) );
2672 This format option is quite general but there are some limitations.
2674 One limitation is that any line length limit still applies and can
2676 cause long welded sections to be broken into multiple lines.
2677 Another limitation is that an opening symbol which delimits quoted
2679 text cannot be included in a welded pair. This is because quote
2680 delimiters are treated specially in perltidy.
2681 Finally, the stacking of containers defined by this flag have
2683 priority over any other container stacking flags. This is because
2684 any welding is done first.
2685 -wfc, --weld-fat-comma
2687 When the -wfc flag is set, along with -wn, perltidy is allowed to
2688 weld an opening paren to an inner opening container when they are
2689 separated by a hash key and fat comma (=>). for example
2690 # perltidy -wn -wfc
2692 elf->call_method( method_name_foo => {
2693 some_arg1 => $foo,
2694 some_other_arg3 => $bar->{'baz'},
2695 } );
2696 This option is off by default.
2698 -wnxl=s, --weld-nested-exclusion-list
2700 The -wnxl=s flag provides some control over the types of containers
2701 which can be welded. The -wn flag by default is "greedy" in
2702 welding adjacent containers. If it welds more types of containers
2703 than desired, this flag provides a capability to reduce the amount
2704 of welding by specifying a list of things which should not be
2705 welded.
2706 The logic in perltidy to apply this is straightforward. As each
2708 container token is being considered for joining a weld, any
2709 exclusion rules are consulted and used to reject the weld if
2710 necessary.
2711 This list is a string with space-separated items. Each item
2713 consists of up to three pieces of information: (1) an optional
2714 position, (2) an optional preceding type, and (3) a container type.
2715 The only required piece of information is a container type, which
2717 is one of '(', '[', '{' or 'q'. The first three of these are
2718 container tokens and the last represents a quoted list. For
2719 example the string
2720 -wnxl='[ { q'
2722 means do NOT include square-brackets, braces, or quotes in any
2724 welds. The only unspecified container is '(', so this string means
2725 that only welds involving parens will be made.
2726 To illustrate, following welded snippet consists of a chain of
2728 three welded containers with types '(' '[' and 'q':
2729 # perltidy -wn
2731 skip_symbols( [ qw(
2732 Perl_dump_fds
2733 Perl_ErrorNo
2734 Perl_GetVars
2735 PL_sys_intern
2736 ) ] );
2737 Even though the qw term uses parens as the quote delimiter, it has
2739 a special type 'q' here. If it appears in a weld it always appears
2740 at the end of the welded chain.
2741 Any of the container types '[', '{', and '(' may be prefixed with a
2743 position indicator which is either '^', to indicate the first token
2744 of a welded sequence, or '.', to indicate an interior token of a
2745 welded sequence. (Since a quoted string 'q' always ends a chain it
2746 does need a position indicator).
2747 For example, if we do not want a sequence of welded containers to
2749 start with a square bracket we could use
2750 -wnxl='^['
2752 In the above snippet, there is a square bracket but it does not
2754 start the chain, so the formatting would be unchanged if it were
2755 formatted with this restriction.
2756 A third optional item of information which can be given is an
2758 alphanumeric letter which is used to limit the selection further
2759 depending on the type of token immediately before the container.
2760 If given, it goes just before the container symbol. The possible
2761 letters are currently 'k', 'K', 'f', 'F', 'w', and 'W', with these
2762 meanings:
2763 'k' matches if the previous nonblank token is a perl built-in keyword (such as 'if', 'while'),
2765 'K' matches if 'k' does not, meaning that the previous token is not a keyword.
2766 'f' matches if the previous token is a function other than a keyword.
2767 'F' matches if 'f' does not.
2768 'w' matches if either 'k' or 'f' match.
2769 'W' matches if 'w' does not.
2770 For example, compare
2772 # perltidy -wn
2774 if ( defined( $_Cgi_Query{
2775 $Config{'methods'}{'authentication'}{'remote'}{'cgi'}{'username'}
2776 } ) )
2777 with
2779 # perltidy -wn -wnxl='^K( {'
2781 if ( defined(
2782 $_Cgi_Query{ $Config{'methods'}{'authentication'}{'remote'}{'cgi'}
2783 {'username'} }
2784 ) )
2785 The first case does maximum welding. In the second case the leading
2787 paren is retained by the rule (it would have been rejected if
2788 preceded by a non-keyword) but the curly brace is rejected by the
2789 rule.
2790 Here are some additional example strings and their meanings:
2792 '^(' - the weld must not start with a paren
2794 '.(' - the second and later tokens may not be parens
2795 '.w(' - the second and later tokens may not keyword or function call parens
2796 '(' - no parens in a weld
2797 '^K(' - exclude a leading paren preceded by a non-keyword
2798 '.k(' - exclude a secondary paren preceded by a keyword
2799 '[ {' - exclude all brackets and braces
2800 '[ ( ^K{' - exclude everything except nested structures like do {{ ... }}
2801 Vertical tightness of non-block curly braces, parentheses, and square
2803 brackets.
2804 These parameters control what shall be called vertical tightness.
2805 Here are the main points:
2806 • Opening tokens (except for block braces) are controlled by
2808 -vt=n, or --vertical-tightness=n, where
2809 -vt=0 always break a line after opening token (default).
2811 -vt=1 do not break unless this would produce more than one
2812 step in indentation in a line.
2813 -vt=2 never break a line after opening token
2814 • You must also use the -lp flag when you use the -vt flag; the
2816 reason is explained below.
2817 • Closing tokens (except for block braces) are controlled by
2819 -vtc=n, or --vertical-tightness-closing=n, where
2820 -vtc=0 always break a line before a closing token (default),
2822 -vtc=1 do not break before a closing token which is followed
2823 by a semicolon or another closing token, and is not in
2824 a list environment.
2825 -vtc=2 never break before a closing token.
2826 -vtc=3 Like -vtc=1 except always break before a closing token
2827 if the corresponding opening token follows an = or =>.
2828 The rules for -vtc=1 and -vtc=3 are designed to maintain a
2830 reasonable balance between tightness and readability in complex
2831 lists.
2832 • Different controls may be applied to different token types, and
2834 it is also possible to control block braces; see below.
2835 • Finally, please note that these vertical tightness flags are
2837 merely hints to the formatter, and it cannot always follow
2838 them. Things which make it difficult or impossible include
2839 comments, blank lines, blocks of code within a list, and
2840 possibly the lack of the -lp parameter. Also, these flags may
2841 be ignored for very small lists (2 or 3 lines in length).
2842 Here are some examples:
2844 # perltidy -lp -vt=0 -vtc=0
2846 %romanNumerals = (
2847 one => 'I',
2848 two => 'II',
2849 three => 'III',
2850 four => 'IV',
2851 );
2852 # perltidy -lp -vt=1 -vtc=0
2854 %romanNumerals = ( one => 'I',
2855 two => 'II',
2856 three => 'III',
2857 four => 'IV',
2858 );
2859 # perltidy -lp -vt=1 -vtc=1
2861 %romanNumerals = ( one => 'I',
2862 two => 'II',
2863 three => 'III',
2864 four => 'IV', );
2865 # perltidy -vtc=3
2867 my_function(
2868 one => 'I',
2869 two => 'II',
2870 three => 'III',
2871 four => 'IV', );
2872 # perltidy -vtc=3
2874 %romanNumerals = (
2875 one => 'I',
2876 two => 'II',
2877 three => 'III',
2878 four => 'IV',
2879 );
2880 In the last example for -vtc=3, the opening paren is preceded by an
2882 equals so the closing paren is placed on a new line.
2883 The difference between -vt=1 and -vt=2 is shown here:
2885 # perltidy -lp -vt=1
2887 $init->add(
2888 mysprintf( "(void)find_threadsv(%s);",
2889 cstring( $threadsv_names[ $op->targ ] )
2890 )
2891 );
2892 # perltidy -lp -vt=2
2894 $init->add( mysprintf( "(void)find_threadsv(%s);",
2895 cstring( $threadsv_names[ $op->targ ] )
2896 )
2897 );
2898 With -vt=1, the line ending in "add(" does not combine with the
2900 next line because the next line is not balanced. This can help
2901 with readability, but -vt=2 can be used to ignore this rule.
2902 The tightest, and least readable, code is produced with both
2904 "-vt=2" and "-vtc=2":
2905 # perltidy -lp -vt=2 -vtc=2
2907 $init->add( mysprintf( "(void)find_threadsv(%s);",
2908 cstring( $threadsv_names[ $op->targ ] ) ) );
2909 Notice how the code in all of these examples collapses vertically
2911 as -vt increases, but the indentation remains unchanged. This is
2912 because perltidy implements the -vt parameter by first formatting
2913 as if -vt=0, and then simply overwriting one output line on top of
2914 the next, if possible, to achieve the desired vertical tightness.
2915 The -lp indentation style has been designed to allow this vertical
2916 collapse to occur, which is why it is required for the -vt
2917 parameter.
2918 The -vt=n and -vtc=n parameters apply to each type of container
2920 token. If desired, vertical tightness controls can be applied
2921 independently to each of the closing container token types.
2922 The parameters for controlling parentheses are -pvt=n or
2924 --paren-vertical-tightness=n, and -pvtc=n or
2925 --paren-vertical-tightness-closing=n.
2926 Likewise, the parameters for square brackets are -sbvt=n or
2928 --square-bracket-vertical-tightness=n, and -sbvtc=n or
2929 --square-bracket-vertical-tightness-closing=n.
2930 Finally, the parameters for controlling non-code block braces are
2932 -bvt=n or --brace-vertical-tightness=n, and -bvtc=n or
2933 --brace-vertical-tightness-closing=n.
2934 In fact, the parameter -vt=n is actually just an abbreviation for
2936 -pvt=n -bvt=n sbvt=n, and likewise -vtc=n is an abbreviation for
2937 -pvtc=n -bvtc=n -sbvtc=n.
2938 -bbvt=n or --block-brace-vertical-tightness=n
2940 The -bbvt=n flag is just like the -vt=n flag but applies to opening
2941 code block braces.
2942 -bbvt=0 break after opening block brace (default).
2944 -bbvt=1 do not break unless this would produce more than one
2945 step in indentation in a line.
2946 -bbvt=2 do not break after opening block brace.
2947 It is necessary to also use either -bl or -bli for this to work,
2949 because, as with other vertical tightness controls, it is
2950 implemented by simply overwriting a line ending with an opening
2951 block brace with the subsequent line. For example:
2952 # perltidy -bli -bbvt=0
2954 if ( open( FILE, "< $File" ) )
2955 {
2956 while ( $File = <FILE> )
2957 {
2958 $In .= $File;
2959 $count++;
2960 }
2961 close(FILE);
2962 }
2963 # perltidy -bli -bbvt=1
2965 if ( open( FILE, "< $File" ) )
2966 { while ( $File = <FILE> )
2967 { $In .= $File;
2968 $count++;
2969 }
2970 close(FILE);
2971 }
2972 By default this applies to blocks associated with keywords if,
2974 elsif, else, unless, for, foreach, sub, while, until, and also with
2975 a preceding label. This can be changed with the parameter
2976 -bbvtl=string, or --block-brace-vertical-tightness-list=string,
2977 where string is a space-separated list of block types. For more
2978 information on the possible values of this string, see "Specifying
2979 Block Types"
2980 For example, if we want to just apply this style to "if", "elsif",
2982 and "else" blocks, we could use "perltidy -bli -bbvt=1 -bbvtl='if
2983 elsif else'".
2984 There is no vertical tightness control for closing block braces;
2986 with one exception they will be placed on separate lines. The
2987 exception is that a cascade of closing block braces may be stacked
2988 on a single line. See -scbb.
2989 -sot, --stack-opening-tokens and related flags
2991 The -sot flag tells perltidy to "stack" opening tokens when
2992 possible to avoid lines with isolated opening tokens.
2993 For example:
2995 # default
2997 $opt_c = Text::CSV_XS->new(
2998 {
2999 binary => 1,
3000 sep_char => $opt_c,
3001 always_quote => 1,
3002 }
3003 );
3004 # -sot
3006 $opt_c = Text::CSV_XS->new( {
3007 binary => 1,
3008 sep_char => $opt_c,
3009 always_quote => 1,
3010 }
3011 );
3012 For detailed control of individual closing tokens the following
3014 controls can be used:
3015 -sop or --stack-opening-paren
3017 -sohb or --stack-opening-hash-brace
3018 -sosb or --stack-opening-square-bracket
3019 -sobb or --stack-opening-block-brace
3020 The flag -sot is an abbreviation for -sop -sohb -sosb.
3022 The flag -sobb is an abbreviation for -bbvt=2 -bbvtl='*'. This
3024 will case a cascade of opening block braces to appear on a single
3025 line, although this an uncommon occurrence except in test scripts.
3026 -sct, --stack-closing-tokens and related flags
3028 The -sct flag tells perltidy to "stack" closing tokens when
3029 possible to avoid lines with isolated closing tokens.
3030 For example:
3032 # default
3034 $opt_c = Text::CSV_XS->new(
3035 {
3036 binary => 1,
3037 sep_char => $opt_c,
3038 always_quote => 1,
3039 }
3040 );
3041 # -sct
3043 $opt_c = Text::CSV_XS->new(
3044 {
3045 binary => 1,
3046 sep_char => $opt_c,
3047 always_quote => 1,
3048 } );
3049 The -sct flag is somewhat similar to the -vtc flags, and in some
3051 cases it can give a similar result. The difference is that the
3052 -vtc flags try to avoid lines with leading opening tokens by
3053 "hiding" them at the end of a previous line, whereas the -sct flag
3054 merely tries to reduce the number of lines with isolated closing
3055 tokens by stacking them but does not try to hide them. For
3056 example:
3057 # -vtc=2
3059 $opt_c = Text::CSV_XS->new(
3060 {
3061 binary => 1,
3062 sep_char => $opt_c,
3063 always_quote => 1, } );
3064 For detailed control of the stacking of individual closing tokens
3066 the following controls can be used:
3067 -scp or --stack-closing-paren
3069 -schb or --stack-closing-hash-brace
3070 -scsb or --stack-closing-square-bracket
3071 -scbb or --stack-closing-block-brace
3072 The flag -sct is an abbreviation for stacking the non-block closing
3074 tokens, -scp -schb -scsb.
3075 Stacking of closing block braces, -scbb, causes a cascade of
3077 isolated closing block braces to be combined into a single line as
3078 in the following example:
3079 # -scbb:
3081 for $w1 (@w1) {
3082 for $w2 (@w2) {
3083 for $w3 (@w3) {
3084 for $w4 (@w4) {
3085 push( @lines, "$w1 $w2 $w3 $w4\n" );
3086 } } } }
3087 To simplify input even further for the case in which both opening
3089 and closing non-block containers are stacked, the flag -sac or
3090 --stack-all-containers is an abbreviation for -sot -sct.
3091 Please note that if both opening and closing tokens are to be
3093 stacked, then the newer flag -weld-nested-containers may be
3094 preferable because it insures that stacking is always done
3095 symmetrically. It also removes an extra level of unnecessary
3096 indentation within welded containers. It is able to do this
3097 because it works on formatting globally rather than locally, as the
3098 -sot and -sct flags do.
3099 Breaking Before or After Operators
3101 Four command line parameters provide some control over whether a line
3102 break should be before or after specific token types. Two parameters
3103 give detailed control:
3104 -wba=s or --want-break-after=s, and
3106 -wbb=s or --want-break-before=s.
3108 These parameters are each followed by a quoted string, s, containing a
3110 list of token types (separated only by spaces). No more than one of
3111 each of these parameters should be specified, because repeating a
3112 command-line parameter always overwrites the previous one before
3113 perltidy ever sees it.
3114 By default, perltidy breaks after these token types:
3116 % + - * / x != == >= <= =~ !~ < > | &
3117 = **= += *= &= <<= &&= -= /= |= >>= ||= //= .= %= ^= x=
3118 And perltidy breaks before these token types by default:
3120 . << >> -> && || //
3121 To illustrate, to cause a break after a concatenation operator, '.',
3123 rather than before it, the command line would be
3124 -wba="."
3126 As another example, the following command would cause a break before
3128 math operators '+', '-', '/', and '*':
3129 -wbb="+ - / *"
3131 These commands should work well for most of the token types that
3133 perltidy uses (use --dump-token-types for a list). Also try the -D
3134 flag on a short snippet of code and look at the .DEBUG file to see the
3135 tokenization. However, for a few token types there may be conflicts
3136 with hardwired logic which cause unexpected results. One example is
3137 curly braces, which should be controlled with the parameter bl provided
3138 for that purpose.
3139 WARNING Be sure to put these tokens in quotes to avoid having them
3141 misinterpreted by your command shell.
3142 Two additional parameters are available which, though they provide no
3144 further capability, can simplify input are:
3145 -baao or --break-after-all-operators,
3147 -bbao or --break-before-all-operators.
3149 The -baao sets the default to be to break after all of the following
3151 operators:
3152 % + - * / x != == >= <= =~ !~ < > | &
3154 = **= += *= &= <<= &&= -= /= |= >>= ||= //= .= %= ^= x=
3155 . : ? && || and or err xor
3156 and the -bbao flag sets the default to break before all of these
3158 operators. These can be used to define an initial break preference
3159 which can be fine-tuned with the -wba and -wbb flags. For example, to
3160 break before all operators except an = one could use --bbao -wba='='
3161 rather than listing every single perl operator except = on a -wbb flag.
3162 -bal=n, --break-after-labels=n
3164 This flag controls whether or not a line break occurs after a
3165 label. There are three possible values for n:
3166 -bal=0 break if there is a break in the input [DEFAULT]
3168 -bal=1 always break after a label
3169 -bal=2 never break after a label
3170 For example,
3172 # perltidy -bal=1
3174 RETURN:
3175 return;
3176 # perltidy -bal=2
3178 RETURN: return;
3179 Controlling List Formatting
3181 Perltidy attempts to format lists of comma-separated values in tables
3182 which look good. Its default algorithms usually work well, but
3183 sometimes they don't. In this case, there are several methods
3184 available to control list formatting.
3185 A very simple way to prevent perltidy from changing the line breaks
3187 within a comma-separated list of values is to insert a blank line,
3188 comment, or side-comment anywhere between the opening and closing
3189 parens (or braces or brackets). This causes perltidy to skip over its
3190 list formatting logic. (The reason is that any of these items put a
3191 constraint on line breaks, and perltidy needs complete control over
3192 line breaks within a container to adjust a list layout). For example,
3193 let us consider
3194 my @list = (1,
3196 1, 1,
3197 1, 2, 1,
3198 1, 3, 3, 1,
3199 1, 4, 6, 4, 1,);
3200 The default formatting, which allows a maximum line length of 80, will
3202 flatten this down to one line:
3203 # perltidy (default)
3205 my @list = ( 1, 1, 1, 1, 2, 1, 1, 3, 3, 1, 1, 4, 6, 4, 1, );
3206 This formatting loses the nice structure. If we place a side comment
3208 anywhere between the opening and closing parens, the original line
3209 break points are retained. For example,
3210 my @list = (
3212 1, # a side comment forces the original line breakpoints to be kept
3213 1, 1,
3214 1, 2, 1,
3215 1, 3, 3, 1,
3216 1, 4, 6, 4, 1,
3217 );
3218 The side comment can be a single hash symbol without any text. We
3220 could achieve the same result with a blank line or full comment
3221 anywhere between the opening and closing parens. Vertical alignment of
3222 the list items will still occur if possible.
3223 For another possibility see the -fs flag in "Skipping Selected Sections
3225 of Code".
3226 -boc, --break-at-old-comma-breakpoints
3228 The -boc flag is another way to prevent comma-separated lists from
3229 being reformatted. Using -boc on the above example, plus
3230 additional flags to retain the original style, yields
3231 # perltidy -boc -lp -pt=2 -vt=1 -vtc=1
3233 my @list = (1,
3234 1, 1,
3235 1, 2, 1,
3236 1, 3, 3, 1,
3237 1, 4, 6, 4, 1,);
3238 A disadvantage of this flag compared to the methods discussed above
3240 is that all tables in the file must already be nicely formatted.
3241 -mft=n, --maximum-fields-per-table=n
3243 If n is a positive number, and the computed number of fields for
3244 any table exceeds n, then it will be reduced to n. This parameter
3245 might be used on a small section of code to force a list to have a
3246 particular number of fields per line, and then either the -boc flag
3247 could be used to retain this formatting, or a single comment could
3248 be introduced somewhere to freeze the formatting in future
3249 applications of perltidy. For example
3250 # perltidy -mft=2
3252 @month_of_year = (
3253 'Jan', 'Feb',
3254 'Mar', 'Apr',
3255 'May', 'Jun',
3256 'Jul', 'Aug',
3257 'Sep', 'Oct',
3258 'Nov', 'Dec'
3259 );
3260 The default value is n=0, which does not place a limit on the
3262 number of fields in a table.
3263 -cab=n, --comma-arrow-breakpoints=n
3265 A comma which follows a comma arrow, '=>', is given special
3266 consideration. In a long list, it is common to break at all such
3267 commas. This parameter can be used to control how perltidy breaks
3268 at these commas. (However, it will have no effect if old comma
3269 breaks are being forced because -boc is used). The possible values
3270 of n are:
3271 n=0 break at all commas after =>
3273 n=1 stable: break at all commas after => if container is open,
3274 EXCEPT FOR one-line containers
3275 n=2 break at all commas after =>, BUT try to form the maximum
3276 one-line container lengths
3277 n=3 do not treat commas after => specially at all
3278 n=4 break everything: like n=0 but ALSO break a short container with
3279 a => not followed by a comma when -vt=0 is used
3280 n=5 stable: like n=1 but ALSO break at open one-line containers when
3281 -vt=0 is used (default)
3282 For example, given the following single line, perltidy by default
3284 will not add any line breaks because it would break the existing
3285 one-line container:
3286 bless { B => $B, Root => $Root } => $package;
3288 Using -cab=0 will force a break after each comma-arrow item:
3290 # perltidy -cab=0:
3292 bless {
3293 B => $B,
3294 Root => $Root
3295 } => $package;
3296 If perltidy is subsequently run with this container broken, then by
3298 default it will break after each '=>' because the container is now
3299 broken. To reform a one-line container, the parameter -cab=2 could
3300 be used.
3301 The flag -cab=3 can be used to prevent these commas from being
3303 treated specially. In this case, an item such as "01" => 31 is
3304 treated as a single item in a table. The number of fields in this
3305 table will be determined by the same rules that are used for any
3306 other table. Here is an example.
3307 # perltidy -cab=3
3309 my %last_day = (
3310 "01" => 31, "02" => 29, "03" => 31, "04" => 30,
3311 "05" => 31, "06" => 30, "07" => 31, "08" => 31,
3312 "09" => 30, "10" => 31, "11" => 30, "12" => 31
3313 );
3314 Adding and Deleting Commas
3316 -drc, --delete-repeated-commas
3317 Repeated commas in a list are undesirable and can be removed with
3318 this flag. For example, given this list with a repeated comma
3319 ignoreSpec( $file, "file",, \%spec, \%Rspec );
3321 we can remove it with -drc
3323 # perltidy -drc:
3325 ignoreSpec( $file, "file", \%spec, \%Rspec );
3326 Since the default is not to add or delete commas, this feature is
3328 off by default and must be requested.
3329 --want-trailing-commas=s or -wtc=s, --add-trailing-commas or -atc, and
3331 --delete-trailing-commas or -dtc
3332 A trailing comma is a comma following the last item of a list. Perl
3333 allows trailing commas but they are not required. By default,
3334 perltidy does not add or delete trailing commas, but it is possible
3335 to manipulate them with the following set of three related
3336 parameters:
3337 --want-trailing-commas=s, -wtc=s - defines where trailing commas are wanted
3339 --add-trailing-commas, -atc - gives permission to add trailing commas to match the style wanted
3340 --delete-trailing-commas, -dtc - gives permission to delete trailing commas which do not match the style wanted
3341 The parameter --want-trailing-commas=s, or -wtc=s, defines a
3343 preferred style. The string s indicates which lists should get
3344 trailing commas, as follows:
3345 s=0 : no list should have a trailing comma
3347 s=1 or * : every list should have a trailing comma
3348 s=m a multi-line list should have a trailing commas
3349 s=b trailing commas should be 'bare' (comma followed by newline)
3350 s=h lists of key=>value pairs, with about one one '=>' and one ',' per line,
3351 with a bare trailing comma
3352 s=i lists with about one comma per line, with a bare trailing comma
3353 s=' ' or -wtc not defined : leave trailing commas unchanged [DEFAULT].
3354 This parameter by itself only indicates the where trailing commas
3356 are wanted. Perltidy only adds these trailing commas if the flag
3357 --add-trailing-commas, or -atc is set. And perltidy only removes
3358 unwanted trailing commas if the flag --delete-trailing-commas, or
3359 -dtc is set.
3360 Here are some example parameter combinations and their meanings
3362 -wtc=0 -dtc : delete all trailing commas
3364 -wtc=1 -atc : all lists get trailing commas
3365 -wtc=m -atc : all multi-line lists get trailing commas, but
3366 single line lists remain unchanged.
3367 -wtc=m -dtc : multi-line lists remain unchanged, but
3368 any trailing commas on single line lists are removed.
3369 -wtc=m -atc -dtc : all multi-line lists get trailing commas, and
3370 any trailing commas on single line lists are removed.
3371 For example, given the following input without a trailing comma
3373 bless {
3375 B => $B,
3376 Root => $Root
3377 } => $package;
3378 we can add a trailing comma after the variable $Root using
3380 # perltidy -wtc=m -atc
3382 bless {
3383 B => $B,
3384 Root => $Root,
3385 } => $package;
3386 This could also be achieved in this case with -wtc=b instead of
3388 -wtc=m because the trailing comma here is bare (separated from its
3389 closing brace by a newline). And it could also be achieved with
3390 -wtc=h because this particular list is a list of key=>value pairs.
3391 The above styles should cover the main of situations of interest,
3393 but it is possible to apply a different style to each type of
3394 container token by including an opening token ahead of the style
3395 character in the above table. For example
3396 -wtc='(m [b'
3398 means that lists within parens should have multi-line trailing
3400 commas, and that lists within square brackets have bare trailing
3401 commas. Since there is no specification for curly braces in this
3402 example, their trailing commas would remain unchanged.
3403 For parentheses, an additional item of information which can be
3405 given is an alphanumeric letter which is used to limit the
3406 selection further depending on the type of token immediately before
3407 the opening paren. The possible letters are currently 'k', 'K',
3408 'f', 'F', 'w', and 'W', with these meanings for matching whatever
3409 precedes an opening paren:
3410 'k' matches if the previous nonblank token is a perl built-in keyword (such as 'if', 'while'),
3412 'K' matches if 'k' does not, meaning that the previous token is not a keyword.
3413 'f' matches if the previous token is a function other than a keyword.
3414 'F' matches if 'f' does not.
3415 'w' matches if either 'k' or 'f' match.
3416 'W' matches if 'w' does not.
3417 These are the same codes used for
3419 --line-up-parentheses-inclusion-list. For example,
3420 -wtc = 'w(m'
3422 means that trailing commas are wanted for multi-line parenthesized
3424 lists following a function call or keyword.
3425 Here are some points to note regarding adding and deleting trailing
3427 commas:
3428 • For the implementation of these parameters, a list is basically
3430 taken to be a container of items (parens, square brackets, or
3431 braces), which is not a code block, with one or more commas.
3432 These parameters only apply to something that fits this
3433 definition of a list.
3434 Note that a paren-less list of parameters is not a list by this
3436 definition, so these parameters have no effect on a peren-less
3437 list.
3438 Another consequence is that if the only comma in a list is
3440 deleted, then it cannot later be added back with these
3441 parameters because the container no longer fits this definition
3442 of a list. For example, given
3443 my ( $self, ) = @_;
3445 and if we remove the comma with
3447 # perltidy -wtc=m -dtc
3449 my ( $self ) = @_;
3450 then we cannot use these trailing comma controls to add this
3452 comma back.
3453 • By multiline list is meant a list for which the first comma and
3455 trailing comma are on different lines.
3456 • A bare trailing comma is a comma which is at the end of a line.
3458 That is, the closing container token follows on a different
3459 line. So a list with a bare trailing comma is a special case
3460 of a multi-line list.
3461 • The decision regarding whether or not a list is multi-line or
3463 bare is made based on the input stream. In some cases it may
3464 take an iteration or two to reach a final state.
3465 • When using these parameters for the first time it is a good
3467 idea to practice on some test scripts and verify that the
3468 results are as expected.
3469 • Since the default behavior is not to add or delete commas,
3471 these parameters can be useful on a temporary basis for
3472 reformatting a script.
3473 -dwic, --delete-weld-interfering-commas
3475 If the closing tokens of two nested containers are separated by a
3476 comma, then welding requested with --weld-nested-containers cannot
3477 occur. Any commas in this situation are optional trailing commas
3478 and can be removed with -dwic. For example, a comma in this script
3479 prevents welding:
3480 # perltidy -wn
3482 skip_symbols(
3483 [ qw(
3484 Perl_dump_fds
3485 Perl_ErrorNo
3486 Perl_GetVars
3487 PL_sys_intern
3488 ) ],
3489 );
3490 Using -dwic removes the comma and allows welding:
3492 # perltidy -wn -dwic
3494 skip_symbols( [ qw(
3495 Perl_dump_fds
3496 Perl_ErrorNo
3497 Perl_GetVars
3498 PL_sys_intern
3499 ) ] );
3500 Since the default is not to add or delete commas, this feature is
3502 off by default. Here are some points to note about the -dwic
3503 parameter
3504 • This operation is not reversible, so please check results of
3506 using this parameter carefully.
3507 • Removing this type of isolated trailing comma is necessary for
3509 welding to be possible, but not sufficient. So welding will
3510 not always occur where these commas are removed.
3511 Retaining or Ignoring Existing Line Breaks
3513 Several additional parameters are available for controlling the extent
3514 to which line breaks in the input script influence the output script.
3515 In most cases, the default parameter values are set so that, if a
3516 choice is possible, the output style follows the input style. For
3517 example, if a short logical container is broken in the input script,
3518 then the default behavior is for it to remain broken in the output
3519 script.
3520 Most of the parameters in this section would only be required for a
3522 one-time conversion of a script from short container lengths to longer
3523 container lengths. The opposite effect, of converting long container
3524 lengths to shorter lengths, can be obtained by temporarily using a
3525 short maximum line length.
3526 -bol, --break-at-old-logical-breakpoints
3528 By default, if a logical expression is broken at a "&&", "||",
3529 "and", or "or", then the container will remain broken. Also,
3530 breaks at internal keywords "if" and "unless" will normally be
3531 retained. To prevent this, and thus form longer lines, use -nbol.
3532 Please note that this flag does not duplicate old logical
3534 breakpoints. They are merely used as a hint with this flag that a
3535 statement should remain broken. Without this flag, perltidy will
3536 normally try to combine relatively short expressions into a single
3537 line.
3538 For example, given this snippet:
3540 return unless $cmd = $cmd || ($dot
3542 && $Last_Shell) || &prompt('|');
3543 # perltidy -bol [default]
3545 return
3546 unless $cmd = $cmd
3547 || ( $dot
3548 && $Last_Shell )
3549 || &prompt('|');
3550 # perltidy -nbol
3552 return unless $cmd = $cmd || ( $dot && $Last_Shell ) || &prompt('|');
3553 -bom, --break-at-old-method-breakpoints
3555 By default, a method call arrow "->" is considered a candidate for
3556 a breakpoint, but method chains will fill to the line width before
3557 a break is considered. With -bom, breaks before the arrow are
3558 preserved, so if you have pre-formatted a method chain:
3559 my $q = $rs
3561 ->related_resultset('CDs')
3562 ->related_resultset('Tracks')
3563 ->search({
3564 'track.id' => {-ident => 'none_search.id'},
3565 })->as_query;
3566 It will keep these breaks, rather than become this:
3568 my $q = $rs->related_resultset('CDs')->related_resultset('Tracks')->search({
3570 'track.id' => {-ident => 'none_search.id'},
3571 })->as_query;
3572 This flag will also look for and keep a 'cuddled' style of calls,
3574 in which lines begin with a closing paren followed by a call arrow,
3575 as in this example:
3576 # perltidy -bom -wn
3578 my $q = $rs->related_resultset(
3579 'CDs'
3580 )->related_resultset(
3581 'Tracks'
3582 )->search( {
3583 'track.id' => { -ident => 'none_search.id' },
3584 } )->as_query;
3585 You may want to include the -weld-nested-containers flag in this
3587 case to keep nested braces and parens together, as in the last
3588 line.
3589 -bos, --break-at-old-semicolon-breakpoints
3591 Semicolons are normally placed at the end of a statement. This
3592 means that formatted lines do not normally begin with semicolons.
3593 If the input stream has some lines which begin with semicolons,
3594 these can be retained by setting this flag. For example, consider
3595 the following two-line input snippet:
3596 $z = sqrt($x**2 + $y**2)
3598 ;
3599 The default formatting will be:
3601 $z = sqrt( $x**2 + $y**2 );
3603 The result using perltidy -bos keeps the isolated semicolon:
3605 $z = sqrt( $x**2 + $y**2 )
3607 ;
3608 The default is not to do this, -nbos.
3610 -bok, --break-at-old-keyword-breakpoints
3612 By default, perltidy will retain a breakpoint before keywords which
3613 may return lists, such as "sort" and <map>. This allows chains of
3614 these operators to be displayed one per line. Use -nbok to prevent
3615 retaining these breakpoints.
3616 -bot, --break-at-old-ternary-breakpoints
3618 By default, if a conditional (ternary) operator is broken at a ":",
3619 then it will remain broken. To prevent this, and thereby form
3620 longer lines, use -nbot.
3621 -boa, --break-at-old-attribute-breakpoints
3623 By default, if an attribute list is broken at a ":" in the source
3624 file, then it will remain broken. For example, given the following
3625 code, the line breaks at the ':'s will be retained:
3626 my @field
3628 : field
3629 : Default(1)
3630 : Get('Name' => 'foo') : Set('Name');
3631 If the attributes are on a single line in the source code then they
3633 will remain on a single line if possible.
3634 To prevent this, and thereby always form longer lines, use -nboa.
3636 Keeping old breakpoints at specific token types
3638 It is possible to override the choice of line breaks made by
3639 perltidy, and force it to follow certain line breaks in the input
3640 stream, with these two parameters:
3641 -kbb=s or --keep-old-breakpoints-before=s, and
3643 -kba=s or --keep-old-breakpoints-after=s
3645 These parameters are each followed by a quoted string, s,
3647 containing a list of token types (separated only by spaces). No
3648 more than one of each of these parameters should be specified,
3649 because repeating a command-line parameter always overwrites the
3650 previous one before perltidy ever sees it.
3651 For example, -kbb='=>' means that if an input line begins with a
3653 '=>' then the output script should also have a line break before
3654 that token.
3655 For example, given the script:
3657 method 'foo'
3659 => [ Int, Int ]
3660 => sub {
3661 my ( $self, $x, $y ) = ( shift, @_ );
3662 ...;
3663 };
3664 # perltidy [default]
3666 method 'foo' => [ Int, Int ] => sub {
3667 my ( $self, $x, $y ) = ( shift, @_ );
3668 ...;
3669 };
3670 # perltidy -kbb='=>'
3672 method 'foo'
3673 => [ Int, Int ]
3674 => sub {
3675 my ( $self, $x, $y ) = ( shift, @_ );
3676 ...;
3677 };
3678 For the container tokens '{', '[' and '(' and, their closing
3680 counterparts, use the token symbol. Thus, the command to keep a
3681 break after all opening parens is:
3682 perltidy -kba='('
3684 It is possible to be more specific in matching parentheses by
3686 preceding them with a letter. The possible letters are 'k', 'K',
3687 'f', 'F', 'w', and 'W', with these meanings (these are the same as
3688 used in the --weld-nested-exclusion-list and
3689 --line-up-parentheses-exclusion-list parameters):
3690 'k' matches if the previous nonblank token is a perl built-in keyword (such as 'if', 'while'),
3692 'K' matches if 'k' does not, meaning that the previous token is not a keyword.
3693 'f' matches if the previous token is a function other than a keyword.
3694 'F' matches if 'f' does not.
3695 'w' matches if either 'k' or 'f' match.
3696 'W' matches if 'w' does not.
3697 So for example the the following parameter will keep breaks after
3699 opening function call parens:
3700 perltidy -kba='f('
3702 NOTE: A request to break before an opening container, such as
3704 -kbb='(', will be silently ignored because it can lead to
3705 formatting instability. Likewise, a request to break after a
3706 closing container, such as -kba=')', will also be silently ignored.
3707 -iob, --ignore-old-breakpoints
3709 Use this flag to tell perltidy to ignore existing line breaks to
3710 the maximum extent possible. This will tend to produce the longest
3711 possible containers, regardless of type, which do not exceed the
3712 line length limit. But please note that this parameter has
3713 priority over all other parameters requesting that certain old
3714 breakpoints be kept.
3715 To illustrate, consider the following input text:
3717 has subcmds => (
3719 is => 'ro',
3720 default => sub { [] },
3721 );
3722 The default formatting will keep the container broken, giving
3724 # perltidy [default]
3726 has subcmds => (
3727 is => 'ro',
3728 default => sub { [] },
3729 );
3730 If old breakpoints are ignored, the list will be flattened:
3732 # perltidy -iob
3734 has subcmds => ( is => 'ro', default => sub { [] }, );
3735 Besides flattening lists, this parameter also applies to lines
3737 broken at certain logical breakpoints such as 'if' and 'or'.
3738 Even if this is parameter is not used globally, it provides a
3740 convenient way to flatten selected lists from within an editor.
3741 -kis, --keep-interior-semicolons
3743 Use the -kis flag to prevent breaking at a semicolon if there was
3744 no break there in the input file. Normally perltidy places a
3745 newline after each semicolon which terminates a statement unless
3746 several statements are contained within a one-line brace block. To
3747 illustrate, consider the following input lines:
3748 dbmclose(%verb_delim); undef %verb_delim;
3750 dbmclose(%expanded); undef %expanded;
3751 The default is to break after each statement, giving
3753 dbmclose(%verb_delim);
3755 undef %verb_delim;
3756 dbmclose(%expanded);
3757 undef %expanded;
3758 With perltidy -kis the multiple statements are retained:
3760 dbmclose(%verb_delim); undef %verb_delim;
3762 dbmclose(%expanded); undef %expanded;
3763 The statements are still subject to the specified value of maximum-
3765 line-length and will be broken if this maximum is exceeded.
3766 Blank Line Control
3768 Blank lines can improve the readability of a script if they are
3769 carefully placed. Perltidy has several commands for controlling the
3770 insertion, retention, and removal of blank lines.
3771 -fbl, --freeze-blank-lines
3773 Set -fbl if you want to the blank lines in your script to remain
3774 exactly as they are. The rest of the parameters in this section
3775 may then be ignored. (Note: setting the -fbl flag is equivalent to
3776 setting -mbl=0 and -kbl=2).
3777 -bbc, --blanks-before-comments
3779 A blank line will be introduced before a full-line comment. This
3780 is the default. Use -nbbc or --noblanks-before-comments to
3781 prevent such blank lines from being introduced.
3782 -blbs=n, --blank-lines-before-subs=n
3784 The parameter -blbs=n requests that least n blank lines precede a
3785 sub definition which does not follow a comment and which is more
3786 than one-line long. The default is <-blbs=1>. BEGIN and END
3787 blocks are included.
3788 The requested number of blanks statement will be inserted
3790 regardless of the value of --maximum-consecutive-blank-lines=n
3791 (-mbl=n) with the exception that if -mbl=0 then no blanks will be
3792 output.
3793 This parameter interacts with the value k of the parameter
3795 --maximum-consecutive-blank-lines=k (-mbl=k) as follows:
3796 1. If -mbl=0 then no blanks will be output. This allows all blanks
3798 to be suppressed with a single parameter. Otherwise,
3799 2. If the number of old blank lines in the script is less than n
3801 then additional blanks will be inserted to make the total n
3802 regardless of the value of -mbl=k.
3803 3. If the number of old blank lines in the script equals or exceeds
3805 n then this parameter has no effect, however the total will not
3806 exceed value specified on the -mbl=k flag.
3807 -blbp=n, --blank-lines-before-packages=n
3809 The parameter -blbp=n requests that least n blank lines precede a
3810 package which does not follow a comment. The default is -blbp=1.
3811 This parameter interacts with the value k of the parameter
3813 --maximum-consecutive-blank-lines=k (-mbl=k) in the same way as
3814 described for the previous item -blbs=n.
3815 -bbs, --blanks-before-subs
3817 For compatibility with previous versions, -bbs or
3818 --blanks-before-subs is equivalent to -blbp=1 and -blbs=1.
3819 Likewise, -nbbs or --noblanks-before-subs is equivalent to -blbp=0
3821 and -blbs=0.
3822 -bbb, --blanks-before-blocks
3824 A blank line will be introduced before blocks of coding delimited
3825 by for, foreach, while, until, and if, unless, in the following
3826 circumstances:
3827 • The block is not preceded by a comment.
3829 • The block is not a one-line block.
3831 • The number of consecutive non-blank lines at the current
3833 indentation depth is at least -lbl (see next section).
3834 This is the default. The intention of this option is to introduce
3836 some space within dense coding. This is negated with -nbbb or
3837 --noblanks-before-blocks.
3838 -lbl=n --long-block-line-count=n
3840 This controls how often perltidy is allowed to add blank lines
3841 before certain block types (see previous section). The default is
3842 8. Entering a value of 0 is equivalent to entering a very large
3843 number.
3844 -blao=i or --blank-lines-after-opening-block=i
3846 This control places a minimum of i blank lines after a line which
3847 ends with an opening block brace of a specified type. By default,
3848 this only applies to the block of a named sub, but this can be
3849 changed (see -blaol below). The default is not to do this (i=0).
3850 Please see the note below on using the -blao and -blbc options.
3852 -blbc=i or --blank-lines-before-closing-block=i
3854 This control places a minimum of i blank lines before a line which
3855 begins with a closing block brace of a specified type. By default,
3856 this only applies to the block of a named sub, but this can be
3857 changed (see -blbcl below). The default is not to do this (i=0).
3858 -blaol=s or --blank-lines-after-opening-block-list=s
3860 The parameter s is a list of block type keywords to which the flag
3861 -blao should apply. The section "Specifying Block Types" explains
3862 how to list block types.
3863 -blbcl=s or --blank-lines-before-closing-block-list=s
3865 This parameter is a list of block type keywords to which the flag
3866 -blbc should apply. The section "Specifying Block Types" explains
3867 how to list block types.
3868 Note on using the -blao and -blbc options.
3870 These blank line controls introduce a certain minimum number of
3871 blank lines in the text, but the final number of blank lines may be
3872 greater, depending on values of the other blank line controls and
3873 the number of old blank lines. A consequence is that introducing
3874 blank lines with these and other controls cannot be exactly undone,
3875 so some experimentation with these controls is recommended before
3876 using them.
3877 For example, suppose that for some reason we decide to introduce
3879 one blank space at the beginning and ending of all blocks. We
3880 could do this using
3881 perltidy -blao=2 -blbc=2 -blaol='*' -blbcl='*' filename
3883 Now suppose the script continues to be developed, but at some later
3885 date we decide we don't want these spaces after all. We might
3886 expect that running with the flags -blao=0 and -blbc=0 will undo
3887 them. However, by default perltidy retains single blank lines, so
3888 the blank lines remain.
3889 We can easily fix this by telling perltidy to ignore old blank
3891 lines by including the added parameter -kbl=0 and rerunning. Then
3892 the unwanted blank lines will be gone. However, this will cause
3893 all old blank lines to be ignored, perhaps even some that were
3894 added by hand to improve formatting. So please be cautious when
3895 using these parameters.
3896 -mbl=n --maximum-consecutive-blank-lines=n
3898 This parameter specifies the maximum number of consecutive blank
3899 lines which will be output within code sections of a script. The
3900 default is n=1. If the input file has more than n consecutive
3901 blank lines, the number will be reduced to n except as noted above
3902 for the -blbp and -blbs parameters. If n=0 then no blank lines
3903 will be output (unless all old blank lines are retained with the
3904 -kbl=2 flag of the next section).
3905 This flag obviously does not apply to pod sections, here-documents,
3907 and quotes.
3908 -kbl=n, --keep-old-blank-lines=n
3910 The -kbl=n flag gives you control over how your existing blank
3911 lines are treated.
3912 The possible values of n are:
3914 n=0 ignore all old blank lines
3916 n=1 stable: keep old blanks, but limited by the value of the B<-mbl=n> flag
3917 n=2 keep all old blank lines, regardless of the value of the B<-mbl=n> flag
3918 The default is n=1.
3920 -sob, --swallow-optional-blank-lines
3922 This is equivalent to kbl=0 and is included for compatibility with
3923 previous versions.
3924 -nsob, --noswallow-optional-blank-lines
3926 This is equivalent to kbl=1 and is included for compatibility with
3927 previous versions.
3928 Controls for blank lines around lines of consecutive keywords
3930 The parameters in this section provide some control over the placement
3932 of blank lines within and around groups of statements beginning with
3933 selected keywords. These blank lines are called here keyword group
3934 blanks, and all of the parameters begin with --keyword-group-blanks*,
3935 or -kgb* for short. The default settings do not employ these controls
3936 but they can be enabled with the following parameters:
3937 -kgbl=s or --keyword-group-blanks-list=s; s is a quoted string of
3939 keywords
3940 -kgbs=s or --keyword-group-blanks-size=s; s gives the number of
3942 keywords required to form a group.
3943 -kgbb=n or --keyword-group-blanks-before=n; n = (0, 1, or 2) controls a
3945 leading blank
3946 -kgba=n or --keyword-group-blanks-after=n; n = (0, 1, or 2) controls a
3948 trailing blank
3949 -kgbi or --keyword-group-blanks-inside is a switch for adding blanks
3951 between subgroups
3952 -kgbd or --keyword-group-blanks-delete is a switch for removing initial
3954 blank lines between keywords
3955 -kgbr=n or --keyword-group-blanks-repeat-count=n can limit the number
3957 of times this logic is applied
3958 In addition, the following abbreviations are available to for
3960 simplified usage:
3961 -kgb or --keyword-group-blanks is short for -kgbb=2 -kgba=2 kgbi
3963 -nkgb or --nokeyword-group-blanks, is short for -kgbb=1 -kgba=1 nkgbi
3965 Before describing the meaning of the parameters in detail let us look
3967 at an example which is formatted with default parameter settings.
3968 print "Entering test 2\n";
3970 use Test;
3971 use Encode qw(from_to encode decode
3972 encode_utf8 decode_utf8
3973 find_encoding is_utf8);
3974 use charnames qw(greek);
3975 my @encodings = grep( /iso-?8859/, Encode::encodings() );
3976 my @character_set = ( '0' .. '9', 'A' .. 'Z', 'a' .. 'z' );
3977 my @source = qw(ascii iso8859-1 cp1250);
3978 my @destiny = qw(cp1047 cp37 posix-bc);
3979 my @ebcdic_sets = qw(cp1047 cp37 posix-bc);
3980 my $str = join( '', map( chr($_), 0x20 .. 0x7E ) );
3981 return unless ($str);
3982 using perltidy -kgb gives:
3984 print "Entering test 2\n";
3986 <----------this blank controlled by -kgbb
3987 use Test;
3988 use Encode qw(from_to encode decode
3989 encode_utf8 decode_utf8
3990 find_encoding is_utf8);
3991 use charnames qw(greek);
3992 <---------this blank controlled by -kgbi
3993 my @encodings = grep( /iso-?8859/, Encode::encodings() );
3994 my @character_set = ( '0' .. '9', 'A' .. 'Z', 'a' .. 'z' );
3995 my @source = qw(ascii iso8859-1 cp1250);
3996 my @destiny = qw(cp1047 cp37 posix-bc);
3997 my @ebcdic_sets = qw(cp1047 cp37 posix-bc);
3998 my $str = join( '', map( chr($_), 0x20 .. 0x7E ) );
3999 <----------this blank controlled by -kgba
4000 return unless ($str);
4001 Blank lines have been introduced around the my and use sequences. What
4003 happened is that the default keyword list includes my and use but not
4004 print and return. So a continuous sequence of nine my and use
4005 statements was located. This number exceeds the default threshold of
4006 five, so blanks were placed before and after the entire group. Then,
4007 since there was also a subsequence of six my lines, a blank line was
4008 introduced to separate them.
4009 Finer control over blank placement can be achieved by using the
4011 individual parameters rather than the -kgb flag. The individual
4012 controls are as follows.
4013 -kgbl=s or --keyword-group-blanks-list=s, where s is a quoted string,
4015 defines the set of keywords which will be formed into groups. The
4016 string is a space separated list of keywords. The default set is
4017 s="use require local our my", but any list of keywords may be used.
4018 Comment lines may also be included in a keyword group, even though they
4019 are not keywords. To include ordinary block comments, include the
4020 symbol BC. To include static block comments (which normally begin with
4021 '##'), include the symbol SBC.
4022 -kgbs=s or --keyword-group-blanks-size=s, where s is a string
4024 describing the number of consecutive keyword statements forming a group
4025 (Note: statements separated by blank lines in the input file are
4026 considered consecutive for purposes of this count). If s is an integer
4027 then it is the minimum number required for a group. A maximum value
4028 may also be given with the format s=min.max, where min is the minimum
4029 number and max is the maximum number, and the min and max values are
4030 separated by one or more dots. No groups will be found if the maximum
4031 is less than the minimum. The maximum is unlimited if not given. The
4032 default is s=5. Some examples:
4033 s min max number for group
4035 3 3 unlimited 3 or more
4036 1.1 1 1 1
4037 1..3 1 3 1 to 3
4038 1.0 1 0 (no match)
4039 There is no really good default value for this parameter. If it is set
4041 too small, then an excessive number of blank lines may be generated.
4042 However, some users may prefer reducing the value somewhat below the
4043 default, perhaps to s=3.
4044 -kgbb=n or --keyword-group-blanks-before=n specifies whether a blank
4046 should appear before the first line of the group, as follows:
4047 n=0 => (delete) an existing blank line will be removed
4049 n=1 => (stable) no change to the input file is made [DEFAULT]
4050 n=2 => (insert) a blank line is introduced if possible
4051 -kgba=n or --keyword-group-blanks-after=n likewise specifies whether a
4053 blank should appear after the last line of the group, using the same
4054 scheme (0=delete, 1=stable, 2=insert).
4055 -kgbi or --keyword-group-blanks-inside controls the insertion of blank
4057 lines between the first and last statement of the entire group. If
4058 there is a continuous run of a single statement type with more than the
4059 minimum threshold number (as specified with -kgbs=s) then this switch
4060 causes a blank line be inserted between this subgroup and the others.
4061 In the example above this happened between the use and my statements.
4062 -kgbd or --keyword-group-blanks-delete controls the deletion of any
4064 blank lines that exist in the the group when it is first scanned. When
4065 statements are initially scanned, any existing blank lines are included
4066 in the collection. Any such original blank lines will be deleted
4067 before any other insertions are made when the parameter -kgbd is set.
4068 The default is not to do this, -nkgbd.
4069 -kgbr=n or --keyword-group-blanks-repeat-count=n specifies n, the
4071 maximum number of times this logic will be applied to any file. The
4072 special value n=0 is the same as n=infinity which means it will be
4073 applied to an entire script [Default]. A value n=1 could be used to
4074 make it apply just one time for example. This might be useful for
4075 adjusting just the use statements in the top part of a module for
4076 example.
4077 -kgb or --keyword-group-blanks is an abbreviation equivalent to setting
4079 -kgbb=1 -kgba=1 -kgbi. This turns on keyword group formatting with a
4080 set of default values.
4081 -nkgb or --nokeyword-group-blanks is equivalent to -kgbb=0 -kgba nkgbi.
4083 This flag turns off keyword group blank lines and is the default
4084 setting.
4085 Here are a few notes about the functioning of this technique.
4087 • These parameters are probably more useful as part of a major code
4089 reformatting operation rather than as a routine formatting
4090 operation.
4091 In particular, note that deleting old blank lines with -kgbd is an
4093 irreversible operation so it should be applied with care. Existing
4094 blank lines may be serving an important role in controlling
4095 vertical alignment.
4096 • Conflicts which arise among these kgb* parameters and other blank
4098 line controls are generally resolved by producing the maximum
4099 number of blank lines implied by any parameter.
4100 For example, if the flags --freeze-blank-lines, or
4102 --keep-old-blank-lines=2, are set, then they have priority over any
4103 blank line deletion implied by the -kgb flags of this section, so
4104 no blank lines will be deleted.
4105 For another example, if a keyword group ends at a sub and the flag
4107 kgba=0 requests no blank line there, but we also have
4108 --blank-lines-before-subs=2, then two blank lines will still be
4109 introduced before the sub.
4110 • The introduction of blank lines does not occur if it would conflict
4112 with other input controls or code validity. For example, a blank
4113 line will not be placed within a here-doc or within a section of
4114 code marked with format skipping comments. And in general, a blank
4115 line will only be introduced at the end of a group if the next
4116 statement is a line of code.
4117 • The count which is used to determine the group size is not the
4119 number of lines but rather the total number of keywords which are
4120 found. Individual statements with a certain leading keyword may
4121 continue on multiple lines, but if any of these lines is nested
4122 more than one level deep then that group will be ended.
4123 • The search for groups of lines with similar leading keywords is
4125 based on the input source, not the final formatted source.
4126 Consequently, if the source code is badly formatted, it would be
4127 best to make a first formatting pass without these options.
4128 Styles
4130 A style refers to a convenient collection of existing parameters.
4131 -gnu, --gnu-style
4133 -gnu gives an approximation to the GNU Coding Standards (which do
4134 not apply to perl) as they are sometimes implemented. At present,
4135 this style overrides the default style with the following
4136 parameters:
4137 -lp -bl -noll -pt=2 -bt=2 -sbt=2 -icp
4139 To use this style with -xlp instead of -lp use -gnu -xlp.
4141 -pbp, --perl-best-practices
4143 -pbp is an abbreviation for the parameters in the book Perl Best
4144 Practices by Damian Conway:
4145 -l=78 -i=4 -ci=4 -st -se -vt=2 -cti=0 -pt=1 -bt=1 -sbt=1 -bbt=1 -nsfs -nolq
4147 -wbb="% + - * / x != == >= <= =~ !~ < > | & =
4148 **= += *= &= <<= &&= -= /= |= >>= ||= //= .= %= ^= x="
4149 Please note that this parameter set includes -st and -se flags,
4151 which make perltidy act as a filter on one file only. These can be
4152 overridden by placing -nst and/or -nse after the -pbp parameter.
4153 Also note that the value of continuation indentation, -ci=4, is
4155 equal to the value of the full indentation, -i=4. It is
4156 recommended that the either (1) the parameter -ci=2 be used
4157 instead, or (2) the flag -xci be set. This will help show
4158 structure, particularly when there are ternary statements. The
4159 following snippet illustrates these options.
4160 # perltidy -pbp
4162 $self->{_text} = (
4163 !$section ? ''
4164 : $type eq 'item' ? "the $section entry"
4165 : "the section on $section"
4166 )
4167 . (
4168 $page
4169 ? ( $section ? ' in ' : '' ) . "the $page$page_ext manpage"
4170 : ' elsewhere in this document'
4171 );
4172 # perltidy -pbp -ci=2
4174 $self->{_text} = (
4175 !$section ? ''
4176 : $type eq 'item' ? "the $section entry"
4177 : "the section on $section"
4178 )
4179 . (
4180 $page
4181 ? ( $section ? ' in ' : '' ) . "the $page$page_ext manpage"
4182 : ' elsewhere in this document'
4183 );
4184 # perltidy -pbp -xci
4186 $self->{_text} = (
4187 !$section ? ''
4188 : $type eq 'item' ? "the $section entry"
4189 : "the section on $section"
4190 )
4191 . ( $page
4192 ? ( $section ? ' in ' : '' ) . "the $page$page_ext manpage"
4193 : ' elsewhere in this document'
4194 );
4195 The -xci flag was developed after the -pbp parameters were
4197 published so you need to include it separately.
4198 One-Line Blocks
4200 A one-line block is a block of code where the contents within the curly
4201 braces is short enough to fit on a single line. For example,
4202 if ( -e $file ) { print "'$file' exists\n" }
4204 The alternative, a block which spans multiple lines, is said to be a
4206 broken block. With few exceptions, perltidy retains existing one-line
4207 blocks, if it is possible within the line-length constraint, but it
4208 does not attempt to form new ones. In other words, perltidy will try
4209 to follow the input file regarding broken and unbroken blocks.
4210 The main exception to this rule is that perltidy will attempt to form
4212 new one-line blocks following the keywords "map", "eval", and "sort",
4213 "eval", because these code blocks are often small and most clearly
4214 displayed in a single line. This behavior can be controlled with the
4215 flag --one-line-block-exclusion-list described below.
4216 When the cuddled-else style is used, the default treatment of one-line
4218 blocks may interfere with the cuddled style. In this case, the default
4219 behavior may be changed with the flag --cuddled-break-option=n
4220 described elsehwere.
4221 When an existing one-line block is longer than the maximum line length,
4223 and must therefore be broken into multiple lines, perltidy checks for
4224 and adds any optional terminating semicolon (unless the -nasc option is
4225 used) if the block is a code block.
4226 -olbxl=s, --one-line-block-exclusion-list=s
4228 As noted above, perltidy will, by default, attempt to create new
4229 one-line blocks for certain block types. This flag allows the user
4230 to prevent this behavior for the block types listed in the string
4231 s. The list s may include any of the words "sort", "map", "grep",
4232 "eval", or it may be "*" to indicate all of these.
4233 So for example to prevent multi-line eval blocks from becoming one-
4235 line blocks, the command would be -olbxl='eval'. In this case,
4236 existing one-line eval blocks will remain on one-line if possible,
4237 and existing multi-line eval blocks will remain multi-line blocks.
4238 -olbn=n, --one-line-block-nesting=n
4240 Nested one-line blocks are lines with code blocks which themselves
4241 contain code blocks. For example, the following line is a nested
4242 one-line block.
4243 foreach (@list) { if ($_ eq $asked_for) { last } ++$found }
4245 The default behavior is to break such lines into multiple lines,
4247 but this behavior can be controlled with this flag. The values of
4248 n are:
4249 n=0 break nested one-line blocks into multiple lines [DEFAULT]
4251 n=1 stable: keep existing nested-one line blocks intact
4252 For the above example, the default formatting (-olbn=0) is
4254 foreach (@list) {
4256 if ( $_ eq $asked_for ) { last }
4257 ++$found;
4258 }
4259 If the parameter -olbn=1 is given, then the line will be left
4261 intact if it is a single line in the source, or it will be broken
4262 into multiple lines if it is broken in multiple lines in the
4263 source.
4264 -olbs=n, --one-line-block-semicolons=n
4266 This flag controls the placement of semicolons at the end of one-
4267 line blocks. Semicolons are optional before a closing block brace,
4268 and frequently they are omitted at the end of a one-line block
4269 containing just a single statement. By default, perltidy follows
4270 the input file regarding these semicolons, but this behavior can be
4271 controlled by this flag. The values of n are:
4272 n=0 remove terminal semicolons in one-line blocks having a single statement
4274 n=1 stable; keep input file placement of terminal semicolons [DEFAULT ]
4275 n=2 add terminal semicolons in all one-line blocks
4276 Note that the n=2 option has no effect if adding semicolons is
4278 prohibited with the -nasc flag. Also not that while n=2 adds
4279 missing semicolons to all one-line blocks, regardless of
4280 complexity, the n=0 option only removes ending semicolons which
4281 terminate one-line blocks containing just one semicolon. So these
4282 two options are not exact inverses.
4283 Forming new one-line blocks
4285 Sometimes it might be desirable to convert a script to have one-
4286 line blocks whenever possible. Although there is currently no flag
4287 for this, a simple workaround is to execute perltidy twice, once
4288 with the flag -noadd-newlines and then once again with normal
4289 parameters, like this:
4290 cat infile | perltidy -nanl | perltidy >outfile
4292 When executed on this snippet
4294 if ( $? == -1 ) {
4296 die "failed to execute: $!\n";
4297 }
4298 if ( $? == -1 ) {
4299 print "Had enough.\n";
4300 die "failed to execute: $!\n";
4301 }
4302 the result is
4304 if ( $? == -1 ) { die "failed to execute: $!\n"; }
4306 if ( $? == -1 ) {
4307 print "Had enough.\n";
4308 die "failed to execute: $!\n";
4309 }
4310 This shows that blocks with a single statement become one-line
4312 blocks.
4313 Breaking existing one-line blocks
4315 There is no automatic way to break existing long one-line blocks
4316 into multiple lines, but this can be accomplished by processing a
4317 script, or section of a script, with a short value of the parameter
4318 maximum-line-length=n. Then, when the script is reformatted again
4319 with the normal parameters, the blocks which were broken will
4320 remain broken (with the exceptions noted above).
4321 Another trick for doing this for certain block types is to format
4323 one time with the -cuddled-else flag and --cuddled-break-option=2.
4324 Then format again with the normal parameters. This will break any
4325 one-line blocks which are involved in a cuddled-else style.
4326 Controlling Vertical Alignment
4328 Vertical alignment refers to lining up certain symbols in a list of
4329 consecutive similar lines to improve readability. For example, the
4330 "fat commas" are aligned in the following statement:
4331 $data = $pkg->new(
4333 PeerAddr => join( ".", @port[ 0 .. 3 ] ),
4334 PeerPort => $port[4] * 256 + $port[5],
4335 Proto => 'tcp'
4336 );
4337 Vertical alignment can be completely turned off using the -novalign
4339 flag mentioned below. However, vertical alignment can be forced to
4340 stop and restart by selectively introducing blank lines. For example,
4341 a blank has been inserted in the following code to keep somewhat
4342 similar things aligned.
4343 %option_range = (
4345 'format' => [ 'tidy', 'html', 'user' ],
4346 'output-line-ending' => [ 'dos', 'win', 'mac', 'unix' ],
4347 'character-encoding' => [ 'none', 'utf8' ],
4348 'block-brace-tightness' => [ 0, 2 ],
4350 'brace-tightness' => [ 0, 2 ],
4351 'paren-tightness' => [ 0, 2 ],
4352 'square-bracket-tightness' => [ 0, 2 ],
4353 );
4354 Vertical alignment is implemented by locally increasing an existing
4356 blank space to produce alignment with an adjacent line. It cannot
4357 occur if there is no blank space to increase. So if a particular space
4358 is removed by one of the existing controls then vertical alignment
4359 cannot occur. Likewise, if a space is added with one of the controls,
4360 then vertical alignment might occur.
4361 For example,
4363 # perltidy -nwls='=>'
4365 $data = $pkg->new(
4366 PeerAddr=> join( ".", @port[ 0 .. 3 ] ),
4367 PeerPort=> $port[4] * 256 + $port[5],
4368 Proto=> 'tcp'
4369 );
4370 Completely turning off vertical alignment with -novalign
4372 The default is to use vertical alignment, but vertical alignment
4373 can be completely turned of with the -novalign flag.
4374 A lower level of control of vertical alignment is possible with
4376 three parameters -vc, -vsc, and -vbc. These independently control
4377 alignment of code, side comments and block comments. They are
4378 described in the next section.
4379 The parameter -valign is in fact an alias for -vc -vsc -vbc, and
4381 its negative -novalign is an alias for -nvc -nvsc -nvbc.
4382 Controlling code alignment with --valign-code or -vc
4384 The -vc flag enables alignment of code symbols such as =. The
4385 default is -vc. For detailed control of which symbols to align,
4386 see the -valign-exclude-list parameter below.
4387 Controlling side comment alignment with --valign-side-comments or -vsc
4389 The -vsc flag enables alignment of side comments and is enabled by
4390 default. If side comment alignment is disabled with -nvsc they
4391 will appear at a fixed space from the preceding code token. The
4392 default is -vsc
4393 Controlling block comment alignment with --valign-block-comments or
4395 -vbc
4396 When -vbc is enabled, block comments can become aligned for example
4397 if one comment of a consecutive sequence of comments becomes
4398 outdented due a length in excess of the maximum line length. If
4399 this occurs, the entire group of comments will remain aligned and
4400 be outdented by the same amount. This coordinated alignment will
4401 not occur if -nvbc is set. The default is -vbc.
4402 Finer alignment control with --valign-exclusion-list=s or -vxl=s and
4404 --valign-inclusion-list=s or -vil=s
4405 More detailed control of alignment types is available with these
4406 two parameters. Most of the vertical alignments in typical
4407 programs occur at one of the tokens ',', '=', and '=>', but many
4408 other alignments are possible and are given in the following list:
4409 = **= += *= &= <<= &&= -= /= |= >>= ||= //= .= %= ^= x=
4411 { ( ? : , ; => && || ~~ !~~ =~ !~ // <=> -> q
4412 if unless and or err for foreach while until
4413 These alignment types correspond to perl symbols, operators and
4415 keywords except for 'q', which refers to the special case of
4416 alignment in a 'use' statement of qw quotes and empty parens.
4417 They are all enabled by default, but they can be selectively
4419 disabled by including one or more of these tokens in the space-
4420 separated list valign-exclusion-list=s. For example, the following
4421 would prevent alignment at = and if:
4422 --valign-exclusion-list='= if'
4424 If it is simpler to specify only the token types which are to be
4426 aligned, then include the types which are to be aligned in the list
4427 of --valign-inclusion-list. In that case you may leave the valign-
4428 exclusion-list undefined, or use the special symbol * for the
4429 exclusion list. For example, the following parameters enable
4430 alignment only at commas and 'fat commas':
4431 --valign-inclusion-list=', =>'
4433 --valign-exclusion-list='*' ( this is optional and may be omitted )
4434 These parameter lists should consist of space-separated tokens from
4436 the above list of possible alignment tokens, or a '*'. If an
4437 unrecognized token appears, it is simply ignored. And if a specific
4438 token is entered in both lists by mistake then the exclusion list
4439 has priority.
4440 The default values of these parameters enable all alignments and
4442 are equivalent to
4443 --valign-exclusion-list=' '
4445 --valign-inclusion-list='*'
4446 To illustrate, consider the following snippet with default
4448 formatting
4449 # perltidy
4451 $co_description = ($color) ? 'bold cyan' : ''; # description
4452 $co_prompt = ($color) ? 'bold green' : ''; # prompt
4453 $co_unused = ($color) ? 'on_green' : 'reverse'; # unused
4454 To exclude all alignments except the equals (i.e., include only
4456 equals) we could use:
4457 # perltidy -vil='='
4459 $co_description = ($color) ? 'bold cyan' : ''; # description
4460 $co_prompt = ($color) ? 'bold green' : ''; # prompt
4461 $co_unused = ($color) ? 'on_green' : 'reverse'; # unused
4462 To exclude only the equals we could use:
4464 # perltidy -vxl='='
4466 $co_description = ($color) ? 'bold cyan' : ''; # description
4467 $co_prompt = ($color) ? 'bold green' : ''; # prompt
4468 $co_unused = ($color) ? 'on_green' : 'reverse'; # unused
4469 Notice in this last example that although only the equals alignment
4471 was excluded, the ternary alignments were also lost. This happens
4472 because the vertical aligner sweeps from left-to-right and usually
4473 stops if an important alignment cannot be made for some reason.
4474 But also notice that side comments remain aligned because their
4476 alignment is controlled separately with the parameter
4477 --valign-side_comments described above.
4478 Extended Syntax
4480 This section describes some parameters for dealing with extended
4481 syntax.
4482 For another method of handling extended syntax see the section
4484 "Skipping Selected Sections of Code".
4485 Also note that the module Perl::Tidy supplies a pre-filter and post-
4487 filter capability. This requires calling the module from a separate
4488 program rather than through the binary perltidy.
4489 -xs, --extended-syntax
4491 This flag allows perltidy to handle certain common extensions to
4492 the standard syntax without complaint.
4493 For example, without this flag a structure such as the following
4495 would generate a syntax error:
4496 Method deposit( Num $amount) {
4498 $self->balance( $self->balance + $amount );
4499 }
4500 This flag is enabled by default but it can be deactivated with
4502 -nxs. Probably the only reason to deactivate this flag is to
4503 generate more diagnostic messages when debugging a script.
4504 -sal=s, --sub-alias-list=s
4506 This flag causes one or more words to be treated the same as if
4507 they were the keyword sub. The string s contains one or more alias
4508 words, separated by spaces or commas.
4509 For example,
4511 perltidy -sal='method fun _sub M4'
4513 will cause the perltidy to treat the words 'method', 'fun', '_sub'
4515 and 'M4' the same as if they were 'sub'. Note that if the alias
4516 words are separated by spaces then the string of words should be
4517 placed in quotes.
4518 Note that several other parameters accept a list of keywords,
4520 including 'sub' (see "Specifying Block Types"). You do not need to
4521 include any sub aliases in these lists. Just include keyword 'sub'
4522 if you wish, and all aliases are automatically included.
4523 -gal=s, --grep-alias-list=s
4525 This flag allows a code block following an external 'list operator'
4526 function to be formatted as if it followed one of the built-in
4527 keywords grep, map or sort. The string s contains the names of
4528 one or more such list operators, separated by spaces or commas.
4529 By 'list operator' is meant a function which is invoked in the form
4531 word {BLOCK} @list
4533 Perltidy tries to keep code blocks for these functions intact,
4535 since they are usually short, and does not automatically break
4536 after the closing brace since a list may follow. It also does some
4537 special handling of continuation indentation.
4538 For example, the code block arguments to functions 'My_grep' and
4540 'My_map' can be given formatting like 'grep' with
4541 perltidy -gal='My_grep My_map'
4543 By default, the following list operators in List::Util are
4545 automatically included:
4546 all any first none notall reduce reductions
4548 Any operators specified with --grep-alias-list are added to this
4550 list. The next parameter can be used to remove words from this
4551 default list.
4552 -gaxl=s, --grep-alias-exclusion-list=s
4554 The -gaxl=s flag provides a method for removing any of the default
4555 list operators given above by listing them in the string s. To
4556 remove all of the default operators use -gaxl='*'.
4557 -uf=s, --use-feature=s
4559 This flag tells perltidy to allow the syntax associated a pragma in
4560 string s. Currently only the recognized values for the string are
4561 s='class' or string s=' '. The default is --use-feature='class'.
4562 This enables perltidy to recognized the special words class,
4563 method, field, and ADJUST. If this causes a conflict with other
4564 uses of these words, the default can be turned off with
4565 --use-feature=' '.
4566 Other Controls
4568 Deleting selected text
4569 Perltidy can selectively delete comments and/or pod documentation.
4570 The command -dac or --delete-all-comments will delete all comments
4571 and all pod documentation, leaving just code and any leading system
4572 control lines.
4573 The command -dp or --delete-pod will remove all pod documentation
4575 (but not comments).
4576 Two commands which remove comments (but not pod) are: -dbc or
4578 --delete-block-comments and -dsc or --delete-side-comments.
4579 (Hanging side comments will be deleted with side comments here.)
4580 When side comments are deleted, any special control side comments
4582 for non-indenting braces will be retained unless they are
4583 deactivated with a -nnib flag.
4584 The negatives of these commands also work, and are the defaults.
4586 When block comments are deleted, any leading 'hash-bang' will be
4587 retained. Also, if the -x flag is used, any system commands before
4588 a leading hash-bang will be retained (even if they are in the form
4589 of comments).
4590 Writing selected text to a file
4592 When perltidy writes a formatted text file, it has the ability to
4593 also send selected text to a file with a .TEE extension. This text
4594 can include comments and pod documentation.
4595 The command -tac or --tee-all-comments will write all comments and
4597 all pod documentation.
4598 The command -tp or --tee-pod will write all pod documentation (but
4600 not comments).
4601 The commands which write comments (but not pod) are: -tbc or
4603 --tee-block-comments and -tsc or --tee-side-comments. (Hanging
4604 side comments will be written with side comments here.)
4605 The negatives of these commands also work, and are the defaults.
4607 Using a .perltidyrc command file
4609 If you use perltidy frequently, you probably won't be happy until
4610 you create a .perltidyrc file to avoid typing commonly-used
4611 parameters. Perltidy will first look in your current directory for
4612 a command file named .perltidyrc. If it does not find one, it will
4613 continue looking for one in other standard locations.
4614 These other locations are system-dependent, and may be displayed
4616 with the command "perltidy -dpro". Under Unix systems, it will
4617 first look for an environment variable PERLTIDY. Then it will look
4618 for a .perltidyrc file in the home directory, and then for a
4619 system-wide file /usr/local/etc/perltidyrc, and then it will look
4620 for /etc/perltidyrc. Note that these last two system-wide files do
4621 not have a leading dot. Further system-dependent information will
4622 be found in the INSTALL file distributed with perltidy.
4623 Under Windows, perltidy will also search for a configuration file
4625 named perltidy.ini since Windows does not allow files with a
4626 leading period (.). Use "perltidy -dpro" to see the possible
4627 locations for your system. An example might be C:\Documents and
4628 Settings\All Users\perltidy.ini.
4629 Another option is the use of the PERLTIDY environment variable.
4631 The method for setting environment variables depends upon the
4632 version of Windows that you are using. Instructions for Windows 95
4633 and later versions can be found here:
4634 http://www.netmanage.com/000/20021101_005_tcm21-6336.pdf
4636 Under Windows NT / 2000 / XP the PERLTIDY environment variable can
4638 be placed in either the user section or the system section. The
4639 later makes the configuration file common to all users on the
4640 machine. Be sure to enter the full path of the configuration file
4641 in the value of the environment variable. Ex.
4642 PERLTIDY=C:\Documents and Settings\perltidy.ini
4643 The configuration file is free format, and simply a list of
4645 parameters, just as they would be entered on a command line. Any
4646 number of lines may be used, with any number of parameters per
4647 line, although it may be easiest to read with one parameter per
4648 line. Comment text begins with a #, and there must also be a space
4649 before the # for side comments. It is a good idea to put complex
4650 parameters in either single or double quotes.
4651 Here is an example of a .perltidyrc file:
4653 # This is a simple of a .perltidyrc configuration file
4655 # This implements a highly spaced style
4656 -se # errors to standard error output
4657 -w # show all warnings
4658 -bl # braces on new lines
4659 -pt=0 # parens not tight at all
4660 -bt=0 # braces not tight
4661 -sbt=0 # square brackets not tight
4662 The parameters in the .perltidyrc file are installed first, so any
4664 parameters given on the command line will have priority over them.
4665 To avoid confusion, perltidy ignores any command in the .perltidyrc
4667 file which would cause some kind of dump and an exit. These are:
4668 -h -v -ddf -dln -dop -dsn -dtt -dwls -dwrs -ss
4670 There are several options may be helpful in debugging a .perltidyrc
4672 file:
4673 • A very helpful command is --dump-profile or -dpro. It writes a
4675 list of all configuration filenames tested to standard output,
4676 and if a file is found, it dumps the content to standard output
4677 before exiting. So, to find out where perltidy looks for its
4678 configuration files, and which one if any it selects, just
4679 enter
4680 perltidy -dpro
4682 • It may be simplest to develop and test configuration files with
4684 alternative names, and invoke them with -pro=filename on the
4685 command line. Then rename the desired file to .perltidyrc when
4686 finished.
4687 • The parameters in the .perltidyrc file can be switched off with
4689 the -npro option.
4690 • The commands --dump-options, --dump-defaults,
4692 --dump-long-names, and --dump-short-names, all described below,
4693 may all be helpful.
4694 Creating a new abbreviation
4696 A special notation is available for use in a .perltidyrc file for
4697 creating an abbreviation for a group of options. This can be used
4698 to create a shorthand for one or more styles which are frequently,
4699 but not always, used. The notation is to group the options within
4700 curly braces which are preceded by the name of the alias (without
4701 leading dashes), like this:
4702 newword {
4704 -opt1
4705 -opt2
4706 }
4707 where newword is the abbreviation, and opt1, etc, are existing
4709 parameters or other abbreviations. The main syntax requirement is
4710 that the new abbreviation along with its opening curly brace must
4711 begin on a new line. Space before and after the curly braces is
4712 optional.
4713 For a specific example, the following line
4715 oneliner { --maximum-line-length=0 --noadd-newlines --noadd-terminal-newline}
4717 or equivalently with abbreviations
4719 oneliner { -l=0 -nanl -natnl }
4721 could be placed in a .perltidyrc file to temporarily override the
4723 maximum line length with a large value, to temporarily prevent new
4724 line breaks from being added, and to prevent an extra newline
4725 character from being added the file. All other settings in the
4726 .perltidyrc file still apply. Thus it provides a way to format a
4727 long 'one liner' when perltidy is invoked with
4728 perltidy --oneliner ...
4730 (Either "-oneliner" or "--oneliner" may be used).
4732 Skipping leading non-perl commands with -x or --look-for-hash-bang
4734 If your script has leading lines of system commands or other text
4735 which are not valid perl code, and which are separated from the
4736 start of the perl code by a "hash-bang" line, ( a line of the form
4737 "#!...perl" ), you must use the -x flag to tell perltidy not to
4738 parse and format any lines before the "hash-bang" line. This
4739 option also invokes perl with a -x flag when checking the syntax.
4740 This option was originally added to allow perltidy to parse
4741 interactive VMS scripts, but it should be used for any script which
4742 is normally invoked with "perl -x".
4743 Please note: do not use this flag unless you are sure your script
4745 needs it. Parsing errors can occur if it does not have a hash-
4746 bang, or, for example, if the actual first hash-bang is in a here-
4747 doc. In that case a parsing error will occur because the
4748 tokenization will begin in the middle of the here-doc.
4749 Making a file unreadable
4751 The goal of perltidy is to improve the readability of files, but
4752 there are two commands which have the opposite effect, --mangle and
4753 --extrude. They are actually merely aliases for combinations of
4754 other parameters. Both of these strip all possible whitespace, but
4755 leave comments and pod documents, so that they are essentially
4756 reversible. The difference between these is that --mangle puts the
4757 fewest possible line breaks in a script while --extrude puts the
4758 maximum possible. Note that these options do not provided any
4759 meaningful obfuscation, because perltidy can be used to reformat
4760 the files. They were originally developed to help test the
4761 tokenization logic of perltidy, but they have other uses. One use
4762 for --mangle is the following:
4763 perltidy --mangle myfile.pl -st | perltidy -o myfile.pl.new
4765 This will form the maximum possible number of one-line blocks (see
4767 next section), and can sometimes help clean up a badly formatted
4768 script.
4769 A similar technique can be used with --extrude instead of --mangle
4771 to make the minimum number of one-line blocks.
4772 Another use for --mangle is to combine it with -dac to reduce the
4774 file size of a perl script.
4775 Debugging
4777 The following flags are available for debugging:
4778 --dump-cuddled-block-list or -dcbl will dump to standard output the
4780 internal hash of cuddled block types created by a
4781 -cuddled-block-list input string.
4782 --dump-defaults or -ddf will write the default option set to
4784 standard output and quit
4785 --dump-profile or -dpro will write the name of the current
4787 configuration file and its contents to standard output and quit.
4788 --dump-options or -dop will write current option set to standard
4790 output and quit.
4791 --dump-long-names or -dln will write all command line long names
4793 (passed to Get_options) to standard output and quit.
4794 --dump-short-names or -dsn will write all command line short names
4796 to standard output and quit.
4797 --dump-token-types or -dtt will write a list of all token types to
4799 standard output and quit.
4800 --dump-want-left-space or -dwls will write the hash
4802 %want_left_space to standard output and quit. See the section on
4803 controlling whitespace around tokens.
4804 --dump-want-right-space or -dwrs will write the hash
4806 %want_right_space to standard output and quit. See the section on
4807 controlling whitespace around tokens.
4808 --no-memoize or -nmem will turn of memoizing. Memoization can
4810 reduce run time when running perltidy repeatedly in a single
4811 process. It is on by default but can be deactivated for testing
4812 with -nmem.
4813 --no-timestamp or -nts will eliminate any time stamps in output
4815 files to prevent differences in dates from causing test
4816 installation scripts to fail. There are just a couple of places
4817 where timestamps normally occur. One is in the headers of html
4818 files, and another is when the -cscw option is selected. The
4819 default is to allow timestamps (--timestamp or -ts).
4820 --file-size-order or -fso will cause files to be processed in order
4822 of increasing size, when multiple files are being processed. This
4823 is useful during program development, when large numbers of files
4824 with varying sizes are processed, because it can reduce virtual
4825 memory usage.
4826 --maximum-file-size-mb=n or -maxfs=n specifies the maximum file
4828 size in megabytes that perltidy will attempt to format. This
4829 parameter is provided to avoid causing system problems by
4830 accidentally attempting to format an extremely large data file.
4831 Most perl scripts are less than about 2 MB in size. The integer n
4832 has a default value of 10, so perltidy will skip formatting files
4833 which have a size greater than 10 MB. The command to increase the
4834 limit to 20 MB for example would be
4835 perltidy -maxfs=20
4837 This only applies to files specified by filename on the command
4839 line.
4840 --maximum-level-errors=n or -maxle=n specifies the maximum number
4842 of indentation level errors are allowed before perltidy skips
4843 formatting and just outputs a file verbatim. The default is n=1.
4844 This means that if the final indentation of a script differs from
4845 the starting indentation by more than 1 levels, the file will be
4846 output verbatim. To avoid formatting if there are any indentation
4847 level errors use -maxle=0. To skip this check you can either set n
4848 equal to a large number, such as n=100, or set n=-1.
4849 For example, the following script has level error of 3 and will be
4851 output verbatim
4852 Input and default output:
4854 {{{
4855 perltidy -maxle=100
4858 {
4859 {
4860 {
4861 --maximum-unexpected-errors=n or -maxue=n specifies the maximum
4863 number of unexpected tokenization errors are allowed before
4864 formatting is skipped and a script is output verbatim. The
4865 intention is to avoid accidentally formatting a non-perl script,
4866 such as an html file for example. This check can be turned off by
4867 setting n=0.
4868 A recommended value is n=3. However, the default is n=0 (skip this
4870 check) to avoid causing problems with scripts which have extended
4871 syntaxes.
4872 -DEBUG will write a file with extension .DEBUG for each input file
4874 showing the tokenization of all lines of code.
4875 Making a table of information on code blocks
4877 A table listing information about the blocks of code in a file can
4878 be made with --dump-block-summary, or -dbs. This causes perltidy
4879 to read and parse the file, write a table of comma-separated values
4880 for selected code blocks to the standard output, and then exit.
4881 This parameter must be on the command line, not in a .perlticyrc
4882 file, and it requires a single file name on the command line. For
4883 example
4884 perltidy -dbs somefile.pl >blocks.csv
4886 produces an output file blocks.csv whose lines hold these
4888 parameters:
4889 filename - the name of the file
4891 line - the line number of the opening brace of this block
4892 line_count - the number of lines between opening and closing braces
4893 code_lines - the number of lines excluding blanks, comments, and pod
4894 type - the block type (sub, for, foreach, ...)
4895 name - the block name if applicable (sub name, label, asub name)
4896 depth - the nesting depth of the opening block brace
4897 max_change - the change in depth to the most deeply nested code block
4898 block_count - the total number of code blocks nested in this block
4899 mccabe_count - the McCabe complexity measure of this code block
4900 This feature was developed to help identify complex sections of
4902 code as an aid in refactoring. The McCabe complexity measure
4903 follows the definition used by Perl::Critic. By default the table
4904 contains these values for subroutines, but the user may request
4905 them for any or all blocks of code or packages. For blocks which
4906 are loops nested within loops, a postfix '+' to the "type" is added
4907 to indicate possible code complexity. Although the table does not
4908 otherwise indicate which blocks are nested in other blocks, this
4909 can be determined by computing and comparing the block ending line
4910 numbers.
4911 By default the table lists subroutines with more than 20
4913 "code_lines", but this can be changed with the following two
4914 parameters:
4915 --dump-block-minimum-lines=n, or -dbl=n, where n is the minimum
4917 number of "code_lines" to be included. The default is -n=20. Note
4918 that "code_lines" is the number of lines excluding and comments,
4919 blanks and pod.
4920 --dump-block-types=s, or -dbt=s, where string s is a list of block
4922 types to be included. The type of a block is either the name of
4923 the perl builtin keyword for that block (such as sub if elsif else
4924 for foreach ..) or the word immediately before the opening brace.
4925 In addition, there are a few symbols for special block types, as
4926 follows:
4927 if elsif else for foreach ... any keyword introducing a block
4929 sub - any sub or anynomous sub
4930 asub - any anonymous sub
4931 * - any block except nameless blocks
4932 + - any nested inner block loop
4933 package - any package or class
4934 closure - any nameless block
4935 In addition, specific block loop types which are nested in other
4937 loops can be selected by adding a + after the block name. (Nested
4938 loops are sometimes good candidates for restructuring).
4939 The default is -dbt='sub'.
4941 In the following examples a table "block.csv" is created for a file
4943 "somefile.pl":
4944 • This selects both "subs" and "packages" which have 20 or more
4946 lines of code. This can be useful in code which contains
4947 multiple packages.
4948 perltidy -dbs -dbt='sub package' somefile.pl >blocks.csv
4950 • This selects block types "sub for foreach while" with 10 or
4952 more code lines.
4953 perltidy -dbs -dbl=10 -dbt='sub for foreach while' somefile.pl >blocks.csv
4955 • This selects blocks with 2 or more code lines which are type
4957 "sub" or which are inner loops.
4958 perltidy -dbs -dbl=2 -dbt='sub +' somefile.pl >blocks.csv
4960 • This selects every block and package.
4962 perltidy -dbs -dbl=1 -dbt='* closure' somefile.pl >blocks.csv
4964 Working with MakeMaker, AutoLoader and SelfLoader
4966 The first $VERSION line of a file which might be eval'd by
4967 MakeMaker is passed through unchanged except for indentation. Use
4968 --nopass-version-line, or -npvl, to deactivate this feature.
4969 If the AutoLoader module is used, perltidy will continue formatting
4971 code after seeing an __END__ line. Use --nolook-for-autoloader, or
4972 -nlal, to deactivate this feature.
4973 Likewise, if the SelfLoader module is used, perltidy will continue
4975 formatting code after seeing a __DATA__ line. Use
4976 --nolook-for-selfloader, or -nlsl, to deactivate this feature.
4977 Working around problems with older version of Perl
4979 Perltidy contains a number of rules which help avoid known
4980 subtleties and problems with older versions of perl, and these
4981 rules always take priority over whatever formatting flags have been
4982 set. For example, perltidy will usually avoid starting a new line
4983 with a bareword, because this might cause problems if "use strict"
4984 is active.
4985 There is no way to override these rules.
4987
4989 The -html master switch
4990 The flag -html causes perltidy to write an html file with extension
4991 .html. So, for example, the following command
4992 perltidy -html somefile.pl
4994 will produce a syntax-colored html file named somefile.pl.html
4996 which may be viewed with a browser.
4997 Please Note: In this case, perltidy does not do any formatting to
4999 the input file, and it does not write a formatted file with
5000 extension .tdy. This means that two perltidy runs are required to
5001 create a fully reformatted, html copy of a script.
5002 The -pre flag for code snippets
5004 When the -pre flag is given, only the pre-formatted section, within
5005 the <PRE> and </PRE> tags, will be output. This simplifies
5006 inclusion of the output in other files. The default is to output a
5007 complete web page.
5008 The -nnn flag for line numbering
5010 When the -nnn flag is given, the output lines will be numbered.
5011 The -toc, or --html-table-of-contents flag
5013 By default, a table of contents to packages and subroutines will be
5014 written at the start of html output. Use -ntoc to prevent this.
5015 This might be useful, for example, for a pod document which
5016 contains a number of unrelated code snippets. This flag only
5017 influences the code table of contents; it has no effect on any
5018 table of contents produced by pod2html (see next item).
5019 The -pod, or --pod2html flag
5021 There are two options for formatting pod documentation. The
5022 default is to pass the pod through the Pod::Html module (which
5023 forms the basis of the pod2html utility). Any code sections are
5024 formatted by perltidy, and the results then merged. Note: perltidy
5025 creates a temporary file when Pod::Html is used; see "FILES".
5026 Also, Pod::Html creates temporary files for its cache.
5027 NOTE: Perltidy counts the number of "=cut" lines, and either moves
5029 the pod text to the top of the html file if there is one "=cut", or
5030 leaves the pod text in its original order (interleaved with code)
5031 otherwise.
5032 Most of the flags accepted by pod2html may be included in the
5034 perltidy command line, and they will be passed to pod2html. In
5035 some cases, the flags have a prefix "pod" to emphasize that they
5036 are for the pod2html, and this prefix will be removed before they
5037 are passed to pod2html. The flags which have the additional "pod"
5038 prefix are:
5039 --[no]podheader --[no]podindex --[no]podrecurse --[no]podquiet
5041 --[no]podverbose --podflush
5042 The flags which are unchanged from their use in pod2html are:
5044 --backlink=s --cachedir=s --htmlroot=s --libpods=s --title=s
5046 --podpath=s --podroot=s
5047 where 's' is an appropriate character string. Not all of these
5049 flags are available in older versions of Pod::Html. See your
5050 Pod::Html documentation for more information.
5051 The alternative, indicated with -npod, is not to use Pod::Html, but
5053 rather to format pod text in italics (or whatever the stylesheet
5054 indicates), without special html markup. This is useful, for
5055 example, if pod is being used as an alternative way to write
5056 comments.
5057 The -frm, or --frames flag
5059 By default, a single html output file is produced. This can be
5060 changed with the -frm option, which creates a frame holding a table
5061 of contents in the left panel and the source code in the right
5062 side. This simplifies code browsing. Assume, for example, that the
5063 input file is MyModule.pm. Then, for default file extension
5064 choices, these three files will be created:
5065 MyModule.pm.html - the frame
5067 MyModule.pm.toc.html - the table of contents
5068 MyModule.pm.src.html - the formatted source code
5069 Obviously this file naming scheme requires that output be directed
5071 to a real file (as opposed to, say, standard output). If this is
5072 not the case, or if the file extension is unknown, the -frm option
5073 will be ignored.
5074 The -text=s, or --html-toc-extension flag
5076 Use this flag to specify the extra file extension of the table of
5077 contents file when html frames are used. The default is "toc".
5078 See "Specifying File Extensions".
5079 The -sext=s, or --html-src-extension flag
5081 Use this flag to specify the extra file extension of the content
5082 file when html frames are used. The default is "src". See
5083 "Specifying File Extensions".
5084 The -hent, or --html-entities flag
5086 This flag controls the use of Html::Entities for html formatting.
5087 By default, the module Html::Entities is used to encode special
5088 symbols. This may not be the right thing for some browser/language
5089 combinations. Use --nohtml-entities or -nhent to prevent this.
5090 Style Sheets
5092 Style sheets make it very convenient to control and adjust the
5093 appearance of html pages. The default behavior is to write a page
5094 of html with an embedded style sheet.
5095 An alternative to an embedded style sheet is to create a page with
5097 a link to an external style sheet. This is indicated with the
5098 -css=filename, where the external style sheet is filename. The
5099 external style sheet filename will be created if and only if it
5100 does not exist. This option is useful for controlling multiple
5101 pages from a single style sheet.
5102 To cause perltidy to write a style sheet to standard output and
5104 exit, use the -ss, or --stylesheet, flag. This is useful if the
5105 style sheet could not be written for some reason, such as if the
5106 -pre flag was used. Thus, for example,
5107 perltidy -html -ss >mystyle.css
5109 will write a style sheet with the default properties to file
5111 mystyle.css.
5112 The use of style sheets is encouraged, but a web page without a
5114 style sheets can be created with the flag -nss. Use this option if
5115 you must to be sure that older browsers (roughly speaking, versions
5116 prior to 4.0 of Netscape Navigator and Internet Explorer) can
5117 display the syntax-coloring of the html files.
5118 Controlling HTML properties
5120 Note: It is usually more convenient to accept the default
5121 properties and then edit the stylesheet which is produced.
5122 However, this section shows how to control the properties with
5123 flags to perltidy.
5124 Syntax colors may be changed from their default values by flags of
5126 the either the long form, -html-color-xxxxxx=n, or more
5127 conveniently the short form, -hcx=n, where xxxxxx is one of the
5128 following words, and x is the corresponding abbreviation:
5129 Token Type xxxxxx x
5131 ---------- -------- --
5132 comment comment c
5133 number numeric n
5134 identifier identifier i
5135 bareword, function bareword w
5136 keyword keyword k
5137 quite, pattern quote q
5138 here doc text here-doc-text h
5139 here doc target here-doc-target hh
5140 punctuation punctuation pu
5141 parentheses paren p
5142 structural braces structure s
5143 semicolon semicolon sc
5144 colon colon co
5145 comma comma cm
5146 label label j
5147 sub definition name subroutine m
5148 pod text pod-text pd
5149 A default set of colors has been defined, but they may be changed
5151 by providing values to any of the following parameters, where n is
5152 either a 6 digit hex RGB color value or an ascii name for a color,
5153 such as 'red'.
5154 To illustrate, the following command will produce an html file
5156 somefile.pl.html with "aqua" keywords:
5157 perltidy -html -hck=00ffff somefile.pl
5159 and this should be equivalent for most browsers:
5161 perltidy -html -hck=aqua somefile.pl
5163 Perltidy merely writes any non-hex names that it sees in the html
5165 file. The following 16 color names are defined in the HTML 3.2
5166 standard:
5167 black => 000000,
5169 silver => c0c0c0,
5170 gray => 808080,
5171 white => ffffff,
5172 maroon => 800000,
5173 red => ff0000,
5174 purple => 800080,
5175 fuchsia => ff00ff,
5176 green => 008000,
5177 lime => 00ff00,
5178 olive => 808000,
5179 yellow => ffff00
5180 navy => 000080,
5181 blue => 0000ff,
5182 teal => 008080,
5183 aqua => 00ffff,
5184 Many more names are supported in specific browsers, but it is
5186 safest to use the hex codes for other colors. Helpful color tables
5187 can be located with an internet search for "HTML color tables".
5188 Besides color, two other character attributes may be set: bold, and
5190 italics. To set a token type to use bold, use the flag
5191 --html-bold-xxxxxx or -hbx, where xxxxxx or x are the long or short
5192 names from the above table. Conversely, to set a token type to NOT
5193 use bold, use --nohtml-bold-xxxxxx or -nhbx.
5194 Likewise, to set a token type to use an italic font, use the flag
5196 --html-italic-xxxxxx or -hix, where again xxxxxx or x are the long
5197 or short names from the above table. And to set a token type to
5198 NOT use italics, use --nohtml-italic-xxxxxx or -nhix.
5199 For example, to use bold braces and lime color, non-bold, italics
5201 keywords the following command would be used:
5202 perltidy -html -hbs -hck=00FF00 -nhbk -hik somefile.pl
5204 The background color can be specified with
5206 --html-color-background=n, or -hcbg=n for short, where n is a 6
5207 character hex RGB value. The default color of text is the value
5208 given to punctuation, which is black as a default.
5209 Here are some notes and hints:
5211 1. If you find a preferred set of these parameters, you may want to
5213 create a .perltidyrc file containing them. See the perltidy man
5214 page for an explanation.
5215 2. Rather than specifying values for these parameters, it is
5217 probably easier to accept the defaults and then edit a style sheet.
5218 The style sheet contains comments which should make this easy.
5219 3. The syntax-colored html files can be very large, so it may be
5221 best to split large files into smaller pieces to improve download
5222 times.
5223
5225 Specifying Block Types
5226 Several parameters which refer to code block types may be customized by
5227 also specifying an associated list of block types. The type of a block
5228 is the name of the keyword which introduces that block, such as if,
5229 else, or sub. An exception is a labeled block, which has no keyword,
5230 and should be specified with just a colon. To specify all blocks use
5231 '*'.
5232 The keyword sub indicates a named sub. For anonymous subs, use the
5234 special keyword asub.
5235 For example, the following parameter specifies "sub", labels, "BEGIN",
5237 and "END" blocks:
5238 -cscl="sub : BEGIN END"
5240 (the meaning of the -cscl parameter is described above.) Note that
5242 quotes are required around the list of block types because of the
5243 spaces. For another example, the following list specifies all block
5244 types for vertical tightness:
5245 -bbvtl='*'
5247 Specifying File Extensions
5249 Several parameters allow default file extensions to be overridden. For
5250 example, a backup file extension may be specified with -bext=ext, where
5251 ext is some new extension. In order to provides the user some
5252 flexibility, the following convention is used in all cases to decide if
5253 a leading '.' should be used. If the extension "ext" begins with
5254 "A-Z", "a-z", or "0-9", then it will be appended to the filename with
5255 an intermediate '.' (or perhaps a '_' on VMS systems). Otherwise, it
5256 will be appended directly.
5257 For example, suppose the file is somefile.pl. For "-bext=old", a '.'
5259 is added to give somefile.pl.old. For "-bext=.old", no additional '.'
5260 is added, so again the backup file is somefile.pl.old. For "-bext=~",
5261 then no dot is added, and the backup file will be somefile.pl~ .
5262
5264 The following list shows all short parameter names which allow a prefix
5265 'n' to produce the negated form:
5266 D anl asbl asc ast asu atc atnl aws b
5268 baa baao bar bbao bbb bbc bbs bl bli boa
5269 boc bok bol bom bos bot cblx ce conv cpb
5270 cs csc cscb cscw dac dbc dbs dcbl dcsc ddf
5271 dln dnl dop dp dpro drc dsc dsm dsn dtc
5272 dtt dwic dwls dwrs dws eos f fll fpva frm
5273 fs fso gcs hbc hbcm hbco hbh hbhh hbi hbj
5274 hbk hbm hbn hbp hbpd hbpu hbq hbs hbsc hbv
5275 hbw hent hic hicm hico hih hihh hii hij hik
5276 him hin hip hipd hipu hiq his hisc hiv hiw
5277 hsc html ibc icb icp iob isbc iscl kgb kgbd
5278 kgbi kis lal log lop lp lsl mem nib ohbr
5279 okw ola olc oll olq opr opt osbc osbr otr
5280 ple pod pvl q sac sbc sbl scbb schb scp
5281 scsb sct se sfp sfs skp sob sobb sohb sop
5282 sosb sot ssc st sts t tac tbc toc tp
5283 tqw trp ts tsc tso vbc vc vmll vsc w
5284 wfc wn x xci xlp xs
5285 Equivalently, the prefix 'no' or 'no-' on the corresponding long names
5287 may be used.
5288
5290 Parsing Limitations
5291 Perltidy should work properly on most perl scripts. It does a lot
5292 of self-checking, but still, it is possible that an error could be
5293 introduced and go undetected. Therefore, it is essential to make
5294 careful backups and to test reformatted scripts.
5295 The main current limitation is that perltidy does not scan modules
5297 included with 'use' statements. This makes it necessary to guess
5298 the context of any bare words introduced by such modules. Perltidy
5299 has good guessing algorithms, but they are not infallible. When it
5300 must guess, it leaves a message in the log file.
5301 If you encounter a bug, please report it.
5303 What perltidy does not parse and format
5305 Perltidy indents but does not reformat comments and "qw" quotes.
5306 Perltidy does not in any way modify the contents of here documents
5307 or quoted text, even if they contain source code. (You could,
5308 however, reformat them separately). Perltidy does not format
5309 'format' sections in any way. And, of course, it does not modify
5310 pod documents.
5311
5313 Temporary files
5314 Under the -html option with the default --pod2html flag, a
5315 temporary file is required to pass text to Pod::Html. Unix systems
5316 will try to use the POSIX tmpnam() function. Otherwise the file
5317 perltidy.TMP will be temporarily created in the current working
5318 directory.
5319 Special files when standard input is used
5321 When standard input is used, the log file, if saved, is
5322 perltidy.LOG, and any errors are written to perltidy.ERR unless the
5323 -se flag is set. These are saved in the current working directory.
5324 Files overwritten
5326 The following file extensions are used by perltidy, and files with
5327 these extensions may be overwritten or deleted: .ERR, .LOG, .TEE,
5328 and/or .tdy, .html, and .bak, depending on the run type and
5329 settings.
5330 Files extensions limitations
5332 Perltidy does not operate on files for which the run could produce
5333 a file with a duplicated file extension. These extensions include
5334 .LOG, .ERR, .TEE, and perhaps .tdy and .bak, depending on the run
5335 type. The purpose of this rule is to prevent generating confusing
5336 filenames such as somefile.tdy.tdy.tdy.
5337
5339 An exit value of 0, 1, or 2 is returned by perltidy to indicate the
5340 status of the result.
5341 A exit value of 0 indicates that perltidy ran to completion with no
5343 error messages.
5344 A non-zero exit value indicates some kind of problem was detected.
5346 An exit value of 1 indicates that perltidy terminated prematurely,
5348 usually due to some kind of errors in the input parameters. This can
5349 happen for example if a parameter is misspelled or given an invalid
5350 value. Error messages in the standard error output will indicate the
5351 cause of any problem. If perltidy terminates prematurely then no
5352 output files will be produced.
5353 An exit value of 2 indicates that perltidy was able to run to
5355 completion but there there are (1) warning messages in the standard
5356 error output related to parameter errors or problems and/or (2) warning
5357 messages in the perltidy error file(s) relating to possible syntax
5358 errors in one or more of the source script(s) being tidied. When
5359 multiple files are being processed, an error detected in any single
5360 file will produce this type of exit condition.
5361
5363 perlstyle(1), Perl::Tidy(3)
5364
5366 The perltidy binary uses the Perl::Tidy module and is installed when
5367 that module is installed. The module name is case-sensitive. For
5368 example, the basic command for installing with cpanm is 'cpanm
5369 Perl::Tidy'.
5370
5372 This man page documents perltidy version 20230309
5373
5375 The source code repository is at
5376 <https://github.com/perltidy/perltidy>.
5377 To report a new bug or problem, use the "issues" link on this page.
5379
5381 Copyright (c) 2000-2022 by Steve Hancock
5382
5384 This package is free software; you can redistribute it and/or modify it
5385 under the terms of the "GNU General Public License".
5386 Please refer to the file "COPYING" for details.
5388
5390 This package is distributed in the hope that it will be useful, but
5391 WITHOUT ANY WARRANTY; without even the implied warranty of
5392 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
5393 See the "GNU General Public License" for more details.
5395perl v5.36.0 2023-03-09 PERLTIDY(1)