1PERLTIDY(1) User Contributed Perl Documentation PERLTIDY(1)
2
6 perltidy - a perl script indenter and reformatter
7
9 perltidy [ options ] file1 file2 file3 ...
10 (output goes to file1.tdy, file2.tdy, file3.tdy, ...)
11 perltidy [ options ] file1 -o outfile
12 perltidy [ options ] file1 -st >outfile
13 perltidy [ options ] <infile >outfile
14
16 Perltidy reads a perl script and writes an indented, reformatted
17 script.
18 Many users will find enough information in "EXAMPLES" to get started.
20 New users may benefit from the short tutorial which can be found at
21 http://perltidy.sourceforge.net/tutorial.html
22 A convenient aid to systematically defining a set of style parameters
24 can be found at http://perltidy.sourceforge.net/stylekey.html
25 Perltidy can produce output on either of two modes, depending on the
27 existence of an -html flag. Without this flag, the output is passed
28 through a formatter. The default formatting tries to follow the
29 recommendations in perlstyle(1), but it can be controlled in detail
30 with numerous input parameters, which are described in "FORMATTING
31 OPTIONS".
32 When the -html flag is given, the output is passed through an HTML
34 formatter which is described in "HTML OPTIONS".
35
37 perltidy somefile.pl
38 This will produce a file somefile.pl.tdy containing the script
40 reformatted using the default options, which approximate the style
41 suggested in perlstyle(1). The source file somefile.pl is unchanged.
42 perltidy *.pl
44 Execute perltidy on all .pl files in the current directory with the
46 default options. The output will be in files with an appended .tdy
47 extension. For any file with an error, there will be a file with
48 extension .ERR.
49 perltidy -b file1.pl file2.pl
51 Modify file1.pl and file2.pl in place, and backup the originals to
53 file1.pl.bak and file2.pl.bak. If file1.pl.bak and/or file2.pl.bak
54 already exist, they will be overwritten.
55 perltidy -b -bext='/' file1.pl file2.pl
57 Same as the previous example except that the backup files file1.pl.bak
59 and file2.pl.bak will be deleted if there are no errors.
60 perltidy -gnu somefile.pl
62 Execute perltidy on file somefile.pl with a style which approximates
64 the GNU Coding Standards for C programs. The output will be
65 somefile.pl.tdy.
66 perltidy -i=3 somefile.pl
68 Execute perltidy on file somefile.pl, with 3 columns for each level of
70 indentation (-i=3) instead of the default 4 columns. There will not be
71 any tabs in the reformatted script, except for any which already exist
72 in comments, pod documents, quotes, and here documents. Output will be
73 somefile.pl.tdy.
74 perltidy -i=3 -et=8 somefile.pl
76 Same as the previous example, except that leading whitespace will be
78 entabbed with one tab character per 8 spaces.
79 perltidy -ce -l=72 somefile.pl
81 Execute perltidy on file somefile.pl with all defaults except use
83 "cuddled elses" (-ce) and a maximum line length of 72 columns (-l=72)
84 instead of the default 80 columns.
85 perltidy -g somefile.pl
87 Execute perltidy on file somefile.pl and save a log file
89 somefile.pl.LOG which shows the nesting of braces, parentheses, and
90 square brackets at the start of every line.
91 perltidy -html somefile.pl
93 This will produce a file somefile.pl.html containing the script with
95 html markup. The output file will contain an embedded style sheet in
96 the <HEAD> section which may be edited to change the appearance.
97 perltidy -html -css=mystyle.css somefile.pl
99 This will produce a file somefile.pl.html containing the script with
101 html markup. This output file will contain a link to a separate style
102 sheet file mystyle.css. If the file mystyle.css does not exist, it
103 will be created. If it exists, it will not be overwritten.
104 perltidy -html -pre somefile.pl
106 Write an html snippet with only the PRE section to somefile.pl.html.
108 This is useful when code snippets are being formatted for inclusion in
109 a larger web page. No style sheet will be written in this case.
110 perltidy -html -ss >mystyle.css
112 Write a style sheet to mystyle.css and exit.
114 perltidy -html -frm mymodule.pm
116 Write html with a frame holding a table of contents and the source
118 code. The output files will be mymodule.pm.html (the frame),
119 mymodule.pm.toc.html (the table of contents), and mymodule.pm.src.html
120 (the source code).
121
123 The entire command line is scanned for options, and they are processed
124 before any files are processed. As a result, it does not matter
125 whether flags are before or after any filenames. However, the relative
126 order of parameters is important, with later parameters overriding the
127 values of earlier parameters.
128 For each parameter, there is a long name and a short name. The short
130 names are convenient for keyboard input, while the long names are self-
131 documenting and therefore useful in scripts. It is customary to use
132 two leading dashes for long names, but one may be used.
133 Most parameters which serve as on/off flags can be negated with a
135 leading "n" (for the short name) or a leading "no" or "no-" (for the
136 long name). For example, the flag to outdent long quotes is -olq or
137 --outdent-long-quotes. The flag to skip this is -nolq or
138 --nooutdent-long-quotes or --no-outdent-long-quotes.
139 Options may not be bundled together. In other words, options -q and -g
141 may NOT be entered as -qg.
142 Option names may be terminated early as long as they are uniquely
144 identified. For example, instead of --dump-token-types, it would be
145 sufficient to enter --dump-tok, or even --dump-t, to uniquely identify
146 this command.
147 I/O control
149 The following parameters concern the files which are read and written.
150 -h, --help
152 Show summary of usage and exit.
153 -o=filename, --outfile=filename
155 Name of the output file (only if a single input file is being
156 processed). If no output file is specified, and output is not
157 redirected to the standard output (see -st), the output will go to
158 filename.tdy. [Note: - does not redirect to standard output. Use
159 -st instead.]
160 -st, --standard-output
162 Perltidy must be able to operate on an arbitrarily large number of
163 files in a single run, with each output being directed to a
164 different output file. Obviously this would conflict with
165 outputting to the single standard output device, so a special flag,
166 -st, is required to request outputting to the standard output. For
167 example,
168 perltidy somefile.pl -st >somefile.new.pl
170 This option may only be used if there is just a single input file.
172 The default is -nst or --nostandard-output.
173 -se, --standard-error-output
175 If perltidy detects an error when processing file somefile.pl, its
176 default behavior is to write error messages to file
177 somefile.pl.ERR. Use -se to cause all error messages to be sent to
178 the standard error output stream instead. This directive may be
179 negated with -nse. Thus, you may place -se in a .perltidyrc and
180 override it when desired with -nse on the command line.
181 -oext=ext, --output-file-extension=ext
183 Change the extension of the output file to be ext instead of the
184 default tdy (or html in case the --html option is used). See
185 "Specifying File Extensions".
186 -opath=path, --output-path=path
188 When perltidy creates a filename for an output file, by default it
189 merely appends an extension to the path and basename of the input
190 file. This parameter causes the path to be changed to path
191 instead.
192 The path should end in a valid path separator character, but
194 perltidy will try to add one if it is missing.
195 For example
197 perltidy somefile.pl -opath=/tmp/
199 will produce /tmp/somefile.pl.tdy. Otherwise, somefile.pl.tdy will
201 appear in whatever directory contains somefile.pl.
202 If the path contains spaces, it should be placed in quotes.
204 This parameter will be ignored if output is being directed to
206 standard output, or if it is being specified explicitly with the
207 -o=s parameter.
208 -b, --backup-and-modify-in-place
210 Modify the input file or files in-place and save the original with
211 the extension .bak. Any existing .bak file will be deleted. See
212 next item for changing the default backup extension, and for
213 eliminating the backup file altogether.
214 A -b flag will be ignored if input is from standard input or goes
216 to standard output, or if the -html flag is set.
217 In particular, if you want to use both the -b flag and the -pbp
219 (--perl-best-practices) flag, then you must put a -nst flag after
220 the -pbp flag because it contains a -st flag as one of its
221 components, which means that output will go to the standard output
222 stream.
223 -bext=ext, --backup-file-extension=ext
225 This parameter serves two purposes: (1) to change the extension of
226 the backup file to be something other than the default .bak, and
227 (2) to indicate that no backup file should be saved.
228 To change the default extension to something other than .bak see
230 "Specifying File Extensions".
231 A backup file of the source is always written, but you can request
233 that it be deleted at the end of processing if there were no
234 errors. This is risky unless the source code is being maintained
235 with a source code control system.
236 To indicate that the backup should be deleted include one forward
238 slash, /, in the extension. If any text remains after the slash is
239 removed it will be used to define the backup file extension (which
240 is always created and only deleted if there were no errors).
241 Here are some examples:
243 Parameter Extension Backup File Treatment
245 <-bext=bak> F<.bak> Keep (same as the default behavior)
246 <-bext='/'> F<.bak> Delete if no errors
247 <-bext='/backup'> F<.backup> Delete if no errors
248 <-bext='original/'> F<.original> Delete if no errors
249 -w, --warning-output
251 Setting -w causes any non-critical warning messages to be reported
252 as errors. These include messages about possible pod problems,
253 possibly bad starting indentation level, and cautions about
254 indirect object usage. The default, -nw or --nowarning-output, is
255 not to include these warnings.
256 -q, --quiet
258 Deactivate error messages (for running under an editor).
259 For example, if you use a vi-style editor, such as vim, you may
261 execute perltidy as a filter from within the editor using something
262 like
263 :n1,n2!perltidy -q
265 where "n1,n2" represents the selected text. Without the -q flag,
267 any error message may mess up your screen, so be prepared to use
268 your "undo" key.
269 -log, --logfile
271 Save the .LOG file, which has many useful diagnostics. Perltidy
272 always creates a .LOG file, but by default it is deleted unless a
273 program bug is suspected. Setting the -log flag forces the log
274 file to be saved.
275 -g=n, --logfile-gap=n
277 Set maximum interval between input code lines in the logfile. This
278 purpose of this flag is to assist in debugging nesting errors. The
279 value of "n" is optional. If you set the flag -g without the value
280 of "n", it will be taken to be 1, meaning that every line will be
281 written to the log file. This can be helpful if you are looking
282 for a brace, paren, or bracket nesting error.
283 Setting -g also causes the logfile to be saved, so it is not
285 necessary to also include -log.
286 If no -g flag is given, a value of 50 will be used, meaning that at
288 least every 50th line will be recorded in the logfile. This helps
289 prevent excessively long log files.
290 Setting a negative value of "n" is the same as not setting -g at
292 all.
293 -npro --noprofile
295 Ignore any .perltidyrc command file. Normally, perltidy looks
296 first in your current directory for a .perltidyrc file of
297 parameters. (The format is described below). If it finds one, it
298 applies those options to the initial default values, and then it
299 applies any that have been defined on the command line. If no
300 .perltidyrc file is found, it looks for one in your home directory.
301 If you set the -npro flag, perltidy will not look for this file.
303 -pro=filename or --profile=filename
305 To simplify testing and switching .perltidyrc files, this command
306 may be used to specify a configuration file which will override the
307 default name of .perltidyrc. There must not be a space on either
308 side of the '=' sign. For example, the line
309 perltidy -pro=testcfg
311 would cause file testcfg to be used instead of the default
313 .perltidyrc.
314 A pathname begins with three dots, e.g. ".../.perltidyrc",
316 indicates that the file should be searched for starting in the
317 current directory and working upwards. This makes it easier to have
318 multiple projects each with their own .perltidyrc in their root
319 directories.
320 -opt, --show-options
322 Write a list of all options used to the .LOG file. Please see
323 --dump-options for a simpler way to do this.
324 -f, --force-read-binary
326 Force perltidy to process binary files. To avoid producing
327 excessive error messages, perltidy skips files identified by the
328 system as non-text. However, valid perl scripts containing binary
329 data may sometimes be identified as non-text, and this flag forces
330 perltidy to process them.
331 -ast, --assert-tidy
333 This flag asserts that the input and output code streams are
334 identical, or in other words that the input code is already 'tidy'
335 according to the formatting parameters. If this is not the case,
336 an error message noting this is produced. This error message will
337 cause the process to return a non-zero exit code. The test for
338 this is made by comparing an MD5 hash value for the input and
339 output code streams. This flag has no other effect on the
340 functioning of perltidy. This might be useful for certain code
341 maintenance operations. Note: you will not see this message if you
342 have error messages turned off with the -quiet flag.
343 -asu, --assert-untidy
345 This flag asserts that the input and output code streams are
346 different, or in other words that the input code is 'untidy'
347 according to the formatting parameters. If this is not the case,
348 an error message noting this is produced. This flag has no other
349 effect on the functioning of perltidy.
350 -sal=s, --sub-alias-list=s
352 This flag causes one or more words to be treated the same as if
353 they were the keyword 'sub'. The string s contains one or more
354 alias words, separated by spaces or commas.
355 For example,
357 perltidy -sal='method fun _sub M4'
359 will cause the perltidy to treate the words 'method', 'fun', '_sub'
361 and 'M4' to be treated the same as if they were 'sub'. Note that
362 if the alias words are separated by spaces then the string of words
363 should be placed in quotes.
364 Note that several other parameters accept a list of keywords,
366 including 'sub' (see "Specifying Block Types"). You do not need to
367 include any sub aliases in these lists. Just include keyword 'sub'
368 if you wish, and all aliases are automatically included.
369 -gal=s, --grep-alias-list=s
371 This flag allows a code block following an external 'list operator'
372 function to be formatted as if it followed one of the builtin
373 keywords grep, map or sort. The string s contains the names of
374 one or more such list operators, separated by spaces or commas.
375 By 'list operator' is meant a function which is invoked in the form
377 word {BLOCK} @list
379 Perltidy tries to keep code blocks for these functions intact,
381 since they are usually short, and does not automatically break
382 after the closing brace since a list may follow. It also does some
383 special handling of continuation indentation.
384 For example, the code block arguments to functions 'My_grep' and
386 'My_map' can be given formatting like 'grep' with
387 perltidy -gal='My_grep My_map'
389 By default, the following list operators in List::Util are
391 automatically included:
392 all any first none notall reduce reductions
394 Any operators specified with --grep-alias-list are added to this
396 list. The next parameter can be used to remove words from this
397 default list.
398 -gaxl=s, --grep-alias-exclusion-list=s
400 The -gaxl=s flag provides a method for removing any of the default
401 list operators given above by listing them in the string s. To
402 remove all of the default operators use -gaxl='*'.
403
405 Basic Options
406 --notidy
407 This flag disables all formatting and causes the input to be copied
408 unchanged to the output except for possible changes in line ending
409 characters and any pre- and post-filters. This can be useful in
410 conjunction with a hierarchical set of .perltidyrc files to avoid
411 unwanted code tidying. See also "Skipping Selected Sections of
412 Code" for a way to avoid tidying specific sections of code.
413 -i=n, --indent-columns=n
415 Use n columns per indentation level (default n=4).
416 -l=n, --maximum-line-length=n
418 The default maximum line length is n=80 characters. Perltidy will
419 try to find line break points to keep lines below this length.
420 However, long quotes and side comments may cause lines to exceed
421 this length.
422 The default length of 80 comes from the past when this was the
424 standard CRT screen width. Many programmers prefer to increase
425 this to something like 120.
426 Setting -l=0 is equivalent to setting -l=(a very large number).
428 But this is not recommended because, for example, a very long list
429 will be formatted in a single long line.
430 -vmll, --variable-maximum-line-length
432 A problem arises using a fixed maximum line length with very deeply
433 nested code and data structures because eventually the amount of
434 leading whitespace used for indicating indentation takes up most or
435 all of the available line width, leaving little or no space for the
436 actual code or data. One solution is to use a very long line
437 length. Another solution is to use the -vmll flag, which basically
438 tells perltidy to ignore leading whitespace when measuring the line
439 length.
440 To be precise, when the -vmll parameter is set, the maximum line
442 length of a line of code will be M+L*I, where
443 M is the value of --maximum-line-length=M (-l=M), default 80,
445 I is the value of --indent-columns=I (-i=I), default 4,
446 L is the indentation level of the line of code
447 When this flag is set, the choice of breakpoints for a block of
449 code should be essentially independent of its nesting depth.
450 However, the absolute line lengths, including leading whitespace,
451 can still be arbitrarily large. This problem can be avoided by
452 including the next parameter.
453 The default is not to do this (-nvmll).
455 -wc=n, --whitespace-cycle=n
457 This flag also addresses problems with very deeply nested code and
458 data structures. When the nesting depth exceeds the value n the
459 leading whitespace will be reduced and start at a depth of 1 again.
460 The result is that blocks of code will shift back to the left
461 rather than moving arbitrarily far to the right. This occurs
462 cyclically to any depth.
463 For example if one level of indentation equals 4 spaces (-i=4, the
465 default), and one uses -wc=15, then if the leading whitespace on a
466 line exceeds about 4*15=60 spaces it will be reduced back to 4*1=4
467 spaces and continue increasing from there. If the whitespace never
468 exceeds this limit the formatting remains unchanged.
469 The combination of -vmll and -wc=n provides a solution to the
471 problem of displaying arbitrarily deep data structures and code in
472 a finite window, although -wc=n may of course be used without
473 -vmll.
474 The default is not to use this, which can also be indicated using
476 -wc=0.
477 Tabs
479 Using tab characters will almost certainly lead to future
480 portability and maintenance problems, so the default and
481 recommendation is not to use them. For those who prefer tabs,
482 however, there are two different options.
483 Except for possibly introducing tab indentation characters, as
485 outlined below, perltidy does not introduce any tab characters into
486 your file, and it removes any tabs from the code (unless requested
487 not to do so with -fws). If you have any tabs in your comments,
488 quotes, or here-documents, they will remain.
489 -et=n, --entab-leading-whitespace
491 This flag causes each n initial space characters to be replaced
492 by one tab character.
493 The value of the integer n can be any value but can be
495 coordinated with the number of spaces used for intentation. For
496 example, -et=4 -ci=4 -i=4 will produce one tab for each
497 indentation level and and one for each continuation indentation
498 level. You may want to coordinate the value of n with what
499 your display software assumes for the spacing of a tab.
500 -t, --tabs
502 This flag causes one leading tab character to be inserted for
503 each level of indentation. Certain other features are
504 incompatible with this option, and if these options are also
505 given, then a warning message will be issued and this flag will
506 be unset. One example is the -lp option. This flag is retained
507 for backwards compatibility, but if you use tabs, the -et=n
508 flag is recommended.
509 -dt=n, --default-tabsize=n
511 If the first line of code passed to perltidy contains leading
512 tabs but no tab scheme is specified for the output stream then
513 perltidy must guess how many spaces correspond to each leading
514 tab. This number of spaces n corresponding to each leading tab
515 of the input stream may be specified with -dt=n. The default
516 is n=8.
517 This flag has no effect if a tab scheme is specified for the
519 output stream, because then the input stream is assumed to use
520 the same tab scheme and indentation spaces as for the output
521 stream (any other assumption would lead to unstable editing).
522 -xs, --extended-syntax
524 A problem with formatting Perl code is that some modules can
525 introduce new syntax. This flag allows perltidy to handle certain
526 common extensions to the standard syntax without complaint.
527 For example, without this flag a structure such as the following
529 would generate a syntax error and the braces would not be balanced:
530 method deposit( Num $amount) {
532 $self->balance( $self->balance + $amount );
533 }
534 For one of the extensions, module Switch::Plain, colons are marked
536 as labels. If you use this module, you may want to also use the
537 --nooutdent-labels flag to prevent lines such as 'default:' from
538 being outdented.
539 This flag is enabled by default but it can be deactivated with
541 -nxs. Probably the only reason to deactivate this flag is to
542 generate more diagnostic messages when debugging a script.
543 For another method of handling extended syntax see the section
545 "Skipping Selected Sections of Code".
546 -io, --indent-only
548 This flag is used to deactivate all whitespace and line break
549 changes within non-blank lines of code. When it is in effect, the
550 only change to the script will be to the indentation and to the
551 number of blank lines. And any flags controlling whitespace and
552 newlines will be ignored. You might want to use this if you are
553 perfectly happy with your whitespace and line breaks, and merely
554 want perltidy to handle the indentation. (This also speeds up
555 perltidy by well over a factor of two, so it might be useful when
556 perltidy is merely being used to help find a brace error in a large
557 script).
558 Setting this flag is equivalent to setting --freeze-newlines and
560 --freeze-whitespace.
561 If you also want to keep your existing blank lines exactly as they
563 are, you can add --freeze-blank-lines.
564 With this option perltidy is still free to modify the indenting
566 (and outdenting) of code and comments as it normally would. If you
567 also want to prevent long comment lines from being outdented, you
568 can add either -noll or -l=0.
569 Setting this flag will prevent perltidy from doing any special
571 operations on closing side comments. You may still delete all side
572 comments however when this flag is in effect.
573 -enc=s, --character-encoding=s
575 This flag indicates if the input data stream use a character
576 encoding. Perltidy does not look for the encoding directives in
577 the soure stream, such as use utf8, and instead relies on this flag
578 to determine the encoding. (Note that perltidy often works on
579 snippets of code rather than complete files so it cannot rely on
580 use utf8 directives).
581 The possible values for s are:
583 -enc=none if no encoding is used, or
585 -enc=utf8 for encoding in utf8
586 -enc=guess if perltidy should guess between these two possibilities.
587 The value none causes the stream to be processed without special
589 encoding assumptions. This is appropriate for files which are
590 written in single-byte character encodings such as latin-1.
591 The value utf8 causes the stream to be read and written as UTF-8.
593 If the input stream cannot be decoded with this encoding then
594 processing is not done.
595 The value guess tells perltidy to guess between either utf8
597 encoding or no encoding (meaning one character per byte). The
598 guess option uses the Encode::Guess module which has been found to
599 be reliable at detecting if a file is encoded in utf8 or not.
600 The current default is guess.
602 The abbreviations -utf8 or -UTF8 are equivalent to -enc=utf8, and
604 the abbreviation -guess is equivalent to -enc=guess. So to process
605 a file named file.pl which is encoded in UTF-8 you can use:
606 perltidy -utf8 file.pl
608 or
610 perltidy -guess file.pl
612 or simply
614 perltidy file.pl
616 since -guess is the default.
618 To process files with an encoding other than UTF-8, it would be
620 necessary to write a short program which calls the Perl::Tidy
621 module with some pre- and post-processing to handle decoding and
622 encoding.
623 -eos=s, --encode-output-strings=s
625 This flag has been added to resolve an issue involving the
626 interface between Perl::Tidy and calling programs, and in
627 particular Code::TidyAll (tidyall). By default Perl::Tidy returns
628 unencoded strings to the calling program, but some programs expect
629 encoded strings. Setting this flag causes Perl::Tidy to return
630 encoded output strings which it decoded. For some background
631 information see <https://github.com/perltidy/perltidy/issues/83>
632 and <https://github.com/houseabsolute/perl-code-tidyall/issues/84>.
633 If you only run the perltidy binary this flag has no effect.
635 If you use tidyall with encoded files and encounter irregularities
637 such as wide character messages you should set this flag.
638 Additional information can be found in the man pages for the
640 Perl::Tidy module.
641 -gcs, --use-unicode-gcstring
643 This flag controls whether or not perltidy may use module
644 Unicode::GCString to obtain accurate display widths of wide
645 characters. The default is --nouse-unicode-gcstring.
646 If this flag is set, and text is encoded, perltidy will look for
648 the module Unicode::GCString and, if found, will use it to obtain
649 character display widths. This can improve displayed vertical
650 alignment for files with wide characters. It is a nice feature but
651 it is off by default to avoid conflicting formatting when there are
652 multiple developers. Perltidy installation does not require
653 Unicode::GCString, so users wanting to use this feature need set
654 this flag and also to install Unicode::GCString separately.
655 If this flag is set and perltidy does not find module
657 Unicode::GCString, a warning message will be produced and
658 processing will continue but without the potential benefit provided
659 by the module.
660 Also note that actual vertical alignment depends upon the fonts
662 used by the text display software, so vertical alignment may not be
663 optimal even when Unicode::GCString is used.
664 -ole=s, --output-line-ending=s
666 where s="win", "dos", "unix", or "mac". This flag tells perltidy
667 to output line endings for a specific system. Normally, perltidy
668 writes files with the line separator character of the host system.
669 The "win" and "dos" flags have an identical result.
670 -ple, --preserve-line-endings
672 This flag tells perltidy to write its output files with the same
673 line endings as the input file, if possible. It should work for
674 dos, unix, and mac line endings. It will only work if perltidy
675 input comes from a filename (rather than stdin, for example). If
676 perltidy has trouble determining the input file line ending, it
677 will revert to the default behavior of using the line ending of the
678 host system.
679 -atnl, --add-terminal-newline
681 This flag, which is enabled by default, allows perltidy to
682 terminate the last line of the output stream with a newline
683 character, regardless of whether or not the input stream was
684 terminated with a newline character. If this flag is negated, with
685 -natnl, then perltidy will add a terminal newline to the the output
686 stream only if the input stream is terminated with a newline.
687 Negating this flag may be useful for manipulating one-line scripts
689 intended for use on a command line.
690 -it=n, --iterations=n
692 This flag causes perltidy to do n complete iterations. The reason
693 for this flag is that code beautification is an iterative process
694 and in some cases the output from perltidy can be different if it
695 is applied a second time. For most purposes the default of n=1
696 should be satisfactory. However n=2 can be useful when a major
697 style change is being made, or when code is being beautified on
698 check-in to a source code control system. It has been found to be
699 extremely rare for the output to change after 2 iterations. If a
700 value n is greater than 2 is input then a convergence test will be
701 used to stop the iterations as soon as possible, almost always
702 after 2 iterations. See the next item for a simplified iteration
703 control.
704 This flag has no effect when perltidy is used to generate html.
706 -conv, --converge
708 This flag is equivalent to -it=4 and is included to simplify
709 iteration control. For all practical purposes one either does or
710 does not want to be sure that the output is converged, and there is
711 no penalty to using a large iteration limit since perltidy will
712 check for convergence and stop iterating as soon as possible. The
713 default is -nconv (no convergence check). Using -conv will
714 approximately double run time since typically one extra iteration
715 is required to verify convergence. No extra iterations are
716 required if no new line breaks are made, and two extra iterations
717 are occasionally needed when reformatting complex code structures,
718 such as deeply nested ternary statements.
719 Code Indentation Control
721 -ci=n, --continuation-indentation=n
722 Continuation indentation is extra indentation spaces applied when a
723 long line is broken. The default is n=2, illustrated here:
724 my $level = # -ci=2
726 ( $max_index_to_go >= 0 ) ? $levels_to_go[0] : $last_output_level;
727 The same example, with n=0, is a little harder to read:
729 my $level = # -ci=0
731 ( $max_index_to_go >= 0 ) ? $levels_to_go[0] : $last_output_level;
732 The value given to -ci is also used by some commands when a small
734 space is required. Examples are commands for outdenting labels,
735 -ola, and control keywords, -okw.
736 When default values are not used, it is recommended that either
738 (1) the value n given with -ci=n be no more than about one-half of
740 the number of spaces assigned to a full indentation level on the
741 -i=n command, or
742 (2) the flag -extended-continuation-indentation is used (see next
744 section).
745 -xci, --extended-continuation-indentation
747 This flag allows perltidy to use some improvements which have been
748 made to its indentation model. One of the things it does is
749 "extend" continuation indentation deeper into structures, hence the
750 name. The improved indentation is particularly noticeable when the
751 flags -ci=n and -i=n use the same value of n. There are no
752 significant disadvantages to using this flag, but to avoid
753 disturbing existing formatting the default is not to use it, -nxci.
754 Please see the section "-pbp, --perl-best-practices" for an example
756 of how this flag can improve the formatting of ternary statements.
757 It can also improve indentation of some multi-line qw lists as
758 shown below.
759 # perltidy
761 foreach $color (
762 qw(
763 AntiqueWhite3 Bisque1 Bisque2 Bisque3 Bisque4
764 SlateBlue3 RoyalBlue1 SteelBlue2 DeepSkyBlue3
765 ),
766 qw(
767 LightBlue1 DarkSlateGray1 Aquamarine2 DarkSeaGreen2
768 SeaGreen1 Yellow1 IndianRed1 IndianRed2 Tan1 Tan4
769 )
770 )
771 # perltidy -xci
773 foreach $color (
774 qw(
775 AntiqueWhite3 Bisque1 Bisque2 Bisque3 Bisque4
776 SlateBlue3 RoyalBlue1 SteelBlue2 DeepSkyBlue3
777 ),
778 qw(
779 LightBlue1 DarkSlateGray1 Aquamarine2 DarkSeaGreen2
780 SeaGreen1 Yellow1 IndianRed1 IndianRed2 Tan1 Tan4
781 )
782 )
783 -sil=n --starting-indentation-level=n
785 By default, perltidy examines the input file and tries to determine
786 the starting indentation level. While it is often zero, it may not
787 be zero for a code snippet being sent from an editing session.
788 To guess the starting indentation level perltidy simply assumes
790 that indentation scheme used to create the code snippet is the same
791 as is being used for the current perltidy process. This is the
792 only sensible guess that can be made. It should be correct if this
793 is true, but otherwise it probably won't. For example, if the
794 input script was written with -i=2 and the current peltidy flags
795 have -i=4, the wrong initial indentation will be guessed for a code
796 snippet which has non-zero initial indentation. Likewise, if an
797 entabbing scheme is used in the input script and not in the current
798 process then the guessed indentation will be wrong.
799 If the default method does not work correctly, or you want to
801 change the starting level, use -sil=n, to force the starting level
802 to be n.
803 List indentation using --line-up-parentheses, -lp or
805 --extended--line-up-parentheses , -xlp
806 These flags provide an alternative indentation method for list
807 data. The original flag for this is -lp, but it has some
808 limitations (explained below) which are avoided with the newer -xlp
809 flag. So -xlp is probably the better choice for new work, but the
810 -lp flag is retained to minimize changes to existing formatting.
811 If you enter both -lp and -xlp, then -xlp will be used.
812 In the default indentation method perltidy indents lists with 4
814 spaces, or whatever value is specified with -i=n. Here is a small
815 list formatted in this way:
816 # perltidy (default)
818 @month_of_year = (
819 'Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun',
820 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'
821 );
822 The -lp or -xlp flags add extra indentation to cause the data to
824 begin past the opening parentheses of a sub call or list, or
825 opening square bracket of an anonymous array, or opening curly
826 brace of an anonymous hash. With this option, the above list would
827 become:
828 # perltidy -lp or -xlp
830 @month_of_year = (
831 'Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun',
832 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'
833 );
834 If the available line length (see -l=n ) does not permit this much
836 space, perltidy will use less. For alternate placement of the
837 closing paren, see the next section.
838 These flags have no effect on code BLOCKS, such as if/then/else
840 blocks, which always use whatever is specified with -i=n.
841 Some limitiations on these flags are:
843 • A limitation on -lp, but not -xlp, occurs in situations where
845 perltidy does not have complete freedom to choose line breaks.
846 Then it may temporarily revert to its default indentation
847 method. This can occur for example if there are blank lines,
848 block comments, multi-line quotes, or side comments between the
849 opening and closing parens, braces, or brackets. It will also
850 occur if a multi-line anonymous sub occurs within a container
851 since that will impose specific line breaks (such as line
852 breaks after statements).
853 • For both the -lp and -xlp flags, any parameter which
855 significantly restricts the ability of perltidy to choose
856 newlines will conflict with these flags and will cause them to
857 be deactivated. These include -io, -fnl, -nanl, and -ndnl.
858 • The -lp and -xlp options may not be used together with the -t
860 tabs option. They may, however, be used with the -et=n tab
861 method
862 There are some potential disadvantages of this indentation method
864 compared to the default method that should be noted:
865 • The available line length can quickly be used up if variable
867 names are long. This can cause deeply nested code to quickly
868 reach the line length limit, and become badly formatted, much
869 sooner than would occur with the default indentation method.
870 • Since the indentation depends on the lengths of variable names,
872 small changes in variable names can cause changes in
873 indentation over many lines in a file. This means that minor
874 name changes can produce significant file differences. This
875 can be annoying and does not occur with the default indentation
876 method.
877 Some things that can be done to minimize these problems are:
879 • Increase --maximum-line-length=n above the default n=80
881 characters if necessary.
882 • If you use -xlp then long side comments can limit the
884 indentation over multiple lines. Consider adding the flag
885 --ignore-side-comment-lengths to prevent this, or minimizing
886 the use of side comments.
887 • Apply this style in a limited way. By default, it applies to
889 all list containers (not just lists in parentheses). The next
890 section describes how to limit this style to, for example, just
891 function calls. The default indentation method will be applied
892 elsewhere.
893 -lpil=s, --line-up-parentheses-inclusion-list and -lpxl=s,
895 --line-up-parentheses-exclusion-list
896 The following discussion is written for -lp but applies equally to
897 the newer -xlp version. By default, the -lp flag applies to as
898 many containers as possible. The set of containers to which the
899 -lp style applies can be reduced by either one of these two flags:
900 Use -lpil=s to specify the containers to which -lp applies, or
902 use -lpxl=s to specify the containers to which -lp does NOT apply.
904 Only one of these two flags may be used. Both flags can achieve
906 the same result, but the -lpil=s flag is much easier to describe
907 and use and is recommended. The -lpxl=s flag was the original
908 implementation and is only retained for backwards compatibility.
909 This list s for these parametes is a string with space-separated
911 items. Each item consists of up to three pieces of information in
912 this order: (1) an optional letter code (2) a required container
913 type, and (3) an optional numeric code.
914 The only required piece of information is a container type, which
916 is one of '(', '[', or '{'. For example the string
917 -lpil='('
919 means use -lp formatting only on lists within parentheses, not
921 lists in square-bracets or braces. The same thing could
922 alternatively be specified with
923 -lpxl = '[ {'
925 which says to exclude lists within square-brackets and braces. So
927 what remains is lists within parentheses.
928 A second optional item of information which can be given for
930 parentheses is an alphanumeric letter which is used to limit the
931 selection further depending on the type of token immediately before
932 the paren. The possible letters are currently 'k', 'K', 'f', 'F',
933 'w', and 'W', with these meanings for matching whatever precedes an
934 opening paren:
935 'k' matches if the previous nonblank token is a perl builtin keyword (such as 'if', 'while'),
937 'K' matches if 'k' does not, meaning that the previous token is not a keyword.
938 'f' matches if the previous token is a function other than a keyword.
939 'F' matches if 'f' does not.
940 'w' matches if either 'k' or 'f' match.
941 'W' matches if 'w' does not.
942 For example:
944 -lpil = 'f('
946 means only apply -lp to function calls, and
948 -lpil = 'w('
950 means only apply -lp to parenthesized lists which follow a function
952 or a keyword.
953 This last example could alternatively be written using the -lpxl=s
955 flag as
956 -lpxl = '[ { W('
958 which says exclude -lp for lists within square-brackets, braces,
960 and parens NOT preceded by a keyword or function. Clearly, the
961 -lpil=s method is easier to understand.
962 An optional numeric code may follow any of the container types to
964 further refine the selection based on container contents. The
965 numeric codes are:
966 '0' or blank: no check on contents is made
968 '1' exclude B<-lp> unless the contents is a simple list without sublists
969 '2' exclude B<-lp> unless the contents is a simple list without sublists, without
970 code blocks, and without ternary operators
971 For example,
973 -lpil = 'f(2'
975 means only apply -lp to function call lists which do not contain
977 any sublists, code blocks or ternary expressions.
978 -cti=n, --closing-token-indentation
980 The -cti=n flag controls the indentation of a line beginning with a
981 ")", "]", or a non-block "}". Such a line receives:
982 -cti = 0 no extra indentation (default)
984 -cti = 1 extra indentation such that the closing token
985 aligns with its opening token.
986 -cti = 2 one extra indentation level if the line looks like:
987 ); or ]; or };
988 -cti = 3 one extra indentation level always
989 The flags -cti=1 and -cti=2 work well with the -lp flag (previous
991 section).
992 # perltidy -lp -cti=1
994 @month_of_year = (
995 'Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun',
996 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'
997 );
998 # perltidy -lp -cti=2
1000 @month_of_year = (
1001 'Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun',
1002 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'
1003 );
1004 These flags are merely hints to the formatter and they may not
1006 always be followed. In particular, if -lp is not being used, the
1007 indentation for cti=1 is constrained to be no more than one
1008 indentation level.
1009 If desired, this control can be applied independently to each of
1011 the closing container token types. In fact, -cti=n is merely an
1012 abbreviation for -cpi=n -csbi=n -cbi=n, where: -cpi or
1013 --closing-paren-indentation controls )'s, -csbi or
1014 --closing-square-bracket-indentation controls ]'s, -cbi or
1015 --closing-brace-indentation controls non-block }'s.
1016 -icp, --indent-closing-paren
1018 The -icp flag is equivalent to -cti=2, described in the previous
1019 section. The -nicp flag is equivalent -cti=0. They are included
1020 for backwards compatibility.
1021 -icb, --indent-closing-brace
1023 The -icb option gives one extra level of indentation to a brace
1024 which terminates a code block . For example,
1025 if ($task) {
1027 yyy();
1028 } # -icb
1029 else {
1030 zzz();
1031 }
1032 The default is not to do this, indicated by -nicb.
1034 -nib, --non-indenting-braces
1036 Normally, lines of code contained within a pair of block braces
1037 receive one additional level of indentation. This flag, which is
1038 enabled by default, causes perltidy to look for opening block
1039 braces which are followed by a special side comment. This special
1040 side comment is #<<< by default. If found, the code between this
1041 opening brace and its corresponding closing brace will not be given
1042 the normal extra indentation level. For example:
1043 { #<<< a closure to contain lexical vars
1045 my $var; # this line does not get one level of indentation
1047 ...
1048 }
1050 # this line does not 'see' $var;
1052 This can be useful, for example, when combining code from different
1054 files. Different sections of code can be placed within braces to
1055 keep their lexical variables from being visible to the end of the
1056 file. To keep the new braces from causing all of their contained
1057 code to be indented if you run perltidy, and possibly introducing
1058 new line breaks in long lines, you can mark the opening braces with
1059 this special side comment.
1060 Only the opening brace needs to be marked, since perltidy knows
1062 where the closing brace is. Braces contained within marked braces
1063 may also be marked as non-indenting.
1064 If your code happens to have some opening braces followed by
1066 '#<<<', and you don't want this behavior, you can use -nnib to
1067 deactivate it. To make it easy to remember, the default string is
1068 the same as the string for starting a format-skipping section.
1069 There is no confusion because in that case it is for a block
1070 comment rather than a side-comment.
1071 The special side comment can be changed with the next parameter.
1073 -nibp=s, --non-indenting-brace-prefix=s
1075 The -nibp=string parameter may be used to change the marker for
1076 non-indenting braces. The default is equivalent to -nibp='#<<<'.
1077 The string that you enter must begin with a # and should be in
1078 quotes as necessary to get past the command shell of your system.
1079 This string is the leading text of a regex pattern that is
1080 constructed by appending pre-pending a '^' and appending a'\s', so
1081 you must also include backslashes for characters to be taken
1082 literally rather than as patterns.
1083 For example, to match the side comment '#++', the parameter would
1085 be
1086 -nibp='#\+\+'
1088 -olq, --outdent-long-quotes
1090 When -olq is set, lines which is a quoted string longer than the
1091 value maximum-line-length will have their indentation removed to
1092 make them more readable. This is the default. To prevent such
1093 out-denting, use -nolq or --nooutdent-long-lines.
1094 -oll, --outdent-long-lines
1096 This command is equivalent to --outdent-long-quotes and
1097 --outdent-long-comments, and it is included for compatibility with
1098 previous versions of perltidy. The negation of this also works,
1099 -noll or --nooutdent-long-lines, and is equivalent to setting -nolq
1100 and -nolc.
1101 Outdenting Labels: -ola, --outdent-labels
1103 This command will cause labels to be outdented by 2 spaces (or
1104 whatever -ci has been set to), if possible. This is the default.
1105 For example:
1106 my $i;
1108 LOOP: while ( $i = <FOTOS> ) {
1109 chomp($i);
1110 next unless $i;
1111 fixit($i);
1112 }
1113 Use -nola to not outdent labels. To control line breaks after
1115 labels see "bal=n, --break-after-labels=n".
1116 Outdenting Keywords
1118 -okw, --outdent-keywords
1119 The command -okw will cause certain leading control keywords to
1120 be outdented by 2 spaces (or whatever -ci has been set to), if
1121 possible. By default, these keywords are "redo", "next",
1122 "last", "goto", and "return". The intention is to make these
1123 control keywords easier to see. To change this list of
1124 keywords being outdented, see the next section.
1125 For example, using "perltidy -okw" on the previous example
1127 gives:
1128 my $i;
1130 LOOP: while ( $i = <FOTOS> ) {
1131 chomp($i);
1132 next unless $i;
1133 fixit($i);
1134 }
1135 The default is not to do this.
1137 Specifying Outdented Keywords: -okwl=string,
1139 --outdent-keyword-list=string
1140 This command can be used to change the keywords which are
1141 outdented with the -okw command. The parameter string is a
1142 required list of perl keywords, which should be placed in
1143 quotes if there are more than one. By itself, it does not
1144 cause any outdenting to occur, so the -okw command is still
1145 required.
1146 For example, the commands "-okwl="next last redo goto" -okw"
1148 will cause those four keywords to be outdented. It is probably
1149 simplest to place any -okwl command in a .perltidyrc file.
1150 Whitespace Control
1152 Whitespace refers to the blank space between variables, operators, and
1153 other code tokens.
1154 -fws, --freeze-whitespace
1156 This flag causes your original whitespace to remain unchanged, and
1157 causes the rest of the whitespace commands in this section, the
1158 Code Indentation section, and the Comment Control section to be
1159 ignored.
1160 Tightness of curly braces, parentheses, and square brackets
1162 Here the term "tightness" will mean the closeness with which pairs
1163 of enclosing tokens, such as parentheses, contain the quantities
1164 within. A numerical value of 0, 1, or 2 defines the tightness,
1165 with 0 being least tight and 2 being most tight. Spaces within
1166 containers are always symmetric, so if there is a space after a "("
1167 then there will be a space before the corresponding ")".
1168 The -pt=n or --paren-tightness=n parameter controls the space
1170 within parens. The example below shows the effect of the three
1171 possible values, 0, 1, and 2:
1172 if ( ( my $len_tab = length( $tabstr ) ) > 0 ) { # -pt=0
1174 if ( ( my $len_tab = length($tabstr) ) > 0 ) { # -pt=1 (default)
1175 if ((my $len_tab = length($tabstr)) > 0) { # -pt=2
1176 When n is 0, there is always a space to the right of a '(' and to
1178 the left of a ')'. For n=2 there is never a space. For n=1, the
1179 default, there is a space unless the quantity within the parens is
1180 a single token, such as an identifier or quoted string.
1181 Likewise, the parameter -sbt=n or --square-bracket-tightness=n
1183 controls the space within square brackets, as illustrated below.
1184 $width = $col[ $j + $k ] - $col[ $j ]; # -sbt=0
1186 $width = $col[ $j + $k ] - $col[$j]; # -sbt=1 (default)
1187 $width = $col[$j + $k] - $col[$j]; # -sbt=2
1188 Curly braces which do not contain code blocks are controlled by the
1190 parameter -bt=n or --brace-tightness=n.
1191 $obj->{ $parsed_sql->{ 'table' }[0] }; # -bt=0
1193 $obj->{ $parsed_sql->{'table'}[0] }; # -bt=1 (default)
1194 $obj->{$parsed_sql->{'table'}[0]}; # -bt=2
1195 And finally, curly braces which contain blocks of code are
1197 controlled by the parameter -bbt=n or --block-brace-tightness=n as
1198 illustrated in the example below.
1199 %bf = map { $_ => -M $_ } grep { /\.deb$/ } dirents '.'; # -bbt=0 (default)
1201 %bf = map { $_ => -M $_ } grep {/\.deb$/} dirents '.'; # -bbt=1
1202 %bf = map {$_ => -M $_} grep {/\.deb$/} dirents '.'; # -bbt=2
1203 To simplify input in the case that all of the tightness flags have
1205 the same value <n>, the parameter <-act=n> or
1206 --all-containers-tightness=n is an abbreviation for the combination
1207 <-pt=n -sbt=n -bt=n -bbt=n>.
1208 -tso, --tight-secret-operators
1210 The flag -tso causes certain perl token sequences (secret
1211 operators) which might be considered to be a single operator to be
1212 formatted "tightly" (without spaces). The operators currently
1213 modified by this flag are:
1214 0+ +0 ()x!! ~~<> ,=> =( )=
1216 For example the sequence 0 +, which converts a string to a number,
1218 would be formatted without a space: 0+ when the -tso flag is set.
1219 This flag is off by default.
1220 -sts, --space-terminal-semicolon
1222 Some programmers prefer a space before all terminal semicolons.
1223 The default is for no such space, and is indicated with -nsts or
1224 --nospace-terminal-semicolon.
1225 $i = 1 ; # -sts
1227 $i = 1; # -nsts (default)
1228 -sfs, --space-for-semicolon
1230 Semicolons within for loops may sometimes be hard to see,
1231 particularly when commas are also present. This option places
1232 spaces on both sides of these special semicolons, and is the
1233 default. Use -nsfs or --nospace-for-semicolon to deactivate it.
1234 for ( @a = @$ap, $u = shift @a ; @a ; $u = $v ) { # -sfs (default)
1236 for ( @a = @$ap, $u = shift @a; @a; $u = $v ) { # -nsfs
1237 -asc, --add-semicolons
1239 Setting -asc allows perltidy to add any missing optional semicolon
1240 at the end of a line which is followed by a closing curly brace on
1241 the next line. This is the default, and may be deactivated with
1242 -nasc or --noadd-semicolons.
1243 -dsm, --delete-semicolons
1245 Setting -dsm allows perltidy to delete extra semicolons which are
1246 simply empty statements. This is the default, and may be
1247 deactivated with -ndsm or --nodelete-semicolons. (Such semicolons
1248 are not deleted, however, if they would promote a side comment to a
1249 block comment).
1250 -aws, --add-whitespace
1252 Setting this option allows perltidy to add certain whitespace to
1253 improve code readability. This is the default. If you do not want
1254 any whitespace added, but are willing to have some whitespace
1255 deleted, use -naws. (Use -fws to leave whitespace completely
1256 unchanged).
1257 -dws, --delete-old-whitespace
1259 Setting this option allows perltidy to remove some old whitespace
1260 between characters, if necessary. This is the default. If you do
1261 not want any old whitespace removed, use -ndws or
1262 --nodelete-old-whitespace.
1263 Detailed whitespace controls around tokens
1265 For those who want more detailed control over the whitespace around
1266 tokens, there are four parameters which can directly modify the
1267 default whitespace rules built into perltidy for any token. They
1268 are:
1269 -wls=s or --want-left-space=s,
1271 -nwls=s or --nowant-left-space=s,
1273 -wrs=s or --want-right-space=s,
1275 -nwrs=s or --nowant-right-space=s.
1277 These parameters are each followed by a quoted string, s,
1279 containing a list of token types. No more than one of each of
1280 these parameters should be specified, because repeating a command-
1281 line parameter always overwrites the previous one before perltidy
1282 ever sees it.
1283 To illustrate how these are used, suppose it is desired that there
1285 be no space on either side of the token types = + - / *. The
1286 following two parameters would specify this desire:
1287 -nwls="= + - / *" -nwrs="= + - / *"
1289 (Note that the token types are in quotes, and that they are
1291 separated by spaces). With these modified whitespace rules, the
1292 following line of math:
1293 $root = -$b + sqrt( $b * $b - 4. * $a * $c ) / ( 2. * $a );
1295 becomes this:
1297 $root=-$b+sqrt( $b*$b-4.*$a*$c )/( 2.*$a );
1299 These parameters should be considered to be hints to perltidy
1301 rather than fixed rules, because perltidy must try to resolve
1302 conflicts that arise between them and all of the other rules that
1303 it uses. One conflict that can arise is if, between two tokens,
1304 the left token wants a space and the right one doesn't. In this
1305 case, the token not wanting a space takes priority.
1306 It is necessary to have a list of all token types in order to
1308 create this type of input. Such a list can be obtained by the
1309 command --dump-token-types. Also try the -D flag on a short
1310 snippet of code and look at the .DEBUG file to see the
1311 tokenization.
1312 WARNING Be sure to put these tokens in quotes to avoid having them
1314 misinterpreted by your command shell.
1315 Note1: Perltidy does always follow whitespace controls
1317 The various parameters controlling whitespace within a program are
1318 requests which perltidy follows as well as possible, but there are
1319 a number of situations where changing whitespace could change
1320 program behavior and is not done. Some of these are obvious; for
1321 example, we should not remove the space between the two plus
1322 symbols in '$x+ +$y' to avoid creating a '++' operator. Some are
1323 more subtle and involve the whitespace around bareword symbols and
1324 locations of possible filehandles. For example, consider the
1325 problem of formatting the following subroutine:
1326 sub print_div {
1328 my ($x,$y)=@_;
1329 print $x/$y;
1330 }
1331 Suppose the user requests that / signs have a space to the left but
1333 not to the right. Perltidy will refuse to do this, but if this were
1334 done the result would be
1335 sub print_div {
1337 my ($x,$y)=@_;
1338 print $x /$y;
1339 }
1340 If formatted in this way, the program will not run (at least with
1342 recent versions of perl) because the $x is taken to be a filehandle
1343 and / is assumed to start a quote. In a complex program, there
1344 might happen to be a / which terminates the multiline quote without
1345 a syntax error, allowing the program to run, but not as intended.
1346 Related issues arise with other binary operator symbols, such as +
1348 and -, and in older versions of perl there could be problems with
1349 ternary operators. So to avoid changing program behavior, perltidy
1350 has the simple rule that whitespace around possible filehandles is
1351 left unchanged. Likewise, whitespace around barewords is left
1352 unchanged. The reason is that if the barewords are defined in
1353 other modules, or in code that has not even been written yet,
1354 perltidy will not have seen their prototypes and must treat them
1355 cautiously.
1356 In perltidy this is implemented in the tokenizer by marking token
1358 following a print keyword as a special type Z. When formatting is
1359 being done, whitespace following this token type is generally left
1360 unchanged as a precaution against changing program behavior. This
1361 is excessively conservative but simple and easy to implement.
1362 Keywords which are treated similarly to print include printf, sort,
1363 exec, system. Changes in spacing around parameters following these
1364 keywords may have to be made manually. For example, the space, or
1365 lack of space, after the parameter $foo in the following line will
1366 be unchanged in formatting.
1367 system($foo );
1369 system($foo);
1370 To find if a token is of type Z you can use perltidy -DEBUG. For
1372 the first line above the result is
1373 1: system($foo );
1375 1: kkkkkk{ZZZZb};
1376 which shows that system is type k (keyword) and $foo is type Z.
1378 Note2: Perltidy's whitespace rules are not perfect
1380 Despite these precautions, it is still possible to introduce syntax
1381 errors with some asymmetric whitespace rules, particularly when
1382 call parameters are not placed in containing parens or braces. For
1383 example, the following two lines will be parsed by perl without a
1384 syntax error:
1385 # original programming, syntax ok
1387 my @newkeys = map $_-$nrecs+@data, @oldkeys;
1388 # perltidy default, syntax ok
1390 my @newkeys = map $_ - $nrecs + @data, @oldkeys;
1391 But the following will give a syntax error:
1393 # perltidy -nwrs='-'
1395 my @newkeys = map $_ -$nrecs + @data, @oldkeys;
1396 For another example, the following two lines will be parsed without
1398 syntax error:
1399 # original programming, syntax ok
1401 for my $severity ( reverse $SEVERITY_LOWEST+1 .. $SEVERITY_HIGHEST ) { ... }
1402 # perltidy default, syntax ok
1404 for my $severity ( reverse $SEVERITY_LOWEST + 1 .. $SEVERITY_HIGHEST ) { ... }
1405 But the following will give a syntax error:
1407 # perltidy -nwrs='+', syntax error:
1409 for my $severity ( reverse $SEVERITY_LOWEST +1 .. $SEVERITY_HIGHEST ) { ... }
1410 To avoid subtle parsing problems like this, it is best to avoid
1412 spacing a binary operator asymetrically with a space on the left
1413 but not on the right.
1414 Space between specific keywords and opening paren
1416 When an opening paren follows a Perl keyword, no space is
1417 introduced after the keyword, unless it is (by default) one of
1418 these:
1419 my local our and or xor eq ne if else elsif until unless
1421 while for foreach return switch case given when
1422 These defaults can be modified with two commands:
1424 -sak=s or --space-after-keyword=s adds keywords.
1426 -nsak=s or --nospace-after-keyword=s removes keywords.
1428 where s is a list of keywords (in quotes if necessary). For
1430 example,
1431 my ( $a, $b, $c ) = @_; # default
1433 my( $a, $b, $c ) = @_; # -nsak="my local our"
1434 The abbreviation -nsak='*' is equivalent to including all of the
1436 keywords in the above list.
1437 When both -nsak=s and -sak=s commands are included, the -nsak=s
1439 command is executed first. For example, to have space after only
1440 the keywords (my, local, our) you could use -nsak="*" -sak="my
1441 local our".
1442 To put a space after all keywords, see the next item.
1444 Space between all keywords and opening parens
1446 When an opening paren follows a function or keyword, no space is
1447 introduced after the keyword except for the keywords noted in the
1448 previous item. To always put a space between a function or keyword
1449 and its opening paren, use the command:
1450 -skp or --space-keyword-paren
1452 You may also want to use the flag -sfp (next item) too.
1454 Space between all function names and opening parens
1456 When an opening paren follows a function the default and
1457 recommended formatting is not to introduce a space. To cause a
1458 space to be introduced use:
1459 -sfp or --space-function-paren
1461 myfunc( $a, $b, $c ); # default
1463 myfunc ( $a, $b, $c ); # -sfp
1464 You will probably also want to use the flag -skp (previous item)
1466 too.
1467 The reason this is not recommended is that spacing a function paren
1469 can make a program vulnerable to parsing problems by Perl. For
1470 example, the following two-line program will run as written but
1471 will have a syntax error if reformatted with -sfp:
1472 if ( -e filename() ) { print "I'm here\n"; }
1474 sub filename { return $0 }
1475 In this particular case the syntax error can be removed if the line
1477 order is reversed, so that Perl parses 'sub filename' first.
1478 -fpva or --function-paren-vertical-alignment
1480 A side-effect of using the -sfp flag is that the parens may become
1481 vertically aligned. For example,
1482 # perltidy -sfp
1484 myfun ( $aaa, $b, $cc );
1485 mylongfun ( $a, $b, $c );
1486 This is the default behavior. To prevent this alignment use
1488 -nfpva:
1489 # perltidy -sfp -nfpva
1491 myfun ( $aaa, $b, $cc );
1492 mylongfun ( $a, $b, $c );
1493 -spp=n or --space-prototype-paren=n
1495 This flag can be used to control whether a function prototype is
1496 preceded by a space. For example, the following prototype does not
1497 have a space.
1498 sub usage();
1500 This integer n may have the value 0, 1, or 2 as follows:
1502 -spp=0 means no space before the paren
1504 -spp=1 means follow the example of the source code [DEFAULT]
1505 -spp=2 means always put a space before the paren
1506 The default is -spp=1, meaning that a space will be used if and
1508 only if there is one in the source code. Given the above line of
1509 code, the result of applying the different options would be:
1510 sub usage(); # n=0 [no space]
1512 sub usage(); # n=1 [default; follows input]
1513 sub usage (); # n=2 [space]
1514 -kpit=n or --keyword-paren-inner-tightness=n
1516 The space inside of an opening paren, which itself follows a
1517 certain keyword, can be controlled by this parameter. The space on
1518 the inside of the corresponding closing paren will be treated in
1519 the same (balanced) manner. This parameter has precedence over any
1520 other paren spacing rules. The values of n are as follows:
1521 -kpit=0 means always put a space (not tight)
1523 -kpit=1 means ignore this parameter [default]
1524 -kpit=2 means never put a space (tight)
1525 To illustrate, the following snippet is shown formatted in three
1527 ways:
1528 if ( seek( DATA, 0, 0 ) ) { ... } # perltidy (default)
1530 if (seek(DATA, 0, 0)) { ... } # perltidy -pt=2
1531 if ( seek(DATA, 0, 0) ) { ... } # perltidy -pt=2 -kpit=0
1532 In the second case the -pt=2 parameter makes all of the parens
1534 tight. In the third case the -kpit=0 flag causes the space within
1535 the 'if' parens to have a space, since 'if' is one of the keywords
1536 to which the -kpit flag applies by default. The remaining parens
1537 are still tight because of the -pt=2 parameter.
1538 The set of keywords to which this parameter applies are by default
1540 are:
1541 if elsif unless while until for foreach
1543 These can be changed with the parameter -kpitl=s described in the
1545 next section.
1546 -kpitl=string or --keyword-paren-inner-tightness=string
1548 This command can be used to change the keywords to which the the
1549 -kpit=n command applies. The parameter string is a required list
1550 either keywords or functions, which should be placed in quotes if
1551 there are more than one. By itself, this parameter does not cause
1552 any change in spacing, so the -kpit=n command is still required.
1553 For example, the commands "-kpitl="if else while" -kpit=2" will
1555 cause the just the spaces inside parens following 'if', 'else',
1556 and 'while' keywords to follow the tightness value indicated by the
1557 -kpit=2 flag.
1558 -lop or --logical-padding
1560 In the following example some extra space has been inserted on the
1561 second line between the two open parens. This extra space is called
1562 "logical padding" and is intended to help align similar things
1563 vertically in some logical or ternary expressions.
1564 # perltidy [default formatting]
1566 $same =
1567 ( ( $aP eq $bP )
1568 && ( $aS eq $bS )
1569 && ( $aT eq $bT )
1570 && ( $a->{'title'} eq $b->{'title'} )
1571 && ( $a->{'href'} eq $b->{'href'} ) );
1572 Note that this is considered to be a different operation from
1574 "vertical alignment" because space at just one line is being
1575 adjusted, whereas in "vertical alignment" the spaces at all lines
1576 are being adjusted. So it sort of a local version of vertical
1577 alignment.
1578 Here is an example involving a ternary operator:
1580 # perltidy [default formatting]
1582 $bits =
1583 $top > 0xffff ? 32
1584 : $top > 0xff ? 16
1585 : $top > 1 ? 8
1586 : 1;
1587 This behavior is controlled with the flag --logical-padding, which
1589 is set 'on' by default. If it is not desired it can be turned off
1590 using --nological-padding or -nlop. The above two examples become,
1591 with -nlop:
1592 # perltidy -nlop
1594 $same =
1595 ( ( $aP eq $bP )
1596 && ( $aS eq $bS )
1597 && ( $aT eq $bT )
1598 && ( $a->{'title'} eq $b->{'title'} )
1599 && ( $a->{'href'} eq $b->{'href'} ) );
1600 # perltidy -nlop
1602 $bits =
1603 $top > 0xffff ? 32
1604 : $top > 0xff ? 16
1605 : $top > 1 ? 8
1606 : 1;
1607 Trimming whitespace around "qw" quotes
1609 -tqw or --trim-qw provide the default behavior of trimming spaces
1610 around multi-line "qw" quotes and indenting them appropriately.
1611 -ntqw or --notrim-qw cause leading and trailing whitespace around
1613 multi-line "qw" quotes to be left unchanged. This option will not
1614 normally be necessary, but was added for testing purposes, because
1615 in some versions of perl, trimming "qw" quotes changes the syntax
1616 tree.
1617 -sbq=n or --space-backslash-quote=n
1619 lines like
1620 $str1=\"string1";
1622 $str2=\'string2';
1623 can confuse syntax highlighters unless a space is included between
1625 the backslash and the single or double quotation mark.
1626 this can be controlled with the value of n as follows:
1628 -sbq=0 means no space between the backslash and quote
1630 -sbq=1 means follow the example of the source code
1631 -sbq=2 means always put a space between the backslash and quote
1632 The default is -sbq=1, meaning that a space will be used if there
1634 is one in the source code.
1635 Trimming trailing whitespace from lines of POD
1637 -trp or --trim-pod will remove trailing whitespace from lines of
1638 POD. The default is not to do this.
1639 Comment Controls
1641 Perltidy has a number of ways to control the appearance of both block
1642 comments and side comments. The term block comment here refers to a
1643 full-line comment, whereas side comment will refer to a comment which
1644 appears on a line to the right of some code.
1645 -ibc, --indent-block-comments
1647 Block comments normally look best when they are indented to the
1648 same level as the code which follows them. This is the default
1649 behavior, but you may use -nibc to keep block comments left-
1650 justified. Here is an example:
1651 # this comment is indented (-ibc, default)
1653 if ($task) { yyy(); }
1654 The alternative is -nibc:
1656 # this comment is not indented (-nibc)
1658 if ($task) { yyy(); }
1659 See also the next item, -isbc, as well as -sbc, for other ways to
1661 have some indented and some outdented block comments.
1662 -isbc, --indent-spaced-block-comments
1664 If there is no leading space on the line, then the comment will not
1665 be indented, and otherwise it may be.
1666 If both -ibc and -isbc are set, then -isbc takes priority.
1668 -olc, --outdent-long-comments
1670 When -olc is set, lines which are full-line (block) comments longer
1671 than the value maximum-line-length will have their indentation
1672 removed. This is the default; use -nolc to prevent outdenting.
1673 -msc=n, --minimum-space-to-comment=n
1675 Side comments look best when lined up several spaces to the right
1676 of code. Perltidy will try to keep comments at least n spaces to
1677 the right. The default is n=4 spaces.
1678 -fpsc=n, --fixed-position-side-comment=n
1680 This parameter tells perltidy to line up side comments in column
1681 number n whenever possible. The default, n=0, will not do this.
1682 -iscl, --ignore-side-comment-lengths
1684 This parameter causes perltidy to ignore the length of side
1685 comments when setting line breaks. The default, -niscl, is to
1686 include the length of side comments when breaking lines to stay
1687 within the length prescribed by the -l=n maximum line length
1688 parameter. For example, the following long single line would
1689 remain intact with -l=80 and -iscl:
1690 perltidy -l=80 -iscl
1692 $vmsfile =~ s/;[\d\-]*$//; # Clip off version number; we can use a newer version as well
1693 whereas without the -iscl flag the line will be broken:
1695 perltidy -l=80
1697 $vmsfile =~ s/;[\d\-]*$//
1698 ; # Clip off version number; we can use a newer version as well
1699 -hsc, --hanging-side-comments
1701 By default, perltidy tries to identify and align "hanging side
1702 comments", which are something like this:
1703 my $IGNORE = 0; # This is a side comment
1705 # This is a hanging side comment
1706 # And so is this
1707 A comment is considered to be a hanging side comment if (1) it
1709 immediately follows a line with a side comment, or another hanging
1710 side comment, and (2) there is some leading whitespace on the line.
1711 To deactivate this feature, use -nhsc or --nohanging-side-comments.
1712 If block comments are preceded by a blank line, or have no leading
1713 whitespace, they will not be mistaken as hanging side comments.
1714 Closing Side Comments
1716 A closing side comment is a special comment which perltidy can
1717 automatically create and place after the closing brace of a code
1718 block. They can be useful for code maintenance and debugging. The
1719 command -csc (or --closing-side-comments) adds or updates closing
1720 side comments. For example, here is a small code snippet
1721 sub message {
1723 if ( !defined( $_[0] ) ) {
1724 print("Hello, World\n");
1725 }
1726 else {
1727 print( $_[0], "\n" );
1728 }
1729 }
1730 And here is the result of processing with "perltidy -csc":
1732 sub message {
1734 if ( !defined( $_[0] ) ) {
1735 print("Hello, World\n");
1736 }
1737 else {
1738 print( $_[0], "\n" );
1739 }
1740 } ## end sub message
1741 A closing side comment was added for "sub message" in this case,
1743 but not for the "if" and "else" blocks, because they were below the
1744 6 line cutoff limit for adding closing side comments. This limit
1745 may be changed with the -csci command, described below.
1746 The command -dcsc (or --delete-closing-side-comments) reverses this
1748 process and removes these comments.
1749 Several commands are available to modify the behavior of these two
1751 basic commands, -csc and -dcsc:
1752 -csci=n, or --closing-side-comment-interval=n
1754 where "n" is the minimum number of lines that a block must have
1755 in order for a closing side comment to be added. The default
1756 value is "n=6". To illustrate:
1757 # perltidy -csci=2 -csc
1759 sub message {
1760 if ( !defined( $_[0] ) ) {
1761 print("Hello, World\n");
1762 } ## end if ( !defined( $_[0] ))
1763 else {
1764 print( $_[0], "\n" );
1765 } ## end else [ if ( !defined( $_[0] ))
1766 } ## end sub message
1767 Now the "if" and "else" blocks are commented. However, now
1769 this has become very cluttered.
1770 -cscp=string, or --closing-side-comment-prefix=string
1772 where string is the prefix used before the name of the block
1773 type. The default prefix, shown above, is "## end". This
1774 string will be added to closing side comments, and it will also
1775 be used to recognize them in order to update, delete, and
1776 format them. Any comment identified as a closing side comment
1777 will be placed just a single space to the right of its closing
1778 brace.
1779 -cscl=string, or --closing-side-comment-list
1781 where "string" is a list of block types to be tagged with
1782 closing side comments. By default, all code block types
1783 preceded by a keyword or label (such as "if", "sub", and so on)
1784 will be tagged. The -cscl command changes the default list to
1785 be any selected block types; see "Specifying Block Types". For
1786 example, the following command requests that only "sub"'s,
1787 labels, "BEGIN", and "END" blocks be affected by any -csc or
1788 -dcsc operation:
1789 -cscl="sub : BEGIN END"
1791 -csct=n, or --closing-side-comment-maximum-text=n
1793 The text appended to certain block types, such as an "if"
1794 block, is whatever lies between the keyword introducing the
1795 block, such as "if", and the opening brace. Since this might
1796 be too much text for a side comment, there needs to be a limit,
1797 and that is the purpose of this parameter. The default value
1798 is "n=20", meaning that no additional tokens will be appended
1799 to this text after its length reaches 20 characters. Omitted
1800 text is indicated with "...". (Tokens, including sub names,
1801 are never truncated, however, so actual lengths may exceed
1802 this). To illustrate, in the above example, the appended text
1803 of the first block is " ( !defined( $_[0] )...". The existing
1804 limit of "n=20" caused this text to be truncated, as indicated
1805 by the "...". See the next flag for additional control of the
1806 abbreviated text.
1807 -cscb, or --closing-side-comments-balanced
1809 As discussed in the previous item, when the closing-side-
1810 comment-maximum-text limit is exceeded the comment text must be
1811 truncated. Older versions of perltidy terminated with three
1812 dots, and this can still be achieved with -ncscb:
1813 perltidy -csc -ncscb
1815 } ## end foreach my $foo (sort { $b cmp $a ...
1816 However this causes a problem with editors which cannot
1818 recognize comments or are not configured to do so because they
1819 cannot "bounce" around in the text correctly. The -cscb flag
1820 has been added to help them by appending appropriate balancing
1821 structure:
1822 perltidy -csc -cscb
1824 } ## end foreach my $foo (sort { $b cmp $a ... })
1825 The default is -cscb.
1827 -csce=n, or --closing-side-comment-else-flag=n
1829 The default, n=0, places the text of the opening "if" statement
1830 after any terminal "else".
1831 If n=2 is used, then each "elsif" is also given the text of the
1833 opening "if" statement. Also, an "else" will include the text
1834 of a preceding "elsif" statement. Note that this may result
1835 some long closing side comments.
1836 If n=1 is used, the results will be the same as n=2 whenever
1838 the resulting line length is less than the maximum allowed.
1839 -cscb, or --closing-side-comments-balanced
1841 When using closing-side-comments, and the closing-side-comment-
1842 maximum-text limit is exceeded, then the comment text must be
1843 abbreviated. It is terminated with three dots if the -cscb
1844 flag is negated:
1845 perltidy -csc -ncscb
1847 } ## end foreach my $foo (sort { $b cmp $a ...
1848 This causes a problem with older editors which do not recognize
1850 comments because they cannot "bounce" around in the text
1851 correctly. The -cscb flag tries to help them by appending
1852 appropriate terminal balancing structures:
1853 perltidy -csc -cscb
1855 } ## end foreach my $foo (sort { $b cmp $a ... })
1856 The default is -cscb.
1858 -cscw, or --closing-side-comment-warnings
1860 This parameter is intended to help make the initial transition
1861 to the use of closing side comments. It causes two things to
1862 happen if a closing side comment replaces an existing,
1863 different closing side comment: first, an error message will
1864 be issued, and second, the original side comment will be placed
1865 alone on a new specially marked comment line for later
1866 attention.
1867 The intent is to avoid clobbering existing hand-written side
1869 comments which happen to match the pattern of closing side
1870 comments. This flag should only be needed on the first run with
1871 -csc.
1872 Important Notes on Closing Side Comments:
1874 • Closing side comments are only placed on lines terminated with
1876 a closing brace. Certain closing styles, such as the use of
1877 cuddled elses (-ce), preclude the generation of some closing
1878 side comments.
1879 • Please note that adding or deleting of closing side comments
1881 takes place only through the commands -csc or -dcsc. The other
1882 commands, if used, merely modify the behavior of these two
1883 commands.
1884 • It is recommended that the -cscw flag be used along with -csc
1886 on the first use of perltidy on a given file. This will
1887 prevent loss of any existing side comment data which happens to
1888 have the csc prefix.
1889 • Once you use -csc, you should continue to use it so that any
1891 closing side comments remain correct as code changes.
1892 Otherwise, these comments will become incorrect as the code is
1893 updated.
1894 • If you edit the closing side comments generated by perltidy,
1896 you must also change the prefix to be different from the
1897 closing side comment prefix. Otherwise, your edits will be
1898 lost when you rerun perltidy with -csc. For example, you
1899 could simply change "## end" to be "## End", since the test is
1900 case sensitive. You may also want to use the -ssc flag to keep
1901 these modified closing side comments spaced the same as actual
1902 closing side comments.
1903 • Temporarily generating closing side comments is a useful
1905 technique for exploring and/or debugging a perl script,
1906 especially one written by someone else. You can always remove
1907 them with -dcsc.
1908 Static Block Comments
1910 Static block comments are block comments with a special leading
1911 pattern, "##" by default, which will be treated slightly
1912 differently from other block comments. They effectively behave as
1913 if they had glue along their left and top edges, because they stick
1914 to the left edge and previous line when there is no blank spaces in
1915 those places. This option is particularly useful for controlling
1916 how commented code is displayed.
1917 -sbc, --static-block-comments
1919 When -sbc is used, a block comment with a special leading
1920 pattern, "##" by default, will be treated specially.
1921 Comments so identified are treated as follows:
1923 • If there is no leading space on the line, then the comment
1925 will not be indented, and otherwise it may be,
1926 • no new blank line will be inserted before such a comment,
1928 and
1929 • such a comment will never become a hanging side comment.
1931 For example, assuming @month_of_year is left-adjusted:
1933 @month_of_year = ( # -sbc (default)
1935 'Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct',
1936 ## 'Dec', 'Nov'
1937 'Nov', 'Dec');
1938 Without this convention, the above code would become
1940 @month_of_year = ( # -nsbc
1942 'Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct',
1943 ## 'Dec', 'Nov'
1945 'Nov', 'Dec'
1946 );
1947 which is not as clear. The default is to use -sbc. This may
1949 be deactivated with -nsbc.
1950 -sbcp=string, --static-block-comment-prefix=string
1952 This parameter defines the prefix used to identify static block
1953 comments when the -sbc parameter is set. The default prefix is
1954 "##", corresponding to "-sbcp=##". The prefix is actually part
1955 of a perl pattern used to match lines and it must either begin
1956 with "#" or "^#". In the first case a prefix ^\s* will be
1957 added to match any leading whitespace, while in the second case
1958 the pattern will match only comments with no leading
1959 whitespace. For example, to identify all comments as static
1960 block comments, one would use "-sbcp=#". To identify all left-
1961 adjusted comments as static block comments, use "-sbcp='^#'".
1962 Please note that -sbcp merely defines the pattern used to
1964 identify static block comments; it will not be used unless the
1965 switch -sbc is set. Also, please be aware that since this
1966 string is used in a perl regular expression which identifies
1967 these comments, it must enable a valid regular expression to be
1968 formed.
1969 A pattern which can be useful is:
1971 -sbcp=^#{2,}[^\s#]
1973 This pattern requires a static block comment to have at least
1975 one character which is neither a # nor a space. It allows a
1976 line containing only '#' characters to be rejected as a static
1977 block comment. Such lines are often used at the start and end
1978 of header information in subroutines and should not be
1979 separated from the intervening comments, which typically begin
1980 with just a single '#'.
1981 -osbc, --outdent-static-block-comments
1983 The command -osbc will cause static block comments to be
1984 outdented by 2 spaces (or whatever -ci=n has been set to), if
1985 possible.
1986 Static Side Comments
1988 Static side comments are side comments with a special leading
1989 pattern. This option can be useful for controlling how commented
1990 code is displayed when it is a side comment.
1991 -ssc, --static-side-comments
1993 When -ssc is used, a side comment with a static leading
1994 pattern, which is "##" by default, will be spaced only a single
1995 space from previous character, and it will not be vertically
1996 aligned with other side comments.
1997 The default is -nssc.
1999 -sscp=string, --static-side-comment-prefix=string
2001 This parameter defines the prefix used to identify static side
2002 comments when the -ssc parameter is set. The default prefix is
2003 "##", corresponding to "-sscp=##".
2004 Please note that -sscp merely defines the pattern used to
2006 identify static side comments; it will not be used unless the
2007 switch -ssc is set. Also, note that this string is used in a
2008 perl regular expression which identifies these comments, so it
2009 must enable a valid regular expression to be formed.
2010 Skipping Selected Sections of Code
2012 Selected lines of code may be passed verbatim to the output without any
2013 formatting by marking the starting and ending lines with special
2014 comments. There are two options for doing this. The first option is
2015 called --format-skipping or -fs, and the second option is called
2016 --code-skipping or -cs.
2017 In both cases the lines of code will be output without any changes.
2019 The difference is that in --format-skipping perltidy will still parse
2020 the marked lines of code and check for errors, whereas in
2021 --code-skipping perltidy will simply pass the lines to the output
2022 without any checking.
2023 Both of these features are enabled by default and are invoked with
2025 special comment markers. --format-skipping uses starting and ending
2026 markers '#<<<' and '#>>>', like this:
2027 #<<< format skipping: do not let perltidy change my nice formatting
2029 my @list = (1,
2030 1, 1,
2031 1, 2, 1,
2032 1, 3, 3, 1,
2033 1, 4, 6, 4, 1,);
2034 #>>>
2035 --code-skipping uses starting and ending markers '#<<V' and '#>>V',
2037 like this:
2038 #<<V code skipping: perltidy will pass this verbatim without error checking
2040 token ident_digit {
2042 [ [ <?word> | _ | <?digit> ] <?ident_digit>
2043 | <''>
2044 ]
2045 };
2046 #>>V
2048 Additional text may appear on the special comment lines provided that
2050 it is separated from the marker by at least one space, as in the above
2051 examples.
2052 Any number of code-skipping or format-skipping sections may appear in a
2054 file. If an opening code-skipping or format-skipping comment is not
2055 followed by a corresponding closing comment, then skipping continues to
2056 the end of the file. If a closing code-skipping or format-skipping
2057 comment appears in a file but does not follow a corresponding opening
2058 comment, then it is treated as an ordinary comment without any special
2059 meaning.
2060 It is recommended to use --code-skipping only if you need to hide a
2062 block of an extended syntax which would produce errors if parsed by
2063 perltidy, and use --format-skipping otherwise. This is because the
2064 --format-skipping option provides the benefits of error checking, and
2065 there are essentially no limitations on which lines to which it can be
2066 applied. The --code-skipping option, on the other hand, does not do
2067 error checking and its use is more restrictive because the code which
2068 remains, after skipping the marked lines, must be syntactically correct
2069 code with balanced containers.
2070 These features should be used sparingly to avoid littering code with
2072 markers, but they can be helpful for working around occasional
2073 problems.
2074 Note that it may be possible to avoid the use of --format-skipping for
2076 the specific case of a comma-separated list of values, as in the above
2077 example, by simply inserting a blank or comment somewhere between the
2078 opening and closing parens. See the section "Controlling List
2079 Formatting".
2080 The following sections describe the available controls for these
2082 options. They should not normally be needed.
2083 -fs, --format-skipping
2085 As explained above, this flag, which is enabled by default, causes
2086 any code between special beginning and ending comment markers to be
2087 passed to the output without formatting. The code between the
2088 comments is still checked for errors however. The default
2089 beginning marker is #<<< and the default ending marker is #>>>.
2090 Format skipping begins when a format skipping beginning comment is
2092 seen and continues until a format-skipping ending comment is found.
2093 This feature can be disabled with -nfs. This should not normally
2095 be necessary.
2096 -fsb=string, --format-skipping-begin=string
2098 This and the next parameter allow the special beginning and ending
2099 comments to be changed. However, it is recommended that they only
2100 be changed if there is a conflict between the default values and
2101 some other use. If they are used, it is recommended that they only
2102 be entered in a .perltidyrc file, rather than on a command line.
2103 This is because properly escaping these parameters on a command
2104 line can be difficult.
2105 If changed comment markers do not appear to be working, use the
2107 -log flag and examine the .LOG file to see if and where they are
2108 being detected.
2109 The -fsb=string parameter may be used to change the beginning
2111 marker for format skipping. The default is equivalent to
2112 -fsb='#<<<'. The string that you enter must begin with a # and
2113 should be in quotes as necessary to get past the command shell of
2114 your system. It is actually the leading text of a pattern that is
2115 constructed by appending a '\s', so you must also include
2116 backslashes for characters to be taken literally rather than as
2117 patterns.
2118 Some examples show how example strings become patterns:
2120 -fsb='#\{\{\{' becomes /^#\{\{\{\s/ which matches #{{{ but not #{{{{
2122 -fsb='#\*\*' becomes /^#\*\*\s/ which matches #** but not #***
2123 -fsb='#\*{2,}' becomes /^#\*{2,}\s/ which matches #** and #*****
2124 -fse=string, --format-skipping-end=string
2126 The -fse=string is the corresponding parameter used to change the
2127 ending marker for format skipping. The default is equivalent to
2128 -fse='#<<<'.
2129 The beginning and ending strings may be the same, but it is
2131 preferable to make them different for clarity.
2132 -cs, --code-skipping
2134 As explained above, this flag, which is enabled by default, causes
2135 any code between special beginning and ending comment markers to be
2136 directly passed to the output without any error checking or
2137 formatting. Essentially, perltidy treats it as if it were a block
2138 of arbitrary text. The default beginning marker is #<<V and the
2139 default ending marker is #>>V.
2140 This feature can be disabled with -ncs. This should not normally
2142 be necessary.
2143 -csb=string, --code-skipping-begin=string
2145 This may be used to change the beginning comment for a
2146 --code-skipping section, and its use is similar to the -fsb=string.
2147 The default is equivalent to -csb='#<<V'.
2148 -cse=string, --code-skipping-end=string
2150 This may be used to change the ending comment for a --code-skipping
2151 section, and its use is similar to the -fse=string. The default is
2152 equivalent to -cse='#>>V'.
2153 Line Break Control
2155 The parameters in this section control breaks after non-blank lines of
2156 code. Blank lines are controlled separately by parameters in the
2157 section "Blank Line Control".
2158 -fnl, --freeze-newlines
2160 If you do not want any changes to the line breaks within lines of
2161 code in your script, set -fnl, and they will remain fixed, and the
2162 rest of the commands in this section and sections "Controlling List
2163 Formatting", "Retaining or Ignoring Existing Line Breaks". You may
2164 want to use -noll with this.
2165 Note: If you also want to keep your blank lines exactly as they
2167 are, you can use the -fbl flag which is described in the section
2168 "Blank Line Control".
2169 -ce, --cuddled-else
2171 Enable the "cuddled else" style, in which "else" and "elsif" are
2172 follow immediately after the curly brace closing the previous
2173 block. The default is not to use cuddled elses, and is indicated
2174 with the flag -nce or --nocuddled-else. Here is a comparison of
2175 the alternatives:
2176 # -ce
2178 if ($task) {
2179 yyy();
2180 } else {
2181 zzz();
2182 }
2183 # -nce (default)
2185 if ($task) {
2186 yyy();
2187 }
2188 else {
2189 zzz();
2190 }
2191 In this example the keyword else is placed on the same line which
2193 begins with the preceding closing block brace and is followed by
2194 its own opening block brace on the same line. Other keywords and
2195 function names which are formatted with this "cuddled" style are
2196 elsif, continue, catch, finally.
2197 Other block types can be formatted by specifying their names on a
2199 separate parameter -cbl, described in a later section.
2200 Cuddling between a pair of code blocks requires that the closing
2202 brace of the first block start a new line. If this block is
2203 entirely on one line in the input file, it is necessary to decide
2204 if it should be broken to allow cuddling. This decision is
2205 controlled by the flag -cbo=n discussed below. The default and
2206 recommended value of -cbo=1 bases this decision on the first block
2207 in the chain. If it spans multiple lines then cuddling is made and
2208 continues along the chain, regardless of the sizes of subsequent
2209 blocks. Otherwise, short lines remain intact.
2210 So for example, the -ce flag would not have any effect if the above
2212 snippet is rewritten as
2213 if ($task) { yyy() }
2215 else { zzz() }
2216 If the first block spans multiple lines, then cuddling can be done
2218 and will continue for the subsequent blocks in the chain, as
2219 illustrated in the previous snippet.
2220 If there are blank lines between cuddled blocks they will be
2222 eliminated. If there are comments after the closing brace where
2223 cuddling would occur then cuddling will be prevented. If this
2224 occurs, cuddling will restart later in the chain if possible.
2225 -cb, --cuddled-blocks
2227 This flag is equivalent to -ce.
2228 -cbl, --cuddled-block-list
2230 The built-in default cuddled block types are else, elsif, continue,
2231 catch, finally.
2232 Additional block types to which the -cuddled-blocks style applies
2234 can be defined by this parameter. This parameter is a character
2235 string, giving a list of block types separated by commas or spaces.
2236 For example, to cuddle code blocks of type sort, map and grep, in
2237 addition to the default types, the string could be set to
2238 -cbl="sort map grep"
2240 or equivalently
2242 -cbl=sort,map,grep
2244 Note however that these particular block types are typically short
2246 so there might not be much opportunity for the cuddled format
2247 style.
2248 Using commas avoids the need to protect spaces with quotes.
2250 As a diagnostic check, the flag --dump-cuddled-block-list or -dcbl
2252 can be used to view the hash of values that are generated by this
2253 flag.
2254 Finally, note that the -cbl flag by itself merely specifies which
2256 blocks are formatted with the cuddled format. It has no effect
2257 unless this formatting style is activated with -ce.
2258 -cblx, --cuddled-block-list-exclusive
2260 When cuddled else formatting is selected with -ce, setting this
2261 flag causes perltidy to ignore its built-in defaults and rely
2262 exclusively on the block types specified on the -cbl flag described
2263 in the previous section. For example, to avoid using cuddled catch
2264 and finally, which among in the defaults, the following set of
2265 parameters could be used:
2266 perltidy -ce -cbl='else elsif continue' -cblx
2268 -cbo=n, --cuddled-break-option=n
2270 Cuddled formatting is only possible between a pair of code blocks
2271 if the closing brace of the first block starts a new line. If a
2272 block is encountered which is entirely on a single line, and
2273 cuddled formatting is selected, it is necessary to make a decision
2274 as to whether or not to "break" the block, meaning to cause it to
2275 span multiple lines. This parameter controls that decision. The
2276 options are:
2277 cbo=0 Never force a short block to break.
2279 cbo=1 If the first of a pair of blocks is broken in the input file,
2280 then break the second [DEFAULT].
2281 cbo=2 Break open all blocks for maximal cuddled formatting.
2282 The default and recommended value is cbo=1. With this value, if
2284 the starting block of a chain spans multiple lines, then a cascade
2285 of breaks will occur for remaining blocks causing the entire chain
2286 to be cuddled.
2287 The option cbo=0 can produce erratic cuddling if there are numerous
2289 one-line blocks.
2290 The option cbo=2 produces maximal cuddling but will not allow any
2292 short blocks.
2293 -bl, --opening-brace-on-new-line, or --brace-left
2295 Use the flag -bl to place an opening block brace on a new line:
2296 if ( $input_file eq '-' )
2298 {
2299 ...
2300 }
2301 By default it applies to all structural blocks except sort map grep
2303 eval and anonymous subs.
2304 The default is -nbl which places an opening brace on the same line
2306 as the keyword introducing it if possible. For example,
2307 # default
2309 if ( $input_file eq '-' ) {
2310 ...
2311 }
2312 When -bl is set, the blocks to which this applies can be controlled
2314 with the parameters --brace-left-list and
2315 -brace-left-exclusion-list described in the next sections.
2316 -bll=s, --brace-left-list=s
2318 Use this parameter to change the types of block braces for which
2319 the -bl flag applies; see "Specifying Block Types". For example,
2320 -bll='if elsif else sub' would apply it to only "if/elsif/else" and
2321 named sub blocks. The default is all blocks, -bll='*'.
2322 -blxl=s, --brace-left-exclusion-list=s
2324 Use this parameter to exclude types of block braces for which the
2325 -bl flag applies; see "Specifying Block Types". For example, the
2326 default settings -bll='*' and -blxl='sort map grep eval asub' mean
2327 all blocks except sort map grep eval and anonymous sub blocks.
2328 Note that the lists -bll=s and -blxl=s control the behavior of the
2330 -bl flag but have no effect unless the -bl flag is set.
2331 -sbl, --opening-sub-brace-on-new-line
2333 The flag -sbl provides a shortcut way to turn on -bl just for named
2334 subs. The same effect can be achieved by turning on -bl with the
2335 block list set as -bll='sub'.
2336 For example,
2338 perltidy -sbl
2340 produces this result:
2342 sub message
2344 {
2345 if (!defined($_[0])) {
2346 print("Hello, World\n");
2347 }
2348 else {
2349 print($_[0], "\n");
2350 }
2351 }
2352 This flag is negated with -nsbl, which is the default.
2354 -asbl, --opening-anonymous-sub-brace-on-new-line
2356 The flag -asbl is like the -sbl flag except that it applies to
2357 anonymous sub's instead of named subs. For example
2358 perltidy -asbl
2360 produces this result:
2362 $a = sub
2364 {
2365 if ( !defined( $_[0] ) ) {
2366 print("Hello, World\n");
2367 }
2368 else {
2369 print( $_[0], "\n" );
2370 }
2371 };
2372 This flag is negated with -nasbl, and the default is -nasbl.
2374 -bli, --brace-left-and-indent
2376 The flag -bli is similar to the -bl flag but in addition it causes
2377 one unit of continuation indentation ( see -ci ) to be placed
2378 before an opening and closing block braces.
2379 For example, perltidy -bli gives
2381 if ( $input_file eq '-' )
2383 {
2384 important_function();
2385 }
2386 By default, this extra indentation occurs for block types: if,
2388 elsif, else, unless, while, for, foreach, do, and also named subs
2389 and blocks preceded by a label. The next item shows how to change
2390 this.
2391 Note: The -bli flag is similar to the -bl flag, with the difference
2393 being that braces get indented. But these two flags are
2394 implemented independently, and have different default settings for
2395 historical reasons. If desired, a mixture of effects can be
2396 achieved if desired by turning them both on with different -list
2397 settings. In the event that both settings are selected for a
2398 certain block type, the -bli style has priority.
2399 -blil=s, --brace-left-and-indent-list=s
2401 Use this parameter to change the types of block braces for which
2402 the -bli flag applies; see "Specifying Block Types".
2403 The default is -blil='if else elsif unless while for foreach do :
2405 sub'.
2406 -blixl=s, --brace-left-and-indent-exclusion-list=s
2408 Use this parameter to exclude types of block braces for which the
2409 -bli flag applies; see "Specifying Block Types".
2410 This might be useful in conjunction with selecting all blocks
2412 -blil='*'. The default setting is -blixl=' ', which does not
2413 exclude any blocks.
2414 Note that the two parameters -blil and -blixl control the behavior
2416 of the -bli flag but have no effect unless the -bli flag is set.
2417 -bar, --opening-brace-always-on-right
2419 The default style, -nbl places the opening code block brace on a
2420 new line if it does not fit on the same line as the opening
2421 keyword, like this:
2422 if ( $bigwasteofspace1 && $bigwasteofspace2
2424 || $bigwasteofspace3 && $bigwasteofspace4 )
2425 {
2426 big_waste_of_time();
2427 }
2428 To force the opening brace to always be on the right, use the -bar
2430 flag. In this case, the above example becomes
2431 if ( $bigwasteofspace1 && $bigwasteofspace2
2433 || $bigwasteofspace3 && $bigwasteofspace4 ) {
2434 big_waste_of_time();
2435 }
2436 A conflict occurs if both -bl and -bar are specified.
2438 -otr, --opening-token-right and related flags
2440 The -otr flag is a hint that perltidy should not place a break
2441 between a comma and an opening token. For example:
2442 # default formatting
2444 push @{ $self->{$module}{$key} },
2445 {
2446 accno => $ref->{accno},
2447 description => $ref->{description}
2448 };
2449 # perltidy -otr
2451 push @{ $self->{$module}{$key} }, {
2452 accno => $ref->{accno},
2453 description => $ref->{description}
2454 };
2455 The flag -otr is actually an abbreviation for three other flags
2457 which can be used to control parens, hash braces, and square
2458 brackets separately if desired:
2459 -opr or --opening-paren-right
2461 -ohbr or --opening-hash-brace-right
2462 -osbr or --opening-square-bracket-right
2463 -bbhb=n, --break-before-hash-brace=n and related flags
2465 When a list of items spans multiple lines, the default formatting
2466 is to place the opening brace (or other container token) at the end
2467 of the starting line, like this:
2468 $romanNumerals = {
2470 one => 'I',
2471 two => 'II',
2472 three => 'III',
2473 four => 'IV',
2474 };
2475 This flag can change the default behavior to cause a line break to
2477 be placed before the opening brace according to the value given to
2478 the integer n:
2479 -bbhb=0 never break [default]
2481 -bbhb=1 stable: break if the input script had a break
2482 -bbhb=2 break if list is 'complex' (see note below)
2483 -bbhb=3 always break
2484 For example,
2486 # perltidy -bbhb=3
2488 $romanNumerals =
2489 {
2490 one => 'I',
2491 two => 'II',
2492 three => 'III',
2493 four => 'IV',
2494 };
2495 There are several points to note about this flag:
2497 • This parameter only applies if the opening brace is preceded by
2499 an '=' or '=>'.
2500 • This parameter only applies if the contents of the container
2502 looks like a list. The contents need to contain some commas or
2503 '=>'s at the next interior level to be considered a list.
2504 • For the n=2 option, a list is considered 'complex' if it is
2506 part of a nested list structure which spans multiple lines in
2507 the input file.
2508 • If multiple opening tokens have been 'welded' together with the
2510 -wn parameter, then this parameter has no effect.
2511 • The indentation of the braces will normally be one level of
2513 continuation indentation by default. This can be changed with
2514 the parameter -bbhbi=n in the next section.
2515 • Similar flags for controlling parens and square brackets are
2517 given in the subsequent section.
2518 -bbhbi=n, --break-before-hash-brace-and-indent=n
2520 This flag is a companion to -bbhb=n for controlling the indentation
2521 of an opening hash brace which is placed on a new line by that
2522 parameter. The indentation is as follows:
2523 -bbhbi=0 one continuation level [default]
2525 -bbhbi=1 outdent by one continuation level
2526 -bbhbi=2 indent one full indentation level
2527 For example:
2529 # perltidy -bbhb=3 -bbhbi=1
2531 $romanNumerals =
2532 {
2533 one => 'I',
2534 two => 'II',
2535 three => 'III',
2536 four => 'IV',
2537 };
2538 # perltidy -bbhb=3 -bbhbi=2
2540 $romanNumerals =
2541 {
2542 one => 'I',
2543 two => 'II',
2544 three => 'III',
2545 four => 'IV',
2546 };
2547 Note that this parameter has no effect unless -bbhb=n is also set.
2549 -bbsb=n, --break-before-square-bracket=n
2551 This flag is similar to the flag described above, except it applies
2552 to lists contained within square brackets.
2553 -bbsb=0 never break [default]
2555 -bbsb=1 stable: break if the input script had a break
2556 -bbsb=2 break if list is 'complex' (part of nested list structure)
2557 -bbsb=3 always break
2558 -bbsbi=n, --break-before-square-bracket-and-indent=n
2560 This flag is a companion to -bbsb=n for controlling the indentation
2561 of an opening square bracket which is placed on a new line by that
2562 parameter. The indentation is as follows:
2563 -bbsbi=0 one continuation level [default]
2565 -bbsbi=1 outdent by one continuation level
2566 -bbsbi=2 indent one full indentation level
2567 -bbp=n, --break-before-paren=n
2569 This flag is similar to -bbhb=n, described above, except it applies
2570 to lists contained within parens.
2571 -bbp=0 never break [default]
2573 -bbp=1 stable: break if the input script had a break
2574 -bpb=2 break if list is 'complex' (part of nested list structure)
2575 -bbp=3 always break
2576 -bbpi=n, --break-before-paren-and-indent=n
2578 This flag is a companion to -bbp=n for controlling the indentation
2579 of an opening paren which is placed on a new line by that
2580 parameter. The indentation is as follows:
2581 -bbpi=0 one continuation level [default]
2583 -bbpi=1 outdent by one continuation level
2584 -bbpi=2 indent one full indentation level
2585 -wn, --weld-nested-containers
2587 The -wn flag causes closely nested pairs of opening and closing
2588 container symbols (curly braces, brackets, or parens) to be
2589 "welded" together, meaning that they are treated as if combined
2590 into a single unit, with the indentation of the innermost code
2591 reduced to be as if there were just a single container symbol.
2592 For example:
2594 # default formatting
2596 do {
2597 {
2598 next if $x == $y;
2599 }
2600 } until $x++ > $z;
2601 # perltidy -wn
2603 do { {
2604 next if $x == $y;
2605 } } until $x++ > $z;
2606 When this flag is set perltidy makes a preliminary pass through the
2608 file and identifies all nested pairs of containers. To qualify as
2609 a nested pair, the closing container symbols must be immediately
2610 adjacent and the opening symbols must either (1) be adjacent as in
2611 the above example, or (2) have an anonymous sub declaration
2612 following an outer opening container symbol which is not a code
2613 block brace, or (3) have an outer opening paren separated from the
2614 inner opening symbol by any single non-container symbol or
2615 something that looks like a function evaluation, as illustrated in
2616 the next examples.
2617 Any container symbol may serve as both the inner container of one
2619 pair and as the outer container of an adjacent pair. Consequently,
2620 any number of adjacent opening or closing symbols may join together
2621 in weld. For example, here are three levels of wrapped function
2622 calls:
2623 # default formatting
2625 my (@date_time) = Localtime(
2626 Date_to_Time(
2627 Add_Delta_DHMS(
2628 $year, $month, $day, $hour, $minute, $second,
2629 '0', $offset, '0', '0'
2630 )
2631 )
2632 );
2633 # perltidy -wn
2635 my (@date_time) = Localtime( Date_to_Time( Add_Delta_DHMS(
2636 $year, $month, $day, $hour, $minute, $second,
2637 '0', $offset, '0', '0'
2638 ) ) );
2639 Notice how the indentation of the inner lines are reduced by two
2641 levels in this case. This example also shows the typical result of
2642 this formatting, namely it is a sandwich consisting of an initial
2643 opening layer, a central section of any complexity forming the
2644 "meat" of the sandwich, and a final closing layer. This
2645 predictable structure helps keep the compacted structure readable.
2646 The inner sandwich layer is required to be at least one line thick.
2648 If this cannot be achieved, welding does not occur. This
2649 constraint can cause formatting to take a couple of iterations to
2650 stabilize when it is first applied to a script. The -conv flag can
2651 be used to insure that the final format is achieved in a single
2652 run.
2653 Here is an example illustrating a welded container within a welded
2655 containers:
2656 # default formatting
2658 $x->badd(
2659 bmul(
2660 $class->new(
2661 abs(
2662 $sx * int( $xr->numify() ) & $sy * int( $yr->numify() )
2663 )
2664 ),
2665 $m
2666 )
2667 );
2668 # perltidy -wn
2670 $x->badd( bmul(
2671 $class->new( abs(
2672 $sx * int( $xr->numify() ) & $sy * int( $yr->numify() )
2673 ) ),
2674 $m
2675 ) );
2676 The welded closing tokens are by default on a separate line but
2678 this can be modified with the -vtc=n flag (described in the next
2679 section). For example, the same example adding -vtc=2 is
2680 # perltidy -wn -vtc=2
2682 $x->badd( bmul(
2683 $class->new( abs(
2684 $sx * int( $xr->numify() ) & $sy * int( $yr->numify() ) ) ),
2685 $m ) );
2686 This format option is quite general but there are some limitations.
2688 One limitation is that any line length limit still applies and can
2690 cause long welded sections to be broken into multiple lines.
2691 Another limitation is that an opening symbol which delimits quoted
2693 text cannot be included in a welded pair. This is because quote
2694 delimiters are treated specially in perltidy.
2695 Finally, the stacking of containers defined by this flag have
2697 priority over any other container stacking flags. This is because
2698 any welding is done first.
2699 -wnxl=s, --weld-nested-exclusion-list
2701 The -wnxl=s flag provides some control over the types of containers
2702 which can be welded. The -wn flag by default is "greedy" in
2703 welding adjacent containers. If it welds more types of containers
2704 than desired, this flag provides a capability to reduce the amount
2705 of welding by specifying a list of things which should not be
2706 welded.
2707 The logic in perltidy to apply this is straightforward. As each
2709 container token is being considered for joining a weld, any
2710 exclusion rules are consulted and used to reject the weld if
2711 necessary.
2712 This list is a string with space-separated items. Each item
2714 consists of up to three pieces of information: (1) an optional
2715 position, (2) an optional preceding type, and (3) a container type.
2716 The only required piece of information is a container type, which
2718 is one of '(', '[', '{' or 'q'. The first three of these are
2719 container tokens and the last represents a quoted list. For
2720 example the string
2721 -wnxl='[ { q'
2723 means do NOT include square-bracets, braces, or quotes in any
2725 welds. The only unspecified container is '(', so this string means
2726 that only welds involving parens will be made.
2727 To illustrate, following welded snippet consists of a chain of
2729 three welded containers with types '(' '[' and 'q':
2730 # perltidy -wn
2732 skip_symbols( [ qw(
2733 Perl_dump_fds
2734 Perl_ErrorNo
2735 Perl_GetVars
2736 PL_sys_intern
2737 ) ] );
2738 Even though the qw term uses parens as the quote delimiter, it has
2740 a special type 'q' here. If it appears in a weld it always appears
2741 at the end of the welded chain.
2742 Any of the container types '[', '{', and '(' may be prefixed with a
2744 position indicator which is either '^', to indicate the first token
2745 of a welded sequence, or '.', to indicate an interior token of a
2746 welded sequence. (Since a quoted string 'q' always ends a chain it
2747 does need a position indicator).
2748 For example, if we do not want a sequence of welded containers to
2750 start with a square bracket we could use
2751 -wnxl='^['
2753 In the above snippet, there is a square bracket but it does not
2755 start the chain, so the formatting would be unchanged if it were
2756 formatted with this restriction.
2757 A third optional item of information which can be given is an
2759 alphanumeric letter which is used to limit the selection further
2760 depending on the type of token immediately before the container.
2761 If given, it goes just before the container symbol. The possible
2762 letters are currently 'k', 'K', 'f', 'F', 'w', and 'W', with these
2763 meanings:
2764 'k' matches if the previous nonblank token is a perl builtin keyword (such as 'if', 'while'),
2766 'K' matches if 'k' does not, meaning that the previous token is not a keyword.
2767 'f' matches if the previous token is a function other than a keyword.
2768 'F' matches if 'f' does not.
2769 'w' matches if either 'k' or 'f' match.
2770 'W' matches if 'w' does not.
2771 For example, compare
2773 # perltidy -wn
2775 if ( defined( $_Cgi_Query{
2776 $Config{'methods'}{'authentication'}{'remote'}{'cgi'}{'username'}
2777 } ) )
2778 with
2780 # perltidy -wn -wnxl='^K( {'
2782 if ( defined(
2783 $_Cgi_Query{ $Config{'methods'}{'authentication'}{'remote'}{'cgi'}
2784 {'username'} }
2785 ) )
2786 The first case does maximum welding. In the second case the leading
2788 paren is retained by the rule (it would have been rejected if
2789 preceded by a non-keyword) but the curly brace is rejected by the
2790 rule.
2791 Here are some additional example strings and their meanings:
2793 '^(' - the weld must not start with a paren
2795 '.(' - the second and later tokens may not be parens
2796 '.w(' - the second and later tokens may not keyword or function call parens
2797 '(' - no parens in a weld
2798 '^K(' - exclude a leading paren preceded by a non-keyword
2799 '.k(' - exclude a secondary paren preceded by a keyword
2800 '[ {' - exclude all brackets and braces
2801 '[ ( ^K{' - exclude everything except nested structures like do {{ ... }}
2802 Vertical tightness of non-block curly braces, parentheses, and square
2804 brackets.
2805 These parameters control what shall be called vertical tightness.
2806 Here are the main points:
2807 • Opening tokens (except for block braces) are controlled by
2809 -vt=n, or --vertical-tightness=n, where
2810 -vt=0 always break a line after opening token (default).
2812 -vt=1 do not break unless this would produce more than one
2813 step in indentation in a line.
2814 -vt=2 never break a line after opening token
2815 • You must also use the -lp flag when you use the -vt flag; the
2817 reason is explained below.
2818 • Closing tokens (except for block braces) are controlled by
2820 -vtc=n, or --vertical-tightness-closing=n, where
2821 -vtc=0 always break a line before a closing token (default),
2823 -vtc=1 do not break before a closing token which is followed
2824 by a semicolon or another closing token, and is not in
2825 a list environment.
2826 -vtc=2 never break before a closing token.
2827 -vtc=3 Like -vtc=1 except always break before a closing token
2828 if the corresponding opening token follows an = or =>.
2829 The rules for -vtc=1 and -vtc=3 are designed to maintain a
2831 reasonable balance between tightness and readability in complex
2832 lists.
2833 • Different controls may be applied to different token types, and
2835 it is also possible to control block braces; see below.
2836 • Finally, please note that these vertical tightness flags are
2838 merely hints to the formatter, and it cannot always follow
2839 them. Things which make it difficult or impossible include
2840 comments, blank lines, blocks of code within a list, and
2841 possibly the lack of the -lp parameter. Also, these flags may
2842 be ignored for very small lists (2 or 3 lines in length).
2843 Here are some examples:
2845 # perltidy -lp -vt=0 -vtc=0
2847 %romanNumerals = (
2848 one => 'I',
2849 two => 'II',
2850 three => 'III',
2851 four => 'IV',
2852 );
2853 # perltidy -lp -vt=1 -vtc=0
2855 %romanNumerals = ( one => 'I',
2856 two => 'II',
2857 three => 'III',
2858 four => 'IV',
2859 );
2860 # perltidy -lp -vt=1 -vtc=1
2862 %romanNumerals = ( one => 'I',
2863 two => 'II',
2864 three => 'III',
2865 four => 'IV', );
2866 # perltidy -vtc=3
2868 my_function(
2869 one => 'I',
2870 two => 'II',
2871 three => 'III',
2872 four => 'IV', );
2873 # perltidy -vtc=3
2875 %romanNumerals = (
2876 one => 'I',
2877 two => 'II',
2878 three => 'III',
2879 four => 'IV',
2880 );
2881 In the last example for -vtc=3, the opening paren is preceded by an
2883 equals so the closing paren is placed on a new line.
2884 The difference between -vt=1 and -vt=2 is shown here:
2886 # perltidy -lp -vt=1
2888 $init->add(
2889 mysprintf( "(void)find_threadsv(%s);",
2890 cstring( $threadsv_names[ $op->targ ] )
2891 )
2892 );
2893 # perltidy -lp -vt=2
2895 $init->add( mysprintf( "(void)find_threadsv(%s);",
2896 cstring( $threadsv_names[ $op->targ ] )
2897 )
2898 );
2899 With -vt=1, the line ending in "add(" does not combine with the
2901 next line because the next line is not balanced. This can help
2902 with readability, but -vt=2 can be used to ignore this rule.
2903 The tightest, and least readable, code is produced with both
2905 "-vt=2" and "-vtc=2":
2906 # perltidy -lp -vt=2 -vtc=2
2908 $init->add( mysprintf( "(void)find_threadsv(%s);",
2909 cstring( $threadsv_names[ $op->targ ] ) ) );
2910 Notice how the code in all of these examples collapses vertically
2912 as -vt increases, but the indentation remains unchanged. This is
2913 because perltidy implements the -vt parameter by first formatting
2914 as if -vt=0, and then simply overwriting one output line on top of
2915 the next, if possible, to achieve the desired vertical tightness.
2916 The -lp indentation style has been designed to allow this vertical
2917 collapse to occur, which is why it is required for the -vt
2918 parameter.
2919 The -vt=n and -vtc=n parameters apply to each type of container
2921 token. If desired, vertical tightness controls can be applied
2922 independently to each of the closing container token types.
2923 The parameters for controlling parentheses are -pvt=n or
2925 --paren-vertical-tightness=n, and -pvtc=n or
2926 --paren-vertical-tightness-closing=n.
2927 Likewise, the parameters for square brackets are -sbvt=n or
2929 --square-bracket-vertical-tightness=n, and -sbvtc=n or
2930 --square-bracket-vertical-tightness-closing=n.
2931 Finally, the parameters for controlling non-code block braces are
2933 -bvt=n or --brace-vertical-tightness=n, and -bvtc=n or
2934 --brace-vertical-tightness-closing=n.
2935 In fact, the parameter -vt=n is actually just an abbreviation for
2937 -pvt=n -bvt=n sbvt=n, and likewise -vtc=n is an abbreviation for
2938 -pvtc=n -bvtc=n -sbvtc=n.
2939 -bbvt=n or --block-brace-vertical-tightness=n
2941 The -bbvt=n flag is just like the -vt=n flag but applies to opening
2942 code block braces.
2943 -bbvt=0 break after opening block brace (default).
2945 -bbvt=1 do not break unless this would produce more than one
2946 step in indentation in a line.
2947 -bbvt=2 do not break after opening block brace.
2948 It is necessary to also use either -bl or -bli for this to work,
2950 because, as with other vertical tightness controls, it is
2951 implemented by simply overwriting a line ending with an opening
2952 block brace with the subsequent line. For example:
2953 # perltidy -bli -bbvt=0
2955 if ( open( FILE, "< $File" ) )
2956 {
2957 while ( $File = <FILE> )
2958 {
2959 $In .= $File;
2960 $count++;
2961 }
2962 close(FILE);
2963 }
2964 # perltidy -bli -bbvt=1
2966 if ( open( FILE, "< $File" ) )
2967 { while ( $File = <FILE> )
2968 { $In .= $File;
2969 $count++;
2970 }
2971 close(FILE);
2972 }
2973 By default this applies to blocks associated with keywords if,
2975 elsif, else, unless, for, foreach, sub, while, until, and also with
2976 a preceding label. This can be changed with the parameter
2977 -bbvtl=string, or --block-brace-vertical-tightness-list=string,
2978 where string is a space-separated list of block types. For more
2979 information on the possible values of this string, see "Specifying
2980 Block Types"
2981 For example, if we want to just apply this style to "if", "elsif",
2983 and "else" blocks, we could use "perltidy -bli -bbvt=1 -bbvtl='if
2984 elsif else'".
2985 There is no vertical tightness control for closing block braces;
2987 with one exception they will be placed on separate lines. The
2988 exception is that a cascade of closing block braces may be stacked
2989 on a single line. See -scbb.
2990 -sot, --stack-opening-tokens and related flags
2992 The -sot flag tells perltidy to "stack" opening tokens when
2993 possible to avoid lines with isolated opening tokens.
2994 For example:
2996 # default
2998 $opt_c = Text::CSV_XS->new(
2999 {
3000 binary => 1,
3001 sep_char => $opt_c,
3002 always_quote => 1,
3003 }
3004 );
3005 # -sot
3007 $opt_c = Text::CSV_XS->new( {
3008 binary => 1,
3009 sep_char => $opt_c,
3010 always_quote => 1,
3011 }
3012 );
3013 For detailed control of individual closing tokens the following
3015 controls can be used:
3016 -sop or --stack-opening-paren
3018 -sohb or --stack-opening-hash-brace
3019 -sosb or --stack-opening-square-bracket
3020 -sobb or --stack-opening-block-brace
3021 The flag -sot is an abbreviation for -sop -sohb -sosb.
3023 The flag -sobb is an abbreviation for -bbvt=2 -bbvtl='*'. This
3025 will case a cascade of opening block braces to appear on a single
3026 line, although this an uncommon occurrence except in test scripts.
3027 -sct, --stack-closing-tokens and related flags
3029 The -sct flag tells perltidy to "stack" closing tokens when
3030 possible to avoid lines with isolated closing tokens.
3031 For example:
3033 # default
3035 $opt_c = Text::CSV_XS->new(
3036 {
3037 binary => 1,
3038 sep_char => $opt_c,
3039 always_quote => 1,
3040 }
3041 );
3042 # -sct
3044 $opt_c = Text::CSV_XS->new(
3045 {
3046 binary => 1,
3047 sep_char => $opt_c,
3048 always_quote => 1,
3049 } );
3050 The -sct flag is somewhat similar to the -vtc flags, and in some
3052 cases it can give a similar result. The difference is that the
3053 -vtc flags try to avoid lines with leading opening tokens by
3054 "hiding" them at the end of a previous line, whereas the -sct flag
3055 merely tries to reduce the number of lines with isolated closing
3056 tokens by stacking them but does not try to hide them. For
3057 example:
3058 # -vtc=2
3060 $opt_c = Text::CSV_XS->new(
3061 {
3062 binary => 1,
3063 sep_char => $opt_c,
3064 always_quote => 1, } );
3065 For detailed control of the stacking of individual closing tokens
3067 the following controls can be used:
3068 -scp or --stack-closing-paren
3070 -schb or --stack-closing-hash-brace
3071 -scsb or --stack-closing-square-bracket
3072 -scbb or --stack-closing-block-brace
3073 The flag -sct is an abbreviation for stacking the non-block closing
3075 tokens, -scp -schb -scsb.
3076 Stacking of closing block braces, -scbb, causes a cascade of
3078 isolated closing block braces to be combined into a single line as
3079 in the following example:
3080 # -scbb:
3082 for $w1 (@w1) {
3083 for $w2 (@w2) {
3084 for $w3 (@w3) {
3085 for $w4 (@w4) {
3086 push( @lines, "$w1 $w2 $w3 $w4\n" );
3087 } } } }
3088 To simplify input even further for the case in which both opening
3090 and closing non-block containers are stacked, the flag -sac or
3091 --stack-all-containers is an abbreviation for -sot -sct.
3092 Please note that if both opening and closing tokens are to be
3094 stacked, then the newer flag -weld-nested-containers may be
3095 preferable because it insures that stacking is always done
3096 symmetrically. It also removes an extra level of unnecessary
3097 indentation within welded containers. It is able to do this
3098 because it works on formatting globally rather than locally, as the
3099 -sot and -sct flags do.
3100 -dnl, --delete-old-newlines
3102 By default, perltidy first deletes all old line break locations,
3103 and then it looks for good break points to match the desired line
3104 length. Use -ndnl or --nodelete-old-newlines to force perltidy to
3105 retain all old line break points.
3106 -anl, --add-newlines
3108 By default, perltidy will add line breaks when necessary to create
3109 continuations of long lines and to improve the script appearance.
3110 Use -nanl or --noadd-newlines to prevent any new line breaks.
3111 This flag does not prevent perltidy from eliminating existing line
3113 breaks; see --freeze-newlines to completely prevent changes to line
3114 break points.
3115 Controlling whether perltidy breaks before or after operators
3117 Four command line parameters provide some control over whether a
3118 line break should be before or after specific token types. Two
3119 parameters give detailed control:
3120 -wba=s or --want-break-after=s, and
3122 -wbb=s or --want-break-before=s.
3124 These parameters are each followed by a quoted string, s,
3126 containing a list of token types (separated only by spaces). No
3127 more than one of each of these parameters should be specified,
3128 because repeating a command-line parameter always overwrites the
3129 previous one before perltidy ever sees it.
3130 By default, perltidy breaks after these token types:
3132 % + - * / x != == >= <= =~ !~ < > | &
3133 = **= += *= &= <<= &&= -= /= |= >>= ||= //= .= %= ^= x=
3134 And perltidy breaks before these token types by default:
3136 . << >> -> && || //
3137 To illustrate, to cause a break after a concatenation operator,
3139 '.', rather than before it, the command line would be
3140 -wba="."
3142 As another example, the following command would cause a break
3144 before math operators '+', '-', '/', and '*':
3145 -wbb="+ - / *"
3147 These commands should work well for most of the token types that
3149 perltidy uses (use --dump-token-types for a list). Also try the -D
3150 flag on a short snippet of code and look at the .DEBUG file to see
3151 the tokenization. However, for a few token types there may be
3152 conflicts with hardwired logic which cause unexpected results. One
3153 example is curly braces, which should be controlled with the
3154 parameter bl provided for that purpose.
3155 WARNING Be sure to put these tokens in quotes to avoid having them
3157 misinterpreted by your command shell.
3158 Two additional parameters are available which, though they provide
3160 no further capability, can simplify input are:
3161 -baao or --break-after-all-operators,
3163 -bbao or --break-before-all-operators.
3165 The -baao sets the default to be to break after all of the
3167 following operators:
3168 % + - * / x != == >= <= =~ !~ < > | &
3170 = **= += *= &= <<= &&= -= /= |= >>= ||= //= .= %= ^= x=
3171 . : ? && || and or err xor
3172 and the -bbao flag sets the default to break before all of these
3174 operators. These can be used to define an initial break preference
3175 which can be fine-tuned with the -wba and -wbb flags. For example,
3176 to break before all operators except an = one could use --bbao
3177 -wba='=' rather than listing every single perl operator except = on
3178 a -wbb flag.
3179 bal=n, --break-after-labels=n
3181 This flag controls whether or not a line break occurs after a
3182 label. There are three possible valuse for n:
3183 -bal=0 break if there is a break in the input [DEFAULt]
3185 -bal=1 always break after a label
3186 -bal=2 never break after a label
3187 For example,
3189 # perltidy -bal=1
3191 RETURN:
3192 return;
3193 # perltidy -bal=2
3195 RETURN: return;
3196 Controlling List Formatting
3198 Perltidy attempts to format lists of comma-separated values in tables
3199 which look good. Its default algorithms usually work well, but
3200 sometimes they don't. In this case, there are several methods
3201 available to control list formatting.
3202 A very simple way to prevent perltidy from changing the line breaks
3204 within a comma-separated list of values is to insert a blank line,
3205 comment, or side-comment anywhere between the opening and closing
3206 parens (or braces or brackets). This causes perltidy to skip over its
3207 list formatting logic. (The reason is that any of these items put a
3208 constraint on line breaks, and perltidy needs complete control over
3209 line breaks within a container to adjust a list layout). For example,
3210 let us consider
3211 my @list = (1,
3213 1, 1,
3214 1, 2, 1,
3215 1, 3, 3, 1,
3216 1, 4, 6, 4, 1,);
3217 The default formatting, which allows a maximum line length of 80, will
3219 flatten this down to one line:
3220 # perltidy (default)
3222 my @list = ( 1, 1, 1, 1, 2, 1, 1, 3, 3, 1, 1, 4, 6, 4, 1, );
3223 This formatting loses the nice structure. If we place a side comment
3225 anywhere between the opening and closing parens, the original line
3226 break points are retained. For example,
3227 my @list = (
3229 1, # a side comment forces the original line breakpoints to be kept
3230 1, 1,
3231 1, 2, 1,
3232 1, 3, 3, 1,
3233 1, 4, 6, 4, 1,
3234 );
3235 The side comment can be a single hash symbol without any text. We
3237 could achieve the same result with a blank line or full comment
3238 anywhere between the opening and closing parens. Vertical alignment of
3239 the list items will still occur if possible.
3240 For another possibility see the -fs flag in "Skipping Selected Sections
3242 of Code".
3243 -boc, --break-at-old-comma-breakpoints
3245 The -boc flag is another way to prevent comma-separated lists from
3246 being reformatted. Using -boc on the above example, plus
3247 additional flags to retain the original style, yields
3248 # perltidy -boc -lp -pt=2 -vt=1 -vtc=1
3250 my @list = (1,
3251 1, 1,
3252 1, 2, 1,
3253 1, 3, 3, 1,
3254 1, 4, 6, 4, 1,);
3255 A disadvantage of this flag compared to the methods discussed above
3257 is that all tables in the file must already be nicely formatted.
3258 -mft=n, --maximum-fields-per-table=n
3260 If the computed number of fields for any table exceeds n, then it
3261 will be reduced to n. The default value for n is a large number,
3262 40. While this value should probably be left unchanged as a
3263 general rule, it might be used on a small section of code to force
3264 a list to have a particular number of fields per line, and then
3265 either the -boc flag could be used to retain this formatting, or a
3266 single comment could be introduced somewhere to freeze the
3267 formatting in future applications of perltidy.
3268 # perltidy -mft=2
3270 @month_of_year = (
3271 'Jan', 'Feb',
3272 'Mar', 'Apr',
3273 'May', 'Jun',
3274 'Jul', 'Aug',
3275 'Sep', 'Oct',
3276 'Nov', 'Dec'
3277 );
3278 -cab=n, --comma-arrow-breakpoints=n
3280 A comma which follows a comma arrow, '=>', is given special
3281 consideration. In a long list, it is common to break at all such
3282 commas. This parameter can be used to control how perltidy breaks
3283 at these commas. (However, it will have no effect if old comma
3284 breaks are being forced because -boc is used). The possible values
3285 of n are:
3286 n=0 break at all commas after =>
3288 n=1 stable: break at all commas after => if container is open,
3289 EXCEPT FOR one-line containers
3290 n=2 break at all commas after =>, BUT try to form the maximum
3291 one-line container lengths
3292 n=3 do not treat commas after => specially at all
3293 n=4 break everything: like n=0 but ALSO break a short container with
3294 a => not followed by a comma when -vt=0 is used
3295 n=5 stable: like n=1 but ALSO break at open one-line containers when
3296 -vt=0 is used (default)
3297 For example, given the following single line, perltidy by default
3299 will not add any line breaks because it would break the existing
3300 one-line container:
3301 bless { B => $B, Root => $Root } => $package;
3303 Using -cab=0 will force a break after each comma-arrow item:
3305 # perltidy -cab=0:
3307 bless {
3308 B => $B,
3309 Root => $Root
3310 } => $package;
3311 If perltidy is subsequently run with this container broken, then by
3313 default it will break after each '=>' because the container is now
3314 broken. To reform a one-line container, the parameter -cab=2 could
3315 be used.
3316 The flag -cab=3 can be used to prevent these commas from being
3318 treated specially. In this case, an item such as "01" => 31 is
3319 treated as a single item in a table. The number of fields in this
3320 table will be determined by the same rules that are used for any
3321 other table. Here is an example.
3322 # perltidy -cab=3
3324 my %last_day = (
3325 "01" => 31, "02" => 29, "03" => 31, "04" => 30,
3326 "05" => 31, "06" => 30, "07" => 31, "08" => 31,
3327 "09" => 30, "10" => 31, "11" => 30, "12" => 31
3328 );
3329 Retaining or Ignoring Existing Line Breaks
3331 Several additional parameters are available for controlling the extent
3332 to which line breaks in the input script influence the output script.
3333 In most cases, the default parameter values are set so that, if a
3334 choice is possible, the output style follows the input style. For
3335 example, if a short logical container is broken in the input script,
3336 then the default behavior is for it to remain broken in the output
3337 script.
3338 Most of the parameters in this section would only be required for a
3340 one-time conversion of a script from short container lengths to longer
3341 container lengths. The opposite effect, of converting long container
3342 lengths to shorter lengths, can be obtained by temporarily using a
3343 short maximum line length.
3344 -bol, --break-at-old-logical-breakpoints
3346 By default, if a logical expression is broken at a "&&", "||",
3347 "and", or "or", then the container will remain broken. Also,
3348 breaks at internal keywords "if" and "unless" will normally be
3349 retained. To prevent this, and thus form longer lines, use -nbol.
3350 Please note that this flag does not duplicate old logical
3352 breakpoints. They are merely used as a hint with this flag that a
3353 statement should remain broken. Without this flag, perltidy will
3354 normally try to combine relatively short expressions into a single
3355 line.
3356 For example, given this snippet:
3358 return unless $cmd = $cmd || ($dot
3360 && $Last_Shell) || &prompt('|');
3361 # perltidy -bol [default]
3363 return
3364 unless $cmd = $cmd
3365 || ( $dot
3366 && $Last_Shell )
3367 || &prompt('|');
3368 # perltidy -nbol
3370 return unless $cmd = $cmd || ( $dot && $Last_Shell ) || &prompt('|');
3371 -bom, --break-at-old-method-breakpoints
3373 By default, a method call arrow "->" is considered a candidate for
3374 a breakpoint, but method chains will fill to the line width before
3375 a break is considered. With -bom, breaks before the arrow are
3376 preserved, so if you have preformatted a method chain:
3377 my $q = $rs
3379 ->related_resultset('CDs')
3380 ->related_resultset('Tracks')
3381 ->search({
3382 'track.id' => {-ident => 'none_search.id'},
3383 })->as_query;
3384 It will keep these breaks, rather than become this:
3386 my $q = $rs->related_resultset('CDs')->related_resultset('Tracks')->search({
3388 'track.id' => {-ident => 'none_search.id'},
3389 })->as_query;
3390 This flag will also look for and keep a 'cuddled' style of calls,
3392 in which lines begin with a closing paren followed by a call arrow,
3393 as in this example:
3394 # perltidy -bom -wn
3396 my $q = $rs->related_resultset(
3397 'CDs'
3398 )->related_resultset(
3399 'Tracks'
3400 )->search( {
3401 'track.id' => { -ident => 'none_search.id' },
3402 } )->as_query;
3403 You may want to include the -weld-nested-containers flag in this
3405 case to keep nested braces and parens together, as in the last
3406 line.
3407 -bos, --break-at-old-semicolon-breakpoints
3409 Semicolons are normally placed at the end of a statement. This
3410 means that formatted lines do not normally begin with semicolons.
3411 If the input stream has some lines which begin with semicolons,
3412 these can be retained by setting this flag. For example, consider
3413 the following two-line input snippet:
3414 $z = sqrt($x**2 + $y**2)
3416 ;
3417 The default formatting will be:
3419 $z = sqrt( $x**2 + $y**2 );
3421 The result using perltidy -bos keeps the isolated semicolon:
3423 $z = sqrt( $x**2 + $y**2 )
3425 ;
3426 The default is not to do this, -nbos.
3428 -bok, --break-at-old-keyword-breakpoints
3430 By default, perltidy will retain a breakpoint before keywords which
3431 may return lists, such as "sort" and <map>. This allows chains of
3432 these operators to be displayed one per line. Use -nbok to prevent
3433 retaining these breakpoints.
3434 -bot, --break-at-old-ternary-breakpoints
3436 By default, if a conditional (ternary) operator is broken at a ":",
3437 then it will remain broken. To prevent this, and thereby form
3438 longer lines, use -nbot.
3439 -boa, --break-at-old-attribute-breakpoints
3441 By default, if an attribute list is broken at a ":" in the source
3442 file, then it will remain broken. For example, given the following
3443 code, the line breaks at the ':'s will be retained:
3444 my @field
3446 : field
3447 : Default(1)
3448 : Get('Name' => 'foo') : Set('Name');
3449 If the attributes are on a single line in the source code then they
3451 will remain on a single line if possible.
3452 To prevent this, and thereby always form longer lines, use -nboa.
3454 Keeping old breakpoints at specific token types
3456 It is possible to override the choice of line breaks made by
3457 perltidy, and force it to follow certain line breaks in the input
3458 stream, with these two parameters:
3459 -kbb=s or --keep-old-breakpoints-before=s, and
3461 -kba=s or --keep-old-breakpoints-after=s
3463 These parameters are each followed by a quoted string, s,
3465 containing a list of token types (separated only by spaces). No
3466 more than one of each of these parameters should be specified,
3467 because repeating a command-line parameter always overwrites the
3468 previous one before perltidy ever sees it.
3469 For example, -kbb='=>' means that if an input line begins with a
3471 '=>' then the output script should also have a line break before
3472 that token.
3473 For example, given the script:
3475 method 'foo'
3477 => [ Int, Int ]
3478 => sub {
3479 my ( $self, $x, $y ) = ( shift, @_ );
3480 ...;
3481 };
3482 # perltidy [default]
3484 method 'foo' => [ Int, Int ] => sub {
3485 my ( $self, $x, $y ) = ( shift, @_ );
3486 ...;
3487 };
3488 # perltidy -kbb='=>'
3490 method 'foo'
3491 => [ Int, Int ]
3492 => sub {
3493 my ( $self, $x, $y ) = ( shift, @_ );
3494 ...;
3495 };
3496 For the container tokens '{', '[' and '(' and, their closing
3498 counterparts, use the token symbol. Thus, the command to keep a
3499 break after all opening parens is:
3500 perltidy -kba='('
3502 It is possible to be more specific in matching parentheses by
3504 preceding them with a letter. The possible letters are 'k', 'K',
3505 'f', 'F', 'w', and 'W', with these meanings (these are the same as
3506 used in the --weld-nested-exclusion-list and
3507 --line-up-parentheses-exclusion-list parameters):
3508 'k' matches if the previous nonblank token is a perl builtin keyword (such as 'if', 'while'),
3510 'K' matches if 'k' does not, meaning that the previous token is not a keyword.
3511 'f' matches if the previous token is a function other than a keyword.
3512 'F' matches if 'f' does not.
3513 'w' matches if either 'k' or 'f' match.
3514 'W' matches if 'w' does not.
3515 So for example the the following parameter will keep breaks after
3517 opening function call parens:
3518 perltidy -kba='f('
3520 NOTE: To match all opening curly braces, and no other opening
3522 tokens, please prefix the brace it with an asterisk, like this:
3523 '*{'. Otherwise a warning message will occur. This is necessary to
3524 avoid problems while the input scheme is being updated and
3525 generalized. A single bare curly brace previously matched all
3526 container tokens, and tentatively still does. Likewise, to match
3527 all closing curly braces, and no other closing tokens, use '*}'.
3528 -iob, --ignore-old-breakpoints
3530 Use this flag to tell perltidy to ignore existing line breaks to
3531 the maximum extent possible. This will tend to produce the longest
3532 possible containers, regardless of type, which do not exceed the
3533 line length limit. But please note that this parameter has
3534 priority over all other parameters requesting that certain old
3535 breakpoints be kept.
3536 To illustrate, consider the following input text:
3538 has subcmds => (
3540 is => 'ro',
3541 default => sub { [] },
3542 );
3543 The default formatting will keep the container broken, giving
3545 # perltidy [default]
3547 has subcmds => (
3548 is => 'ro',
3549 default => sub { [] },
3550 );
3551 If old breakpoints are ignored, the list will be flattened:
3553 # perltidy -iob
3555 has subcmds => ( is => 'ro', default => sub { [] }, );
3556 Besides flattening lists, this parameter also applies to lines
3558 broken at certain logical breakpoints such as 'if' and 'or'.
3559 Even if this is parameter is not used globally, it provides a
3561 convenient way to flatten selected lists from within an editor.
3562 -kis, --keep-interior-semicolons
3564 Use the -kis flag to prevent breaking at a semicolon if there was
3565 no break there in the input file. Normally perltidy places a
3566 newline after each semicolon which terminates a statement unless
3567 several statements are contained within a one-line brace block. To
3568 illustrate, consider the following input lines:
3569 dbmclose(%verb_delim); undef %verb_delim;
3571 dbmclose(%expanded); undef %expanded;
3572 The default is to break after each statement, giving
3574 dbmclose(%verb_delim);
3576 undef %verb_delim;
3577 dbmclose(%expanded);
3578 undef %expanded;
3579 With perltidy -kis the multiple statements are retained:
3581 dbmclose(%verb_delim); undef %verb_delim;
3583 dbmclose(%expanded); undef %expanded;
3584 The statements are still subject to the specified value of maximum-
3586 line-length and will be broken if this maximum is exceeded.
3587 Blank Line Control
3589 Blank lines can improve the readability of a script if they are
3590 carefully placed. Perltidy has several commands for controlling the
3591 insertion, retention, and removal of blank lines.
3592 -fbl, --freeze-blank-lines
3594 Set -fbl if you want to the blank lines in your script to remain
3595 exactly as they are. The rest of the parameters in this section
3596 may then be ignored. (Note: setting the -fbl flag is equivalent to
3597 setting -mbl=0 and -kbl=2).
3598 -bbc, --blanks-before-comments
3600 A blank line will be introduced before a full-line comment. This
3601 is the default. Use -nbbc or --noblanks-before-comments to
3602 prevent such blank lines from being introduced.
3603 -blbs=n, --blank-lines-before-subs=n
3605 The parameter -blbs=n requests that least n blank lines precede a
3606 sub definition which does not follow a comment and which is more
3607 than one-line long. The default is <-blbs=1>. BEGIN and END
3608 blocks are included.
3609 The requested number of blanks statement will be inserted
3611 regardless of the value of --maximum-consecutive-blank-lines=n
3612 (-mbl=n) with the exception that if -mbl=0 then no blanks will be
3613 output.
3614 This parameter interacts with the value k of the parameter
3616 --maximum-consecutive-blank-lines=k (-mbl=k) as follows:
3617 1. If -mbl=0 then no blanks will be output. This allows all blanks
3619 to be suppressed with a single parameter. Otherwise,
3620 2. If the number of old blank lines in the script is less than n
3622 then additional blanks will be inserted to make the total n
3623 regardless of the value of -mbl=k.
3624 3. If the number of old blank lines in the script equals or exceeds
3626 n then this parameter has no effect, however the total will not
3627 exceed value specified on the -mbl=k flag.
3628 -blbp=n, --blank-lines-before-packages=n
3630 The parameter -blbp=n requests that least n blank lines precede a
3631 package which does not follow a comment. The default is -blbp=1.
3632 This parameter interacts with the value k of the parameter
3634 --maximum-consecutive-blank-lines=k (-mbl=k) in the same way as
3635 described for the previous item -blbs=n.
3636 -bbs, --blanks-before-subs
3638 For compatibility with previous versions, -bbs or
3639 --blanks-before-subs is equivalent to -blbp=1 and -blbs=1.
3640 Likewise, -nbbs or --noblanks-before-subs is equivalent to -blbp=0
3642 and -blbs=0.
3643 -bbb, --blanks-before-blocks
3645 A blank line will be introduced before blocks of coding delimited
3646 by for, foreach, while, until, and if, unless, in the following
3647 circumstances:
3648 • The block is not preceded by a comment.
3650 • The block is not a one-line block.
3652 • The number of consecutive non-blank lines at the current
3654 indentation depth is at least -lbl (see next section).
3655 This is the default. The intention of this option is to introduce
3657 some space within dense coding. This is negated with -nbbb or
3658 --noblanks-before-blocks.
3659 -lbl=n --long-block-line-count=n
3661 This controls how often perltidy is allowed to add blank lines
3662 before certain block types (see previous section). The default is
3663 8. Entering a value of 0 is equivalent to entering a very large
3664 number.
3665 -blao=i or --blank-lines-after-opening-block=i
3667 This control places a minimum of i blank lines after a line which
3668 ends with an opening block brace of a specified type. By default,
3669 this only applies to the block of a named sub, but this can be
3670 changed (see -blaol below). The default is not to do this (i=0).
3671 Please see the note below on using the -blao and -blbc options.
3673 -blbc=i or --blank-lines-before-closing-block=i
3675 This control places a minimum of i blank lines before a line which
3676 begins with a closing block brace of a specified type. By default,
3677 this only applies to the block of a named sub, but this can be
3678 changed (see -blbcl below). The default is not to do this (i=0).
3679 -blaol=s or --blank-lines-after-opening-block-list=s
3681 The parameter s is a list of block type keywords to which the flag
3682 -blao should apply. The section "Specifying Block Types" explains
3683 how to list block types.
3684 -blbcl=s or --blank-lines-before-closing-block-list=s
3686 This parameter is a list of block type keywords to which the flag
3687 -blbc should apply. The section "Specifying Block Types" explains
3688 how to list block types.
3689 Note on using the -blao and -blbc options.
3691 These blank line controls introduce a certain minimum number of
3692 blank lines in the text, but the final number of blank lines may be
3693 greater, depending on values of the other blank line controls and
3694 the number of old blank lines. A consequence is that introducing
3695 blank lines with these and other controls cannot be exactly undone,
3696 so some experimentation with these controls is recommended before
3697 using them.
3698 For example, suppose that for some reason we decide to introduce
3700 one blank space at the beginning and ending of all blocks. We
3701 could do this using
3702 perltidy -blao=2 -blbc=2 -blaol='*' -blbcl='*' filename
3704 Now suppose the script continues to be developed, but at some later
3706 date we decide we don't want these spaces after all. We might
3707 expect that running with the flags -blao=0 and -blbc=0 will undo
3708 them. However, by default perltidy retains single blank lines, so
3709 the blank lines remain.
3710 We can easily fix this by telling perltidy to ignore old blank
3712 lines by including the added parameter -kbl=0 and rerunning. Then
3713 the unwanted blank lines will be gone. However, this will cause
3714 all old blank lines to be ignored, perhaps even some that were
3715 added by hand to improve formatting. So please be cautious when
3716 using these parameters.
3717 -mbl=n --maximum-consecutive-blank-lines=n
3719 This parameter specifies the maximum number of consecutive blank
3720 lines which will be output within code sections of a script. The
3721 default is n=1. If the input file has more than n consecutive
3722 blank lines, the number will be reduced to n except as noted above
3723 for the -blbp and -blbs parameters. If n=0 then no blank lines
3724 will be output (unless all old blank lines are retained with the
3725 -kbl=2 flag of the next section).
3726 This flag obviously does not apply to pod sections, here-documents,
3728 and quotes.
3729 -kbl=n, --keep-old-blank-lines=n
3731 The -kbl=n flag gives you control over how your existing blank
3732 lines are treated.
3733 The possible values of n are:
3735 n=0 ignore all old blank lines
3737 n=1 stable: keep old blanks, but limited by the value of the B<-mbl=n> flag
3738 n=2 keep all old blank lines, regardless of the value of the B<-mbl=n> flag
3739 The default is n=1.
3741 -sob, --swallow-optional-blank-lines
3743 This is equivalent to kbl=0 and is included for compatibility with
3744 previous versions.
3745 -nsob, --noswallow-optional-blank-lines
3747 This is equivalent to kbl=1 and is included for compatibility with
3748 previous versions.
3749 Controls for blank lines around lines of consecutive keywords
3751 The parameters in this section provide some control over the placement
3753 of blank lines within and around groups of statements beginning with
3754 selected keywords. These blank lines are called here keyword group
3755 blanks, and all of the parameters begin with --keyword-group-blanks*,
3756 or -kgb* for short. The default settings do not employ these controls
3757 but they can be enabled with the following parameters:
3758 -kgbl=s or --keyword-group-blanks-list=s; s is a quoted string of
3760 keywords
3761 -kgbs=s or --keyword-group-blanks-size=s; s gives the number of
3763 keywords required to form a group.
3764 -kgbb=n or --keyword-group-blanks-before=n; n = (0, 1, or 2) controls a
3766 leading blank
3767 -kgba=n or --keyword-group-blanks-after=n; n = (0, 1, or 2) controls a
3769 trailing blank
3770 -kgbi or --keyword-group-blanks-inside is a switch for adding blanks
3772 between subgroups
3773 -kgbd or --keyword-group-blanks-delete is a switch for removing initial
3775 blank lines between keywords
3776 -kgbr=n or --keyword-group-blanks-repeat-count=n can limit the number
3778 of times this logic is applied
3779 In addition, the following abbreviations are available to for
3781 simplified usage:
3782 -kgb or --keyword-group-blanks is short for -kgbb=2 -kgba=2 kgbi
3784 -nkgb or --nokeyword-group-blanks, is short for -kgbb=1 -kgba=1 nkgbi
3786 Before describing the meaning of the parameters in detail let us look
3788 at an example which is formatted with default parameter settings.
3789 print "Entering test 2\n";
3791 use Test;
3792 use Encode qw(from_to encode decode
3793 encode_utf8 decode_utf8
3794 find_encoding is_utf8);
3795 use charnames qw(greek);
3796 my @encodings = grep( /iso-?8859/, Encode::encodings() );
3797 my @character_set = ( '0' .. '9', 'A' .. 'Z', 'a' .. 'z' );
3798 my @source = qw(ascii iso8859-1 cp1250);
3799 my @destiny = qw(cp1047 cp37 posix-bc);
3800 my @ebcdic_sets = qw(cp1047 cp37 posix-bc);
3801 my $str = join( '', map( chr($_), 0x20 .. 0x7E ) );
3802 return unless ($str);
3803 using perltidy -kgb gives:
3805 print "Entering test 2\n";
3807 <----------this blank controlled by -kgbb
3808 use Test;
3809 use Encode qw(from_to encode decode
3810 encode_utf8 decode_utf8
3811 find_encoding is_utf8);
3812 use charnames qw(greek);
3813 <---------this blank controlled by -kgbi
3814 my @encodings = grep( /iso-?8859/, Encode::encodings() );
3815 my @character_set = ( '0' .. '9', 'A' .. 'Z', 'a' .. 'z' );
3816 my @source = qw(ascii iso8859-1 cp1250);
3817 my @destiny = qw(cp1047 cp37 posix-bc);
3818 my @ebcdic_sets = qw(cp1047 cp37 posix-bc);
3819 my $str = join( '', map( chr($_), 0x20 .. 0x7E ) );
3820 <----------this blank controlled by -kgba
3821 return unless ($str);
3822 Blank lines have been introduced around the my and use sequences. What
3824 happened is that the default keyword list includes my and use but not
3825 print and return. So a continuous sequence of nine my and use
3826 statements was located. This number exceeds the default threshold of
3827 five, so blanks were placed before and after the entire group. Then,
3828 since there was also a subsequence of six my lines, a blank line was
3829 introduced to separate them.
3830 Finer control over blank placement can be achieved by using the
3832 individual parameters rather than the -kgb flag. The individual
3833 controls are as follows.
3834 -kgbl=s or --keyword-group-blanks-list=s, where s is a quoted string,
3836 defines the set of keywords which will be formed into groups. The
3837 string is a space separated list of keywords. The default set is
3838 s="use require local our my", but any list of keywords may be used.
3839 Comment lines may also be included in a keyword group, even though they
3840 are not keywords. To include ordinary block comments, include the
3841 symbol BC. To include static block comments (which normally begin with
3842 '##'), include the symbol SBC.
3843 -kgbs=s or --keyword-group-blanks-size=s, where s is a string
3845 describing the number of consecutive keyword statements forming a group
3846 (Note: statements separated by blank lines in the input file are
3847 considered consecutive for purposes of this count). If s is an integer
3848 then it is the minimum number required for a group. A maximum value
3849 may also be given with the format s=min.max, where min is the minimum
3850 number and max is the maximum number, and the min and max values are
3851 separated by one or more dots. No groups will be found if the maximum
3852 is less than the minimum. The maximum is unlimited if not given. The
3853 default is s=5. Some examples:
3854 s min max number for group
3856 3 3 unlimited 3 or more
3857 1.1 1 1 1
3858 1..3 1 3 1 to 3
3859 1.0 1 0 (no match)
3860 There is no really good default value for this parameter. If it is set
3862 too small, then an excessive number of blank lines may be generated.
3863 However, some users may prefer reducing the value somewhat below the
3864 default, perhaps to s=3.
3865 -kgbb=n or --keyword-group-blanks-before=n specifies whether a blank
3867 should appear before the first line of the group, as follows:
3868 n=0 => (delete) an existing blank line will be removed
3870 n=1 => (stable) no change to the input file is made [DEFAULT]
3871 n=2 => (insert) a blank line is introduced if possible
3872 -kgba=n or --keyword-group-blanks-after=n likewise specifies whether a
3874 blank should appear after the last line of the group, using the same
3875 scheme (0=delete, 1=stable, 2=insert).
3876 -kgbi or --keyword-group-blanks-inside controls the insertion of blank
3878 lines between the first and last statement of the entire group. If
3879 there is a continuous run of a single statement type with more than the
3880 minimum threshold number (as specified with -kgbs=s) then this switch
3881 causes a blank line be inserted between this subgroup and the others.
3882 In the example above this happened between the use and my statements.
3883 -kgbd or --keyword-group-blanks-delete controls the deletion of any
3885 blank lines that exist in the the group when it is first scanned. When
3886 statements are initially scanned, any existing blank lines are included
3887 in the collection. Any such orignial blank lines will be deleted
3888 before any other insertions are made when the parameter -kgbd is set.
3889 The default is not to do this, -nkgbd.
3890 -kgbr=n or --keyword-group-blanks-repeat-count=n specifies n, the
3892 maximum number of times this logic will be applied to any file. The
3893 special value n=0 is the same as n=infinity which means it will be
3894 applied to an entire script [Default]. A value n=1 could be used to
3895 make it apply just one time for example. This might be useful for
3896 adjusting just the use statements in the top part of a module for
3897 example.
3898 -kgb or --keyword-group-blanks is an abbreviation equivalent to setting
3900 -kgbb=1 -kgba=1 -kgbi. This turns on keyword group formatting with a
3901 set of default values.
3902 -nkgb or --nokeyword-group-blanks is equivalent to -kgbb=0 -kgba nkgbi.
3904 This flag turns off keyword group blank lines and is the default
3905 setting.
3906 Here are a few notes about the functioning of this technique.
3908 • These parameters are probably more useful as part of a major code
3910 reformatting operation rather than as a routine formatting
3911 operation.
3912 In particular, note that deleting old blank lines with -kgbd is an
3914 irreversible operation so it should be applied with care. Existing
3915 blank lines may be serving an important role in controlling
3916 vertical alignment.
3917 • Conflicts which arise among these kgb* parameters and other blank
3919 line controls are generally resolved by producing the maximum
3920 number of blank lines implied by any parameter.
3921 For example, if the flags --freeze-blank-lines, or
3923 --keep-old-blank-lines=2, are set, then they have priority over any
3924 blank line deletion implied by the -kgb flags of this section, so
3925 no blank lines will be deleted.
3926 For another example, if a keyword group ends at a sub and the flag
3928 kgba=0 requests no blank line there, but we also have
3929 --blank-lines-before-subs=2, then two blank lines will still be
3930 introduced before the sub.
3931 • The introduction of blank lines does not occur if it would conflict
3933 with other input controls or code validity. For example, a blank
3934 line will not be placed within a here-doc or within a section of
3935 code marked with format skipping comments. And in general, a blank
3936 line will only be introduced at the end of a group if the next
3937 statement is a line of code.
3938 • The count which is used to determine the group size is not the
3940 number of lines but rather the total number of keywords which are
3941 found. Individual statements with a certain leading keyword may
3942 continue on multiple lines, but if any of these lines is nested
3943 more than one level deep then that group will be ended.
3944 • The search for groups of lines with similar leading keywords is
3946 based on the input source, not the final formatted source.
3947 Consequently, if the source code is badly formatted, it would be
3948 best to make a first formatting pass without these options.
3949 Styles
3951 A style refers to a convenient collection of existing parameters.
3952 -gnu, --gnu-style
3954 -gnu gives an approximation to the GNU Coding Standards (which do
3955 not apply to perl) as they are sometimes implemented. At present,
3956 this style overrides the default style with the following
3957 parameters:
3958 -lp -bl -noll -pt=2 -bt=2 -sbt=2 -icp
3960 To use this style with -xlp instead of -lp use -gnu -xlp.
3962 -pbp, --perl-best-practices
3964 -pbp is an abbreviation for the parameters in the book Perl Best
3965 Practices by Damian Conway:
3966 -l=78 -i=4 -ci=4 -st -se -vt=2 -cti=0 -pt=1 -bt=1 -sbt=1 -bbt=1 -nsfs -nolq
3968 -wbb="% + - * / x != == >= <= =~ !~ < > | & =
3969 **= += *= &= <<= &&= -= /= |= >>= ||= //= .= %= ^= x="
3970 Please note that this parameter set includes -st and -se flags,
3972 which make perltidy act as a filter on one file only. These can be
3973 overridden by placing -nst and/or -nse after the -pbp parameter.
3974 Also note that the value of continuation indentation, -ci=4, is
3976 equal to the value of the full indentation, -i=4. It is
3977 recommended that the either (1) the parameter -ci=2 be used
3978 instead, or the flag -xci be set. This will help show structure,
3979 particularly when there are ternary statements. The following
3980 snippet illustrates these options.
3981 # perltidy -pbp
3983 $self->{_text} = (
3984 !$section ? ''
3985 : $type eq 'item' ? "the $section entry"
3986 : "the section on $section"
3987 )
3988 . (
3989 $page
3990 ? ( $section ? ' in ' : '' ) . "the $page$page_ext manpage"
3991 : ' elsewhere in this document'
3992 );
3993 # perltidy -pbp -ci=2
3995 $self->{_text} = (
3996 !$section ? ''
3997 : $type eq 'item' ? "the $section entry"
3998 : "the section on $section"
3999 )
4000 . (
4001 $page
4002 ? ( $section ? ' in ' : '' ) . "the $page$page_ext manpage"
4003 : ' elsewhere in this document'
4004 );
4005 # perltidy -pbp -xci
4007 $self->{_text} = (
4008 !$section ? ''
4009 : $type eq 'item' ? "the $section entry"
4010 : "the section on $section"
4011 )
4012 . ( $page
4013 ? ( $section ? ' in ' : '' ) . "the $page$page_ext manpage"
4014 : ' elsewhere in this document'
4015 );
4016 The -xci flag was developed after the -pbp parameters were
4018 published so you need to include it separately.
4019 One-line blocks
4021 There are a few points to note regarding one-line blocks. A one-
4022 line block is something like this,
4023 if ( -e $file ) { print "'$file' exists\n" }
4025 where the contents within the curly braces is short enough to fit
4027 on a single line.
4028 With few exceptions, perltidy retains existing one-line blocks, if
4030 it is possible within the line-length constraint, but it does not
4031 attempt to form new ones. In other words, perltidy will try to
4032 follow the one-line block style of the input file.
4033 If an existing one-line block is longer than the maximum line
4035 length, however, it will be broken into multiple lines. When this
4036 happens, perltidy checks for and adds any optional terminating
4037 semicolon (unless the -nasc option is used) if the block is a code
4038 block.
4039 The main exception is that perltidy will attempt to form new one-
4041 line blocks following the keywords "map", "eval", and "sort",
4042 because these code blocks are often small and most clearly
4043 displayed in a single line.
4044 One-line block rules can conflict with the cuddled-else option.
4046 When the cuddled-else option is used, perltidy retains existing
4047 one-line blocks, even if they do not obey cuddled-else formatting.
4048 Occasionally, when one-line blocks get broken because they exceed
4050 the available line length, the formatting will violate the
4051 requested brace style. If this happens, reformatting the script a
4052 second time should correct the problem.
4053 Sometimes it might be desirable to convert a script to have one-
4055 line blocks whenever possible. Although there is currently no flag
4056 for this, a simple workaround is to execute perltidy twice, once
4057 with the flag -noadd-newlines and then once again with normal
4058 parameters, like this:
4059 cat infile | perltidy -nanl | perltidy >outfile
4061 When executed on this snippet
4063 if ( $? == -1 ) {
4065 die "failed to execute: $!\n";
4066 }
4067 if ( $? == -1 ) {
4068 print "Had enough.\n";
4069 die "failed to execute: $!\n";
4070 }
4071 the result is
4073 if ( $? == -1 ) { die "failed to execute: $!\n"; }
4075 if ( $? == -1 ) {
4076 print "Had enough.\n";
4077 die "failed to execute: $!\n";
4078 }
4079 This shows that blocks with a single statement become one-line
4081 blocks.
4082 -olbs=n, --one-line-block-semicolons=n
4084 This flag controls the placement of semicolons at the end of one-
4085 line blocks. Semicolons are optional before a closing block brace,
4086 and frequently they are omitted at the end of a one-line block
4087 containing just a single statement. By default, perltidy follows
4088 the input file regarding these semicolons, but this behavior can be
4089 controlled by this flag. The values of n are:
4090 n=0 remove terminal semicolons in one-line blocks having a single statement
4092 n=1 stable; keep input file placement of terminal semicolons [DEFAULT ]
4093 n=2 add terminal semicolons in all one-line blocks
4094 Note that the n=2 option has no effect if adding semicolons is
4096 prohibited with the -nasc flag. Also not that while n=2 adds
4097 missing semicolons to all one-line blocks, regardless of
4098 complexity, the n=0 option only removes ending semicolons which
4099 terminate one-line blocks containing just one semicolon. So these
4100 two options are not exact inverses.
4101 -olbn=n, --one-line-block-nesting=n
4103 Nested one-line blocks are lines with code blocks which themselves
4104 contain code blocks. For example, the following line is a nested
4105 one-line block.
4106 foreach (@list) { if ($_ eq $asked_for) { last } ++$found }
4108 The default behavior is to break such lines into multiple lines,
4110 but this behavior can be controlled with this flag. The values of
4111 n are:
4112 n=0 break nested one-line blocks into multiple lines [DEFAULT]
4114 n=1 stable: keep existing nested-one line blocks intact
4115 For the above example, the default formatting (-olbn=0) is
4117 foreach (@list) {
4119 if ( $_ eq $asked_for ) { last }
4120 ++$found;
4121 }
4122 If the parameter -olbn=1 is given, then the line will be left
4124 intact if it is a single line in the source, or it will be broken
4125 into multiple lines if it is broken in multiple lines in the
4126 source.
4127 Controlling Vertical Alignment
4129 Vertical alignment refers to lining up certain symbols in a list of
4130 consecutive similar lines to improve readability. For example, the
4131 "fat commas" are aligned in the following statement:
4132 $data = $pkg->new(
4134 PeerAddr => join( ".", @port[ 0 .. 3 ] ),
4135 PeerPort => $port[4] * 256 + $port[5],
4136 Proto => 'tcp'
4137 );
4138 Vertical alignment can be completely turned off using the -novalign
4140 flag mentioned below. However, vertical alignment can be forced to
4141 stop and restart by selectively introducing blank lines. For example,
4142 a blank has been inserted in the following code to keep somewhat
4143 similar things aligned.
4144 %option_range = (
4146 'format' => [ 'tidy', 'html', 'user' ],
4147 'output-line-ending' => [ 'dos', 'win', 'mac', 'unix' ],
4148 'character-encoding' => [ 'none', 'utf8' ],
4149 'block-brace-tightness' => [ 0, 2 ],
4151 'brace-tightness' => [ 0, 2 ],
4152 'paren-tightness' => [ 0, 2 ],
4153 'square-bracket-tightness' => [ 0, 2 ],
4154 );
4155 Vertical alignment is implemented by locally increasing an existing
4157 blank space to produce alignment with an adjacent line. It cannot
4158 occur if there is no blank space to increase. So if a particular space
4159 is removed by one of the existing controls then vertical alignment
4160 cannot occur. Likewise, if a space is added with one of the controls,
4161 then vertical alignment might occur.
4162 For example,
4164 # perltidy -nwls='=>'
4166 $data = $pkg->new(
4167 PeerAddr=> join( ".", @port[ 0 .. 3 ] ),
4168 PeerPort=> $port[4] * 256 + $port[5],
4169 Proto=> 'tcp'
4170 );
4171 Completely turning off vertical alignment with -novalign
4173 The default is to use vertical alignment, but bertical alignment
4174 can be completely turned of with the -novalign flag.
4175 A lower level of control of vertical alignment is possible with
4177 three parameters -vc, -vsc, and -vbc. These independently control
4178 alignment of code, side comments and block comments. They are
4179 described in the next section.
4180 The parameter -valign is in fact an alias for -vc -vsc -vbc, and
4182 its negative -novalign is an alias for -nvc -nvsc -nvbc.
4183 Controlling code alignment with --valign-code or -vc
4185 The -vc flag enables alignment of code symbols such as =. The
4186 default is -vc. For detailed control of which symbols to align,
4187 see the -valign-exclude-list parameter below.
4188 Controlling side comment alignment with --valign-side-comments or -vsc
4190 The -vsc flag enables alignment of side comments and is enabled by
4191 default. If side comment aligment is disabled with -nvsc they will
4192 appear at a fixed space from the preceding code token. The default
4193 is -vsc
4194 Controlling block comment alignment with --valign-block-comments or
4196 -vbc
4197 When -vbc is enabled, block comments can become aligned for example
4198 if one comment of a consecutive sequence of comments becomes
4199 outdented due a length in excess of the maximum line length. If
4200 this occurs, the entire group of comments will remain aligned and
4201 be outdented by the same amount. This coordinated alignment will
4202 not occur if -nvbc is set. The default is -vbc.
4203 Finer alignment control with --valign-exclusion-list=s or -vxl=s and
4205 --valign-inclusion-list=s or -vil=s
4206 More detailed control of alignment types is available with these
4207 two parameters. Most of the vertical alignments in typical
4208 programs occur at one of the tokens ',', '=', and '=>', but many
4209 other alignments are possible and are given in the following list:
4210 = **= += *= &= <<= &&= -= /= |= >>= ||= //= .= %= ^= x=
4212 { ( ? : , ; => && || ~~ !~~ =~ !~ // <=> ->
4213 if unless and or err for foreach while until
4214 These alignments are all enabled by default, but they can be
4216 selectively disabled by including one or more of these tokens in
4217 the space-separated list valign-exclusion-list=s. For example, the
4218 following would prevent alignment at = and if:
4219 --valign-exclusion-list='= if'
4221 If it is simpler to specify only the token types which are to be
4223 aligned, then include the types which are to be aligned in the list
4224 of --valign-inclusion-list. You may leave the valign-exclusion-
4225 list undefined, or use the special symbol * for the exclusion list.
4226 For example, the following parameters enable alignment only at
4227 commas and 'fat commas':
4228 --valign-inclusion-list=', =>'
4230 --valign-exclusion-list='*' ( this is optional and may be omitted )
4231 These parameter lists should consist of space-separated tokens from
4233 the above list of possible alignment tokens, or a '*'. If an
4234 unrecognized token appears, it is simply ignored. And if a specific
4235 token is entered in both lists by mistake then the exclusion list
4236 has priority.
4237 The default values of these parameters enable all alignments and
4239 are equivalent to
4240 --valign-exclusion-list=' '
4242 --valign-inclusion-list='*'
4243 To illustrate, consider the following snippet with default
4245 formatting
4246 # perltidy
4248 $co_description = ($color) ? 'bold cyan' : ''; # description
4249 $co_prompt = ($color) ? 'bold green' : ''; # prompt
4250 $co_unused = ($color) ? 'on_green' : 'reverse'; # unused
4251 To exclude all alignments except the equals (i.e., include only
4253 equals) we could use:
4254 # perltidy -vil='='
4256 $co_description = ($color) ? 'bold cyan' : ''; # description
4257 $co_prompt = ($color) ? 'bold green' : ''; # prompt
4258 $co_unused = ($color) ? 'on_green' : 'reverse'; # unused
4259 To exclude only the equals we could use:
4261 # perltidy -vxl='='
4263 $co_description = ($color) ? 'bold cyan' : ''; # description
4264 $co_prompt = ($color) ? 'bold green' : ''; # prompt
4265 $co_unused = ($color) ? 'on_green' : 'reverse'; # unused
4266 Notice in this last example that although only the equals alignment
4268 was excluded, the ternary alignments were also lost. This happens
4269 because the vertical aligner sweeps from left-to-right and usually
4270 stops if an important alignment cannot be made for some reason.
4271 But also notice that side comments remain aligned because their
4273 alignment is controlled separately with the parameter
4274 --valign-side_comments described above.
4275 Other Controls
4277 Deleting selected text
4278 Perltidy can selectively delete comments and/or pod documentation.
4279 The command -dac or --delete-all-comments will delete all comments
4280 and all pod documentation, leaving just code and any leading system
4281 control lines.
4282 The command -dp or --delete-pod will remove all pod documentation
4284 (but not comments).
4285 Two commands which remove comments (but not pod) are: -dbc or
4287 --delete-block-comments and -dsc or --delete-side-comments.
4288 (Hanging side comments will be deleted with side comments here.)
4289 The negatives of these commands also work, and are the defaults.
4291 When block comments are deleted, any leading 'hash-bang' will be
4292 retained. Also, if the -x flag is used, any system commands before
4293 a leading hash-bang will be retained (even if they are in the form
4294 of comments).
4295 Writing selected text to a file
4297 When perltidy writes a formatted text file, it has the ability to
4298 also send selected text to a file with a .TEE extension. This text
4299 can include comments and pod documentation.
4300 The command -tac or --tee-all-comments will write all comments and
4302 all pod documentation.
4303 The command -tp or --tee-pod will write all pod documentation (but
4305 not comments).
4306 The commands which write comments (but not pod) are: -tbc or
4308 --tee-block-comments and -tsc or --tee-side-comments. (Hanging
4309 side comments will be written with side comments here.)
4310 The negatives of these commands also work, and are the defaults.
4312 Using a .perltidyrc command file
4314 If you use perltidy frequently, you probably won't be happy until
4315 you create a .perltidyrc file to avoid typing commonly-used
4316 parameters. Perltidy will first look in your current directory for
4317 a command file named .perltidyrc. If it does not find one, it will
4318 continue looking for one in other standard locations.
4319 These other locations are system-dependent, and may be displayed
4321 with the command "perltidy -dpro". Under Unix systems, it will
4322 first look for an environment variable PERLTIDY. Then it will look
4323 for a .perltidyrc file in the home directory, and then for a
4324 system-wide file /usr/local/etc/perltidyrc, and then it will look
4325 for /etc/perltidyrc. Note that these last two system-wide files do
4326 not have a leading dot. Further system-dependent information will
4327 be found in the INSTALL file distributed with perltidy.
4328 Under Windows, perltidy will also search for a configuration file
4330 named perltidy.ini since Windows does not allow files with a
4331 leading period (.). Use "perltidy -dpro" to see the possible
4332 locations for your system. An example might be C:\Documents and
4333 Settings\All Users\perltidy.ini.
4334 Another option is the use of the PERLTIDY environment variable.
4336 The method for setting environment variables depends upon the
4337 version of Windows that you are using. Instructions for Windows 95
4338 and later versions can be found here:
4339 http://www.netmanage.com/000/20021101_005_tcm21-6336.pdf
4341 Under Windows NT / 2000 / XP the PERLTIDY environment variable can
4343 be placed in either the user section or the system section. The
4344 later makes the configuration file common to all users on the
4345 machine. Be sure to enter the full path of the configuration file
4346 in the value of the environment variable. Ex.
4347 PERLTIDY=C:\Documents and Settings\perltidy.ini
4348 The configuration file is free format, and simply a list of
4350 parameters, just as they would be entered on a command line. Any
4351 number of lines may be used, with any number of parameters per
4352 line, although it may be easiest to read with one parameter per
4353 line. Comment text begins with a #, and there must also be a space
4354 before the # for side comments. It is a good idea to put complex
4355 parameters in either single or double quotes.
4356 Here is an example of a .perltidyrc file:
4358 # This is a simple of a .perltidyrc configuration file
4360 # This implements a highly spaced style
4361 -se # errors to standard error output
4362 -w # show all warnings
4363 -bl # braces on new lines
4364 -pt=0 # parens not tight at all
4365 -bt=0 # braces not tight
4366 -sbt=0 # square brackets not tight
4367 The parameters in the .perltidyrc file are installed first, so any
4369 parameters given on the command line will have priority over them.
4370 To avoid confusion, perltidy ignores any command in the .perltidyrc
4372 file which would cause some kind of dump and an exit. These are:
4373 -h -v -ddf -dln -dop -dsn -dtt -dwls -dwrs -ss
4375 There are several options may be helpful in debugging a .perltidyrc
4377 file:
4378 • A very helpful command is --dump-profile or -dpro. It writes a
4380 list of all configuration filenames tested to standard output,
4381 and if a file is found, it dumps the content to standard output
4382 before exiting. So, to find out where perltidy looks for its
4383 configuration files, and which one if any it selects, just
4384 enter
4385 perltidy -dpro
4387 • It may be simplest to develop and test configuration files with
4389 alternative names, and invoke them with -pro=filename on the
4390 command line. Then rename the desired file to .perltidyrc when
4391 finished.
4392 • The parameters in the .perltidyrc file can be switched off with
4394 the -npro option.
4395 • The commands --dump-options, --dump-defaults,
4397 --dump-long-names, and --dump-short-names, all described below,
4398 may all be helpful.
4399 Creating a new abbreviation
4401 A special notation is available for use in a .perltidyrc file for
4402 creating an abbreviation for a group of options. This can be used
4403 to create a shorthand for one or more styles which are frequently,
4404 but not always, used. The notation is to group the options within
4405 curly braces which are preceded by the name of the alias (without
4406 leading dashes), like this:
4407 newword {
4409 -opt1
4410 -opt2
4411 }
4412 where newword is the abbreviation, and opt1, etc, are existing
4414 parameters or other abbreviations. The main syntax requirement is
4415 that the new abbreviation along with its opening curly brace must
4416 begin on a new line. Space before and after the curly braces is
4417 optional.
4418 For a specific example, the following line
4420 oneliner { --maximum-line-length=0 --noadd-newlines --noadd-terminal-newline}
4422 or equivalently with abbreviations
4424 oneliner { -l=0 -nanl -natnl }
4426 could be placed in a .perltidyrc file to temporarily override the
4428 maximum line length with a large value, to temporarily prevent new
4429 line breaks from being added, and to prevent an extra newline
4430 character from being added the file. All other settings in the
4431 .perltidyrc file still apply. Thus it provides a way to format a
4432 long 'one liner' when perltidy is invoked with
4433 perltidy --oneliner ...
4435 (Either "-oneliner" or "--oneliner" may be used).
4437 Skipping leading non-perl commands with -x or --look-for-hash-bang
4439 If your script has leading lines of system commands or other text
4440 which are not valid perl code, and which are separated from the
4441 start of the perl code by a "hash-bang" line, ( a line of the form
4442 "#!...perl" ), you must use the -x flag to tell perltidy not to
4443 parse and format any lines before the "hash-bang" line. This
4444 option also invokes perl with a -x flag when checking the syntax.
4445 This option was originally added to allow perltidy to parse
4446 interactive VMS scripts, but it should be used for any script which
4447 is normally invoked with "perl -x".
4448 Please note: do not use this flag unless you are sure your script
4450 needs it. Parsing errors can occur if it does not have a hash-
4451 bang, or, for example, if the actual first hash-bang is in a here-
4452 doc. In that case a parsing error will occur because the
4453 tokenization will begin in the middle of the here-doc.
4454 Making a file unreadable
4456 The goal of perltidy is to improve the readability of files, but
4457 there are two commands which have the opposite effect, --mangle and
4458 --extrude. They are actually merely aliases for combinations of
4459 other parameters. Both of these strip all possible whitespace, but
4460 leave comments and pod documents, so that they are essentially
4461 reversible. The difference between these is that --mangle puts the
4462 fewest possible line breaks in a script while --extrude puts the
4463 maximum possible. Note that these options do not provided any
4464 meaningful obfuscation, because perltidy can be used to reformat
4465 the files. They were originally developed to help test the
4466 tokenization logic of perltidy, but they have other uses. One use
4467 for --mangle is the following:
4468 perltidy --mangle myfile.pl -st | perltidy -o myfile.pl.new
4470 This will form the maximum possible number of one-line blocks (see
4472 next section), and can sometimes help clean up a badly formatted
4473 script.
4474 A similar technique can be used with --extrude instead of --mangle
4476 to make the minimum number of one-line blocks.
4477 Another use for --mangle is to combine it with -dac to reduce the
4479 file size of a perl script.
4480 Debugging
4482 The following flags are available for debugging:
4483 --dump-cuddled-block-list or -dcbl will dump to standard output the
4485 internal hash of cuddled block types created by a
4486 -cuddled-block-list input string.
4487 --dump-defaults or -ddf will write the default option set to
4489 standard output and quit
4490 --dump-profile or -dpro will write the name of the current
4492 configuration file and its contents to standard output and quit.
4493 --dump-options or -dop will write current option set to standard
4495 output and quit.
4496 --dump-long-names or -dln will write all command line long names
4498 (passed to Get_options) to standard output and quit.
4499 --dump-short-names or -dsn will write all command line short names
4501 to standard output and quit.
4502 --dump-token-types or -dtt will write a list of all token types to
4504 standard output and quit.
4505 --dump-want-left-space or -dwls will write the hash
4507 %want_left_space to standard output and quit. See the section on
4508 controlling whitespace around tokens.
4509 --dump-want-right-space or -dwrs will write the hash
4511 %want_right_space to standard output and quit. See the section on
4512 controlling whitespace around tokens.
4513 --no-memoize or -nmem will turn of memoizing. Memoization can
4515 reduce run time when running perltidy repeatedly in a single
4516 process. It is on by default but can be deactivated for testing
4517 with -nmem.
4518 --no-timestamp or -nts will eliminate any time stamps in output
4520 files to prevent differences in dates from causing test
4521 installation scripts to fail. There are just a couple of places
4522 where timestamps normally occur. One is in the headers of html
4523 files, and another is when the -cscw option is selected. The
4524 default is to allow timestamps (--timestamp or -ts).
4525 --file-size-order or -fso will cause files to be processed in order
4527 of increasing size, when multiple files are being processed. This
4528 is useful during program development, when large numbers of files
4529 with varying sizes are processed, because it can reduce virtual
4530 memory usage.
4531 --maximum-file-size-mb=n or -maxfs=n specifies the maximum file
4533 size in megabytes that perltidy will attempt to format. This
4534 parameter is provided to avoid causing system problems by
4535 accidentally attempting to format an extremely large data file.
4536 Most perl scripts are less than about 2 MB in size. The integer n
4537 has a default value of 10, so perltidy will skip formatting files
4538 which have a size greater than 10 MB. The command to increase the
4539 limit to 20 MB for example would be
4540 perltidy -maxfs=20
4542 This only applies to files specified by filename on the command
4544 line.
4545 --maximum-level-errors=n or -maxle=n specifies the maximum number
4547 of indentation level errors are allowed before perltidy skips
4548 formatting and just outputs a file verbatim. The default is n=1.
4549 This means that if the final indentation of a script differs from
4550 the starting indentation by more than 1 levels, the file will be
4551 output verbatim. To avoid formatting if there are any indentation
4552 level errors use -maxle=0. To skip this check you can either set n
4553 equal to a large number, such as n=100, or set n=-1.
4554 For example, the following script has level error of 3 and will be
4556 output verbatim
4557 Input and default output:
4559 {{{
4560 perltidy -maxle=100
4563 {
4564 {
4565 {
4566 --maximum-unexpected-errors=n or -maxue=n specifies the maximum
4568 number of unexpected tokenization errors are allowed before
4569 formatting is skipped and a script is output verbatim. The
4570 intention is to avoid accidentally formatting a non-perl script,
4571 such as an html file for example. This check can be turned off by
4572 setting n=0.
4573 A recommended value is n=3. However, the default is n=0 (skip this
4575 check) to avoid causing problems with scripts which have extended
4576 syntaxes.
4577 -DEBUG will write a file with extension .DEBUG for each input file
4579 showing the tokenization of all lines of code.
4580 Working with MakeMaker, AutoLoader and SelfLoader
4582 The first $VERSION line of a file which might be eval'd by
4583 MakeMaker is passed through unchanged except for indentation. Use
4584 --nopass-version-line, or -npvl, to deactivate this feature.
4585 If the AutoLoader module is used, perltidy will continue formatting
4587 code after seeing an __END__ line. Use --nolook-for-autoloader, or
4588 -nlal, to deactivate this feature.
4589 Likewise, if the SelfLoader module is used, perltidy will continue
4591 formatting code after seeing a __DATA__ line. Use
4592 --nolook-for-selfloader, or -nlsl, to deactivate this feature.
4593 Working around problems with older version of Perl
4595 Perltidy contains a number of rules which help avoid known
4596 subtleties and problems with older versions of perl, and these
4597 rules always take priority over whatever formatting flags have been
4598 set. For example, perltidy will usually avoid starting a new line
4599 with a bareword, because this might cause problems if "use strict"
4600 is active.
4601 There is no way to override these rules.
4603
4605 The -html master switch
4606 The flag -html causes perltidy to write an html file with extension
4607 .html. So, for example, the following command
4608 perltidy -html somefile.pl
4610 will produce a syntax-colored html file named somefile.pl.html
4612 which may be viewed with a browser.
4613 Please Note: In this case, perltidy does not do any formatting to
4615 the input file, and it does not write a formatted file with
4616 extension .tdy. This means that two perltidy runs are required to
4617 create a fully reformatted, html copy of a script.
4618 The -pre flag for code snippets
4620 When the -pre flag is given, only the pre-formatted section, within
4621 the <PRE> and </PRE> tags, will be output. This simplifies
4622 inclusion of the output in other files. The default is to output a
4623 complete web page.
4624 The -nnn flag for line numbering
4626 When the -nnn flag is given, the output lines will be numbered.
4627 The -toc, or --html-table-of-contents flag
4629 By default, a table of contents to packages and subroutines will be
4630 written at the start of html output. Use -ntoc to prevent this.
4631 This might be useful, for example, for a pod document which
4632 contains a number of unrelated code snippets. This flag only
4633 influences the code table of contents; it has no effect on any
4634 table of contents produced by pod2html (see next item).
4635 The -pod, or --pod2html flag
4637 There are two options for formatting pod documentation. The
4638 default is to pass the pod through the Pod::Html module (which
4639 forms the basis of the pod2html utility). Any code sections are
4640 formatted by perltidy, and the results then merged. Note: perltidy
4641 creates a temporary file when Pod::Html is used; see "FILES".
4642 Also, Pod::Html creates temporary files for its cache.
4643 NOTE: Perltidy counts the number of "=cut" lines, and either moves
4645 the pod text to the top of the html file if there is one "=cut", or
4646 leaves the pod text in its original order (interleaved with code)
4647 otherwise.
4648 Most of the flags accepted by pod2html may be included in the
4650 perltidy command line, and they will be passed to pod2html. In
4651 some cases, the flags have a prefix "pod" to emphasize that they
4652 are for the pod2html, and this prefix will be removed before they
4653 are passed to pod2html. The flags which have the additional "pod"
4654 prefix are:
4655 --[no]podheader --[no]podindex --[no]podrecurse --[no]podquiet
4657 --[no]podverbose --podflush
4658 The flags which are unchanged from their use in pod2html are:
4660 --backlink=s --cachedir=s --htmlroot=s --libpods=s --title=s
4662 --podpath=s --podroot=s
4663 where 's' is an appropriate character string. Not all of these
4665 flags are available in older versions of Pod::Html. See your
4666 Pod::Html documentation for more information.
4667 The alternative, indicated with -npod, is not to use Pod::Html, but
4669 rather to format pod text in italics (or whatever the stylesheet
4670 indicates), without special html markup. This is useful, for
4671 example, if pod is being used as an alternative way to write
4672 comments.
4673 The -frm, or --frames flag
4675 By default, a single html output file is produced. This can be
4676 changed with the -frm option, which creates a frame holding a table
4677 of contents in the left panel and the source code in the right
4678 side. This simplifies code browsing. Assume, for example, that the
4679 input file is MyModule.pm. Then, for default file extension
4680 choices, these three files will be created:
4681 MyModule.pm.html - the frame
4683 MyModule.pm.toc.html - the table of contents
4684 MyModule.pm.src.html - the formatted source code
4685 Obviously this file naming scheme requires that output be directed
4687 to a real file (as opposed to, say, standard output). If this is
4688 not the case, or if the file extension is unknown, the -frm option
4689 will be ignored.
4690 The -text=s, or --html-toc-extension flag
4692 Use this flag to specify the extra file extension of the table of
4693 contents file when html frames are used. The default is "toc".
4694 See "Specifying File Extensions".
4695 The -sext=s, or --html-src-extension flag
4697 Use this flag to specify the extra file extension of the content
4698 file when html frames are used. The default is "src". See
4699 "Specifying File Extensions".
4700 The -hent, or --html-entities flag
4702 This flag controls the use of Html::Entities for html formatting.
4703 By default, the module Html::Entities is used to encode special
4704 symbols. This may not be the right thing for some browser/language
4705 combinations. Use --nohtml-entities or -nhent to prevent this.
4706 Style Sheets
4708 Style sheets make it very convenient to control and adjust the
4709 appearance of html pages. The default behavior is to write a page
4710 of html with an embedded style sheet.
4711 An alternative to an embedded style sheet is to create a page with
4713 a link to an external style sheet. This is indicated with the
4714 -css=filename, where the external style sheet is filename. The
4715 external style sheet filename will be created if and only if it
4716 does not exist. This option is useful for controlling multiple
4717 pages from a single style sheet.
4718 To cause perltidy to write a style sheet to standard output and
4720 exit, use the -ss, or --stylesheet, flag. This is useful if the
4721 style sheet could not be written for some reason, such as if the
4722 -pre flag was used. Thus, for example,
4723 perltidy -html -ss >mystyle.css
4725 will write a style sheet with the default properties to file
4727 mystyle.css.
4728 The use of style sheets is encouraged, but a web page without a
4730 style sheets can be created with the flag -nss. Use this option if
4731 you must to be sure that older browsers (roughly speaking, versions
4732 prior to 4.0 of Netscape Navigator and Internet Explorer) can
4733 display the syntax-coloring of the html files.
4734 Controlling HTML properties
4736 Note: It is usually more convenient to accept the default
4737 properties and then edit the stylesheet which is produced.
4738 However, this section shows how to control the properties with
4739 flags to perltidy.
4740 Syntax colors may be changed from their default values by flags of
4742 the either the long form, -html-color-xxxxxx=n, or more
4743 conveniently the short form, -hcx=n, where xxxxxx is one of the
4744 following words, and x is the corresponding abbreviation:
4745 Token Type xxxxxx x
4747 ---------- -------- --
4748 comment comment c
4749 number numeric n
4750 identifier identifier i
4751 bareword, function bareword w
4752 keyword keyword k
4753 quite, pattern quote q
4754 here doc text here-doc-text h
4755 here doc target here-doc-target hh
4756 punctuation punctuation pu
4757 parentheses paren p
4758 structural braces structure s
4759 semicolon semicolon sc
4760 colon colon co
4761 comma comma cm
4762 label label j
4763 sub definition name subroutine m
4764 pod text pod-text pd
4765 A default set of colors has been defined, but they may be changed
4767 by providing values to any of the following parameters, where n is
4768 either a 6 digit hex RGB color value or an ascii name for a color,
4769 such as 'red'.
4770 To illustrate, the following command will produce an html file
4772 somefile.pl.html with "aqua" keywords:
4773 perltidy -html -hck=00ffff somefile.pl
4775 and this should be equivalent for most browsers:
4777 perltidy -html -hck=aqua somefile.pl
4779 Perltidy merely writes any non-hex names that it sees in the html
4781 file. The following 16 color names are defined in the HTML 3.2
4782 standard:
4783 black => 000000,
4785 silver => c0c0c0,
4786 gray => 808080,
4787 white => ffffff,
4788 maroon => 800000,
4789 red => ff0000,
4790 purple => 800080,
4791 fuchsia => ff00ff,
4792 green => 008000,
4793 lime => 00ff00,
4794 olive => 808000,
4795 yellow => ffff00
4796 navy => 000080,
4797 blue => 0000ff,
4798 teal => 008080,
4799 aqua => 00ffff,
4800 Many more names are supported in specific browsers, but it is
4802 safest to use the hex codes for other colors. Helpful color tables
4803 can be located with an internet search for "HTML color tables".
4804 Besides color, two other character attributes may be set: bold, and
4806 italics. To set a token type to use bold, use the flag
4807 --html-bold-xxxxxx or -hbx, where xxxxxx or x are the long or short
4808 names from the above table. Conversely, to set a token type to NOT
4809 use bold, use --nohtml-bold-xxxxxx or -nhbx.
4810 Likewise, to set a token type to use an italic font, use the flag
4812 --html-italic-xxxxxx or -hix, where again xxxxxx or x are the long
4813 or short names from the above table. And to set a token type to
4814 NOT use italics, use --nohtml-italic-xxxxxx or -nhix.
4815 For example, to use bold braces and lime color, non-bold, italics
4817 keywords the following command would be used:
4818 perltidy -html -hbs -hck=00FF00 -nhbk -hik somefile.pl
4820 The background color can be specified with
4822 --html-color-background=n, or -hcbg=n for short, where n is a 6
4823 character hex RGB value. The default color of text is the value
4824 given to punctuation, which is black as a default.
4825 Here are some notes and hints:
4827 1. If you find a preferred set of these parameters, you may want to
4829 create a .perltidyrc file containing them. See the perltidy man
4830 page for an explanation.
4831 2. Rather than specifying values for these parameters, it is
4833 probably easier to accept the defaults and then edit a style sheet.
4834 The style sheet contains comments which should make this easy.
4835 3. The syntax-colored html files can be very large, so it may be
4837 best to split large files into smaller pieces to improve download
4838 times.
4839
4841 Specifying Block Types
4842 Several parameters which refer to code block types may be customized by
4843 also specifying an associated list of block types. The type of a block
4844 is the name of the keyword which introduces that block, such as if,
4845 else, or sub. An exception is a labeled block, which has no keyword,
4846 and should be specified with just a colon. To specify all blocks use
4847 '*'.
4848 The keyword sub indicates a named sub. For anonymous subs, use the
4850 special keyword asub.
4851 For example, the following parameter specifies "sub", labels, "BEGIN",
4853 and "END" blocks:
4854 -cscl="sub : BEGIN END"
4856 (the meaning of the -cscl parameter is described above.) Note that
4858 quotes are required around the list of block types because of the
4859 spaces. For another example, the following list specifies all block
4860 types for vertical tightness:
4861 -bbvtl='*'
4863 Specifying File Extensions
4865 Several parameters allow default file extensions to be overridden. For
4866 example, a backup file extension may be specified with -bext=ext, where
4867 ext is some new extension. In order to provides the user some
4868 flexibility, the following convention is used in all cases to decide if
4869 a leading '.' should be used. If the extension "ext" begins with
4870 "A-Z", "a-z", or "0-9", then it will be appended to the filename with
4871 an intermediate '.' (or perhaps a '_' on VMS systems). Otherwise, it
4872 will be appended directly.
4873 For example, suppose the file is somefile.pl. For "-bext=old", a '.'
4875 is added to give somefile.pl.old. For "-bext=.old", no additional '.'
4876 is added, so again the backup file is somefile.pl.old. For "-bext=~",
4877 then no dot is added, and the backup file will be somefile.pl~ .
4878
4880 The following list shows all short parameter names which allow a prefix
4881 'n' to produce the negated form:
4882 D anl asbl asc ast asu atnl aws b baa
4884 baao bar bbao bbb bbc bbs bl bli boa boc
4885 bok bol bom bos bot cblx ce conv cs csc
4886 cscb cscw dac dbc dcbl dcsc ddf dln dnl dop
4887 dp dpro dsc dsm dsn dtt dwls dwrs dws eos
4888 f fll fpva frm fs fso gcs hbc hbcm hbco
4889 hbh hbhh hbi hbj hbk hbm hbn hbp hbpd hbpu
4890 hbq hbs hbsc hbv hbw hent hic hicm hico hih
4891 hihh hii hij hik him hin hip hipd hipu hiq
4892 his hisc hiv hiw hsc html ibc icb icp iob
4893 isbc iscl kgb kgbd kgbi kis lal log lop lp
4894 lsl mem nib ohbr okw ola olc oll olq opr
4895 opt osbc osbr otr ple pod pvl q sac sbc
4896 sbl scbb schb scp scsb sct se sfp sfs skp
4897 sob sobb sohb sop sosb sot ssc st sts t
4898 tac tbc toc tp tqw trp ts tsc tso vbc
4899 vc vmll vsc w wn x xci xlp xs
4900 Equivalently, the prefix 'no' or 'no-' on the corresponding long names
4902 may be used.
4903
4905 Parsing Limitations
4906 Perltidy should work properly on most perl scripts. It does a lot
4907 of self-checking, but still, it is possible that an error could be
4908 introduced and go undetected. Therefore, it is essential to make
4909 careful backups and to test reformatted scripts.
4910 The main current limitation is that perltidy does not scan modules
4912 included with 'use' statements. This makes it necessary to guess
4913 the context of any bare words introduced by such modules. Perltidy
4914 has good guessing algorithms, but they are not infallible. When it
4915 must guess, it leaves a message in the log file.
4916 If you encounter a bug, please report it.
4918 What perltidy does not parse and format
4920 Perltidy indents but does not reformat comments and "qw" quotes.
4921 Perltidy does not in any way modify the contents of here documents
4922 or quoted text, even if they contain source code. (You could,
4923 however, reformat them separately). Perltidy does not format
4924 'format' sections in any way. And, of course, it does not modify
4925 pod documents.
4926
4928 Temporary files
4929 Under the -html option with the default --pod2html flag, a
4930 temporary file is required to pass text to Pod::Html. Unix systems
4931 will try to use the POSIX tmpnam() function. Otherwise the file
4932 perltidy.TMP will be temporarily created in the current working
4933 directory.
4934 Special files when standard input is used
4936 When standard input is used, the log file, if saved, is
4937 perltidy.LOG, and any errors are written to perltidy.ERR unless the
4938 -se flag is set. These are saved in the current working directory.
4939 Files overwritten
4941 The following file extensions are used by perltidy, and files with
4942 these extensions may be overwritten or deleted: .ERR, .LOG, .TEE,
4943 and/or .tdy, .html, and .bak, depending on the run type and
4944 settings.
4945 Files extensions limitations
4947 Perltidy does not operate on files for which the run could produce
4948 a file with a duplicated file extension. These extensions include
4949 .LOG, .ERR, .TEE, and perhaps .tdy and .bak, depending on the run
4950 type. The purpose of this rule is to prevent generating confusing
4951 filenames such as somefile.tdy.tdy.tdy.
4952
4954 An exit value of 0, 1, or 2 is returned by perltidy to indicate the
4955 status of the result.
4956 A exit value of 0 indicates that perltidy ran to completion with no
4958 error messages.
4959 A non-zero exit value indicates some kind of problem was detected.
4961 An exit value of 1 indicates that perltidy terminated prematurely,
4963 usually due to some kind of errors in the input parameters. This can
4964 happen for example if a parameter is misspelled or given an invalid
4965 value. Error messages in the standard error output will indicate the
4966 cause of any problem. If perltidy terminates prematurely then no
4967 output files will be produced.
4968 An exit value of 2 indicates that perltidy was able to run to
4970 completion but there there are (1) warning messages in the standard
4971 error output related to parameter errors or problems and/or (2) warning
4972 messages in the perltidy error file(s) relating to possible syntax
4973 errors in one or more of the source script(s) being tidied. When
4974 multiple files are being processed, an error detected in any single
4975 file will produce this type of exit condition.
4976
4978 perlstyle(1), Perl::Tidy(3)
4979
4981 The perltidy binary uses the Perl::Tidy module and is installed when
4982 that module is installed. The module name is case-sensitive. For
4983 example, the basic command for installing with cpanm is 'cpanm
4984 Perl::Tidy'.
4985
4987 This man page documents perltidy version 20220217
4988
4990 A list of current bugs and issues can be found at the CPAN site
4991 <https://rt.cpan.org/Public/Dist/Display.html?Name=Perl-Tidy>
4992 To report a new bug or problem, use the link on this page.
4994 The source code repository is at
4996 <https://github.com/perltidy/perltidy>.
4997
4999 Copyright (c) 2000-2022 by Steve Hancock
5000
5002 This package is free software; you can redistribute it and/or modify it
5003 under the terms of the "GNU General Public License".
5004 Please refer to the file "COPYING" for details.
5006
5008 This package is distributed in the hope that it will be useful, but
5009 WITHOUT ANY WARRANTY; without even the implied warranty of
5010 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
5011 See the "GNU General Public License" for more details.
5013perl v5.34.0 2022-02-15 PERLTIDY(1)