1PERLTIDY(1) User Contributed Perl Documentation PERLTIDY(1)
2
6 perltidy - a perl script indenter and reformatter
7
9 perltidy [ options ] file1 file2 file3 ...
10 (output goes to file1.tdy, file2.tdy, file3.tdy, ...)
11 perltidy [ options ] file1 -o outfile
12 perltidy [ options ] file1 -st >outfile
13 perltidy [ options ] <infile >outfile
14
16 Perltidy reads a perl script and writes an indented, reformatted
17 script.
18 Many users will find enough information in "EXAMPLES" to get started.
20 New users may benefit from the short tutorial which can be found at
21 http://perltidy.sourceforge.net/tutorial.html
22 A convenient aid to systematically defining a set of style parameters
24 can be found at http://perltidy.sourceforge.net/stylekey.html
25 Perltidy can produce output on either of two modes, depending on the
27 existence of an -html flag. Without this flag, the output is passed
28 through a formatter. The default formatting tries to follow the
29 recommendations in perlstyle(1), but it can be controlled in detail
30 with numerous input parameters, which are described in "FORMATTING
31 OPTIONS".
32 When the -html flag is given, the output is passed through an HTML
34 formatter which is described in "HTML OPTIONS".
35
37 perltidy somefile.pl
38 This will produce a file somefile.pl.tdy containing the script
40 reformatted using the default options, which approximate the style
41 suggested in perlstyle(1). The source file somefile.pl is unchanged.
42 perltidy *.pl
44 Execute perltidy on all .pl files in the current directory with the
46 default options. The output will be in files with an appended .tdy
47 extension. For any file with an error, there will be a file with
48 extension .ERR.
49 perltidy -b file1.pl file2.pl
51 Modify file1.pl and file2.pl in place, and backup the originals to
53 file1.pl.bak and file2.pl.bak. If file1.pl.bak and/or file2.pl.bak
54 already exist, they will be overwritten.
55 perltidy -b -bext='/' file1.pl file2.pl
57 Same as the previous example except that the backup files file1.pl.bak
59 and file2.pl.bak will be deleted if there are no errors.
60 perltidy -gnu somefile.pl
62 Execute perltidy on file somefile.pl with a style which approximates
64 the GNU Coding Standards for C programs. The output will be
65 somefile.pl.tdy.
66 perltidy -i=3 somefile.pl
68 Execute perltidy on file somefile.pl, with 3 columns for each level of
70 indentation (-i=3) instead of the default 4 columns. There will not be
71 any tabs in the reformatted script, except for any which already exist
72 in comments, pod documents, quotes, and here documents. Output will be
73 somefile.pl.tdy.
74 perltidy -i=3 -et=8 somefile.pl
76 Same as the previous example, except that leading whitespace will be
78 entabbed with one tab character per 8 spaces.
79 perltidy -ce -l=72 somefile.pl
81 Execute perltidy on file somefile.pl with all defaults except use
83 "cuddled elses" (-ce) and a maximum line length of 72 columns (-l=72)
84 instead of the default 80 columns.
85 perltidy -g somefile.pl
87 Execute perltidy on file somefile.pl and save a log file
89 somefile.pl.LOG which shows the nesting of braces, parentheses, and
90 square brackets at the start of every line.
91 perltidy -html somefile.pl
93 This will produce a file somefile.pl.html containing the script with
95 html markup. The output file will contain an embedded style sheet in
96 the <HEAD> section which may be edited to change the appearance.
97 perltidy -html -css=mystyle.css somefile.pl
99 This will produce a file somefile.pl.html containing the script with
101 html markup. This output file will contain a link to a separate style
102 sheet file mystyle.css. If the file mystyle.css does not exist, it
103 will be created. If it exists, it will not be overwritten.
104 perltidy -html -pre somefile.pl
106 Write an html snippet with only the PRE section to somefile.pl.html.
108 This is useful when code snippets are being formatted for inclusion in
109 a larger web page. No style sheet will be written in this case.
110 perltidy -html -ss >mystyle.css
112 Write a style sheet to mystyle.css and exit.
114 perltidy -html -frm mymodule.pm
116 Write html with a frame holding a table of contents and the source
118 code. The output files will be mymodule.pm.html (the frame),
119 mymodule.pm.toc.html (the table of contents), and mymodule.pm.src.html
120 (the source code).
121
123 The entire command line is scanned for options, and they are processed
124 before any files are processed. As a result, it does not matter
125 whether flags are before or after any filenames. However, the relative
126 order of parameters is important, with later parameters overriding the
127 values of earlier parameters.
128 For each parameter, there is a long name and a short name. The short
130 names are convenient for keyboard input, while the long names are self-
131 documenting and therefore useful in scripts. It is customary to use
132 two leading dashes for long names, but one may be used.
133 Most parameters which serve as on/off flags can be negated with a
135 leading "n" (for the short name) or a leading "no" or "no-" (for the
136 long name). For example, the flag to outdent long quotes is -olq or
137 --outdent-long-quotes. The flag to skip this is -nolq or
138 --nooutdent-long-quotes or --no-outdent-long-quotes.
139 Options may not be bundled together. In other words, options -q and -g
141 may NOT be entered as -qg.
142 Option names may be terminated early as long as they are uniquely
144 identified. For example, instead of --dump-token-types, it would be
145 sufficient to enter --dump-tok, or even --dump-t, to uniquely identify
146 this command.
147 I/O control
149 The following parameters concern the files which are read and written.
150 -h, --help
152 Show summary of usage and exit.
153 -o=filename, --outfile=filename
155 Name of the output file (only if a single input file is being
156 processed). If no output file is specified, and output is not
157 redirected to the standard output (see -st), the output will go to
158 filename.tdy. [Note: - does not redirect to standard output. Use
159 -st instead.]
160 -st, --standard-output
162 Perltidy must be able to operate on an arbitrarily large number of
163 files in a single run, with each output being directed to a
164 different output file. Obviously this would conflict with
165 outputting to the single standard output device, so a special flag,
166 -st, is required to request outputting to the standard output. For
167 example,
168 perltidy somefile.pl -st >somefile.new.pl
170 This option may only be used if there is just a single input file.
172 The default is -nst or --nostandard-output.
173 -se, --standard-error-output
175 If perltidy detects an error when processing file somefile.pl, its
176 default behavior is to write error messages to file
177 somefile.pl.ERR. Use -se to cause all error messages to be sent to
178 the standard error output stream instead. This directive may be
179 negated with -nse. Thus, you may place -se in a .perltidyrc and
180 override it when desired with -nse on the command line.
181 -oext=ext, --output-file-extension=ext
183 Change the extension of the output file to be ext instead of the
184 default tdy (or html in case the --html option is used). See
185 "Specifying File Extensions".
186 -opath=path, --output-path=path
188 When perltidy creates a filename for an output file, by default it
189 merely appends an extension to the path and basename of the input
190 file. This parameter causes the path to be changed to path
191 instead.
192 The path should end in a valid path separator character, but
194 perltidy will try to add one if it is missing.
195 For example
197 perltidy somefile.pl -opath=/tmp/
199 will produce /tmp/somefile.pl.tdy. Otherwise, somefile.pl.tdy will
201 appear in whatever directory contains somefile.pl.
202 If the path contains spaces, it should be placed in quotes.
204 This parameter will be ignored if output is being directed to
206 standard output, or if it is being specified explicitly with the
207 -o=s parameter.
208 -b, --backup-and-modify-in-place
210 Modify the input file or files in-place and save the original with
211 the extension .bak. Any existing .bak file will be deleted. See
212 next item for changing the default backup extension, and for
213 eliminating the backup file altogether.
214 A -b flag will be ignored if input is from standard input or goes
216 to standard output, or if the -html flag is set.
217 In particular, if you want to use both the -b flag and the -pbp
219 (--perl-best-practices) flag, then you must put a -nst flag after
220 the -pbp flag because it contains a -st flag as one of its
221 components, which means that output will go to the standard output
222 stream.
223 -bext=ext, --backup-file-extension=ext
225 This parameter serves two purposes: (1) to change the extension of
226 the backup file to be something other than the default .bak, and
227 (2) to indicate that no backup file should be saved.
228 To change the default extension to something other than .bak see
230 "Specifying File Extensions".
231 A backup file of the source is always written, but you can request
233 that it be deleted at the end of processing if there were no
234 errors. This is risky unless the source code is being maintained
235 with a source code control system.
236 To indicate that the backup should be deleted include one forward
238 slash, /, in the extension. If any text remains after the slash is
239 removed it will be used to define the backup file extension (which
240 is always created and only deleted if there were no errors).
241 Here are some examples:
243 Parameter Extension Backup File Treatment
245 <-bext=bak> F<.bak> Keep (same as the default behavior)
246 <-bext='/'> F<.bak> Delete if no errors
247 <-bext='/backup'> F<.backup> Delete if no errors
248 <-bext='original/'> F<.original> Delete if no errors
249 -w, --warning-output
251 Setting -w causes any non-critical warning messages to be reported
252 as errors. These include messages about possible pod problems,
253 possibly bad starting indentation level, and cautions about
254 indirect object usage. The default, -nw or --nowarning-output, is
255 not to include these warnings.
256 -q, --quiet
258 Deactivate error messages and syntax checking (for running under an
259 editor).
260 For example, if you use a vi-style editor, such as vim, you may
262 execute perltidy as a filter from within the editor using something
263 like
264 :n1,n2!perltidy -q
266 where "n1,n2" represents the selected text. Without the -q flag,
268 any error message may mess up your screen, so be prepared to use
269 your "undo" key.
270 -log, --logfile
272 Save the .LOG file, which has many useful diagnostics. Perltidy
273 always creates a .LOG file, but by default it is deleted unless a
274 program bug is suspected. Setting the -log flag forces the log
275 file to be saved.
276 -g=n, --logfile-gap=n
278 Set maximum interval between input code lines in the logfile. This
279 purpose of this flag is to assist in debugging nesting errors. The
280 value of "n" is optional. If you set the flag -g without the value
281 of "n", it will be taken to be 1, meaning that every line will be
282 written to the log file. This can be helpful if you are looking
283 for a brace, paren, or bracket nesting error.
284 Setting -g also causes the logfile to be saved, so it is not
286 necessary to also include -log.
287 If no -g flag is given, a value of 50 will be used, meaning that at
289 least every 50th line will be recorded in the logfile. This helps
290 prevent excessively long log files.
291 Setting a negative value of "n" is the same as not setting -g at
293 all.
294 -npro --noprofile
296 Ignore any .perltidyrc command file. Normally, perltidy looks
297 first in your current directory for a .perltidyrc file of
298 parameters. (The format is described below). If it finds one, it
299 applies those options to the initial default values, and then it
300 applies any that have been defined on the command line. If no
301 .perltidyrc file is found, it looks for one in your home directory.
302 If you set the -npro flag, perltidy will not look for this file.
304 -pro=filename or --profile=filename
306 To simplify testing and switching .perltidyrc files, this command
307 may be used to specify a configuration file which will override the
308 default name of .perltidyrc. There must not be a space on either
309 side of the '=' sign. For example, the line
310 perltidy -pro=testcfg
312 would cause file testcfg to be used instead of the default
314 .perltidyrc.
315 A pathname begins with three dots, e.g. ".../.perltidyrc",
317 indicates that the file should be searched for starting in the
318 current directory and working upwards. This makes it easier to have
319 multiple projects each with their own .perltidyrc in their root
320 directories.
321 -opt, --show-options
323 Write a list of all options used to the .LOG file. Please see
324 --dump-options for a simpler way to do this.
325 -f, --force-read-binary
327 Force perltidy to process binary files. To avoid producing
328 excessive error messages, perltidy skips files identified by the
329 system as non-text. However, valid perl scripts containing binary
330 data may sometimes be identified as non-text, and this flag forces
331 perltidy to process them.
332 -ast, --assert-tidy
334 This flag asserts that the input and output code streams are
335 identical, or in other words that the input code is already 'tidy'
336 according to the formatting parameters. If this is not the case,
337 an error message noting this is produced. This error message will
338 cause the process to return a non-zero exit code. The test for
339 this is made by comparing an MD5 hash value for the input and
340 output code streams. This flag has no other effect on the
341 functioning of perltidy. This might be useful for certain code
342 maintenance operations.
343 -asu, --assert-untidy
345 This flag asserts that the input and output code streams are
346 different, or in other words that the input code is 'untidy'
347 according to the formatting parameters. If this is not the case,
348 an error message noting this is produced. This flag has no other
349 effect on the functioning of perltidy.
350 -sal=s, --sub-alias-list=s
352 This flag causes one or more words to be treated the same as if
353 they were the keyword 'sub'. The string s contains one or more
354 alias words, separated by spaces or commas.
355 For example,
357 perltidy -sal='method fun _sub M4'
359 will cause the perltidy to treate the words 'method', 'fun', '_sub'
361 and 'M4' to be treated the same as if they were 'sub'. Note that
362 if the alias words are separated by spaces then the string of words
363 should be placed in quotes.
364
366 Basic Options
367 --notidy
368 This flag disables all formatting and causes the input to be copied
369 unchanged to the output except for possible changes in line ending
370 characters and any pre- and post-filters. This can be useful in
371 conjunction with a hierarchical set of .perltidyrc files to avoid
372 unwanted code tidying. See also "Skipping Selected Sections of
373 Code" for a way to avoid tidying specific sections of code.
374 -i=n, --indent-columns=n
376 Use n columns per indentation level (default n=4).
377 -l=n, --maximum-line-length=n
379 The default maximum line length is n=80 characters. Perltidy will
380 try to find line break points to keep lines below this length.
381 However, long quotes and side comments may cause lines to exceed
382 this length. Setting -l=0 is equivalent to setting -l=(a large
383 number).
384 -vmll, --variable-maximum-line-length
386 A problem arises using a fixed maximum line length with very deeply
387 nested code and data structures because eventually the amount of
388 leading whitespace used for indicating indentation takes up most or
389 all of the available line width, leaving little or no space for the
390 actual code or data. One solution is to use a vary long line
391 length. Another solution is to use the -vmll flag, which basically
392 tells perltidy to ignore leading whitespace when measuring the line
393 length.
394 To be precise, when the -vmll parameter is set, the maximum line
396 length of a line of code will be M+L*I, where
397 M is the value of --maximum-line-length=M (-l=M), default 80,
399 I is the value of --indent-columns=I (-i=I), default 4,
400 L is the indentation level of the line of code
401 When this flag is set, the choice of breakpoints for a block of
403 code should be essentially independent of its nesting depth.
404 However, the absolute line lengths, including leading whitespace,
405 can still be arbitrarily large. This problem can be avoided by
406 including the next parameter.
407 The default is not to do this (-nvmll).
409 -wc=n, --whitespace-cycle=n
411 This flag also addresses problems with very deeply nested code and
412 data structures. When the nesting depth exceeds the value n the
413 leading whitespace will be reduced and start at a depth of 1 again.
414 The result is that blocks of code will shift back to the left
415 rather than moving arbitrarily far to the right. This occurs
416 cyclically to any depth.
417 For example if one level of indentation equals 4 spaces (-i=4, the
419 default), and one uses -wc=15, then if the leading whitespace on a
420 line exceeds about 4*15=60 spaces it will be reduced back to 4*1=4
421 spaces and continue increasing from there. If the whitespace never
422 exceeds this limit the formatting remains unchanged.
423 The combination of -vmll and -wc=n provides a solution to the
425 problem of displaying arbitrarily deep data structures and code in
426 a finite window, although -wc=n may of course be used without
427 -vmll.
428 The default is not to use this, which can also be indicated using
430 -wc=0.
431 tabs
433 Using tab characters will almost certainly lead to future
434 portability and maintenance problems, so the default and
435 recommendation is not to use them. For those who prefer tabs,
436 however, there are two different options.
437 Except for possibly introducing tab indentation characters, as
439 outlined below, perltidy does not introduce any tab characters into
440 your file, and it removes any tabs from the code (unless requested
441 not to do so with -fws). If you have any tabs in your comments,
442 quotes, or here-documents, they will remain.
443 -et=n, --entab-leading-whitespace
445 This flag causes each n initial space characters to be replaced
446 by one tab character. Note that the integer n is completely
447 independent of the integer specified for indentation parameter,
448 -i=n.
449 -t, --tabs
451 This flag causes one leading tab character to be inserted for
452 each level of indentation. Certain other features are
453 incompatible with this option, and if these options are also
454 given, then a warning message will be issued and this flag will
455 be unset. One example is the -lp option.
456 -dt=n, --default-tabsize=n
458 If the first line of code passed to perltidy contains leading
459 tabs but no tab scheme is specified for the output stream then
460 perltidy must guess how many spaces correspond to each leading
461 tab. This number of spaces n corresponding to each leading tab
462 of the input stream may be specified with -dt=n. The default
463 is n=8.
464 This flag has no effect if a tab scheme is specified for the
466 output stream, because then the input stream is assumed to use
467 the same tab scheme and indentation spaces as for the output
468 stream (any other assumption would lead to unstable editing).
469 -syn, --check-syntax
471 This flag is now ignored for safety, but the following
472 documentation has been retained for reference.
473 This flag causes perltidy to run "perl -c -T" to check syntax of
475 input and output. (To change the flags passed to perl, see the
476 next item, -pscf). The results are written to the .LOG file, which
477 will be saved if an error is detected in the output script. The
478 output script is not checked if the input script has a syntax
479 error. Perltidy does its own checking, but this option employs
480 perl to get a "second opinion".
481 If perl reports errors in the input file, they will not be reported
483 in the error output unless the --warning-output flag is given.
484 The default is NOT to do this type of syntax checking (although
486 perltidy will still do as much self-checking as possible). The
487 reason is that it causes all code in BEGIN blocks to be executed,
488 for all modules being used, and this opens the door to security
489 issues and infinite loops when running perltidy.
490 -pscf=s, -perl-syntax-check-flags=s
492 When perl is invoked to check syntax, the normal flags are "-c -T".
493 In addition, if the -x flag is given to perltidy, then perl will
494 also be passed a -x flag. It should not normally be necessary to
495 change these flags, but it can be done with the -pscf=s flag. For
496 example, if the taint flag, "-T", is not wanted, the flag could be
497 set to be just -pscf=-c.
498 Perltidy will pass your string to perl with the exception that it
500 will add a -c and -x if appropriate. The .LOG file will show
501 exactly what flags were passed to perl.
502 -xs, --extended-syntax
504 A problem with formatting Perl code is that some modules can
505 introduce new syntax. This flag allows perltidy to handle certain
506 common extensions to the standard syntax without complaint.
507 For example, without this flag a structure such as the following
509 would generate a syntax error and the braces would not be balanced:
510 method deposit( Num $amount) {
512 $self->balance( $self->balance + $amount );
513 }
514 This flag is enabled by default but it can be deactivated with
516 -nxs. Probably the only reason to deactivate this flag is to
517 generate more diagnostic messages when debugging a script.
518 -io, --indent-only
520 This flag is used to deactivate all whitespace and line break
521 changes within non-blank lines of code. When it is in effect, the
522 only change to the script will be to the indentation and to the
523 number of blank lines. And any flags controlling whitespace and
524 newlines will be ignored. You might want to use this if you are
525 perfectly happy with your whitespace and line breaks, and merely
526 want perltidy to handle the indentation. (This also speeds up
527 perltidy by well over a factor of two, so it might be useful when
528 perltidy is merely being used to help find a brace error in a large
529 script).
530 Setting this flag is equivalent to setting --freeze-newlines and
532 --freeze-whitespace.
533 If you also want to keep your existing blank lines exactly as they
535 are, you can add --freeze-blank-lines.
536 With this option perltidy is still free to modify the indenting
538 (and outdenting) of code and comments as it normally would. If you
539 also want to prevent long comment lines from being outdented, you
540 can add either -noll or -l=0.
541 Setting this flag will prevent perltidy from doing any special
543 operations on closing side comments. You may still delete all side
544 comments however when this flag is in effect.
545 -enc=s, --character-encoding=s
547 where s=none or utf8. This flag tells perltidy the character
548 encoding of both the input and output character streams. The value
549 utf8 causes the stream to be read and written as UTF-8. The value
550 none causes the stream to be processed without special encoding
551 assumptions. At present there is no automatic detection of
552 character encoding (even if there is a 'use utf8' statement in your
553 code) so this flag must be set for streams encoded in UTF-8.
554 Incorrectly setting this parameter can cause data corruption, so
555 please carefully check the output.
556 The default is none.
558 The abbreviations -utf8 or -UTF8 are equivalent to -enc=utf8. So
560 to process a file named file.pl which is encoded in UTF-8 you can
561 use:
562 perltidy -utf8 file.pl
564 -ole=s, --output-line-ending=s
566 where s="win", "dos", "unix", or "mac". This flag tells perltidy
567 to output line endings for a specific system. Normally, perltidy
568 writes files with the line separator character of the host system.
569 The "win" and "dos" flags have an identical result.
570 -ple, --preserve-line-endings
572 This flag tells perltidy to write its output files with the same
573 line endings as the input file, if possible. It should work for
574 dos, unix, and mac line endings. It will only work if perltidy
575 input comes from a filename (rather than stdin, for example). If
576 perltidy has trouble determining the input file line ending, it
577 will revert to the default behavior of using the line ending of the
578 host system.
579 -it=n, --iterations=n
581 This flag causes perltidy to do n complete iterations. The reason
582 for this flag is that code beautification is an iterative process
583 and in some cases the output from perltidy can be different if it
584 is applied a second time. For most purposes the default of n=1
585 should be satisfactory. However n=2 can be useful when a major
586 style change is being made, or when code is being beautified on
587 check-in to a source code control system. It has been found to be
588 extremely rare for the output to change after 2 iterations. If a
589 value n is greater than 2 is input then a convergence test will be
590 used to stop the iterations as soon as possible, almost always
591 after 2 iterations. See the next item for a simplified iteration
592 control.
593 This flag has no effect when perltidy is used to generate html.
595 -conv, --converge
597 This flag is equivalent to -it=4 and is included to simplify
598 iteration control. For all practical purposes one either does or
599 does not want to be sure that the output is converged, and there is
600 no penalty to using a large iteration limit since perltidy will
601 check for convergence and stop iterating as soon as possible. The
602 default is -nconv (no convergence check). Using -conv will
603 approximately double run time since normally one extra iteration is
604 required to verify convergence.
605 Code Indentation Control
607 -ci=n, --continuation-indentation=n
608 Continuation indentation is extra indentation spaces applied when a
609 long line is broken. The default is n=2, illustrated here:
610 my $level = # -ci=2
612 ( $max_index_to_go >= 0 ) ? $levels_to_go[0] : $last_output_level;
613 The same example, with n=0, is a little harder to read:
615 my $level = # -ci=0
617 ( $max_index_to_go >= 0 ) ? $levels_to_go[0] : $last_output_level;
618 The value given to -ci is also used by some commands when a small
620 space is required. Examples are commands for outdenting labels,
621 -ola, and control keywords, -okw.
622 When default values are not used, it is suggested that the value n
624 given with -ci=n be no more than about one-half of the number of
625 spaces assigned to a full indentation level on the -i=n command.
626 -sil=n --starting-indentation-level=n
628 By default, perltidy examines the input file and tries to determine
629 the starting indentation level. While it is often zero, it may not
630 be zero for a code snippet being sent from an editing session.
631 To guess the starting indentation level perltidy simply assumes
633 that indentation scheme used to create the code snippet is the same
634 as is being used for the current perltidy process. This is the
635 only sensible guess that can be made. It should be correct if this
636 is true, but otherwise it probably won't. For example, if the
637 input script was written with -i=2 and the current peltidy flags
638 have -i=4, the wrong initial indentation will be guessed for a code
639 snippet which has non-zero initial indentation. Likewise, if an
640 entabbing scheme is used in the input script and not in the current
641 process then the guessed indentation will be wrong.
642 If the default method does not work correctly, or you want to
644 change the starting level, use -sil=n, to force the starting level
645 to be n.
646 List indentation using -lp, --line-up-parentheses
648 By default, perltidy indents lists with 4 spaces, or whatever value
649 is specified with -i=n. Here is a small list formatted in this
650 way:
651 # perltidy (default)
653 @month_of_year = (
654 'Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun',
655 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'
656 );
657 Use the -lp flag to add extra indentation to cause the data to
659 begin past the opening parentheses of a sub call or list, or
660 opening square bracket of an anonymous array, or opening curly
661 brace of an anonymous hash. With this option, the above list would
662 become:
663 # perltidy -lp
665 @month_of_year = (
666 'Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun',
667 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'
668 );
669 If the available line length (see -l=n ) does not permit this much
671 space, perltidy will use less. For alternate placement of the
672 closing paren, see the next section.
673 This option has no effect on code BLOCKS, such as if/then/else
675 blocks, which always use whatever is specified with -i=n. Also,
676 the existence of line breaks and/or block comments between the
677 opening and closing parens may cause perltidy to temporarily revert
678 to its default method.
679 Note: The -lp option may not be used together with the -t tabs
681 option. It may, however, be used with the -et=n tab method.
682 In addition, any parameter which significantly restricts the
684 ability of perltidy to choose newlines will conflict with -lp and
685 will cause -lp to be deactivated. These include -io, -fnl, -nanl,
686 and -ndnl. The reason is that the -lp indentation style can
687 require the careful coordination of an arbitrary number of break
688 points in hierarchical lists, and these flags may prevent that.
689 -cti=n, --closing-token-indentation
691 The -cti=n flag controls the indentation of a line beginning with a
692 ")", "]", or a non-block "}". Such a line receives:
693 -cti = 0 no extra indentation (default)
695 -cti = 1 extra indentation such that the closing token
696 aligns with its opening token.
697 -cti = 2 one extra indentation level if the line looks like:
698 ); or ]; or };
699 -cti = 3 one extra indentation level always
700 The flags -cti=1 and -cti=2 work well with the -lp flag (previous
702 section).
703 # perltidy -lp -cti=1
705 @month_of_year = (
706 'Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun',
707 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'
708 );
709 # perltidy -lp -cti=2
711 @month_of_year = (
712 'Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun',
713 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'
714 );
715 These flags are merely hints to the formatter and they may not
717 always be followed. In particular, if -lp is not being used, the
718 indentation for cti=1 is constrained to be no more than one
719 indentation level.
720 If desired, this control can be applied independently to each of
722 the closing container token types. In fact, -cti=n is merely an
723 abbreviation for -cpi=n -csbi=n -cbi=n, where: -cpi or
724 --closing-paren-indentation controls )'s, -csbi or
725 --closing-square-bracket-indentation controls ]'s, -cbi or
726 --closing-brace-indentation controls non-block }'s.
727 -icp, --indent-closing-paren
729 The -icp flag is equivalent to -cti=2, described in the previous
730 section. The -nicp flag is equivalent -cti=0. They are included
731 for backwards compatibility.
732 -icb, --indent-closing-brace
734 The -icb option gives one extra level of indentation to a brace
735 which terminates a code block . For example,
736 if ($task) {
738 yyy();
739 } # -icb
740 else {
741 zzz();
742 }
743 The default is not to do this, indicated by -nicb.
745 -olq, --outdent-long-quotes
747 When -olq is set, lines which is a quoted string longer than the
748 value maximum-line-length will have their indentation removed to
749 make them more readable. This is the default. To prevent such
750 out-denting, use -nolq or --nooutdent-long-lines.
751 -oll, --outdent-long-lines
753 This command is equivalent to --outdent-long-quotes and
754 --outdent-long-comments, and it is included for compatibility with
755 previous versions of perltidy. The negation of this also works,
756 -noll or --nooutdent-long-lines, and is equivalent to setting -nolq
757 and -nolc.
758 Outdenting Labels: -ola, --outdent-labels
760 This command will cause labels to be outdented by 2 spaces (or
761 whatever -ci has been set to), if possible. This is the default.
762 For example:
763 my $i;
765 LOOP: while ( $i = <FOTOS> ) {
766 chomp($i);
767 next unless $i;
768 fixit($i);
769 }
770 Use -nola to not outdent labels.
772 Outdenting Keywords
774 -okw, --outdent-keywords
775 The command -okw will cause certain leading control keywords to
776 be outdented by 2 spaces (or whatever -ci has been set to), if
777 possible. By default, these keywords are "redo", "next",
778 "last", "goto", and "return". The intention is to make these
779 control keywords easier to see. To change this list of
780 keywords being outdented, see the next section.
781 For example, using "perltidy -okw" on the previous example
783 gives:
784 my $i;
786 LOOP: while ( $i = <FOTOS> ) {
787 chomp($i);
788 next unless $i;
789 fixit($i);
790 }
791 The default is not to do this.
793 Specifying Outdented Keywords: -okwl=string,
795 --outdent-keyword-list=string
796 This command can be used to change the keywords which are
797 outdented with the -okw command. The parameter string is a
798 required list of perl keywords, which should be placed in
799 quotes if there are more than one. By itself, it does not
800 cause any outdenting to occur, so the -okw command is still
801 required.
802 For example, the commands "-okwl="next last redo goto" -okw"
804 will cause those four keywords to be outdented. It is probably
805 simplest to place any -okwl command in a .perltidyrc file.
806 Whitespace Control
808 Whitespace refers to the blank space between variables, operators, and
809 other code tokens.
810 -fws, --freeze-whitespace
812 This flag causes your original whitespace to remain unchanged, and
813 causes the rest of the whitespace commands in this section, the
814 Code Indentation section, and the Comment Control section to be
815 ignored.
816 Tightness of curly braces, parentheses, and square brackets.
818 Here the term "tightness" will mean the closeness with which pairs
819 of enclosing tokens, such as parentheses, contain the quantities
820 within. A numerical value of 0, 1, or 2 defines the tightness,
821 with 0 being least tight and 2 being most tight. Spaces within
822 containers are always symmetric, so if there is a space after a "("
823 then there will be a space before the corresponding ")".
824 The -pt=n or --paren-tightness=n parameter controls the space
826 within parens. The example below shows the effect of the three
827 possible values, 0, 1, and 2:
828 if ( ( my $len_tab = length( $tabstr ) ) > 0 ) { # -pt=0
830 if ( ( my $len_tab = length($tabstr) ) > 0 ) { # -pt=1 (default)
831 if ((my $len_tab = length($tabstr)) > 0) { # -pt=2
832 When n is 0, there is always a space to the right of a '(' and to
834 the left of a ')'. For n=2 there is never a space. For n=1, the
835 default, there is a space unless the quantity within the parens is
836 a single token, such as an identifier or quoted string.
837 Likewise, the parameter -sbt=n or --square-bracket-tightness=n
839 controls the space within square brackets, as illustrated below.
840 $width = $col[ $j + $k ] - $col[ $j ]; # -sbt=0
842 $width = $col[ $j + $k ] - $col[$j]; # -sbt=1 (default)
843 $width = $col[$j + $k] - $col[$j]; # -sbt=2
844 Curly braces which do not contain code blocks are controlled by the
846 parameter -bt=n or --brace-tightness=n.
847 $obj->{ $parsed_sql->{ 'table' }[0] }; # -bt=0
849 $obj->{ $parsed_sql->{'table'}[0] }; # -bt=1 (default)
850 $obj->{$parsed_sql->{'table'}[0]}; # -bt=2
851 And finally, curly braces which contain blocks of code are
853 controlled by the parameter -bbt=n or --block-brace-tightness=n as
854 illustrated in the example below.
855 %bf = map { $_ => -M $_ } grep { /\.deb$/ } dirents '.'; # -bbt=0 (default)
857 %bf = map { $_ => -M $_ } grep {/\.deb$/} dirents '.'; # -bbt=1
858 %bf = map {$_ => -M $_} grep {/\.deb$/} dirents '.'; # -bbt=2
859 To simplify input in the case that all of the tightness flags have
861 the same value <n>, the parameter <-act=n> or
862 --all-containers-tightness=n is an abbreviation for the combination
863 <-pt=n -sbt=n -bt=n -bbt=n>.
864 -tso, --tight-secret-operators
866 The flag -tso causes certain perl token sequences (secret
867 operators) which might be considered to be a single operator to be
868 formatted "tightly" (without spaces). The operators currently
869 modified by this flag are:
870 0+ +0 ()x!! ~~<> ,=> =( )=
872 For example the sequence 0 +, which converts a string to a number,
874 would be formatted without a space: 0+ when the -tso flag is set.
875 This flag is off by default.
876 -sts, --space-terminal-semicolon
878 Some programmers prefer a space before all terminal semicolons.
879 The default is for no such space, and is indicated with -nsts or
880 --nospace-terminal-semicolon.
881 $i = 1 ; # -sts
883 $i = 1; # -nsts (default)
884 -sfs, --space-for-semicolon
886 Semicolons within for loops may sometimes be hard to see,
887 particularly when commas are also present. This option places
888 spaces on both sides of these special semicolons, and is the
889 default. Use -nsfs or --nospace-for-semicolon to deactivate it.
890 for ( @a = @$ap, $u = shift @a ; @a ; $u = $v ) { # -sfs (default)
892 for ( @a = @$ap, $u = shift @a; @a; $u = $v ) { # -nsfs
893 -asc, --add-semicolons
895 Setting -asc allows perltidy to add any missing optional semicolon
896 at the end of a line which is followed by a closing curly brace on
897 the next line. This is the default, and may be deactivated with
898 -nasc or --noadd-semicolons.
899 -dsm, --delete-semicolons
901 Setting -dsm allows perltidy to delete extra semicolons which are
902 simply empty statements. This is the default, and may be
903 deactivated with -ndsm or --nodelete-semicolons. (Such semicolons
904 are not deleted, however, if they would promote a side comment to a
905 block comment).
906 -aws, --add-whitespace
908 Setting this option allows perltidy to add certain whitespace
909 improve code readability. This is the default. If you do not want
910 any whitespace added, but are willing to have some whitespace
911 deleted, use -naws. (Use -fws to leave whitespace completely
912 unchanged).
913 -dws, --delete-old-whitespace
915 Setting this option allows perltidy to remove some old whitespace
916 between characters, if necessary. This is the default. If you do
917 not want any old whitespace removed, use -ndws or
918 --nodelete-old-whitespace.
919 Detailed whitespace controls around tokens
921 For those who want more detailed control over the whitespace around
922 tokens, there are four parameters which can directly modify the
923 default whitespace rules built into perltidy for any token. They
924 are:
925 -wls=s or --want-left-space=s,
927 -nwls=s or --nowant-left-space=s,
929 -wrs=s or --want-right-space=s,
931 -nwrs=s or --nowant-right-space=s.
933 These parameters are each followed by a quoted string, s,
935 containing a list of token types. No more than one of each of
936 these parameters should be specified, because repeating a command-
937 line parameter always overwrites the previous one before perltidy
938 ever sees it.
939 To illustrate how these are used, suppose it is desired that there
941 be no space on either side of the token types = + - / *. The
942 following two parameters would specify this desire:
943 -nwls="= + - / *" -nwrs="= + - / *"
945 (Note that the token types are in quotes, and that they are
947 separated by spaces). With these modified whitespace rules, the
948 following line of math:
949 $root = -$b + sqrt( $b * $b - 4. * $a * $c ) / ( 2. * $a );
951 becomes this:
953 $root=-$b+sqrt( $b*$b-4.*$a*$c )/( 2.*$a );
955 These parameters should be considered to be hints to perltidy
957 rather than fixed rules, because perltidy must try to resolve
958 conflicts that arise between them and all of the other rules that
959 it uses. One conflict that can arise is if, between two tokens,
960 the left token wants a space and the right one doesn't. In this
961 case, the token not wanting a space takes priority.
962 It is necessary to have a list of all token types in order to
964 create this type of input. Such a list can be obtained by the
965 command --dump-token-types. Also try the -D flag on a short
966 snippet of code and look at the .DEBUG file to see the
967 tokenization.
968 WARNING Be sure to put these tokens in quotes to avoid having them
970 misinterpreted by your command shell.
971 Space between specific keywords and opening paren
973 When an opening paren follows a Perl keyword, no space is
974 introduced after the keyword, unless it is (by default) one of
975 these:
976 my local our and or eq ne if else elsif until unless
978 while for foreach return switch case given when
979 These defaults can be modified with two commands:
981 -sak=s or --space-after-keyword=s adds keywords.
983 -nsak=s or --nospace-after-keyword=s removes keywords.
985 where s is a list of keywords (in quotes if necessary). For
987 example,
988 my ( $a, $b, $c ) = @_; # default
990 my( $a, $b, $c ) = @_; # -nsak="my local our"
991 The abbreviation -nsak='*' is equivalent to including all of the
993 keywords in the above list.
994 When both -nsak=s and -sak=s commands are included, the -nsak=s
996 command is executed first. For example, to have space after only
997 the keywords (my, local, our) you could use -nsak="*" -sak="my
998 local our".
999 To put a space after all keywords, see the next item.
1001 Space between all keywords and opening parens
1003 When an opening paren follows a function or keyword, no space is
1004 introduced after the keyword except for the keywords noted in the
1005 previous item. To always put a space between a function or keyword
1006 and its opening paren, use the command:
1007 -skp or --space-keyword-paren
1009 You will probably also want to use the flag -sfp (next item) too.
1011 Space between all function names and opening parens
1013 When an opening paren follows a function the default is not to
1014 introduce a space. To cause a space to be introduced use:
1015 -sfp or --space-function-paren
1017 myfunc( $a, $b, $c ); # default
1019 myfunc ( $a, $b, $c ); # -sfp
1020 You will probably also want to use the flag -skp (previous item)
1022 too.
1023 -spp=n or --space-prototype-paren=n
1025 This flag can be used to control whether a function prototype is
1026 preceded by a space. For example, the following prototype does not
1027 have a space.
1028 sub usage();
1030 This integer n may have the value 0, 1, or 2 as follows:
1032 -spp=0 means no space before the paren
1034 -spp=1 means follow the example of the source code [DEFAULT]
1035 -spp=2 means always put a space before the paren
1036 The default is -spp=1, meaning that a space will be used if and
1038 only if there is one in the source code. Given the above line of
1039 code, the result of applying the different options would be:
1040 sub usage(); # n=0 [no space]
1042 sub usage(); # n=1 [default; follows input]
1043 sub usage (); # n=2 [space]
1044 Trimming whitespace around "qw" quotes
1046 -tqw or --trim-qw provide the default behavior of trimming spaces
1047 around multi-line "qw" quotes and indenting them appropriately.
1048 -ntqw or --notrim-qw cause leading and trailing whitespace around
1050 multi-line "qw" quotes to be left unchanged. This option will not
1051 normally be necessary, but was added for testing purposes, because
1052 in some versions of perl, trimming "qw" quotes changes the syntax
1053 tree.
1054 -sbq=n or --space-backslash-quote=n
1056 Lines like
1057 $str1=\"string1";
1059 $str2=\'string2';
1060 can confuse syntax highlighters unless a space is included between
1062 the backslash and the single or double quotation mark.
1063 This can be controlled with the value of n as follows:
1065 -sbq=0 means no space between the backslash and quote
1067 -sbq=1 means follow the example of the source code
1068 -sbq=2 means always put a space between the backslash and quote
1069 The default is -sbq=1, meaning that a space will be used 0if there
1071 is one in the source code.
1072 Trimming trailing whitespace from lines of POD
1074 -trp or --trim-pod will remove trailing whitespace from lines of
1075 POD. The default is not to do this.
1076 Comment Controls
1078 Perltidy has a number of ways to control the appearance of both block
1079 comments and side comments. The term block comment here refers to a
1080 full-line comment, whereas side comment will refer to a comment which
1081 appears on a line to the right of some code.
1082 -ibc, --indent-block-comments
1084 Block comments normally look best when they are indented to the
1085 same level as the code which follows them. This is the default
1086 behavior, but you may use -nibc to keep block comments left-
1087 justified. Here is an example:
1088 # this comment is indented (-ibc, default)
1090 if ($task) { yyy(); }
1091 The alternative is -nibc:
1093 # this comment is not indented (-nibc)
1095 if ($task) { yyy(); }
1096 See also the next item, -isbc, as well as -sbc, for other ways to
1098 have some indented and some outdented block comments.
1099 -isbc, --indent-spaced-block-comments
1101 If there is no leading space on the line, then the comment will not
1102 be indented, and otherwise it may be.
1103 If both -ibc and -isbc are set, then -isbc takes priority.
1105 -olc, --outdent-long-comments
1107 When -olc is set, lines which are full-line (block) comments longer
1108 than the value maximum-line-length will have their indentation
1109 removed. This is the default; use -nolc to prevent outdenting.
1110 -msc=n, --minimum-space-to-comment=n
1112 Side comments look best when lined up several spaces to the right
1113 of code. Perltidy will try to keep comments at least n spaces to
1114 the right. The default is n=4 spaces.
1115 -fpsc=n, --fixed-position-side-comment=n
1117 This parameter tells perltidy to line up side comments in column
1118 number n whenever possible. The default, n=0, will not do this.
1119 -iscl, --ignore-side-comment-lengths
1121 This parameter causes perltidy to ignore the length of side
1122 comments when setting line breaks. The default, -niscl, is to
1123 include the length of side comments when breaking lines to stay
1124 within the length prescribed by the -l=n maximum line length
1125 parameter. For example, the following long single line would
1126 remain intact with -l=80 and -iscl:
1127 perltidy -l=80 -iscl
1129 $vmsfile =~ s/;[\d\-]*$//; # Clip off version number; we can use a newer version as well
1130 whereas without the -iscl flag the line will be broken:
1132 perltidy -l=80
1134 $vmsfile =~ s/;[\d\-]*$//
1135 ; # Clip off version number; we can use a newer version as well
1136 -hsc, --hanging-side-comments
1138 By default, perltidy tries to identify and align "hanging side
1139 comments", which are something like this:
1140 my $IGNORE = 0; # This is a side comment
1142 # This is a hanging side comment
1143 # And so is this
1144 A comment is considered to be a hanging side comment if (1) it
1146 immediately follows a line with a side comment, or another hanging
1147 side comment, and (2) there is some leading whitespace on the line.
1148 To deactivate this feature, use -nhsc or --nohanging-side-comments.
1149 If block comments are preceded by a blank line, or have no leading
1150 whitespace, they will not be mistaken as hanging side comments.
1151 Closing Side Comments
1153 A closing side comment is a special comment which perltidy can
1154 automatically create and place after the closing brace of a code
1155 block. They can be useful for code maintenance and debugging. The
1156 command -csc (or --closing-side-comments) adds or updates closing
1157 side comments. For example, here is a small code snippet
1158 sub message {
1160 if ( !defined( $_[0] ) ) {
1161 print("Hello, World\n");
1162 }
1163 else {
1164 print( $_[0], "\n" );
1165 }
1166 }
1167 And here is the result of processing with "perltidy -csc":
1169 sub message {
1171 if ( !defined( $_[0] ) ) {
1172 print("Hello, World\n");
1173 }
1174 else {
1175 print( $_[0], "\n" );
1176 }
1177 } ## end sub message
1178 A closing side comment was added for "sub message" in this case,
1180 but not for the "if" and "else" blocks, because they were below the
1181 6 line cutoff limit for adding closing side comments. This limit
1182 may be changed with the -csci command, described below.
1183 The command -dcsc (or --delete-closing-side-comments) reverses this
1185 process and removes these comments.
1186 Several commands are available to modify the behavior of these two
1188 basic commands, -csc and -dcsc:
1189 -csci=n, or --closing-side-comment-interval=n
1191 where "n" is the minimum number of lines that a block must have
1192 in order for a closing side comment to be added. The default
1193 value is "n=6". To illustrate:
1194 # perltidy -csci=2 -csc
1196 sub message {
1197 if ( !defined( $_[0] ) ) {
1198 print("Hello, World\n");
1199 } ## end if ( !defined( $_[0] ))
1200 else {
1201 print( $_[0], "\n" );
1202 } ## end else [ if ( !defined( $_[0] ))
1203 } ## end sub message
1204 Now the "if" and "else" blocks are commented. However, now
1206 this has become very cluttered.
1207 -cscp=string, or --closing-side-comment-prefix=string
1209 where string is the prefix used before the name of the block
1210 type. The default prefix, shown above, is "## end". This
1211 string will be added to closing side comments, and it will also
1212 be used to recognize them in order to update, delete, and
1213 format them. Any comment identified as a closing side comment
1214 will be placed just a single space to the right of its closing
1215 brace.
1216 -cscl=string, or --closing-side-comment-list
1218 where "string" is a list of block types to be tagged with
1219 closing side comments. By default, all code block types
1220 preceded by a keyword or label (such as "if", "sub", and so on)
1221 will be tagged. The -cscl command changes the default list to
1222 be any selected block types; see "Specifying Block Types". For
1223 example, the following command requests that only "sub"'s,
1224 labels, "BEGIN", and "END" blocks be affected by any -csc or
1225 -dcsc operation:
1226 -cscl="sub : BEGIN END"
1228 -csct=n, or --closing-side-comment-maximum-text=n
1230 The text appended to certain block types, such as an "if"
1231 block, is whatever lies between the keyword introducing the
1232 block, such as "if", and the opening brace. Since this might
1233 be too much text for a side comment, there needs to be a limit,
1234 and that is the purpose of this parameter. The default value
1235 is "n=20", meaning that no additional tokens will be appended
1236 to this text after its length reaches 20 characters. Omitted
1237 text is indicated with "...". (Tokens, including sub names,
1238 are never truncated, however, so actual lengths may exceed
1239 this). To illustrate, in the above example, the appended text
1240 of the first block is " ( !defined( $_[0] )...". The existing
1241 limit of "n=20" caused this text to be truncated, as indicated
1242 by the "...". See the next flag for additional control of the
1243 abbreviated text.
1244 -cscb, or --closing-side-comments-balanced
1246 As discussed in the previous item, when the closing-side-
1247 comment-maximum-text limit is exceeded the comment text must be
1248 truncated. Older versions of perltidy terminated with three
1249 dots, and this can still be achieved with -ncscb:
1250 perltidy -csc -ncscb
1252 } ## end foreach my $foo (sort { $b cmp $a ...
1253 However this causes a problem with editors which cannot
1255 recognize comments or are not configured to do so because they
1256 cannot "bounce" around in the text correctly. The -cscb flag
1257 has been added to help them by appending appropriate balancing
1258 structure:
1259 perltidy -csc -cscb
1261 } ## end foreach my $foo (sort { $b cmp $a ... })
1262 The default is -cscb.
1264 -csce=n, or --closing-side-comment-else-flag=n
1266 The default, n=0, places the text of the opening "if" statement
1267 after any terminal "else".
1268 If n=2 is used, then each "elsif" is also given the text of the
1270 opening "if" statement. Also, an "else" will include the text
1271 of a preceding "elsif" statement. Note that this may result
1272 some long closing side comments.
1273 If n=1 is used, the results will be the same as n=2 whenever
1275 the resulting line length is less than the maximum allowed.
1276 -cscb, or --closing-side-comments-balanced
1278 When using closing-side-comments, and the closing-side-comment-
1279 maximum-text limit is exceeded, then the comment text must be
1280 abbreviated. It is terminated with three dots if the -cscb
1281 flag is negated:
1282 perltidy -csc -ncscb
1284 } ## end foreach my $foo (sort { $b cmp $a ...
1285 This causes a problem with older editors which do not recognize
1287 comments because they cannot "bounce" around in the text
1288 correctly. The -cscb flag tries to help them by appending
1289 appropriate terminal balancing structures:
1290 perltidy -csc -cscb
1292 } ## end foreach my $foo (sort { $b cmp $a ... })
1293 The default is -cscb.
1295 -cscw, or --closing-side-comment-warnings
1297 This parameter is intended to help make the initial transition
1298 to the use of closing side comments. It causes two things to
1299 happen if a closing side comment replaces an existing,
1300 different closing side comment: first, an error message will
1301 be issued, and second, the original side comment will be placed
1302 alone on a new specially marked comment line for later
1303 attention.
1304 The intent is to avoid clobbering existing hand-written side
1306 comments which happen to match the pattern of closing side
1307 comments. This flag should only be needed on the first run with
1308 -csc.
1309 Important Notes on Closing Side Comments:
1311 · Closing side comments are only placed on lines terminated with
1313 a closing brace. Certain closing styles, such as the use of
1314 cuddled elses (-ce), preclude the generation of some closing
1315 side comments.
1316 · Please note that adding or deleting of closing side comments
1318 takes place only through the commands -csc or -dcsc. The other
1319 commands, if used, merely modify the behavior of these two
1320 commands.
1321 · It is recommended that the -cscw flag be used along with -csc
1323 on the first use of perltidy on a given file. This will
1324 prevent loss of any existing side comment data which happens to
1325 have the csc prefix.
1326 · Once you use -csc, you should continue to use it so that any
1328 closing side comments remain correct as code changes.
1329 Otherwise, these comments will become incorrect as the code is
1330 updated.
1331 · If you edit the closing side comments generated by perltidy,
1333 you must also change the prefix to be different from the
1334 closing side comment prefix. Otherwise, your edits will be
1335 lost when you rerun perltidy with -csc. For example, you
1336 could simply change "## end" to be "## End", since the test is
1337 case sensitive. You may also want to use the -ssc flag to keep
1338 these modified closing side comments spaced the same as actual
1339 closing side comments.
1340 · Temporarily generating closing side comments is a useful
1342 technique for exploring and/or debugging a perl script,
1343 especially one written by someone else. You can always remove
1344 them with -dcsc.
1345 Static Block Comments
1347 Static block comments are block comments with a special leading
1348 pattern, "##" by default, which will be treated slightly
1349 differently from other block comments. They effectively behave as
1350 if they had glue along their left and top edges, because they stick
1351 to the left edge and previous line when there is no blank spaces in
1352 those places. This option is particularly useful for controlling
1353 how commented code is displayed.
1354 -sbc, --static-block-comments
1356 When -sbc is used, a block comment with a special leading
1357 pattern, "##" by default, will be treated specially.
1358 Comments so identified are treated as follows:
1360 · If there is no leading space on the line, then the comment
1362 will not be indented, and otherwise it may be,
1363 · no new blank line will be inserted before such a comment,
1365 and
1366 · such a comment will never become a hanging side comment.
1368 For example, assuming @month_of_year is left-adjusted:
1370 @month_of_year = ( # -sbc (default)
1372 'Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct',
1373 ## 'Dec', 'Nov'
1374 'Nov', 'Dec');
1375 Without this convention, the above code would become
1377 @month_of_year = ( # -nsbc
1379 'Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct',
1380 ## 'Dec', 'Nov'
1382 'Nov', 'Dec'
1383 );
1384 which is not as clear. The default is to use -sbc. This may
1386 be deactivated with -nsbc.
1387 -sbcp=string, --static-block-comment-prefix=string
1389 This parameter defines the prefix used to identify static block
1390 comments when the -sbc parameter is set. The default prefix is
1391 "##", corresponding to "-sbcp=##". The prefix is actually part
1392 of a perl pattern used to match lines and it must either begin
1393 with "#" or "^#". In the first case a prefix ^\s* will be
1394 added to match any leading whitespace, while in the second case
1395 the pattern will match only comments with no leading
1396 whitespace. For example, to identify all comments as static
1397 block comments, one would use "-sbcp=#". To identify all left-
1398 adjusted comments as static block comments, use "-sbcp='^#'".
1399 Please note that -sbcp merely defines the pattern used to
1401 identify static block comments; it will not be used unless the
1402 switch -sbc is set. Also, please be aware that since this
1403 string is used in a perl regular expression which identifies
1404 these comments, it must enable a valid regular expression to be
1405 formed.
1406 A pattern which can be useful is:
1408 -sbcp=^#{2,}[^\s#]
1410 This pattern requires a static block comment to have at least
1412 one character which is neither a # nor a space. It allows a
1413 line containing only '#' characters to be rejected as a static
1414 block comment. Such lines are often used at the start and end
1415 of header information in subroutines and should not be
1416 separated from the intervening comments, which typically begin
1417 with just a single '#'.
1418 -osbc, --outdent-static-block-comments
1420 The command -osbc will cause static block comments to be
1421 outdented by 2 spaces (or whatever -ci=n has been set to), if
1422 possible.
1423 Static Side Comments
1425 Static side comments are side comments with a special leading
1426 pattern. This option can be useful for controlling how commented
1427 code is displayed when it is a side comment.
1428 -ssc, --static-side-comments
1430 When -ssc is used, a side comment with a static leading
1431 pattern, which is "##" by default, will be spaced only a single
1432 space from previous character, and it will not be vertically
1433 aligned with other side comments.
1434 The default is -nssc.
1436 -sscp=string, --static-side-comment-prefix=string
1438 This parameter defines the prefix used to identify static side
1439 comments when the -ssc parameter is set. The default prefix is
1440 "##", corresponding to "-sscp=##".
1441 Please note that -sscp merely defines the pattern used to
1443 identify static side comments; it will not be used unless the
1444 switch -ssc is set. Also, note that this string is used in a
1445 perl regular expression which identifies these comments, so it
1446 must enable a valid regular expression to be formed.
1447 Skipping Selected Sections of Code
1449 Selected lines of code may be passed verbatim to the output without any
1450 formatting. This feature is enabled by default but can be disabled
1451 with the --noformat-skipping or -nfs flag. It should be used sparingly
1452 to avoid littering code with markers, but it might be helpful for
1453 working around occasional problems. For example it might be useful for
1454 keeping the indentation of old commented code unchanged, keeping
1455 indentation of long blocks of aligned comments unchanged, keeping
1456 certain list formatting unchanged, or working around a glitch in
1457 perltidy.
1458 -fs, --format-skipping
1460 This flag, which is enabled by default, causes any code between
1461 special beginning and ending comment markers to be passed to the
1462 output without formatting. The default beginning marker is #<<<
1463 and the default ending marker is #>>> but they may be changed (see
1464 next items below). Additional text may appear on these special
1465 comment lines provided that it is separated from the marker by at
1466 least one space. For example
1467 #<<< do not let perltidy touch this
1469 my @list = (1,
1470 1, 1,
1471 1, 2, 1,
1472 1, 3, 3, 1,
1473 1, 4, 6, 4, 1,);
1474 #>>>
1475 The comment markers may be placed at any location that a block
1477 comment may appear. If they do not appear to be working, use the
1478 -log flag and examine the .LOG file. Use -nfs to disable this
1479 feature.
1480 -fsb=string, --format-skipping-begin=string
1482 The -fsb=string parameter may be used to change the beginning
1483 marker for format skipping. The default is equivalent to
1484 -fsb='#<<<'. The string that you enter must begin with a # and
1485 should be in quotes as necessary to get past the command shell of
1486 your system. It is actually the leading text of a pattern that is
1487 constructed by appending a '\s', so you must also include
1488 backslashes for characters to be taken literally rather than as
1489 patterns.
1490 Some examples show how example strings become patterns:
1492 -fsb='#\{\{\{' becomes /^#\{\{\{\s/ which matches #{{{ but not #{{{{
1494 -fsb='#\*\*' becomes /^#\*\*\s/ which matches #** but not #***
1495 -fsb='#\*{2,}' becomes /^#\*{2,}\s/ which matches #** and #*****
1496 -fse=string, --format-skipping-end=string
1498 The -fsb=string is the corresponding parameter used to change the
1499 ending marker for format skipping. The default is equivalent to
1500 -fse='#<<<'.
1501 Line Break Control
1503 The parameters in this section control breaks after non-blank lines of
1504 code. Blank lines are controlled separately by parameters in the
1505 section "Blank Line Control".
1506 -fnl, --freeze-newlines
1508 If you do not want any changes to the line breaks within lines of
1509 code in your script, set -fnl, and they will remain fixed, and the
1510 rest of the commands in this section and sections "Controlling List
1511 Formatting", "Retaining or Ignoring Existing Line Breaks". You may
1512 want to use -noll with this.
1513 Note: If you also want to keep your blank lines exactly as they
1515 are, you can use the -fbl flag which is described in the section
1516 "Blank Line Control".
1517 -ce, --cuddled-else
1519 Enable the "cuddled else" style, in which "else" and "elsif" are
1520 follow immediately after the curly brace closing the previous
1521 block. The default is not to use cuddled elses, and is indicated
1522 with the flag -nce or --nocuddled-else. Here is a comparison of
1523 the alternatives:
1524 # -ce
1526 if ($task) {
1527 yyy();
1528 } else {
1529 zzz();
1530 }
1531 # -nce (default)
1533 if ($task) {
1534 yyy();
1535 }
1536 else {
1537 zzz();
1538 }
1539 In this example the keyword else is placed on the same line which
1541 begins with the preceding closing block brace and is followed by
1542 its own opening block brace on the same line. Other keywords and
1543 function names which are formatted with this "cuddled" style are
1544 elsif, continue, catch, finally.
1545 Other block types can be formatted by specifying their names on a
1547 separate parameter -cbl, described in a later section.
1548 Cuddling between a pair of code blocks requires that the closing
1550 brace of the first block start a new line. If this block is
1551 entirely on one line in the input file, it is necessary to decide
1552 if it should be broken to allow cuddling. This decision is
1553 controlled by the flag -cbo=n discussed below. The default and
1554 recommended value of -cbo=1 bases this decision on the first block
1555 in the chain. If it spans multiple lines then cuddling is made and
1556 continues along the chain, regardless of the sizes of subsequent
1557 blocks. Otherwise, short lines remain intact.
1558 So for example, the -ce flag would not have any effect if the above
1560 snippet is rewritten as
1561 if ($task) { yyy() }
1563 else { zzz() }
1564 If the first block spans multiple lines, then cuddling can be done
1566 and will continue for the subsequent blocks in the chain, as
1567 illustrated in the previous snippet.
1568 If there are blank lines between cuddled blocks they will be
1570 eliminated. If there are comments after the closing brace where
1571 cuddling would occur then cuddling will be prevented. If this
1572 occurs, cuddling will restart later in the chain if possible.
1573 -cb, --cuddled-blocks
1575 This flag is equivalent to -ce.
1576 -cbl, --cuddled-block-list
1578 The built-in default cuddled block types are else, elsif, continue,
1579 catch, finally.
1580 Additional block types to which the -cuddled-blocks style applies
1582 can be defined by this parameter. This parameter is a character
1583 string, giving a list of block types separated by commas or spaces.
1584 For example, to cuddle code blocks of type sort, map and grep, in
1585 addition to the default types, the string could be set to
1586 -cbl="sort map grep"
1588 or equivalently
1590 -cbl=sort,map,grep
1592 Note however that these particular block types are typically short
1594 so there might not be much opportunity for the cuddled format
1595 style.
1596 Using commas avoids the need to protect spaces with quotes.
1598 As a diagnostic check, the flag --dump-cuddled-block-list or -dcbl
1600 can be used to view the hash of values that are generated by this
1601 flag.
1602 Finally, note that the -cbl flag by itself merely specifies which
1604 blocks are formatted with the cuddled format. It has no effect
1605 unless this formatting style is activated with -ce.
1606 -cblx, --cuddled-block-list-exclusive
1608 When cuddled else formatting is selected with -ce, setting this
1609 flag causes perltidy to ignore its built-in defaults and rely
1610 exclusively on the block types specified on the -cbl flag described
1611 in the previous section. For example, to avoid using cuddled catch
1612 and finally, which among in the defaults, the following set of
1613 parameters could be used:
1614 perltidy -ce -cbl='else elsif continue' -cblx
1616 -cbo=n, --cuddled-break-option=n
1618 Cuddled formatting is only possible between a pair of code blocks
1619 if the closing brace of the first block starts a new line. If a
1620 block is encountered which is entirely on a single line, and
1621 cuddled formatting is selected, it is necessary to make a decision
1622 as to whether or not to "break" the block, meaning to cause it to
1623 span multiple lines. This parameter controls that decision. The
1624 options are:
1625 cbo=0 Never force a short block to break.
1627 cbo=1 If the first of a pair of blocks is broken in the input file,
1628 then break the second [DEFAULT].
1629 cbo=2 Break open all blocks for maximal cuddled formatting.
1630 The default and recommended value is cbo=1. With this value, if
1632 the starting block of a chain spans multiple lines, then a cascade
1633 of breaks will occur for remaining blocks causing the entire chain
1634 to be cuddled.
1635 The option cbo=0 can produce erratic cuddling if there are numerous
1637 one-line blocks.
1638 The option cbo=2 produces maximal cuddling but will not allow any
1640 short blocks.
1641 -bl, --opening-brace-on-new-line
1643 Use the flag -bl to place the opening brace on a new line:
1644 if ( $input_file eq '-' ) # -bl
1646 {
1647 important_function();
1648 }
1649 This flag applies to all structural blocks, including named sub's
1651 (unless the -sbl flag is set -- see next item).
1652 The default style, -nbl, places an opening brace on the same line
1654 as the keyword introducing it. For example,
1655 if ( $input_file eq '-' ) { # -nbl (default)
1657 -sbl, --opening-sub-brace-on-new-line
1659 The flag -sbl can be used to override the value of -bl for the
1660 opening braces of named sub's. For example,
1661 perltidy -sbl
1663 produces this result:
1665 sub message
1667 {
1668 if (!defined($_[0])) {
1669 print("Hello, World\n");
1670 }
1671 else {
1672 print($_[0], "\n");
1673 }
1674 }
1675 This flag is negated with -nsbl. If -sbl is not specified, the
1677 value of -bl is used.
1678 -asbl, --opening-anonymous-sub-brace-on-new-line
1680 The flag -asbl is like the -sbl flag except that it applies to
1681 anonymous sub's instead of named subs. For example
1682 perltidy -asbl
1684 produces this result:
1686 $a = sub
1688 {
1689 if ( !defined( $_[0] ) ) {
1690 print("Hello, World\n");
1691 }
1692 else {
1693 print( $_[0], "\n" );
1694 }
1695 };
1696 This flag is negated with -nasbl, and the default is -nasbl.
1698 -bli, --brace-left-and-indent
1700 The flag -bli is the same as -bl but in addition it causes one unit
1701 of continuation indentation ( see -ci ) to be placed before an
1702 opening and closing block braces.
1703 For example,
1705 if ( $input_file eq '-' ) # -bli
1707 {
1708 important_function();
1709 }
1710 By default, this extra indentation occurs for blocks of type: if,
1712 elsif, else, unless, for, foreach, sub, while, until, and also with
1713 a preceding label. The next item shows how to change this.
1714 -blil=s, --brace-left-and-indent-list=s
1716 Use this parameter to change the types of block braces for which
1717 the -bli flag applies; see "Specifying Block Types". For example,
1718 -blil='if elsif else' would apply it to only "if/elsif/else"
1719 blocks.
1720 -bar, --opening-brace-always-on-right
1722 The default style, -nbl places the opening code block brace on a
1723 new line if it does not fit on the same line as the opening
1724 keyword, like this:
1725 if ( $bigwasteofspace1 && $bigwasteofspace2
1727 || $bigwasteofspace3 && $bigwasteofspace4 )
1728 {
1729 big_waste_of_time();
1730 }
1731 To force the opening brace to always be on the right, use the -bar
1733 flag. In this case, the above example becomes
1734 if ( $bigwasteofspace1 && $bigwasteofspace2
1736 || $bigwasteofspace3 && $bigwasteofspace4 ) {
1737 big_waste_of_time();
1738 }
1739 A conflict occurs if both -bl and -bar are specified.
1741 -otr, --opening-token-right and related flags
1743 The -otr flag is a hint that perltidy should not place a break
1744 between a comma and an opening token. For example:
1745 # default formatting
1747 push @{ $self->{$module}{$key} },
1748 {
1749 accno => $ref->{accno},
1750 description => $ref->{description}
1751 };
1752 # perltidy -otr
1754 push @{ $self->{$module}{$key} }, {
1755 accno => $ref->{accno},
1756 description => $ref->{description}
1757 };
1758 The flag -otr is actually an abbreviation for three other flags
1760 which can be used to control parens, hash braces, and square
1761 brackets separately if desired:
1762 -opr or --opening-paren-right
1764 -ohbr or --opening-hash-brace-right
1765 -osbr or --opening-square-bracket-right
1766 -wn, --weld-nested-containers
1768 The -wn flag causes closely nested pairs of opening and closing
1769 container symbols (curly braces, brackets, or parens) to be
1770 "welded" together, meaning that they are treated as if combined
1771 into a single unit, with the indentation of the innermost code
1772 reduced to be as if there were just a single container symbol.
1773 For example:
1775 # default formatting
1777 do {
1778 {
1779 next if $x == $y;
1780 }
1781 } until $x++ > $z;
1782 # perltidy -wn
1784 do { {
1785 next if $x == $y;
1786 } } until $x++ > $z;
1787 When this flag is set perltidy makes a preliminary pass through the
1789 file and identifies all nested pairs of containers. To qualify as
1790 a nested pair, the closing container symbols must be immediately
1791 adjacent. The opening symbols must either be adjacent, or, if the
1792 outer opening symbol is an opening paren, they may be separated by
1793 any single non-container symbol or something that looks like a
1794 function evaluation.
1795 Any container symbol may serve as both the inner container of one
1797 pair and as the outer container of an adjacent pair. Consequently,
1798 any number of adjacent opening or closing symbols may join together
1799 in weld. For example, here are three levels of wrapped function
1800 calls:
1801 # default formatting
1803 my (@date_time) = Localtime(
1804 Date_to_Time(
1805 Add_Delta_DHMS(
1806 $year, $month, $day, $hour, $minute, $second,
1807 '0', $offset, '0', '0'
1808 )
1809 )
1810 );
1811 # perltidy -wn
1813 my (@date_time) = Localtime( Date_to_Time( Add_Delta_DHMS(
1814 $year, $month, $day, $hour, $minute, $second,
1815 '0', $offset, '0', '0'
1816 ) ) );
1817 Notice how the indentation of the inner lines are reduced by two
1819 levels in this case. This example also shows the typical result of
1820 this formatting, namely it is a sandwich consisting of an initial
1821 opening layer, a central section of any complexity forming the
1822 "meat" of the sandwich, and a final closing layer. This
1823 predictable structure helps keep the compacted structure readable.
1824 The inner sandwich layer is required to be at least one line thick.
1826 If this cannot be achieved, welding does not occur. This
1827 constraint can cause formatting to take a couple of iterations to
1828 stabilize when it is first applied to a script. The -conv flag can
1829 be used to insure that the final format is achieved in a single
1830 run.
1831 Here is an example illustrating a welded container within a welded
1833 containers:
1834 # default formatting
1836 $x->badd(
1837 bmul(
1838 $class->new(
1839 abs(
1840 $sx * int( $xr->numify() ) & $sy * int( $yr->numify() )
1841 )
1842 ),
1843 $m
1844 )
1845 );
1846 # perltidy -wn
1848 $x->badd( bmul(
1849 $class->new( abs(
1850 $sx * int( $xr->numify() ) & $sy * int( $yr->numify() )
1851 ) ),
1852 $m
1853 ) );
1854 This format option is quite general but there are some limitations.
1856 One limitation is that any line length limit still applies and can
1858 cause long welded sections to be broken into multiple lines.
1859 Another limitation is that an opening symbol which delimits quoted
1861 text cannot be included in a welded pair. This is because quote
1862 delimiters are treated specially in perltidy.
1863 Finally, the stacking of containers defined by this flag have
1865 priority over any other container stacking flags. This is because
1866 any welding is done first.
1867 Vertical tightness of non-block curly braces, parentheses, and square
1869 brackets.
1870 These parameters control what shall be called vertical tightness.
1871 Here are the main points:
1872 · Opening tokens (except for block braces) are controlled by
1874 -vt=n, or --vertical-tightness=n, where
1875 -vt=0 always break a line after opening token (default).
1877 -vt=1 do not break unless this would produce more than one
1878 step in indentation in a line.
1879 -vt=2 never break a line after opening token
1880 · You must also use the -lp flag when you use the -vt flag; the
1882 reason is explained below.
1883 · Closing tokens (except for block braces) are controlled by
1885 -vtc=n, or --vertical-tightness-closing=n, where
1886 -vtc=0 always break a line before a closing token (default),
1888 -vtc=1 do not break before a closing token which is followed
1889 by a semicolon or another closing token, and is not in
1890 a list environment.
1891 -vtc=2 never break before a closing token.
1892 The rules for -vtc=1 are designed to maintain a reasonable
1894 balance between tightness and readability in complex lists.
1895 · Different controls may be applied to different token types, and
1897 it is also possible to control block braces; see below.
1898 · Finally, please note that these vertical tightness flags are
1900 merely hints to the formatter, and it cannot always follow
1901 them. Things which make it difficult or impossible include
1902 comments, blank lines, blocks of code within a list, and
1903 possibly the lack of the -lp parameter. Also, these flags may
1904 be ignored for very small lists (2 or 3 lines in length).
1905 Here are some examples:
1907 # perltidy -lp -vt=0 -vtc=0
1909 %romanNumerals = (
1910 one => 'I',
1911 two => 'II',
1912 three => 'III',
1913 four => 'IV',
1914 );
1915 # perltidy -lp -vt=1 -vtc=0
1917 %romanNumerals = ( one => 'I',
1918 two => 'II',
1919 three => 'III',
1920 four => 'IV',
1921 );
1922 # perltidy -lp -vt=1 -vtc=1
1924 %romanNumerals = ( one => 'I',
1925 two => 'II',
1926 three => 'III',
1927 four => 'IV', );
1928 The difference between -vt=1 and -vt=2 is shown here:
1930 # perltidy -lp -vt=1
1932 $init->add(
1933 mysprintf( "(void)find_threadsv(%s);",
1934 cstring( $threadsv_names[ $op->targ ] )
1935 )
1936 );
1937 # perltidy -lp -vt=2
1939 $init->add( mysprintf( "(void)find_threadsv(%s);",
1940 cstring( $threadsv_names[ $op->targ ] )
1941 )
1942 );
1943 With -vt=1, the line ending in "add(" does not combine with the
1945 next line because the next line is not balanced. This can help
1946 with readability, but -vt=2 can be used to ignore this rule.
1947 The tightest, and least readable, code is produced with both
1949 "-vt=2" and "-vtc=2":
1950 # perltidy -lp -vt=2 -vtc=2
1952 $init->add( mysprintf( "(void)find_threadsv(%s);",
1953 cstring( $threadsv_names[ $op->targ ] ) ) );
1954 Notice how the code in all of these examples collapses vertically
1956 as -vt increases, but the indentation remains unchanged. This is
1957 because perltidy implements the -vt parameter by first formatting
1958 as if -vt=0, and then simply overwriting one output line on top of
1959 the next, if possible, to achieve the desired vertical tightness.
1960 The -lp indentation style has been designed to allow this vertical
1961 collapse to occur, which is why it is required for the -vt
1962 parameter.
1963 The -vt=n and -vtc=n parameters apply to each type of container
1965 token. If desired, vertical tightness controls can be applied
1966 independently to each of the closing container token types.
1967 The parameters for controlling parentheses are -pvt=n or
1969 --paren-vertical-tightness=n, and -pcvt=n or
1970 --paren-vertical-tightness-closing=n.
1971 Likewise, the parameters for square brackets are -sbvt=n or
1973 --square-bracket-vertical-tightness=n, and -sbcvt=n or
1974 --square-bracket-vertical-tightness-closing=n.
1975 Finally, the parameters for controlling non-code block braces are
1977 -bvt=n or --brace-vertical-tightness=n, and -bcvt=n or
1978 --brace-vertical-tightness-closing=n.
1979 In fact, the parameter -vt=n is actually just an abbreviation for
1981 -pvt=n -bvt=n sbvt=n, and likewise -vtc=n is an abbreviation for
1982 -pvtc=n -bvtc=n sbvtc=n.
1983 -bbvt=n or --block-brace-vertical-tightness=n
1985 The -bbvt=n flag is just like the -vt=n flag but applies to opening
1986 code block braces.
1987 -bbvt=0 break after opening block brace (default).
1989 -bbvt=1 do not break unless this would produce more than one
1990 step in indentation in a line.
1991 -bbvt=2 do not break after opening block brace.
1992 It is necessary to also use either -bl or -bli for this to work,
1994 because, as with other vertical tightness controls, it is
1995 implemented by simply overwriting a line ending with an opening
1996 block brace with the subsequent line. For example:
1997 # perltidy -bli -bbvt=0
1999 if ( open( FILE, "< $File" ) )
2000 {
2001 while ( $File = <FILE> )
2002 {
2003 $In .= $File;
2004 $count++;
2005 }
2006 close(FILE);
2007 }
2008 # perltidy -bli -bbvt=1
2010 if ( open( FILE, "< $File" ) )
2011 { while ( $File = <FILE> )
2012 { $In .= $File;
2013 $count++;
2014 }
2015 close(FILE);
2016 }
2017 By default this applies to blocks associated with keywords if,
2019 elsif, else, unless, for, foreach, sub, while, until, and also with
2020 a preceding label. This can be changed with the parameter
2021 -bbvtl=string, or --block-brace-vertical-tightness-list=string,
2022 where string is a space-separated list of block types. For more
2023 information on the possible values of this string, see "Specifying
2024 Block Types"
2025 For example, if we want to just apply this style to "if", "elsif",
2027 and "else" blocks, we could use "perltidy -bli -bbvt=1 -bbvtl='if
2028 elsif else'".
2029 There is no vertical tightness control for closing block braces;
2031 with one exception they will be placed on separate lines. The
2032 exception is that a cascade of closing block braces may be stacked
2033 on a single line. See -scbb.
2034 -sot, --stack-opening-tokens and related flags
2036 The -sot flag tells perltidy to "stack" opening tokens when
2037 possible to avoid lines with isolated opening tokens.
2038 For example:
2040 # default
2042 $opt_c = Text::CSV_XS->new(
2043 {
2044 binary => 1,
2045 sep_char => $opt_c,
2046 always_quote => 1,
2047 }
2048 );
2049 # -sot
2051 $opt_c = Text::CSV_XS->new( {
2052 binary => 1,
2053 sep_char => $opt_c,
2054 always_quote => 1,
2055 }
2056 );
2057 For detailed control of individual closing tokens the following
2059 controls can be used:
2060 -sop or --stack-opening-paren
2062 -sohb or --stack-opening-hash-brace
2063 -sosb or --stack-opening-square-bracket
2064 -sobb or --stack-opening-block-brace
2065 The flag -sot is an abbreviation for -sop -sohb -sosb.
2067 The flag -sobb is an abbreviation for -bbvt=2 -bbvtl='*'. This
2069 will case a cascade of opening block braces to appear on a single
2070 line, although this an uncommon occurrence except in test scripts.
2071 -sct, --stack-closing-tokens and related flags
2073 The -sct flag tells perltidy to "stack" closing tokens when
2074 possible to avoid lines with isolated closing tokens.
2075 For example:
2077 # default
2079 $opt_c = Text::CSV_XS->new(
2080 {
2081 binary => 1,
2082 sep_char => $opt_c,
2083 always_quote => 1,
2084 }
2085 );
2086 # -sct
2088 $opt_c = Text::CSV_XS->new(
2089 {
2090 binary => 1,
2091 sep_char => $opt_c,
2092 always_quote => 1,
2093 } );
2094 The -sct flag is somewhat similar to the -vtc flags, and in some
2096 cases it can give a similar result. The difference is that the
2097 -vtc flags try to avoid lines with leading opening tokens by
2098 "hiding" them at the end of a previous line, whereas the -sct flag
2099 merely tries to reduce the number of lines with isolated closing
2100 tokens by stacking them but does not try to hide them. For
2101 example:
2102 # -vtc=2
2104 $opt_c = Text::CSV_XS->new(
2105 {
2106 binary => 1,
2107 sep_char => $opt_c,
2108 always_quote => 1, } );
2109 For detailed control of the stacking of individual closing tokens
2111 the following controls can be used:
2112 -scp or --stack-closing-paren
2114 -schb or --stack-closing-hash-brace
2115 -scsb or --stack-closing-square-bracket
2116 -scbb or --stack-closing-block-brace
2117 The flag -sct is an abbreviation for stacking the non-block closing
2119 tokens, -scp -schb -scsb.
2120 Stacking of closing block braces, -scbb, causes a cascade of
2122 isolated closing block braces to be combined into a single line as
2123 in the following example:
2124 # -scbb:
2126 for $w1 (@w1) {
2127 for $w2 (@w2) {
2128 for $w3 (@w3) {
2129 for $w4 (@w4) {
2130 push( @lines, "$w1 $w2 $w3 $w4\n" );
2131 } } } }
2132 To simplify input even further for the case in which both opening
2134 and closing non-block containers are stacked, the flag -sac or
2135 --stack-all-containers is an abbreviation for -sot -sot.
2136 -dnl, --delete-old-newlines
2138 By default, perltidy first deletes all old line break locations,
2139 and then it looks for good break points to match the desired line
2140 length. Use -ndnl or --nodelete-old-newlines to force perltidy to
2141 retain all old line break points.
2142 -anl, --add-newlines
2144 By default, perltidy will add line breaks when necessary to create
2145 continuations of long lines and to improve the script appearance.
2146 Use -nanl or --noadd-newlines to prevent any new line breaks.
2147 This flag does not prevent perltidy from eliminating existing line
2149 breaks; see --freeze-newlines to completely prevent changes to line
2150 break points.
2151 Controlling whether perltidy breaks before or after operators
2153 Four command line parameters provide some control over whether a
2154 line break should be before or after specific token types. Two
2155 parameters give detailed control:
2156 -wba=s or --want-break-after=s, and
2158 -wbb=s or --want-break-before=s.
2160 These parameters are each followed by a quoted string, s,
2162 containing a list of token types (separated only by spaces). No
2163 more than one of each of these parameters should be specified,
2164 because repeating a command-line parameter always overwrites the
2165 previous one before perltidy ever sees it.
2166 By default, perltidy breaks after these token types:
2168 % + - * / x != == >= <= =~ !~ < > | &
2169 = **= += *= &= <<= &&= -= /= |= >>= ||= //= .= %= ^= x=
2170 And perltidy breaks before these token types by default:
2172 . << >> -> && || //
2173 To illustrate, to cause a break after a concatenation operator,
2175 '.', rather than before it, the command line would be
2176 -wba="."
2178 As another example, the following command would cause a break
2180 before math operators '+', '-', '/', and '*':
2181 -wbb="+ - / *"
2183 These commands should work well for most of the token types that
2185 perltidy uses (use --dump-token-types for a list). Also try the -D
2186 flag on a short snippet of code and look at the .DEBUG file to see
2187 the tokenization. However, for a few token types there may be
2188 conflicts with hardwired logic which cause unexpected results. One
2189 example is curly braces, which should be controlled with the
2190 parameter bl provided for that purpose.
2191 WARNING Be sure to put these tokens in quotes to avoid having them
2193 misinterpreted by your command shell.
2194 Two additional parameters are available which, though they provide
2196 no further capability, can simplify input are:
2197 -baao or --break-after-all-operators,
2199 -bbao or --break-before-all-operators.
2201 The -baao sets the default to be to break after all of the
2203 following operators:
2204 % + - * / x != == >= <= =~ !~ < > | &
2206 = **= += *= &= <<= &&= -= /= |= >>= ||= //= .= %= ^= x=
2207 . : ? && || and or err xor
2208 and the -bbao flag sets the default to break before all of these
2210 operators. These can be used to define an initial break preference
2211 which can be fine-tuned with the -wba and -wbb flags. For example,
2212 to break before all operators except an = one could use --bbao
2213 -wba='=' rather than listing every single perl operator except = on
2214 a -wbb flag.
2215 Controlling List Formatting
2217 Perltidy attempts to place comma-separated arrays of values in tables
2218 which look good. Its default algorithms usually work well, and they
2219 have been improving with each release, but several parameters are
2220 available to control list formatting.
2221 -boc, --break-at-old-comma-breakpoints
2223 This flag tells perltidy to try to break at all old commas. This
2224 is not the default. Normally, perltidy makes a best guess at list
2225 formatting, and seldom uses old comma breakpoints. Usually this
2226 works well, but consider:
2227 my @list = (1,
2229 1, 1,
2230 1, 2, 1,
2231 1, 3, 3, 1,
2232 1, 4, 6, 4, 1,);
2233 The default formatting will flatten this down to one line:
2235 # perltidy (default)
2237 my @list = ( 1, 1, 1, 1, 2, 1, 1, 3, 3, 1, 1, 4, 6, 4, 1, );
2238 which hides the structure. Using -boc, plus additional flags to
2240 retain the original style, yields
2241 # perltidy -boc -lp -pt=2 -vt=1 -vtc=1
2243 my @list = (1,
2244 1, 1,
2245 1, 2, 1,
2246 1, 3, 3, 1,
2247 1, 4, 6, 4, 1,);
2248 A disadvantage of this flag is that all tables in the file must
2250 already be nicely formatted. For another possibility see the -fs
2251 flag in "Skipping Selected Sections of Code".
2252 -mft=n, --maximum-fields-per-table=n
2254 If the computed number of fields for any table exceeds n, then it
2255 will be reduced to n. The default value for n is a large number,
2256 40. While this value should probably be left unchanged as a
2257 general rule, it might be used on a small section of code to force
2258 a list to have a particular number of fields per line, and then
2259 either the -boc flag could be used to retain this formatting, or a
2260 single comment could be introduced somewhere to freeze the
2261 formatting in future applications of perltidy.
2262 # perltidy -mft=2
2264 @month_of_year = (
2265 'Jan', 'Feb',
2266 'Mar', 'Apr',
2267 'May', 'Jun',
2268 'Jul', 'Aug',
2269 'Sep', 'Oct',
2270 'Nov', 'Dec'
2271 );
2272 -cab=n, --comma-arrow-breakpoints=n
2274 A comma which follows a comma arrow, '=>', is given special
2275 consideration. In a long list, it is common to break at all such
2276 commas. This parameter can be used to control how perltidy breaks
2277 at these commas. (However, it will have no effect if old comma
2278 breaks are being forced because -boc is used). The possible values
2279 of n are:
2280 n=0 break at all commas after =>
2282 n=1 stable: break at all commas after => if container is open,
2283 EXCEPT FOR one-line containers
2284 n=2 break at all commas after =>, BUT try to form the maximum
2285 maximum one-line container lengths
2286 n=3 do not treat commas after => specially at all
2287 n=4 break everything: like n=0 but ALSO break a short container with
2288 a => not followed by a comma when -vt=0 is used
2289 n=5 stable: like n=1 but ALSO break at open one-line containers when
2290 -vt=0 is used (default)
2291 For example, given the following single line, perltidy by default
2293 will not add any line breaks because it would break the existing
2294 one-line container:
2295 bless { B => $B, Root => $Root } => $package;
2297 Using -cab=0 will force a break after each comma-arrow item:
2299 # perltidy -cab=0:
2301 bless {
2302 B => $B,
2303 Root => $Root
2304 } => $package;
2305 If perltidy is subsequently run with this container broken, then by
2307 default it will break after each '=>' because the container is now
2308 broken. To reform a one-line container, the parameter -cab=2 could
2309 be used.
2310 The flag -cab=3 can be used to prevent these commas from being
2312 treated specially. In this case, an item such as "01" => 31 is
2313 treated as a single item in a table. The number of fields in this
2314 table will be determined by the same rules that are used for any
2315 other table. Here is an example.
2316 # perltidy -cab=3
2318 my %last_day = (
2319 "01" => 31, "02" => 29, "03" => 31, "04" => 30,
2320 "05" => 31, "06" => 30, "07" => 31, "08" => 31,
2321 "09" => 30, "10" => 31, "11" => 30, "12" => 31
2322 );
2323 Retaining or Ignoring Existing Line Breaks
2325 Several additional parameters are available for controlling the extent
2326 to which line breaks in the input script influence the output script.
2327 In most cases, the default parameter values are set so that, if a
2328 choice is possible, the output style follows the input style. For
2329 example, if a short logical container is broken in the input script,
2330 then the default behavior is for it to remain broken in the output
2331 script.
2332 Most of the parameters in this section would only be required for a
2334 one-time conversion of a script from short container lengths to longer
2335 container lengths. The opposite effect, of converting long container
2336 lengths to shorter lengths, can be obtained by temporarily using a
2337 short maximum line length.
2338 -bol, --break-at-old-logical-breakpoints
2340 By default, if a logical expression is broken at a "&&", "||",
2341 "and", or "or", then the container will remain broken. Also,
2342 breaks at internal keywords "if" and "unless" will normally be
2343 retained. To prevent this, and thus form longer lines, use -nbol.
2344 -bom, --break-at-old-method-breakpoints
2346 By default, a method call arrow "->" is considered a candidate for
2347 a breakpoint, but method chains will fill to the line width before
2348 a break is considered. With -bom, breaks before the arrow are
2349 preserved, so if you have preformatted a method chain:
2350 my $q = $rs
2352 ->related_resultset('CDs')
2353 ->related_resultset('Tracks')
2354 ->search({
2355 'track.id' => {-ident => 'none_search.id'},
2356 })->as_query;
2357 It will keep these breaks, rather than become this:
2359 my $q = $rs->related_resultset('CDs')->related_resultset('Tracks')->search({
2361 'track.id' => {-ident => 'none_search.id'},
2362 })->as_query;
2363 This flag will also look for and keep a 'cuddled' style of calls,
2365 in which lines begin with a closing paren followed by a call arrow,
2366 as in this example:
2367 my $q = $rs->related_resultset(
2369 'CDs'
2370 )->related_resultset(
2371 'Tracks'
2372 )->search( {
2373 'track.id' => { -ident => 'none_search.id' },
2374 } )->as_query;
2375 You may want to include the -weld-nested-containers flag in this
2377 case to keep nested braces and parens together, as in the last
2378 line.
2379 -bok, --break-at-old-keyword-breakpoints
2381 By default, perltidy will retain a breakpoint before keywords which
2382 may return lists, such as "sort" and <map>. This allows chains of
2383 these operators to be displayed one per line. Use -nbok to prevent
2384 retaining these breakpoints.
2385 -bot, --break-at-old-ternary-breakpoints
2387 By default, if a conditional (ternary) operator is broken at a ":",
2388 then it will remain broken. To prevent this, and thereby form
2389 longer lines, use -nbot.
2390 -boa, --break-at-old-attribute-breakpoints
2392 By default, if an attribute list is broken at a ":" in the source
2393 file, then it will remain broken. For example, given the following
2394 code, the line breaks at the ':'s will be retained:
2395 my @field
2397 : field
2398 : Default(1)
2399 : Get('Name' => 'foo') : Set('Name');
2400 If the attributes are on a single line in the source code then they
2402 will remain on a single line if possible.
2403 To prevent this, and thereby always form longer lines, use -nboa.
2405 -iob, --ignore-old-breakpoints
2407 Use this flag to tell perltidy to ignore existing line breaks to
2408 the maximum extent possible. This will tend to produce the longest
2409 possible containers, regardless of type, which do not exceed the
2410 line length limit.
2411 -kis, --keep-interior-semicolons
2413 Use the -kis flag to prevent breaking at a semicolon if there was
2414 no break there in the input file. Normally perltidy places a
2415 newline after each semicolon which terminates a statement unless
2416 several statements are contained within a one-line brace block. To
2417 illustrate, consider the following input lines:
2418 dbmclose(%verb_delim); undef %verb_delim;
2420 dbmclose(%expanded); undef %expanded;
2421 The default is to break after each statement, giving
2423 dbmclose(%verb_delim);
2425 undef %verb_delim;
2426 dbmclose(%expanded);
2427 undef %expanded;
2428 With perltidy -kis the multiple statements are retained:
2430 dbmclose(%verb_delim); undef %verb_delim;
2432 dbmclose(%expanded); undef %expanded;
2433 The statements are still subject to the specified value of maximum-
2435 line-length and will be broken if this maximum is exceeded.
2436 Blank Line Control
2438 Blank lines can improve the readability of a script if they are
2439 carefully placed. Perltidy has several commands for controlling the
2440 insertion, retention, and removal of blank lines.
2441 -fbl, --freeze-blank-lines
2443 Set -fbl if you want to the blank lines in your script to remain
2444 exactly as they are. The rest of the parameters in this section
2445 may then be ignored. (Note: setting the -fbl flag is equivalent to
2446 setting -mbl=0 and -kbl=2).
2447 -bbc, --blanks-before-comments
2449 A blank line will be introduced before a full-line comment. This
2450 is the default. Use -nbbc or --noblanks-before-comments to
2451 prevent such blank lines from being introduced.
2452 -blbs=n, --blank-lines-before-subs=n
2454 The parameter -blbs=n requests that least n blank lines precede a
2455 sub definition which does not follow a comment and which is more
2456 than one-line long. The default is <-blbs=1>. BEGIN and END
2457 blocks are included.
2458 The requested number of blanks statement will be inserted
2460 regardless of the value of --maximum-consecutive-blank-lines=n
2461 (-mbl=n) with the exception that if -mbl=0 then no blanks will be
2462 output.
2463 This parameter interacts with the value k of the parameter
2465 --maximum-consecutive-blank-lines=k (-mbl=k) as follows:
2466 1. If -mbl=0 then no blanks will be output. This allows all blanks
2468 to be suppressed with a single parameter. Otherwise,
2469 2. If the number of old blank lines in the script is less than n
2471 then additional blanks will be inserted to make the total n
2472 regardless of the value of -mbl=k.
2473 3. If the number of old blank lines in the script equals or exceeds
2475 n then this parameter has no effect, however the total will not
2476 exceed value specified on the -mbl=k flag.
2477 -blbp=n, --blank-lines-before-packages=n
2479 The parameter -blbp=n requests that least n blank lines precede a
2480 package which does not follow a comment. The default is -blbp=1.
2481 This parameter interacts with the value k of the parameter
2483 --maximum-consecutive-blank-lines=k (-mbl=k) in the same way as
2484 described for the previous item -blbs=n.
2485 -bbs, --blanks-before-subs
2487 For compatibility with previous versions, -bbs or
2488 --blanks-before-subs is equivalent to -blbp=1 and -blbs=1.
2489 Likewise, -nbbs or --noblanks-before-subs is equivalent to -blbp=0
2491 and -blbs=0.
2492 -bbb, --blanks-before-blocks
2494 A blank line will be introduced before blocks of coding delimited
2495 by for, foreach, while, until, and if, unless, in the following
2496 circumstances:
2497 · The block is not preceded by a comment.
2499 · The block is not a one-line block.
2501 · The number of consecutive non-blank lines at the current
2503 indentation depth is at least -lbl (see next section).
2504 This is the default. The intention of this option is to introduce
2506 some space within dense coding. This is negated with -nbbb or
2507 --noblanks-before-blocks.
2508 -lbl=n --long-block-line-count=n
2510 This controls how often perltidy is allowed to add blank lines
2511 before certain block types (see previous section). The default is
2512 8. Entering a value of 0 is equivalent to entering a very large
2513 number.
2514 -blao=i or --blank-lines-after-opening-block=i
2516 This control places a minimum of i blank lines after a line which
2517 ends with an opening block brace of a specified type. By default,
2518 this only applies to the block of a named sub, but this can be
2519 changed (see -blaol below). The default is not to do this (i=0).
2520 Please see the note below on using the -blao and -blbc options.
2522 -blbc=i or --blank-lines-before-closing-block=i
2524 This control places a minimum of i blank lines before a line which
2525 begins with a closing block brace of a specified type. By default,
2526 this only applies to the block of a named sub, but this can be
2527 changed (see -blbcl below). The default is not to do this (i=0).
2528 -blaol=s or --blank-lines-after-opening-block-list=s
2530 The parameter s is a list of block type keywords to which the flag
2531 -blao should apply. The section "Specifying Block Types" explains
2532 how to list block types.
2533 -blbcl=s or --blank-lines-before-closing-block-list=s
2535 This parameter is a list of block type keywords to which the flag
2536 -blbc should apply. The section "Specifying Block Types" explains
2537 how to list block types.
2538 Note on using the -blao and -blbc options.
2540 These blank line controls introduce a certain minimum number of
2541 blank lines in the text, but the final number of blank lines may be
2542 greater, depending on values of the other blank line controls and
2543 the number of old blank lines. A consequence is that introducing
2544 blank lines with these and other controls cannot be exactly undone,
2545 so some experimentation with these controls is recommended before
2546 using them.
2547 For example, suppose that for some reason we decide to introduce
2549 one blank space at the beginning and ending of all blocks. We
2550 could do this using
2551 perltidy -blao=2 -blbc=2 -blaol='*' -blbcl='*' filename
2553 Now suppose the script continues to be developed, but at some later
2555 date we decide we don't want these spaces after all. we might
2556 expect that running with the flags -blao=0 and -blbc=0 will undo
2557 them. However, by default perltidy retains single blank lines, so
2558 the blank lines remain.
2559 We can easily fix this by telling perltidy to ignore old blank
2561 lines by including the added parameter -kbl=0 and rerunning. Then
2562 the unwanted blank lines will be gone. However, this will cause
2563 all old blank lines to be ignored, perhaps even some that were
2564 added by hand to improve formatting. So please be cautious when
2565 using these parameters.
2566 -mbl=n --maximum-consecutive-blank-lines=n
2568 This parameter specifies the maximum number of consecutive blank
2569 lines which will be output within code sections of a script. The
2570 default is n=1. If the input file has more than n consecutive
2571 blank lines, the number will be reduced to n except as noted above
2572 for the -blbp and -blbs parameters. If n=0 then no blank lines
2573 will be output (unless all old blank lines are retained with the
2574 -kbl=2 flag of the next section).
2575 This flag obviously does not apply to pod sections, here-documents,
2577 and quotes.
2578 -kbl=n, --keep-old-blank-lines=n
2580 The -kbl=n flag gives you control over how your existing blank
2581 lines are treated.
2582 The possible values of n are:
2584 n=0 ignore all old blank lines
2586 n=1 stable: keep old blanks, but limited by the value of the B<-mbl=n> flag
2587 n=2 keep all old blank lines, regardless of the value of the B<-mbl=n> flag
2588 The default is n=1.
2590 -sob, --swallow-optional-blank-lines
2592 This is equivalent to kbl=0 and is included for compatibility with
2593 previous versions.
2594 -nsob, --noswallow-optional-blank-lines
2596 This is equivalent to kbl=1 and is included for compatibility with
2597 previous versions.
2598 Controls for blank lines around lines of consecutive keywords
2600 The parameters in this section provide some control over the placement
2602 of blank lines within and around groups of statements beginning with
2603 selected keywords. These blank lines are called here keyword group
2604 blanks, and all of the parameters begin with --keyword-group-blanks*,
2605 or -kgb* for short. The default settings do not employ these controls
2606 but they can be enabled with the following parameters:
2607 -kgbl=s or --keyword-group-blanks-list=s; s is a quoted string of
2609 keywords
2610 -kgbs=s or --keyword-group-blanks-size=s; s gives the number of
2612 keywords required to form a group.
2613 -kgbb=n or --keyword-group-blanks-before=n; n = (0, 1, or 2) controls a
2615 leading blank
2616 -kgba=n or --keyword-group-blanks-after=n; n = (0, 1, or 2) controls a
2618 trailing blank
2619 -kgbi or --keyword-group-blanks-inside is a switch for adding blanks
2621 between subgroups
2622 -kgbd or --keyword-group-blanks-delete is a switch for removing initial
2624 blank lines between keywords
2625 -kgbr=n or --keyword-group-blanks-repeat-count=n can limit the number
2627 of times this logic is applied
2628 In addition, the following abbreviations are available to for
2630 simplified usage:
2631 -kgb or --keyword-group-blanks is short for -kgbb=2 -kgba=2 kgbi
2633 -nkgb or --nokeyword-group-blanks, is short for -kgbb=1 -kgba=1 nkgbi
2635 Before describing the meaning of the parameters in detail let us look
2637 at an example which is formatted with default parameter settings.
2638 print "Entering test 2\n";
2640 use Test;
2641 use Encode qw(from_to encode decode
2642 encode_utf8 decode_utf8
2643 find_encoding is_utf8);
2644 use charnames qw(greek);
2645 my @encodings = grep( /iso-?8859/, Encode::encodings() );
2646 my @character_set = ( '0' .. '9', 'A' .. 'Z', 'a' .. 'z' );
2647 my @source = qw(ascii iso8859-1 cp1250);
2648 my @destiny = qw(cp1047 cp37 posix-bc);
2649 my @ebcdic_sets = qw(cp1047 cp37 posix-bc);
2650 my $str = join( '', map( chr($_), 0x20 .. 0x7E ) );
2651 return unless ($str);
2652 using perltidy -kgb gives:
2654 print "Entering test 2\n";
2656 <----------this blank controlled by -kgbb
2657 use Test;
2658 use Encode qw(from_to encode decode
2659 encode_utf8 decode_utf8
2660 find_encoding is_utf8);
2661 use charnames qw(greek);
2662 <---------this blank controlled by -kgbi
2663 my @encodings = grep( /iso-?8859/, Encode::encodings() );
2664 my @character_set = ( '0' .. '9', 'A' .. 'Z', 'a' .. 'z' );
2665 my @source = qw(ascii iso8859-1 cp1250);
2666 my @destiny = qw(cp1047 cp37 posix-bc);
2667 my @ebcdic_sets = qw(cp1047 cp37 posix-bc);
2668 my $str = join( '', map( chr($_), 0x20 .. 0x7E ) );
2669 <----------this blank controlled by -kgba
2670 return unless ($str);
2671 Blank lines have been introduced around the my and use sequences. What
2673 happened is that the default keyword list includes my and use but not
2674 print and return. So a continuous sequence of nine my and use
2675 statements was located. This number exceeds the default threshold of
2676 five, so blanks were placed before and after the entire group. Then,
2677 since there was also a subsequence of six my lines, a blank line was
2678 introduced to separate them.
2679 Finer control over blank placement can be achieved by using the
2681 individual parameters rather than the -kgb flag. The individual
2682 controls are as follows.
2683 -kgbl=s or --keyword-group-blanks-list=s, where s is a quoted string,
2685 defines the set of keywords which will be formed into groups. The
2686 string is a space separated list of keywords. The default set is
2687 s="use require local our my", but any list of keywords may be used.
2688 Comment lines may also be included in a keyword group, even though they
2689 are not keywords. To include ordinary block comments, include the
2690 symbol BC. To include static block comments (which normally begin with
2691 '##'), include the symbol SBC.
2692 -kgbs=s or --keyword-group-blanks-size=s, where s is a string
2694 describing the number of consecutive keyword statements forming a
2695 group. If s is an integer then it is the minimum number required for a
2696 group. A maximum value may also be given with the format s=min.max,
2697 where min is the minimum number and max is the maximum number, and the
2698 min and max values are separated by one or more dots. No groups will
2699 be found if the maximum is less than the minimum. The maximum is
2700 unlimited if not given. The default is s=5. Some examples:
2701 s min max number for group
2703 3 3 unlimited 3 or more
2704 1.1 1 1 1
2705 1..3 1 3 1 to 3
2706 1.0 1 0 (no match)
2707 -kgbb=n or --keyword-group-blanks-before=n specifies whether a blank
2709 should appear before the first line of the group, as follows:
2710 n=0 => (delete) an existing blank line will be removed
2712 n=1 => (stable) no change to the input file is made [DEFAULT]
2713 n=2 => (insert) a blank line is introduced if possible
2714 -kgba=n or --keyword-group-blanks-after=n likewise specifies whether a
2716 blank should appear after the last line of the group, using the same
2717 scheme (0=delete, 1=stable, 2=insert).
2718 -kgbi or --keyword-group-blanks-inside controls the insertion of blank
2720 lines between the first and last statement of the entire group. If
2721 there is a continuous run of a single statement type with more than the
2722 minimum threshold number (as specified with -kgbs=s) then this switch
2723 causes a blank line be inserted between this subgroup and the others.
2724 In the example above this happened between the use and my statements.
2725 -kgbd or --keyword-group-blanks-delete controls the deletion of any
2727 blank lines that exist in the the group when it is first scanned. When
2728 statements are initially scanned, any existing blank lines are included
2729 in the collection. Any such orignial blank lines will be deleted
2730 before any other insertions are made when the parameter -kgbd is set.
2731 The default is not to do this, -nkgbd.
2732 -kgbr=n or --keyword-group-blanks-repeat-count=n specifies n, the
2734 maximum number of times this logic will be applied to any file. The
2735 special value n=0 is the same as n=infinity which means it will be
2736 applied to an entire script [Default]. A value n=1 could be used to
2737 make it apply just one time for example. This might be useful for
2738 adjusting just the use statements in the top part of a module for
2739 example.
2740 -kgb or --keyword-group-blanks is an abbreviation equivalent to setting
2742 -kgbb=1 -kgba=1 -kgbi. This turns on keyword group formatting with a
2743 set of default values.
2744 -nkgb or --nokeyword-group-blanks is equivalent to -kgbb=0 -kgba nkgbi.
2746 This flag turns off keyword group blank lines and is the default
2747 setting.
2748 Here are a few notes about the functioning of this technique.
2750 · These parameters are probably more useful as part of a major code
2752 reformatting operation rather than as a routine formatting
2753 operation.
2754 In particular, note that deleting old blank lines with -kgbd is an
2756 irreversible operation so it should be applied with care. Existing
2757 blank lines may be serving an important role in controlling
2758 vertical alignment.
2759 · Conflicts which arise among these kgb* parameters and other blank
2761 line controls are generally resolved by producing the maximum
2762 number of blank lines implied by any parameter.
2763 For example, if the flags --freeze-blank-lines, or
2765 --keep-old-blank-lines=2, are set, then they have priority over any
2766 blank line deletion implied by the -kgb flags of this section, so
2767 no blank lines will be deleted.
2768 For another example, if a keyword group ends at a sub and the flag
2770 kgba=0 requests no blank line there, but we also have
2771 --blank-lines-before-subs=2, then two blank lines will still be
2772 introduced before the sub.
2773 · The introduction of blank lines does not occur if it would conflict
2775 with other input controls or code validity. For example, a blank
2776 line will not be placed within a here-doc or within a section of
2777 code marked with format skipping comments. And in general, a blank
2778 line will only be introduced at the end of a group if the next
2779 statement is a line of code.
2780 · The count which is used to determine the group size is not the
2782 number of lines but rather the total number of keywords which are
2783 found. Individual statements with a certain leading keyword may
2784 continue on multiple lines, but if any of these lines is nested
2785 more than one level deep then that group will be ended.
2786 · The search for groups of lines with similar leading keywords is
2788 based on the input source, not the final formatted source.
2789 Consequently, if the source code is badly formatted, it would be
2790 best to make a first formatting pass without these options.
2791 Styles
2793 A style refers to a convenient collection of existing parameters.
2794 -gnu, --gnu-style
2796 -gnu gives an approximation to the GNU Coding Standards (which do
2797 not apply to perl) as they are sometimes implemented. At present,
2798 this style overrides the default style with the following
2799 parameters:
2800 -lp -bl -noll -pt=2 -bt=2 -sbt=2 -icp
2802 -pbp, --perl-best-practices
2804 -pbp is an abbreviation for the parameters in the book Perl Best
2805 Practices by Damian Conway:
2806 -l=78 -i=4 -ci=4 -st -se -vt=2 -cti=0 -pt=1 -bt=1 -sbt=1 -bbt=1 -nsfs -nolq
2808 -wbb="% + - * / x != == >= <= =~ !~ < > | & =
2809 **= += *= &= <<= &&= -= /= |= >>= ||= //= .= %= ^= x="
2810 Please note that this parameter set includes -st and -se flags,
2812 which make perltidy act as a filter on one file only. These can be
2813 overridden by placing -nst and/or -nse after the -pbp parameter.
2814 Also note that the value of continuation indentation, -ci=4, is
2816 equal to the value of the full indentation, -i=4. In some complex
2817 statements perltidy will produce nicer results with -ci=2. This can
2818 be implemented by including -ci=2 after the -pbp parameter. For
2819 example,
2820 # perltidy -pbp
2822 $self->{_text} = (
2823 !$section ? ''
2824 : $type eq 'item' ? "the $section entry"
2825 : "the section on $section"
2826 )
2827 . (
2828 $page
2829 ? ( $section ? ' in ' : '' ) . "the $page$page_ext manpage"
2830 : ' elsewhere in this document'
2831 );
2832 # perltidy -pbp -ci=2
2834 $self->{_text} = (
2835 !$section ? ''
2836 : $type eq 'item' ? "the $section entry"
2837 : "the section on $section"
2838 )
2839 . (
2840 $page
2841 ? ( $section ? ' in ' : '' ) . "the $page$page_ext manpage"
2842 : ' elsewhere in this document'
2843 );
2844 One-line blocks
2846 There are a few points to note regarding one-line blocks. A one-
2847 line block is something like this,
2848 if ($x > 0) { $y = 1 / $x }
2850 where the contents within the curly braces is short enough to fit
2852 on a single line.
2853 With few exceptions, perltidy retains existing one-line blocks, if
2855 it is possible within the line-length constraint, but it does not
2856 attempt to form new ones. In other words, perltidy will try to
2857 follow the one-line block style of the input file.
2858 If an existing one-line block is longer than the maximum line
2860 length, however, it will be broken into multiple lines. When this
2861 happens, perltidy checks for and adds any optional terminating
2862 semicolon (unless the -nasc option is used) if the block is a code
2863 block.
2864 The main exception is that perltidy will attempt to form new one-
2866 line blocks following the keywords "map", "eval", and "sort",
2867 because these code blocks are often small and most clearly
2868 displayed in a single line.
2869 One-line block rules can conflict with the cuddled-else option.
2871 When the cuddled-else option is used, perltidy retains existing
2872 one-line blocks, even if they do not obey cuddled-else formatting.
2873 Occasionally, when one-line blocks get broken because they exceed
2875 the available line length, the formatting will violate the
2876 requested brace style. If this happens, reformatting the script a
2877 second time should correct the problem.
2878 Sometimes it might be desirable to convert a script to have one-
2880 line blocks whenever possible. Although there is currently no flag
2881 for this, a simple workaround is to execute perltidy twice, once
2882 with the flag -noadd-newlines and then once again with normal
2883 parameters, like this:
2884 cat infile | perltidy -nanl | perltidy >outfile
2886 When executed on this snippet
2888 if ( $? == -1 ) {
2890 die "failed to execute: $!\n";
2891 }
2892 if ( $? == -1 ) {
2893 print "Had enough.\n";
2894 die "failed to execute: $!\n";
2895 }
2896 the result is
2898 if ( $? == -1 ) { die "failed to execute: $!\n"; }
2900 if ( $? == -1 ) {
2901 print "Had enough.\n";
2902 die "failed to execute: $!\n";
2903 }
2904 This shows that blocks with a single statement become one-line
2906 blocks.
2907 -olbs=n, --one-line-block-semicolons=n
2909 This flag controls the placement of semicolons at the end of one-
2910 line blocks. Semicolons are optional before a closing block brace,
2911 and frequently they are omitted at the end of a one-line block
2912 containing just a single statement. By default, perltidy follows
2913 the input file regarding these semicolons, but this behavior can be
2914 controlled by this flag. The values of n are:
2915 n=0 remove terminal semicolons in one-line blocks having a single statement
2917 n=1 stable; keep input file placement of terminal semicolons [DEFAULT ]
2918 n=2 add terminal semicolons in all one-line blocks
2919 Note that the n=2 option has no effect if adding semicolons is
2921 prohibited with the -nasc flag. Also not that while n=2 adds
2922 missing semicolons to all one-line blocks, regardless of
2923 complexity, the n=0 option only removes ending semicolons which
2924 terminate one-line blocks containing just one semicolon. So these
2925 two options are not exact inverses.
2926 -olbn=n, --one-line-block-nesting=n
2928 Nested one-line blocks are lines with code blocks which themselves
2929 contain code blocks. For example, the following line is a nested
2930 one-line block.
2931 foreach (@list) { if ($_ eq $asked_for) { last } ++$found }
2933 The default behavior is to break such lines into multiple lines,
2935 but this behavior can be controlled with this flag. The values of
2936 n are:
2937 n=0 break nested one-line blocks into multiple lines [DEFAULT]
2939 n=1 stable: keep existing nested-one line blocks intact
2940 For the above example, the default formatting (-olbn=0) is
2942 foreach (@list) {
2944 if ( $_ eq $asked_for ) { last }
2945 ++$found;
2946 }
2947 If the parameter -olbn=1 is given, then the line will be left
2949 intact if it is a single line in the source, or it will be broken
2950 into multiple lines if it is broken in multiple lines in the
2951 source.
2952 Controlling Vertical Alignment
2954 Vertical alignment refers to lining up certain symbols in list of
2955 consecutive similar lines to improve readability. For example, the
2956 "fat commas" are aligned in the following statement:
2957 $data = $pkg->new(
2959 PeerAddr => join( ".", @port[ 0 .. 3 ] ),
2960 PeerPort => $port[4] * 256 + $port[5],
2961 Proto => 'tcp'
2962 );
2963 The only explicit control on vertical alignment is to turn it off using
2965 -novalign, a flag mainly intended for debugging. However, vertical
2966 alignment can be forced to stop and restart by selectively introducing
2967 blank lines. For example, a blank has been inserted in the following
2968 code to keep somewhat similar things aligned.
2969 %option_range = (
2971 'format' => [ 'tidy', 'html', 'user' ],
2972 'output-line-ending' => [ 'dos', 'win', 'mac', 'unix' ],
2973 'character-encoding' => [ 'none', 'utf8' ],
2974 'block-brace-tightness' => [ 0, 2 ],
2976 'brace-tightness' => [ 0, 2 ],
2977 'paren-tightness' => [ 0, 2 ],
2978 'square-bracket-tightness' => [ 0, 2 ],
2979 );
2980 Other Controls
2982 Deleting selected text
2983 Perltidy can selectively delete comments and/or pod documentation.
2984 The command -dac or --delete-all-comments will delete all comments
2985 and all pod documentation, leaving just code and any leading system
2986 control lines.
2987 The command -dp or --delete-pod will remove all pod documentation
2989 (but not comments).
2990 Two commands which remove comments (but not pod) are: -dbc or
2992 --delete-block-comments and -dsc or --delete-side-comments.
2993 (Hanging side comments will be deleted with block comments here.)
2994 The negatives of these commands also work, and are the defaults.
2996 When block comments are deleted, any leading 'hash-bang' will be
2997 retained. Also, if the -x flag is used, any system commands before
2998 a leading hash-bang will be retained (even if they are in the form
2999 of comments).
3000 Writing selected text to a file
3002 When perltidy writes a formatted text file, it has the ability to
3003 also send selected text to a file with a .TEE extension. This text
3004 can include comments and pod documentation.
3005 The command -tac or --tee-all-comments will write all comments and
3007 all pod documentation.
3008 The command -tp or --tee-pod will write all pod documentation (but
3010 not comments).
3011 The commands which write comments (but not pod) are: -tbc or
3013 --tee-block-comments and -tsc or --tee-side-comments. (Hanging
3014 side comments will be written with block comments here.)
3015 The negatives of these commands also work, and are the defaults.
3017 Using a .perltidyrc command file
3019 If you use perltidy frequently, you probably won't be happy until
3020 you create a .perltidyrc file to avoid typing commonly-used
3021 parameters. Perltidy will first look in your current directory for
3022 a command file named .perltidyrc. If it does not find one, it will
3023 continue looking for one in other standard locations.
3024 These other locations are system-dependent, and may be displayed
3026 with the command "perltidy -dpro". Under Unix systems, it will
3027 first look for an environment variable PERLTIDY. Then it will look
3028 for a .perltidyrc file in the home directory, and then for a
3029 system-wide file /usr/local/etc/perltidyrc, and then it will look
3030 for /etc/perltidyrc. Note that these last two system-wide files do
3031 not have a leading dot. Further system-dependent information will
3032 be found in the INSTALL file distributed with perltidy.
3033 Under Windows, perltidy will also search for a configuration file
3035 named perltidy.ini since Windows does not allow files with a
3036 leading period (.). Use "perltidy -dpro" to see the possible
3037 locations for your system. An example might be C:\Documents and
3038 Settings\All Users\perltidy.ini.
3039 Another option is the use of the PERLTIDY environment variable.
3041 The method for setting environment variables depends upon the
3042 version of Windows that you are using. Instructions for Windows 95
3043 and later versions can be found here:
3044 http://www.netmanage.com/000/20021101_005_tcm21-6336.pdf
3046 Under Windows NT / 2000 / XP the PERLTIDY environment variable can
3048 be placed in either the user section or the system section. The
3049 later makes the configuration file common to all users on the
3050 machine. Be sure to enter the full path of the configuration file
3051 in the value of the environment variable. Ex.
3052 PERLTIDY=C:\Documents and Settings\perltidy.ini
3053 The configuration file is free format, and simply a list of
3055 parameters, just as they would be entered on a command line. Any
3056 number of lines may be used, with any number of parameters per
3057 line, although it may be easiest to read with one parameter per
3058 line. Comment text begins with a #, and there must also be a space
3059 before the # for side comments. It is a good idea to put complex
3060 parameters in either single or double quotes.
3061 Here is an example of a .perltidyrc file:
3063 # This is a simple of a .perltidyrc configuration file
3065 # This implements a highly spaced style
3066 -se # errors to standard error output
3067 -w # show all warnings
3068 -bl # braces on new lines
3069 -pt=0 # parens not tight at all
3070 -bt=0 # braces not tight
3071 -sbt=0 # square brackets not tight
3072 The parameters in the .perltidyrc file are installed first, so any
3074 parameters given on the command line will have priority over them.
3075 To avoid confusion, perltidy ignores any command in the .perltidyrc
3077 file which would cause some kind of dump and an exit. These are:
3078 -h -v -ddf -dln -dop -dsn -dtt -dwls -dwrs -ss
3080 There are several options may be helpful in debugging a .perltidyrc
3082 file:
3083 · A very helpful command is --dump-profile or -dpro. It writes a
3085 list of all configuration filenames tested to standard output,
3086 and if a file is found, it dumps the content to standard output
3087 before exiting. So, to find out where perltidy looks for its
3088 configuration files, and which one if any it selects, just
3089 enter
3090 perltidy -dpro
3092 · It may be simplest to develop and test configuration files with
3094 alternative names, and invoke them with -pro=filename on the
3095 command line. Then rename the desired file to .perltidyrc when
3096 finished.
3097 · The parameters in the .perltidyrc file can be switched off with
3099 the -npro option.
3100 · The commands --dump-options, --dump-defaults,
3102 --dump-long-names, and --dump-short-names, all described below,
3103 may all be helpful.
3104 Creating a new abbreviation
3106 A special notation is available for use in a .perltidyrc file for
3107 creating an abbreviation for a group of options. This can be used
3108 to create a shorthand for one or more styles which are frequently,
3109 but not always, used. The notation is to group the options within
3110 curly braces which are preceded by the name of the alias (without
3111 leading dashes), like this:
3112 newword {
3114 -opt1
3115 -opt2
3116 }
3117 where newword is the abbreviation, and opt1, etc, are existing
3119 parameters or other abbreviations. The main syntax requirement is
3120 that the new abbreviation along with its opening curly brace must
3121 begin on a new line. Space before and after the curly braces is
3122 optional. For a specific example, the following line
3123 airy {-bl -pt=0 -bt=0 -sbt=0}
3125 could be placed in a .perltidyrc file, and then invoked at will
3127 with
3128 perltidy -airy somefile.pl
3130 (Either "-airy" or "--airy" may be used).
3132 Skipping leading non-perl commands with -x or --look-for-hash-bang
3134 If your script has leading lines of system commands or other text
3135 which are not valid perl code, and which are separated from the
3136 start of the perl code by a "hash-bang" line, ( a line of the form
3137 "#!...perl" ), you must use the -x flag to tell perltidy not to
3138 parse and format any lines before the "hash-bang" line. This
3139 option also invokes perl with a -x flag when checking the syntax.
3140 This option was originally added to allow perltidy to parse
3141 interactive VMS scripts, but it should be used for any script which
3142 is normally invoked with "perl -x".
3143 Making a file unreadable
3145 The goal of perltidy is to improve the readability of files, but
3146 there are two commands which have the opposite effect, --mangle and
3147 --extrude. They are actually merely aliases for combinations of
3148 other parameters. Both of these strip all possible whitespace, but
3149 leave comments and pod documents, so that they are essentially
3150 reversible. The difference between these is that --mangle puts the
3151 fewest possible line breaks in a script while --extrude puts the
3152 maximum possible. Note that these options do not provided any
3153 meaningful obfuscation, because perltidy can be used to reformat
3154 the files. They were originally developed to help test the
3155 tokenization logic of perltidy, but they have other uses. One use
3156 for --mangle is the following:
3157 perltidy --mangle myfile.pl -st | perltidy -o myfile.pl.new
3159 This will form the maximum possible number of one-line blocks (see
3161 next section), and can sometimes help clean up a badly formatted
3162 script.
3163 A similar technique can be used with --extrude instead of --mangle
3165 to make the minimum number of one-line blocks.
3166 Another use for --mangle is to combine it with -dac to reduce the
3168 file size of a perl script.
3169 Debugging
3171 The following flags are available for debugging:
3172 --dump-cuddled-block-list or -dcbl will dump to standard output the
3174 internal hash of cuddled block types created by a
3175 -cuddled-block-list input string.
3176 --dump-defaults or -ddf will write the default option set to
3178 standard output and quit
3179 --dump-profile or -dpro will write the name of the current
3181 configuration file and its contents to standard output and quit.
3182 --dump-options or -dop will write current option set to standard
3184 output and quit.
3185 --dump-long-names or -dln will write all command line long names
3187 (passed to Get_options) to standard output and quit.
3188 --dump-short-names or -dsn will write all command line short names
3190 to standard output and quit.
3191 --dump-token-types or -dtt will write a list of all token types to
3193 standard output and quit.
3194 --dump-want-left-space or -dwls will write the hash
3196 %want_left_space to standard output and quit. See the section on
3197 controlling whitespace around tokens.
3198 --dump-want-right-space or -dwrs will write the hash
3200 %want_right_space to standard output and quit. See the section on
3201 controlling whitespace around tokens.
3202 --no-memoize or -nmem will turn of memoizing. Memoization can
3204 reduce run time when running perltidy repeatedly in a single
3205 process. It is on by default but can be deactivated for testing
3206 with -nmem.
3207 --no-timestamp or -nts will eliminate any time stamps in output
3209 files to prevent differences in dates from causing test
3210 installation scripts to fail. There are just a couple of places
3211 where timestamps normally occur. One is in the headers of html
3212 files, and another is when the -cscw option is selected. The
3213 default is to allow timestamps (--timestamp or -ts).
3214 --file-size-order or -fso will cause files to be processed in order
3216 of increasing size, when multiple files are being processed. This
3217 is useful during program development, when large numbers of files
3218 with varying sizes are processed, because it can reduce virtual
3219 memory usage.
3220 -DEBUG will write a file with extension .DEBUG for each input file
3222 showing the tokenization of all lines of code.
3223 Working with MakeMaker, AutoLoader and SelfLoader
3225 The first $VERSION line of a file which might be eval'd by
3226 MakeMaker is passed through unchanged except for indentation. Use
3227 --nopass-version-line, or -npvl, to deactivate this feature.
3228 If the AutoLoader module is used, perltidy will continue formatting
3230 code after seeing an __END__ line. Use --nolook-for-autoloader, or
3231 -nlal, to deactivate this feature.
3232 Likewise, if the SelfLoader module is used, perltidy will continue
3234 formatting code after seeing a __DATA__ line. Use
3235 --nolook-for-selfloader, or -nlsl, to deactivate this feature.
3236 Working around problems with older version of Perl
3238 Perltidy contains a number of rules which help avoid known
3239 subtleties and problems with older versions of perl, and these
3240 rules always take priority over whatever formatting flags have been
3241 set. For example, perltidy will usually avoid starting a new line
3242 with a bareword, because this might cause problems if "use strict"
3243 is active.
3244 There is no way to override these rules.
3246
3248 The -html master switch
3249 The flag -html causes perltidy to write an html file with extension
3250 .html. So, for example, the following command
3251 perltidy -html somefile.pl
3253 will produce a syntax-colored html file named somefile.pl.html
3255 which may be viewed with a browser.
3256 Please Note: In this case, perltidy does not do any formatting to
3258 the input file, and it does not write a formatted file with
3259 extension .tdy. This means that two perltidy runs are required to
3260 create a fully reformatted, html copy of a script.
3261 The -pre flag for code snippets
3263 When the -pre flag is given, only the pre-formatted section, within
3264 the <PRE> and </PRE> tags, will be output. This simplifies
3265 inclusion of the output in other files. The default is to output a
3266 complete web page.
3267 The -nnn flag for line numbering
3269 When the -nnn flag is given, the output lines will be numbered.
3270 The -toc, or --html-table-of-contents flag
3272 By default, a table of contents to packages and subroutines will be
3273 written at the start of html output. Use -ntoc to prevent this.
3274 This might be useful, for example, for a pod document which
3275 contains a number of unrelated code snippets. This flag only
3276 influences the code table of contents; it has no effect on any
3277 table of contents produced by pod2html (see next item).
3278 The -pod, or --pod2html flag
3280 There are two options for formatting pod documentation. The
3281 default is to pass the pod through the Pod::Html module (which
3282 forms the basis of the pod2html utility). Any code sections are
3283 formatted by perltidy, and the results then merged. Note: perltidy
3284 creates a temporary file when Pod::Html is used; see "FILES".
3285 Also, Pod::Html creates temporary files for its cache.
3286 NOTE: Perltidy counts the number of "=cut" lines, and either moves
3288 the pod text to the top of the html file if there is one "=cut", or
3289 leaves the pod text in its original order (interleaved with code)
3290 otherwise.
3291 Most of the flags accepted by pod2html may be included in the
3293 perltidy command line, and they will be passed to pod2html. In
3294 some cases, the flags have a prefix "pod" to emphasize that they
3295 are for the pod2html, and this prefix will be removed before they
3296 are passed to pod2html. The flags which have the additional "pod"
3297 prefix are:
3298 --[no]podheader --[no]podindex --[no]podrecurse --[no]podquiet
3300 --[no]podverbose --podflush
3301 The flags which are unchanged from their use in pod2html are:
3303 --backlink=s --cachedir=s --htmlroot=s --libpods=s --title=s
3305 --podpath=s --podroot=s
3306 where 's' is an appropriate character string. Not all of these
3308 flags are available in older versions of Pod::Html. See your
3309 Pod::Html documentation for more information.
3310 The alternative, indicated with -npod, is not to use Pod::Html, but
3312 rather to format pod text in italics (or whatever the stylesheet
3313 indicates), without special html markup. This is useful, for
3314 example, if pod is being used as an alternative way to write
3315 comments.
3316 The -frm, or --frames flag
3318 By default, a single html output file is produced. This can be
3319 changed with the -frm option, which creates a frame holding a table
3320 of contents in the left panel and the source code in the right
3321 side. This simplifies code browsing. Assume, for example, that the
3322 input file is MyModule.pm. Then, for default file extension
3323 choices, these three files will be created:
3324 MyModule.pm.html - the frame
3326 MyModule.pm.toc.html - the table of contents
3327 MyModule.pm.src.html - the formatted source code
3328 Obviously this file naming scheme requires that output be directed
3330 to a real file (as opposed to, say, standard output). If this is
3331 not the case, or if the file extension is unknown, the -frm option
3332 will be ignored.
3333 The -text=s, or --html-toc-extension flag
3335 Use this flag to specify the extra file extension of the table of
3336 contents file when html frames are used. The default is "toc".
3337 See "Specifying File Extensions".
3338 The -sext=s, or --html-src-extension flag
3340 Use this flag to specify the extra file extension of the content
3341 file when html frames are used. The default is "src". See
3342 "Specifying File Extensions".
3343 The -hent, or --html-entities flag
3345 This flag controls the use of Html::Entities for html formatting.
3346 By default, the module Html::Entities is used to encode special
3347 symbols. This may not be the right thing for some browser/language
3348 combinations. Use --nohtml-entities or -nhent to prevent this.
3349 Style Sheets
3351 Style sheets make it very convenient to control and adjust the
3352 appearance of html pages. The default behavior is to write a page
3353 of html with an embedded style sheet.
3354 An alternative to an embedded style sheet is to create a page with
3356 a link to an external style sheet. This is indicated with the
3357 -css=filename, where the external style sheet is filename. The
3358 external style sheet filename will be created if and only if it
3359 does not exist. This option is useful for controlling multiple
3360 pages from a single style sheet.
3361 To cause perltidy to write a style sheet to standard output and
3363 exit, use the -ss, or --stylesheet, flag. This is useful if the
3364 style sheet could not be written for some reason, such as if the
3365 -pre flag was used. Thus, for example,
3366 perltidy -html -ss >mystyle.css
3368 will write a style sheet with the default properties to file
3370 mystyle.css.
3371 The use of style sheets is encouraged, but a web page without a
3373 style sheets can be created with the flag -nss. Use this option if
3374 you must to be sure that older browsers (roughly speaking, versions
3375 prior to 4.0 of Netscape Navigator and Internet Explorer) can
3376 display the syntax-coloring of the html files.
3377 Controlling HTML properties
3379 Note: It is usually more convenient to accept the default
3380 properties and then edit the stylesheet which is produced.
3381 However, this section shows how to control the properties with
3382 flags to perltidy.
3383 Syntax colors may be changed from their default values by flags of
3385 the either the long form, -html-color-xxxxxx=n, or more
3386 conveniently the short form, -hcx=n, where xxxxxx is one of the
3387 following words, and x is the corresponding abbreviation:
3388 Token Type xxxxxx x
3390 ---------- -------- --
3391 comment comment c
3392 number numeric n
3393 identifier identifier i
3394 bareword, function bareword w
3395 keyword keyword k
3396 quite, pattern quote q
3397 here doc text here-doc-text h
3398 here doc target here-doc-target hh
3399 punctuation punctuation pu
3400 parentheses paren p
3401 structural braces structure s
3402 semicolon semicolon sc
3403 colon colon co
3404 comma comma cm
3405 label label j
3406 sub definition name subroutine m
3407 pod text pod-text pd
3408 A default set of colors has been defined, but they may be changed
3410 by providing values to any of the following parameters, where n is
3411 either a 6 digit hex RGB color value or an ascii name for a color,
3412 such as 'red'.
3413 To illustrate, the following command will produce an html file
3415 somefile.pl.html with "aqua" keywords:
3416 perltidy -html -hck=00ffff somefile.pl
3418 and this should be equivalent for most browsers:
3420 perltidy -html -hck=aqua somefile.pl
3422 Perltidy merely writes any non-hex names that it sees in the html
3424 file. The following 16 color names are defined in the HTML 3.2
3425 standard:
3426 black => 000000,
3428 silver => c0c0c0,
3429 gray => 808080,
3430 white => ffffff,
3431 maroon => 800000,
3432 red => ff0000,
3433 purple => 800080,
3434 fuchsia => ff00ff,
3435 green => 008000,
3436 lime => 00ff00,
3437 olive => 808000,
3438 yellow => ffff00
3439 navy => 000080,
3440 blue => 0000ff,
3441 teal => 008080,
3442 aqua => 00ffff,
3443 Many more names are supported in specific browsers, but it is
3445 safest to use the hex codes for other colors. Helpful color tables
3446 can be located with an internet search for "HTML color tables".
3447 Besides color, two other character attributes may be set: bold, and
3449 italics. To set a token type to use bold, use the flag
3450 --html-bold-xxxxxx or -hbx, where xxxxxx or x are the long or short
3451 names from the above table. Conversely, to set a token type to NOT
3452 use bold, use --nohtml-bold-xxxxxx or -nhbx.
3453 Likewise, to set a token type to use an italic font, use the flag
3455 --html-italic-xxxxxx or -hix, where again xxxxxx or x are the long
3456 or short names from the above table. And to set a token type to
3457 NOT use italics, use --nohtml-italic-xxxxxx or -nhix.
3458 For example, to use bold braces and lime color, non-bold, italics
3460 keywords the following command would be used:
3461 perltidy -html -hbs -hck=00FF00 -nhbk -hik somefile.pl
3463 The background color can be specified with
3465 --html-color-background=n, or -hcbg=n for short, where n is a 6
3466 character hex RGB value. The default color of text is the value
3467 given to punctuation, which is black as a default.
3468 Here are some notes and hints:
3470 1. If you find a preferred set of these parameters, you may want to
3472 create a .perltidyrc file containing them. See the perltidy man
3473 page for an explanation.
3474 2. Rather than specifying values for these parameters, it is
3476 probably easier to accept the defaults and then edit a style sheet.
3477 The style sheet contains comments which should make this easy.
3478 3. The syntax-colored html files can be very large, so it may be
3480 best to split large files into smaller pieces to improve download
3481 times.
3482
3484 Specifying Block Types
3485 Several parameters which refer to code block types may be customized by
3486 also specifying an associated list of block types. The type of a block
3487 is the name of the keyword which introduces that block, such as if,
3488 else, or sub. An exception is a labeled block, which has no keyword,
3489 and should be specified with just a colon. To specify all blocks use
3490 '*'.
3491 The keyword sub indicates a named sub. For anonymous subs, use the
3493 special keyword asub.
3494 For example, the following parameter specifies "sub", labels, "BEGIN",
3496 and "END" blocks:
3497 -cscl="sub : BEGIN END"
3499 (the meaning of the -cscl parameter is described above.) Note that
3501 quotes are required around the list of block types because of the
3502 spaces. For another example, the following list specifies all block
3503 types for vertical tightness:
3504 -bbvtl='*'
3506 Specifying File Extensions
3508 Several parameters allow default file extensions to be overridden. For
3509 example, a backup file extension may be specified with -bext=ext, where
3510 ext is some new extension. In order to provides the user some
3511 flexibility, the following convention is used in all cases to decide if
3512 a leading '.' should be used. If the extension "ext" begins with
3513 "A-Z", "a-z", or "0-9", then it will be appended to the filename with
3514 an intermediate '.' (or perhaps a '_' on VMS systems). Otherwise, it
3515 will be appended directly.
3516 For example, suppose the file is somefile.pl. For "-bext=old", a '.'
3518 is added to give somefile.pl.old. For "-bext=.old", no additional '.'
3519 is added, so again the backup file is somefile.pl.old. For "-bext=~",
3520 then no dot is added, and the backup file will be somefile.pl~ .
3521
3523 The following list shows all short parameter names which allow a prefix
3524 'n' to produce the negated form:
3525 D anl asc aws b bbb bbc bbs bl bli boc bok bol bot ce
3527 csc dac dbc dcsc ddf dln dnl dop dp dpro dsc dsm dsn dtt dwls
3528 dwrs dws f fll frm fs hsc html ibc icb icp iob isbc lal log
3529 lp lsl ohbr okw ola oll opr opt osbr otr ple pod pvl q
3530 sbc sbl schb scp scsb sct se sfp sfs skp sob sohb sop sosb sot
3531 ssc st sts syn t tac tbc toc tp tqw tsc w x bar kis
3532 Equivalently, the prefix 'no' or 'no-' on the corresponding long names
3534 may be used.
3535
3537 Parsing Limitations
3538 Perltidy should work properly on most perl scripts. It does a lot
3539 of self-checking, but still, it is possible that an error could be
3540 introduced and go undetected. Therefore, it is essential to make
3541 careful backups and to test reformatted scripts.
3542 The main current limitation is that perltidy does not scan modules
3544 included with 'use' statements. This makes it necessary to guess
3545 the context of any bare words introduced by such modules. Perltidy
3546 has good guessing algorithms, but they are not infallible. When it
3547 must guess, it leaves a message in the log file.
3548 If you encounter a bug, please report it.
3550 What perltidy does not parse and format
3552 Perltidy indents but does not reformat comments and "qw" quotes.
3553 Perltidy does not in any way modify the contents of here documents
3554 or quoted text, even if they contain source code. (You could,
3555 however, reformat them separately). Perltidy does not format
3556 'format' sections in any way. And, of course, it does not modify
3557 pod documents.
3558
3560 Temporary files
3561 Under the -html option with the default --pod2html flag, a
3562 temporary file is required to pass text to Pod::Html. Unix systems
3563 will try to use the POSIX tmpnam() function. Otherwise the file
3564 perltidy.TMP will be temporarily created in the current working
3565 directory.
3566 Special files when standard input is used
3568 When standard input is used, the log file, if saved, is
3569 perltidy.LOG, and any errors are written to perltidy.ERR unless the
3570 -se flag is set. These are saved in the current working directory.
3571 Files overwritten
3573 The following file extensions are used by perltidy, and files with
3574 these extensions may be overwritten or deleted: .ERR, .LOG, .TEE,
3575 and/or .tdy, .html, and .bak, depending on the run type and
3576 settings.
3577 Files extensions limitations
3579 Perltidy does not operate on files for which the run could produce
3580 a file with a duplicated file extension. These extensions include
3581 .LOG, .ERR, .TEE, and perhaps .tdy and .bak, depending on the run
3582 type. The purpose of this rule is to prevent generating confusing
3583 filenames such as somefile.tdy.tdy.tdy.
3584
3586 An exit value of 0, 1, or 2 is returned by perltidy to indicate the
3587 status of the result.
3588 A exit value of 0 indicates that perltidy ran to completion with no
3590 error messages.
3591 A non-zero exit value indicates some kind of problem was detected.
3593 An exit value of 1 indicates that perltidy terminated prematurely,
3595 usually due to some kind of errors in the input parameters. This can
3596 happen for example if a parameter is misspelled or given an invalid
3597 value. Error messages in the standard error output will indicate the
3598 cause of any problem. If perltidy terminates prematurely then no
3599 output files will be produced.
3600 An exit value of 2 indicates that perltidy was able to run to
3602 completion but there there are (1) warning messages in the standard
3603 error output related to parameter errors or problems and/or (2) warning
3604 messages in the perltidy error file(s) relating to possible syntax
3605 errors in one or more of the source script(s) being tidied. When
3606 multiple files are being processed, an error detected in any single
3607 file will produce this type of exit condition.
3608
3610 perlstyle(1), Perl::Tidy(3)
3611
3613 The perltidy binary uses the Perl::Tidy module and is installed when
3614 that module is installed. The module name is case-sensitive. For
3615 example, the basic command for installing with cpanm is 'cpanm
3616 Perl::Tidy'.
3617
3619 This man page documents perltidy version 20200110
3620
3622 A list of current bugs and issues can be found at the CPAN site
3623 <https://rt.cpan.org/Public/Dist/Display.html?Name=Perl-Tidy>
3624 To report a new bug or problem, use the link on this page.
3626 The source code repository is at
3628 <https://github.com/perltidy/perltidy>.
3629
3631 Copyright (c) 2000-2020 by Steve Hancock
3632
3634 This package is free software; you can redistribute it and/or modify it
3635 under the terms of the "GNU General Public License".
3636 Please refer to the file "COPYING" for details.
3638
3640 This package is distributed in the hope that it will be useful, but
3641 WITHOUT ANY WARRANTY; without even the implied warranty of
3642 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
3643 See the "GNU General Public License" for more details.
3645perl v5.30.1 2020-01-30 PERLTIDY(1)