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). Perltidy never changes the input file.
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 -gnu somefile.pl
57 Execute perltidy on file somefile.pl with a style which approximates
59 the GNU Coding Standards for C programs. The output will be
60 somefile.pl.tdy.
61 perltidy -i=3 somefile.pl
63 Execute perltidy on file somefile.pl, with 3 columns for each level of
65 indentation (-i=3) instead of the default 4 columns. There will not be
66 any tabs in the reformatted script, except for any which already exist
67 in comments, pod documents, quotes, and here documents. Output will be
68 somefile.pl.tdy.
69 perltidy -i=3 -et=8 somefile.pl
71 Same as the previous example, except that leading whitespace will be
73 entabbed with one tab character per 8 spaces.
74 perltidy -ce -l=72 somefile.pl
76 Execute perltidy on file somefile.pl with all defaults except use
78 "cuddled elses" (-ce) and a maximum line length of 72 columns (-l=72)
79 instead of the default 80 columns.
80 perltidy -g somefile.pl
82 Execute perltidy on file somefile.pl and save a log file
84 somefile.pl.LOG which shows the nesting of braces, parentheses, and
85 square brackets at the start of every line.
86 perltidy -html somefile.pl
88 This will produce a file somefile.pl.html containing the script with
90 html markup. The output file will contain an embedded style sheet in
91 the <HEAD> section which may be edited to change the appearance.
92 perltidy -html -css=mystyle.css somefile.pl
94 This will produce a file somefile.pl.html containing the script with
96 html markup. This output file will contain a link to a separate style
97 sheet file mystyle.css. If the file mystyle.css does not exist, it
98 will be created. If it exists, it will not be overwritten.
99 perltidy -html -pre somefile.pl
101 Write an html snippet with only the PRE section to somefile.pl.html.
103 This is useful when code snippets are being formatted for inclusion in
104 a larger web page. No style sheet will be written in this case.
105 perltidy -html -ss >mystyle.css
107 Write a style sheet to mystyle.css and exit.
109 perltidy -html -frm mymodule.pm
111 Write html with a frame holding a table of contents and the source
113 code. The output files will be mymodule.pm.html (the frame),
114 mymodule.pm.toc.html (the table of contents), and mymodule.pm.src.html
115 (the source code).
116
118 The entire command line is scanned for options, and they are processed
119 before any files are processed. As a result, it does not matter
120 whether flags are before or after any filenames. However, the relative
121 order of parameters is important, with later parameters overriding the
122 values of earlier parameters.
123 For each parameter, there is a long name and a short name. The short
125 names are convenient for keyboard input, while the long names are self-
126 documenting and therefore useful in scripts. It is customary to use
127 two leading dashes for long names, but one may be used.
128 Most parameters which serve as on/off flags can be negated with a
130 leading "n" (for the short name) or a leading "no" or "no-" (for the
131 long name). For example, the flag to outdent long quotes is is -olq or
132 --outdent-long-quotes. The flag to skip this is -nolq or
133 --nooutdent-long-quotes or --no-outdent-long-quotes.
134 Options may not be bundled together. In other words, options -q and -g
136 may NOT be entered as -qg.
137 Option names may be terminated early as long as they are uniquely
139 identified. For example, instead of --dump-token-types, it would be
140 sufficient to enter --dump-tok, or even --dump-t, to uniquely identify
141 this command.
142 I/O control
144 The following parameters concern the files which are read and written.
145 -h, --help
147 Show summary of usage and exit.
148 -o=filename, --outfile=filename
150 Name of the output file (only if a single input file is being
151 processed). If no output file is specified, and output is not
152 redirected to the standard output, the output will go to
153 filename.tdy.
154 -st, --standard-output
156 Perltidy must be able to operate on an arbitrarily large number of
157 files in a single run, with each output being directed to a
158 different output file. Obviously this would conflict with
159 outputting to the single standard output device, so a special flag,
160 -st, is required to request outputting to the standard output. For
161 example,
162 perltidy somefile.pl -st >somefile.new.pl
164 This option may only be used if there is just a single input file.
166 The default is -nst or --nostandard-output.
167 -se, --standard-error-output
169 If perltidy detects an error when processing file somefile.pl, its
170 default behavior is to write error messages to file
171 somefile.pl.ERR. Use -se to cause all error messages to be sent to
172 the standard error output stream instead. This directive may be
173 negated with -nse. Thus, you may place -se in a .perltidyrc and
174 override it when desired with -nse on the command line.
175 -oext=ext, --output-file-extension=ext
177 Change the extension of the output file to be ext instead of the
178 default tdy (or html in case the --html option is used). See
179 "Specifying File Extensions".
180 -opath=path, --output-path=path
182 When perltidy creates a filename for an output file, by default it
183 merely appends an extension to the path and basename of the input
184 file. This parameter causes the path to be changed to path
185 instead.
186 The path should end in a valid path separator character, but
188 perltidy will try to add one if it is missing.
189 For example
191 perltidy somefile.pl -opath=/tmp/
193 will produce /tmp/somefile.pl.tdy. Otherwise, somefile.pl.tdy will
195 appear in whatever directory contains somefile.pl.
196 If the path contains spaces, it should be placed in quotes.
198 This parameter will be ignored if output is being directed to
200 standard output, or if it is being specified explicitly with the
201 -o=s parameter.
202 -b, --backup-and-modify-in-place
204 Modify the input file or files in-place and save the original with
205 the extension .bak. Any existing .bak file will be deleted. See
206 next item for changing the default backup extension.
207 A -b flag will be ignored if input is from standard input, or if
209 the -html flag is set.
210 -bext=ext, --backup-file-extension=ext
212 Change the extension of the backup file to be something other than
213 the default .bak. See "Specifying File Extensions".
214 -w, --warning-output
216 Setting -w causes any non-critical warning messages to be reported
217 as errors. These include messages about possible pod problems,
218 possibly bad starting indentation level, and cautions about
219 indirect object usage. The default, -nw or --nowarning-output, is
220 not to include these warnings.
221 -q, --quiet
223 Deactivate error messages and syntax checking (for running under an
224 editor).
225 For example, if you use a vi-style editor, such as vim, you may
227 execute perltidy as a filter from within the editor using something
228 like
229 :n1,n2!perltidy -q
231 where "n1,n2" represents the selected text. Without the -q flag,
233 any error message may mess up your screen, so be prepared to use
234 your "undo" key.
235 -log, --logfile
237 Save the .LOG file, which has many useful diagnostics. Perltidy
238 always creates a .LOG file, but by default it is deleted unless a
239 program bug is suspected. Setting the -log flag forces the log
240 file to be saved.
241 -g=n, --logfile-gap=n
243 Set maximum interval between input code lines in the logfile. This
244 purpose of this flag is to assist in debugging nesting errors. The
245 value of "n" is optional. If you set the flag -g without the value
246 of "n", it will be taken to be 1, meaning that every line will be
247 written to the log file. This can be helpful if you are looking
248 for a brace, paren, or bracket nesting error.
249 Setting -g also causes the logfile to be saved, so it is not
251 necessary to also include -log.
252 If no -g flag is given, a value of 50 will be used, meaning that at
254 least every 50th line will be recorded in the logfile. This helps
255 prevent excessively long log files.
256 Setting a negative value of "n" is the same as not setting -g at
258 all.
259 -npro --noprofile
261 Ignore any .perltidyrc command file. Normally, perltidy looks
262 first in your current directory for a .perltidyrc file of
263 parameters. (The format is described below). If it finds one, it
264 applies those options to the initial default values, and then it
265 applies any that have been defined on the command line. If no
266 .perltidyrc file is found, it looks for one in your home directory.
267 If you set the -npro flag, perltidy will not look for this file.
269 -pro=filename or --profile=filename
271 To simplify testing and switching .perltidyrc files, this command
272 may be used to specify a configuration file which will override the
273 default name of .perltidyrc. There must not be a space on either
274 side of the '=' sign. For example, the line
275 perltidy -pro=testcfg
277 would cause file testcfg to be used instead of the default
279 .perltidyrc.
280 A pathname begins with three dots, e.g. ".../.perltidyrc",
282 indicates that the file should be searched for starting in the
283 current directory and working upwards. This makes it easier to have
284 multiple projects each with their own .perltidyrc in their root
285 directories.
286 -opt, --show-options
288 Write a list of all options used to the .LOG file. Please see
289 --dump-options for a simpler way to do this.
290 -f, --force-read-binary
292 Force perltidy to process binary files. To avoid producing
293 excessive error messages, perltidy skips files identified by the
294 system as non-text. However, valid perl scripts containing binary
295 data may sometimes be identified as non-text, and this flag forces
296 perltidy to process them.
297
299 Basic Options
300 --notidy
301 This flag disables all formatting and causes the input to be copied
302 unchanged to the output except for possible changes in line ending
303 characters and any pre- and post-filters. This can be useful in
304 conjunction with a hierarchical set of .perltidyrc files to avoid
305 unwanted code tidying. See also "Skipping Selected Sections of
306 Code" for a way to avoid tidying specific sections of code.
307 -l=n, --maximum-line-length=n
309 The default maximum line length is n=80 characters. Perltidy will
310 try to find line break points to keep lines below this length.
311 However, long quotes and side comments may cause lines to exceed
312 this length. Setting -l=0 is equivalent to setting -l=(a large
313 number).
314 -i=n, --indent-columns=n
316 Use n columns per indentation level (default n=4).
317 tabs
319 Using tab characters will almost certainly lead to future
320 portability and maintenance problems, so the default and
321 recommendation is not to use them. For those who prefer tabs,
322 however, there are two different options.
323 Except for possibly introducing tab indentation characters, as
325 outlined below, perltidy does not introduce any tab characters into
326 your file, and it removes any tabs from the code (unless requested
327 not to do so with -fws). If you have any tabs in your comments,
328 quotes, or here-documents, they will remain.
329 -et=n, --entab-leading-whitespace
331 This flag causes each n initial space characters to be replaced
332 by one tab character. Note that the integer n is completely
333 independent of the integer specified for indentation parameter,
334 -i=n.
335 -t, --tabs
337 This flag causes one leading tab character to be inserted for
338 each level of indentation. Certain other features are
339 incompatible with this option, and if these options are also
340 given, then a warning message will be issued and this flag will
341 be unset. One example is the -lp option.
342 -syn, --check-syntax
344 This flag causes perltidy to run "perl -c -T" to check syntax of
345 input and output. (To change the flags passed to perl, see the
346 next item, -pscf). The results are written to the .LOG file, which
347 will be saved if an error is detected in the output script. The
348 output script is not checked if the input script has a syntax
349 error. Perltidy does its own checking, but this option employs
350 perl to get a "second opinion".
351 If perl reports errors in the input file, they will not be reported
353 in the error output unless the --warning-output flag is given.
354 The default is not to do this type of syntax checking (although
356 perltidy will still do as much self-checking as possible). The
357 reason is that it causes all code in BEGIN blocks to be executed,
358 for all modules being used, and this opens the door to security
359 issues and infinite loops when running perltidy.
360 -pscf=s, -perl-syntax-check-flags=s
362 When perl is invoked to check syntax, the normal flags are "-c -T".
363 In addition, if the -x flag is given to perltidy, then perl will
364 also be passed a -x flag. It should not normally be necessary to
365 change these flags, but it can be done with the -pscf=s flag. For
366 example, if the taint flag, "-T", is not wanted, the flag could be
367 set to be just -pscf=-c.
368 Perltidy will pass your string to perl with the exception that it
370 will add a -c and -x if appropriate. The .LOG file will show
371 exactly what flags were passed to perl.
372 -io, --indent-only
374 This flag is used to deactivate all formatting and line break
375 changes within non-blank lines of code. When it is in effect, the
376 only change to the script will be to the indentation and blank
377 lines. And any flags controlling whitespace and newlines will be
378 ignored. You might want to use this if you are perfectly happy
379 with your whitespace and line breaks, and merely want perltidy to
380 handle the indentation. (This also speeds up perltidy by well over
381 a factor of two, so it might be useful when perltidy is merely
382 being used to help find a brace error in a large script).
383 Setting this flag is equivalent to setting --freeze-newlines and
385 --freeze-whitespace.
386 If you also want to keep your existing blank lines exactly as they
388 are, you can add --freeze-blank-lines.
389 -ole=s, --output-line-ending=s
391 where s="win", "dos", "unix", or "mac". This flag tells perltidy
392 to output line endings for a specific system. Normally, perltidy
393 writes files with the line separator character of the host system.
394 The "win" and "dos" flags have an identical result.
395 -ple, --preserve-line-endings
397 This flag tells perltidy to write its output files with the same
398 line endings as the input file, if possible. It should work for
399 dos, unix, and mac line endings. It will only work if perltidy
400 input comes from a filename (rather than stdin, for example). If
401 perltidy has trouble determining the input file line ending, it
402 will revert to the default behavior of using the line ending of the
403 host system.
404 -it=n, --iterations=n
406 This flag causes perltidy to do n complete iterations. The reason
407 for this flag is that code beautification is a somewhat iterative
408 process and in some cases the output from perltidy can be different
409 if it is applied a second time. For most purposes the default of
410 n=1 should be satisfactory. However n=2 can be useful when a major
411 style change is being made, or when code is being beautified on
412 check-in to a source code control system. The run time will be
413 approximately proportional to n, and it should seldom be necessary
414 to use a value greater than n=2. This flag has no effect when
415 perltidy is used to generate html.
416 Code Indentation Control
418 -ci=n, --continuation-indentation=n
419 Continuation indentation is extra indentation spaces applied when a
420 long line is broken. The default is n=2, illustrated here:
421 my $level = # -ci=2
423 ( $max_index_to_go >= 0 ) ? $levels_to_go[0] : $last_output_level;
424 The same example, with n=0, is a little harder to read:
426 my $level = # -ci=0
428 ( $max_index_to_go >= 0 ) ? $levels_to_go[0] : $last_output_level;
429 The value given to -ci is also used by some commands when a small
431 space is required. Examples are commands for outdenting labels,
432 -ola, and control keywords, -okw.
433 When default values are not used, it is suggested that the value n
435 given with -ci=n be no more than about one-half of the number of
436 spaces assigned to a full indentation level on the -i=n command.
437 -sil=n --starting-indentation-level=n
439 By default, perltidy examines the input file and tries to determine
440 the starting indentation level. While it is often zero, it may not
441 be zero for a code snippet being sent from an editing session. If
442 the default method does not work correctly, or you want to change
443 the starting level, use -sil=n, to force the starting level to be
444 n.
445 List indentation using -lp, --line-up-parentheses
447 By default, perltidy indents lists with 4 spaces, or whatever value
448 is specified with -i=n. Here is a small list formatted in this
449 way:
450 # perltidy (default)
452 @month_of_year = (
453 'Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun',
454 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'
455 );
456 Use the -lp flag to add extra indentation to cause the data to
458 begin past the opening parentheses of a sub call or list, or
459 opening square bracket of an anonymous array, or opening curly
460 brace of an anonymous hash. With this option, the above list would
461 become:
462 # perltidy -lp
464 @month_of_year = (
465 'Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun',
466 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'
467 );
468 If the available line length (see -l=n ) does not permit this much
470 space, perltidy will use less. For alternate placement of the
471 closing paren, see the next section.
472 This option has no effect on code BLOCKS, such as if/then/else
474 blocks, which always use whatever is specified with -i=n. Also,
475 the existence of line breaks and/or block comments between the
476 opening and closing parens may cause perltidy to temporarily revert
477 to its default method.
478 Note: The -lp option may not be used together with the -t tabs
480 option. It may, however, be used with the -et=n tab method.
481 In addition, any parameter which significantly restricts the
483 ability of perltidy to choose newlines will conflict with -lp and
484 will cause -lp to be deactivated. These include -io, -fnl, -nanl,
485 and -ndnl. The reason is that the -lp indentation style can
486 require the careful coordination of an arbitrary number of break
487 points in hierarchical lists, and these flags may prevent that.
488 -cti=n, --closing-token-indentation
490 The -cti=n flag controls the indentation of a line beginning with a
491 ")", "]", or a non-block "}". Such a line receives:
492 -cti = 0 no extra indentation (default)
494 -cti = 1 extra indentation such that the closing token
495 aligns with its opening token.
496 -cti = 2 one extra indentation level if the line looks like:
497 ); or ]; or };
498 -cti = 3 one extra indentation level always
499 The flags -cti=1 and -cti=2 work well with the -lp flag (previous
501 section).
502 # perltidy -lp -cti=1
504 @month_of_year = (
505 'Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun',
506 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'
507 );
508 # perltidy -lp -cti=2
510 @month_of_year = (
511 'Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun',
512 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'
513 );
514 These flags are merely hints to the formatter and they may not
516 always be followed. In particular, if -lp is not being used, the
517 indentation for cti=1 is constrained to be no more than one
518 indentation level.
519 If desired, this control can be applied independently to each of
521 the closing container token types. In fact, -cti=n is merely an
522 abbreviation for -cpi=n -csbi=n -cbi=n, where: -cpi or
523 --closing-paren-indentation controls )'s, -csbi or
524 --closing-square-bracket-indentation controls ]'s, -cbi or
525 --closing-brace-indentation controls non-block }'s.
526 -icp, --indent-closing-paren
528 The -icp flag is equivalent to -cti=2, described in the previous
529 section. The -nicp flag is equivalent -cti=0. They are included
530 for backwards compatability.
531 -icb, --indent-closing-brace
533 The -icb option gives one extra level of indentation to a brace
534 which terminates a code block . For example,
535 if ($task) {
537 yyy();
538 } # -icb
539 else {
540 zzz();
541 }
542 The default is not to do this, indicated by -nicb.
544 -olq, --outdent-long-quotes
546 When -olq is set, lines which is a quoted string longer than the
547 value maximum-line-length will have their indentation removed to
548 make them more readable. This is the default. To prevent such
549 out-denting, use -nolq or --nooutdent-long-lines.
550 -oll, --outdent-long-lines
552 This command is equivalent to --outdent-long-quotes and
553 --outdent-long-comments, and it is included for compatibility with
554 previous versions of perltidy. The negation of this also works,
555 -noll or --nooutdent-long-lines, and is equivalent to setting -nolq
556 and -nolc.
557 Outdenting Labels: -ola, --outdent-labels
559 This command will cause labels to be outdented by 2 spaces (or
560 whatever -ci has been set to), if possible. This is the default.
561 For example:
562 my $i;
564 LOOP: while ( $i = <FOTOS> ) {
565 chomp($i);
566 next unless $i;
567 fixit($i);
568 }
569 Use -nola to not outdent labels.
571 Outdenting Keywords
573 -okw, --outdent-keywords
574 The command -okw will will cause certain leading control
575 keywords to be outdented by 2 spaces (or whatever -ci has been
576 set to), if possible. By default, these keywords are "redo",
577 "next", "last", "goto", and "return". The intention is to make
578 these control keywords easier to see. To change this list of
579 keywords being outdented, see the next section.
580 For example, using "perltidy -okw" on the previous example
582 gives:
583 my $i;
585 LOOP: while ( $i = <FOTOS> ) {
586 chomp($i);
587 next unless $i;
588 fixit($i);
589 }
590 The default is not to do this.
592 Specifying Outdented Keywords: -okwl=string,
594 --outdent-keyword-list=string
595 This command can be used to change the keywords which are
596 outdented with the -okw command. The parameter string is a
597 required list of perl keywords, which should be placed in
598 quotes if there are more than one. By itself, it does not
599 cause any outdenting to occur, so the -okw command is still
600 required.
601 For example, the commands "-okwl="next last redo goto" -okw"
603 will cause those four keywords to be outdented. It is probably
604 simplest to place any -okwl command in a .perltidyrc file.
605 Whitespace Control
607 Whitespace refers to the blank space between variables, operators, and
608 other code tokens.
609 -fws, --freeze-whitespace
611 This flag causes your original whitespace to remain unchanged, and
612 causes the rest of the whitespace commands in this section, the
613 Code Indentation section, and the Comment Control section to be
614 ignored.
615 Tightness of curly braces, parentheses, and square brackets.
617 Here the term "tightness" will mean the closeness with which pairs
618 of enclosing tokens, such as parentheses, contain the quantities
619 within. A numerical value of 0, 1, or 2 defines the tightness,
620 with 0 being least tight and 2 being most tight. Spaces within
621 containers are always symmetric, so if there is a space after a "("
622 then there will be a space before the corresponding ")".
623 The -pt=n or --paren-tightness=n parameter controls the space
625 within parens. The example below shows the effect of the three
626 possible values, 0, 1, and 2:
627 if ( ( my $len_tab = length( $tabstr ) ) > 0 ) { # -pt=0
629 if ( ( my $len_tab = length($tabstr) ) > 0 ) { # -pt=1 (default)
630 if ((my $len_tab = length($tabstr)) > 0) { # -pt=2
631 When n is 0, there is always a space to the right of a '(' and to
633 the left of a ')'. For n=2 there is never a space. For n=1, the
634 default, there is a space unless the quantity within the parens is
635 a single token, such as an identifier or quoted string.
636 Likewise, the parameter -sbt=n or --square-bracket-tightness=n
638 controls the space within square brackets, as illustrated below.
639 $width = $col[ $j + $k ] - $col[ $j ]; # -sbt=0
641 $width = $col[ $j + $k ] - $col[$j]; # -sbt=1 (default)
642 $width = $col[$j + $k] - $col[$j]; # -sbt=2
643 Curly braces which do not contain code blocks are controlled by the
645 parameter -bt=n or --brace-tightness=n.
646 $obj->{ $parsed_sql->{ 'table' }[0] }; # -bt=0
648 $obj->{ $parsed_sql->{'table'}[0] }; # -bt=1 (default)
649 $obj->{$parsed_sql->{'table'}[0]}; # -bt=2
650 And finally, curly braces which contain blocks of code are
652 controlled by the parameter -bbt=n or --block-brace-tightness=n as
653 illustrated in the example below.
654 %bf = map { $_ => -M $_ } grep { /\.deb$/ } dirents '.'; # -bbt=0 (default)
656 %bf = map { $_ => -M $_ } grep {/\.deb$/} dirents '.'; # -bbt=1
657 %bf = map {$_ => -M $_} grep {/\.deb$/} dirents '.'; # -bbt=2
658 -sts, --space-terminal-semicolon
660 Some programmers prefer a space before all terminal semicolons.
661 The default is for no such space, and is indicated with -nsts or
662 --nospace-terminal-semicolon.
663 $i = 1 ; # -sts
665 $i = 1; # -nsts (default)
666 -sfs, --space-for-semicolon
668 Semicolons within for loops may sometimes be hard to see,
669 particularly when commas are also present. This option places
670 spaces on both sides of these special semicolons, and is the
671 default. Use -nsfs or --nospace-for-semicolon to deactivate it.
672 for ( @a = @$ap, $u = shift @a ; @a ; $u = $v ) { # -sfs (default)
674 for ( @a = @$ap, $u = shift @a; @a; $u = $v ) { # -nsfs
675 -asc, --add-semicolons
677 Setting -asc allows perltidy to add any missing optional semicolon
678 at the end of a line which is followed by a closing curly brace on
679 the next line. This is the default, and may be deactivated with
680 -nasc or --noadd-semicolons.
681 -dsm, --delete-semicolons
683 Setting -dsm allows perltidy to delete extra semicolons which are
684 simply empty statements. This is the default, and may be
685 deactivated with -ndsm or --nodelete-semicolons. (Such semicolons
686 are not deleted, however, if they would promote a side comment to a
687 block comment).
688 -aws, --add-whitespace
690 Setting this option allows perltidy to add certain whitespace
691 improve code readability. This is the default. If you do not want
692 any whitespace added, but are willing to have some whitespace
693 deleted, use -naws. (Use -fws to leave whitespace completely
694 unchanged).
695 -dws, --delete-old-whitespace
697 Setting this option allows perltidy to remove some old whitespace
698 between characters, if necessary. This is the default. If you do
699 not want any old whitespace removed, use -ndws or
700 --nodelete-old-whitespace.
701 Detailed whitespace controls around tokens
703 For those who want more detailed control over the whitespace around
704 tokens, there are four parameters which can directly modify the
705 default whitespace rules built into perltidy for any token. They
706 are:
707 -wls=s or --want-left-space=s,
709 -nwls=s or --nowant-left-space=s,
711 -wrs=s or --want-right-space=s,
713 -nwrs=s or --nowant-right-space=s.
715 These parameters are each followed by a quoted string, s,
717 containing a list of token types. No more than one of each of
718 these parameters should be specified, because repeating a command-
719 line parameter always overwrites the previous one before perltidy
720 ever sees it.
721 To illustrate how these are used, suppose it is desired that there
723 be no space on either side of the token types = + - / *. The
724 following two parameters would specify this desire:
725 -nwls="= + - / *" -nwrs="= + - / *"
727 (Note that the token types are in quotes, and that they are
729 separated by spaces). With these modified whitespace rules, the
730 following line of math:
731 $root = -$b + sqrt( $b * $b - 4. * $a * $c ) / ( 2. * $a );
733 becomes this:
735 $root=-$b+sqrt( $b*$b-4.*$a*$c )/( 2.*$a );
737 These parameters should be considered to be hints to perltidy
739 rather than fixed rules, because perltidy must try to resolve
740 conflicts that arise between them and all of the other rules that
741 it uses. One conflict that can arise is if, between two tokens,
742 the left token wants a space and the right one doesn't. In this
743 case, the token not wanting a space takes priority.
744 It is necessary to have a list of all token types in order to
746 create this type of input. Such a list can be obtained by the
747 command --dump-token-types. Also try the -D flag on a short
748 snippet of code and look at the .DEBUG file to see the
749 tokenization.
750 WARNING Be sure to put these tokens in quotes to avoid having them
752 misinterpreted by your command shell.
753 Space between specific keywords and opening paren
755 When an opening paren follows a Perl keyword, no space is
756 introduced after the keyword, unless it is (by default) one of
757 these:
758 my local our and or eq ne if else elsif until unless
760 while for foreach return switch case given when
761 These defaults can be modified with two commands:
763 -sak=s or --space-after-keyword=s adds keywords.
765 -nsak=s or --nospace-after-keyword=s removes keywords.
767 where s is a list of keywords (in quotes if necessary). For
769 example,
770 my ( $a, $b, $c ) = @_; # default
772 my( $a, $b, $c ) = @_; # -nsak="my local our"
773 To put a space after all keywords, see the next item.
775 Space between all keywords and opening parens
777 When an opening paren follows a function or keyword, no space is
778 introduced after the keyword except for the keywords noted in the
779 previous item. To always put a space between a function or keyword
780 and its opening paren, use the command:
781 -skp or --space-keyword-paren
783 You will probably also want to use the flag -sfp (next item) too.
785 Space between all function names and opening parens
787 When an opening paren follows a function the default is not to
788 introduce a space. To cause a space to be introduced use:
789 -sfp or --space-function-paren
791 myfunc( $a, $b, $c ); # default
793 myfunc ( $a, $b, $c ); # -sfp
794 You will probably also want to use the flag -skp (previous item)
796 too.
797 Trimming whitespace around "qw" quotes
799 -tqw or --trim-qw provide the default behavior of trimming spaces
800 around multi-line "qw" quotes and indenting them appropriately.
801 -ntqw or --notrim-qw cause leading and trailing whitespace around
803 multi-line "qw" quotes to be left unchanged. This option will not
804 normally be necessary, but was added for testing purposes, because
805 in some versions of perl, trimming "qw" quotes changes the syntax
806 tree.
807 Comment Controls
809 Perltidy has a number of ways to control the appearance of both block
810 comments and side comments. The term block comment here refers to a
811 full-line comment, whereas side comment will refer to a comment which
812 appears on a line to the right of some code.
813 -ibc, --indent-block-comments
815 Block comments normally look best when they are indented to the
816 same level as the code which follows them. This is the default
817 behavior, but you may use -nibc to keep block comments left-
818 justified. Here is an example:
819 # this comment is indented (-ibc, default)
821 if ($task) { yyy(); }
822 The alternative is -nibc:
824 # this comment is not indented (-nibc)
826 if ($task) { yyy(); }
827 See also the next item, -isbc, as well as -sbc, for other ways to
829 have some indented and some outdented block comments.
830 -isbc, --indent-spaced-block-comments
832 If there is no leading space on the line, then the comment will not
833 be indented, and otherwise it may be.
834 If both -ibc and -isbc are set, then -isbc takes priority.
836 -olc, --outdent-long-comments
838 When -olc is set, lines which are full-line (block) comments longer
839 than the value maximum-line-length will have their indentation
840 removed. This is the default; use -nolc to prevent outdenting.
841 -msc=n, --minimum-space-to-comment=n
843 Side comments look best when lined up several spaces to the right
844 of code. Perltidy will try to keep comments at least n spaces to
845 the right. The default is n=4 spaces.
846 -fpsc=n, --fixed-position-side-comment=n
848 This parameter tells perltidy to line up side comments in column
849 number n whenever possible. The default, n=0, is not do do this.
850 -hsc, --hanging-side-comments
852 By default, perltidy tries to identify and align "hanging side
853 comments", which are something like this:
854 my $IGNORE = 0; # This is a side comment
856 # This is a hanging side comment
857 # And so is this
858 A comment is considered to be a hanging side comment if (1) it
860 immediately follows a line with a side comment, or another hanging
861 side comment, and (2) there is some leading whitespace on the line.
862 To deactivate this feature, use -nhsc or --nohanging-side-comments.
863 If block comments are preceded by a blank line, or have no leading
864 whitespace, they will not be mistaken as hanging side comments.
865 Closing Side Comments
867 A closing side comment is a special comment which perltidy can
868 automatically create and place after the closing brace of a code
869 block. They can be useful for code maintenance and debugging. The
870 command -csc (or --closing-side-comments) adds or updates closing
871 side comments. For example, here is a small code snippet
872 sub message {
874 if ( !defined( $_[0] ) ) {
875 print("Hello, World\n");
876 }
877 else {
878 print( $_[0], "\n" );
879 }
880 }
881 And here is the result of processing with "perltidy -csc":
883 sub message {
885 if ( !defined( $_[0] ) ) {
886 print("Hello, World\n");
887 }
888 else {
889 print( $_[0], "\n" );
890 }
891 } ## end sub message
892 A closing side comment was added for "sub message" in this case,
894 but not for the "if" and "else" blocks, because they were below the
895 6 line cutoff limit for adding closing side comments. This limit
896 may be changed with the -csci command, described below.
897 The command -dcsc (or --delete-closing-side-comments) reverses this
899 process and removes these comments.
900 Several commands are available to modify the behavior of these two
902 basic commands, -csc and -dcsc:
903 -csci=n, or --closing-side-comment-interval=n
905 where "n" is the minimum number of lines that a block must have
906 in order for a closing side comment to be added. The default
907 value is "n=6". To illustrate:
908 # perltidy -csci=2 -csc
910 sub message {
911 if ( !defined( $_[0] ) ) {
912 print("Hello, World\n");
913 } ## end if ( !defined( $_[0] ))
914 else {
915 print( $_[0], "\n" );
916 } ## end else [ if ( !defined( $_[0] ))
917 } ## end sub message
918 Now the "if" and "else" blocks are commented. However, now
920 this has become very cluttered.
921 -cscp=string, or --closing-side-comment-prefix=string
923 where string is the prefix used before the name of the block
924 type. The default prefix, shown above, is "## end". This
925 string will be added to closing side comments, and it will also
926 be used to recognize them in order to update, delete, and
927 format them. Any comment identified as a closing side comment
928 will be placed just a single space to the right of its closing
929 brace.
930 -cscl=string, or --closing-side-comment-list-string
932 where "string" is a list of block types to be tagged with
933 closing side comments. By default, all code block types
934 preceded by a keyword or label (such as "if", "sub", and so on)
935 will be tagged. The -cscl command changes the default list to
936 be any selected block types; see "Specifying Block Types". For
937 example, the following command requests that only "sub"'s,
938 labels, "BEGIN", and "END" blocks be affected by any -csc or
939 -dcsc operation:
940 -cscl="sub : BEGIN END"
942 -csct=n, or --closing-side-comment-maximum-text=n
944 The text appended to certain block types, such as an "if"
945 block, is whatever lies between the keyword introducing the
946 block, such as "if", and the opening brace. Since this might
947 be too much text for a side comment, there needs to be a limit,
948 and that is the purpose of this parameter. The default value
949 is "n=20", meaning that no additional tokens will be appended
950 to this text after its length reaches 20 characters. Omitted
951 text is indicated with "...". (Tokens, including sub names,
952 are never truncated, however, so actual lengths may exceed
953 this). To illustrate, in the above example, the appended text
954 of the first block is " ( !defined( $_[0] )...". The existing
955 limit of "n=20" caused this text to be truncated, as indicated
956 by the "...". See the next flag for additional control of the
957 abbreviated text.
958 -cscb, or --closing-side-comments-balanced
960 As discussed in the previous item, when the closing-side-
961 comment-maximum-text limit is exceeded the comment text must be
962 truncated. Older versions of perltidy terminated with three
963 dots, and this can still be achieved with -ncscb:
964 perltidy -csc -ncscb
966 } ## end foreach my $foo (sort { $b cmp $a ...
967 However this causes a problem with editors editors which cannot
969 recognize comments or are not configured to do so because they
970 cannot "bounce" around in the text correctly. The -cscb flag
971 has been added to help them by appending appropriate balancing
972 structure:
973 perltidy -csc -cscb
975 } ## end foreach my $foo (sort { $b cmp $a ... })
976 The default is -cscb.
978 -csce=n, or --closing-side-comment-else-flag=n
980 The default, n=0, places the text of the opening "if" statement
981 after any terminal "else".
982 If n=2 is used, then each "elsif" is also given the text of the
984 opening "if" statement. Also, an "else" will include the text
985 of a preceding "elsif" statement. Note that this may result
986 some long closing side comments.
987 If n=1 is used, the results will be the same as n=2 whenever
989 the resulting line length is less than the maximum allowed.
990 =item -cscb, or --closing-side-comments-balanced
991 When using closing-side-comments, and the closing-side-comment-
993 maximum-text limit is exceeded, then the comment text must be
994 abbreviated. It is terminated with three dots if the -cscb
995 flag is negated:
996 perltidy -csc -ncscb
998 } ## end foreach my $foo (sort { $b cmp $a ...
999 This causes a problem with older editors which do not recognize
1001 comments because they cannot "bounce" around in the text
1002 correctly. The -cscb flag tries to help them by appending
1003 appropriate terminal balancing structures:
1004 perltidy -csc -cscb
1006 } ## end foreach my $foo (sort { $b cmp $a ... })
1007 The default is -cscb.
1009 -cscw, or --closing-side-comment-warnings
1011 This parameter is intended to help make the initial transition
1012 to the use of closing side comments. It causes two things to
1013 happen if a closing side comment replaces an existing,
1014 different closing side comment: first, an error message will
1015 be issued, and second, the original side comment will be placed
1016 alone on a new specially marked comment line for later
1017 attention.
1018 The intent is to avoid clobbering existing hand-written side
1020 comments which happen to match the pattern of closing side
1021 comments. This flag should only be needed on the first run with
1022 -csc.
1023 Important Notes on Closing Side Comments:
1025 · Closing side comments are only placed on lines terminated with
1027 a closing brace. Certain closing styles, such as the use of
1028 cuddled elses (-ce), preclude the generation of some closing
1029 side comments.
1030 · Please note that adding or deleting of closing side comments
1032 takes place only through the commands -csc or -dcsc. The other
1033 commands, if used, merely modify the behavior of these two
1034 commands.
1035 · It is recommended that the -cscw flag be used along with -csc
1037 on the first use of perltidy on a given file. This will
1038 prevent loss of any existing side comment data which happens to
1039 have the csc prefix.
1040 · Once you use -csc, you should continue to use it so that any
1042 closing side comments remain correct as code changes.
1043 Otherwise, these comments will become incorrect as the code is
1044 updated.
1045 · If you edit the closing side comments generated by perltidy,
1047 you must also change the prefix to be different from the
1048 closing side comment prefix. Otherwise, your edits will be
1049 lost when you rerun perltidy with -csc. For example, you
1050 could simply change "## end" to be "## End", since the test is
1051 case sensitive. You may also want to use the -ssc flag to keep
1052 these modified closing side comments spaced the same as actual
1053 closing side comments.
1054 · Temporarily generating closing side comments is a useful
1056 technique for exploring and/or debugging a perl script,
1057 especially one written by someone else. You can always remove
1058 them with -dcsc.
1059 Static Block Comments
1061 Static block comments are block comments with a special leading
1062 pattern, "##" by default, which will be treated slightly
1063 differently from other block comments. They effectively behave as
1064 if they had glue along their left and top edges, because they stick
1065 to the left edge and previous line when there is no blank spaces in
1066 those places. This option is particularly useful for controlling
1067 how commented code is displayed.
1068 -sbc, --static-block-comments
1070 When -sbc is used, a block comment with a special leading
1071 pattern, "##" by default, will be treated specially.
1072 Comments so identified are treated as follows:
1074 · If there is no leading space on the line, then the comment
1076 will not be indented, and otherwise it may be,
1077 · no new blank line will be inserted before such a comment,
1079 and
1080 · such a comment will never become a hanging side comment.
1082 For example, assuming @month_of_year is left-adjusted:
1084 @month_of_year = ( # -sbc (default)
1086 'Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct',
1087 ## 'Dec', 'Nov'
1088 'Nov', 'Dec');
1089 Without this convention, the above code would become
1091 @month_of_year = ( # -nsbc
1093 'Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct',
1094 ## 'Dec', 'Nov'
1096 'Nov', 'Dec'
1097 );
1098 which is not as clear. The default is to use -sbc. This may
1100 be deactivated with -nsbc.
1101 -sbcp=string, --static-block-comment-prefix=string
1103 This parameter defines the prefix used to identify static block
1104 comments when the -sbc parameter is set. The default prefix is
1105 "##", corresponding to "-sbcp=##". The prefix is actually part
1106 of a perl pattern used to match lines and it must either begin
1107 with "#" or "^#". In the first case a prefix ^\s* will be
1108 added to match any leading whitespace, while in the second case
1109 the pattern will match only comments with no leading
1110 whitespace. For example, to identify all comments as static
1111 block comments, one would use "-sbcp=#". To identify all left-
1112 adjusted comments as static block comments, use "-sbcp='^#'".
1113 Please note that -sbcp merely defines the pattern used to
1115 identify static block comments; it will not be used unless the
1116 switch -sbc is set. Also, please be aware that since this
1117 string is used in a perl regular expression which identifies
1118 these comments, it must enable a valid regular expression to be
1119 formed.
1120 A pattern which can be useful is:
1122 -sbcp=^#{2,}[^\s#]
1124 This pattern requires a static block comment to have at least
1126 one character which is neither a # nor a space. It allows a
1127 line containing only '#' characters to be rejected as a static
1128 block comment. Such lines are often used at the start and end
1129 of header information in subroutines and should not be
1130 separated from the intervening comments, which typically begin
1131 with just a single '#'.
1132 -osbc, --outdent-static-block-comments
1134 The command -osbc will will cause static block comments to be
1135 outdented by 2 spaces (or whatever -ci=n has been set to), if
1136 possible.
1137 Static Side Comments
1139 Static side comments are side comments with a special leading
1140 pattern. This option can be useful for controlling how commented
1141 code is displayed when it is a side comment.
1142 -ssc, --static-side-comments
1144 When -ssc is used, a side comment with a static leading
1145 pattern, which is "##" by default, will be be spaced only a
1146 single space from previous character, and it will not be
1147 vertically aligned with other side comments.
1148 The default is -nssc.
1150 -sscp=string, --static-side-comment-prefix=string
1152 This parameter defines the prefix used to identify static side
1153 comments when the -ssc parameter is set. The default prefix is
1154 "##", corresponding to "-sscp=##".
1155 Please note that -sscp merely defines the pattern used to
1157 identify static side comments; it will not be used unless the
1158 switch -ssc is set. Also, note that this string is used in a
1159 perl regular expression which identifies these comments, so it
1160 must enable a valid regular expression to be formed.
1161 Skipping Selected Sections of Code
1163 Selected lines of code may be passed verbatim to the output without any
1164 formatting. This feature is enabled by default but can be disabled
1165 with the --noformat-skipping or -nfs flag. It should be used sparingly
1166 to avoid littering code with markers, but it might be helpful for
1167 working around occasional problems. For example it might be useful for
1168 keeping the indentation of old commented code unchanged, keeping
1169 indentation of long blocks of aligned comments unchanged, keeping
1170 certain list formatting unchanged, or working around a glitch in
1171 perltidy.
1172 -fs, --format-skipping
1174 This flag, which is enabled by default, causes any code between
1175 special beginning and ending comment markers to be passed to the
1176 output without formatting. The default beginning marker is #<<<
1177 and the default ending marker is #>>> but they may be changed (see
1178 next items below). Additional text may appear on these special
1179 comment lines provided that it is separated from the marker by at
1180 least one space. For example
1181 #<<< do not let perltidy touch this
1183 my @list = (1,
1184 1, 1,
1185 1, 2, 1,
1186 1, 3, 3, 1,
1187 1, 4, 6, 4, 1,);
1188 #>>>
1189 The comment markers may be placed at any location that a block
1191 comment may appear. If they do not appear to be working, use the
1192 -log flag and examine the .LOG file. Use -nfs to disable this
1193 feature.
1194 -fsb=string, --format-skipping-begin=string
1196 The -fsb=string parameter may be used to change the beginning
1197 marker for format skipping. The default is equivalent to
1198 -fsb='#<<<'. The string that you enter must begin with a # and
1199 should be in quotes as necessary to get past the command shell of
1200 your system. It is actually the leading text of a pattern that is
1201 constructed by appending a '\s', so you must also include
1202 backslashes for characters to be taken literally rather than as
1203 patterns.
1204 Some examples show how example strings become patterns:
1206 -fsb='#\{\{\{' becomes /^#\{\{\{\s/ which matches #{{{ but not #{{{{
1208 -fsb='#\*\*' becomes /^#\*\*\s/ which matches #** but not #***
1209 -fsb='#\*{2,}' becomes /^#\*{2,}\s/ which matches #** and #*****
1210 -fse=string, --format-skipping-end=string
1212 The -fsb=string is the corresponding parameter used to change the
1213 ending marker for format skipping. The default is equivalent to
1214 -fse='#<<<'.
1215 Line Break Control
1217 The parameters in this section control breaks after non-blank lines of
1218 code. Blank lines are controlled separately by parameters in the
1219 section "Blank Line Control".
1220 -fnl, --freeze-newlines
1222 If you do not want any changes to the line breaks within lines of
1223 code in your script, set -fnl, and they will remain fixed, and the
1224 rest of the commands in this section and sections "Controlling List
1225 Formatting", "Retaining or Ignoring Existing Line Breaks". You may
1226 want to use -noll with this.
1227 Note: If you also want to keep your blank lines exactly as they
1229 are, you can use the -fbl flag which is described in the section
1230 "Blank Line Control".
1231 -ce, --cuddled-else
1233 Enable the "cuddled else" style, in which "else" and "elsif" are
1234 follow immediately after the curly brace closing the previous
1235 block. The default is not to use cuddled elses, and is indicated
1236 with the flag -nce or --nocuddled-else. Here is a comparison of
1237 the alternatives:
1238 if ($task) {
1240 yyy();
1241 } else { # -ce
1242 zzz();
1243 }
1244 if ($task) {
1246 yyy();
1247 }
1248 else { # -nce (default)
1249 zzz();
1250 }
1251 -bl, --opening-brace-on-new-line
1253 Use the flag -bl to place the opening brace on a new line:
1254 if ( $input_file eq '-' ) # -bl
1256 {
1257 important_function();
1258 }
1259 This flag applies to all structural blocks, including named sub's
1261 (unless the -sbl flag is set -- see next item).
1262 The default style, -nbl, places an opening brace on the same line
1264 as the keyword introducing it. For example,
1265 if ( $input_file eq '-' ) { # -nbl (default)
1267 -sbl, --opening-sub-brace-on-new-line
1269 The flag -sbl can be used to override the value of -bl for the
1270 opening braces of named sub's. For example,
1271 perltidy -sbl
1273 produces this result:
1275 sub message
1277 {
1278 if (!defined($_[0])) {
1279 print("Hello, World\n");
1280 }
1281 else {
1282 print($_[0], "\n");
1283 }
1284 }
1285 This flag is negated with -nsbl. If -sbl is not specified, the
1287 value of -bl is used.
1288 -asbl, --opening-anonymous-sub-brace-on-new-line
1290 The flag -asbl is like the -sbl flag except that it applies to
1291 anonymous sub's instead of named subs. For example
1292 perltidy -asbl
1294 produces this result:
1296 $a = sub
1298 {
1299 if ( !defined( $_[0] ) ) {
1300 print("Hello, World\n");
1301 }
1302 else {
1303 print( $_[0], "\n" );
1304 }
1305 };
1306 This flag is negated with -nasbl, and the default is -nasbl.
1308 -bli, --brace-left-and-indent
1310 The flag -bli is the same as -bl but in addition it causes one unit
1311 of continuation indentation ( see -ci ) to be placed before an
1312 opening and closing block braces.
1313 For example,
1315 if ( $input_file eq '-' ) # -bli
1317 {
1318 important_function();
1319 }
1320 By default, this extra indentation occurs for blocks of type: if,
1322 elsif, else, unless, for, foreach, sub, while, until, and also with
1323 a preceding label. The next item shows how to change this.
1324 -blil=s, --brace-left-and-indent-list=s
1326 Use this parameter to change the types of block braces for which
1327 the -bli flag applies; see "Specifying Block Types". For example,
1328 -blil='if elsif else' would apply it to only "if/elsif/else"
1329 blocks.
1330 -bar, --opening-brace-always-on-right
1332 The default style, -nbl places the opening code block brace on a
1333 new line if it does not fit on the same line as the opening
1334 keyword, like this:
1335 if ( $bigwasteofspace1 && $bigwasteofspace2
1337 || $bigwasteofspace3 && $bigwasteofspace4 )
1338 {
1339 big_waste_of_time();
1340 }
1341 To force the opening brace to always be on the right, use the -bar
1343 flag. In this case, the above example becomes
1344 if ( $bigwasteofspace1 && $bigwasteofspace2
1346 || $bigwasteofspace3 && $bigwasteofspace4 ) {
1347 big_waste_of_time();
1348 }
1349 A conflict occurs if both -bl and -bar are specified.
1351 -otr, --opening-token-right and related flags
1353 The -otr flag is a hint that perltidy should not place a break
1354 between a comma and an opening token. For example:
1355 # default formatting
1357 push @{ $self->{$module}{$key} },
1358 {
1359 accno => $ref->{accno},
1360 description => $ref->{description}
1361 };
1362 # perltidy -otr
1364 push @{ $self->{$module}{$key} }, {
1365 accno => $ref->{accno},
1366 description => $ref->{description}
1367 };
1368 The flag -otr is actually a synonym for three other flags which can
1370 be used to control parens, hash braces, and square brackets
1371 separately if desired:
1372 -opr or --opening-paren-right
1374 -ohbr or --opening-hash-brace-right
1375 -osbr or --opening-square-bracket-right
1376 Vertical tightness of non-block curly braces, parentheses, and square
1378 brackets.
1379 These parameters control what shall be called vertical tightness.
1380 Here are the main points:
1381 · Opening tokens (except for block braces) are controlled by
1383 -vt=n, or --vertical-tightness=n, where
1384 -vt=0 always break a line after opening token (default).
1386 -vt=1 do not break unless this would produce more than one
1387 step in indentation in a line.
1388 -vt=2 never break a line after opening token
1389 · You must also use the -lp flag when you use the -vt flag; the
1391 reason is explained below.
1392 · Closing tokens (except for block braces) are controlled by
1394 -vtc=n, or --vertical-tightness-closing=n, where
1395 -vtc=0 always break a line before a closing token (default),
1397 -vtc=1 do not break before a closing token which is followed
1398 by a semicolon or another closing token, and is not in
1399 a list environment.
1400 -vtc=2 never break before a closing token.
1401 The rules for -vtc=1 are designed to maintain a reasonable
1403 balance between tightness and readability in complex lists.
1404 · Different controls may be applied to to different token types,
1406 and it is also possible to control block braces; see below.
1407 · Finally, please note that these vertical tightness flags are
1409 merely hints to the formatter, and it cannot always follow
1410 them. Things which make it difficult or impossible include
1411 comments, blank lines, blocks of code within a list, and
1412 possibly the lack of the -lp parameter. Also, these flags may
1413 be ignored for very small lists (2 or 3 lines in length).
1414 Here are some examples:
1416 # perltidy -lp -vt=0 -vtc=0
1418 %romanNumerals = (
1419 one => 'I',
1420 two => 'II',
1421 three => 'III',
1422 four => 'IV',
1423 );
1424 # perltidy -lp -vt=1 -vtc=0
1426 %romanNumerals = ( one => 'I',
1427 two => 'II',
1428 three => 'III',
1429 four => 'IV',
1430 );
1431 # perltidy -lp -vt=1 -vtc=1
1433 %romanNumerals = ( one => 'I',
1434 two => 'II',
1435 three => 'III',
1436 four => 'IV', );
1437 The difference between -vt=1 and -vt=2 is shown here:
1439 # perltidy -lp -vt=1
1441 $init->add(
1442 mysprintf( "(void)find_threadsv(%s);",
1443 cstring( $threadsv_names[ $op->targ ] )
1444 )
1445 );
1446 # perltidy -lp -vt=2
1448 $init->add( mysprintf( "(void)find_threadsv(%s);",
1449 cstring( $threadsv_names[ $op->targ ] )
1450 )
1451 );
1452 With -vt=1, the line ending in "add(" does not combine with the
1454 next line because the next line is not balanced. This can help
1455 with readability, but -vt=2 can be used to ignore this rule.
1456 The tightest, and least readable, code is produced with both
1458 "-vt=2" and "-vtc=2":
1459 # perltidy -lp -vt=2 -vtc=2
1461 $init->add( mysprintf( "(void)find_threadsv(%s);",
1462 cstring( $threadsv_names[ $op->targ ] ) ) );
1463 Notice how the code in all of these examples collapses vertically
1465 as -vt increases, but the indentation remains unchanged. This is
1466 because perltidy implements the -vt parameter by first formatting
1467 as if -vt=0, and then simply overwriting one output line on top of
1468 the next, if possible, to achieve the desired vertical tightness.
1469 The -lp indentation style has been designed to allow this vertical
1470 collapse to occur, which is why it is required for the -vt
1471 parameter.
1472 The -vt=n and -vtc=n parameters apply to each type of container
1474 token. If desired, vertical tightness controls can be applied
1475 independently to each of the closing container token types.
1476 The parameters for controlling parentheses are -pvt=n or
1478 --paren-vertical-tightness=n, and -pcvt=n or
1479 --paren-vertical-tightness-closing=n.
1480 Likewise, the parameters for square brackets are -sbvt=n or
1482 --square-bracket-vertical-tightness=n, and -sbcvt=n or
1483 --square-bracket-vertical-tightness-closing=n.
1484 Finally, the parameters for controlling non-code block braces are
1486 -bvt=n or --brace-vertical-tightness=n, and -bcvt=n or
1487 --brace-vertical-tightness-closing=n.
1488 In fact, the parameter -vt=n is actually just an abbreviation for
1490 -pvt=n -bvt=n sbvt=n, and likewise -vtc=n is an abbreviation for
1491 -pvtc=n -bvtc=n sbvtc=n.
1492 -bbvt=n or --block-brace-vertical-tightness=n
1494 The -bbvt=n flag is just like the -vt=n flag but applies to opening
1495 code block braces.
1496 -bbvt=0 break after opening block brace (default).
1498 -bbvt=1 do not break unless this would produce more than one
1499 step in indentation in a line.
1500 -bbvt=2 do not break after opening block brace.
1501 It is necessary to also use either -bl or -bli for this to work,
1503 because, as with other vertical tightness controls, it is
1504 implemented by simply overwriting a line ending with an opening
1505 block brace with the subsequent line. For example:
1506 # perltidy -bli -bbvt=0
1508 if ( open( FILE, "< $File" ) )
1509 {
1510 while ( $File = <FILE> )
1511 {
1512 $In .= $File;
1513 $count++;
1514 }
1515 close(FILE);
1516 }
1517 # perltidy -bli -bbvt=1
1519 if ( open( FILE, "< $File" ) )
1520 { while ( $File = <FILE> )
1521 { $In .= $File;
1522 $count++;
1523 }
1524 close(FILE);
1525 }
1526 By default this applies to blocks associated with keywords if,
1528 elsif, else, unless, for, foreach, sub, while, until, and also with
1529 a preceding label. This can be changed with the parameter
1530 -bbvtl=string, or --block-brace-vertical-tightness-list=string,
1531 where string is a space-separated list of block types. For more
1532 information on the possible values of this string, see "Specifying
1533 Block Types"
1534 For example, if we want to just apply this style to "if", "elsif",
1536 and "else" blocks, we could use "perltidy -bli -bbvt=1 -bbvtl='if
1537 elsif else'".
1538 There is no vertical tightness control for closing block braces;
1540 with the exception of one-line blocks, they will normally remain on
1541 a separate line.
1542 -sot, --stack-opening-tokens and related flags
1544 The -sot flag tells perltidy to "stack" opening tokens when
1545 possible to avoid lines with isolated opening tokens.
1546 For example:
1548 # default
1550 $opt_c = Text::CSV_XS->new(
1551 {
1552 binary => 1,
1553 sep_char => $opt_c,
1554 always_quote => 1,
1555 }
1556 );
1557 # -sot
1559 $opt_c = Text::CSV_XS->new( {
1560 binary => 1,
1561 sep_char => $opt_c,
1562 always_quote => 1,
1563 }
1564 );
1565 For detailed control of individual closing tokens the following
1567 controls can be used:
1568 -sop or --stack-opening-paren
1570 -sohb or --stack-opening-hash-brace
1571 -sosb or --stack-opening-square-bracket
1572 The flag -sot is a synonym for -sop -sohb -sosb.
1574 -sct, --stack-closing-tokens and related flags
1576 The -sct flag tells perltidy to "stack" closing tokens when
1577 possible to avoid lines with isolated closing tokens.
1578 For example:
1580 # default
1582 $opt_c = Text::CSV_XS->new(
1583 {
1584 binary => 1,
1585 sep_char => $opt_c,
1586 always_quote => 1,
1587 }
1588 );
1589 # -sct
1591 $opt_c = Text::CSV_XS->new(
1592 {
1593 binary => 1,
1594 sep_char => $opt_c,
1595 always_quote => 1,
1596 } );
1597 The -sct flag is somewhat similar to the -vtc flags, and in some
1599 cases it can give a similar result. The difference is that the
1600 -vtc flags try to avoid lines with leading opening tokens by
1601 "hiding" them at the end of a previous line, whereas the -sct flag
1602 merely tries to reduce the number of lines with isolated closing
1603 tokens by stacking them but does not try to hide them. For
1604 example:
1605 # -vtc=2
1607 $opt_c = Text::CSV_XS->new(
1608 {
1609 binary => 1,
1610 sep_char => $opt_c,
1611 always_quote => 1, } );
1612 For detailed control of the stacking of individual closing tokens
1614 the following controls can be used:
1615 -scp or --stack-closing-paren
1617 -schb or --stack-closing-hash-brace
1618 -scsb or --stack-closing-square-bracket
1619 The flag -sct is a synonym for -scp -schb -scsb.
1621 -dnl, --delete-old-newlines
1623 By default, perltidy first deletes all old line break locations,
1624 and then it looks for good break points to match the desired line
1625 length. Use -ndnl or --nodelete-old-newlines to force perltidy to
1626 retain all old line break points.
1627 -anl, --add-newlines
1629 By default, perltidy will add line breaks when necessary to create
1630 continuations of long lines and to improve the script appearance.
1631 Use -nanl or --noadd-newlines to prevent any new line breaks.
1632 This flag does not prevent perltidy from eliminating existing line
1634 breaks; see --freeze-newlines to completely prevent changes to line
1635 break points.
1636 Controlling whether perltidy breaks before or after operators
1638 Four command line parameters provide some control over whether a
1639 line break should be before or after specific token types. Two
1640 parameters give detailed control:
1641 -wba=s or --want-break-after=s, and
1643 -wbb=s or --want-break-before=s.
1645 These parameters are each followed by a quoted string, s,
1647 containing a list of token types (separated only by spaces). No
1648 more than one of each of these parameters should be specified,
1649 because repeating a command-line parameter always overwrites the
1650 previous one before perltidy ever sees it.
1651 By default, perltidy breaks after these token types:
1653 % + - * / x != == >= <= =~ !~ < > | &
1654 = **= += *= &= <<= &&= -= /= |= >>= ||= //= .= %= ^= x=
1655 And perltidy breaks before these token types by default:
1657 . << >> -> && || //
1658 To illustrate, to cause a break after a concatenation operator,
1660 '.', rather than before it, the command line would be
1661 -wba="."
1663 As another example, the following command would cause a break
1665 before math operators '+', '-', '/', and '*':
1666 -wbb="+ - / *"
1668 These commands should work well for most of the token types that
1670 perltidy uses (use --dump-token-types for a list). Also try the -D
1671 flag on a short snippet of code and look at the .DEBUG file to see
1672 the tokenization. However, for a few token types there may be
1673 conflicts with hardwired logic which cause unexpected results. One
1674 example is curly braces, which should be controlled with the
1675 parameter bl provided for that purpose.
1676 WARNING Be sure to put these tokens in quotes to avoid having them
1678 misinterpreted by your command shell.
1679 Two additional parameters are available which, though they provide
1681 no further capability, can simplify input are:
1682 -baao or --break-after-all-operators,
1684 -bbao or --break-before-all-operators.
1686 The -baao sets the default to be to break after all of the
1688 following operators:
1689 % + - * / x != == >= <= =~ !~ < > | &
1691 = **= += *= &= <<= &&= -= /= |= >>= ||= //= .= %= ^= x=
1692 . : ? && || and or err xor
1693 and the -bbao flag sets the default to break before all of these
1695 operators. These can be used to define an initial break preference
1696 which can be fine-tuned with the -wba and -wbb flags. For example,
1697 to break before all operators except an = one could use --bbao
1698 -wba='=' rather than listing every single perl operator except = on
1699 a -wbb flag.
1700 Controlling List Formatting
1702 Perltidy attempts to place comma-separated arrays of values in tables
1703 which look good. Its default algorithms usually work well, and they
1704 have been improving with each release, but several parameters are
1705 available to control list formatting.
1706 -boc, --break-at-old-comma-breakpoints
1708 This flag tells perltidy to try to break at all old commas. This
1709 is not the default. Normally, perltidy makes a best guess at list
1710 formatting, and seldom uses old comma breakpoints. Usually this
1711 works well, but consider:
1712 my @list = (1,
1714 1, 1,
1715 1, 2, 1,
1716 1, 3, 3, 1,
1717 1, 4, 6, 4, 1,);
1718 The default formatting will flatten this down to one line:
1720 # perltidy (default)
1722 my @list = ( 1, 1, 1, 1, 2, 1, 1, 3, 3, 1, 1, 4, 6, 4, 1, );
1723 which hides the structure. Using -boc, plus additional flags to
1725 retain the original style, yields
1726 # perltidy -boc -lp -pt=2 -vt=1 -vtc=1
1728 my @list = (1,
1729 1, 1,
1730 1, 2, 1,
1731 1, 3, 3, 1,
1732 1, 4, 6, 4, 1,);
1733 A disadvantage of this flag is that all tables in the file must
1735 already be nicely formatted. For another possibility see the -fs
1736 flag in "Skipping Selected Sections of Code".
1737 -mft=n, --maximum-fields-per-table=n
1739 If the computed number of fields for any table exceeds n, then it
1740 will be reduced to n. The default value for n is a large number,
1741 40. While this value should probably be left unchanged as a
1742 general rule, it might be used on a small section of code to force
1743 a list to have a particular number of fields per line, and then
1744 either the -boc flag could be used to retain this formatting, or a
1745 single comment could be introduced somewhere to freeze the
1746 formatting in future applications of perltidy.
1747 # perltidy -mft=2
1749 @month_of_year = (
1750 'Jan', 'Feb',
1751 'Mar', 'Apr',
1752 'May', 'Jun',
1753 'Jul', 'Aug',
1754 'Sep', 'Oct',
1755 'Nov', 'Dec'
1756 );
1757 -cab=n, --comma-arrow-breakpoints=n
1759 A comma which follows a comma arrow, '=>', requires special
1760 consideration. In a long list, it is common to break at all such
1761 commas. This parameter can be used to control how perltidy breaks
1762 at these commas. (However, it will have no effect if old comma
1763 breaks are being forced because -boc is used). The possible values
1764 of n are:
1765 n=0 break at all commas after =>
1767 n=1 stable: break at all commas after => unless this would break
1768 an existing one-line container (default)
1769 n=2 break at all commas after =>, but try to form the maximum
1770 maximum one-line container lengths
1771 n=3 do not treat commas after => specially at all
1772 For example, given the following single line, perltidy by default
1774 will not add any line breaks because it would break the existing
1775 one-line container:
1776 bless { B => $B, Root => $Root } => $package;
1778 Using -cab=0 will force a break after each comma-arrow item:
1780 # perltidy -cab=0:
1782 bless {
1783 B => $B,
1784 Root => $Root
1785 } => $package;
1786 If perltidy is subsequently run with this container broken, then by
1788 default it will break after each '=>' because the container is now
1789 broken. To reform a one-line container, the parameter -cab=2 would
1790 be needed.
1791 The flag -cab=3 can be used to prevent these commas from being
1793 treated specially. In this case, an item such as "01" => 31 is
1794 treated as a single item in a table. The number of fields in this
1795 table will be determined by the same rules that are used for any
1796 other table. Here is an example.
1797 # perltidy -cab=3
1799 my %last_day = (
1800 "01" => 31, "02" => 29, "03" => 31, "04" => 30,
1801 "05" => 31, "06" => 30, "07" => 31, "08" => 31,
1802 "09" => 30, "10" => 31, "11" => 30, "12" => 31
1803 );
1804 Retaining or Ignoring Existing Line Breaks
1806 Several additional parameters are available for controlling the extent
1807 to which line breaks in the input script influence the output script.
1808 In most cases, the default parameter values are set so that, if a
1809 choice is possible, the output style follows the input style. For
1810 example, if a short logical container is broken in the input script,
1811 then the default behavior is for it to remain broken in the output
1812 script.
1813 Most of the parameters in this section would only be required for a
1815 one-time conversion of a script from short container lengths to longer
1816 container lengths. The opposite effect, of converting long container
1817 lengths to shorter lengths, can be obtained by temporarily using a
1818 short maximum line length.
1819 -bol, --break-at-old-logical-breakpoints
1821 By default, if a logical expression is broken at a "&&", "||",
1822 "and", or "or", then the container will remain broken. Also,
1823 breaks at internal keywords "if" and "unless" will normally be
1824 retained. To prevent this, and thus form longer lines, use -nbol.
1825 -bok, --break-at-old-keyword-breakpoints
1827 By default, perltidy will retain a breakpoint before keywords which
1828 may return lists, such as "sort" and <map>. This allows chains of
1829 these operators to be displayed one per line. Use -nbok to prevent
1830 retaining these breakpoints.
1831 -bot, --break-at-old-ternary-breakpoints
1833 By default, if a conditional (ternary) operator is broken at a ":",
1834 then it will remain broken. To prevent this, and thereby form
1835 longer lines, use -nbot.
1836 -iob, --ignore-old-breakpoints
1838 Use this flag to tell perltidy to ignore existing line breaks to
1839 the maximum extent possible. This will tend to produce the longest
1840 possible containers, regardless of type, which do not exceed the
1841 line length limit.
1842 -kis, --keep-interior-semicolons
1844 Use the -kis flag to prevent breaking at a semicolon if there was
1845 no break there in the input file. Normally perltidy places a
1846 newline after each semicolon which terminates a statement unless
1847 several statements are contained within a one-line brace block. To
1848 illustrate, consider the following input lines:
1849 dbmclose(%verb_delim); undef %verb_delim;
1851 dbmclose(%expanded); undef %expanded;
1852 The default is to break after each statement, giving
1854 dbmclose(%verb_delim);
1856 undef %verb_delim;
1857 dbmclose(%expanded);
1858 undef %expanded;
1859 With perltidy -kis the multiple statements are retained:
1861 dbmclose(%verb_delim); undef %verb_delim;
1863 dbmclose(%expanded); undef %expanded;
1864 The statements are still subject to the specified value of maximum-
1866 line-length and will be broken if this maximum is exceeed.
1867 Blank Line Control
1869 Blank lines can improve the readability of a script if they are
1870 carefully placed. Perltidy has several commands for controlling the
1871 insertion, retention, and removal of blank lines.
1872 -fbl, --freeze-blank-lines
1874 Set -fbl if you want to the blank lines in your script to remain
1875 exactly as they are. The rest of the parameters in this section
1876 may then be ignored. (Note: setting the -fbl flag is equivalent to
1877 setting -mbl=0 and -kbl=2).
1878 -bbc, --blanks-before-comments
1880 A blank line will be introduced before a full-line comment. This
1881 is the default. Use -nbbc or --noblanks-before-comments to
1882 prevent such blank lines from being introduced.
1883 -bbs, --blanks-before-subs
1885 A blank line will be introduced before a sub definition, unless it
1886 is a one-liner or preceded by a comment. A blank line will also be
1887 introduced before a package statement and a BEGIN and END block.
1888 This is the default. The intention is to help display the
1889 structure of a program by setting off certain key sections of code.
1890 This is negated with -nbbs or --noblanks-before-subs.
1891 -bbb, --blanks-before-blocks
1893 A blank line will be introduced before blocks of coding delimited
1894 by for, foreach, while, until, and if, unless, in the following
1895 circumstances:
1896 · The block is not preceded by a comment.
1898 · The block is not a one-line block.
1900 · The number of consecutive non-blank lines at the current
1902 indentation depth is at least -lbl (see next section).
1903 This is the default. The intention of this option is to introduce
1905 some space within dense coding. This is negated with -nbbb or
1906 --noblanks-before-blocks.
1907 -lbl=n --long-block-line-count=n
1909 This controls how often perltidy is allowed to add blank lines
1910 before certain block types (see previous section). The default is
1911 8. Entering a value of 0 is equivalent to entering a very large
1912 number.
1913 -mbl=n --maximum-consecutive-blank-lines=n
1915 This parameter specifies the maximum number of consecutive blank
1916 lines which will be output within code sections of a script. The
1917 default is n=1. If the input file has more than n consecutive
1918 blank lines, the number will be reduced to n. If n=0 then no blank
1919 lines will be output (unless all old blank lines are retained with
1920 the -kbl=2 flag of the next section).
1921 This flag obviously does not apply to pod sections, here-documents,
1923 and quotes.
1924 -kbl=n, --keep-old-blank-lines=n
1926 The -kbl=n flag gives you control over how your existing blank
1927 lines are treated.
1928 The possible values of n are:
1930 n=0 ignore all old blank lines
1932 n=1 stable: keep old blanks, but limited by the value of the B<-mbl=n> flag
1933 n=2 keep all old blank lines, regardless of the value of the B<-mbl=n> flag
1934 The default is n=1.
1936 -sob, --swallow-optional-blank-lines
1938 This is equivalent to kbl=0 and is included for compatability with
1939 previous versions.
1940 -nsob, --noswallow-optional-blank-lines
1942 This is equivalent to kbl=1 and is included for compatability with
1943 previous versions.
1944 Styles
1946 A style refers to a convenient collection of existing parameters.
1947 -gnu, --gnu-style
1949 -gnu gives an approximation to the GNU Coding Standards (which do
1950 not apply to perl) as they are sometimes implemented. At present,
1951 this style overrides the default style with the following
1952 parameters:
1953 -lp -bl -noll -pt=2 -bt=2 -sbt=2 -icp
1955 -pbp, --perl-best-practices
1957 -pbp is an abbreviation for the parameters in the book Perl Best
1958 Practices by Damian Conway:
1959 -l=78 -i=4 -ci=4 -st -se -vt=2 -cti=0 -pt=1 -bt=1 -sbt=1 -bbt=1 -nsfs -nolq
1961 -wbb="% + - * / x != == >= <= =~ !~ < > | & =
1962 **= += *= &= <<= &&= -= /= |= >>= ||= //= .= %= ^= x="
1963 Note that the -st and -se flags make perltidy act as a filter on
1965 one file only. These can be overridden with -nst and -nse if
1966 necessary.
1967 Other Controls
1969 Deleting selected text
1970 Perltidy can selectively delete comments and/or pod documentation.
1971 The command -dac or --delete-all-comments will delete all comments
1972 and all pod documentation, leaving just code and any leading system
1973 control lines.
1974 The command -dp or --delete-pod will remove all pod documentation
1976 (but not comments).
1977 Two commands which remove comments (but not pod) are: -dbc or
1979 --delete-block-comments and -dsc or --delete-side-comments.
1980 (Hanging side comments will be deleted with block comments here.)
1981 The negatives of these commands also work, and are the defaults.
1983 When block comments are deleted, any leading 'hash-bang' will be
1984 retained. Also, if the -x flag is used, any system commands before
1985 a leading hash-bang will be retained (even if they are in the form
1986 of comments).
1987 Writing selected text to a file
1989 When perltidy writes a formatted text file, it has the ability to
1990 also send selected text to a file with a .TEE extension. This text
1991 can include comments and pod documentation.
1992 The command -tac or --tee-all-comments will write all comments and
1994 all pod documentation.
1995 The command -tp or --tee-pod will write all pod documentation (but
1997 not comments).
1998 The commands which write comments (but not pod) are: -tbc or
2000 --tee-block-comments and -tsc or --tee-side-comments. (Hanging
2001 side comments will be written with block comments here.)
2002 The negatives of these commands also work, and are the defaults.
2004 Using a .perltidyrc command file
2006 If you use perltidy frequently, you probably won't be happy until
2007 you create a .perltidyrc file to avoid typing commonly-used
2008 parameters. Perltidy will first look in your current directory for
2009 a command file named .perltidyrc. If it does not find one, it will
2010 continue looking for one in other standard locations.
2011 These other locations are system-dependent, and may be displayed
2013 with the command "perltidy -dpro". Under Unix systems, it will
2014 first look for an environment variable PERLTIDY. Then it will look
2015 for a .perltidyrc file in the home directory, and then for a
2016 system-wide file /usr/local/etc/perltidyrc, and then it will look
2017 for /etc/perltidyrc. Note that these last two system-wide files do
2018 not have a leading dot. Further system-dependent information will
2019 be found in the INSTALL file distributed with perltidy.
2020 Under Windows, perltidy will also search for a configuration file
2022 named perltidy.ini since Windows does not allow files with a
2023 leading period (.). Use "perltidy -dpro" to see the possbile
2024 locations for your system. An example might be C:\Documents and
2025 Settings\All Users\perltidy.ini.
2026 Another option is the use of the PERLTIDY environment variable.
2028 The method for setting environment variables depends upon the
2029 version of Windows that you are using. Instructions for Windows 95
2030 and later versions can be found here:
2031 http://www.netmanage.com/000/20021101_005_tcm21-6336.pdf
2033 Under Windows NT / 2000 / XP the PERLTIDY environment variable can
2035 be placed in either the user section or the system section. The
2036 later makes the configuration file common to all users on the
2037 machine. Be sure to enter the full path of the configuration file
2038 in the value of the environment variable. Ex.
2039 PERLTIDY=C:\Documents and Settings\perltidy.ini
2040 The configuation file is free format, and simply a list of
2042 parameters, just as they would be entered on a command line. Any
2043 number of lines may be used, with any number of parameters per
2044 line, although it may be easiest to read with one parameter per
2045 line. Blank lines are ignored, and text after a '#' is ignored to
2046 the end of a line.
2047 Here is an example of a .perltidyrc file:
2049 # This is a simple of a .perltidyrc configuration file
2051 # This implements a highly spaced style
2052 -se # errors to standard error output
2053 -w # show all warnings
2054 -bl # braces on new lines
2055 -pt=0 # parens not tight at all
2056 -bt=0 # braces not tight
2057 -sbt=0 # square brackets not tight
2058 The parameters in the .perltidyrc file are installed first, so any
2060 parameters given on the command line will have priority over them.
2061 To avoid confusion, perltidy ignores any command in the .perltidyrc
2063 file which would cause some kind of dump and an exit. These are:
2064 -h -v -ddf -dln -dop -dsn -dtt -dwls -dwrs -ss
2066 There are several options may be helpful in debugging a .perltidyrc
2068 file:
2069 · A very helpful command is --dump-profile or -dpro. It writes a
2071 list of all configuration filenames tested to standard output,
2072 and if a file is found, it dumps the content to standard output
2073 before exiting. So, to find out where perltidy looks for its
2074 configuration files, and which one if any it selects, just
2075 enter
2076 perltidy -dpro
2078 · It may be simplest to develop and test configuration files with
2080 alternative names, and invoke them with -pro=filename on the
2081 command line. Then rename the desired file to .perltidyrc when
2082 finished.
2083 · The parameters in the .perltidyrc file can be switched off with
2085 the -npro option.
2086 · The commands --dump-options, --dump-defaults,
2088 --dump-long-names, and --dump-short-names, all described below,
2089 may all be helpful.
2090 Creating a new abbreviation
2092 A special notation is available for use in a .perltidyrc file for
2093 creating an abbreviation for a group of options. This can be used
2094 to create a shorthand for one or more styles which are frequently,
2095 but not always, used. The notation is to group the options within
2096 curly braces which are preceded by the name of the alias (without
2097 leading dashes), like this:
2098 newword {
2100 -opt1
2101 -opt2
2102 }
2103 where newword is the abbreviation, and opt1, etc, are existing
2105 parameters or other abbreviations. The main syntax requirement is
2106 that the new abbreviation must begin on a new line. Space before
2107 and after the curly braces is optional. For a specific example,
2108 the following line
2109 airy {-bl -pt=0 -bt=0 -sbt=0}
2111 could be placed in a .perltidyrc file, and then invoked at will
2113 with
2114 perltidy -airy somefile.pl
2116 (Either "-airy" or "--airy" may be used).
2118 Skipping leading non-perl commands with -x or --look-for-hash-bang
2120 If your script has leading lines of system commands or other text
2121 which are not valid perl code, and which are separated from the
2122 start of the perl code by a "hash-bang" line, ( a line of the form
2123 "#!...perl" ), you must use the -x flag to tell perltidy not to
2124 parse and format any lines before the "hash-bang" line. This
2125 option also invokes perl with a -x flag when checking the syntax.
2126 This option was originally added to allow perltidy to parse
2127 interactive VMS scripts, but it should be used for any script which
2128 is normally invoked with "perl -x".
2129 Making a file unreadable
2131 The goal of perltidy is to improve the readability of files, but
2132 there are two commands which have the opposite effect, --mangle and
2133 --extrude. They are actually merely aliases for combinations of
2134 other parameters. Both of these strip all possible whitespace, but
2135 leave comments and pod documents, so that they are essentially
2136 reversible. The difference between these is that --mangle puts the
2137 fewest possible line breaks in a script while --extrude puts the
2138 maximum possible. Note that these options do not provided any
2139 meaningful obfuscation, because perltidy can be used to reformat
2140 the files. They were originally developed to help test the
2141 tokenization logic of perltidy, but they have other uses. One use
2142 for --mangle is the following:
2143 perltidy --mangle myfile.pl -st | perltidy -o myfile.pl.new
2145 This will form the maximum possible number of one-line blocks (see
2147 next section), and can sometimes help clean up a badly formatted
2148 script.
2149 A similar technique can be used with --extrude instead of --mangle
2151 to make the minimum number of one-line blocks.
2152 Another use for --mangle is to combine it with -dac to reduce the
2154 file size of a perl script.
2155 One-line blocks
2157 There are a few points to note regarding one-line blocks. A one-
2158 line block is something like this,
2159 if ($x > 0) { $y = 1 / $x }
2161 where the contents within the curly braces is short enough to fit
2163 on a single line.
2164 With few exceptions, perltidy retains existing one-line blocks, if
2166 it is possible within the line-length constraint, but it does not
2167 attempt to form new ones. In other words, perltidy will try to
2168 follow the one-line block style of the input file.
2169 If an existing one-line block is longer than the maximum line
2171 length, however, it will be broken into multiple lines. When this
2172 happens, perltidy checks for and adds any optional terminating
2173 semicolon (unless the -nasc option is used) if the block is a code
2174 block.
2175 The main exception is that perltidy will attempt to form new one-
2177 line blocks following the keywords "map", "eval", and "sort",
2178 because these code blocks are often small and most clearly
2179 displayed in a single line.
2180 One-line block rules can conflict with the cuddled-else option.
2182 When the cuddled-else option is used, perltidy retains existing
2183 one-line blocks, even if they do not obey cuddled-else formatting.
2184 Occasionally, when one-line blocks get broken because they exceed
2186 the available line length, the formatting will violate the
2187 requested brace style. If this happens, reformatting the script a
2188 second time should correct the problem.
2189 Debugging
2191 The following flags are available for debugging:
2192 --dump-defaults or -ddf will write the default option set to
2194 standard output and quit
2195 --dump-profile or -dpro will write the name of the current
2197 configuration file and its contents to standard output and quit.
2198 --dump-options or -dop will write current option set to standard
2200 output and quit.
2201 --dump-long-names or -dln will write all command line long names
2203 (passed to Get_options) to standard output and quit.
2204 --dump-short-names or -dsn will write all command line short names
2206 to standard output and quit.
2207 --dump-token-types or -dtt will write a list of all token types to
2209 standard output and quit.
2210 --dump-want-left-space or -dwls will write the hash
2212 %want_left_space to standard output and quit. See the section on
2213 controlling whitespace around tokens.
2214 --dump-want-right-space or -dwrs will write the hash
2216 %want_right_space to standard output and quit. See the section on
2217 controlling whitespace around tokens.
2218 -DEBUG will write a file with extension .DEBUG for each input file
2220 showing the tokenization of all lines of code.
2221 Working with MakeMaker, AutoLoader and SelfLoader
2223 The first $VERSION line of a file which might be eval'd by
2224 MakeMaker is passed through unchanged except for indentation. Use
2225 --nopass-version-line, or -npvl, to deactivate this feature.
2226 If the AutoLoader module is used, perltidy will continue formatting
2228 code after seeing an __END__ line. Use --nolook-for-autoloader, or
2229 -nlal, to deactivate this feature.
2230 Likewise, if the SelfLoader module is used, perltidy will continue
2232 formatting code after seeing a __DATA__ line. Use
2233 --nolook-for-selfloader, or -nlsl, to deactivate this feature.
2234 Working around problems with older version of Perl
2236 Perltidy contains a number of rules which help avoid known
2237 subtleties and problems with older versions of perl, and these
2238 rules always take priority over whatever formatting flags have been
2239 set. For example, perltidy will usually avoid starting a new line
2240 with a bareword, because this might cause problems if "use strict"
2241 is active.
2242 There is no way to override these rules.
2244
2246 The -html master switch
2247 The flag -html causes perltidy to write an html file with extension
2248 .html. So, for example, the following command
2249 perltidy -html somefile.pl
2251 will produce a syntax-colored html file named somefile.pl.html
2253 which may be viewed with a browser.
2254 Please Note: In this case, perltidy does not do any formatting to
2256 the input file, and it does not write a formatted file with
2257 extension .tdy. This means that two perltidy runs are required to
2258 create a fully reformatted, html copy of a script.
2259 The -pre flag for code snippets
2261 When the -pre flag is given, only the pre-formatted section, within
2262 the <PRE> and </PRE> tags, will be output. This simplifies
2263 inclusion of the output in other files. The default is to output a
2264 complete web page.
2265 The -nnn flag for line numbering
2267 When the -nnn flag is given, the output lines will be numbered.
2268 The -toc, or --html-table-of-contents flag
2270 By default, a table of contents to packages and subroutines will be
2271 written at the start of html output. Use -ntoc to prevent this.
2272 This might be useful, for example, for a pod document which
2273 contains a number of unrelated code snippets. This flag only
2274 influences the code table of contents; it has no effect on any
2275 table of contents produced by pod2html (see next item).
2276 The -pod, or --pod2html flag
2278 There are two options for formatting pod documentation. The
2279 default is to pass the pod through the Pod::Html module (which
2280 forms the basis of the pod2html utility). Any code sections are
2281 formatted by perltidy, and the results then merged. Note: perltidy
2282 creates a temporary file when Pod::Html is used; see "FILES".
2283 Also, Pod::Html creates temporary files for its cache.
2284 NOTE: Perltidy counts the number of "=cut" lines, and either moves
2286 the pod text to the top of the html file if there is one "=cut", or
2287 leaves the pod text in its original order (interleaved with code)
2288 otherwise.
2289 Most of the flags accepted by pod2html may be included in the
2291 perltidy command line, and they will be passed to pod2html. In
2292 some cases, the flags have a prefix "pod" to emphasize that they
2293 are for the pod2html, and this prefix will be removed before they
2294 are passed to pod2html. The flags which have the additional "pod"
2295 prefix are:
2296 --[no]podheader --[no]podindex --[no]podrecurse --[no]podquiet
2298 --[no]podverbose --podflush
2299 The flags which are unchanged from their use in pod2html are:
2301 --backlink=s --cachedir=s --htmlroot=s --libpods=s --title=s
2303 --podpath=s --podroot=s
2304 where 's' is an appropriate character string. Not all of these
2306 flags are available in older versions of Pod::Html. See your
2307 Pod::Html documentation for more information.
2308 The alternative, indicated with -npod, is not to use Pod::Html, but
2310 rather to format pod text in italics (or whatever the stylesheet
2311 indicates), without special html markup. This is useful, for
2312 example, if pod is being used as an alternative way to write
2313 comments.
2314 The -frm, or --frames flag
2316 By default, a single html output file is produced. This can be
2317 changed with the -frm option, which creates a frame holding a table
2318 of contents in the left panel and the source code in the right
2319 side. This simplifies code browsing. Assume, for example, that the
2320 input file is MyModule.pm. Then, for default file extension
2321 choices, these three files will be created:
2322 MyModule.pm.html - the frame
2324 MyModule.pm.toc.html - the table of contents
2325 MyModule.pm.src.html - the formatted source code
2326 Obviously this file naming scheme requires that output be directed
2328 to a real file (as opposed to, say, standard output). If this is
2329 not the case, or if the file extension is unknown, the -frm option
2330 will be ignored.
2331 The -text=s, or --html-toc-extension flag
2333 Use this flag to specify the extra file extension of the table of
2334 contents file when html frames are used. The default is "toc".
2335 See "Specifying File Extensions".
2336 The -sext=s, or --html-src-extension flag
2338 Use this flag to specify the extra file extension of the content
2339 file when html frames are used. The default is "src". See
2340 "Specifying File Extensions".
2341 The -hent, or --html-entities flag
2343 This flag controls the use of Html::Entities for html formatting.
2344 By default, the module Html::Entities is used to encode special
2345 symbols. This may not be the right thing for some browser/language
2346 combinations. Use --nohtml-entities or -nhent to prevent this.
2347 Style Sheets
2349 Style sheets make it very convenient to control and adjust the
2350 appearance of html pages. The default behavior is to write a page
2351 of html with an embedded style sheet.
2352 An alternative to an embedded style sheet is to create a page with
2354 a link to an external style sheet. This is indicated with the
2355 -css=filename, where the external style sheet is filename. The
2356 external style sheet filename will be created if and only if it
2357 does not exist. This option is useful for controlling multiple
2358 pages from a single style sheet.
2359 To cause perltidy to write a style sheet to standard output and
2361 exit, use the -ss, or --stylesheet, flag. This is useful if the
2362 style sheet could not be written for some reason, such as if the
2363 -pre flag was used. Thus, for example,
2364 perltidy -html -ss >mystyle.css
2366 will write a style sheet with the default properties to file
2368 mystyle.css.
2369 The use of style sheets is encouraged, but a web page without a
2371 style sheets can be created with the flag -nss. Use this option if
2372 you must to be sure that older browsers (roughly speaking, versions
2373 prior to 4.0 of Netscape Navigator and Internet Explorer) can
2374 display the syntax-coloring of the html files.
2375 Controlling HTML properties
2377 Note: It is usually more convenient to accept the default
2378 properties and then edit the stylesheet which is produced.
2379 However, this section shows how to control the properties with
2380 flags to perltidy.
2381 Syntax colors may be changed from their default values by flags of
2383 the either the long form, -html-color-xxxxxx=n, or more
2384 conveniently the short form, -hcx=n, where xxxxxx is one of the
2385 following words, and x is the corresponding abbreviation:
2386 Token Type xxxxxx x
2388 ---------- -------- --
2389 comment comment c
2390 number numeric n
2391 identifier identifier i
2392 bareword, function bareword w
2393 keyword keyword k
2394 quite, pattern quote q
2395 here doc text here-doc-text h
2396 here doc target here-doc-target hh
2397 punctuation punctuation pu
2398 parentheses paren p
2399 structural braces structure s
2400 semicolon semicolon sc
2401 colon colon co
2402 comma comma cm
2403 label label j
2404 sub definition name subroutine m
2405 pod text pod-text pd
2406 A default set of colors has been defined, but they may be changed
2408 by providing values to any of the following parameters, where n is
2409 either a 6 digit hex RGB color value or an ascii name for a color,
2410 such as 'red'.
2411 To illustrate, the following command will produce an html file
2413 somefile.pl.html with "aqua" keywords:
2414 perltidy -html -hck=00ffff somefile.pl
2416 and this should be equivalent for most browsers:
2418 perltidy -html -hck=aqua somefile.pl
2420 Perltidy merely writes any non-hex names that it sees in the html
2422 file. The following 16 color names are defined in the HTML 3.2
2423 standard:
2424 black => 000000,
2426 silver => c0c0c0,
2427 gray => 808080,
2428 white => ffffff,
2429 maroon => 800000,
2430 red => ff0000,
2431 purple => 800080,
2432 fuchsia => ff00ff,
2433 green => 008000,
2434 lime => 00ff00,
2435 olive => 808000,
2436 yellow => ffff00
2437 navy => 000080,
2438 blue => 0000ff,
2439 teal => 008080,
2440 aqua => 00ffff,
2441 Many more names are supported in specific browsers, but it is
2443 safest to use the hex codes for other colors. Helpful color tables
2444 can be located with an internet search for "HTML color tables".
2445 Besides color, two other character attributes may be set: bold, and
2447 italics. To set a token type to use bold, use the flag
2448 --html-bold-xxxxxx or -hbx, where xxxxxx or x are the long or short
2449 names from the above table. Conversely, to set a token type to NOT
2450 use bold, use --nohtml-bold-xxxxxx or -nhbx.
2451 Likewise, to set a token type to use an italic font, use the flag
2453 --html-italic-xxxxxx or -hix, where again xxxxxx or x are the long
2454 or short names from the above table. And to set a token type to
2455 NOT use italics, use --nohtml-italic-xxxxxx or -nhix.
2456 For example, to use bold braces and lime color, non-bold, italics
2458 keywords the following command would be used:
2459 perltidy -html -hbs -hck=00FF00 -nhbk -hik somefile.pl
2461 The background color can be specified with
2463 --html-color-background=n, or -hcbg=n for short, where n is a 6
2464 character hex RGB value. The default color of text is the value
2465 given to punctuation, which is black as a default.
2466 Here are some notes and hints:
2468 1. If you find a preferred set of these parameters, you may want to
2470 create a .perltidyrc file containing them. See the perltidy man
2471 page for an explanation.
2472 2. Rather than specifying values for these parameters, it is
2474 probably easier to accept the defaults and then edit a style sheet.
2475 The style sheet contains comments which should make this easy.
2476 3. The syntax-colored html files can be very large, so it may be
2478 best to split large files into smaller pieces to improve download
2479 times.
2480
2482 Specifying Block Types
2483 Several parameters which refer to code block types may be customized by
2484 also specifying an associated list of block types. The type of a block
2485 is the name of the keyword which introduces that block, such as if,
2486 else, or sub. An exception is a labeled block, which has no keyword,
2487 and should be specified with just a colon.
2488 For example, the following parameter specifies "sub", labels, "BEGIN",
2490 and "END" blocks:
2491 -cscl="sub : BEGIN END"
2493 (the meaning of the -cscl parameter is described above.) Note that
2495 quotes are required around the list of block types because of the
2496 spaces.
2497 Specifying File Extensions
2499 Several parameters allow default file extensions to be overridden. For
2500 example, a backup file extension may be specified with -bext=ext, where
2501 ext is some new extension. In order to provides the user some
2502 flexibility, the following convention is used in all cases to decide if
2503 a leading '.' should be used. If the extension "ext" begins with
2504 "A-Z", "a-z", or "0-9", then it will be appended to the filename with
2505 an intermediate '.' (or perhaps an '_' on VMS systems). Otherwise, it
2506 will be appended directly.
2507 For example, suppose the file is somefile.pl. For "-bext=old", a '.'
2509 is added to give somefile.pl.old. For "-bext=.old", no additional '.'
2510 is added, so again the backup file is somefile.pl.old. For "-bext=~",
2511 then no dot is added, and the backup file will be somefile.pl~ .
2512
2514 The following list shows all short parameter names which allow a prefix
2515 'n' to produce the negated form:
2516 D anl asc aws b bbb bbc bbs bl bli boc bok bol bot ce
2518 csc dac dbc dcsc ddf dln dnl dop dp dpro dsc dsm dsn dtt dwls
2519 dwrs dws f fll frm fs hsc html ibc icb icp iob isbc lal log
2520 lp lsl ohbr okw ola oll opr opt osbr otr ple ple pod pvl q
2521 sbc sbl schb scp scsb sct se sfp sfs skp sob sohb sop sosb sot
2522 ssc st sts syn t tac tbc toc tp tqw tsc w x bar kis
2523 Equivalently, the prefix 'no' or 'no-' on the corresponding long names
2525 may be used.
2526
2528 Parsing Limitations
2529 Perltidy should work properly on most perl scripts. It does a lot
2530 of self-checking, but still, it is possible that an error could be
2531 introduced and go undetected. Therefore, it is essential to make
2532 careful backups and to test reformatted scripts.
2533 The main current limitation is that perltidy does not scan modules
2535 included with 'use' statements. This makes it necessary to guess
2536 the context of any bare words introduced by such modules. Perltidy
2537 has good guessing algorithms, but they are not infallible. When it
2538 must guess, it leaves a message in the log file.
2539 If you encounter a bug, please report it.
2541 What perltidy does not parse and format
2543 Perltidy indents but does not reformat comments and "qw" quotes.
2544 Perltidy does not in any way modify the contents of here documents
2545 or quoted text, even if they contain source code. (You could,
2546 however, reformat them separately). Perltidy does not format
2547 'format' sections in any way. And, of course, it does not modify
2548 pod documents.
2549
2551 Temporary files
2552 Under the -html option with the default --pod2html flag, a
2553 temporary file is required to pass text to Pod::Html. Unix systems
2554 will try to use the POSIX tmpnam() function. Otherwise the file
2555 perltidy.TMP will be temporarily created in the current working
2556 directory.
2557 Special files when standard input is used
2559 When standard input is used, the log file, if saved, is
2560 perltidy.LOG, and any errors are written to perltidy.ERR unless the
2561 -se flag is set. These are saved in the current working directory.
2562 Files overwritten
2564 The following file extensions are used by perltidy, and files with
2565 these extensions may be overwritten or deleted: .ERR, .LOG, .TEE,
2566 and/or .tdy, .html, and .bak, depending on the run type and
2567 settings.
2568 Files extensions limitations
2570 Perltidy does not operate on files for which the run could produce
2571 a file with a duplicated file extension. These extensions include
2572 .LOG, .ERR, .TEE, and perhaps .tdy and .bak, depending on the run
2573 type. The purpose of this rule is to prevent generating confusing
2574 filenames such as somefile.tdy.tdy.tdy.
2575
2577 perlstyle(1), Perl::Tidy(3)
2578
2580 This man page documents perltidy version 20101217.
2581
2583 Michael Cartmell supplied code for adaptation to VMS and helped with
2584 v-strings.
2585 Yves Orton supplied code for adaptation to the various versions of
2587 Windows.
2588 Axel Rose supplied a patch for MacPerl.
2590 Hugh S. Myers designed and implemented the initial Perl::Tidy module
2592 interface.
2593 Many others have supplied key ideas, suggestions, and bug reports; see
2595 the CHANGES file.
2596
2598 Steve Hancock
2599 email: perltidy at users.sourceforge.net
2600 http://perltidy.sourceforge.net
2601
2603 Copyright (c) 2000-2010 by Steve Hancock
2604
2606 This package is free software; you can redistribute it and/or modify it
2607 under the terms of the "GNU General Public License".
2608 Please refer to the file "COPYING" for details.
2610
2612 This package is distributed in the hope that it will be useful, but
2613 WITHOUT ANY WARRANTY; without even the implied warranty of
2614 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
2615 See the "GNU General Public License" for more details.
2617perl v5.12.2 2010-12-16 PERLTIDY(1)