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. This document describes the parameters available for
18 controlling this formatting.
19 Perltidy is a commandline frontend to the module Perl::Tidy. For
21 documentation describing how to call the Perl::Tidy module from other
22 applications see the separate documentation for Perl::Tidy. It is the
23 file Perl::Tidy.pod in the source distribution.
24 Many users will find enough information in "EXAMPLES" to get started.
26 New users may benefit from the short tutorial which can be found at
27 http://perltidy.sourceforge.net/tutorial.html
28 A convenient aid to systematically defining a set of style parameters
30 can be found at http://perltidy.sourceforge.net/stylekey.html
31 Perltidy can produce output on either of two modes, depending on the
33 existence of an -html flag. Without this flag, the output is passed
34 through a formatter. The default formatting tries to follow the
35 recommendations in perlstyle(1), but it can be controlled in detail
36 with numerous input parameters, which are described in "FORMATTING
37 OPTIONS".
38 When the -html flag is given, the output is passed through an HTML
40 formatter which is described in "HTML OPTIONS".
41
43 perltidy somefile.pl
44 This will produce a file somefile.pl.tdy containing the script
46 reformatted using the default options, which approximate the style
47 suggested in perlstyle(1). The source file somefile.pl is unchanged.
48 perltidy *.pl
50 Execute perltidy on all .pl files in the current directory with the
52 default options. The output will be in files with an appended .tdy
53 extension. For any file with an error, there will be a file with
54 extension .ERR.
55 perltidy -b file1.pl file2.pl
57 Modify file1.pl and file2.pl in place, and backup the originals to
59 file1.pl.bak and file2.pl.bak. If file1.pl.bak and/or file2.pl.bak
60 already exist, they will be overwritten.
61 perltidy -b -bext='/' file1.pl file2.pl
63 Same as the previous example except that the backup files file1.pl.bak
65 and file2.pl.bak will be deleted if there are no errors.
66 perltidy -gnu somefile.pl
68 Execute perltidy on file somefile.pl with a style which approximates
70 the GNU Coding Standards for C programs. The output will be
71 somefile.pl.tdy.
72 perltidy -i=3 somefile.pl
74 Execute perltidy on file somefile.pl, with 3 columns for each level of
76 indentation (-i=3) instead of the default 4 columns. There will not be
77 any tabs in the reformatted script, except for any which already exist
78 in comments, pod documents, quotes, and here documents. Output will be
79 somefile.pl.tdy.
80 perltidy -i=3 -et=8 somefile.pl
82 Same as the previous example, except that leading whitespace will be
84 entabbed with one tab character per 8 spaces.
85 perltidy -ce -l=72 somefile.pl
87 Execute perltidy on file somefile.pl with all defaults except use
89 "cuddled elses" (-ce) and a maximum line length of 72 columns (-l=72)
90 instead of the default 80 columns.
91 perltidy -g somefile.pl
93 Execute perltidy on file somefile.pl and save a log file
95 somefile.pl.LOG which shows the nesting of braces, parentheses, and
96 square brackets at the start of every line.
97 perltidy -html somefile.pl
99 This will produce a file somefile.pl.html containing the script with
101 html markup. The output file will contain an embedded style sheet in
102 the <HEAD> section which may be edited to change the appearance.
103 perltidy -html -css=mystyle.css somefile.pl
105 This will produce a file somefile.pl.html containing the script with
107 html markup. This output file will contain a link to a separate style
108 sheet file mystyle.css. If the file mystyle.css does not exist, it
109 will be created. If it exists, it will not be overwritten.
110 perltidy -html -pre somefile.pl
112 Write an html snippet with only the PRE section to somefile.pl.html.
114 This is useful when code snippets are being formatted for inclusion in
115 a larger web page. No style sheet will be written in this case.
116 perltidy -html -ss >mystyle.css
118 Write a style sheet to mystyle.css and exit.
120 perltidy -html -frm mymodule.pm
122 Write html with a frame holding a table of contents and the source
124 code. The output files will be mymodule.pm.html (the frame),
125 mymodule.pm.toc.html (the table of contents), and mymodule.pm.src.html
126 (the source code).
127
129 The entire command line is scanned for options, and they are processed
130 before any files are processed. As a result, it does not matter
131 whether flags are before or after any filenames. However, the relative
132 order of parameters is important, with later parameters overriding the
133 values of earlier parameters.
134 For each parameter, there is a long name and a short name. The short
136 names are convenient for keyboard input, while the long names are self-
137 documenting and therefore useful in scripts. It is customary to use
138 two leading dashes for long names, but one may be used.
139 Most parameters which serve as on/off flags can be negated with a
141 leading "n" (for the short name) or a leading "no" or "no-" (for the
142 long name). For example, the flag to outdent long quotes is -olq or
143 --outdent-long-quotes. The flag to skip this is -nolq or
144 --nooutdent-long-quotes or --no-outdent-long-quotes.
145 Options may not be bundled together. In other words, options -q and -g
147 may NOT be entered as -qg.
148 Option names may be terminated early as long as they are uniquely
150 identified. For example, instead of --dump-token-types, it would be
151 sufficient to enter --dump-tok, or even --dump-t, to uniquely identify
152 this command.
153 I/O control
155 The following parameters concern the files which are read and written.
156 -h, --help
158 Show summary of usage and exit.
159 -o=filename, --outfile=filename
161 Name of the output file (only if a single input file is being
162 processed). If no output file is specified, and output is not
163 redirected to the standard output (see -st), the output will go to
164 filename.tdy. [Note: - does not redirect to standard output. Use
165 -st instead.]
166 -st, --standard-output
168 Perltidy must be able to operate on an arbitrarily large number of
169 files in a single run, with each output being directed to a
170 different output file. Obviously this would conflict with
171 outputting to the single standard output device, so a special flag,
172 -st, is required to request outputting to the standard output. For
173 example,
174 perltidy somefile.pl -st >somefile.new.pl
176 This option may only be used if there is just a single input file.
178 The default is -nst or --nostandard-output.
179 -se, --standard-error-output
181 If perltidy detects an error when processing file somefile.pl, its
182 default behavior is to write error messages to file
183 somefile.pl.ERR. Use -se to cause all error messages to be sent to
184 the standard error output stream instead. This directive may be
185 negated with -nse. Thus, you may place -se in a .perltidyrc and
186 override it when desired with -nse on the command line.
187 -oext=ext, --output-file-extension=ext
189 Change the extension of the output file to be ext instead of the
190 default tdy (or html in case the --html option is used). See
191 "Specifying File Extensions".
192 -opath=path, --output-path=path
194 When perltidy creates a filename for an output file, by default it
195 merely appends an extension to the path and basename of the input
196 file. This parameter causes the path to be changed to path
197 instead.
198 The path should end in a valid path separator character, but
200 perltidy will try to add one if it is missing.
201 For example
203 perltidy somefile.pl -opath=/tmp/
205 will produce /tmp/somefile.pl.tdy. Otherwise, somefile.pl.tdy will
207 appear in whatever directory contains somefile.pl.
208 If the path contains spaces, it should be placed in quotes.
210 This parameter will be ignored if output is being directed to
212 standard output, or if it is being specified explicitly with the
213 -o=s parameter.
214 -b, --backup-and-modify-in-place
216 Modify the input file or files in-place and save the original with
217 the extension .bak. Any existing .bak file will be deleted. See
218 next item for changing the default backup extension, and for
219 eliminating the backup file altogether.
220 A -b flag will be ignored if input is from standard input or goes
222 to standard output, or if the -html flag is set.
223 In particular, if you want to use both the -b flag and the -pbp
225 (--perl-best-practices) flag, then you must put a -nst flag after
226 the -pbp flag because it contains a -st flag as one of its
227 components, which means that output will go to the standard output
228 stream.
229 -bext=ext, --backup-file-extension=ext
231 This parameter serves two purposes: (1) to change the extension of
232 the backup file to be something other than the default .bak, and
233 (2) to indicate that no backup file should be saved.
234 To change the default extension to something other than .bak see
236 "Specifying File Extensions".
237 A backup file of the source is always written, but you can request
239 that it be deleted at the end of processing if there were no
240 errors. This is risky unless the source code is being maintained
241 with a source code control system.
242 To indicate that the backup should be deleted include one forward
244 slash, /, in the extension. If any text remains after the slash is
245 removed it will be used to define the backup file extension (which
246 is always created and only deleted if there were no errors).
247 Here are some examples:
249 Parameter Extension Backup File Treatment
251 <-bext=bak> F<.bak> Keep (same as the default behavior)
252 <-bext='/'> F<.bak> Delete if no errors
253 <-bext='/backup'> F<.backup> Delete if no errors
254 <-bext='original/'> F<.original> Delete if no errors
255 -w, --warning-output
257 Setting -w causes any non-critical warning messages to be reported
258 as errors. These include messages about possible pod problems,
259 possibly bad starting indentation level, and cautions about
260 indirect object usage. The default, -nw or --nowarning-output, is
261 not to include these warnings.
262 -q, --quiet
264 Deactivate error messages (for running under an editor).
265 For example, if you use a vi-style editor, such as vim, you may
267 execute perltidy as a filter from within the editor using something
268 like
269 :n1,n2!perltidy -q
271 where "n1,n2" represents the selected text. Without the -q flag,
273 any error message may mess up your screen, so be prepared to use
274 your "undo" key.
275 -log, --logfile
277 Save the .LOG file, which has many useful diagnostics. Perltidy
278 always creates a .LOG file, but by default it is deleted unless a
279 program bug is suspected. Setting the -log flag forces the log
280 file to be saved.
281 -g=n, --logfile-gap=n
283 Set maximum interval between input code lines in the logfile. This
284 purpose of this flag is to assist in debugging nesting errors. The
285 value of "n" is optional. If you set the flag -g without the value
286 of "n", it will be taken to be 1, meaning that every line will be
287 written to the log file. This can be helpful if you are looking
288 for a brace, paren, or bracket nesting error.
289 Setting -g also causes the logfile to be saved, so it is not
291 necessary to also include -log.
292 If no -g flag is given, a value of 50 will be used, meaning that at
294 least every 50th line will be recorded in the logfile. This helps
295 prevent excessively long log files.
296 Setting a negative value of "n" is the same as not setting -g at
298 all.
299 -npro --noprofile
301 Ignore any .perltidyrc command file. Normally, perltidy looks
302 first in your current directory for a .perltidyrc file of
303 parameters. (The format is described below). If it finds one, it
304 applies those options to the initial default values, and then it
305 applies any that have been defined on the command line. If no
306 .perltidyrc file is found, it looks for one in your home directory.
307 If you set the -npro flag, perltidy will not look for this file.
309 -pro=filename or --profile=filename
311 To simplify testing and switching .perltidyrc files, this command
312 may be used to specify a configuration file which will override the
313 default name of .perltidyrc. There must not be a space on either
314 side of the '=' sign. For example, the line
315 perltidy -pro=testcfg
317 would cause file testcfg to be used instead of the default
319 .perltidyrc.
320 A pathname begins with three dots, e.g. ".../.perltidyrc",
322 indicates that the file should be searched for starting in the
323 current directory and working upwards. This makes it easier to have
324 multiple projects each with their own .perltidyrc in their root
325 directories.
326 -opt, --show-options
328 Write a list of all options used to the .LOG file. Please see
329 --dump-options for a simpler way to do this.
330 -f, --force-read-binary
332 Force perltidy to process binary files. To avoid producing
333 excessive error messages, perltidy skips files identified by the
334 system as non-text. However, valid perl scripts containing binary
335 data may sometimes be identified as non-text, and this flag forces
336 perltidy to process them.
337 -ast, --assert-tidy
339 This flag asserts that the input and output code streams are
340 identical, or in other words that the input code is already 'tidy'
341 according to the formatting parameters. If this is not the case,
342 an error message noting this is produced. This error message will
343 cause the process to return a non-zero exit code. The test for
344 this is made by comparing an MD5 hash value for the input and
345 output code streams. This flag has no other effect on the
346 functioning of perltidy. This might be useful for certain code
347 maintenance operations. Note: you will not see this message if you
348 have error messages turned off with the -quiet flag.
349 -asu, --assert-untidy
351 This flag asserts that the input and output code streams are
352 different, or in other words that the input code is 'untidy'
353 according to the formatting parameters. If this is not the case,
354 an error message noting this is produced. This flag has no other
355 effect on the functioning of perltidy.
356 -sal=s, --sub-alias-list=s
358 This flag causes one or more words to be treated the same as if
359 they were the keyword 'sub'. The string s contains one or more
360 alias words, separated by spaces or commas.
361 For example,
363 perltidy -sal='method fun _sub M4'
365 will cause the perltidy to treat the words 'method', 'fun', '_sub'
367 and 'M4' the same as if they were 'sub'. Note that if the alias
368 words are separated by spaces then the string of words should be
369 placed in quotes.
370 Note that several other parameters accept a list of keywords,
372 including 'sub' (see "Specifying Block Types"). You do not need to
373 include any sub aliases in these lists. Just include keyword 'sub'
374 if you wish, and all aliases are automatically included.
375 -gal=s, --grep-alias-list=s
377 This flag allows a code block following an external 'list operator'
378 function to be formatted as if it followed one of the built-in
379 keywords grep, map or sort. The string s contains the names of
380 one or more such list operators, separated by spaces or commas.
381 By 'list operator' is meant a function which is invoked in the form
383 word {BLOCK} @list
385 Perltidy tries to keep code blocks for these functions intact,
387 since they are usually short, and does not automatically break
388 after the closing brace since a list may follow. It also does some
389 special handling of continuation indentation.
390 For example, the code block arguments to functions 'My_grep' and
392 'My_map' can be given formatting like 'grep' with
393 perltidy -gal='My_grep My_map'
395 By default, the following list operators in List::Util are
397 automatically included:
398 all any first none notall reduce reductions
400 Any operators specified with --grep-alias-list are added to this
402 list. The next parameter can be used to remove words from this
403 default list.
404 -gaxl=s, --grep-alias-exclusion-list=s
406 The -gaxl=s flag provides a method for removing any of the default
407 list operators given above by listing them in the string s. To
408 remove all of the default operators use -gaxl='*'.
409
411 Basic Options
412 --notidy
413 This flag disables all formatting and causes the input to be copied
414 unchanged to the output except for possible changes in line ending
415 characters and any pre- and post-filters. This can be useful in
416 conjunction with a hierarchical set of .perltidyrc files to avoid
417 unwanted code tidying. See also "Skipping Selected Sections of
418 Code" for a way to avoid tidying specific sections of code.
419 -i=n, --indent-columns=n
421 Use n columns per indentation level (default n=4).
422 -l=n, --maximum-line-length=n
424 The default maximum line length is n=80 characters. Perltidy will
425 try to find line break points to keep lines below this length.
426 However, long quotes and side comments may cause lines to exceed
427 this length.
428 The default length of 80 comes from the past when this was the
430 standard CRT screen width. Many programmers prefer to increase
431 this to something like 120.
432 Setting -l=0 is equivalent to setting -l=(a very large number).
434 But this is not recommended because, for example, a very long list
435 will be formatted in a single long line.
436 -vmll, --variable-maximum-line-length
438 A problem arises using a fixed maximum line length with very deeply
439 nested code and data structures because eventually the amount of
440 leading whitespace used for indicating indentation takes up most or
441 all of the available line width, leaving little or no space for the
442 actual code or data. One solution is to use a very long line
443 length. Another solution is to use the -vmll flag, which basically
444 tells perltidy to ignore leading whitespace when measuring the line
445 length.
446 To be precise, when the -vmll parameter is set, the maximum line
448 length of a line of code will be M+L*I, where
449 M is the value of --maximum-line-length=M (-l=M), default 80,
451 I is the value of --indent-columns=I (-i=I), default 4,
452 L is the indentation level of the line of code
453 When this flag is set, the choice of breakpoints for a block of
455 code should be essentially independent of its nesting depth.
456 However, the absolute line lengths, including leading whitespace,
457 can still be arbitrarily large. This problem can be avoided by
458 including the next parameter.
459 The default is not to do this (-nvmll).
461 -wc=n, --whitespace-cycle=n
463 This flag also addresses problems with very deeply nested code and
464 data structures. When the nesting depth exceeds the value n the
465 leading whitespace will be reduced and start at a depth of 1 again.
466 The result is that blocks of code will shift back to the left
467 rather than moving arbitrarily far to the right. This occurs
468 cyclically to any depth.
469 For example if one level of indentation equals 4 spaces (-i=4, the
471 default), and one uses -wc=15, then if the leading whitespace on a
472 line exceeds about 4*15=60 spaces it will be reduced back to 4*1=4
473 spaces and continue increasing from there. If the whitespace never
474 exceeds this limit the formatting remains unchanged.
475 The combination of -vmll and -wc=n provides a solution to the
477 problem of displaying arbitrarily deep data structures and code in
478 a finite window, although -wc=n may of course be used without
479 -vmll.
480 The default is not to use this, which can also be indicated using
482 -wc=0.
483 Tabs
485 Using tab characters will almost certainly lead to future
486 portability and maintenance problems, so the default and
487 recommendation is not to use them. For those who prefer tabs,
488 however, there are two different options.
489 Except for possibly introducing tab indentation characters, as
491 outlined below, perltidy does not introduce any tab characters into
492 your file, and it removes any tabs from the code (unless requested
493 not to do so with -fws). If you have any tabs in your comments,
494 quotes, or here-documents, they will remain.
495 -et=n, --entab-leading-whitespace
497 This flag causes each n leading space characters produced by
498 the formatting process to be replaced by one tab character.
499 The formatting process itself works with space characters. The
500 -et=n parameter is applied as a last step, after formatting is
501 complete, to convert leading spaces into tabs. Before starting
502 to use tabs, it is essential to first get the indentation
503 controls set as desired without tabs, particularly the two
504 parameters --indent-columns=n (or -i=n) and
505 --continuation-indentation=n (or -ci=n).
506 The value of the integer n can be any value but can be
508 coordinated with the number of spaces used for indentation. For
509 example, -et=4 -ci=4 -i=4 will produce one tab for each
510 indentation level and and one for each continuation indentation
511 level. You may want to coordinate the value of n with what
512 your display software assumes for the spacing of a tab.
513 -t, --tabs
515 This flag causes one leading tab character to be inserted for
516 each level of indentation. Certain other features are
517 incompatible with this option, and if these options are also
518 given, then a warning message will be issued and this flag will
519 be unset. One example is the -lp option. This flag is retained
520 for backwards compatibility, but if you use tabs, the -et=n
521 flag is recommended. If both -t and -et=n are set, the -et=n
522 is used.
523 -dt=n, --default-tabsize=n
525 If the first line of code passed to perltidy contains leading
526 tabs but no tab scheme is specified for the output stream then
527 perltidy must guess how many spaces correspond to each leading
528 tab. This number of spaces n corresponding to each leading tab
529 of the input stream may be specified with -dt=n. The default
530 is n=8.
531 This flag has no effect if a tab scheme is specified for the
533 output stream, because then the input stream is assumed to use
534 the same tab scheme and indentation spaces as for the output
535 stream (any other assumption would lead to unstable editing).
536 -xs, --extended-syntax
538 A problem with formatting Perl code is that some modules can
539 introduce new syntax. This flag allows perltidy to handle certain
540 common extensions to the standard syntax without complaint.
541 For example, without this flag a structure such as the following
543 would generate a syntax error and the braces would not be balanced:
544 method deposit( Num $amount) {
546 $self->balance( $self->balance + $amount );
547 }
548 For one of the extensions, module Switch::Plain, colons are marked
550 as labels. If you use this module, you may want to also use the
551 --nooutdent-labels flag to prevent lines such as 'default:' from
552 being outdented.
553 This flag is enabled by default but it can be deactivated with
555 -nxs. Probably the only reason to deactivate this flag is to
556 generate more diagnostic messages when debugging a script.
557 For another method of handling extended syntax see the section
559 "Skipping Selected Sections of Code".
560 -io, --indent-only
562 This flag is used to deactivate all whitespace and line break
563 changes within non-blank lines of code. When it is in effect, the
564 only change to the script will be to the indentation and to the
565 number of blank lines. And any flags controlling whitespace and
566 newlines will be ignored. You might want to use this if you are
567 perfectly happy with your whitespace and line breaks, and merely
568 want perltidy to handle the indentation. (This also speeds up
569 perltidy by well over a factor of two, so it might be useful when
570 perltidy is merely being used to help find a brace error in a large
571 script).
572 Setting this flag is equivalent to setting --freeze-newlines and
574 --freeze-whitespace.
575 If you also want to keep your existing blank lines exactly as they
577 are, you can add --freeze-blank-lines.
578 With this option perltidy is still free to modify the indenting
580 (and outdenting) of code and comments as it normally would. If you
581 also want to prevent long comment lines from being outdented, you
582 can add either -noll or -l=0.
583 Setting this flag will prevent perltidy from doing any special
585 operations on closing side comments. You may still delete all side
586 comments however when this flag is in effect.
587 -enc=s, --character-encoding=s
589 This flag indicates if the input data stream use a character
590 encoding. Perltidy does not look for the encoding directives in
591 the source stream, such as use utf8, and instead relies on this
592 flag to determine the encoding. (Note that perltidy often works on
593 snippets of code rather than complete files so it cannot rely on
594 use utf8 directives).
595 The possible values for s are:
597 -enc=none if no encoding is used, or
599 -enc=utf8 for encoding in utf8
600 -enc=guess if perltidy should guess between these two possibilities.
601 The value none causes the stream to be processed without special
603 encoding assumptions. This is appropriate for files which are
604 written in single-byte character encodings such as latin-1.
605 The value utf8 causes the stream to be read and written as UTF-8.
607 If the input stream cannot be decoded with this encoding then
608 processing is not done.
609 The value guess tells perltidy to guess between either utf8
611 encoding or no encoding (meaning one character per byte). The
612 guess option uses the Encode::Guess module which has been found to
613 be reliable at detecting if a file is encoded in utf8 or not.
614 The current default is guess.
616 The abbreviations -utf8 or -UTF8 are equivalent to -enc=utf8, and
618 the abbreviation -guess is equivalent to -enc=guess. So to process
619 a file named file.pl which is encoded in UTF-8 you can use:
620 perltidy -utf8 file.pl
622 or
624 perltidy -guess file.pl
626 or simply
628 perltidy file.pl
630 since -guess is the default.
632 To process files with an encoding other than UTF-8, it would be
634 necessary to write a short program which calls the Perl::Tidy
635 module with some pre- and post-processing to handle decoding and
636 encoding.
637 -eos=s, --encode-output-strings=s
639 This flag was added to resolve an issue involving the interface
640 between Perl::Tidy and calling programs, and in particular
641 Code::TidyAll (tidyall).
642 If you only run the perltidy binary this flag has no effect. If
644 you run a program which calls the Perl::Tidy module and receives a
645 string in return, then the meaning of the flag is as follows:
646 • The setting -eos means Perl::Tidy should encode any string
648 which it decodes. This is the default because it makes
649 perltidy behave well as a filter, and is the correct setting
650 for most programs.
651 • The setting -neos means that a string should remain decoded if
653 it was decoded by Perl::Tidy. This is only appropriate if the
654 calling program will handle any needed encoding before
655 outputting the string.
656 The default was changed from -neos to -eos in versions after
658 20220217. If this change causes a program to start running
659 incorrectly on encoded files, an emergency fix might be to set
660 -neos. Additional information can be found in the man pages for
661 the Perl::Tidy module and also in
662 <https://github.com/perltidy/perltidy/blob/master/docs/eos_flag.md>.
663 -gcs, --use-unicode-gcstring
665 This flag controls whether or not perltidy may use module
666 Unicode::GCString to obtain accurate display widths of wide
667 characters. The default is --nouse-unicode-gcstring.
668 If this flag is set, and text is encoded, perltidy will look for
670 the module Unicode::GCString and, if found, will use it to obtain
671 character display widths. This can improve displayed vertical
672 alignment for files with wide characters. It is a nice feature but
673 it is off by default to avoid conflicting formatting when there are
674 multiple developers. Perltidy installation does not require
675 Unicode::GCString, so users wanting to use this feature need set
676 this flag and also to install Unicode::GCString separately.
677 If this flag is set and perltidy does not find module
679 Unicode::GCString, a warning message will be produced and
680 processing will continue but without the potential benefit provided
681 by the module.
682 Also note that actual vertical alignment depends upon the fonts
684 used by the text display software, so vertical alignment may not be
685 optimal even when Unicode::GCString is used.
686 -ole=s, --output-line-ending=s
688 where s="win", "dos", "unix", or "mac". This flag tells perltidy
689 to output line endings for a specific system. Normally, perltidy
690 writes files with the line separator character of the host system.
691 The "win" and "dos" flags have an identical result.
692 -ple, --preserve-line-endings
694 This flag tells perltidy to write its output files with the same
695 line endings as the input file, if possible. It should work for
696 dos, unix, and mac line endings. It will only work if perltidy
697 input comes from a filename (rather than stdin, for example). If
698 perltidy has trouble determining the input file line ending, it
699 will revert to the default behavior of using the line ending of the
700 host system.
701 -atnl, --add-terminal-newline
703 This flag, which is enabled by default, allows perltidy to
704 terminate the last line of the output stream with a newline
705 character, regardless of whether or not the input stream was
706 terminated with a newline character. If this flag is negated, with
707 -natnl, then perltidy will add a terminal newline to the the output
708 stream only if the input stream is terminated with a newline.
709 Negating this flag may be useful for manipulating one-line scripts
711 intended for use on a command line.
712 -it=n, --iterations=n
714 This flag causes perltidy to do n complete iterations. The reason
715 for this flag is that code beautification is an iterative process
716 and in some cases the output from perltidy can be different if it
717 is applied a second time. For most purposes the default of n=1
718 should be satisfactory. However n=2 can be useful when a major
719 style change is being made, or when code is being beautified on
720 check-in to a source code control system. It has been found to be
721 extremely rare for the output to change after 2 iterations. If a
722 value n is greater than 2 is input then a convergence test will be
723 used to stop the iterations as soon as possible, almost always
724 after 2 iterations. See the next item for a simplified iteration
725 control.
726 This flag has no effect when perltidy is used to generate html.
728 -conv, --converge
730 This flag is equivalent to -it=4 and is included to simplify
731 iteration control. For all practical purposes one either does or
732 does not want to be sure that the output is converged, and there is
733 no penalty to using a large iteration limit since perltidy will
734 check for convergence and stop iterating as soon as possible. The
735 default is -nconv (no convergence check). Using -conv will
736 approximately double run time since typically one extra iteration
737 is required to verify convergence. No extra iterations are
738 required if no new line breaks are made, and two extra iterations
739 are occasionally needed when reformatting complex code structures,
740 such as deeply nested ternary statements.
741 Code Indentation Control
743 -ci=n, --continuation-indentation=n
744 Continuation indentation is extra indentation spaces applied when a
745 long line is broken. The default is n=2, illustrated here:
746 my $level = # -ci=2
748 ( $max_index_to_go >= 0 ) ? $levels_to_go[0] : $last_output_level;
749 The same example, with n=0, is a little harder to read:
751 my $level = # -ci=0
753 ( $max_index_to_go >= 0 ) ? $levels_to_go[0] : $last_output_level;
754 The value given to -ci is also used by some commands when a small
756 space is required. Examples are commands for outdenting labels,
757 -ola, and control keywords, -okw.
758 When default values are not used, it is recommended that either
760 (1) the value n given with -ci=n be no more than about one-half of
762 the number of spaces assigned to a full indentation level on the
763 -i=n command, or
764 (2) the flag -extended-continuation-indentation is used (see next
766 section).
767 -xci, --extended-continuation-indentation
769 This flag allows perltidy to use some improvements which have been
770 made to its indentation model. One of the things it does is
771 "extend" continuation indentation deeper into structures, hence the
772 name. The improved indentation is particularly noticeable when the
773 flags -ci=n and -i=n use the same value of n. There are no
774 significant disadvantages to using this flag, but to avoid
775 disturbing existing formatting the default is not to use it, -nxci.
776 Please see the section "-pbp, --perl-best-practices" for an example
778 of how this flag can improve the formatting of ternary statements.
779 It can also improve indentation of some multi-line qw lists as
780 shown below.
781 # perltidy
783 foreach $color (
784 qw(
785 AntiqueWhite3 Bisque1 Bisque2 Bisque3 Bisque4
786 SlateBlue3 RoyalBlue1 SteelBlue2 DeepSkyBlue3
787 ),
788 qw(
789 LightBlue1 DarkSlateGray1 Aquamarine2 DarkSeaGreen2
790 SeaGreen1 Yellow1 IndianRed1 IndianRed2 Tan1 Tan4
791 )
792 )
793 # perltidy -xci
795 foreach $color (
796 qw(
797 AntiqueWhite3 Bisque1 Bisque2 Bisque3 Bisque4
798 SlateBlue3 RoyalBlue1 SteelBlue2 DeepSkyBlue3
799 ),
800 qw(
801 LightBlue1 DarkSlateGray1 Aquamarine2 DarkSeaGreen2
802 SeaGreen1 Yellow1 IndianRed1 IndianRed2 Tan1 Tan4
803 )
804 )
805 -sil=n --starting-indentation-level=n
807 By default, perltidy examines the input file and tries to determine
808 the starting indentation level. While it is often zero, it may not
809 be zero for a code snippet being sent from an editing session.
810 To guess the starting indentation level perltidy simply assumes
812 that indentation scheme used to create the code snippet is the same
813 as is being used for the current perltidy process. This is the
814 only sensible guess that can be made. It should be correct if this
815 is true, but otherwise it probably won't. For example, if the
816 input script was written with -i=2 and the current perltidy flags
817 have -i=4, the wrong initial indentation will be guessed for a code
818 snippet which has non-zero initial indentation. Likewise, if an
819 entabbing scheme is used in the input script and not in the current
820 process then the guessed indentation will be wrong.
821 If the default method does not work correctly, or you want to
823 change the starting level, use -sil=n, to force the starting level
824 to be n.
825 List indentation using --line-up-parentheses, -lp or
827 --extended--line-up-parentheses , -xlp
828 These flags provide an alternative indentation method for list
829 data. The original flag for this is -lp, but it has some
830 limitations (explained below) which are avoided with the newer -xlp
831 flag. So -xlp is probably the better choice for new work, but the
832 -lp flag is retained to minimize changes to existing formatting.
833 If you enter both -lp and -xlp, then -xlp will be used.
834 In the default indentation method perltidy indents lists with 4
836 spaces, or whatever value is specified with -i=n. Here is a small
837 list formatted in this way:
838 # perltidy (default)
840 @month_of_year = (
841 'Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun',
842 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'
843 );
844 The -lp or -xlp flags add extra indentation to cause the data to
846 begin past the opening parentheses of a sub call or list, or
847 opening square bracket of an anonymous array, or opening curly
848 brace of an anonymous hash. With this option, the above list would
849 become:
850 # perltidy -lp or -xlp
852 @month_of_year = (
853 'Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun',
854 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'
855 );
856 If the available line length (see -l=n ) does not permit this much
858 space, perltidy will use less. For alternate placement of the
859 closing paren, see the next section.
860 These flags have no effect on code BLOCKS, such as if/then/else
862 blocks, which always use whatever is specified with -i=n.
863 Some limitations on these flags are:
865 • A limitation on -lp, but not -xlp, occurs in situations where
867 perltidy does not have complete freedom to choose line breaks.
868 Then it may temporarily revert to its default indentation
869 method. This can occur for example if there are blank lines,
870 block comments, multi-line quotes, or side comments between the
871 opening and closing parens, braces, or brackets. It will also
872 occur if a multi-line anonymous sub occurs within a container
873 since that will impose specific line breaks (such as line
874 breaks after statements).
875 • For both the -lp and -xlp flags, any parameter which
877 significantly restricts the ability of perltidy to choose
878 newlines will conflict with these flags and will cause them to
879 be deactivated. These include -io, -fnl, -nanl, and -ndnl.
880 • The -lp and -xlp options may not be used together with the -t
882 tabs option. They may, however, be used with the -et=n tab
883 method
884 There are some potential disadvantages of this indentation method
886 compared to the default method that should be noted:
887 • The available line length can quickly be used up if variable
889 names are long. This can cause deeply nested code to quickly
890 reach the line length limit, and become badly formatted, much
891 sooner than would occur with the default indentation method.
892 • Since the indentation depends on the lengths of variable names,
894 small changes in variable names can cause changes in
895 indentation over many lines in a file. This means that minor
896 name changes can produce significant file differences. This
897 can be annoying and does not occur with the default indentation
898 method.
899 Some things that can be done to minimize these problems are:
901 • Increase --maximum-line-length=n above the default n=80
903 characters if necessary.
904 • If you use -xlp then long side comments can limit the
906 indentation over multiple lines. Consider adding the flag
907 --ignore-side-comment-lengths to prevent this, or minimizing
908 the use of side comments.
909 • Apply this style in a limited way. By default, it applies to
911 all list containers (not just lists in parentheses). The next
912 section describes how to limit this style to, for example, just
913 function calls. The default indentation method will be applied
914 elsewhere.
915 -lpil=s, --line-up-parentheses-inclusion-list and -lpxl=s,
917 --line-up-parentheses-exclusion-list
918 The following discussion is written for -lp but applies equally to
919 the newer -xlp version. By default, the -lp flag applies to as
920 many containers as possible. The set of containers to which the
921 -lp style applies can be reduced by either one of these two flags:
922 Use -lpil=s to specify the containers to which -lp applies, or
924 use -lpxl=s to specify the containers to which -lp does NOT apply.
926 Only one of these two flags may be used. Both flags can achieve
928 the same result, but the -lpil=s flag is much easier to describe
929 and use and is recommended. The -lpxl=s flag was the original
930 implementation and is only retained for backwards compatibility.
931 This list s for these parameters is a string with space-separated
933 items. Each item consists of up to three pieces of information in
934 this order: (1) an optional letter code (2) a required container
935 type, and (3) an optional numeric code.
936 The only required piece of information is a container type, which
938 is one of '(', '[', or '{'. For example the string
939 -lpil='('
941 means use -lp formatting only on lists within parentheses, not
943 lists in square-brackets or braces. The same thing could
944 alternatively be specified with
945 -lpxl = '[ {'
947 which says to exclude lists within square-brackets and braces. So
949 what remains is lists within parentheses.
950 A second optional item of information which can be given for
952 parentheses is an alphanumeric letter which is used to limit the
953 selection further depending on the type of token immediately before
954 the paren. The possible letters are currently 'k', 'K', 'f', 'F',
955 'w', and 'W', with these meanings for matching whatever precedes an
956 opening paren:
957 'k' matches if the previous nonblank token is a perl built-in keyword (such as 'if', 'while'),
959 'K' matches if 'k' does not, meaning that the previous token is not a keyword.
960 'f' matches if the previous token is a function other than a keyword.
961 'F' matches if 'f' does not.
962 'w' matches if either 'k' or 'f' match.
963 'W' matches if 'w' does not.
964 For example:
966 -lpil = 'f('
968 means only apply -lp to function calls, and
970 -lpil = 'w('
972 means only apply -lp to parenthesized lists which follow a function
974 or a keyword.
975 This last example could alternatively be written using the -lpxl=s
977 flag as
978 -lpxl = '[ { W('
980 which says exclude -lp for lists within square-brackets, braces,
982 and parens NOT preceded by a keyword or function. Clearly, the
983 -lpil=s method is easier to understand.
984 An optional numeric code may follow any of the container types to
986 further refine the selection based on container contents. The
987 numeric codes are:
988 '0' or blank: no check on contents is made
990 '1' exclude B<-lp> unless the contents is a simple list without sublists
991 '2' exclude B<-lp> unless the contents is a simple list without sublists, without
992 code blocks, and without ternary operators
993 For example,
995 -lpil = 'f(2'
997 means only apply -lp to function call lists which do not contain
999 any sublists, code blocks or ternary expressions.
1000 -cti=n, --closing-token-indentation
1002 The -cti=n flag controls the indentation of a line beginning with a
1003 ")", "]", or a non-block "}". Such a line receives:
1004 -cti = 0 no extra indentation (default)
1006 -cti = 1 extra indentation such that the closing token
1007 aligns with its opening token.
1008 -cti = 2 one extra indentation level if the line looks like:
1009 ); or ]; or };
1010 -cti = 3 one extra indentation level always
1011 The flags -cti=1 and -cti=2 work well with the -lp flag (previous
1013 section).
1014 # perltidy -lp -cti=1
1016 @month_of_year = (
1017 'Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun',
1018 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'
1019 );
1020 # perltidy -lp -cti=2
1022 @month_of_year = (
1023 'Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun',
1024 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'
1025 );
1026 These flags are merely hints to the formatter and they may not
1028 always be followed. In particular, if -lp is not being used, the
1029 indentation for cti=1 is constrained to be no more than one
1030 indentation level.
1031 If desired, this control can be applied independently to each of
1033 the closing container token types. In fact, -cti=n is merely an
1034 abbreviation for -cpi=n -csbi=n -cbi=n, where: -cpi or
1035 --closing-paren-indentation controls )'s, -csbi or
1036 --closing-square-bracket-indentation controls ]'s, -cbi or
1037 --closing-brace-indentation controls non-block }'s.
1038 -icp, --indent-closing-paren
1040 The -icp flag is equivalent to -cti=2, described in the previous
1041 section. The -nicp flag is equivalent -cti=0. They are included
1042 for backwards compatibility.
1043 -icb, --indent-closing-brace
1045 The -icb option gives one extra level of indentation to a brace
1046 which terminates a code block . For example,
1047 if ($task) {
1049 yyy();
1050 } # -icb
1051 else {
1052 zzz();
1053 }
1054 The default is not to do this, indicated by -nicb.
1056 -nib, --non-indenting-braces
1058 Normally, lines of code contained within a pair of block braces
1059 receive one additional level of indentation. This flag, which is
1060 enabled by default, causes perltidy to look for opening block
1061 braces which are followed by a special side comment. This special
1062 side comment is #<<< by default. If found, the code between this
1063 opening brace and its corresponding closing brace will not be given
1064 the normal extra indentation level. For example:
1065 { #<<< a closure to contain lexical vars
1067 my $var; # this line does not get one level of indentation
1069 ...
1070 }
1072 # this line does not 'see' $var;
1074 This can be useful, for example, when combining code from different
1076 files. Different sections of code can be placed within braces to
1077 keep their lexical variables from being visible to the end of the
1078 file. To keep the new braces from causing all of their contained
1079 code to be indented if you run perltidy, and possibly introducing
1080 new line breaks in long lines, you can mark the opening braces with
1081 this special side comment.
1082 Only the opening brace needs to be marked, since perltidy knows
1084 where the closing brace is. Braces contained within marked braces
1085 may also be marked as non-indenting.
1086 If your code happens to have some opening braces followed by
1088 '#<<<', and you don't want this behavior, you can use -nnib to
1089 deactivate it. To make it easy to remember, the default string is
1090 the same as the string for starting a format-skipping section.
1091 There is no confusion because in that case it is for a block
1092 comment rather than a side-comment.
1093 The special side comment can be changed with the next parameter.
1095 -nibp=s, --non-indenting-brace-prefix=s
1097 The -nibp=string parameter may be used to change the marker for
1098 non-indenting braces. The default is equivalent to -nibp='#<<<'.
1099 The string that you enter must begin with a # and should be in
1100 quotes as necessary to get past the command shell of your system.
1101 This string is the leading text of a regex pattern that is
1102 constructed by appending pre-pending a '^' and appending a'\s', so
1103 you must also include backslashes for characters to be taken
1104 literally rather than as patterns.
1105 For example, to match the side comment '#++', the parameter would
1107 be
1108 -nibp='#\+\+'
1110 -olq, --outdent-long-quotes
1112 When -olq is set, lines which is a quoted string longer than the
1113 value maximum-line-length will have their indentation removed to
1114 make them more readable. This is the default. To prevent such
1115 out-denting, use -nolq or --nooutdent-long-lines.
1116 -oll, --outdent-long-lines
1118 This command is equivalent to --outdent-long-quotes and
1119 --outdent-long-comments, and it is included for compatibility with
1120 previous versions of perltidy. The negation of this also works,
1121 -noll or --nooutdent-long-lines, and is equivalent to setting -nolq
1122 and -nolc.
1123 Outdenting Labels: -ola, --outdent-labels
1125 This command will cause labels to be outdented by 2 spaces (or
1126 whatever -ci has been set to), if possible. This is the default.
1127 For example:
1128 my $i;
1130 LOOP: while ( $i = <FOTOS> ) {
1131 chomp($i);
1132 next unless $i;
1133 fixit($i);
1134 }
1135 Use -nola to not outdent labels. To control line breaks after
1137 labels see "bal=n, --break-after-labels=n".
1138 Outdenting Keywords
1140 -okw, --outdent-keywords
1141 The command -okw will cause certain leading control keywords to
1142 be outdented by 2 spaces (or whatever -ci has been set to), if
1143 possible. By default, these keywords are "redo", "next",
1144 "last", "goto", and "return". The intention is to make these
1145 control keywords easier to see. To change this list of
1146 keywords being outdented, see the next section.
1147 For example, using "perltidy -okw" on the previous example
1149 gives:
1150 my $i;
1152 LOOP: while ( $i = <FOTOS> ) {
1153 chomp($i);
1154 next unless $i;
1155 fixit($i);
1156 }
1157 The default is not to do this.
1159 Specifying Outdented Keywords: -okwl=string,
1161 --outdent-keyword-list=string
1162 This command can be used to change the keywords which are
1163 outdented with the -okw command. The parameter string is a
1164 required list of perl keywords, which should be placed in
1165 quotes if there are more than one. By itself, it does not
1166 cause any outdenting to occur, so the -okw command is still
1167 required.
1168 For example, the commands "-okwl="next last redo goto" -okw"
1170 will cause those four keywords to be outdented. It is probably
1171 simplest to place any -okwl command in a .perltidyrc file.
1172 Whitespace Control
1174 Whitespace refers to the blank space between variables, operators, and
1175 other code tokens.
1176 -fws, --freeze-whitespace
1178 This flag causes your original whitespace to remain unchanged, and
1179 causes the rest of the whitespace commands in this section, the
1180 Code Indentation section, and the Comment Control section to be
1181 ignored.
1182 Tightness of curly braces, parentheses, and square brackets
1184 Here the term "tightness" will mean the closeness with which pairs
1185 of enclosing tokens, such as parentheses, contain the quantities
1186 within. A numerical value of 0, 1, or 2 defines the tightness,
1187 with 0 being least tight and 2 being most tight. Spaces within
1188 containers are always symmetric, so if there is a space after a "("
1189 then there will be a space before the corresponding ")".
1190 The -pt=n or --paren-tightness=n parameter controls the space
1192 within parens. The example below shows the effect of the three
1193 possible values, 0, 1, and 2:
1194 if ( ( my $len_tab = length( $tabstr ) ) > 0 ) { # -pt=0
1196 if ( ( my $len_tab = length($tabstr) ) > 0 ) { # -pt=1 (default)
1197 if ((my $len_tab = length($tabstr)) > 0) { # -pt=2
1198 When n is 0, there is always a space to the right of a '(' and to
1200 the left of a ')'. For n=2 there is never a space. For n=1, the
1201 default, there is a space unless the quantity within the parens is
1202 a single token, such as an identifier or quoted string.
1203 Likewise, the parameter -sbt=n or --square-bracket-tightness=n
1205 controls the space within square brackets, as illustrated below.
1206 $width = $col[ $j + $k ] - $col[ $j ]; # -sbt=0
1208 $width = $col[ $j + $k ] - $col[$j]; # -sbt=1 (default)
1209 $width = $col[$j + $k] - $col[$j]; # -sbt=2
1210 Curly braces which do not contain code blocks are controlled by the
1212 parameter -bt=n or --brace-tightness=n.
1213 $obj->{ $parsed_sql->{ 'table' }[0] }; # -bt=0
1215 $obj->{ $parsed_sql->{'table'}[0] }; # -bt=1 (default)
1216 $obj->{$parsed_sql->{'table'}[0]}; # -bt=2
1217 And finally, curly braces which contain blocks of code are
1219 controlled by the parameter -bbt=n or --block-brace-tightness=n as
1220 illustrated in the example below.
1221 %bf = map { $_ => -M $_ } grep { /\.deb$/ } dirents '.'; # -bbt=0 (default)
1223 %bf = map { $_ => -M $_ } grep {/\.deb$/} dirents '.'; # -bbt=1
1224 %bf = map {$_ => -M $_} grep {/\.deb$/} dirents '.'; # -bbt=2
1225 To simplify input in the case that all of the tightness flags have
1227 the same value <n>, the parameter <-act=n> or
1228 --all-containers-tightness=n is an abbreviation for the combination
1229 <-pt=n -sbt=n -bt=n -bbt=n>.
1230 -tso, --tight-secret-operators
1232 The flag -tso causes certain perl token sequences (secret
1233 operators) which might be considered to be a single operator to be
1234 formatted "tightly" (without spaces). The operators currently
1235 modified by this flag are:
1236 0+ +0 ()x!! ~~<> ,=> =( )=
1238 For example the sequence 0 +, which converts a string to a number,
1240 would be formatted without a space: 0+ when the -tso flag is set.
1241 This flag is off by default.
1242 -sts, --space-terminal-semicolon
1244 Some programmers prefer a space before all terminal semicolons.
1245 The default is for no such space, and is indicated with -nsts or
1246 --nospace-terminal-semicolon.
1247 $i = 1 ; # -sts
1249 $i = 1; # -nsts (default)
1250 -sfs, --space-for-semicolon
1252 Semicolons within for loops may sometimes be hard to see,
1253 particularly when commas are also present. This option places
1254 spaces on both sides of these special semicolons, and is the
1255 default. Use -nsfs or --nospace-for-semicolon to deactivate it.
1256 for ( @a = @$ap, $u = shift @a ; @a ; $u = $v ) { # -sfs (default)
1258 for ( @a = @$ap, $u = shift @a; @a; $u = $v ) { # -nsfs
1259 -asc, --add-semicolons
1261 Setting -asc allows perltidy to add any missing optional semicolon
1262 at the end of a line which is followed by a closing curly brace on
1263 the next line. This is the default, and may be deactivated with
1264 -nasc or --noadd-semicolons.
1265 -dsm, --delete-semicolons
1267 Setting -dsm allows perltidy to delete extra semicolons which are
1268 simply empty statements. This is the default, and may be
1269 deactivated with -ndsm or --nodelete-semicolons. (Such semicolons
1270 are not deleted, however, if they would promote a side comment to a
1271 block comment).
1272 -aws, --add-whitespace
1274 Setting this option allows perltidy to add certain whitespace to
1275 improve code readability. This is the default. If you do not want
1276 any whitespace added, but are willing to have some whitespace
1277 deleted, use -naws. (Use -fws to leave whitespace completely
1278 unchanged).
1279 -dws, --delete-old-whitespace
1281 Setting this option allows perltidy to remove some old whitespace
1282 between characters, if necessary. This is the default. If you do
1283 not want any old whitespace removed, use -ndws or
1284 --nodelete-old-whitespace.
1285 Detailed whitespace controls around tokens
1287 For those who want more detailed control over the whitespace around
1288 tokens, there are four parameters which can directly modify the
1289 default whitespace rules built into perltidy for any token. They
1290 are:
1291 -wls=s or --want-left-space=s,
1293 -nwls=s or --nowant-left-space=s,
1295 -wrs=s or --want-right-space=s,
1297 -nwrs=s or --nowant-right-space=s.
1299 These parameters are each followed by a quoted string, s,
1301 containing a list of token types. No more than one of each of
1302 these parameters should be specified, because repeating a command-
1303 line parameter always overwrites the previous one before perltidy
1304 ever sees it.
1305 To illustrate how these are used, suppose it is desired that there
1307 be no space on either side of the token types = + - / *. The
1308 following two parameters would specify this desire:
1309 -nwls="= + - / *" -nwrs="= + - / *"
1311 (Note that the token types are in quotes, and that they are
1313 separated by spaces). With these modified whitespace rules, the
1314 following line of math:
1315 $root = -$b + sqrt( $b * $b - 4. * $a * $c ) / ( 2. * $a );
1317 becomes this:
1319 $root=-$b+sqrt( $b*$b-4.*$a*$c )/( 2.*$a );
1321 These parameters should be considered to be hints to perltidy
1323 rather than fixed rules, because perltidy must try to resolve
1324 conflicts that arise between them and all of the other rules that
1325 it uses. One conflict that can arise is if, between two tokens,
1326 the left token wants a space and the right one doesn't. In this
1327 case, the token not wanting a space takes priority.
1328 It is necessary to have a list of all token types in order to
1330 create this type of input. Such a list can be obtained by the
1331 command --dump-token-types. Also try the -D flag on a short
1332 snippet of code and look at the .DEBUG file to see the
1333 tokenization.
1334 WARNING Be sure to put these tokens in quotes to avoid having them
1336 misinterpreted by your command shell.
1337 Note1: Perltidy does always follow whitespace controls
1339 The various parameters controlling whitespace within a program are
1340 requests which perltidy follows as well as possible, but there are
1341 a number of situations where changing whitespace could change
1342 program behavior and is not done. Some of these are obvious; for
1343 example, we should not remove the space between the two plus
1344 symbols in '$x+ +$y' to avoid creating a '++' operator. Some are
1345 more subtle and involve the whitespace around bareword symbols and
1346 locations of possible filehandles. For example, consider the
1347 problem of formatting the following subroutine:
1348 sub print_div {
1350 my ($x,$y)=@_;
1351 print $x/$y;
1352 }
1353 Suppose the user requests that / signs have a space to the left but
1355 not to the right. Perltidy will refuse to do this, but if this were
1356 done the result would be
1357 sub print_div {
1359 my ($x,$y)=@_;
1360 print $x /$y;
1361 }
1362 If formatted in this way, the program will not run (at least with
1364 recent versions of perl) because the $x is taken to be a filehandle
1365 and / is assumed to start a quote. In a complex program, there
1366 might happen to be a / which terminates the multiline quote without
1367 a syntax error, allowing the program to run, but not as intended.
1368 Related issues arise with other binary operator symbols, such as +
1370 and -, and in older versions of perl there could be problems with
1371 ternary operators. So to avoid changing program behavior, perltidy
1372 has the simple rule that whitespace around possible filehandles is
1373 left unchanged. Likewise, whitespace around barewords is left
1374 unchanged. The reason is that if the barewords are defined in
1375 other modules, or in code that has not even been written yet,
1376 perltidy will not have seen their prototypes and must treat them
1377 cautiously.
1378 In perltidy this is implemented in the tokenizer by marking token
1380 following a print keyword as a special type Z. When formatting is
1381 being done, whitespace following this token type is generally left
1382 unchanged as a precaution against changing program behavior. This
1383 is excessively conservative but simple and easy to implement.
1384 Keywords which are treated similarly to print include printf, sort,
1385 exec, system. Changes in spacing around parameters following these
1386 keywords may have to be made manually. For example, the space, or
1387 lack of space, after the parameter $foo in the following line will
1388 be unchanged in formatting.
1389 system($foo );
1391 system($foo);
1392 To find if a token is of type Z you can use perltidy -DEBUG. For
1394 the first line above the result is
1395 1: system($foo );
1397 1: kkkkkk{ZZZZb};
1398 which shows that system is type k (keyword) and $foo is type Z.
1400 Note2: Perltidy's whitespace rules are not perfect
1402 Despite these precautions, it is still possible to introduce syntax
1403 errors with some asymmetric whitespace rules, particularly when
1404 call parameters are not placed in containing parens or braces. For
1405 example, the following two lines will be parsed by perl without a
1406 syntax error:
1407 # original programming, syntax ok
1409 my @newkeys = map $_-$nrecs+@data, @oldkeys;
1410 # perltidy default, syntax ok
1412 my @newkeys = map $_ - $nrecs + @data, @oldkeys;
1413 But the following will give a syntax error:
1415 # perltidy -nwrs='-'
1417 my @newkeys = map $_ -$nrecs + @data, @oldkeys;
1418 For another example, the following two lines will be parsed without
1420 syntax error:
1421 # original programming, syntax ok
1423 for my $severity ( reverse $SEVERITY_LOWEST+1 .. $SEVERITY_HIGHEST ) { ... }
1424 # perltidy default, syntax ok
1426 for my $severity ( reverse $SEVERITY_LOWEST + 1 .. $SEVERITY_HIGHEST ) { ... }
1427 But the following will give a syntax error:
1429 # perltidy -nwrs='+', syntax error:
1431 for my $severity ( reverse $SEVERITY_LOWEST +1 .. $SEVERITY_HIGHEST ) { ... }
1432 To avoid subtle parsing problems like this, it is best to avoid
1434 spacing a binary operator asymmetrically with a space on the left
1435 but not on the right.
1436 Space between specific keywords and opening paren
1438 When an opening paren follows a Perl keyword, no space is
1439 introduced after the keyword, unless it is (by default) one of
1440 these:
1441 my local our and or xor eq ne if else elsif until unless
1443 while for foreach return switch case given when
1444 These defaults can be modified with two commands:
1446 -sak=s or --space-after-keyword=s adds keywords.
1448 -nsak=s or --nospace-after-keyword=s removes keywords.
1450 where s is a list of keywords (in quotes if necessary). For
1452 example,
1453 my ( $a, $b, $c ) = @_; # default
1455 my( $a, $b, $c ) = @_; # -nsak="my local our"
1456 The abbreviation -nsak='*' is equivalent to including all of the
1458 keywords in the above list.
1459 When both -nsak=s and -sak=s commands are included, the -nsak=s
1461 command is executed first. For example, to have space after only
1462 the keywords (my, local, our) you could use -nsak="*" -sak="my
1463 local our".
1464 To put a space after all keywords, see the next item.
1466 Space between all keywords and opening parens
1468 When an opening paren follows a function or keyword, no space is
1469 introduced after the keyword except for the keywords noted in the
1470 previous item. To always put a space between a function or keyword
1471 and its opening paren, use the command:
1472 -skp or --space-keyword-paren
1474 You may also want to use the flag -sfp (next item) too.
1476 Space between all function names and opening parens
1478 When an opening paren follows a function the default and
1479 recommended formatting is not to introduce a space. To cause a
1480 space to be introduced use:
1481 -sfp or --space-function-paren
1483 myfunc( $a, $b, $c ); # default
1485 myfunc ( $a, $b, $c ); # -sfp
1486 You will probably also want to use the flag -skp (previous item)
1488 too.
1489 The reason this is not recommended is that spacing a function paren
1491 can make a program vulnerable to parsing problems by Perl. For
1492 example, the following two-line program will run as written but
1493 will have a syntax error if reformatted with -sfp:
1494 if ( -e filename() ) { print "I'm here\n"; }
1496 sub filename { return $0 }
1497 In this particular case the syntax error can be removed if the line
1499 order is reversed, so that Perl parses 'sub filename' first.
1500 -fpva or --function-paren-vertical-alignment
1502 A side-effect of using the -sfp flag is that the parens may become
1503 vertically aligned. For example,
1504 # perltidy -sfp
1506 myfun ( $aaa, $b, $cc );
1507 mylongfun ( $a, $b, $c );
1508 This is the default behavior. To prevent this alignment use
1510 -nfpva:
1511 # perltidy -sfp -nfpva
1513 myfun ( $aaa, $b, $cc );
1514 mylongfun ( $a, $b, $c );
1515 -spp=n or --space-prototype-paren=n
1517 This flag can be used to control whether a function prototype is
1518 preceded by a space. For example, the following prototype does not
1519 have a space.
1520 sub usage();
1522 This integer n may have the value 0, 1, or 2 as follows:
1524 -spp=0 means no space before the paren
1526 -spp=1 means follow the example of the source code [DEFAULT]
1527 -spp=2 means always put a space before the paren
1528 The default is -spp=1, meaning that a space will be used if and
1530 only if there is one in the source code. Given the above line of
1531 code, the result of applying the different options would be:
1532 sub usage(); # n=0 [no space]
1534 sub usage(); # n=1 [default; follows input]
1535 sub usage (); # n=2 [space]
1536 -kpit=n or --keyword-paren-inner-tightness=n
1538 The space inside of an opening paren, which itself follows a
1539 certain keyword, can be controlled by this parameter. The space on
1540 the inside of the corresponding closing paren will be treated in
1541 the same (balanced) manner. This parameter has precedence over any
1542 other paren spacing rules. The values of n are as follows:
1543 -kpit=0 means always put a space (not tight)
1545 -kpit=1 means ignore this parameter [default]
1546 -kpit=2 means never put a space (tight)
1547 To illustrate, the following snippet is shown formatted in three
1549 ways:
1550 if ( seek( DATA, 0, 0 ) ) { ... } # perltidy (default)
1552 if (seek(DATA, 0, 0)) { ... } # perltidy -pt=2
1553 if ( seek(DATA, 0, 0) ) { ... } # perltidy -pt=2 -kpit=0
1554 In the second case the -pt=2 parameter makes all of the parens
1556 tight. In the third case the -kpit=0 flag causes the space within
1557 the 'if' parens to have a space, since 'if' is one of the keywords
1558 to which the -kpit flag applies by default. The remaining parens
1559 are still tight because of the -pt=2 parameter.
1560 The set of keywords to which this parameter applies are by default
1562 are:
1563 if elsif unless while until for foreach
1565 These can be changed with the parameter -kpitl=s described in the
1567 next section.
1568 -kpitl=string or --keyword-paren-inner-tightness=string
1570 This command can be used to change the keywords to which the the
1571 -kpit=n command applies. The parameter string is a required list
1572 either keywords or functions, which should be placed in quotes if
1573 there are more than one. By itself, this parameter does not cause
1574 any change in spacing, so the -kpit=n command is still required.
1575 For example, the commands "-kpitl="if else while" -kpit=2" will
1577 cause the just the spaces inside parens following 'if', 'else',
1578 and 'while' keywords to follow the tightness value indicated by the
1579 -kpit=2 flag.
1580 -lop or --logical-padding
1582 In the following example some extra space has been inserted on the
1583 second line between the two open parens. This extra space is called
1584 "logical padding" and is intended to help align similar things
1585 vertically in some logical or ternary expressions.
1586 # perltidy [default formatting]
1588 $same =
1589 ( ( $aP eq $bP )
1590 && ( $aS eq $bS )
1591 && ( $aT eq $bT )
1592 && ( $a->{'title'} eq $b->{'title'} )
1593 && ( $a->{'href'} eq $b->{'href'} ) );
1594 Note that this is considered to be a different operation from
1596 "vertical alignment" because space at just one line is being
1597 adjusted, whereas in "vertical alignment" the spaces at all lines
1598 are being adjusted. So it sort of a local version of vertical
1599 alignment.
1600 Here is an example involving a ternary operator:
1602 # perltidy [default formatting]
1604 $bits =
1605 $top > 0xffff ? 32
1606 : $top > 0xff ? 16
1607 : $top > 1 ? 8
1608 : 1;
1609 This behavior is controlled with the flag --logical-padding, which
1611 is set 'on' by default. If it is not desired it can be turned off
1612 using --nological-padding or -nlop. The above two examples become,
1613 with -nlop:
1614 # perltidy -nlop
1616 $same =
1617 ( ( $aP eq $bP )
1618 && ( $aS eq $bS )
1619 && ( $aT eq $bT )
1620 && ( $a->{'title'} eq $b->{'title'} )
1621 && ( $a->{'href'} eq $b->{'href'} ) );
1622 # perltidy -nlop
1624 $bits =
1625 $top > 0xffff ? 32
1626 : $top > 0xff ? 16
1627 : $top > 1 ? 8
1628 : 1;
1629 Trimming whitespace around "qw" quotes
1631 -tqw or --trim-qw provide the default behavior of trimming spaces
1632 around multi-line "qw" quotes and indenting them appropriately.
1633 -ntqw or --notrim-qw cause leading and trailing whitespace around
1635 multi-line "qw" quotes to be left unchanged. This option will not
1636 normally be necessary, but was added for testing purposes, because
1637 in some versions of perl, trimming "qw" quotes changes the syntax
1638 tree.
1639 -sbq=n or --space-backslash-quote=n
1641 lines like
1642 $str1=\"string1";
1644 $str2=\'string2';
1645 can confuse syntax highlighters unless a space is included between
1647 the backslash and the single or double quotation mark.
1648 this can be controlled with the value of n as follows:
1650 -sbq=0 means no space between the backslash and quote
1652 -sbq=1 means follow the example of the source code
1653 -sbq=2 means always put a space between the backslash and quote
1654 The default is -sbq=1, meaning that a space will be used if there
1656 is one in the source code.
1657 Trimming trailing whitespace from lines of POD
1659 -trp or --trim-pod will remove trailing whitespace from lines of
1660 POD. The default is not to do this.
1661 Comment Controls
1663 Perltidy has a number of ways to control the appearance of both block
1664 comments and side comments. The term block comment here refers to a
1665 full-line comment, whereas side comment will refer to a comment which
1666 appears on a line to the right of some code.
1667 -ibc, --indent-block-comments
1669 Block comments normally look best when they are indented to the
1670 same level as the code which follows them. This is the default
1671 behavior, but you may use -nibc to keep block comments left-
1672 justified. Here is an example:
1673 # this comment is indented (-ibc, default)
1675 if ($task) { yyy(); }
1676 The alternative is -nibc:
1678 # this comment is not indented (-nibc)
1680 if ($task) { yyy(); }
1681 See also the next item, -isbc, as well as -sbc, for other ways to
1683 have some indented and some outdented block comments.
1684 -isbc, --indent-spaced-block-comments
1686 If there is no leading space on the line, then the comment will not
1687 be indented, and otherwise it may be.
1688 If both -ibc and -isbc are set, then -isbc takes priority.
1690 -olc, --outdent-long-comments
1692 When -olc is set, lines which are full-line (block) comments longer
1693 than the value maximum-line-length will have their indentation
1694 removed. This is the default; use -nolc to prevent outdenting.
1695 -msc=n, --minimum-space-to-comment=n
1697 Side comments look best when lined up several spaces to the right
1698 of code. Perltidy will try to keep comments at least n spaces to
1699 the right. The default is n=4 spaces.
1700 -fpsc=n, --fixed-position-side-comment=n
1702 This parameter tells perltidy to line up side comments in column
1703 number n whenever possible. The default, n=0, will not do this.
1704 -iscl, --ignore-side-comment-lengths
1706 This parameter causes perltidy to ignore the length of side
1707 comments when setting line breaks. The default, -niscl, is to
1708 include the length of side comments when breaking lines to stay
1709 within the length prescribed by the -l=n maximum line length
1710 parameter. For example, the following long single line would
1711 remain intact with -l=80 and -iscl:
1712 perltidy -l=80 -iscl
1714 $vmsfile =~ s/;[\d\-]*$//; # Clip off version number; we can use a newer version as well
1715 whereas without the -iscl flag the line will be broken:
1717 perltidy -l=80
1719 $vmsfile =~ s/;[\d\-]*$//
1720 ; # Clip off version number; we can use a newer version as well
1721 -hsc, --hanging-side-comments
1723 By default, perltidy tries to identify and align "hanging side
1724 comments", which are something like this:
1725 my $IGNORE = 0; # This is a side comment
1727 # This is a hanging side comment
1728 # And so is this
1729 A comment is considered to be a hanging side comment if (1) it
1731 immediately follows a line with a side comment, or another hanging
1732 side comment, and (2) there is some leading whitespace on the line.
1733 To deactivate this feature, use -nhsc or --nohanging-side-comments.
1734 If block comments are preceded by a blank line, or have no leading
1735 whitespace, they will not be mistaken as hanging side comments.
1736 Closing Side Comments
1738 A closing side comment is a special comment which perltidy can
1739 automatically create and place after the closing brace of a code
1740 block. They can be useful for code maintenance and debugging. The
1741 command -csc (or --closing-side-comments) adds or updates closing
1742 side comments. For example, here is a small code snippet
1743 sub message {
1745 if ( !defined( $_[0] ) ) {
1746 print("Hello, World\n");
1747 }
1748 else {
1749 print( $_[0], "\n" );
1750 }
1751 }
1752 And here is the result of processing with "perltidy -csc":
1754 sub message {
1756 if ( !defined( $_[0] ) ) {
1757 print("Hello, World\n");
1758 }
1759 else {
1760 print( $_[0], "\n" );
1761 }
1762 } ## end sub message
1763 A closing side comment was added for "sub message" in this case,
1765 but not for the "if" and "else" blocks, because they were below the
1766 6 line cutoff limit for adding closing side comments. This limit
1767 may be changed with the -csci command, described below.
1768 The command -dcsc (or --delete-closing-side-comments) reverses this
1770 process and removes these comments.
1771 Several commands are available to modify the behavior of these two
1773 basic commands, -csc and -dcsc:
1774 -csci=n, or --closing-side-comment-interval=n
1776 where "n" is the minimum number of lines that a block must have
1777 in order for a closing side comment to be added. The default
1778 value is "n=6". To illustrate:
1779 # perltidy -csci=2 -csc
1781 sub message {
1782 if ( !defined( $_[0] ) ) {
1783 print("Hello, World\n");
1784 } ## end if ( !defined( $_[0] ))
1785 else {
1786 print( $_[0], "\n" );
1787 } ## end else [ if ( !defined( $_[0] ))
1788 } ## end sub message
1789 Now the "if" and "else" blocks are commented. However, now
1791 this has become very cluttered.
1792 -cscp=string, or --closing-side-comment-prefix=string
1794 where string is the prefix used before the name of the block
1795 type. The default prefix, shown above, is "## end". This
1796 string will be added to closing side comments, and it will also
1797 be used to recognize them in order to update, delete, and
1798 format them. Any comment identified as a closing side comment
1799 will be placed just a single space to the right of its closing
1800 brace.
1801 -cscl=string, or --closing-side-comment-list
1803 where "string" is a list of block types to be tagged with
1804 closing side comments. By default, all code block types
1805 preceded by a keyword or label (such as "if", "sub", and so on)
1806 will be tagged. The -cscl command changes the default list to
1807 be any selected block types; see "Specifying Block Types". For
1808 example, the following command requests that only "sub"'s,
1809 labels, "BEGIN", and "END" blocks be affected by any -csc or
1810 -dcsc operation:
1811 -cscl="sub : BEGIN END"
1813 -csct=n, or --closing-side-comment-maximum-text=n
1815 The text appended to certain block types, such as an "if"
1816 block, is whatever lies between the keyword introducing the
1817 block, such as "if", and the opening brace. Since this might
1818 be too much text for a side comment, there needs to be a limit,
1819 and that is the purpose of this parameter. The default value
1820 is "n=20", meaning that no additional tokens will be appended
1821 to this text after its length reaches 20 characters. Omitted
1822 text is indicated with "...". (Tokens, including sub names,
1823 are never truncated, however, so actual lengths may exceed
1824 this). To illustrate, in the above example, the appended text
1825 of the first block is " ( !defined( $_[0] )...". The existing
1826 limit of "n=20" caused this text to be truncated, as indicated
1827 by the "...". See the next flag for additional control of the
1828 abbreviated text.
1829 -cscb, or --closing-side-comments-balanced
1831 As discussed in the previous item, when the closing-side-
1832 comment-maximum-text limit is exceeded the comment text must be
1833 truncated. Older versions of perltidy terminated with three
1834 dots, and this can still be achieved with -ncscb:
1835 perltidy -csc -ncscb
1837 } ## end foreach my $foo (sort { $b cmp $a ...
1838 However this causes a problem with editors which cannot
1840 recognize comments or are not configured to do so because they
1841 cannot "bounce" around in the text correctly. The -cscb flag
1842 has been added to help them by appending appropriate balancing
1843 structure:
1844 perltidy -csc -cscb
1846 } ## end foreach my $foo (sort { $b cmp $a ... })
1847 The default is -cscb.
1849 -csce=n, or --closing-side-comment-else-flag=n
1851 The default, n=0, places the text of the opening "if" statement
1852 after any terminal "else".
1853 If n=2 is used, then each "elsif" is also given the text of the
1855 opening "if" statement. Also, an "else" will include the text
1856 of a preceding "elsif" statement. Note that this may result
1857 some long closing side comments.
1858 If n=1 is used, the results will be the same as n=2 whenever
1860 the resulting line length is less than the maximum allowed.
1861 -cscb, or --closing-side-comments-balanced
1863 When using closing-side-comments, and the closing-side-comment-
1864 maximum-text limit is exceeded, then the comment text must be
1865 abbreviated. It is terminated with three dots if the -cscb
1866 flag is negated:
1867 perltidy -csc -ncscb
1869 } ## end foreach my $foo (sort { $b cmp $a ...
1870 This causes a problem with older editors which do not recognize
1872 comments because they cannot "bounce" around in the text
1873 correctly. The -cscb flag tries to help them by appending
1874 appropriate terminal balancing structures:
1875 perltidy -csc -cscb
1877 } ## end foreach my $foo (sort { $b cmp $a ... })
1878 The default is -cscb.
1880 -cscw, or --closing-side-comment-warnings
1882 This parameter is intended to help make the initial transition
1883 to the use of closing side comments. It causes two things to
1884 happen if a closing side comment replaces an existing,
1885 different closing side comment: first, an error message will
1886 be issued, and second, the original side comment will be placed
1887 alone on a new specially marked comment line for later
1888 attention.
1889 The intent is to avoid clobbering existing hand-written side
1891 comments which happen to match the pattern of closing side
1892 comments. This flag should only be needed on the first run with
1893 -csc.
1894 Important Notes on Closing Side Comments:
1896 • Closing side comments are only placed on lines terminated with
1898 a closing brace. Certain closing styles, such as the use of
1899 cuddled elses (-ce), preclude the generation of some closing
1900 side comments.
1901 • Please note that adding or deleting of closing side comments
1903 takes place only through the commands -csc or -dcsc. The other
1904 commands, if used, merely modify the behavior of these two
1905 commands.
1906 • It is recommended that the -cscw flag be used along with -csc
1908 on the first use of perltidy on a given file. This will
1909 prevent loss of any existing side comment data which happens to
1910 have the csc prefix.
1911 • Once you use -csc, you should continue to use it so that any
1913 closing side comments remain correct as code changes.
1914 Otherwise, these comments will become incorrect as the code is
1915 updated.
1916 • If you edit the closing side comments generated by perltidy,
1918 you must also change the prefix to be different from the
1919 closing side comment prefix. Otherwise, your edits will be
1920 lost when you rerun perltidy with -csc. For example, you
1921 could simply change "## end" to be "## End", since the test is
1922 case sensitive. You may also want to use the -ssc flag to keep
1923 these modified closing side comments spaced the same as actual
1924 closing side comments.
1925 • Temporarily generating closing side comments is a useful
1927 technique for exploring and/or debugging a perl script,
1928 especially one written by someone else. You can always remove
1929 them with -dcsc.
1930 Static Block Comments
1932 Static block comments are block comments with a special leading
1933 pattern, "##" by default, which will be treated slightly
1934 differently from other block comments. They effectively behave as
1935 if they had glue along their left and top edges, because they stick
1936 to the left edge and previous line when there is no blank spaces in
1937 those places. This option is particularly useful for controlling
1938 how commented code is displayed.
1939 -sbc, --static-block-comments
1941 When -sbc is used, a block comment with a special leading
1942 pattern, "##" by default, will be treated specially.
1943 Comments so identified are treated as follows:
1945 • If there is no leading space on the line, then the comment
1947 will not be indented, and otherwise it may be,
1948 • no new blank line will be inserted before such a comment,
1950 and
1951 • such a comment will never become a hanging side comment.
1953 For example, assuming @month_of_year is left-adjusted:
1955 @month_of_year = ( # -sbc (default)
1957 'Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct',
1958 ## 'Dec', 'Nov'
1959 'Nov', 'Dec');
1960 Without this convention, the above code would become
1962 @month_of_year = ( # -nsbc
1964 'Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct',
1965 ## 'Dec', 'Nov'
1967 'Nov', 'Dec'
1968 );
1969 which is not as clear. The default is to use -sbc. This may
1971 be deactivated with -nsbc.
1972 -sbcp=string, --static-block-comment-prefix=string
1974 This parameter defines the prefix used to identify static block
1975 comments when the -sbc parameter is set. The default prefix is
1976 "##", corresponding to "-sbcp=##". The prefix is actually part
1977 of a perl pattern used to match lines and it must either begin
1978 with "#" or "^#". In the first case a prefix ^\s* will be
1979 added to match any leading whitespace, while in the second case
1980 the pattern will match only comments with no leading
1981 whitespace. For example, to identify all comments as static
1982 block comments, one would use "-sbcp=#". To identify all left-
1983 adjusted comments as static block comments, use "-sbcp='^#'".
1984 Please note that -sbcp merely defines the pattern used to
1986 identify static block comments; it will not be used unless the
1987 switch -sbc is set. Also, please be aware that since this
1988 string is used in a perl regular expression which identifies
1989 these comments, it must enable a valid regular expression to be
1990 formed.
1991 A pattern which can be useful is:
1993 -sbcp=^#{2,}[^\s#]
1995 This pattern requires a static block comment to have at least
1997 one character which is neither a # nor a space. It allows a
1998 line containing only '#' characters to be rejected as a static
1999 block comment. Such lines are often used at the start and end
2000 of header information in subroutines and should not be
2001 separated from the intervening comments, which typically begin
2002 with just a single '#'.
2003 -osbc, --outdent-static-block-comments
2005 The command -osbc will cause static block comments to be
2006 outdented by 2 spaces (or whatever -ci=n has been set to), if
2007 possible.
2008 Static Side Comments
2010 Static side comments are side comments with a special leading
2011 pattern. This option can be useful for controlling how commented
2012 code is displayed when it is a side comment.
2013 -ssc, --static-side-comments
2015 When -ssc is used, a side comment with a static leading
2016 pattern, which is "##" by default, will be spaced only a single
2017 space from previous character, and it will not be vertically
2018 aligned with other side comments.
2019 The default is -nssc.
2021 -sscp=string, --static-side-comment-prefix=string
2023 This parameter defines the prefix used to identify static side
2024 comments when the -ssc parameter is set. The default prefix is
2025 "##", corresponding to "-sscp=##".
2026 Please note that -sscp merely defines the pattern used to
2028 identify static side comments; it will not be used unless the
2029 switch -ssc is set. Also, note that this string is used in a
2030 perl regular expression which identifies these comments, so it
2031 must enable a valid regular expression to be formed.
2032 Skipping Selected Sections of Code
2034 Selected lines of code may be passed verbatim to the output without any
2035 formatting by marking the starting and ending lines with special
2036 comments. There are two options for doing this. The first option is
2037 called --format-skipping or -fs, and the second option is called
2038 --code-skipping or -cs.
2039 In both cases the lines of code will be output without any changes.
2041 The difference is that in --format-skipping perltidy will still parse
2042 the marked lines of code and check for errors, whereas in
2043 --code-skipping perltidy will simply pass the lines to the output
2044 without any checking.
2045 Both of these features are enabled by default and are invoked with
2047 special comment markers. --format-skipping uses starting and ending
2048 markers '#<<<' and '#>>>', like this:
2049 #<<< format skipping: do not let perltidy change my nice formatting
2051 my @list = (1,
2052 1, 1,
2053 1, 2, 1,
2054 1, 3, 3, 1,
2055 1, 4, 6, 4, 1,);
2056 #>>>
2057 --code-skipping uses starting and ending markers '#<<V' and '#>>V',
2059 like this:
2060 #<<V code skipping: perltidy will pass this verbatim without error checking
2062 token ident_digit {
2064 [ [ <?word> | _ | <?digit> ] <?ident_digit>
2065 | <''>
2066 ]
2067 };
2068 #>>V
2070 Additional text may appear on the special comment lines provided that
2072 it is separated from the marker by at least one space, as in the above
2073 examples.
2074 Any number of code-skipping or format-skipping sections may appear in a
2076 file. If an opening code-skipping or format-skipping comment is not
2077 followed by a corresponding closing comment, then skipping continues to
2078 the end of the file. If a closing code-skipping or format-skipping
2079 comment appears in a file but does not follow a corresponding opening
2080 comment, then it is treated as an ordinary comment without any special
2081 meaning.
2082 It is recommended to use --code-skipping only if you need to hide a
2084 block of an extended syntax which would produce errors if parsed by
2085 perltidy, and use --format-skipping otherwise. This is because the
2086 --format-skipping option provides the benefits of error checking, and
2087 there are essentially no limitations on which lines to which it can be
2088 applied. The --code-skipping option, on the other hand, does not do
2089 error checking and its use is more restrictive because the code which
2090 remains, after skipping the marked lines, must be syntactically correct
2091 code with balanced containers.
2092 These features should be used sparingly to avoid littering code with
2094 markers, but they can be helpful for working around occasional
2095 problems.
2096 Note that it may be possible to avoid the use of --format-skipping for
2098 the specific case of a comma-separated list of values, as in the above
2099 example, by simply inserting a blank or comment somewhere between the
2100 opening and closing parens. See the section "Controlling List
2101 Formatting".
2102 The following sections describe the available controls for these
2104 options. They should not normally be needed.
2105 -fs, --format-skipping
2107 As explained above, this flag, which is enabled by default, causes
2108 any code between special beginning and ending comment markers to be
2109 passed to the output without formatting. The code between the
2110 comments is still checked for errors however. The default
2111 beginning marker is #<<< and the default ending marker is #>>>.
2112 Format skipping begins when a format skipping beginning comment is
2114 seen and continues until a format-skipping ending comment is found.
2115 This feature can be disabled with -nfs. This should not normally
2117 be necessary.
2118 -fsb=string, --format-skipping-begin=string
2120 This and the next parameter allow the special beginning and ending
2121 comments to be changed. However, it is recommended that they only
2122 be changed if there is a conflict between the default values and
2123 some other use. If they are used, it is recommended that they only
2124 be entered in a .perltidyrc file, rather than on a command line.
2125 This is because properly escaping these parameters on a command
2126 line can be difficult.
2127 If changed comment markers do not appear to be working, use the
2129 -log flag and examine the .LOG file to see if and where they are
2130 being detected.
2131 The -fsb=string parameter may be used to change the beginning
2133 marker for format skipping. The default is equivalent to
2134 -fsb='#<<<'. The string that you enter must begin with a # and
2135 should be in quotes as necessary to get past the command shell of
2136 your system. It is actually the leading text of a pattern that is
2137 constructed by appending a '\s', so you must also include
2138 backslashes for characters to be taken literally rather than as
2139 patterns.
2140 Some examples show how example strings become patterns:
2142 -fsb='#\{\{\{' becomes /^#\{\{\{\s/ which matches #{{{ but not #{{{{
2144 -fsb='#\*\*' becomes /^#\*\*\s/ which matches #** but not #***
2145 -fsb='#\*{2,}' becomes /^#\*{2,}\s/ which matches #** and #*****
2146 -fse=string, --format-skipping-end=string
2148 The -fse=string is the corresponding parameter used to change the
2149 ending marker for format skipping. The default is equivalent to
2150 -fse='#<<<'.
2151 The beginning and ending strings may be the same, but it is
2153 preferable to make them different for clarity.
2154 -cs, --code-skipping
2156 As explained above, this flag, which is enabled by default, causes
2157 any code between special beginning and ending comment markers to be
2158 directly passed to the output without any error checking or
2159 formatting. Essentially, perltidy treats it as if it were a block
2160 of arbitrary text. The default beginning marker is #<<V and the
2161 default ending marker is #>>V.
2162 This feature can be disabled with -ncs. This should not normally
2164 be necessary.
2165 -csb=string, --code-skipping-begin=string
2167 This may be used to change the beginning comment for a
2168 --code-skipping section, and its use is similar to the -fsb=string.
2169 The default is equivalent to -csb='#<<V'.
2170 -cse=string, --code-skipping-end=string
2172 This may be used to change the ending comment for a --code-skipping
2173 section, and its use is similar to the -fse=string. The default is
2174 equivalent to -cse='#>>V'.
2175 Line Break Control
2177 The parameters in this section control breaks after non-blank lines of
2178 code. Blank lines are controlled separately by parameters in the
2179 section "Blank Line Control".
2180 -fnl, --freeze-newlines
2182 If you do not want any changes to the line breaks within lines of
2183 code in your script, set -fnl, and they will remain fixed, and the
2184 rest of the commands in this section and sections "Controlling List
2185 Formatting", "Retaining or Ignoring Existing Line Breaks". You may
2186 want to use -noll with this.
2187 Note: If you also want to keep your blank lines exactly as they
2189 are, you can use the -fbl flag which is described in the section
2190 "Blank Line Control".
2191 -ce, --cuddled-else
2193 Enable the "cuddled else" style, in which "else" and "elsif" are
2194 follow immediately after the curly brace closing the previous
2195 block. The default is not to use cuddled elses, and is indicated
2196 with the flag -nce or --nocuddled-else. Here is a comparison of
2197 the alternatives:
2198 # -ce
2200 if ($task) {
2201 yyy();
2202 } else {
2203 zzz();
2204 }
2205 # -nce (default)
2207 if ($task) {
2208 yyy();
2209 }
2210 else {
2211 zzz();
2212 }
2213 In this example the keyword else is placed on the same line which
2215 begins with the preceding closing block brace and is followed by
2216 its own opening block brace on the same line. Other keywords and
2217 function names which are formatted with this "cuddled" style are
2218 elsif, continue, catch, finally.
2219 Other block types can be formatted by specifying their names on a
2221 separate parameter -cbl, described in a later section.
2222 Cuddling between a pair of code blocks requires that the closing
2224 brace of the first block start a new line. If this block is
2225 entirely on one line in the input file, it is necessary to decide
2226 if it should be broken to allow cuddling. This decision is
2227 controlled by the flag -cbo=n discussed below. The default and
2228 recommended value of -cbo=1 bases this decision on the first block
2229 in the chain. If it spans multiple lines then cuddling is made and
2230 continues along the chain, regardless of the sizes of subsequent
2231 blocks. Otherwise, short lines remain intact.
2232 So for example, the -ce flag would not have any effect if the above
2234 snippet is rewritten as
2235 if ($task) { yyy() }
2237 else { zzz() }
2238 If the first block spans multiple lines, then cuddling can be done
2240 and will continue for the subsequent blocks in the chain, as
2241 illustrated in the previous snippet.
2242 If there are blank lines between cuddled blocks they will be
2244 eliminated. If there are comments after the closing brace where
2245 cuddling would occur then cuddling will be prevented. If this
2246 occurs, cuddling will restart later in the chain if possible.
2247 -cb, --cuddled-blocks
2249 This flag is equivalent to -ce.
2250 -cbl, --cuddled-block-list
2252 The built-in default cuddled block types are else, elsif, continue,
2253 catch, finally.
2254 Additional block types to which the -cuddled-blocks style applies
2256 can be defined by this parameter. This parameter is a character
2257 string, giving a list of block types separated by commas or spaces.
2258 For example, to cuddle code blocks of type sort, map and grep, in
2259 addition to the default types, the string could be set to
2260 -cbl="sort map grep"
2262 or equivalently
2264 -cbl=sort,map,grep
2266 Note however that these particular block types are typically short
2268 so there might not be much opportunity for the cuddled format
2269 style.
2270 Using commas avoids the need to protect spaces with quotes.
2272 As a diagnostic check, the flag --dump-cuddled-block-list or -dcbl
2274 can be used to view the hash of values that are generated by this
2275 flag.
2276 Finally, note that the -cbl flag by itself merely specifies which
2278 blocks are formatted with the cuddled format. It has no effect
2279 unless this formatting style is activated with -ce.
2280 -cblx, --cuddled-block-list-exclusive
2282 When cuddled else formatting is selected with -ce, setting this
2283 flag causes perltidy to ignore its built-in defaults and rely
2284 exclusively on the block types specified on the -cbl flag described
2285 in the previous section. For example, to avoid using cuddled catch
2286 and finally, which among in the defaults, the following set of
2287 parameters could be used:
2288 perltidy -ce -cbl='else elsif continue' -cblx
2290 -cbo=n, --cuddled-break-option=n
2292 Cuddled formatting is only possible between a pair of code blocks
2293 if the closing brace of the first block starts a new line. If a
2294 block is encountered which is entirely on a single line, and
2295 cuddled formatting is selected, it is necessary to make a decision
2296 as to whether or not to "break" the block, meaning to cause it to
2297 span multiple lines. This parameter controls that decision. The
2298 options are:
2299 cbo=0 Never force a short block to break.
2301 cbo=1 If the first of a pair of blocks is broken in the input file,
2302 then break the second [DEFAULT].
2303 cbo=2 Break open all blocks for maximal cuddled formatting.
2304 The default and recommended value is cbo=1. With this value, if
2306 the starting block of a chain spans multiple lines, then a cascade
2307 of breaks will occur for remaining blocks causing the entire chain
2308 to be cuddled.
2309 The option cbo=0 can produce erratic cuddling if there are numerous
2311 one-line blocks.
2312 The option cbo=2 produces maximal cuddling but will not allow any
2314 short blocks.
2315 -bl, --opening-brace-on-new-line, or --brace-left
2317 Use the flag -bl to place an opening block brace on a new line:
2318 if ( $input_file eq '-' )
2320 {
2321 ...
2322 }
2323 By default it applies to all structural blocks except sort map grep
2325 eval and anonymous subs.
2326 The default is -nbl which places an opening brace on the same line
2328 as the keyword introducing it if possible. For example,
2329 # default
2331 if ( $input_file eq '-' ) {
2332 ...
2333 }
2334 When -bl is set, the blocks to which this applies can be controlled
2336 with the parameters --brace-left-list and
2337 -brace-left-exclusion-list described in the next sections.
2338 -bll=s, --brace-left-list=s
2340 Use this parameter to change the types of block braces for which
2341 the -bl flag applies; see "Specifying Block Types". For example,
2342 -bll='if elsif else sub' would apply it to only "if/elsif/else" and
2343 named sub blocks. The default is all blocks, -bll='*'.
2344 -blxl=s, --brace-left-exclusion-list=s
2346 Use this parameter to exclude types of block braces for which the
2347 -bl flag applies; see "Specifying Block Types". For example, the
2348 default settings -bll='*' and -blxl='sort map grep eval asub' mean
2349 all blocks except sort map grep eval and anonymous sub blocks.
2350 Note that the lists -bll=s and -blxl=s control the behavior of the
2352 -bl flag but have no effect unless the -bl flag is set.
2353 -sbl, --opening-sub-brace-on-new-line
2355 The flag -sbl provides a shortcut way to turn on -bl just for named
2356 subs. The same effect can be achieved by turning on -bl with the
2357 block list set as -bll='sub'.
2358 For example,
2360 perltidy -sbl
2362 produces this result:
2364 sub message
2366 {
2367 if (!defined($_[0])) {
2368 print("Hello, World\n");
2369 }
2370 else {
2371 print($_[0], "\n");
2372 }
2373 }
2374 This flag is negated with -nsbl, which is the default.
2376 -asbl, --opening-anonymous-sub-brace-on-new-line
2378 The flag -asbl is like the -sbl flag except that it applies to
2379 anonymous sub's instead of named subs. For example
2380 perltidy -asbl
2382 produces this result:
2384 $a = sub
2386 {
2387 if ( !defined( $_[0] ) ) {
2388 print("Hello, World\n");
2389 }
2390 else {
2391 print( $_[0], "\n" );
2392 }
2393 };
2394 This flag is negated with -nasbl, and the default is -nasbl.
2396 -bli, --brace-left-and-indent
2398 The flag -bli is similar to the -bl flag but in addition it causes
2399 one unit of continuation indentation ( see -ci ) to be placed
2400 before an opening and closing block braces.
2401 For example, perltidy -bli gives
2403 if ( $input_file eq '-' )
2405 {
2406 important_function();
2407 }
2408 By default, this extra indentation occurs for block types: if,
2410 elsif, else, unless, while, for, foreach, do, and also named subs
2411 and blocks preceded by a label. The next item shows how to change
2412 this.
2413 Note: The -bli flag is similar to the -bl flag, with the difference
2415 being that braces get indented. But these two flags are
2416 implemented independently, and have different default settings for
2417 historical reasons. If desired, a mixture of effects can be
2418 achieved if desired by turning them both on with different -list
2419 settings. In the event that both settings are selected for a
2420 certain block type, the -bli style has priority.
2421 -blil=s, --brace-left-and-indent-list=s
2423 Use this parameter to change the types of block braces for which
2424 the -bli flag applies; see "Specifying Block Types".
2425 The default is -blil='if else elsif unless while for foreach do :
2427 sub'.
2428 -blixl=s, --brace-left-and-indent-exclusion-list=s
2430 Use this parameter to exclude types of block braces for which the
2431 -bli flag applies; see "Specifying Block Types".
2432 This might be useful in conjunction with selecting all blocks
2434 -blil='*'. The default setting is -blixl=' ', which does not
2435 exclude any blocks.
2436 Note that the two parameters -blil and -blixl control the behavior
2438 of the -bli flag but have no effect unless the -bli flag is set.
2439 -bar, --opening-brace-always-on-right
2441 The default style, -nbl places the opening code block brace on a
2442 new line if it does not fit on the same line as the opening
2443 keyword, like this:
2444 if ( $bigwasteofspace1 && $bigwasteofspace2
2446 || $bigwasteofspace3 && $bigwasteofspace4 )
2447 {
2448 big_waste_of_time();
2449 }
2450 To force the opening brace to always be on the right, use the -bar
2452 flag. In this case, the above example becomes
2453 if ( $bigwasteofspace1 && $bigwasteofspace2
2455 || $bigwasteofspace3 && $bigwasteofspace4 ) {
2456 big_waste_of_time();
2457 }
2458 A conflict occurs if both -bl and -bar are specified.
2460 -otr, --opening-token-right and related flags
2462 The -otr flag is a hint that perltidy should not place a break
2463 between a comma and an opening token. For example:
2464 # default formatting
2466 push @{ $self->{$module}{$key} },
2467 {
2468 accno => $ref->{accno},
2469 description => $ref->{description}
2470 };
2471 # perltidy -otr
2473 push @{ $self->{$module}{$key} }, {
2474 accno => $ref->{accno},
2475 description => $ref->{description}
2476 };
2477 The flag -otr is actually an abbreviation for three other flags
2479 which can be used to control parens, hash braces, and square
2480 brackets separately if desired:
2481 -opr or --opening-paren-right
2483 -ohbr or --opening-hash-brace-right
2484 -osbr or --opening-square-bracket-right
2485 -bbhb=n, --break-before-hash-brace=n and related flags
2487 When a list of items spans multiple lines, the default formatting
2488 is to place the opening brace (or other container token) at the end
2489 of the starting line, like this:
2490 $romanNumerals = {
2492 one => 'I',
2493 two => 'II',
2494 three => 'III',
2495 four => 'IV',
2496 };
2497 This flag can change the default behavior to cause a line break to
2499 be placed before the opening brace according to the value given to
2500 the integer n:
2501 -bbhb=0 never break [default]
2503 -bbhb=1 stable: break if the input script had a break
2504 -bbhb=2 break if list is 'complex' (see note below)
2505 -bbhb=3 always break
2506 For example,
2508 # perltidy -bbhb=3
2510 $romanNumerals =
2511 {
2512 one => 'I',
2513 two => 'II',
2514 three => 'III',
2515 four => 'IV',
2516 };
2517 There are several points to note about this flag:
2519 • This parameter only applies if the opening brace is preceded by
2521 an '=' or '=>'.
2522 • This parameter only applies if the contents of the container
2524 looks like a list. The contents need to contain some commas or
2525 '=>'s at the next interior level to be considered a list.
2526 • For the n=2 option, a list is considered 'complex' if it is
2528 part of a nested list structure which spans multiple lines in
2529 the input file.
2530 • If multiple opening tokens have been 'welded' together with the
2532 -wn parameter, then this parameter has no effect.
2533 • The indentation of the braces will normally be one level of
2535 continuation indentation by default. This can be changed with
2536 the parameter -bbhbi=n in the next section.
2537 • Similar flags for controlling parens and square brackets are
2539 given in the subsequent section.
2540 -bbhbi=n, --break-before-hash-brace-and-indent=n
2542 This flag is a companion to -bbhb=n for controlling the indentation
2543 of an opening hash brace which is placed on a new line by that
2544 parameter. The indentation is as follows:
2545 -bbhbi=0 one continuation level [default]
2547 -bbhbi=1 outdent by one continuation level
2548 -bbhbi=2 indent one full indentation level
2549 For example:
2551 # perltidy -bbhb=3 -bbhbi=1
2553 $romanNumerals =
2554 {
2555 one => 'I',
2556 two => 'II',
2557 three => 'III',
2558 four => 'IV',
2559 };
2560 # perltidy -bbhb=3 -bbhbi=2
2562 $romanNumerals =
2563 {
2564 one => 'I',
2565 two => 'II',
2566 three => 'III',
2567 four => 'IV',
2568 };
2569 Note that this parameter has no effect unless -bbhb=n is also set.
2571 -bbsb=n, --break-before-square-bracket=n
2573 This flag is similar to the flag described above, except it applies
2574 to lists contained within square brackets.
2575 -bbsb=0 never break [default]
2577 -bbsb=1 stable: break if the input script had a break
2578 -bbsb=2 break if list is 'complex' (part of nested list structure)
2579 -bbsb=3 always break
2580 -bbsbi=n, --break-before-square-bracket-and-indent=n
2582 This flag is a companion to -bbsb=n for controlling the indentation
2583 of an opening square bracket which is placed on a new line by that
2584 parameter. The indentation is as follows:
2585 -bbsbi=0 one continuation level [default]
2587 -bbsbi=1 outdent by one continuation level
2588 -bbsbi=2 indent one full indentation level
2589 -bbp=n, --break-before-paren=n
2591 This flag is similar to -bbhb=n, described above, except it applies
2592 to lists contained within parens.
2593 -bbp=0 never break [default]
2595 -bbp=1 stable: break if the input script had a break
2596 -bpb=2 break if list is 'complex' (part of nested list structure)
2597 -bbp=3 always break
2598 -bbpi=n, --break-before-paren-and-indent=n
2600 This flag is a companion to -bbp=n for controlling the indentation
2601 of an opening paren which is placed on a new line by that
2602 parameter. The indentation is as follows:
2603 -bbpi=0 one continuation level [default]
2605 -bbpi=1 outdent by one continuation level
2606 -bbpi=2 indent one full indentation level
2607 -wn, --weld-nested-containers
2609 The -wn flag causes closely nested pairs of opening and closing
2610 container symbols (curly braces, brackets, or parens) to be
2611 "welded" together, meaning that they are treated as if combined
2612 into a single unit, with the indentation of the innermost code
2613 reduced to be as if there were just a single container symbol.
2614 For example:
2616 # default formatting
2618 do {
2619 {
2620 next if $x == $y;
2621 }
2622 } until $x++ > $z;
2623 # perltidy -wn
2625 do { {
2626 next if $x == $y;
2627 } } until $x++ > $z;
2628 When this flag is set perltidy makes a preliminary pass through the
2630 file and identifies all nested pairs of containers. To qualify as
2631 a nested pair, the closing container symbols must be immediately
2632 adjacent and the opening symbols must either (1) be adjacent as in
2633 the above example, or (2) have an anonymous sub declaration
2634 following an outer opening container symbol which is not a code
2635 block brace, or (3) have an outer opening paren separated from the
2636 inner opening symbol by any single non-container symbol or
2637 something that looks like a function evaluation, as illustrated in
2638 the next examples.
2639 Any container symbol may serve as both the inner container of one
2641 pair and as the outer container of an adjacent pair. Consequently,
2642 any number of adjacent opening or closing symbols may join together
2643 in weld. For example, here are three levels of wrapped function
2644 calls:
2645 # default formatting
2647 my (@date_time) = Localtime(
2648 Date_to_Time(
2649 Add_Delta_DHMS(
2650 $year, $month, $day, $hour, $minute, $second,
2651 '0', $offset, '0', '0'
2652 )
2653 )
2654 );
2655 # perltidy -wn
2657 my (@date_time) = Localtime( Date_to_Time( Add_Delta_DHMS(
2658 $year, $month, $day, $hour, $minute, $second,
2659 '0', $offset, '0', '0'
2660 ) ) );
2661 Notice how the indentation of the inner lines are reduced by two
2663 levels in this case. This example also shows the typical result of
2664 this formatting, namely it is a sandwich consisting of an initial
2665 opening layer, a central section of any complexity forming the
2666 "meat" of the sandwich, and a final closing layer. This
2667 predictable structure helps keep the compacted structure readable.
2668 The inner sandwich layer is required to be at least one line thick.
2670 If this cannot be achieved, welding does not occur. This
2671 constraint can cause formatting to take a couple of iterations to
2672 stabilize when it is first applied to a script. The -conv flag can
2673 be used to insure that the final format is achieved in a single
2674 run.
2675 Here is an example illustrating a welded container within a welded
2677 containers:
2678 # default formatting
2680 $x->badd(
2681 bmul(
2682 $class->new(
2683 abs(
2684 $sx * int( $xr->numify() ) & $sy * int( $yr->numify() )
2685 )
2686 ),
2687 $m
2688 )
2689 );
2690 # perltidy -wn
2692 $x->badd( bmul(
2693 $class->new( abs(
2694 $sx * int( $xr->numify() ) & $sy * int( $yr->numify() )
2695 ) ),
2696 $m
2697 ) );
2698 The welded closing tokens are by default on a separate line but
2700 this can be modified with the -vtc=n flag (described in the next
2701 section). For example, the same example adding -vtc=2 is
2702 # perltidy -wn -vtc=2
2704 $x->badd( bmul(
2705 $class->new( abs(
2706 $sx * int( $xr->numify() ) & $sy * int( $yr->numify() ) ) ),
2707 $m ) );
2708 This format option is quite general but there are some limitations.
2710 One limitation is that any line length limit still applies and can
2712 cause long welded sections to be broken into multiple lines.
2713 Another limitation is that an opening symbol which delimits quoted
2715 text cannot be included in a welded pair. This is because quote
2716 delimiters are treated specially in perltidy.
2717 Finally, the stacking of containers defined by this flag have
2719 priority over any other container stacking flags. This is because
2720 any welding is done first.
2721 -wnxl=s, --weld-nested-exclusion-list
2723 The -wnxl=s flag provides some control over the types of containers
2724 which can be welded. The -wn flag by default is "greedy" in
2725 welding adjacent containers. If it welds more types of containers
2726 than desired, this flag provides a capability to reduce the amount
2727 of welding by specifying a list of things which should not be
2728 welded.
2729 The logic in perltidy to apply this is straightforward. As each
2731 container token is being considered for joining a weld, any
2732 exclusion rules are consulted and used to reject the weld if
2733 necessary.
2734 This list is a string with space-separated items. Each item
2736 consists of up to three pieces of information: (1) an optional
2737 position, (2) an optional preceding type, and (3) a container type.
2738 The only required piece of information is a container type, which
2740 is one of '(', '[', '{' or 'q'. The first three of these are
2741 container tokens and the last represents a quoted list. For
2742 example the string
2743 -wnxl='[ { q'
2745 means do NOT include square-bracets, braces, or quotes in any
2747 welds. The only unspecified container is '(', so this string means
2748 that only welds involving parens will be made.
2749 To illustrate, following welded snippet consists of a chain of
2751 three welded containers with types '(' '[' and 'q':
2752 # perltidy -wn
2754 skip_symbols( [ qw(
2755 Perl_dump_fds
2756 Perl_ErrorNo
2757 Perl_GetVars
2758 PL_sys_intern
2759 ) ] );
2760 Even though the qw term uses parens as the quote delimiter, it has
2762 a special type 'q' here. If it appears in a weld it always appears
2763 at the end of the welded chain.
2764 Any of the container types '[', '{', and '(' may be prefixed with a
2766 position indicator which is either '^', to indicate the first token
2767 of a welded sequence, or '.', to indicate an interior token of a
2768 welded sequence. (Since a quoted string 'q' always ends a chain it
2769 does need a position indicator).
2770 For example, if we do not want a sequence of welded containers to
2772 start with a square bracket we could use
2773 -wnxl='^['
2775 In the above snippet, there is a square bracket but it does not
2777 start the chain, so the formatting would be unchanged if it were
2778 formatted with this restriction.
2779 A third optional item of information which can be given is an
2781 alphanumeric letter which is used to limit the selection further
2782 depending on the type of token immediately before the container.
2783 If given, it goes just before the container symbol. The possible
2784 letters are currently 'k', 'K', 'f', 'F', 'w', and 'W', with these
2785 meanings:
2786 'k' matches if the previous nonblank token is a perl built-in keyword (such as 'if', 'while'),
2788 'K' matches if 'k' does not, meaning that the previous token is not a keyword.
2789 'f' matches if the previous token is a function other than a keyword.
2790 'F' matches if 'f' does not.
2791 'w' matches if either 'k' or 'f' match.
2792 'W' matches if 'w' does not.
2793 For example, compare
2795 # perltidy -wn
2797 if ( defined( $_Cgi_Query{
2798 $Config{'methods'}{'authentication'}{'remote'}{'cgi'}{'username'}
2799 } ) )
2800 with
2802 # perltidy -wn -wnxl='^K( {'
2804 if ( defined(
2805 $_Cgi_Query{ $Config{'methods'}{'authentication'}{'remote'}{'cgi'}
2806 {'username'} }
2807 ) )
2808 The first case does maximum welding. In the second case the leading
2810 paren is retained by the rule (it would have been rejected if
2811 preceded by a non-keyword) but the curly brace is rejected by the
2812 rule.
2813 Here are some additional example strings and their meanings:
2815 '^(' - the weld must not start with a paren
2817 '.(' - the second and later tokens may not be parens
2818 '.w(' - the second and later tokens may not keyword or function call parens
2819 '(' - no parens in a weld
2820 '^K(' - exclude a leading paren preceded by a non-keyword
2821 '.k(' - exclude a secondary paren preceded by a keyword
2822 '[ {' - exclude all brackets and braces
2823 '[ ( ^K{' - exclude everything except nested structures like do {{ ... }}
2824 Vertical tightness of non-block curly braces, parentheses, and square
2826 brackets.
2827 These parameters control what shall be called vertical tightness.
2828 Here are the main points:
2829 • Opening tokens (except for block braces) are controlled by
2831 -vt=n, or --vertical-tightness=n, where
2832 -vt=0 always break a line after opening token (default).
2834 -vt=1 do not break unless this would produce more than one
2835 step in indentation in a line.
2836 -vt=2 never break a line after opening token
2837 • You must also use the -lp flag when you use the -vt flag; the
2839 reason is explained below.
2840 • Closing tokens (except for block braces) are controlled by
2842 -vtc=n, or --vertical-tightness-closing=n, where
2843 -vtc=0 always break a line before a closing token (default),
2845 -vtc=1 do not break before a closing token which is followed
2846 by a semicolon or another closing token, and is not in
2847 a list environment.
2848 -vtc=2 never break before a closing token.
2849 -vtc=3 Like -vtc=1 except always break before a closing token
2850 if the corresponding opening token follows an = or =>.
2851 The rules for -vtc=1 and -vtc=3 are designed to maintain a
2853 reasonable balance between tightness and readability in complex
2854 lists.
2855 • Different controls may be applied to different token types, and
2857 it is also possible to control block braces; see below.
2858 • Finally, please note that these vertical tightness flags are
2860 merely hints to the formatter, and it cannot always follow
2861 them. Things which make it difficult or impossible include
2862 comments, blank lines, blocks of code within a list, and
2863 possibly the lack of the -lp parameter. Also, these flags may
2864 be ignored for very small lists (2 or 3 lines in length).
2865 Here are some examples:
2867 # perltidy -lp -vt=0 -vtc=0
2869 %romanNumerals = (
2870 one => 'I',
2871 two => 'II',
2872 three => 'III',
2873 four => 'IV',
2874 );
2875 # perltidy -lp -vt=1 -vtc=0
2877 %romanNumerals = ( one => 'I',
2878 two => 'II',
2879 three => 'III',
2880 four => 'IV',
2881 );
2882 # perltidy -lp -vt=1 -vtc=1
2884 %romanNumerals = ( one => 'I',
2885 two => 'II',
2886 three => 'III',
2887 four => 'IV', );
2888 # perltidy -vtc=3
2890 my_function(
2891 one => 'I',
2892 two => 'II',
2893 three => 'III',
2894 four => 'IV', );
2895 # perltidy -vtc=3
2897 %romanNumerals = (
2898 one => 'I',
2899 two => 'II',
2900 three => 'III',
2901 four => 'IV',
2902 );
2903 In the last example for -vtc=3, the opening paren is preceded by an
2905 equals so the closing paren is placed on a new line.
2906 The difference between -vt=1 and -vt=2 is shown here:
2908 # perltidy -lp -vt=1
2910 $init->add(
2911 mysprintf( "(void)find_threadsv(%s);",
2912 cstring( $threadsv_names[ $op->targ ] )
2913 )
2914 );
2915 # perltidy -lp -vt=2
2917 $init->add( mysprintf( "(void)find_threadsv(%s);",
2918 cstring( $threadsv_names[ $op->targ ] )
2919 )
2920 );
2921 With -vt=1, the line ending in "add(" does not combine with the
2923 next line because the next line is not balanced. This can help
2924 with readability, but -vt=2 can be used to ignore this rule.
2925 The tightest, and least readable, code is produced with both
2927 "-vt=2" and "-vtc=2":
2928 # perltidy -lp -vt=2 -vtc=2
2930 $init->add( mysprintf( "(void)find_threadsv(%s);",
2931 cstring( $threadsv_names[ $op->targ ] ) ) );
2932 Notice how the code in all of these examples collapses vertically
2934 as -vt increases, but the indentation remains unchanged. This is
2935 because perltidy implements the -vt parameter by first formatting
2936 as if -vt=0, and then simply overwriting one output line on top of
2937 the next, if possible, to achieve the desired vertical tightness.
2938 The -lp indentation style has been designed to allow this vertical
2939 collapse to occur, which is why it is required for the -vt
2940 parameter.
2941 The -vt=n and -vtc=n parameters apply to each type of container
2943 token. If desired, vertical tightness controls can be applied
2944 independently to each of the closing container token types.
2945 The parameters for controlling parentheses are -pvt=n or
2947 --paren-vertical-tightness=n, and -pvtc=n or
2948 --paren-vertical-tightness-closing=n.
2949 Likewise, the parameters for square brackets are -sbvt=n or
2951 --square-bracket-vertical-tightness=n, and -sbvtc=n or
2952 --square-bracket-vertical-tightness-closing=n.
2953 Finally, the parameters for controlling non-code block braces are
2955 -bvt=n or --brace-vertical-tightness=n, and -bvtc=n or
2956 --brace-vertical-tightness-closing=n.
2957 In fact, the parameter -vt=n is actually just an abbreviation for
2959 -pvt=n -bvt=n sbvt=n, and likewise -vtc=n is an abbreviation for
2960 -pvtc=n -bvtc=n -sbvtc=n.
2961 -bbvt=n or --block-brace-vertical-tightness=n
2963 The -bbvt=n flag is just like the -vt=n flag but applies to opening
2964 code block braces.
2965 -bbvt=0 break after opening block brace (default).
2967 -bbvt=1 do not break unless this would produce more than one
2968 step in indentation in a line.
2969 -bbvt=2 do not break after opening block brace.
2970 It is necessary to also use either -bl or -bli for this to work,
2972 because, as with other vertical tightness controls, it is
2973 implemented by simply overwriting a line ending with an opening
2974 block brace with the subsequent line. For example:
2975 # perltidy -bli -bbvt=0
2977 if ( open( FILE, "< $File" ) )
2978 {
2979 while ( $File = <FILE> )
2980 {
2981 $In .= $File;
2982 $count++;
2983 }
2984 close(FILE);
2985 }
2986 # perltidy -bli -bbvt=1
2988 if ( open( FILE, "< $File" ) )
2989 { while ( $File = <FILE> )
2990 { $In .= $File;
2991 $count++;
2992 }
2993 close(FILE);
2994 }
2995 By default this applies to blocks associated with keywords if,
2997 elsif, else, unless, for, foreach, sub, while, until, and also with
2998 a preceding label. This can be changed with the parameter
2999 -bbvtl=string, or --block-brace-vertical-tightness-list=string,
3000 where string is a space-separated list of block types. For more
3001 information on the possible values of this string, see "Specifying
3002 Block Types"
3003 For example, if we want to just apply this style to "if", "elsif",
3005 and "else" blocks, we could use "perltidy -bli -bbvt=1 -bbvtl='if
3006 elsif else'".
3007 There is no vertical tightness control for closing block braces;
3009 with one exception they will be placed on separate lines. The
3010 exception is that a cascade of closing block braces may be stacked
3011 on a single line. See -scbb.
3012 -sot, --stack-opening-tokens and related flags
3014 The -sot flag tells perltidy to "stack" opening tokens when
3015 possible to avoid lines with isolated opening tokens.
3016 For example:
3018 # default
3020 $opt_c = Text::CSV_XS->new(
3021 {
3022 binary => 1,
3023 sep_char => $opt_c,
3024 always_quote => 1,
3025 }
3026 );
3027 # -sot
3029 $opt_c = Text::CSV_XS->new( {
3030 binary => 1,
3031 sep_char => $opt_c,
3032 always_quote => 1,
3033 }
3034 );
3035 For detailed control of individual closing tokens the following
3037 controls can be used:
3038 -sop or --stack-opening-paren
3040 -sohb or --stack-opening-hash-brace
3041 -sosb or --stack-opening-square-bracket
3042 -sobb or --stack-opening-block-brace
3043 The flag -sot is an abbreviation for -sop -sohb -sosb.
3045 The flag -sobb is an abbreviation for -bbvt=2 -bbvtl='*'. This
3047 will case a cascade of opening block braces to appear on a single
3048 line, although this an uncommon occurrence except in test scripts.
3049 -sct, --stack-closing-tokens and related flags
3051 The -sct flag tells perltidy to "stack" closing tokens when
3052 possible to avoid lines with isolated closing tokens.
3053 For example:
3055 # default
3057 $opt_c = Text::CSV_XS->new(
3058 {
3059 binary => 1,
3060 sep_char => $opt_c,
3061 always_quote => 1,
3062 }
3063 );
3064 # -sct
3066 $opt_c = Text::CSV_XS->new(
3067 {
3068 binary => 1,
3069 sep_char => $opt_c,
3070 always_quote => 1,
3071 } );
3072 The -sct flag is somewhat similar to the -vtc flags, and in some
3074 cases it can give a similar result. The difference is that the
3075 -vtc flags try to avoid lines with leading opening tokens by
3076 "hiding" them at the end of a previous line, whereas the -sct flag
3077 merely tries to reduce the number of lines with isolated closing
3078 tokens by stacking them but does not try to hide them. For
3079 example:
3080 # -vtc=2
3082 $opt_c = Text::CSV_XS->new(
3083 {
3084 binary => 1,
3085 sep_char => $opt_c,
3086 always_quote => 1, } );
3087 For detailed control of the stacking of individual closing tokens
3089 the following controls can be used:
3090 -scp or --stack-closing-paren
3092 -schb or --stack-closing-hash-brace
3093 -scsb or --stack-closing-square-bracket
3094 -scbb or --stack-closing-block-brace
3095 The flag -sct is an abbreviation for stacking the non-block closing
3097 tokens, -scp -schb -scsb.
3098 Stacking of closing block braces, -scbb, causes a cascade of
3100 isolated closing block braces to be combined into a single line as
3101 in the following example:
3102 # -scbb:
3104 for $w1 (@w1) {
3105 for $w2 (@w2) {
3106 for $w3 (@w3) {
3107 for $w4 (@w4) {
3108 push( @lines, "$w1 $w2 $w3 $w4\n" );
3109 } } } }
3110 To simplify input even further for the case in which both opening
3112 and closing non-block containers are stacked, the flag -sac or
3113 --stack-all-containers is an abbreviation for -sot -sct.
3114 Please note that if both opening and closing tokens are to be
3116 stacked, then the newer flag -weld-nested-containers may be
3117 preferable because it insures that stacking is always done
3118 symmetrically. It also removes an extra level of unnecessary
3119 indentation within welded containers. It is able to do this
3120 because it works on formatting globally rather than locally, as the
3121 -sot and -sct flags do.
3122 -dnl, --delete-old-newlines
3124 By default, perltidy first deletes all old line break locations,
3125 and then it looks for good break points to match the desired line
3126 length. Use -ndnl or --nodelete-old-newlines to force perltidy to
3127 retain all old line break points.
3128 -anl, --add-newlines
3130 By default, perltidy will add line breaks when necessary to create
3131 continuations of long lines and to improve the script appearance.
3132 Use -nanl or --noadd-newlines to prevent any new line breaks.
3133 This flag does not prevent perltidy from eliminating existing line
3135 breaks; see --freeze-newlines to completely prevent changes to line
3136 break points.
3137 Controlling whether perltidy breaks before or after operators
3139 Four command line parameters provide some control over whether a
3140 line break should be before or after specific token types. Two
3141 parameters give detailed control:
3142 -wba=s or --want-break-after=s, and
3144 -wbb=s or --want-break-before=s.
3146 These parameters are each followed by a quoted string, s,
3148 containing a list of token types (separated only by spaces). No
3149 more than one of each of these parameters should be specified,
3150 because repeating a command-line parameter always overwrites the
3151 previous one before perltidy ever sees it.
3152 By default, perltidy breaks after these token types:
3154 % + - * / x != == >= <= =~ !~ < > | &
3155 = **= += *= &= <<= &&= -= /= |= >>= ||= //= .= %= ^= x=
3156 And perltidy breaks before these token types by default:
3158 . << >> -> && || //
3159 To illustrate, to cause a break after a concatenation operator,
3161 '.', rather than before it, the command line would be
3162 -wba="."
3164 As another example, the following command would cause a break
3166 before math operators '+', '-', '/', and '*':
3167 -wbb="+ - / *"
3169 These commands should work well for most of the token types that
3171 perltidy uses (use --dump-token-types for a list). Also try the -D
3172 flag on a short snippet of code and look at the .DEBUG file to see
3173 the tokenization. However, for a few token types there may be
3174 conflicts with hardwired logic which cause unexpected results. One
3175 example is curly braces, which should be controlled with the
3176 parameter bl provided for that purpose.
3177 WARNING Be sure to put these tokens in quotes to avoid having them
3179 misinterpreted by your command shell.
3180 Two additional parameters are available which, though they provide
3182 no further capability, can simplify input are:
3183 -baao or --break-after-all-operators,
3185 -bbao or --break-before-all-operators.
3187 The -baao sets the default to be to break after all of the
3189 following operators:
3190 % + - * / x != == >= <= =~ !~ < > | &
3192 = **= += *= &= <<= &&= -= /= |= >>= ||= //= .= %= ^= x=
3193 . : ? && || and or err xor
3194 and the -bbao flag sets the default to break before all of these
3196 operators. These can be used to define an initial break preference
3197 which can be fine-tuned with the -wba and -wbb flags. For example,
3198 to break before all operators except an = one could use --bbao
3199 -wba='=' rather than listing every single perl operator except = on
3200 a -wbb flag.
3201 bal=n, --break-after-labels=n
3203 This flag controls whether or not a line break occurs after a
3204 label. There are three possible values for n:
3205 -bal=0 break if there is a break in the input [DEFAULT]
3207 -bal=1 always break after a label
3208 -bal=2 never break after a label
3209 For example,
3211 # perltidy -bal=1
3213 RETURN:
3214 return;
3215 # perltidy -bal=2
3217 RETURN: return;
3218 Controlling List Formatting
3220 Perltidy attempts to format lists of comma-separated values in tables
3221 which look good. Its default algorithms usually work well, but
3222 sometimes they don't. In this case, there are several methods
3223 available to control list formatting.
3224 A very simple way to prevent perltidy from changing the line breaks
3226 within a comma-separated list of values is to insert a blank line,
3227 comment, or side-comment anywhere between the opening and closing
3228 parens (or braces or brackets). This causes perltidy to skip over its
3229 list formatting logic. (The reason is that any of these items put a
3230 constraint on line breaks, and perltidy needs complete control over
3231 line breaks within a container to adjust a list layout). For example,
3232 let us consider
3233 my @list = (1,
3235 1, 1,
3236 1, 2, 1,
3237 1, 3, 3, 1,
3238 1, 4, 6, 4, 1,);
3239 The default formatting, which allows a maximum line length of 80, will
3241 flatten this down to one line:
3242 # perltidy (default)
3244 my @list = ( 1, 1, 1, 1, 2, 1, 1, 3, 3, 1, 1, 4, 6, 4, 1, );
3245 This formatting loses the nice structure. If we place a side comment
3247 anywhere between the opening and closing parens, the original line
3248 break points are retained. For example,
3249 my @list = (
3251 1, # a side comment forces the original line breakpoints to be kept
3252 1, 1,
3253 1, 2, 1,
3254 1, 3, 3, 1,
3255 1, 4, 6, 4, 1,
3256 );
3257 The side comment can be a single hash symbol without any text. We
3259 could achieve the same result with a blank line or full comment
3260 anywhere between the opening and closing parens. Vertical alignment of
3261 the list items will still occur if possible.
3262 For another possibility see the -fs flag in "Skipping Selected Sections
3264 of Code".
3265 -boc, --break-at-old-comma-breakpoints
3267 The -boc flag is another way to prevent comma-separated lists from
3268 being reformatted. Using -boc on the above example, plus
3269 additional flags to retain the original style, yields
3270 # perltidy -boc -lp -pt=2 -vt=1 -vtc=1
3272 my @list = (1,
3273 1, 1,
3274 1, 2, 1,
3275 1, 3, 3, 1,
3276 1, 4, 6, 4, 1,);
3277 A disadvantage of this flag compared to the methods discussed above
3279 is that all tables in the file must already be nicely formatted.
3280 -mft=n, --maximum-fields-per-table=n
3282 If the computed number of fields for any table exceeds n, then it
3283 will be reduced to n. The default value for n is a large number,
3284 40. While this value should probably be left unchanged as a
3285 general rule, it might be used on a small section of code to force
3286 a list to have a particular number of fields per line, and then
3287 either the -boc flag could be used to retain this formatting, or a
3288 single comment could be introduced somewhere to freeze the
3289 formatting in future applications of perltidy.
3290 # perltidy -mft=2
3292 @month_of_year = (
3293 'Jan', 'Feb',
3294 'Mar', 'Apr',
3295 'May', 'Jun',
3296 'Jul', 'Aug',
3297 'Sep', 'Oct',
3298 'Nov', 'Dec'
3299 );
3300 -cab=n, --comma-arrow-breakpoints=n
3302 A comma which follows a comma arrow, '=>', is given special
3303 consideration. In a long list, it is common to break at all such
3304 commas. This parameter can be used to control how perltidy breaks
3305 at these commas. (However, it will have no effect if old comma
3306 breaks are being forced because -boc is used). The possible values
3307 of n are:
3308 n=0 break at all commas after =>
3310 n=1 stable: break at all commas after => if container is open,
3311 EXCEPT FOR one-line containers
3312 n=2 break at all commas after =>, BUT try to form the maximum
3313 one-line container lengths
3314 n=3 do not treat commas after => specially at all
3315 n=4 break everything: like n=0 but ALSO break a short container with
3316 a => not followed by a comma when -vt=0 is used
3317 n=5 stable: like n=1 but ALSO break at open one-line containers when
3318 -vt=0 is used (default)
3319 For example, given the following single line, perltidy by default
3321 will not add any line breaks because it would break the existing
3322 one-line container:
3323 bless { B => $B, Root => $Root } => $package;
3325 Using -cab=0 will force a break after each comma-arrow item:
3327 # perltidy -cab=0:
3329 bless {
3330 B => $B,
3331 Root => $Root
3332 } => $package;
3333 If perltidy is subsequently run with this container broken, then by
3335 default it will break after each '=>' because the container is now
3336 broken. To reform a one-line container, the parameter -cab=2 could
3337 be used.
3338 The flag -cab=3 can be used to prevent these commas from being
3340 treated specially. In this case, an item such as "01" => 31 is
3341 treated as a single item in a table. The number of fields in this
3342 table will be determined by the same rules that are used for any
3343 other table. Here is an example.
3344 # perltidy -cab=3
3346 my %last_day = (
3347 "01" => 31, "02" => 29, "03" => 31, "04" => 30,
3348 "05" => 31, "06" => 30, "07" => 31, "08" => 31,
3349 "09" => 30, "10" => 31, "11" => 30, "12" => 31
3350 );
3351 Retaining or Ignoring Existing Line Breaks
3353 Several additional parameters are available for controlling the extent
3354 to which line breaks in the input script influence the output script.
3355 In most cases, the default parameter values are set so that, if a
3356 choice is possible, the output style follows the input style. For
3357 example, if a short logical container is broken in the input script,
3358 then the default behavior is for it to remain broken in the output
3359 script.
3360 Most of the parameters in this section would only be required for a
3362 one-time conversion of a script from short container lengths to longer
3363 container lengths. The opposite effect, of converting long container
3364 lengths to shorter lengths, can be obtained by temporarily using a
3365 short maximum line length.
3366 -bol, --break-at-old-logical-breakpoints
3368 By default, if a logical expression is broken at a "&&", "||",
3369 "and", or "or", then the container will remain broken. Also,
3370 breaks at internal keywords "if" and "unless" will normally be
3371 retained. To prevent this, and thus form longer lines, use -nbol.
3372 Please note that this flag does not duplicate old logical
3374 breakpoints. They are merely used as a hint with this flag that a
3375 statement should remain broken. Without this flag, perltidy will
3376 normally try to combine relatively short expressions into a single
3377 line.
3378 For example, given this snippet:
3380 return unless $cmd = $cmd || ($dot
3382 && $Last_Shell) || &prompt('|');
3383 # perltidy -bol [default]
3385 return
3386 unless $cmd = $cmd
3387 || ( $dot
3388 && $Last_Shell )
3389 || &prompt('|');
3390 # perltidy -nbol
3392 return unless $cmd = $cmd || ( $dot && $Last_Shell ) || &prompt('|');
3393 -bom, --break-at-old-method-breakpoints
3395 By default, a method call arrow "->" is considered a candidate for
3396 a breakpoint, but method chains will fill to the line width before
3397 a break is considered. With -bom, breaks before the arrow are
3398 preserved, so if you have preformatted a method chain:
3399 my $q = $rs
3401 ->related_resultset('CDs')
3402 ->related_resultset('Tracks')
3403 ->search({
3404 'track.id' => {-ident => 'none_search.id'},
3405 })->as_query;
3406 It will keep these breaks, rather than become this:
3408 my $q = $rs->related_resultset('CDs')->related_resultset('Tracks')->search({
3410 'track.id' => {-ident => 'none_search.id'},
3411 })->as_query;
3412 This flag will also look for and keep a 'cuddled' style of calls,
3414 in which lines begin with a closing paren followed by a call arrow,
3415 as in this example:
3416 # perltidy -bom -wn
3418 my $q = $rs->related_resultset(
3419 'CDs'
3420 )->related_resultset(
3421 'Tracks'
3422 )->search( {
3423 'track.id' => { -ident => 'none_search.id' },
3424 } )->as_query;
3425 You may want to include the -weld-nested-containers flag in this
3427 case to keep nested braces and parens together, as in the last
3428 line.
3429 -bos, --break-at-old-semicolon-breakpoints
3431 Semicolons are normally placed at the end of a statement. This
3432 means that formatted lines do not normally begin with semicolons.
3433 If the input stream has some lines which begin with semicolons,
3434 these can be retained by setting this flag. For example, consider
3435 the following two-line input snippet:
3436 $z = sqrt($x**2 + $y**2)
3438 ;
3439 The default formatting will be:
3441 $z = sqrt( $x**2 + $y**2 );
3443 The result using perltidy -bos keeps the isolated semicolon:
3445 $z = sqrt( $x**2 + $y**2 )
3447 ;
3448 The default is not to do this, -nbos.
3450 -bok, --break-at-old-keyword-breakpoints
3452 By default, perltidy will retain a breakpoint before keywords which
3453 may return lists, such as "sort" and <map>. This allows chains of
3454 these operators to be displayed one per line. Use -nbok to prevent
3455 retaining these breakpoints.
3456 -bot, --break-at-old-ternary-breakpoints
3458 By default, if a conditional (ternary) operator is broken at a ":",
3459 then it will remain broken. To prevent this, and thereby form
3460 longer lines, use -nbot.
3461 -boa, --break-at-old-attribute-breakpoints
3463 By default, if an attribute list is broken at a ":" in the source
3464 file, then it will remain broken. For example, given the following
3465 code, the line breaks at the ':'s will be retained:
3466 my @field
3468 : field
3469 : Default(1)
3470 : Get('Name' => 'foo') : Set('Name');
3471 If the attributes are on a single line in the source code then they
3473 will remain on a single line if possible.
3474 To prevent this, and thereby always form longer lines, use -nboa.
3476 Keeping old breakpoints at specific token types
3478 It is possible to override the choice of line breaks made by
3479 perltidy, and force it to follow certain line breaks in the input
3480 stream, with these two parameters:
3481 -kbb=s or --keep-old-breakpoints-before=s, and
3483 -kba=s or --keep-old-breakpoints-after=s
3485 These parameters are each followed by a quoted string, s,
3487 containing a list of token types (separated only by spaces). No
3488 more than one of each of these parameters should be specified,
3489 because repeating a command-line parameter always overwrites the
3490 previous one before perltidy ever sees it.
3491 For example, -kbb='=>' means that if an input line begins with a
3493 '=>' then the output script should also have a line break before
3494 that token.
3495 For example, given the script:
3497 method 'foo'
3499 => [ Int, Int ]
3500 => sub {
3501 my ( $self, $x, $y ) = ( shift, @_ );
3502 ...;
3503 };
3504 # perltidy [default]
3506 method 'foo' => [ Int, Int ] => sub {
3507 my ( $self, $x, $y ) = ( shift, @_ );
3508 ...;
3509 };
3510 # perltidy -kbb='=>'
3512 method 'foo'
3513 => [ Int, Int ]
3514 => sub {
3515 my ( $self, $x, $y ) = ( shift, @_ );
3516 ...;
3517 };
3518 For the container tokens '{', '[' and '(' and, their closing
3520 counterparts, use the token symbol. Thus, the command to keep a
3521 break after all opening parens is:
3522 perltidy -kba='('
3524 It is possible to be more specific in matching parentheses by
3526 preceding them with a letter. The possible letters are 'k', 'K',
3527 'f', 'F', 'w', and 'W', with these meanings (these are the same as
3528 used in the --weld-nested-exclusion-list and
3529 --line-up-parentheses-exclusion-list parameters):
3530 'k' matches if the previous nonblank token is a perl built-in keyword (such as 'if', 'while'),
3532 'K' matches if 'k' does not, meaning that the previous token is not a keyword.
3533 'f' matches if the previous token is a function other than a keyword.
3534 'F' matches if 'f' does not.
3535 'w' matches if either 'k' or 'f' match.
3536 'W' matches if 'w' does not.
3537 So for example the the following parameter will keep breaks after
3539 opening function call parens:
3540 perltidy -kba='f('
3542 NOTE: A request to break before an opening container, such as
3544 -kbb='(', will be silently ignored because it can lead to
3545 formatting instability. Likewise, a request to break after a
3546 closing container, such as -kba=')', will also be silently ignored.
3547 -iob, --ignore-old-breakpoints
3549 Use this flag to tell perltidy to ignore existing line breaks to
3550 the maximum extent possible. This will tend to produce the longest
3551 possible containers, regardless of type, which do not exceed the
3552 line length limit. But please note that this parameter has
3553 priority over all other parameters requesting that certain old
3554 breakpoints be kept.
3555 To illustrate, consider the following input text:
3557 has subcmds => (
3559 is => 'ro',
3560 default => sub { [] },
3561 );
3562 The default formatting will keep the container broken, giving
3564 # perltidy [default]
3566 has subcmds => (
3567 is => 'ro',
3568 default => sub { [] },
3569 );
3570 If old breakpoints are ignored, the list will be flattened:
3572 # perltidy -iob
3574 has subcmds => ( is => 'ro', default => sub { [] }, );
3575 Besides flattening lists, this parameter also applies to lines
3577 broken at certain logical breakpoints such as 'if' and 'or'.
3578 Even if this is parameter is not used globally, it provides a
3580 convenient way to flatten selected lists from within an editor.
3581 -kis, --keep-interior-semicolons
3583 Use the -kis flag to prevent breaking at a semicolon if there was
3584 no break there in the input file. Normally perltidy places a
3585 newline after each semicolon which terminates a statement unless
3586 several statements are contained within a one-line brace block. To
3587 illustrate, consider the following input lines:
3588 dbmclose(%verb_delim); undef %verb_delim;
3590 dbmclose(%expanded); undef %expanded;
3591 The default is to break after each statement, giving
3593 dbmclose(%verb_delim);
3595 undef %verb_delim;
3596 dbmclose(%expanded);
3597 undef %expanded;
3598 With perltidy -kis the multiple statements are retained:
3600 dbmclose(%verb_delim); undef %verb_delim;
3602 dbmclose(%expanded); undef %expanded;
3603 The statements are still subject to the specified value of maximum-
3605 line-length and will be broken if this maximum is exceeded.
3606 Blank Line Control
3608 Blank lines can improve the readability of a script if they are
3609 carefully placed. Perltidy has several commands for controlling the
3610 insertion, retention, and removal of blank lines.
3611 -fbl, --freeze-blank-lines
3613 Set -fbl if you want to the blank lines in your script to remain
3614 exactly as they are. The rest of the parameters in this section
3615 may then be ignored. (Note: setting the -fbl flag is equivalent to
3616 setting -mbl=0 and -kbl=2).
3617 -bbc, --blanks-before-comments
3619 A blank line will be introduced before a full-line comment. This
3620 is the default. Use -nbbc or --noblanks-before-comments to
3621 prevent such blank lines from being introduced.
3622 -blbs=n, --blank-lines-before-subs=n
3624 The parameter -blbs=n requests that least n blank lines precede a
3625 sub definition which does not follow a comment and which is more
3626 than one-line long. The default is <-blbs=1>. BEGIN and END
3627 blocks are included.
3628 The requested number of blanks statement will be inserted
3630 regardless of the value of --maximum-consecutive-blank-lines=n
3631 (-mbl=n) with the exception that if -mbl=0 then no blanks will be
3632 output.
3633 This parameter interacts with the value k of the parameter
3635 --maximum-consecutive-blank-lines=k (-mbl=k) as follows:
3636 1. If -mbl=0 then no blanks will be output. This allows all blanks
3638 to be suppressed with a single parameter. Otherwise,
3639 2. If the number of old blank lines in the script is less than n
3641 then additional blanks will be inserted to make the total n
3642 regardless of the value of -mbl=k.
3643 3. If the number of old blank lines in the script equals or exceeds
3645 n then this parameter has no effect, however the total will not
3646 exceed value specified on the -mbl=k flag.
3647 -blbp=n, --blank-lines-before-packages=n
3649 The parameter -blbp=n requests that least n blank lines precede a
3650 package which does not follow a comment. The default is -blbp=1.
3651 This parameter interacts with the value k of the parameter
3653 --maximum-consecutive-blank-lines=k (-mbl=k) in the same way as
3654 described for the previous item -blbs=n.
3655 -bbs, --blanks-before-subs
3657 For compatibility with previous versions, -bbs or
3658 --blanks-before-subs is equivalent to -blbp=1 and -blbs=1.
3659 Likewise, -nbbs or --noblanks-before-subs is equivalent to -blbp=0
3661 and -blbs=0.
3662 -bbb, --blanks-before-blocks
3664 A blank line will be introduced before blocks of coding delimited
3665 by for, foreach, while, until, and if, unless, in the following
3666 circumstances:
3667 • The block is not preceded by a comment.
3669 • The block is not a one-line block.
3671 • The number of consecutive non-blank lines at the current
3673 indentation depth is at least -lbl (see next section).
3674 This is the default. The intention of this option is to introduce
3676 some space within dense coding. This is negated with -nbbb or
3677 --noblanks-before-blocks.
3678 -lbl=n --long-block-line-count=n
3680 This controls how often perltidy is allowed to add blank lines
3681 before certain block types (see previous section). The default is
3682 8. Entering a value of 0 is equivalent to entering a very large
3683 number.
3684 -blao=i or --blank-lines-after-opening-block=i
3686 This control places a minimum of i blank lines after a line which
3687 ends with an opening block brace of a specified type. By default,
3688 this only applies to the block of a named sub, but this can be
3689 changed (see -blaol below). The default is not to do this (i=0).
3690 Please see the note below on using the -blao and -blbc options.
3692 -blbc=i or --blank-lines-before-closing-block=i
3694 This control places a minimum of i blank lines before a line which
3695 begins with a closing block brace of a specified type. By default,
3696 this only applies to the block of a named sub, but this can be
3697 changed (see -blbcl below). The default is not to do this (i=0).
3698 -blaol=s or --blank-lines-after-opening-block-list=s
3700 The parameter s is a list of block type keywords to which the flag
3701 -blao should apply. The section "Specifying Block Types" explains
3702 how to list block types.
3703 -blbcl=s or --blank-lines-before-closing-block-list=s
3705 This parameter is a list of block type keywords to which the flag
3706 -blbc should apply. The section "Specifying Block Types" explains
3707 how to list block types.
3708 Note on using the -blao and -blbc options.
3710 These blank line controls introduce a certain minimum number of
3711 blank lines in the text, but the final number of blank lines may be
3712 greater, depending on values of the other blank line controls and
3713 the number of old blank lines. A consequence is that introducing
3714 blank lines with these and other controls cannot be exactly undone,
3715 so some experimentation with these controls is recommended before
3716 using them.
3717 For example, suppose that for some reason we decide to introduce
3719 one blank space at the beginning and ending of all blocks. We
3720 could do this using
3721 perltidy -blao=2 -blbc=2 -blaol='*' -blbcl='*' filename
3723 Now suppose the script continues to be developed, but at some later
3725 date we decide we don't want these spaces after all. We might
3726 expect that running with the flags -blao=0 and -blbc=0 will undo
3727 them. However, by default perltidy retains single blank lines, so
3728 the blank lines remain.
3729 We can easily fix this by telling perltidy to ignore old blank
3731 lines by including the added parameter -kbl=0 and rerunning. Then
3732 the unwanted blank lines will be gone. However, this will cause
3733 all old blank lines to be ignored, perhaps even some that were
3734 added by hand to improve formatting. So please be cautious when
3735 using these parameters.
3736 -mbl=n --maximum-consecutive-blank-lines=n
3738 This parameter specifies the maximum number of consecutive blank
3739 lines which will be output within code sections of a script. The
3740 default is n=1. If the input file has more than n consecutive
3741 blank lines, the number will be reduced to n except as noted above
3742 for the -blbp and -blbs parameters. If n=0 then no blank lines
3743 will be output (unless all old blank lines are retained with the
3744 -kbl=2 flag of the next section).
3745 This flag obviously does not apply to pod sections, here-documents,
3747 and quotes.
3748 -kbl=n, --keep-old-blank-lines=n
3750 The -kbl=n flag gives you control over how your existing blank
3751 lines are treated.
3752 The possible values of n are:
3754 n=0 ignore all old blank lines
3756 n=1 stable: keep old blanks, but limited by the value of the B<-mbl=n> flag
3757 n=2 keep all old blank lines, regardless of the value of the B<-mbl=n> flag
3758 The default is n=1.
3760 -sob, --swallow-optional-blank-lines
3762 This is equivalent to kbl=0 and is included for compatibility with
3763 previous versions.
3764 -nsob, --noswallow-optional-blank-lines
3766 This is equivalent to kbl=1 and is included for compatibility with
3767 previous versions.
3768 Controls for blank lines around lines of consecutive keywords
3770 The parameters in this section provide some control over the placement
3772 of blank lines within and around groups of statements beginning with
3773 selected keywords. These blank lines are called here keyword group
3774 blanks, and all of the parameters begin with --keyword-group-blanks*,
3775 or -kgb* for short. The default settings do not employ these controls
3776 but they can be enabled with the following parameters:
3777 -kgbl=s or --keyword-group-blanks-list=s; s is a quoted string of
3779 keywords
3780 -kgbs=s or --keyword-group-blanks-size=s; s gives the number of
3782 keywords required to form a group.
3783 -kgbb=n or --keyword-group-blanks-before=n; n = (0, 1, or 2) controls a
3785 leading blank
3786 -kgba=n or --keyword-group-blanks-after=n; n = (0, 1, or 2) controls a
3788 trailing blank
3789 -kgbi or --keyword-group-blanks-inside is a switch for adding blanks
3791 between subgroups
3792 -kgbd or --keyword-group-blanks-delete is a switch for removing initial
3794 blank lines between keywords
3795 -kgbr=n or --keyword-group-blanks-repeat-count=n can limit the number
3797 of times this logic is applied
3798 In addition, the following abbreviations are available to for
3800 simplified usage:
3801 -kgb or --keyword-group-blanks is short for -kgbb=2 -kgba=2 kgbi
3803 -nkgb or --nokeyword-group-blanks, is short for -kgbb=1 -kgba=1 nkgbi
3805 Before describing the meaning of the parameters in detail let us look
3807 at an example which is formatted with default parameter settings.
3808 print "Entering test 2\n";
3810 use Test;
3811 use Encode qw(from_to encode decode
3812 encode_utf8 decode_utf8
3813 find_encoding is_utf8);
3814 use charnames qw(greek);
3815 my @encodings = grep( /iso-?8859/, Encode::encodings() );
3816 my @character_set = ( '0' .. '9', 'A' .. 'Z', 'a' .. 'z' );
3817 my @source = qw(ascii iso8859-1 cp1250);
3818 my @destiny = qw(cp1047 cp37 posix-bc);
3819 my @ebcdic_sets = qw(cp1047 cp37 posix-bc);
3820 my $str = join( '', map( chr($_), 0x20 .. 0x7E ) );
3821 return unless ($str);
3822 using perltidy -kgb gives:
3824 print "Entering test 2\n";
3826 <----------this blank controlled by -kgbb
3827 use Test;
3828 use Encode qw(from_to encode decode
3829 encode_utf8 decode_utf8
3830 find_encoding is_utf8);
3831 use charnames qw(greek);
3832 <---------this blank controlled by -kgbi
3833 my @encodings = grep( /iso-?8859/, Encode::encodings() );
3834 my @character_set = ( '0' .. '9', 'A' .. 'Z', 'a' .. 'z' );
3835 my @source = qw(ascii iso8859-1 cp1250);
3836 my @destiny = qw(cp1047 cp37 posix-bc);
3837 my @ebcdic_sets = qw(cp1047 cp37 posix-bc);
3838 my $str = join( '', map( chr($_), 0x20 .. 0x7E ) );
3839 <----------this blank controlled by -kgba
3840 return unless ($str);
3841 Blank lines have been introduced around the my and use sequences. What
3843 happened is that the default keyword list includes my and use but not
3844 print and return. So a continuous sequence of nine my and use
3845 statements was located. This number exceeds the default threshold of
3846 five, so blanks were placed before and after the entire group. Then,
3847 since there was also a subsequence of six my lines, a blank line was
3848 introduced to separate them.
3849 Finer control over blank placement can be achieved by using the
3851 individual parameters rather than the -kgb flag. The individual
3852 controls are as follows.
3853 -kgbl=s or --keyword-group-blanks-list=s, where s is a quoted string,
3855 defines the set of keywords which will be formed into groups. The
3856 string is a space separated list of keywords. The default set is
3857 s="use require local our my", but any list of keywords may be used.
3858 Comment lines may also be included in a keyword group, even though they
3859 are not keywords. To include ordinary block comments, include the
3860 symbol BC. To include static block comments (which normally begin with
3861 '##'), include the symbol SBC.
3862 -kgbs=s or --keyword-group-blanks-size=s, where s is a string
3864 describing the number of consecutive keyword statements forming a group
3865 (Note: statements separated by blank lines in the input file are
3866 considered consecutive for purposes of this count). If s is an integer
3867 then it is the minimum number required for a group. A maximum value
3868 may also be given with the format s=min.max, where min is the minimum
3869 number and max is the maximum number, and the min and max values are
3870 separated by one or more dots. No groups will be found if the maximum
3871 is less than the minimum. The maximum is unlimited if not given. The
3872 default is s=5. Some examples:
3873 s min max number for group
3875 3 3 unlimited 3 or more
3876 1.1 1 1 1
3877 1..3 1 3 1 to 3
3878 1.0 1 0 (no match)
3879 There is no really good default value for this parameter. If it is set
3881 too small, then an excessive number of blank lines may be generated.
3882 However, some users may prefer reducing the value somewhat below the
3883 default, perhaps to s=3.
3884 -kgbb=n or --keyword-group-blanks-before=n specifies whether a blank
3886 should appear before the first line of the group, as follows:
3887 n=0 => (delete) an existing blank line will be removed
3889 n=1 => (stable) no change to the input file is made [DEFAULT]
3890 n=2 => (insert) a blank line is introduced if possible
3891 -kgba=n or --keyword-group-blanks-after=n likewise specifies whether a
3893 blank should appear after the last line of the group, using the same
3894 scheme (0=delete, 1=stable, 2=insert).
3895 -kgbi or --keyword-group-blanks-inside controls the insertion of blank
3897 lines between the first and last statement of the entire group. If
3898 there is a continuous run of a single statement type with more than the
3899 minimum threshold number (as specified with -kgbs=s) then this switch
3900 causes a blank line be inserted between this subgroup and the others.
3901 In the example above this happened between the use and my statements.
3902 -kgbd or --keyword-group-blanks-delete controls the deletion of any
3904 blank lines that exist in the the group when it is first scanned. When
3905 statements are initially scanned, any existing blank lines are included
3906 in the collection. Any such original blank lines will be deleted
3907 before any other insertions are made when the parameter -kgbd is set.
3908 The default is not to do this, -nkgbd.
3909 -kgbr=n or --keyword-group-blanks-repeat-count=n specifies n, the
3911 maximum number of times this logic will be applied to any file. The
3912 special value n=0 is the same as n=infinity which means it will be
3913 applied to an entire script [Default]. A value n=1 could be used to
3914 make it apply just one time for example. This might be useful for
3915 adjusting just the use statements in the top part of a module for
3916 example.
3917 -kgb or --keyword-group-blanks is an abbreviation equivalent to setting
3919 -kgbb=1 -kgba=1 -kgbi. This turns on keyword group formatting with a
3920 set of default values.
3921 -nkgb or --nokeyword-group-blanks is equivalent to -kgbb=0 -kgba nkgbi.
3923 This flag turns off keyword group blank lines and is the default
3924 setting.
3925 Here are a few notes about the functioning of this technique.
3927 • These parameters are probably more useful as part of a major code
3929 reformatting operation rather than as a routine formatting
3930 operation.
3931 In particular, note that deleting old blank lines with -kgbd is an
3933 irreversible operation so it should be applied with care. Existing
3934 blank lines may be serving an important role in controlling
3935 vertical alignment.
3936 • Conflicts which arise among these kgb* parameters and other blank
3938 line controls are generally resolved by producing the maximum
3939 number of blank lines implied by any parameter.
3940 For example, if the flags --freeze-blank-lines, or
3942 --keep-old-blank-lines=2, are set, then they have priority over any
3943 blank line deletion implied by the -kgb flags of this section, so
3944 no blank lines will be deleted.
3945 For another example, if a keyword group ends at a sub and the flag
3947 kgba=0 requests no blank line there, but we also have
3948 --blank-lines-before-subs=2, then two blank lines will still be
3949 introduced before the sub.
3950 • The introduction of blank lines does not occur if it would conflict
3952 with other input controls or code validity. For example, a blank
3953 line will not be placed within a here-doc or within a section of
3954 code marked with format skipping comments. And in general, a blank
3955 line will only be introduced at the end of a group if the next
3956 statement is a line of code.
3957 • The count which is used to determine the group size is not the
3959 number of lines but rather the total number of keywords which are
3960 found. Individual statements with a certain leading keyword may
3961 continue on multiple lines, but if any of these lines is nested
3962 more than one level deep then that group will be ended.
3963 • The search for groups of lines with similar leading keywords is
3965 based on the input source, not the final formatted source.
3966 Consequently, if the source code is badly formatted, it would be
3967 best to make a first formatting pass without these options.
3968 Styles
3970 A style refers to a convenient collection of existing parameters.
3971 -gnu, --gnu-style
3973 -gnu gives an approximation to the GNU Coding Standards (which do
3974 not apply to perl) as they are sometimes implemented. At present,
3975 this style overrides the default style with the following
3976 parameters:
3977 -lp -bl -noll -pt=2 -bt=2 -sbt=2 -icp
3979 To use this style with -xlp instead of -lp use -gnu -xlp.
3981 -pbp, --perl-best-practices
3983 -pbp is an abbreviation for the parameters in the book Perl Best
3984 Practices by Damian Conway:
3985 -l=78 -i=4 -ci=4 -st -se -vt=2 -cti=0 -pt=1 -bt=1 -sbt=1 -bbt=1 -nsfs -nolq
3987 -wbb="% + - * / x != == >= <= =~ !~ < > | & =
3988 **= += *= &= <<= &&= -= /= |= >>= ||= //= .= %= ^= x="
3989 Please note that this parameter set includes -st and -se flags,
3991 which make perltidy act as a filter on one file only. These can be
3992 overridden by placing -nst and/or -nse after the -pbp parameter.
3993 Also note that the value of continuation indentation, -ci=4, is
3995 equal to the value of the full indentation, -i=4. It is
3996 recommended that the either (1) the parameter -ci=2 be used
3997 instead, or the flag -xci be set. This will help show structure,
3998 particularly when there are ternary statements. The following
3999 snippet illustrates these options.
4000 # perltidy -pbp
4002 $self->{_text} = (
4003 !$section ? ''
4004 : $type eq 'item' ? "the $section entry"
4005 : "the section on $section"
4006 )
4007 . (
4008 $page
4009 ? ( $section ? ' in ' : '' ) . "the $page$page_ext manpage"
4010 : ' elsewhere in this document'
4011 );
4012 # perltidy -pbp -ci=2
4014 $self->{_text} = (
4015 !$section ? ''
4016 : $type eq 'item' ? "the $section entry"
4017 : "the section on $section"
4018 )
4019 . (
4020 $page
4021 ? ( $section ? ' in ' : '' ) . "the $page$page_ext manpage"
4022 : ' elsewhere in this document'
4023 );
4024 # perltidy -pbp -xci
4026 $self->{_text} = (
4027 !$section ? ''
4028 : $type eq 'item' ? "the $section entry"
4029 : "the section on $section"
4030 )
4031 . ( $page
4032 ? ( $section ? ' in ' : '' ) . "the $page$page_ext manpage"
4033 : ' elsewhere in this document'
4034 );
4035 The -xci flag was developed after the -pbp parameters were
4037 published so you need to include it separately.
4038 One-line blocks
4040 There are a few points to note regarding one-line blocks. A one-
4041 line block is something like this,
4042 if ( -e $file ) { print "'$file' exists\n" }
4044 where the contents within the curly braces is short enough to fit
4046 on a single line.
4047 With few exceptions, perltidy retains existing one-line blocks, if
4049 it is possible within the line-length constraint, but it does not
4050 attempt to form new ones. In other words, perltidy will try to
4051 follow the one-line block style of the input file.
4052 If an existing one-line block is longer than the maximum line
4054 length, however, it will be broken into multiple lines. When this
4055 happens, perltidy checks for and adds any optional terminating
4056 semicolon (unless the -nasc option is used) if the block is a code
4057 block.
4058 The main exception is that perltidy will attempt to form new one-
4060 line blocks following the keywords "map", "eval", and "sort",
4061 because these code blocks are often small and most clearly
4062 displayed in a single line.
4063 One-line block rules can conflict with the cuddled-else option.
4065 When the cuddled-else option is used, perltidy retains existing
4066 one-line blocks, even if they do not obey cuddled-else formatting.
4067 Occasionally, when one-line blocks get broken because they exceed
4069 the available line length, the formatting will violate the
4070 requested brace style. If this happens, reformatting the script a
4071 second time should correct the problem.
4072 Sometimes it might be desirable to convert a script to have one-
4074 line blocks whenever possible. Although there is currently no flag
4075 for this, a simple workaround is to execute perltidy twice, once
4076 with the flag -noadd-newlines and then once again with normal
4077 parameters, like this:
4078 cat infile | perltidy -nanl | perltidy >outfile
4080 When executed on this snippet
4082 if ( $? == -1 ) {
4084 die "failed to execute: $!\n";
4085 }
4086 if ( $? == -1 ) {
4087 print "Had enough.\n";
4088 die "failed to execute: $!\n";
4089 }
4090 the result is
4092 if ( $? == -1 ) { die "failed to execute: $!\n"; }
4094 if ( $? == -1 ) {
4095 print "Had enough.\n";
4096 die "failed to execute: $!\n";
4097 }
4098 This shows that blocks with a single statement become one-line
4100 blocks.
4101 -olbs=n, --one-line-block-semicolons=n
4103 This flag controls the placement of semicolons at the end of one-
4104 line blocks. Semicolons are optional before a closing block brace,
4105 and frequently they are omitted at the end of a one-line block
4106 containing just a single statement. By default, perltidy follows
4107 the input file regarding these semicolons, but this behavior can be
4108 controlled by this flag. The values of n are:
4109 n=0 remove terminal semicolons in one-line blocks having a single statement
4111 n=1 stable; keep input file placement of terminal semicolons [DEFAULT ]
4112 n=2 add terminal semicolons in all one-line blocks
4113 Note that the n=2 option has no effect if adding semicolons is
4115 prohibited with the -nasc flag. Also not that while n=2 adds
4116 missing semicolons to all one-line blocks, regardless of
4117 complexity, the n=0 option only removes ending semicolons which
4118 terminate one-line blocks containing just one semicolon. So these
4119 two options are not exact inverses.
4120 -olbn=n, --one-line-block-nesting=n
4122 Nested one-line blocks are lines with code blocks which themselves
4123 contain code blocks. For example, the following line is a nested
4124 one-line block.
4125 foreach (@list) { if ($_ eq $asked_for) { last } ++$found }
4127 The default behavior is to break such lines into multiple lines,
4129 but this behavior can be controlled with this flag. The values of
4130 n are:
4131 n=0 break nested one-line blocks into multiple lines [DEFAULT]
4133 n=1 stable: keep existing nested-one line blocks intact
4134 For the above example, the default formatting (-olbn=0) is
4136 foreach (@list) {
4138 if ( $_ eq $asked_for ) { last }
4139 ++$found;
4140 }
4141 If the parameter -olbn=1 is given, then the line will be left
4143 intact if it is a single line in the source, or it will be broken
4144 into multiple lines if it is broken in multiple lines in the
4145 source.
4146 Controlling Vertical Alignment
4148 Vertical alignment refers to lining up certain symbols in a list of
4149 consecutive similar lines to improve readability. For example, the
4150 "fat commas" are aligned in the following statement:
4151 $data = $pkg->new(
4153 PeerAddr => join( ".", @port[ 0 .. 3 ] ),
4154 PeerPort => $port[4] * 256 + $port[5],
4155 Proto => 'tcp'
4156 );
4157 Vertical alignment can be completely turned off using the -novalign
4159 flag mentioned below. However, vertical alignment can be forced to
4160 stop and restart by selectively introducing blank lines. For example,
4161 a blank has been inserted in the following code to keep somewhat
4162 similar things aligned.
4163 %option_range = (
4165 'format' => [ 'tidy', 'html', 'user' ],
4166 'output-line-ending' => [ 'dos', 'win', 'mac', 'unix' ],
4167 'character-encoding' => [ 'none', 'utf8' ],
4168 'block-brace-tightness' => [ 0, 2 ],
4170 'brace-tightness' => [ 0, 2 ],
4171 'paren-tightness' => [ 0, 2 ],
4172 'square-bracket-tightness' => [ 0, 2 ],
4173 );
4174 Vertical alignment is implemented by locally increasing an existing
4176 blank space to produce alignment with an adjacent line. It cannot
4177 occur if there is no blank space to increase. So if a particular space
4178 is removed by one of the existing controls then vertical alignment
4179 cannot occur. Likewise, if a space is added with one of the controls,
4180 then vertical alignment might occur.
4181 For example,
4183 # perltidy -nwls='=>'
4185 $data = $pkg->new(
4186 PeerAddr=> join( ".", @port[ 0 .. 3 ] ),
4187 PeerPort=> $port[4] * 256 + $port[5],
4188 Proto=> 'tcp'
4189 );
4190 Completely turning off vertical alignment with -novalign
4192 The default is to use vertical alignment, but vertical alignment
4193 can be completely turned of with the -novalign flag.
4194 A lower level of control of vertical alignment is possible with
4196 three parameters -vc, -vsc, and -vbc. These independently control
4197 alignment of code, side comments and block comments. They are
4198 described in the next section.
4199 The parameter -valign is in fact an alias for -vc -vsc -vbc, and
4201 its negative -novalign is an alias for -nvc -nvsc -nvbc.
4202 Controlling code alignment with --valign-code or -vc
4204 The -vc flag enables alignment of code symbols such as =. The
4205 default is -vc. For detailed control of which symbols to align,
4206 see the -valign-exclude-list parameter below.
4207 Controlling side comment alignment with --valign-side-comments or -vsc
4209 The -vsc flag enables alignment of side comments and is enabled by
4210 default. If side comment alignment is disabled with -nvsc they
4211 will appear at a fixed space from the preceding code token. The
4212 default is -vsc
4213 Controlling block comment alignment with --valign-block-comments or
4215 -vbc
4216 When -vbc is enabled, block comments can become aligned for example
4217 if one comment of a consecutive sequence of comments becomes
4218 outdented due a length in excess of the maximum line length. If
4219 this occurs, the entire group of comments will remain aligned and
4220 be outdented by the same amount. This coordinated alignment will
4221 not occur if -nvbc is set. The default is -vbc.
4222 Finer alignment control with --valign-exclusion-list=s or -vxl=s and
4224 --valign-inclusion-list=s or -vil=s
4225 More detailed control of alignment types is available with these
4226 two parameters. Most of the vertical alignments in typical
4227 programs occur at one of the tokens ',', '=', and '=>', but many
4228 other alignments are possible and are given in the following list:
4229 = **= += *= &= <<= &&= -= /= |= >>= ||= //= .= %= ^= x=
4231 { ( ? : , ; => && || ~~ !~~ =~ !~ // <=> -> q
4232 if unless and or err for foreach while until
4233 These alignment types correspond to perl symbols, operators and
4235 keywords except for 'q', which refers to the special case of
4236 alignment in a 'use' statement of qw quotes and empty parens.
4237 They are all enabled by default, but they can be selectively
4239 disabled by including one or more of these tokens in the space-
4240 separated list valign-exclusion-list=s. For example, the following
4241 would prevent alignment at = and if:
4242 --valign-exclusion-list='= if'
4244 If it is simpler to specify only the token types which are to be
4246 aligned, then include the types which are to be aligned in the list
4247 of --valign-inclusion-list. In that case you may leave the valign-
4248 exclusion-list undefined, or use the special symbol * for the
4249 exclusion list. For example, the following parameters enable
4250 alignment only at commas and 'fat commas':
4251 --valign-inclusion-list=', =>'
4253 --valign-exclusion-list='*' ( this is optional and may be omitted )
4254 These parameter lists should consist of space-separated tokens from
4256 the above list of possible alignment tokens, or a '*'. If an
4257 unrecognized token appears, it is simply ignored. And if a specific
4258 token is entered in both lists by mistake then the exclusion list
4259 has priority.
4260 The default values of these parameters enable all alignments and
4262 are equivalent to
4263 --valign-exclusion-list=' '
4265 --valign-inclusion-list='*'
4266 To illustrate, consider the following snippet with default
4268 formatting
4269 # perltidy
4271 $co_description = ($color) ? 'bold cyan' : ''; # description
4272 $co_prompt = ($color) ? 'bold green' : ''; # prompt
4273 $co_unused = ($color) ? 'on_green' : 'reverse'; # unused
4274 To exclude all alignments except the equals (i.e., include only
4276 equals) we could use:
4277 # perltidy -vil='='
4279 $co_description = ($color) ? 'bold cyan' : ''; # description
4280 $co_prompt = ($color) ? 'bold green' : ''; # prompt
4281 $co_unused = ($color) ? 'on_green' : 'reverse'; # unused
4282 To exclude only the equals we could use:
4284 # perltidy -vxl='='
4286 $co_description = ($color) ? 'bold cyan' : ''; # description
4287 $co_prompt = ($color) ? 'bold green' : ''; # prompt
4288 $co_unused = ($color) ? 'on_green' : 'reverse'; # unused
4289 Notice in this last example that although only the equals alignment
4291 was excluded, the ternary alignments were also lost. This happens
4292 because the vertical aligner sweeps from left-to-right and usually
4293 stops if an important alignment cannot be made for some reason.
4294 But also notice that side comments remain aligned because their
4296 alignment is controlled separately with the parameter
4297 --valign-side_comments described above.
4298 Other Controls
4300 Deleting selected text
4301 Perltidy can selectively delete comments and/or pod documentation.
4302 The command -dac or --delete-all-comments will delete all comments
4303 and all pod documentation, leaving just code and any leading system
4304 control lines.
4305 The command -dp or --delete-pod will remove all pod documentation
4307 (but not comments).
4308 Two commands which remove comments (but not pod) are: -dbc or
4310 --delete-block-comments and -dsc or --delete-side-comments.
4311 (Hanging side comments will be deleted with side comments here.)
4312 When side comments are deleted, any special control side comments
4314 for non-indenting braces will be retained unless they are
4315 deactivated with a -nnib flag.
4316 The negatives of these commands also work, and are the defaults.
4318 When block comments are deleted, any leading 'hash-bang' will be
4319 retained. Also, if the -x flag is used, any system commands before
4320 a leading hash-bang will be retained (even if they are in the form
4321 of comments).
4322 Writing selected text to a file
4324 When perltidy writes a formatted text file, it has the ability to
4325 also send selected text to a file with a .TEE extension. This text
4326 can include comments and pod documentation.
4327 The command -tac or --tee-all-comments will write all comments and
4329 all pod documentation.
4330 The command -tp or --tee-pod will write all pod documentation (but
4332 not comments).
4333 The commands which write comments (but not pod) are: -tbc or
4335 --tee-block-comments and -tsc or --tee-side-comments. (Hanging
4336 side comments will be written with side comments here.)
4337 The negatives of these commands also work, and are the defaults.
4339 Using a .perltidyrc command file
4341 If you use perltidy frequently, you probably won't be happy until
4342 you create a .perltidyrc file to avoid typing commonly-used
4343 parameters. Perltidy will first look in your current directory for
4344 a command file named .perltidyrc. If it does not find one, it will
4345 continue looking for one in other standard locations.
4346 These other locations are system-dependent, and may be displayed
4348 with the command "perltidy -dpro". Under Unix systems, it will
4349 first look for an environment variable PERLTIDY. Then it will look
4350 for a .perltidyrc file in the home directory, and then for a
4351 system-wide file /usr/local/etc/perltidyrc, and then it will look
4352 for /etc/perltidyrc. Note that these last two system-wide files do
4353 not have a leading dot. Further system-dependent information will
4354 be found in the INSTALL file distributed with perltidy.
4355 Under Windows, perltidy will also search for a configuration file
4357 named perltidy.ini since Windows does not allow files with a
4358 leading period (.). Use "perltidy -dpro" to see the possible
4359 locations for your system. An example might be C:\Documents and
4360 Settings\All Users\perltidy.ini.
4361 Another option is the use of the PERLTIDY environment variable.
4363 The method for setting environment variables depends upon the
4364 version of Windows that you are using. Instructions for Windows 95
4365 and later versions can be found here:
4366 http://www.netmanage.com/000/20021101_005_tcm21-6336.pdf
4368 Under Windows NT / 2000 / XP the PERLTIDY environment variable can
4370 be placed in either the user section or the system section. The
4371 later makes the configuration file common to all users on the
4372 machine. Be sure to enter the full path of the configuration file
4373 in the value of the environment variable. Ex.
4374 PERLTIDY=C:\Documents and Settings\perltidy.ini
4375 The configuration file is free format, and simply a list of
4377 parameters, just as they would be entered on a command line. Any
4378 number of lines may be used, with any number of parameters per
4379 line, although it may be easiest to read with one parameter per
4380 line. Comment text begins with a #, and there must also be a space
4381 before the # for side comments. It is a good idea to put complex
4382 parameters in either single or double quotes.
4383 Here is an example of a .perltidyrc file:
4385 # This is a simple of a .perltidyrc configuration file
4387 # This implements a highly spaced style
4388 -se # errors to standard error output
4389 -w # show all warnings
4390 -bl # braces on new lines
4391 -pt=0 # parens not tight at all
4392 -bt=0 # braces not tight
4393 -sbt=0 # square brackets not tight
4394 The parameters in the .perltidyrc file are installed first, so any
4396 parameters given on the command line will have priority over them.
4397 To avoid confusion, perltidy ignores any command in the .perltidyrc
4399 file which would cause some kind of dump and an exit. These are:
4400 -h -v -ddf -dln -dop -dsn -dtt -dwls -dwrs -ss
4402 There are several options may be helpful in debugging a .perltidyrc
4404 file:
4405 • A very helpful command is --dump-profile or -dpro. It writes a
4407 list of all configuration filenames tested to standard output,
4408 and if a file is found, it dumps the content to standard output
4409 before exiting. So, to find out where perltidy looks for its
4410 configuration files, and which one if any it selects, just
4411 enter
4412 perltidy -dpro
4414 • It may be simplest to develop and test configuration files with
4416 alternative names, and invoke them with -pro=filename on the
4417 command line. Then rename the desired file to .perltidyrc when
4418 finished.
4419 • The parameters in the .perltidyrc file can be switched off with
4421 the -npro option.
4422 • The commands --dump-options, --dump-defaults,
4424 --dump-long-names, and --dump-short-names, all described below,
4425 may all be helpful.
4426 Creating a new abbreviation
4428 A special notation is available for use in a .perltidyrc file for
4429 creating an abbreviation for a group of options. This can be used
4430 to create a shorthand for one or more styles which are frequently,
4431 but not always, used. The notation is to group the options within
4432 curly braces which are preceded by the name of the alias (without
4433 leading dashes), like this:
4434 newword {
4436 -opt1
4437 -opt2
4438 }
4439 where newword is the abbreviation, and opt1, etc, are existing
4441 parameters or other abbreviations. The main syntax requirement is
4442 that the new abbreviation along with its opening curly brace must
4443 begin on a new line. Space before and after the curly braces is
4444 optional.
4445 For a specific example, the following line
4447 oneliner { --maximum-line-length=0 --noadd-newlines --noadd-terminal-newline}
4449 or equivalently with abbreviations
4451 oneliner { -l=0 -nanl -natnl }
4453 could be placed in a .perltidyrc file to temporarily override the
4455 maximum line length with a large value, to temporarily prevent new
4456 line breaks from being added, and to prevent an extra newline
4457 character from being added the file. All other settings in the
4458 .perltidyrc file still apply. Thus it provides a way to format a
4459 long 'one liner' when perltidy is invoked with
4460 perltidy --oneliner ...
4462 (Either "-oneliner" or "--oneliner" may be used).
4464 Skipping leading non-perl commands with -x or --look-for-hash-bang
4466 If your script has leading lines of system commands or other text
4467 which are not valid perl code, and which are separated from the
4468 start of the perl code by a "hash-bang" line, ( a line of the form
4469 "#!...perl" ), you must use the -x flag to tell perltidy not to
4470 parse and format any lines before the "hash-bang" line. This
4471 option also invokes perl with a -x flag when checking the syntax.
4472 This option was originally added to allow perltidy to parse
4473 interactive VMS scripts, but it should be used for any script which
4474 is normally invoked with "perl -x".
4475 Please note: do not use this flag unless you are sure your script
4477 needs it. Parsing errors can occur if it does not have a hash-
4478 bang, or, for example, if the actual first hash-bang is in a here-
4479 doc. In that case a parsing error will occur because the
4480 tokenization will begin in the middle of the here-doc.
4481 Making a file unreadable
4483 The goal of perltidy is to improve the readability of files, but
4484 there are two commands which have the opposite effect, --mangle and
4485 --extrude. They are actually merely aliases for combinations of
4486 other parameters. Both of these strip all possible whitespace, but
4487 leave comments and pod documents, so that they are essentially
4488 reversible. The difference between these is that --mangle puts the
4489 fewest possible line breaks in a script while --extrude puts the
4490 maximum possible. Note that these options do not provided any
4491 meaningful obfuscation, because perltidy can be used to reformat
4492 the files. They were originally developed to help test the
4493 tokenization logic of perltidy, but they have other uses. One use
4494 for --mangle is the following:
4495 perltidy --mangle myfile.pl -st | perltidy -o myfile.pl.new
4497 This will form the maximum possible number of one-line blocks (see
4499 next section), and can sometimes help clean up a badly formatted
4500 script.
4501 A similar technique can be used with --extrude instead of --mangle
4503 to make the minimum number of one-line blocks.
4504 Another use for --mangle is to combine it with -dac to reduce the
4506 file size of a perl script.
4507 Debugging
4509 The following flags are available for debugging:
4510 --dump-cuddled-block-list or -dcbl will dump to standard output the
4512 internal hash of cuddled block types created by a
4513 -cuddled-block-list input string.
4514 --dump-defaults or -ddf will write the default option set to
4516 standard output and quit
4517 --dump-profile or -dpro will write the name of the current
4519 configuration file and its contents to standard output and quit.
4520 --dump-options or -dop will write current option set to standard
4522 output and quit.
4523 --dump-long-names or -dln will write all command line long names
4525 (passed to Get_options) to standard output and quit.
4526 --dump-short-names or -dsn will write all command line short names
4528 to standard output and quit.
4529 --dump-token-types or -dtt will write a list of all token types to
4531 standard output and quit.
4532 --dump-want-left-space or -dwls will write the hash
4534 %want_left_space to standard output and quit. See the section on
4535 controlling whitespace around tokens.
4536 --dump-want-right-space or -dwrs will write the hash
4538 %want_right_space to standard output and quit. See the section on
4539 controlling whitespace around tokens.
4540 --no-memoize or -nmem will turn of memoizing. Memoization can
4542 reduce run time when running perltidy repeatedly in a single
4543 process. It is on by default but can be deactivated for testing
4544 with -nmem.
4545 --no-timestamp or -nts will eliminate any time stamps in output
4547 files to prevent differences in dates from causing test
4548 installation scripts to fail. There are just a couple of places
4549 where timestamps normally occur. One is in the headers of html
4550 files, and another is when the -cscw option is selected. The
4551 default is to allow timestamps (--timestamp or -ts).
4552 --file-size-order or -fso will cause files to be processed in order
4554 of increasing size, when multiple files are being processed. This
4555 is useful during program development, when large numbers of files
4556 with varying sizes are processed, because it can reduce virtual
4557 memory usage.
4558 --maximum-file-size-mb=n or -maxfs=n specifies the maximum file
4560 size in megabytes that perltidy will attempt to format. This
4561 parameter is provided to avoid causing system problems by
4562 accidentally attempting to format an extremely large data file.
4563 Most perl scripts are less than about 2 MB in size. The integer n
4564 has a default value of 10, so perltidy will skip formatting files
4565 which have a size greater than 10 MB. The command to increase the
4566 limit to 20 MB for example would be
4567 perltidy -maxfs=20
4569 This only applies to files specified by filename on the command
4571 line.
4572 --maximum-level-errors=n or -maxle=n specifies the maximum number
4574 of indentation level errors are allowed before perltidy skips
4575 formatting and just outputs a file verbatim. The default is n=1.
4576 This means that if the final indentation of a script differs from
4577 the starting indentation by more than 1 levels, the file will be
4578 output verbatim. To avoid formatting if there are any indentation
4579 level errors use -maxle=0. To skip this check you can either set n
4580 equal to a large number, such as n=100, or set n=-1.
4581 For example, the following script has level error of 3 and will be
4583 output verbatim
4584 Input and default output:
4586 {{{
4587 perltidy -maxle=100
4590 {
4591 {
4592 {
4593 --maximum-unexpected-errors=n or -maxue=n specifies the maximum
4595 number of unexpected tokenization errors are allowed before
4596 formatting is skipped and a script is output verbatim. The
4597 intention is to avoid accidentally formatting a non-perl script,
4598 such as an html file for example. This check can be turned off by
4599 setting n=0.
4600 A recommended value is n=3. However, the default is n=0 (skip this
4602 check) to avoid causing problems with scripts which have extended
4603 syntaxes.
4604 -DEBUG will write a file with extension .DEBUG for each input file
4606 showing the tokenization of all lines of code.
4607 Working with MakeMaker, AutoLoader and SelfLoader
4609 The first $VERSION line of a file which might be eval'd by
4610 MakeMaker is passed through unchanged except for indentation. Use
4611 --nopass-version-line, or -npvl, to deactivate this feature.
4612 If the AutoLoader module is used, perltidy will continue formatting
4614 code after seeing an __END__ line. Use --nolook-for-autoloader, or
4615 -nlal, to deactivate this feature.
4616 Likewise, if the SelfLoader module is used, perltidy will continue
4618 formatting code after seeing a __DATA__ line. Use
4619 --nolook-for-selfloader, or -nlsl, to deactivate this feature.
4620 Working around problems with older version of Perl
4622 Perltidy contains a number of rules which help avoid known
4623 subtleties and problems with older versions of perl, and these
4624 rules always take priority over whatever formatting flags have been
4625 set. For example, perltidy will usually avoid starting a new line
4626 with a bareword, because this might cause problems if "use strict"
4627 is active.
4628 There is no way to override these rules.
4630
4632 The -html master switch
4633 The flag -html causes perltidy to write an html file with extension
4634 .html. So, for example, the following command
4635 perltidy -html somefile.pl
4637 will produce a syntax-colored html file named somefile.pl.html
4639 which may be viewed with a browser.
4640 Please Note: In this case, perltidy does not do any formatting to
4642 the input file, and it does not write a formatted file with
4643 extension .tdy. This means that two perltidy runs are required to
4644 create a fully reformatted, html copy of a script.
4645 The -pre flag for code snippets
4647 When the -pre flag is given, only the pre-formatted section, within
4648 the <PRE> and </PRE> tags, will be output. This simplifies
4649 inclusion of the output in other files. The default is to output a
4650 complete web page.
4651 The -nnn flag for line numbering
4653 When the -nnn flag is given, the output lines will be numbered.
4654 The -toc, or --html-table-of-contents flag
4656 By default, a table of contents to packages and subroutines will be
4657 written at the start of html output. Use -ntoc to prevent this.
4658 This might be useful, for example, for a pod document which
4659 contains a number of unrelated code snippets. This flag only
4660 influences the code table of contents; it has no effect on any
4661 table of contents produced by pod2html (see next item).
4662 The -pod, or --pod2html flag
4664 There are two options for formatting pod documentation. The
4665 default is to pass the pod through the Pod::Html module (which
4666 forms the basis of the pod2html utility). Any code sections are
4667 formatted by perltidy, and the results then merged. Note: perltidy
4668 creates a temporary file when Pod::Html is used; see "FILES".
4669 Also, Pod::Html creates temporary files for its cache.
4670 NOTE: Perltidy counts the number of "=cut" lines, and either moves
4672 the pod text to the top of the html file if there is one "=cut", or
4673 leaves the pod text in its original order (interleaved with code)
4674 otherwise.
4675 Most of the flags accepted by pod2html may be included in the
4677 perltidy command line, and they will be passed to pod2html. In
4678 some cases, the flags have a prefix "pod" to emphasize that they
4679 are for the pod2html, and this prefix will be removed before they
4680 are passed to pod2html. The flags which have the additional "pod"
4681 prefix are:
4682 --[no]podheader --[no]podindex --[no]podrecurse --[no]podquiet
4684 --[no]podverbose --podflush
4685 The flags which are unchanged from their use in pod2html are:
4687 --backlink=s --cachedir=s --htmlroot=s --libpods=s --title=s
4689 --podpath=s --podroot=s
4690 where 's' is an appropriate character string. Not all of these
4692 flags are available in older versions of Pod::Html. See your
4693 Pod::Html documentation for more information.
4694 The alternative, indicated with -npod, is not to use Pod::Html, but
4696 rather to format pod text in italics (or whatever the stylesheet
4697 indicates), without special html markup. This is useful, for
4698 example, if pod is being used as an alternative way to write
4699 comments.
4700 The -frm, or --frames flag
4702 By default, a single html output file is produced. This can be
4703 changed with the -frm option, which creates a frame holding a table
4704 of contents in the left panel and the source code in the right
4705 side. This simplifies code browsing. Assume, for example, that the
4706 input file is MyModule.pm. Then, for default file extension
4707 choices, these three files will be created:
4708 MyModule.pm.html - the frame
4710 MyModule.pm.toc.html - the table of contents
4711 MyModule.pm.src.html - the formatted source code
4712 Obviously this file naming scheme requires that output be directed
4714 to a real file (as opposed to, say, standard output). If this is
4715 not the case, or if the file extension is unknown, the -frm option
4716 will be ignored.
4717 The -text=s, or --html-toc-extension flag
4719 Use this flag to specify the extra file extension of the table of
4720 contents file when html frames are used. The default is "toc".
4721 See "Specifying File Extensions".
4722 The -sext=s, or --html-src-extension flag
4724 Use this flag to specify the extra file extension of the content
4725 file when html frames are used. The default is "src". See
4726 "Specifying File Extensions".
4727 The -hent, or --html-entities flag
4729 This flag controls the use of Html::Entities for html formatting.
4730 By default, the module Html::Entities is used to encode special
4731 symbols. This may not be the right thing for some browser/language
4732 combinations. Use --nohtml-entities or -nhent to prevent this.
4733 Style Sheets
4735 Style sheets make it very convenient to control and adjust the
4736 appearance of html pages. The default behavior is to write a page
4737 of html with an embedded style sheet.
4738 An alternative to an embedded style sheet is to create a page with
4740 a link to an external style sheet. This is indicated with the
4741 -css=filename, where the external style sheet is filename. The
4742 external style sheet filename will be created if and only if it
4743 does not exist. This option is useful for controlling multiple
4744 pages from a single style sheet.
4745 To cause perltidy to write a style sheet to standard output and
4747 exit, use the -ss, or --stylesheet, flag. This is useful if the
4748 style sheet could not be written for some reason, such as if the
4749 -pre flag was used. Thus, for example,
4750 perltidy -html -ss >mystyle.css
4752 will write a style sheet with the default properties to file
4754 mystyle.css.
4755 The use of style sheets is encouraged, but a web page without a
4757 style sheets can be created with the flag -nss. Use this option if
4758 you must to be sure that older browsers (roughly speaking, versions
4759 prior to 4.0 of Netscape Navigator and Internet Explorer) can
4760 display the syntax-coloring of the html files.
4761 Controlling HTML properties
4763 Note: It is usually more convenient to accept the default
4764 properties and then edit the stylesheet which is produced.
4765 However, this section shows how to control the properties with
4766 flags to perltidy.
4767 Syntax colors may be changed from their default values by flags of
4769 the either the long form, -html-color-xxxxxx=n, or more
4770 conveniently the short form, -hcx=n, where xxxxxx is one of the
4771 following words, and x is the corresponding abbreviation:
4772 Token Type xxxxxx x
4774 ---------- -------- --
4775 comment comment c
4776 number numeric n
4777 identifier identifier i
4778 bareword, function bareword w
4779 keyword keyword k
4780 quite, pattern quote q
4781 here doc text here-doc-text h
4782 here doc target here-doc-target hh
4783 punctuation punctuation pu
4784 parentheses paren p
4785 structural braces structure s
4786 semicolon semicolon sc
4787 colon colon co
4788 comma comma cm
4789 label label j
4790 sub definition name subroutine m
4791 pod text pod-text pd
4792 A default set of colors has been defined, but they may be changed
4794 by providing values to any of the following parameters, where n is
4795 either a 6 digit hex RGB color value or an ascii name for a color,
4796 such as 'red'.
4797 To illustrate, the following command will produce an html file
4799 somefile.pl.html with "aqua" keywords:
4800 perltidy -html -hck=00ffff somefile.pl
4802 and this should be equivalent for most browsers:
4804 perltidy -html -hck=aqua somefile.pl
4806 Perltidy merely writes any non-hex names that it sees in the html
4808 file. The following 16 color names are defined in the HTML 3.2
4809 standard:
4810 black => 000000,
4812 silver => c0c0c0,
4813 gray => 808080,
4814 white => ffffff,
4815 maroon => 800000,
4816 red => ff0000,
4817 purple => 800080,
4818 fuchsia => ff00ff,
4819 green => 008000,
4820 lime => 00ff00,
4821 olive => 808000,
4822 yellow => ffff00
4823 navy => 000080,
4824 blue => 0000ff,
4825 teal => 008080,
4826 aqua => 00ffff,
4827 Many more names are supported in specific browsers, but it is
4829 safest to use the hex codes for other colors. Helpful color tables
4830 can be located with an internet search for "HTML color tables".
4831 Besides color, two other character attributes may be set: bold, and
4833 italics. To set a token type to use bold, use the flag
4834 --html-bold-xxxxxx or -hbx, where xxxxxx or x are the long or short
4835 names from the above table. Conversely, to set a token type to NOT
4836 use bold, use --nohtml-bold-xxxxxx or -nhbx.
4837 Likewise, to set a token type to use an italic font, use the flag
4839 --html-italic-xxxxxx or -hix, where again xxxxxx or x are the long
4840 or short names from the above table. And to set a token type to
4841 NOT use italics, use --nohtml-italic-xxxxxx or -nhix.
4842 For example, to use bold braces and lime color, non-bold, italics
4844 keywords the following command would be used:
4845 perltidy -html -hbs -hck=00FF00 -nhbk -hik somefile.pl
4847 The background color can be specified with
4849 --html-color-background=n, or -hcbg=n for short, where n is a 6
4850 character hex RGB value. The default color of text is the value
4851 given to punctuation, which is black as a default.
4852 Here are some notes and hints:
4854 1. If you find a preferred set of these parameters, you may want to
4856 create a .perltidyrc file containing them. See the perltidy man
4857 page for an explanation.
4858 2. Rather than specifying values for these parameters, it is
4860 probably easier to accept the defaults and then edit a style sheet.
4861 The style sheet contains comments which should make this easy.
4862 3. The syntax-colored html files can be very large, so it may be
4864 best to split large files into smaller pieces to improve download
4865 times.
4866
4868 Specifying Block Types
4869 Several parameters which refer to code block types may be customized by
4870 also specifying an associated list of block types. The type of a block
4871 is the name of the keyword which introduces that block, such as if,
4872 else, or sub. An exception is a labeled block, which has no keyword,
4873 and should be specified with just a colon. To specify all blocks use
4874 '*'.
4875 The keyword sub indicates a named sub. For anonymous subs, use the
4877 special keyword asub.
4878 For example, the following parameter specifies "sub", labels, "BEGIN",
4880 and "END" blocks:
4881 -cscl="sub : BEGIN END"
4883 (the meaning of the -cscl parameter is described above.) Note that
4885 quotes are required around the list of block types because of the
4886 spaces. For another example, the following list specifies all block
4887 types for vertical tightness:
4888 -bbvtl='*'
4890 Specifying File Extensions
4892 Several parameters allow default file extensions to be overridden. For
4893 example, a backup file extension may be specified with -bext=ext, where
4894 ext is some new extension. In order to provides the user some
4895 flexibility, the following convention is used in all cases to decide if
4896 a leading '.' should be used. If the extension "ext" begins with
4897 "A-Z", "a-z", or "0-9", then it will be appended to the filename with
4898 an intermediate '.' (or perhaps a '_' on VMS systems). Otherwise, it
4899 will be appended directly.
4900 For example, suppose the file is somefile.pl. For "-bext=old", a '.'
4902 is added to give somefile.pl.old. For "-bext=.old", no additional '.'
4903 is added, so again the backup file is somefile.pl.old. For "-bext=~",
4904 then no dot is added, and the backup file will be somefile.pl~ .
4905
4907 The following list shows all short parameter names which allow a prefix
4908 'n' to produce the negated form:
4909 D anl asbl asc ast asu atnl aws b baa
4911 baao bar bbao bbb bbc bbs bl bli boa boc
4912 bok bol bom bos bot cblx ce conv cs csc
4913 cscb cscw dac dbc dcbl dcsc ddf dln dnl dop
4914 dp dpro dsc dsm dsn dtt dwls dwrs dws eos
4915 f fll fpva frm fs fso gcs hbc hbcm hbco
4916 hbh hbhh hbi hbj hbk hbm hbn hbp hbpd hbpu
4917 hbq hbs hbsc hbv hbw hent hic hicm hico hih
4918 hihh hii hij hik him hin hip hipd hipu hiq
4919 his hisc hiv hiw hsc html ibc icb icp iob
4920 isbc iscl kgb kgbd kgbi kis lal log lop lp
4921 lsl mem nib ohbr okw ola olc oll olq opr
4922 opt osbc osbr otr ple pod pvl q sac sbc
4923 sbl scbb schb scp scsb sct se sfp sfs skp
4924 sob sobb sohb sop sosb sot ssc st sts t
4925 tac tbc toc tp tqw trp ts tsc tso vbc
4926 vc vmll vsc w wn x xci xlp xs
4927 Equivalently, the prefix 'no' or 'no-' on the corresponding long names
4929 may be used.
4930
4932 Parsing Limitations
4933 Perltidy should work properly on most perl scripts. It does a lot
4934 of self-checking, but still, it is possible that an error could be
4935 introduced and go undetected. Therefore, it is essential to make
4936 careful backups and to test reformatted scripts.
4937 The main current limitation is that perltidy does not scan modules
4939 included with 'use' statements. This makes it necessary to guess
4940 the context of any bare words introduced by such modules. Perltidy
4941 has good guessing algorithms, but they are not infallible. When it
4942 must guess, it leaves a message in the log file.
4943 If you encounter a bug, please report it.
4945 What perltidy does not parse and format
4947 Perltidy indents but does not reformat comments and "qw" quotes.
4948 Perltidy does not in any way modify the contents of here documents
4949 or quoted text, even if they contain source code. (You could,
4950 however, reformat them separately). Perltidy does not format
4951 'format' sections in any way. And, of course, it does not modify
4952 pod documents.
4953
4955 Temporary files
4956 Under the -html option with the default --pod2html flag, a
4957 temporary file is required to pass text to Pod::Html. Unix systems
4958 will try to use the POSIX tmpnam() function. Otherwise the file
4959 perltidy.TMP will be temporarily created in the current working
4960 directory.
4961 Special files when standard input is used
4963 When standard input is used, the log file, if saved, is
4964 perltidy.LOG, and any errors are written to perltidy.ERR unless the
4965 -se flag is set. These are saved in the current working directory.
4966 Files overwritten
4968 The following file extensions are used by perltidy, and files with
4969 these extensions may be overwritten or deleted: .ERR, .LOG, .TEE,
4970 and/or .tdy, .html, and .bak, depending on the run type and
4971 settings.
4972 Files extensions limitations
4974 Perltidy does not operate on files for which the run could produce
4975 a file with a duplicated file extension. These extensions include
4976 .LOG, .ERR, .TEE, and perhaps .tdy and .bak, depending on the run
4977 type. The purpose of this rule is to prevent generating confusing
4978 filenames such as somefile.tdy.tdy.tdy.
4979
4981 An exit value of 0, 1, or 2 is returned by perltidy to indicate the
4982 status of the result.
4983 A exit value of 0 indicates that perltidy ran to completion with no
4985 error messages.
4986 A non-zero exit value indicates some kind of problem was detected.
4988 An exit value of 1 indicates that perltidy terminated prematurely,
4990 usually due to some kind of errors in the input parameters. This can
4991 happen for example if a parameter is misspelled or given an invalid
4992 value. Error messages in the standard error output will indicate the
4993 cause of any problem. If perltidy terminates prematurely then no
4994 output files will be produced.
4995 An exit value of 2 indicates that perltidy was able to run to
4997 completion but there there are (1) warning messages in the standard
4998 error output related to parameter errors or problems and/or (2) warning
4999 messages in the perltidy error file(s) relating to possible syntax
5000 errors in one or more of the source script(s) being tidied. When
5001 multiple files are being processed, an error detected in any single
5002 file will produce this type of exit condition.
5003
5005 perlstyle(1), Perl::Tidy(3)
5006
5008 The perltidy binary uses the Perl::Tidy module and is installed when
5009 that module is installed. The module name is case-sensitive. For
5010 example, the basic command for installing with cpanm is 'cpanm
5011 Perl::Tidy'.
5012
5014 This man page documents perltidy version 20220613
5015
5017 The source code repository is at
5018 <https://github.com/perltidy/perltidy>.
5019 To report a new bug or problem, use the "issues" link on this page.
5021
5023 Copyright (c) 2000-2022 by Steve Hancock
5024
5026 This package is free software; you can redistribute it and/or modify it
5027 under the terms of the "GNU General Public License".
5028 Please refer to the file "COPYING" for details.
5030
5032 This package is distributed in the hope that it will be useful, but
5033 WITHOUT ANY WARRANTY; without even the implied warranty of
5034 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
5035 See the "GNU General Public License" for more details.
5037perl v5.36.0 2022-07-22 PERLTIDY(1)